@czap/core 0.1.0

package/src/derived.ts

@@ -0,0 +1,164 @@
+/**
+ * Derived<T> -- computed reactive value.
+ *
+ * @module
+ */
+
+import type { Scope } from 'effect';
+import { Effect, Stream, SubscriptionRef } from 'effect';
+import { tupleMap } from './tuple.js';
+import type { Cell } from './cell.js';
+import { readAllCellValues } from './cell.js';
+
+interface DerivedShape<T> {
+  readonly _tag: 'Derived';
+  readonly changes: Stream.Stream<T>;
+  readonly get: Effect.Effect<T>;
+}
+
+const _make = <T>(
+  compute: Effect.Effect<T>,
+  sources: ReadonlyArray<Stream.Stream<unknown>> = [],
+): Effect.Effect<DerivedShape<T>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const initialValue = yield* compute;
+    const ref = yield* SubscriptionRef.make(initialValue);
+
+    if (sources.length > 0) {
+      const merged = Stream.mergeAll(sources, { concurrency: 'unbounded' });
+      yield* Effect.forkScoped(
+        Stream.runForEach(merged, () =>
+          Effect.gen(function* () {
+            const newValue = yield* compute;
+            yield* SubscriptionRef.set(ref, newValue);
+          }),
+        ),
+      );
+    }
+
+    return {
+      _tag: 'Derived' as const,
+      changes: SubscriptionRef.changes(ref),
+      get: SubscriptionRef.get(ref),
+    };
+  });
+
+const _combine = <T extends readonly unknown[], U>(
+  cells: { [K in keyof T]: Cell.Shape<T[K]> },
+  combiner: (...args: T) => U,
+): Effect.Effect<DerivedShape<U>, never, Scope.Scope> => {
+  const readAll = readAllCellValues<T>(cells);
+
+  return Effect.gen(function* () {
+    const initialValues = yield* readAll;
+    const initialResult = combiner(...initialValues);
+    const ref = yield* SubscriptionRef.make(initialResult);
+
+    const cellStreams = tupleMap(cells, (cell) => cell.changes);
+    const combinedStream = Stream.mergeAll(cellStreams, {
+      concurrency: 'unbounded',
+    }).pipe(
+      Stream.mapEffect(() =>
+        Effect.gen(function* () {
+          const currentValues = yield* readAll;
+          const result = combiner(...currentValues);
+          yield* SubscriptionRef.set(ref, result);
+          return result;
+        }),
+      ),
+    );
+
+    yield* Effect.forkScoped(Stream.runDrain(combinedStream));
+
+    return {
+      _tag: 'Derived' as const,
+      changes: SubscriptionRef.changes(ref),
+      get: SubscriptionRef.get(ref),
+    };
+  });
+};
+
+const _map = <A, B>(derived: DerivedShape<A>, f: (a: A) => B): Effect.Effect<DerivedShape<B>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const initialValue = yield* derived.get;
+    const mappedValue = f(initialValue);
+    const ref = yield* SubscriptionRef.make(mappedValue);
+
+    const mappedStream = derived.changes.pipe(
+      Stream.map(f),
+      Stream.tap((value) => SubscriptionRef.set(ref, value)),
+    );
+
+    yield* Effect.forkScoped(Stream.runDrain(mappedStream));
+
+    return {
+      _tag: 'Derived' as const,
+      changes: SubscriptionRef.changes(ref),
+      get: SubscriptionRef.get(ref),
+    };
+  });
+
+const _flatten = <T>(nested: DerivedShape<DerivedShape<T>>): Effect.Effect<DerivedShape<T>, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const initialInner = yield* nested.get;
+    const initialValue = yield* initialInner.get;
+    const ref = yield* SubscriptionRef.make(initialValue);
+
+    const flattenedStream = nested.changes.pipe(
+      Stream.switchMap((inner) => {
+        let currentValue: T | undefined;
+        let hasCurrentValue = false;
+        let skippedReplay = false;
+        return Stream.concat(
+          Stream.make(inner).pipe(
+            Stream.mapEffect((currentInner) => currentInner.get),
+            Stream.tap((value) =>
+              Effect.sync(() => {
+                currentValue = value;
+                hasCurrentValue = true;
+              }),
+            ),
+          ),
+          inner.changes.pipe(
+            Stream.filter((value) => {
+              if (!skippedReplay && hasCurrentValue && Object.is(value, currentValue)) {
+                skippedReplay = true;
+                return false;
+              }
+              return true;
+            }),
+          ),
+        );
+      }),
+      Stream.tap((value) => SubscriptionRef.set(ref, value)),
+    );
+
+    yield* Effect.forkScoped(Stream.runDrain(flattenedStream));
+
+    return {
+      _tag: 'Derived' as const,
+      changes: SubscriptionRef.changes(ref),
+      get: SubscriptionRef.get(ref),
+    };
+  });
+
+/**
+ * Derived — read-only reactive view computed from upstream {@link Cell}s.
+ * A `Derived` recomputes lazily and pushes the new value into its own stream
+ * when any dependency changes; composes via `combine`, `map`, and `flatten`.
+ */
+export const Derived = {
+  /** Build a derived cell from a factory computing against upstream sources. */
+  make: _make,
+  /** Combine multiple cells into a single derived cell of their tuple. */
+  combine: _combine,
+  /** Pure projection of an existing cell/derived. */
+  map: _map,
+  /** Flatten a derived-of-derived into a single derived of the inner value. */
+  flatten: _flatten,
+};
+
+export declare namespace Derived {
+  /** Structural shape of a {@link Derived}: `_tag`, `get`, `changes`. */
+  export type Shape<T> = DerivedShape<T>;
+}

