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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/async",
-  "version": "0.8.4-main.f9ba587",
+  "version": "0.8.4-main.fd6878d",
   "description": "Async utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,12 +10,12 @@
   "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",
@@ -29,12 +29,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.fd6878d",
+    "@dxos/debug": "0.8.4-main.fd6878d",
+    "@dxos/invariant": "0.8.4-main.fd6878d",
+    "@dxos/log": "0.8.4-main.fd6878d",
+    "@dxos/util": "0.8.4-main.fd6878d",
+    "@dxos/node-std": "0.8.4-main.fd6878d"
   },
   "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

@@ -38,15 +38,15 @@ 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[] = [];

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,49 @@
 // Copyright 2023 DXOS.org
 //
 
-import { throttle } from './throttle';
+type Callback = (...args: any[]) => void;
 
 /**
  * Debounce callback.
+ *
+ * @param cb Callback to invoke.
+ * @param delay Time window to wait before allowing calls.
+ * @returns A new function that wraps the callback and ensures that the callback is only invoked after the time window has passed and no new calls have been made.
  */
-export const debounce = (cb: (...args: any[]) => void, wait = 100): ((...args: any[]) => void) => {
+export const debounce = <CB extends Callback>(cb: CB, delay = 100): CB => {
   let t: ReturnType<typeof setTimeout>;
-  return (...args: any[]) => {
+  return ((...args: any[]) => {
     clearTimeout(t);
-    t = setTimeout(() => cb(...args), wait);
-  };
+    t = setTimeout(() => cb(...args), delay);
+  }) as CB;
 };
 
 /**
- * Debounce and throttle callback.
+ * Throttle callback.
+ *
+ * @param cb Callback to invoke.
+ * @param delay Time window to allow calls in.
+ * @returns A new function that wraps the callback and prevents multiple invocations within the time window.
  */
-export const debounceAndThrottle = (cb: (...args: any[]) => void, wait = 100): ((...args: any[]) => void) => {
-  const debounced = debounce(cb, wait);
-  const throttled = throttle(cb, wait);
+export const throttle = <CB extends Callback>(cb: CB, delay = 100): CB => {
+  let lastCall = 0;
+  return ((...args: any[]) => {
+    const now = Date.now();
+    if (now - lastCall >= delay) {
+      cb(...args);
+      lastCall = now;
+    }
+  }) as CB;
+};
 
-  return (...args: any[]) => {
+/**
+ * Debounce and throttle callback.
+ */
+export const debounceAndThrottle = <CB extends Callback>(cb: CB, delay = 100): CB => {
+  const debounced = debounce(cb, delay);
+  const throttled = throttle(cb, delay);
+  return ((...args: any[]) => {
     debounced(...args);
     throttled(...args);
-  };
+  }) as CB;
 };

package/src/event-emitter.test.ts

@@ -3,11 +3,12 @@
 //
 
 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/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/task-scheduling.ts

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import { ContextDisposedError, type Context } from '@dxos/context';
+import { type Context, ContextDisposedError } from '@dxos/context';
 import { StackTrace } from '@dxos/debug';
 import { type MaybePromise } from '@dxos/util';
 

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

package/src/timeout.ts

@@ -4,7 +4,7 @@
 
 import { type Context, ContextDisposedError } from '@dxos/context';
 
-import { createPromiseFromCallback } from './callback';
+import { promiseFromCallback } from './callback';
 import { TimeoutError } from './errors';
 
 /**
@@ -28,6 +28,27 @@ export const sleep = (ms: number) => {
   });
 };
 
+// TODO(burdon): Reconcile with sleep.
+export const sleepWithContext = (ctx: Context, ms: number) => {
+  const error = new ContextDisposedError();
+  return new Promise<void>((resolve, reject) => {
+    if (ctx.disposed) {
+      reject(error);
+      return;
+    }
+
+    const timeout = setTimeout(() => {
+      clearDispose();
+      resolve();
+    }, ms);
+
+    const clearDispose = ctx.onDispose(() => {
+      clearTimeout(timeout);
+      reject(error);
+    });
+  });
+};
+
 /**
  * Can be used in long-running tasks to let other callbacks be invoked.
  */
@@ -52,7 +73,7 @@ export const asyncTimeout = async <T>(
     unrefTimeout(timeoutId);
   });
 
-  const conditionTimeout = typeof promise === 'function' ? createPromiseFromCallback<T>(promise) : promise;
+  const conditionTimeout = typeof promise === 'function' ? promiseFromCallback<T>(promise) : promise;
   return await Promise.race([conditionTimeout, timeoutPromise]).finally(() => {
     clearTimeout(timeoutId);
   });
@@ -67,23 +88,3 @@ export const unrefTimeout = (timeoutId: NodeJS.Timeout) => {
     timeoutId.unref();
   }
 };
-
-export const sleepWithContext = (ctx: Context, ms: number) => {
-  const error = new ContextDisposedError();
-  return new Promise<void>((resolve, reject) => {
-    if (ctx.disposed) {
-      reject(error);
-      return;
-    }
-
-    const timeout = setTimeout(() => {
-      clearDispose();
-      resolve();
-    }, ms);
-
-    const clearDispose = ctx.onDispose(() => {
-      clearTimeout(timeout);
-      reject(error);
-    });
-  });
-};

