@czap/core 0.1.0

package/src/wasm-fallback.ts

@@ -0,0 +1,102 @@
+/**
+ * Pure TypeScript fallback kernels for WASM compute functions.
+ *
+ * These produce bit-identical results (within float precision) to the
+ * Rust WASM kernels. When WASM is unavailable, these are used automatically.
+ *
+ * @module
+ */
+
+import type { WASMKernels } from './wasm-dispatch.js';
+
+function springCurve(stiffness: number, damping: number, mass: number, samples: number): Float32Array {
+  const m = mass <= 0 ? 1 : mass;
+  const count = Math.min(Math.max(0, samples | 0), 255);
+  const omega = Math.sqrt(stiffness / m);
+  const zeta = damping / (2 * Math.sqrt(stiffness * m));
+  const out = new Float32Array(count + 1);
+
+  for (let i = 0; i <= count; i++) {
+    const t = i / count;
+    if (t <= 0) {
+      out[i] = 0;
+    } else if (t >= 1) {
+      out[i] = 1;
+    } else if (zeta < 1) {
+      const omegaD = omega * Math.sqrt(1 - zeta * zeta);
+      out[i] =
+        1 - Math.exp(-zeta * omega * t) * (Math.cos(omegaD * t) + ((zeta * omega) / omegaD) * Math.sin(omegaD * t));
+    } else if (zeta === 1) {
+      out[i] = 1 - (1 + omega * t) * Math.exp(-omega * t);
+    } else {
+      const s = Math.sqrt(zeta * zeta - 1);
+      const r1 = -omega * (zeta + s);
+      const r2 = -omega * (zeta - s);
+      const c1 = r2 / (r2 - r1);
+      const c2 = -r1 / (r2 - r1);
+      out[i] = 1 - (c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t));
+    }
+  }
+
+  return out;
+}
+
+function batchBoundaryEval(thresholds: Float64Array, values: Float64Array): Uint32Array {
+  const tLen = thresholds.length;
+  const vLen = values.length;
+  const out = new Uint32Array(vLen);
+
+  for (let vi = 0; vi < vLen; vi++) {
+    const value = values[vi]!;
+    let stateIdx = 0;
+
+    for (let ti = tLen - 1; ti >= 0; ti--) {
+      if (value >= thresholds[ti]!) {
+        stateIdx = ti;
+        break;
+      }
+    }
+
+    out[vi] = stateIdx;
+  }
+
+  return out;
+}
+
+function blendNormalize(weights: Float32Array): Float32Array {
+  const len = weights.length;
+  if (len === 0) return weights;
+
+  let total = 0;
+  for (let i = 0; i < len; i++) {
+    let w = weights[i]!;
+    if (w < 0) {
+      w = 0;
+      weights[i] = 0;
+    }
+    total += w;
+  }
+
+  if (total > 0) {
+    const inv = 1 / total;
+    for (let i = 0; i < len; i++) {
+      weights[i] = weights[i]! * inv;
+    }
+  }
+
+  return weights;
+}
+
+/**
+ * Pure-JS implementation of the {@link WASMKernels} contract.
+ *
+ * Selected automatically by {@link WASMDispatch} when the Rust compute crate
+ * cannot be instantiated (e.g. missing `WebAssembly`, CSP restrictions, or
+ * startup failure). Produces results bit-identical to the WASM build within
+ * IEEE-754 precision limits.
+ */
+export const fallbackKernels: WASMKernels = {
+  springCurve,
+  batchBoundaryEval,
+  blendNormalize,
+};

package/src/wire.ts

