@volynets/reflex 0.1.0 → 0.1.2

package/src/api/derived.ts

@@ -0,0 +1,90 @@
+import { readConsumerEager, readConsumerLazy } from "@reflex/runtime";
+import { createComputedNode } from "../infra";
+
+/**
+ * Creates a lazy derived accessor.
+ *
+ * `computed` runs `fn` only when the returned accessor is read. During that
+ * evaluation it tracks the reactive values that `fn` touches, caches the
+ * result, and reuses the cached value for subsequent clean reads.
+ *
+ * @typeParam T - Derived value type.
+ *
+ * @param fn - Pure synchronous computation that derives a value from reactive
+ * reads.
+ *
+ * @returns Tracked accessor that returns the latest derived value.
+ *
+ * @example
+ * ```ts
+ * createRuntime();
+ *
+ * const [count, setCount] = signal(1);
+ * const doubled = computed(() => count() * 2);
+ *
+ * console.log(doubled()); // 2
+ *
+ * setCount(2);
+ *
+ * console.log(doubled()); // 4
+ * ```
+ *
+ * @remarks
+ * - `fn` does not run until the first read.
+ * - Dependencies are tracked dynamically on each execution, so branch changes
+ *   automatically update the dependency set.
+ * - Dirty computeds recompute on demand when read again.
+ * - Reading a computed does not require `rt.flush()`; `flush()` is only for
+ *   scheduled effects.
+ * - Keep `fn` pure and synchronous.
+ *
+ * @see memo
+ * @see effect
+ */
+export function computed<T>(fn: () => T): Accessor<T> {
+  const node = createComputedNode(fn);
+  return readConsumerLazy.bind(null, node) as Accessor<T>;
+}
+
+/**
+ * Creates a computed accessor and warms it eagerly once.
+ *
+ * `memo` has the same dependency tracking and caching semantics as
+ * `computed()`, but it performs one eager read immediately after creation.
+ * This is useful when you want the initial value materialized up front while
+ * still interacting with a normal accessor afterward.
+ *
+ * @typeParam T - Derived value type.
+ *
+ * @param fn - Pure synchronous computation that derives a value from reactive
+ * reads.
+ *
+ * @returns Tracked accessor that returns the latest memoized value.
+ *
+ * @example
+ * ```ts
+ * createRuntime();
+ *
+ * const [price, setPrice] = signal(100);
+ * const total = memo(() => price() * 1.2);
+ *
+ * console.log(total()); // 120
+ *
+ * setPrice(200);
+ *
+ * console.log(total()); // 240
+ * ```
+ *
+ * @remarks
+ * - `memo(fn)` is equivalent to `computed(fn)` plus one immediate warm-up read.
+ * - After the warm-up, clean reads reuse the cached value exactly like
+ *   `computed()`.
+ * - Later invalidations still follow normal computed semantics.
+ *
+ * @see computed
+ */
+export function memo<T>(fn: () => T): Accessor<T> {
+  const node = createComputedNode(fn);
+  readConsumerEager(node);
+  return readConsumerLazy.bind(null, node) as Accessor<T>;
+}

package/src/api/effect.ts

