@actuallab/core 13.0.4 → 13.0.14

package/dist/index.d.ts

@@ -171,8 +171,9 @@ declare class EventHandlerSet<T> {
 }
 
 /** Externally-resolvable promise — similar to .NET's TaskCompletionSource<T>. */
-declare class PromiseSource<T> {
+declare class PromiseSource<T> implements Promise<T> {
     readonly promise: Promise<T>;
+    readonly [Symbol.toStringTag] = "Promise";
     private _resolve;
     private _reject;
     private _isCompleted;
@@ -180,9 +181,139 @@ declare class PromiseSource<T> {
     get isCompleted(): boolean;
     resolve(value: T): boolean;
     reject(reason?: unknown): boolean;
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<T>;
 }
 declare const resolvedVoidPromise: Promise<void>;
 
+/**
+ * A {@link PromiseSource} with a built-in timer that can reject (or run a
+ * caller-supplied callback) after a configurable delay. The timer is
+ * automatically cleared when the promise settles by other means, so callers
+ * don't have to remember to `clearTimeout()` on every success path.
+ *
+ * Typical use:
+ * ```ts
+ * const ps = new PromiseSourceWithTimeout<string>();
+ * ps.setTimeout(5_000);                  // rejects after 5s if still pending
+ * ps.setTimeout(5_000, () => ps.resolve('fallback')); // or run a custom callback
+ * ```
+ *
+ * Replaces the `PromiseSourceWithTimeout` previously kept in
+ * `ActualChat/src/nodejs/src/promises.ts`. Note: the Voxt original supported a
+ * "precise" (requestAnimationFrame-based) variant; we drop it here because no
+ * caller in ActualChat uses it outside `promises.ts` itself.
+ */
+declare class PromiseSourceWithTimeout<T> extends PromiseSource<T> {
+    private _timer;
+    hasTimeout(): boolean;
+    /**
+     * Install (or replace) a timeout. Pass `null` to remove without setting a
+     * new one. `callback` is invoked when the timer fires — if omitted, the
+     * promise is rejected with a generic "timed out" error.
+     */
+    setTimeout(ms: number | null, callback?: () => unknown): void;
+    clearTimeout(): void;
+    resolve(value: T): boolean;
+    reject(reason?: unknown): boolean;
+}
+
+/**
+ * Pre-resolved promises for the three values most often returned as a
+ * "no-op" successful path: `void`, `true`, `false`. Returning these
+ * avoids allocating a fresh promise per call site.
+ *
+ * Idiomatic use:
+ * ```ts
+ * if (alreadyInitialized) return ResolvedPromise.Void;
+ * ```
+ */
+declare const ResolvedPromise: {
+    readonly Void: Promise<void>;
+    readonly True: Promise<boolean>;
+    readonly False: Promise<boolean>;
+};
+
+/**
+ * Sentinel returned/thrown by code that distinguishes "the operation took
+ * too long" from a generic rejection. Identity-comparable via the
+ * `instance` singleton — callers can branch on `result === TimedOut.instance`.
+ */
+declare class TimedOut {
+    static readonly instance: TimedOut;
+}
+
+/** Error type rejected by {@link withTimeout} when its budget elapses. */
+declare class TimeoutError extends Error {
+    readonly name = "TimeoutError";
+    constructor(message?: string);
+}
+/**
+ * Race `promise` against a `ms`-millisecond timer. Resolves with the inner
+ * promise's value if it settles first; otherwise rejects with a
+ * {@link TimeoutError} carrying `message`. The timer is always cleared in
+ * a `finally`, so it cannot keep the event loop alive after the race ends.
+ *
+ * The inner promise's rejection (and the timeout's) are routed through
+ * `Promise.race`, so callers should `await` the result inside a `try/catch`
+ * exactly as they would for a single awaited promise. There's no
+ * "unhandled rejection" hazard from the timeout branch — the race always
+ * observes whichever promise wins, and the loser is allowed to settle
+ * silently into the void.
+ */
+declare function withTimeout<T>(promise: PromiseLike<T>, ms: number, message?: string): Promise<T>;
+
+/** Resolves after `ms` milliseconds. */
+declare function delayAsync(ms: number): Promise<void>;
+/** Resolves with `value` after `ms` milliseconds. */
+declare function delayAsyncWith<T>(ms: number, value: T): Promise<T>;
+
+declare function abortPromise(signal: AbortSignal): Promise<never>;
+
+/** A function wrapped by {@link throttle} or {@link debounce}. Calling it
+ *  triggers the underlying function according to the scheduling rule;
+ *  `reset()` discards any pending scheduled call. */
+interface ResettableFunc<TArgs extends unknown[]> {
+    (...args: TArgs): void;
+    reset(): void;
+}
+/** Throttle modes:
+ *  - `default` — fire the head call immediately, then drop further calls
+ *    until the interval elapses; the *last* one is fired at interval end.
+ *  - `skip` — fire the head call immediately, drop ALL calls during the
+ *    interval (no tail call).
+ *  - `delayHead` — delay even the head call by one interval; subsequent
+ *    calls overwrite the pending one. */
+type ThrottleMode = 'default' | 'skip' | 'delayHead';
+/**
+ * Throttle calls to `func` so that it fires at most once every `intervalMs`.
+ * The returned function has a `.reset()` that discards any pending tail call
+ * and re-arms the head-call behavior on the next invocation.
+ */
+declare function throttle<TArgs extends unknown[]>(func: (...args: TArgs) => unknown, intervalMs: number, mode?: ThrottleMode): ResettableFunc<TArgs>;
+/**
+ * Debounce calls to `func`: the function fires only after `intervalMs` have
+ * elapsed since the LAST call. Each new call resets the timer. `.reset()`
+ * discards any pending fire without invoking `func`.
+ */
+declare function debounce<TArgs extends unknown[]>(func: (...args: TArgs) => unknown, intervalMs: number): ResettableFunc<TArgs>;
+
+/**
+ * Wrap an async function so concurrent invocations are serialized into a
+ * single chain — each call awaits the previous one before running, and the
+ * caller receives the result of *its* own invocation.
+ *
+ * Useful for stateful async operations (DB writes, file I/O, network I/O
+ * that must not overlap) where the underlying contract is "one at a time."
+ *
+ * If `limit` is set and the queue is already that deep, the call short-
+ * circuits and returns the same promise the most recent queued call returned
+ * — i.e. it coalesces excess pressure onto the trailing in-flight call.
+ * Pass `null` (the default) for unbounded queueing.
+ */
+declare function serialize<TArgs extends unknown[], TResult>(func: (...args: TArgs) => PromiseLike<TResult> | TResult, limit?: number | null): (...args: TArgs) => Promise<TResult>;
+
 /**
  * A fixed-capacity circular buffer supporting efficient push/pull at both
  * head and tail.
@@ -250,4 +381,29 @@ declare class RetryDelayer {
     cancelDelays(): void;
 }
 
-export { AsyncContext, AsyncContextKey, type AsyncDisposable, AsyncLock, type Disposable, DisposableBag, EventHandlerSet, type IResult, Log, LogLevel, LogLevelController, type LogRef, type LogScopeFns, PromiseSource, Result, type RetryDelay, RetryDelayLimitExceeded, RetryDelayNone, RetryDelaySeq, RetryDelayer, RingBuffer, abortSignalKey, createLogProvider, errorResult, initLogging, initWorkerLogging, resolvedVoidPromise, result, resultFrom, resultFromAsync };
+/** A sequence of retry delays — given a 1-based try index (1 = first
+ *  retry, i.e. AFTER the initial failure), returns the delay in ms before
+ *  the next attempt. For more elaborate delay schemes, see
+ *  {@link RetryDelaySeq.getDelay}. */
+type RetryDelaySchedule = (tryIndex: number) => number;
+/**
+ * Run `fn` up to `tryCount` times, awaiting a delay between attempts.
+ * The last error is rethrown if every attempt fails.
+ *
+ * `fn` is passed the 0-based attempt index and the last error (or
+ * `undefined` for the first attempt) — useful for adapting behavior per
+ * try (e.g. switching endpoints, escalating timeouts).
+ */
+declare function retry<TResult>(tryCount: number, fn: (tryIndex: number, lastError: unknown) => PromiseLike<TResult> | TResult, retryDelays?: RetryDelaySchedule): Promise<TResult>;
+/**
+ * Run `fn` and swallow any throw, returning `onError(e)` if provided or
+ * `undefined` otherwise. The returned promise always settles successfully
+ * — the caller never has to `try/catch` it.
+ *
+ * Useful where a logical "best-effort" return is wanted but the runtime
+ * defaults — unhandled rejection warnings, exception escape past finally
+ * blocks — are not.
+ */
+declare function catchErrors<TResult>(fn: () => PromiseLike<TResult> | TResult, onError?: (e: unknown) => TResult): Promise<TResult | undefined>;
+
+export { AsyncContext, AsyncContextKey, type AsyncDisposable, AsyncLock, type Disposable, DisposableBag, EventHandlerSet, type IResult, Log, LogLevel, LogLevelController, type LogRef, type LogScopeFns, PromiseSource, PromiseSourceWithTimeout, type ResettableFunc, ResolvedPromise, Result, type RetryDelay, RetryDelayLimitExceeded, RetryDelayNone, type RetryDelaySchedule, RetryDelaySeq, RetryDelayer, RingBuffer, type ThrottleMode, TimedOut, TimeoutError, abortPromise, abortSignalKey, catchErrors, createLogProvider, debounce, delayAsync, delayAsyncWith, errorResult, initLogging, initWorkerLogging, resolvedVoidPromise, result, resultFrom, resultFromAsync, retry, serialize, throttle, withTimeout };

package/dist/index.js

@@ -593,6 +593,7 @@ var AsyncLock = class {
 // src/promise-source.ts
 var PromiseSource = class {
   promise;
+  [Symbol.toStringTag] = "Promise";
   _resolve;
   _reject;
   _isCompleted = false;
@@ -617,6 +618,15 @@ var PromiseSource = class {
     this._reject(reason);
     return true;
   }
+  then(onfulfilled, onrejected) {
+    return this.promise.then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this.promise.catch(onrejected);
+  }
+  finally(onfinally) {
+    return this.promise.finally(onfinally);
+  }
 };
 var resolvedVoidPromise = Promise.resolve();
 
@@ -645,10 +655,235 @@ var EventHandlerSet = class {
       ps.resolve(arg);
     };
     this._handlers.add(handler);
-    return ps.promise;
+    return ps;
+  }
+};
+
+// src/withTimeout.ts
+var TimeoutError = class extends Error {
+  name = "TimeoutError";
+  constructor(message = "Operation timed out") {
+    super(message);
+  }
+};
+async function withTimeout(promise, ms, message) {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(new TimeoutError(message ?? `Operation timed out after ${ms}ms`)),
+      ms
+    );
+  });
+  timeoutPromise.catch(() => {
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+
+// src/promise-source-with-timeout.ts
+var PromiseSourceWithTimeout = class extends PromiseSource {
+  _timer;
+  hasTimeout() {
+    return this._timer !== void 0;
+  }
+  /**
+   * Install (or replace) a timeout. Pass `null` to remove without setting a
+   * new one. `callback` is invoked when the timer fires — if omitted, the
+   * promise is rejected with a generic "timed out" error.
+   */
+  setTimeout(ms, callback) {
+    this.clearTimeout();
+    if (ms === null || this.isCompleted) return;
+    this._timer = setTimeout(() => {
+      this._timer = void 0;
+      if (callback) callback();
+      else this.reject(new TimeoutError(`The promise has timed out after ${ms}ms.`));
+    }, ms);
+  }
+  clearTimeout() {
+    if (this._timer === void 0) return;
+    clearTimeout(this._timer);
+    this._timer = void 0;
+  }
+  resolve(value) {
+    const didSettle = super.resolve(value);
+    if (didSettle) this.clearTimeout();
+    return didSettle;
+  }
+  reject(reason) {
+    const didSettle = super.reject(reason);
+    if (didSettle) this.clearTimeout();
+    return didSettle;
   }
 };
 
+// src/resolved-promise.ts
+var ResolvedPromise = {
+  Void: Promise.resolve(),
+  True: Promise.resolve(true),
+  False: Promise.resolve(false)
+};
+
+// src/timed-out.ts
+var TimedOut = class _TimedOut {
+  static instance = new _TimedOut();
+};
+
+// src/delay.ts
+function delayAsync(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function delayAsyncWith(ms, value) {
+  return new Promise((resolve) => {
+    setTimeout(() => resolve(value), ms);
+  });
+}
+
+// src/abort-promise.ts
+var abortPromiseCache = /* @__PURE__ */ new WeakMap();
+function abortPromise(signal) {
+  if (signal.aborted) return Promise.reject(signal.reason);
+  let cached = abortPromiseCache.get(signal);
+  if (!cached) {
+    cached = new Promise((_, reject) => {
+      signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+    });
+    cached.catch(() => {
+    });
+    abortPromiseCache.set(signal, cached);
+  }
+  return cached;
+}
+
+// src/internal-logging.ts
+var scopeDefaults = {
+  retry: 3 /* Warn */,
+  throttle: 3 /* Warn */
+};
+var getLogs = createLogProvider("core.", scopeDefaults);
+
+// src/throttle.ts
+var { errorLog } = getLogs("throttle");
+var Call = class {
+  constructor(func, self, parameters) {
+    this.func = func;
+    this.self = self;
+    this.parameters = parameters;
+  }
+  invoke() {
+    return this.func.apply(this.self, this.parameters);
+  }
+  invokeSilently() {
+    try {
+      return this.invoke();
+    } catch (error) {
+      errorLog?.log("Call.invokeSilently: unhandled error:", error);
+    }
+  }
+};
+function throttle(func, intervalMs, mode = "default") {
+  let lastCall = null;
+  let nextFireTime = 0;
+  let timeoutHandle = null;
+  const reset2 = () => {
+    if (timeoutHandle !== null) clearTimeout(timeoutHandle);
+    timeoutHandle = null;
+    lastCall = null;
+    nextFireTime = 0;
+  };
+  const fire = () => {
+    if (timeoutHandle !== null) clearTimeout(timeoutHandle);
+    if (lastCall !== null) {
+      const call = lastCall;
+      lastCall = null;
+      nextFireTime = Date.now() + intervalMs;
+      timeoutHandle = setTimeout(fire, intervalMs);
+      call.invokeSilently();
+    } else {
+      timeoutHandle = null;
+      nextFireTime = 0;
+    }
+  };
+  const wrapped = function(...args) {
+    const call = new Call(func, this, args);
+    const fireDelay = nextFireTime - Date.now();
+    if (timeoutHandle !== null && fireDelay <= 0) {
+      fire();
+    }
+    if (timeoutHandle === null) {
+      nextFireTime = Date.now() + intervalMs;
+      timeoutHandle = setTimeout(fire, intervalMs);
+      if (mode === "delayHead") {
+        lastCall = call;
+      } else {
+        call.invokeSilently();
+      }
+    } else if (mode !== "skip") {
+      lastCall = call;
+    }
+  };
+  wrapped.reset = reset2;
+  return wrapped;
+}
+function debounce(func, intervalMs) {
+  let lastCall = null;
+  let nextFireTime = 0;
+  let timeoutHandle = null;
+  const reset2 = () => {
+    timeoutHandle = null;
+    lastCall = null;
+    nextFireTime = 0;
+  };
+  const fire = () => {
+    if (timeoutHandle !== null) clearTimeout(timeoutHandle);
+    timeoutHandle = null;
+    const fireDelay = nextFireTime - Date.now();
+    if (fireDelay <= 0) {
+      nextFireTime = 0;
+      if (lastCall !== null) {
+        const call = lastCall;
+        lastCall = null;
+        call.invokeSilently();
+      }
+    } else {
+      timeoutHandle = setTimeout(fire, fireDelay);
+    }
+  };
+  const wrapped = function(...args) {
+    lastCall = new Call(func, this, args);
+    nextFireTime = Date.now() + intervalMs;
+    timeoutHandle ??= setTimeout(fire, intervalMs);
+  };
+  wrapped.reset = reset2;
+  return wrapped;
+}
+
+// src/serialize.ts
+function serialize(func, limit = null) {
+  let lastCall = Promise.resolve(null);
+  let queueSize = 0;
+  return function(...args) {
+    if (limit !== null && queueSize >= limit) return lastCall;
+    queueSize++;
+    const prevCall = lastCall;
+    const invoke = () => func.apply(this, args);
+    return lastCall = (async () => {
+      try {
+        await prevCall.catch(() => {
+        });
+        return await invoke();
+      } finally {
+        queueSize--;
+      }
+    })();
+  };
+}
+
 // src/ring-buffer.ts
 var RingBuffer = class {
   _buffer;
@@ -839,6 +1074,34 @@ var RetryDelayer = class {
     this.cancelDelaysChanged.trigger();
   }
 };
+
+// src/retry.ts
+var { warnLog } = getLogs("retry");
+var defaultRetryDelays = () => 50;
+async function retry(tryCount, fn, retryDelays = defaultRetryDelays) {
+  if (tryCount <= 0)
+    throw new Error("retry: tryCount must be positive.");
+  let lastError;
+  for (let tryIndex = 0; ; ) {
+    if (tryIndex >= tryCount) throw lastError;
+    try {
+      return await fn(tryIndex, lastError);
+    } catch (e) {
+      lastError = e;
+    }
+    ++tryIndex;
+    if (tryIndex >= tryCount) throw lastError;
+    warnLog?.log(`retry(${tryIndex}/${tryCount}): error:`, lastError);
+    await delayAsync(retryDelays(tryIndex));
+  }
+}
+async function catchErrors(fn, onError) {
+  try {
+    return await fn();
+  } catch (e) {
+    return onError ? onError(e) : void 0;
+  }
+}
 export {
   AsyncContext,
   AsyncContextKey,
@@ -849,20 +1112,33 @@ export {
   LogLevel,
   LogLevelController,
   PromiseSource,
+  PromiseSourceWithTimeout,
+  ResolvedPromise,
   Result,
   RetryDelayLimitExceeded,
   RetryDelayNone,
   RetryDelaySeq,
   RetryDelayer,
   RingBuffer,
+  TimedOut,
+  TimeoutError,
+  abortPromise,
   abortSignalKey,
+  catchErrors,
   createLogProvider,
+  debounce,
+  delayAsync,
+  delayAsyncWith,
   errorResult,
   initLogging,
   initWorkerLogging,
   resolvedVoidPromise,
   result,
   resultFrom,
-  resultFromAsync
+  resultFromAsync,
+  retry,
+  serialize,
+  throttle,
+  withTimeout
 };
 //# sourceMappingURL=index.js.map