@volynets/reflex 0.1.1 → 0.1.2

package/src/infra/event.ts

@@ -0,0 +1,182 @@
+export const enum EventSubscriberState {
+  Active = 1 << 0,
+  Disposed = 1 << 1,
+}
+
+export class EventSource<T> {
+  dispatchDepth = 0;
+  head: EventSubscriber<T> | null = null;
+  tail: EventSubscriber<T> | null = null;
+  pendingHead: EventSubscriber<T> | null = null;
+}
+
+export interface EventSubscriber<T> {
+  fn: (value: T) => void;
+  next: EventSubscriber<T> | null;
+  prev: EventSubscriber<T> | null;
+  state: number;
+  unlinkNext: EventSubscriber<T> | null;
+}
+
+export type EventBoundary = <T>(fn: () => T) => T;
+
+const EVENT_SUBSCRIBER_OWNER = Symbol("EventSubscriber.owner");
+
+type OwnedEventSubscriber<T> = EventSubscriber<T> & {
+  [EVENT_SUBSCRIBER_OWNER]?: EventSource<T> | null;
+};
+
+function getSubscriberOwner<T>(
+  subscriber: EventSubscriber<T>,
+): EventSource<T> | null | undefined {
+  return (subscriber as OwnedEventSubscriber<T>)[EVENT_SUBSCRIBER_OWNER];
+}
+
+function setSubscriberOwner<T>(
+  subscriber: EventSubscriber<T>,
+  source: EventSource<T> | null,
+): void {
+  (subscriber as OwnedEventSubscriber<T>)[EVENT_SUBSCRIBER_OWNER] = source;
+}
+
+export function identityBoundary<T>(fn: () => T): T {
+  return fn();
+}
+
+export function appendSubscriber<T>(
+  source: EventSource<T>,
+  subscriber: EventSubscriber<T>,
+): void {
+  if ((subscriber.state & EventSubscriberState.Active) === 0) return;
+
+  const owner = getSubscriberOwner(subscriber);
+  if (owner !== undefined && owner !== null) return;
+
+  const tail = source.tail;
+  subscriber.prev = tail;
+  subscriber.next = null;
+  subscriber.unlinkNext = null;
+  setSubscriberOwner(subscriber, source);
+
+  if (tail === null) {
+    source.head = source.tail = subscriber;
+    return;
+  }
+
+  tail.next = subscriber;
+  source.tail = subscriber;
+}
+
+function unlinkSubscriber<T>(
+  source: EventSource<T>,
+  subscriber: EventSubscriber<T>,
+): void {
+  const prev = subscriber.prev;
+  const next = subscriber.next;
+
+  if (prev === null) source.head = next;
+  else prev.next = next;
+
+  if (next === null) source.tail = prev;
+  else next.prev = prev;
+
+  subscriber.prev = null;
+  subscriber.next = null;
+  subscriber.unlinkNext = null;
+  setSubscriberOwner(subscriber, null);
+}
+
+function enqueuePendingRemoval<T>(
+  source: EventSource<T>,
+  subscriber: EventSubscriber<T>,
+): void {
+  if ((subscriber.state & EventSubscriberState.Disposed) !== 0) return;
+
+  subscriber.state |= EventSubscriberState.Disposed;
+  subscriber.unlinkNext = source.pendingHead;
+  source.pendingHead = subscriber;
+}
+
+function flushPendingRemovals<T>(source: EventSource<T>): void {
+  let node = source.pendingHead;
+  source.pendingHead = null;
+
+  while (node !== null) {
+    const next = node.unlinkNext;
+    node.unlinkNext = null;
+
+    unlinkSubscriber(source, node);
+    node = next;
+  }
+}
+
+export function removeSubscriber<T>(
+  source: EventSource<T>,
+  subscriber: EventSubscriber<T>,
+): void {
+  if (getSubscriberOwner(subscriber) !== source) return;
+  if ((subscriber.state & EventSubscriberState.Active) === 0) return;
+
+  subscriber.state &= ~EventSubscriberState.Active;
+
+  if (source.dispatchDepth !== 0) {
+    enqueuePendingRemoval(source, subscriber);
+    return;
+  }
+
+  subscriber.state |= EventSubscriberState.Disposed;
+  unlinkSubscriber(source, subscriber);
+}
+
+export function subscribeEvent<T>(
+  source: EventSource<T>,
+  fn: (value: T) => void,
+): () => void {
+  const subscriber: EventSubscriber<T> = {
+    fn,
+    next: null,
+    prev: null,
+    state: EventSubscriberState.Active,
+    unlinkNext: null,
+  };
+
+  appendSubscriber(source, subscriber);
+
+  return () => {
+    removeSubscriber(source, subscriber);
+  };
+}
+
+export function emitEvent<T>(
+  source: EventSource<T>,
+  value: T,
+  boundary: EventBoundary = identityBoundary,
+): void {
+  boundary(() => {
+    const end = source.tail;
+    if (end === null) return;
+
+    ++source.dispatchDepth;
+
+    try {
+      let node = source.head;
+
+      while (node !== null) {
+        const current = node;
+        const next = current === end ? null : current.next;
+
+        if ((current.state & EventSubscriberState.Active) !== 0) {
+          current.fn(value);
+        }
+
+        node = next;
+      }
+    } finally {
+      --source.dispatchDepth;
+
+      if (source.dispatchDepth === 0 && source.pendingHead !== null) {
+        flushPendingRemovals(source);
+      }
+    }
+  });
+}

