synstate 3.3.0 → 4.0.0

package/src/core/scope/scope.mts

@@ -0,0 +1,260 @@
+// Sumi bans classes, `this`, method syntax and writes to `this` outside a
+// `mut_` binding. A scope is a class for the reason the observables are (see
+// `ScopeClass` 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 type { Scope } from '../types/index.mjs';
+import {
+  getCurrentScopeInternals,
+  runWithScope,
+  type ScopeInternals,
+  type ScopeMember,
+} from '../utils/index.mjs';
+
+/**
+ * Creates a {@link Scope}. Observables created synchronously inside
+ * `scope.run(body)` belong to it, and `scope.dispose()` disposes them without
+ * completing the shared observables they were derived from.
+ *
+ * With `parent`, the new scope is disposed together with it; without one it
+ * stands alone and lives until its own `dispose()`. A parent that is already
+ * disposed gives a scope that is born disposed, with a warning.
+ *
+ * Intended for authors of libraries built on synstate rather than for
+ * application code; state defined at module level belongs to no scope and
+ * lives as long as the page.
+ *
+ * `run` and `dispose` read the scope they are called on, so call them on it
+ * (`scope.dispose()`) rather than taking them off it.
+ *
+ * @param parent - The scope whose disposal also disposes the new one
+ * @returns The new scope
+ */
+export const createScope = (parent?: Scope): Scope =>
+  new ScopeClass(parent instanceof ScopeClass ? parent : undefined);
+
+/**
+ * Returns the scope whose `run` is executing, or `undefined` outside every
+ * `run` and inside {@link untracked}.
+ *
+ * To put work that runs later (after an `await`, in a callback) into the
+ * current scope, take it here while still synchronous and wrap the later work
+ * in its `run`.
+ *
+ * @returns The current scope, if any
+ */
+export const getCurrentScope = (): Scope | undefined =>
+  getCurrentScopeInternals();
+
+/**
+ * Registers `cleanup` to be called when the current scope is disposed. Cleanups
+ * run after the child scopes are disposed and before the owned observables
+ * are, newest first.
+ *
+ * Outside every scope it warns and registers nothing.
+ *
+ * @param cleanup - The function to call
+ */
+export const onScopeDispose = (cleanup: () => void): void => {
+  const current = getCurrentScopeInternals();
+
+  if (current === undefined) {
+    console.warn(
+      'synstate: onScopeDispose() was called outside any scope; the cleanup will never run.',
+    );
+
+    return;
+  }
+
+  current.addCleanup(cleanup);
+};
+
+/**
+ * Calls `body` with no current scope and returns what it returns, so that the
+ * observables it creates belong to no scope and outlive the surrounding one.
+ *
+ * @param body - The function to call
+ * @returns What `body` returns
+ */
+export const untracked = <R,>(body: () => R): R =>
+  runWithScope(undefined, body);
+
+/**
+ * A scope is created for every row and branch of a UI, so creating one has to
+ * be cheap. It used to be a set of closures with a `Set` of children, a `Set`
+ * of owned observables and a record in a `WeakMap`; it is now one object whose
+ * methods live on the prototype and whose lists are arrays made when the
+ * first entry arrives.
+ *
+ * Whatever leaves a list on its own (a child scope disposed by itself, an
+ * observable that completed) is not looked up and spliced out: it only counts
+ * itself gone, and once at least half of a list is gone the list is rebuilt
+ * from what is left. Disposal walks the lists newest first, as before.
+ *
+ * The class itself is not exported; `createScope` is the way to make one.
+ */
+class ScopeClass implements ScopeInternals {
+  readonly #parent: ScopeClass | undefined;
+  // Pushed to in place: a scope gains children, cleanups and nodes one at a
+  // time, and copying the list for each would make a big scope quadratic.
+  // @sumi-expect-error readonly/require-readonly-type
+  #mut_children: ScopeClass[] | undefined;
+  #mut_goneChildren: number;
+  // @sumi-expect-error readonly/require-readonly-type
+  #mut_cleanups: (() => void)[] | undefined;
+  // @sumi-expect-error readonly/require-readonly-type
+  #mut_nodes: ScopeMember[] | undefined;
+  #mut_goneNodes: number;
+  #mut_isDisposed: boolean;
+
+  constructor(parent: ScopeClass | undefined) {
+    this.#parent = parent;
+
+    this.#mut_children = undefined;
+
+    this.#mut_goneChildren = 0;
+
+    this.#mut_cleanups = undefined;
+
+    this.#mut_nodes = undefined;
+
+    this.#mut_goneNodes = 0;
+
+    this.#mut_isDisposed = false;
+
+    if (parent !== undefined) {
+      if (parent.#mut_isDisposed) {
+        console.warn(
+          'synstate: createScope() was given a disposed parent; the new scope is born disposed.',
+        );
+
+        this.#mut_isDisposed = true;
+      } else if (parent.#mut_children === undefined) {
+        parent.#mut_children = [this];
+      } else {
+        parent.#mut_children.push(this);
+      }
+    }
+  }
+
+  /** Called by a child scope that was disposed on its own. */
+  #childGone(): void {
+    const children = this.#mut_children;
+
+    if (children === undefined) {
+      return;
+    }
+
+    this.#mut_goneChildren += 1;
+
+    if (!isMostlyGone(this.#mut_goneChildren, children.length)) {
+      return;
+    }
+
+    this.#mut_children = children.filter((c) => !c.#mut_isDisposed);
+
+    this.#mut_goneChildren = 0;
+  }
+
+  run<R>(body: () => R): R {
+    if (this.#mut_isDisposed) {
+      console.warn(
+        'synstate: run() was called on a disposed scope; what it creates belongs to no scope.',
+      );
+
+      return runWithScope(undefined, body);
+    }
+
+    return runWithScope(this, body);
+  }
+
+  dispose(): void {
+    if (this.#mut_isDisposed) {
+      return;
+    }
+
+    // Set first: the children, cleanups and nodes below call back into this
+    // scope (`childGone`, `release`), which has nothing to do once it is
+    // disposing everything anyway.
+    this.#mut_isDisposed = true;
+
+    const children = this.#mut_children;
+
+    if (children !== undefined) {
+      this.#mut_children = undefined;
+
+      for (let mut_i = children.length - 1; mut_i >= 0; mut_i -= 1) {
+        children[mut_i]?.dispose();
+      }
+    }
+
+    const cleanups = this.#mut_cleanups;
+
+    if (cleanups !== undefined) {
+      this.#mut_cleanups = undefined;
+
+      for (let mut_i = cleanups.length - 1; mut_i >= 0; mut_i -= 1) {
+        cleanups[mut_i]?.();
+      }
+    }
+
+    const nodes = this.#mut_nodes;
+
+    if (nodes !== undefined) {
+      this.#mut_nodes = undefined;
+
+      for (let mut_i = nodes.length - 1; mut_i >= 0; mut_i -= 1) {
+        nodes[mut_i]?.dispose();
+      }
+    }
+
+    if (this.#parent !== undefined) {
+      this.#parent.#childGone();
+    }
+  }
+
+  adopt(node: ScopeMember): void {
+    if (this.#mut_nodes === undefined) {
+      this.#mut_nodes = [node];
+    } else {
+      this.#mut_nodes.push(node);
+    }
+  }
+
+  release(): void {
+    const nodes = this.#mut_nodes;
+
+    if (nodes === undefined) {
+      return;
+    }
+
+    this.#mut_goneNodes += 1;
+
+    if (!isMostlyGone(this.#mut_goneNodes, nodes.length)) {
+      return;
+    }
+
+    this.#mut_nodes = nodes.filter((n) => !n.isCompleted);
+
+    this.#mut_goneNodes = 0;
+  }
+
+  addCleanup(cleanup: () => void): void {
+    if (this.#mut_cleanups === undefined) {
+      this.#mut_cleanups = [cleanup];
+    } else {
+      this.#mut_cleanups.push(cleanup);
+    }
+  }
+}
+
+/**
+ * Whether a list is worth rebuilding: at least half of it is gone, and enough
+ * of it that the rebuild is paid for by the entries it drops.
+ */
+const isMostlyGone = (gone: number, length: number): boolean =>
+  gone >= minGoneToCompact && gone * 2 >= length;
+
+const minGoneToCompact = 16;

package/src/core/scope/scope.test.mts

@@ -0,0 +1,462 @@
+// cspell:ignore unstub
+import { expectType } from 'ts-data-forge';
+import type { Mock } from 'vitest';
+import { toNode } from '../class/index.mjs';
+import { source } from '../create/index.mjs';
+import { map } from '../operators/index.mjs';
+import type { Scope } from '../types/index.mjs';
+import {
+  createScope,
+  getCurrentScope,
+  onScopeDispose,
+  untracked,
+} from './scope.mjs';
+
+describe(createScope, () => {
+  test('types', () => {
+    expectType<ReturnType<typeof createScope>, Scope>('=');
+
+    expectType<ReturnType<typeof getCurrentScope>, Scope | undefined>('=');
+
+    expectType<ReturnType<typeof untracked<number>>, number>('=');
+  });
+
+  test('run returns what fn returns and makes the scope current only while it runs', () => {
+    const scope = createScope();
+
+    assert.isUndefined(getCurrentScope());
+
+    const result = scope.run(() => {
+      assert.strictEqual(getCurrentScope(), scope);
+
+      return 42;
+    });
+
+    assert.strictEqual(result, 42);
+
+    assert.isUndefined(getCurrentScope());
+  });
+
+  test('the outer scope is current again after a nested run, and after fn throws', () => {
+    const outer = createScope();
+
+    const inner = createScope(outer);
+
+    outer.run(() => {
+      inner.run(() => {
+        assert.strictEqual(getCurrentScope(), inner);
+      });
+
+      assert.strictEqual(getCurrentScope(), outer);
+
+      assert.throws(() => {
+        // throws a SyntaxError
+        inner.run(() => JSON.parse('{'));
+      }, SyntaxError);
+
+      assert.strictEqual(getCurrentScope(), outer);
+    });
+
+    assert.isUndefined(getCurrentScope());
+  });
+
+  test('an observable created inside run is disposed with the scope; a shared parent outside it is not', () => {
+    const store$ = source<number>();
+
+    const scope = createScope();
+
+    const doubled$ = scope.run(() => store$.pipe(map((x) => x * 2)));
+
+    const mut_history: number[] = [];
+
+    doubled$.subscribe((x) => {
+      mut_history.push(x);
+    });
+
+    store$.next(1);
+
+    assert.deepStrictEqual(mut_history, [2]);
+
+    scope.dispose();
+
+    assert.isTrue(doubled$.isCompleted);
+
+    assert.isFalse(store$.isCompleted);
+
+    assert.isFalse(toNode(store$).hasChild);
+
+    store$.next(2);
+
+    assert.deepStrictEqual(mut_history, [2]);
+  });
+
+  test('an observable created outside any scope belongs to nothing', () => {
+    const store$ = source<number>();
+
+    const doubled$ = store$.pipe(map((x) => x * 2));
+
+    const scope = createScope();
+
+    scope.run(() => {
+      // a derived node created elsewhere is not adopted by being used here
+      doubled$.subscribe(() => {});
+    });
+
+    scope.dispose();
+
+    assert.isFalse(doubled$.isCompleted);
+  });
+
+  test('nodes go to the innermost scope', () => {
+    const store$ = source<number>();
+
+    const outer = createScope();
+
+    const inner = createScope(outer);
+
+    const [a$, b$] = outer.run(() => {
+      const a = store$.pipe(map((x) => x + 1));
+
+      const b = inner.run(() => store$.pipe(map((x) => x + 2)));
+
+      return [a, b] as const;
+    });
+
+    inner.dispose();
+
+    assert.isFalse(a$.isCompleted);
+
+    assert.isTrue(b$.isCompleted);
+
+    outer.dispose();
+
+    assert.isTrue(a$.isCompleted);
+  });
+
+  test('dispose runs child scopes, then cleanups in reverse, then owned nodes in reverse creation order', () => {
+    const store$ = source<number>();
+
+    const parent = createScope();
+
+    const child1 = createScope(parent);
+
+    const child2 = createScope(parent);
+
+    const mut_order: string[] = [];
+
+    child1.run(() => {
+      onScopeDispose(() => {
+        mut_order.push('child1');
+      });
+    });
+
+    child2.run(() => {
+      onScopeDispose(() => {
+        mut_order.push('child2');
+      });
+    });
+
+    parent.run(() => {
+      const first$ = store$.pipe(map((x) => x));
+
+      first$.subscribe(
+        () => {},
+        () => {
+          mut_order.push('node first');
+        },
+      );
+
+      onScopeDispose(() => {
+        mut_order.push('cleanup 1');
+      });
+
+      const second$ = store$.pipe(map((x) => x));
+
+      second$.subscribe(
+        () => {},
+        () => {
+          mut_order.push('node second');
+        },
+      );
+
+      onScopeDispose(() => {
+        mut_order.push('cleanup 2');
+      });
+    });
+
+    parent.dispose();
+
+    assert.deepStrictEqual(mut_order, [
+      'child2',
+      'child1',
+      'cleanup 2',
+      'cleanup 1',
+      'node second',
+      'node first',
+    ]);
+  });
+
+  test('dispose is idempotent', () => {
+    const scope = createScope();
+
+    const mut_calls: number[] = [];
+
+    scope.run(() => {
+      onScopeDispose(() => {
+        mut_calls.push(1);
+      });
+    });
+
+    scope.dispose();
+
+    scope.dispose();
+
+    assert.deepStrictEqual(mut_calls, [1]);
+  });
+
+  test('a disposed child scope leaves its parent, so the parent does not dispose it again', () => {
+    const parent = createScope();
+
+    const child = createScope(parent);
+
+    const mut_calls: string[] = [];
+
+    child.run(() => {
+      onScopeDispose(() => {
+        mut_calls.push('child');
+      });
+    });
+
+    child.dispose();
+
+    parent.dispose();
+
+    assert.deepStrictEqual(mut_calls, ['child']);
+  });
+
+  test('a node that completes on its own is released by its scope', () => {
+    const store$ = source<number>();
+
+    const scope = createScope();
+
+    const mut_completions: number[] = [];
+
+    const doubled$ = scope.run(() => store$.pipe(map((x) => x * 2)));
+
+    doubled$.subscribe(
+      () => {},
+      () => {
+        mut_completions.push(1);
+      },
+    );
+
+    doubled$.complete();
+
+    scope.dispose();
+
+    assert.deepStrictEqual(mut_completions, [1]);
+  });
+
+  test('after many child scopes are disposed on their own, the parent disposes the rest once, newest first', () => {
+    const parent = createScope();
+
+    const mut_order: number[] = [];
+
+    const children = Array.from({ length: 100 }, (_, i) => {
+      const child = createScope(parent);
+
+      child.run(() => {
+        onScopeDispose(() => {
+          mut_order.push(i);
+        });
+      });
+
+      return child;
+    });
+
+    // Every child whose index is not a multiple of 3 goes on its own: 66 of
+    // them, enough for the parent to rebuild its list of children.
+    for (const [i, child] of children.entries()) {
+      if (i % 3 !== 0) {
+        child.dispose();
+      }
+    }
+
+    const disposedAlone = mut_order.length;
+
+    parent.dispose();
+
+    assert.strictEqual(disposedAlone, 66);
+
+    assert.deepStrictEqual(
+      mut_order.slice(disposedAlone),
+      Array.from({ length: 34 }, (_, k) => (33 - k) * 3),
+    );
+  });
+
+  test('after many owned nodes complete on their own, the scope disposes the rest once, newest first', () => {
+    const store$ = source<number>();
+
+    const scope = createScope();
+
+    const mut_completions: number[] = [];
+
+    const nodes = scope.run(() =>
+      Array.from({ length: 100 }, (_, i) => {
+        const node$ = store$.pipe(map((x) => x + i));
+
+        node$.subscribe(
+          () => {},
+          () => {
+            mut_completions.push(i);
+          },
+        );
+
+        return node$;
+      }),
+    );
+
+    for (const [i, node$] of nodes.entries()) {
+      if (i % 3 !== 0) {
+        node$.complete();
+      }
+    }
+
+    const completedAlone = mut_completions.length;
+
+    scope.dispose();
+
+    assert.strictEqual(completedAlone, 66);
+
+    assert.deepStrictEqual(
+      mut_completions.slice(completedAlone),
+      Array.from({ length: 34 }, (_, k) => (33 - k) * 3),
+    );
+  });
+
+  test('nodes created inside untracked belong to no scope', () => {
+    const store$ = source<number>();
+
+    const scope = createScope();
+
+    const [owned$, free$] = scope.run(() => {
+      const owned = store$.pipe(map((x) => x));
+
+      const free = untracked(() => {
+        assert.isUndefined(getCurrentScope());
+
+        return store$.pipe(map((x) => x));
+      });
+
+      assert.strictEqual(getCurrentScope(), scope);
+
+      return [owned, free] as const;
+    });
+
+    scope.dispose();
+
+    assert.isTrue(owned$.isCompleted);
+
+    assert.isFalse(free$.isCompleted);
+  });
+
+  test('a node created after await belongs to no scope', async () => {
+    const store$ = source<number>();
+
+    const scope = createScope();
+
+    const promise = scope.run(async () => {
+      await Promise.resolve();
+
+      assert.isUndefined(getCurrentScope());
+
+      return store$.pipe(map((x) => x));
+    });
+
+    const late$ = await promise;
+
+    scope.dispose();
+
+    assert.isFalse(late$.isCompleted);
+  });
+
+  test('run on a disposed scope warns, still runs fn, and owns nothing it creates', () => {
+    const warn = stubConsoleWarn();
+
+    const store$ = source<number>();
+
+    const scope = createScope();
+
+    scope.dispose();
+
+    const free$ = scope.run(() => {
+      assert.isUndefined(getCurrentScope());
+
+      return store$.pipe(map((x) => x));
+    });
+
+    assert.isFalse(free$.isCompleted);
+
+    expect(warn).toHaveBeenCalledExactlyOnceWith(
+      expect.stringContaining('disposed scope'),
+    );
+
+    vi.unstubAllGlobals();
+  });
+
+  test('onScopeDispose outside any scope warns and registers nothing', () => {
+    const warn = stubConsoleWarn();
+
+    onScopeDispose(() => {});
+
+    expect(warn).toHaveBeenCalledExactlyOnceWith(
+      expect.stringContaining('outside any scope'),
+    );
+
+    vi.unstubAllGlobals();
+  });
+
+  test('a scope created under a disposed parent is born disposed', () => {
+    const warn = stubConsoleWarn();
+
+    const parent = createScope();
+
+    parent.dispose();
+
+    const child = createScope(parent);
+
+    expect(warn).toHaveBeenCalledExactlyOnceWith(
+      expect.stringContaining('disposed parent'),
+    );
+
+    child.run(() => {
+      assert.isUndefined(getCurrentScope());
+    });
+
+    expect(warn).toHaveBeenCalledTimes(2);
+
+    vi.unstubAllGlobals();
+  });
+
+  test('disposing a parent disposes nodes of its child scopes', () => {
+    const store$ = source<number>();
+
+    const parent = createScope();
+
+    const child = createScope(parent);
+
+    const owned$ = child.run(() => store$.pipe(map((x) => x)));
+
+    parent.dispose();
+
+    assert.isTrue(owned$.isCompleted);
+  });
+});
+
+const stubConsoleWarn = (): Mock => {
+  const warn = vi.fn();
+
+  vi.stubGlobal('console', { ...console, warn });
+
+  return warn;
+};

package/src/core/types/id.mts

@@ -1,7 +1,3 @@
 import type { Brand } from 'ts-type-forge';
 
-export type ObservableId = Brand<symbol, 'observable-id'>;
-
-export type SubscriberId = Brand<symbol, 'subscriber-id'>;
-
 export type UpdateToken = Brand<symbol, 'update-token'>;