synstate 3.4.0 → 4.0.0

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'>;

package/src/core/types/index.mts

@@ -2,5 +2,6 @@ export * from './id.mjs';
 export * from './observable-family.mjs';
 export * from './observable-kind.mjs';
 export * from './observable.mjs';
+export * from './scope.mjs';
 export * from './timer.mjs';
 export * from './types.mjs';

package/src/core/types/observable-family.mts

@@ -210,6 +210,8 @@ export type PairwiseOperatorObservable<A> = SyncChildObservable<
   readonly [A]
 >;
 
+export type TakeOperatorObservable<A> = SyncChildObservable<A, readonly [A]>;
+
 export type TakeWhileOperatorObservable<A> = SyncChildObservable<
   A,
   readonly [A]

package/src/core/types/observable.mts

@@ -1,6 +1,13 @@
-import { expectType, type Optional, type Some } from 'ts-data-forge';
+import {
+  expectType,
+  hasKey,
+  isRecord,
+  type Optional,
+  type Some,
+} from 'ts-data-forge';
 import type { FixedLengthTuple, StrictOmit } from 'ts-type-forge';
-import type { ObservableId, UpdateToken } from './id.mjs';
+import { observableBrand } from '../utils/index.mjs';
+import type { UpdateToken } from './id.mjs';
 import type { ObservableKind } from './observable-kind.mjs';
 import type { NonEmptyUnknownList, Subscription } from './types.mjs';
 