@@ -0,0 +1,120 @@
+import {
+  disposeWatcher,
+  getDefaultContext,
+  ReactiveNodeState,
+  runWatcher,
+} from "@reflex/runtime";
+import type { ReactiveNode } from "@reflex/runtime";
+import type { UNINITIALIZED } from "../infra/factory";
+import { createWatcherNode } from "../infra/factory";
+
+/**
+ * Marks an effect watcher node as scheduled.
+ *
+ * This is a low-level helper used by scheduler integrations and tests to set
+ * the runtime's scheduled flag on a watcher node.
+ */
+export function effectScheduled(
+  node: ReactiveNode<typeof UNINITIALIZED | Destructor>,
+) {
+  node.state |= ReactiveNodeState.Scheduled;
+}
+
+/**
+ * Clears the scheduled flag from an effect watcher node.
+ *
+ * This is a low-level helper used by scheduler integrations and tests to mark
+ * a watcher as no longer queued for execution.
+ */
+export function effectUnscheduled(
+  node: ReactiveNode<typeof UNINITIALIZED | Destructor>,
+) {
+  node.state &= ~ReactiveNodeState.Scheduled;
+}
+
+/**
+ * Callback used to register cleanup produced by nested helpers with an
+ * enclosing effect scope.
+ */
+export type EffectCleanupRegistrar = (cleanup: Destructor) => void;
+
+/**
+ * Runs `fn` with a temporary cleanup registrar installed on the active runtime
+ * context.
+ *
+ * Helpers that allocate resources during `fn` can forward their teardown to
+ * `registrar`, allowing the surrounding effect or integration to dispose them
+ * automatically.
+ *
+ * @typeParam T - Return type of `fn`.
+ *
+ * @param registrar - Cleanup registrar to expose during `fn`, or `null` to run
+ * without one.
+ * @param fn - Callback executed with the temporary registrar installed.
+ *
+ * @returns The value returned by `fn`.
+ *
+ * @remarks
+ * - The registrar is scoped to the duration of `fn`.
+ * - This is a low-level integration helper. Most application code should use
+ *   `effect()` directly.
+ */
+export function withEffectCleanupRegistrar<T>(
+  registrar: EffectCleanupRegistrar | null,
+  fn: () => T,
+): T {
+  const context = getDefaultContext();
+  return context.withCleanupRegistrar(registrar, fn);
+}
+
+/**
+ * Creates a reactive effect.
+ *
+ * `effect` runs `fn` immediately, tracks any reactive values read during that
+ * run, and schedules re-execution when those dependencies change.
+ *
+ * @param fn - Effect body. It may return a cleanup function that runs before
+ * the next execution and when the effect is disposed.
+ *
+ * @returns Destructor that disposes the effect and runs the latest cleanup, if
+ * present.
+ *
+ * @example
+ * ```ts
+ * const rt = createRuntime();
+ * const [count, setCount] = signal(0);
+ *
+ * const stop = effect(() => {
+ *   console.log(count());
+ * });
+ *
+ * setCount(1);
+ * rt.flush();
+ *
+ * stop();
+ * ```
+ *
+ * @remarks
+ * - The first run happens synchronously during `effect()` creation.
+ * - With the default runtime strategy, later re-runs are queued until
+ *   `rt.flush()`.
+ * - With `createRuntime({ effectStrategy: "sab" })`, invalidations stay lazy
+ *   during propagation but auto-deliver after the outermost `rt.batch()`.
+ * - With `createRuntime({ effectStrategy: "eager" })`, invalidations flush
+ *   automatically.
+ * - Reads performed inside cleanup do not become dependencies of the next run.
+ * - Disposing the returned scope prevents future re-runs.
+ *
+ * @see createRuntime
+ * @see computed
+ * @see memo
+ */
+export function effect(fn: EffectFn): Destructor {
+  const context = getDefaultContext();
+  const node = createWatcherNode(fn);
+  runWatcher(node);
+
+  const dispose = disposeWatcher.bind(null, node) as Destructor;
+  context.registerWatcherCleanup(dispose);
+  return dispose;
+}

package/src/api/event.ts

