@classytic/arc 2.8.5 → 2.10.3

package/dist/types-Csi3FLfq.mjs

@@ -0,0 +1,27 @@
+//#region src/types/base.ts
+/** Extract user ID from a user object (supports both id and _id). */
+function getUserId(user) {
+	if (!user) return void 0;
+	const id = user.id ?? user._id;
+	return id ? String(id) : void 0;
+}
+/**
+* Wrap data in Arc's standard `{ success: true, data }` envelope.
+*
+* @example
+* ```typescript
+* handler: async (req, reply) => {
+*   const data = await getResults();
+*   return envelope(data);  // → { success: true, data }
+* }
+* ```
+*/
+function envelope(data, meta) {
+	return {
+		success: true,
+		data,
+		...meta
+	};
+}
+//#endregion
+export { getUserId as n, envelope as t };

package/dist/utils/index.d.mts

@@ -1,8 +1,212 @@
-import { Y as OpenApiSchemas, Z as ParsedQuery, m as AnyRecord, nt as QueryParserInterface } from "../interface-CMRutPfe.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-Ck2h67pm.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-dTtG-UyS.mjs";
+import { Kt as QueryParserInterface, Wt as ParsedQuery, dn as AnyRecord, rt as OpenApiSchemas } from "../index-Cl0uoKd5.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-CCSsMpXE.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
@@ -554,7 +758,7 @@ declare function convertOpenApiSchemas(schemas: OpenApiSchemas, target?: JsonSch
  *
  * JSON Schema values pass through unchanged. Only Zod schemas are converted.
  *
- * Used for both additionalRoutes and customSchemas (CRUD overrides).
+ * Used for both custom routes and customSchemas (CRUD overrides).
  *
  * Defaults to `draft-7` so Fastify v5's bundled AJV 8 accepts the output.
  * Pass `openapi-3.0` (or `openapi-3.1`) when generating OpenAPI documents.

package/dist/utils/index.mjs

@@ -1,7 +1,6 @@
-import { n as createQueryParser, t as ArcQueryParser } from "../queryParser-CgCtsjti.mjs";
-import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-Y7nCYaLJ.mjs";
-import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-cmi5XDv5.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-yYT3HDXt.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-BF2bIOIS.mjs";
-import { t as hasEvents } from "../typeGuards-CcFZXgU7.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-D5c-5BJL.mjs";
+import { n as createQueryParser, t as ArcQueryParser } from "../queryParser-DBqBB6AC.mjs";
+import { C as createCircuitBreakerRegistry, S as createCircuitBreaker, _ as withCompensation, a as getListQueryParams, b as CircuitBreakerRegistry, 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, v as CircuitBreaker, x as CircuitState, y as CircuitBreakerError } from "../utils-B2fNOD_i.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 };

package/dist/{utils-yYT3HDXt.mjs → utils-B2fNOD_i.mjs}

@@ -1,4 +1,287 @@
-import { t as ArcError } from "./errors-BF2bIOIS.mjs";
+import { t as ArcError } from "./errors-D5c-5BJL.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.
@@ -643,4 +926,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 { createCircuitBreakerRegistry as C, createCircuitBreaker as S, withCompensation as _, getListQueryParams as a, CircuitBreakerRegistry as b, 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, CircuitBreaker as v, CircuitState as x, CircuitBreakerError as y };

package/dist/{versioning-CDugduqI.mjs → versioning-C2U_bLY0.mjs}

@@ -10,7 +10,7 @@ const versioningPlugin = async (fastify, opts) => {
 	const { type, defaultVersion = "1", headerName = "accept-version", responseHeader = "x-api-version", deprecated = [], sunset } = opts;
 	const deprecatedSet = new Set(deprecated);
 	fastify.decorateRequest("apiVersion", defaultVersion);
-	fastify.addHook("onRequest", async (request) => {
+	fastify.addHook("onRequest", async (request, reply) => {
 		let version = defaultVersion;
 		if (type === "header") {
 			const headerValue = request.headers[headerName];
@@ -20,10 +20,8 @@ const versioningPlugin = async (fastify, opts) => {
 			if (match) version = match[1] ?? defaultVersion;
 		}
 		request.apiVersion = version;
-	});
-	fastify.addHook("onSend", async (request, reply) => {
-		reply.header(responseHeader, request.apiVersion);
-		if (deprecatedSet.has(request.apiVersion)) {
+		reply.header(responseHeader, version);
+		if (deprecatedSet.has(version)) {
 			reply.header("deprecation", "true");
 			reply.header("sunset", sunset ?? new Date(Date.now() + 2160 * 60 * 60 * 1e3).toISOString());
 		}