package/src/infra/factory.ts

@@ -0,0 +1,46 @@
+import {
+  ReactiveNode as RuntimeReactiveNode,
+  PRODUCER_INITIAL_STATE,
+  WATCHER_INITIAL_STATE,
+  CONSUMER_INITIAL_STATE,
+} from "@reflex/runtime";
+import type { ReactiveNode } from "@reflex/runtime";
+import { EventSource as RuntimeEventSource } from "./event";
+
+export const UNINITIALIZED = Symbol("UNINITIALIZED") as unknown;
+
+export const createSignalNode = <T>(payload: T) => {
+  return new RuntimeReactiveNode<T>(
+    payload,
+    /*TODO: replace with undefined*/ null,
+    PRODUCER_INITIAL_STATE,
+  );
+};
+
+export const createSource = <T>(): RuntimeEventSource<T> => {
+  return new RuntimeEventSource<T>();
+};
+
+export const createResourceStateNode = () => {
+  return new RuntimeReactiveNode<number>(
+    0,
+    /*TODO: replace with undefined*/ null,
+    PRODUCER_INITIAL_STATE,
+  );
+};
+
+export const createAccumulator = <T>(payload: T): ReactiveNode<T> => {
+  return new RuntimeReactiveNode(
+    payload,
+    /*TODO: replace with undefined*/ null,
+    PRODUCER_INITIAL_STATE,
+  );
+};
+
+export const createComputedNode = <T>(fn: () => T) => {
+  return new RuntimeReactiveNode<T>(undefined as T, fn, CONSUMER_INITIAL_STATE);
+};
+
+export const createWatcherNode = (compute: EffectFn): ReactiveNode => {
+  return new RuntimeReactiveNode(undefined, compute, WATCHER_INITIAL_STATE);
+};

package/src/infra/index.ts

@@ -0,0 +1,2 @@
+export * from "./factory";
+export * from "./runtime";

package/src/infra/runtime.ts

