Align Queue and TxQueue APIs with unified completion semantics #629

mikearnaldi · 2025-10-07T14:43:38Z

Summary

Comprehensive refactoring to align Queue and TxQueue APIs with consistent completion semantics using Cause.Done as 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)

Created Cause.Done singleton for completion signaling across Effect library
Migrated Queue from local error types to Cause.Done
- Replaced QueueDone with Cause.Done
- Maintained backward compatibility during transition
Migrated TxQueue from NoSuchElementError to Cause.Done
- Consistent completion semantics across both queue types
Added Queue.interrupt() for graceful queue closure
- Returns Effect<boolean> indicating if interruption succeeded
- Allows draining remaining items before closure
Updated TxQueue.clear() to return Array<A> instead of void
- Enables recovery of cleared items

Phase 1: Interface Structure (1 commit)

Added Enqueue interface for interface segregation principle
- Supports write-only queue operations
- Enables type-safe producer patterns
Implemented three-interface pattern: Enqueue, Dequeue, Queue

Phase 2: Return Type Fixes (2 commits)

Changed TxQueue.takeAll() to return NonEmptyArray<A>
- More precise type matching Queue behavior
- Better compile-time guarantees
Changed TxQueue.offerAll() to return Array<A> instead of Chunk<A>
- Consistent with Queue return types

Phase 3: Missing Operations (2 commits)

Added Queue.poll() for non-blocking take
- Returns Effect<Option<A>>
- No suspension when queue is empty
Added Queue.peek() to view items without removing
- Returns Effect<A> with same error channel as take()

Phase 4: API Refinements (5 commits)

Fixed linter breaking runtime imports in TxQueue
Refactored Queue.end() to use failCause(causeFail(Done))
- Consistent with TxQueue implementation
Added Queue.failCauseUnsafe() and made failCause dual
Removed done()/doneUnsafe() entirely
- Replaced all usages with failCause/failCauseUnsafe
- Cleaner API with failCause as primary completion primitive
Migrated all Queue.Done references to Cause.Done
- Updated JSDoc examples across 9 source files
- Fixed 2667 documentation examples to compile correctly
- Simplified import statements in examples

API Impact

Breaking Changes

Queue.done(exit) → removed, use Queue.failCause(Cause.fail(Done)) or Queue.end()
Queue.doneUnsafe(exit) → removed, use Queue.failCauseUnsafe(Cause.fail(Done)) or Queue.endUnsafe()
Queue.Done → use Cause.Done instead
Queue.isDone() → use Cause.isDone() instead
TxQueue.clear() → now returns Array<A> instead of void
TxQueue.takeAll() → now returns NonEmptyArray<A> instead of Array<A>
TxQueue.offerAll() → now returns Array<A> instead of Chunk<A>

New APIs

Queue.interrupt() - graceful queue closure with draining
Queue.poll() - non-blocking take operation
Queue.peek() - view items without removing
Queue.Enqueue<A, E> - write-only interface
Queue.failCauseUnsafe(cause) - synchronous cause-based failure
Cause.Done - unified completion type for queues/streams

Implementation Details

Key Design Decisions

Cause.Done as completion primitive - Unified approach across Queue, TxQueue, Stream, Channel
failCause over done(exit) - Simpler mental model, one way to signal completion/errors
Interface segregation - Enqueue/Dequeue split enables type-safe producer/consumer patterns
Return cleared/rejected items - Enables proper cleanup and item recovery

Files Changed (20 files)

Core Queue modules: Queue.ts (+492/-257), TxQueue.ts (+65/-47), Cause.ts (+74)
Stream modules: Stream.ts, Channel.ts, Pull.ts
RPC/Socket modules: Rpc.ts, RpcClient.ts, RpcGroup.ts, RpcServer.ts, Socket.ts
Tests: Queue.test.ts, TxQueue.test.ts, Channel.test.ts, Stream.test.ts
Platform: NodeFileSystem.ts, SqlStream.ts, Reactivity.ts

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

Queue completion semantics (end, interrupt, fail)
TxQueue atomic operations with new return types
Error propagation with Cause.Done
Interface segregation (Enqueue/Dequeue)
Poll and peek operations
Backward compatibility scenarios

Migration Guide

Before

import { Queue } from "effect"

const queue = yield* Queue.bounded<number, Queue.Done>(10)
yield* Queue.offer(queue, 1)

// Complete queue
yield* Queue.done(queue, Exit.void)

// Check if done
if (Queue.isDone(error)) { /* ... */ }

After

import { Cause, Queue } from "effect"

const queue = yield* Queue.bounded<number, Cause.Done>(10)
yield* Queue.offer(queue, 1)

// Complete queue (recommended)
yield* Queue.end(queue)

// Or with explicit cause
yield* Queue.failCause(queue, Cause.fail(Cause.Done))

// Check if done
if (Cause.isDone(error)) { /* ... */ }

Benefits

