abxbus 2.5.1 → 2.5.4

package/dist/cjs/event_result.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { BaseEvent } from './base_event.js';
+import type { EventBus } from './event_bus.js';
+import { EventHandler } from './event_handler.js';
+import { type HandlerLock } from './lock_manager.js';
+import type { Deferred } from './lock_manager.js';
+import type { EventResultType } from './types.js';
+export type EventResultStatus = 'pending' | 'started' | 'completed' | 'error';
+export declare const EventResultJSONSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        started: "started";
+        completed: "completed";
+        error: "error";
+    }>;
+    event_id: z.ZodString;
+    handler_id: z.ZodString;
+    handler_name: z.ZodString;
+    handler_file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    handler_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    handler_slow_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    handler_registered_at: z.ZodOptional<z.ZodString>;
+    handler_event_pattern: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"*">]>>;
+    eventbus_name: z.ZodString;
+    eventbus_id: z.ZodString;
+    started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodUnknown>;
+    event_children: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type EventResultJSON = z.infer<typeof EventResultJSONSchema>;
+export declare class EventResult<TEvent extends BaseEvent = BaseEvent> {
+    id: string;
+    status: EventResultStatus;
+    event: TEvent;
+    handler: EventHandler;
+    started_at: string | null;
+    completed_at: string | null;
+    result?: EventResultType<TEvent>;
+    error?: unknown;
+    event_children: BaseEvent[];
+    _abort: Deferred<never> | null;
+    _lock: HandlerLock | null;
+    _queue_jump_pause_releases: Map<EventBus, () => void> | null;
+    constructor(params: {
+        event: TEvent;
+        handler: EventHandler;
+    });
+    toString(): string;
+    get event_id(): string;
+    get bus(): EventBus;
+    get handler_id(): string;
+    get handler_name(): string;
+    get handler_file_path(): string | null;
+    get eventbus_name(): string;
+    get eventbus_id(): string;
+    get eventbus_label(): string;
+    private getHookBus;
+    private _notifyStatusHook;
+    get value(): EventResultType<TEvent> | undefined;
+    get result_type(): TEvent['event_result_type'];
+    _linkEmittedChildEvent(child_event: BaseEvent): void;
+    get raw_value(): EventResultType<TEvent> | undefined;
+    get handler_timeout(): number | null;
+    get handler_slow_timeout(): number | null;
+    _createSlowHandlerWarningTimer(effective_timeout: number | null): ReturnType<typeof setTimeout> | null;
+    _ensureQueueJumpPause(bus: EventBus): void;
+    _releaseQueueJumpPauses(): void;
+    update(params: {
+        status?: EventResultStatus;
+        result?: EventResultType<TEvent> | BaseEvent | undefined;
+        error?: unknown;
+    }): this;
+    private _createHandlerTimeoutError;
+    private _handleHandlerError;
+    private _onHandlerExit;
+    runHandler(handler_lock: HandlerLock | null): Promise<void>;
+    _signalAbort(error: Error): void;
+    _markStarted(notify_hook?: boolean): Promise<never>;
+    _markCompleted(result: EventResultType<TEvent> | BaseEvent | undefined, notify_hook?: boolean): void;
+    _markError(error: unknown, notify_hook?: boolean): void;
+    toJSON(): EventResultJSON;
+    static fromJSON<TEvent extends BaseEvent>(event: TEvent, data: unknown): EventResult<TEvent>;
+}

package/dist/cjs/lock_manager.d.ts

