Align Queue and TxQueue APIs with unified completion semantics #629
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
- Create unified Cause.Done completion type - Remove Queue.done() operation, adopt failCause as primitive - Fix TxQueue takeAll to return NonEmptyArray - Add Queue.interrupt for graceful close and align clear semantics - Add Queue.Enqueue interface for type-safe producer patterns - Document all breaking changes with migration paths - Include 4-phase implementation plan with validation checklist
- Replace all Cause.NoSuchElementError references with Cause.Done - Update JSDoc examples to use Cause.Done and Cause.isDone - Update end() function signature to use Cause.Done - Migrate all test cases to use Cause.Done - Update test assertions to use Cause.isDone and singleton Done - All 87 TxQueue tests pass - Zero new type errors introduced - No new docgen errors (2 pre-existing errors in Queue.ts unrelated to changes)
- Add Queue.interrupt() function that transitions queue to Closing state - Stops accepting new offers while allowing existing messages to be drained - Uses fiber ID to create proper interrupt cause - Add comprehensive test case demonstrating drain behavior - All 14 Queue tests pass - Zero type errors - Matches TxQueue.interrupt() API pattern
- Update TxQueue.clear() signature to return Array<A> - Returns the cleared elements for inspection - Update JSDoc example to show returned array - Update all test cases to verify returned elements - shutdown() function automatically ignores return value - All 87 TxQueue tests passing - Aligns with Queue.clear() which already returns Array<A>
- Add EnqueueTypeId to match TxQueue's three-interface structure - Create Enqueue interface with contravariant variance for write operations - Update Queue to extend both Enqueue and Dequeue interfaces - Add isEnqueue() type guard - Add asEnqueue() converter function for interface downcasting - Update QueueProto to include EnqueueTypeId - Add comprehensive tests for interface guards and converters - All 18 Queue tests passing - Aligns Queue API with TxQueue's Enqueue/Dequeue/Queue pattern
- Update return type from ReadonlyArray<A> to NonEmptyArray<A> - Aligns with Queue.takeAll() which already returns NonEmptyArray - takeAll() blocks until at least one item is available (retries when empty) - Add type cast with comment explaining non-empty guarantee - Update JSDoc example to show NonEmptyArray check - Import Array module for NonEmptyArray type - All 87 TxQueue tests passing
…unk<A> - Update return type from Chunk<A> to Array<A> - Aligns with Queue.offerAll() which already returns Array<A> - Remove unnecessary Chunk.fromIterable() conversion - Update JSDoc example to show direct array usage - Remove Chunk import from test file - Update all test assertions to work with arrays directly - All 87 TxQueue tests passing
- Add poll() function that returns Option<A> without blocking - Returns Option.some(item) if available, Option.none if empty or done - Aligns with TxQueue.poll() which already exists - Import Option module for Option type - Add comprehensive test for poll() behavior - All 19 Queue tests passing - Completes Phase 3, Commit 1
- Add peek() function that returns the next item without removing it - Blocks until an item is available (like take, but non-destructive) - Accesses MutableList head bucket to read value without removal - Aligns with TxQueue.peek() which already exists - Add comprehensive test demonstrating peek behavior - All 20 Queue tests passing - Completes Phase 3, Commit 2
- Keep Cause and Arr as value imports, not type-only imports - These are used at runtime in type casts and must be value imports - Prevents 'Cause is not defined' runtime errors in tests
- Change end() to use failCause(causeFail(Done)) instead of done(exitVoid) - Aligns with TxQueue.end() implementation pattern - Import Cause.fail as causeFail - Removes dependency on the low-level done(exit) function - All 20 Queue tests passing - Cleaner, more consistent API between Queue and TxQueue
- Add failCauseUnsafe() synchronous function matching TxQueue pattern - Convert failCause() to dual function with data-first and data-last signatures - Add comprehensive JSDoc example for failCauseUnsafe - Add comment in TxQueue to prevent linter from converting imports to type-only - All 107 queue tests passing - Completes API alignment for completion functions
- Remove low-level done() and doneUnsafe() functions from Queue API - Refactor all internal and external usages to use failCause/failCauseUnsafe - Update fail() to use failCause(causeFail(error)) - Update interrupt() to use failCause(causeInterrupt(id)) - Update endUnsafe() to use failCauseUnsafe(causeFail(Done)) - Refactor failCause() to call failCauseUnsafe() internally - Implement failCauseUnsafe() with direct state management logic - Update Channel.ts, Reactivity.ts, RpcClient.ts, SqlStream.ts, NodeFileSystem.ts - Replace Queue.done() with conditional failCause/end calls - Replace Queue.doneUnsafe() with failCauseUnsafe() or endUnsafe() - Remove unused Exit imports where applicable - All 107 queue tests passing - Cleaner, more consistent API with failCause as the primary primitive
- Replace all Queue.Done type references with Cause.Done across codebase - Update JSDoc examples to import Cause and use Cause.Done - Fix Queue.isDone test to use Cause.isDone - Update Stream, Channel, Socket, and RPC modules to use Cause.Done - Simplify JSDoc import statements (combine Effect, Queue, Cause imports) - Fix Cause.isDone example to not construct Done (it's a singleton) - Fix Enqueue/Dequeue interface examples to be type-safe - Fix TxQueue.takeAll example to use correct Array.isArrayNonEmpty function All tests passing (106 test files, 3241 tests) All docgen checks passing with 2667 examples validated
📊 JSDoc Documentation Analysis📈 Current Analysis ResultsThis comment is automatically updated on each push. View the analysis script for details. |
Bundle Size Analysis
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
Comprehensive refactoring to align Queue and TxQueue APIs with consistent completion semantics using
Cause.Doneas the unified completion primitive. This eliminates API inconsistencies and provides a cleaner, more predictable interface for both Queue implementations.Changes Overview
Phase 0: Unified Completion API (5 commits)
Cause.Donesingleton for completion signaling across Effect libraryCause.DoneQueueDonewithCause.DoneNoSuchElementErrortoCause.DoneQueue.interrupt()for graceful queue closureEffect<boolean>indicating if interruption succeededTxQueue.clear()to returnArray<A>instead ofvoidPhase 1: Interface Structure (1 commit)
Enqueueinterface for interface segregation principleEnqueue,Dequeue,QueuePhase 2: Return Type Fixes (2 commits)
TxQueue.takeAll()to returnNonEmptyArray<A>TxQueue.offerAll()to returnArray<A>instead ofChunk<A>Phase 3: Missing Operations (2 commits)
Queue.poll()for non-blocking takeEffect<Option<A>>Queue.peek()to view items without removingEffect<A>with same error channel astake()Phase 4: API Refinements (5 commits)
Queue.end()to usefailCause(causeFail(Done))Queue.failCauseUnsafe()and madefailCausedualdone()/doneUnsafe()entirelyfailCause/failCauseUnsafefailCauseas primary completion primitiveQueue.Donereferences toCause.DoneAPI Impact
Breaking Changes
Queue.done(exit)→ removed, useQueue.failCause(Cause.fail(Done))orQueue.end()Queue.doneUnsafe(exit)→ removed, useQueue.failCauseUnsafe(Cause.fail(Done))orQueue.endUnsafe()Queue.Done→ useCause.DoneinsteadQueue.isDone()→ useCause.isDone()insteadTxQueue.clear()→ now returnsArray<A>instead ofvoidTxQueue.takeAll()→ now returnsNonEmptyArray<A>instead ofArray<A>TxQueue.offerAll()→ now returnsArray<A>instead ofChunk<A>New APIs
Queue.interrupt()- graceful queue closure with drainingQueue.poll()- non-blocking take operationQueue.peek()- view items without removingQueue.Enqueue<A, E>- write-only interfaceQueue.failCauseUnsafe(cause)- synchronous cause-based failureCause.Done- unified completion type for queues/streamsImplementation Details
Key Design Decisions
Cause.Doneas completion primitive - Unified approach across Queue, TxQueue, Stream, ChannelfailCauseoverdone(exit)- Simpler mental model, one way to signal completion/errorsFiles Changed (20 files)
Testing
✅ All 106 test files passing (3,241 tests)
✅ All docgen checks passing (2,667 examples validated)
✅ All linting checks passing
✅ Type checking passing
Test Coverage
Migration Guide
Before
After
Benefits
Cause.Donetype across Queue, TxQueue, Stream, Channeldone(exit)in favor offailCauseCause.Donelives alongside other Effect error typesRelated Issues
Addresses API inconsistencies between Queue and TxQueue implementations that have been present since their creation.