@dxos/async 0.8.4-main.fbb7a13 → 0.8.4-main.fcfe5033a5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/async",
-  "version": "0.8.4-main.fbb7a13",
+  "version": "0.8.4-main.fcfe5033a5",
   "description": "Async utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -33,12 +33,12 @@
   "dependencies": {
     "zen-observable": "^0.10.0",
     "zen-push": "^0.3.1",
-    "@dxos/context": "0.8.4-main.fbb7a13",
-    "@dxos/debug": "0.8.4-main.fbb7a13",
-    "@dxos/invariant": "0.8.4-main.fbb7a13",
-    "@dxos/log": "0.8.4-main.fbb7a13",
-    "@dxos/util": "0.8.4-main.fbb7a13",
-    "@dxos/node-std": "0.8.4-main.fbb7a13"
+    "@dxos/context": "0.8.4-main.fcfe5033a5",
+    "@dxos/debug": "0.8.4-main.fcfe5033a5",
+    "@dxos/invariant": "0.8.4-main.fcfe5033a5",
+    "@dxos/util": "0.8.4-main.fcfe5033a5",
+    "@dxos/log": "0.8.4-main.fcfe5033a5",
+    "@dxos/node-std": "0.8.4-main.fcfe5033a5"
   },
   "devDependencies": {
     "@types/zen-observable": "^0.8.3"

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());
   };
 };
 
@@ -37,7 +40,6 @@ 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`.
- * @deprecated use bind-event-listener
  */
 export const addEventListener = <T extends EventTarget, K extends keyof EventMap<T>>(
   target: T,
@@ -52,8 +54,8 @@ export const addEventListener = <T extends EventTarget, K extends keyof EventMap
 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.ts

@@ -12,7 +12,7 @@ type Callback = (...args: any[]) => void;
  * @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 delay = <CB extends Callback>(cb: CB, delay = 100): CB => {
+export const delay = <F extends Callback>(cb: F, delay = 100): F => {
   let pending = false;
   return ((...args: any[]) => {
     if (pending) {
@@ -27,32 +27,37 @@ export const delay = <CB extends Callback>(cb: CB, delay = 100): CB => {
         pending = false;
       }
     }, delay);
-  }) as CB;
+  }) as F;
 };
 
 /**
- * Debounce callback.
+ * 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 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.
+ * @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 = <CB extends Callback>(cb: CB, delay = 100): CB => {
+export const debounce = <F extends Callback>(cb: F, delay = 100): F => {
   let t: ReturnType<typeof setTimeout>;
   return ((...args: any[]) => {
     clearTimeout(t);
     t = setTimeout(() => cb(...args), delay);
-  }) as CB;
+  }) as F;
 };
 
 /**
- * Throttle callback.
+ * 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 Time window to allow calls in.
- * @returns A new function that wraps the callback and prevents multiple invocations within the time window.
+ * @param delay Minimum interval (ms) between successive invocations.
+ * @returns Wrapped function that rate-limits invocations.
  */
-export const throttle = <CB extends Callback>(cb: CB, delay = 100): CB => {
+export const throttle = <F extends Callback>(cb: F, delay = 100): F => {
   let lastCall = 0;
   return ((...args: any[]) => {
     const now = Date.now();
@@ -60,7 +65,7 @@ export const throttle = <CB extends Callback>(cb: CB, delay = 100): CB => {
       cb(...args);
       lastCall = now;
     }
-  }) as CB;
+  }) as F;
 };
 
 /**
@@ -72,7 +77,7 @@ export const throttle = <CB extends Callback>(cb: CB, delay = 100): CB => {
  * @param delay Time window for both throttle and debounce.
  * @returns A new function that combines throttle and debounce behavior.
  */
-export const debounceAndThrottle = <CB extends Callback>(cb: CB, delay = 100): CB => {
+export const debounceAndThrottle = <F extends Callback>(cb: F, delay = 100): F => {
   let timeout: ReturnType<typeof setTimeout>;
   let lastCall = 0;
 
@@ -94,5 +99,5 @@ export const debounceAndThrottle = <CB extends Callback>(cb: CB, delay = 100): C
         lastCall = Date.now();
       }, delay - delta);
     }
-  }) as CB;
+  }) as F;
 };

package/src/event-emitter.test.ts

@@ -3,7 +3,6 @@
 //
 
 import { EventEmitter } from 'node:events';
-
 import { describe, expect, test } from 'vitest';
 
 import { onEvent, waitForEvent } from './event-emitter';

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/task-scheduling.ts

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import { type Context, ContextDisposedError } from '@dxos/context';
+import { Context, ContextDisposedError } from '@dxos/context';
 import { StackTrace } from '@dxos/debug';
 import { type MaybePromise } from '@dxos/util';
 
@@ -98,17 +98,17 @@ export class AsyncTask {
    * Context of the resource that owns the task.
    * When the context is disposed, the task is cancelled and cannot be scheduled again.
    */
-  // TODO(dmaretskyi): We don't really need to pass ctx in here, since close will also signal dispose.
-  open(ctx: Context): void {
-    this.#ctx = ctx;
+  open(): void {
+    this.#ctx = new Context();
   }
 
   /**
    * Closes the task and waits for it to finish if it is running.
    */
   async close(): Promise<void> {
-    this.#ctx = undefined;
+    await this.#ctx?.dispose();
     await this.join();
+    this.#ctx = undefined;
   }
 
   [Symbol.asyncDispose](): Promise<void> {
@@ -118,6 +118,7 @@ export class AsyncTask {
   /**
    * 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');

package/src/timeout.ts

@@ -4,7 +4,6 @@
 
 import { type Context, ContextDisposedError } from '@dxos/context';
 
-import { promiseFromCallback } from './callback';
 import { TimeoutError } from './errors';
 
 /**
@@ -57,12 +56,11 @@ export const asyncReturn = () => sleep(0);
 /**
  * Wait for promise or throw error.
  */
-export const asyncTimeout = async <T>(
-  // TODO(dmaretskyi): This callback API is unintuitive and leads to bugs.
-  promise: Promise<T> | (() => Promise<T>),
-  timeout: number,
-  err?: Error | string,
-): Promise<T> => {
+export const asyncTimeout = async <T>(promise: Promise<T>, timeout: number, err?: Error | string): Promise<T> => {
+  if (typeof promise === 'function') {
+    throw new Error('First argument must be a promise.');
+  }
+
   let timeoutId: NodeJS.Timeout;
   const throwable = err === undefined || typeof err === 'string' ? new TimeoutError(timeout, err) : err;
   const timeoutPromise = new Promise<T>((resolve, reject) => {
@@ -73,8 +71,7 @@ export const asyncTimeout = async <T>(
     unrefTimeout(timeoutId);
   });
 
-  const conditionTimeout = typeof promise === 'function' ? promiseFromCallback<T>(promise) : promise;
-  return await Promise.race([conditionTimeout, timeoutPromise]).finally(() => {
+  return await Promise.race([promise, timeoutPromise]).finally(() => {
     clearTimeout(timeoutId);
   });
 };