@private.me/xbind 3.0.2 → 3.0.4

package/dist-standalone/timeouts.js

@@ -1,398 +1 @@
-/**
- * @module timeouts
- * Configurable request timeouts for xBind operations
- *
- * Provides centralized timeout management with:
- * - Per-operation timeout configuration
- * - Default timeouts for registry, gateway, transport
- * - Timeout inheritance and overrides
- * - Timeout error messages with context
- * - Integration with AbortController/cancellation tokens
- *
- * @example
- * ```typescript
- * import { TimeoutConfig, withTimeout, createTimeoutController } from '@private.me/xbind';
- *
- * // Create timeout configuration
- * const config = new TimeoutConfig({
- *   registry: 10000,
- *   gateway: 15000,
- *   transport: 30000,
- * });
- *
- * // Use timeout with fetch
- * const controller = createTimeoutController(config.registry);
- * const response = await fetch(url, { signal: controller.signal });
- *
- * // Wrap async operation with timeout
- * const result = await withTimeout(
- *   async () => performOperation(),
- *   5000,
- *   'Operation description'
- * );
- * ```
- */
-import { err, ok } from"./_deps/shared/index.js";
-/**
- * Timeout error with operation context.
- */
-export class TimeoutError extends Error {
-    code = 'TIMEOUT';
-    operation;
-    timeoutMs;
-    timestamp;
-    constructor(operation, timeoutMs) {
-        super(`Operation '${operation}' timed out after ${timeoutMs}ms. ` +
-            `Actions: (1) Check network connectivity, (2) Increase timeout threshold, ` +
-            `(3) Verify service availability, (4) Implement retry with exponential backoff.`);
-        this.name = 'TimeoutError';
-        this.operation = operation;
-        this.timeoutMs = timeoutMs;
-        this.timestamp = Date.now();
-    }
-    /**
-     * Create timeout error with additional context.
-     */
-    static withContext(operation, timeoutMs, context) {
-        const error = new TimeoutError(operation, timeoutMs);
-        if (context) {
-            Object.assign(error, { context });
-        }
-        return error;
-    }
-}
-/**
- * Default timeout values (milliseconds).
- */
-export const DEFAULT_TIMEOUTS = {
-    registry: 10_000, // 10 seconds for registry lookups
-    gateway: 15_000, // 15 seconds for gateway operations
-    transport: 30_000, // 30 seconds for transport/HTTP
-    default: 30_000, // 30 seconds fallback
-};
-/**
- * Timeout configuration manager.
- * Provides timeout values with inheritance and override support.
- */
-export class TimeoutConfig {
-    registry;
-    gateway;
-    transport;
-    default;
-    constructor(options = {}) {
-        this.registry = options.registry ?? DEFAULT_TIMEOUTS.registry;
-        this.gateway = options.gateway ?? DEFAULT_TIMEOUTS.gateway;
-        this.transport = options.transport ?? DEFAULT_TIMEOUTS.transport;
-        this.default = options.default ?? DEFAULT_TIMEOUTS.default;
-        // Validate timeout values
-        this.validateTimeout('registry', this.registry);
-        this.validateTimeout('gateway', this.gateway);
-        this.validateTimeout('transport', this.transport);
-        this.validateTimeout('default', this.default);
-    }
-    /**
-     * Get timeout for registry operations.
-     * @param override - Optional override timeout
-     */
-    getRegistry(override) {
-        return override ?? this.registry;
-    }
-    /**
-     * Get timeout for gateway operations.
-     * @param override - Optional override timeout
-     */
-    getGateway(override) {
-        return override ?? this.gateway;
-    }
-    /**
-     * Get timeout for transport operations.
-     * @param override - Optional override timeout
-     */
-    getTransport(override) {
-        return override ?? this.transport;
-    }
-    /**
-     * Get default timeout.
-     * @param override - Optional override timeout
-     */
-    getDefault(override) {
-        return override ?? this.default;
-    }
-    /**
-     * Get timeout for specific operation category.
-     * @param category - Operation category
-     * @param override - Optional override timeout
-     */
-    get(category, override) {
-        switch (category) {
-            case 'registry':
-                return this.getRegistry(override);
-            case 'gateway':
-                return this.getGateway(override);
-            case 'transport':
-                return this.getTransport(override);
-            case 'default':
-                return this.getDefault(override);
-        }
-    }
-    /**
-     * Create new config with overrides.
-     * @param overrides - Timeout overrides
-     */
-    with(overrides) {
-        return new TimeoutConfig({
-            registry: overrides.registry ?? this.registry,
-            gateway: overrides.gateway ?? this.gateway,
-            transport: overrides.transport ?? this.transport,
-            default: overrides.default ?? this.default,
-        });
-    }
-    /**
-     * Validate timeout value.
-     */
-    validateTimeout(name, value) {
-        if (!Number.isFinite(value) || value <= 0) {
-            throw new Error(`Invalid timeout for '${name}': ${value}. Must be positive finite number.`);
-        }
-        if (value > 300_000) {
-            // Warn if timeout > 5 minutes (likely config error)
-            console.warn(`[xbind:timeout] Large timeout for '${name}': ${value}ms. ` +
-                `Consider reducing to avoid indefinite hangs.`);
-        }
-    }
-    /**
-     * Export configuration as plain object.
-     */
-    toJSON() {
-        return {
-            registry: this.registry,
-            gateway: this.gateway,
-            transport: this.transport,
-            default: this.default,
-        };
-    }
-}
-/**
- * Operation timeout controller with cancellation support.
- * Wraps AbortController with timeout semantics.
- */
-export class OperationTimeoutController {
-    signal;
-    timeoutMs;
-    operation;
-    controller;
-    timer;
-    timedOut = false;
-    constructor(timeoutMs, operation = 'operation') {
-        this.controller = new AbortController();
-        this.signal = this.controller.signal;
-        this.timeoutMs = timeoutMs;
-        this.operation = operation;
-        // Set timeout
-        this.timer = setTimeout(() => {
-            this.timedOut = true;
-            this.controller.abort();
-        }, timeoutMs);
-    }
-    /**
-     * Cancel the operation (clear timeout).
-     */
-    cancel() {
-        clearTimeout(this.timer);
-        if (!this.controller.signal.aborted) {
-            this.controller.abort();
-        }
-    }
-    /**
-     * Clear timeout if operation completed successfully.
-     * Call this when operation finishes to prevent unnecessary abort.
-     */
-    clear() {
-        clearTimeout(this.timer);
-    }
-    /**
-     * Check if controller timed out (vs manual cancellation).
-     */
-    didTimeout() {
-        return this.timedOut;
-    }
-    /**
-     * Get timeout error if operation timed out.
-     */
-    getTimeoutError() {
-        return this.timedOut ? new TimeoutError(this.operation, this.timeoutMs) : null;
-    }
-}
-/**
- * Create timeout controller for operation.
- * @param timeoutMs - Timeout in milliseconds
- * @param operation - Operation description for error messages
- */
-export function createTimeoutController(timeoutMs, operation = 'operation') {
-    return new OperationTimeoutController(timeoutMs, operation);
-}
-/**
- * Wrap async operation with timeout.
- * Rejects with TimeoutError if operation exceeds timeout.
- *
- * @param fn - Async operation to execute
- * @param timeoutMs - Timeout in milliseconds
- * @param operation - Operation description for error messages
- * @returns Result of operation or timeout error
- *
- * @example
- * ```typescript
- * const result = await withTimeout(
- *   async () => fetch('https://api.example.com'),
- *   5000,
- *   'API request'
- * );
- * ```
- */
-export async function withTimeout(fn, timeoutMs, operation = 'operation') {
-    const controller = createTimeoutController(timeoutMs, operation);
-    try {
-        const result = await Promise.race([
-            fn(),
-            new Promise((_, reject) => {
-                controller.signal.addEventListener('abort', () => {
-                    reject(new TimeoutError(operation, timeoutMs));
-                });
-            }),
-        ]);
-        controller.clear();
-        return result;
-    }
-    catch (error) {
-        controller.clear();
-        throw error;
-    }
-}
-/**
- * Wrap async operation with timeout (Result-based).
- * Returns ok(result) or err('TIMEOUT') without throwing.
- *
- * @param fn - Async operation to execute
- * @param timeoutMs - Timeout in milliseconds
- * @param operation - Operation description for error messages
- * @returns Result with operation result or timeout error
- *
- * @example
- * ```typescript
- * const result = await withTimeoutResult(
- *   async () => fetch('https://api.example.com'),
- *   5000,
- *   'API request'
- * );
- * if (result.ok) {
- *   console.log('Success:', result.value);
- * } else {
- *   console.error('Timeout:', result.error);
- * }
- * ```
- */
-export async function withTimeoutResult(fn, timeoutMs, operation = 'operation') {
-    try {
-        const result = await withTimeout(fn, timeoutMs, operation);
-        return ok(result);
-    }
-    catch (error) {
-        if (error instanceof TimeoutError) {
-            return err('TIMEOUT');
-        }
-        throw error; // Re-throw non-timeout errors
-    }
-}
-/**
- * Create timeout signal for use with fetch/AbortController APIs.
- *
- * @param timeoutMs - Timeout in milliseconds
- * @param operation - Operation description
- * @returns AbortSignal that aborts after timeout
- *
- * @example
- * ```typescript
- * const signal = createOperationTimeoutSignal(5000, 'fetch request');
- * const response = await fetch(url, { signal });
- * ```
- */
-export function createOperationTimeoutSignal(timeoutMs, operation = 'operation') {
-    return createTimeoutController(timeoutMs, operation).signal;
-}
-/**
- * Timeout helper for operations with cancellation token.
- * Returns controller that can be passed to fetch, agent.send, etc.
- *
- * @param config - Timeout configuration
- * @param category - Operation category
- * @param operation - Operation description
- * @param override - Optional timeout override
- * @returns Timeout controller
- *
- * @example
- * ```typescript
- * const controller = createOperationTimeout(config, 'registry', 'lookup DID');
- * const response = await fetch(url, { signal: controller.signal });
- * controller.clear(); // Clear timeout on success
- * ```
- */
-export function createOperationTimeout(config, category, operation, override) {
-    const timeoutMs = config.get(category, override);
-    return createTimeoutController(timeoutMs, operation);
-}
-/**
- * Check if error is a timeout error.
- */
-export function isTimeoutError(error) {
-    return error instanceof TimeoutError;
-}
-/**
- * Extract timeout from error if it's a timeout error.
- * Returns timeout in milliseconds or undefined.
- */
-export function getTimeoutFromError(error) {
-    return isTimeoutError(error) ? error.timeoutMs : undefined;
-}
-/**
- * Create timeout configuration from environment variables.
- * Looks for:
- * - XBIND_TIMEOUT_REGISTRY
- * - XBIND_TIMEOUT_GATEWAY
- * - XBIND_TIMEOUT_TRANSPORT
- * - XBIND_TIMEOUT_DEFAULT
- *
- * Falls back to default values if not set.
- */
-export function createTimeoutConfigFromEnv() {
-    const options = {};
-    const registry = process.env.XBIND_TIMEOUT_REGISTRY;
-    if (registry) {
-        const parsed = parseInt(registry, 10);
-        if (!isNaN(parsed))
-            options.registry = parsed;
-    }
-    const gateway = process.env.XBIND_TIMEOUT_GATEWAY;
-    if (gateway) {
-        const parsed = parseInt(gateway, 10);
-        if (!isNaN(parsed))
-            options.gateway = parsed;
-    }
-    const transport = process.env.XBIND_TIMEOUT_TRANSPORT;
-    if (transport) {
-        const parsed = parseInt(transport, 10);
-        if (!isNaN(parsed))
-            options.transport = parsed;
-    }
-    const defaultTimeout = process.env.XBIND_TIMEOUT_DEFAULT;
-    if (defaultTimeout) {
-        const parsed = parseInt(defaultTimeout, 10);
-        if (!isNaN(parsed))
-            options.default = parsed;
-    }
-    return new TimeoutConfig(options);
-}
-/**
- * Global default timeout configuration.
- * Can be overridden by setting environment variables.
- */
-export const globalTimeoutConfig = createTimeoutConfigFromEnv();
+import{err,ok}from"./_deps/shared/index.js";export class TimeoutError extends Error{code="TIMEOUT";operation;timeoutMs;timestamp;constructor(t,e){super(`Operation '${t}' timed out after ${e}ms. Actions: (1) Check network connectivity, (2) Increase timeout threshold, (3) Verify service availability, (4) Implement retry with exponential backoff.`),this.name="TimeoutError",this.operation=t,this.timeoutMs=e,this.timestamp=Date.now()}static withContext(t,e,r){const i=new TimeoutError(t,e);return r&&Object.assign(i,{context:r}),i}}export const DEFAULT_TIMEOUTS={registry:1e4,gateway:15e3,transport:3e4,default:3e4};export class TimeoutConfig{registry;gateway;transport;default;constructor(t={}){this.registry=t.registry??DEFAULT_TIMEOUTS.registry,this.gateway=t.gateway??DEFAULT_TIMEOUTS.gateway,this.transport=t.transport??DEFAULT_TIMEOUTS.transport,this.default=t.default??DEFAULT_TIMEOUTS.default,this.validateTimeout("registry",this.registry),this.validateTimeout("gateway",this.gateway),this.validateTimeout("transport",this.transport),this.validateTimeout("default",this.default)}getRegistry(t){return t??this.registry}getGateway(t){return t??this.gateway}getTransport(t){return t??this.transport}getDefault(t){return t??this.default}get(t,e){switch(t){case"registry":return this.getRegistry(e);case"gateway":return this.getGateway(e);case"transport":return this.getTransport(e);case"default":return this.getDefault(e)}}with(t){return new TimeoutConfig({registry:t.registry??this.registry,gateway:t.gateway??this.gateway,transport:t.transport??this.transport,default:t.default??this.default})}validateTimeout(t,e){if(!Number.isFinite(e)||e<=0)throw new Error(`Invalid timeout for '${t}': ${e}. Must be positive finite number.`);e>3e5&&console.warn(`[xbind:timeout] Large timeout for '${t}': ${e}ms. Consider reducing to avoid indefinite hangs.`)}toJSON(){return{registry:this.registry,gateway:this.gateway,transport:this.transport,default:this.default}}}export class OperationTimeoutController{signal;timeoutMs;operation;controller;timer;timedOut=!1;constructor(t,e="operation"){this.controller=new AbortController,this.signal=this.controller.signal,this.timeoutMs=t,this.operation=e,this.timer=setTimeout(()=>{this.timedOut=!0,this.controller.abort()},t)}cancel(){clearTimeout(this.timer),this.controller.signal.aborted||this.controller.abort()}clear(){clearTimeout(this.timer)}didTimeout(){return this.timedOut}getTimeoutError(){return this.timedOut?new TimeoutError(this.operation,this.timeoutMs):null}}export function createTimeoutController(t,e="operation"){return new OperationTimeoutController(t,e)}export async function withTimeout(t,e,r="operation"){const i=createTimeoutController(e,r);try{const o=await Promise.race([t(),new Promise((t,o)=>{i.signal.addEventListener("abort",()=>{o(new TimeoutError(r,e))})})]);return i.clear(),o}catch(t){throw i.clear(),t}}export async function withTimeoutResult(t,e,r="operation"){try{const i=await withTimeout(t,e,r);return ok(i)}catch(t){if(t instanceof TimeoutError)return err("TIMEOUT");throw t}}export function createOperationTimeoutSignal(t,e="operation"){return createTimeoutController(t,e).signal}export function createOperationTimeout(t,e,r,i){return createTimeoutController(t.get(e,i),r)}export function isTimeoutError(t){return t instanceof TimeoutError}export function getTimeoutFromError(t){return isTimeoutError(t)?t.timeoutMs:void 0}export function createTimeoutConfigFromEnv(){const t={},e=process.env.XBIND_TIMEOUT_REGISTRY;if(e){const r=parseInt(e,10);isNaN(r)||(t.registry=r)}const r=process.env.XBIND_TIMEOUT_GATEWAY;if(r){const e=parseInt(r,10);isNaN(e)||(t.gateway=e)}const i=process.env.XBIND_TIMEOUT_TRANSPORT;if(i){const e=parseInt(i,10);isNaN(e)||(t.transport=e)}const o=process.env.XBIND_TIMEOUT_DEFAULT;if(o){const e=parseInt(o,10);isNaN(e)||(t.default=e)}return new TimeoutConfig(t)}export const globalTimeoutConfig=createTimeoutConfigFromEnv();