@wild-framework/cache-redis 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wild Framework contributors
+
+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

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @wild-framework/cache-redis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Redis driver for [Wild Framework](https://github.com/KhandaSoftware/wild-framework)'s cache package.
+
+## Install
+
+```bash
+pnpm add @wild-framework/cache-redis
+```
+
+## Usage
+
+```ts
+import { RedisCacheProvider } from "@wild-framework/cache-redis";
+
+RedisCacheProvider.url = process.env.REDIS_URL ?? "redis://localhost:6379";
+RedisCacheProvider.keyPrefix = "app:"; // optional
+
+app.register(RedisCacheProvider);
+// … cache is now Redis-backed, resolved via app.resolve(Cache)
+```
+
+Values are JSON-serialized on write and parsed on read. TTL is in milliseconds.
+
+## Integration test
+
+```bash
+REDIS_URL='redis://localhost:6379' pnpm --filter @wild-framework/cache-redis test
+```
+
+Skips automatically when `REDIS_URL` is not set.
+
+## License
+
+MIT

package/dist/driver.d.ts

@@ -0,0 +1,42 @@
+import type { CacheDriver } from "@wild-framework/cache";
+import { createClient } from "redis";
+/** A connected node-redis client (or any compatible client). */
+export type RedisClient = ReturnType<typeof createClient>;
+/**
+ * Configuration for the Redis cache driver.
+ */
+export interface RedisCacheConfig {
+    /** Redis connection string (e.g. `redis://localhost:6379` or `rediss://…`). */
+    url?: string;
+    /** A pre-connected client — for advanced use or tests. */
+    client?: RedisClient;
+    /** Optional prefix prepended to every key. */
+    keyPrefix?: string;
+}
+/**
+ * Redis-backed cache driver implementing `CacheDriver`.
+ *
+ * Values are serialized to JSON on write and parsed on read, so any
+ * JSON-serializable value round-trips. Call `connect()` before use —
+ * `RedisCacheProvider` does this on boot.
+ */
+export declare class RedisCacheDriver implements CacheDriver {
+    private config;
+    private client;
+    private connected;
+    private ownsClient;
+    constructor(config?: RedisCacheConfig);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    flush(): Promise<void>;
+    private requireClient;
+    private applyPrefix;
+    private serialize;
+    private deserialize;
+}
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAErC,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAKpC,OAAO,CAAC,MAAM;IAJ1B,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;gBAEP,MAAM,GAAE,gBAAqB;IAE3C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B,WAAW,IAAI,OAAO;IAIhB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAM3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW5D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;CAOtB"}

package/dist/driver.js

@@ -0,0 +1,92 @@
+import { createClient } from "redis";
+/**
+ * Redis-backed cache driver implementing `CacheDriver`.
+ *
+ * Values are serialized to JSON on write and parsed on read, so any
+ * JSON-serializable value round-trips. Call `connect()` before use —
+ * `RedisCacheProvider` does this on boot.
+ */
+export class RedisCacheDriver {
+    config;
+    client = null;
+    connected = false;
+    ownsClient = false;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    async connect() {
+        if (this.connected)
+            return;
+        if (this.config.client) {
+            this.client = this.config.client;
+            this.ownsClient = false;
+            if (!this.client.isOpen) {
+                await this.client.connect();
+            }
+        }
+        else {
+            this.client = createClient({ url: this.config.url ?? "redis://localhost:6379" });
+            this.ownsClient = true;
+            await this.client.connect();
+        }
+        this.connected = true;
+    }
+    async close() {
+        // Only close clients we created — an injected client is the caller's.
+        if (this.client && this.ownsClient && this.client.isOpen) {
+            await this.client.quit();
+        }
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected;
+    }
+    async get(key) {
+        const raw = await this.requireClient().get(this.applyPrefix(key));
+        if (raw === null)
+            return undefined;
+        return this.deserialize(raw);
+    }
+    async set(key, value, ttlMs) {
+        const raw = this.serialize(value);
+        const client = this.requireClient();
+        if (ttlMs !== undefined) {
+            await client.set(this.applyPrefix(key), raw, { PX: ttlMs });
+        }
+        else {
+            await client.set(this.applyPrefix(key), raw);
+        }
+    }
+    async delete(key) {
+        await this.requireClient().del(this.applyPrefix(key));
+    }
+    async has(key) {
+        const count = await this.requireClient().exists(this.applyPrefix(key));
+        return count === 1;
+    }
+    async flush() {
+        await this.requireClient().flushDb();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new Error("Cache is not connected. Call connect() first.");
+        }
+        return this.client;
+    }
+    applyPrefix(key) {
+        return this.config.keyPrefix ? `${this.config.keyPrefix}${key}` : key;
+    }
+    serialize(value) {
+        return JSON.stringify(value) ?? "null";
+    }
+    deserialize(raw) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+}
+//# sourceMappingURL=driver.js.map

