@actuallab/core 13.0.25 → 13.0.167

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   AsyncContext: () => AsyncContext,
   AsyncContextKey: () => AsyncContextKey,
   AsyncLock: () => AsyncLock,
+  AsyncSignal: () => AsyncSignal,
   DisposableBag: () => DisposableBag,
   EventHandlerSet: () => EventHandlerSet,
   Log: () => Log,
@@ -41,6 +42,8 @@ __export(index_exports, {
   TimeoutError: () => TimeoutError,
   abortPromise: () => abortPromise,
   abortSignalKey: () => abortSignalKey,
+  awaitWithCleanup: () => awaitWithCleanup,
+  cancellationError: () => cancellationError,
   catchErrors: () => catchErrors,
   createLogProvider: () => createLogProvider,
   debounce: () => debounce,
@@ -49,6 +52,9 @@ __export(index_exports, {
   errorResult: () => errorResult,
   initLogging: () => initLogging,
   initWorkerLogging: () => initWorkerLogging,
+  isCancellation: () => isCancellation,
+  ownMetadata: () => ownMetadata,
+  resolveArgCount: () => resolveArgCount,
   resolvedVoidPromise: () => resolvedVoidPromise,
   result: () => result,
   resultFrom: () => resultFrom,
@@ -501,9 +507,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;
   }
@@ -517,11 +523,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) {
@@ -558,15 +570,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))
@@ -580,20 +612,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). */
@@ -615,6 +654,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
@@ -624,13 +669,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() {
@@ -642,8 +700,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 {
@@ -664,6 +722,8 @@ var PromiseSource = class {
       this._resolve = resolve;
       this._reject = reject;
     });
+    this.promise.catch(() => {
+    });
   }
   get isCompleted() {
     return this._isCompleted;
@@ -705,7 +765,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();
@@ -721,6 +792,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";
@@ -795,9 +879,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) {
@@ -809,10 +903,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(() => {
@@ -822,6 +919,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 */,
@@ -1103,29 +1253,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 };
   }
@@ -1140,7 +1271,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;
@@ -1154,7 +1285,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) {
@@ -1164,11 +1295,52 @@ 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;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AsyncContext,
   AsyncContextKey,
   AsyncLock,
+  AsyncSignal,
   DisposableBag,
   EventHandlerSet,
   Log,
@@ -1187,6 +1359,8 @@ async function catchErrors(fn, onError) {
   TimeoutError,
   abortPromise,
   abortSignalKey,
+  awaitWithCleanup,
+  cancellationError,
   catchErrors,
   createLogProvider,
   debounce,
@@ -1195,6 +1369,9 @@ async function catchErrors(fn, onError) {
   errorResult,
   initLogging,
   initWorkerLogging,
+  isCancellation,
+  ownMetadata,
+  resolveArgCount,
   resolvedVoidPromise,
   result,
   resultFrom,