@silvery/tea 0.3.0

package/src/streams/index.ts

@@ -0,0 +1,405 @@
+/**
+ * AsyncIterable stream helpers for event-driven TUI architecture.
+ *
+ * These are pure functions over AsyncIterables - no EventEmitters, no callbacks.
+ * All helpers properly handle cleanup via return() on early break.
+ *
+ * @example
+ * ```typescript
+ * const keys = term.keys()
+ * const resizes = term.resizes()
+ *
+ * // Merge multiple sources
+ * const events = merge(
+ *   map(keys, k => ({ type: 'key', ...k })),
+ *   map(resizes, r => ({ type: 'resize', ...r }))
+ * )
+ *
+ * // Consume until ctrl+c
+ * for await (const event of events) {
+ *   if (event.type === 'key' && event.key === 'ctrl+c') break
+ * }
+ * ```
+ */
+
+/**
+ * Merge multiple AsyncIterables into one.
+ *
+ * Values are emitted in arrival order (first-come). When all sources complete,
+ * the merged iterable completes. If any source throws, the error propagates
+ * and remaining sources are cleaned up.
+ *
+ * IMPORTANT: Each call to merge() creates a fresh iterable. Don't share
+ * the same merged iterable between multiple consumers.
+ *
+ * @example
+ * ```typescript
+ * const merged = merge(keys, resizes, ticks)
+ * for await (const event of merged) {
+ *   // Process events from any source
+ * }
+ * ```
+ */
+export async function* merge<T>(...sources: AsyncIterable<T>[]): AsyncGenerator<T, void, undefined> {
+  if (sources.length === 0) return
+
+  // Track active iterators and their pending promises
+  const iterators = sources.map((source) => source[Symbol.asyncIterator]())
+  const pending = new Map<number, Promise<{ index: number; result: IteratorResult<T, unknown> }>>()
+
+  async function nextWithIndex(idx: number): Promise<{ index: number; result: IteratorResult<T, unknown> }> {
+    const iterator = iterators[idx]
+    if (!iterator) throw new Error(`No iterator at index ${idx}`)
+    const result = await iterator.next()
+    return { index: idx, result }
+  }
+
+  // Start all iterators
+  for (let i = 0; i < iterators.length; i++) {
+    pending.set(i, nextWithIndex(i))
+  }
+
+  try {
+    while (pending.size > 0) {
+      // Race all pending promises
+      const { index, result } = await Promise.race(pending.values())
+
+      if (result.done) {
+        // This source is exhausted, remove it
+        pending.delete(index)
+      } else {
+        // Yield the value and request next from this source
+        yield result.value
+        pending.set(index, nextWithIndex(index))
+      }
+    }
+  } finally {
+    // Clean up all iterators on early exit or error
+    await Promise.all(iterators.map((it) => (it.return ? it.return() : Promise.resolve())))
+  }
+}
+
+/**
+ * Transform each value from an AsyncIterable.
+ *
+ * @example
+ * ```typescript
+ * const keyEvents = map(keys, k => ({ type: 'key' as const, key: k }))
+ * ```
+ */
+export async function* map<T, U>(source: AsyncIterable<T>, fn: (value: T) => U): AsyncGenerator<U, void, undefined> {
+  const iterator = source[Symbol.asyncIterator]()
+  try {
+    // Use the iterator directly to avoid double-iteration
+    for await (const value of { [Symbol.asyncIterator]: () => iterator }) {
+      yield fn(value)
+    }
+  } finally {
+    if (iterator.return) {
+      await iterator.return()
+    }
+  }
+}
+
+/**
+ * Filter values from an AsyncIterable.
+ *
+ * @example
+ * ```typescript
+ * const letters = filter(keys, k => k.key.length === 1)
+ * ```
+ */
+export async function* filter<T>(
+  source: AsyncIterable<T>,
+  predicate: (value: T) => boolean,
+): AsyncGenerator<T, void, undefined> {
+  const iterator = source[Symbol.asyncIterator]()
+  try {
+    for await (const value of { [Symbol.asyncIterator]: () => iterator }) {
+      if (predicate(value)) {
+        yield value
+      }
+    }
+  } finally {
+    if (iterator.return) {
+      await iterator.return()
+    }
+  }
+}
+
+/**
+ * Filter and transform in one pass (type narrowing).
+ *
+ * @example
+ * ```typescript
+ * const keyEvents = filterMap(events, e =>
+ *   e.type === 'key' ? e : undefined
+ * )
+ * ```
+ */
+export async function* filterMap<T, U>(
+  source: AsyncIterable<T>,
+  fn: (value: T) => U | undefined,
+): AsyncGenerator<U, void, undefined> {
+  const iterator = source[Symbol.asyncIterator]()
+  try {
+    for await (const value of { [Symbol.asyncIterator]: () => iterator }) {
+      const mapped = fn(value)
+      if (mapped !== undefined) {
+        yield mapped
+      }
+    }
+  } finally {
+    if (iterator.return) {
+      await iterator.return()
+    }
+  }
+}
+
+/**
+ * Take values until an AbortSignal fires.
+ *
+ * When the signal aborts, the iterator completes gracefully (no error thrown).
+ * The source iterator is properly cleaned up.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController()
+ * const events = takeUntil(allEvents, controller.signal)
+ *
+ * // Later: controller.abort() will end the iteration
+ * ```
+ */
+export async function* takeUntil<T>(source: AsyncIterable<T>, signal: AbortSignal): AsyncGenerator<T, void, undefined> {
+  if (signal.aborted) return
+
+  const iterator = source[Symbol.asyncIterator]()
+
+  // Create a promise that resolves when signal aborts
+  let abortResolve: () => void
+  const abortPromise = new Promise<void>((resolve) => {
+    abortResolve = resolve
+  })
+  const onAbort = () => abortResolve()
+  signal.addEventListener("abort", onAbort, { once: true })
+
+  try {
+    while (!signal.aborted) {
+      // Race between next value and abort
+      const result = await Promise.race([
+        iterator.next(),
+        abortPromise.then(() => ({ done: true, value: undefined }) as const),
+      ])
+
+      if (result.done) break
+      yield result.value as T
+    }
+  } finally {
+    signal.removeEventListener("abort", onAbort)
+    if (iterator.return) {
+      await iterator.return()
+    }
+  }
+}
+
+/**
+ * Take the first n values from an AsyncIterable.
+ *
+ * @example
+ * ```typescript
+ * const firstThree = take(events, 3)
+ * ```
+ */
+export async function* take<T>(source: AsyncIterable<T>, count: number): AsyncGenerator<T, void, undefined> {
+  if (count <= 0) return
+
+  const iterator = source[Symbol.asyncIterator]()
+  let taken = 0
+
+  try {
+    for await (const value of { [Symbol.asyncIterator]: () => iterator }) {
+      yield value
+      taken++
+      if (taken >= count) break
+    }
+  } finally {
+    if (iterator.return) {
+      await iterator.return()
+    }
+  }
+}
+
+/**
+ * Create an AsyncIterable from an array (useful for testing).
+ *
+ * @example
+ * ```typescript
+ * const events = fromArray([
+ *   { type: 'key', key: 'j' },
+ *   { type: 'key', key: 'k' },
+ * ])
+ * ```
+ */
+export async function* fromArray<T>(items: T[]): AsyncGenerator<T, void, undefined> {
+  for (const item of items) {
+    yield item
+  }
+}
+
+/**
+ * Create an AsyncIterable that yields after a delay (useful for testing).
+ *
+ * @example
+ * ```typescript
+ * const delayed = fromArrayWithDelay([1, 2, 3], 100) // 100ms between each
+ * ```
+ */
+export async function* fromArrayWithDelay<T>(items: T[], delayMs: number): AsyncGenerator<T, void, undefined> {
+  for (const item of items) {
+    await new Promise((resolve) => setTimeout(resolve, delayMs))
+    yield item
+  }
+}
+
+/**
+ * Throttle high-frequency sources.
+ *
+ * Emits the first value immediately, then ignores values for the specified
+ * duration. After the duration, the next value is emitted and the cycle repeats.
+ *
+ * @example
+ * ```typescript
+ * const throttled = throttle(mouseMoves, 16) // ~60fps
+ * ```
+ */
+export async function* throttle<T>(source: AsyncIterable<T>, ms: number): AsyncGenerator<T, void, undefined> {
+  const iterator = source[Symbol.asyncIterator]()
+  let lastEmit = 0
+
+  try {
+    for await (const value of { [Symbol.asyncIterator]: () => iterator }) {
+      const now = Date.now()
+      if (now - lastEmit >= ms) {
+        lastEmit = now
+        yield value
+      }
+    }
+  } finally {
+    if (iterator.return) {
+      await iterator.return()
+    }
+  }
+}
+
+/**
+ * Debounce values - only emit after source is quiet for specified duration.
+ *
+ * NOTE: With pull-based AsyncIterables, true debouncing is complex. This
+ * implementation collects all values and only yields the final value after
+ * the source completes and quiet period passes. For real-time debouncing,
+ * consider using a push-based pattern or EventEmitter.
+ *
+ * @example
+ * ```typescript
+ * const debounced = debounce(searchInput, 300) // Yields last value after source ends + delay
+ * ```
+ */
+export async function* debounce<T>(source: AsyncIterable<T>, ms: number): AsyncGenerator<T, void, undefined> {
+  const iterator = source[Symbol.asyncIterator]()
+  let last: { value: T } | undefined
+
+  try {
+    for await (const value of { [Symbol.asyncIterator]: () => iterator }) {
+      last = { value }
+    }
+
+    if (last) {
+      await new Promise((resolve) => setTimeout(resolve, ms))
+      yield last.value
+    }
+  } finally {
+    if (iterator.return) {
+      await iterator.return()
+    }
+  }
+}
+
+/**
+ * Collect values into batches of specified size.
+ *
+ * @throws {Error} If size is not positive
+ *
+ * @example
+ * ```typescript
+ * const batched = batch(events, 10) // Emit arrays of 10 events
+ * ```
+ */
+export function batch<T>(source: AsyncIterable<T>, size: number): AsyncGenerator<T[], void, undefined> {
+  if (size <= 0) throw new Error("Batch size must be positive")
+  return batchImpl(source, size)
+}
+
+async function* batchImpl<T>(source: AsyncIterable<T>, size: number): AsyncGenerator<T[], void, undefined> {
+  const iterator = source[Symbol.asyncIterator]()
+  let buffer: T[] = []
+
+  try {
+    for await (const value of { [Symbol.asyncIterator]: () => iterator }) {
+      buffer.push(value)
+      if (buffer.length >= size) {
+        yield buffer
+        buffer = []
+      }
+    }
+    // Emit remaining items
+    if (buffer.length > 0) {
+      yield buffer
+    }
+  } finally {
+    if (iterator.return) {
+      await iterator.return()
+    }
+  }
+}
+
+/**
+ * Concatenate multiple AsyncIterables in sequence.
+ *
+ * @example
+ * ```typescript
+ * const all = concat(header, body, footer)
+ * ```
+ */
+export async function* concat<T>(...sources: AsyncIterable<T>[]): AsyncGenerator<T, void, undefined> {
+  for (const source of sources) {
+    yield* source
+  }
+}
+
+/**
+ * Zip multiple AsyncIterables together.
+ * Completes when the shortest source completes.
+ *
+ * @example
+ * ```typescript
+ * const pairs = zip(keys, timestamps) // [key, timestamp][]
+ * ```
+ */
+export async function* zip<T extends unknown[]>(
+  ...sources: { [K in keyof T]: AsyncIterable<T[K]> }
+): AsyncGenerator<T, void, undefined> {
+  const iterators = sources.map((source) => source[Symbol.asyncIterator]())
+
+  try {
+    while (true) {
+      const results = await Promise.all(iterators.map((it) => it.next()))
+
+      // If any source is done, we're done
+      if (results.some((r) => r.done)) break
+
+      yield results.map((r) => r.value) as T
+    }
+  } finally {
+    await Promise.all(iterators.map((it) => (it.return ? it.return() : Promise.resolve())))
+  }
+}

