@commandkit/cache 0.0.0-dev.20250512141518

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2025 Avraj Sahota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# `@commandkit/cache`
+
+CommandKit plugin for cache management.
+
+## Installation
+
+```bash
+npm install @commandkit/cache
+```
+
+## Usage
+
+To use the `@commandkit/cache` plugin, you need to add it to your CommandKit application. This can be done by importing the plugin and adding it to your configuration.
+
+```ts
+import { cache } from '@commandkit/cache';
+
+export default defineConfig({
+  plugins: [
+    cache(),
+  ],
+})
+```
+
+Next, you can define advanced configurations for the plugin if needed. For example, you can set a custom cache provider:
+
+```ts
+import { setCacheProvider } from '@commandkit/cache';
+import { RedisCache } from '@commandkit/redis';
+
+setCacheProvider(new RedisCache({...}));
+```
+
+Then, you can add `"use cache"` directive to the function you want to cache. For example:
+
+```ts
+import { cacheTag, cacheLife } from '@commandkit/cache';
+
+async function fetchDogs() {
+  "use cache";
+
+  cacheTag('dogs');
+  cacheLife('1h');
+
+  const dogs = await fetch('https://example.com/dogs');
+  return dogs.json();
+}
+```
+
+Now the `fetchDogs` function will be cached for 1 hour. You can perform on-demand cache invalidation or revalidation using the `invalidate` and `revalidate` methods:
+
+```ts
+import { invalidate, revalidate } from '@commandkit/cache';
+
+async function refreshCache() {
+  // invalidate the cache for the "dogs" tag. This will remove the cached data.
+  // calling the function again will fetch fresh data.
+  await invalidate('dogs');
+
+  // revalidate the cache for the "dogs" tag. This will fetch fresh data and update the cache.
+  await revalidate('dogs');
+}
+```

package/dist/cache-plugin.d.ts

@@ -0,0 +1,9 @@
+import { RuntimePlugin } from 'commandkit';
+import type { CacheProvider } from './cache-provider';
+export declare function setCacheProvider(provider: CacheProvider): void;
+export declare function getCacheProvider(): CacheProvider;
+export declare class CachePlugin extends RuntimePlugin {
+    name: string;
+    activate(): Promise<void>;
+    deactivate(): Promise<void>;
+}

package/dist/cache-plugin.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachePlugin = void 0;
+exports.setCacheProvider = setCacheProvider;
+exports.getCacheProvider = getCacheProvider;
+const commandkit_1 = require("commandkit");
+const memory_cache_1 = require("./memory-cache");
+let cacheProvider = null;
+function setCacheProvider(provider) {
+    cacheProvider = provider;
+}
+function getCacheProvider() {
+    if (!cacheProvider) {
+        throw new Error('Cache provider is not set. Please set a cache provider.');
+    }
+    return cacheProvider;
+}
+class CachePlugin extends commandkit_1.RuntimePlugin {
+    constructor() {
+        super(...arguments);
+        this.name = 'CommandKitCachePlugin';
+    }
+    async activate() {
+        if (!cacheProvider) {
+            cacheProvider = new memory_cache_1.MemoryCache();
+        }
+        commandkit_1.Logger.info('CommandKit CachePlugin has been activated!');
+    }
+    async deactivate() {
+        cacheProvider = null;
+    }
+}
+exports.CachePlugin = CachePlugin;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2FjaGUtcGx1Z2luLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2NhY2hlLXBsdWdpbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFNQSw0Q0FFQztBQUVELDRDQU1DO0FBaEJELDJDQUFtRDtBQUVuRCxpREFBNkM7QUFFN0MsSUFBSSxhQUFhLEdBQXlCLElBQUksQ0FBQztBQUUvQyxTQUFnQixnQkFBZ0IsQ0FBQyxRQUF1QjtJQUN0RCxhQUFhLEdBQUcsUUFBUSxDQUFDO0FBQzNCLENBQUM7QUFFRCxTQUFnQixnQkFBZ0I7SUFDOUIsSUFBSSxDQUFDLGFBQWEsRUFBRSxDQUFDO1FBQ25CLE1BQU0sSUFBSSxLQUFLLENBQUMseURBQXlELENBQUMsQ0FBQztJQUM3RSxDQUFDO0lBRUQsT0FBTyxhQUFhLENBQUM7QUFDdkIsQ0FBQztBQUVELE1BQWEsV0FBWSxTQUFRLDBCQUFhO0lBQTlDOztRQUNTLFNBQUksR0FBRyx1QkFBdUIsQ0FBQztJQWF4QyxDQUFDO0lBWFEsS0FBSyxDQUFDLFFBQVE7UUFDbkIsSUFBSSxDQUFDLGFBQWEsRUFBRSxDQUFDO1lBQ25CLGFBQWEsR0FBRyxJQUFJLDBCQUFXLEVBQUUsQ0FBQztRQUNwQyxDQUFDO1FBRUQsbUJBQU0sQ0FBQyxJQUFJLENBQUMsNENBQTRDLENBQUMsQ0FBQztJQUM1RCxDQUFDO0lBRU0sS0FBSyxDQUFDLFVBQVU7UUFDckIsYUFBYSxHQUFHLElBQUksQ0FBQztJQUN2QixDQUFDO0NBQ0Y7QUFkRCxrQ0FjQyJ9

