@farm.js/cache-redis 0.1.0-beta.3

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+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,33 @@
+# @farm.js/cache-redis
+
+Redis-backed distributed cache for Farm.js applications. It provides shared cache entries,
+atomic tag invalidation, and ownership-safe regeneration leases across server instances.
+
+## Install
+
+```bash
+pnpm add @farm.js/cache-redis ioredis
+```
+
+## Configure
+
+```ts
+import { redisCache } from "@farm.js/cache-redis";
+import { defineConfig } from "@farm.js/core";
+import Redis from "ioredis";
+
+export default defineConfig({
+  cache: {
+    adapter: redisCache({
+      client: () => new Redis(process.env.REDIS_URL!),
+    }),
+    namespace: process.env.FARM_CACHE_NAMESPACE || "storefront",
+  },
+});
+```
+
+Farm uses the shared adapter for cached queries, ISR and PPR output, and tag/path invalidation.
+Application code keeps using the cache APIs from `@farm.js/core/cache`.
+
+Use a distinct namespace for each application or deployment environment. Do not put
+user-specific values in shared keys unless the key includes the user or tenant identity.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { FarmCacheAdapter } from "@farm.js/core/cache";
+export interface FarmRedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    set(key: string, value: string, expiryMode: "PX", ttlMs: number, condition: "NX"): Promise<unknown>;
+    del(key: string): Promise<number>;
+    incr(key: string): Promise<number>;
+    mget?(...keys: string[]): Promise<Array<string | null>>;
+    eval(script: string, numberOfKeys: number, ...args: string[]): Promise<unknown>;
+}
+export interface RedisCacheOptions {
+    /** Existing Redis-compatible client or a lazy client factory. */
+    client: FarmRedisClient | (() => FarmRedisClient | Promise<FarmRedisClient>);
+    /** Prefix isolating Farm cache records from other Redis data. */
+    prefix?: string;
+}
+/**
+ * Create a Redis-backed Farm cache with atomic tag versions and regeneration
+ * leases.
+ */
+export declare function redisCache(options: RedisCacheOptions): FarmCacheAdapter;
+//# 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,KAAK,EAAE,gBAAgB,EAAkB,MAAM,qBAAqB,CAAC;AAE5E,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,IAAI,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjF;AAED,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,MAAM,EAAE,eAAe,GAAG,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;IAC7E,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AASD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAqEvE"}

package/dist/index.js

@@ -0,0 +1,91 @@
+const RELEASE_LEASE_SCRIPT = `
+if redis.call("get", KEYS[1]) == ARGV[1] then
+  return redis.call("del", KEYS[1])
+end
+return 0
+`;
+/**
+ * Create a Redis-backed Farm cache with atomic tag versions and regeneration
+ * leases.
+ */
+export function redisCache(options) {
+    if (!options?.client) {
+        throw new TypeError("redisCache requires a Redis-compatible client.");
+    }
+    const prefix = normalizePrefix(options.prefix || "farm-cache");
+    let clientPromise;
+    const getClient = () => {
+        clientPromise ??= Promise.resolve(typeof options.client === "function" ? options.client() : options.client);
+        return clientPromise;
+    };
+    const key = (value) => `${prefix}:${value}`;
+    return {
+        name: "redis",
+        async get(cacheKey) {
+            const serialized = await (await getClient()).get(key(cacheKey));
+            if (serialized === null)
+                return null;
+            try {
+                return JSON.parse(serialized);
+            }
+            catch (error) {
+                throw new Error(`Redis cache entry ${JSON.stringify(cacheKey)} is not valid JSON.`, {
+                    cause: error,
+                });
+            }
+        },
+        async set(cacheKey, entry) {
+            let serialized;
+            try {
+                serialized = JSON.stringify(entry);
+            }
+            catch (error) {
+                throw new TypeError(`Redis cache entry ${JSON.stringify(cacheKey)} is not JSON serializable.`, { cause: error });
+            }
+            await (await getClient()).set(key(cacheKey), serialized);
+        },
+        async delete(cacheKey) {
+            await (await getClient()).del(key(cacheKey));
+        },
+        async getTagVersions(tags) {
+            if (tags.length === 0)
+                return {};
+            const client = await getClient();
+            const keys = tags.map((tag) => key(`tag-version:${tag}`));
+            const values = client.mget
+                ? await client.mget(...keys)
+                : await Promise.all(keys.map((tagKey) => client.get(tagKey)));
+            return Object.fromEntries(tags.map((tag, index) => [tag, normalizeVersion(values[index])]));
+        },
+        async invalidateTags(tags) {
+            const client = await getClient();
+            await Promise.all(tags.map((tag) => client.incr(key(`tag-version:${tag}`))));
+        },
+        async acquireLease(leaseKey, ttlMs) {
+            const token = createLeaseToken();
+            const result = await (await getClient()).set(key(`lease:${leaseKey}`), token, "PX", ttlMs, "NX");
+            return result === "OK" ? token : null;
+        },
+        async releaseLease(leaseKey, token) {
+            await (await getClient()).eval(RELEASE_LEASE_SCRIPT, 1, key(`lease:${leaseKey}`), token);
+        },
+    };
+}
+function normalizePrefix(value) {
+    const prefix = value.trim().replace(/:+$/g, "");
+    if (!prefix)
+        throw new TypeError("redisCache prefix cannot be empty.");
+    return prefix;
+}
+function normalizeVersion(value) {
+    if (!value)
+        return 0;
+    const version = Number(value);
+    return Number.isSafeInteger(version) && version > 0 ? version : 0;
+}
+function createLeaseToken() {
+    if (typeof globalThis.crypto?.randomUUID === "function") {
+        return globalThis.crypto.randomUUID();
+    }
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@farm.js/cache-redis",
+  "version": "0.1.0-beta.3",
+  "description": "Distributed Redis cache adapter for Farm.js",
+  "keywords": [
+    "cache",
+    "farm.js",
+    "isr",
+    "ppr",
+    "redis"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-cache-redis"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@farm.js/core": "0.1.0-beta.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}