@zudojs/errors 0.1.1 → 1.0.0

package/dist/infrastructure/network/httpClientError.types.js

@@ -1,6 +1,7 @@
 /**
  * HTTP client error subclasses.
  */
+import { ErrorCode } from "../../base/types/errorCode.type.js";
 import { HttpClientError, } from "./httpClientError.base.js";
 /**
  * HTTP client timeout error.
@@ -12,72 +13,84 @@ export class HttpClientTimeoutError extends HttpClientError {
     constructor(timeout, options = {}) {
         super(`HTTP request timed out after ${timeout}ms.`, {
             ...options,
-            code: options.code ?? "HTTP_CLIENT_TIMEOUT",
+            code: options.code ?? ErrorCode.HTTP_CLIENT_TIMEOUT,
+            statusCode: options.statusCode ?? 504,
+            metadata: { ...options.metadata, timeout },
         });
-        this.name = "HttpClientTimeoutError";
         this.timeout = timeout;
     }
+    toJSON() {
+        return { ...super.toJSON(), timeout: this.timeout };
+    }
+}
+/** Resolves the `(request?, cause?, options?)` argument form. */
+function resolveClientErrorArguments(request, cause, options) {
+    if (request === undefined) {
+        return { ...options, ...(cause !== undefined ? { cause } : {}) };
+    }
+    if (typeof Request !== "undefined" && request instanceof Request) {
+        return {
+            ...options,
+            request,
+            ...(cause !== undefined ? { cause } : {}),
+        };
+    }
+    // Legacy form: a single options object.
+    return { ...request, ...options };
 }
 /**
  * HTTP client abort error.
  *
  * Thrown when an outbound HTTP request is aborted via AbortSignal.
+ *
+ * Signature: `new HttpClientAbortError(request?, cause?, options?)`. The
+ * second argument is ALWAYS treated as the cause (never as options), so Node
+ * system errors and `DOMException`s that happen to carry a `code` property
+ * are preserved. The legacy single-options form is still accepted.
  */
 export class HttpClientAbortError extends HttpClientError {
-    constructor(requestOrOptions = {}, causeOrOptions) {
-        let opts;
-        if (requestOrOptions instanceof Request) {
-            opts =
-                causeOrOptions !== undefined &&
-                    typeof causeOrOptions === "object" &&
-                    causeOrOptions !== null &&
-                    !Array.isArray(causeOrOptions) &&
-                    "code" in causeOrOptions
-                    ? {
-                        request: requestOrOptions,
-                        ...causeOrOptions,
-                    }
-                    : { request: requestOrOptions, cause: causeOrOptions };
-        }
-        else {
-            opts = requestOrOptions;
-        }
+    constructor(request, cause, options) {
+        const opts = resolveClientErrorArguments(request, cause, options);
         super("HTTP request was aborted.", {
             ...opts,
-            code: opts.code ?? "HTTP_CLIENT_ABORTED",
+            code: opts.code ?? ErrorCode.HTTP_CLIENT_ABORTED,
+            statusCode: opts.statusCode ?? 499,
         });
-        this.name = "HttpClientAbortError";
     }
 }
 /**
  * HTTP client network error.
  *
  * Thrown when an outbound HTTP request fails due to a network issue.
+ *
+ * Signature: `new HttpClientNetworkError(message, request?, cause?, options?)`.
  */
 export class HttpClientNetworkError extends HttpClientError {
-    constructor(message, requestOrOptions = {}, causeOrOptions) {
-        let opts;
-        if (requestOrOptions instanceof Request) {
-            opts =
-                causeOrOptions !== undefined &&
-                    typeof causeOrOptions === "object" &&
-                    causeOrOptions !== null &&
-                    !Array.isArray(causeOrOptions) &&
-                    "code" in causeOrOptions
-                    ? {
-                        request: requestOrOptions,
-                        ...causeOrOptions,
-                    }
-                    : { request: requestOrOptions, cause: causeOrOptions };
-        }
-        else {
-            opts = requestOrOptions;
-        }
+    constructor(message, request, cause, options) {
+        const opts = resolveClientErrorArguments(request, cause, options);
         super(message, {
             ...opts,
-            code: opts.code ?? "HTTP_CLIENT_NETWORK_ERROR",
+            code: opts.code ?? ErrorCode.HTTP_CLIENT_NETWORK,
+            statusCode: opts.statusCode ?? 502,
+            metadata: {
+                ...opts.metadata,
+                ...describeSystemError(opts.cause),
+            },
         });
-        this.name = "HttpClientNetworkError";
     }
 }
+/** Extracts diagnostic fields (errno/syscall/address/port) from a Node system error. */
+function describeSystemError(cause) {
+    if (cause === null || typeof cause !== "object")
+        return {};
+    const record = cause;
+    const result = {};
+    for (const key of ["code", "errno", "syscall", "address", "port"]) {
+        const value = record[key];
+        if (typeof value === "string" || typeof value === "number") {
+            result[key === "code" ? "systemCode" : key] = value;
+        }
+    }
+    return result;
+}
 //# sourceMappingURL=httpClientError.types.js.map

package/dist/infrastructure/network/httpResponse.error.js

@@ -15,7 +15,6 @@ export class HttpResponseWriterError extends BaseError {
             statusCode: options.statusCode ?? 500,
             expose: options.expose ?? false,
         });
-        this.name = "HttpResponseWriterError";
     }
 }
 /**
@@ -26,7 +25,6 @@ export class ResponseAlreadySentError extends HttpResponseWriterError {
         super(message, {
             code: ErrorCode.HTTP_RESPONSE_ALREADY_SENT,
         });
-        this.name = "ResponseAlreadySentError";
     }
 }
 /**
@@ -37,7 +35,6 @@ export class UnsupportedResponseBodyError extends HttpResponseWriterError {
         super(message, {
             code: ErrorCode.HTTP_UNSUPPORTED_RESPONSE_BODY,
         });
-        this.name = "UnsupportedResponseBodyError";
     }
 }
 /**

package/dist/infrastructure/network/httpRouterError.base.js

@@ -15,7 +15,6 @@ export class HttpRouterError extends BaseError {
             statusCode: options.statusCode ?? 500,
             expose: options.expose ?? false,
         });
-        this.name = "HttpRouterError";
     }
 }
 /** Creates an HTTP router error. */

