@classytic/arc 2.9.1 → 2.10.8

package/dist/{types-CoSzA-s-.d.mts → types-CVKBssX5.d.mts}

@@ -1,4 +1,4 @@
-import { Kt as ResourceDefinition } from "./interface-YrWsmKqE.mjs";
+import { B as ResourceDefinition } from "./index-BGbpGVyM.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts

package/dist/{types-CunEX4UX.d.mts → types-CVdgPXBW.d.mts}

@@ -1,11 +1,12 @@
-import { b as Authenticator } from "./interface-YrWsmKqE.mjs";
-import { n as ElevationOptions } from "./elevation-B6S5csVA.mjs";
+import { Gt as Authenticator } from "./index-BGbpGVyM.mjs";
+import { n as ElevationOptions } from "./elevation-s5ykdNHr.mjs";
+import { o as EventTransport } from "./EventTransport-CfVEGaEl.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-Bapitwvd.mjs";
-import { i as CacheStore } from "./interface-DplgQO2e.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-CnTZZTC5.mjs";
-import { o as EventTransport } from "./EventTransport-CqZ8FyM_.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-BxvaCIZF.mjs";
-import { a as VersioningOptions, g as CachingOptions, p as SSEOptions, t as ErrorHandlerOptions, u as MetricsOptions } from "./errorHandler-DixGcttC.mjs";
+import { r as CacheStore } from "./interface-yhyb_pLY.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-Dumka73q.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-D1ThQ1Pp.mjs";
+import { f as CachingOptions, l as SSEOptions, o as MetricsOptions, t as VersioningOptions } from "./versioning-CeUXHfjw.mjs";
+import { t as ErrorHandlerOptions } from "./errorHandler-2ii4RIYr.mjs";
 import { r as IdempotencyStore } from "./interface-B-pe8fhj.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 
