synstate 3.3.0 → 4.0.0

package/src/core/class/create-root-observable.mts

@@ -0,0 +1,107 @@
+// @sumi-expect-error-file classes/no-class
+// @sumi-expect-error-file banned-syntax/no-this
+// @sumi-expect-error-file functions/prefer-arrow-function
+// @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
+import { Arr, type Optional } from 'ts-data-forge';
+import type { ReadonlyRecord } from 'ts-type-forge';
+import type { RootObservable } from '../types/index.mjs';
+import { RootObservableClass } from './root-observable-class.mjs';
+
+/**
+ * The tools a custom root's `init` receives: the `protected` methods a
+ * subclass of `RootObservableClass` inherits.
+ */
+export type RootObservableTools<A> = Readonly<{
+  /** Emits `nextValue` and propagates the update to all descendants. */
+  startUpdate: (nextValue: A) => void;
+
+  getSnapshot: () => Optional<A>;
+
+  isCompleted: () => boolean;
+
+  /** Completes this observable (leaf teardown included). */
+  complete: () => void;
+
+  /**
+   * Registers a teardown (clear timers, abort requests, remove listeners, …)
+   * to run at the beginning of `complete()`, in the order registered. Called
+   * from `init`, it lets the teardown close over what `init` creates.
+   * Registered once the observable has completed — `init` may complete it
+   * synchronously first — the teardown runs at once.
+   */
+  onComplete: (teardown: () => void) => void;
+}>;
+
+export type RootObservableConfig<A> = Readonly<{
+  initialValue: Optional<A>;
+}>;
+
+/**
+ * Creates a root observable, for a custom creator written without a class
+ * of its own.
+ *
+ * `init` runs during construction, receives the tools, and returns extra
+ * public members to merge into the observable (e.g. `next` for a source,
+ * `start` for a timer). It may register asynchronous callbacks that use the
+ * tools, and may call `complete` synchronously.
+ */
+export const createRootObservable = <
+  A,
+  // The default is deliberately empty: a root without `init` adds no members.
+  // eslint-disable-next-line @typescript-eslint/no-generated-empty-object-type
+  Extension extends ReadonlyRecord<string, unknown> = ReadonlyRecord<
+    never,
+    never
+  >,
+>(
+  { initialValue }: RootObservableConfig<A>,
+  init: (tools: RootObservableTools<A>) => Extension,
+): Extension & RootObservable<A> =>
+  // The members `init` returned are assigned to the observable.
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+  new CustomRootObservableClass(initialValue, init) as unknown as Extension &
+    RootObservable<A>;
+
+/* implementation */
+
+class CustomRootObservableClass<A> extends RootObservableClass<A> {
+  #mut_teardowns: readonly (() => void)[] | undefined;
+
+  constructor(
+    initialValue: Optional<A>,
+    init: (tools: RootObservableTools<A>) => ReadonlyRecord<string, unknown>,
+  ) {
+    super({ initialValue });
+
+    this.#mut_teardowns = undefined;
+
+    const extension = init({
+      startUpdate: (nextValue) => {
+        this.startUpdate(nextValue);
+      },
+      getSnapshot: () => this.getSnapshot(),
+      isCompleted: () => this.isCompleted,
+      complete: () => {
+        this.complete();
+      },
+      onComplete: (teardown) => {
+        if (this.isCompleted) {
+          teardown();
+        } else {
+          this.#mut_teardowns = Arr.toPushed(
+            this.#mut_teardowns ?? [],
+            teardown,
+          );
+        }
+      },
+    });
+
+    Object.assign(this, extension);
+  }
+
+  protected override teardown(): void {
+    for (const teardown of this.#mut_teardowns ?? []) {
+      teardown();
+    }
+  }
+}

package/src/core/class/index.mts

@@ -0,0 +1,8 @@
+export * from './child-observable-class.mjs';
+export * from './create-child-observable.mjs';
+export * from './create-root-observable.mjs';
+export * from './manager-observable-class.mjs';
+export * from './observable-base-class.mjs';
+export * from './observable-node.mjs';
+export * from './propagation-state.mjs';
+export * from './root-observable-class.mjs';

package/src/core/class/manager-observable-class.mts