package/src/trigger.ts

@@ -2,6 +2,8 @@
 // Copyright 2020 DXOS.org
 //
 
+import { invariant } from '@dxos/invariant';
+
 import { TimeoutError } from './errors';
 import { asyncTimeout } from './timeout';
 
@@ -10,7 +12,7 @@ import { asyncTimeout } from './timeout';
  * @deprecated Use `Trigger` instead.
  */
 export const trigger = <T = void>(timeout?: number): [() => Promise<T>, (arg: T) => void] => {
-  // eslint-disable-line @stayradiated/prefer-arrow-functions/prefer-arrow-functions
+  // eslint-disable-line prefer-arrow-functions/prefer-arrow-functions
   let callback: (arg: T) => void;
 
   const promise = new Promise<T>((resolve, reject) => {
@@ -121,3 +123,58 @@ export class Trigger<T = void> {
     return this;
   }
 }
+
+type LatchProps = {
+  count?: number;
+  timeout?: number;
+};
+
+type LatchResult = [() => Promise<number>, () => number, (err: Error) => void];
+
+/**
+ * Returns a callback and a promise that's resolved when the callback is called n times.
+ * @deprecated Use `Trigger` instead.
+ */
+export const latch = ({ count = 1, timeout }: LatchProps = {}): LatchResult => {
+  invariant(count >= 0);
+
+  let t: ReturnType<typeof setTimeout>;
+  let doResolve: (value: number) => void;
+  let doReject: (err: Error) => void;
+  const promise = new Promise<number>((resolve, reject) => {
+    doResolve = (value) => {
+      clearTimeout(t);
+      resolve(value);
+    };
+
+    doReject = (err) => {
+      clearTimeout(t);
+      reject(err);
+    };
+  });
+
+  if (count === 0) {
+    setTimeout(() => {
+      doResolve(0);
+    });
+  } else {
+    if (timeout) {
+      t = setTimeout(() => {
+        doReject(new Error(`Timed out after ${timeout.toLocaleString()}ms`));
+      }, timeout);
+    }
+  }
+
+  let i = 0;
+  return [
+    async () => await promise,
+    () => {
+      if (++i === count) {
+        doResolve(i);
+      }
+
+      return i;
+    },
+    (err: Error) => doReject(err),
+  ];
+};

package/src/update-scheduler.ts

@@ -16,7 +16,7 @@ export type UpdateSchedulerOptions = {
 /**
  * Time period for update counting.
  */
-const TIME_PERIOD = 1000;
+const TIME_PERIOD = 1_000;
 
 export class UpdateScheduler {
   /**

package/dist/types/src/latch.d.ts

@@ -1,11 +0,0 @@
-type LatchProps = {
-    count?: number;
-    timeout?: number;
-};
-type LatchResult = [() => Promise<number>, () => number, (err: Error) => void];
-/**
- * Returns a callback and a promise that's resolved when the callback is called n times.
- */
-export declare const latch: ({ count, timeout }?: LatchProps) => LatchResult;
-export {};
-//# sourceMappingURL=latch.d.ts.map

package/dist/types/src/latch.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"latch.d.ts","sourceRoot":"","sources":["../../../src/latch.ts"],"names":[],"mappings":"AAMA,KAAK,UAAU,GAAG;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,KAAK,WAAW,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC;AAE/E;;GAEG;AAEH,eAAO,MAAM,KAAK,GAAI,qBAAwB,UAAe,KAAG,WA0C/D,CAAC"}

package/dist/types/src/sink.d.ts

@@ -1,6 +0,0 @@
-import { type EventEmitter } from 'node:events';
-/**
- * Waits for the specified number of events from the given emitter.
- */
-export declare const sink: (emitter: EventEmitter, event: string, count?: number) => Promise<void>;
-//# sourceMappingURL=sink.d.ts.map

package/dist/types/src/sink.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../../../src/sink.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD;;GAEG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,YAAY,EAAE,OAAO,MAAM,EAAE,cAAS,KAAG,OAAO,CAAC,IAAI,CAclF,CAAC"}

package/dist/types/src/throttle.d.ts

@@ -1,2 +0,0 @@
-export declare const throttle: (cb: (...args: any[]) => void, wait?: number) => ((...args: any[]) => void);
-//# sourceMappingURL=throttle.d.ts.map

package/dist/types/src/throttle.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"throttle.d.ts","sourceRoot":"","sources":["../../../src/throttle.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,QAAQ,GAAI,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,aAAU,KAAG,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAS5F,CAAC"}

package/dist/types/src/throttle.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=throttle.test.d.ts.map

package/dist/types/src/throttle.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"throttle.test.d.ts","sourceRoot":"","sources":["../../../src/throttle.test.ts"],"names":[],"mappings":""}

package/dist/types/src/types.d.ts

@@ -1,2 +0,0 @@
-export type Awaited<T> = T extends Promise<infer U> ? U : T;
-//# sourceMappingURL=types.d.ts.map

package/dist/types/src/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC"}