@soffinal/stream 0.2.3 → 0.3.0

package/dist/transformers/filter.d.ts

@@ -1,96 +0,0 @@
-import { Stream } from "../stream.ts";
-/**
- * Adaptive filter transformer that maintains state and can terminate streams.
- * Supports multiple concurrency strategies for async predicates.
- *
- * @template VALUE - The type of values flowing through the stream
- * @template STATE - The type of the internal state object
- * @template FILTERED - The type of filtered values (for type guards)
- *
- * @param initialStateOrPredicate - Initial state object or predicate function
- * @param statefulPredicateOrOptions - Stateful predicate function or options for simple predicates
- *
- * @returns A transformer function that can be used with `.pipe()`
- *
- * @see {@link Stream} - Complete copy-paste transformers library
- *
- * @example
- * // Simple synchronous filtering
- * stream.pipe(filter((value) => value > 0))
- *
- * @example
- * // Type guard filtering (synchronous only)
- * stream.pipe(filter((value): value is number => typeof value === "number"))
- *
- * @example
- * // Async filtering with sequential strategy (default)
- * stream.pipe(
- *   filter(async (value) => {
- *     const valid = await validateAsync(value);
- *     return valid;
- *   })
- * )
- *
- * @example
- * // Async filtering with concurrent-unordered strategy
- * stream.pipe(
- *   filter(async (value) => {
- *     const result = await expensiveCheck(value);
- *     return result;
- *   }, { strategy: "concurrent-unordered" })
- * )
- *
- * @example
- * // Async filtering with concurrent-ordered strategy
- * stream.pipe(
- *   filter(async (value) => {
- *     const result = await apiValidation(value);
- *     return result;
- *   }, { strategy: "concurrent-ordered" })
- * )
- *
- * @example
- * // Stateful filtering (always sequential)
- * stream.pipe(
- *   filter({ count: 0 }, (state, value) => {
- *     if (state.count >= 10) return; // Terminate after 10 items
- *     return [value > 0, { count: state.count + 1 }];
- *   })
- * )
- *
- * @example
- * // Stateful filtering with complex state
- * stream.pipe(
- *   filter({ seen: new Set() }, (state, value) => {
- *     if (state.seen.has(value)) return [false, state]; // Duplicate
- *     state.seen.add(value);
- *     return [true, state]; // First occurrence
- *   })
- * )
- *
- * @example
- * // Stream termination
- * stream.pipe(
- *   filter(async (value) => {
- *     if (value === "STOP") return; // Terminates stream
- *     return value.length > 3;
- *   })
- * )
- */
-export declare const filter: filter.Filter;
-export declare namespace filter {
-    type Options = {
-        strategy: "sequential" | "concurrent-unordered" | "concurrent-ordered";
-    };
-    type Predicate<VALUE = unknown> = (value: VALUE) => boolean | void | Promise<boolean | void>;
-    type GuardPredicate<VALUE = unknown, FILTERED extends VALUE = VALUE> = (value: VALUE) => value is FILTERED;
-    type StatefulPredicate<VALUE = unknown, STATE extends Record<string, unknown> = {}> = (state: STATE, value: VALUE) => [boolean, STATE] | void | Promise<[boolean, STATE] | void>;
-    type StatefulGuardPredicate<VALUE = unknown, STATE extends Record<string, unknown> = {}, FILTERED extends VALUE = VALUE> = (state: STATE, value: VALUE) => [boolean, STATE, FILTERED] | void | Promise<[boolean, STATE, FILTERED] | void>;
-    interface Filter {
-        <VALUE, FILTERED extends VALUE = VALUE>(predicate: GuardPredicate<VALUE, FILTERED>): (stream: Stream<VALUE>) => Stream<FILTERED>;
-        <VALUE>(predicate: Predicate<VALUE>, options?: Options): (stream: Stream<VALUE>) => Stream<VALUE>;
-        <VALUE, STATE extends Record<string, unknown> = {}>(initialState: STATE, predicate: StatefulPredicate<VALUE, STATE>): (stream: Stream<VALUE>) => Stream<VALUE>;
-        <VALUE, STATE extends Record<string, unknown> = {}, FILTERED extends VALUE = VALUE>(initialState: STATE, predicate: StatefulGuardPredicate<VALUE, STATE, FILTERED>): (stream: Stream<VALUE>) => Stream<FILTERED>;
-    }
-}
-//# sourceMappingURL=filter.d.ts.map

