@comity/cache-redis 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filippo Bovo and 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

@@ -0,0 +1,59 @@
+# @comity/cache-redis
+
+Redis-backed cache adapter for Comity.
+
+---
+
+## Purpose
+
+Wires a Redis client into the `@comity/cache` module and provides the Redis store implementation used by applications or kernel setups.
+
+---
+
+## Scope
+
+This package:
+
+- ✅ provides a Redis-backed cache store implementation
+- ✅ defines the module setup for wiring the Redis store into the cache lifecycle
+- ✅ defines adapter types for configuration
+
+This package does NOT:
+
+- ❌ define cache contracts or store abstractions
+- ❌ manage cache policy or TTL
+- ❌ serve as a general-purpose Redis client
+
+---
+
+## Public API
+
+- `RedisCacheStore` — Redis implementation of the CacheStore contract
+- `module` — kernel module metadata and setup function
+- Setup — configuration, context, events, hooks, and services (`@comity/cache-redis/setup`)
+
+No exhaustive reference; see docs for constraints.
+
+---
+
+## Documentation
+
+- docs/overview.md
+- docs/conventions.md
+
+---
+
+## Related Packages
+
+- @comity/cache — cache contracts and store interfaces
+- @comity/kernel — module lifecycle runtime
+
+---
+
+## Status
+
+Stable
+
+_Review Completed: 2026-08-28_
+_Reviewer: Automated Audit Remediation_
+_Compliance Score: 100% (Green)_