@@ -0,0 +1,70 @@
+import type { BaseEvent } from './base_event.js';
+import type { EventResult } from './event_result.js';
+export type Deferred<T> = {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+};
+export declare const withResolvers: <T>() => Deferred<T>;
+export declare const EVENT_CONCURRENCY_MODES: readonly ["global-serial", "bus-serial", "parallel"];
+export type EventConcurrencyMode = (typeof EVENT_CONCURRENCY_MODES)[number];
+export declare const EVENT_HANDLER_CONCURRENCY_MODES: readonly ["serial", "parallel"];
+export type EventHandlerConcurrencyMode = (typeof EVENT_HANDLER_CONCURRENCY_MODES)[number];
+export declare const EVENT_HANDLER_COMPLETION_MODES: readonly ["all", "first"];
+export type EventHandlerCompletionMode = (typeof EVENT_HANDLER_COMPLETION_MODES)[number];
+export declare class AsyncLock {
+    size: number;
+    in_use: number;
+    waiters: Array<() => void>;
+    constructor(size: number);
+    acquire(): Promise<void>;
+    release(): void;
+}
+export declare const runWithLock: <T>(lock: AsyncLock | null, fn: () => Promise<T>) => Promise<T>;
+export type HandlerExecutionState = 'held' | 'yielded' | 'closed';
+export declare class HandlerLock {
+    private lock;
+    private state;
+    constructor(lock: AsyncLock | null);
+    yieldHandlerLockForChildRun(): boolean;
+    reclaimHandlerLockIfRunning(): Promise<boolean>;
+    exitHandlerRun(): void;
+    runQueueJump<T>(fn: () => Promise<T>): Promise<T>;
+}
+export type EventBusInterfaceForLockManager = {
+    isIdleAndQueueEmpty: () => boolean;
+    event_concurrency: EventConcurrencyMode;
+    _lock_for_event_global_serial: AsyncLock;
+};
+export type LockManagerOptions = {
+    auto_schedule_idle_checks?: boolean;
+};
+export declare class LockManager {
+    private bus;
+    private auto_schedule_idle_checks;
+    readonly bus_event_lock: AsyncLock;
+    private pause_depth;
+    private pause_waiters;
+    private active_handler_results;
+    private idle_waiters;
+    private idle_check_pending;
+    private idle_check_streak;
+    constructor(bus: EventBusInterfaceForLockManager, options?: LockManagerOptions);
+    _requestRunloopPause(): () => void;
+    _waitUntilRunloopResumed(): Promise<void>;
+    _isPaused(): boolean;
+    _runWithHandlerDispatchContext<T>(result: EventResult, fn: () => Promise<T>): Promise<T>;
+    _getActiveHandlerResultForCurrentAsyncContext(): EventResult | undefined;
+    _getActiveHandlerResults(): EventResult[];
+    _isAnyHandlerActive(): boolean;
+    waitForIdle(timeout_seconds?: number | null): Promise<boolean>;
+    _notifyIdleListeners(): void;
+    getLockForEvent(event: BaseEvent): AsyncLock | null;
+    _runWithEventLock<T>(event: BaseEvent, fn: () => Promise<T>, options?: {
+        bypass_event_locks?: boolean;
+        pre_acquired_lock?: AsyncLock | null;
+    }): Promise<T>;
+    _runWithHandlerLock<T>(event: BaseEvent, default_handler_concurrency: EventHandlerConcurrencyMode | undefined, fn: (lock: HandlerLock | null) => Promise<T>): Promise<T>;
+    private scheduleIdleCheck;
+    clear(): void;
+}

package/dist/cjs/retry.d.ts

@@ -1,4 +1,11 @@
 type SemaphoreScope = 'multiprocess' | 'global' | 'class' | 'instance';
