synstate 3.4.0 → 4.0.0

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();
+  });
+});

package/src/core/operators/debounce.mts

@@ -1,16 +1,27 @@
+// 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 {
   DebounceOperatorObservable,
   KeepInitialValueOperator,
   Observable,
   TimerId,
+  UpdateToken,
 } from '../types/index.mjs';
 
 /**
  * Delays emissions from the source observable until a specified time has passed without another emission.
  * Useful for handling user input events like typing or scrolling.
  *
+ * 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 debounce duration in milliseconds
  * @returns An operator that debounces the observable
@@ -97,50 +108,80 @@ export const debounce = <A,>(
 ): KeepInitialValueOperator<A, A> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
   ((parentObservable) =>
-    createDebounceObservable(
+    new DebounceObservableClass(
       parentObservable,
       milliSeconds,
     )) as KeepInitialValueOperator<A, A>;
 
-const createDebounceObservable = <A,>(
-  parentObservable: Observable<A>,
-  milliSeconds: number,
-): DebounceOperatorObservable<A> => {
-  let mut_timerId: TimerId | undefined = undefined;
+class DebounceObservableClass<A>
+  extends AsyncChildObservableClass<A, readonly [A]>
+  implements DebounceOperatorObservable<A>
+{
+  readonly #milliSeconds: number;
+  #mut_timerId: TimerId | undefined;
 
-  const resetTimer = (): void => {
-    if (mut_timerId !== undefined) {
-      clearTimeout(mut_timerId);
-    }
-  };
+  /** The value the running timer will pass on. */
+  #mut_pending: Optional<A>;
 
-  return createAsyncChildObservable(
-    {
+  constructor(parentObservable: Observable<A>, milliSeconds: number) {
+    super({
       parents: [parentObservable],
       initialValue: parentObservable.getSnapshot(),
-      onComplete: resetTimer,
-    },
-    ({ startUpdate }) =>
-      (updateToken) => {
-        const sn = parentObservable.getSnapshot();
-
-        if (
-          parentObservable.updateToken !== updateToken ||
-          Optional.isNone(sn)
-        ) {
-          return; // skip update
-        }
-
-        resetTimer();
-
-        // set timer
-        mut_timerId = setTimeout(() => {
-          if (Optional.isNone(sn)) {
-            return;
-          }
-
-          startUpdate(sn.value);
-        }, milliSeconds);
-      },
-  );
-};
+    });
+
+    this.#mut_timerId = undefined;
+
+    this.#mut_pending = Optional.none;
+
+    this.#milliSeconds = milliSeconds;
+
+    this.attach();
+  }
+
+  #resetTimer(): void {
+    if (this.#mut_timerId !== undefined) {
+      clearTimeout(this.#mut_timerId);
+
+      this.#mut_timerId = undefined;
+    }
+
+    this.#mut_pending = Optional.none;
+  }
+
+  override tryUpdate(updateToken: UpdateToken): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (par.updateToken !== updateToken || Optional.isNone(sn)) {
+      return; // skip update
+    }
+
+    this.#resetTimer();
+
+    this.#mut_pending = sn;
+
+    // set timer
+    this.#mut_timerId = setTimeout(() => {
+      this.#mut_timerId = undefined;
+
+      this.#mut_pending = Optional.none;
+
+      this.startUpdate(sn.value);
+    }, this.#milliSeconds);
+  }
+
+  protected override flush(): void {
+    const pending = this.#mut_pending;
+
+    this.#resetTimer();
+
+    if (Optional.isSome(pending)) {
+      this.startUpdate(pending.value);
+    }
+  }
+
+  protected override teardown(): void {
+    this.#resetTimer();
+  }
+}

package/src/core/operators/filter.mts

@@ -1,3 +1,10 @@
+// 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 {
   asSafeUint,
   expectType,
@@ -7,13 +14,14 @@ import {
   pipe,
   SafeUint,
 } from 'ts-data-forge';
-import { createSyncChildObservable } from '../base/index.mjs';
+import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
 import type {
   DropInitialValueOperator,
   FilterOperatorObservable,
   InitializedObservable,
   Observable,
+  UpdateToken,
 } from '../types/index.mjs';
 import { withInitialValue } from './with-initial-value.mjs';
 
@@ -83,15 +91,21 @@ export function filter<A>(
   predicate: (value: A, index: SafeUint | -1) => boolean,
 ): DropInitialValueOperator<A, A> {
   return (parentObservable) =>
-    createFilterObservable(parentObservable, predicate);
+    new FilterObservableClass(parentObservable, predicate);
 }
 
-const createFilterObservable = <A,>(
-  parentObservable: Observable<A>,
-  predicate: (x: A, index: SafeUint | -1) => boolean,
-): FilterOperatorObservable<A> =>
-  createSyncChildObservable(
-    {
+class FilterObservableClass<A>
+  extends SyncChildObservableClass<A, readonly [A]>
+  implements FilterOperatorObservable<A>
+{
+  readonly #predicate: (x: A, index: SafeUint | -1) => boolean;
+  #mut_index: SafeUint | -1;
+
+  constructor(
+    parentObservable: Observable<A>,
+    predicate: (x: A, index: SafeUint | -1) => boolean,
+  ) {
+    super({
       parents: [parentObservable],
       initialValue: pipe(parentObservable.getSnapshot()).map((sn) =>
         Optional.isNone(sn)
@@ -100,29 +114,32 @@ const createFilterObservable = <A,>(
             ? sn
             : Optional.none,
       ).value,
-    },
-    ({ setNext }) => {
-      let mut_index: SafeUint | -1 = -1;
-
-      return (updateToken) => {
-        const sn = parentObservable.getSnapshot();
-
-        if (
-          parentObservable.updateToken !== updateToken ||
-          Optional.isNone(sn)
-        ) {
-          return; // skip update
-        }
-
-        mut_index =
-          mut_index === -1 ? asSafeUint(0) : SafeUint.add(1, mut_index);
-
-        if (predicate(sn.value, mut_index)) {
-          setNext(sn.value, updateToken);
-        }
-      };
-    },
-  );
+    });
+
+    this.#mut_index = -1;
+
+    this.#predicate = predicate;
+
+    this.attach();
+  }
+
+  override tryUpdate(updateToken: UpdateToken): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (par.updateToken !== updateToken || Optional.isNone(sn)) {
+      return; // skip update
+    }
+
+    this.#mut_index =
+      this.#mut_index === -1 ? asSafeUint(0) : SafeUint.add(1, this.#mut_index);
+
+    if (this.#predicate(sn.value, this.#mut_index)) {
+      this.setNext(sn.value, updateToken);
+    }
+  }
+}
 
 if (import.meta.vitest !== undefined) {
   test('type test', () => {

package/src/core/operators/index.mts

@@ -11,6 +11,7 @@ export * from './skip-while.mjs';
 export * from './switch-map.mjs';
 export * from './take-until.mjs';
 export * from './take-while.mjs';
+export * from './take.mjs';
 export * from './throttle.mjs';
 export * from './with-buffered-from.mjs';
 export * from './with-current-value-from.mjs';