@soederpop/luca 0.1.2 → 0.2.1

package/dist/node/features/disk-cache.d.ts

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+import cacache from "cacache";
+import { Feature, type FeatureState } from "../feature.js";
+export declare const DiskCacheOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    encrypt: z.ZodOptional<z.ZodBoolean>;
+    secret: z.ZodOptional<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DiskCacheOptions = z.infer<typeof DiskCacheOptionsSchema>;
+/**
+ * File-backed key-value cache built on top of the cacache library (the same store
+ * that powers npm). Suitable for persisting arbitrary data including very large
+ * blobs when necessary, with optional encryption support.
+ *
+ * @extends Feature
+ * @example
+ * ```typescript
+ * const diskCache = container.feature('diskCache', { path: '/tmp/cache' })
+ * await diskCache.set('greeting', 'Hello World')
+ * const value = await diskCache.get('greeting')
+ * ```
+ */
+export declare class DiskCache extends Feature<FeatureState, DiskCacheOptions> {
+    static shortcut: "features.diskCache";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        encrypt: z.ZodOptional<z.ZodBoolean>;
+        secret: z.ZodOptional<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    /** Returns the underlying cacache instance configured with the cache directory path. */
+    get cache(): ReturnType<typeof this.create>;
+    /**
+     * Retrieve a file from the disk cache and save it to the local disk
+     * @param key - The cache key to retrieve
+     * @param outputPath - The local path where the file should be saved
+     * @param isBase64 - Whether the cached content is base64 encoded
+     * @returns Promise that resolves to the file data as Buffer
+     * @example
+     * ```typescript
+     * await diskCache.saveFile('myFile', './output/file.txt')
+     * await diskCache.saveFile('encodedImage', './images/photo.jpg', true)
+     * ```
+     */
+    saveFile(key: string, outputPath: string, isBase64?: boolean): Promise<Buffer | string>;
+    /**
+     * Ensure a key exists in the cache, setting it with the provided content if it doesn't exist
+     * @param key - The cache key to check/set
+     * @param content - The content to set if the key doesn't exist
+     * @returns Promise that resolves to the key
+     * @example
+     * ```typescript
+     * await diskCache.ensure('config', JSON.stringify(defaultConfig))
+     * ```
+     */
+    ensure(key: string, content: string): Promise<string>;
+    /**
+     * Copy a cached item from one key to another
+     * @param source - The source cache key
+     * @param destination - The destination cache key
+     * @param overwrite - Whether to overwrite if destination exists (default: false)
+     * @returns Promise that resolves to the destination key
+     * @throws Error if destination exists and overwrite is false
+     * @example
+     * ```typescript
+     * await diskCache.copy('original', 'backup')
+     * await diskCache.copy('file1', 'file2', true) // force overwrite
+     * ```
+     */
+    copy(source: string, destination: string, overwrite?: boolean): Promise<string>;
+    /**
+     * Move a cached item from one key to another (copy then delete source)
+     * @param source - The source cache key
+     * @param destination - The destination cache key
+     * @param overwrite - Whether to overwrite if destination exists (default: false)
+     * @returns Promise that resolves to the destination key
+     * @throws Error if destination exists and overwrite is false
+     * @example
+     * ```typescript
+     * await diskCache.move('temp', 'permanent')
+     * await diskCache.move('old_key', 'new_key', true) // force overwrite
+     * ```
+     */
+    move(source: string, destination: string, overwrite?: boolean): Promise<string>;
+    /**
+     * Check if a key exists in the cache
+     * @param key - The cache key to check
+     * @returns Promise that resolves to true if key exists, false otherwise
+     * @example
+     * ```typescript
+     * if (await diskCache.has('myKey')) {
+     *   console.log('Key exists!')
+     * }
+     * ```
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Retrieve a value from the cache
+     * @param key - The cache key to retrieve
+     * @param json - Whether to parse the value as JSON (default: false)
+     * @returns Promise that resolves to the cached value (string or parsed JSON)
+     * @example
+     * ```typescript
+     * const text = await diskCache.get('myText')
+     * const data = await diskCache.get('myData', true) // parse as JSON
+     * ```
+     */
+    get(key: string, json?: boolean): Promise<any>;
+    /**
+     * Store a value in the cache
+     * @param key - The cache key to store under
+     * @param value - The value to store (string, object, or any serializable data)
+     * @param meta - Optional metadata to associate with the cached item
+     * @returns Promise that resolves when the value is stored
+     * @example
+     * ```typescript
+     * await diskCache.set('myKey', 'Hello World')
+     * await diskCache.set('userData', { name: 'John', age: 30 })
+     * await diskCache.set('file', content, { size: 1024, type: 'image' })
+     * ```
+     */
+    set(key: string, value: any, meta?: any): Promise<any>;
+    /**
+     * Remove a cached item
+     * @param key - The cache key to remove
+     * @returns Promise that resolves when the item is removed
+     * @example
+     * ```typescript
+     * await diskCache.rm('obsoleteKey')
+     * ```
+     */
+    rm(key: string): Promise<any>;
+    /**
+     * Clear all cached items
+     * @param confirm - Must be set to true to confirm the operation
+     * @returns Promise that resolves to this instance for chaining
+     * @throws Error if confirm is not true
+     * @example
+     * ```typescript
+     * await diskCache.clearAll(true) // Must explicitly confirm
+     * ```
+     */
+    clearAll(confirm?: boolean): Promise<this>;
+    /**
+     * Get all cache keys
+     * @returns Promise that resolves to an array of all cache keys
+     * @example
+     * ```typescript
+     * const allKeys = await diskCache.keys()
+     * console.log(`Cache contains ${allKeys.length} items`)
+     * ```
+     */
+    keys(): Promise<string[]>;
+    /**
+     * List all cache keys (alias for keys())
+     * @returns Promise that resolves to an array of all cache keys
+     * @example
+     * ```typescript
+     * const keyList = await diskCache.listKeys()
+     * ```
+     */
+    listKeys(): Promise<string[]>;
+    /**
+     * Get encrypted cache operations interface
+     * Requires encryption to be enabled and a secret to be provided
+     * @returns Object with encrypted get/set operations
+     * @throws Error if encryption is not enabled or no secret is provided
+     * @example
+     * ```typescript
+     * // Initialize with encryption
+     * const cache = container.feature('diskCache', {
+     *   encrypt: true,
+     *   secret: Buffer.from('my-secret-key')
+     * })
+     *
+     * // Use encrypted operations
+     * await cache.securely.set('sensitive', 'secret data')
+     * const decrypted = await cache.securely.get('sensitive')
+     * ```
+     */
+    get securely(): {
+        set(name: string, payload: any, meta?: any): Promise<any>;
+        get(name: string): Promise<any>;
+    };
+    _cache: ReturnType<typeof this.create>;
+    /**
+     * Create a cacache instance with the specified path
+     * @param path - Optional cache directory path (defaults to options.path or ~/.cache/luca/disk-cache-{cwdHash})
+     * @returns Configured cacache instance with all methods bound to the path
+     * @example
+     * ```typescript
+     * const customCache = diskCache.create('/custom/cache/path')
+     * ```
+     */
+    create(path?: string): {
+        cachePath: string;
+        ls: ((...ts: any[]) => any) & {
+            stream: (...ts: any[]) => any;
+        };
+        get: ((...ts: any[]) => any) & {
+            stream: (...ts: any[]) => any;
+            byDigest: (...ts: any[]) => any;
+            copy: (...ts: any[]) => any;
+            info: (...ts: any[]) => any;
+            hasContent: (...ts: any[]) => any;
+        };
+        put: ((...ts: any[]) => any) & {
+            stream: (...ts: any[]) => any;
+        };
+        rm: ((...ts: any[]) => any) & {
+            all: (...ts: any[]) => any;
+            entry: (...ts: any[]) => any;
+            content: (...ts: any[]) => any;
+        };
+        tmp: {
+            mkdir: (...ts: any[]) => any;
+            withTmp: (...ts: any[]) => any;
+        };
+        verify: ((...ts: any[]) => any) & {
+            lastRun: (...ts: any[]) => any;
+        };
+        clearMemoized(): Record<string, cacache.CacheObject>;
+    };
+}
+export default DiskCache;
+//# sourceMappingURL=disk-cache.d.ts.map