@@ -0,0 +1,274 @@
+/**
+ * `Wire<T, E>` — fluent stream wrapper.
+ *
+ * @module
+ */
+
+import { Effect, Stream, Queue } from 'effect';
+import type { Millis } from './brands.js';
+
+// Fluent composition: chainable transform pipeline for Effect streams, enabling .map/.filter/.merge without breaking the Effect fiber model.
+
+interface WireShape<T, E = never> {
+  readonly _tag: 'Wire';
+  readonly stream: Stream.Stream<T, E>;
+  map<B>(f: (a: T) => B): WireShape<B, E>;
+  filter(f: (a: T) => boolean): WireShape<T, E>;
+  take(n: number): WireShape<T, E>;
+  takeUntil(predicate: (a: T) => boolean): WireShape<T, E>;
+  debounce(ms: Millis): WireShape<T, E>;
+  throttle(ms: Millis): WireShape<T, E>;
+  scan<B>(initial: B, f: (acc: B, value: T) => B): WireShape<B, E>;
+  flatMap<B, E2>(f: (a: T) => WireShape<B, E2>): WireShape<B, E | E2>;
+  merge<B, E2>(other: WireShape<B, E2>): WireShape<T | B, E | E2>;
+  run(): Effect.Effect<void, E>;
+  runCollect(): Effect.Effect<T[], E>;
+}
+
+function wrap<T, E = never>(stream: Stream.Stream<T, E>): WireShape<T, E> {
+  const wireStream: WireShape<T, E> = {
+    _tag: 'Wire' as const,
+    stream,
+
+    map: <B>(f: (a: T) => B) => wrap<B, E>(Stream.map(stream, f)),
+
+    filter: (f: (a: T) => boolean) => wrap<T, E>(Stream.filter(stream, f)),
+
+    take: (n: number) => wrap<T, E>(Stream.take(stream, n)),
+
+    takeUntil: (predicate: (a: T) => boolean) => wrap<T, E>(Stream.takeUntil(stream, predicate)),
+
+    debounce: (ms: Millis) => wrap<T, E>(Stream.debounce(stream, ms)),
+
+    throttle: (ms: Millis) =>
+      wrap<T, E>(
+        Stream.throttle(stream, {
+          cost: () => 1,
+          units: 1,
+          duration: ms,
+          strategy: 'enforce',
+        }),
+      ),
+
+    scan: <B>(initial: B, f: (acc: B, value: T) => B) => wrap<B, E>(Stream.scan(stream, initial, f)),
+
+    flatMap: <B, E2>(f: (a: T) => WireShape<B, E2>) => wrap<B, E | E2>(Stream.flatMap(stream, (a) => f(a).stream)),
+
+    merge: <B, E2>(other: WireShape<B, E2>) => wrap<T | B, E | E2>(Stream.merge(stream, other.stream)),
+
+    run: () => Stream.runDrain(stream),
+
+    runCollect: () => Effect.map(Stream.runCollect(stream), (chunk) => Array.from<T>(chunk)),
+  };
+
+  return wireStream;
+}
+
+/**
+ * Wraps an Effect Stream into a fluent Wire with chainable operators.
+ *
+ * @example
+ * ```ts
+ * const wire = Wire.from(Stream.make(1, 2, 3));
+ * const doubled = wire.map(n => n * 2).filter(n => n > 2);
+ * const results = Effect.runSync(doubled.runCollect()); // [4, 6]
+ * ```
+ */
+const _from = <T, E = never>(stream: Stream.Stream<T, E>): WireShape<T, E> => wrap(stream);
+
+/**
+ * Creates a Wire from a Server-Sent Events endpoint.
+ * The EventSource is cleaned up when the stream finalizes.
+ *
+ * @example
+ * ```ts
+ * const wire = Wire.fromSSE('/api/events');
+ * const parsed = wire.map(evt => JSON.parse(evt.data));
+ * await Effect.runPromise(Wire.runForEach(parsed, msg => Effect.log(msg)));
+ * ```
+ */
+const _fromSSE = (url: string, options?: EventSourceInit): WireShape<MessageEvent, Error> => {
+  const stream = Stream.callback<MessageEvent, Error>((queue) =>
+    Effect.gen(function* () {
+      const eventSource = new EventSource(url, options);
+      let closed = false;
+
+      const shutdown = (): void => {
+        if (closed) return;
+        closed = true;
+        Queue.shutdown(queue).pipe(Effect.runSync);
+      };
+
+      eventSource.onmessage = (event) => {
+        Queue.offerUnsafe(queue, event);
+      };
+
+      eventSource.onerror = () => {
+        eventSource.close();
+        shutdown();
+      };
+
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          eventSource.close();
+          shutdown();
+        }),
+      );
+
+      yield* Effect.never;
+    }),
+  );
+
+  return wrap(stream);
+};
+
+/**
+ * Creates a Wire from a WebSocket connection.
+ * The socket is closed when the stream finalizes.
+ *
+ * @example
+ * ```ts
+ * const wire = Wire.fromWebSocket('wss://example.com/ws');
+ * const messages = wire.map(evt => evt.data as string);
+ * await Effect.runPromise(Wire.runForEach(messages, m => Effect.log(m)));
+ * ```
+ */
+const _fromWebSocket = (url: string, protocols?: string | string[]): WireShape<MessageEvent, Error> => {
+  const stream = Stream.callback<MessageEvent, Error>((queue) =>
+    Effect.gen(function* () {
+      const ws = new WebSocket(url, protocols);
+      let closed = false;
+
+      const shutdown = (): void => {
+        if (closed) return;
+        closed = true;
+        Queue.shutdown(queue).pipe(Effect.runSync);
+      };
+
+      ws.onmessage = (event) => {
+        Queue.offerUnsafe(queue, event);
+      };
+
+      ws.onerror = () => {
+        shutdown();
+      };
+
+      ws.onclose = () => {
+        shutdown();
+      };
+
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+            ws.close();
+          }
+          shutdown();
+        }),
+      );
+
+      yield* Effect.never;
+    }),
+  );
+
+  return wrap(stream);
+};
+
+/**
+ * Creates a Wire from any AsyncIterable source.
+ *
+ * @example
+ * ```ts
+ * async function* gen() { yield 1; yield 2; yield 3; }
+ * const wire = Wire.fromAsyncIterable(gen());
+ * const results = await Effect.runPromise(wire.runCollect()); // [1, 2, 3]
+ * ```
+ */
+const _fromAsyncIterable = <T>(iterable: AsyncIterable<T>): WireShape<T, Error> => {
+  const stream = Stream.fromAsyncIterable(iterable, (e) => (e instanceof Error ? e : new Error(String(e))));
+  return wrap(stream);
+};
+
+/**
+ * Zips two Wires into a Wire of tuples, pairing elements pairwise.
+ *
+ * @example
+ * ```ts
+ * const a = Wire.from(Stream.make(1, 2));
+ * const b = Wire.from(Stream.make('a', 'b'));
+ * const zipped = Wire.zip(a, b);
+ * const results = Effect.runSync(zipped.runCollect()); // [[1,'a'], [2,'b']]
+ * ```
+ */
+const _zip = <A, B>(a: WireShape<A>, b: WireShape<B>): WireShape<readonly [A, B]> =>
+  wrap(Stream.zip(a.stream, b.stream));
+
+/**
+ * Merges multiple Wires into a single Wire, interleaving their emissions.
+ *
+ * @example
+ * ```ts
+ * const a = Wire.from(Stream.make(1, 2));
+ * const b = Wire.from(Stream.make(3, 4));
+ * const merged = Wire.merge([a, b]);
+ * const results = Effect.runSync(merged.runCollect()); // [1, 2, 3, 4] (order varies)
+ * ```
+ */
+const _merge = <T, E>(streams: ReadonlyArray<WireShape<T, E>>): WireShape<T, E> => {
+  const effectStreams = streams.map((s) => s.stream);
+  const merged = Stream.mergeAll(effectStreams, { concurrency: 'unbounded' });
+  return wrap(merged);
+};
+
+/**
+ * Collects all values from a Wire into an array.
+ *
+ * @example
+ * ```ts
+ * const wire = Wire.from(Stream.make(10, 20, 30));
+ * const values = Effect.runSync(Wire.runCollect(wire)); // [10, 20, 30]
+ * ```
+ */
+const _runCollect = <T, E>(stream: WireShape<T, E>): Effect.Effect<ReadonlyArray<T>, E> =>
+  Effect.map(Stream.runCollect(stream.stream), (chunk) => Array.from(chunk));
+
+/**
+ * Runs an effectful function for each value emitted by the Wire.
+ *
+ * @example
+ * ```ts
+ * const wire = Wire.from(Stream.make('hello', 'world'));
+ * await Effect.runPromise(Wire.runForEach(wire, s => Effect.log(s)));
+ * // Logs: hello, world
+ * ```
+ */
+const _runForEach = <T, SE, E, R>(
+  stream: WireShape<T, SE>,
+  fn: (t: T) => Effect.Effect<void, E, R>,
+): Effect.Effect<void, SE | E, R> => Stream.runForEach(stream.stream, fn);
+
+/**
+ * Wire -- fluent stream wrapper with chainable operators for map, filter,
+ * scan, debounce, throttle, merge, and more. Wraps Effect Streams.
+ *
+ * @example
+ * ```ts
+ * const wire = Wire.from(Stream.make(1, 2, 3, 4, 5));
+ * const result = wire.filter(n => n > 2).map(n => n * 10);
+ * const values = Effect.runSync(result.runCollect()); // [30, 40, 50]
+ * ```
+ */
+export const Wire = {
+  from: _from,
+  fromSSE: _fromSSE,
+  fromWebSocket: _fromWebSocket,
+  fromAsyncIterable: _fromAsyncIterable,
+  zip: _zip,
+  merge: _merge,
+  runCollect: _runCollect,
+  runForEach: _runForEach,
+};
+
+export declare namespace Wire {
+  /** Structural shape of a {@link Wire}: a fluent wrapper over `Stream.Stream<T, E>`. */
+  export type Shape<T, E = never> = WireShape<T, E>;
+}

