@classytic/arc 1.0.0

package/dist/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export { ac as HookContext, ad as HookHandler, aH as HookOperation, aG as HookPhase, aI as HookRegistration, H as HookSystem, aJ as HookSystemOptions, aB as afterCreate, aF as afterDelete, aD as afterUpdate, aA as beforeCreate, aE as beforeDelete, aC as beforeUpdate, az as createHookSystem, ab as hookSystem } from '../index-DkAW8BXh.js';
+import 'mongoose';
+import 'fastify';
+import '../types-B99TBmFV.js';

package/dist/hooks/index.js

@@ -0,0 +1,199 @@
+// src/hooks/HookSystem.ts
+var HookSystem = class {
+  hooks;
+  logger;
+  constructor(options) {
+    this.hooks = /* @__PURE__ */ new Map();
+    this.logger = options?.logger ?? { error: (...args) => console.error(...args) };
+  }
+  /**
+   * Generate hook key
+   */
+  getKey(resource, operation, phase) {
+    return `${resource}:${operation}:${phase}`;
+  }
+  /**
+   * Register a hook
+   * Supports both object parameter and positional arguments
+   */
+  register(resourceOrOptions, operation, phase, handler, priority = 10) {
+    let resource;
+    let finalOperation;
+    let finalPhase;
+    let finalHandler;
+    let finalPriority;
+    if (typeof resourceOrOptions === "object") {
+      resource = resourceOrOptions.resource;
+      finalOperation = resourceOrOptions.operation;
+      finalPhase = resourceOrOptions.phase;
+      finalHandler = resourceOrOptions.handler;
+      finalPriority = resourceOrOptions.priority ?? 10;
+    } else {
+      resource = resourceOrOptions;
+      finalOperation = operation;
+      finalPhase = phase;
+      finalHandler = handler;
+      finalPriority = priority;
+    }
+    const key = this.getKey(resource, finalOperation, finalPhase);
+    if (!this.hooks.has(key)) {
+      this.hooks.set(key, []);
+    }
+    const registration = {
+      resource,
+      operation: finalOperation,
+      phase: finalPhase,
+      handler: finalHandler,
+      priority: finalPriority
+    };
+    const hooks = this.hooks.get(key);
+    hooks.push(registration);
+    hooks.sort((a, b) => a.priority - b.priority);
+    return () => {
+      const idx = hooks.indexOf(registration);
+      if (idx !== -1) {
+        hooks.splice(idx, 1);
+      }
+    };
+  }
+  /**
+   * Register before hook
+   */
+  before(resource, operation, handler, priority = 10) {
+    return this.register(resource, operation, "before", handler, priority);
+  }
+  /**
+   * Register after hook
+   */
+  after(resource, operation, handler, priority = 10) {
+    return this.register(resource, operation, "after", handler, priority);
+  }
+  /**
+   * Execute hooks for a given context
+   */
+  async execute(ctx) {
+    const key = this.getKey(ctx.resource, ctx.operation, ctx.phase);
+    const hooks = this.hooks.get(key) ?? [];
+    const wildcardKey = this.getKey("*", ctx.operation, ctx.phase);
+    const wildcardHooks = this.hooks.get(wildcardKey) ?? [];
+    const allHooks = [...wildcardHooks, ...hooks];
+    allHooks.sort((a, b) => a.priority - b.priority);
+    let result = ctx.data;
+    for (const hook of allHooks) {
+      const handlerContext = {
+        resource: ctx.resource,
+        operation: ctx.operation,
+        phase: ctx.phase,
+        data: result,
+        result: ctx.result,
+        user: ctx.user,
+        context: ctx.context,
+        meta: ctx.meta
+      };
+      const hookResult = await hook.handler(handlerContext);
+      if (hookResult !== void 0 && hookResult !== null) {
+        result = hookResult;
+      }
+    }
+    return result;
+  }
+  /**
+   * Execute before hooks
+   */
+  async executeBefore(resource, operation, data, options) {
+    const result = await this.execute({
+      resource,
+      operation,
+      phase: "before",
+      data,
+      user: options?.user,
+      context: options?.context,
+      meta: options?.meta
+    });
+    return result ?? data;
+  }
+  /**
+   * Execute after hooks
+   * Errors in after hooks are logged but don't fail the request
+   */
+  async executeAfter(resource, operation, result, options) {
+    try {
+      await this.execute({
+        resource,
+        operation,
+        phase: "after",
+        result,
+        user: options?.user,
+        context: options?.context,
+        meta: options?.meta
+      });
+    } catch (error) {
+      this.logger.error(
+        `[HookSystem] Error in after hook for ${resource}:${operation}:`,
+        error
+      );
+    }
+  }
+  /**
+   * Get all registered hooks
+   */
+  getAll() {
+    const all = [];
+    for (const hooks of this.hooks.values()) {
+      all.push(...hooks);
+    }
+    return all;
+  }
+  /**
+   * Get hooks for a specific resource
+   */
+  getForResource(resource) {
+    const all = [];
+    for (const [key, hooks] of this.hooks.entries()) {
+      if (key.startsWith(`${resource}:`)) {
+        all.push(...hooks);
+      }
+    }
+    return all;
+  }
+  /**
+   * Clear all hooks
+   */
+  clear() {
+    this.hooks.clear();
+  }
+  /**
+   * Clear hooks for a specific resource
+   */
+  clearResource(resource) {
+    for (const key of this.hooks.keys()) {
+      if (key.startsWith(`${resource}:`)) {
+        this.hooks.delete(key);
+      }
+    }
+  }
+};
+function createHookSystem(options) {
+  return new HookSystem(options);
+}
+var hookSystem = new HookSystem();
+function beforeCreate(resource, handler, priority = 10) {
+  return hookSystem.before(resource, "create", handler, priority);
+}
+function afterCreate(resource, handler, priority = 10) {
+  return hookSystem.after(resource, "create", handler, priority);
+}
+function beforeUpdate(resource, handler, priority = 10) {
+  return hookSystem.before(resource, "update", handler, priority);
+}
+function afterUpdate(resource, handler, priority = 10) {
+  return hookSystem.after(resource, "update", handler, priority);
+}
+function beforeDelete(resource, handler, priority = 10) {
+  return hookSystem.before(resource, "delete", handler, priority);
+}
+function afterDelete(resource, handler, priority = 10) {
+  return hookSystem.after(resource, "delete", handler, priority);
+}
+
+export { HookSystem, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, hookSystem };