@@ -149,6 +150,18 @@ type HelmetOptions = Record<string, unknown>;
 type RateLimitOpts = Record<string, unknown> & {
   max?: number;
   timeWindow?: string | number;
+  /**
+   * Path patterns to exempt from rate limiting. Supports exact match
+   * (`/health`) or prefix match with trailing `*` (`/api/auth/*`).
+   *
+   * Implemented by synthesising a `@fastify/rate-limit` `allowList`
+   * function. When combined with a user-supplied `allowList`, both
+   * are OR-ed together (path OR ip/custom match skips the limit).
+   *
+   * Use this for endpoints that are hit frequently but independently
+   * of user traffic — session heartbeat, webhooks, health probes.
+   */
+  skipPaths?: string[];
 };
 /**
  * Arc's built-in JWT auth

package/dist/utils/index.d.mts

@@ -1,8 +1,213 @@
-import { J as OpenApiSchemas, X as ParsedQuery, p as AnyRecord, tt as QueryParserInterface } from "../interface-YrWsmKqE.mjs";
+import { S as QueryParserInterface, Yt as AnyRecord, b as ParsedQuery, mt as OpenApiSchemas } from "../index-BGbpGVyM.mjs";
+import { n as ErrorMapper } from "../errorHandler-2ii4RIYr.mjs";
 import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-BI8kEKsO.mjs";
-import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-CvXkjfrW.mjs";
 import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 
+//#region src/utils/circuitBreaker.d.ts
+/**
+ * Circuit Breaker Pattern
+ *
+ * Wraps external service calls with failure protection.
+ * Prevents cascading failures by "opening" the circuit when
+ * a service is failing, allowing it time to recover.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Too many failures, all requests fail fast
+ * - HALF_OPEN: Testing if service recovered, limited requests
+ *
+ * @example
+ * import { CircuitBreaker } from '@classytic/arc/utils';
+ *
+ * const paymentBreaker = new CircuitBreaker(async (amount) => {
+ *   return await stripe.charges.create({ amount });
+ * }, {
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000,
+ *   timeout: 5000,
+ * });
+ *
+ * try {
+ *   const result = await paymentBreaker.call(100);
+ * } catch (error) {
+ *   // Handle failure or circuit open
+ * }
+ */
+declare const CircuitState: {
+  readonly CLOSED: "CLOSED";
+  readonly OPEN: "OPEN";
+  readonly HALF_OPEN: "HALF_OPEN";
+};
+type CircuitState = (typeof CircuitState)[keyof typeof CircuitState];
+interface CircuitBreakerOptions {
+  /**
+   * Number of failures before opening circuit
+   * @default 5
+   */
+  failureThreshold?: number;
+  /**
+   * Time in ms before attempting to close circuit
+   * @default 60000 (60 seconds)
+   */
+  resetTimeout?: number;
+  /**
+   * Request timeout in ms
+   * @default 10000 (10 seconds)
+   */
+  timeout?: number;
+  /**
+   * Number of successful requests in HALF_OPEN before closing
+   * @default 1
+   */
+  successThreshold?: number;
+  /**
+   * Fallback function when circuit is open.
+   * Receives the same arguments as the wrapped function.
+   */
+  fallback?: (...args: unknown[]) => Promise<unknown>;
+  /**
+   * Callback when state changes
+   */
+  onStateChange?: (from: CircuitState, to: CircuitState) => void;
+  /**
+   * Callback on error
+   */
+  onError?: (error: Error) => void;
+  /**
+   * Name for logging/monitoring
+   */
+  name?: string;
+}
+interface CircuitBreakerStats {
+  name?: string;
+  state: CircuitState;
+  failures: number;
+  successes: number;
+  totalCalls: number;
+  openedAt: number | null;
+  lastCallAt: number | null;
+}
+declare class CircuitBreakerError extends Error {
+  state: CircuitState;
+  constructor(message: string, state: CircuitState);
+}
+declare class CircuitBreaker<T extends (...args: any[]) => Promise<any>> {
+  private state;
+  private failures;
+  private successes;
+  private totalCalls;
+  private nextAttempt;
+  private lastCallAt;
+  private openedAt;
+  private readonly failureThreshold;
+  private readonly resetTimeout;
+  private readonly timeout;
+  private readonly successThreshold;
+  private readonly fallback?;
+  private readonly onStateChange?;
+  private readonly onError?;
+  private readonly name;
+  private readonly fn;
+  constructor(fn: T, options?: CircuitBreakerOptions);
+  /**
+   * Call the wrapped function with circuit breaker protection
+   */
+  call(...args: Parameters<T>): Promise<ReturnType<T>>;
+  /**
+   * Execute function with timeout
+   */
+  private executeWithTimeout;
+  /**
+   * Handle successful call
+   */
+  private onSuccess;
+  /**
+   * Handle failed call
+   */
+  private onFailure;
+  /**
+   * Change circuit state
+   */
+  private setState;
+  /**
+   * Manually open the circuit
+   */
+  open(): void;
+  /**
+   * Manually close the circuit
+   */
+  close(): void;
+  /**
+   * Get current statistics
+   */
+  getStats(): CircuitBreakerStats;
+  /**
+   * Get current state
+   */
+  getState(): CircuitState;
+  /**
+   * Check if circuit is open
+   */
+  isOpen(): boolean;
+  /**
+   * Check if circuit is closed
+   */
+  isClosed(): boolean;
+  /**
+   * Reset statistics
+   */
+  reset(): void;
+}
+/**
+ * Create a circuit breaker with sensible defaults
+ *
+ * @example
+ * const emailBreaker = createCircuitBreaker(
+ *   async (to, subject, body) => sendEmail(to, subject, body),
+ *   { name: 'email-service' }
+ * );
+ */
+declare function createCircuitBreaker<T extends (...args: any[]) => Promise<any>>(fn: T, options?: CircuitBreakerOptions): CircuitBreaker<T>;
+/**
+ * Circuit breaker registry for managing multiple breakers
+ */
+declare class CircuitBreakerRegistry {
+  private breakers;
+  /**
+   * Register a circuit breaker
+   */
+  register<T extends (...args: any[]) => Promise<any>>(name: string, fn: T, options?: Omit<CircuitBreakerOptions, "name">): CircuitBreaker<T>;
+  /**
+   * Get a circuit breaker by name
+   */
+  get(name: string): CircuitBreaker<any> | undefined;
+  /**
+   * Get all breakers
+   */
+  getAll(): Map<string, CircuitBreaker<any>>;
+  /**
+   * Get statistics for all breakers
+   */
+  getAllStats(): Record<string, CircuitBreakerStats>;
+  /**
+   * Reset all breakers
+   */
+  resetAll(): void;
+  /**
+   * Open all breakers
+   */
+  openAll(): void;
+  /**
+   * Close all breakers
+   */
+  closeAll(): void;
+}
+/**
+ * Create a new CircuitBreakerRegistry instance.
+ * Use this instead of a global singleton — attach to fastify.arc or pass explicitly.
+ */
+declare function createCircuitBreakerRegistry(): CircuitBreakerRegistry;
+//#endregion
 //#region src/utils/compensation.d.ts
 /**
  * Compensating Transaction — In-Process Rollback Primitive
@@ -92,6 +297,22 @@ interface CompensationDefinition<TCtx extends Record<string, unknown> = Record<s
 }
 declare function defineCompensation<TCtx extends Record<string, unknown> = Record<string, unknown>>(name: string, steps: readonly CompensationStep<TCtx>[]): CompensationDefinition<TCtx>;
 //#endregion
+//#region src/utils/defineErrorMapper.d.ts
+/**
+ * Register an `ErrorMapper` with its domain-specific generic argument and
+ * have it assign cleanly into `ErrorMapper[]` (no `as unknown as ErrorMapper`).
+ *
+ * The returned mapper is identical at runtime — `type` and `toResponse` are
+ * passed through untouched. Only the declared type widens from
+ * `ErrorMapper<T>` to `ErrorMapper` so the array inference works.
+ *
+ * Safety: the `errorHandlerPlugin` dispatches via `error instanceof mapper.type`
+ * before invoking `toResponse`, so the widened callback signature is never
+ * called with a non-`T` error at runtime. This helper codifies that invariant
+ * in one place.
+ */
+declare function defineErrorMapper<T extends Error>(mapper: ErrorMapper<T>): ErrorMapper;
+//#endregion
 //#region src/utils/defineGuard.d.ts
 interface GuardConfig<T> {
   /** Unique name — used as the storage key on the request. */
@@ -561,6 +782,59 @@ declare function convertOpenApiSchemas(schemas: OpenApiSchemas, target?: JsonSch
  */
 declare function convertRouteSchema(schema: Record<string, unknown>, target?: JsonSchemaTarget): Record<string, unknown>;
 //#endregion
+//#region src/utils/simpleEqualityMatcher.d.ts
+/**
+ * `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality
+ * matcher for `DataAdapter.matchesFilter` / `BaseController({ matchesFilter })`.
+ *
+ * **What it does:** for each `[key, expected]` in the filter, compares
+ * `item[key]` to `expected` via string coercion (so Mongo `ObjectId` values
+ * match their string representation) and returns `true` only if every
+ * filter entry matches. Array item values are matched implicitly (contains).
+ *
+ * **What it does NOT do:**
+ * - No `$eq` / `$ne` / `$in` / `$nin` / `$gt` / `$lt` / `$regex` / `$exists`
+ * - No `$and` / `$or`
+ * - No dot-path traversal (`"owner.id"`)
+ * - No schema-specific coercion
+ *
+ * **Why it exists:** 95%+ of arc's `_policyFilters` are produced by built-in
+ * permission helpers and are shaped like `{ ownerId: "u1" }` or
+ * `{ organizationId: "org_x" }` — flat equality. For that common shape,
+ * this helper is a safe, tested, 15-line defense-in-depth matcher that
+ * hosts using minimal repos (no `getOne(compoundFilter)` DB path) can opt
+ * into without arc shipping a full Mongo-syntax engine.
+ *
+ * **When to use:**
+ * - Your adapter/repo doesn't natively filter on `getOne(compoundFilter)`
+ * - Your `_policyFilters` are flat equality (from arc's built-in permission helpers)
+ * - You want defense-in-depth on `validateItemAccess` / `fetchDetailed`'s `getById` fallback
+ *
+ * **When NOT to use:**
+ * - Your `_policyFilters` use operators (`$in`, `$ne`, etc.) — supply a
+ *   native matcher (mongokit's repo does the filter at the DB layer; for
+ *   custom repos, wrap the kit's own predicate engine).
+ * - You're a mongokit / sqlitekit / Prisma user — the DB-level filter
+ *   applied by `getOne(compoundFilter)` already covers this.
+ *
+ * @example
+ * ```ts
+ * import { simpleEqualityMatcher } from '@classytic/arc/utils';
+ *
+ * // On a custom adapter
+ * const adapter: DataAdapter = {
+ *   repository,
+ *   type: 'custom',
+ *   name: 'in-memory',
+ *   matchesFilter: simpleEqualityMatcher,
+ * };
+ *
+ * // Or directly on BaseController for ad-hoc controllers
+ * new BaseController(repo, { matchesFilter: simpleEqualityMatcher });
+ * ```
+ */
+declare function simpleEqualityMatcher(item: unknown, filters: Record<string, unknown>): boolean;
+//#endregion
 //#region src/utils/stateMachine.d.ts
 /**
  * State Machine Utility
@@ -691,4 +965,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
   events: EventsDecorator;
 };
 //#endregion
-export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorDetails, type EventsDecorator, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineGuard, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, listResponse, mutationResponse, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };
+export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorDetails, type EventsDecorator, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, listResponse, mutationResponse, paginationSchema, queryParams, responses, simpleEqualityMatcher, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };

package/dist/utils/index.mjs

@@ -1,7 +1,6 @@
-import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-CqWnSqM-.mjs";
-import { n as createQueryParser, t as ArcQueryParser } from "../queryParser-Cs-6SHQK.mjs";
-import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-l18oRgL5.mjs";
-import { _ as withCompensation, a as getListQueryParams, c as mutationResponse, d as responses, f as successResponseSchema, g as defineCompensation, h as defineGuard, i as getDefaultCrudSchemas, l as paginationSchema, m as handleRaw, n as deleteResponse, o as itemResponse, p as wrapResponse, r as errorResponseSchema, s as listResponse, t as createStateMachine, u as queryParams } from "../utils-B7FuRr9w.mjs";
+import { n as createQueryParser, r as simpleEqualityMatcher, t as ArcQueryParser } from "../queryParser-NR__Qiju.mjs";
+import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-BqdUDja_.mjs";
+import { C as createCircuitBreaker, S as CircuitState, _ as defineCompensation, a as getListQueryParams, b as CircuitBreakerError, c as mutationResponse, d as responses, f as successResponseSchema, g as defineErrorMapper, h as defineGuard, i as getDefaultCrudSchemas, l as paginationSchema, m as handleRaw, n as deleteResponse, o as itemResponse, p as wrapResponse, r as errorResponseSchema, s as listResponse, t as createStateMachine, u as queryParams, v as withCompensation, w as createCircuitBreakerRegistry, x as CircuitBreakerRegistry, y as CircuitBreaker } from "../utils-LMwVidKy.mjs";
 import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-BxFDdtXu.mjs";
 import { t as hasEvents } from "../typeGuards-Cj5Rgvlg.mjs";
-export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineGuard, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, listResponse, mutationResponse, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };
+export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, listResponse, mutationResponse, paginationSchema, queryParams, responses, simpleEqualityMatcher, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };

package/dist/{utils-B7FuRr9w.mjs → utils-LMwVidKy.mjs}

@@ -1,4 +1,287 @@
-import { t as ArcError } from "./errors-CqWnSqM-.mjs";
+import { t as ArcError } from "./errors-BqdUDja_.mjs";
+//#region src/utils/circuitBreaker.ts
+/**
+* Circuit Breaker Pattern
+*
+* Wraps external service calls with failure protection.
+* Prevents cascading failures by "opening" the circuit when
+* a service is failing, allowing it time to recover.
+*
+* States:
+* - CLOSED: Normal operation, requests pass through
+* - OPEN: Too many failures, all requests fail fast
+* - HALF_OPEN: Testing if service recovered, limited requests
+*
+* @example
+* import { CircuitBreaker } from '@classytic/arc/utils';
+*
+* const paymentBreaker = new CircuitBreaker(async (amount) => {
+*   return await stripe.charges.create({ amount });
+* }, {
+*   failureThreshold: 5,
+*   resetTimeout: 30000,
+*   timeout: 5000,
+* });
+*
+* try {
+*   const result = await paymentBreaker.call(100);
+* } catch (error) {
+*   // Handle failure or circuit open
+* }
+*/
+const CircuitState = {
+	CLOSED: "CLOSED",
+	OPEN: "OPEN",
+	HALF_OPEN: "HALF_OPEN"
+};
+var CircuitBreakerError = class extends Error {
+	state;
+	constructor(message, state) {
+		super(message);
+		this.name = "CircuitBreakerError";
+		this.state = state;
+	}
+};
+var CircuitBreaker = class {
+	state = CircuitState.CLOSED;
+	failures = 0;
+	successes = 0;
+	totalCalls = 0;
+	nextAttempt = 0;
+	lastCallAt = null;
+	openedAt = null;
+	failureThreshold;
+	resetTimeout;
+	timeout;
+	successThreshold;
+	fallback;
+	onStateChange;
+	onError;
+	name;
+	fn;
+	constructor(fn, options = {}) {
+		this.fn = fn;
+		this.failureThreshold = options.failureThreshold ?? 5;
+		this.resetTimeout = options.resetTimeout ?? 6e4;
+		this.timeout = options.timeout ?? 1e4;
+		this.successThreshold = options.successThreshold ?? 1;
+		this.fallback = options.fallback;
+		this.onStateChange = options.onStateChange;
+		this.onError = options.onError;
+		this.name = options.name ?? "CircuitBreaker";
+	}
+	/**
+	* Call the wrapped function with circuit breaker protection
+	*/
+	async call(...args) {
+		this.totalCalls++;
+		this.lastCallAt = Date.now();
+		if (this.state === CircuitState.OPEN) {
+			if (Date.now() < this.nextAttempt) {
+				const error = new CircuitBreakerError(`Circuit breaker is OPEN for ${this.name}`, CircuitState.OPEN);
+				if (this.fallback) return this.fallback(...args);
+				throw error;
+			}
+			this.setState(CircuitState.HALF_OPEN);
+		}
+		try {
+			const result = await this.executeWithTimeout(args);
+			this.onSuccess();
+			return result;
+		} catch (err) {
+			this.onFailure(err instanceof Error ? err : new Error(String(err)));
+			throw err;
+		}
+	}
+	/**
+	* Execute function with timeout
+	*/
+	async executeWithTimeout(args) {
+		return new Promise((resolve, reject) => {
+			const timeoutId = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`Request timeout after ${this.timeout}ms`));
+			}, this.timeout);
+			this.fn(...args).then((result) => {
+				clearTimeout(timeoutId);
+				resolve(result);
+			}).catch((error) => {
+				clearTimeout(timeoutId);
+				reject(error);
+			});
+		});
+	}
+	/**
+	* Handle successful call
+	*/
+	onSuccess() {
+		this.failures = 0;
+		this.successes++;
+		if (this.state === CircuitState.HALF_OPEN) {
+			if (this.successes >= this.successThreshold) {
+				this.setState(CircuitState.CLOSED);
+				this.successes = 0;
+			}
+		}
+	}
+	/**
+	* Handle failed call
+	*/
+	onFailure(error) {
+		this.failures++;
+		this.successes = 0;
+		if (this.onError) this.onError(error);
+		if (this.state === CircuitState.HALF_OPEN || this.failures >= this.failureThreshold) {
+			this.setState(CircuitState.OPEN);
+			this.nextAttempt = Date.now() + this.resetTimeout;
+			this.openedAt = Date.now();
+		}
+	}
+	/**
+	* Change circuit state
+	*/
+	setState(newState) {
+		const oldState = this.state;
+		if (oldState !== newState) {
+			this.state = newState;
+			if (this.onStateChange) this.onStateChange(oldState, newState);
+		}
+	}
+	/**
+	* Manually open the circuit
+	*/
+	open() {
+		this.setState(CircuitState.OPEN);
+		this.nextAttempt = Date.now() + this.resetTimeout;
+		this.openedAt = Date.now();
+	}
+	/**
+	* Manually close the circuit
+	*/
+	close() {
+		this.failures = 0;
+		this.successes = 0;
+		this.setState(CircuitState.CLOSED);
+		this.openedAt = null;
+	}
+	/**
+	* Get current statistics
+	*/
+	getStats() {
+		return {
+			name: this.name,
+			state: this.state,
+			failures: this.failures,
+			successes: this.successes,
+			totalCalls: this.totalCalls,
+			openedAt: this.openedAt,
+			lastCallAt: this.lastCallAt
+		};
+	}
+	/**
+	* Get current state
+	*/
+	getState() {
+		return this.state;
+	}
+	/**
+	* Check if circuit is open
+	*/
+	isOpen() {
+		return this.state === CircuitState.OPEN;
+	}
+	/**
+	* Check if circuit is closed
+	*/
+	isClosed() {
+		return this.state === CircuitState.CLOSED;
+	}
+	/**
+	* Reset statistics
+	*/
+	reset() {
+		this.failures = 0;
+		this.successes = 0;
+		this.totalCalls = 0;
+		this.lastCallAt = null;
+		this.openedAt = null;
+		this.setState(CircuitState.CLOSED);
+	}
+};
+/**
+* Create a circuit breaker with sensible defaults
+*
+* @example
+* const emailBreaker = createCircuitBreaker(
+*   async (to, subject, body) => sendEmail(to, subject, body),
+*   { name: 'email-service' }
+* );
+*/
+function createCircuitBreaker(fn, options) {
+	return new CircuitBreaker(fn, options);
+}
+/**
+* Circuit breaker registry for managing multiple breakers
+*/
+var CircuitBreakerRegistry = class {
+	breakers = /* @__PURE__ */ new Map();
+	/**
+	* Register a circuit breaker
+	*/
+	register(name, fn, options) {
+		const breaker = new CircuitBreaker(fn, {
+			...options,
+			name
+		});
+		this.breakers.set(name, breaker);
+		return breaker;
+	}
+	/**
+	* Get a circuit breaker by name
+	*/
+	get(name) {
+		return this.breakers.get(name);
+	}
+	/**
+	* Get all breakers
+	*/
+	getAll() {
+		return this.breakers;
+	}
+	/**
+	* Get statistics for all breakers
+	*/
+	getAllStats() {
+		const stats = {};
+		for (const [name, breaker] of this.breakers.entries()) stats[name] = breaker.getStats();
+		return stats;
+	}
+	/**
+	* Reset all breakers
+	*/
+	resetAll() {
+		for (const breaker of this.breakers.values()) breaker.reset();
+	}
+	/**
+	* Open all breakers
+	*/
+	openAll() {
+		for (const breaker of this.breakers.values()) breaker.open();
+	}
+	/**
+	* Close all breakers
+	*/
+	closeAll() {
+		for (const breaker of this.breakers.values()) breaker.close();
+	}
+};
+/**
+* Create a new CircuitBreakerRegistry instance.
+* Use this instead of a global singleton — attach to fastify.arc or pass explicitly.
+*/
+function createCircuitBreakerRegistry() {
+	return new CircuitBreakerRegistry();
+}
+//#endregion
 //#region src/utils/compensation.ts
 /**
 * Run steps in order with automatic compensation on failure.
@@ -70,6 +353,24 @@ function defineCompensation(name, steps) {
 	};
 }
 //#endregion
+//#region src/utils/defineErrorMapper.ts
+/**
+* Register an `ErrorMapper` with its domain-specific generic argument and
+* have it assign cleanly into `ErrorMapper[]` (no `as unknown as ErrorMapper`).
+*
+* The returned mapper is identical at runtime — `type` and `toResponse` are
+* passed through untouched. Only the declared type widens from
+* `ErrorMapper<T>` to `ErrorMapper` so the array inference works.
+*
+* Safety: the `errorHandlerPlugin` dispatches via `error instanceof mapper.type`
+* before invoking `toResponse`, so the widened callback signature is never
+* called with a non-`T` error at runtime. This helper codifies that invariant
+* in one place.
+*/
+function defineErrorMapper(mapper) {
+	return mapper;
+}
+//#endregion
 //#region src/utils/defineGuard.ts
 /** Hidden property key for guard context storage on the request object. */
 const GUARD_STORE_KEY = "__arcGuardContext";
@@ -643,4 +944,4 @@ function createStateMachine(name, transitions = {}, options = {}) {
 	};
 }
 //#endregion
-export { withCompensation as _, getListQueryParams as a, mutationResponse as c, responses as d, successResponseSchema as f, defineCompensation as g, defineGuard as h, getDefaultCrudSchemas as i, paginationSchema as l, handleRaw as m, deleteResponse as n, itemResponse as o, wrapResponse as p, errorResponseSchema as r, listResponse as s, createStateMachine as t, queryParams as u };
+export { createCircuitBreaker as C, CircuitState as S, defineCompensation as _, getListQueryParams as a, CircuitBreakerError as b, mutationResponse as c, responses as d, successResponseSchema as f, defineErrorMapper as g, defineGuard as h, getDefaultCrudSchemas as i, paginationSchema as l, handleRaw as m, deleteResponse as n, itemResponse as o, wrapResponse as p, errorResponseSchema as r, listResponse as s, createStateMachine as t, queryParams as u, withCompensation as v, createCircuitBreakerRegistry as w, CircuitBreakerRegistry as x, CircuitBreaker as y };