package/src/zap.ts

@@ -0,0 +1,241 @@
+/**
+ * Zap<T> -- push-based event channel via PubSub.
+ *
+ * @module
+ */
+
+import { Effect, Stream, PubSub, Fiber, Duration } from 'effect';
+import type { Scope } from 'effect';
+import type { Millis } from './brands.js';
+
+interface ZapShape<T> {
+  readonly _tag: 'Zap';
+  readonly stream: Stream.Stream<T>;
+  emit(value: T): Effect.Effect<void>;
+}
+
+/**
+ * Creates a new push-based event channel backed by an unbounded PubSub.
+ *
+ * @example
+ * ```ts
+ * const zap = await Effect.runPromise(Effect.scoped(Zap.make<number>()));
+ * Effect.runSync(zap.emit(42));
+ * // Subscribers on zap.stream will receive 42
+ * ```
+ */
+const _make = <T>(): Effect.Effect<ZapShape<T>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const pubsub = yield* PubSub.unbounded<T>();
+
+    yield* Effect.addFinalizer(() => PubSub.shutdown(pubsub));
+
+    return {
+      _tag: 'Zap' as const,
+      stream: Stream.fromPubSub(pubsub),
+      emit: (value: T) => PubSub.publish(pubsub, value),
+    };
+  });
+
+/**
+ * Creates a Zap from a DOM event, auto-managing listener lifecycle via Scope.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const btn = document.getElementById('btn');
+ *   if (!(btn instanceof HTMLElement)) return;
+ *   const clicks = yield* Zap.fromDOMEvent(btn, 'click');
+ *   // clicks.stream emits MouseEvents; listener removed when scope closes
+ * }));
+ * ```
+ */
+const _fromDOMEvent = <K extends keyof HTMLElementEventMap>(
+  element: HTMLElement,
+  event: K,
+): Effect.Effect<ZapShape<HTMLElementEventMap[K]>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const zap = yield* _make<HTMLElementEventMap[K]>();
+
+    const listener = (e: HTMLElementEventMap[K]): void => {
+      Effect.runSync(zap.emit(e));
+    };
+
+    yield* Effect.acquireRelease(
+      Effect.sync(() => element.addEventListener(event, listener)),
+      () => Effect.sync(() => element.removeEventListener(event, listener)),
+    );
+
+    return zap;
+  });
+
+/**
+ * Merges multiple Zaps of the same type into a single Zap.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const a = yield* Zap.make<number>();
+ *   const b = yield* Zap.make<number>();
+ *   const merged = yield* Zap.merge([a, b]);
+ *   // merged.stream receives events from both a and b
+ * }));
+ * ```
+ */
+const _merge = <T>(events: ReadonlyArray<ZapShape<T>>): Effect.Effect<ZapShape<T>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const merged = yield* _make<T>();
+
+    yield* Effect.forkScoped(
+      Effect.all(
+        events.map((event) => Stream.runForEach(event.stream, (value) => merged.emit(value))),
+        { concurrency: 'unbounded' },
+      ),
+    );
+
+    return merged;
+  });
+
+/**
+ * Transforms each value emitted by a Zap through a mapping function.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const nums = yield* Zap.make<number>();
+ *   const strs = yield* Zap.map(nums, n => `value: ${n}`);
+ *   // strs.stream emits transformed strings
+ * }));
+ * ```
+ */
+const _map = <A, B>(event: ZapShape<A>, f: (a: A) => B): Effect.Effect<ZapShape<B>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const mapped = yield* _make<B>();
+
+    yield* Effect.forkScoped(Stream.runForEach(event.stream, (value) => mapped.emit(f(value))));
+
+    return mapped;
+  });
+
+/**
+ * Filters a Zap, only forwarding values that satisfy the predicate.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const nums = yield* Zap.make<number>();
+ *   const evens = yield* Zap.filter(nums, n => n % 2 === 0);
+ *   // evens.stream only receives even numbers
+ * }));
+ * ```
+ */
+const _filter = <T>(
+  event: ZapShape<T>,
+  predicate: (value: T) => boolean,
+): Effect.Effect<ZapShape<T>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const filtered = yield* _make<T>();
+
+    yield* Effect.forkScoped(
+      Stream.runForEach(event.stream, (value) => (predicate(value) ? filtered.emit(value) : Effect.void)),
+    );
+
+    return filtered;
+  });
+
+/**
+ * Debounces a Zap, only emitting after `ms` milliseconds of silence.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const input = yield* Zap.make<string>();
+ *   const debounced = yield* Zap.debounce(input, Millis(300));
+ *   // debounced.stream emits only after 300ms pause in input
+ * }));
+ * ```
+ */
+const _debounce = <T>(event: ZapShape<T>, ms: Millis): Effect.Effect<ZapShape<T>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const debounced = yield* _make<T>();
+    let pendingFiber: Fiber.Fiber<void> | null = null;
+
+    yield* Effect.forkScoped(
+      Stream.runForEach(event.stream, (value) =>
+        Effect.gen(function* () {
+          if (pendingFiber) {
+            yield* Fiber.interrupt(pendingFiber);
+          }
+          pendingFiber = yield* Effect.forkChild(
+            Effect.gen(function* () {
+              yield* Effect.sleep(Duration.millis(ms));
+              yield* debounced.emit(value);
+            }),
+          );
+        }),
+      ),
+    );
+
+    return debounced;
+  });
+
+/**
+ * Throttles a Zap, allowing at most one emission per `ms` milliseconds.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const scroll = yield* Zap.make<number>();
+ *   const throttled = yield* Zap.throttle(scroll, Millis(16));
+ *   // throttled.stream emits at most once every 16ms (~60fps)
+ * }));
+ * ```
+ */
+const _throttle = <T>(event: ZapShape<T>, ms: Millis): Effect.Effect<ZapShape<T>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const throttled = yield* _make<T>();
+    let lastEmitTime = 0;
+
+    yield* Effect.forkScoped(
+      Stream.runForEach(event.stream, (value) =>
+        Effect.gen(function* () {
+          const now = Date.now();
+          if (now - lastEmitTime >= ms) {
+            lastEmitTime = now;
+            yield* throttled.emit(value);
+          }
+        }),
+      ),
+    );
+
+    return throttled;
+  });
+
+/**
+ * Zap -- push-based event channel backed by Effect PubSub.
+ * Provides reactive event streams with map, filter, merge, debounce, and throttle.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const zap = yield* Zap.make<number>();
+ *   const doubled = yield* Zap.map(zap, n => n * 2);
+ *   yield* zap.emit(5);
+ *   // doubled.stream receives 10
+ * }));
+ * ```
+ */
+export const Zap = {
+  make: _make,
+  fromDOMEvent: _fromDOMEvent,
+  merge: _merge,
+  map: _map,
+  filter: _filter,
+  debounce: _debounce,
+  throttle: _throttle,
+};
+
+export declare namespace Zap {
+  /** Structural shape of a {@link Zap}: event-sourced reactive primitive exposing a discrete stream. */
+  export type Shape<T> = ZapShape<T>;
+}