synstate 2.0.2 → 3.0.0

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

@@ -0,0 +1,358 @@
+import { Arr, Optional } from 'ts-data-forge';
+import {
+  type MutableMap,
+  type MutableSet,
+  type ReadonlyRecord,
+} from 'ts-type-forge';
+import {
+  type ChildObservable,
+  type InitializedObservable,
+  type Observable,
+  type ObservableBase,
+  type ObservableId,
+  type ObservableKind,
+  type Operator,
+  type Subscriber,
+  type SubscriberId,
+  type Subscription,
+  type UpdateToken,
+  type 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;
+
+  addChild: <B>(child: ChildObservable<B>) => void;
+
+  getSnapshot: () => Optional<A>;
+
+  isCompleted: () => boolean;
+
+  updateToken: () => UpdateToken;
+
+  hasSubscriber: () => boolean;
+
+  hasChild: () => 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;
+}>;
+
+export const createObservableBaseHandle = <A,>(
+  initialValue: Optional<A>,
+): ObservableBaseHandle<A> => {
+  const id = issueObservableId();
+
+  let mut_children: readonly ChildObservable<unknown>[] = [];
+
+  const mut_subscribers: MutableMap<SubscriberId, Subscriber<A>> = new Map();
+
+  let mut_currentValue: Optional<A> = initialValue;
+
+  let mut_isCompleted = false;
+
+  let mut_updateToken: UpdateToken = issueUpdateToken();
+
+  const addSubscriber = (s: Subscriber<A>): SubscriberId => {
+    // return the id of added subscriber
+    const subscriberId = issueSubscriberId();
+
+    mut_subscribers.set(subscriberId, s);
+
+    return subscriberId;
+  };
+
+  const removeSubscriber = (subscriberId: SubscriberId): void => {
+    mut_subscribers.delete(subscriberId);
+  };
+
+  const addChild = <B,>(child: ChildObservable<B>): void => {
+    mut_children = Arr.toPushed(
+      mut_children,
+
+      child as ChildObservable<unknown>,
+    );
+  };
+
+  const getSnapshot = (): Optional<A> => mut_currentValue;
+
+  const isCompleted = (): boolean => mut_isCompleted;
+
+  const updateToken = (): UpdateToken => mut_updateToken;
+
+  const hasSubscriber = (): boolean => mut_subscribers.size > 0;
+
+  const hasChild = (): boolean => Arr.isNonEmpty(mut_children);
+
+  const hasActiveChild = (): boolean =>
+    mut_children.some((c) => !c.isCompleted);
+
+  const setNext = (nextValue: A, nextUpdateToken: UpdateToken): void => {
+    mut_updateToken = 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;
+
+    // run subscribers for the current value
+    for (const s of mut_subscribers.values()) {
+      s.onComplete();
+    }
+
+    // remove all subscribers
+    mut_subscribers.clear();
+
+    // propagate to children
+    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,
+    addChild,
+    getSnapshot,
+    isCompleted,
+    updateToken,
+    hasSubscriber,
+    hasChild,
+    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;
+
+  /** 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 descendant set and a depth-ordered
+ * propagation list; this is the single implementation of that pair (the class
+ * version duplicated it across `RootObservableClass` and
+ * `AsyncChildObservableClass`).
+ */
+export const createManagerObservableParts = <A,>(
+  handle: ObservableBaseHandle<A>,
+): ManagerObservableParts<A> => {
+  let mut_propagationOrder: readonly ChildObservable<unknown>[] = [];
+
+  const mut_descendantsIdSet: MutableSet<ObservableId> = new Set();
+
+  const addDescendant = <B,>(child: ChildObservable<B>): void => {
+    if (mut_descendantsIdSet.has(child.id)) return;
+
+    mut_descendantsIdSet.add(child.id);
+
+    const insertPos = binarySearch(
+      mut_propagationOrder.map((a) => a.depth),
+      child.depth,
+    );
+
+    mut_propagationOrder = Arr.toInserted(
+      mut_propagationOrder,
+      insertPos,
+      child,
+    );
+  };
+
+  const startUpdate = (nextValue: A): void => {
+    const updateToken = issueUpdateToken();
+
+    handle.setNext(nextValue, updateToken);
+
+    for (const p of mut_propagationOrder) {
+      p.tryUpdate(updateToken);
+    }
+  };
+
+  return { addDescendant, startUpdate };
+};
+
+/** Default `tryUpdate` for observables that never receive parent updates. */
+export const createTryUpdateNotImplemented = (): ((
+  _updateToken: UpdateToken,
+) => void) => tryUpdateNotImplemented;
+
+const tryUpdateNotImplemented = (_updateToken: UpdateToken): void => {
+  throw new Error('not implemented');
+};
+
+type AssembleObservableArgs<
+  A,
+  Kind extends ObservableKind,
+  Extra extends ReadonlyRecord<string, unknown>,
+> = Readonly<{
+  kind: Kind;
+  depth: number;
+  handle: ObservableBaseHandle<A>;
+  tryUpdate: (updateToken: UpdateToken) => void;
+  tryComplete: () => void;
+  complete: () => void;
+  /**
+   * 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 public getters below must not
+   * be copied by a spread (spreading 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 getters
+ * delegating to the handle, 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,
+  extra,
+}: AssembleObservableArgs<A, Kind, Extra>): Extra &
+  ObservableBase<A> &
+  Readonly<{ kind: Kind }> => {
+  function pipe<B>(
+    operator: WithInitialValueOperator<A, B>,
+  ): InitializedObservable<B>;
+
+  function pipe<B>(operator: Operator<A, B>): Observable<B>;
+
+  function pipe<B>(operator: Operator<A, B>): Observable<B> {
+    return operator(
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      observable as unknown as InitializedObservable<A>,
+    );
+  }
+
+  const observable = {
+    ...extra,
+
+    id: handle.id,
+
+    kind,
+
+    depth,
+
+    addChild: handle.addChild,
+
+    getSnapshot: handle.getSnapshot,
+
+    get isCompleted(): boolean {
+      return handle.isCompleted();
+    },
+
+    get updateToken(): UpdateToken {
+      return handle.updateToken();
+    },
+
+    get hasSubscriber(): boolean {
+      return handle.hasSubscriber();
+    },
+
+    get hasChild(): boolean {
+      return handle.hasChild();
+    },
+
+    hasActiveChild: handle.hasActiveChild,
+
+    tryUpdate,
+
+    tryComplete,
+
+    complete,
+
+    subscribe: handle.subscribe,
+
+    pipe,
+  } as const;
+
+  return observable;
+};

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

@@ -0,0 +1,102 @@
+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,
+  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, startUpdate } = createManagerObservableParts(handle);
+
+  const complete = (): void => {
+    onComplete?.();
+
+    handle.completeBase();
+  };
+
+  const tryComplete = (): void => {
+    if (!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,
+    extra: {
+      ...extension,
+      addDescendant,
+    },
+  });
+};
+
+if (import.meta.vitest !== undefined) {
+  test('isRootObservable', () => {
+    assert.isTrue(
+      isRootObservable(
+        createRootObservable({ initialValue: Optional.some(0) }, () => ({})),
+      ),
+    );
+  });
+}

package/src/core/base/index.mts

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

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

@@ -8,10 +8,11 @@ import {
   type SyncChildObservable,
 } from '../types/index.mjs';
 import {
-  AsyncChildObservableClass,
-  SyncChildObservableClass,
-} from './child-observable-class.mjs';
-import { RootObservableClass } from './root-observable-class.mjs';
+  createAsyncChildObservable,
+  createSyncChildObservable,
+} from './create-child-observable.mjs';
+import { createTryUpdateNotImplemented } from './create-observable-base.mjs';
+import { createRootObservable } from './create-root-observable.mjs';
 
 /**
  * Inheritance
@@ -60,30 +61,37 @@ expectType<Observable<1>, Observable<number>>('<=');
 
 expectType<Observable<number>, Observable<1>>('!<=');
 
-const root = new RootObservableClass({
-  initialValue: Optional.some(0),
-});
+const root = createRootObservable(
+  { initialValue: Optional.some(0) },
+  () => ({}),
+);
 
 expectType<typeof root, RootObservable<number>>('<=');
 
-const syncChild = new SyncChildObservableClass({
-  parents: [root],
-  initialValue: Optional.some(0),
-});
+const syncChild = createSyncChildObservable(
+  {
+    parents: [root],
+    initialValue: Optional.some(0),
+  },
+  createTryUpdateNotImplemented,
+);
 
 expectType<typeof syncChild, SyncChildObservable<number>>('<=');
 
-const asyncChild = new AsyncChildObservableClass({
-  parents: [root],
-  initialValue: Optional.some(0),
-});
+const asyncChild = createAsyncChildObservable(
+  {
+    parents: [root],
+    initialValue: Optional.some(0),
+  },
+  createTryUpdateNotImplemented,
+);
 
 expectType<typeof asyncChild, AsyncChildObservable<number>>('<=');
 
-test('SyncChildObservableClass', () => {
+test('createSyncChildObservable', () => {
   expect(syncChild.depth).toBe(1);
 });
 
-test('AsyncChildObservableClass', () => {
+test('createAsyncChildObservable', () => {
   expect(asyncChild.depth).toBe(1);
 });

package/src/core/combine/combine.mts

@@ -1,6 +1,6 @@
 import { Arr, expectType, Optional } from 'ts-data-forge';
 import { type NonEmptyTuple, type Tuple } from 'ts-type-forge';
-import { SyncChildObservableClass } from '../class/index.mjs';
+import { createSyncChildObservable } from '../base/index.mjs';
 import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
 import {
@@ -11,7 +11,6 @@ import {
   type NonEmptyUnknownList,
   type Observable,
   type SyncChildObservable,
-  type UpdateToken,
   type Wrap,
 } from '../types/index.mjs';
 
@@ -76,9 +75,7 @@ export const combine = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): CombineObservableRefined<OS> =>
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  new CombineObservableClass(
-    parents,
-  ) as unknown as CombineObservableRefined<OS>;
+  createCombineObservable(parents) as unknown as CombineObservableRefined<OS>;
 
 /**
  * Alias for `combine`.
@@ -86,56 +83,57 @@ export const combine = <const OS extends NonEmptyTuple<Observable<unknown>>>(
  */
 export const combineLatest = combine;
 
-class CombineObservableClass<const A extends NonEmptyUnknownList>
-  extends SyncChildObservableClass<A, A>
-  implements CombineObservable<A>
-{
-  constructor(parents: Wrap<A>) {
-    const parentsValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
-      parents,
-      (p) => p.getSnapshot(),
-    );
-
-    // The annotation on `initialValue` is what replaces the type assertion.
-    // `Arr.map` carries a single result element type, so it reports `A[number]`
-    // at every position, and `Tuple.MapTo<A[number], A>` — the uniform mapping
-    // — is *not* assignable back to `A`. The positional
-    // `Readonly<{ [K in keyof A]: A[K] }>` is, and TypeScript accepts the
-    // uniform result into it because the two mapped types share `keyof A`. So
-    // it is the annotation, not an assertion, that records the position-wise
-    // fact the checker cannot derive on its own.
-    const initialValue: Optional<Readonly<{ [K in keyof A]: A[K] }>> =
-      Arr.every(parentsValues, Optional.isSome)
-        ? Optional.some(Arr.map(parentsValues, (c) => c.value))
-        : Optional.none;
-
-    super({
+const createCombineObservable = <const A extends NonEmptyUnknownList>(
+  parents: Wrap<A>,
+): CombineObservable<A> => {
+  const parentsValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
+    parents,
+    (p) => p.getSnapshot(),
+  );
+
+  // The annotation on `initialValue` is what replaces the type assertion.
+  // `Arr.map` carries a single result element type, so it reports `A[number]`
+  // at every position, and `Tuple.MapTo<A[number], A>` — the uniform mapping
+  // — is *not* assignable back to `A`. The positional
+  // `Readonly<{ [K in keyof A]: A[K] }>` is, and TypeScript accepts the
+  // uniform result into it because the two mapped types share `keyof A`. So
+  // it is the annotation, not an assertion, that records the position-wise
+  // fact the checker cannot derive on its own.
+  const initialValue: Optional<Readonly<{ [K in keyof A]: A[K] }>> = Arr.every(
+    parentsValues,
+    Optional.isSome,
+  )
+    ? Optional.some(Arr.map(parentsValues, (c) => c.value))
+    : Optional.none;
+
+  return createSyncChildObservable<A, A>(
+    {
       parents,
       initialValue,
-    });
-  }
-
-  override tryUpdate(updateToken: UpdateToken): void {
-    if (this.parents.every((o) => o.updateToken !== updateToken)) return; // all parents are skipped
-
-    // Same shape-preserving chain as the constructor: `Arr.map` (not the
-    // native one, which drops the tuple shape) into the uniform
-    // `Tuple.MapTo`, then a positional annotation to get back to `A`.
-    const parentValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
-      this.parents,
-      (a) => a.getSnapshot(),
-    );
-
-    if (Arr.every(parentValues, Optional.isSome)) {
-      const nextValue: Readonly<{ [K in keyof A]: A[K] }> = Arr.map(
-        parentValues,
-        (a) => a.value,
-      );
-
-      this.setNext(nextValue, updateToken);
-    }
-  }
-}
+    },
+    ({ setNext }) =>
+      (updateToken) => {
+        if (parents.every((o) => o.updateToken !== updateToken)) return; // all parents are skipped
+
+        // Same shape-preserving chain as the initial value: `Arr.map` (not the
+        // native one, which drops the tuple shape) into the uniform
+        // `Tuple.MapTo`, then a positional annotation to get back to `A`.
+        const parentValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
+          parents,
+          (a) => a.getSnapshot(),
+        );
+
+        if (Arr.every(parentValues, Optional.isSome)) {
+          const nextValue: Readonly<{ [K in keyof A]: A[K] }> = Arr.map(
+            parentValues,
+            (a) => a.value,
+          );
+
+          setNext(nextValue, updateToken);
+        }
+      },
+  );
+};
 
 if (import.meta.vitest !== undefined) {
   test('type test', () => {