@soffinal/stream 0.2.0 → 0.2.2

package/src/transformers/filter.md

@@ -121,8 +121,6 @@ const take = <T>(n: number) =>
   });
 ```
 
-**Psychology**: `take` demonstrates **self-limiting behavior** - the filter knows its purpose and fulfills it completely, then gracefully terminates.
-
 ### distinct - The Memory Gatekeeper
 
 ```typescript
@@ -134,7 +132,19 @@ const distinct = <T>() =>
   });
 ```
 
-**Philosophy**: `distinct` embodies **perfect memory** - it never forgets what it has seen, ensuring uniqueness through accumulated values.
+### tap - The Observer Gatekeeper
+
+```typescript
+const tap = <T>(fn: (value: T) => void | Promise<void>) =>
+  filter<T, {}>({}, async (_, value) => {
+    await fn(value);
+    return [true, {}]; // Always pass through
+  });
+
+// Usage: Side effects without changing the stream
+stream.pipe(tap((value) => console.log("Saw:", value)));
+stream.pipe(tap(async (value) => await logToDatabase(value)));
+```
 
 ## The Termination
 
@@ -151,6 +161,37 @@ const untilCondition = <T>(condition: (value: T) => boolean) =>
 
 This represents a fundamental shift from infinite streams to **purpose-driven streams** that know when their work is done.
 
+## Enhanced Pipe Integration
+
+The new pipe architecture enables seamless integration:
+
+```typescript
+// Filter integrates with any transformer
+const result = stream
+  .pipe(filter({}, (_, v) => [v > 0, {}])) // Returns Stream<T>
+  .pipe(map({}, (_, v) => [v.toString(), {}])) // Returns Stream<string>
+  .pipe(toState("0")); // Returns State<string>
+
+// Complex filtering chains
+const processed = source
+  .pipe(
+    filter({ seen: 0 }, (state, v) => {
+      if (state.seen >= 100) return; // Terminate after 100
+      return [v > 0, { seen: state.seen + 1 }];
+    })
+  )
+  .pipe(tap((v) => console.log("Positive:", v)))
+  .pipe(
+    filter({ count: 0 }, (state, v) => {
+      return [state.count % 2 === 0, { count: state.count + 1 }]; // Every other
+    })
+  );
+```
+
+**Note**: Filters compose naturally because they all speak the same language - **adaptive constraints** that can terminate, remember, and evolve.
+
+**Design insight**: Filtering State creates **conditional reactivity** - the derived state only reacts to values that pass the adaptive constraints.
+
 ## Conclusion
 
 The `filter` transformer isn't just about removing unwanted values - it's about **intelligent gatekeeping** that:

package/src/transformers/map.md

@@ -146,6 +146,36 @@ const pluck = <T, K extends keyof T>(key: K) => map<T, {}, T[K]>({}, (_, value)
 
 `pluck` demonstrates **selective transformation** - the alchemist knows exactly what it wants and ignores everything else.
 
+### tap - The Observer Gatekeeper
+
+```typescript
+const tap = <T>(fn: (value: T) => void | Promise<void>) =>
+  map<T, {}, T>({}, async (_, value) => {
+    await fn(value);
+    return [value, {}]; // Always pass through
+  });
+
+// Usage: Side effects without changing the stream
+stream.pipe(tap((value) => console.log("Saw:", value)));
+stream.pipe(tap(async (value) => await logToDatabase(value)));
+```
+
+### scan - The Accumulating Alchemist
+
+```typescript
+const scan = <T, U>(fn: (acc: U, value: T) => U, initial: U) =>
+  map<T, { acc: U }, U>({ acc: initial }, (state, value) => {
+    const newAcc = fn(state.acc, value);
+    return [newAcc, { acc: newAcc }];
+  });
+
+// Usage: Accumulate values over time
+stream.pipe(scan((sum, value) => sum + value, 0)); // Running sum
+stream.pipe(scan((max, value) => Math.max(max, value), -Infinity)); // Running max
+```
+
+`scan` demonstrates **accumulative transformation** - each value builds upon all previous values, creating a growing understanding.
+
 ## The Order Preservation
 
 Async transformations maintain order because **sequence matters**. Even if transformation B completes before transformation A, the stream waits. This isn't just about correctness - it's about **respecting the narrative** of the data.
@@ -182,3 +212,5 @@ The `map` transformer isn't just about changing values - it's about **intelligen
 - **Learns** from patterns (adaptation)
 - **Evolves** its approach over time (constraints)
 - **Preserves** the narrative order (respect)
+- **Integrates** with reactive state (toState)
+- **Accumulates** knowledge over time (scan)

package/CHANGELOG.md

@@ -1,22 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.2.0] - 2024-12-19
-
-### Changed
-
-- **BREAKING**: Removed instance methods for transformers from Stream class - use `.pipe()` exclusively
-- **BREAKING**: filte and map transformers signatures now require state-based accumulators instead of simple sync/async predicates
-- Improved internal transformer implementation
-
-## [0.1.4] - 2024-12-18
-
-[Unreleased]: https://github.com/soffinal/stream/compare/v0.1.4...HEAD
-[0.2.0]: https://github.com/soffinal/stream/compare/v0.1.4...v0.2.0
-[0.1.4]: https://github.com/soffinal/stream/releases/tag/v0.1.4