package/dist/transformers/filter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/transformers/filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MA+G3B,CAAC;AAEF,yBAAiB,MAAM,CAAC;IACtB,KAAY,OAAO,GAAG;QAAE,QAAQ,EAAE,YAAY,GAAG,sBAAsB,GAAG,oBAAoB,CAAA;KAAE,CAAC;IACjG,KAAY,SAAS,CAAC,KAAK,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACpG,KAAY,cAAc,CAAC,KAAK,GAAG,OAAO,EAAE,QAAQ,SAAS,KAAK,GAAG,KAAK,IAAI,CAAC,KAAK,EAAE,KAAK,KAAK,KAAK,IAAI,QAAQ,CAAC;IAClH,KAAY,iBAAiB,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,IAAI,CAC3F,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,KACT,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IAChE,KAAY,sBAAsB,CAChC,KAAK,GAAG,OAAO,EACf,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,EAC1C,QAAQ,SAAS,KAAK,GAAG,KAAK,IAC5B,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;IACnH,UAAiB,MAAM;QACrB,CAAC,KAAK,EAAE,QAAQ,SAAS,KAAK,GAAG,KAAK,EAAE,SAAS,EAAE,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,CACnF,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAClB,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEtB,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC;QAElG,CAAC,KAAK,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,EAChD,YAAY,EAAE,KAAK,EACnB,SAAS,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC,GACzC,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC;QAE5C,CAAC,KAAK,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,SAAS,KAAK,GAAG,KAAK,EAChF,YAAY,EAAE,KAAK,EACnB,SAAS,EAAE,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,GACxD,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,QAAQ,CAAC,CAAC;KAChD;CACF"}

package/dist/transformers/flat.d.ts

@@ -1,31 +0,0 @@
-import { Stream } from "../stream.ts";
-/**
- * Flatten arrays in a stream, converting 1 array event into N individual events.
- *
- * @template VALUE - The type of values in the stream (should be arrays)
- * @template DEPTH - The depth of flattening (0 = one level, 1 = two levels, etc.)
- *
- * @param depth - How many levels deep to flatten (default: 0 = one level)
- *
- * @returns A transformer that flattens array values into individual events
- *
- * @see {@link Stream} - Complete copy-paste transformers library
- *
- * @example
- * // Basic flattening - 1 array → N events
- * const arrayStream = new Stream<number[]>();
- * const individualNumbers = arrayStream.pipe(flat());
- *
- * arrayStream.push([1, 2, 3]); // Emits: 1, 2, 3 as separate events
- *
- * @example
- * // Deep flattening
- * const deepArrays = new Stream<number[][]>();
- * const flattened = deepArrays.pipe(flat(1)); // Flatten 2 levels
- *
- * deepArrays.push([[1, 2], [3, 4]]);
- * // Emits: 1, 2, 3, 4 as separate events
- *
- */
-export declare function flat<VALUE, DEPTH extends number = 0>(depth?: DEPTH): (stream: Stream<VALUE>) => Stream<FlatArray<VALUE, DEPTH>>;
-//# sourceMappingURL=flat.d.ts.map

package/dist/transformers/flat.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"flat.d.ts","sourceRoot":"","sources":["../../src/transformers/flat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,KAAK,SAAS,MAAM,GAAG,CAAC,EAClD,KAAK,GAAE,KAAkB,GACxB,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAe5D"}

package/dist/transformers/map.d.ts

