synstate 3.3.0 → 4.0.0

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

@@ -1,548 +0,0 @@
-import { Arr, Optional } from 'ts-data-forge';
-import { unreachable } from 'ts-std-forge';
-import type { MutableMap, MutableSet, ReadonlyRecord } from 'ts-type-forge';
-import type {
-  ChildObservable,
-  InitializedObservable,
-  Observable,
-  ObservableBase,
-  ObservableId,
-  ObservableKind,
-  Operator,
-  Subscriber,
-  SubscriberId,
-  Subscription,
-  UpdateToken,
-  WithInitialValueOperator,
-} from '../types/index.mjs';
-import {
-  binarySearch,
-  issueObservableId,
-  issueSubscriberId,
-  issueUpdateToken,
-  toSubscriber,
-} from '../utils/index.mjs';
-
-/**
- * The mutable core shared by every observable, expressed as closures instead of
- * a base class.
- *
- * The returned handle is the "protected" surface of the former
- * `ObservableBaseClass`: the layer factories (`createRootObservable`,
- * `createSyncChildObservable`, `createAsyncChildObservable`) build the public
- * object from it via {@link assembleObservable}, and leaf factories receive
- * only the narrow tools they need. Neither the handle nor its type is exported
- * from the package (`core/base/**` is excluded from index generation), so
- * `setNext` and friends stay internal, as `protected` kept them before.
- */
-export type ObservableBaseHandle<A> = Readonly<{
-  id: ObservableId;
-
-  /**
-   * Registers the public object {@link assembleObservable} built from this
-   * handle, so that its four state flags (`isCompleted`, `updateToken`,
-   * `hasSubscriber`, `hasChild`) can be mirrored onto it as plain data
-   * properties.
-   *
-   * They used to be getters delegating to this handle's closures, and that
-   * costs more than it looks. Reading one was an accessor call plus a closure
-   * call where a field read would do — `updateToken` is read once per child
-   * per update, so the propagation path paid it on every step — and an object
-   * literal carrying accessors is far more expensive to create than one
-   * carrying data, which is most of what building a graph costs. Measured on
-   * one machine with `pnpm run benchmark`: the derived chain's 100,000 updates
-   * 16.7 ms -> 13.6 ms, and the cascaded diamond at N=20, whose measurement is
-   * dominated by graph construction, 587 ms -> 362 ms.
-   *
-   * Every write below therefore has to keep the mirror in step; that is the
-   * price of not reading through a closure on the hot path. It is paid in
-   * clarity too, and on purpose: `hasSubscriber` and `hasChild` are derived
-   * from `mut_subscribers` and `mut_children`, which a getter stated once and
-   * declaratively, whereas the mirror restates it at every write.
-   *
-   * Nor can the rarely read flags alone go back to getters while `updateToken`
-   * stays data. A single accessor in the literal is enough to lose nearly all
-   * of the gain: measured on Node 26 with the `...extra` spread followed by
-   * these properties, one getter among data properties made the literal about
-   * 10x slower to create than all data (four getters: about 15x) and gave
-   * every instance its own hidden class (`%HaveSameMap` false). Keep all four
-   * as data, or measure again before changing that.
-   */
-  attach: (writers: ObservableStateWriters) => void;
-
-  addChild: <B>(child: ChildObservable<B>) => void;
-
-  /**
-   * Forgets `child`, which a completed child calls on each of its parents so
-   * that nothing keeps a reference to it (#2134).
-   */
-  deleteChild: <B>(child: ChildObservable<B>) => void;
-
-  getSnapshot: () => Optional<A>;
-
-  isCompleted: () => boolean;
-
-  updateToken: () => UpdateToken;
-
-  hasSubscriber: () => boolean;
-
-  hasActiveChild: () => boolean;
-
-  subscribe: (onNext: (v: A) => void, onComplete?: () => void) => Subscription;
-
-  /** Stores `nextValue` as the current value and notifies subscribers. */
-  setNext: (nextValue: A, updateToken: UpdateToken) => void;
-
-  /**
-   * The innermost part of `complete()` (what `ObservableBaseClass.complete`
-   * used to do): marks this observable completed exactly once, notifies and
-   * removes all subscribers, and propagates `tryComplete` to children. Layer
-   * factories wrap this with leaf teardown and propagation to parents.
-   */
-  completeBase: () => void;
-}>;
-
-/**
- * How the handle writes the four state flags onto the public object. The
- * writers are closures over that object rather than the object itself, because
- * a parameter this side could mutate has to be a mutable type, which
- * `@typescript-eslint/prefer-readonly-parameter-types` rejects — and the object
- * is `Readonly` to everyone else.
- */
-type ObservableStateWriters = Readonly<{
-  setIsCompleted: (value: boolean) => void;
-  setUpdateToken: (value: UpdateToken) => void;
-  setHasSubscriber: (value: boolean) => void;
-  setHasChild: (value: boolean) => void;
-}>;
-
-export const createObservableBaseHandle = <A,>(
-  initialValue: Optional<A>,
-): ObservableBaseHandle<A> => {
-  const id = issueObservableId();
-
-  // 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.
-  const mut_children: MutableSet<ChildObservable<unknown>> = new Set();
-
-  const mut_subscribers: MutableMap<SubscriberId, Subscriber<A>> = new Map();
-
-  let mut_currentValue: Optional<A> = initialValue;
-
-  let mut_isCompleted = false;
-
-  let mut_updateToken: UpdateToken = issueUpdateToken();
-
-  /**
-   * Set once {@link assembleObservable} has built the public object. It does
-   * not exist while a leaf factory's `init` callback runs — that callback may
-   * already subscribe or complete — so every write below is optional, and
-   * `attach` copies the state as it stands rather than assuming defaults.
-   */
-  let mut_writers: ObservableStateWriters | undefined;
-
-  const attach = (writers: ObservableStateWriters): void => {
-    mut_writers = writers;
-
-    writers.setIsCompleted(mut_isCompleted);
-
-    writers.setUpdateToken(mut_updateToken);
-
-    writers.setHasSubscriber(mut_subscribers.size > 0);
-
-    writers.setHasChild(mut_children.size > 0);
-  };
-
-  const addSubscriber = (s: Subscriber<A>): SubscriberId => {
-    // return the id of added subscriber
-    const subscriberId = issueSubscriberId();
-
-    mut_subscribers.set(subscriberId, s);
-
-    mut_writers?.setHasSubscriber(true);
-
-    return subscriberId;
-  };
-
-  const removeSubscriber = (subscriberId: SubscriberId): void => {
-    mut_subscribers.delete(subscriberId);
-
-    mut_writers?.setHasSubscriber(mut_subscribers.size > 0);
-  };
-
-  const addChild = <B,>(child: ChildObservable<B>): void => {
-    mut_children.add(child);
-
-    mut_writers?.setHasChild(true);
-  };
-
-  const deleteChild = <B,>(child: ChildObservable<B>): void => {
-    mut_children.delete(child);
-
-    mut_writers?.setHasChild(mut_children.size > 0);
-  };
-
-  const getSnapshot = (): Optional<A> => mut_currentValue;
-
-  const isCompleted = (): boolean => mut_isCompleted;
-
-  const updateToken = (): UpdateToken => mut_updateToken;
-
-  const hasSubscriber = (): boolean => mut_subscribers.size > 0;
-
-  const hasActiveChild = (): boolean => {
-    for (const c of mut_children) {
-      if (!c.isCompleted) {
-        return true;
-      }
-    }
-
-    return false;
-  };
-
-  const setNext = (nextValue: A, nextUpdateToken: UpdateToken): void => {
-    mut_updateToken = nextUpdateToken;
-
-    mut_writers?.setUpdateToken(nextUpdateToken);
-
-    mut_currentValue = Optional.some(nextValue);
-
-    for (const s of mut_subscribers.values()) {
-      s.onNext(nextValue);
-    }
-  };
-
-  const completeBase = (): void => {
-    if (mut_isCompleted) {
-      return; // terminate only once
-    }
-
-    // change state
-    mut_isCompleted = true;
-
-    mut_writers?.setIsCompleted(true);
-
-    // run subscribers for the current value
-    for (const s of mut_subscribers.values()) {
-      s.onComplete();
-    }
-
-    // remove all subscribers
-    mut_subscribers.clear();
-
-    mut_writers?.setHasSubscriber(false);
-
-    // Propagate to children. A child that completes removes itself from
-    // `mut_children` during this loop, which iterating a `Set` tolerates.
-    for (const o of mut_children) {
-      o.tryComplete();
-    }
-  };
-
-  const subscribe = (
-    onNext: (v: A) => void,
-    onComplete?: () => void,
-  ): Subscription => {
-    // first emit
-    const curr = getSnapshot();
-
-    if (Optional.isSome(curr)) {
-      onNext(curr.value);
-    }
-
-    if (mut_isCompleted) {
-      if (onComplete !== undefined) {
-        onComplete();
-      }
-
-      return { unsubscribe: () => {} };
-    }
-
-    const subscriberId: SubscriberId = addSubscriber(
-      toSubscriber(onNext, onComplete),
-    );
-
-    return {
-      unsubscribe: () => {
-        removeSubscriber(subscriberId);
-      },
-    };
-  };
-
-  return {
-    id,
-    attach,
-    addChild,
-    deleteChild,
-    getSnapshot,
-    isCompleted,
-    updateToken,
-    hasSubscriber,
-    hasActiveChild,
-    subscribe,
-    setNext,
-    completeBase,
-  };
-};
-
-/**
- * The extra members every manager observable — a root or an async child — owns:
- * the depth-ordered descendant list and the update propagation that walks it.
- */
-export type ManagerObservableParts<A> = Readonly<{
-  addDescendant: <B>(child: ChildObservable<B>) => void;
-
-  /**
-   * Takes `child` out of the propagation order, which a completed child calls
-   * on every manager it registered to (#2134).
-   */
-  deleteDescendant: <B>(child: ChildObservable<B>) => void;
-
-  /** Emits `nextValue` and propagates the update to all descendants. */
-  startUpdate: (nextValue: A) => void;
-}>;
-
-/**
- * Builds the manager half of a root or async-child observable. Both start their
- * own update propagation, so both keep a depth-ordered propagation list; this
- * is the single implementation of it (the class version duplicated it across
- * `RootObservableClass` and `AsyncChildObservableClass`).
- *
- * The descendants are kept in one insertion-ordered set per depth, so adding
- * and removing one is O(1) apart from the first node of a new depth. The flat
- * array `startUpdate` walks is rebuilt only when an update finds it stale: it
- * used to be copied on every `addDescendant`, which made creating n nodes under
- * one root O(n²). Rebuilding at the start of an update also keeps the walk a
- * snapshot, as the copy-on-write array was — a node created or completed while
- * an update is propagating does not change which nodes that update visits.
- */
-export const createManagerObservableParts = <A,>(
-  handle: ObservableBaseHandle<A>,
-): ManagerObservableParts<A> => {
-  const mut_buckets: MutableMap<
-    number,
-    MutableSet<ChildObservable<unknown>>
-  > = new Map();
-
-  /** The keys of `mut_buckets`, ascending. */
-  let mut_depths: readonly number[] = [];
-
-  /** `undefined` while stale. */
-  let mut_propagationOrder: readonly ChildObservable<unknown>[] | undefined =
-    [];
-
-  const addDescendant = <B,>(child: ChildObservable<B>): void => {
-    const mut_bucket = mut_buckets.get(child.depth);
-
-    if (mut_bucket === undefined) {
-      mut_buckets.set(child.depth, new Set<ChildObservable<unknown>>([child]));
-
-      mut_depths = Arr.toInserted(
-        mut_depths,
-        binarySearch(mut_depths, child.depth),
-        child.depth,
-      );
-    } else {
-      if (mut_bucket.has(child)) {
-        return;
-      }
-
-      mut_bucket.add(child);
-    }
-
-    mut_propagationOrder = undefined;
-  };
-
-  const deleteDescendant = <B,>(child: ChildObservable<B>): void => {
-    // An emptied bucket stays, so that its depth is not inserted again.
-    const mut_bucket = mut_buckets.get(child.depth);
-
-    if (mut_bucket?.delete(child) === true) {
-      mut_propagationOrder = undefined;
-    }
-  };
-
-  const getPropagationOrder = (): readonly ChildObservable<unknown>[] => {
-    if (mut_propagationOrder !== undefined) {
-      return mut_propagationOrder;
-    }
-
-    const mut_order: ChildObservable<unknown>[] = [];
-
-    for (const depth of mut_depths) {
-      const bucket = mut_buckets.get(depth);
-
-      if (bucket !== undefined) {
-        // Not `push(...bucket)`: a spread passes every element as an argument,
-        // which overflows the stack for a bucket of a few hundred thousand.
-        for (const c of bucket) {
-          mut_order.push(c);
-        }
-      }
-    }
-
-    mut_propagationOrder = mut_order;
-
-    return mut_order;
-  };
-
-  const startUpdate = (nextValue: A): void => {
-    const updateToken = issueUpdateToken();
-
-    handle.setNext(nextValue, updateToken);
-
-    for (const p of getPropagationOrder()) {
-      p.tryUpdate(updateToken);
-    }
-  };
-
-  return { addDescendant, deleteDescendant, startUpdate };
-};
-
-/** Default `tryUpdate` for observables that never receive parent updates. */
-export const createTryUpdateNotImplemented = (): ((
-  _updateToken: UpdateToken,
-) => void) => tryUpdateNotImplemented;
-
-const tryUpdateNotImplemented = (_updateToken: UpdateToken): void => {
-  // Not `todo()`: nothing here is waiting to be written. This is the base
-  // default of what was a base-class method, and every observable that can
-  // receive a parent update supplies its own `tryUpdate`; an observable with
-  // no parents never gets one. Reaching this is the invariant breaking, which
-  // is what `unreachable` says (Sumi D-48). There is no `never` value to
-  // hand it — the fact of the call is the error.
-  unreachable();
-};
-
-type AssembleObservableArgs<
-  A,
-  Kind extends ObservableKind,
-  Extra extends ReadonlyRecord<string, unknown>,
-> = Readonly<{
-  kind: Kind;
-  depth: Kind extends 'root' ? 0 : number;
-  handle: ObservableBaseHandle<A>;
-  tryUpdate: (updateToken: UpdateToken) => void;
-  tryComplete: () => void;
-  complete: () => void;
-  dispose: () => void;
-  autoComplete: boolean;
-  /**
-   * Kind-specific public members (`parents`, `addDescendant`) and leaf
-   * extensions (`next`, `start`). They are merged here, in the one place the
-   * final object literal is created, because the handle keeps the state flags
-   * up to date on that object alone: a copy made by spreading it afterwards
-   * would freeze their current values.
-   */
-  extra: Extra;
-}>;
-
-/**
- * Builds the public observable object from a base handle. This replaces the
- * implicit assembly a `class` performs: state stays in the handle's closures,
- * `isCompleted` / `updateToken` / `hasSubscriber` / `hasChild` become data
- * properties the handle keeps in step through `attach`, and the kind-specific
- * behavior (`tryUpdate`, `tryComplete`, `complete`) is passed in already
- * composed.
- */
-export const assembleObservable = <
-  A,
-  Kind extends ObservableKind,
-  Extra extends ReadonlyRecord<string, unknown>,
->({
-  kind,
-  depth,
-  handle,
-  tryUpdate,
-  tryComplete,
-  complete,
-  dispose,
-  autoComplete,
-  extra,
-}: AssembleObservableArgs<A, Kind, Extra>): Extra &
-  ObservableBase<A> &
-  Readonly<{
-    kind: Kind;
-    depth: AssembleObservableArgs<A, Kind, Extra>['depth'];
-  }> => {
-  function pipe<B>(
-    operator: WithInitialValueOperator<A, B>,
-  ): InitializedObservable<B>;
-
-  // A `WithInitialValueOperator` is also an `Operator`: nothing at run time
-  // tells the two apart, so this set only refines the return type (#1952).
-  // @sumi-expect-error functions/no-refinement-overload
-  function pipe<B>(operator: Operator<A, B>): Observable<B>;
-
-  function pipe<B>(operator: Operator<A, B>): Observable<B> {
-    return operator(
-      // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-      mut_observable as unknown as InitializedObservable<A>,
-    );
-  }
-
-  // The four state flags are plain data properties kept in step by the handle,
-  // not getters delegating to it — see `ObservableBaseHandle.attach` for the
-  // measurements that decided this. `updateToken` in particular is read once
-  // per child per update, and `tryUpdate` reading a field rather than calling
-  // through an accessor is most of what the change buys.
-  const mut_observable = {
-    ...extra,
-
-    id: handle.id,
-
-    kind,
-
-    depth,
-
-    addChild: handle.addChild,
-
-    deleteChild: handle.deleteChild,
-
-    getSnapshot: handle.getSnapshot,
-
-    isCompleted: false,
-
-    updateToken: handle.updateToken(),
-
-    hasSubscriber: false,
-
-    hasChild: false,
-
-    hasActiveChild: handle.hasActiveChild,
-
-    autoComplete,
-
-    tryUpdate,
-
-    tryComplete,
-
-    complete,
-
-    dispose,
-
-    subscribe: handle.subscribe,
-
-    pipe,
-  };
-
-  handle.attach({
-    setIsCompleted: (value) => {
-      mut_observable.isCompleted = value;
-    },
-
-    setUpdateToken: (value) => {
-      mut_observable.updateToken = value;
-    },
-
-    setHasSubscriber: (value) => {
-      mut_observable.hasSubscriber = value;
-    },
-
-    setHasChild: (value) => {
-      mut_observable.hasChild = value;
-    },
-  });
-
-  return mut_observable;
-};

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

@@ -1,113 +0,0 @@
-import { Optional } from 'ts-data-forge';
-import type { ReadonlyRecord } from 'ts-type-forge';
-import { isRootObservable, type RootObservable } from '../types/index.mjs';
-import {
-  assembleObservable,
-  createManagerObservableParts,
-  createObservableBaseHandle,
-  createTryUpdateNotImplemented,
-} from './create-observable-base.mjs';
-
-/**
- * The internal tools a root leaf factory (`source`, `timer`, `fromPromise`, …)
- * receives — the replacement for the `protected` methods a subclass of
- * `RootObservableClass` used to inherit.
- */
-export type RootObservableTools<A> = Readonly<{
-  /** Emits `nextValue` and propagates the update to all descendants. */
-  startUpdate: (nextValue: A) => void;
-
-  isCompleted: () => boolean;
-
-  /** Completes this observable (leaf teardown included). */
-  complete: () => void;
-}>;
-
-export type RootObservableConfig<A> = Readonly<{
-  initialValue: Optional<A>;
-
-  /**
-   * Leaf teardown (clear timers, abort requests, …), run at the beginning of
-   * `complete()` — the closure replacement for
-   * `override complete() { teardown(); super.complete(); }`.
-   */
-  onComplete?: () => void;
-}>;
-
-/**
- * Creates a root observable — the classless replacement for extending
- * `RootObservableClass`.
- *
- * The optional `init` callback receives the internal tools and returns extra
- * public members to merge into the observable (e.g. `next` for `source`,
- * `start` for `timer`). `init` runs during construction; it may register
- * asynchronous callbacks that use the tools, and may call `complete`
- * synchronously, but the observable object itself does not exist yet at that
- * point.
- */
-export const createRootObservable = <
-  A,
-  // The default is deliberately empty: a root leaf 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, onComplete }: RootObservableConfig<A>,
-  init: (tools: RootObservableTools<A>) => Extension,
-): Extension & RootObservable<A> => {
-  const handle = createObservableBaseHandle<A>(initialValue);
-
-  const { addDescendant, deleteDescendant, startUpdate } =
-    createManagerObservableParts(handle);
-
-  const complete = (): void => {
-    onComplete?.();
-
-    handle.completeBase();
-  };
-
-  // A root without a teardown (`source`, `createState`, `just`) releases
-  // nothing by completing, so a child completing never completes it (#2133).
-  const autoComplete = onComplete !== undefined;
-
-  const tryComplete = (): void => {
-    if (autoComplete && !handle.hasSubscriber() && !handle.hasActiveChild()) {
-      complete();
-    }
-  };
-
-  const extension: Extension = init({
-    startUpdate,
-    isCompleted: handle.isCompleted,
-    complete,
-  });
-
-  return assembleObservable({
-    kind: 'root',
-    depth: 0,
-    handle,
-    tryUpdate: createTryUpdateNotImplemented,
-    tryComplete,
-    complete,
-    // A root has no parents to keep out of it.
-    dispose: complete,
-    autoComplete,
-    extra: {
-      ...extension,
-      addDescendant,
-      deleteDescendant,
-    },
-  });
-};
-
-if (import.meta.vitest !== undefined) {
-  test('isRootObservable', () => {
-    assert.isTrue(
-      isRootObservable(
-        createRootObservable({ initialValue: Optional.some(0) }, () => ({})),
-      ),
-    );
-  });
-}