package/src/diagnostics.ts

@@ -0,0 +1,186 @@
+/**
+ * Diagnostics -- centralized runtime warning/error emission.
+ *
+ * Provides typed warning/error helpers with a swappable sink so runtime
+ * boundaries can emit operator-visible diagnostics without hard-coding
+ * console calls throughout the codebase.
+ *
+ * @module
+ */
+
+/** Severity level for a {@link DiagnosticEvent}. */
+export type DiagnosticLevel = 'warn' | 'error';
+
+/**
+ * Operator-facing payload shape for a single diagnostic emission: a stable
+ * `source`/`code` pair for filtering, a human message, plus optional structured
+ * detail and an underlying cause.
+ */
+export interface DiagnosticPayload {
+  readonly source: string;
+  readonly code: string;
+  readonly message: string;
+  readonly cause?: unknown;
+  readonly detail?: unknown;
+}
+
+/** A {@link DiagnosticPayload} enriched with severity and an emission timestamp. */
+export interface DiagnosticEvent extends DiagnosticPayload {
+  readonly level: DiagnosticLevel;
+  readonly timestamp: number;
+}
+
+/** Swappable transport that receives {@link DiagnosticEvent}s from {@link Diagnostics}. */
+export interface DiagnosticsSink {
+  emit(event: DiagnosticEvent): void;
+}
+
+type ConsoleMethodName = Extract<DiagnosticLevel, 'warn' | 'error'>;
+
+interface ConsoleLike {
+  readonly warn?: (...args: readonly unknown[]) => void;
+  readonly error?: (...args: readonly unknown[]) => void;
+}
+
+function asConsoleLike(value: unknown): ConsoleLike | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const v = value as Record<string, unknown>;
+  // Require at least one usable method; warn/error may be absent in stripped envs.
+  if (typeof v['warn'] !== 'function' && typeof v['error'] !== 'function') return null;
+  return value as ConsoleLike;
+}
+
+function getConsoleMethod(level: ConsoleMethodName): ((...args: readonly unknown[]) => void) | null {
+  const consoleLike = asConsoleLike(globalThis.console);
+  const method = consoleLike?.[level];
+  return typeof method === 'function' ? method.bind(consoleLike) : null;
+}
+
+function formatHeadline(event: DiagnosticEvent): string {
+  return `[${event.source}] ${event.code}: ${event.message}`;
+}
+
+function toArgs(event: DiagnosticEvent): readonly unknown[] {
+  const args: unknown[] = [formatHeadline(event)];
+
+  if (event.detail !== undefined) {
+    args.push(event.detail);
+  }
+
+  if (event.cause !== undefined) {
+    args.push(event.cause);
+  }
+
+  return args;
+}
+
+const defaultSink: DiagnosticsSink = {
+  emit(event) {
+    const method = getConsoleMethod(event.level);
+    if (method) {
+      method(...toArgs(event));
+    }
+  },
+};
+
+let currentSink: DiagnosticsSink = defaultSink;
+const onceKeys = new Set<string>();
+
+function toEvent(level: DiagnosticLevel, payload: DiagnosticPayload): DiagnosticEvent {
+  return {
+    ...payload,
+    level,
+    timestamp: Date.now(),
+  };
+}
+
+function emit(level: DiagnosticLevel, payload: DiagnosticPayload): DiagnosticEvent {
+  const event = toEvent(level, payload);
+  currentSink.emit(event);
+  return event;
+}
+
+function buildOnceKey(payload: DiagnosticPayload): string {
+  return `${payload.source}:${payload.code}:${payload.message}`;
+}
+
+function warn(payload: DiagnosticPayload): DiagnosticEvent {
+  return emit('warn', payload);
+}
+
+function error(payload: DiagnosticPayload): DiagnosticEvent {
+  return emit('error', payload);
+}
+
+function warnOnce(payload: DiagnosticPayload): DiagnosticEvent | null {
+  const key = buildOnceKey(payload);
+  if (onceKeys.has(key)) {
+    return null;
+  }
+
+  onceKeys.add(key);
+  return warn(payload);
+}
+
+function setSink(sink: DiagnosticsSink): void {
+  currentSink = sink;
+}
+
+function resetSink(): void {
+  currentSink = defaultSink;
+}
+
+function clearOnce(): void {
+  onceKeys.clear();
+}
+
+function reset(): void {
+  resetSink();
+  clearOnce();
+}
+
+function createBufferSink(): { readonly sink: DiagnosticsSink; readonly events: DiagnosticEvent[] } {
+  const events: DiagnosticEvent[] = [];
+  return {
+    sink: {
+      emit(event) {
+        events.push(event);
+      },
+    },
+    events,
+  };
+}
+
+/**
+ * Diagnostics facade — runtime boundaries call {@link Diagnostics.warn} / {@link Diagnostics.error}
+ * instead of `console.*` so hosts can redirect or capture every diagnostic via {@link Diagnostics.setSink}.
+ */
+export const Diagnostics = {
+  /** Emit a `warn`-level {@link DiagnosticEvent} to the current sink. */
+  warn,
+  /** Emit an `error`-level {@link DiagnosticEvent} to the current sink. */
+  error,
+  /** {@link Diagnostics.warn}, but deduplicated by `source:code:message`. */
+  warnOnce,
+  /** Replace the active sink (e.g. for tests or hosted environments). */
+  setSink,
+  /** Restore the default sink that writes through `console`. */
+  resetSink,
+  /** Clear the deduplication set used by {@link Diagnostics.warnOnce}. */
+  clearOnce,
+  /** Convenience for `resetSink()` + `clearOnce()` — mostly for test teardown. */
+  reset,
+  /** Build an in-memory sink that collects events into an array — useful for tests. */
+  createBufferSink,
+} as const;
+
+export declare namespace Diagnostics {
+  /** Alias for {@link DiagnosticPayload}. */
+  export type Payload = DiagnosticPayload;
+  /** Alias for {@link DiagnosticEvent}. */
+  export type Event = DiagnosticEvent;
+  /** Alias for {@link DiagnosticLevel}. */
+  export type Level = DiagnosticLevel;
+  /** Alias for {@link DiagnosticsSink}. */
+  export type Sink = DiagnosticsSink;
+}