@@ -1,106 +0,0 @@
-import { Stream } from "../stream.ts";
-/**
- * Adaptive map transformer that transforms values while maintaining state.
- * Supports multiple concurrency strategies for async mappers.
- *
- * @template VALUE - The type of input values
- * @template STATE - The type of the internal state object
- * @template MAPPED - The type of output values after transformation
- *
- * @param initialStateOrMapper - Initial state object or mapper function
- * @param statefulMapperOrOptions - Stateful mapper function or options for simple mappers
- *
- * @returns A transformer function that can be used with `.pipe()`
- *
- * @see {@link Stream} - Complete copy-paste transformers library
- *
- * @example
- * // Simple synchronous transformation
- * stream.pipe(map((value) => value * 2))
- *
- * @example
- * // Type transformation
- * stream.pipe(map((value: number) => value.toString()))
- *
- * @example
- * // Async transformation with sequential strategy (default)
- * stream.pipe(
- *   map(async (value) => {
- *     const result = await processAsync(value);
- *     return result;
- *   })
- * )
- *
- * @example
- * // Async transformation with concurrent-unordered strategy
- * stream.pipe(
- *   map(async (value) => {
- *     const enriched = await enrichWithAPI(value);
- *     return enriched;
- *   }, { strategy: "concurrent-unordered" })
- * )
- *
- * @example
- * // Async transformation with concurrent-ordered strategy
- * stream.pipe(
- *   map(async (value) => {
- *     const processed = await heavyProcessing(value);
- *     return processed;
- *   }, { strategy: "concurrent-ordered" })
- * )
- *
- * @example
- * // Stateful transformation (always sequential)
- * stream.pipe(
- *   map({ sum: 0 }, (state, value) => {
- *     const newSum = state.sum + value;
- *     return [{ value, runningSum: newSum }, { sum: newSum }];
- *   })
- * )
- *
- * @example
- * // Complex stateful transformation
- * stream.pipe(
- *   map({ count: 0, items: [] }, (state, value) => {
- *     const newItems = [...state.items, value];
- *     const newCount = state.count + 1;
- *     return [
- *       {
- *         item: value,
- *         index: newCount,
- *         total: newItems.length,
- *         history: newItems
- *       },
- *       { count: newCount, items: newItems }
- *     ];
- *   })
- * )
- *
- * @example
- * // Async stateful transformation
- * stream.pipe(
- *   map({ cache: new Map() }, async (state, value) => {
- *     const cached = state.cache.get(value);
- *     if (cached) return [cached, state];
- *
- *     const processed = await expensiveOperation(value);
- *     const newCache = new Map(state.cache);
- *     newCache.set(value, processed);
- *
- *     return [processed, { cache: newCache }];
- *   })
- * )
- */
-export declare const map: map.Map;
-export declare namespace map {
-    type Options = {
-        strategy: "sequential" | "concurrent-unordered" | "concurrent-ordered";
-    };
-    type Mapper<VALUE = unknown, MAPPED = VALUE> = (value: VALUE) => MAPPED | Promise<MAPPED>;
-    type StatefulMapper<VALUE = unknown, STATE extends Record<string, unknown> = {}, MAPPED = VALUE> = (state: STATE, value: VALUE) => [MAPPED, STATE] | Promise<[MAPPED, STATE]>;
-    interface Map {
-        <VALUE, MAPPED>(mapper: Mapper<VALUE, MAPPED>, options?: Options): (stream: Stream<VALUE>) => Stream<MAPPED>;
-        <VALUE, STATE extends Record<string, unknown> = {}, MAPPED = VALUE>(initialState: STATE, mapper: StatefulMapper<VALUE, STATE, MAPPED>): (stream: Stream<VALUE>) => Stream<MAPPED>;
-    }
-}
-//# sourceMappingURL=map.d.ts.map

package/dist/transformers/map.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../src/transformers/map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AACH,eAAO,MAAM,GAAG,EAAE,GAAG,CAAC,GAwFrB,CAAC;AAEF,yBAAiB,GAAG,CAAC;IACnB,KAAY,OAAO,GAAG;QAAE,QAAQ,EAAE,YAAY,GAAG,sBAAsB,GAAG,oBAAoB,CAAA;KAAE,CAAC;IACjG,KAAY,MAAM,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK,IAAI,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjG,KAAY,cAAc,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,GAAG,KAAK,IAAI,CACxG,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,KACT,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;IAEhD,UAAiB,GAAG;QAClB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7G,CAAC,KAAK,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,GAAG,KAAK,EAChE,YAAY,EAAE,KAAK,EACnB,MAAM,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,GAC3C,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC;KAC9C;CACF"}

