@holo-js/cache-redis 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import { CacheDriverContract, CacheLockContract } from '@holo-js/cache';
+
+type RedisClusterNode = {
+    readonly url: string;
+    readonly host?: never;
+    readonly port?: never;
+} | {
+    readonly url?: never;
+    readonly host: string;
+    readonly port: number;
+};
+type RedisCacheDriverOptions = {
+    readonly name: string;
+    readonly connectionName: string;
+    readonly prefix: string;
+    readonly redis: {
+        readonly username?: string;
+        readonly password?: string;
+    } & ({
+        readonly db: number;
+        readonly url?: never;
+        readonly clusters?: never;
+        readonly socketPath?: never;
+        readonly host: string;
+        readonly port: number;
+    } | {
+        readonly db: number;
+        readonly url: string;
+        readonly clusters?: never;
+        readonly socketPath?: never;
+        readonly host?: string;
+        readonly port?: number;
+    } | {
+        readonly db: 0;
+        readonly clusters: readonly RedisClusterNode[];
+        readonly url?: never;
+        readonly socketPath?: never;
+        readonly host?: string;
+        readonly port?: number;
+    } | {
+        readonly db: number;
+        readonly url?: never;
+        readonly clusters?: never;
+        readonly socketPath: string;
+        readonly host?: never;
+        readonly port?: never;
+    });
+    readonly now?: () => number;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+    readonly ownerFactory?: () => string;
+};
+type RedisClientOptions = {
+    readonly host?: string;
+    readonly port?: number;
+    readonly path?: string;
+    readonly password?: string;
+    readonly username?: string;
+    readonly db?: number;
+    readonly connectionName?: string;
+    readonly lazyConnect: true;
+    readonly maxRetriesPerRequest: number;
+    readonly tls?: Record<string, never>;
+};
+type RedisClusterStartupNode = {
+    readonly host: string;
+    readonly port: number;
+    readonly tls?: Record<string, never>;
+};
+type RedisClusterOptions = {
+    readonly redisOptions: RedisClientOptions;
+};
+type RedisClientLike = {
+    readonly isCluster?: boolean;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...arguments_: readonly (string | number)[]): Promise<'OK' | null>;
+    del(...keys: string[]): Promise<number>;
+    scan(cursor: string, matchLabel: string, pattern: string, countLabel: string, count: number): Promise<[string, string[]]>;
+    incrby(key: string, amount: number): Promise<number>;
+    decrby(key: string, amount: number): Promise<number>;
+    eval(script: string, numberOfKeys: number, ...arguments_: readonly string[]): Promise<number>;
+    nodes?(role: 'master'): readonly RedisClientLike[];
+};
+declare function isRedisSocketConnectionTarget(value: string): boolean;
+declare function toRedisSocketPath(value: string): string;
+declare function escapeRedisGlob(value: string): string;
+declare function createRedisClientOptions(options: RedisCacheDriverOptions): RedisClientOptions;
+declare function parseClusterNodeUrl(url: string, label: string): RedisClusterStartupNode;
+declare function resolveClusterStartupNodes(options: RedisCacheDriverOptions): readonly RedisClusterStartupNode[];
+declare function createRedisClusterOptions(options: RedisCacheDriverOptions): RedisClusterOptions;
+declare function createRedisClient(options: RedisCacheDriverOptions): RedisClientLike;
+declare function toLockTtlMilliseconds(seconds: number): number;
+declare function isRedisNumericMutationError(error: unknown): error is Error;
+declare function createRedisLock(client: RedisClientLike, name: string, seconds: number, ownerFactory: () => string, sleep: (milliseconds: number) => Promise<void>, now: () => number): CacheLockContract;
+declare function createRedisCacheDriver(options: RedisCacheDriverOptions): CacheDriverContract;
+declare const redisCacheDriverInternals: {
+    createRedisClient: typeof createRedisClient;
+    createRedisClientOptions: typeof createRedisClientOptions;
+    createRedisClusterOptions: typeof createRedisClusterOptions;
+    createRedisLock: typeof createRedisLock;
+    escapeRedisGlob: typeof escapeRedisGlob;
+    isRedisSocketConnectionTarget: typeof isRedisSocketConnectionTarget;
+    isRedisNumericMutationError: typeof isRedisNumericMutationError;
+    parseClusterNodeUrl: typeof parseClusterNodeUrl;
+    resolveClusterStartupNodes: typeof resolveClusterStartupNodes;
+    toLockTtlMilliseconds: typeof toLockTtlMilliseconds;
+    toRedisSocketPath: typeof toRedisSocketPath;
+};
+
+export { type RedisCacheDriverOptions, createRedisCacheDriver, redisCacheDriverInternals };

package/dist/index.mjs