@@ -0,0 +1,166 @@
+// @sumi-expect-error-file classes/no-class
+// @sumi-expect-error-file banned-syntax/no-this
+// @sumi-expect-error-file functions/prefer-arrow-function
+// @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
+import type { Optional } from 'ts-data-forge';
+import type { MutableSet } from 'ts-type-forge';
+import type { ManagerObservableKind, UpdateToken } from '../types/index.mjs';
+import { issueUpdateToken } from '../utils/index.mjs';
+import { ObservableBaseClass } from './observable-base-class.mjs';
+import type { ChildNode, ManagerNode } from './observable-node.mjs';
+import { beginPropagation, endPropagation } from './propagation-state.mjs';
+
+/**
+ * The base of the observables that start updates of their own: a root, and
+ * an async child (`debounce`, `switchMap`), which emits later than its
+ * parents do. Every descendant registers to the managers it is reached from,
+ * and an update reaches them in ascending depth, so that each sees its
+ * parents' values of that update (no glitch).
+ */
+export class ManagerObservableClass<
+  A,
+  Kind extends ManagerObservableKind,
+  Depth extends number,
+> extends ObservableBaseClass<A, Kind, Depth> {
+  /**
+   * The descendants, by depth: the set at index `i` holds those at
+   * `depth + 1 + i`, in the order they registered. Depths below a live node
+   * never skip one (every live node has a live parent one level up), so the
+   * array has few holes; a hole is `undefined`, never a gap left for V8 to
+   * treat as a holey array.
+   *
+   * An update walks this array and its sets in place. Adding or removing a
+   * node is O(1) and there is no flat order to rebuild; only the first node
+   * of a depth replaces the array with a longer copy. A node deleted during
+   * the walk is skipped by the set's iterator; a node registered during it is
+   * also put in `#mut_joinedDuringUpdate` and skipped, so an update visits the
+   * nodes that existed when it began.
+   */
+  #mut_propagationOrder: readonly (MutableSet<ChildNode> | undefined)[];
+
+  /** Whether this node is propagating an update of its own. */
+  #mut_isPropagating: boolean;
+
+  /**
+   * The descendants that registered while this node propagated the update
+   * under way, which that update does not visit; made when the first one
+   * arrives. Kept on the manager rather than in a module, so that it also
+   * holds for a node another copy of synstate registered.
+   */
+  #mut_joinedDuringUpdate: MutableSet<ChildNode> | undefined;
+
+  /** The managers this node's descendants register to: itself. */
+  readonly managers: readonly ManagerNode[];
+
+  constructor(
+    config: Readonly<{
+      kind: Kind;
+      depth: Depth;
+      initialValue: Optional<A>;
+    }>,
+  ) {
+    super(config);
+
+    this.managers = [this];
+
+    this.#mut_propagationOrder = [];
+
+    this.#mut_isPropagating = false;
+
+    this.#mut_joinedDuringUpdate = undefined;
+  }
+
+  /**
+   * Runs `tryUpdate` on the descendants, shallowest first, skipping those
+   * registered after this update began.
+   */
+  #propagate(updateToken: UpdateToken): void {
+    for (const bucket of this.#mut_propagationOrder) {
+      if (bucket !== undefined) {
+        for (const c of bucket) {
+          // Read for each node, since the set is made when the first joins.
+          if (this.#mut_joinedDuringUpdate?.has(c) !== true) {
+            c.tryUpdate(updateToken);
+          }
+        }
+      }
+    }
+  }
+
+  addDescendant(child: ChildNode): void {
+    const descendants = this.#mut_propagationOrder;
+
+    const index = child.depth - this.depth - 1;
+
+    const mut_bucket = descendants[index];
+
+    if (mut_bucket === undefined) {
+      // The first node of its depth: rare, so the array is copied rather than
+      // written, which also leaves a walk already under way on the old one.
+      this.#mut_propagationOrder = Array.from(
+        { length: Math.max(descendants.length, index + 1) },
+        (_, i) => (i === index ? new Set([child]) : descendants[i]),
+      );
+    } else {
+      mut_bucket.add(child);
+    }
+
+    if (!this.#mut_isPropagating) {
+      return;
+    }
+
+    this.#mut_joinedDuringUpdate ??= new Set();
+
+    this.#mut_joinedDuringUpdate.add(child);
+  }
+
+  deleteDescendant(child: ChildNode): void {
+    // An emptied set stays, to be reused by the next node of its depth.
+    this.#mut_propagationOrder[child.depth - this.depth - 1]?.delete(child);
+  }
+
+  /** Emits `nextValue` and propagates it to the descendants. */
+  protected startUpdate(nextValue: A): void {
+    const updateToken = issueUpdateToken();
+
+    // A write to this same manager from inside its own update starts an inner
+    // one; what joins during it joined during the outer one too.
+    const wasPropagating = this.#mut_isPropagating;
+
+    const joinedBefore = this.#mut_joinedDuringUpdate;
+
+    this.#mut_isPropagating = true;
+
+    this.#mut_joinedDuringUpdate = undefined;
+
+    beginPropagation(updateToken);
+
+    // A subscriber or projection may throw, and the depth has to come back
+    // down regardless, or every later write would warn. The exception itself
+    // is not caught: it reaches the caller of `next` as it always has.
+    // @sumi-expect-error exceptions/no-try
+    try {
+      this.setNext(nextValue, updateToken);
+
+      this.#propagate(updateToken);
+    } finally {
+      // Widened: TypeScript would take the write above for the value.
+      const joinedNow = this.#mut_joinedDuringUpdate as
+        MutableSet<ChildNode> | undefined;
+
+      this.#mut_isPropagating = wasPropagating;
+
+      this.#mut_joinedDuringUpdate = joinedBefore;
+
+      if (wasPropagating && joinedNow !== undefined) {
+        this.#mut_joinedDuringUpdate ??= new Set();
+
+        for (const c of joinedNow) {
+          this.#mut_joinedDuringUpdate.add(c);
+        }
+      }
+
+      endPropagation();
+    }
+  }
+}