package/dist/idempotency/index.d.ts

@@ -0,0 +1,323 @@
+import { FastifyPluginAsync } from 'fastify';
+
+/**
+ * Idempotency Store Interface
+ *
+ * Defines the contract for idempotency key storage backends.
+ * Implement this interface for custom stores (Redis, DynamoDB, etc.)
+ */
+interface IdempotencyResult {
+    /** The idempotency key */
+    key: string;
+    /** HTTP status code of the cached response */
+    statusCode: number;
+    /** Response headers to replay */
+    headers: Record<string, string>;
+    /** Response body */
+    body: unknown;
+    /** When this entry was created */
+    createdAt: Date;
+    /** When this entry expires */
+    expiresAt: Date;
+}
+interface IdempotencyLock {
+    /** The idempotency key being locked */
+    key: string;
+    /** Request ID that holds the lock */
+    requestId: string;
+    /** When the lock was acquired */
+    lockedAt: Date;
+    /** When the lock expires (auto-release) */
+    expiresAt: Date;
+}
+interface IdempotencyStore {
+    /** Store name for logging */
+    readonly name: string;
+    /**
+     * Get a cached result for an idempotency key
+     * Returns undefined if not found or expired
+     */
+    get(key: string): Promise<IdempotencyResult | undefined>;
+    /**
+     * Store a result for an idempotency key
+     * TTL is handled by the store implementation
+     */
+    set(key: string, result: Omit<IdempotencyResult, 'key'>): Promise<void>;
+    /**
+     * Try to acquire a lock for processing a key
+     * Returns true if lock acquired, false if already locked
+     * Used to prevent concurrent processing of the same key
+     */
+    tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
+    /**
+     * Release a lock after processing complete
+     */
+    unlock(key: string, requestId: string): Promise<void>;
+    /**
+     * Check if a key is currently locked
+     */
+    isLocked(key: string): Promise<boolean>;
+    /**
+     * Delete a cached result (for manual invalidation)
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Close the store (cleanup connections)
+     */
+    close?(): Promise<void>;
+}
+/**
+ * Helper to create a result object
+ */
+declare function createIdempotencyResult(statusCode: number, body: unknown, headers: Record<string, string>, ttlMs: number): Omit<IdempotencyResult, 'key'>;
+
+/**
+ * Idempotency Plugin
+ *
+ * Duplicate request protection for mutating operations.
+ * Uses idempotency keys to ensure safe retries.
+ *
+ * @example
+ * import { idempotencyPlugin } from '@classytic/arc/idempotency';
+ *
+ * await fastify.register(idempotencyPlugin, {
+ *   enabled: true,
+ *   headerName: 'idempotency-key',
+ *   ttlMs: 86400000, // 24 hours
+ * });
+ *
+ * // Client sends:
+ * // POST /api/orders
+ * // Idempotency-Key: order-123-abc
+ *
+ * // If same key sent again within TTL, returns cached response
+ */
+
+interface IdempotencyPluginOptions {
+    /** Enable idempotency (default: false) */
+    enabled?: boolean;
+    /** Header name for idempotency key (default: 'idempotency-key') */
+    headerName?: string;
+    /** TTL for cached responses in ms (default: 86400000 = 24h) */
+    ttlMs?: number;
+    /** Lock timeout in ms (default: 30000 = 30s) */
+    lockTimeoutMs?: number;
+    /** HTTP methods to apply idempotency to (default: ['POST', 'PUT', 'PATCH']) */
+    methods?: string[];
+    /** URL patterns to include (regex). If set, only matching URLs use idempotency */
+    include?: RegExp[];
+    /** URL patterns to exclude (regex). Excluded patterns take precedence */
+    exclude?: RegExp[];
+    /** Custom store (default: MemoryIdempotencyStore) */
+    store?: IdempotencyStore;
+    /** Retry-After header value in seconds when request is in-flight (default: 1) */
+    retryAfterSeconds?: number;
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        /** The idempotency key for this request (if present) */
+        idempotencyKey?: string;
+        /** Whether this response was replayed from cache */
+        idempotencyReplayed?: boolean;
+    }
+    interface FastifyInstance {
+        /** Idempotency utilities */
+        idempotency: {
+            /** Manually invalidate an idempotency key */
+            invalidate: (key: string) => Promise<void>;
+            /** Check if a key has a cached response */
+            has: (key: string) => Promise<boolean>;
+        };
+    }
+}
+declare const idempotencyPlugin: FastifyPluginAsync<IdempotencyPluginOptions>;
+declare const _default: FastifyPluginAsync<IdempotencyPluginOptions>;
+
+/**
+ * In-Memory Idempotency Store
+ *
+ * Default store for development and small deployments.
+ * NOT suitable for multi-instance deployments - use Redis or similar.
+ *
+ * Features:
+ * - Automatic TTL expiration
+ * - Lock support for concurrent request handling
+ * - Periodic cleanup of expired entries
+ */
+
+interface MemoryIdempotencyStoreOptions {
+    /** Default TTL in milliseconds (default: 86400000 = 24h) */
+    ttlMs?: number;
+    /** Cleanup interval in milliseconds (default: 60000 = 1 min) */
+    cleanupIntervalMs?: number;
+    /** Maximum entries before oldest are evicted (default: 10000) */
+    maxEntries?: number;
+}
+declare class MemoryIdempotencyStore implements IdempotencyStore {
+    readonly name = "memory";
+    private results;
+    private locks;
+    private ttlMs;
+    private maxEntries;
+    private cleanupInterval;
+    constructor(options?: MemoryIdempotencyStoreOptions);
+    get(key: string): Promise<IdempotencyResult | undefined>;
+    set(key: string, result: Omit<IdempotencyResult, 'key'>): Promise<void>;
+    tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
+    unlock(key: string, requestId: string): Promise<void>;
+    isLocked(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Get current stats (for debugging/monitoring)
+     */
+    getStats(): {
+        results: number;
+        locks: number;
+    };
+    /**
+     * Remove expired entries
+     */
+    private cleanup;
+    /**
+     * Evict oldest entries when at capacity
+     */
+    private evictOldest;
+}
+
+/**
+ * Redis Idempotency Store
+ *
+ * Durable idempotency store using Redis.
+ * Suitable for multi-instance deployments.
+ *
+ * @example
+ * import { createClient } from 'redis';
+ * import { RedisIdempotencyStore } from '@classytic/arc/idempotency';
+ *
+ * const redis = createClient({ url: process.env.REDIS_URL });
+ * await redis.connect();
+ *
+ * await fastify.register(idempotencyPlugin, {
+ *   store: new RedisIdempotencyStore({ client: redis }),
+ * });
+ */
+
+interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        EX?: number;
+        NX?: boolean;
+    }): Promise<string | null>;
+    del(key: string | string[]): Promise<number>;
+    exists(key: string | string[]): Promise<number>;
+    quit?(): Promise<string>;
+    disconnect?(): Promise<void>;
+}
+interface RedisIdempotencyStoreOptions {
+    /** Redis client instance */
+    client: RedisClient;
+    /** Key prefix (default: 'idem:') */
+    prefix?: string;
+    /** Lock key prefix (default: 'idem:lock:') */
+    lockPrefix?: string;
+    /** Default TTL in ms (default: 86400000 = 24 hours) */
+    ttlMs?: number;
+}
+declare class RedisIdempotencyStore implements IdempotencyStore {
+    readonly name = "redis";
+    private client;
+    private prefix;
+    private lockPrefix;
+    private ttlMs;
+    constructor(options: RedisIdempotencyStoreOptions);
+    private resultKey;
+    private lockKey;
+    get(key: string): Promise<IdempotencyResult | undefined>;
+    set(key: string, result: Omit<IdempotencyResult, 'key'>): Promise<void>;
+    tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
+    unlock(key: string, requestId: string): Promise<void>;
+    isLocked(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * MongoDB Idempotency Store
+ *
+ * Durable idempotency store using MongoDB.
+ * Suitable for multi-instance deployments.
+ *
+ * @example
+ * import mongoose from 'mongoose';
+ * import { MongoIdempotencyStore } from '@classytic/arc/idempotency';
+ *
+ * await fastify.register(idempotencyPlugin, {
+ *   store: new MongoIdempotencyStore({
+ *     connection: mongoose.connection,
+ *     collection: 'idempotency_keys',
+ *   }),
+ * });
+ */
+
+interface MongoConnection {
+    db: {
+        collection(name: string): MongoCollection;
+    };
+}
+interface MongoCollection {
+    findOne(filter: object): Promise<IdempotencyDocument | null>;
+    insertOne(doc: object): Promise<{
+        acknowledged: boolean;
+    }>;
+    updateOne(filter: object, update: object, options?: object): Promise<{
+        acknowledged: boolean;
+    }>;
+    deleteOne(filter: object): Promise<{
+        deletedCount: number;
+    }>;
+    createIndex(spec: object, options?: object): Promise<string>;
+}
+interface IdempotencyDocument {
+    _id: string;
+    result?: {
+        statusCode: number;
+        headers: Record<string, string>;
+        body: unknown;
+    };
+    lock?: {
+        requestId: string;
+        expiresAt: Date;
+    };
+    createdAt: Date;
+    expiresAt: Date;
+}
+interface MongoIdempotencyStoreOptions {
+    /** Mongoose connection or MongoDB connection object */
+    connection: MongoConnection;
+    /** Collection name (default: 'arc_idempotency') */
+    collection?: string;
+    /** Create TTL index on startup (default: true) */
+    createIndex?: boolean;
+    /** Default TTL in ms (default: 86400000 = 24 hours) */
+    ttlMs?: number;
+}
+declare class MongoIdempotencyStore implements IdempotencyStore {
+    readonly name = "mongodb";
+    private connection;
+    private collectionName;
+    private ttlMs;
+    private indexCreated;
+    constructor(options: MongoIdempotencyStoreOptions);
+    private get collection();
+    private ensureIndex;
+    get(key: string): Promise<IdempotencyResult | undefined>;
+    set(key: string, result: Omit<IdempotencyResult, 'key'>): Promise<void>;
+    tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
+    unlock(key: string, requestId: string): Promise<void>;
+    isLocked(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    close(): Promise<void>;
+}
+
+export { type IdempotencyLock, type IdempotencyPluginOptions, type IdempotencyResult, type IdempotencyStore, MemoryIdempotencyStore, type MemoryIdempotencyStoreOptions, MongoIdempotencyStore, type MongoIdempotencyStoreOptions, type RedisClient, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, createIdempotencyResult, _default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn };