@dxos/async 0.8.4-main.ef1bc66f44 → 0.8.4-main.f466a3d56e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/async",
-  "version": "0.8.4-main.ef1bc66f44",
+  "version": "0.8.4-main.f466a3d56e",
   "description": "Async utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": true,
   "type": "module",
@@ -23,9 +23,6 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
@@ -33,12 +30,12 @@
   "dependencies": {
     "zen-observable": "^0.10.0",
     "zen-push": "^0.3.1",
-    "@dxos/context": "0.8.4-main.ef1bc66f44",
-    "@dxos/debug": "0.8.4-main.ef1bc66f44",
-    "@dxos/invariant": "0.8.4-main.ef1bc66f44",
-    "@dxos/log": "0.8.4-main.ef1bc66f44",
-    "@dxos/util": "0.8.4-main.ef1bc66f44",
-    "@dxos/node-std": "0.8.4-main.ef1bc66f44"
+    "@dxos/debug": "0.8.4-main.f466a3d56e",
+    "@dxos/log": "0.8.4-main.f466a3d56e",
+    "@dxos/node-std": "0.8.4-main.f466a3d56e",
+    "@dxos/util": "0.8.4-main.f466a3d56e",
+    "@dxos/context": "0.8.4-main.f466a3d56e",
+    "@dxos/invariant": "0.8.4-main.f466a3d56e"
   },
   "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,

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/persistent-lifecycle.ts

@@ -69,12 +69,20 @@ export class PersistentLifecycle<T> extends Resource {
       try {
         await this._restart();
       } catch (err) {
+        // Suppress noise from restarts that race with shutdown.
+        if (this._ctx?.disposed) {
+          return;
+        }
         log.warn('Restart failed', { err });
         this._restartTask?.schedule();
       }
     });
 
     this._currentState = await this._start().catch((err) => {
+      // Suppress noise when shutdown was requested while the initial start was in flight.
+      if (this._ctx?.disposed) {
+        return undefined;
+      }
       log.warn('Start failed', { err });
       this._restartTask?.schedule();
       return undefined;

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