package/dist/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAiBrC;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IAKL;IAJZ,MAAM,GAAuB,IAAI,CAAC;IAClC,SAAS,GAAG,KAAK,CAAC;IAClB,UAAU,GAAG,KAAK,CAAC;IAE3B,YAAoB,SAA2B,EAAE;QAA7B,WAAM,GAAN,MAAM,CAAuB;IAAG,CAAC;IAErD,KAAK,CAAC,OAAO;QACT,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAE3B,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;YACjC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;YACxB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBACtB,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAChC,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,wBAAwB,EAAE,CAAC,CAAC;YACjF,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAChC,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,KAAK;QACP,sEAAsE;QACtE,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACvD,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC7B,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;IAC3B,CAAC;IAED,WAAW;QACP,OAAO,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,GAAW;QACpB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC;QACnC,OAAO,IAAI,CAAC,WAAW,CAAI,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,KAAc;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QAEpC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAChE,CAAC;aAAM,CAAC;YACJ,MAAM,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;QACjD,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACpB,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACjB,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;QACvE,OAAO,KAAK,KAAK,CAAC,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,KAAK;QACP,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,CAAC;IACzC,CAAC;IAEO,aAAa;QACjB,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAEO,WAAW,CAAC,GAAW;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IAC1E,CAAC;IAEO,SAAS,CAAC,KAAc;QAC5B,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;IAC3C,CAAC;IAEO,WAAW,CAAI,GAAW;QAC9B,IAAI,CAAC;YACD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACL,OAAO,GAAmB,CAAC;QAC/B,CAAC;IACL,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { RedisCacheDriver } from "./driver.js";
+export type { RedisCacheConfig, RedisClient } from "./driver.js";
+export { RedisCacheProvider } from "./provider.js";
+//# 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,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { RedisCacheDriver } from "./driver.js";
+export { RedisCacheProvider } from "./provider.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,24 @@
+import type { Provider, Application } from "@wild-framework/core";
+/**
+ * Registers a Redis-backed cache with the application.
+ *
+ * Static configuration (no-arg constructor requirement):
+ *
+ * ```ts
+ * RedisCacheProvider.url = process.env.REDIS_URL ?? "redis://localhost:6379";
+ * RedisCacheProvider.keyPrefix = "app:";
+ * ```
+ *
+ * Connects on boot and disconnects on shutdown.
+ */
+export declare class RedisCacheProvider implements Provider {
+    /** Redis connection string. Defaults to `redis://localhost:6379`. */
+    static url: string | undefined;
+    /** Optional prefix prepended to every key. */
+    static keyPrefix: string | undefined;
+    private driver;
+    register(app: Application): void;
+    boot(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKlE;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAmB,YAAW,QAAQ;IAC/C,qEAAqE;IACrE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,8CAA8C;IAC9C,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC,OAAO,CAAC,MAAM,CAA+B;IAE7C,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAY1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/provider.js

@@ -0,0 +1,38 @@
+import { Container } from "@wild-framework/container";
+import { Cache } from "@wild-framework/cache";
+import { RedisCacheDriver } from "./driver.js";
+/**
+ * Registers a Redis-backed cache with the application.
+ *
+ * Static configuration (no-arg constructor requirement):
+ *
+ * ```ts
+ * RedisCacheProvider.url = process.env.REDIS_URL ?? "redis://localhost:6379";
+ * RedisCacheProvider.keyPrefix = "app:";
+ * ```
+ *
+ * Connects on boot and disconnects on shutdown.
+ */
+export class RedisCacheProvider {
+    /** Redis connection string. Defaults to `redis://localhost:6379`. */
+    static url;
+    /** Optional prefix prepended to every key. */
+    static keyPrefix;
+    driver;
+    register(app) {
+        const container = app.resolve(Container);
+        const driver = new RedisCacheDriver({
+            url: RedisCacheProvider.url,
+            keyPrefix: RedisCacheProvider.keyPrefix,
+        });
+        this.driver = driver;
+        container.singleton(Cache, () => new Cache(driver));
+    }
+    async boot() {
+        await this.driver?.connect();
+    }
+    async shutdown() {
+        await this.driver?.close();
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,kBAAkB;IAC3B,qEAAqE;IACrE,MAAM,CAAC,GAAG,CAAqB;IAC/B,8CAA8C;IAC9C,MAAM,CAAC,SAAS,CAAqB;IAE7B,MAAM,CAA+B;IAE7C,QAAQ,CAAC,GAAgB;QACrB,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEzC,MAAM,MAAM,GAAG,IAAI,gBAAgB,CAAC;YAChC,GAAG,EAAE,kBAAkB,CAAC,GAAG;YAC3B,SAAS,EAAE,kBAAkB,CAAC,SAAS;SAC1C,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,KAAK,CAAC,IAAI;QACN,MAAM,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,QAAQ;QACV,MAAM,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;IAC/B,CAAC;CACJ"}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@wild-framework/cache-redis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Sphah",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KhandaSoftware/wild-framework.git"
+  },
+  "description": "Redis cache driver for Wild Framework's cache package (node-redis).",
+  "keywords": [
+    "wild",
+    "framework",
+    "cache",
+    "redis",
+    "ttl"
+  ],
+  "dependencies": {
+    "redis": "^4.7.0",
+    "@wild-framework/core": "0.2.0",
+    "@wild-framework/container": "0.2.0",
+    "@wild-framework/cache": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
 }