synstate 3.4.0 → 4.0.0

package/src/core/base/create-child-observable.mts

@@ -1,485 +0,0 @@
-import { Arr, type Optional, type Some } from 'ts-data-forge';
-import { panic } from 'ts-std-forge';
-import type { MutableSet } from 'ts-type-forge';
-import {
-  isChildObservable,
-  isManagerObservable,
-  type AsyncChildObservable,
-  type ChildObservable,
-  type InitializedSyncChildObservable,
-  type NonEmptyUnknownList,
-  type Observable,
-  type ObservableId,
-  type SyncChildObservable,
-  type UpdateToken,
-  type Wrap,
-} from '../types/index.mjs';
-import { maxDepth } from '../utils/index.mjs';
-import {
-  assembleObservable,
-  createManagerObservableParts,
-  createObservableBaseHandle,
-} from './create-observable-base.mjs';
-
-/**
- * The internal tools a sync-child leaf factory (`map`, `filter`, `zip`, …)
- * receives — the replacement for the `protected` methods a subclass of
- * `SyncChildObservableClass` used to inherit.
- */
-export type SyncChildObservableTools<A> = Readonly<{
-  /** Emits `nextValue` under `updateToken` and notifies subscribers. */
-  setNext: (nextValue: A, updateToken: UpdateToken) => void;
-
-  getSnapshot: () => Optional<A>;
-
-  /** Completes this observable (leaf teardown included). */
-  complete: () => void;
-}>;
-
-/**
- * The internal tools an async-child leaf factory (`debounce`, `switchMap`, …)
- * receives. Async children additionally start their own update propagation.
- */
-export type AsyncChildObservableTools<A> = Readonly<{
-  /** Emits `nextValue` and propagates the update to all descendants. */
-  startUpdate: (nextValue: A) => void;
-}> &
-  SyncChildObservableTools<A>;
-
-type ChildObservableConfigBase<P extends NonEmptyUnknownList> = Readonly<{
-  parents: Wrap<P>;
-
-  depth?: number;
-
-  /**
-   * Leaf teardown (clear timers, unsubscribe inner observables, …), run at
-   * the beginning of `complete()` — the closure replacement for
-   * `override complete() { teardown(); super.complete(); }`.
-   */
-  onComplete?: () => void;
-
-  /**
-   * 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).
-   */
-  canEmitNoMore?: () => boolean;
-}>;
-
-export type ChildObservableConfig<
-  A,
-  P extends NonEmptyUnknownList,
-> = ChildObservableConfigBase<P> &
-  Readonly<{
-    initialValue: Optional<A>;
-  }>;
-
-export type InitializedChildObservableConfig<
-  A,
-  P extends NonEmptyUnknownList,
-> = ChildObservableConfigBase<P> &
-  Readonly<{
-    initialValue: Some<A>;
-  }>;
-
-/**
- * Creates a sync-child observable — the classless replacement for extending
- * `SyncChildObservableClass`.
- *
- * `createTryUpdate` receives the internal tools and returns the `tryUpdate`
- * implementation (the former `override tryUpdate`). It runs during
- * construction, before the observable is registered to its parents; leaf
- * state can live either in the enclosing factory scope or inside the
- * `createTryUpdate` closure.
- */
-export const createSyncChildObservable = <A, P extends NonEmptyUnknownList>(
-  {
-    parents,
-    depth = 1 + maxDepth(parents),
-    initialValue,
-    onComplete,
-    canEmitNoMore,
-  }: ChildObservableConfig<A, P>,
-  createTryUpdate: (
-    tools: SyncChildObservableTools<A>,
-  ) => (updateToken: UpdateToken) => void,
-): SyncChildObservable<A, P> => {
-  const handle = createObservableBaseHandle<A>(initialValue);
-
-  /** Set once assembled; see {@link unregisterChild}. */
-  let mut_self: ChildObservable<A> | undefined = undefined;
-
-  const autoComplete =
-    onComplete !== undefined || parents.some((p) => p.autoComplete);
-
-  const dispose = (): void => {
-    // A completed node is reached again through every parent and child that
-    // completes after it; running again would repeat the teardown and the
-    // ancestor walk in `unregisterChild` for each of them.
-    if (handle.isCompleted()) {
-      return;
-    }
-
-    onComplete?.();
-
-    handle.completeBase();
-
-    if (mut_self !== undefined) {
-      unregisterChild(mut_self, parents);
-    }
-  };
-
-  const complete = (): void => {
-    if (handle.isCompleted()) {
-      return;
-    }
-
-    dispose();
-
-    // propagate to parents
-    for (const par of parents) {
-      par.tryComplete();
-    }
-  };
-
-  const tryComplete = (): void => {
-    if (handle.isCompleted()) {
-      return;
-    }
-
-    tryCompleteChild({
-      canEmitNoMore,
-      hasSubscriber: handle.hasSubscriber(),
-      hasActiveChild: handle.hasActiveChild(),
-      autoComplete,
-      parents,
-      complete,
-    });
-  };
-
-  const tryUpdate = createTryUpdate({
-    setNext: handle.setNext,
-    getSnapshot: handle.getSnapshot,
-    complete,
-  });
-
-  const observable: SyncChildObservable<A, P> = assembleObservable({
-    kind: 'sync child',
-    depth,
-    handle,
-    tryUpdate,
-    tryComplete,
-    complete,
-    dispose,
-    autoComplete,
-    extra: { parents },
-  });
-
-  // Completed parents never update again, so a child created under them is
-  // complete from the start; registering it would only leave a reference in
-  // each parent (#2248).
-  if (parents.every((p) => p.isCompleted)) {
-    dispose();
-  } else {
-    registerChild(observable, parents);
-
-    mut_self = observable;
-  }
-
-  return observable;
-};
-
-/**
- * Creates a sync-child observable that always holds a value.
- *
- * Runtime-wise this is exactly `createSyncChildObservable`; only the types of
- * `getSnapshot` and `pipe` are narrowed, which is what the
- * `InitializedSyncChildObservableClass` overrides existed for.
- */
-export const createInitializedSyncChildObservable = <
-  A,
-  P extends NonEmptyUnknownList,
->(
-  config: InitializedChildObservableConfig<A, P>,
-  createTryUpdate: (
-    tools: SyncChildObservableTools<A>,
-  ) => (updateToken: UpdateToken) => void,
-): InitializedSyncChildObservable<A, P> => {
-  const observable = createSyncChildObservable<A, P>(config, createTryUpdate);
-
-  return (
-    // `getSnapshot` always returns `Some` here: `initialValue` is a `Some` and
-    // `setNext` only ever stores a `Some`.
-    // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-    observable as InitializedSyncChildObservable<A, P>
-  );
-};
-
-/**
- * Creates an async-child observable — the classless replacement for extending
- * `AsyncChildObservableClass`. See {@link createSyncChildObservable} for the
- * `createTryUpdate` contract.
- */
-export const createAsyncChildObservable = <A, P extends NonEmptyUnknownList>(
-  {
-    parents,
-    depth = 1 + maxDepth(parents),
-    initialValue,
-    onComplete,
-    canEmitNoMore,
-  }: ChildObservableConfig<A, P>,
-  createTryUpdate: (
-    tools: AsyncChildObservableTools<A>,
-  ) => (updateToken: UpdateToken) => void,
-): AsyncChildObservable<A, P> => {
-  const handle = createObservableBaseHandle<A>(initialValue);
-
-  const { addDescendant, deleteDescendant, startUpdate } =
-    createManagerObservableParts(handle);
-
-  /** Set once assembled; see {@link unregisterChild}. */
-  let mut_self: ChildObservable<A> | undefined = undefined;
-
-  const autoComplete =
-    onComplete !== undefined || parents.some((p) => p.autoComplete);
-
-  const dispose = (): void => {
-    // A completed node is reached again through every parent and child that
-    // completes after it; running again would repeat the teardown and the
-    // ancestor walk in `unregisterChild` for each of them.
-    if (handle.isCompleted()) {
-      return;
-    }
-
-    onComplete?.();
-
-    handle.completeBase();
-
-    if (mut_self !== undefined) {
-      unregisterChild(mut_self, parents);
-    }
-  };
-
-  const complete = (): void => {
-    if (handle.isCompleted()) {
-      return;
-    }
-
-    dispose();
-
-    // propagate to parents
-    for (const par of parents) {
-      par.tryComplete();
-    }
-  };
-
-  const tryComplete = (): void => {
-    if (handle.isCompleted()) {
-      return;
-    }
-
-    tryCompleteChild({
-      canEmitNoMore,
-      hasSubscriber: handle.hasSubscriber(),
-      hasActiveChild: handle.hasActiveChild(),
-      autoComplete,
-      parents,
-      complete,
-    });
-  };
-
-  const tryUpdate = createTryUpdate({
-    setNext: handle.setNext,
-    getSnapshot: handle.getSnapshot,
-    complete,
-    startUpdate,
-  });
-
-  const observable: AsyncChildObservable<A, P> = assembleObservable({
-    kind: 'async child',
-    depth,
-    handle,
-    tryUpdate,
-    tryComplete,
-    complete,
-    dispose,
-    autoComplete,
-    extra: { parents, addDescendant, deleteDescendant },
-  });
-
-  // Completed parents never update again, so a child created under them is
-  // complete from the start; registering it would only leave a reference in
-  // each parent (#2248).
-  if (parents.every((p) => p.isCompleted)) {
-    dispose();
-  } else {
-    registerChild(observable, parents);
-
-    mut_self = observable;
-  }
-
-  return observable;
-};
-
-/* helpers */
-
-/**
- * Detects circular dependencies by walking the full ancestor chain of the
- * given parents and checking whether `child` already appears among them.
- *
- * @throws {Error} if a circular dependency is detected
- */
-const hasCircularDependencyFrom = (
-  node: Observable<unknown>,
-  mut_visited: MutableSet<ObservableId>,
-  mut_inPath: MutableSet<ObservableId>,
-): boolean => {
-  if (mut_inPath.has(node.id)) {
-    return true;
-  }
-
-  if (mut_visited.has(node.id)) {
-    return false;
-  }
-
-  mut_visited.add(node.id);
-
-  mut_inPath.add(node.id);
-
-  if (isChildObservable(node)) {
-    for (const parent of node.parents) {
-      if (hasCircularDependencyFrom(parent, mut_visited, mut_inPath)) {
-        return true;
-      }
-    }
-  }
-
-  mut_inPath.delete(node.id);
-
-  return false;
-};
-
-const detectCircularDependency = (
-  child: ChildObservable<unknown>,
-  parents: readonly Observable<unknown>[],
-): void => {
-  const mut_visited = new Set<ObservableId>();
-
-  const mut_inPath = new Set<ObservableId>([child.id]);
-
-  for (const parent of 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.',
-      );
-    }
-  }
-};
-
-/**
- * Registers `child` to its parents and to all reachable manager observables.
- * Runs after the child object is fully assembled, so parents only ever hold a
- * reference to the final composed object (the class version registered `this`
- * from inside the constructor instead).
- */
-const registerChild = <A,>(
-  child: ChildObservable<A>,
-  parents: ChildObservable<A>['parents'],
-): void => {
-  detectCircularDependency(child, parents);
-
-  for (const p of parents) {
-    p.addChild(child);
-  }
-
-  // register child to all reachable ManagerObservables
-  const mut_rest = Array.from(parents);
-
-  while (Arr.isNonEmpty(mut_rest)) {
-    const p = mut_rest.pop();
-
-    if (p === undefined) {
-      break;
-    }
-
-    if (isManagerObservable(p)) {
-      p.addDescendant(child);
-    } else {
-      // trace back dependency graph
-      mut_rest.push(...p.parents);
-    }
-  }
-};
-
-/**
- * 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).
- *
- * A completion that happens while the child is still being constructed (from
- * a leaf factory's `createTryUpdate`) precedes its registration, so there is
- * nothing to undo; `mut_self` is still `undefined` then.
- */
-const unregisterChild = <A,>(
-  child: ChildObservable<A>,
-  parents: ChildObservable<A>['parents'],
-): void => {
-  for (const p of parents) {
-    p.deleteChild(child);
-  }
-
-  const mut_rest = Array.from(parents);
-
-  while (Arr.isNonEmpty(mut_rest)) {
-    const p = mut_rest.pop();
-
-    if (p === undefined) {
-      break;
-    }
-
-    if (isManagerObservable(p)) {
-      p.deleteDescendant(child);
-    } else {
-      mut_rest.push(...p.parents);
-    }
-  }
-};
-
-const tryCompleteChild = <A,>({
-  canEmitNoMore,
-  hasSubscriber,
-  hasActiveChild,
-  autoComplete,
-  parents,
-  complete,
-}: Readonly<{
-  canEmitNoMore: (() => boolean) | undefined;
-  hasSubscriber: boolean;
-  hasActiveChild: boolean;
-  autoComplete: boolean;
-  parents: ChildObservable<A>['parents'];
-  complete: () => void;
-}>): void => {
-  // If there is no working parent node, or no value can come from the live ones
-  if (parents.every((r) => r.isCompleted) || canEmitNoMore?.() === true) {
-    complete();
-
-    return;
-  }
-
-  // If there are no active child node, and completing releases something
-  if (autoComplete && !hasSubscriber && !hasActiveChild) {
-    complete();
-  }
-
-  // propagate to parents
-  for (const par of parents) {
-    par.tryComplete();
-  }
-};