Nozzle Development Guide

Adding New Functions

Checklist

1. Create src/transforms/yourFunction.ts
2. Export from src/transforms/index.ts
3. Add method to Pipeline class in src/pipeline.ts
4. Create tests in test/yourFunction.test.ts
5. Add JSDoc with @group tag (Timing, Buffering, Filtering, Transformation, or Utilities)
6. Run pnpm test && pnpm lint && pnpm build-fast

Basic Pattern

export async function* yourFunction<T>(source: AsyncIterable<T>, param: P): AsyncGenerator<T> {
  for await (const item of source) {
    yield transformedItem
  }
}

Reference Examples

• Simple transforms: map.ts, filter.ts
• Timing: minInterval.ts, throttle.ts
• Buffering: buffer.ts, chunk.ts
• String-specific: split.ts, replace.ts

Async Error Handling

Critical rule: Errors must be thrown during await ticks, not in callbacks.

Errors in setTimeout/Promise.race callbacks escape user try/catch blocks. Instead, store errors and rethrow on the next await:

export async function* myTimingFunction<T>(source: AsyncIterable<T>) {
  let error: Error | null = null

  const consumer = (async () => {
    try {
      for await (const item of source) {
        /* ... */
      }
    } catch (err) {
      error = err instanceof Error ? err : new Error(String(err))
    }
  })()

  while (true) {
    if (error) throw error // Thrown during await tick - catchable by user
    // ... yield logic
  }
}

When to apply: Any function using setTimeout, setInterval, Promise.race, or background async operations.

Reference: buffer.ts has the canonical error handling pattern.

Testing Requirements

1. Basic functionality with typical inputs
2. Edge cases: empty sources, single items, boundaries
3. Error handling: source errors must be catchable
4. Return value preservation: verify with consume().return()
5. Timing behavior (if applicable): use test/timing-helpers.ts

Gotchas

• Return types: Functions like tap() must pass through parent's return type, not just yield type
• Forgetting exports: Add to both transforms/index.ts AND pipeline.ts
• Pipeline integration: Generic methods go first in Pipeline class; string-specific methods go in second section with type constraints