package/dist/node/features/disk-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk-cache.d.ts","sourceRoot":"","sources":["../../../src/node/features/disk-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAK3D,eAAO,MAAM,sBAAsB;;;;;;;;iBAOjC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAErE;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAU,SAAQ,OAAO,CAAC,YAAY,EAAC,gBAAgB,CAAC;IACnE,OAAgB,QAAQ,EAAG,oBAAoB,CAAS;IACxD,OAAgB,WAAW;;sBAAqB;IAChD,OAAgB,aAAa;;;;;;;;sBAAyB;IAGtD,wFAAwF;IACxF,IAAI,KAAK,IAAI,UAAU,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,CAU1C;IAED;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;IAQ3F;;;;;;;;;OASG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAU3D;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,GAAE,OAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAU5F;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,GAAE,OAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAW5F;;;;;;;;;;OAUG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxC;;;;;;;;;;OAUG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,UAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAgBlD;;;;;;;;;;;;OAYG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAgB5D;;;;;;;;OAQG;IACG,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAInC;;;;;;;;;OASG;IACG,QAAQ,CAAC,OAAO,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9C;;;;;;;;OAQG;IACG,IAAI,IAAK,OAAO,CAAC,MAAM,EAAE,CAAC;IAIhC;;;;;;;OAOG;IACG,QAAQ,IAAK,OAAO,CAAC,MAAM,EAAE,CAAC;IAIpC;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,QAAQ,IAAI;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAAC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,CA2C7G;IAED,MAAM,EAAG,UAAU,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAA;IAEvC;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CrB;AAED,eAAe,SAAS,CAAC"}