@soffinal/stream 0.1.0 → 0.1.3

package/README.md

@@ -1,290 +1,183 @@
 # @soffinal/stream
 
-Reactive async-first streaming library with functional transformations and reactive data structures. Build real-time apps with streams, state management, and event-driven collections.
-
-## Key Features
-
-- **Multicast by Default**: One stream, many consumers - perfect for event systems
-- **Awaitable Streams**: Simply `await stream` to get the next value
-- **Async Iterable**: Use `for await` loops to process data as it flows
-- **Lazy & Shared**: All operation run once per event, results shared across all listeners
-- **Auto Cleanup**: Resources freed automatically when no longer needed
-- **Async & Stateful Transformers**: Filter, map, group accept sync/async predicates and can maintain state
-- **Custom Transformers**: Build your own transformers like throttle, debounce, distinctUntilChanged
-- **Reactive State**: State objects that automatically notify dependents of changes
-- **Reactive Collections**: Lists, Maps, Sets that emit change events
-
-**@soffinal/stream** treats asynchronous data flow as the primary concern, making it useful for:
-
-- Real-time data processing
-- Event-driven architectures
-- Streaming APIs and WebSockets
-- State management
-- Memory-efficient data pipelines
-- UI updates
-
-## The Stream: Your Data Pipeline Foundation
-
-A `Stream` is an async iterable that can push values to multiple listeners, while also being a promise for the next value. Think of it as a data pipe where information flows through - multiple consumers can tap into the same flow to receive all values, or you can simply await the stream to get the next single value.
-
-```typescript
-import { Stream } from "@soffinal/stream";
-
-// Create a data pipeline
-const userEvents = new Stream<{ userId: string; action: string }>();
-
-// Multiple consumers can listen to the same stream
-userEvents.listen((event) => logToAnalytics(event));
-userEvents.listen((event) => updateUserActivity(event));
-userEvents.listen((event) => triggerNotifications(event));
-
-// Push data through the pipeline
-userEvents.push({ userId: "alice", action: "login" }, { userId: "bob", action: "purchase" });
-// All three listeners receive both events
-
-// Stream is also a promise for the next value
-const nextEvent = await userEvents; // Waits for next pushed value
-console.log("Next event:", nextEvent);
-```
-
-### Async Iteration: Processing Data as it Flows
-
-Streams implement `AsyncIterable`, allowing you to process data as it arrives using `for await` loops:
+[![npm version](https://badge.fury.io/js/@soffinal%2Fstream.svg)](https://badge.fury.io/js/@soffinal%2Fstream)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@soffinal/stream)](https://bundlephobia.com/package/@soffinal/stream)
+
+> **High-performance reactive streaming library for TypeScript/JavaScript**
+
+A modern, async-first streaming library that treats asynchronous data flow as a first-class citizen. Built for real-time applications, event-driven architectures, and reactive programming patterns.
+
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+- [Performance](#performance)
+- [Browser Support](#browser-support)
+- [Migration Guide](#migration-guide)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- 🚀 **High Performance** - Optimized for speed and efficiency
+- 🔄 **Multicast by Default** - One stream, many consumers
+- ⏳ **Awaitable Streams** - `await stream` for next value
+- 🔁 **Async Iterable** - Use `for await` loops naturally
+- 🧠 **Smart Caching** - Operations run once, results shared
+- 🗑️ **Auto Cleanup** - Memory management handled automatically
+- 🔧 **Dual Programming Paradigms** - Method chaining or functional pipe composition
+- 🛠️ **Custom Transformers** - Create reusable transformers in both OOP and functional styles
+- 📊 **Reactive Collections** - Lists, Maps, Sets with fine-grained change events
+- 🔀 **Stateful Operations** - Built-in support for stateful filtering, mapping, and grouping
+- 📦 **Zero Dependencies** - Lightweight (~6KB minified, ~2KB gzipped) and tree-shakeable
+- 🌐 **Universal** - Node.js, browsers, Deno, Bun, Cloudflare Workers
+- 📘 **Full TypeScript** - Complete type safety and inference
+
+## Quick Start
 
 ```typescript
-const messageStream = new Stream<string>();
-
-// Process messages as they arrive
-(async () => {
-  for await (const message of messageStream) {
-    await processMessage(message);
-    if (message === "shutdown") break;
-  }
-})();
+import { Stream, State } from "@soffinal/stream";
 
-messageStream.push("user-login", "data-sync", "shutdown");
-```
+// Create reactive data streams
+const events = new Stream<string>();
+const counter = new State(0);
 
-### Generator-based Streams: Infinite Data Sources
+// Transform and filter data
+const processed = events.filter((msg) => msg.length > 3).map((msg) => msg.toUpperCase());
 
-Create infinite, lazy data sources using async generators:
+// Multiple consumers
+processed.listen((msg) => console.log("Logger:", msg));
+processed.listen((msg) => updateUI(msg));
 
-```typescript
-const sensorStream = new Stream(async function* () {
-  while (true) {
-    const temperature = await readTemperatureSensor();
-    const humidity = await readHumiditySensor();
-    yield { temperature, humidity, timestamp: Date.now() };
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-  }
-});
+// Push data through the pipeline
+events.push("hello", "hi", "world"); // Only 'HELLO' and 'WORLD' processed
 
-sensorStream.listen((data) => console.log("Sensor reading:", data));
+// Reactive state management
+counter.listen((count) => (document.title = `Count: ${count}`));
+counter.value++; // UI updates automatically
 ```
 
-### Instance Transformers
-
-Streams support method chaining for familiar object-oriented programming patterns:
-
-#### Filter: Smart Data Selection
-
-Filtering goes beyond simple predicates - it supports stateful filtering and async predicates:
-
-```typescript
-const events = new Stream<{ type: string; userId: string; data: any }>();
-
-// Simple filtering
-const loginEvents = events.filter((e) => e.type === "login");
-
-// Stateful filtering - only allow increasing user IDs
-const validEvents = events.filter(
-  0, // initial state
-  (lastUserId, event) => {
-    const currentId = parseInt(event.userId);
-    return [currentId > lastUserId, currentId];
-  }
-);
+## Installation
 
-// Async filtering - validate against external service
-const authorizedEvents = events.filter(async (event) => {
-  const isAuthorized = await checkUserPermissions(event.userId);
-  return isAuthorized;
-});
-```
+### Package Managers
 
-#### Map: Data Transformation Pipeline
+```bash
+# npm
+npm install @soffinal/stream
 
-Mapping transforms data while maintaining the stream's async nature:
+# yarn
+yarn add @soffinal/stream
 
-```typescript
-const rawEvents = new Stream<string>();
+# pnpm
+pnpm add @soffinal/stream
 
-// Simple transformation
-const parsedEvents = rawEvents.map((json) => JSON.parse(json));
-
-// Stateful transformation - add sequence numbers
-const sequencedEvents = rawEvents.map(
-  0, // initial sequence
-  (seq, event) => [{ ...event, sequence: seq + 1 }, seq + 1]
-);
+# bun
+bun add @soffinal/stream
 
-// Async transformation - enrich with external data
-const enrichedEvents = parsedEvents.map(async (event) => {
-  const userProfile = await getUserProfile(event.userId);
-  return { ...event, user: userProfile };
-});
+# Deno
+deno add jsr:@soffinal/stream
 ```
 
-#### Merge: Combine Multiple Streams
+### CDN (Browser)
 
-Combine multiple streams into a single output stream:
+```html
+<!-- Production (minified) -->
+<script type="module">
+  import { Stream, State } from "https://cdn.jsdelivr.net/npm/@soffinal/stream@latest/dist/index.js";
+</script>
 
-```typescript
-const stream1 = new Stream<string>();
-const stream2 = new Stream<string>();
-const merged = stream1.merge(stream2);
-
-merged.listen((msg) => console.log("Merged:", msg));
-
-stream1.push("from stream1");
-stream2.push("from stream2");
+<!-- Alternative CDNs -->
+<script type="module">
+  import { Stream } from "https://esm.sh/@soffinal/stream";
+  import { Stream } from "https://cdn.skypack.dev/@soffinal/stream";
+</script>
 ```
 
-#### Group: Intelligent Batching
-
-Grouping allows you to batch data based on complex conditions:
+## Core Concepts
 
-```typescript
-const transactions = new Stream<{ amount: number; userId: string }>();
-
-// Batch by count
-const countBatches = transactions.group((batch) => batch.length >= 100);
-
-// Batch by total amount
-const amountBatches = transactions.group(
-  0, // initial sum
-  (sum, transaction) => {
-    const newSum = sum + transaction.amount;
-    return [newSum >= 10000, newSum >= 10000 ? 0 : newSum];
-  }
-);
-
-// Process batches efficiently
-amountBatches.listen(async (totalAmount) => {
-  await processBulkTransaction(totalAmount);
-});
-```
-
-#### Flat: Flatten Nested Arrays
+### Streams: Async Data Pipelines
 
-Flatten nested arrays in stream values:
+A `Stream` is an async iterable that can push values to multiple listeners while also being awaitable for the next value.
 
 ```typescript
-const arrays = new Stream<number[]>();
-const flattened = arrays.flat();
+const userEvents = new Stream<UserEvent>();
 
-flattened.listen((n) => console.log("Flat:", n));
-arrays.push([1, 2], [3, 4]);
-// Output: Flat: 1, Flat: 2, Flat: 3, Flat: 4
-
-// Deep flattening
-const nested = new Stream<number[][][]>();
-const deepFlat = nested.flat(2);
-```
-
-#### Promise Interface
-
-Streams are directly awaitable for the next event/data:
-
-```typescript
-const stream = new Stream<number>();
+// Multiple consumers
+userEvents.listen((event) => analytics.track(event));
+userEvents.listen((event) => notifications.send(event));
+userEvents.listen((event) => database.save(event));
 
-setTimeout(() => {
-  // Both resolve when stream.push() is called
-  stream.push(5); // nextValue = 5, doubled = 10
-})(async () => {
-  // Simply await the stream for the next value
-  const nextValue = await stream;
-  console.log("Received:", nextValue);
-})()(async () => {
-  // Or use .then() for transformation
-  const doubled = await stream.then((x) => x * 2);
-})();
+// Or await the next event
+const nextEvent = await userEvents;
 ```
 
-#### Listener Events
+### Transformers: Fluent & Functional Styles
 
-React to listener lifecycle changes on streams:
+#### Method Chaining (Fluent)
 
 ```typescript
 const stream = new Stream<number>();
 
-// Listen to listener lifecycle
-stream.listenerAdded.listen(() => console.log("Listener added"));
-stream.listenerRemoved.listen(() => console.log("Listener removed"));
-
-const cleanup = stream.listen((value) => console.log(value));
-cleanup(); // Triggers 'Listener removed'
-```
-
-## Functional Programming style: Composable Data Transformations
-
-The library provides functional programming patterns through the `pipe` method and transformer functions, enabling powerful composition and reusable transformation pipelines.
-
-### Pipe: Functional Composition Made Easy
-
-The `pipe` method enables functional composition of stream transformations:
-
-```typescript
-import { Stream, map, filter, group, merge, flat } from "@soffinal/stream";
-
-const numbers = new Stream<number>();
-
-// Functional composition with built-in transformers
-const result = numbers
-  .pipe(filter((n) => n > 0)) // Remove negative numbers
-  .pipe(map((n) => n * 2)) // Double each value
-  .pipe(group((batch) => batch.length >= 5)) // Group into batches of 5
-  .pipe(flat()); // Flatten the batches
+// Simple transformations
+const result = stream
+  .filter((x) => x > 0)
+  .map((x) => x * 2)
+  .group((batch) => batch.length >= 5);
 
-result.listen((value) => console.log("Processed:", value));
+// Stateful operations with initial state
+const stateful = stream
+  .filter(0, (prev, curr) => [curr > prev, Math.max(prev, curr)]) // Only increasing values
+  .map([], (history, value) => {
+    const newHistory = [...history, value].slice(-3); // Keep last 3
+    const average = newHistory.reduce((a, b) => a + b, 0) / newHistory.length;
+    return [{ value, average, history: newHistory }, newHistory];
+  })
+  .group(5, (count, item) => [count >= 5, count >= 5 ? 0 : count + 1]); // Batch every 5
 ```
 
-### Built-in Transformer Functions
-
-The library provides irreducible building block transformers that work seamlessly with pipe:
+#### Functional Composition (Pipe)
 
 ```typescript
-// Import transformer functions
-import { map, filter, group, merge, flat } from "@soffinal/stream";
-
-const stream = new Stream<number>();
+import { filter, map, group, merge } from "@soffinal/stream";
 
-// Simple transformations
-stream
-  .pipe(map((n) => n.toString())) // Stream<string>
-  .pipe(filter((s) => s.length > 1)) // Stream<string>
-  .pipe(map((s) => parseInt(s))); // Stream<number>
+// Simple functional composition
+const result = stream
+  .pipe(filter((x) => x > 0))
+  .pipe(map((x) => x * 2))
+  .pipe(group((batch) => batch.length >= 5));
 
-// Stateful transformations
-stream
+// Stateful functional transformers
+const advanced = stream
   .pipe(filter(0, (prev, curr) => [curr > prev, Math.max(prev, curr)]))
-  .pipe(map(0, (sum, n) => [sum + n, sum + n]));
+  .pipe(
+    map([], (acc, value) => {
+      const newAcc = [...acc, value].slice(-10);
+      const sum = newAcc.reduce((a, b) => a + b, 0);
+      return [{ value, sum, count: newAcc.length }, newAcc];
+    })
+  )
+  .pipe(group(0, (count, item) => [count >= 3, count >= 3 ? 0 : count + 1]));
 
-// Advanced transformations
+// Combining multiple streams
 const stream2 = new Stream<number>();
-stream
-  .pipe(merge(stream2)) // Merge multiple streams
-  .pipe(group((batch) => batch.length >= 10)) // Batch processing
-  .pipe(flat()); // Flatten results
+const merged = stream
+  .pipe(filter((x) => x % 2 === 0))
+  .pipe(merge(stream2))
+  .pipe(map((x) => x.toString()));
 ```
 
-### Custom Transformers: Building Your Own
+### Custom Transformers
 
-You can create custom transformers using generator functions:
+Create reusable transformers for both paradigms:
 
 ```typescript
-// DistinctUntilChanged transformer - only emit when value changes
+// Custom transformer: distinctUntilChanged
 const distinctUntilChanged = <T>(stream: Stream<T>): Stream<T> => {
   return new Stream<T>(async function* () {
     let prev: T;
@@ -300,7 +193,7 @@ const distinctUntilChanged = <T>(stream: Stream<T>): Stream<T> => {
   });
 };
 
-// Rate limiting transformer
+// Custom transformer: throttle
 const throttle =
   <T>(ms: number) =>
   (stream: Stream<T>): Stream<T> => {
@@ -320,272 +213,126 @@ const throttle =
 // Usage with perfect type inference
 const searchInput = new Stream<string>();
 const searchResults = searchInput
-  .pipe(distinctUntilChanged) // Only emit when search term changes
-  .pipe(throttle(1000)) // Limit API calls
+  .pipe(distinctUntilChanged)
+  .pipe(throttle(300))
   .pipe(map((query) => searchAPI(query)));
 ```
 
-### Dual Programming Paradigms
-
-@soffinal/stream supports both Object-Oriented and Functional programming styles:
-
-#### Object-Oriented Style (Method Chaining)
-
-```typescript
-// Familiar method chaining
-const result = stream
-  .filter((x) => x > 0)
-  .map((x) => x * 2)
-  .group((batch) => batch.length >= 5);
-
-// Rich instance methods with overloads
-stream
-  .filter(0, (prev, curr) => [curr > prev, curr]) // Stateful filtering
-  .map(async (x) => await enrich(x)); // Async mapping
-```
-
-#### Functional Style (Pipe Composition)
-
-```typescript
-// Composable transformers
-const result = stream
-  .pipe(filter((x) => x > 0))
-  .pipe(map((x) => x * 2))
-  .pipe(group((batch) => batch.length >= 5));
-
-// Reusable transformation pipelines
-const processNumbers = (stream: Stream<number>) => stream.pipe(filter((x) => x > 0)).pipe(map((x) => x * 2));
-
-const result1 = stream1.pipe(processNumbers);
-const result2 = stream2.pipe(processNumbers);
-```
-
-## State: Reactive State Management
+### Reactive State
 
-State objects are streams that hold current values, enabling reactive programming patterns:
+State objects hold current values and notify dependents of changes:
 
 ```typescript
-import { State } from "@soffinal/stream";
-
-// Application state
 const user = new State<User | null>(null);
 const theme = new State<"light" | "dark">("light");
-const notifications = new State<Notification[]>([]);
 
-// Reactive computations
+// Derived state with transformations
 const isLoggedIn = user.map((u) => u !== null);
-const unreadCount = notifications.map((n) => n.filter((x) => !x.read).length);
+const userProfile = user
+  .filter((u): u is User => u !== null)
+  .map((u) => ({ ...u, displayName: u.firstName + " " + u.lastName }));
 
 // Automatic UI updates
 isLoggedIn.listen((loggedIn) => {
-  document.body.classList.toggle("logged-in", loggedIn);
-});
-
-unreadCount.listen((count) => {
-  document.title = count > 0 ? `(${count}) My App` : "My App";
-});
-```
-
-### State Management Example
-
-```typescript
-interface AppState {
-  user: { id: string; name: string } | null;
-  notifications: string[];
-  theme: "light" | "dark";
-}
-
-const appState = new State<AppState>({
-  user: null,
-  notifications: [],
-  theme: "light",
-});
-
-const isLoggedIn = appState.map((state) => state.user !== null);
-const notificationCount = appState.map((state) => state.notifications.length);
-
-// React to login state
-isLoggedIn.listen((loggedIn) => {
-  if (loggedIn) {
-    console.log("User logged in");
-    loadUserData();
-  }
-});
-
-// Update state immutably
-function login(user: { id: string; name: string }) {
-  appState.value = {
-    ...appState.value,
-    user,
-  };
-}
-
-function addNotification(message: string) {
-  appState.value = {
-    ...appState.value,
-    notifications: [...appState.value.notifications, message],
-  };
-}
-```
-
-## Reactive Collections: Data Structures That Notify
-
-The library extends JavaScript's native collections with reactive capabilities. Every mutation emits events, allowing you to build reactive UIs and data synchronization systems.
-
-### List: Reactive Arrays
-
-Reactive Lists provide array-like functionality with fine-grained change notifications:
-
-```typescript
-import { List } from "@soffinal/stream";
-
-// Create a reactive todo list
-const todos = new List<{ id: string; text: string; done: boolean }>();
-
-// Build reactive UI components
-todos.insert.listen(([index, todo]) => {
-  const element = createTodoElement(todo);
-  todoContainer.insertBefore(element, todoContainer.children[index]);
-});
-
-todos.delete.listen(([index, todo]) => {
-  todoContainer.children[index].remove();
+  document.body.classList.toggle("authenticated", loggedIn);
 });
-
-// Reactive operations
-const completedCount = new State(0);
-todos.insert.listen(() => updateCompletedCount());
-todos.delete.listen(() => updateCompletedCount());
-
-function updateCompletedCount() {
-  const completed = [...todos].filter((t) => t.done).length;
-  completedCount.value = completed;
-}
-
-// Automatic persistence
-todos.insert.listen(() => saveTodosToStorage([...todos]));
-todos.delete.listen(() => saveTodosToStorage([...todos]));
 ```
 
-### Map: Reactive Key-Value Store
+### Reactive Collections
 
-Key-value store that emits events on changes:
+Collections that emit fine-grained change events:
 
 ```typescript
-import { Map } from "@soffinal/stream";
-
+const todos = new List<Todo>();
 const cache = new Map<string, any>();
+const activeUsers = new Set<string>();
 
-// Listen to cache updates (only emits on actual changes)
-cache.set.listen(([key, value]) => {
-  console.log(`Cache updated: ${key} = ${value}`);
-});
+// React to changes
+todos.insert.listen(([index, todo]) => renderTodo(todo, index));
+cache.set.listen(([key, value]) => console.log(`Cached: ${key}`));
+activeUsers.add.listen((userId) => showOnlineStatus(userId));
+```
 
-// Listen to cache evictions
-cache.delete.listen(([key, value]) => {
-  console.log(`Cache evicted: ${key}`);
-});
+## API Reference
 
-// Listen to clear events
-cache.clear.listen(() => console.log("Cache cleared"));
+### Stream\<T>
 
-cache.set("user:123", { name: "John" }); // Cache updated: user:123 = {...}
-cache.set("user:123", { name: "John" }); // No emission (same value)
-cache.delete("user:123"); // Cache evicted: user:123
-cache.delete("nonexistent"); // No emission (didn't exist)
+#### Properties
 
-// All native Map methods available
-console.log(cache.size);
-console.log(cache.has("key"));
-for (const [key, value] of cache) {
-  console.log(key, value);
-}
-```
+- `hasListeners: boolean` - Whether stream has active listeners
+- `listenerAdded: Stream<void>` - Emits when listener is added
+- `listenerRemoved: Stream<void>` - Emits when listener is removed
 
-### Set: Reactive Unique Collections
+#### Methods
 
-Unique value collection that emits events on changes:
+- `push(...values: T[]): void` - Emit values to all listeners
+- `listen(callback: (value: T) => void, signal?: AbortSignal): () => void` - Add listener
+- `filter(predicate: (value: T) => boolean): Stream<T>` - Filter values
+- `map<U>(mapper: (value: T) => U): Stream<U>` - Transform values
+- `merge(...streams: Stream<T>[]): Stream<T>` - Combine streams
+- `group(predicate: (batch: T[]) => boolean): Stream<T[]>` - Batch values
+- `flat(depth?: number): Stream<U>` - Flatten arrays
+- `pipe<U>(transformer: (stream: Stream<T>) => Stream<U>): Stream<U>` - Apply transformer
 
-```typescript
-import { Set } from "@soffinal/stream";
+#### Async Interface
 
-const activeUsers = new Set<string>();
+- `then<U>(callback?: (value: T) => U): Promise<U>` - Promise interface
+- `[Symbol.asyncIterator](): AsyncIterator<T>` - Async iteration
 
-// Listen to additions (only emits for new values)
-activeUsers.add.listen((userId) => {
-  console.log(`User ${userId} came online`);
-  broadcastUserStatus(userId, "online");
-});
+### State\<T> extends Stream\<T>
 
-// Listen to deletions
-activeUsers.delete.listen((userId) => {
-  console.log(`User ${userId} went offline`);
-  broadcastUserStatus(userId, "offline");
-});
+#### Properties
 
-// Listen to clear events
-activeUsers.clear.listen(() => console.log("All users cleared"));
+- `value: T` - Current state value (get/set)
 
-activeUsers.add("alice"); // User alice came online
-activeUsers.add("alice"); // No emission (duplicate)
-activeUsers.delete("alice"); // User alice went offline
-activeUsers.delete("bob"); // No emission (didn't exist)
+### Transformer Functions
 
-// All native Set methods available
-console.log(activeUsers.size);
-console.log(activeUsers.has("alice"));
-for (const user of activeUsers) {
-  console.log(user);
-}
-```
+Functional transformers for use with `pipe()`:
 
-## Use Cases
+- `filter<T>(predicate: (value: T) => boolean): (stream: Stream<T>) => Stream<T>`
+- `map<T, U>(mapper: (value: T) => U): (stream: Stream<T>) => Stream<U>`
+- `group<T>(predicate: (batch: T[]) => boolean): (stream: Stream<T>) => Stream<T[]>`
+- `merge<T>(...streams: Stream<T>[]): (stream: Stream<T>) => Stream<T>`
+- `flat<T>(depth?: number): (stream: Stream<T>) => Stream<U>`
 
-Practical examples of building reactive applications.
+### Reactive Collections
 
-### Real-time Data Processing
+#### List\<T>
 
-Process sensor data with filtering and transformation:
+- `insert: Stream<[number, T]>` - Insertion events
+- `delete: Stream<[number, T]>` - Deletion events
+- `clear: Stream<void>` - Clear events
 
-```typescript
-const sensorData = new Stream<{ temperature: number; humidity: number }>();
+#### Map\<K,V> extends globalThis.Map\<K,V>
 
-// Alert system
-sensorData.filter((data) => data.temperature > 30).listen((data) => console.log("High temperature alert:", data));
+- `set: Stream<[K, V]>` - Set events (only on changes)
+- `delete: Stream<[K, V]>` - Delete events
+- `clear: Stream<void>` - Clear events
 
-// Data logging
-sensorData.map((data) => ({ ...data, timestamp: Date.now() })).listen((data) => saveToDatabase(data));
+#### Set\<T> extends globalThis.Set\<T>
 
-// Simulate sensor readings
-setInterval(() => {
-  sensorData.push({
-    temperature: Math.random() * 40,
-    humidity: Math.random() * 100,
-  });
-}, 1000);
-```
+- `add: Stream<T>` - Add events (only new values)
+- `delete: Stream<T>` - Delete events
+- `clear: Stream<void>` - Clear events
 
-### Event Aggregation
+## Examples
 
-Collect and batch user events for analytics:
+### Real-time Data Processing
 
 ```typescript
-const userActions = new Stream<{ userId: string; action: string }>();
+const sensorData = new Stream<SensorReading>();
 
-// Group actions by time windows
-const actionBatches = userActions.group(0, (count, action) => {
-  return count >= 10 ? [true, 0] : [false, count + 1];
-});
+// Multi-stage processing pipeline
+const alerts = sensorData
+  .filter((reading) => reading.temperature > 30)
+  .map((reading) => ({ ...reading, timestamp: Date.now() }))
+  .group((batch) => batch.length >= 5);
 
-actionBatches.listen((count) => {
-  console.log(`Processed ${count} actions`);
-});
+alerts.listen((batch) => sendAlertNotification(batch));
 ```
 
 ### WebSocket Integration
 
-Create reactive streams from WebSocket connections:
-
 ```typescript
 const wsStream = new Stream<MessageEvent>(async function* () {
   const ws = new WebSocket("wss://api.example.com");
@@ -597,180 +344,150 @@ const wsStream = new Stream<MessageEvent>(async function* () {
   }
 });
 
-wsStream
-  .map((event) => JSON.parse(event.data))
-  .filter((data) => data.type === "update")
-  .listen((update) => handleUpdate(update));
-```
-
-### Real-time Data Processing Pipeline
-
-Build sophisticated data processing systems:
-
-```typescript
-// Raw sensor data stream
-const sensorData = new Stream<SensorReading>();
-
-// Multi-stage processing pipeline
-const processedData = sensorData
-  // 1. Validate data quality
-  .filter(async (reading) => {
-    return await validateSensorReading(reading);
-  })
-  // 2. Normalize and enrich
-  .map(async (reading) => {
-    const location = await getLocationData(reading.sensorId);
-    return {
-      ...reading,
-      location,
-      normalized: normalizeReading(reading.value),
-    };
-  })
-  // 3. Detect anomalies using sliding window
-  .group(
-    { readings: [], sum: 0 }, // sliding window state
-    (window, reading) => {
-      const newWindow = {
-        readings: [...window.readings, reading].slice(-10), // keep last 10
-        sum: window.sum + reading.normalized,
-      };
-      const average = newWindow.sum / newWindow.readings.length;
-      const isAnomaly = Math.abs(reading.normalized - average) > threshold;
-
-      return [isAnomaly, newWindow];
-    }
-  )
-  // 4. Batch anomalies for processing
-  .group((batch) => batch.length >= 5 || Date.now() - batch[0]?.timestamp > 30000);
+const messages = wsStream.map((event) => JSON.parse(event.data)).filter((data) => data.type === "update");
 
-// Multiple consumers for different purposes
-processedData.listen((anomalies) => sendAlerts(anomalies));
-processedData.listen((anomalies) => updateDashboard(anomalies));
-processedData.listen((anomalies) => logToDatabase(anomalies));
+messages.listen((update) => handleUpdate(update));
 ```
 
-### Cleanup and Memory Management
-
-Properly clean up listeners and prevent memory leaks:
+### State Management
 
 ```typescript
-const stream = new Stream<number>();
-
-// Automatic cleanup with AbortSignal
-const controller = new AbortController();
-stream.listen((value) => console.log(value), controller.signal);
-
-// Clean up when component unmounts
-setTimeout(() => controller.abort(), 5000);
+interface AppState {
+  user: User | null;
+  theme: "light" | "dark";
+  notifications: Notification[];
+}
 
-// Or manual cleanup
-const cleanup = stream.listen((value) => console.log(value));
-setTimeout(cleanup, 5000);
-```
+const appState = new State<AppState>({
+  user: null,
+  theme: "light",
+  notifications: [],
+});
 
-## Installation
+// Derived state
+const unreadCount = appState.map((state) => state.notifications.filter((n) => !n.read).length);
 
-```bash
-bun add @soffinal/stream
+// Reactive UI
+unreadCount.listen((count) => {
+  document.title = count > 0 ? `(${count}) App` : "App";
+});
 ```
 
-```bash
-npm install @soffinal/stream
+### Browser Counter Example
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Reactive Counter</title>
+  </head>
+  <body>
+    <div id="counter">0</div>
+    <button id="increment">+</button>
+    <button id="decrement">-</button>
+
+    <script type="module">
+      import { State } from "https://esm.sh/@soffinal/stream";
+
+      const count = new State(0);
+      const display = document.getElementById("counter");
+
+      // Reactive UI updates
+      count.listen((value) => (display.textContent = value));
+
+      // User interactions
+      document.getElementById("increment").onclick = () => count.value++;
+      document.getElementById("decrement").onclick = () => count.value--;
+    </script>
+  </body>
+</html>
 ```
 
-## API Reference
-
-### Stream<T>
-
-**Properties:**
-
-- `hasListeners: boolean` - True if stream has active listeners
-- `listenerAdded: Stream<void>` - Emits when listener is added
-- `listenerRemoved: Stream<void>` - Emits when listener is removed
-
-**Methods:**
-
-- `push(...values: T[]): void` - Emit values to all listeners
-- `listen(callback: (value: T) => void, signal?: AbortSignal): () => void` - Add listener, returns cleanup function
-- `filter<U extends T>(predicate: (value: T) => value is U): Stream<U>` - Filter values with type guard
-- `filter(predicate: (value: T) => boolean | Promise<boolean>): Stream<T>` - Filter values with predicate
-- `filter<S>(initialState: S, accumulator: (state: S, value: T) => [boolean, S] | Promise<[boolean, S]>): Stream<T>` - Stateful filtering
-- `map<U>(mapper: (value: T) => U | Promise<U>): Stream<U>` - Transform values
-- `map<S, U>(initialState: S, accumulator: (state: S, value: T) => [U, S] | Promise<[U, S]>): Stream<U>` - Stateful mapping
-- `merge(...streams: Stream<T>[]): Stream<T>` - Combine multiple streams
-- `group(predicate: (batch: T[]) => boolean): Stream<T[]>` - Group values into batches
-- `group<S>(initialState: S, accumulator: (state: S, value: T) => [boolean, S]): Stream<T[]>` - Stateful grouping
-- `flat<U>(depth?: number): Stream<U>` - Flatten array values (default depth: 0)
-- `pipe<U>(transformer: (stream: Stream<T>) => Stream<U>): Stream<U>` - Apply functional transformer
-- `then<U>(callback?: (value: T) => U): Promise<U>` - Promise-like interface for first value
-- `[Symbol.asyncIterator](): AsyncIterator<T>` - Async iteration support
-
-### Transformer Functions
-
-**Built-in transformers for functional composition:**
+## Performance
 
-- `map<T, U>(mapper: (value: T) => U | Promise<U>): (stream: Stream<T>) => Stream<U>` - Transform values
-- `map<T, S, U>(initialState: S, accumulator: (state: S, value: T) => [U, S] | Promise<[U, S]>): (stream: Stream<T>) => Stream<U>` - Stateful mapping
-- `filter<T, U extends T>(predicate: (value: T) => value is U): (stream: Stream<T>) => Stream<U>` - Type guard filtering
-- `filter<T>(predicate: (value: T) => boolean | Promise<boolean>): (stream: Stream<T>) => Stream<T>` - Predicate filtering
-- `filter<T, S>(initialState: S, accumulator: (state: S, value: T) => [boolean, S] | Promise<[boolean, S]>): (stream: Stream<T>) => Stream<T>` - Stateful filtering
-- `group<T>(predicate: (batch: T[]) => boolean): (stream: Stream<T>) => Stream<T[]>` - Group values into batches
-- `group<T, S>(initialState: S, accumulator: (state: S, value: T) => [boolean, S]): (stream: Stream<T>) => Stream<T[]>` - Stateful grouping
-- `merge<T>(...streams: Stream<T>[]): (stream: Stream<T>) => Stream<T>` - Merge multiple streams into one
-- `flat<T, U>(depth?: number): (stream: Stream<T>) => Stream<U>` - Flatten array values with configurable depth
+@soffinal/stream delivers exceptional performance:
 
-### State<T> extends Stream<T>
+- **High throughput** for basic operations
+- **Efficient processing** for complex pipelines
+- **Memory efficient** with automatic cleanup
+- **Zero overhead** for unused features
 
-**Properties:**
+### Performance Characteristics
 
-- `value: T` - Get/set current state value
+- **Optimized data structures** for minimal memory allocation
+- **Efficient event dispatch** with smart caching
+- **Lazy evaluation** reduces unnecessary computations
+- **Automatic cleanup** prevents memory leaks
 
-**Methods:**
+## Browser Support
 
-- `push(...values: T[]): void` - Update state with multiple values sequentially
+- **Modern browsers** supporting ES2020+
+- **Node.js** 16+
+- **Deno** 1.0+
+- **Bun** 1.0+
+- **Cloudflare Workers**
 
-### List<T>
+## Migration Guide
 
-**Properties:**
+### From RxJS
 
-- `length: number` - Current list length
-- `insert: Stream<[number, T]>` - Emits on insertions
-- `delete: Stream<[number, T]>` - Emits on deletions
-- `clear: Stream<void>` - Emits on clear
-- `[index]: T` - Index access with modulo wrapping
-
-**Methods:**
+```typescript
+// RxJS
+import { Subject, map, filter } from "rxjs";
+const subject = new Subject();
+subject
+  .pipe(
+    filter((x) => x > 0),
+    map((x) => x * 2)
+  )
+  .subscribe(console.log);
 
-- `insert(index: number, value: T): void` - Insert value at index
-- `delete(index: number): T | undefined` - Delete value at index, returns deleted value
-- `clear(): void` - Clear all items
-- `get(index: number): T | undefined` - Get value without modulo wrapping
-- `values(): IterableIterator<T>` - Iterator for values
+// @soffinal/stream
+import { Stream } from "@soffinal/stream";
+const stream = new Stream();
+stream
+  .filter((x) => x > 0)
+  .map((x) => x * 2)
+  .listen(console.log);
+```
 
-### Map<K,V> extends globalThis.Map<K,V>
+### From EventEmitter
 
-**Stream Properties:**
+```typescript
+// EventEmitter
+import { EventEmitter } from "events";
+const emitter = new EventEmitter();
+emitter.on("data", console.log);
+emitter.emit("data", "hello");
 
-- `set: Stream<[K, V]>` - Emits on set operation (only actual changes)
-- `delete: Stream<[K, V]>` - Emits on successful deletions
-- `clear: Stream<void>` - Emits on clear (only if not empty)
+// @soffinal/stream
+import { Stream } from "@soffinal/stream";
+const stream = new Stream();
+stream.listen(console.log);
+stream.push("hello");
+```
 
-**Methods:**
+## Contributing
 
-- All native Map methods plus reactive stream properties
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
-### Set<T> extends globalThis.Set<T>
+### Development Setup
 
-**Stream Properties:**
+```bash
+git clone https://github.com/soffinal/stream.git
+cd stream
+bun install
+bun test
+```
 
-- `add: Stream<T>` - Emits on successful additions (no duplicates)
-- `delete: Stream<T>` - Emits on successful deletions
-- `clear: Stream<void>` - Emits on clear (only if not empty)
+## License
 
-**Methods:**
+MIT © [Soffinal](https://github.com/soffinal)
 
-- All native Set methods plus reactive stream properties
+Contact: <smari.sofiane@gmail.com>
 
-MIT License
+---
 
-Copyright (c) 2024 Soffinal <https://github.com/soffinal> <smari.sofiane@gmail.com>
+<div align="center">
+  <strong>Built with ❤️ for the JavaScript community</strong>
+</div>