@dxos/async 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@dxos/async",
-  "version": "0.8.4-main.fffef41",
+  "version": "0.8.4-staging.60fe92afc8",
   "description": "Async utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": true,
   "type": "module",
@@ -19,9 +23,6 @@
     }
   },
   "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.fffef41",
-    "@dxos/log": "0.8.4-main.fffef41",
-    "@dxos/debug": "0.8.4-main.fffef41",
-    "@dxos/node-std": "0.8.4-main.fffef41",
-    "@dxos/util": "0.8.4-main.fffef41",
-    "@dxos/invariant": "0.8.4-main.fffef41"
+    "@dxos/debug": "0.8.4-staging.60fe92afc8",
+    "@dxos/context": "0.8.4-staging.60fe92afc8",
+    "@dxos/invariant": "0.8.4-staging.60fe92afc8",
+    "@dxos/log": "0.8.4-staging.60fe92afc8",
+    "@dxos/util": "0.8.4-staging.60fe92afc8",
+    "@dxos/node-std": "0.8.4-staging.60fe92afc8"
   },
   "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());
   };
 };
 
@@ -51,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/persistent-lifecycle.test.ts

@@ -57,6 +57,42 @@ describe('ConnectionState', () => {
     expect(timeToTrigger).to.be.greaterThanOrEqual(100);
   });
 
+  test('connection that drops immediately backs off instead of hot-looping', async () => {
+    const startTimes: number[] = [];
+    const maxStarts = 4;
+    const done = new Trigger();
+
+    const persistentLifecycle = new PersistentLifecycle({
+      start: async () => {
+        startTimes.push(Date.now());
+        if (startTimes.length >= maxStarts) {
+          done.wake();
+        }
+      },
+      stop: async () => {},
+      // Simulate the connection dropping the moment it is established.
+      onRestart: async () => {
+        if (startTimes.length < maxStarts) {
+          void persistentLifecycle.scheduleRestart();
+        }
+      },
+    });
+
+    await persistentLifecycle.open();
+    onTestFinished(async () => {
+      await persistentLifecycle.close();
+    });
+
+    // The initial open already performed the first start; simulate its immediate drop.
+    void persistentLifecycle.scheduleRestart();
+    await done.wait({ timeout: 5000 });
+
+    // Successive reconnects must back off (~0, ~100, ~200ms), not fire back-to-back.
+    const gaps = startTimes.slice(1).map((time, index) => time - startTimes[index]);
+    expect(gaps[1]).to.be.greaterThanOrEqual(90);
+    expect(gaps[2]).to.be.greaterThanOrEqual(180);
+  });
+
   test('finish `restart` before close', async () => {
     let restarted = false;
     const persistentLifecycle = new PersistentLifecycle({

package/src/persistent-lifecycle.ts

@@ -13,7 +13,14 @@ import { sleep } from './timeout';
 const INIT_RESTART_DELAY = 100;
 const DEFAULT_MAX_RESTART_DELAY = 5000;
 
-export type PersistentLifecycleParams<T> = {
+/**
+ * Minimum duration a connection must stay up before it is considered stable and the backoff is
+ * reset. A connection that drops sooner keeps escalating the delay, so an endpoint that accepts
+ * then immediately closes the connection cannot produce a zero-delay reconnect loop.
+ */
+const STABLE_CONNECTION_THRESHOLD = 5000;
+
+export type PersistentLifecycleProps<T> = {
   /**
    * Create connection.
    * If promise resolves successfully, connection is considered established.
@@ -50,8 +57,9 @@ export class PersistentLifecycle<T> extends Resource {
   private _currentState: T | undefined = undefined;
   private _restartTask?: DeferredTask = undefined;
   private _restartAfter = 0;
+  private _connectedAt: number | undefined = undefined;
 
-  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;
@@ -69,16 +77,26 @@ 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) => {
+    try {
+      this._currentState = await this._start();
+      this._connectedAt = Date.now();
+    } catch (err) {
+      // Suppress noise when shutdown was requested while the initial start was in flight.
+      if (this._ctx?.disposed) {
+        return;
+      }
       log.warn('Start failed', { err });
       this._restartTask?.schedule();
-      return undefined;
-    });
+    }
   }
 
   protected override async _close(): Promise<void> {
@@ -89,6 +107,15 @@ export class PersistentLifecycle<T> extends Resource {
 
   private async _restart(): Promise<void> {
     log(`restarting in ${this._restartAfter}ms`, { state: this._lifecycleState });
+
+    // Reset the backoff only if the previous connection stayed up long enough to be considered
+    // stable. A connection that drops shortly after starting must keep escalating the delay,
+    // otherwise reconnects degenerate into a hot loop.
+    if (this._connectedAt !== undefined && Date.now() - this._connectedAt >= STABLE_CONNECTION_THRESHOLD) {
+      this._restartAfter = 0;
+    }
+    this._connectedAt = undefined;
+
     await this._stopCurrentState();
     if (this._lifecycleState !== LifecycleState.OPEN) {
       return;
@@ -101,7 +128,7 @@ export class PersistentLifecycle<T> extends Resource {
       this._currentState = await this._start();
     });
 
-    this._restartAfter = 0;
+    this._connectedAt = Date.now();
     await this._onRestart?.();
   }
 

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';
 
@@ -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/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);
   });
 };