Skip to content

feat: add FlexJob with bounded intermediate publication - #30

Merged
miinhho merged 2 commits into
mainfrom
feat/flex-job-channel
Sep 15, 2026
Merged

miinhho merged 2 commits into
mainfrom
feat/flex-job-channel

Conversation

@miinhho

@miinhho miinhho commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

Jobs currently expose only a final result, while HandoffJob permits one intermediate value and waits for an acknowledgement. Add FlexJob for producers that publish multiple intermediate values while continuing independently of consumers.

publish(value) synchronously delivers to a pending receive or a bounded FIFO channel. The default retains the latest unread value; FlexJob.withBuffer(capacity, body, options) supports drop-oldest, drop-newest, and error overflow policies. receive({ signal }) cancels only that observation. Successful body completion preserves queued updates for draining, while failures and cancellation discard stale progress and release receivers. Cancellation stays connected before start and while descendants outlive the body; the registration is disposed only after the whole Job settles. result() and await job keep the existing Job ownership, descendant-joining, and failure contracts.

Keep the Job kernel unchanged. FlexJob manages body publication and channel cleanup; the channel validates its own buffer configuration and manages delivery, with one explicit open/closed/failed state. Deprecate HandoffJob and Handoff without changing their existing acknowledgement behavior or introducing compatibility wrappers. Update README and repository guidance for the new contracts.

Validation: pnpm format && pnpm check && pnpm build && pnpm test && pnpm pack passed (159 tests, including 28 lifecycle/channel cases). Regression cases verify cold cancellation and cancellation/failure before remaining descendants finish; all five failed against the implementation that disposed cancellation on body return. The descendant-joining test also fails when joining is deliberately disabled in an isolated copy. Body cleanup uses an actual await using resource and verifies exact independent failure identities.

A separate consumer loaded the packed package, verified channel delivery, descendant joining, receive-only cancellation, cold cancellation, cancellation while descendants remain active, and existing HandoffJob behavior, and typechecked the public declarations.

This branch is based directly on main and is independent of the ambient-access and module-identity documentation PR #29.

@miinhho
miinhho merged commit e4821a0 into main Sep 15, 2026
1 check passed
@miinhho
miinhho deleted the feat/flex-job-channel branch September 15, 2026 19:00
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