@@ -0,0 +1,257 @@
+import {
+  disposeNodeEvent,
+  isDisposedNode,
+  readProducer,
+  writeProducer,
+} from "@reflex/runtime";
+import type { Event } from "../infra";
+import { createAccumulator } from "../infra";
+
+type EventValue<E extends Event<unknown>> =
+  E extends Event<infer T> ? T : never;
+
+function createEvent<T>(
+  subscribe: (fn: (value: T) => void) => Destructor,
+): Event<T> {
+  return { subscribe };
+}
+
+/**
+ * Subscribes to the first value from `source`, then unsubscribes automatically.
+ *
+ * The subscription is disposed before `fn` runs, so nested emits triggered from
+ * inside `fn` will not deliver a second time to the same callback.
+ */
+export function subscribeOnce<T>(
+  source: Event<T>,
+  fn: (value: T) => void,
+): Destructor {
+  let active = true;
+  let unsubscribe: Destructor | undefined;
+  let unsubscribePending = false;
+
+  const dispose = () => {
+    if (!active) return;
+
+    active = false;
+
+    const stop = unsubscribe;
+    if (stop === undefined) {
+      unsubscribePending = true;
+      return;
+    }
+
+    unsubscribe = undefined;
+    stop();
+  };
+
+  unsubscribe = source.subscribe((value) => {
+    if (!active) return;
+
+    dispose();
+    fn(value);
+  });
+
+  if (unsubscribePending) {
+    const stop = unsubscribe;
+    unsubscribe = undefined;
+    stop?.();
+  }
+
+  return dispose;
+}
+
+/**
+ * Projects each event value from `source` into a new event stream.
+ */
+export function map<T, U>(
+  source: Event<T>,
+  project: (value: T) => U,
+): Event<U> {
+  return createEvent((fn) =>
+    source.subscribe((value) => {
+      fn(project(value));
+    }),
+  );
+}
+
+/**
+ * Forwards only the values from `source` that satisfy `predicate`.
+ */
+export function filter<T, S extends T>(
+  source: Event<T>,
+  predicate: (value: T) => value is S,
+): Event<S>;
+export function filter<T>(
+  source: Event<T>,
+  predicate: (value: T) => boolean,
+): Event<T>;
+export function filter<T>(
+  source: Event<T>,
+  predicate: (value: T) => boolean,
+): Event<T> {
+  return createEvent((fn) =>
+    source.subscribe((value) => {
+      if (predicate(value)) {
+        fn(value);
+      }
+    }),
+  );
+}
+
+/**
+ * Merges multiple event sources into one event stream.
+ *
+ * The resulting event preserves the delivery order defined by the upstream
+ * sources and their runtime dispatcher.
+ */
+export function merge<const Sources extends readonly Event<unknown>[]>(
+  ...sources: Sources
+): Event<EventValue<Sources[number]>> {
+  return createEvent((fn) => {
+    const unsubscribers = sources.map((source) =>
+      source.subscribe((value) => {
+        fn(value as EventValue<Sources[number]>);
+      }),
+    );
+
+    return () => {
+      for (const unsubscribe of unsubscribers) {
+        unsubscribe();
+      }
+    };
+  });
+}
+
+/**
+ * Creates an accumulator derived from an event stream.
+ *
+ * `scan` listens to `source` and applies `reducer` to the current accumulated
+ * state and each incoming event value. The result becomes the next stored state.
+ *
+ * It is analogous to `Array.prototype.reduce`, but for a stream of events over time.
+ *
+ * @typeParam T - Event payload type.
+ * @typeParam A - Accumulator state type.
+ *
+ * @param source - Event source to subscribe to.
+ * @param seed - Initial accumulator state used before the first event arrives.
+ * @param reducer - Pure function that receives the current accumulated state and
+ * the next event value, and returns the next accumulated state.
+ *
+ * @returns A tuple:
+ * - `read` - accessor that returns the current accumulated state.
+ * - `dispose` - destructor that unsubscribes from the source and disposes the internal node.
+ *
+ * @example
+ * ```ts
+ * const rt = createRuntime();
+ * const increments = rt.event<number>();
+ *
+ * const [total, dispose] = scan(increments, 0, (acc, value) => acc + value);
+ *
+ * increments.emit(1);
+ * increments.emit(2);
+ *
+ * console.log(total()); // 3
+ *
+ * dispose();
+ * ```
+ *
+ * @remarks
+ * - `seed` is used as the initial state until the first event is delivered.
+ * - `reducer` should be pure and synchronous.
+ * - `reducer` should derive the next state only from the previous accumulated
+ *   state and the current event value.
+ * - The accumulated value is updated only in response to `source` events.
+ * - Do not read signals, computeds, or other reactive values inside
+ *   `reducer`. `scan` does not track reactive dependencies read there.
+ * - If you need to combine event-driven state with reactive state, first
+ *   derive the accumulator with `scan`, then combine it outside via
+ *   `computed()`.
+ * - To stop receiving updates and release subscriptions, call `dispose`.
+ *
+ * @see hold
+ */
+export function scan<T, A>(
+  source: Event<T>,
+  seed: A,
+  reducer: (acc: A, value: T) => A,
+): [read: Accessor<A>, dispose: Destructor] {
+  return createScan(source, seed, reducer);
+}
+
+/**
+ * Stores the latest value emitted by an event source.
+ *
+ * `hold` is a specialized form of {@link scan} that replaces the current state
+ * with each new event value.
+ *
+ * @typeParam T - Event payload type.
+ *
+ * @param source - Event source to subscribe to.
+ * @param initial - Initial value returned before the first event arrives.
+ *
+ * @returns A tuple:
+ * - `read` - accessor that returns the latest observed event value.
+ * - `dispose` - destructor that unsubscribes from the source and disposes the internal node.
+ *
+ * @example
+ * ```ts
+ * const rt = createRuntime();
+ * const updates = rt.event<string>();
+ *
+ * const [latest, dispose] = hold(updates, "idle");
+ *
+ * console.log(latest()); // "idle"
+ *
+ * updates.emit("loading");
+ * console.log(latest()); // "loading"
+ *
+ * updates.emit("done");
+ * console.log(latest()); // "done"
+ *
+ * dispose();
+ * ```
+ *
+ * @remarks
+ * - `initial` is returned until the first event is delivered.
+ * - Equivalent to:
+ *   `scan(source, initial, (_, value) => value)`
+ *
+ * @see scan
+ */
+export function hold<T>(
+  source: Event<T>,
+  initial: T,
+): [read: Accessor<T>, dispose: Destructor] {
+  return createScan(source, initial, (_, value) => value);
+}
+
+function createScan<T, A>(
+  source: Event<T>,
+  seed: A,
+  reducer: (acc: A, value: T) => A,
+): [read: Accessor<A>, dispose: Destructor] {
+  const node = createAccumulator(seed);
+  let current = seed;
+  const accessor = () => (isDisposedNode(node) ? current : readProducer(node));
+
+  let unsubscribe: Destructor | undefined = source.subscribe((value: T) => {
+    /* c8 ignore start -- disposal unsubscribes before a queued delivery can reach this callback */
+    if (isDisposedNode(node)) return;
+    /* c8 ignore stop */
+    current = reducer(current, value);
+    writeProducer(node, current);
+  });
+
+  function dispose(): void {
+    disposeNodeEvent(node);
+
+    const stop = unsubscribe;
+    unsubscribe = undefined;
+    stop?.();
+  }
+
+  return [accessor, dispose];
+}