package/dist/infrastructure/network/httpRouterError.types.d.ts

@@ -1,3 +1,4 @@
+import { RoutePatternError } from "./routePattern.error.js";
 import { HttpRouterError } from "./httpRouterError.base.js";
 /**
  * Error thrown when a route conflicts with an existing route.
@@ -11,10 +12,11 @@ export declare class RouteConflictError extends HttpRouterError {
 }
 /**
  * Error thrown when a route pattern is invalid.
+ *
+ * Specialisation of `RoutePatternError` (same hierarchy, code
+ * `ERR_HTTP_INVALID_ROUTE_PATTERN`).
  */
-export declare class InvalidRoutePatternError extends HttpRouterError {
-    /** The invalid route pattern. */
-    readonly pattern: string;
+export declare class InvalidRoutePatternError extends RoutePatternError {
     constructor(pattern: string, message: string);
 }
 //# sourceMappingURL=httpRouterError.types.d.ts.map

package/dist/infrastructure/network/httpRouterError.types.js

@@ -1,4 +1,5 @@
 import { ErrorCode } from "../../base/types/errorCode.type.js";
+import { RoutePatternError } from "./routePattern.error.js";
 import { HttpRouterError } from "./httpRouterError.base.js";
 /**
  * Error thrown when a route conflicts with an existing route.
@@ -13,24 +14,22 @@ export class RouteConflictError extends HttpRouterError {
             code: ErrorCode.HTTP_ROUTE_CONFLICT,
             metadata: { path, method },
         });
-        this.name = "RouteConflictError";
         this.path = path;
         this.method = method;
     }
 }
 /**
  * Error thrown when a route pattern is invalid.
+ *
+ * Specialisation of `RoutePatternError` (same hierarchy, code
+ * `ERR_HTTP_INVALID_ROUTE_PATTERN`).
  */
-export class InvalidRoutePatternError extends HttpRouterError {
-    /** The invalid route pattern. */
-    pattern;
+export class InvalidRoutePatternError extends RoutePatternError {
     constructor(pattern, message) {
         super(`Invalid route pattern "${pattern}": ${message}`, {
             code: ErrorCode.HTTP_INVALID_ROUTE_PATTERN,
-            metadata: { pattern },
+            pattern,
         });
-        this.name = "InvalidRoutePatternError";
-        this.pattern = pattern;
     }
 }
 //# sourceMappingURL=httpRouterError.types.js.map

package/dist/infrastructure/network/httpServerError.error.js

@@ -5,6 +5,7 @@
  * failures into consistent responses without coupling the errors to a
  * particular server adapter.
  */
+import { ErrorCode } from "../../base/types/errorCode.type.js";
 import { HttpError } from "./http.error.js";
 /**
  * 500 Internal Server Error
@@ -14,10 +15,9 @@ export class InternalServerError extends HttpError {
         super(message, {
             ...options,
             statusCode: 500,
-            code: options.code ?? "INTERNAL_SERVER_ERROR",
+            code: options.code ?? ErrorCode.HTTP_INTERNAL_SERVER_ERROR,
             expose: options.expose ?? false,
         });
-        this.name = "InternalServerError";
     }
 }
 /**
@@ -28,10 +28,9 @@ export class NotImplementedError extends HttpError {
         super(message, {
             ...options,
             statusCode: 501,
-            code: options.code ?? "NOT_IMPLEMENTED",
+            code: options.code ?? ErrorCode.HTTP_NOT_IMPLEMENTED,
             expose: options.expose ?? false,
         });
-        this.name = "NotImplementedError";
     }
 }
 /**
@@ -42,10 +41,9 @@ export class BadGatewayError extends HttpError {
         super(message, {
             ...options,
             statusCode: 502,
-            code: options.code ?? "BAD_GATEWAY",
+            code: options.code ?? ErrorCode.HTTP_BAD_GATEWAY,
             expose: options.expose ?? false,
         });
-        this.name = "BadGatewayError";
     }
 }
 /**
@@ -56,10 +54,9 @@ export class ServiceUnavailableError extends HttpError {
         super(message, {
             ...options,
             statusCode: 503,
-            code: options.code ?? "SERVICE_UNAVAILABLE",
+            code: options.code ?? ErrorCode.HTTP_SERVICE_UNAVAILABLE,
             expose: options.expose ?? false,
         });
-        this.name = "ServiceUnavailableError";
     }
 }
 /**
@@ -70,10 +67,9 @@ export class GatewayTimeoutError extends HttpError {
         super(message, {
             ...options,
             statusCode: 504,
-            code: options.code ?? "GATEWAY_TIMEOUT",
+            code: options.code ?? ErrorCode.HTTP_GATEWAY_TIMEOUT,
             expose: options.expose ?? false,
         });
-        this.name = "GatewayTimeoutError";
     }
 }
 //# sourceMappingURL=httpServerError.error.js.map

package/dist/infrastructure/network/httpServerLifecycleError.base.js

@@ -15,7 +15,6 @@ export class HttpServerLifecycleError extends BaseError {
             statusCode: options.statusCode ?? 500,
             expose: options.expose ?? false,
         });
-        this.name = "HttpServerLifecycleError";
     }
 }
 /** Creates an HTTP server lifecycle error. */

package/dist/infrastructure/network/httpServerLifecycleError.types.js

@@ -11,7 +11,6 @@ export class InvalidHttpServerStateError extends HttpServerLifecycleError {
             code: ErrorCode.HTTP_SERVER_INVALID_STATE,
             metadata: { state, operation },
         });
-        this.name = "InvalidHttpServerStateError";
         this.state = state;
     }
 }
