suaveplan/openspec/archive/2026-04-24-enterprise-streams/tasks.md

Tasks: enterprise-streams

• Change ID: enterprise-streams
• Package: @suaveplan/streams
• Date: 2026-04-24

Prerequisites (must be published to Verdaccio first)

• @suaveplan/error
• @suaveplan/types

Tasks

1. Scaffold package

• Create universal/streams/streams/ directory tree per file layout in proposal.md
• Write package.json (name @suaveplan/streams, version 0.1.0, sideEffects: false, correct workspace deps and catalog externals)
• Write tsconfig.json extending @suaveplan/typescript-config/library.json
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config

2. Error codes (src/error-codes.ts)

• Define StreamErrorCode union type
• Call defineCodes to register all STREAM.* codes
• Export registerStreamErrorCodes() and StreamError

3. Types (src/types/common.ts)

• Define and export ReadableOptions, TransformOptions, InstrumentOptions
• Write common.md

4. Readable factories

• fromArray in src/readable/from-array/
• fromAsyncGenerator in src/readable/from-generator/
• fromBytes in src/readable/from-bytes/
• Each: .ts, .md, .test.ts, index.ts

5. Transform factories

• mapStream, filterStream, flatMapStream, batchStream, tapStream, limitStream in src/transforms/
• encodeTextStream, decodeTextStream in src/transforms/text-codec/
• compressStream, decompressStream (using CompressionStream / DecompressionStream WHATWG API) in src/transforms/compress/
• Each: .ts, .md, .test.ts, index.ts; highWaterMark and AbortSignal support

6. Sink utilities

• toArray, toBytes, toString, forEach, toWritable in src/sinks/
• Each: .ts, .md, .test.ts, index.ts; AbortSignal cancellation

7. Pipeline builder (src/pipeline/pipeline-builder/)

• Implement type-safe PipelineBuilder<T> with .pipe(), .collect(), .drain(), .forEach()
• fanOut and merge in respective src/pipeline/ subdirectories
• Each: .ts, .md, .types.ts, .test.ts, index.ts

8. Instrumentation (src/instrument/instrument-transform/)

• Implement instrumentTransform wrapping any named transform with OTel span + counters
• Write .md, .types.ts, .test.ts, index.ts

9. Node.js adapters (src/node/node-adapters.ts)

• fromNodeReadable, toNodeReadable, fromNodeWritable
• Guard with typeof process !== 'undefined' check; throw StreamError in browser contexts
• Write node-adapters.md and node-adapters.test.ts

10. OTel instrumentation

• Add spans, counters, histograms per proposal.md §4

11. Tests

• Unit tests co-located (100% coverage target)
• tests/integration.test.ts — multi-stage pipelines including Node adapter
• tests/property.test.ts — fast-check properties per proposal.md §5

12. Benchmarks (src/__benchmarks__/streams.bench.ts)

• Implement benchmark cases per proposal.md §6

13. Docs

• Every .ts implementation file has a sibling .md
• Root README.md

14. Pre-publish gate

• bunx turbo lint typecheck test --filter=@suaveplan/streams green
• bunx turbo test:coverage --filter=@suaveplan/streams ≥ 100% on touched modules

15. Publish

• bun scripts/publish.ts --package @suaveplan/streams

16. Archive

• Fold spec delta into openspec/specs/streams/spec.md
• mv openspec/changes/enterprise-streams openspec/archive/2026-04-24-enterprise-streams