Skip to content

refactor: simplify scheduling, verify performance and clarify usage - #1

Merged
oe merged 5 commits into
mainfrom
fix/scheduler-correctness
Oct 3, 2026
Merged

oe merged 5 commits into
mainfrom
fix/scheduler-correctness

Conversation

@oe

@oe oe commented Oct 3, 2026 •

Copy link
Copy Markdown
Owner

The scheduler scans waiting callers after each completion and duplicates task state across queues and caches. This can make individual execution quadratic and leave expired results or failed tasks reusable while unrelated work runs. Each unique task now has one record and shared result Promise, with a cursor for serial queues. Existing batching, waiting, cache, retry, and deferred cache-clearing behavior is preserved.

Changes

  • Fix single-task rejection, empty dispatches, active-task deduplication, batch sizes in serial mode, cache expiration / retry eligibility during unrelated work, and executor / TTL-policy exception handling.
  • Provide optional indexed identity through getTaskKey, and handle cyclic plain-object / array comparison safely. Opaque objects use reference identity.
  • Correct built package entry points and declaration paths; retain zero runtime dependencies.
  • Rewrite the README around request deduplication, batching and TTL, with a runnable six-calls / one-batch example, JSON caching instead of reusable Response bodies, serial batching, error handling, and an honest alternatives comparison.
  • Explain cache identity, shared result objects, batch-size versus concurrency limits, and published 1.0.1 versus upcoming behavior. Move detailed performance guidance to docs/performance.md.
  • Update npm description, keywords, homepage and issue links. Add the MIT license text and an unreleased changelog.

Upgrade compatibility

Published file paths (dist/index.js, dist/index.es.js, dist/types.d.ts), CommonJS require/import-equals, default imports with esModuleInterop, exported strategy types, and structural public instance types are retained and checked against the real packed artifact. CI now includes that package-level consumer check.

API signatures remain available, but identical behavior cannot be guaranteed for users relying on 1.0.1 bugs. Single-task failures now reject; parallel batches really execute in parallel; serial mode respects batch size; opaque-object identity and equality boundaries are corrected; TTL and retries take effect while unrelated work runs. docs/upgrading.md lists the changes and configuration adjustments. Merge/release is pending the user's decision on these observable corrections.

Validation

  • 199 tests pass, including 11 deterministic performance regressions; source coverage is 100% across statements, branches, functions and lines.
  • Source/test typechecking, build, npm pack --dry-run and git diff --check pass. The package includes the generated declarations and license.
  • Five documentation TypeScript snippets typecheck and pass runtime assertions against the built package, including mocked JSON reads and HTTP errors. The four README snippets also typecheck and run against published 1.0.1; the serial batch-size difference is explicitly documented.
  • Performance budgets assert one key extraction per submitted item, no completion-time identity lookups, and one execution per distinct task. The benchmark verifies results and execution counts for batch, single, overlapping and serial workloads at 100/500/1000 tasks, using five-run medians after warmup.
  • CI runs tests and benchmarks on Node 22/24 and uploads JSON reports.

The benchmark compares against pre-refactor commit f2e07d2 on the same runtime. Local Node 24 measurements for 1,000 unique tasks: individual execution 13.789 → 1.609 ms, overlapping requests 18.543 → 3.040 ms, serial execution 13.226 → 1.965 ms. Individual execution key calls fall from 508,500 to 2,000 for 2,000 submitted items. Hot-cache individual requests measured 0.109 → 0.192 ms per 1,000 requests. Timings are diagnostic, not portable performance guarantees or CI thresholds.

Boundaries

Arrays still represent multiple tasks. maxBatchCount is a batch size, not a global parallel concurrency limit. Unlimited caching and lazy cleanup remain available. npm run test:package verifies the packed consumer interfaces with skipLibCheck disabled. The npm version remains 1.0.1; the changelog and README identify unpublished changes. This PR does not merge or publish the package.

@oe oe changed the title fix: correct scheduling, deduplication, and failure handling fix/perf: correct scheduling and add indexed task identities Oct 3, 2026
@oe oe changed the title fix/perf: correct scheduling and add indexed task identities refactor: share task records and add performance regression coverage Oct 3, 2026
@oe
oe marked this pull request as ready for review October 3, 2026 11:16
@oe oe changed the title refactor: share task records and add performance regression coverage refactor: simplify scheduling, verify performance and clarify usage Oct 3, 2026
@oe
oe merged commit 6080a22 into main Oct 3, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant