synstate 3.3.0 → 4.0.0

package/src/core/create/from-subscribable.test.mts

@@ -0,0 +1,134 @@
+import { Result } from 'ts-data-forge';
+import { take } from '../operators/index.mjs';
+import type { Subscribable } from '../types/index.mjs';
+import { fromSubscribable } from './from-subscribable.mjs';
+
+describe(fromSubscribable, () => {
+  test('complete() unsubscribes from the subscribable once', () => {
+    const { subscribable, emit, unsubscribe } = createManualSubscribable();
+
+    const observable$ = fromSubscribable(subscribable);
+
+    observable$.complete();
+
+    observable$.complete();
+
+    expect(unsubscribe).toHaveBeenCalledExactlyOnceWith();
+
+    emit(1);
+
+    assert.isTrue(observable$.isCompleted);
+  });
+
+  test('dispose() unsubscribes from the subscribable', () => {
+    const { subscribable, unsubscribe } = createManualSubscribable();
+
+    fromSubscribable(subscribable).dispose();
+
+    expect(unsubscribe).toHaveBeenCalledExactlyOnceWith();
+  });
+
+  test('does not unsubscribe when the subscribable completes first', () => {
+    const { subscribable, emit, completeSource, unsubscribe } =
+      createManualSubscribable();
+
+    const observable$ = fromSubscribable(subscribable);
+
+    const mut_history: number[] = [];
+
+    observable$.subscribe((result) => {
+      if (Result.isOk(result)) {
+        mut_history.push(result.value);
+      }
+    });
+
+    emit(1);
+
+    completeSource();
+
+    assert.isTrue(observable$.isCompleted);
+
+    observable$.complete();
+
+    expect(unsubscribe).not.toHaveBeenCalled();
+
+    assert.deepStrictEqual(mut_history, [1]);
+  });
+
+  test('does not unsubscribe when the subscribable completes synchronously during subscribe', () => {
+    const unsubscribe = vi.fn<() => void>();
+
+    const observable$ = fromSubscribable<number>({
+      subscribe: (_onNext, _onError, onComplete) => {
+        onComplete?.();
+
+        return { unsubscribe };
+      },
+    });
+
+    assert.isTrue(observable$.isCompleted);
+
+    expect(unsubscribe).not.toHaveBeenCalled();
+  });
+
+  test('a child that completes leaves the subscribable subscribed until the observable is completed', () => {
+    const { subscribable, emit, unsubscribe } = createManualSubscribable();
+
+    const observable$ = fromSubscribable(subscribable);
+
+    const taken$ = observable$.pipe(take(1));
+
+    taken$.subscribe(() => {});
+
+    emit(1);
+
+    emit(2);
+
+    assert.isTrue(taken$.isCompleted);
+
+    // Completion flows only downstream.
+    assert.isFalse(observable$.isCompleted);
+
+    expect(unsubscribe).not.toHaveBeenCalled();
+
+    observable$.complete();
+
+    expect(unsubscribe).toHaveBeenCalledExactlyOnceWith();
+  });
+});
+
+const createManualSubscribable = (): Readonly<{
+  subscribable: Subscribable<number>;
+  emit: (value: number) => void;
+  completeSource: () => void;
+  unsubscribe: () => void;
+}> => {
+  let mut_onNext: ((value: number) => void) | undefined = undefined;
+
+  let mut_onComplete: (() => void) | undefined = undefined;
+
+  const unsubscribe = vi.fn<() => void>(() => {
+    mut_onNext = undefined;
+
+    mut_onComplete = undefined;
+  });
+
+  return {
+    subscribable: {
+      subscribe: (onNext, _onError, onComplete) => {
+        mut_onNext = onNext;
+
+        mut_onComplete = onComplete;
+
+        return { unsubscribe };
+      },
+    },
+    emit: (value) => {
+      mut_onNext?.(value);
+    },
+    completeSource: () => {
+      mut_onComplete?.();
+    },
+    unsubscribe,
+  };
+};

package/src/core/create/just.mts

@@ -1,5 +1,5 @@
 import { Optional } from 'ts-data-forge';
-import { createRootObservable } from '../base/index.mjs';
+import { RootObservableClass } from '../class/index.mjs';
 import type { InitializedRootObservable } from '../types/index.mjs';
 
 /**
@@ -32,10 +32,9 @@ import type { InitializedRootObservable } from '../types/index.mjs';
  * ```
  */
 export const just = <const A,>(value: A): InitializedRootObservable<A> => {
-  const obs = createRootObservable<A>(
-    { initialValue: Optional.some(value) },
-    () => ({}),
-  );
+  const obs = new RootObservableClass<A>({
+    initialValue: Optional.some(value),
+  });
 
   obs.complete();
 

package/src/core/create/source.mts

@@ -1,5 +1,11 @@
+// Sumi bans classes, `this`, method syntax and writes to `this` outside a
+// `mut_` binding; an observable is a class (`ObservableBaseClass` says why),
+// so those rules are waived here (D-63).
+// @sumi-expect-error-file classes/no-class
+// @sumi-expect-error-file banned-syntax/no-this
+// @sumi-expect-error-file functions/prefer-arrow-function
 import { Arr, Optional } from 'ts-data-forge';
-import { createRootObservable } from '../base/index.mjs';
+import { RootObservableClass } from '../class/index.mjs';
 import type {
   InitializedSourceObservable,
   SourceObservable,
@@ -43,6 +49,13 @@ import type {
  *
  * assert.deepStrictEqual(valueHistory, [1, 2, 3]);
  * ```
+ *
+ * @note Do not call `next` from a subscriber or a projection while another
+ * update is propagating: the write propagates immediately, so subscribers can
+ * see an intermediate state, and it logs a `console.warn` (once per
+ * observable). Derive the value from its source instead —
+ * `const b$ = a$.pipe(map((a) => a * 2))` rather than
+ * `a$.subscribe((a) => { setB(a * 2); })`.
  */
 export function source<const A>(
   initialValue: A,
@@ -51,20 +64,31 @@ export function source<const A>(
 export function source<const A>(): SourceObservable<A>;
 
 export function source<const A>(...args: readonly A[]): SourceObservable<A> {
-  return createRootObservable<A, Readonly<{ next: (nextValue: A) => void }>>(
-    {
+  return new SourceObservableClass<A>(...args);
+}
+
+class SourceObservableClass<A>
+  extends RootObservableClass<A>
+  implements SourceObservable<A>
+{
+  constructor(...args: readonly A[]) {
+    super({
       initialValue: Arr.isNonEmpty(args)
         ? Optional.some(args[0])
         : Optional.none,
-    },
-    ({ startUpdate, isCompleted }) => ({
-      next: (nextValue: A) => {
-        if (isCompleted()) {
-          return;
-        }
+    });
+  }
+
+  // Returns the value held after the call: `nextValue`, or, once completed,
+  // the value already there — `undefined` only on a source that never had
+  // one, whose `next` is typed `void`.
+  next(nextValue: A): A | undefined {
+    if (this.isCompleted) {
+      return Optional.unwrap(this.getSnapshot());
+    }
+
+    this.startUpdate(nextValue);
 
-        startUpdate(nextValue);
-      },
-    }),
-  );
+    return nextValue;
+  }
 }

package/src/core/create/source.test.mts

@@ -0,0 +1,41 @@
+import { expectType } from 'ts-data-forge';
+import type { SourceObservable } from '../types/index.mjs';
+import { source } from './source.mjs';
+
+describe(source, () => {
+  test('`next` returns the value it passed on', () => {
+    const count$ = source<number>(0);
+
+    assert.strictEqual(count$.next(1), 1);
+
+    assert.strictEqual(count$.getSnapshot().value, 1);
+  });
+
+  test('once completed, `next` passes nothing on and returns the value held', () => {
+    const count$ = source<number>(0);
+
+    const mut_seen: number[] = [];
+
+    count$.subscribe((value) => {
+      mut_seen.push(value);
+    });
+
+    count$.next(1);
+
+    count$.complete();
+
+    assert.strictEqual(count$.next(2), 1);
+
+    assert.deepStrictEqual(mut_seen, [0, 1]);
+  });
+
+  test('`next` returns the value only on a source with an initial value', () => {
+    const passed = source<number>(0).next(1);
+
+    expectType<typeof passed, number>('=');
+
+    assert.strictEqual(passed, 1);
+
+    expectType<SourceObservable<number>['next'], (value: number) => void>('=');
+  });
+});

package/src/core/create/timer.mts

@@ -1,5 +1,12 @@
+// Sumi bans classes, `this`, method syntax and writes to `this` outside a
+// `mut_` binding; an observable is a class (`ObservableBaseClass` says why),
+// so those rules are waived here (D-63).
+// @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 { Optional } from 'ts-data-forge';
-import { createRootObservable } from '../base/index.mjs';
+import { RootObservableClass } from '../class/index.mjs';
 import type { TimerId, TimerObservable } from '../types/index.mjs';
 
 /**
@@ -44,46 +51,58 @@ export const timer = (
     startManually?: boolean;
   }>,
 ): TimerObservable => {
-  let mut_timerId: TimerId | undefined = undefined;
+  const observable = new TimerObservableClass(milliSeconds);
 
-  let mut_isStarted = false;
+  if (!(options?.startManually ?? false)) {
+    observable.start();
+  }
 
-  const resetTimer = (): void => {
-    if (mut_timerId !== undefined) {
-      clearTimeout(mut_timerId);
-    }
-  };
+  return observable;
+};
 
-  const observable = createRootObservable<0, Readonly<{ start: () => void }>>(
-    { initialValue: Optional.none, onComplete: resetTimer },
-    ({ startUpdate, isCompleted, complete }) => ({
-      start: () => {
-        if (mut_isStarted) {
-          console.warn('cannot start twice');
+class TimerObservableClass
+  extends RootObservableClass<0>
+  implements TimerObservable
+{
+  readonly #milliSeconds: number;
+  #mut_timerId: TimerId | undefined;
+  #mut_isStarted: boolean;
 
-          return;
-        }
+  constructor(milliSeconds: number) {
+    super({ initialValue: Optional.none });
 
-        mut_isStarted = true;
+    this.#milliSeconds = milliSeconds;
 
-        if (isCompleted()) {
-          console.warn('cannot restart stopped TimerObservable');
+    this.#mut_timerId = undefined;
 
-          return;
-        }
+    this.#mut_isStarted = false;
+  }
 
-        mut_timerId = setTimeout(() => {
-          startUpdate(0);
+  start(): void {
+    if (this.#mut_isStarted) {
+      console.warn('cannot start twice');
 
-          complete();
-        }, milliSeconds);
-      },
-    }),
-  );
+      return;
+    }
 
-  if (!(options?.startManually ?? false)) {
-    observable.start();
+    this.#mut_isStarted = true;
+
+    if (this.isCompleted) {
+      console.warn('cannot restart stopped TimerObservable');
+
+      return;
+    }
+
+    this.#mut_timerId = setTimeout(() => {
+      this.startUpdate(0);
+
+      this.complete();
+    }, this.#milliSeconds);
   }
 
-  return observable;
-};
+  protected override teardown(): void {
+    if (this.#mut_timerId !== undefined) {
+      clearTimeout(this.#mut_timerId);
+    }
+  }
+}

package/src/core/index.mts

@@ -1,5 +1,7 @@
+export * from './authoring.mjs';
 export * from './combine/index.mjs';
 export * from './create/index.mjs';
 export * from './operators/index.mjs';
 export * from './predefined/index.mjs';
+export * from './scope/index.mjs';
 export * from './types/index.mjs';

package/src/core/operators/audit.mts

@@ -1,10 +1,18 @@
+// Sumi bans classes, `this`, method syntax and writes to `this` outside a
+// `mut_` binding; an observable is a class (`ObservableBaseClass` says why),
+// so those rules are waived here (D-63).
+// @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 { Optional } from 'ts-data-forge';
-import { createAsyncChildObservable } from '../base/index.mjs';
+import { AsyncChildObservableClass } from '../class/index.mjs';
 import type {
   AuditOperatorObservable,
   KeepInitialValueOperator,
   Observable,
   TimerId,
+  UpdateToken,
 } from '../types/index.mjs';
 
 /**
@@ -12,6 +20,9 @@ import type {
  *
  * Unlike `throttle` which emits the first value, `audit` emits the last value.
  *
+ * Completing it, or its source completing, passes on the value its timer is
+ * still holding before the completion; `dispose()` drops that value.
+ *
  * @template A - The type of values from the source
  * @param milliSeconds - The audit time window in milliseconds
  * @returns An operator that audits emissions from the observable
@@ -106,55 +117,78 @@ export const audit = <A,>(
 ): KeepInitialValueOperator<A, A> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
   ((parentObservable) =>
-    createAuditObservable(
+    new AuditObservableClass(
       parentObservable,
       milliSeconds,
     )) as KeepInitialValueOperator<A, A>;
 
-const createAuditObservable = <A,>(
-  parentObservable: Observable<A>,
-  milliSeconds: number,
-): AuditOperatorObservable<A> => {
-  let mut_timerId: TimerId | undefined = undefined;
-
-  let mut_isSkipping = false;
+class AuditObservableClass<A>
+  extends AsyncChildObservableClass<A, readonly [A]>
+  implements AuditOperatorObservable<A>
+{
+  readonly #milliSeconds: number;
 
-  const resetTimer = (): void => {
-    if (mut_timerId !== undefined) {
-      clearTimeout(mut_timerId);
-    }
-  };
+  /** Set while a window is open; its end passes on the latest value. */
+  #mut_timerId: TimerId | undefined;
 
-  return createAsyncChildObservable(
-    {
+  constructor(parentObservable: Observable<A>, milliSeconds: number) {
+    super({
       parents: [parentObservable],
       initialValue: parentObservable.getSnapshot(),
-      onComplete: resetTimer,
-    },
-    ({ startUpdate }) =>
-      (updateToken) => {
-        if (
-          mut_isSkipping ||
-          parentObservable.updateToken !== updateToken ||
-          Optional.isNone(parentObservable.getSnapshot())
-        ) {
-          return; // skip update
-        }
-
-        // set timer
-        mut_isSkipping = true;
-
-        mut_timerId = setTimeout(() => {
-          const sn = parentObservable.getSnapshot();
-
-          if (Optional.isNone(sn)) {
-            return;
-          }
-
-          startUpdate(sn.value);
-
-          mut_isSkipping = false;
-        }, milliSeconds);
-      },
-  );
-};
+    });
+
+    this.#mut_timerId = undefined;
+
+    this.#milliSeconds = milliSeconds;
+
+    this.attach();
+  }
+
+  /** Ends the open window, passing on the latest value of the source. */
+  #emitLatest(): void {
+    this.#mut_timerId = undefined;
+
+    const sn = this.parents[0].getSnapshot();
+
+    if (Optional.isSome(sn)) {
+      this.startUpdate(sn.value);
+    }
+  }
+
+  override tryUpdate(updateToken: UpdateToken): void {
+    const par = this.parents[0];
+
+    if (
+      this.#mut_timerId !== undefined ||
+      par.updateToken !== updateToken ||
+      Optional.isNone(par.getSnapshot())
+    ) {
+      return; // skip update
+    }
+
+    // set timer
+    this.#mut_timerId = setTimeout(() => {
+      this.#emitLatest();
+    }, this.#milliSeconds);
+  }
+
+  protected override flush(): void {
+    if (this.#mut_timerId === undefined) {
+      return;
+    }
+
+    clearTimeout(this.#mut_timerId);
+
+    this.#emitLatest();
+  }
+
+  protected override teardown(): void {
+    if (this.#mut_timerId === undefined) {
+      return;
+    }
+
+    clearTimeout(this.#mut_timerId);
+
+    this.#mut_timerId = undefined;
+  }
+}

package/src/core/operators/debounce-audit-complete.test.mts

@@ -0,0 +1,121 @@
+import { source } from '../create/index.mjs';
+import type {
+  KeepInitialValueOperator,
+  Observable,
+  SourceObservable,
+} from '../types/index.mjs';
+import { audit } from './audit.mjs';
+import { debounce } from './debounce.mjs';
+
+const operators: readonly (readonly [
+  string,
+  (milliSeconds: number) => KeepInitialValueOperator<number, number>,
+])[] = [
+  ['debounce', debounce],
+  ['audit', audit],
+] as const;
+
+describe.each(operators)('%s', (_name, operator) => {
+  const setup = (): Readonly<{
+    source$: SourceObservable<number>;
+    operated$: Observable<number>;
+    history: readonly string[];
+  }> => {
+    const source$ = source<number>();
+
+    const operated$ = source$.pipe(operator(100));
+
+    const mut_history: string[] = [];
+
+    operated$.subscribe(
+      (v) => {
+        mut_history.push(`next ${v}`);
+      },
+      () => {
+        mut_history.push('complete');
+      },
+    );
+
+    return { source$, operated$, history: mut_history };
+  };
+
+  test('passes on the pending value, then completes, when the source completes within the window', () => {
+    vi.useFakeTimers();
+
+    const { source$, operated$, history } = setup();
+
+    source$.next(1);
+
+    source$.next(2);
+
+    source$.complete();
+
+    assert.deepStrictEqual(history, ['next 2', 'complete']);
+
+    assert.isTrue(operated$.isCompleted);
+
+    vi.runAllTimers();
+
+    assert.deepStrictEqual(history, ['next 2', 'complete']);
+
+    vi.useRealTimers();
+  });
+
+  test('passes on the pending value, then completes, when it is completed itself', () => {
+    vi.useFakeTimers();
+
+    const { source$, operated$, history } = setup();
+
+    source$.next(1);
+
+    operated$.complete();
+
+    assert.deepStrictEqual(history, ['next 1', 'complete']);
+
+    vi.runAllTimers();
+
+    assert.deepStrictEqual(history, ['next 1', 'complete']);
+
+    vi.useRealTimers();
+  });
+
+  test('completes without emitting when nothing is pending', () => {
+    vi.useFakeTimers();
+
+    const { source$, operated$, history } = setup();
+
+    source$.next(1);
+
+    vi.runAllTimers();
+
+    assert.deepStrictEqual(history, ['next 1']);
+
+    operated$.complete();
+
+    assert.deepStrictEqual(history, ['next 1', 'complete']);
+
+    vi.useRealTimers();
+  });
+
+  test('drops the pending value when it is disposed', () => {
+    vi.useFakeTimers();
+
+    const { source$, operated$, history } = setup();
+
+    source$.next(1);
+
+    operated$.dispose();
+
+    assert.deepStrictEqual(history, ['complete']);
+
+    assert.isTrue(operated$.isCompleted);
+
+    vi.runAllTimers();
+
+    assert.deepStrictEqual(history, ['complete']);
+
+    assert.isFalse(source$.isCompleted);
+
+    vi.useRealTimers();
+  });
+});