@@ -24,7 +23,6 @@ export class HttpServerStartError extends HttpServerLifecycleError {
             code: ErrorCode.HTTP_SERVER_START,
             cause,
         });
-        this.name = "HttpServerStartError";
     }
 }
 /**
@@ -36,7 +34,6 @@ export class HttpServerStopError extends HttpServerLifecycleError {
             code: ErrorCode.HTTP_SERVER_STOP,
             cause,
         });
-        this.name = "HttpServerStopError";
     }
 }
 //# sourceMappingURL=httpServerLifecycleError.types.js.map

package/dist/infrastructure/network/httpStream.error.js

@@ -15,7 +15,6 @@ export class HttpStreamError extends BaseError {
             statusCode: options.statusCode ?? 500,
             expose: options.expose ?? false,
         });
-        this.name = "HttpStreamError";
     }
 }
 /**

package/dist/infrastructure/network/network.error.d.ts

@@ -3,5 +3,5 @@
  */
 export { NetworkError, createNetworkError, isNetworkError, } from "./networkError.base.js";
 export type { NetworkErrorOptions } from "./networkError.base.js";
-export { connectionFailedError, networkTimeoutError, externalServiceUnavailableError, } from "./networkError.factory.js";
+export { connectionFailedError, networkTimeoutError, networkServiceUnavailableError, } from "./networkError.factory.js";
 //# sourceMappingURL=network.error.d.ts.map

