@boostkit/cache 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 BoostKit
+
+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, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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,48 @@
+# @boostkit/cache
+
+Cache facade, cache registry, and provider factory with an in-memory built-in driver.
+
+## Installation
+
+```bash
+pnpm add @boostkit/cache
+```
+
+## Usage
+
+```ts
+// bootstrap/providers.ts
+import { cache } from '@boostkit/cache'
+import configs from '../config/index.js'
+
+export default [
+  cache(configs.cache),
+]
+
+// anywhere after boot
+import { Cache } from '@boostkit/cache'
+await Cache.set('users:count', 10, 60)
+const count = await Cache.get<number>('users:count')
+```
+
+## API Reference
+
+- `CacheAdapter`, `CacheAdapterProvider`
+- `CacheRegistry`
+- `Cache`
+- `CacheStoreConfig`, `CacheConfig`
+- `cache(config)`
+
+## Configuration
+
+- `CacheConfig`
+  - `default`
+  - `stores`
+- `CacheStoreConfig`
+  - `driver`
+  - additional driver-specific keys
+
+## Notes
+
+- Built-in driver: `memory`.
+- Plugin driver supported by factory: `redis` (via `@boostkit/cache-redis`).

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { ServiceProvider, type Application } from '@boostkit/core';
+export interface CacheAdapter {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    forget(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    flush(): Promise<void>;
+}
+export interface CacheAdapterProvider {
+    create(): CacheAdapter | Promise<CacheAdapter>;
+}
+export declare class CacheRegistry {
+    private static adapter;
+    static set(adapter: CacheAdapter): void;
+    static get(): CacheAdapter | null;
+}
+export declare class Cache {
+    private static store;
+    /** Retrieve a value. Returns null on miss or expiry. */
+    static get<T = unknown>(key: string): Promise<T | null>;
+    /** Store a value, optionally with a TTL in seconds. */
+    static set(key: string, value: unknown, ttl?: number): Promise<void>;
+    /**
+     * Retrieve a value, or compute + store it if missing.
+     * @param ttl Time-to-live in seconds
+     */
+    static remember<T = unknown>(key: string, ttl: number, callback: () => T | Promise<T>): Promise<T>;
+    /** Remove a single key. */
+    static forget(key: string): Promise<void>;
+    /** Check if a key exists (and hasn't expired). */
+    static has(key: string): Promise<boolean>;
+    /** Remove all cached entries. */
+    static flush(): Promise<void>;
+}
+export interface CacheStoreConfig {
+    driver: string;
+    [key: string]: unknown;
+}
+export interface CacheConfig {
+    /** The default cache store name */
+    default: string;
+    /** Named cache stores */
+    stores: Record<string, CacheStoreConfig>;
+}
+/**
+ * Returns a CacheServiceProvider class configured for the given cache config.
+ *
+ * Built-in drivers:  memory (in-process — resets on restart, great for dev)
+ * Plugin drivers:    redis (@boostkit/cache-redis)
+ *
+ * Usage in bootstrap/providers.ts:
+ *   import { cache } from '@boostkit/cache'
+ *   import configs from '../config/index.js'
+ *   export default [..., cache(configs.cache), ...]
+ */
+export declare function cache(config: CacheConfig): new (app: Application) => ServiceProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAKlE,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IAChD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,IAAI,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CAC/C;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,OAAO,CAA4B;IAElD,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IACvC,MAAM,CAAC,GAAG,IAAI,YAAY,GAAG,IAAI;CAClC;AAID,qBAAa,KAAK;IAChB,OAAO,CAAC,MAAM,CAAC,KAAK;IAMpB,wDAAwD;IACxD,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAIvD,uDAAuD;IACvD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;OAGG;WACU,QAAQ,CAAC,CAAC,GAAG,OAAO,EAC/B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC;IAQb,2BAA2B;IAC3B,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEzC,kDAAkD;IAClD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAEzC,iCAAiC;IACjC,MAAM,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAC9B;AA0CD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CACzC;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,GAAG,EAAE,WAAW,KAAK,eAAe,CA4BpF"}

package/dist/index.js

@@ -0,0 +1,113 @@
+import { ServiceProvider } from '@boostkit/core';
+import { resolveOptionalPeer } from '@boostkit/core';
+// ─── Cache Registry ────────────────────────────────────────
+export class CacheRegistry {
+    static adapter = null;
+    static set(adapter) { this.adapter = adapter; }
+    static get() { return this.adapter; }
+}
+// ─── Cache Facade ──────────────────────────────────────────
+export class Cache {
+    static store() {
+        const a = CacheRegistry.get();
+        if (!a)
+            throw new Error('[BoostKit Cache] No cache adapter registered. Add cache() to providers.');
+        return a;
+    }
+    /** Retrieve a value. Returns null on miss or expiry. */
+    static get(key) {
+        return this.store().get(key);
+    }
+    /** Store a value, optionally with a TTL in seconds. */
+    static set(key, value, ttl) {
+        return this.store().set(key, value, ttl);
+    }
+    /**
+     * Retrieve a value, or compute + store it if missing.
+     * @param ttl Time-to-live in seconds
+     */
+    static async remember(key, ttl, callback) {
+        const cached = await this.get(key);
+        if (cached !== null)
+            return cached;
+        const value = await callback();
+        await this.set(key, value, ttl);
+        return value;
+    }
+    /** Remove a single key. */
+    static forget(key) { return this.store().forget(key); }
+    /** Check if a key exists (and hasn't expired). */
+    static has(key) { return this.store().has(key); }
+    /** Remove all cached entries. */
+    static flush() { return this.store().flush(); }
+}
+class MemoryAdapter {
+    store = new Map();
+    expired(entry) {
+        return entry.expiresAt !== null && Date.now() > entry.expiresAt;
+    }
+    async get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return null;
+        if (this.expired(entry)) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    async set(key, value, ttlSeconds) {
+        const expiresAt = ttlSeconds ? Date.now() + ttlSeconds * 1_000 : null;
+        this.store.set(key, { value, expiresAt });
+    }
+    async forget(key) { this.store.delete(key); }
+    async has(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return false;
+        if (this.expired(entry)) {
+            this.store.delete(key);
+            return false;
+        }
+        return true;
+    }
+    async flush() { this.store.clear(); }
+}
+// ─── Service Provider Factory ──────────────────────────────
+/**
+ * Returns a CacheServiceProvider class configured for the given cache config.
+ *
+ * Built-in drivers:  memory (in-process — resets on restart, great for dev)
+ * Plugin drivers:    redis (@boostkit/cache-redis)
+ *
+ * Usage in bootstrap/providers.ts:
+ *   import { cache } from '@boostkit/cache'
+ *   import configs from '../config/index.js'
+ *   export default [..., cache(configs.cache), ...]
+ */
+export function cache(config) {
+    class CacheServiceProvider extends ServiceProvider {
+        register() { }
+        async boot() {
+            const storeName = config.default;
+            const storeConfig = config.stores[storeName] ?? { driver: 'memory' };
+            const driver = storeConfig['driver'];
+            let adapter;
+            if (driver === 'memory') {
+                adapter = new MemoryAdapter();
+            }
+            else if (driver === 'redis') {
+                const { redis } = await resolveOptionalPeer('@boostkit/cache-redis');
+                adapter = await redis(storeConfig).create();
+            }
+            else {
+                throw new Error(`[BoostKit Cache] Unknown driver "${driver}". Available: memory, redis`);
+            }
+            CacheRegistry.set(adapter);
+            this.app.instance('cache', adapter);
+            console.log(`[CacheServiceProvider] booted — driver: ${driver}`);
+        }
+    }
+    return CacheServiceProvider;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@boostkit/cache",
+  "version": "0.0.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/boostkitjs/boostkit",
+    "directory": "packages/cache"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@boostkit/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "tsx": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/index.test.js; rm -rf dist-test"
+  }
+}