@classytic/arc 1.1.0 → 2.1.3

package/dist/utils/index.d.mts

@@ -0,0 +1,747 @@
+import "../elevation-DGo5shaX.mjs";
+import "../interface-e9XfSsUV.mjs";
+import "../types-RLkFVgaw.mjs";
+import { AnyRecord, OpenApiSchemas, ParsedQuery, QueryParserInterface } from "../types/index.mjs";
+import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createError, i as ForbiddenError, l as ServiceUnavailableError, n as ConflictError, o as OrgAccessDeniedError, p as isArcError, r as ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-DAWRdiYP.mjs";
+import { FastifyInstance } from "fastify";
+
+//#region src/utils/responseSchemas.d.ts
+interface JsonSchema {
+  type: string;
+  properties?: Record<string, JsonSchema | AnyRecord>;
+  required?: string[];
+  items?: JsonSchema | AnyRecord;
+  additionalProperties?: boolean | JsonSchema;
+  description?: string;
+  example?: unknown;
+  [key: string]: unknown;
+}
+/**
+ * Base success response schema
+ */
+declare const successResponseSchema: JsonSchema;
+/**
+ * Error response schema
+ */
+declare const errorResponseSchema: JsonSchema;
+/**
+ * Pagination schema - matches MongoKit/Arc runtime format
+ *
+ * Runtime format (flat fields):
+ * { page, limit, total, pages, hasNext, hasPrev }
+ */
+declare const paginationSchema: JsonSchema;
+/**
+ * Wrap a data schema in a success response
+ */
+declare function wrapResponse(dataSchema: JsonSchema): JsonSchema;
+/**
+ * Create a list response schema with pagination - matches MongoKit/Arc runtime format
+ *
+ * Runtime format:
+ * { success, docs: [...], page, limit, total, pages, hasNext, hasPrev }
+ *
+ * Note: Uses 'docs' array (not 'data') with flat pagination fields
+ */
+declare function listResponse(itemSchema: JsonSchema): JsonSchema;
+/**
+ * Alias for listResponse - matches local responseSchemas.js naming
+ */
+declare const paginateWrapper: typeof listResponse;
+/**
+ * Create a single item response schema
+ *
+ * Runtime format: { success, data: {...} }
+ */
+declare function itemResponse(itemSchema: JsonSchema): JsonSchema;
+/**
+ * Alias for itemResponse - matches local responseSchemas.js naming
+ */
+declare const itemWrapper: typeof itemResponse;
+/**
+ * Create a create/update response schema
+ */
+declare function mutationResponse(itemSchema: JsonSchema): JsonSchema;
+/**
+ * Create a delete response schema
+ *
+ * Runtime format: { success, message }
+ */
+declare function deleteResponse(): JsonSchema;
+/**
+ * Alias for deleteResponse - matches local responseSchemas.js naming
+ */
+declare const messageWrapper: typeof deleteResponse;
+declare const responses: {
+  200: (schema: JsonSchema) => {
+    description: string;
+    content: {
+      'application/json': {
+        schema: JsonSchema;
+      };
+    };
+  };
+  201: (schema: JsonSchema) => {
+    description: string;
+    content: {
+      'application/json': {
+        schema: JsonSchema;
+      };
+    };
+  };
+  400: {
+    description: string;
+    content: {
+      'application/json': {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+            details: {
+              type: string;
+              properties: {
+                errors: {
+                  type: string;
+                  items: {
+                    type: string;
+                    properties: {
+                      field: {
+                        type: string;
+                      };
+                      message: {
+                        type: string;
+                      };
+                    };
+                  };
+                };
+              };
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+  401: {
+    description: string;
+    content: {
+      'application/json': {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+  403: {
+    description: string;
+    content: {
+      'application/json': {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+  404: {
+    description: string;
+    content: {
+      'application/json': {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+  409: {
+    description: string;
+    content: {
+      'application/json': {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+  500: {
+    description: string;
+    content: {
+      'application/json': {
+        schema: {
+          properties: {
+            code: {
+              type: string;
+              example: string;
+            };
+          };
+          type: string;
+          required?: string[];
+          items?: JsonSchema | AnyRecord;
+          additionalProperties?: boolean | JsonSchema;
+          description?: string;
+          example?: unknown;
+        };
+      };
+    };
+  };
+};
+declare const queryParams: {
+  pagination: {
+    page: {
+      type: string;
+      minimum: number;
+      default: number;
+      description: string;
+    };
+    limit: {
+      type: string;
+      minimum: number;
+      maximum: number;
+      default: number;
+      description: string;
+    };
+  };
+  sorting: {
+    sort: {
+      type: string;
+      description: string;
+      example: string;
+    };
+  };
+  filtering: {
+    select: {
+      description: string;
+      example: string;
+    };
+    populate: {
+      description: string;
+      example: string;
+    };
+  };
+};
+/**
+ * Get standard list query parameters schema
+ */
+declare function getListQueryParams(): AnyRecord;
+/**
+ * Get default response schemas for all CRUD operations.
+ *
+ * When routes have response schemas, Fastify compiles them with
+ * fast-json-stringify for 2-3x faster serialization and prevents
+ * accidental field disclosure.
+ *
+ * These defaults use `additionalProperties: true` so all fields pass through.
+ * Override with specific schemas for full serialization performance + safety.
+ *
+ * Note: `example` properties are stripped from defaults so they work with
+ * any Fastify instance (not just createApp which adds `keywords: ['example']`).
+ */
+declare function getDefaultCrudSchemas(): Record<string, Record<string, unknown>>;
+//#endregion
+//#region src/utils/stateMachine.d.ts
+/**
+ * State Machine Utility
+ *
+ * Pure utility for validating state transitions in workflow systems.
+ * Zero dependencies, framework-agnostic.
+ *
+ * @example
+ * const orderState = createStateMachine('Order', {
+ *   approve: ['pending', 'draft'],
+ *   cancel: ['pending', 'approved'],
+ *   fulfill: ['approved'],
+ * });
+ *
+ * // Check if transition is allowed
+ * if (orderState.can('approve', currentStatus)) {
+ *   // Perform approval
+ * }
+ *
+ * // Assert transition (throws if invalid)
+ * orderState.assert('approve', currentStatus, ValidationError);
+ */
+interface StateMachine {
+  /**
+   * Synchronously check if action can be performed from current status.
+   * Only checks the transition map — does NOT evaluate guards.
+   * Use `canAsync()` when guards need to be evaluated.
+   */
+  can(action: string, status: string | null | undefined): boolean;
+  /**
+   * Asynchronously check if action can be performed, including guard evaluation.
+   * Falls back to simple transition check when no guard is defined.
+   */
+  canAsync(action: string, status: string | null | undefined, context?: any): Promise<boolean>;
+  /**
+   * Assert action can be performed, throw error if invalid
+   * @param action - Action to perform
+   * @param status - Current status
+   * @param errorFactory - Optional error constructor
+   * @param message - Optional custom error message
+   */
+  assert(action: string, status: string | null | undefined, errorFactory?: (msg: string) => Error, message?: string): void;
+  /**
+   * Get transition history
+   */
+  getHistory?(): TransitionHistoryEntry[];
+  /**
+   * Record a transition
+   */
+  recordTransition?(from: string, to: string, action: string, metadata?: any): void;
+  /**
+   * Clear history
+   */
+  clearHistory?(): void;
+  /**
+   * Get available actions for current status
+   */
+  getAvailableActions?(status: string): string[];
+}
+interface TransitionHistoryEntry {
+  from: string;
+  to: string;
+  action: string;
+  timestamp: Date;
+  metadata?: any;
+}
+interface TransitionGuard {
+  (context: {
+    from: string;
+    to: string;
+    action: string;
+    data?: any;
+  }): boolean | Promise<boolean>;
+}
+interface TransitionAction {
+  (context: {
+    from: string;
+    to: string;
+    action: string;
+    data?: any;
+  }): void | Promise<void>;
+}
+type TransitionConfig = Record<string, string[] | {
+  from: string[];
+  to?: string;
+  guard?: TransitionGuard;
+  before?: TransitionAction;
+  after?: TransitionAction;
+}>;
+/**
+ * Create a state machine for validating transitions
+ *
+ * @param name - Name of the state machine (used in error messages)
+ * @param transitions - Map of actions to allowed source statuses
+ * @param options - Additional options (history, guards, actions)
+ * @returns State machine with can() and assert() methods
+ *
+ * @example
+ * // Basic usage
+ * const transferState = createStateMachine('Transfer', {
+ *   approve: ['draft'],
+ *   dispatch: ['approved'],
+ *   receive: ['dispatched', 'in_transit'],
+ *   cancel: ['draft', 'approved'],
+ * });
+ *
+ * @example
+ * // With guards and actions
+ * const orderState = createStateMachine('Order', {
+ *   approve: {
+ *     from: ['pending'],
+ *     to: 'approved',
+ *     guard: ({ data }) => data.paymentConfirmed,
+ *     before: ({ from, to }) => console.log(`Approving order from ${from} to ${to}`),
+ *     after: ({ data }) => sendApprovalEmail(data.customerId),
+ *   },
+ * }, { trackHistory: true });
+ */
+declare function createStateMachine(name: string, transitions?: TransitionConfig, options?: {
+  trackHistory?: boolean;
+}): StateMachine;
+//#endregion
+//#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
+   */
+  fallback?: (...args: any[]) => Promise<any>;
+  /**
+   * 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/queryParser.d.ts
+interface ArcQueryParserOptions {
+  /** Maximum allowed limit value (default: 1000) */
+  maxLimit?: number;
+  /** Default limit for pagination (default: 20) */
+  defaultLimit?: number;
+  /** Maximum regex pattern length (default: 500) */
+  maxRegexLength?: number;
+  /** Maximum search query length (default: 200) */
+  maxSearchLength?: number;
+  /** Maximum filter nesting depth (default: 10) */
+  maxFilterDepth?: number;
+}
+/**
+ * Arc's default query parser
+ *
+ * Converts URL query parameters to a structured query format:
+ * - Pagination: ?page=1&limit=20
+ * - Sorting: ?sort=-createdAt,name (- prefix = descending)
+ * - Filtering: ?status=active&price[gte]=100&price[lte]=500
+ * - Search: ?search=keyword
+ * - Populate: ?populate=author,category
+ * - Field selection: ?select=name,price,status
+ * - Keyset pagination: ?after=cursor_value
+ *
+ * For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
+ */
+declare class ArcQueryParser implements QueryParserInterface {
+  private readonly maxLimit;
+  private readonly defaultLimit;
+  private readonly maxRegexLength;
+  private readonly maxSearchLength;
+  private readonly maxFilterDepth;
+  /** Supported filter operators */
+  private readonly operators;
+  constructor(options?: ArcQueryParserOptions);
+  /**
+   * Parse URL query parameters into structured query options
+   */
+  parse(query: Record<string, unknown> | null | undefined): ParsedQuery;
+  private parseNumber;
+  private parseString;
+  /**
+   * Parse populate parameter — handles both simple string and bracket notation.
+   *
+   * Simple: ?populate=author,category → { populate: 'author,category' }
+   * Bracket: ?populate[author][select]=name,email → { populateOptions: [{ path: 'author', select: 'name email' }] }
+   */
+  private parsePopulate;
+  private parseSort;
+  private parseSearch;
+  private parseSelect;
+  /**
+   * Check if a value exceeds the maximum nesting depth.
+   * Prevents filter bombs where deeply nested objects consume excessive memory/CPU.
+   */
+  private exceedsDepth;
+  private parseFilters;
+  private parseFilterValue;
+  private coerceValue;
+  /**
+   * Generate OpenAPI-compatible JSON Schema for query parameters.
+   * Arc's defineResource() auto-detects this method and uses it
+   * to document list endpoint query parameters in OpenAPI/Swagger.
+   */
+  getQuerySchema(): {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  private sanitizeRegex;
+}
+/**
+ * Create a new ArcQueryParser instance
+ */
+declare function createQueryParser(options?: ArcQueryParserOptions): ArcQueryParser;
+//#endregion
+//#region src/utils/typeGuards.d.ts
+interface EventsDecorator {
+  publish: <T>(type: string, payload: T, meta?: Record<string, unknown>) => Promise<void>;
+  subscribe: (pattern: string, handler: (event: {
+    type: string;
+    payload: unknown;
+    meta: Record<string, unknown>;
+  }) => Promise<void>) => Promise<() => void>;
+  transportName: string;
+}
+/** Check if fastify has the events plugin registered */
+declare function hasEvents(instance: FastifyInstance): instance is FastifyInstance & {
+  events: EventsDecorator;
+};
+//#endregion
+//#region src/utils/schemaConverter.d.ts
+/**
+ * Check if an object is already a plain JSON Schema.
+ * Returns true if it has JSON Schema markers (`type`, `properties`, `$ref`,
+ * `allOf`, `anyOf`, `oneOf`, `items`, `enum`) and does NOT have Zod markers.
+ */
+declare function isJsonSchema(input: unknown): input is Record<string, unknown>;
+/**
+ * Check if an object is a Zod schema (has `_zod` marker from Zod v4).
+ */
+declare function isZodSchema(input: unknown): boolean;
+/**
+ * Convert any schema input to JSON Schema.
+ *
+ * Detection order:
+ * 1. `null`/`undefined` → `undefined`
+ * 2. Already JSON Schema → pass through as-is (zero overhead)
+ * 3. Zod v4 schema → `z.toJSONSchema(schema, { target: 'openapi-3.0' })`
+ * 4. Unrecognized object → return as-is (treat as opaque schema)
+ */
+declare function toJsonSchema(input: unknown): Record<string, unknown> | undefined;
+/**
+ * Convert all schema fields in an OpenApiSchemas object.
+ * JSON Schema values pass through unchanged. Only Zod schemas are converted.
+ */
+declare function convertOpenApiSchemas(schemas: OpenApiSchemas): OpenApiSchemas;
+/**
+ * Convert schema values in a Fastify route schema record.
+ *
+ * Handles `body`, `querystring`, `params`, `headers` (top-level conversion)
+ * and `response` (iterates by status code — each value converted individually).
+ *
+ * JSON Schema values pass through unchanged. Only Zod schemas are converted.
+ *
+ * Used for both additionalRoutes and customSchemas (CRUD overrides).
+ */
+declare function convertRouteSchema(schema: Record<string, unknown>): Record<string, unknown>;
+//#endregion
+export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, ConflictError, type ErrorDetails, type EventsDecorator, ForbiddenError, type JsonSchema, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createError, createQueryParser, createStateMachine, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, itemWrapper, listResponse, messageWrapper, mutationResponse, paginateWrapper, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, wrapResponse };