package/dist/transformers/merge.d.ts

@@ -1,33 +0,0 @@
-import { Stream } from "../stream.ts";
-/**
- * Merge multiple streams into a single stream with temporal ordering.
- *
- * @template VALUE - The type of values from the source stream
- * @template STREAMS - Tuple type of additional streams to merge
- *
- * @param streams - Additional streams to merge with the source stream
- *
- * @returns A transformer that merges all streams into one with union types
- *
- * @see {@link Stream} - Complete copy-paste transformers library
- *
- * @example
- * // Basic merge with type safety
- * const numbers = new Stream<number>();
- * const strings = new Stream<string>();
- * const merged = numbers.pipe(merge(strings));
- * // Type: Stream<number | string>
- *
- * @example
- * // Multiple streams
- * const stream1 = new Stream<number>();
- * const stream2 = new Stream<string>();
- * const stream3 = new Stream<boolean>();
- *
- * const combined = stream1.pipe(merge(stream2, stream3));
- * // Type: Stream<number | string | boolean>
- *
-
- */
-export declare function merge<VALUE, STREAMS extends [Stream<any>, ...Stream<any>[]]>(...streams: STREAMS): (stream: Stream<VALUE>) => Stream<VALUE | Stream.ValueOf<STREAMS[number]>>;
-//# sourceMappingURL=merge.d.ts.map

package/dist/transformers/merge.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/transformers/merge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAC1E,GAAG,OAAO,EAAE,OAAO,GAClB,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CA0B5E"}

package/src/transformers/filter.md

