@ontrails/core 1.0.0-beta.0

package/src/resilience.ts

@@ -0,0 +1,234 @@
+/**
+ * Resilience utilities for @ontrails/core
+ *
+ * Retry with exponential backoff and timeout wrappers,
+ * all returning Result types.
+ */
+
+import { CancelledError, TimeoutError, isRetryable } from './errors.js';
+import { Result } from './result.js';
+
+// ---------------------------------------------------------------------------
+// RetryOptions
+// ---------------------------------------------------------------------------
+
+export interface RetryOptions {
+  /** Maximum number of attempts (default: 3) */
+  readonly maxAttempts?: number | undefined;
+  /** Base delay in ms before first retry (default: 1000) */
+  readonly baseDelay?: number | undefined;
+  /** Maximum delay in ms (default: 30000) */
+  readonly maxDelay?: number | undefined;
+  /** Exponential backoff factor (default: 2) */
+  readonly backoffFactor?: number | undefined;
+  /** Custom predicate — defaults to isRetryable from error taxonomy */
+  readonly shouldRetry?: ((error: Error) => boolean) | undefined;
+  /** AbortSignal for cancellation */
+  readonly signal?: AbortSignal | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers (defined before usage)
+// ---------------------------------------------------------------------------
+
+const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
+  // oxlint-disable-next-line avoid-new -- Promise constructor needed for setTimeout-based sleep
+  new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    let settled = false;
+    const done = () => {
+      if (!settled) {
+        settled = true;
+        resolve();
+      }
+    };
+    const timer = setTimeout(done, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      done();
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+
+// ---------------------------------------------------------------------------
+// shouldRetry (default)
+// ---------------------------------------------------------------------------
+
+/** Default retry predicate using the error taxonomy. */
+export const shouldRetry = (error: Error): boolean => isRetryable(error);
+
+// ---------------------------------------------------------------------------
+// getBackoffDelay
+// ---------------------------------------------------------------------------
+
+/** Compute exponential backoff delay with full jitter. */
+export const getBackoffDelay = (
+  attempt: number,
+  options?: Pick<RetryOptions, 'baseDelay' | 'maxDelay' | 'backoffFactor'>
+): number => {
+  const base = options?.baseDelay ?? 1000;
+  const max = options?.maxDelay ?? 30_000;
+  const factor = options?.backoffFactor ?? 2;
+  const exponential = base * factor ** attempt;
+  const capped = Math.min(exponential, max);
+  // Full jitter: random value in [0, capped]
+  return Math.floor(Math.random() * capped);
+};
+
+// ---------------------------------------------------------------------------
+// retry
+// ---------------------------------------------------------------------------
+
+/**
+ * Retry an async function that returns a Result.
+ *
+ * On each failure, checks whether the error is retryable and whether the
+ * attempt budget remains. Applies exponential backoff with jitter between
+ * retries.
+ */
+/** Attempt a single retry iteration. Returns the result to stop, or undefined to continue. */
+const tryAttempt = async <T>(
+  fn: () => Promise<Result<T, Error>>,
+  attempt: number,
+  maxAttempts: number,
+  retryPredicate: (error: Error) => boolean,
+  options?: RetryOptions
+): Promise<
+  | { done: true; result: Result<T, Error> }
+  | { done: false; result: Result<T, Error> }
+> => {
+  const result = await fn();
+  if (result.isOk()) {
+    return { done: true, result };
+  }
+  const isLast = attempt === maxAttempts - 1;
+  if (isLast || !retryPredicate(result.error)) {
+    return { done: true, result };
+  }
+  const delay = getBackoffDelay(attempt, options);
+  if (delay > 0) {
+    await sleep(delay, options?.signal);
+  }
+  return { done: false, result };
+};
+
+/** Resolve retry options to concrete values. */
+const resolveRetryOptions = (options?: RetryOptions) => ({
+  maxAttempts: options?.maxAttempts ?? 3,
+  retryPredicate: options?.shouldRetry ?? shouldRetry,
+  signal: options?.signal,
+});
+
+export const retry = async <T>(
+  fn: () => Promise<Result<T, Error>>,
+  options?: RetryOptions
+): Promise<Result<T, Error>> => {
+  const { maxAttempts, retryPredicate, signal } = resolveRetryOptions(options);
+  let lastResult: Result<T, Error> | undefined;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    if (signal?.aborted) {
+      return Result.err(new CancelledError('Retry cancelled'));
+    }
+    const outcome = await tryAttempt(
+      fn,
+      attempt,
+      maxAttempts,
+      retryPredicate,
+      options
+    );
+    lastResult = outcome.result;
+    if (outcome.done) {
+      return outcome.result;
+    }
+  }
+
+  return lastResult ?? Result.err(new CancelledError('Retry exhausted'));
+};
+
+// ---------------------------------------------------------------------------
+// withTimeout
+// ---------------------------------------------------------------------------
+
+/**
+ * Run an async Result-returning function with a timeout.
+ *
+ * If the timeout fires first, returns a TimeoutError result.
+ * Also respects an external AbortSignal.
+ */
+export const withTimeout = <T>(
+  fn: () => Promise<Result<T, Error>>,
+  ms: number,
+  signal?: AbortSignal
+): Promise<Result<T, Error>> => {
+  if (signal?.aborted) {
+    return Promise.resolve(Result.err(new CancelledError('Already cancelled')));
+  }
+
+  // oxlint-disable-next-line avoid-new, promise/no-multiple-resolved -- Promise constructor needed for timeout race; settled guard ensures single resolution
+  return new Promise<Result<T, Error>>((resolve) => {
+    let settled = false;
+    // oxlint-disable-next-line prefer-const -- assigned after declaration
+    let timer: ReturnType<typeof setTimeout>;
+
+    const onAbort = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      // oxlint-disable-next-line promise/no-multiple-resolved -- settled guard ensures single resolution
+      resolve(Result.err(new CancelledError('Operation cancelled')));
+    };
+
+    signal?.addEventListener('abort', onAbort, { once: true });
+
+    timer = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      signal?.removeEventListener('abort', onAbort);
+      // oxlint-disable-next-line promise/no-multiple-resolved -- settled guard ensures single resolution
+      resolve(
+        Result.err(
+          new TimeoutError(`Operation timed out after ${ms}ms`, {
+            context: { timeoutMs: ms },
+          })
+        )
+      );
+    }, ms);
+
+    // oxlint-disable-next-line prefer-await-to-then, no-void -- .then() needed inside Promise constructor; void discards unhandled rejection
+    void fn().then(
+      // oxlint-disable-next-line prefer-await-to-callbacks -- callback required inside .then()
+      (result) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        // oxlint-disable-next-line promise/no-multiple-resolved -- settled guard ensures single resolution
+        resolve(result);
+      },
+      // oxlint-disable-next-line prefer-await-to-callbacks -- rejection handler required inside .then()
+      (error: unknown) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        // oxlint-disable-next-line promise/no-multiple-resolved -- settled guard ensures single resolution
+        resolve(
+          Result.err(error instanceof Error ? error : new Error(String(error)))
+        );
+      }
+    );
+  });
+};

package/src/result.ts

@@ -0,0 +1,180 @@
+/**
+ * A type-safe Result monad for representing success/failure without exceptions.
+ */
+
+import { InternalError, ValidationError } from './errors.js';
+
+class Ok<T, E> {
+  readonly value: T;
+
+  constructor(value: T) {
+    this.value = value;
+  }
+
+  // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+  isOk(): this is Ok<T, E> {
+    return true;
+  }
+
+  // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+  isErr(): this is Err<T, E> {
+    return false;
+  }
+
+  map<U>(fn: (value: T) => U): Result<U, E> {
+    return new Ok(fn(this.value));
+  }
+
+  flatMap<U, F = E>(fn: (value: T) => Result<U, F>): Result<U, E | F> {
+    return fn(this.value);
+  }
+
+  mapErr<F>(_fn: (error: E) => F): Result<T, F> {
+    return new Ok(this.value);
+  }
+
+  match<U>(handlers: { ok: (value: T) => U; err: (error: E) => U }): U {
+    return handlers.ok(this.value);
+  }
+
+  unwrap(): T {
+    return this.value;
+  }
+
+  unwrapOr(_fallback: T): T {
+    return this.value;
+  }
+}
+
+// oxlint-disable-next-line max-classes-per-file -- Result monad requires paired Ok/Err classes
+class Err<T, E> {
+  readonly error: E;
+
+  constructor(error: E) {
+    this.error = error;
+  }
+
+  // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+  isOk(): this is Ok<T, E> {
+    return false;
+  }
+
+  // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+  isErr(): this is Err<T, E> {
+    return true;
+  }
+
+  map<U>(_fn: (value: T) => U): Result<U, E> {
+    return new Err(this.error);
+  }
+
+  flatMap<U, F = E>(_fn: (value: T) => Result<U, F>): Result<U, E | F> {
+    return new Err(this.error);
+  }
+
+  mapErr<F>(fn: (error: E) => F): Result<T, F> {
+    return new Err(fn(this.error));
+  }
+
+  match<U>(handlers: { ok: (value: T) => U; err: (error: E) => U }): U {
+    return handlers.err(this.error);
+  }
+
+  unwrap(): never {
+    throw this.error instanceof Error
+      ? this.error
+      : new Error(String(this.error));
+  }
+
+  // oxlint-disable-next-line class-methods-use-this -- symmetric API with Ok.unwrapOr
+  unwrapOr(fallback: T): T {
+    return fallback;
+  }
+}
+
+export type Result<T, E = Error> = Ok<T, E> | Err<T, E>;
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export const Result = {
+  combine<T, E>(results: readonly Result<T, E>[]): Result<T[], E> {
+    const values: T[] = [];
+    for (const result of results) {
+      if (result.isErr()) {
+        return new Err(result.error);
+      }
+      values.push(result.value);
+    }
+    return new Ok(values);
+  },
+
+  err<E>(error: E): Result<never, E> {
+    return new Err(error);
+  },
+
+  /**
+   * Wrap a fetch call in a Result, mapping failures to TrailsError subclasses.
+   *
+   * Network errors become NetworkError. Abort signals become CancelledError.
+   * HTTP error status codes map to the appropriate error category.
+   */
+  async fromFetch(
+    input: string | URL | Request,
+    init?: RequestInit
+  ): Promise<Result<Response, Error>> {
+    // Lazy import avoids a circular dependency (fetch.ts imports Result)
+    const { fromFetch: fetchImpl } = await import('./fetch.js');
+    return fetchImpl(input, init);
+  },
+
+  /**
+   * Parse a JSON string, returning a Result instead of throwing.
+   */
+  fromJson(json: string): Result<unknown, ValidationError> {
+    try {
+      return new Ok(JSON.parse(json) as unknown);
+    } catch (error) {
+      return new Err(
+        new ValidationError('Invalid JSON', {
+          cause: error instanceof Error ? error : new Error(String(error)),
+          context: { input: json.slice(0, 200) },
+        })
+      );
+    }
+  },
+
+  ok<T = void>(value?: T): Result<T, never> {
+    return new Ok(value as T);
+  },
+
+  /**
+   * Stringify a value to JSON, returning a Result. Handles circular references.
+   */
+  toJson(value: unknown): Result<string, InternalError> {
+    try {
+      const seen = new WeakSet();
+      const json = JSON.stringify(value, (_key, val: unknown) => {
+        if (typeof val === 'object' && val !== null) {
+          if (seen.has(val)) {
+            return '[Circular]';
+          }
+          seen.add(val);
+        }
+        return val;
+      });
+      if (json === undefined) {
+        return new Err(
+          new InternalError('Value is not JSON-serializable', {
+            context: { type: typeof value },
+          })
+        );
+      }
+      return new Ok(json);
+    } catch (error) {
+      return new Err(
+        new InternalError('Failed to stringify value', {
+          cause: error instanceof Error ? error : new Error(String(error)),
+        })
+      );
+    }
+  },
+} as const;