Unified completion semantics - Single Cause.Done type across Queue, TxQueue, Stream, Channel
Cleaner API surface - Removed confusing done(exit) in favor of failCause
Better type safety - NonEmptyArray return types, interface segregation
Improved discoverability - Cause.Done lives alongside other Effect error types
Enhanced functionality - New poll(), peek(), interrupt() operations
Item recovery - clear() and offerAll() return rejected items

Related Issues

Addresses API inconsistencies between Queue and TxQueue implementations that have been present since their creation.

github-actions · 2025-10-07T14:47:34Z

📊 JSDoc Documentation Analysis

📈 Current Analysis Results

Analyzing 123 TypeScript files in packages/effect/src/ (including schema and config subdirectories)...

============================================================
         EFFECT JSDOC ANALYSIS REPORT
============================================================

📊 SUMMARY STATISTICS
------------------------------
Total files analyzed: 123
Total exported members: 3992
Missing @example: 1658 (41.5%)
Missing @category: 510 (12.8%)

🎯 TOP FILES NEEDING ATTENTION
----------------------------------------
1. Schema.ts
   📝 451 missing examples, 🏷️  260 missing categories
   📦 451 total exports
2. SchemaRepresentation.ts
   📝 92 missing examples, 🏷️  91 missing categories
   📦 92 total exports
3. Stream.ts
   📝 138 missing examples, 🏷️  0 missing categories
   📦 227 total exports
4. SchemaAST.ts
   📝 74 missing examples, 🏷️  18 missing categories
   📦 74 total exports
5. Channel.ts
   📝 73 missing examples, 🏷️  0 missing categories
   📦 142 total exports
6. Sink.ts
   📝 64 missing examples, 🏷️  2 missing categories
   📦 81 total exports
7. SchemaGetter.ts
   📝 49 missing examples, 🏷️  0 missing categories
   📦 49 total exports
8. SchemaTransformation.ts
   📝 29 missing examples, 🏷️  18 missing categories
   📦 29 total exports
9. Config.ts
   📝 33 missing examples, 🏷️  5 missing categories
   📦 33 total exports
10. Cause.ts
   📝 33 missing examples, 🏷️  2 missing categories
   📦 75 total exports
11. Effect.ts
   📝 34 missing examples, 🏷️  1 missing categories
   📦 241 total exports
12. JsonSchema.ts
   📝 17 missing examples, 🏷️  17 missing categories
   📦 17 total exports
13. Order.ts
   📝 25 missing examples, 🏷️  0 missing categories
   📦 25 total exports
14. Filter.ts
   📝 24 missing examples, 🏷️  0 missing categories
   📦 35 total exports
15. SchemaIssue.ts
   📝 22 missing examples, 🏷️  2 missing categories
   📦 22 total exports

✅ PERFECTLY DOCUMENTED FILES
-----------------------------------
   Chunk.ts (87 exports)
   Clock.ts (5 exports)
   FiberHandle.ts (15 exports)
   FiberMap.ts (19 exports)
   FiberSet.ts (14 exports)
   HKT.ts (4 exports)
   HashMap.ts (44 exports)
   HashSet.ts (21 exports)
   Match.ts (57 exports)
   MutableHashSet.ts (9 exports)
   MutableRef.ts (17 exports)
   NonEmptyIterable.ts (3 exports)
   Random.ts (7 exports)
   Redacted.ts (9 exports)
   RegExp.ts (3 exports)
   Runtime.ts (3 exports)
   Symbol.ts (1 exports)
   Trie.ts (29 exports)
   TxChunk.ts (22 exports)
   TxHashMap.ts (41 exports)
   TxHashSet.ts (24 exports)
   TxRef.ts (7 exports)
   TxSemaphore.ts (14 exports)
   Unify.ts (8 exports)
   index.ts (0 exports)

🔍 SAMPLE MISSING ITEMS FROM Schema.ts
-----------------------------------
   Optionality (type, line 60): missing example, category
   Mutability (type, line 67): missing example, category
   ConstructorDefault (type, line 74): missing example, category
   MakeOptions (interface, line 82): missing example, category
   Bottom (interface, line 106): missing example, category
   declareConstructor (interface, line 158): missing example, category
   declareConstructor (function, line 182): missing example
   declare (interface, line 206): missing example
   declare (function, line 215): missing example, category
   revealBottom (function, line 235): missing example, category

📋 BREAKDOWN BY EXPORT TYPE
-----------------------------------
const: 826 missing examples, 157 missing categories
function: 298 missing examples, 97 missing categories
type: 176 missing examples, 86 missing categories
interface: 268 missing examples, 150 missing categories
class: 55 missing examples, 1 missing categories
namespace: 35 missing examples, 19 missing categories

📈 DOCUMENTATION PROGRESS
------------------------------
Examples: 2334/3992 (58.5% complete)
Categories: 3482/3992 (87.2% complete)

============================================================
Analysis complete! 2168 items need attention.
============================================================

