@flight-framework/core 0.2.2 → 0.2.3

package/dist/cache/index.d.ts

@@ -2,7 +2,21 @@
  * Flight Cache - Agnostic caching primitives
  *
  * Flight provides the interface, you choose the implementation.
- * Use in-memory, Redis, Cloudflare KV, or anything else.
+ * Use in-memory, Redis, Cloudflare KV, Upstash, or anything else.
+ *
+ * @example
+ * ```typescript
+ * import { createCache } from '@flight-framework/core';
+ * import { redis } from '@flight-framework/cache-redis';
+ *
+ * const cache = createCache({
+ *     adapter: redis({ url: process.env.REDIS_URL }),
+ *     defaultTTL: 3600,
+ * });
+ *
+ * await cache.set('user:1', userData, { tags: ['users'] });
+ * await cache.invalidateTag('users');
+ * ```
  */
 interface CacheOptions {
     /** Time-to-live in seconds */
@@ -37,40 +51,141 @@ interface Cache {
     clear(): Promise<void>;
     /** Invalidate entries by tag */
     invalidateTag(tag: string): Promise<void>;
+    /** Invalidate entries by multiple tags */
+    invalidateTags(tags: string[]): Promise<void>;
     /** Get or set with a factory function */
     getOrSet<T>(key: string, factory: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    /** Get multiple values at once */
+    getMany<T>(keys: string[]): Promise<Map<string, T | undefined>>;
+    /** Set multiple values at once */
+    setMany<T>(entries: Map<string, T>, options?: CacheOptions): Promise<void>;
+    /** Get cache statistics (if tracking enabled) */
+    getStats?(): CacheStats | undefined;
+}
+interface CacheStats {
+    hits: number;
+    misses: number;
+    sets: number;
+    deletes: number;
 }
 /** Adapter interface for external cache providers */
 interface CacheAdapter {
-    name: string;
+    /** Adapter name for identification */
+    readonly name: string;
+    /** Get an entry from cache */
     get<T>(key: string): Promise<CacheEntry<T> | undefined>;
+    /** Set an entry in cache */
     set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
+    /** Delete an entry from cache */
     delete(key: string): Promise<boolean>;
+    /** Check if key exists */
     has(key: string): Promise<boolean>;
+    /** Clear all entries */
     clear(): Promise<void>;
+    /** Get keys matching pattern (optional) */
     keys?(pattern?: string): Promise<string[]>;
+    /** Get multiple entries at once (optional, for performance) */
+    getMany?<T>(keys: string[]): Promise<Map<string, CacheEntry<T> | undefined>>;
+    /** Set multiple entries at once (optional, for performance) */
+    setMany?<T>(entries: Map<string, CacheEntry<T>>): Promise<void>;
+    /** Whether this adapter supports distributed tags natively */
+    readonly supportsDistributedTags?: boolean;
+    /** Add a key to a tag set (for distributed tag management) */
+    addToTag?(tag: string, key: string): Promise<void>;
+    /** Get all keys associated with a tag */
+    getTagMembers?(tag: string): Promise<string[]>;
+    /** Delete a tag and return its members */
+    deleteTag?(tag: string): Promise<string[]>;
+    /** Close connection (for cleanup) */
+    close?(): Promise<void>;
+    /** Check if adapter is healthy */
+    ping?(): Promise<boolean>;
+}
+interface Serializer {
+    serialize(value: unknown): string;
+    deserialize<T>(data: string): T;
 }
+/** Default JSON serializer */
+declare const jsonSerializer: Serializer;
+interface MemoryCacheAdapterOptions {
+    /** Maximum number of entries (0 = unlimited) */
+    maxSize?: number;
+    /** Cleanup interval in ms (default: 60000) */
+    cleanupInterval?: number;
+}
+/**
+ * Create in-memory cache adapter
+ */
+declare function memory(options?: MemoryCacheAdapterOptions): CacheAdapter;
 interface CreateCacheOptions {
     /** Custom cache adapter (defaults to in-memory) */
     adapter?: CacheAdapter;
-    /** Default TTL for all entries */
+    /** Default TTL for all entries (seconds) */
     defaultTTL?: number;
     /** Key prefix for namespacing */
     prefix?: string;
+    /** Custom serializer (for external adapters) */
+    serializer?: Serializer;
+    /** Track cache statistics */
+    trackStats?: boolean;
 }
 /**
  * Create a new cache instance
+ *
+ * @example
+ * ```typescript
+ * // Simple in-memory cache
+ * const cache = createCache();
+ *
+ * // With Redis adapter
+ * import { redis } from '@flight-framework/cache-redis';
+ * const cache = createCache({
+ *     adapter: redis({ url: 'redis://localhost:6379' }),
+ *     defaultTTL: 3600,
+ *     prefix: 'myapp',
+ * });
+ * ```
  */
 declare function createCache(options?: CreateCacheOptions): Cache;
 /**
  * Create a cache key from multiple parts
+ *
+ * @example
+ * ```typescript
+ * cacheKey('user', userId, 'profile'); // "user:123:profile"
+ * ```
  */
 declare function cacheKey(...parts: (string | number | boolean | undefined)[]): string;
 /**
  * Wrap a function with caching
+ *
+ * @example
+ * ```typescript
+ * const getCachedUser = cached(cache, getUser, {
+ *     ttl: 300,
+ *     keyFn: (userId) => `user:${userId}`,
+ * });
+ *
+ * const user = await getCachedUser(123);
+ * ```
  */
 declare function cached<T extends (...args: unknown[]) => Promise<unknown>>(cache: Cache, fn: T, options?: CacheOptions & {
     keyFn?: (...args: Parameters<T>) => string;
 }): T;
+/**
+ * Create a deduplication wrapper to prevent duplicate concurrent requests
+ *
+ * @example
+ * ```typescript
+ * const dedupedFetch = dedupe(fetchUser);
+ *
+ * // These will share the same request
+ * const [user1, user2] = await Promise.all([
+ *     dedupedFetch(123),
+ *     dedupedFetch(123),
+ * ]);
+ * ```
+ */
+declare function dedupe<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, keyFn?: (...args: Parameters<T>) => string): T;
 
-export { type Cache, type CacheAdapter, type CacheEntry, type CacheOptions, type CreateCacheOptions, cacheKey, cached, createCache };
+export { type Cache, type CacheAdapter, type CacheEntry, type CacheOptions, type CacheStats, type CreateCacheOptions, type MemoryCacheAdapterOptions, type Serializer, cacheKey, cached, createCache, dedupe, jsonSerializer, memory };

package/dist/cache/index.js

@@ -1,3 +1,3 @@
-export { cacheKey, cached, createCache } from '../chunk-3AIQVGTM.js';
+export { cacheKey, cached, createCache, dedupe, jsonSerializer, memory } from '../chunk-R7SQAREQ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map