@outfitter/contracts 0.1.0-rc.1

package/dist/resilience.d.ts

@@ -0,0 +1,299 @@
+import { TaggedErrorClass } from "better-result";
+declare const ValidationErrorBase: TaggedErrorClass<"ValidationError", {
+	message: string;
+	field?: string;
+}>;
+declare const AssertionErrorBase: TaggedErrorClass<"AssertionError", {
+	message: string;
+}>;
+declare const NotFoundErrorBase: TaggedErrorClass<"NotFoundError", {
+	message: string;
+	resourceType: string;
+	resourceId: string;
+}>;
+declare const ConflictErrorBase: TaggedErrorClass<"ConflictError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const PermissionErrorBase: TaggedErrorClass<"PermissionError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const TimeoutErrorBase: TaggedErrorClass<"TimeoutError", {
+	message: string;
+	operation: string;
+	timeoutMs: number;
+}>;
+declare const RateLimitErrorBase: TaggedErrorClass<"RateLimitError", {
+	message: string;
+	retryAfterSeconds?: number;
+}>;
+declare const NetworkErrorBase: TaggedErrorClass<"NetworkError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const InternalErrorBase: TaggedErrorClass<"InternalError", {
+	message: string;
+	context?: Record<string, unknown>;
+}>;
+declare const AuthErrorBase: TaggedErrorClass<"AuthError", {
+	message: string;
+	reason?: "missing" | "invalid" | "expired";
+}>;
+declare const CancelledErrorBase: TaggedErrorClass<"CancelledError", {
+	message: string;
+}>;
+/**
+* Input validation failed.
+*
+* @example
+* ```typescript
+* new ValidationError({ message: "Email format invalid", field: "email" });
+* ```
+*/
+declare class ValidationError extends ValidationErrorBase {
+	readonly category: "validation";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Assertion failed (invariant violation).
+*
+* Used by assertion utilities that return Result types instead of throwing.
+* AssertionError indicates a programming bug — an invariant that should
+* never be violated was broken. These are internal errors, not user input
+* validation failures.
+*
+* **Category rationale**: Uses `internal` (not `validation`) because:
+* - Assertions check **invariants** (programmer assumptions), not user input
+* - A failed assertion means "this should be impossible if the code is correct"
+* - User-facing validation uses {@link ValidationError} with helpful field info
+* - HTTP 500 is correct: this is a server bug, not a client mistake
+*
+* @example
+* ```typescript
+* // In domain logic after validation has passed
+* const result = assertDefined(cachedValue, "Cache should always have value after init");
+* if (result.isErr()) {
+*   return result; // Propagate as internal error
+* }
+* ```
+*
+* @see ValidationError - For user input validation failures (HTTP 400)
+*/
+declare class AssertionError extends AssertionErrorBase {
+	readonly category: "internal";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Requested resource not found.
+*
+* @example
+* ```typescript
+* new NotFoundError({ message: "note not found: abc123", resourceType: "note", resourceId: "abc123" });
+* ```
+*/
+declare class NotFoundError extends NotFoundErrorBase {
+	readonly category: "not_found";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* State conflict (optimistic locking, concurrent modification).
+*
+* @example
+* ```typescript
+* new ConflictError({ message: "Resource was modified by another process" });
+* ```
+*/
+declare class ConflictError extends ConflictErrorBase {
+	readonly category: "conflict";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Authorization denied.
+*
+* @example
+* ```typescript
+* new PermissionError({ message: "Cannot delete read-only resource" });
+* ```
+*/
+declare class PermissionError extends PermissionErrorBase {
+	readonly category: "permission";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Operation timed out.
+*
+* @example
+* ```typescript
+* new TimeoutError({ message: "Database query timed out after 5000ms", operation: "Database query", timeoutMs: 5000 });
+* ```
+*/
+declare class TimeoutError extends TimeoutErrorBase {
+	readonly category: "timeout";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Rate limit exceeded.
+*
+* @example
+* ```typescript
+* new RateLimitError({ message: "Rate limit exceeded, retry after 60s", retryAfterSeconds: 60 });
+* ```
+*/
+declare class RateLimitError extends RateLimitErrorBase {
+	readonly category: "rate_limit";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Network/transport failure.
+*
+* @example
+* ```typescript
+* new NetworkError({ message: "Connection refused to api.example.com" });
+* ```
+*/
+declare class NetworkError extends NetworkErrorBase {
+	readonly category: "network";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Unexpected internal error.
+*
+* @example
+* ```typescript
+* new InternalError({ message: "Unexpected state in processor" });
+* ```
+*/
+declare class InternalError extends InternalErrorBase {
+	readonly category: "internal";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Authentication failed (missing or invalid credentials).
+*
+* @example
+* ```typescript
+* new AuthError({ message: "Invalid API key", reason: "invalid" });
+* ```
+*/
+declare class AuthError extends AuthErrorBase {
+	readonly category: "auth";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Operation cancelled by user or signal.
+*
+* @example
+* ```typescript
+* new CancelledError({ message: "Operation cancelled by user" });
+* ```
+*/
+declare class CancelledError extends CancelledErrorBase {
+	readonly category: "cancelled";
+	exitCode(): number;
+	statusCode(): number;
+}
+/**
+* Union type of all concrete error class instances.
+*/
+type AnyKitError = InstanceType<typeof ValidationError> | InstanceType<typeof AssertionError> | InstanceType<typeof NotFoundError> | InstanceType<typeof ConflictError> | InstanceType<typeof PermissionError> | InstanceType<typeof TimeoutError> | InstanceType<typeof RateLimitError> | InstanceType<typeof NetworkError> | InstanceType<typeof InternalError> | InstanceType<typeof AuthError> | InstanceType<typeof CancelledError>;
+/**
+* Type alias for backwards compatibility with handler signatures.
+* Use AnyKitError for the union type.
+*/
+type OutfitterError = AnyKitError;
+import { Result } from "better-result";
+/**
+* Options for retry behavior.
+*/
+interface RetryOptions {
+	/** Maximum number of retry attempts (default: 3) */
+	maxAttempts?: number;
+	/** Initial delay in milliseconds (default: 1000) */
+	initialDelayMs?: number;
+	/** Maximum delay in milliseconds (default: 30000) */
+	maxDelayMs?: number;
+	/** Exponential backoff multiplier (default: 2) */
+	backoffMultiplier?: number;
+	/** Whether to add jitter to delays (default: true) */
+	jitter?: boolean;
+	/** Predicate to determine if error is retryable */
+	isRetryable?: (error: OutfitterError) => boolean;
+	/** Abort signal for cancellation */
+	signal?: AbortSignal;
+	/** Callback invoked before each retry */
+	onRetry?: (attempt: number, error: OutfitterError, delayMs: number) => void;
+}
+/**
+* Options for timeout behavior.
+*/
+interface TimeoutOptions {
+	/** Timeout duration in milliseconds */
+	timeoutMs: number;
+	/** Operation name for error context */
+	operation?: string;
+}
+/**
+* Retry an async operation with exponential backoff.
+*
+* Automatically retries transient errors (network, timeout, rate_limit)
+* unless overridden with `isRetryable`.
+*
+* @typeParam T - Success type
+* @param fn - Async function returning Result
+* @param options - Retry configuration
+* @returns Result from final attempt
+*
+* @example
+* ```typescript
+* const result = await retry(
+*   () => fetchData(url),
+*   {
+*     maxAttempts: 5,
+*     initialDelayMs: 500,
+*     onRetry: (attempt, error) => {
+*       logger.warn(`Retry ${attempt}`, { error: error._tag });
+*     },
+*   }
+* );
+* ```
+*/
+declare function retry<T>(fn: () => Promise<Result<T, OutfitterError>>, options?: RetryOptions): Promise<Result<T, OutfitterError>>;
+/**
+* Wrap an async operation with a timeout.
+*
+* Returns TimeoutError if operation doesn't complete within the specified duration.
+*
+* @typeParam T - Success type
+* @typeParam E - Error type
+* @param fn - Async function returning Result
+* @param options - Timeout configuration
+* @returns Result from operation or TimeoutError
+*
+* @example
+* ```typescript
+* const result = await withTimeout(
+*   () => slowOperation(),
+*   { timeoutMs: 5000, operation: "database query" }
+* );
+*
+* if (result.isErr() && result.error._tag === "TimeoutError") {
+*   // Handle timeout
+* }
+* ```
+*/
+declare function withTimeout<
+	T,
+	E extends OutfitterError
+>(fn: () => Promise<Result<T, E>>, options: TimeoutOptions): Promise<Result<T, E | TimeoutError>>;
+export { withTimeout, retry, TimeoutOptions, RetryOptions };

package/dist/resilience.js

@@ -0,0 +1,82 @@
+// @bun
+import {
+  TimeoutError
+} from "./errors.js";
+
+// packages/contracts/src/resilience.ts
+import { Result } from "better-result";
+function defaultIsRetryable(error) {
+  return error.category === "network" || error.category === "timeout" || error.category === "rate_limit";
+}
+function calculateDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier, jitter) {
+  const baseDelay = initialDelayMs * backoffMultiplier ** (attempt - 1);
+  const cappedDelay = Math.min(baseDelay, maxDelayMs);
+  if (jitter) {
+    const jitterFactor = 0.5 + Math.random();
+    return Math.floor(cappedDelay * jitterFactor);
+  }
+  return cappedDelay;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function retry(fn, options) {
+  const maxAttempts = options?.maxAttempts ?? 3;
+  const initialDelayMs = options?.initialDelayMs ?? 1000;
+  const maxDelayMs = options?.maxDelayMs ?? 30000;
+  const backoffMultiplier = options?.backoffMultiplier ?? 2;
+  const jitter = options?.jitter ?? true;
+  const isRetryable = options?.isRetryable ?? defaultIsRetryable;
+  const onRetry = options?.onRetry;
+  const signal = options?.signal;
+  let lastError;
+  let attempt = 0;
+  while (attempt < maxAttempts) {
+    attempt++;
+    if (signal?.aborted) {
+      return Result.err(lastError ?? new TimeoutError({
+        message: "Operation cancelled",
+        operation: "retry",
+        timeoutMs: 0
+      }));
+    }
+    const result = await fn();
+    if (result.isOk()) {
+      return result;
+    }
+    lastError = result.error;
+    if (attempt >= maxAttempts || !isRetryable(lastError)) {
+      return result;
+    }
+    const delayMs = calculateDelay(attempt, initialDelayMs, maxDelayMs, backoffMultiplier, jitter);
+    if (onRetry) {
+      onRetry(attempt, lastError, delayMs);
+    }
+    await sleep(delayMs);
+  }
+  throw new Error("Unexpected: retry loop completed without returning a result");
+}
+async function withTimeout(fn, options) {
+  const { timeoutMs, operation = "operation" } = options;
+  let timeoutId;
+  const timeoutPromise = new Promise((resolve) => {
+    timeoutId = setTimeout(() => {
+      resolve(Result.err(new TimeoutError({
+        message: `${operation} timed out after ${timeoutMs}ms`,
+        operation,
+        timeoutMs
+      })));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([fn(), timeoutPromise]);
+  } finally {
+    if (timeoutId !== undefined) {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+export {
+  withTimeout,
+  retry
+};

package/dist/result/index.d.ts

@@ -0,0 +1,103 @@
+import { Result } from "better-result";
+/**
+* Extract value from Ok, or compute default from error.
+*
+* Unlike `unwrapOr`, the default is computed lazily only on Err.
+* This is useful when the default value is expensive to compute
+* and should only be evaluated when needed.
+*
+* @param result - The Result to unwrap
+* @param defaultFn - Function to compute default value from error
+* @returns The success value or computed default
+*
+* @example
+* ```typescript
+* const result = Result.err("not found");
+* const value = unwrapOrElse(result, (error) => {
+*   console.log("Computing expensive default due to:", error);
+*   return expensiveComputation();
+* });
+* ```
+*/
+declare const unwrapOrElse: <
+	T,
+	E
+>(result: Result<T, E>, defaultFn: (error: E) => T) => T;
+/**
+* Return first Ok, or fallback if first is Err.
+*
+* Useful for trying alternative operations - if the first fails,
+* fall back to an alternative Result.
+*
+* @param result - The primary Result to try
+* @param fallback - The fallback Result if primary is Err
+* @returns First Ok result, or fallback
+*
+* @example
+* ```typescript
+* const primary = parseFromCache(key);
+* const fallback = parseFromNetwork(key);
+* const result = orElse(primary, fallback);
+* ```
+*/
+declare const orElse: <
+	T,
+	E,
+	F
+>(result: Result<T, E>, fallback: Result<T, F>) => Result<T, F>;
+/**
+* Combine two Results into a tuple Result.
+*
+* Returns first error if either fails, evaluated left-to-right.
+* Useful for combining independent operations that must all succeed.
+*
+* @param r1 - First Result
+* @param r2 - Second Result
+* @returns Result containing tuple of both values, or first error
+*
+* @example
+* ```typescript
+* const user = fetchUser(id);
+* const settings = fetchSettings(id);
+* const combined = combine2(user, settings);
+*
+* if (combined.isOk()) {
+*   const [userData, userSettings] = combined.value;
+* }
+* ```
+*/
+declare const combine2: <
+	T1,
+	T2,
+	E
+>(r1: Result<T1, E>, r2: Result<T2, E>) => Result<[T1, T2], E>;
+/**
+* Combine three Results into a tuple Result.
+*
+* Returns first error if any fails, evaluated left-to-right.
+* Useful for combining independent operations that must all succeed.
+*
+* @param r1 - First Result
+* @param r2 - Second Result
+* @param r3 - Third Result
+* @returns Result containing tuple of all values, or first error
+*
+* @example
+* ```typescript
+* const user = fetchUser(id);
+* const settings = fetchSettings(id);
+* const permissions = fetchPermissions(id);
+* const combined = combine3(user, settings, permissions);
+*
+* if (combined.isOk()) {
+*   const [userData, userSettings, userPermissions] = combined.value;
+* }
+* ```
+*/
+declare const combine3: <
+	T1,
+	T2,
+	T3,
+	E
+>(r1: Result<T1, E>, r2: Result<T2, E>, r3: Result<T3, E>) => Result<[T1, T2, T3], E>;
+export { unwrapOrElse, orElse, combine3, combine2 };

package/dist/result/index.js

@@ -0,0 +1,13 @@
+// @bun
+import {
+  combine2,
+  combine3,
+  orElse,
+  unwrapOrElse
+} from "./utilities.js";
+export {
+  unwrapOrElse,
+  orElse,
+  combine3,
+  combine2
+};

package/dist/result/utilities.d.ts

@@ -0,0 +1,103 @@
+import { Result } from "better-result";
+/**
+* Extract value from Ok, or compute default from error.
+*
+* Unlike `unwrapOr`, the default is computed lazily only on Err.
+* This is useful when the default value is expensive to compute
+* and should only be evaluated when needed.
+*
+* @param result - The Result to unwrap
+* @param defaultFn - Function to compute default value from error
+* @returns The success value or computed default
+*
+* @example
+* ```typescript
+* const result = Result.err("not found");
+* const value = unwrapOrElse(result, (error) => {
+*   console.log("Computing expensive default due to:", error);
+*   return expensiveComputation();
+* });
+* ```
+*/
+declare const unwrapOrElse: <
+	T,
+	E
+>(result: Result<T, E>, defaultFn: (error: E) => T) => T;
+/**
+* Return first Ok, or fallback if first is Err.
+*
+* Useful for trying alternative operations - if the first fails,
+* fall back to an alternative Result.
+*
+* @param result - The primary Result to try
+* @param fallback - The fallback Result if primary is Err
+* @returns First Ok result, or fallback
+*
+* @example
+* ```typescript
+* const primary = parseFromCache(key);
+* const fallback = parseFromNetwork(key);
+* const result = orElse(primary, fallback);
+* ```
+*/
+declare const orElse: <
+	T,
+	E,
+	F
+>(result: Result<T, E>, fallback: Result<T, F>) => Result<T, F>;
+/**
+* Combine two Results into a tuple Result.
+*
+* Returns first error if either fails, evaluated left-to-right.
+* Useful for combining independent operations that must all succeed.
+*
+* @param r1 - First Result
+* @param r2 - Second Result
+* @returns Result containing tuple of both values, or first error
+*
+* @example
+* ```typescript
+* const user = fetchUser(id);
+* const settings = fetchSettings(id);
+* const combined = combine2(user, settings);
+*
+* if (combined.isOk()) {
+*   const [userData, userSettings] = combined.value;
+* }
+* ```
+*/
+declare const combine2: <
+	T1,
+	T2,
+	E
+>(r1: Result<T1, E>, r2: Result<T2, E>) => Result<[T1, T2], E>;
+/**
+* Combine three Results into a tuple Result.
+*
+* Returns first error if any fails, evaluated left-to-right.
+* Useful for combining independent operations that must all succeed.
+*
+* @param r1 - First Result
+* @param r2 - Second Result
+* @param r3 - Third Result
+* @returns Result containing tuple of all values, or first error
+*
+* @example
+* ```typescript
+* const user = fetchUser(id);
+* const settings = fetchSettings(id);
+* const permissions = fetchPermissions(id);
+* const combined = combine3(user, settings, permissions);
+*
+* if (combined.isOk()) {
+*   const [userData, userSettings, userPermissions] = combined.value;
+* }
+* ```
+*/
+declare const combine3: <
+	T1,
+	T2,
+	T3,
+	E
+>(r1: Result<T1, E>, r2: Result<T2, E>, r3: Result<T3, E>) => Result<[T1, T2, T3], E>;
+export { unwrapOrElse, orElse, combine3, combine2 };

package/dist/result/utilities.js

@@ -0,0 +1,31 @@
+// @bun
+// packages/contracts/src/result/utilities.ts
+import { Result } from "better-result";
+var unwrapOrElse = (result, defaultFn) => {
+  return result.isOk() ? result.value : defaultFn(result.error);
+};
+var orElse = (result, fallback) => {
+  return result.isOk() ? result : fallback;
+};
+var combine2 = (r1, r2) => {
+  if (r1.isErr())
+    return r1;
+  if (r2.isErr())
+    return r2;
+  return Result.ok([r1.value, r2.value]);
+};
+var combine3 = (r1, r2, r3) => {
+  if (r1.isErr())
+    return r1;
+  if (r2.isErr())
+    return r2;
+  if (r3.isErr())
+    return r3;
+  return Result.ok([r1.value, r2.value, r3.value]);
+};
+export {
+  unwrapOrElse,
+  orElse,
+  combine3,
+  combine2
+};