@actuallab/core 13.0.25 → 13.0.167

package/dist/index.d.ts

@@ -108,10 +108,11 @@ declare class Result<T> implements IResult<T> {
     readonly hasError: boolean;
     private readonly _value;
     private readonly _error;
-    constructor(value: T | undefined, error?: unknown);
+    constructor(value: T | undefined, error?: unknown, hasError?: boolean);
     get value(): T;
     get error(): unknown;
     get valueOrUndefined(): T | undefined;
+    equals(other: Result<T>, valueComparer?: (a: T, b: T) => boolean): boolean;
     static ok<T>(value: T): Result<T>;
     static error<T>(error: unknown): Result<T>;
 }
@@ -129,12 +130,16 @@ declare class AsyncContextKey<T> {
 /** General-purpose typed context container — named for forward-compatibility with TC39 AsyncContext proposal. */
 declare const abortSignalKey: AsyncContextKey<AbortSignal | undefined>;
 declare class AsyncContext {
-    static current: AsyncContext | undefined;
     /** Immutable empty singleton — avoids allocating new AsyncContext(). */
     static readonly empty: AsyncContext;
+    private static _current;
     private static _defaults;
     private _values;
     constructor(values?: Map<symbol, unknown>);
+    static get current(): AsyncContext | undefined;
+    static set current(value: AsyncContext | undefined);
+    /** True when AsyncContext.current flows across awaits (Node AsyncLocalStorage is active). */
+    static get isAsyncLocalStorageActive(): boolean;
     get<T>(key: AsyncContextKey<T>): T;
     with<T>(key: AsyncContextKey<T>, value: T): AsyncContext;
     activate(): Disposable;
@@ -147,6 +152,7 @@ declare class AsyncContext {
     static fromArgs(args: unknown[]): AsyncContext | undefined;
     static setDefault<T>(key: AsyncContextKey<T>, value: T): void;
     static getOrCreate(): AsyncContext;
+    static _setAsyncLocalStorageActive(active: boolean): void;
 }
 
 /** Promise-based mutual exclusion lock for serializing async operations. */
@@ -154,22 +160,32 @@ declare class AsyncLock {
     private _queue;
     private _locked;
     get isLocked(): boolean;
-    acquire(): Promise<void>;
+    acquire(signal?: AbortSignal): Promise<void>;
     release(): void;
-    run<T>(fn: () => T | Promise<T>): Promise<T>;
+    run<T>(fn: () => T | Promise<T>, signal?: AbortSignal): Promise<T>;
 }
 
-/** Typed pub/sub event handler set — similar to .NET's EventHandler<T> multicast delegate. */
+/**
+ * Typed pub/sub event handler set — similar to .NET's EventHandler<T> multicast delegate.
+ * Deviation: Set-backed, so adding the same handler twice fires it once (a C# delegate fires it twice).
+ */
 declare class EventHandlerSet<T> {
     private _handlers;
     get count(): number;
     add(handler: (arg: T) => void): void;
     remove(handler: (arg: T) => void): void;
     trigger(arg: T): void;
+    triggerSafe(arg: T, onError: (error: unknown) => void): void;
     clear(): void;
     whenNext(): Promise<T>;
 }
 
+declare class AsyncSignal {
+    private source;
+    wait(): Promise<void>;
+    notify(): void;
+}
+
 /** Externally-resolvable promise — similar to .NET's TaskCompletionSource<T>. */
 declare class PromiseSource<T> implements Promise<T> {
     readonly promise: Promise<T>;
@@ -264,13 +280,43 @@ declare class TimeoutError extends Error {
  */
 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 after `ms` milliseconds, or rejects with `signal.reason` if
+ *  `signal` aborts first (including when it is already aborted). */
+declare function delayAsync(ms: number, signal?: AbortSignal): 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>;
 
+/**
+ * True when `error` is a cancellation/abort signal rather than a real failure.
+ *
+ * Recognizes the wave-1 cancellation convention: `delayAsync`, `AsyncLock`, and
+ * `abortPromise` all reject with `signal.reason`, which — per the Web spec —
+ * defaults to a `DOMException` named `'AbortError'` (and is whatever value was
+ * passed to `abort(reason)` otherwise). A plain `Error` named `'AbortError'`
+ * (e.g. from a fetch abort) is matched too.
+ */
+declare function isCancellation(error: unknown): boolean;
+/**
+ * Builds a cancellation-shaped error recognized by {@link isCancellation}.
+ * Named `'AbortError'` so it rides the same never-cache path as an aborted
+ * `fetch`: the compute kernel invalidates such computeds instead of caching
+ * the error (K6), and RPC callers treat it as a retryable cancellation.
+ */
+declare function cancellationError(message?: string): Error;
+
+type AbortOutcome = 'resolve' | 'reject';
+/**
+ * Builds a Promise that settles when the first completion source fires, then runs
+ * every registered cleanup exactly once — on completion or when `abortSignal`
+ * aborts. `wire` installs the sources (timers, event handlers), calling
+ * `complete()` to resolve and `addCleanup(fn)` to register teardown; every
+ * cleanup, plus the abort listener, is removed on every exit path. `onAbort`
+ * selects whether an abort resolves or rejects (with `signal.reason`).
+ */
+declare function awaitWithCleanup(abortSignal: AbortSignal | undefined, onAbort: AbortOutcome, wire: (complete: () => void, addCleanup: (cleanup: () => void) => void) => void): Promise<void>;
+
 /** 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. */
@@ -393,8 +439,11 @@ type RetryDelaySchedule = (tryIndex: number) => number;
  * `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).
+ *
+ * Aborting `signal` during an inter-attempt delay rejects with
+ * `signal.reason` instead of waiting the delay out.
  */
-declare function retry<TResult>(tryCount: number, fn: (tryIndex: number, lastError: unknown) => PromiseLike<TResult> | TResult, retryDelays?: RetryDelaySchedule): Promise<TResult>;
+declare function retry<TResult>(tryCount: number, fn: (tryIndex: number, lastError: unknown) => PromiseLike<TResult> | TResult, retryDelays?: RetryDelaySchedule, signal?: AbortSignal): Promise<TResult>;
 /**
  * Run `fn` and swallow any throw, returning `onError(e)` if provided or
  * `undefined` otherwise. The returned promise always settles successfully
@@ -406,4 +455,7 @@ declare function retry<TResult>(tryCount: number, fn: (tryIndex: number, lastErr
  */
 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 };
+declare function ownMetadata<T extends object>(metadata: object, key: symbol): T;
+declare function resolveArgCount(fn: (...args: never[]) => unknown, explicit: number | undefined, methodName: string): number;
+
+export { type AbortOutcome, AsyncContext, AsyncContextKey, type AsyncDisposable, AsyncLock, AsyncSignal, 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, awaitWithCleanup, cancellationError, catchErrors, createLogProvider, debounce, delayAsync, delayAsyncWith, errorResult, initLogging, initWorkerLogging, isCancellation, ownMetadata, resolveArgCount, resolvedVoidPromise, result, resultFrom, resultFromAsync, retry, serialize, throttle, withTimeout };

package/dist/index.js

@@ -439,9 +439,9 @@ var Result = class _Result {
   hasError;
   _value;
   _error;
-  constructor(value, error) {
-    this.hasValue = error === void 0;
-    this.hasError = !this.hasValue;
+  constructor(value, error, hasError = error !== void 0) {
+    this.hasError = hasError;
+    this.hasValue = !hasError;
     this._value = value;
     this._error = error;
   }
@@ -455,11 +455,17 @@ var Result = class _Result {
   get valueOrUndefined() {
     return this.hasValue ? this._value : void 0;
   }
+  // Values compared with valueComparer (Object.is by default); errors by reference — mirrors C# Result<T>.Equals.
+  equals(other, valueComparer = Object.is) {
+    if (this.hasError !== other.hasError || this._error !== other._error)
+      return false;
+    return valueComparer(this._value, other._value);
+  }
   static ok(value) {
-    return new _Result(value);
+    return new _Result(value, void 0, false);
   }
   static error(error) {
-    return new _Result(void 0, error);
+    return new _Result(void 0, error ?? new Error("Unspecified error"), true);
   }
 };
 function result(value, error) {
@@ -496,15 +502,35 @@ var abortSignalKey = new AsyncContextKey(
   "AbortSignal",
   void 0
 );
+var _alsImpl = detectAsyncLocalStorage();
+var _als = _alsImpl;
+function detectAsyncLocalStorage() {
+  const proc = globalThis.process;
+  const asyncHooks = proc?.getBuiltinModule?.("node:async_hooks");
+  return asyncHooks === void 0 ? void 0 : new asyncHooks.AsyncLocalStorage();
+}
 var AsyncContext = class _AsyncContext {
-  static current = void 0;
   /** Immutable empty singleton — avoids allocating new AsyncContext(). */
   static empty = new _AsyncContext();
+  static _current = void 0;
   static _defaults = /* @__PURE__ */ new Map();
   _values;
   constructor(values) {
     this._values = values ?? /* @__PURE__ */ new Map();
   }
+  static get current() {
+    return _als?.getStore() ?? _AsyncContext._current;
+  }
+  static set current(value) {
+    if (_als !== void 0)
+      _als.enterWith(value);
+    else
+      _AsyncContext._current = value;
+  }
+  /** True when AsyncContext.current flows across awaits (Node AsyncLocalStorage is active). */
+  static get isAsyncLocalStorageActive() {
+    return _als !== void 0;
+  }
   get(key) {
     if (this._values.has(key.id)) return this._values.get(key.id);
     if (_AsyncContext._defaults.has(key.id))
@@ -518,20 +544,27 @@ var AsyncContext = class _AsyncContext {
   }
   activate() {
     const prev = _AsyncContext.current;
-    _AsyncContext.current = this;
+    const als = _als;
+    if (als !== void 0) {
+      als.enterWith(this);
+      return { dispose: () => als.enterWith(prev) };
+    }
+    _AsyncContext._current = this;
     return {
       dispose: () => {
-        _AsyncContext.current = prev;
+        _AsyncContext._current = prev;
       }
     };
   }
   run(fn) {
-    const prev = _AsyncContext.current;
-    _AsyncContext.current = this;
+    if (_als !== void 0)
+      return _als.run(this, fn);
+    const prev = _AsyncContext._current;
+    _AsyncContext._current = this;
     try {
       return fn();
     } finally {
-      _AsyncContext.current = prev;
+      _AsyncContext._current = prev;
     }
   }
   /** Strip THIS exact instance from args if it's the last element (reference equality). */
@@ -553,6 +586,12 @@ var AsyncContext = class _AsyncContext {
   static getOrCreate() {
     return _AsyncContext.current ?? _AsyncContext.empty;
   }
+  // Toggles AsyncLocalStorage backing — for tests that exercise the browser fallback path.
+  // Clears the fallback static field so no stale context bleeds across the toggle.
+  static _setAsyncLocalStorageActive(active) {
+    _als = active ? _alsImpl : void 0;
+    _AsyncContext._current = void 0;
+  }
 };
 
 // src/async-lock.ts
@@ -562,13 +601,26 @@ var AsyncLock = class {
   get isLocked() {
     return this._locked;
   }
-  async acquire() {
+  async acquire(signal) {
+    if (signal?.aborted)
+      throw signal.reason;
     if (!this._locked) {
       this._locked = true;
       return;
     }
-    return new Promise((resolve) => {
-      this._queue.push(resolve);
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        const i = this._queue.indexOf(waiter);
+        if (i >= 0)
+          this._queue.splice(i, 1);
+        reject(signal.reason);
+      };
+      const waiter = () => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      };
+      this._queue.push(waiter);
+      signal?.addEventListener("abort", onAbort, { once: true });
     });
   }
   release() {
@@ -580,8 +632,8 @@ var AsyncLock = class {
       this._locked = false;
     }
   }
-  async run(fn) {
-    await this.acquire();
+  async run(fn, signal) {
+    await this.acquire(signal);
     try {
       return await fn();
     } finally {
@@ -602,6 +654,8 @@ var PromiseSource = class {
       this._resolve = resolve;
       this._reject = reject;
     });
+    this.promise.catch(() => {
+    });
   }
   get isCompleted() {
     return this._isCompleted;
@@ -643,7 +697,18 @@ var EventHandlerSet = class {
     this._handlers.delete(handler);
   }
   trigger(arg) {
-    for (const handler of this._handlers) handler(arg);
+    for (const handler of [...this._handlers])
+      handler(arg);
+  }
+  // Fires every handler once, isolating each so one that throws can't stop the rest.
+  triggerSafe(arg, onError) {
+    for (const handler of [...this._handlers]) {
+      try {
+        handler(arg);
+      } catch (error) {
+        onError(error);
+      }
+    }
   }
   clear() {
     this._handlers.clear();
@@ -659,6 +724,19 @@ var EventHandlerSet = class {
   }
 };
 
+// src/async-signal.ts
+var AsyncSignal = class {
+  source = new PromiseSource();
+  wait() {
+    return this.source.promise;
+  }
+  notify() {
+    const source = this.source;
+    this.source = new PromiseSource();
+    source.resolve();
+  }
+};
+
 // src/withTimeout.ts
 var TimeoutError = class extends Error {
   name = "TimeoutError";
@@ -733,9 +811,19 @@ var TimedOut = class _TimedOut {
 };
 
 // src/delay.ts
-function delayAsync(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
+function delayAsync(ms, signal) {
+  if (signal?.aborted)
+    return Promise.reject(signal.reason);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
 function delayAsyncWith(ms, value) {
@@ -747,10 +835,13 @@ function delayAsyncWith(ms, value) {
 // 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) => {
+      if (signal.aborted) {
+        reject(signal.reason);
+        return;
+      }
       signal.addEventListener("abort", () => reject(signal.reason), { once: true });
     });
     cached.catch(() => {
@@ -760,6 +851,59 @@ function abortPromise(signal) {
   return cached;
 }
 
+// src/cancellation.ts
+function isCancellation(error) {
+  return error != null && typeof error === "object" && error.name === "AbortError";
+}
+function cancellationError(message = "The operation was cancelled.") {
+  const error = new Error(message);
+  error.name = "AbortError";
+  return error;
+}
+
+// src/await-with-cleanup.ts
+function awaitWithCleanup(abortSignal, onAbort, wire) {
+  if (abortSignal?.aborted)
+    return onAbort === "reject" ? Promise.reject(abortSignal.reason ?? new Error("Operation cancelled.")) : resolvedVoidPromise;
+  const ps = new PromiseSource();
+  const cleanups = [];
+  let settled = false;
+  const runCleanups = () => {
+    for (const cleanup of cleanups)
+      cleanup();
+    cleanups.length = 0;
+  };
+  const complete = () => {
+    if (settled)
+      return;
+    settled = true;
+    runCleanups();
+    ps.resolve(void 0);
+  };
+  const addCleanup = (cleanup) => {
+    if (settled)
+      cleanup();
+    else
+      cleanups.push(cleanup);
+  };
+  if (abortSignal !== void 0) {
+    const onAbortFired = () => {
+      if (settled)
+        return;
+      settled = true;
+      runCleanups();
+      if (onAbort === "reject")
+        ps.reject(abortSignal.reason ?? new Error("Operation cancelled."));
+      else
+        ps.resolve(void 0);
+    };
+    abortSignal.addEventListener("abort", onAbortFired, { once: true });
+    cleanups.push(() => abortSignal.removeEventListener("abort", onAbortFired));
+  }
+  wire(complete, addCleanup);
+  return ps;
+}
+
 // src/internal-logging.ts
 var scopeDefaults = {
   retry: 3 /* Warn */,
@@ -1041,29 +1185,10 @@ var RetryDelayer = class {
     const actualDelayMs = Math.max(1, delayMs);
     const endsAt = Date.now() + actualDelayMs;
     const cancelSignal = this._cancelController.signal;
-    const promise = new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        cleanup();
-        resolve();
-      }, actualDelayMs);
-      const onCancel = () => {
-        clearTimeout(timer);
-        cleanup();
-        resolve();
-      };
-      const onAbort = () => {
-        clearTimeout(timer);
-        cleanup();
-        reject(new Error("Retry delay aborted."));
-      };
-      const cleanup = () => {
-        cancelSignal.removeEventListener("abort", onCancel);
-        cancellationSignal?.removeEventListener("abort", onAbort);
-      };
-      cancelSignal.addEventListener("abort", onCancel, { once: true });
-      cancellationSignal?.addEventListener("abort", onAbort, {
-        once: true
-      });
+    const combinedSignal = cancellationSignal ? AbortSignal.any([cancellationSignal, cancelSignal]) : cancelSignal;
+    const promise = delayAsync(actualDelayMs, combinedSignal).catch((e) => {
+      if (!cancelSignal.aborted)
+        throw e;
     });
     return { promise, endsAt, isLimitExceeded: false };
   }
@@ -1078,7 +1203,7 @@ var RetryDelayer = class {
 // src/retry.ts
 var { warnLog } = getLogs("retry");
 var defaultRetryDelays = () => 50;
-async function retry(tryCount, fn, retryDelays = defaultRetryDelays) {
+async function retry(tryCount, fn, retryDelays = defaultRetryDelays, signal) {
   if (tryCount <= 0)
     throw new Error("retry: tryCount must be positive.");
   let lastError;
@@ -1092,7 +1217,7 @@ async function retry(tryCount, fn, retryDelays = defaultRetryDelays) {
     ++tryIndex;
     if (tryIndex >= tryCount) throw lastError;
     warnLog?.log(`retry(${tryIndex}/${tryCount}): error:`, lastError);
-    await delayAsync(retryDelays(tryIndex));
+    await delayAsync(retryDelays(tryIndex), signal);
   }
 }
 async function catchErrors(fn, onError) {
@@ -1102,10 +1227,51 @@ async function catchErrors(fn, onError) {
     return onError ? onError(e) : void 0;
   }
 }
+
+// src/decorators.ts
+function ownMetadata(metadata, key) {
+  const bag = metadata;
+  if (!Object.hasOwn(metadata, key))
+    bag[key] = { ...bag[key] };
+  return bag[key];
+}
+function resolveArgCount(fn, explicit, methodName) {
+  if (explicit !== void 0)
+    return explicit;
+  if (hasAmbiguousArity(fn))
+    throw new Error(
+      `Cannot infer the argument count of "${methodName}": its parameter list uses default and/or rest parameters, for which Function.length is unreliable. Pass an explicit argCount to the decorator.`
+    );
+  return fn.length;
+}
+function hasAmbiguousArity(fn) {
+  const params = parameterListText(fn);
+  return params !== void 0 && (params.includes("=") || params.includes("..."));
+}
+function parameterListText(fn) {
+  const src = fn.toString();
+  const open = src.indexOf("(");
+  const arrow = src.indexOf("=>");
+  if (open < 0 || arrow >= 0 && arrow < open)
+    return void 0;
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    const ch = src[i];
+    if (ch === "(")
+      depth++;
+    else if (ch === ")") {
+      depth--;
+      if (depth === 0)
+        return src.slice(open + 1, i);
+    }
+  }
+  return void 0;
+}
 export {
   AsyncContext,
   AsyncContextKey,
   AsyncLock,
+  AsyncSignal,
   DisposableBag,
   EventHandlerSet,
   Log,
@@ -1124,6 +1290,8 @@ export {
   TimeoutError,
   abortPromise,
   abortSignalKey,
+  awaitWithCleanup,
+  cancellationError,
   catchErrors,
   createLogProvider,
   debounce,
@@ -1132,6 +1300,9 @@ export {
   errorResult,
   initLogging,
   initWorkerLogging,
+  isCancellation,
+  ownMetadata,
+  resolveArgCount,
   resolvedVoidPromise,
   result,
   resultFrom,