@comity/cache-kv 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,57 @@
+# @comity/cache-kv
+
+Key-value cache adapter for the Comity cache module.
+
+---
+
+## Purpose
+
+Adapts a key-value cache store into the `@comity/cache` module wiring. Provides the kernel setup needed to connect a KV store to the standard cache lifecycle.
+
+---
+
+## Scope
+
+This package:
+
+- provides a module that wires a KV cache into Comity
+- exposes setup types for configuring the KV cache adapter
+
+This package does NOT:
+
+- define cache contracts or store abstractions
+- implement the cache store itself
+- manage cache TTL or serialization
+
+---
+
+## Public API
+
+- `module` — kernel module metadata and setup function
+- Setup — configuration types for the KV adapter (`@comity/cache-kv/setup`)
+
+No exhaustive reference; see docs for constraints.
+
+---
+
+## Documentation
+
+- docs/overview.md
+- docs/conventions.md
+
+---
+
+## Related Packages
+
+- @comity/cache — cache contracts and store abstractions
+- @comity/kernel — module lifecycle runtime
+
+---
+
+## Status
+
+Stable
+
+_Review Completed: 2026-07-25_
+_Reviewer: Hobiri MAGI (DeepSeek v4 Pro)_
+_Compliance Score: 99.5% (Green)_

package/dist/cjs/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KvCacheStore = void 0;
+var store_js_1 = require("./store.js");
+Object.defineProperty(exports, "KvCacheStore", { enumerable: true, get: function () { return store_js_1.KvCacheStore; } });
+//# 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-kv",
+    version: "0.9.0",
+    dependsOn: { "@comity/cache": { optional: false } },
+    incompatibleWith: [],
+    /** @inheritdoc */
+    setup: async (ctx, options) => {
+        if (options?.ns) {
+            const store = new store_js_1.KvCacheStore(options.ns);
+            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,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KvCacheStore = void 0;
+/**
+ * A cache store implementation that uses a key-value namespace for storage.
+ */
+class KvCacheStore {
+    /** The key-value namespace used for caching. */
+    #ns;
+    /**
+     * @param ns - The key-value namespace to use for caching.
+     */
+    constructor(ns) {
+        this.#ns = ns;
+    }
+    /**
+     * @inheritdoc
+     */
+    async get(key) {
+        const v = await this.#ns.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.#ns.delete(key);
+            return;
+        }
+        await this.#ns.put(key, value, {
+            ...(ttl !== undefined ? { expirationTtl: ttl } : {}),
+        });
+    }
+    /**
+     * @inheritdoc
+     */
+    async delete(key) {
+        await this.#ns.delete(key);
+    }
+}
+exports.KvCacheStore = KvCacheStore;
+//# 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 { KvCacheStore } from "./store.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/setup/composition.js

@@ -0,0 +1,22 @@
+import { success } from "@comity/primitives/result";
+import { KvCacheStore } from "../store.js";
+export default {
+    name: "@comity/cache-kv",
+    version: "0.9.0",
+    dependsOn: { "@comity/cache": { optional: false } },
+    incompatibleWith: [],
+    /** @inheritdoc */
+    setup: async (ctx, options) => {
+        if (options?.ns) {
+            const store = new KvCacheStore(options.ns);
+            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,42 @@
+/**
+ * A cache store implementation that uses a key-value namespace for storage.
+ */
+export class KvCacheStore {
+    /** The key-value namespace used for caching. */
+    #ns;
+    /**
+     * @param ns - The key-value namespace to use for caching.
+     */
+    constructor(ns) {
+        this.#ns = ns;
+    }
+    /**
+     * @inheritdoc
+     */
+    async get(key) {
+        const v = await this.#ns.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.#ns.delete(key);
+            return;
+        }
+        await this.#ns.put(key, value, {
+            ...(ttl !== undefined ? { expirationTtl: ttl } : {}),
+        });
+    }
+    /**
+     * @inheritdoc
+     */
+    async delete(key) {
+        await this.#ns.delete(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 { KvCacheStore } from "./store.js";

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

@@ -0,0 +1,15 @@
+import type { CacheModuleContext } from "@comity/cache/setup";
+import type { KvCacheModuleContext, KvCacheModuleOptions } from "./types.js";
+declare const _default: {
+    name: string;
+    version: string;
+    dependsOn: {
+        "@comity/cache": {
+            optional: false;
+        };
+    };
+    incompatibleWith: never[];
+    /** @inheritdoc */
+    setup: (ctx: KvCacheModuleContext & CacheModuleContext, options: KvCacheModuleOptions | 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 { KvNamespace } from "../types.js";
+/** Hooks exposed by the module */
+export type KvCacheModuleHooks = {};
+/** Events emitted by the module */
+export type KvCacheModuleEvents = {};
+/**
+ * Services exposed by the module
+ */
+export type KvCacheModuleServices = {};
+/**
+ * Context provided to the cache module setup function.
+ */
+export interface KvCacheModuleContext extends ModuleSetupContext<KvCacheModuleServices, KvCacheModuleEvents, KvCacheModuleHooks> {
+}
+/** Cache module setup options */
+export type KvCacheModuleOptions = {
+    /** Namespace to use for cache storage. */
+    ns: KvNamespace;
+};

package/dist/types/store.d.ts

@@ -0,0 +1,27 @@
+import type { CacheStore } from "@comity/cache";
+import type { KvNamespace } from "./types";
+/**
+ * A cache store implementation that uses a key-value namespace for storage.
+ */
+export declare class KvCacheStore implements CacheStore {
+    #private;
+    /**
+     * @param ns - The key-value namespace to use for caching.
+     */
+    constructor(ns: KvNamespace);
+    /**
+     * @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,14 @@
+/**
+ * Represents a namespace for key-value caching.
+ */
+export interface KvNamespace {
+    /** Retrieves a value by its key. */
+    get(key: string): Promise<string | null>;
+    /** Stores a value with an optional expiration time. */
+    put(key: string, value: string, options?: {
+        /** Time-to-live in seconds */
+        expirationTtl?: number;
+    }): Promise<void>;
+    /** Deletes a value by its key. */
+    delete(key: string): Promise<void>;
+}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@comity/cache-kv",
+  "version": "0.9.0",
+  "description": "Key-Value 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",
+    "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": {
+    "@comity/cache": "0.9.0",
+    "@comity/primitives": "0.9.0",
+    "@comity/composition": "0.9.0"
+  },
+  "dependencies": {
+    "@comity/cache": "0.9.0",
+    "@comity/composition": "0.9.0",
+    "@comity/primitives": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "typescript": "^5.9.3"
+  },
+  "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"
+  }
+}