📄 Detailed results saved to: jsdoc-analysis-results.json

This comment is automatically updated on each push. View the analysis script for details.

github-actions · 2025-10-07T14:47:35Z

Bundle Size Analysis

File Name	Current Size	Previous Size	Difference
`bundle/basic.ts`	6.23 KB	6.23 KB	0.00 KB (0.00%)
`bundle/batching.ts`	8.48 KB	8.48 KB	0.00 KB (0.00%)
`bundle/brand.ts`	6.25 KB	6.25 KB	0.00 KB (0.00%)
`bundle/cache.ts`	9.54 KB	9.54 KB	0.00 KB (0.00%)
`bundle/config.ts`	16.05 KB	16.05 KB	0.00 KB (0.00%)
`bundle/differ.ts`	14.28 KB	14.28 KB	0.00 KB (0.00%)
`bundle/http-client.ts`	18.74 KB	18.73 KB	+0.01 KB (+0.07%)
`bundle/logger.ts`	8.82 KB	8.82 KB	0.00 KB (0.00%)
`bundle/metric.ts`	8.70 KB	8.70 KB	0.00 KB (0.00%)
`bundle/optic.ts`	7.48 KB	7.48 KB	0.00 KB (0.00%)
`bundle/pubsub.ts`	13.05 KB	13.05 KB	0.00 KB (0.00%)
`bundle/queue.ts`	10.93 KB	10.92 KB	+0.01 KB (+0.08%)
`bundle/schedule.ts`	9.65 KB	9.65 KB	0.00 KB (0.00%)
`bundle/schema-representation-roundtrip.ts`	23.77 KB	23.77 KB	0.00 KB (0.00%)
`bundle/schema-string-transformation.ts`	11.22 KB	11.22 KB	0.00 KB (0.00%)
`bundle/schema-string.ts`	9.54 KB	9.54 KB	0.00 KB (0.00%)
`bundle/schema-template-literal.ts`	12.04 KB	12.04 KB	0.00 KB (0.00%)
`bundle/schema-toArbitraryLazy.ts`	16.27 KB	16.27 KB	0.00 KB (0.00%)
`bundle/schema-toCodeDocument.ts`	19.15 KB	19.15 KB	0.00 KB (0.00%)
`bundle/schema-toCodecJson.ts`	15.11 KB	15.11 KB	0.00 KB (0.00%)
`bundle/schema-toEquivalence.ts`	15.40 KB	15.40 KB	0.00 KB (0.00%)
`bundle/schema-toFormatter.ts`	15.26 KB	15.26 KB	0.00 KB (0.00%)
`bundle/schema-toJsonSchemaDocument.ts`	17.85 KB	17.85 KB	0.00 KB (0.00%)
`bundle/schema-toRepresentation.ts`	16.05 KB	16.05 KB	0.00 KB (0.00%)
`bundle/schema.ts`	14.89 KB	14.89 KB	0.00 KB (0.00%)
`bundle/stm.ts`	11.94 KB	11.94 KB	0.00 KB (0.00%)
`bundle/stream.ts`	8.42 KB	8.42 KB	+0.01 KB (+0.07%)

mikearnaldi requested a review from tim-smart October 8, 2025 11:18

align Queue/TxQueue

e3d3c90

tim-smart force-pushed the feat/align-queue branch from 9659391 to e3d3c90 Compare January 20, 2026 01:53

tim-smart added 3 commits January 20, 2026 15:05

move Pull.done

8b18c59

docs

9f84536

lint fix

6579f8d

tim-smart enabled auto-merge (squash) January 20, 2026 02:19

tim-smart merged commit 5480c71 into main Jan 20, 2026
11 of 12 checks passed

tim-smart deleted the feat/align-queue branch January 20, 2026 02:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Align Queue and TxQueue APIs with unified completion semantics #629

Align Queue and TxQueue APIs with unified completion semantics #629

Uh oh!

mikearnaldi commented Oct 7, 2025

Uh oh!

github-actions bot commented Oct 7, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 7, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Align Queue and TxQueue APIs with unified completion semantics #629

Align Queue and TxQueue APIs with unified completion semantics #629

Uh oh!

Conversation

mikearnaldi commented Oct 7, 2025

Summary

Changes Overview

Phase 0: Unified Completion API (5 commits)

Phase 1: Interface Structure (1 commit)

Phase 2: Return Type Fixes (2 commits)

Phase 3: Missing Operations (2 commits)

Phase 4: API Refinements (5 commits)

API Impact

Breaking Changes

New APIs

Implementation Details

Key Design Decisions

Files Changed (20 files)

Testing

Test Coverage

Migration Guide

Before

After

Benefits

Related Issues

Uh oh!

github-actions bot commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 JSDoc Documentation Analysis

Uh oh!

github-actions bot commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Size Analysis

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Oct 7, 2025 •

edited

Loading

github-actions bot commented Oct 7, 2025 •

edited

Loading