feat: add FlexJob with bounded intermediate publication - #30
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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)supportsdrop-oldest,drop-newest, anderroroverflow 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()andawait jobkeep 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 packpassed (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 actualawait usingresource 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.