package/dist/infrastructure/network/network.error.js

@@ -2,5 +2,5 @@
  * Network error classes — re-exports from focused files.
  */
 export { NetworkError, createNetworkError, isNetworkError, } from "./networkError.base.js";
-export { connectionFailedError, networkTimeoutError, externalServiceUnavailableError, } from "./networkError.factory.js";
+export { connectionFailedError, networkTimeoutError, networkServiceUnavailableError, } from "./networkError.factory.js";
 //# sourceMappingURL=network.error.js.map

package/dist/infrastructure/network/networkError.factory.d.ts

@@ -6,6 +6,13 @@ import { NetworkError, type NetworkErrorOptions } from "./networkError.base.js";
 export declare function connectionFailedError(service?: string, options?: Omit<NetworkErrorOptions, "service">): NetworkError;
 /** Creates a network timeout error. */
 export declare function networkTimeoutError(service?: string, options?: Omit<NetworkErrorOptions, "service">): NetworkError;
-/** Creates an error for an unavailable remote service. */
-export declare function externalServiceUnavailableError(service?: string, options?: Omit<NetworkErrorOptions, "service">): NetworkError;
+/**
+ * Creates an error for an unavailable remote service.
+ *
+ * @deprecated Use `externalServiceUnavailableError` from the service module
+ * (creates an `ExternalServiceError`, so `isExternalServiceError` matches).
+ * This variant creates a `NetworkError` and is kept for compatibility under
+ * the name `networkServiceUnavailableError`.
+ */
+export declare function networkServiceUnavailableError(service?: string, options?: Omit<NetworkErrorOptions, "service">): NetworkError;
 //# sourceMappingURL=networkError.factory.d.ts.map

package/dist/infrastructure/network/networkError.factory.js

@@ -22,8 +22,15 @@ export function networkTimeoutError(service, options = {}) {
         service,
     });
 }