package/src/dirty.ts

@@ -0,0 +1,101 @@
+/**
+ * DirtyFlags -- bitmask dirty tracking.
+ *
+ * Maps string keys to bit positions in a 32-bit integer mask,
+ * enabling O(1) mark/clear/check operations for change tracking.
+ *
+ * @module
+ */
+
+import { DIRTY_FLAGS_MAX } from './defaults.js';
+
+interface DirtyFlagsShape<K extends string = string> {
+  mark(key: K): void;
+  clear(key: K): void;
+  clearAll(): void;
+  isDirty(key: K): boolean;
+  getDirty(): readonly K[];
+  readonly mask: number;
+}
+
+/**
+ * Creates a bitmask-based dirty tracker for the given keys (max 31).
+ * Enables O(1) mark, clear, and check operations for change tracking.
+ *
+ * @example
+ * ```ts
+ * const flags = DirtyFlags.make(['position', 'color', 'opacity'] as const);
+ * flags.mark('position');
+ * flags.mark('color');
+ * flags.isDirty('position'); // true
+ * flags.isDirty('opacity');  // false
+ * flags.getDirty();          // ['position', 'color']
+ * flags.clearAll();
+ * flags.mask;                // 0
+ * ```
+ */
+function _make<K extends string>(keys: readonly K[]): DirtyFlagsShape<K> {
+  if (keys.length > DIRTY_FLAGS_MAX) {
+    throw new RangeError(`DirtyFlags supports at most ${DIRTY_FLAGS_MAX} keys, got ${keys.length}`);
+  }
+
+  const bitMap = new Map<K, number>();
+  keys.forEach((key, i) => {
+    bitMap.set(key, 1 << i);
+  });
+
+  let mask = 0;
+
+  return {
+    mark(key: K): void {
+      const bit = bitMap.get(key);
+      if (bit !== undefined) mask |= bit;
+    },
+
+    clear(key: K): void {
+      const bit = bitMap.get(key);
+      if (bit !== undefined) mask &= ~bit;
+    },
+
+    clearAll(): void {
+      mask = 0;
+    },
+
+    isDirty(key: K): boolean {
+      const bit = bitMap.get(key);
+      return bit !== undefined ? (mask & bit) !== 0 : false;
+    },
+
+    getDirty(): readonly K[] {
+      const dirty: K[] = [];
+      for (const [key, bit] of bitMap) {
+        if ((mask & bit) !== 0) dirty.push(key);
+      }
+      return dirty;
+    },
+
+    get mask(): number {
+      return mask;
+    },
+  };
+}
+
+/**
+ * DirtyFlags -- bitmask-based dirty tracking for up to 31 named keys.
+ * O(1) mark/clear/check operations using bitwise integer operations.
+ *
+ * @example
+ * ```ts
+ * const flags = DirtyFlags.make(['transform', 'style'] as const);
+ * flags.mark('transform');
+ * flags.isDirty('transform'); // true
+ * flags.clear('transform');
+ * flags.isDirty('transform'); // false
+ * ```
+ */
+export const DirtyFlags = { make: _make };
+
+export declare namespace DirtyFlags {
+  /** Structural shape of a {@link DirtyFlags} instance keyed by flag name `K`. */
+  export type Shape<K extends string = string> = DirtyFlagsShape<K>;
+}