@@ -1,326 +0,0 @@
-# Filter Transformer
-
-The `filter` transformer selectively passes values through a stream based on predicate functions. It supports synchronous and asynchronous filtering, type guards, stateful operations, and multiple concurrency strategies.
-
-## Quick Start
-
-```typescript
-import { Stream, filter } from "@soffinal/stream";
-
-const numbers = new Stream<number>();
-
-// Simple filtering
-const positives = numbers.pipe(filter((n) => n > 0));
-
-positives.listen(console.log);
-numbers.push(-1, 2, -3, 4); // Outputs: 2, 4
-```
-
-## Basic Usage
-
-### Synchronous Filtering
-
-```typescript
-// Basic predicate
-stream.pipe(filter((value) => value > 10));
-
-// Complex conditions
-stream.pipe(filter((user) => user.active && user.age >= 18));
-
-// Null/undefined filtering
-stream.pipe(filter((value) => value != null));
-```
-
-### Type Guards
-
-Filter supports TypeScript type guards for type narrowing:
-
-```typescript
-const mixed = new Stream<string | number>();
-
-// Type narrows to Stream<number>
-const numbers = mixed.pipe(filter((value): value is number => typeof value === "number"));
-
-// Type narrows to Stream<string>
-const strings = mixed.pipe(filter((value): value is string => typeof value === "string"));
-```
-
-## Asynchronous Filtering
-
-### Sequential Processing (Default)
-
-```typescript
-const stream = new Stream<string>();
-
-const validated = stream.pipe(
-  filter(async (email) => {
-    const isValid = await validateEmail(email);
-    return isValid;
-  })
-);
-```
-
-### Concurrent Strategies
-
-For expensive async predicates, choose a concurrency strategy:
-
-#### Concurrent Unordered
-
-Results emit as soon as they complete, potentially out of order:
-
-```typescript
-const stream = new Stream<string>();
-
-const validated = stream.pipe(
-  filter(
-    async (url) => {
-      const isReachable = await checkURL(url);
-      return isReachable;
-    },
-    { strategy: "concurrent-unordered" }
-  )
-);
-
-// URLs may emit in different order based on response times
-```
-
-#### Concurrent Ordered
-
-Parallel processing but maintains original order:
-
-```typescript
-const stream = new Stream<User>();
-
-const verified = stream.pipe(
-  filter(
-    async (user) => {
-      const isVerified = await verifyUser(user.id);
-      return isVerified;
-    },
-    { strategy: "concurrent-ordered" }
-  )
-);
-
-// Users always emit in original order despite varying verification times
-```
-
-## Stateful Filtering
-
-Maintain state across filter operations for complex logic:
-
-### Basic Stateful Filtering
-
-```typescript
-const stream = new Stream<number>();
-
-// Take only first 5 items
-const limited = stream.pipe(
-  filter({ count: 0 }, (state, value) => {
-    if (state.count >= 5) return; // Terminate stream
-    return [true, { count: state.count + 1 }];
-  })
-);
-```
-
-### Advanced State Management
-
-```typescript
-const stream = new Stream<string>();
-
-// Deduplicate values
-const unique = stream.pipe(
-  filter({ seen: new Set<string>() }, (state, value) => {
-    if (state.seen.has(value)) {
-      return [false, state]; // Skip duplicate
-    }
-
-    const newSeen = new Set(state.seen);
-    newSeen.add(value);
-    return [true, { seen: newSeen }];
-  })
-);
-```
-
-### Complex Stateful Logic
-
-```typescript
-const events = new Stream<{ type: string; timestamp: number }>();
-
-// Rate limiting: max 5 events per second
-const rateLimited = events.pipe(
-  filter(
-    {
-      timestamps: [] as number[],
-      maxPerSecond: 5,
-    },
-    (state, event) => {
-      const now = event.timestamp;
-      const recent = state.timestamps.filter((t) => now - t < 1000);
-
-      if (recent.length >= state.maxPerSecond) {
-        return [false, { ...state, timestamps: recent }];
-      }
-
-      return [
-        true,
-        {
-          ...state,
-          timestamps: [...recent, now],
-        },
-      ];
-    }
-  )
-);
-```
-
-## Stream Termination
-
-Filters can terminate streams by returning `undefined`:
-
-```typescript
-const stream = new Stream<string>();
-
-const untilStop = stream.pipe(
-  filter((value) => {
-    if (value === "STOP") return; // Terminates stream
-    return value.length > 0;
-  })
-);
-
-stream.push("hello", "world", "STOP", "ignored");
-// Only "hello" and "world" are emitted
-```
-
-### Conditional Termination
-
-```typescript
-const numbers = new Stream<number>();
-
-const untilNegative = numbers.pipe(
-  filter({ sum: 0 }, (state, value) => {
-    const newSum = state.sum + value;
-    if (newSum < 0) return; // Terminate when sum goes negative
-
-    return [value > 0, { sum: newSum }];
-  })
-);
-```
-
-## Performance Considerations
-
-### When to Use Concurrency
-
-- **Sequential**: Default choice, maintains order, lowest overhead
-- **Concurrent-unordered**: Use when order doesn't matter and predicates are expensive
-- **Concurrent-ordered**: Use when order matters but predicates are expensive
-
-### Memory Management
-
-Stateful filters maintain state objects. For large datasets:
-
-```typescript
-// Good: Bounded state
-filter({ count: 0, limit: 1000 }, (state, value) => {
-  if (state.count >= state.limit) return;
-  return [predicate(value), { ...state, count: state.count + 1 }];
-});
-
-// Avoid: Unbounded state growth
-filter({ history: [] }, (state, value) => {
-  // This grows indefinitely!
-  return [true, { history: [...state.history, value] }];
-});
-```
-
-## Error Handling
-
-Errors in predicates will propagate and potentially terminate the stream:
-
-```typescript
-const stream = new Stream<number>();
-
-const safe = stream.pipe(
-  filter((value) => {
-    try {
-      return riskyPredicate(value);
-    } catch (error) {
-      console.error("Filter error:", error);
-      return false; // Skip problematic values
-    }
-  })
-);
-```
-
-## Common Patterns
-
-### Throttling
-
-```typescript
-const throttle = <T>(ms: number) =>
-  filter<T, { lastEmit: number }>({ lastEmit: 0 }, (state, value) => {
-    const now = Date.now();
-    if (now - state.lastEmit < ms) {
-      return [false, state];
-    }
-    return [true, { lastEmit: now }];
-  });
-
-stream.pipe(throttle(1000)); // Max one value per second
-```
-
-### Sampling
-
-```typescript
-const sample = <T>(n: number) =>
-  filter<T, { count: number }>({ count: 0 }, (state, value) => {
-    const shouldEmit = (state.count + 1) % n === 0;
-    return [shouldEmit, { count: state.count + 1 }];
-  });
-
-stream.pipe(sample(3)); // Every 3rd value
-```
-
-### Windowing
-
-```typescript
-const slidingWindow = <T>(size: number) =>
-  filter<T, { window: T[] }>({ window: [] }, (state, value) => {
-    const newWindow = [...state.window, value].slice(-size);
-    const shouldEmit = newWindow.length === size;
-
-    return [shouldEmit, { window: newWindow }];
-  });
-
-stream.pipe(slidingWindow(5)); // Emit when window is full
-```
-
-## Type Signatures
-
-```typescript
-// Simple predicate with optional concurrency
-filter<VALUE>(
-  predicate: (value: VALUE) => boolean | void | Promise<boolean | void>,
-  options?: { strategy: "sequential" | "concurrent-unordered" | "concurrent-ordered" }
-): (stream: Stream<VALUE>) => Stream<VALUE>
-
-// Type guard predicate (synchronous only)
-filter<VALUE, FILTERED extends VALUE>(
-  predicate: (value: VALUE) => value is FILTERED
-): (stream: Stream<VALUE>) => Stream<FILTERED>
-
-// Stateful predicate (always sequential)
-filter<VALUE, STATE>(
-  initialState: STATE,
-  predicate: (state: STATE, value: VALUE) => [boolean, STATE] | void
-): (stream: Stream<VALUE>) => Stream<VALUE>
-```
-
-## Best Practices
-
-1. **Choose the right strategy**: Use sequential for simple predicates, concurrent for expensive async operations
-2. **Manage state size**: Keep stateful filter state bounded to prevent memory leaks
-3. **Handle errors gracefully**: Wrap risky predicates in try-catch blocks
-4. **Use type guards**: Leverage TypeScript's type narrowing for better type safety
-5. **Consider termination**: Use `return undefined` to cleanly terminate streams when conditions are met
-
-The filter transformer is a powerful tool for stream processing that scales from simple synchronous predicates to complex stateful async operations with optimal performance characteristics.