package/src/api/index.ts

@@ -0,0 +1,4 @@
+export * from "./derived";
+export * from "./effect";
+export * from "./event";
+export * from "./signal";

package/src/api/signal.ts

@@ -0,0 +1,68 @@
+import { readProducer, writeProducer } from "@reflex/runtime";
+import { createSignalNode } from "../infra";
+
+/**
+ * Creates writable reactive state.
+ *
+ * `signal` returns a tuple containing a tracked read accessor and a setter.
+ * Reading the accessor inside `computed()`, `memo()`, or `effect()` registers
+ * a dependency. Writing through the setter updates the stored value
+ * synchronously and invalidates downstream reactive consumers only when the
+ * value actually changes.
+ *
+ * @typeParam T - Signal value type.
+ *
+ * @param initialValue - Initial signal value returned until a later write
+ * replaces it.
+ * @param options - Optional development diagnostics. `options.name` is used
+ * only in development builds when formatting setter error messages.
+ *
+ * @returns A readonly tuple:
+ * - `value` - tracked accessor that returns the current signal value.
+ * - `setValue` - setter that accepts either a direct value or an updater
+ *   function receiving the previous value. The setter returns the committed
+ *   next value.
+ *
+ * @example
+ * ```ts
+ * createRuntime();
+ *
+ * const [count, setCount] = signal(0);
+ *
+ * console.log(count()); // 0
+ *
+ * setCount(1);
+ * setCount((prev) => prev + 1);
+ *
+ * console.log(count()); // 2
+ * ```
+ *
+ * @remarks
+ * - Reads are synchronous and always return the latest committed value.
+ * - Same-value writes do not invalidate downstream computed values or effects.
+ * - Calling `setValue()` with no argument is only valid when `T` includes
+ *   `undefined`.
+ * - In typical app code, call `createRuntime()` during setup before building
+ *   the rest of the reactive graph.
+ *
+ * @see computed
+ * @see memo
+ * @see effect
+ */
+export function signal<T>(initialValue: T): readonly [Accessor<T>, Setter<T>] {
+  const node = createSignalNode(initialValue);
+
+  function set(input: SetInput<T>) {
+    const payload = node.payload;
+    const next =
+      typeof input === "function"
+        ? (input as (prev: T) => T)(payload as T)
+        : input;
+    writeProducer(node, next);
+  }
+
+  return [
+    readProducer.bind(null, node) as Accessor<T>,
+    set as Setter<T>,
+  ] as const;
+}

package/src/globals.d.ts