package/src/tea/README.md

@@ -0,0 +1,208 @@
+# silvery/tea
+
+Zustand middleware for TEA (The Elm Architecture) effects-as-data pattern.
+
+A ~30-line middleware that lets Zustand reducers optionally return `[state, effects]`
+alongside plain state. Gradual adoption: start with pure state updates (Level 3),
+add effects-as-data when you need side effects (Level 4).
+
+## Install
+
+```ts
+import { tea, collect } from "@silvery/tea"
+import type { TeaResult, TeaReducer, EffectRunners, TeaSlice, EffectLike } from "@silvery/tea"
+```
+
+Not a standalone package. Exported as a sub-path from Silvery.
+
+## Quick Start
+
+Level 3 — ops as data. The reducer takes state and an operation, returns new state.
+`tea()` wraps it as a Zustand state creator with `dispatch`.
+
+```ts
+import { createStore } from "zustand"
+import { tea } from "@silvery/tea"
+
+interface State {
+  count: number
+}
+
+type Op = { type: "increment" } | { type: "decrement" } | { type: "reset" }
+
+function reducer(state: State, op: Op): State {
+  switch (op.type) {
+    case "increment":
+      return { ...state, count: state.count + 1 }
+    case "decrement":
+      return { ...state, count: state.count - 1 }
+    case "reset":
+      return { ...state, count: 0 }
+  }
+}
+
+const store = createStore(tea({ count: 0 }, reducer))
+
+store.getState().dispatch({ type: "increment" })
+store.getState().count // 1
+```
+
+No effects, no runners, no ceremony. Plain `(state, op) => state`.
+
+## Effects
+
+Level 4 — effects as data. Same middleware, same reducer signature. When an operation
+needs a side effect, return `[state, effects]` instead of plain state. Mix freely
+on a per-case basis.
+
+```ts
+import { createStore } from "zustand"
+import { tea, type TeaResult, type EffectRunners } from "@silvery/tea"
+
+// Effects are plain objects with a `type` discriminant
+const log = (msg: string) => ({ type: "log" as const, msg })
+const save = (url: string, body: unknown) => ({ type: "save" as const, url, body })
+
+type MyEffect = ReturnType<typeof log> | ReturnType<typeof save>
+
+interface State {
+  count: number
+}
+
+type Op = { type: "increment" } | { type: "save" }
+
+function reducer(state: State, op: Op): TeaResult<State, MyEffect> {
+  switch (op.type) {
+    case "increment":
+      return { ...state, count: state.count + 1 } // Level 3: plain state
+    case "save":
+      return [state, [save("/api/count", state), log("saved")]] // Level 4: [state, effects]
+  }
+}
+
+// Effect runners: swappable for production, test, replay
+const runners: EffectRunners<MyEffect, Op> = {
+  log: (effect) => console.log(effect.msg),
+  save: async (effect, dispatch) => {
+    await fetch(effect.url, { method: "POST", body: JSON.stringify(effect.body) })
+    // Round-trip: dispatch back into the reducer (Elm's Cmd Msg pattern)
+    dispatch({ type: "increment" })
+  },
+}
+
+const store = createStore(tea({ count: 0 }, reducer, { runners }))
+
+store.getState().dispatch({ type: "save" })
+// -> state unchanged, effects executed: POST /api/count + console.log("saved")
+```
+
+### Detection mechanism
+
+`Array.isArray` distinguishes plain state (object) from `[state, effects]` (array).
+Safe because Zustand state is always an object — never an array.
+
+### Effect execution
+
+Effects run synchronously after state update, in order. Each effect is routed to a
+runner by its `type` field. Runners receive a `dispatch` callback for round-trip
+communication. Unmatched effects (no runner for that type) are silently dropped.
+
+## API Reference
+
+### `tea(initialState, reducer, options?)`
+
+Zustand `StateCreator` middleware. Returns a store shape of `S & { dispatch }`.
+
+| Parameter      | Type                   | Description                                              |
+| -------------- | ---------------------- | -------------------------------------------------------- |
+| `initialState` | `S extends object`     | Initial domain state                                     |
+| `reducer`      | `TeaReducer<S, Op, E>` | Pure reducer: `(state, op) => state \| [state, effects]` |
+| `options`      | `TeaOptions<E, Op>`    | Optional `{ runners }` for effect execution              |
+
+Returns: `StateCreator<TeaSlice<S, Op>>`
+
+### `collect(result)`
+
+Test helper. Normalizes a reducer result to `[state, effects]` regardless of what
+the reducer returned.
+
+| Parameter | Type              | Description                      |
+| --------- | ----------------- | -------------------------------- |
+| `result`  | `TeaResult<S, E>` | Return value from a reducer call |
+
+Returns: `[S, E[]]` — always a tuple. Plain state becomes `[state, []]`.
+
+### Types
+
+```ts
+// An effect must have a `type` discriminant
+type EffectLike = { type: string }
+
+// Reducer return: plain state (no effects) or [state, effects]
+type TeaResult<S, E extends EffectLike = EffectLike> = S | readonly [S, E[]]
+
+// A reducer function
+type TeaReducer<S, Op, E extends EffectLike = EffectLike> = (state: S, op: Op) => TeaResult<S, E>
+
+// Runners keyed by effect type. Each receives the effect + dispatch for round-trips.
+type EffectRunners<E extends EffectLike, Op = unknown> = {
+  [K in E["type"]]?: (effect: Extract<E, { type: K }>, dispatch: (op: Op) => void) => void | Promise<void>
+}
+
+// Options for tea()
+interface TeaOptions<E extends EffectLike, Op> {
+  runners?: EffectRunners<E, Op>
+}
+
+// The store shape: domain state + dispatch
+type TeaSlice<S, Op> = S & { dispatch: (op: Op) => void }
+```
+
+## Testing
+
+Reducers are pure functions. Test them directly without a store. `collect()` normalizes
+the return value so assertions work uniformly whether the reducer returned plain state
+or a tuple.
+
+```ts
+import { collect } from "@silvery/tea"
+
+const initial: State = { count: 0 }
+
+// Level 3 case: plain state
+const [state1, effects1] = collect(reducer(initial, { type: "increment" }))
+expect(state1.count).toBe(1)
+expect(effects1).toEqual([])
+
+// Level 4 case: state + effects
+const [state2, effects2] = collect(reducer(initial, { type: "save" }))
+expect(state2).toEqual(initial)
+expect(effects2).toContainEqual(save("/api/count", initial))
+expect(effects2).toContainEqual(log("saved"))
+```
+
+Effect runners are tested separately — inject mock dispatch, assert on calls:
+
+```ts
+const dispatched: Op[] = []
+const mockDispatch = (op: Op) => dispatched.push(op)
+
+runners.save!(save("/api/count", { count: 5 }), mockDispatch)
+// assert: dispatched contains expected round-trip ops
+```
+
+## Prior Art
+
+| System                                                  | Approach                                      | Difference                                            |
+| ------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------- |
+| [redux-loop](https://github.com/redux-loop/redux-loop)  | Redux middleware, `loop(state, effects)`      | Store enhancer, more API surface. tea() is ~30 lines. |
+| [Hyperapp v2](https://github.com/jorgebucaran/hyperapp) | `[state, effects]` tuples from actions        | Full framework. tea() is just a Zustand middleware.   |
+| [Elm](https://guide.elm-lang.org/effects/)              | `Cmd Msg` — effects return messages to update | The original. tea() adapts this to JS/Zustand.        |
+
+The key insight shared by all: effects are **data**, not imperative calls. The reducer
+declares _what_ should happen; runners decide _how_. This makes reducers pure, testable,
+and replayable.
+
+## See Also
+
+- [docs/guide/state-management.md](../../docs/guide/state-management.md) — full state management guide covering createApp, createSlice, selectors, and effects middleware