synstate 3.3.0 → 4.0.0

package/dist/utils/create-state.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"create-state.d.mts","sourceRoot":"","sources":["../../src/utils/create-state.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAuBxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,gBACb,CAAC,YACL,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KACjC,SAAS,CACV,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,EAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EACrB,KAAK,EAAE,QAAQ,CAAC;IACd,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7C,UAAU,EAAE,MAAM,CAAC,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,CAAC;IACrB,YAAY,EAAE,CAAC,CAAC;CACjB,CAAC,CA0BH,CAAC"}
+{"version":3,"file":"create-state.d.mts","sourceRoot":"","sources":["../../src/utils/create-state.mts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAuBxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,gBACb,CAAC,YACL,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KACjC,SAAS,CACV,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,EAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EACrB,KAAK,EAAE,QAAQ,CAAC;IACd,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7C,UAAU,EAAE,MAAM,CAAC,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,CAAC;IACrB,YAAY,EAAE,CAAC,CAAC;CACjB,CAAC,CA0BH,CAAC"}

package/dist/utils/create-state.mjs

@@ -66,6 +66,13 @@ const reducer = (state, action) => {
 
 
 
+
+
+
+
+
+
+
 
 
 

package/dist/utils/create-state.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"create-state.mjs","sourceRoot":"","sources":["../../src/utils/create-state.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAqB,MAAM,sBAAsB,CAAC;AAaxE,MAAM,OAAO,GAAG,CAAK,KAAQ,EAAE,MAAiB,EAAK,EAAE;IACrD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,KAAK;YACR,OAAO,MAAM,CAAC,SAAS,CAAC;QAE1B,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,YAAe,EACf,OAAkC,EAUlC,EAAE;IACF,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,CAAC,GAAG,aAAa,CACtD,OAAO,EACP,YAAY,EACZ,OAAO,CACR,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,QAAwB,EAAK,EAAE,CAClD,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;IAEzC,MAAM,QAAQ,GAAG,CAAC,SAAY,EAAK,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAE3E,MAAM,UAAU,GAAG,GAAM,EAAE,CACzB,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;IAErD,OAAO;QACL,KAAK;QACL,QAAQ;QACR;YACE,WAAW;YACX,UAAU;YACV,WAAW;YACX,YAAY;SACb;KACO,CAAC;AACb,CAAC,CAAC"}
+{"version":3,"file":"create-state.mjs","sourceRoot":"","sources":["../../src/utils/create-state.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAqB,MAAM,sBAAsB,CAAC;AAaxE,MAAM,OAAO,GAAG,CAAK,KAAQ,EAAE,MAAiB,EAAK,EAAE;IACrD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,KAAK;YACR,OAAO,MAAM,CAAC,SAAS,CAAC;QAE1B,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,YAAe,EACf,OAAkC,EAUlC,EAAE;IACF,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,CAAC,GAAG,aAAa,CACtD,OAAO,EACP,YAAY,EACZ,OAAO,CACR,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,QAAwB,EAAK,EAAE,CAClD,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;IAEzC,MAAM,QAAQ,GAAG,CAAC,SAAY,EAAK,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAE3E,MAAM,UAAU,GAAG,GAAM,EAAE,CACzB,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;IAErD,OAAO;QACL,KAAK;QACL,QAAQ;QACR;YACE,WAAW;YACX,UAAU;YACV,WAAW;YACX,YAAY;SACb;KACO,CAAC;AACb,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synstate",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "description": "Type-safe State Management Library for TypeScript/JavaScript",
   "repository": {
     "type": "git",
@@ -29,20 +29,20 @@
     "LICENSE"
   ],
   "dependencies": {
-    "ts-data-forge": "^14.7.1",
+    "ts-data-forge": "^14.8.0",
     "ts-std-forge": "^0.5.1",
     "ts-type-forge": "^9.2.2"
   },
   "devDependencies": {
     "@reduxjs/toolkit": "2.13.0",
-    "@sumi-lang/cli": "0.0.5",
+    "@sumi-lang/cli": "0.0.6",
     "@types/react": "19.3.0",
     "@vitest/browser-playwright": "5.0.3",
     "argparse": "3.0.2",
-    "eslint-config-typed": "5.17.4",
-    "eslint-plugin-ts-data-forge": "0.8.6",
-    "eslint-plugin-ts-fortress": "1.3.3",
-    "eslint-plugin-ts-type-forge": "0.8.8",
+    "eslint-config-typed": "5.19.0",
+    "eslint-plugin-ts-data-forge": "0.9.0",
+    "eslint-plugin-ts-fortress": "1.3.4",
+    "eslint-plugin-ts-type-forge": "0.8.9",
     "jotai": "3.0.1",
     "mobx": "7.0.6",
     "playwright": "1.64.0",
@@ -51,8 +51,8 @@
     "prettier-plugin-packagejson": "3.0.2",
     "react": "19.3.0",
     "rxjs": "7.8.2",
-    "synstate-react-hooks": "3.3.0",
-    "synstate-react-hooks-compat": "3.3.0",
+    "synstate-react-hooks": "4.0.0",
+    "synstate-react-hooks-compat": "4.0.0",
     "ts-repo-utils": "10.7.1",
     "valtio": "2.3.2",
     "zustand": "5.0.15"
@@ -68,22 +68,22 @@
   "scripts": {
     "build": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/build.mts",
     "check:ext": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/check-ext.mts",
-    "check:lint": "oxlint . && eslint .",
+    "check:lint": "node ../../tools/scripts/cmd/assert-deps-built.mts && oxlint . && eslint .",
     "check:sumi": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../languages/sumi/cli/src/cmd/sumi.mts check ./tsconfig.sumi.json",
-    "check:test": "pnpm run z:vitest:node run",
-    "check:test:browser": "pnpm run z:vitest --project='Browser' run",
-    "check:test:cov": "pnpm run z:vitest:node run --coverage",
-    "check:types": "node ../../node_modules/typescript-native/bin/tsc --noEmit",
+    "check:test": "node ../../tools/scripts/cmd/assert-deps-built.mts && pnpm run z:vitest:node run",
+    "check:test:browser": "node ../../tools/scripts/cmd/assert-deps-built.mts && pnpm run z:vitest --project='Browser' run",
+    "check:test:cov": "node ../../tools/scripts/cmd/assert-deps-built.mts && pnpm run z:vitest:node run --coverage",
+    "check:types": "node ../../tools/scripts/cmd/assert-deps-built.mts && node ../../node_modules/typescript-native/bin/tsc --noEmit",
     "check-all": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/check-all.mts",
     "doc": "run-s gen:readme gen:jsdoc gen:sample-diffs fix:fmt",
     "fix:fmt": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-uncommitted.mts --cwd .",
     "fix:fmt:diff": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/format-diff-from.mts origin/main --cwd .",
     "fix:fmt:full": "pnpm run z:prettier .",
-    "fix:lint": "oxlint . --fix && eslint . --fix",
+    "fix:lint": "node ../../tools/scripts/cmd/assert-deps-built.mts && oxlint . --fix && eslint . --fix",
     "fmt": "pnpm run fix:fmt",
     "gen": "run-s gen:index gen:readme gen:jsdoc gen:sample-diffs",
     "gen:index": "run-s gen:index:src fix:fmt",
-    "gen:index:src": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/gen-index-ts.mts ./src --index-ext .mts --export-ext .mjs --target-ext .mts --target-ext .tsx --exclude entry-point.mts --exclude \"core/base/**\" --exclude \"core/utils/**\"",
+    "gen:index:src": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ../../libs/ts-repo-utils/src/cmd/gen-index-ts.mts ./src --index-ext .mts --export-ext .mjs --target-ext .mts --target-ext .tsx --exclude entry-point.mts --exclude \"core/class/**\" --exclude \"core/utils/**\"",
     "gen:jsdoc": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/embed-examples-in-jsdoc.mts",
     "gen:readme": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/embed-examples.mts",
     "gen:sample-diffs": "tsx --tsconfig ../../tools/configs/tsconfig.tsx.json ./scripts/cmd/generate-sample-diffs.mts",

package/src/core/authoring.mts

@@ -0,0 +1,19 @@
+/**
+ * What custom creators and operators are written with: the factories every
+ * built-in observable is made by (#2117). The rest of `core/base` stays
+ * internal.
+ */
+export {
+  createAsyncChildObservable,
+  createInitializedSyncChildObservable,
+  createRootObservable,
+  createSyncChildObservable,
+  type AsyncChildObservableHooks,
+  type AsyncChildObservableTools,
+  type ChildObservableConfig,
+  type InitializedChildObservableConfig,
+  type RootObservableConfig,
+  type RootObservableTools,
+  type SyncChildObservableHooks,
+  type SyncChildObservableTools,
+} from './class/index.mjs';

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

@@ -0,0 +1,374 @@
+// @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, hasKey, isRecord, type Optional, type Some } from 'ts-data-forge';
+import { panic } from 'ts-std-forge';
+import type { MutableSet } from 'ts-type-forge';
+import type {
+  AsyncChildObservable,
+  DropInitialValueOperator,
+  InitializedObservable,
+  InitializedSyncChildObservable,
+  KeepInitialValueOperator,
+  NonEmptyUnknownList,
+  Observable,
+  Operator,
+  SyncChildObservable,
+  WithInitialValueOperator,
+  Wrap,
+} from '../types/index.mjs';
+import { maxDepth } from '../utils/index.mjs';
+import { ManagerObservableClass } from './manager-observable-class.mjs';
+import { ObservableBaseClass } from './observable-base-class.mjs';
+import {
+  toNode,
+  type ChildNode,
+  type ManagerNode,
+} from './observable-node.mjs';
+import { runAfterPropagation } from './propagation-state.mjs';
+
+type ChildObservableConfig<A, P extends NonEmptyUnknownList> = Readonly<{
+  parents: Wrap<P>;
+
+  /**
+   * Defaults to one more than the deepest parent. An update reaches
+   * observables in ascending depth, so an observable `tryUpdate` reads with
+   * `getSnapshot` without being its child (`withCurrentValueFrom`'s second
+   * source) has to be shallower than this one too, or this one reads its value
+   * from before the update: pass `1 + Math.max(...)` over both then.
+   */
+  depth?: number;
+
+  initialValue: Optional<A>;
+}>;
+
+/**
+ * An observable derived from `parents` that emits, if at all, in the same
+ * update as they do (`map`, `filter`, `combine`, …).
+ *
+ * A subclass overrides `tryUpdate`, and, when it holds something to
+ * release, `teardown`; its constructor ends with `this.attach()`, once
+ * everything `tryUpdate` and `teardown` read is in place.
+ */
+export class SyncChildObservableClass<A, const P extends NonEmptyUnknownList>
+  extends ObservableBaseClass<A, 'sync child', number>
+  implements SyncChildObservable<A, P>
+{
+  #mut_isAttached: boolean;
+  readonly parents: Wrap<P>;
+  readonly managers: readonly ManagerNode[];
+
+  constructor({
+    parents,
+    depth = 1 + maxDepth(parents),
+    initialValue,
+  }: ChildObservableConfig<A, P>) {
+    super({
+      kind: 'sync child',
+      depth,
+      initialValue,
+    });
+
+    this.parents = parents;
+
+    this.managers = managersOf(parents);
+
+    this.#mut_isAttached = false;
+  }
+
+  /**
+   * Joins the current scope and registers this observable to its parents
+   * and the managers it is reached from. Completed parents never update
+   * again, so a child created under them is complete from the start
+   * (#2248), as is one its constructor completed; registering it would only
+   * leave a reference in each parent.
+   */
+  protected attach(): void {
+    this.adoptIntoCurrentScope();
+
+    if (this.isCompleted || this.parents.every((p) => p.isCompleted)) {
+      this.complete();
+    } else {
+      registerChild(this, this.managers);
+
+      this.#mut_isAttached = true;
+    }
+  }
+
+  protected override detach(): void {
+    if (!this.#mut_isAttached) {
+      return;
+    }
+
+    this.#mut_isAttached = false;
+
+    unregisterChild(this, this.managers);
+  }
+
+  override tryComplete(): void {
+    if (shouldComplete(this)) {
+      this.complete();
+    }
+  }
+
+  /**
+   * Whether this observable can emit nothing more although some parent is
+   * still live, asked whenever a parent completes. `true` completes it then,
+   * as all parents completing does (`zip` once a completed source's queue is
+   * empty).
+   */
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+  canEmitNoMore(): boolean {
+    return false;
+  }
+
+  /**
+   * Completes this observable once the update now propagating has reached
+   * every descendant, so that they see the value just passed on first.
+   */
+  protected completeAfterPropagation(): void {
+    runAfterPropagation(() => {
+      this.complete();
+    });
+  }
+}
+
+/**
+ * An observable derived from `parents` that may emit later, in an update of
+ * its own, through `startUpdate` (`debounce`, `switchMap`). It may also emit
+ * synchronously with `setNext`, as a sync child does. A subclass may also
+ * override `flush`, to pass on at completion what it still holds.
+ */
+export class AsyncChildObservableClass<A, const P extends NonEmptyUnknownList>
+  extends ManagerObservableClass<A, 'async child', number>
+  implements AsyncChildObservable<A, P>
+{
+  #mut_isAttached: boolean;
+  readonly parents: Wrap<P>;
+
+  constructor({
+    parents,
+    depth = 1 + maxDepth(parents),
+    initialValue,
+  }: ChildObservableConfig<A, P>) {
+    super({
+      kind: 'async child',
+      depth,
+      initialValue,
+    });
+
+    this.parents = parents;
+
+    this.#mut_isAttached = false;
+  }
+
+  /** See `SyncChildObservableClass.attach`. */
+  protected attach(): void {
+    this.adoptIntoCurrentScope();
+
+    if (this.isCompleted || this.parents.every((p) => p.isCompleted)) {
+      this.complete();
+    } else {
+      registerChild(this, managersOf(this.parents));
+
+      this.#mut_isAttached = true;
+    }
+  }
+
+  protected override detach(): void {
+    if (!this.#mut_isAttached) {
+      return;
+    }
+
+    this.#mut_isAttached = false;
+
+    unregisterChild(this, managersOf(this.parents));
+  }
+
+  override tryComplete(): void {
+    if (shouldComplete(this)) {
+      this.complete();
+    }
+  }
+
+  /** See `SyncChildObservableClass.canEmitNoMore`. */
+  // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+  canEmitNoMore(): boolean {
+    return false;
+  }
+
+  /** See `SyncChildObservableClass.completeAfterPropagation`. */
+  protected completeAfterPropagation(): void {
+    runAfterPropagation(() => {
+      this.complete();
+    });
+  }
+}
+
+/**
+ * A sync child that always holds a value: a subclass passes a `Some` as its
+ * `initialValue`. It differs from its base only in the types of
+ * `getSnapshot` and `pipe`.
+ */
+export class InitializedSyncChildObservableClass<
+  A,
+  const P extends NonEmptyUnknownList,
+>
+  extends SyncChildObservableClass<A, P>
+  implements InitializedSyncChildObservable<A, P>
+{
+  override getSnapshot(): Some<A> {
+    // `initialValue` is a `Some`, and `setNext` only ever stores a `Some`.
+    // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+    return super.getSnapshot() as Some<A>;
+  }
+
+  override pipe<B>(
+    operator: KeepInitialValueOperator<A, B> | WithInitialValueOperator<A, B>,
+  ): InitializedObservable<B>;
+
+  override pipe<B>(operator: DropInitialValueOperator<A, B>): Observable<B>;
+
+  override pipe<B>(operator: Operator<A, B>): Observable<B> {
+    return operator(this);
+  }
+}
+
+/* helpers */
+
+/**
+ * Called by a parent that has completed: whether no live parent is left, or
+ * no value can come from the live ones.
+ */
+const shouldComplete = (
+  child: ChildNode & Readonly<{ canEmitNoMore: () => boolean }>,
+): boolean =>
+  !child.isCompleted &&
+  (child.parents.every((p) => p.isCompleted) || child.canEmitNoMore());
+
+/** Registers a child to its parents and to `managers`. */
+const registerChild = (
+  child: ChildNode,
+  managers: readonly ManagerNode[],
+): void => {
+  if (checksCircularDependency) {
+    detectCircularDependency(child);
+  }
+
+  for (const p of child.parents) {
+    toNode(p).addChild(child);
+  }
+
+  for (const m of managers) {
+    m.addDescendant(child);
+  }
+};
+
+/**
+ * Undoes {@link registerChild} for a completed child: its parents forget it,
+ * and every manager it registered to stops propagating updates to it.
+ * Without this a completed node stayed reachable for as long as its root
+ * lived, and ran its `tryUpdate` on every update (#2134).
+ */
+const unregisterChild = (
+  child: ChildNode,
+  managers: readonly ManagerNode[],
+): void => {
+  for (const p of child.parents) {
+    toNode(p).deleteChild(child);
+  }
+
+  for (const m of managers) {
+    m.deleteDescendant(child);
+  }
+};
+
+/**
+ * The managers the descendants of `parents` register to, shared with the
+ * parent when there is one.
+ */
+const managersOf = (
+  parents: readonly Observable<unknown>[],
+): readonly ManagerNode[] =>
+  Arr.isFixedLengthArray(1, parents)
+    ? toNode(parents[0]).managers
+    : Array.from(new Set(parents.flatMap((p) => toNode(p).managers)));
+
+const isDevelopmentProcess = (): boolean => {
+  const proc: unknown = Reflect.get(globalThis, 'process');
+
+  return (
+    isRecord(proc) &&
+    hasKey(proc, 'env') &&
+    isRecord(proc.env) &&
+    (!hasKey(proc.env, 'NODE_ENV') || proc.env.NODE_ENV !== 'production')
+  );
+};
+
+/**
+ * Whether {@link registerChild} checks for a circular dependency: everywhere
+ * but in a process whose `NODE_ENV` is `production`. A child's parents exist
+ * before it and cannot be changed afterwards, so only code that rewrites an
+ * observable's readonly `parents` can make a cycle, while the walk over every
+ * ancestor is paid on every creation. Where there is no `process` (a browser
+ * bundle) the check is off.
+ */
+export const checksCircularDependency: boolean = isDevelopmentProcess();
+
+/**
+ * Detects circular dependencies by walking the full ancestor chain of the
+ * child's parents and checking whether the child already appears among them.
+ *
+ * @throws {Error} if a circular dependency is detected
+ */
+const detectCircularDependency = (child: ChildNode): void => {
+  const mut_visited = new Set<Observable<unknown>>();
+
+  const mut_inPath = new Set<Observable<unknown>>([
+    // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+    child as Observable<unknown>,
+  ]);
+
+  for (const parent of child.parents) {
+    if (hasCircularDependencyFrom(parent, mut_visited, mut_inPath)) {
+      // A programming error (invariant violation), not a recoverable
+      // failure. `panic` marks the error it throws, so the `Result` /
+      // `AsyncResult` boundaries rethrow it rather than turning an invariant
+      // violation into an `Err` a caller might handle (Sumi D-48 / D-53).
+      panic(
+        'Circular dependency detected in observable graph: a child observable cannot be its own ancestor.',
+      );
+    }
+  }
+};
+
+const hasCircularDependencyFrom = (
+  node: Observable<unknown>,
+  mut_visited: MutableSet<Observable<unknown>>,
+  mut_inPath: MutableSet<Observable<unknown>>,
+): boolean => {
+  if (mut_inPath.has(node)) {
+    return true;
+  }
+
+  if (mut_visited.has(node)) {
+    return false;
+  }
+
+  mut_visited.add(node);
+
+  mut_inPath.add(node);
+
+  if (node.kind !== 'root') {
+    for (const parent of node.parents) {
+      if (hasCircularDependencyFrom(parent, mut_visited, mut_inPath)) {
+        return true;
+      }
+    }
+  }
+
+  mut_inPath.delete(node);
+
+  return false;
+};

package/src/core/{base → class}/circular-dependency-comparison.test.mts

@@ -1,7 +1,8 @@
 /**
  * Comparison tests: how SynState, RxJS, and Jotai handle circular dependencies.
  *
- * - SynState: detects cycles at construction time and throws a clear error.
+ * - SynState: detects cycles at construction time and throws a clear error,
+ *   outside production (`checksCircularDependency`).
  * - RxJS: pipe() always returns a new Observable, so static cycles cannot be
  *   expressed through the public API. No detection is needed or provided.
  * - Jotai: circular atom definitions are silently accepted. A cycle manifests
@@ -13,55 +14,62 @@ import { Optional } from 'ts-data-forge';
 import { combine } from '../combine/index.mjs';
 import { source } from '../create/index.mjs';
 import { map } from '../operators/index.mjs';
-import { createSyncChildObservable } from './create-child-observable.mjs';
-import { createTryUpdateNotImplemented } from './create-observable-base.mjs';
+import { checksCircularDependency } from './child-observable-class.mjs';
+import {
+  createSyncChildObservable,
+  createTryUpdateNotImplemented,
+} from './create-child-observable.mjs';
 import { createRootObservable } from './create-root-observable.mjs';
 
 describe('circular dependency comparison', () => {
   describe('SynState', () => {
-    test('detects cycle at construction time with a clear error message', () => {
-      const root = createRootObservable(
-        { initialValue: Optional.some(0) },
-        () => ({}),
-      );
-
-      const mut_childA = createSyncChildObservable(
-        {
-          parents: [root],
-          initialValue: Optional.some(0),
-        },
-        createTryUpdateNotImplemented,
-      );
-
-      const childB = createSyncChildObservable(
-        {
-          parents: [mut_childA],
-          initialValue: Optional.some(0),
-        },
-        createTryUpdateNotImplemented,
-      );
+    // Only where the check runs: see `checksCircularDependency`.
+    test.runIf(checksCircularDependency)(
+      'detects cycle at construction time with a clear error message',
+      () => {
+        const root = createRootObservable(
+          { initialValue: Optional.some(0) },
+          () => ({}),
+        );
 
-      // Simulate a cycle: mut_childA → childB → mut_childA
-      // In normal usage this is impossible — the check runs in every
-      // child constructor before the reference becomes available.
-      Object.defineProperty(mut_childA, 'parents', {
-        value: [childB],
-        writable: false,
-        configurable: true,
-      });
+        const mut_childA = createSyncChildObservable(
+          {
+            parents: [root],
+            initialValue: Optional.some(0),
+          },
+          createTryUpdateNotImplemented,
+        );
 
-      expect(() => {
-        createSyncChildObservable(
+        const childB = createSyncChildObservable(
           {
             parents: [mut_childA],
             initialValue: Optional.some(0),
           },
           createTryUpdateNotImplemented,
         );
-      }).toThrow(
-        'Circular dependency detected in observable graph: a child observable cannot be its own ancestor.',
-      );
-    });
+
+        // Simulate a cycle: mut_childA → childB → mut_childA
+        // In normal usage this is impossible — the check runs in every
+        // child constructor before the reference becomes available.
+        Object.defineProperty(mut_childA, 'parents', {
+          value: [childB],
+          writable: false,
+          configurable: true,
+        });
+
+        expect(() => {
+          createSyncChildObservable(
+            {
+              parents: [mut_childA],
+              initialValue: Optional.some(0),
+            },
+            createTryUpdateNotImplemented,
+          );
+        }).toThrow(
+          'Circular dependency detected in observable graph: a child observable cannot be its own ancestor.',
+        );
+      },
+    );
 
     test('accepts valid DAG (diamond dependency)', () => {
       const a$ = source(0);

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

@@ -2,15 +2,18 @@ import { Optional } from 'ts-data-forge';
 import { combine, merge } from '../combine/index.mjs';
 import { source } from '../create/index.mjs';
 import { map } from '../operators/index.mjs';
+import { checksCircularDependency } from './child-observable-class.mjs';
 import {
   createAsyncChildObservable,
   createSyncChildObservable,
+  createTryUpdateNotImplemented,
 } from './create-child-observable.mjs';
-import { createTryUpdateNotImplemented } from './create-observable-base.mjs';
 import { createRootObservable } from './create-root-observable.mjs';
 
 describe('circular dependency detection', () => {
-  describe('cycle in ancestor graph', () => {
+  // The check runs only in a process whose `NODE_ENV` is not `production`;
+  // the browser run has no `process`, and there nothing is checked.
+  describe.runIf(checksCircularDependency)('cycle in ancestor graph', () => {
     test('should throw when parent chain contains a cycle (A -> B -> A)', () => {
       const root = createRootObservable(
         { initialValue: Optional.some(0) },
@@ -180,6 +183,39 @@ describe('circular dependency detection', () => {
     });
   });
 
+  describe.skipIf(checksCircularDependency)('with the check off', () => {
+    test('does not walk the ancestors of a new child', () => {
+      const root = createRootObservable(
+        { initialValue: Optional.some(0) },
+        () => ({}),
+      );
+
+      const mut_childA = createSyncChildObservable(
+        {
+          parents: [root],
+          initialValue: Optional.some(0),
+        },
+        createTryUpdateNotImplemented,
+      );
+
+      Object.defineProperty(mut_childA, 'parents', {
+        value: [mut_childA],
+        writable: false,
+        configurable: true,
+      });
+
+      expect(() => {
+        createSyncChildObservable(
+          {
+            parents: [mut_childA],
+            initialValue: Optional.some(0),
+          },
+          createTryUpdateNotImplemented,
+        );
+      }).not.toThrow();
+    });
+  });
+
   describe('valid DAG patterns should not throw', () => {
     test('diamond dependency is not a cycle', () => {
       const root = createRootObservable(