package/src/serialization.ts

@@ -0,0 +1,183 @@
+/**
+ * Serialization utilities for @ontrails/core
+ *
+ * Safe JSON parsing/stringifying and error serialization/deserialization
+ * for transport across process boundaries.
+ */
+
+import type { ErrorCategory, TrailsError } from './errors.js';
+import {
+  ValidationError,
+  NotFoundError,
+  ConflictError,
+  PermissionError,
+  TimeoutError,
+  RateLimitError,
+  NetworkError,
+  InternalError,
+  AuthError,
+  CancelledError,
+  isTrailsError,
+} from './errors.js';
+import { Result } from './result.js';
+
+// ---------------------------------------------------------------------------
+// SerializedError interface
+// ---------------------------------------------------------------------------
+
+export interface SerializedError {
+  readonly name: string;
+  readonly message: string;
+  readonly category?: ErrorCategory | undefined;
+  readonly retryable?: boolean | undefined;
+  readonly retryAfter?: number | undefined;
+  readonly context?: Record<string, unknown> | undefined;
+  readonly stack?: string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers (defined before usage)
+// ---------------------------------------------------------------------------
+
+/** Build options object without including undefined context. */
+const buildOpts = (
+  context: Record<string, unknown> | undefined
+): {
+  context?: Record<string, unknown>;
+} => {
+  if (context !== undefined) {
+    return { context };
+  }
+  return {};
+};
+
+type ErrorFactory = (
+  message: string,
+  opts: { context?: Record<string, unknown> },
+  retryAfter: number | undefined
+) => TrailsError;
+
+const errorFactories: Record<ErrorCategory, ErrorFactory> = {
+  auth: (msg, opts) => new AuthError(msg, opts),
+  cancelled: (msg, opts) => new CancelledError(msg, opts),
+  conflict: (msg, opts) => new ConflictError(msg, opts),
+  internal: (msg, opts) => new InternalError(msg, opts),
+  network: (msg, opts) => new NetworkError(msg, opts),
+  not_found: (msg, opts) => new NotFoundError(msg, opts),
+  permission: (msg, opts) => new PermissionError(msg, opts),
+  rate_limit: (msg, opts, retryAfter) => {
+    const rlOpts: { context?: Record<string, unknown>; retryAfter?: number } = {
+      ...opts,
+    };
+    if (retryAfter !== undefined) {
+      rlOpts.retryAfter = retryAfter;
+    }
+    return new RateLimitError(msg, rlOpts);
+  },
+  timeout: (msg, opts) => new TimeoutError(msg, opts),
+  validation: (msg, opts) => new ValidationError(msg, opts),
+};
+
+const createErrorByCategory = (
+  category: ErrorCategory,
+  message: string,
+  context: Record<string, unknown> | undefined,
+  retryAfter: number | undefined
+): TrailsError => {
+  const opts = buildOpts(context);
+  const factory = errorFactories[category] ?? errorFactories.internal;
+  return factory(message, opts, retryAfter);
+};
+
+// ---------------------------------------------------------------------------
+// Error serialization
+// ---------------------------------------------------------------------------
+
+/** Extract structured data from an Error for transport. */
+export const serializeError = (error: Error): SerializedError => {
+  const result: SerializedError = {
+    message: error.message,
+    name: error.name,
+    stack: error.stack,
+  };
+
+  if (isTrailsError(error)) {
+    return {
+      ...result,
+      category: error.category,
+      context: error.context,
+      retryAfter:
+        error instanceof RateLimitError ? error.retryAfter : undefined,
+      retryable: error.retryable,
+    };
+  }
+
+  return result;
+};
+
+/** Reconstruct a TrailsError from serialized data. */
+export const deserializeError = (data: SerializedError): TrailsError => {
+  const category = data.category ?? 'internal';
+  const error = createErrorByCategory(
+    category,
+    data.message,
+    data.context,
+    data.retryAfter
+  );
+
+  if (data.stack) {
+    error.stack = data.stack;
+  }
+
+  return error;
+};
+
+// ---------------------------------------------------------------------------
+// Safe JSON
+// ---------------------------------------------------------------------------
+
+/** Parse a JSON string, returning a Result instead of throwing. */
+export const safeParse = (json: string): Result<unknown, ValidationError> => {
+  try {
+    return Result.ok(JSON.parse(json) as unknown);
+  } catch (error) {
+    return Result.err(
+      new ValidationError('Invalid JSON', {
+        cause: error instanceof Error ? error : new Error(String(error)),
+        context: { input: json.slice(0, 200) },
+      })
+    );
+  }
+};
+
+/** Stringify a value, returning a Result. Handles circular references. */
+export const safeStringify = (
+  value: unknown
+): Result<string, InternalError> => {
+  try {
+    const seen = new WeakSet();
+    const json = JSON.stringify(value, (_key, val: unknown) => {
+      if (typeof val === 'object' && val !== null) {
+        if (seen.has(val)) {
+          return '[Circular]';
+        }
+        seen.add(val);
+      }
+      return val;
+    });
+    if (json === undefined) {
+      return Result.err(
+        new InternalError('Value is not JSON-serializable', {
+          context: { type: typeof value },
+        })
+      );
+    }
+    return Result.ok(json);
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to stringify value', {
+        cause: error instanceof Error ? error : new Error(String(error)),
+      })
+    );
+  }
+};