@classytic/arc 1.0.0

package/dist/utils/index.d.ts

@@ -0,0 +1,655 @@
+export { A as ArcError, C as ConflictError, E as ErrorDetails, F as ForbiddenError, N as NotFoundError, a as OrgAccessDeniedError, O as OrgRequiredError, R as RateLimitError, S as ServiceUnavailableError, U as UnauthorizedError, V as ValidationError, c as createError, i as isArcError } from '../errors-8WIxGS_6.js';
+import { d as AnyRecord, h as QueryParserInterface, ae as ParsedQuery } from '../index-DkAW8BXh.js';
+import 'mongoose';
+import 'fastify';
+import '../types-B99TBmFV.js';
+
+/**
+ * Response Schemas
+ *
+ * Standard JSON Schema definitions for API responses.
+ */
+
+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
+ */
+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
+ */
+declare function listResponse(itemSchema: JsonSchema): JsonSchema;
+/**
+ * Create a single item response schema
+ */
+declare function itemResponse(itemSchema: JsonSchema): JsonSchema;
+/**
+ * Create a create/update response schema
+ */
+declare function mutationResponse(itemSchema: JsonSchema): JsonSchema;
+/**
+ * Create a delete response schema
+ */
+declare function deleteResponse(): JsonSchema;
+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: {
+            type: string;
+            description: string;
+            example: string;
+        };
+        populate: {
+            type: string;
+            description: string;
+            example: string;
+        };
+    };
+};
+/**
+ * Get standard list query parameters schema
+ */
+declare function getListQueryParams(): AnyRecord;
+
+/**
+ * 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 {
+    /**
+     * Check if action can be performed from current status
+     */
+    can(action: string, status: string | null | undefined, context?: any): 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;
+
+/**
+ * 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 enum CircuitState {
+    CLOSED = "CLOSED",
+    OPEN = "OPEN",
+    HALF_OPEN = "HALF_OPEN"
+}
+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 readonly fn;
+    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;
+    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;
+}
+/**
+ * Global circuit breaker registry
+ */
+declare const circuitBreakerRegistry: CircuitBreakerRegistry;
+
+/**
+ * Arc Query Parser - Default URL-to-Query Parser
+ *
+ * Framework-agnostic query parser that converts URL parameters to query options.
+ * This is Arc's built-in parser; users can swap in MongoKit's QueryParser,
+ * pgkit's parser, or any custom parser implementing QueryParserInterface.
+ *
+ * @example
+ * // Use Arc default parser (auto-applied if no queryParser option)
+ * defineResource({ name: 'product', adapter: ... });
+ *
+ * // Use MongoKit's QueryParser (recommended for MongoDB - has $lookup, aggregations, etc.)
+ * import { QueryParser } from '@classytic/mongokit';
+ * defineResource({
+ *   name: 'product',
+ *   adapter: ...,
+ *   queryParser: new QueryParser(),
+ * });
+ *
+ * // Use custom parser for SQL databases
+ * defineResource({
+ *   name: 'user',
+ *   adapter: ...,
+ *   queryParser: new PgQueryParser(),
+ * });
+ */
+
+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;
+    private parseSort;
+    private parseSearch;
+    private parseSelect;
+    private parseFilters;
+    private parseFilterValue;
+    private coerceValue;
+    private sanitizeRegex;
+}
+/**
+ * Create a new ArcQueryParser instance
+ */
+declare function createQueryParser(options?: ArcQueryParserOptions): ArcQueryParser;
+
+export { ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type JsonSchema, type StateMachine, type TransitionConfig, circuitBreakerRegistry, createCircuitBreaker, createQueryParser, createStateMachine, deleteResponse, errorResponseSchema, getListQueryParams, itemResponse, listResponse, mutationResponse, paginationSchema, queryParams, responses, successResponseSchema, wrapResponse };