-/** Creates an error for an unavailable remote service. */
-export function externalServiceUnavailableError(service, options = {}) {
+/**
+ * Creates an error for an unavailable remote service.
+ *
+ * @deprecated Use `externalServiceUnavailableError` from the service module
+ * (creates an `ExternalServiceError`, so `isExternalServiceError` matches).
+ * This variant creates a `NetworkError` and is kept for compatibility under
+ * the name `networkServiceUnavailableError`.
+ */
+export function networkServiceUnavailableError(service, options = {}) {
     return new NetworkError(service
         ? `${service} is currently unavailable.`
         : "The external service is currently unavailable.", {

package/dist/infrastructure/network/routePattern.error.d.ts

@@ -1,18 +1,19 @@
-import { BaseError } from "../../base/core/baseError.core.js";
-import type { BaseErrorOptions } from "../../base/types/baseError.type.js";
-import { ErrorCategory } from "../../base/types/errorCategory.type.js";
+import { HttpRouterError, type HttpRouterErrorOptions } from "./httpRouterError.base.js";
 /**
  * Options for creating a route pattern error.
  */
-export interface RoutePatternErrorOptions extends Omit<BaseErrorOptions, "category"> {
-    readonly category?: ErrorCategory;
+export interface RoutePatternErrorOptions extends HttpRouterErrorOptions {
     readonly pattern?: string;
     readonly position?: number;
 }
 /**
  * Error thrown when a route pattern is invalid.
+ *
+ * Route patterns are authored by developers, not clients, so this is a
+ * server-side configuration error: 500, not exposed, non-operational.
+ * `InvalidRoutePatternError` (in `httpRouterError.types`) extends this class.
  */
-export declare class RoutePatternError extends BaseError {
+export declare class RoutePatternError extends HttpRouterError {
     /**
      * The route pattern that caused the error.
      */

package/dist/infrastructure/network/routePattern.error.js

@@ -1,11 +1,14 @@
-import { BaseError } from "../../base/core/baseError.core.js";
 import { ErrorCode } from "../../base/types/errorCode.type.js";
-import { ErrorCategory } from "../../base/types/errorCategory.type.js";
 import { ErrorSeverity } from "../../base/types/errorSeverity.type.js";
+import { HttpRouterError, } from "./httpRouterError.base.js";
 /**
  * Error thrown when a route pattern is invalid.
+ *
+ * Route patterns are authored by developers, not clients, so this is a
+ * server-side configuration error: 500, not exposed, non-operational.
+ * `InvalidRoutePatternError` (in `httpRouterError.types`) extends this class.
  */
-export class RoutePatternError extends BaseError {
+export class RoutePatternError extends HttpRouterError {
     /**
      * The route pattern that caused the error.
      */
@@ -18,12 +21,18 @@ export class RoutePatternError extends BaseError {
         super(message, {
             ...options,
             code: options.code ?? ErrorCode.HTTP_ROUTE_PATTERN,
-            category: options.category ?? ErrorCategory.VALIDATION,
             severity: options.severity ?? ErrorSeverity.ERROR,
-            statusCode: options.statusCode ?? 400,
-            expose: options.expose ?? true,
+            statusCode: options.statusCode ?? 500,
+            expose: options.expose ?? false,
+            isOperational: options.isOperational ?? false,
+            metadata: {
+                ...options.metadata,
+                ...(options.pattern !== undefined ? { pattern: options.pattern } : {}),
+                ...(options.position !== undefined
+                    ? { position: options.position }
+                    : {}),
+            },
         });
-        this.name = "RoutePatternError";
         this.pattern = options.pattern ?? "";
         this.position = options.position;
     }
@@ -44,7 +53,6 @@ export class DuplicateRouteParameterError extends RoutePatternError {
                 paramName,
             },
         });
-        this.name = "DuplicateRouteParameterError";
         this.paramName = paramName;
     }
 }

package/dist/infrastructure/network/timeoutError.base.d.ts

@@ -51,4 +51,11 @@ export declare class TimeoutError extends BaseError {
 export declare function createTimeoutError(message?: string, options?: TimeoutErrorOptions): TimeoutError;
 /** Determines whether an unknown value is a TimeoutError. */
 export declare function isTimeoutError(value: unknown): value is TimeoutError;
+/**
+ * Returns whether a timeout operation may expose its message (and target) to
+ * clients. Only request-level timeouts are public by default; database,
+ * cache, queue, lock, network and external-service timeouts describe internal
+ * resources and stay internal.
+ */
+export declare function isPublicTimeoutOperation(operation: TimeoutOperation | undefined): boolean;
 //# sourceMappingURL=timeoutError.base.d.ts.map

package/dist/infrastructure/network/timeoutError.base.js

@@ -31,7 +31,7 @@ export class TimeoutError extends BaseError {
             category: options.category ?? ErrorCategory.TIMEOUT,
             severity: options.severity ?? ErrorSeverity.WARNING,
             statusCode: options.statusCode ?? 504,
-            expose: options.expose ?? true,
+            expose: options.expose ?? isPublicTimeoutOperation(options.operation),
             isOperational: options.isOperational ?? true,
             metadata: {
                 ...options.metadata,
@@ -65,6 +65,17 @@ export function createTimeoutError(message = "The operation timed out.", options
 export function isTimeoutError(value) {
     return value instanceof TimeoutError;
 }
+/**
+ * Returns whether a timeout operation may expose its message (and target) to
+ * clients. Only request-level timeouts are public by default; database,
+ * cache, queue, lock, network and external-service timeouts describe internal
+ * resources and stay internal.
+ */
+export function isPublicTimeoutOperation(operation) {
+    return (operation === undefined ||
+        operation === TimeoutOperation.UNKNOWN ||
+        operation === TimeoutOperation.REQUEST);
+}
 /** Validates a timeout duration. */
 function validateTimeout(timeoutMs) {
     if (timeoutMs === undefined) {

package/dist/infrastructure/network/timeoutError.factory.d.ts

@@ -1,13 +1,27 @@
 /**
  * Timeout error factory functions for specific operations.
+ *
+ * Every factory accepts either an options object `{ timeoutMs, target }` or
+ * the legacy positional arguments. The positional order differs between the
+ * request/database factories (`timeoutMs, target`) and the service/lock
+ * factories (`target, timeoutMs`); the object form is recommended.
  */
 import { TimeoutError } from "./timeoutError.base.js";
+/** Arguments shared by the timeout factories. */
+export interface TimeoutFactoryOptions {
+    readonly timeoutMs?: number;
+    readonly target?: string;
+}
 /** Creates a request timeout error. */
+export declare function requestTimeoutError(options?: TimeoutFactoryOptions): TimeoutError;
 export declare function requestTimeoutError(timeoutMs?: number, target?: string): TimeoutError;
 /** Creates a database timeout error. */
+export declare function databaseTimeoutError(options?: TimeoutFactoryOptions): TimeoutError;
 export declare function databaseTimeoutError(timeoutMs?: number, target?: string): TimeoutError;
 /** Creates an external-service timeout error. */
+export declare function serviceTimeoutError(options?: TimeoutFactoryOptions): TimeoutError;
 export declare function serviceTimeoutError(target?: string, timeoutMs?: number): TimeoutError;
 /** Creates a lock acquisition timeout error. */
+export declare function lockTimeoutError(options?: TimeoutFactoryOptions): TimeoutError;
 export declare function lockTimeoutError(target?: string, timeoutMs?: number): TimeoutError;
 //# sourceMappingURL=timeoutError.factory.d.ts.map

package/dist/infrastructure/network/timeoutError.factory.js

@@ -1,11 +1,25 @@
 /**
  * Timeout error factory functions for specific operations.
+ *
+ * Every factory accepts either an options object `{ timeoutMs, target }` or
+ * the legacy positional arguments. The positional order differs between the
+ * request/database factories (`timeoutMs, target`) and the service/lock
+ * factories (`target, timeoutMs`); the object form is recommended.
  */
 import { ErrorCategory } from "../../base/types/errorCategory.type.js";
 import { ErrorCode } from "../../base/types/errorCode.type.js";
 import { TimeoutError, TimeoutOperation } from "./timeoutError.base.js";
-/** Creates a request timeout error. */
-export function requestTimeoutError(timeoutMs, target) {
+function resolveTimeoutArgs(first, second, order) {
+    if (first !== undefined && typeof first === "object")
+        return first;
+    const [timeoutMs, target] = order === "timeoutFirst" ? [first, second] : [second, first];
+    return {
+        ...(typeof timeoutMs === "number" ? { timeoutMs } : {}),
+        ...(typeof target === "string" ? { target } : {}),
+    };
+}
+export function requestTimeoutError(first, second) {
+    const { timeoutMs, target } = resolveTimeoutArgs(first, second, "timeoutFirst");
     return new TimeoutError(target ? `The request to ${target} timed out.` : "The request timed out.", {
         code: ErrorCode.TIMEOUT,
         operation: TimeoutOperation.REQUEST,
@@ -13,11 +27,9 @@ export function requestTimeoutError(timeoutMs, target) {
         target,
     });
 }
-/** Creates a database timeout error. */
-export function databaseTimeoutError(timeoutMs, target) {
-    return new TimeoutError(target
-        ? `The database operation on ${target} timed out.`
-        : "The database operation timed out.", {
+export function databaseTimeoutError(first, second) {
+    const { timeoutMs, target } = resolveTimeoutArgs(first, second, "timeoutFirst");
+    return new TimeoutError("The database operation timed out.", {
         code: ErrorCode.DATABASE_TIMEOUT,
         category: ErrorCategory.DATABASE,
         operation: TimeoutOperation.DATABASE,
@@ -25,11 +37,9 @@ export function databaseTimeoutError(timeoutMs, target) {
         target,
     });
 }
-/** Creates an external-service timeout error. */
-export function serviceTimeoutError(target, timeoutMs) {
-    return new TimeoutError(target
-        ? `The request to ${target} timed out.`
-        : "The external service request timed out.", {
+export function serviceTimeoutError(first, second) {
+    const { timeoutMs, target } = resolveTimeoutArgs(first, second, "targetFirst");
+    return new TimeoutError("The external service request timed out.", {
         code: ErrorCode.EXTERNAL_SERVICE_TIMEOUT,
         category: ErrorCategory.EXTERNAL_SERVICE,
         operation: TimeoutOperation.EXTERNAL_SERVICE,
@@ -37,11 +47,9 @@ export function serviceTimeoutError(target, timeoutMs) {
         target,
     });
 }
-/** Creates a lock acquisition timeout error. */
-export function lockTimeoutError(target, timeoutMs) {
-    return new TimeoutError(target
-        ? `Timed out while waiting for lock "${target}".`
-        : "Timed out while waiting for a lock.", {
+export function lockTimeoutError(first, second) {
+    const { timeoutMs, target } = resolveTimeoutArgs(first, second, "targetFirst");
+    return new TimeoutError("Timed out while waiting for a lock.", {
         code: ErrorCode.LOCK_TIMEOUT,
         category: ErrorCategory.CONFLICT,
         operation: TimeoutOperation.LOCK,

package/dist/infrastructure/service/externalService.error.d.ts

@@ -3,5 +3,5 @@
  */
 export { ExternalServiceError, createExternalServiceError, isExternalServiceError, } from "./externalServiceError.base.js";
 export type { ExternalServiceErrorOptions } from "./externalServiceError.base.js";
-export { externalServiceTimeoutError, externalServiceUnavailable, } from "./externalServiceError.factory.js";
+export { externalServiceTimeoutError, externalServiceUnavailable, externalServiceUnavailableError, } from "./externalServiceError.factory.js";
 //# sourceMappingURL=externalService.error.d.ts.map

package/dist/infrastructure/service/externalService.error.js

@@ -2,5 +2,5 @@
  * External service error classes — re-exports from focused files.
  */
 export { ExternalServiceError, createExternalServiceError, isExternalServiceError, } from "./externalServiceError.base.js";
-export { externalServiceTimeoutError, externalServiceUnavailable, } from "./externalServiceError.factory.js";
+export { externalServiceTimeoutError, externalServiceUnavailable, externalServiceUnavailableError, } from "./externalServiceError.factory.js";
 //# sourceMappingURL=externalService.error.js.map

package/dist/infrastructure/service/externalServiceError.base.d.ts

@@ -42,4 +42,12 @@ export declare class ExternalServiceError extends BaseError {
 export declare function createExternalServiceError(service: string, message?: string, options?: Omit<ExternalServiceErrorOptions, "service">): ExternalServiceError;
 /** Determines whether an unknown value is an ExternalServiceError. */
 export declare function isExternalServiceError(value: unknown): value is ExternalServiceError;
+/**
+ * Maps a remote response status into an appropriate local HTTP status.
+ *
+ * An upstream failure is our problem, not our caller's: every upstream status
+ * maps to 502 Bad Gateway except 429, which is passed through so that callers
+ * can back off. Pass an explicit `statusCode` option to override.
+ */
+export declare function mapResponseStatus(responseStatus: number | undefined): number;
 //# sourceMappingURL=externalServiceError.base.d.ts.map