@@ -19,42 +26,37 @@ import type { NonEmptyUnknownList, Subscription } from './types.mjs';
  */
 
 type CreateObservableType<A, Kind extends ObservableKind> = Readonly<{
-  id: ObservableId;
+  [observableBrand]: true;
+
   kind: Kind;
 
-  // reactive dependency tree structure
+  /**
+   * One more than the deepest observable this one is derived from; 0 for a
+   * root. An update reaches observables in ascending depth, so every parent
+   * has emitted before its child reads it.
+   */
   depth: Kind extends 'root' ? 0 : number;
-  addChild: <B>(child: ChildObservable<B>) => void;
-  deleteChild: <B>(child: ChildObservable<B>) => void;
 
-  // state
   getSnapshot: () => Optional<A>;
   isCompleted: boolean;
-  updateToken: UpdateToken;
-  hasSubscriber: boolean;
-  hasChild: boolean;
-  hasActiveChild: () => boolean;
 
   /**
-   * Whether this observable completes itself once nothing uses it any more —
-   * once it has neither subscribers nor live children when one of its children
-   * completes. True when completing it would release something: it has a
-   * teardown of its own (a timer, an inner subscription) or a parent with
-   * `autoComplete`. A `source` or `createState` and everything derived from
-   * it alone are never completed this way, so completing a derived observable
-   * cannot end a state that something else may still read (#2133).
+   * The token of the update in which this observable last emitted. A child's
+   * `tryUpdate` receives the token of the update now propagating; a parent
+   * whose token differs did not emit in it. The token is opaque: compare it,
+   * store it, or pass it on to `setNext`.
    */
-  autoComplete: boolean;
+  updateToken: UpdateToken;
 
-  tryUpdate: (updateToken: UpdateToken) => void;
-  tryComplete: () => void;
   complete: () => void;
 
   /**
-   * Completes this observable and takes it out of the graph, without telling
-   * its parents: unlike `complete()`, it never completes an upstream
-   * observable, whatever its `autoComplete`. Its descendants are completed as
-   * by `complete()` once none of their parents is live.
+   * Completes this observable and takes it out of the graph, for whoever owns
+   * it (a scope) to release it. Neither this nor `complete()` reaches upstream:
+   * a child completing never completes its parents, which may be shared
+   * (#2133). Its descendants complete once none of their parents is live.
+   * Unlike `complete()`, it passes on nothing the observable still holds: a
+   * `debounce` or `audit` drops its pending value instead of emitting it.
    */
   dispose: () => void;
   subscribe: (onNext: (v: A) => void, onComplete?: () => void) => Subscription;
@@ -97,15 +99,6 @@ namespace ObservableTypeConverter {
     Readonly<{
       parents: Wrap<P>;
     }>;
-
-  export type ToManager<
-    A,
-    O extends CreateObservableType<A, 'async child' | 'root'>,
-  > = O &
-    Readonly<{
-      addDescendant: <B>(child: ChildObservable<B>) => void;
-      deleteDescendant: <B>(child: ChildObservable<B>) => void;
-    }>;
 }
 
 export type SyncChildObservable<
@@ -125,9 +118,10 @@ export type InitializedSyncChildObservable<
 export type AsyncChildObservable<
   A,
   P extends NonEmptyUnknownList = NonEmptyUnknownList,
-> = ObservableTypeConverter.ToManager<
+> = ObservableTypeConverter.ToChild<
   A,
-  ObservableTypeConverter.ToChild<A, CreateObservableType<A, 'async child'>, P>
+  CreateObservableType<A, 'async child'>,
+  P
 >;
 
 export type InitializedAsyncChildObservable<
@@ -140,10 +134,7 @@ export type ChildObservable<
   P extends NonEmptyUnknownList = NonEmptyUnknownList,
 > = AsyncChildObservable<A, P> | SyncChildObservable<A, P>;
 
-export type RootObservable<A> = ObservableTypeConverter.ToManager<
-  A,
-  CreateObservableType<A, 'root'>
->;
+export type RootObservable<A> = CreateObservableType<A, 'root'>;
 
 export type InitializedRootObservable<A> =
   ObservableTypeConverter.ToInitialized<A, RootObservable<A>>;
@@ -180,6 +171,27 @@ export type Operator<A, B> =
   | DropInitialValueOperator<A, B>
   | KeepInitialValueOperator<A, B>;
 
+/**
+ * Tells an observable made by synstate from any other value, by the brand
+ * every observable carries. Checking for a `subscribe` method instead would
+ * also accept plain values that happen to have one.
+ *
+ * @example
+ *
+ * ```ts
+ * const [count$] = createState(0);
+ *
+ * assert.isTrue(isObservable(count$));
+ *
+ * // A `subscribe` method alone does not make an observable.
+ * assert.isFalse(isObservable({ subscribe: () => {} }));
+ *
+ * assert.isFalse(isObservable(0));
+ * ```
+ */
+export const isObservable = (value: unknown): value is Observable<unknown> =>
+  isRecord(value) && hasKey(value, observableBrand);
+
 export const isManagerObservable = <A,>(
   obs: Observable<A>,
 ): obs is ManagerObservable<A> => obs.kind !== 'sync child';
@@ -210,9 +222,32 @@ export type WrapInitialized<A extends readonly unknown[]> = Readonly<{
 // type GetDestTypeOfOperator<Op extends Operator<unknown, unknown>> =
 //   Op extends Operator<unknown, infer B> ? B : never;
 
-expectType<keyof AsyncChildObservable<unknown>, 'addDescendant'>('>=');
+// Only the members meant for users are public; the rest live on the
+// internal node types in `core/class` (#2117).
+expectType<
+  keyof Observable<unknown>,
+  | typeof observableBrand
+  | 'kind'
+  | 'depth'
+  | 'getSnapshot'
+  | 'isCompleted'
+  | 'updateToken'
+  | 'complete'
+  | 'dispose'
+  | 'subscribe'
+  | 'pipe'
+>('=');
 
-expectType<keyof RootObservable<unknown>, 'addDescendant'>('>=');
+expectType<
+  keyof ChildObservable<unknown>,
+  keyof Observable<unknown> | 'parents'
+>('=');
+
+// Everything but the brand is not enough to pass for an observable.
+expectType<
+  StrictOmit<RootObservable<unknown>, typeof observableBrand>,
+  Observable<unknown>
+>('!<=');
 
 expectType<RootObservable<unknown>['depth'], 0>('=');
 

package/src/core/types/scope.mts

@@ -0,0 +1,27 @@
+/**
+ * A unit of ownership: the observables created while {@link Scope.run} is
+ * running belong to the scope, and {@link Scope.dispose} releases them all at
+ * once. Create one with `createScope`.
+ *
+ * For authors of libraries built on synstate (a UI binding mounts and unmounts
+ * by scope); application code that defines its state at module level does not
+ * need it.
+ */
+export type Scope = Readonly<{
+  /**
+   * Calls `body` with this scope as the current one and returns what it
+   * returns. Only what `body` creates synchronously joins the scope: by the time
+   * code after an `await` or in a callback runs, `run` has already returned.
+   *
+   * On a disposed scope it warns, still calls `body`, and nothing created there
+   * belongs to any scope.
+   */
+  run: <R>(body: () => R) => R;
+
+  /**
+   * Disposes the child scopes (newest first), calls the functions registered
+   * with `onScopeDispose` (newest first), disposes the owned observables
+   * (newest first) and leaves the parent scope. Calling it again does nothing.
+   */
+  dispose: () => void;
+}>;