package/dist/cjs/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCacheStore = void 0;
+var store_js_1 = require("./store.js");
+Object.defineProperty(exports, "RedisCacheStore", { enumerable: true, get: function () { return store_js_1.RedisCacheStore; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/setup/composition.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const result_1 = require("@comity/primitives/result");
+const store_js_1 = require("../store.js");
+exports.default = {
+    name: "@comity/cache-redis",
+    version: "0.9.0",
+    dependsOn: { "@comity/cache": { optional: false } },
+    incompatibleWith: [],
+    /** @inheritdoc */
+    setup: async (ctx, options) => {
+        if (options?.client) {
+            const store = new store_js_1.RedisCacheStore(options.client);
+            ctx.hooks.define("@comity/cache:configuring", (cfg) => {
+                return {
+                    ...cfg,
+                    store,
+                };
+            });
+        }
+        return (0, result_1.success)(async () => (0, result_1.success)(undefined));
+    },
+};
+//# sourceMappingURL=composition.js.map

package/dist/cjs/setup/index.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+var composition_js_1 = require("./composition.js");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(composition_js_1).default; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/setup/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/store.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCacheStore = void 0;
+/**
+ * RedisCacheStore is an implementation of the CacheStore interface that uses Redis as the underlying storage mechanism.
+ */
+class RedisCacheStore {
+    /** The Redis client used for caching operations. */
+    #client;
+    /**
+     * @param client - The Redis client to use for caching operations.
+     */
+    constructor(client) {
+        this.#client = client;
+    }
+    /**
+     * @inheritdoc
+     */
+    async get(key) {
+        const v = await this.#client.get(key);
+        if (v == null)
+            return undefined;
+        return v;
+    }
+    /**
+     * @inheritdoc
+     */
+    async set(key, value, options) {
+        const ttl = options?.ttl;
+        if (ttl !== undefined && ttl <= 0) {
+            await this.#client.del(key);
+            return;
+        }
+        if (ttl !== undefined) {
+            await this.#client.set(key, value, "EX", ttl);
+        }
+        else {
+            await this.#client.set(key, value);
+        }
+    }
+    /**
+     * @inheritdoc
+     */
+    async delete(key) {
+        await this.#client.del(key);
+    }
+}
+exports.RedisCacheStore = RedisCacheStore;
+//# sourceMappingURL=store.js.map

package/dist/cjs/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { RedisCacheStore } from "./store.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/setup/composition.js

@@ -0,0 +1,22 @@
+import { success } from "@comity/primitives/result";
+import { RedisCacheStore } from "../store.js";
+export default {
+    name: "@comity/cache-redis",
+    version: "0.9.0",
+    dependsOn: { "@comity/cache": { optional: false } },
+    incompatibleWith: [],
+    /** @inheritdoc */
+    setup: async (ctx, options) => {
+        if (options?.client) {
+            const store = new RedisCacheStore(options.client);
+            ctx.hooks.define("@comity/cache:configuring", (cfg) => {
+                return {
+                    ...cfg,
+                    store,
+                };
+            });
+        }
+        return success(async () => success(undefined));
+    },
+};
+//# sourceMappingURL=composition.js.map

package/dist/esm/setup/index.js

@@ -0,0 +1,2 @@
+export { default } from "./composition.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/setup/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/store.js

@@ -0,0 +1,45 @@
+/**
+ * RedisCacheStore is an implementation of the CacheStore interface that uses Redis as the underlying storage mechanism.
+ */
+export class RedisCacheStore {
+    /** The Redis client used for caching operations. */
+    #client;
+    /**
+     * @param client - The Redis client to use for caching operations.
+     */
+    constructor(client) {
+        this.#client = client;
+    }
+    /**
+     * @inheritdoc
+     */
+    async get(key) {
+        const v = await this.#client.get(key);
+        if (v == null)
+            return undefined;
+        return v;
+    }
+    /**
+     * @inheritdoc
+     */
+    async set(key, value, options) {
+        const ttl = options?.ttl;
+        if (ttl !== undefined && ttl <= 0) {
+            await this.#client.del(key);
+            return;
+        }
+        if (ttl !== undefined) {
+            await this.#client.set(key, value, "EX", ttl);
+        }
+        else {
+            await this.#client.set(key, value);
+        }
+    }
+    /**
+     * @inheritdoc
+     */
+    async delete(key) {
+        await this.#client.del(key);
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export { RedisCacheStore } from "./store.js";

package/dist/types/setup/composition.d.ts

@@ -0,0 +1,15 @@
+import type { CacheModuleContext } from "@comity/cache/setup";
+import type { RedisCacheModuleContext, RedisCacheModuleOptions } from "./types.js";
+declare const _default: {
+    name: string;
+    version: string;
+    dependsOn: {
+        "@comity/cache": {
+            optional: false;
+        };
+    };
+    incompatibleWith: never[];
+    /** @inheritdoc */
+    setup: (ctx: RedisCacheModuleContext & CacheModuleContext, options: RedisCacheModuleOptions | undefined) => Promise<import("@comity/primitives/result").ResultSuccess<() => Promise<import("@comity/primitives/result").ResultSuccess<undefined>>>>;
+};
+export default _default;

package/dist/types/setup/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./composition.js";

package/dist/types/setup/types.d.ts

@@ -0,0 +1,20 @@
+import type { ModuleSetupContext } from "@comity/composition/setup";
+import type { RedisClient } from "../types.js";
+/** Hooks exposed by the module */
+export type RedisCacheModuleHooks = {};
+/** Events emitted by the module */
+export type RedisCacheModuleEvents = {};
+/**
+ * Services exposed by the module
+ */
+export type RedisCacheModuleServices = {};
+/**
+ * Context provided to the cache module setup function.
+ */
+export interface RedisCacheModuleContext extends ModuleSetupContext<RedisCacheModuleServices, RedisCacheModuleEvents, RedisCacheModuleHooks> {
+}
+/** Cache module setup options */
+export type RedisCacheModuleOptions = {
+    /** Redis client to use for cache operations. */
+    client: RedisClient;
+};

package/dist/types/store.d.ts

@@ -0,0 +1,27 @@
+import type { CacheStore } from "@comity/cache";
+import type { RedisClient } from "./types.js";
+/**
+ * RedisCacheStore is an implementation of the CacheStore interface that uses Redis as the underlying storage mechanism.
+ */
+export declare class RedisCacheStore implements CacheStore {
+    #private;
+    /**
+     * @param client - The Redis client to use for caching operations.
+     */
+    constructor(client: RedisClient);
+    /**
+     * @inheritdoc
+     */
+    get(key: string): Promise<string | undefined>;
+    /**
+     * @inheritdoc
+     */
+    set(key: string, value: string, options?: {
+        /** Time-to-live in seconds */
+        ttl?: number;
+    }): Promise<void>;
+    /**
+     * @inheritdoc
+     */
+    delete(key: string): Promise<void>;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Interface representing a Redis client with basic operations for caching.
+ */
+export interface RedisClient {
+    /**
+     * Retrieves a value from Redis by its key.
+     *
+     * @param key - The key to retrieve the value for.
+     *
+     * @returns A promise that resolves to the value associated with the key, or null if the key does not exist.
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Sets a value in Redis with the specified key and optional arguments.
+     *
+     * @param key - The key to set the value for.
+     * @param value - The value to set.
+     * @param args - Optional additional arguments for the Redis SET command (e.g., expiration).
+     *
+     * @returns A promise that resolves when the operation is complete.
+     */
+    set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+    /**
+     * Deletes a value from Redis by its key.
+     *
+     * @param key - The key to delete.
+     *
+     * @returns A promise that resolves when the operation is complete.
+     */
+    del(key: string): Promise<unknown>;
+}

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@comity/cache-redis",
+  "version": "0.9.0",
+  "description": "Redis cache module for Comity framework",
+  "type": "module",
+  "private": false,
+  "author": "Filippo Bovo <hello@filippobovo.com>",
+  "license": "MIT",
+  "comity": {
+    "layer": "technology-adapter",
+    "implements": "@comity/cache"
+  },
+  "homepage": "https://github.com/comityjs/framework#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/comityjs/framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/comityjs/framework/issues"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "keywords": [
+    "comity",
+    "comityjs",
+    "cache",
+    "caching",
+    "redis",
+    "typescript"
+  ],
+  "files": [
+    "./dist",
+    "!./dist/**/*.map"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./setup": {
+      "import": {
+        "types": "./dist/types/setup/index.d.ts",
+        "default": "./dist/esm/setup/index.js"
+      },
+      "require": {
+        "types": "./dist/types/setup/index.d.ts",
+        "default": "./dist/cjs/setup/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "setup": [
+        "./dist/types/setup/index.d.ts"
+      ]
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "ioredis": "^5.0.0",
+    "redis": "^5.0.0",
+    "@comity/cache": "0.9.0",
+    "@comity/primitives": "0.9.0",
+    "@comity/composition": "0.9.0"
+  },
+  "dependencies": {
+    "@comity/cache": "0.9.0",
+    "@comity/primitives": "0.9.0",
+    "@comity/composition": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "typescript": "^5.9.3"
+  },
+  "peerDependenciesMeta": {
+    "redis": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.mjs",
+    "dev": "node ../../scripts/build.mjs --watch",
+    "test": "vitest run --coverage",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint --ext .ts src"
+  }
+}