@classytic/arc 1.1.0 → 2.1.3

package/dist/interface-CSNjltAc.d.mts

@@ -0,0 +1,77 @@
+//#region src/idempotency/stores/interface.d.ts
+/**
+ * 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.
+   */
+  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 by exact key */
+  delete(key: string): Promise<void>;
+  /**
+   * Delete all cached results whose key starts with the given prefix.
+   * Used by invalidate() to clear entries by raw idempotency key
+   * regardless of fingerprint.
+   * Returns the number of entries deleted.
+   */
+  deleteByPrefix(prefix: string): Promise<number>;
+  /**
+   * Find the first cached result whose key starts with the given prefix.
+   * Used by has() to check if any entry exists for a raw idempotency key.
+   * Returns undefined if no matching entry found.
+   */
+  findByPrefix(prefix: string): Promise<IdempotencyResult | undefined>;
+  /** 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'>;
+//#endregion
+export { createIdempotencyResult as i, IdempotencyResult as n, IdempotencyStore as r, IdempotencyLock as t };

package/dist/interface-DTbsvIWe.d.mts

@@ -0,0 +1,54 @@
+//#region src/cache/interface.d.ts
+/**
+ * Generic Cache Store Interface
+ *
+ * Shared contract for reusable cache backends (memory, Redis, etc.).
+ * Used by runtime systems such as dynamic permission matrices and QueryCache.
+ */
+interface CacheLogger {
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+interface CacheSetOptions {
+  /** Time-to-live in milliseconds */
+  ttlMs?: number;
+}
+interface CacheStats {
+  /** Number of entries currently stored */
+  entries: number;
+  /** Estimated memory usage in bytes (-1 if unavailable) */
+  memoryBytes: number;
+  /** Cache hit count since creation */
+  hits: number;
+  /** Cache miss count since creation */
+  misses: number;
+  /** Number of entries evicted since creation */
+  evictions: number;
+}
+interface CacheStore<TValue = unknown> {
+  /** Store name for logs/diagnostics */
+  readonly name: string;
+  /**
+   * Get cached value by key.
+   * Returns undefined when missing or expired.
+   */
+  get(key: string): Promise<TValue | undefined>;
+  /**
+   * Set a cache value.
+   * Store implementation handles TTL and eviction policy.
+   */
+  set(key: string, value: TValue, options?: CacheSetOptions): Promise<void>;
+  /**
+   * Delete a single cache key.
+   */
+  delete(key: string): Promise<void>;
+  /**
+   * Clear all keys in this store namespace.
+   * Optional because distributed stores may not support cheap global clear.
+   */
+  clear?(): Promise<void>;
+  /** Cache statistics for observability. */
+  stats?(): CacheStats;
+}
+//#endregion
+export { CacheStore as i, CacheSetOptions as n, CacheStats as r, CacheLogger as t };