@revealui/core 0.0.1-pre.4 → 0.2.0

package/dist/dataloader.js

@@ -0,0 +1,162 @@
+import DataLoader from 'dataloader';
+import { isValidID } from './utils/isValidID.js';
+const parseCacheKey = (value) => JSON.parse(value);
+const parseBatchKey = (value) => JSON.parse(value);
+// RevealUI uses `dataloader` to solve the classic N+1 problem.
+// We keep a list of all documents requested to be populated for any given request
+// and then batch together documents within the same collection,
+// making only 1 find per each collection, rather than `findByID` per each requested doc.
+// This dramatically improves performance for REST and Local API `depth` populations.
+const batchAndLoadDocs = (req) => async (keys) => {
+    const revealui = req.revealui;
+    if (!revealui) {
+        throw new Error('RevealUI instance not available on request');
+    }
+    // Create docs array of same length as keys, using null as value
+    // We will replace nulls with injected docs as they are retrieved
+    const docs = keys.map(() => null);
+    /**
+    * Batch IDs by their `find` args
+    * so we can make one find query per combination of collection, depth, locale, and fallbackLocale.
+    *
+    * Resulting shape will be as follows:
+      {
+        // key is stringified set of find args
+        '[null,"pages",2,0,"es","en",false,false]': [
+          // value is array of IDs to find with these args
+          'q34tl23462346234524',
+          '435523540194324280',
+          '2346245j35l3j5234532li',
+        ],
+        // etc
+      };
+    *
+    **/
+    const batchByFindArgs = {};
+    for (const key of keys) {
+        const [transactionID, collection, id, depth, currentDepth, locale, fallbackLocale, overrideAccess, showHiddenFields, draft, select, populate,] = parseCacheKey(key);
+        const batchKeyArray = [
+            transactionID,
+            collection,
+            depth,
+            currentDepth,
+            locale,
+            fallbackLocale,
+            overrideAccess,
+            showHiddenFields,
+            draft,
+            select,
+            populate,
+        ];
+        const batchKey = JSON.stringify(batchKeyArray);
+        // RevealUI uses text IDs by default
+        const idType = 'text';
+        const sanitizedID = typeof id === 'string' ? id : String(id);
+        if (isValidID(sanitizedID, idType)) {
+            batchByFindArgs[batchKey] = [...(batchByFindArgs[batchKey] || []), sanitizedID];
+        }
+    }
+    // Run find requests one after another, so as to not hang transactions
+    for (const [batchKey, ids] of Object.entries(batchByFindArgs)) {
+        const [transactionID, collection, depth, currentDepth, locale, fallbackLocale, overrideAccess, showHiddenFields, draft, select, populate,] = parseBatchKey(batchKey);
+        req.transactionID =
+            typeof transactionID === 'number' ? String(transactionID) : (transactionID ?? undefined);
+        const result = await revealui.find({
+            collection,
+            currentDepth,
+            depth,
+            disableErrors: true,
+            draft,
+            fallbackLocale: typeof fallbackLocale === 'string' ? fallbackLocale : undefined,
+            locale: Array.isArray(locale) ? locale[0] : locale,
+            overrideAccess: Boolean(overrideAccess),
+            pagination: false,
+            populate,
+            req,
+            select,
+            showHiddenFields: Boolean(showHiddenFields),
+            where: {
+                id: {
+                    in: ids,
+                },
+            },
+        });
+        // For each returned doc, find index in original keys
+        // Inject doc within docs array if index exists
+        for (const doc of result.docs) {
+            const docKey = createDataloaderCacheKey({
+                collectionSlug: collection,
+                currentDepth,
+                depth,
+                docID: doc.id,
+                draft,
+                fallbackLocale,
+                locale,
+                overrideAccess,
+                populate,
+                select,
+                showHiddenFields,
+                transactionID: req.transactionID ?? undefined,
+            });
+            const docsIndex = keys.indexOf(docKey);
+            if (docsIndex > -1) {
+                docs[docsIndex] = doc;
+            }
+        }
+    }
+    // Return docs array,
+    // which has now been injected with all fetched docs
+    // and should match the length of the incoming keys arg
+    return docs;
+};
+export const getDataLoader = (req) => {
+    const findQueries = new Map();
+    const dataLoader = new DataLoader(batchAndLoadDocs(req));
+    dataLoader.find = (args) => {
+        const key = createFindDataloaderCacheKey(args);
+        const cached = findQueries.get(key);
+        if (cached) {
+            return cached;
+        }
+        if (!req.revealui) {
+            throw new Error('RevealUI instance not available on request');
+        }
+        const request = req.revealui.find(args);
+        findQueries.set(key, request);
+        return request;
+    };
+    return dataLoader;
+};
+const createFindDataloaderCacheKey = ({ collection, currentDepth, depth, disableErrors, draft, includeLockStatus, joins, limit, overrideAccess, page, pagination, populate, req, select, showHiddenFields, sort, where, }) => JSON.stringify([
+    collection,
+    currentDepth,
+    depth,
+    disableErrors,
+    draft,
+    includeLockStatus,
+    joins,
+    limit,
+    overrideAccess,
+    page,
+    pagination,
+    populate,
+    req?.transactionID,
+    select,
+    showHiddenFields,
+    sort,
+    where,
+]);
+export const createDataloaderCacheKey = ({ collectionSlug, currentDepth, depth, docID, draft, fallbackLocale, locale, overrideAccess, populate, select, showHiddenFields, transactionID, }) => JSON.stringify([
+    transactionID,
+    collectionSlug,
+    docID,
+    depth,
+    currentDepth,
+    locale,
+    fallbackLocale,
+    overrideAccess,
+    showHiddenFields,
+    draft,
+    select,
+    populate,
+]);

package/dist/error-handling/circuit-breaker.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Circuit Breaker Pattern
+ *
+ * Prevents cascading failures by stopping requests to failing services
+ */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerConfig {
+    failureThreshold?: number;
+    successThreshold?: number;
+    timeout?: number;
+    resetTimeout?: number;
+    volumeThreshold?: number;
+    errorFilter?: (error: Error) => boolean;
+    onStateChange?: (state: CircuitState) => void;
+    onTrip?: () => void;
+    onReset?: () => void;
+}
+export interface CircuitBreakerStats {
+    [key: string]: unknown;
+    state: CircuitState;
+    failures: number;
+    successes: number;
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+    totalCalls: number;
+    totalFailures: number;
+    totalSuccesses: number;
+    lastFailureTime?: number;
+    lastSuccessTime?: number;
+    stateChangedAt: number;
+}
+/**
+ * Circuit Breaker implementation
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private consecutiveFailures;
+    private consecutiveSuccesses;
+    private totalCalls;
+    private totalFailures;
+    private totalSuccesses;
+    private lastFailureTime?;
+    private lastSuccessTime?;
+    private stateChangedAt;
+    private resetTimer?;
+    private config;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Execute function with circuit breaker
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Handle successful execution
+     */
+    private onSuccess;
+    /**
+     * Handle failed execution
+     */
+    private onFailure;
+    /**
+     * Transition to new state
+     */
+    private transitionTo;
+    /**
+     * Get current state
+     */
+    getState(): CircuitState;
+    /**
+     * Get statistics
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Manually open circuit
+     */
+    trip(): void;
+    /**
+     * Manually close circuit
+     */
+    reset(): void;
+    /**
+     * Force state to half-open
+     */
+    halfOpen(): void;
+    /**
+     * Check if circuit is open
+     */
+    isOpen(): boolean;
+    /**
+     * Check if circuit is closed
+     */
+    isClosed(): boolean;
+    /**
+     * Check if circuit is half-open
+     */
+    isHalfOpen(): boolean;
+    /**
+     * Get failure rate
+     */
+    getFailureRate(): number;
+    /**
+     * Get success rate
+     */
+    getSuccessRate(): number;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Circuit breaker open error
+ */
+export declare class CircuitBreakerOpenError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Circuit breaker registry
+ */
+export declare class CircuitBreakerRegistry {
+    private breakers;
+    /**
+     * Get or create circuit breaker
+     */
+    get(name: string, config?: CircuitBreakerConfig): CircuitBreaker;
+    /**
+     * Check if breaker exists
+     */
+    has(name: string): boolean;
+    /**
+     * Remove circuit breaker
+     */
+    remove(name: string): boolean;
+    /**
+     * Get all breakers
+     */
+    getAll(): Map<string, CircuitBreaker>;
+    /**
+     * Get all statistics
+     */
+    getAllStats(): Record<string, CircuitBreakerStats>;
+    /**
+     * Reset all breakers
+     */
+    resetAll(): void;
+    /**
+     * Clear all breakers
+     */
+    clear(): void;
+}
+/**
+ * Global circuit breaker registry
+ */
+export declare const circuitBreakerRegistry: CircuitBreakerRegistry;
+/**
+ * Create circuit breaker decorator
+ */
+export declare function CircuitBreak(nameOrConfig?: string | CircuitBreakerConfig): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Execute with circuit breaker
+ */
+export declare function withCircuitBreaker<T>(name: string, fn: () => Promise<T>, config?: CircuitBreakerConfig): Promise<T>;
+/**
+ * Create circuit breaker middleware
+ */
+export declare function createCircuitBreakerMiddleware<TRequest = unknown, TResponse = unknown>(name: string, config?: CircuitBreakerConfig): (_request: TRequest, next: () => Promise<TResponse>) => Promise<TResponse>;
+/**
+ * Circuit breaker for fetch
+ */
+export declare function fetchWithCircuitBreaker(name: string, url: string, init?: RequestInit, config?: CircuitBreakerConfig): Promise<Response>;
+/**
+ * Adaptive circuit breaker with dynamic thresholds
+ */
+export declare class AdaptiveCircuitBreaker extends CircuitBreaker {
+    private errorRateWindow;
+    private windowSize;
+    private adaptiveThreshold;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Execute with adaptive thresholds
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Record success in window
+     */
+    private recordSuccess;
+    /**
+     * Record failure in window
+     */
+    private recordFailure;
+    /**
+     * Trim window to size
+     */
+    private trimWindow;
+    /**
+     * Adjust threshold based on error rate
+     */
+    private adjustThreshold;
+    /**
+     * Get error rate in window
+     */
+    private getWindowErrorRate;
+    /**
+     * Get adaptive threshold
+     */
+    getAdaptiveThreshold(): number;
+}
+/**
+ * Bulkhead pattern - limit concurrent executions
+ */
+export declare class Bulkhead {
+    private activeRequests;
+    private queue;
+    private maxConcurrent;
+    private maxQueue;
+    constructor(maxConcurrent?: number, maxQueue?: number);
+    /**
+     * Execute with bulkhead
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get active requests
+     */
+    getActiveRequests(): number;
+    /**
+     * Get queue size
+     */
+    getQueueSize(): number;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        activeRequests: number;
+        queueSize: number;
+        maxConcurrent: number;
+        maxQueue: number;
+    };
+}
+/**
+ * Combined resilience wrapper
+ */
+export declare class ResilientOperation<T> {
+    private fn;
+    private circuitBreaker?;
+    private bulkhead?;
+    constructor(fn: () => Promise<T>, circuitBreaker?: CircuitBreaker | undefined, bulkhead?: Bulkhead | undefined);
+    /**
+     * Execute with all resilience patterns
+     */
+    execute(): Promise<T>;
+}
+/**
+ * Create resilient function
+ */
+export declare function createResilientFunction<T>(fn: () => Promise<T>, options?: {
+    circuitBreaker?: CircuitBreakerConfig;
+    bulkhead?: {
+        maxConcurrent: number;
+        maxQueue: number;
+    };
+}): () => Promise<T>;
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/error-handling/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/error-handling/circuit-breaker.ts"],"names":[],"mappings":"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"}