@ontrails/core 1.0.0-beta.14 → 1.0.0-beta.15

package/src/errors.ts

@@ -10,17 +10,20 @@
 // Category
 // ---------------------------------------------------------------------------
 
-export type ErrorCategory =
-  | 'validation'
-  | 'not_found'
-  | 'conflict'
-  | 'permission'
-  | 'timeout'
-  | 'rate_limit'
-  | 'network'
-  | 'internal'
-  | 'auth'
-  | 'cancelled';
+export const errorCategories = [
+  'validation',
+  'not_found',
+  'conflict',
+  'permission',
+  'timeout',
+  'rate_limit',
+  'network',
+  'internal',
+  'auth',
+  'cancelled',
+] as const;
+
+export type ErrorCategory = (typeof errorCategories)[number];
 
 // ---------------------------------------------------------------------------
 // Base class
@@ -109,6 +112,11 @@ export class NetworkError extends TrailsError {
 }
 
 export class InternalError extends TrailsError {
+  readonly category: ErrorCategory = 'internal';
+  readonly retryable = false as const;
+}
+
+export class DerivationError extends TrailsError {
   readonly category = 'internal' as const;
   readonly retryable = false as const;
 }
@@ -123,11 +131,47 @@ export class CancelledError extends TrailsError {
   readonly retryable = false as const;
 }
 
+/**
+ * Returned when a detour exhausts all recovery attempts.
+ *
+ * Inherits the wrapped error's category for trailhead mapping (e.g. a
+ * `RetryExhaustedError<ConflictError>` maps to HTTP 409), but always
+ * sets `retryable = false` to prevent amplification across `ctx.cross()`
+ * boundaries or stacked layers.
+ */
+export class RetryExhaustedError<
+  TErr extends TrailsError = TrailsError,
+> extends InternalError {
+  readonly category: ErrorCategory;
+  readonly cause: TErr;
+
+  /** Number of recovery attempts made before exhaustion. */
+  readonly attempts: number;
+
+  /** Name of the detour whose recovery was exhausted. */
+  readonly detour: string;
+
+  constructor(
+    wrapped: TErr,
+    metadata: { readonly attempts: number; readonly detour: string }
+  ) {
+    super(
+      `Recovery exhausted after ${metadata.attempts} attempts: ${wrapped.message}`,
+      { cause: wrapped }
+    );
+    this.cause = wrapped;
+    this.attempts = metadata.attempts;
+    this.detour = metadata.detour;
+    // Dynamic — inherited from wrapped error at construction time.
+    this.category = wrapped.category;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Taxonomy maps
 // ---------------------------------------------------------------------------
 
-export const exitCodeMap: Record<ErrorCategory, number> = {
+export const exitCodeMap = {
   auth: 9,
   cancelled: 130,
   conflict: 3,
@@ -138,9 +182,9 @@ export const exitCodeMap: Record<ErrorCategory, number> = {
   rate_limit: 6,
   timeout: 5,
   validation: 1,
-} as const;
+} as const satisfies Record<ErrorCategory, number>;
 
-export const statusCodeMap: Record<ErrorCategory, number> = {
+export const statusCodeMap = {
   auth: 401,
   cancelled: 499,
   conflict: 409,
@@ -151,9 +195,9 @@ export const statusCodeMap: Record<ErrorCategory, number> = {
   rate_limit: 429,
   timeout: 504,
   validation: 400,
-} as const;
+} as const satisfies Record<ErrorCategory, number>;
 
-export const jsonRpcCodeMap: Record<ErrorCategory, number> = {
+export const jsonRpcCodeMap = {
   auth: -32_600,
   cancelled: -32_603,
   conflict: -32_603,
@@ -164,7 +208,7 @@ export const jsonRpcCodeMap: Record<ErrorCategory, number> = {
   rate_limit: -32_603,
   timeout: -32_603,
   validation: -32_602,
-} as const;
+} as const satisfies Record<ErrorCategory, number>;
 
 export const retryableMap: Record<ErrorCategory, boolean> = {
   auth: false,
@@ -190,7 +234,7 @@ export const isTrailsError = (error?: unknown): error is TrailsError =>
 /** Returns true if the error is retryable (TrailsError with retryable category). */
 export const isRetryable = (error: Error): boolean => {
   if (isTrailsError(error)) {
-    return retryableMap[error.category];
+    return error.retryable;
   }
   return false;
 };