package/dist/cache-provider.d.ts

@@ -0,0 +1,12 @@
+export interface CacheEntry<T = unknown> {
+    value: T;
+    ttl?: number;
+}
+export declare abstract class CacheProvider {
+    abstract get<T>(key: string): Promise<CacheEntry<T> | undefined>;
+    abstract set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    abstract exists(key: string): Promise<boolean>;
+    abstract delete(key: string): Promise<void>;
+    abstract clear(): Promise<void>;
+    abstract expire(key: string, ttl: number): Promise<void>;
+}

package/dist/cache-provider.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheProvider = void 0;
+class CacheProvider {
+}
+exports.CacheProvider = CacheProvider;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2FjaGUtcHJvdmlkZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY2FjaGUtcHJvdmlkZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBS0EsTUFBc0IsYUFBYTtDQU9sQztBQVBELHNDQU9DIn0=

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { CommonDirectiveTransformerOptions, CommandKitPlugin } from 'commandkit';
+export * from './cache-provider';
+export * from './memory-cache';
+export * from './use-cache';
+export * from './use-cache-directive';
+export * from './cache-plugin';
+/**
+ * The cache plugin for CommandKit.
+ * @param options The options for the cache plugin.
+ * @returns The cache plugin for CommandKit.
+ */
+export declare function cache(options?: Partial<{
+    compiler: CommonDirectiveTransformerOptions;
+    runtime: Record<never, never>;
+}>): CommandKitPlugin[];