@@ -0,0 +1,189 @@
+import { createExecutionContext, setDefaultContext } from "@reflex/runtime";
+import type { ExecutionContext, EngineHooks } from "@reflex/runtime";
+import { subscribeEvent } from "./event";
+import { createSource } from "./factory";
+import { EventDispatcher } from "../policy";
+import type { EffectStrategy } from "../policy/scheduler";
+import {
+  createEffectScheduler,
+  resolveEffectSchedulerMode,
+} from "../policy/scheduler";
+
+export interface RuntimeOptions {
+  /**
+   * Optional low-level runtime hooks forwarded to the execution context.
+   *
+   * These hooks are composed with Reflex's scheduler integration rather than
+   * replacing it.
+   */
+  hooks?: EngineHooks;
+  /**
+   * Controls when invalidated effects are executed.
+   *
+   * - `"flush"` queues reruns until `rt.flush()` is called.
+   * - `"sab"` keeps lazy enqueue semantics but stabilizes effects after the
+   *   outermost `rt.batch()` exits.
+   * - `"eager"` flushes reruns automatically.
+   *
+   * @default "flush"
+   */
+  effectStrategy?: EffectStrategy;
+}
+
+function createRuntimeInfrastructure(options?: RuntimeOptions) {
+  const executionContext = createExecutionContext(options?.hooks);
+  const scheduler = createEffectScheduler(
+    resolveEffectSchedulerMode(options?.effectStrategy),
+    executionContext,
+  );
+  const dispatcher = new EventDispatcher(scheduler.batch);
+
+  executionContext.setRuntimeHooks(
+    scheduler.enqueue,
+    scheduler.runtimeNotifySettled,
+  );
+
+  executionContext.resetState();
+  setDefaultContext(executionContext);
+
+  return {
+    scheduler,
+    dispatcher,
+    executionContext,
+  };
+}
+
+/**
+ * Push-based event stream that allows observers to subscribe to future values.
+ *
+ * `Event` is the read-only view of an event source. It does not expose
+ * mutation, only observation.
+ *
+ * @typeParam T - Event payload type.
+ */
+export interface Event<T> {
+  /**
+   * Registers a callback for future event deliveries.
+   *
+   * @param fn - Callback invoked for each emitted value.
+   *
+   * @returns Destructor that unsubscribes `fn`.
+   */
+  subscribe(fn: (value: T) => void): Destructor;
+}
+
+/**
+ * Mutable event source created by `Runtime.event()`.
+ *
+ * @typeParam T - Event payload type.
+ */
+export interface EventSource<T> extends Event<T> {
+  /**
+   * Emits a value to current subscribers using the runtime dispatcher.
+   *
+   * Nested emits are queued after the current delivery completes, preserving
+   * FIFO ordering across sources created by the same runtime.
+   *
+   * @param value - Event payload to deliver.
+   */
+  emit(value: T): void;
+}
+
+/**
+ * Connected Reflex runtime returned by `createRuntime()`.
+ *
+ * The runtime owns the event dispatcher, effect scheduler, and execution
+ * context used by the top-level Reflex primitives.
+ */
+export interface Runtime {
+  batch<T>(fn: () => T): T;
+  /**
+   * Creates a new mutable event source associated with this runtime.
+   *
+   * @typeParam T - Event payload type.
+   *
+   * @returns Event source with `emit(value)` and `subscribe(fn)`.
+   */
+  event<T>(): EventSource<T>;
+  /**
+   * Flushes queued effect re-runs immediately.
+   *
+   * In the default `"flush"` strategy, call this after writes when you want
+   * scheduled effects to observe the latest stable snapshot. In `"sab"` and
+   * `"eager"` it remains available as an explicit synchronization escape hatch.
+   */
+  flush(): void;
+  /**
+   * Underlying execution context used by this runtime.
+   *
+   * Most application code does not need this. It exists for low-level
+   * integrations, tests, and diagnostics.
+   */
+  readonly ctx: ExecutionContext;
+}
+
+/**
+ * Creates and installs the active Reflex runtime.
+ *
+ * `createRuntime` wires together an execution context, effect scheduler, and
+ * event dispatcher, then makes that context the default runtime used by the
+ * top-level Reflex primitives exported from this package.
+ *
+ * @param options - Optional runtime configuration:
+ * - `effectStrategy` controls whether invalidated effects flush on
+ *   `rt.flush()`, stabilize after the outermost batch, or run automatically.
+ * - `hooks` installs low-level runtime hooks that are composed with Reflex's
+ *   scheduler integration.
+ *
+ * @returns Connected runtime with event creation, flushing, and context
+ * access.
+ *
+ * @example
+ * ```ts
+ * const rt = createRuntime();
+ * const ticks = rt.event<number>();
+ * const [count, setCount] = signal(0);
+ *
+ * ticks.subscribe((value) => {
+ *   setCount((current) => current + value);
+ * });
+ *
+ * effect(() => {
+ *   console.log(count());
+ * });
+ *
+ * ticks.emit(1);
+ * rt.flush();
+ * ```
+ *
+ * @remarks
+ * - Call this once during app startup or per test case to establish the active
+ *   runtime.
+ * - Creating a new runtime replaces the previously active default context.
+ * - `rt.flush()` is primarily for scheduled effects; signals and computed
+ *   reads stay current without it.
+ * - Event sources created by `rt.event()` share one dispatcher and preserve
+ *   FIFO delivery order.
+ */
+export function createRuntime(options?: RuntimeOptions): Runtime {
+  const { scheduler, dispatcher, executionContext } =
+    createRuntimeInfrastructure(options);
+  return {
+    ctx: executionContext,
+    batch: scheduler.batch,
+
+    event<T>() {
+      const source = createSource();
+
+      return {
+        subscribe(fn: (value: T) => void) {
+          return subscribeEvent(source, fn);
+        },
+        emit(value: T) {
+          dispatcher.emit(source, value);
+        },
+      };
+    },
+    flush: scheduler.flush,
+  };
+}