@@ -0,0 +1,275 @@
+// src/index.ts
+import { randomUUID } from "crypto";
+import Redis from "ioredis";
+import {
+  CacheInvalidNumericMutationError
+} from "@holo-js/cache";
+var REDIS_SCAN_COUNT = 100;
+var RELEASE_LOCK_SCRIPT = [
+  'if redis.call("get", KEYS[1]) == ARGV[1] then',
+  '  return redis.call("del", KEYS[1])',
+  "end",
+  "return 0"
+].join("\n");
+function defaultSleep(milliseconds) {
+  return new Promise((resolveDelay) => {
+    setTimeout(resolveDelay, milliseconds);
+  });
+}
+function isRedisSocketConnectionTarget(value) {
+  return value.startsWith("unix://") || value.startsWith("/");
+}
+function toRedisSocketPath(value) {
+  return value.startsWith("unix://") ? value.slice("unix://".length) : value;
+}
+function escapeRedisGlob(value) {
+  return value.replace(/[\\*?[\]]/g, (match) => `\\${match}`);
+}
+function isRedisUrl(value) {
+  return value.startsWith("redis://") || value.startsWith("rediss://");
+}
+function createRedisClientOptions(options) {
+  return {
+    password: options.redis.password,
+    username: options.redis.username,
+    db: options.redis.db,
+    ...typeof options.redis.url === "undefined" && !options.redis.clusters?.length && typeof options.redis.socketPath === "string" ? { path: options.redis.socketPath } : typeof options.redis.url === "undefined" && !options.redis.clusters?.length && typeof options.redis.host === "string" && isRedisSocketConnectionTarget(options.redis.host) ? { path: toRedisSocketPath(options.redis.host) } : typeof options.redis.url === "undefined" && !options.redis.clusters?.length ? {
+      host: options.redis.host,
+      port: options.redis.port
+    } : {},
+    ...typeof options.redis.url === "undefined" && !options.redis.clusters?.length && !isRedisUrl(options.connectionName) ? { connectionName: options.connectionName } : {},
+    lazyConnect: true,
+    maxRetriesPerRequest: 3
+  };
+}
+function parseClusterNodeUrl(url, label) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "redis:" && parsed.protocol !== "rediss:") {
+      throw new Error(`unsupported protocol "${parsed.protocol}"`);
+    }
+    if (!parsed.hostname) {
+      throw new Error("missing hostname");
+    }
+    if (parsed.username || parsed.password || parsed.pathname && parsed.pathname !== "/") {
+      throw new Error("cluster node URLs must not include credentials or a Redis database/path; supply those via redisOptions instead");
+    }
+    return {
+      host: parsed.hostname,
+      port: parsed.port ? Number.parseInt(parsed.port, 10) : 6379,
+      ...parsed.protocol === "rediss:" ? { tls: {} } : {}
+    };
+  } catch (error) {
+    throw new Error(
+      `[@holo-js/cache-redis] ${label} is invalid: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function resolveClusterStartupNodes(options) {
+  return (options.redis.clusters ?? []).map((node, index) => {
+    const label = `Cache Redis cluster node ${index + 1}`;
+    if (typeof node.url === "string") {
+      return parseClusterNodeUrl(node.url, `${label} url`);
+    }
+    const socketPath = "socketPath" in node ? node.socketPath : void 0;
+    if (typeof socketPath === "string" || isRedisSocketConnectionTarget(node.host)) {
+      throw new Error(`[@holo-js/cache-redis] ${label} cannot use a Unix socket path in Redis cluster mode.`);
+    }
+    return {
+      host: node.host,
+      port: node.port
+    };
+  });
+}
+function createRedisClusterOptions(options) {
+  if (options.redis.db !== 0) {
+    throw new Error("[@holo-js/cache-redis] Redis Cluster does not support selecting a non-zero database. Remove redis.db or set it to 0.");
+  }
+  const startupNodes = resolveClusterStartupNodes(options);
+  return {
+    redisOptions: {
+      password: options.redis.password,
+      username: options.redis.username,
+      lazyConnect: true,
+      maxRetriesPerRequest: 3,
+      ...startupNodes.some((node) => typeof node.tls !== "undefined") ? { tls: {} } : {}
+    }
+  };
+}
+function createRedisClient(options) {
+  const RedisConstructor = Redis;
+  const clientOptions = createRedisClientOptions(options);
+  const hasStandaloneUrl = typeof options.redis.url === "string";
+  const hasClusters = !!options.redis.clusters?.length;
+  if (hasStandaloneUrl && hasClusters) {
+    throw new Error("[@holo-js/cache-redis] Configure either redis.url or redis.clusters, but not both.");
+  }
+  if (hasStandaloneUrl) {
+    return new RedisConstructor(options.redis.url, clientOptions);
+  }
+  if (hasClusters) {
+    return new RedisConstructor.Cluster(
+      resolveClusterStartupNodes(options),
+      createRedisClusterOptions(options)
+    );
+  }
+  return new RedisConstructor(clientOptions);
+}
+function toLockTtlMilliseconds(seconds) {
+  return Math.max(1, Math.round(seconds * 1e3));
+}
+function isRedisNumericMutationError(error) {
+  return error instanceof Error && (error.message.includes("value is not an integer or out of range") || error.message.includes("WRONGTYPE"));
+}
+function createRedisLock(client, name, seconds, ownerFactory, sleep, now) {
+  const owner = ownerFactory();
+  async function tryAcquire() {
+    return await client.set(name, owner, "PX", toLockTtlMilliseconds(seconds), "NX") === "OK";
+  }
+  async function withCallback(callback) {
+    if (!callback) {
+      return true;
+    }
+    try {
+      return await callback();
+    } finally {
+      await lock.release();
+    }
+  }
+  const lock = {
+    name,
+    async get(callback) {
+      if (!await tryAcquire()) {
+        return false;
+      }
+      return withCallback(callback);
+    },
+    async release() {
+      return await client.eval(RELEASE_LOCK_SCRIPT, 1, name, owner) === 1;
+    },
+    async block(waitSeconds, callback) {
+      const deadline = now() + Math.max(0, Math.round(waitSeconds * 1e3));
+      while (true) {
+        if (await tryAcquire()) {
+          return withCallback(callback);
+        }
+        if (now() >= deadline) {
+          return false;
+        }
+        await sleep(10);
+      }
+    }
+  };
+  return lock;
+}
+function createRedisCacheDriver(options) {
+  const client = createRedisClient(options);
+  const sleep = options.sleep ?? defaultSleep;
+  const ownerFactory = options.ownerFactory ?? randomUUID;
+  const now = options.now ?? Date.now;
+  const flushPattern = `${escapeRedisGlob(options.prefix)}*`;
+  async function flushClient(target) {
+    let cursor = "0";
+    do {
+      const [nextCursor, keys] = await target.scan(cursor, "MATCH", flushPattern, "COUNT", REDIS_SCAN_COUNT);
+      cursor = nextCursor;
+      if (keys.length > 0) {
+        await Promise.all(keys.map(async (key) => target.del(key)));
+      }
+    } while (cursor !== "0");
+  }
+  return {
+    name: options.name,
+    driver: "redis",
+    async get(key) {
+      const payload = await client.get(key);
+      if (payload === null) {
+        return Object.freeze({ hit: false });
+      }
+      return Object.freeze({
+        hit: true,
+        payload
+      });
+    },
+    async put(input) {
+      if (typeof input.expiresAt === "number" && input.expiresAt <= now()) {
+        await client.del(input.key);
+        return true;
+      }
+      if (typeof input.expiresAt === "number") {
+        await client.set(input.key, input.payload, "PXAT", input.expiresAt);
+        return true;
+      }
+      await client.set(input.key, input.payload);
+      return true;
+    },
+    async add(input) {
+      if (typeof input.expiresAt === "number" && input.expiresAt <= now()) {
+        await client.del(input.key);
+        return true;
+      }
+      if (typeof input.expiresAt === "number") {
+        return await client.set(input.key, input.payload, "PXAT", input.expiresAt, "NX") === "OK";
+      }
+      return await client.set(input.key, input.payload, "NX") === "OK";
+    },
+    async forget(key) {
+      return await client.del(key) > 0;
+    },
+    async flush() {
+      if (client.isCluster) {
+        for (const node of client.nodes?.("master") ?? []) {
+          await flushClient(node);
+        }
+        return;
+      }
+      await flushClient(client);
+    },
+    async increment(key, amount) {
+      try {
+        return await client.incrby(key, amount);
+      } catch (error) {
+        if (!isRedisNumericMutationError(error)) {
+          throw error;
+        }
+        throw new CacheInvalidNumericMutationError(
+          `[@holo-js/cache] Cache key "${key}" does not contain a numeric value.`,
+          { cause: error }
+        );
+      }
+    },
+    async decrement(key, amount) {
+      try {
+        return await client.decrby(key, amount);
+      } catch (error) {
+        if (!isRedisNumericMutationError(error)) {
+          throw error;
+        }
+        throw new CacheInvalidNumericMutationError(
+          `[@holo-js/cache] Cache key "${key}" does not contain a numeric value.`,
+          { cause: error }
+        );
+      }
+    },
+    lock(name, seconds) {
+      return createRedisLock(client, name, seconds, ownerFactory, sleep, now);
+    }
+  };
+}
+var redisCacheDriverInternals = {
+  createRedisClient,
+  createRedisClientOptions,
+  createRedisClusterOptions,
+  createRedisLock,
+  escapeRedisGlob,
+  isRedisSocketConnectionTarget,
+  isRedisNumericMutationError,
+  parseClusterNodeUrl,
+  resolveClusterStartupNodes,
+  toLockTtlMilliseconds,
+  toRedisSocketPath
+};
+export {
+  createRedisCacheDriver,
+  redisCacheDriverInternals
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@holo-js/cache-redis",
+  "version": "0.1.3",
+  "description": "Holo-JS Framework - Redis cache driver",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "stub": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest --run"
+  },
+  "peerDependencies": {
+    "@holo-js/cache": "^0.1.3"
+  },
+  "dependencies": {
+    "ioredis": "catalog:",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@holo-js/cache": "workspace:*",
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}