package/src/core/base/index.mts

@@ -1,2 +0,0 @@
-export * from './create-child-observable.mjs';
-export * from './create-root-observable.mjs';

package/src/core/predefined/operators/take.mts

@@ -1,48 +0,0 @@
-import type { PositiveSafeIntWithSmallInt } from 'ts-type-forge';
-import { takeWhile } from '../../operators/index.mjs';
-import type { DropInitialValueOperator } from '../../types/index.mjs';
-
-/**
- * Takes only the first `n` emissions from the source observable, then completes.
- *
- * @template A - The type of values from the source
- * @param n - The number of values to take
- * @returns An operator that takes the first n emissions
- *
- * @example
- * ```ts
- * //  Timeline:
- * //
- * //  num$    1     2     3     4 (ignored)
- * //  taken$  1     2     3     | (completes)
- * //
- * //  Explanation:
- * //  - take emits only the first n values, then completes
- * //  - Subsequent emissions from the source are ignored
- *
- * const num$ = source<number>();
- *
- * const taken$ = num$.pipe(take(3));
- *
- * const valueHistory: number[] = [];
- *
- * taken$.subscribe((x) => {
- *   valueHistory.push(x);
- * });
- *
- * num$.next(1);
- *
- * num$.next(2);
- *
- * num$.next(3);
- *
- * assert.deepStrictEqual(valueHistory, [1, 2, 3]);
- *
- * num$.next(4); // ignored (already completed)
- *
- * assert.deepStrictEqual(valueHistory, [1, 2, 3]);
- * ```
- */
-export const take = <A,>(
-  n: PositiveSafeIntWithSmallInt,
-): DropInitialValueOperator<A, A> => takeWhile((_, index) => index + 1 <= n);