@@ -0,0 +1,169 @@
+declare const __DEV__: boolean;
+
+/**
+ * Cleanup function returned from an effect.
+ */
+type Destructor = () => void;
+
+/**
+ * Effect callback.
+ * May return a cleanup function.
+ */
+type EffectFn = () => void | Destructor;
+
+type AnyFn = (...args: unknown[]) => unknown;
+
+/**
+ * Direct value that can be assigned via `.set(value)`.
+ * Function values are excluded to avoid ambiguity with updater functions.
+ */
+type DirectValue<T> = Exclude<T, AnyFn>;
+
+/**
+ * Functional updater.
+ */
+type Updater<T> = (prev: T) => T;
+
+/**
+ * Accepted input for writable reactive values.
+ */
+type SetInput<T> = DirectValue<T> | Updater<T>;
+
+interface RequiredSetter<T> {
+  (value: SetInput<T>): T;
+}
+
+interface OptionalSetter<T> {
+  (): T;
+  (value: SetInput<T>): T;
+}
+
+/**
+ * If T includes undefined, calling `set()` with no arguments is allowed.
+ */
+type Setter<T> = undefined extends T ? OptionalSetter<T> : RequiredSetter<T>;
+
+/**
+ * Nominal brand helper for semantically distinct reactive primitives.
+ */
+interface Brand<K extends string> {
+  readonly __brand?: K;
+}
+
+/**
+ * Callable tracked read.
+ */
+interface Accessor<T> {
+  (): T;
+}
+
+/**
+ * Property-based read.
+ */
+interface ValueReadable<T> {
+  readonly value: T;
+}
+
+/**
+ * Untracked read.
+ */
+interface Peekable<T> {
+  peek(): T;
+}
+
+/**
+ * Writable capability.
+ */
+interface Writable<T> {
+  set: Setter<T>;
+}
+
+interface Disposable {
+  (): void;
+}
+
+/**
+ * Standard readable reactive value.
+ */
+interface Readable<T> extends Accessor<T>, ValueReadable<T> {}
+
+/**
+ * Readable value with untracked read.
+ */
+interface PeekableReadable<T> extends Readable<T>, Peekable<T> {}
+
+/**
+ * Writable signal-like value.
+ */
+interface WritableReadable<T> extends Readable<T>, Writable<T> {}
+
+/**
+ * Writable signal-like value with untracked read.
+ */
+interface PeekableWritableReadable<T>
+  extends WritableReadable<T>,
+    Peekable<T> {}
+
+/**
+ * Mutable signal.
+ */
+interface Signal<T> extends PeekableWritableReadable<T>, Brand<"signal"> {}
+
+/**
+ * Computed reactive value.
+ */
+interface Computed<T> extends PeekableReadable<T>, Brand<"computed"> {}
+
+/**
+ * Memoized derived value.
+ */
+interface Memo<T> extends PeekableReadable<T>, Brand<"memo"> {}
+
+/**
+ * Derived reactive value.
+ */
+interface Derived<T> extends PeekableReadable<T>, Brand<"derived"> {}
+
+interface Effect<T> extends Readable<T>, Brand<"effect">, Disposable {}
+
+interface Scan<T> extends Readable<T>, Brand<"scan">, Disposable {}
+
+/**
+ * Push-based realtime source.
+ */
+interface Realtime<T> extends PeekableWritableReadable<T>, Brand<"realtime"> {
+  subscribe(cb: () => void): () => void;
+}
+
+/**
+ * Async iterable stream source.
+ */
+interface Stream<T> extends PeekableWritableReadable<T>, Brand<"stream"> {
+  [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+
+/**
+ * Common readonly view over reactive values.
+ */
+type ReadableLike<T> =
+  | Signal<T>
+  | Computed<T>
+  | Memo<T>
+  | Derived<T>
+  | Realtime<T>
+  | Stream<T>;
+
+/**
+ * Common writable view over reactive values.
+ */
+type WritableLike<T> = Signal<T> | Realtime<T> | Stream<T>;
+
+/**
+ * Extract value type from a reactive value.
+ */
+type ValueOf<T> =
+  T extends Accessor<infer V>
+    ? V
+    : T extends ValueReadable<infer V>
+      ? V
+      : never;

package/src/index.ts

@@ -0,0 +1,6 @@
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="./globals.d.ts" />
+
+export { signal, computed, memo, effect, withEffectCleanupRegistrar } from "./api";
+export { subscribeOnce, map, filter, merge, scan, hold } from "./api";
+export { createRuntime } from "./infra";