package/src/transformers/flat.md

@@ -1,56 +0,0 @@
-# Flat Transformer
-
-## Event Multiplication
-
-The `flat` transformer converts array events into individual events - essentially `Array.prototype.flat()` for streams.
-
-**Core Concept**: 1 array event → N individual events
-
-## Usage
-
-```typescript
-stream.pipe(flat(depth?));
-```
-
-- **Input**: `Stream<T[]>`
-- **Output**: `Stream<T>`
-- **Transformation**: Each array becomes separate events
-
-## Basic Example
-
-```typescript
-const arrayStream = new Stream<number[]>();
-const flattened = arrayStream.pipe(flat());
-
-arrayStream.push([1, 2, 3]);
-// Emits: 1, 2, 3 as separate events
-
-flattened.listen((value) => console.log(value));
-// Logs: 1, 2, 3
-```
-
-## Depth Control
-
-```typescript
-const nested = new Stream<number[][]>();
-const flattened = nested.pipe(flat(1)); // Flatten 2 levels
-
-nested.push([
-  [1, 2],
-  [3, 4],
-]);
-// Emits: 1, 2, 3, 4 as separate events
-```
-
-## Common Pattern
-
-```typescript
-// Map then flatten
-const sentences = new Stream<string>();
-const characters = sentences.pipe(map({}, (_, s) => [s.split(""), {}])).pipe(flat());
-
-sentences.push("hello");
-// Emits: 'h', 'e', 'l', 'l', 'o' as separate events
-```
-
-That's it. Simple event multiplication for arrays.