+type AnyFunction = (this: any, ...args: any[]) => any;
+type LegacyMethodDescriptor = TypedPropertyDescriptor<AnyFunction>;
+type RetryDecorator = {
+    <T extends AnyFunction>(target: T): T;
+    <T extends AnyFunction>(target: T, context: ClassMethodDecoratorContext): T;
+    (target: object, property_key: string | symbol, descriptor: LegacyMethodDescriptor): LegacyMethodDescriptor;
+};
 export interface RetryOptions {
     /** Total number of attempts including the initial call (1 = no retry, 3 = up to 2 retries). Default: 1 */
     max_attempts?: number;
@@ -51,5 +58,5 @@ export declare class SemaphoreTimeoutError extends Error {
 }
 /** Reset the global semaphore registry. Useful in tests. */
 export declare function clearSemaphoreRegistry(): void;
-export declare function retry(options?: RetryOptions): <T extends (...args: any[]) => any>(target: T, _context?: ClassMethodDecoratorContext) => T;
+export declare function retry(options?: RetryOptions): RetryDecorator;
 export {};

package/dist/cjs/retry.js

@@ -84,12 +84,18 @@ class RetrySemaphore {
     this.inUse = 0;
     this.waiters = [];
   }
-  async acquire() {
+  tryAcquire() {
     if (this.size === Infinity) {
-      return;
+      return true;
     }
     if (this.inUse < this.size) {
       this.inUse += 1;
+      return true;
+    }
+    return false;
+  }
+  async acquire() {
+    if (this.tryAcquire()) {
       return;
     }
     await new Promise((resolve) => {
@@ -133,11 +139,51 @@ function retry(options = {}) {
     semaphore_scope = "global",
     semaphore_timeout
   } = options;
-  return function decorator(target, _context) {
+  const decorateFunction = (target, _context) => {
     const fn_name = target.name || _context?.name || "anonymous";
     const effective_max_attempts = Math.max(1, max_attempts);
     const effective_retry_after = Math.max(0, retry_after);
-    async function retryWrapper(...args) {
+    const shouldRetry = (error) => {
+      if (!retry_on_errors || retry_on_errors.length === 0) return true;
+      return retry_on_errors.some(
+        (matcher) => typeof matcher === "string" ? error?.name === matcher : matcher instanceof RegExp ? matcher.test(String(error)) : error instanceof matcher
+      );
+    };
+    const asyncRetryDelay = async (attempt) => {
+      const delay_seconds = effective_retry_after * Math.pow(retry_backoff_factor, attempt - 1);
+      if (delay_seconds > 0) {
+        await sleep(delay_seconds * 1e3);
+      }
+    };
+    const syncRetryDelay = (attempt) => {
+      const delay_seconds = effective_retry_after * Math.pow(retry_backoff_factor, attempt - 1);
+      if (delay_seconds > 0) {
+        sleepSync(delay_seconds * 1e3);
+      }
+    };
+    const runRetryLoopFromThenable = async (this_arg, args, first_thenable, first_attempt) => {
+      let current_result = first_thenable;
+      for (let attempt = first_attempt; attempt <= effective_max_attempts; attempt++) {
+        try {
+          if (attempt !== first_attempt) {
+            current_result = target.apply(this_arg, args);
+          }
+          if (isThenable(current_result)) {
+            if (timeout != null && timeout > 0) {
+              return await _runWithTimeout(() => Promise.resolve(current_result), timeout * 1e3, attempt);
+            }
+            return await current_result;
+          }
+          return current_result;
+        } catch (error) {
+          if (!shouldRetry(error)) throw error;
+          if (attempt >= effective_max_attempts) throw error;
+          await asyncRetryDelay(attempt);
+        }
+      }
+      throw new Error(`retry(${fn_name}): unexpected end of retry loop`);
+    };
+    async function asyncRetryWrapper(...args) {
       const base_name = typeof semaphore_name_option === "function" ? semaphore_name_option(...args) : semaphore_name_option ?? fn_name;
       const sem_name = typeof base_name === "string" ? base_name : String(base_name);
       const scoped_key = scopedSemaphoreKey(sem_name, semaphore_scope, this);
@@ -202,17 +248,9 @@ function retry(options = {}) {
               return await Promise.resolve(target.apply(this, args));
             }
           } catch (error) {
-            if (retry_on_errors && retry_on_errors.length > 0) {
-              const is_retryable = retry_on_errors.some(
-                (matcher) => typeof matcher === "string" ? error?.name === matcher : matcher instanceof RegExp ? matcher.test(String(error)) : error instanceof matcher
-              );
-              if (!is_retryable) throw error;
-            }
+            if (!shouldRetry(error)) throw error;
             if (attempt >= effective_max_attempts) throw error;
-            const delay_seconds = effective_retry_after * Math.pow(retry_backoff_factor, attempt - 1);
-            if (delay_seconds > 0) {
-              await sleep(delay_seconds * 1e3);
-            }
+            await asyncRetryDelay(attempt);
           }
         }
         throw new Error(`retry(${fn_name}): unexpected end of retry loop`);
@@ -227,6 +265,79 @@ function retry(options = {}) {
         }
       }
     }
+    function syncRetryWrapper(...args) {
+      const base_name = typeof semaphore_name_option === "function" ? semaphore_name_option(...args) : semaphore_name_option ?? fn_name;
+      const sem_name = typeof base_name === "string" ? base_name : String(base_name);
+      const scoped_key = scopedSemaphoreKey(sem_name, semaphore_scope, this);
+      const held = getHeldSemaphores();
+      const needs_semaphore = semaphore_limit != null && semaphore_limit > 0;
+      const is_reentrant = needs_semaphore && held.has(scoped_key);
+      let semaphore = null;
+      let multiprocess_lock = null;
+      let semaphore_acquired = false;
+      if (needs_semaphore && !is_reentrant) {
+        const effective_sem_timeout = semaphore_timeout != null ? semaphore_timeout : timeout != null ? timeout * Math.max(1, semaphore_limit - 1) : null;
+        if (semaphore_scope === "multiprocess") {
+          if ((0, import_optional_deps.isNodeRuntime)()) {
+            multiprocess_lock = acquireMultiprocessSemaphoreSync(scoped_key, semaphore_limit, effective_sem_timeout, semaphore_lax);
+            semaphore_acquired = multiprocess_lock !== null;
+          } else {
+            logMultiprocessFallbackOnce("multiprocess semaphores require a Node.js runtime; falling back to in-process global scope");
+            semaphore = getOrCreateSemaphore(scoped_key, semaphore_limit);
+            semaphore_acquired = acquireSemaphoreSyncOrThrow(semaphore, scoped_key, semaphore_limit, effective_sem_timeout, semaphore_lax);
+          }
+        } else {
+          semaphore = getOrCreateSemaphore(scoped_key, semaphore_limit);
+          semaphore_acquired = acquireSemaphoreSyncOrThrow(semaphore, scoped_key, semaphore_limit, effective_sem_timeout, semaphore_lax);
+        }
+      }
+      const new_held = new Set(held);
+      if (semaphore_acquired) {
+        new_held.add(scoped_key);
+      }
+      const release = () => {
+        if (semaphore_acquired && multiprocess_lock) {
+          multiprocess_lock.release();
+        } else if (semaphore_acquired && semaphore) {
+          semaphore.release();
+        }
+      };
+      const runRetryLoop = () => {
+        for (let attempt = 1; attempt <= effective_max_attempts; attempt++) {
+          const attempt_started_at = Date.now();
+          try {
+            const result = target.apply(this, args);
+            if (isThenable(result)) {
+              return runRetryLoopFromThenable(this, args, result, attempt);
+            }
+            if (timeout != null && timeout > 0 && Date.now() - attempt_started_at > timeout * 1e3) {
+              throw new RetryTimeoutError(`Timed out after ${timeout}s (attempt ${attempt})`, {
+                timeout_seconds: timeout,
+                attempt
+              });
+            }
+            return result;
+          } catch (error) {
+            if (!shouldRetry(error)) throw error;
+            if (attempt >= effective_max_attempts) throw error;
+            syncRetryDelay(attempt);
+          }
+        }
+        throw new Error(`retry(${fn_name}): unexpected end of retry loop`);
+      };
+      try {
+        const result = runWithHeldSemaphores(new_held, runRetryLoop);
+        if (isThenable(result)) {
+          return Promise.resolve(result).finally(release);
+        }
+        release();
+        return result;
+      } catch (error) {
+        release();
+        throw error;
+      }
+    }
+    const retryWrapper = isAsyncFunction(target) ? asyncRetryWrapper : syncRetryWrapper;
     Object.defineProperty(retryWrapper, "name", { value: fn_name, configurable: true });
     if (_context?.kind === "method" && typeof _context.addInitializer === "function") {
       _context.addInitializer(function() {
@@ -238,6 +349,17 @@ function retry(options = {}) {
     }
     return retryWrapper;
   };
+  function decorator(target, context_or_property_key, descriptor) {
+    if (descriptor?.value && typeof descriptor.value === "function") {
+      descriptor.value = decorateFunction(descriptor.value);
+      return descriptor;
+    }
+    if (typeof target === "function") {
+      return decorateFunction(target, typeof context_or_property_key === "object" ? context_or_property_key : void 0);
+    }
+    throw new TypeError("retry() can only decorate functions and class methods");
+  }
+  return decorator;
 }
 function findDecoratedMethodOwnerName(context_this, context, replacement) {
   const method_name = context.name;
@@ -270,6 +392,12 @@ function findDecoratedMethodOwnerName(context_this, context, replacement) {
   }
   return null;
 }
+function isAsyncFunction(fn) {
+  return Object.prototype.toString.call(fn) === "[object AsyncFunction]";
+}
+function isThenable(value) {
+  return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+}
 async function acquireWithTimeout(semaphore, timeout_ms) {
   return new Promise((resolve) => {
     let settled = false;
@@ -290,11 +418,51 @@ async function acquireWithTimeout(semaphore, timeout_ms) {
     });
   });
 }
+function acquireSemaphoreSyncOrThrow(semaphore, scoped_key, semaphore_limit, timeout_seconds, semaphore_lax) {
+  const acquired = acquireSemaphoreSync(semaphore, timeout_seconds == null ? null : timeout_seconds * 1e3);
+  if (acquired) return true;
+  if (!semaphore_lax) {
+    throw new SemaphoreTimeoutError(`Failed to acquire semaphore "${scoped_key}" within ${timeout_seconds}s (limit=${semaphore_limit})`, {
+      semaphore_name: scoped_key,
+      semaphore_limit,
+      timeout_seconds: timeout_seconds ?? 0
+    });
+  }
+  return false;
+}
+function acquireSemaphoreSync(semaphore, timeout_ms) {
+  if (semaphore.tryAcquire()) return true;
+  const start = Date.now();
+  while (true) {
+    if (timeout_ms != null && timeout_ms > 0 && Date.now() - start >= timeout_ms) {
+      return false;
+    }
+    sleepSync(10);
+    if (semaphore.tryAcquire()) return true;
+  }
+}
 function logMultiprocessFallbackOnce(reason) {
   if (multiprocess_fallback_reason_logged === reason) return;
   multiprocess_fallback_reason_logged = reason;
   console.warn(`[abxbus.retry] ${reason}`);
 }
+function importNodeModuleSync(specifier) {
+  const maybe_process = globalThis.process;
+  const get_builtin_module = maybe_process?.getBuiltinModule;
+  const bare_specifier = specifier.startsWith("node:") ? specifier.slice("node:".length) : specifier;
+  if (typeof get_builtin_module === "function") {
+    const builtin = get_builtin_module(bare_specifier) ?? get_builtin_module(specifier);
+    if (builtin) return builtin;
+  }
+  let require_fn;
+  try {
+    require_fn = Function('return typeof require === "function" ? require : undefined')();
+  } catch {
+    require_fn = void 0;
+  }
+  if (require_fn) return require_fn(specifier);
+  throw new Error("[abxbus.retry] synchronous Node.js module loading is unavailable; cannot use sync multiprocess semaphores");
+}
 async function importNodeModule(specifier) {
   const dynamic_import = Function("module_name", "return import(module_name)");
   return dynamic_import(specifier);
@@ -385,6 +553,90 @@ async function acquireMultiprocessSemaphore(scoped_key, semaphore_limit, semapho
   }
   return null;
 }
+function acquireMultiprocessSemaphoreSync(scoped_key, semaphore_limit, semaphore_timeout_seconds, semaphore_lax) {
+  const crypto = importNodeModuleSync("node:crypto");
+  const fs = importNodeModuleSync("node:fs");
+  const os = importNodeModuleSync("node:os");
+  const path = importNodeModuleSync("node:path");
+  const semaphore_directory = path.join(os.tmpdir(), MULTIPROCESS_SEMAPHORE_DIRNAME);
+  const lock_prefix = crypto.createHash("sha256").update(scoped_key).digest("hex").slice(0, 40);
+  fs.mkdirSync(semaphore_directory, { recursive: true });
+  const start = Date.now();
+  let retry_delay_ms = 100;
+  while (true) {
+    const elapsed_ms = Date.now() - start;
+    const remaining_ms = semaphore_timeout_seconds != null && semaphore_timeout_seconds > 0 ? semaphore_timeout_seconds * 1e3 - elapsed_ms : null;
+    if (remaining_ms != null && remaining_ms <= 0) {
+      break;
+    }
+    for (let slot = 0; slot < semaphore_limit; slot++) {
+      const slot_file = path.join(semaphore_directory, `${lock_prefix}.${String(slot).padStart(2, "0")}.lock`);
+      const token = `${process.pid}:${Date.now()}:${Math.random().toString(16).slice(2)}`;
+      try {
+        const fd = fs.openSync(slot_file, "wx", 384);
+        try {
+          fs.writeFileSync(
+            fd,
+            JSON.stringify({
+              token,
+              pid: process.pid,
+              semaphore_name: scoped_key,
+              created_at_ms: Date.now()
+            }),
+            "utf8"
+          );
+        } finally {
+          fs.closeSync(fd);
+        }
+        return {
+          release: () => {
+            try {
+              const raw = String(fs.readFileSync(slot_file, "utf8") || "").trim();
+              const current_owner = raw ? JSON.parse(raw) : null;
+              if (current_owner?.token === token) {
+                fs.unlinkSync(slot_file);
+              }
+            } catch {
+            }
+          }
+        };
+      } catch (error) {
+        if (!(error instanceof Error) || error.code !== "EEXIST") {
+          throw error;
+        }
+        try {
+          const raw = String(fs.readFileSync(slot_file, "utf8") || "").trim();
+          const current_owner = raw ? JSON.parse(raw) : null;
+          const current_pid = typeof current_owner?.pid === "number" ? current_owner.pid : null;
+          if (current_pid != null) {
+            try {
+              process.kill(current_pid, 0);
+              continue;
+            } catch {
+            }
+          }
+          const slot_age_ms = Date.now() - fs.statSync(slot_file).mtimeMs;
+          if (current_pid != null || slot_age_ms >= MULTIPROCESS_STALE_LOCK_MS) {
+            fs.unlinkSync(slot_file);
+          }
+        } catch {
+        }
+      }
+    }
+    const sleep_ms = Math.min(retry_delay_ms, remaining_ms ?? retry_delay_ms);
+    if (sleep_ms > 0) {
+      sleepSync(sleep_ms);
+    }
+    retry_delay_ms = Math.min(retry_delay_ms * 2, 1e3);
+  }
+  if (!semaphore_lax) {
+    throw new SemaphoreTimeoutError(
+      `Failed to acquire semaphore "${scoped_key}" within ${semaphore_timeout_seconds}s (limit=${semaphore_limit})`,
+      { semaphore_name: scoped_key, semaphore_limit, timeout_seconds: semaphore_timeout_seconds ?? 0 }
+    );
+  }
+  return null;
+}
 async function _runWithTimeout(fn, timeout_ms, attempt) {
   return new Promise((resolve, reject) => {
     let settled = false;
@@ -420,4 +672,21 @@ async function _runWithTimeout(fn, timeout_ms, attempt) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function sleepSync(ms) {
+  if (ms <= 0) return;
+  const shared_array_buffer = globalThis.SharedArrayBuffer;
+  const atomics = globalThis.Atomics;
+  if (typeof shared_array_buffer === "function" && typeof atomics?.wait === "function") {
+    try {
+      const buffer = new shared_array_buffer(4);
+      const view = new Int32Array(buffer);
+      atomics.wait(view, 0, 0, ms);
+      return;
+    } catch {
+    }
+  }
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+  }
+}
 //# sourceMappingURL=retry.js.map