@dxos/async 0.8.4-main.f9ba587 → 0.8.4-main.fcc0d83b33

package/package.json

@@ -1,27 +1,28 @@
 {
   "name": "@dxos/async",
-  "version": "0.8.4-main.f9ba587",
+  "version": "0.8.4-main.fcc0d83b33",
   "description": "Async utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
   "sideEffects": true,
   "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": {
         "require": "./dist/lib/node/index.cjs",
         "default": "./dist/lib/node-esm/index.mjs"
-      },
-      "types": "./dist/types/src/index.d.ts"
+      }
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
@@ -29,12 +30,12 @@
   "dependencies": {
     "zen-observable": "^0.10.0",
     "zen-push": "^0.3.1",
-    "@dxos/context": "0.8.4-main.f9ba587",
-    "@dxos/debug": "0.8.4-main.f9ba587",
-    "@dxos/invariant": "0.8.4-main.f9ba587",
-    "@dxos/log": "0.8.4-main.f9ba587",
-    "@dxos/node-std": "0.8.4-main.f9ba587",
-    "@dxos/util": "0.8.4-main.f9ba587"
+    "@dxos/context": "0.8.4-main.fcc0d83b33",
+    "@dxos/debug": "0.8.4-main.fcc0d83b33",
+    "@dxos/invariant": "0.8.4-main.fcc0d83b33",
+    "@dxos/log": "0.8.4-main.fcc0d83b33",
+    "@dxos/node-std": "0.8.4-main.fcc0d83b33",
+    "@dxos/util": "0.8.4-main.fcc0d83b33"
   },
   "devDependencies": {
     "@types/zen-observable": "^0.8.3"

package/src/callback.ts

@@ -2,12 +2,12 @@
 // Copyright 2020 DXOS.org
 //
 
+export type Awaited<T> = T extends Promise<infer U> ? U : T;
+
 /**
  * Helper to convert a callback based API into a promise based API.
  */
-export const createPromiseFromCallback = <T = void>(
-  run: (cb: (error?: Error, value?: T) => void) => void,
-): Promise<T> =>
+export const promiseFromCallback = <T = void>(run: (cb: (error?: Error, value?: T) => void) => void): Promise<T> =>
   new Promise((resolve, reject) => {
     run((error, value) => {
       if (error) {

package/src/chain.ts

@@ -7,7 +7,7 @@ type Transform = (...args: any) => Promise<any>;
 /**
  * Async reducer iteratively applies functions to the given array of elements.
  */
-export const asyncChain =
+export const chain =
   <T>(chain: Transform[]) =>
   async (elements: Promise<T[]>) => {
     let result = await elements;

package/src/cleanup.ts

@@ -10,9 +10,12 @@ export type CleanupFn = () => void;
  * Combine multiple cleanup functions into a single cleanup function.
  * Can be used in effect hooks in conjunction with `addEventListener`.
  */
-export const combine = (...cleanupFns: (CleanupFn | CleanupFn[])[]): CleanupFn => {
+export const combine = (...cleanupFns: (boolean | undefined | CleanupFn | CleanupFn[])[]): CleanupFn => {
   return () => {
-    cleanupFns.flat().forEach((cleanupFn) => cleanupFn());
+    cleanupFns
+      .flat()
+      .filter((f): f is CleanupFn => typeof f === 'function')
+      .forEach((cleanupFn) => cleanupFn());
   };
 };
 
@@ -38,21 +41,21 @@ type EventMap<T> = T extends Window
  * Add the event listener and return a cleanup function.
  * Can be used in effect hooks in conjunction with `combine`.
  */
-export function addEventListener<T extends EventTarget, K extends keyof EventMap<T>>(
+export const addEventListener = <T extends EventTarget, K extends keyof EventMap<T>>(
   target: T,
   type: K,
   listener: (this: T, ev: EventMap<T>[K]) => any,
   options?: boolean | AddEventListenerOptions,
-): CleanupFn {
+): CleanupFn => {
   target.addEventListener(type as string, listener as EventListener, options);
   return () => target.removeEventListener(type as string, listener as EventListener, options);
-}
+};
 
 export class SubscriptionList {
   private readonly _cleanups: CleanupFn[] = [];
 
-  add(cb: CleanupFn): this {
-    this._cleanups.push(cb);
+  add(...cb: CleanupFn[]): this {
+    this._cleanups.push(...cb);
     return this;
   }
 

package/src/debounce.test.ts

@@ -4,25 +4,82 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { debounce } from './debounce';
+import { debounce, throttle } from './debounce';
 import { sleep } from './timeout';
 
+describe('throttle', () => {
+  test('throttles function calls', async () => {
+    let count = 0;
+    const fn = throttle(() => count++, 100);
+
+    // First call should execute immediately.
+    fn();
+    expect(count).toBe(1);
+
+    // Second call within throttle window should not execute.
+    fn();
+    expect(count).toBe(1);
+
+    // Wait for throttle window to pass.
+    await sleep(150);
+
+    // Next call should execute.
+    fn();
+    expect(count).toBe(2);
+  });
+
+  test('passes arguments to throttled function', async () => {
+    let lastArgs: any[] = [];
+    const fn = throttle((...args: any[]) => {
+      lastArgs = args;
+    }, 100);
+
+    fn('test', 123);
+    expect(lastArgs).toEqual(['test', 123]);
+
+    // Call with different args within throttle window.
+    fn('different', 456);
+    expect(lastArgs).toEqual(['test', 123]); // Should not update.
+
+    await sleep(150);
+    fn('new', 789);
+    expect(lastArgs).toEqual(['new', 789]);
+  });
+
+  test('handles multiple rapid calls', async () => {
+    let count = 0;
+    const fn = throttle(() => count++, 100);
+
+    // Make multiple rapid calls.
+    for (let i = 0; i < 5; i++) {
+      fn();
+    }
+    expect(count).toBe(1); // Only first call should execute.
+
+    await sleep(150);
+    expect(count).toBe(1); // Still only one execution.
+
+    fn();
+    expect(count).toBe(2); // Next call after wait should execute.
+  });
+});
+
 describe('debounce', () => {
   test('debounces function calls', async () => {
     let count = 0;
     const fn = debounce(() => count++, 100);
 
-    // First call should not execute immediately
+    // First call should not execute immediately.
     fn();
     expect(count).toBe(0);
 
-    // Second call should reset the timer
+    // Second call should reset the timer.
     fn();
     expect(count).toBe(0);
 
-    // Wait for debounce window to pass
+    // Wait for debounce window to pass.
     await sleep(150);
-    expect(count).toBe(1); // Only the last call should execute
+    expect(count).toBe(1); // Only the last call should execute.
   });
 
   test('passes arguments to debounced function', async () => {
@@ -32,27 +89,27 @@ describe('debounce', () => {
     }, 100);
 
     fn('test', 123);
-    expect(lastArgs).toEqual([]); // Should not execute immediately
+    expect(lastArgs).toEqual([]); // Should not execute immediately.
 
-    // Call with different args
+    // Call with different args.
     fn('different', 456);
-    expect(lastArgs).toEqual([]); // Should not execute immediately
+    expect(lastArgs).toEqual([]); // Should not execute immediately.
 
     await sleep(150);
-    expect(lastArgs).toEqual(['different', 456]); // Should execute with last args
+    expect(lastArgs).toEqual(['different', 456]); // Should execute with last args.
   });
 
   test('handles multiple rapid calls', async () => {
     let count = 0;
     const fn = debounce(() => count++, 100);
 
-    // Make multiple rapid calls
+    // Make multiple rapid calls.
     for (let i = 0; i < 5; i++) {
       fn();
     }
-    expect(count).toBe(0); // Should not execute immediately
+    expect(count).toBe(0); // Should not execute immediately.
 
     await sleep(150);
-    expect(count).toBe(1); // Should execute only once after wait
+    expect(count).toBe(1); // Should execute only once after wait.
   });
 });

package/src/debounce.ts

@@ -2,28 +2,102 @@
 // Copyright 2023 DXOS.org
 //
 
-import { throttle } from './throttle';
+type Callback = (...args: any[]) => void;
 
 /**
- * Debounce callback.
+ * Delay callback execution by a specified time.
+ * Unlike debounce, subsequent calls during the delay period are ignored.
+ *
+ * @param cb Callback to invoke.
+ * @param delay Time to wait before invoking the callback.
+ * @returns A new function that schedules the callback once and ignores subsequent calls until executed.
  */
-export const debounce = (cb: (...args: any[]) => void, wait = 100): ((...args: any[]) => void) => {
+export const delay = <F extends Callback>(cb: F, delay = 100): F => {
+  let pending = false;
+  return ((...args: any[]) => {
+    if (pending) {
+      return;
+    }
+
+    pending = true;
+    setTimeout(() => {
+      try {
+        cb(...args);
+      } finally {
+        pending = false;
+      }
+    }, delay);
+  }) as F;
+};
+
+/**
+ * Debounce callback: delays execution until calls stop.
+ * Each new call resets the timer, so the callback fires only after the delay elapses with no further calls (trailing-edge).
+ * Use when you want to react to the end of a burst of events (e.g. user stops typing).
+ *
+ * @param cb Callback to invoke.
+ * @param delay Idle time (ms) to wait after the last call before invoking.
+ * @returns Wrapped function that postpones invocation until activity ceases.
+ */
+export const debounce = <F extends Callback>(cb: F, delay = 100): F => {
   let t: ReturnType<typeof setTimeout>;
-  return (...args: any[]) => {
+  return ((...args: any[]) => {
     clearTimeout(t);
-    t = setTimeout(() => cb(...args), wait);
-  };
+    t = setTimeout(() => cb(...args), delay);
+  }) as F;
+};
+
+/**
+ * Throttle callback: limits execution to at most once per interval.
+ * The callback fires immediately on the first call;
+ * subsequent calls within the same interval are dropped (leading-edge).
+ * Use when you need regular updates at a bounded rate (e.g. scroll or resize handlers).
+ *
+ * @param cb Callback to invoke.
+ * @param delay Minimum interval (ms) between successive invocations.
+ * @returns Wrapped function that rate-limits invocations.
+ */
+export const throttle = <F extends Callback>(cb: F, delay = 100): F => {
+  let lastCall = 0;
+  return ((...args: any[]) => {
+    const now = Date.now();
+    if (now - lastCall >= delay) {
+      cb(...args);
+      lastCall = now;
+    }
+  }) as F;
 };
 
 /**
  * Debounce and throttle callback.
+ * Executes immediately on the first call (throttle), prevents calls during the throttle window,
+ * and ensures a final call happens after activity stops (debounce).
+ *
+ * @param cb Callback to invoke.
+ * @param delay Time window for both throttle and debounce.
+ * @returns A new function that combines throttle and debounce behavior.
  */
-export const debounceAndThrottle = (cb: (...args: any[]) => void, wait = 100): ((...args: any[]) => void) => {
-  const debounced = debounce(cb, wait);
-  const throttled = throttle(cb, wait);
-
-  return (...args: any[]) => {
-    debounced(...args);
-    throttled(...args);
-  };
+export const debounceAndThrottle = <F extends Callback>(cb: F, delay = 100): F => {
+  let timeout: ReturnType<typeof setTimeout>;
+  let lastCall = 0;
+
+  return ((...args: any[]) => {
+    const now = Date.now();
+    const delta = now - lastCall;
+
+    // Clear any pending debounced call.
+    clearTimeout(timeout);
+
+    // Throttle: execute immediately if enough time has passed.
+    if (delta >= delay) {
+      cb(...args);
+      lastCall = now;
+    } else {
+      // Debounce: schedule to execute after the remaining time.
+      timeout = setTimeout(() => {
+        cb(...args);
+        lastCall = Date.now();
+      }, delay - delta);
+    }
+  }) as F;
 };

package/src/event-emitter.test.ts

@@ -6,8 +6,8 @@ import { EventEmitter } from 'node:events';
 import { describe, expect, test } from 'vitest';
 
 import { onEvent, waitForEvent } from './event-emitter';
-import { latch } from './latch';
 import { asyncTimeout } from './timeout';
+import { latch } from './trigger';
 
 describe('event-emitter', () => {
   test('onEvent', async () => {

package/src/index.ts

@@ -9,22 +9,17 @@ export * from './debounce';
 export * from './errors';
 export * from './event-emitter';
 export * from './events';
-export * from './latch';
 export * from './mutex';
 export * from './observable';
 export * from './observable-value';
 export * from './persistent-lifecycle';
 export * from './push-iterable';
-export * from './sink';
 export * from './stream-to-array';
 export * from './task-scheduling';
 export * from './test-stream';
 export * from './testing';
-export * from './throttle';
 export * from './timeout';
 export * from './timer';
 export * from './track-leaks';
 export * from './trigger';
-export * from './types';
-export * from './until';
 export * from './update-scheduler';

package/src/observable-value.test.ts

@@ -5,12 +5,12 @@
 import { describe, expect, test } from 'vitest';
 
 import { type AsyncEvents, TimeoutError } from './errors';
-import { latch } from './latch';
 import {
   type CancellableObservable,
   type CancellableObservableEvents,
   CancellableObservableProvider,
 } from './observable-value';
+import { latch } from './trigger';
 
 interface ConnectionEvents extends AsyncEvents, CancellableObservableEvents {
   onConnected(connectionId: string): void;

package/src/observable-value.ts

@@ -66,8 +66,10 @@ export interface CancellableObservableEvents {
 /**
  * @deprecated
  */
-export interface CancellableObservable<Events extends CancellableObservableEvents, Value = unknown>
-  extends ObservableValue<Events, Value> {
+export interface CancellableObservable<
+  Events extends CancellableObservableEvents,
+  Value = unknown,
+> extends ObservableValue<Events, Value> {
   cancel(): Promise<void>;
 }
 

package/src/persistent-lifecycle.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { describe, expect, test, onTestFinished } from 'vitest';
+import { describe, expect, onTestFinished, test } from 'vitest';
 
 import { log } from '@dxos/log';
 

package/src/persistent-lifecycle.ts

@@ -13,7 +13,7 @@ import { sleep } from './timeout';
 const INIT_RESTART_DELAY = 100;
 const DEFAULT_MAX_RESTART_DELAY = 5000;
 
-export type PersistentLifecycleParams<T> = {
+export type PersistentLifecycleProps<T> = {
   /**
    * Create connection.
    * If promise resolves successfully, connection is considered established.
@@ -51,7 +51,7 @@ export class PersistentLifecycle<T> extends Resource {
   private _restartTask?: DeferredTask = undefined;
   private _restartAfter = 0;
 
-  constructor({ start, stop, onRestart, maxRestartDelay = DEFAULT_MAX_RESTART_DELAY }: PersistentLifecycleParams<T>) {
+  constructor({ start, stop, onRestart, maxRestartDelay = DEFAULT_MAX_RESTART_DELAY }: PersistentLifecycleProps<T>) {
     super();
     this._start = start;
     this._stop = stop;

package/src/task-scheduling.ts

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import { ContextDisposedError, type Context } from '@dxos/context';
+import { Context, ContextDisposedError } from '@dxos/context';
 import { StackTrace } from '@dxos/debug';
 import { type MaybePromise } from '@dxos/util';
 
@@ -77,6 +77,100 @@ export class DeferredTask {
   }
 }
 
+// TODO(dmaretskyi): Protyping this an alternative API to DeferredTask.
+export class AsyncTask {
+  #callback: () => Promise<void>;
+  #ctx?: Context = undefined;
+
+  #scheduled = false;
+  #currentTask: Promise<void> | null = null; // Can't be rejected.
+  #nextTask = new Trigger();
+
+  constructor(callback: () => Promise<void>) {
+    this.#callback = callback;
+  }
+
+  get scheduled() {
+    return this.#scheduled;
+  }
+
+  /**
+   * Context of the resource that owns the task.
+   * When the context is disposed, the task is cancelled and cannot be scheduled again.
+   */
+  open(): void {
+    this.#ctx = new Context();
+  }
+
+  /**
+   * Closes the task and waits for it to finish if it is running.
+   */
+  async close(): Promise<void> {
+    await this.#ctx?.dispose();
+    await this.join();
+    this.#ctx = undefined;
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.close();
+  }
+
+  /**
+   * Schedule the task to run asynchronously.
+   */
+  // TODO(dmaretskyi): Add scheduleAt. Where the earlier time will override the later one.
+  schedule(): void {
+    if (!this.#ctx || this.#ctx.disposed) {
+      throw new Error('AsyncTask not open');
+    }
+
+    if (this.#scheduled) {
+      return; // Already scheduled.
+    }
+
+    scheduleTask(this.#ctx, async () => {
+      // The previous task might still be running, so we need to wait for it to finish.
+      await this.#currentTask; // Can't be rejected.
+
+      if (!this.#ctx || this.#ctx.disposed) {
+        return;
+      }
+
+      // Reset the flag. New tasks can now be scheduled. They would wait for the callback to finish.
+      this.#scheduled = false;
+      const completionTrigger = this.#nextTask;
+      this.#nextTask = new Trigger(); // Re-create the trigger as opposed to resetting it since there might be listeners waiting for it.
+
+      // Store the promise so that new tasks could wait for this one to finish.
+      this.#currentTask = runInContextAsync(this.#ctx, () => this.#callback()).then(() => {
+        completionTrigger.wake();
+      });
+    });
+
+    this.#scheduled = true;
+  }
+
+  /**
+   * Schedule the task to run and wait for it to finish.
+   */
+  async runBlocking(): Promise<void> {
+    if (this.#ctx?.disposed) {
+      throw new ContextDisposedError();
+    }
+
+    this.schedule();
+    await this.#nextTask.wait();
+  }
+
+  /**
+   * Waits for the current task to finish if it is running.
+   * Does not schedule a new task.
+   */
+  async join(): Promise<void> {
+    await this.#currentTask;
+  }
+}
+
 export const runInContext = (ctx: Context, fn: () => void) => {
   try {
     fn();

package/src/testing.test.ts

@@ -6,7 +6,8 @@ import { describe, expect, test } from 'vitest';
 
 import { expectToThrow, raise } from '@dxos/debug';
 
-import { waitForCondition } from './testing';
+import { until, waitForCondition } from './testing';
+import { sleep } from './timeout';
 
 describe('waitForCondition', () => {
   test('succeeds', async () => {
@@ -27,3 +28,42 @@ describe('waitForCondition', () => {
     ).rejects.toThrow('test');
   });
 });
+
+describe('until', () => {
+  test('success', async () => {
+    const value = await until<number>(async (resolve) => {
+      await sleep(100);
+      resolve(100);
+      return 1;
+    });
+
+    expect(value).to.equal(100);
+  });
+
+  test('error', async () => {
+    await expect(async () => {
+      await until(async (resolve, reject) => {
+        await sleep(100);
+        reject(new Error());
+      });
+    }).rejects.toThrowError();
+  });
+
+  test('catch', async () => {
+    await expect(async () => {
+      await until(async () => {
+        await sleep(100);
+        throw new Error();
+      });
+    }).rejects.toThrowError();
+  });
+
+  test('timeout', async () => {
+    await expect(async () => {
+      await until(async (resolve) => {
+        await sleep(500);
+        resolve();
+      }, 100); // Timeout before complete.
+    }).rejects.toThrowError();
+  });
+});

package/src/testing.ts

@@ -54,3 +54,56 @@ export const waitForCondition = <FunctionType extends (...args: any) => any>({
 
   return trigger.wait({ timeout });
 };
+
+export type UntilCallback<T> = (resolve: (value: T) => void, reject: (error: Error) => void) => Promise<T> | void;
+
+/**
+ * Awaits promise.
+ */
+export const until = <T = void>(cb: UntilCallback<T>, timeout?: number): Promise<T> => {
+  return new Promise((resolve, reject) => {
+    const t =
+      timeout &&
+      setTimeout(() => {
+        reject(new Error(`Timeout after ${t}ms`));
+      }, timeout);
+
+    setTimeout(async () => {
+      try {
+        await cb(
+          (value: T) => {
+            t && clearTimeout(t);
+            resolve(value);
+          },
+          (error: Error) => {
+            t && clearTimeout(t);
+            reject(error);
+          },
+        );
+      } catch (err) {
+        reject(err);
+      }
+    });
+  });
+};
+
+/**
+ * Wait until promise resolves.
+ */
+export const untilPromise = <T = void>(cb: () => Promise<T>) => cb();
+
+/**
+ * Wait until error is thrown.
+ */
+export const untilError = (cb: () => Promise<any>) => {
+  return new Promise((resolve, reject) => {
+    setTimeout(async () => {
+      try {
+        await cb();
+        reject(new Error('No error was thrown.'));
+      } catch (err) {
+        resolve(err);
+      }
+    });
+  });
+};