package/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cache = cache;
+const use_cache_directive_1 = require("./use-cache-directive");
+const cache_plugin_1 = require("./cache-plugin");
+__exportStar(require("./cache-provider"), exports);
+__exportStar(require("./memory-cache"), exports);
+__exportStar(require("./use-cache"), exports);
+__exportStar(require("./use-cache-directive"), exports);
+__exportStar(require("./cache-plugin"), exports);
+/**
+ * The cache plugin for CommandKit.
+ * @param options The options for the cache plugin.
+ * @returns The cache plugin for CommandKit.
+ */
+function cache(options) {
+    const compiler = new use_cache_directive_1.UseCacheDirectivePlugin(options?.compiler);
+    const runtime = new cache_plugin_1.CachePlugin(options?.runtime ?? {});
+    return [compiler, runtime];
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQWtCQSxzQkFVQztBQXhCRCwrREFBZ0U7QUFDaEUsaURBQTZDO0FBRTdDLG1EQUFpQztBQUNqQyxpREFBK0I7QUFDL0IsOENBQTRCO0FBQzVCLHdEQUFzQztBQUN0QyxpREFBK0I7QUFFL0I7Ozs7R0FJRztBQUNILFNBQWdCLEtBQUssQ0FDbkIsT0FHRTtJQUVGLE1BQU0sUUFBUSxHQUFHLElBQUksNkNBQXVCLENBQUMsT0FBTyxFQUFFLFFBQVEsQ0FBQyxDQUFDO0lBQ2hFLE1BQU0sT0FBTyxHQUFHLElBQUksMEJBQVcsQ0FBQyxPQUFPLEVBQUUsT0FBTyxJQUFJLEVBQUUsQ0FBQyxDQUFDO0lBRXhELE9BQU8sQ0FBQyxRQUFRLEVBQUUsT0FBTyxDQUFDLENBQUM7QUFDN0IsQ0FBQyJ9

package/dist/memory-cache.d.ts

@@ -0,0 +1,10 @@
+import { CacheEntry, CacheProvider } from './cache-provider';
+export declare class MemoryCache extends CacheProvider {
+    #private;
+    get<T>(key: string): Promise<CacheEntry<T> | undefined>;
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    expire(key: string, ttl: number): Promise<void>;
+}

package/dist/memory-cache.js

@@ -0,0 +1,58 @@
+"use strict";
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _MemoryCache_cache;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCache = void 0;
+const cache_provider_1 = require("./cache-provider");
+class MemoryCache extends cache_provider_1.CacheProvider {
+    constructor() {
+        super(...arguments);
+        _MemoryCache_cache.set(this, new Map());
+    }
+    async get(key) {
+        const entry = __classPrivateFieldGet(this, _MemoryCache_cache, "f").get(key);
+        if (!entry) {
+            return undefined;
+        }
+        if (entry.ttl && Date.now() > entry.ttl) {
+            __classPrivateFieldGet(this, _MemoryCache_cache, "f").delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+    async set(key, value, ttl) {
+        const entry = {
+            value,
+            ttl: ttl != null ? Date.now() + ttl : undefined,
+        };
+        __classPrivateFieldGet(this, _MemoryCache_cache, "f").set(key, entry);
+    }
+    async exists(key) {
+        return __classPrivateFieldGet(this, _MemoryCache_cache, "f").has(key);
+    }
+    async delete(key) {
+        __classPrivateFieldGet(this, _MemoryCache_cache, "f").delete(key);
+    }
+    async clear() {
+        __classPrivateFieldGet(this, _MemoryCache_cache, "f").clear();
+    }
+    async expire(key, ttl) {
+        const entry = __classPrivateFieldGet(this, _MemoryCache_cache, "f").get(key);
+        if (!entry)
+            return;
+        const _ttl = Date.now() + ttl;
+        // delete if _ttl is in the past
+        if (_ttl < Date.now()) {
+            __classPrivateFieldGet(this, _MemoryCache_cache, "f").delete(key);
+            return;
+        }
+        entry.ttl = _ttl;
+    }
+}
+exports.MemoryCache = MemoryCache;
+_MemoryCache_cache = new WeakMap();
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWVtb3J5LWNhY2hlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL21lbW9yeS1jYWNoZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7QUFBQSxxREFBNkQ7QUFFN0QsTUFBYSxXQUFZLFNBQVEsOEJBQWE7SUFBOUM7O1FBQ0UsNkJBQVMsSUFBSSxHQUFHLEVBQXNCLEVBQUM7SUFxRHpDLENBQUM7SUFuRFEsS0FBSyxDQUFDLEdBQUcsQ0FBSSxHQUFXO1FBQzdCLE1BQU0sS0FBSyxHQUFHLHVCQUFBLElBQUksMEJBQU8sQ0FBQyxHQUFHLENBQUMsR0FBRyxDQUFDLENBQUM7UUFFbkMsSUFBSSxDQUFDLEtBQUssRUFBRSxDQUFDO1lBQ1gsT0FBTyxTQUFTLENBQUM7UUFDbkIsQ0FBQztRQUVELElBQUksS0FBSyxDQUFDLEdBQUcsSUFBSSxJQUFJLENBQUMsR0FBRyxFQUFFLEdBQUcsS0FBSyxDQUFDLEdBQUcsRUFBRSxDQUFDO1lBQ3hDLHVCQUFBLElBQUksMEJBQU8sQ0FBQyxNQUFNLENBQUMsR0FBRyxDQUFDLENBQUM7WUFDeEIsT0FBTyxTQUFTLENBQUM7UUFDbkIsQ0FBQztRQUVELE9BQU8sS0FBc0IsQ0FBQztJQUNoQyxDQUFDO0lBRU0sS0FBSyxDQUFDLEdBQUcsQ0FBSSxHQUFXLEVBQUUsS0FBUSxFQUFFLEdBQVk7UUFDckQsTUFBTSxLQUFLLEdBQWtCO1lBQzNCLEtBQUs7WUFDTCxHQUFHLEVBQUUsR0FBRyxJQUFJLElBQUksQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxHQUFHLEdBQUcsQ0FBQyxDQUFDLENBQUMsU0FBUztTQUNoRCxDQUFDO1FBRUYsdUJBQUEsSUFBSSwwQkFBTyxDQUFDLEdBQUcsQ0FBQyxHQUFHLEVBQUUsS0FBSyxDQUFDLENBQUM7SUFDOUIsQ0FBQztJQUVNLEtBQUssQ0FBQyxNQUFNLENBQUMsR0FBVztRQUM3QixPQUFPLHVCQUFBLElBQUksMEJBQU8sQ0FBQyxHQUFHLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDOUIsQ0FBQztJQUVNLEtBQUssQ0FBQyxNQUFNLENBQUMsR0FBVztRQUM3Qix1QkFBQSxJQUFJLDBCQUFPLENBQUMsTUFBTSxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBQzFCLENBQUM7SUFFTSxLQUFLLENBQUMsS0FBSztRQUNoQix1QkFBQSxJQUFJLDBCQUFPLENBQUMsS0FBSyxFQUFFLENBQUM7SUFDdEIsQ0FBQztJQUVNLEtBQUssQ0FBQyxNQUFNLENBQUMsR0FBVyxFQUFFLEdBQVc7UUFDMUMsTUFBTSxLQUFLLEdBQUcsdUJBQUEsSUFBSSwwQkFBTyxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsQ0FBQztRQUVuQyxJQUFJLENBQUMsS0FBSztZQUFFLE9BQU87UUFFbkIsTUFBTSxJQUFJLEdBQUcsSUFBSSxDQUFDLEdBQUcsRUFBRSxHQUFHLEdBQUcsQ0FBQztRQUU5QixnQ0FBZ0M7UUFDaEMsSUFBSSxJQUFJLEdBQUcsSUFBSSxDQUFDLEdBQUcsRUFBRSxFQUFFLENBQUM7WUFDdEIsdUJBQUEsSUFBSSwwQkFBTyxDQUFDLE1BQU0sQ0FBQyxHQUFHLENBQUMsQ0FBQztZQUN4QixPQUFPO1FBQ1QsQ0FBQztRQUVELEtBQUssQ0FBQyxHQUFHLEdBQUcsSUFBSSxDQUFDO0lBQ25CLENBQUM7Q0FDRjtBQXRERCxrQ0FzREMifQ==

package/dist/use-cache-directive.d.ts

@@ -0,0 +1,6 @@
+import { CommonDirectiveTransformer, CommonDirectiveTransformerOptions, CompilerPluginRuntime } from 'commandkit';
+export declare class UseCacheDirectivePlugin extends CommonDirectiveTransformer {
+    readonly name = "UseCacheDirectivePlugin";
+    constructor(options?: Partial<CommonDirectiveTransformerOptions>);
+    activate(ctx: CompilerPluginRuntime): Promise<void>;
+}

package/dist/use-cache-directive.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UseCacheDirectivePlugin = void 0;
+const commandkit_1 = require("commandkit");
+class UseCacheDirectivePlugin extends commandkit_1.CommonDirectiveTransformer {
+    constructor(options) {
+        super({
+            enabled: true,
+            ...options,
+            directive: 'use cache',
+            importPath: '@commandkit/cache',
+            importName: '__SECRET_USE_CACHE_INTERNAL_DO_NOT_USE_OR_YOU_WILL_BE_FIRED',
+            asyncOnly: true,
+        });
+        this.name = 'UseCacheDirectivePlugin';
+    }
+    async activate(ctx) {
+        super.activate(ctx);
+        commandkit_1.Logger.info('"use cache" directive compiler plugin activated');
+    }
+}
+exports.UseCacheDirectivePlugin = UseCacheDirectivePlugin;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXNlLWNhY2hlLWRpcmVjdGl2ZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy91c2UtY2FjaGUtZGlyZWN0aXZlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUFBLDJDQUtvQjtBQUVwQixNQUFhLHVCQUF3QixTQUFRLHVDQUEwQjtJQUdyRSxZQUFtQixPQUFvRDtRQUNyRSxLQUFLLENBQUM7WUFDSixPQUFPLEVBQUUsSUFBSTtZQUNiLEdBQUcsT0FBTztZQUNWLFNBQVMsRUFBRSxXQUFXO1lBQ3RCLFVBQVUsRUFBRSxtQkFBbUI7WUFDL0IsVUFBVSxFQUFFLDZEQUE2RDtZQUN6RSxTQUFTLEVBQUUsSUFBSTtTQUNoQixDQUFDLENBQUM7UUFWVyxTQUFJLEdBQUcseUJBQXlCLENBQUM7SUFXakQsQ0FBQztJQUVNLEtBQUssQ0FBQyxRQUFRLENBQUMsR0FBMEI7UUFDOUMsS0FBSyxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQUMsQ0FBQztRQUNwQixtQkFBTSxDQUFDLElBQUksQ0FBQyxpREFBaUQsQ0FBQyxDQUFDO0lBQ2pFLENBQUM7Q0FDRjtBQWxCRCwwREFrQkMifQ==

package/dist/use-cache.d.ts

@@ -0,0 +1,104 @@
+import { AsyncFunction, GenericFunction } from 'commandkit';
+/**
+ * Context for managing cache operations within an async scope
+ */
+export interface CacheContext {
+    params: {
+        /** Custom name for the cache entry */
+        name?: string;
+        /** Time-to-live in milliseconds */
+        ttl?: number;
+    };
+}
+/**
+ * Configuration options for cache behavior
+ */
+export interface CacheMetadata {
+    /** Time-to-live duration in milliseconds or as a string (e.g., '1h', '5m') */
+    ttl?: number | string;
+    /** Custom name for the cache entry */
+    name?: string;
+}
+/**
+ * Wraps an async function with caching capability
+ * @template R - Array of argument types
+ * @template F - Type of the async function
+ * @param fn - The async function to cache
+ * @param params - Optional cache configuration
+ * @returns The wrapped function with caching behavior
+ * @example
+ * ```ts
+ * const cachedFetch = cache(async (id: string) => {
+ *   return await db.findOne(id);
+ * }, { ttl: '1h' });
+ * ```
+ */
+export declare function cache<R extends any[], F extends AsyncFunction<R>>(fn: F, params?: CacheMetadata): F;
+/**
+ * Sets a custom identifier for the current cache operation
+ * @param tag - The custom cache tag
+ * @throws {Error} When called outside a cached function or without a tag
+ * @example
+ * ```ts
+ * const fetchUser = cache(async (id: string) => {
+ *   cacheTag(`user:${id}`);
+ *   return await db.users.findOne(id);
+ * });
+ * ```
+ */
+export declare function cacheTag(tag: string): void;
+/**
+ * Sets the TTL for the current cache operation
+ * @param ttl - Time-to-live in milliseconds or as a string (e.g., '1h', '5m')
+ * @throws {Error} When called outside a cached function or with invalid TTL
+ * @example
+ * ```ts
+ * const fetchData = cache(async () => {
+ *   cacheLife('30m');
+ *   return await expensiveOperation();
+ * });
+ * ```
+ */
+export declare function cacheLife(ttl: number | string): void;
+/**
+ * Removes a cached value by its tag
+ * @param tag - The cache tag to invalidate. Can be a single tag or an array of tags.
+ * @throws {Error} When the cache key is not found
+ * @example
+ * ```ts
+ * await invalidate('user:123');
+ * // or
+ * await invalidate(['user:123', 'user:456']);
+ * ```
+ */
+export declare function invalidate(tag: string | string[]): Promise<void>;
+/**
+ * Forces a refresh of cached data by its tag (on-demand revalidation)
+ * @template T - Type of the cached value
+ * @param tag - The cache tag to revalidate
+ * @param args - Arguments to pass to the cached function
+ * @returns Fresh data from the cached function
+ * @throws {Error} When the cache key or function is not found
+ * @example
+ * ```ts
+ * const freshData = await revalidate('user:123');
+ * ```
+ */
+export declare function revalidate<T = unknown>(tag: string, ...args: any[]): Promise<T>;
+/**
+ * Checks if a function is wrapped with cache functionality
+ * @param fn - Function to check
+ * @returns True if the function is cached
+ * @example
+ * ```ts
+ * if (isCachedFunction(myFunction)) {
+ *   console.log('Function is cached');
+ * }
+ * ```
+ */
+export declare function isCachedFunction(fn: GenericFunction): boolean;
+/**
+ * @private
+ * @internal
+ */
+export declare const __SECRET_USE_CACHE_INTERNAL_DO_NOT_USE_OR_YOU_WILL_BE_FIRED: any;

package/dist/use-cache.js

@@ -0,0 +1,232 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__SECRET_USE_CACHE_INTERNAL_DO_NOT_USE_OR_YOU_WILL_BE_FIRED = void 0;
+exports.cache = cache;
+exports.cacheTag = cacheTag;
+exports.cacheLife = cacheLife;
+exports.invalidate = invalidate;
+exports.revalidate = revalidate;
+exports.isCachedFunction = isCachedFunction;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
+const ms_1 = __importDefault(require("ms"));
+const utils_1 = require("./utils");
+const cache_plugin_1 = require("./cache-plugin");
+const cacheContext = new node_async_hooks_1.AsyncLocalStorage();
+const fnStore = new Map();
+const DEFAULT_TTL = (0, ms_1.default)('15m');
+const CACHE_FN_ID = `__cache_fn_id_${Date.now()}__${Math.random()}__`;
+const CACHED_FN_SYMBOL = Symbol('commandkit.cache.sentinel');
+/**
+ * Internal cache implementation
+ * @internal
+ * @private
+ * This is used directly by the compiler if the function is annotated with `"use cache"` directive.
+ * @example
+ * ```ts
+ * async function myCachedFunction() {
+ *   "use cache";
+ *   // can use cacheTag() and cacheLife() here to customize cache behavior
+ *   return await db.query('SELECT * FROM users');
+ * }
+ * ```
+ */
+function useCache(fn, id, params) {
+    const isLocal = id === CACHE_FN_ID;
+    if (id && !isLocal) {
+        throw new Error('Illegal use of cache function.');
+    }
+    const fnId = (0, node_crypto_1.randomUUID)();
+    const memo = (async (...args) => {
+        const forcedName = isLocal ? params?.name : null;
+        const keyHash = forcedName ?? (await (0, utils_1.createObjectHash)(fnId, ...args));
+        const resolvedTTL = isLocal && params?.ttl != null
+            ? typeof params.ttl === 'string'
+                ? (0, ms_1.default)(params.ttl)
+                : params.ttl
+            : null;
+        return cacheContext.run({
+            params: {
+                name: keyHash,
+                ttl: resolvedTTL ?? DEFAULT_TTL,
+            },
+        }, async () => {
+            const provider = (0, cache_plugin_1.getCacheProvider)();
+            const context = cacheContext.getStore();
+            if (!context) {
+                throw new Error('Cache context was not found.');
+            }
+            // Get the effective cache key, preferring any existing association
+            const storedFn = fnStore.get(keyHash);
+            const effectiveKey = storedFn?.key ?? context.params.name;
+            // Try to get cached value using effective key
+            const cached = await provider.get(effectiveKey);
+            if (cached && cached.value != null)
+                return cached.value;
+            // If we reach here, we need to cache the value
+            const result = await fn(...args);
+            // Only cache if result is not null/undefined
+            if (result != null) {
+                // Get the final key name (might have been modified by cacheTag)
+                const finalKey = context.params.name;
+                const ttl = context.params.ttl ?? DEFAULT_TTL;
+                // Store the result
+                await provider.set(finalKey, result, ttl);
+                // Update function store
+                fnStore.set(keyHash, {
+                    key: finalKey,
+                    hash: keyHash,
+                    ttl,
+                    original: fn,
+                    memo,
+                });
+            }
+            return result;
+        });
+    });
+    if (!Object.prototype.hasOwnProperty.call(fn, CACHED_FN_SYMBOL)) {
+        Object.defineProperty(memo, CACHED_FN_SYMBOL, {
+            get() {
+                return true;
+            },
+            configurable: false,
+            enumerable: false,
+        });
+    }
+    return memo;
+}
+/**
+ * Wraps an async function with caching capability
+ * @template R - Array of argument types
+ * @template F - Type of the async function
+ * @param fn - The async function to cache
+ * @param params - Optional cache configuration
+ * @returns The wrapped function with caching behavior
+ * @example
+ * ```ts
+ * const cachedFetch = cache(async (id: string) => {
+ *   return await db.findOne(id);
+ * }, { ttl: '1h' });
+ * ```
+ */
+function cache(fn, params) {
+    return useCache(fn, CACHE_FN_ID, params);
+}
+/**
+ * Sets a custom identifier for the current cache operation
+ * @param tag - The custom cache tag
+ * @throws {Error} When called outside a cached function or without a tag
+ * @example
+ * ```ts
+ * const fetchUser = cache(async (id: string) => {
+ *   cacheTag(`user:${id}`);
+ *   return await db.users.findOne(id);
+ * });
+ * ```
+ */
+function cacheTag(tag) {
+    const context = cacheContext.getStore();
+    if (!context) {
+        throw new Error('cacheTag() must be called inside a cached function.');
+    }
+    if (!tag) {
+        throw new Error('cacheTag() must be called with a tag name.');
+    }
+    context.params.name = tag;
+}
+/**
+ * Sets the TTL for the current cache operation
+ * @param ttl - Time-to-live in milliseconds or as a string (e.g., '1h', '5m')
+ * @throws {Error} When called outside a cached function or with invalid TTL
+ * @example
+ * ```ts
+ * const fetchData = cache(async () => {
+ *   cacheLife('30m');
+ *   return await expensiveOperation();
+ * });
+ * ```
+ */
+function cacheLife(ttl) {
+    const context = cacheContext.getStore();
+    if (!context) {
+        throw new Error('cacheLife() must be called inside a cached function.');
+    }
+    if (ttl == null || !['string', 'number'].includes(typeof ttl)) {
+        throw new Error('cacheLife() must be called with a ttl.');
+    }
+    context.params.ttl = typeof ttl === 'string' ? (0, ms_1.default)(ttl) : ttl;
+}
+/**
+ * Removes a cached value by its tag
+ * @param tag - The cache tag to invalidate. Can be a single tag or an array of tags.
+ * @throws {Error} When the cache key is not found
+ * @example
+ * ```ts
+ * await invalidate('user:123');
+ * // or
+ * await invalidate(['user:123', 'user:456']);
+ * ```
+ */
+async function invalidate(tag) {
+    const provider = (0, cache_plugin_1.getCacheProvider)();
+    let errors = [];
+    for (const t of Array.isArray(tag) ? tag : [tag]) {
+        try {
+            const entry = Array.from(fnStore.values()).find((v) => v.key === t || v.hash === t);
+            if (!entry)
+                continue;
+            await provider.delete(entry.key);
+        }
+        catch (e) {
+            errors.push(e);
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`Failed to invalidate cache for tags: ${errors
+            .map((e) => e.message)
+            .join(', ')}`);
+    }
+}
+/**
+ * Forces a refresh of cached data by its tag (on-demand revalidation)
+ * @template T - Type of the cached value
+ * @param tag - The cache tag to revalidate
+ * @param args - Arguments to pass to the cached function
+ * @returns Fresh data from the cached function
+ * @throws {Error} When the cache key or function is not found
+ * @example
+ * ```ts
+ * const freshData = await revalidate('user:123');
+ * ```
+ */
+async function revalidate(tag, ...args) {
+    const provider = (0, cache_plugin_1.getCacheProvider)();
+    const entry = Array.from(fnStore.values()).find((v) => v.key === tag || v.hash === tag);
+    if (!entry)
+        return undefined;
+    await provider.delete(entry.key);
+    return entry.memo(...args);
+}
+/**
+ * Checks if a function is wrapped with cache functionality
+ * @param fn - Function to check
+ * @returns True if the function is cached
+ * @example
+ * ```ts
+ * if (isCachedFunction(myFunction)) {
+ *   console.log('Function is cached');
+ * }
+ * ```
+ */
+function isCachedFunction(fn) {
+    return Object.prototype.hasOwnProperty.call(fn, CACHED_FN_SYMBOL);
+}
+/**
+ * @private
+ * @internal
+ */
+exports.__SECRET_USE_CACHE_INTERNAL_DO_NOT_USE_OR_YOU_WILL_BE_FIRED = useCache;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXNlLWNhY2hlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3VzZS1jYWNoZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7QUErSkEsc0JBS0M7QUFjRCw0QkFZQztBQWNELDhCQVlDO0FBYUQsZ0NBeUJDO0FBY0QsZ0NBY0M7QUFhRCw0Q0FFQztBQXpTRCx1REFBcUQ7QUFFckQsNkNBQXlDO0FBQ3pDLDRDQUFvQjtBQUNwQixtQ0FBMkM7QUFDM0MsaURBQWtEO0FBRWxELE1BQU0sWUFBWSxHQUFHLElBQUksb0NBQWlCLEVBQWdCLENBQUM7QUFDM0QsTUFBTSxPQUFPLEdBQUcsSUFBSSxHQUFHLEVBU3BCLENBQUM7QUFDSixNQUFNLFdBQVcsR0FBRyxJQUFBLFlBQUUsRUFBQyxLQUFLLENBQUMsQ0FBQztBQUM5QixNQUFNLFdBQVcsR0FBRyxpQkFBaUIsSUFBSSxDQUFDLEdBQUcsRUFBRSxLQUFLLElBQUksQ0FBQyxNQUFNLEVBQUUsSUFBSSxDQUFDO0FBQ3RFLE1BQU0sZ0JBQWdCLEdBQUcsTUFBTSxDQUFDLDJCQUEyQixDQUFDLENBQUM7QUF3QjdEOzs7Ozs7Ozs7Ozs7O0dBYUc7QUFDSCxTQUFTLFFBQVEsQ0FDZixFQUFLLEVBQ0wsRUFBVyxFQUNYLE1BQXNCO0lBRXRCLE1BQU0sT0FBTyxHQUFHLEVBQUUsS0FBSyxXQUFXLENBQUM7SUFFbkMsSUFBSSxFQUFFLElBQUksQ0FBQyxPQUFPLEVBQUUsQ0FBQztRQUNuQixNQUFNLElBQUksS0FBSyxDQUFDLGdDQUFnQyxDQUFDLENBQUM7SUFDcEQsQ0FBQztJQUVELE1BQU0sSUFBSSxHQUFHLElBQUEsd0JBQVUsR0FBRSxDQUFDO0lBRTFCLE1BQU0sSUFBSSxHQUFHLENBQUMsS0FBSyxFQUFFLEdBQUcsSUFBSSxFQUFFLEVBQUU7UUFDOUIsTUFBTSxVQUFVLEdBQUcsT0FBTyxDQUFDLENBQUMsQ0FBQyxNQUFNLEVBQUUsSUFBSSxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUM7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

package/dist/utils.d.ts

@@ -0,0 +1 @@
+export declare function createObjectHash(...args: any[]): Promise<string>;

package/dist/utils.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createObjectHash = createObjectHash;
+const node_crypto_1 = require("node:crypto");
+let tracker = 0n;
+const references = new WeakMap();
+const PRIMITIVE_TYPES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'bigint',
+    'undefined',
+]);
+function isSerializablePrimitive(value) {
+    return value === null || PRIMITIVE_TYPES.has(typeof value);
+}
+function createKey(val) {
+    return `commandkit:cache:object:${val}`;
+}
+// returns runtime object id of the given argument
+function getObjectId(obj) {
+    const primitive = isSerializablePrimitive(obj);
+    if (primitive)
+        return createKey(obj);
+    if (obj instanceof Date)
+        return createKey(obj.getTime());
+    if (obj instanceof RegExp)
+        return createKey(obj);
+    const ref = references.get(obj);
+    if (ref)
+        return createKey(ref);
+    const id = tracker++;
+    references.set(obj, id);
+    return createKey(id);
+}
+async function createObjectHash(...args) {
+    const serializedKey = args.map(getObjectId).join(':');
+    try {
+        const hash = (0, node_crypto_1.createHash)('sha256');
+        hash.update(serializedKey);
+        return hash.digest('hex');
+    }
+    catch {
+        return serializedKey;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXRpbHMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdXRpbHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7QUF1Q0EsNENBVUM7QUFqREQsNkNBQXlDO0FBRXpDLElBQUksT0FBTyxHQUFHLEVBQUUsQ0FBQztBQUVqQixNQUFNLFVBQVUsR0FBRyxJQUFJLE9BQU8sRUFBZSxDQUFDO0FBQzlDLE1BQU0sZUFBZSxHQUFHLElBQUksR0FBRyxDQUFDO0lBQzlCLFFBQVE7SUFDUixRQUFRO0lBQ1IsU0FBUztJQUNULFFBQVE7SUFDUixXQUFXO0NBQ1osQ0FBQyxDQUFDO0FBRUgsU0FBUyx1QkFBdUIsQ0FBQyxLQUFVO0lBQ3pDLE9BQU8sS0FBSyxLQUFLLElBQUksSUFBSSxlQUFlLENBQUMsR0FBRyxDQUFDLE9BQU8sS0FBSyxDQUFDLENBQUM7QUFDN0QsQ0FBQztBQUVELFNBQVMsU0FBUyxDQUFDLEdBQVE7SUFDekIsT0FBTywyQkFBMkIsR0FBRyxFQUFFLENBQUM7QUFDMUMsQ0FBQztBQUVELGtEQUFrRDtBQUNsRCxTQUFTLFdBQVcsQ0FBQyxHQUFRO0lBQzNCLE1BQU0sU0FBUyxHQUFHLHVCQUF1QixDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBQy9DLElBQUksU0FBUztRQUFFLE9BQU8sU0FBUyxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBRXJDLElBQUksR0FBRyxZQUFZLElBQUk7UUFBRSxPQUFPLFNBQVMsQ0FBQyxHQUFHLENBQUMsT0FBTyxFQUFFLENBQUMsQ0FBQztJQUN6RCxJQUFJLEdBQUcsWUFBWSxNQUFNO1FBQUUsT0FBTyxTQUFTLENBQUMsR0FBRyxDQUFDLENBQUM7SUFFakQsTUFBTSxHQUFHLEdBQUcsVUFBVSxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUNoQyxJQUFJLEdBQUc7UUFBRSxPQUFPLFNBQVMsQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUUvQixNQUFNLEVBQUUsR0FBRyxPQUFPLEVBQUUsQ0FBQztJQUVyQixVQUFVLENBQUMsR0FBRyxDQUFDLEdBQUcsRUFBRSxFQUFFLENBQUMsQ0FBQztJQUV4QixPQUFPLFNBQVMsQ0FBQyxFQUFFLENBQUMsQ0FBQztBQUN2QixDQUFDO0FBRU0sS0FBSyxVQUFVLGdCQUFnQixDQUFDLEdBQUcsSUFBVztJQUNuRCxNQUFNLGFBQWEsR0FBRyxJQUFJLENBQUMsR0FBRyxDQUFDLFdBQVcsQ0FBQyxDQUFDLElBQUksQ0FBQyxHQUFHLENBQUMsQ0FBQztJQUV0RCxJQUFJLENBQUM7UUFDSCxNQUFNLElBQUksR0FBRyxJQUFBLHdCQUFVLEVBQUMsUUFBUSxDQUFDLENBQUM7UUFDbEMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxhQUFhLENBQUMsQ0FBQztRQUMzQixPQUFPLElBQUksQ0FBQyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUM7SUFDNUIsQ0FBQztJQUFDLE1BQU0sQ0FBQztRQUNQLE9BQU8sYUFBYSxDQUFDO0lBQ3ZCLENBQUM7QUFDSCxDQUFDIn0=

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@commandkit/cache",
+  "version": "0.0.0-dev.20250512141518",
+  "description": "CommandKit plugin that provides caching apis",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/underctrl-io/commandkit.git"
+  },
+  "keywords": [
+    "commandkit",
+    "cache",
+    "caching",
+    "cache management",
+    "commandkit cache"
+  ],
+  "author": "twilight <hello@twlite.dev>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/underctrl-io/commandkit/issues"
+  },
+  "homepage": "https://github.com/underctrl-io/commandkit#readme",
+  "devDependencies": {
+    "@types/ms": "^0.7.34",
+    "typescript": "^5.7.3",
+    "commandkit": "1.0.0",
+    "tsconfig": "0.0.0"
+  },
+  "dependencies": {
+    "ms": "^2.1.3"
+  },
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "build": "tsc"
+  }
+}