package/src/core/class/observable-base-class.mts

@@ -0,0 +1,315 @@
+// Sumi bans classes, `this`, method syntax and writes to `this` outside a
+// `mut_` binding. The observables are classes (why is on
+// `ObservableBaseClass` below), so those four rules are waived here (D-63).
+// @sumi-expect-error-file classes/no-class
+// @sumi-expect-error-file banned-syntax/no-this
+// @sumi-expect-error-file functions/prefer-arrow-function
+// @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
+import { Optional } from 'ts-data-forge';
+import { unreachable } from 'ts-std-forge';
+import type { MutableSet } from 'ts-type-forge';
+import type {
+  DropInitialValueOperator,
+  InitializedObservable,
+  KeepInitialValueOperator,
+  Observable,
+  ObservableBase,
+  ObservableKind,
+  Operator,
+  Subscriber,
+  Subscription,
+  UpdateToken,
+  WithInitialValueOperator,
+} from '../types/index.mjs';
+import {
+  getCurrentScopeInternals,
+  notUpdatedYet,
+  observableBrand,
+  toSubscriber,
+  type ScopeInternals,
+} from '../utils/index.mjs';
+import type { ChildNode } from './observable-node.mjs';
+
+/**
+ * The base of every observable, and the reason an observable is a class.
+ *
+ * A node is created for every derived value of a UI, so creating one has to
+ * be cheap, and most of its cost was its methods: each observable used to be
+ * a set of closures made for it, a dozen or more per node (#2421). Sharing
+ * the methods among all nodes removes that cost, and a shared method has to
+ * read the node it is called on from `this`. Once `this` is unavoidable, a
+ * class is the plainest way to say it: the methods live once on the
+ * prototype, `this` is typed, a creator or operator is a subclass that
+ * overrides `tryUpdate` (and `flush` / `teardown` where it holds something),
+ * and assigning every field in the constructor gives the nodes of one class
+ * one shape for V8. The collections (`children`, subscribers) are made when
+ * the first one arrives.
+ *
+ * The methods read the observable they are called on, so taking one off it
+ * (`const { subscribe } = obs$`) is not supported.
+ *
+ * A node reaches another node only through its methods and its public
+ * fields, never through a `#private` one: the other node may be an instance
+ * of another copy of synstate in the same program, whose classes are not
+ * these.
+ */
+export class ObservableBaseClass<
+  A,
+  Kind extends ObservableKind,
+  Depth extends number,
+> implements ObservableBase<A> {
+  #mut_snapshot: Optional<A>;
+  #mut_isCompleted: boolean;
+  #mut_updateToken: UpdateToken;
+  #mut_children: MutableSet<ChildNode> | undefined;
+  #mut_subscribers: MutableSet<Subscriber<A>> | undefined;
+  #mut_scope: ScopeInternals | undefined;
+  readonly kind: Kind;
+  readonly depth: Depth;
+  declare readonly [observableBrand]: true;
+
+  constructor({
+    kind,
+    depth,
+    initialValue,
+  }: Readonly<{
+    kind: Kind;
+    depth: Depth;
+    initialValue: Optional<A>;
+  }>) {
+    this.kind = kind;
+
+    this.depth = depth;
+
+    this.#mut_snapshot = initialValue;
+
+    this.#mut_isCompleted = false;
+
+    this.#mut_updateToken = notUpdatedYet;
+
+    this.#mut_children = undefined;
+
+    this.#mut_subscribers = undefined;
+
+    this.#mut_scope = undefined;
+
+    this[observableBrand] = true;
+  }
+
+  getSnapshot(): Optional<A> {
+    return this.#mut_snapshot;
+  }
+
+  get isCompleted(): boolean {
+    return this.#mut_isCompleted;
+  }
+
+  get updateToken(): UpdateToken {
+    return this.#mut_updateToken;
+  }
+
+  get hasSubscriber(): boolean {
+    return (
+      this.#mut_subscribers !== undefined && this.#mut_subscribers.size > 0
+    );
+  }
+
+  get hasChild(): boolean {
+    return this.#mut_children !== undefined && this.#mut_children.size > 0;
+  }
+
+  hasActiveChild(): boolean {
+    if (this.#mut_children !== undefined) {
+      for (const c of this.#mut_children) {
+        if (!c.isCompleted) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  addChild(child: ChildNode): void {
+    // A set, not an array: a completed child removes itself, and that has to
+    // be O(1) for a UI that creates and completes derived nodes on every mount.
+    if (this.#mut_children === undefined) {
+      this.#mut_children = new Set([child]);
+    } else {
+      this.#mut_children.add(child);
+    }
+  }
+
+  deleteChild(child: ChildNode): void {
+    this.#mut_children?.delete(child);
+  }
+
+  /** Stores `nextValue` as the current value and notifies subscribers. */
+  protected setNext(nextValue: A, updateToken: UpdateToken): void {
+    this.#mut_updateToken = updateToken;
+
+    this.#mut_snapshot = Optional.some(nextValue);
+
+    if (this.#mut_subscribers !== undefined) {
+      for (const s of this.#mut_subscribers) {
+        s.onNext(nextValue);
+      }
+    }
+  }
+
+  /**
+   * Called with the token of every update that reaches this observable; a
+   * parent that did not emit in that update has a different `updateToken`.
+   * Every observable that can receive a parent update overrides it, and an
+   * observable with no parents never gets one, so reaching this is the
+   * invariant breaking (Sumi D-48).
+   */
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+  tryUpdate(_updateToken: UpdateToken): void {
+    unreachable();
+  }
+
+  /**
+   * Called by a parent that has completed. A root has no parents, and a child
+   * completing never completes it (#2133), so only its own `complete()` ends
+   * it.
+   */
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+  tryComplete(): void {}
+
+  /**
+   * Completes the observable: an async child first passes on what it still
+   * holds (`flush`), then it is disposed. Completing never reaches the
+   * parents: an upstream observable may be shared, and only whoever owns it
+   * decides when it ends (#2133).
+   */
+  complete(): void {
+    if (this.#mut_isCompleted) {
+      return;
+    }
+
+    this.flush();
+
+    this.dispose();
+  }
+
+  /**
+   * Completes the observable without passing on anything it still holds,
+   * runs its teardown, and takes it out of the graph.
+   */
+  dispose(): void {
+    // A completed node is reached again through every parent that completes
+    // after it; running again would repeat the teardown and the unregistering.
+    if (this.#mut_isCompleted) {
+      return;
+    }
+
+    this.teardown();
+
+    this.#mut_isCompleted = true;
+
+    if (this.#mut_scope !== undefined) {
+      this.#mut_scope.release();
+
+      this.#mut_scope = undefined;
+    }
+
+    if (this.#mut_subscribers !== undefined) {
+      for (const s of this.#mut_subscribers) {
+        s.onComplete();
+      }
+
+      this.#mut_subscribers.clear();
+    }
+
+    // A child that completes removes itself from `children` during this loop,
+    // which iterating a `Set` tolerates.
+    if (this.#mut_children !== undefined) {
+      for (const c of this.#mut_children) {
+        c.tryComplete();
+      }
+    }
+
+    this.detach();
+  }
+
+  /**
+   * Passes on what the observable still holds, at the beginning of
+   * `complete()` and never in `dispose()` (`debounce`'s pending value).
+   */
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+  protected flush(): void {}
+
+  /**
+   * Releases what the observable holds (timers, subscriptions, inner
+   * observables), once, when it completes or is disposed, before its
+   * subscribers hear of it.
+   */
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+  protected teardown(): void {}
+
+  /** Takes a completed child out of its parents' and managers' lists. */
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+  protected detach(): void {}
+
+  /**
+   * Joins the scope whose `run` is executing (`createScope`), if any. A node
+   * that completed while it was built (`just`, a child of completed parents)
+   * has nothing left to release.
+   */
+  protected adoptIntoCurrentScope(): void {
+    const scope = getCurrentScopeInternals();
+
+    if (scope === undefined || this.#mut_isCompleted) {
+      return;
+    }
+
+    scope.adopt(this);
+
+    this.#mut_scope = scope;
+  }
+
+  // A `WithInitialValueOperator` is also an `Operator`: nothing at run time
+  // tells the operators apart, and the overloads only refine the return type
+  // (#1952).
+  pipe<B>(operator: WithInitialValueOperator<A, B>): InitializedObservable<B>;
+
+  pipe<B>(
+    operator: DropInitialValueOperator<A, B> | KeepInitialValueOperator<A, B>,
+  ): Observable<B>;
+
+  pipe<B>(operator: Operator<A, B>): Observable<B> {
+    return operator(
+      // The node is the observable; the public types are only a view of it.
+      // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+      this as unknown as InitializedObservable<A>,
+    );
+  }
+
+  subscribe(onNext: (v: A) => void, onComplete?: () => void): Subscription {
+    // first emit
+    if (Optional.isSome(this.#mut_snapshot)) {
+      onNext(this.#mut_snapshot.value);
+    }
+
+    if (this.#mut_isCompleted) {
+      onComplete?.();
+
+      return noopSubscription;
+    }
+
+    const subscriber = toSubscriber(onNext, onComplete);
+
+    this.#mut_subscribers ??= new Set();
+
+    this.#mut_subscribers.add(subscriber);
+
+    return {
+      unsubscribe: () => {
+        this.#mut_subscribers?.delete(subscriber);
+      },
+    };
+  }
+}
+
+const noopSubscription: Subscription = { unsubscribe: () => {} } as const;

package/src/core/{base → class}/observable-base.test.mts

@@ -10,8 +10,8 @@ import type {
 import {
   createAsyncChildObservable,
   createSyncChildObservable,
+  createTryUpdateNotImplemented,
 } from './create-child-observable.mjs';
-import { createTryUpdateNotImplemented } from './create-observable-base.mjs';
 import { createRootObservable } from './create-root-observable.mjs';
 
 /**

package/src/core/class/observable-node.mts

@@ -0,0 +1,54 @@
+import type {
+  Observable,
+  ObservableBase,
+  UpdateToken,
+} from '../types/index.mjs';
+
+/**
+ * The members the nodes of the graph call on one another, which the public
+ * types leave out (#2117). Every observable is an instance of
+ * `ObservableBaseClass` — of this copy of synstate or of another — and has
+ * them.
+ */
+type NodeInternals = Readonly<{
+  hasSubscriber: boolean;
+  hasChild: boolean;
+  hasActiveChild: () => boolean;
+  tryUpdate: (updateToken: UpdateToken) => void;
+  tryComplete: () => void;
+  addChild: (child: ChildNode) => void;
+  deleteChild: (child: ChildNode) => void;
+
+  /**
+   * The managers this node's own descendants register to: itself for a
+   * manager, its parents' for a sync child, shared with its parent when it
+   * has one. Cached so that creating a child does not walk its ancestors.
+   */
+  managers: readonly ManagerNode[];
+}>;
+
+/** An observable, as the other nodes of the graph see it. */
+export type ObservableNode<A = unknown> = NodeInternals & Observable<A>;
+
+export type ChildNode = NodeInternals &
+  ObservableBase<unknown> &
+  Readonly<{
+    parents: readonly Observable<unknown>[];
+  }>;
+
+export type ManagerNode = NodeInternals &
+  ObservableBase<unknown> &
+  Readonly<{
+    addDescendant: (child: ChildNode) => void;
+    deleteDescendant: (child: ChildNode) => void;
+  }>;
+
+/**
+ * The one place a public observable is seen as the node it is. Every
+ * observable is built by a synstate class, and the public types carry a
+ * brand an object literal cannot supply, so this holds for every value of
+ * those types.
+ */
+export const toNode = <A,>(observable: Observable<A>): ObservableNode<A> =>
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+  observable as ObservableNode<A>;