clhq-cache-module 1.1.0-alpha.90

package/README.md

@@ -0,0 +1,47 @@
+# Clippy Cache Module
+
+Reusable NestJS module that wires Redis backed caching (via `cache-manager`) for all Clippy API services.
+
+## Features
+
+- Async Redis store bootstrap with automatic fallback to in-memory cache for local development.
+- Helper service with `get`, `set`, `del`, `delMany`, and `wrap` helpers.
+- Configurable through environment variables or module options.
+
+## Environment Variables
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `REDIS_HOST` | Redis endpoint hostname | `undefined` |
+| `REDIS_PORT` | Redis endpoint port | `6379` |
+| `REDIS_URL` | Full connection URL. Takes precedence over host/port | `undefined` |
+| `REDIS_USERNAME` | ACL user | `undefined` |
+| `REDIS_PASSWORD` | Auth token | `undefined` |
+| `REDIS_DB` | Database index | `0` |
+| `REDIS_TLS_ENABLED` | Enable TLS | `true` |
+| `REDIS_CACHE_TTL_SECONDS` | Default TTL for cache entries | `300` |
+| `REDIS_CACHE_MAX_ITEMS` | Max number of cache entries | `1000` |
+
+## Usage
+
+```ts
+import { RedisCacheModule, RedisCacheService } from 'clhq-cache-module';
+
+@Module({
+  imports: [RedisCacheModule.register()],
+  providers: [SampleService],
+})
+export class SampleModule {}
+
+@Injectable()
+export class SampleService {
+  constructor(private readonly cache: RedisCacheService) {}
+
+  async getValue(id: string) {
+    return this.cache.wrap(`sample:${id}`, async () => {
+      return this.repository.findById(id);
+    }, 600);
+  }
+}
+```
+

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './interfaces/redis-cache-options.interface';
+export * from './redis-cache.module';
+export * from './redis-cache.service';
+export * from './valkey-proxy-client';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"/","sources":["index.ts"],"names":[],"mappings":"AAAA,cAAc,4CAA4C,CAAC;AAC3D,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./interfaces/redis-cache-options.interface"), exports);
+__exportStar(require("./redis-cache.module"), exports);
+__exportStar(require("./redis-cache.service"), exports);
+__exportStar(require("./valkey-proxy-client"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"/","sources":["index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6EAA2D;AAC3D,uDAAqC;AACrC,wDAAsC;AACtC,wDAAsC","sourcesContent":["export * from './interfaces/redis-cache-options.interface';\nexport * from './redis-cache.module';\nexport * from './redis-cache.service';\nexport * from './valkey-proxy-client';\n\n"]}

package/dist/interfaces/redis-cache-options.interface.d.ts

@@ -0,0 +1,33 @@
+export interface RedisCacheModuleOptions {
+    host?: string;
+    port?: number;
+    url?: string;
+    username?: string;
+    password?: string;
+    db?: number;
+    ttlMs?: number;
+    max?: number;
+    clusterNodes?: Array<{
+        host: string;
+        port?: number;
+    }>;
+    tlsEnabled?: boolean;
+    isGlobal?: boolean;
+}
+export interface InternalRedisCacheOptions extends RedisCacheModuleOptions {
+    resolvedHost?: string;
+    resolvedPort?: number;
+    resolvedUrl?: string;
+    resolvedUsername?: string;
+    resolvedPassword?: string;
+    resolvedDb?: number;
+    resolvedTtlMs?: number;
+    resolvedMax?: number;
+    resolvedTlsEnabled?: boolean;
+    resolvedIsGlobal?: boolean;
+    resolvedClusterNodes?: Array<{
+        host: string;
+        port?: number;
+    }>;
+}
+//# sourceMappingURL=redis-cache-options.interface.d.ts.map

package/dist/interfaces/redis-cache-options.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache-options.interface.d.ts","sourceRoot":"/","sources":["interfaces/redis-cache-options.interface.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IAKtC,IAAI,CAAC,EAAE,MAAM,CAAC;IAKd,IAAI,CAAC,EAAE,MAAM,CAAC;IAId,GAAG,CAAC,EAAE,MAAM,CAAC;IAIb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAIlB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAIlB,EAAE,CAAC,EAAE,MAAM,CAAC;IAIZ,KAAK,CAAC,EAAE,MAAM,CAAC;IAIf,GAAG,CAAC,EAAE,MAAM,CAAC;IAKb,YAAY,CAAC,EAAE,KAAK,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IAIH,UAAU,CAAC,EAAE,OAAO,CAAC;IAIrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oBAAoB,CAAC,EAAE,KAAK,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;CACJ"}

package/dist/interfaces/redis-cache-options.interface.js

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

package/dist/interfaces/redis-cache-options.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache-options.interface.js","sourceRoot":"/","sources":["interfaces/redis-cache-options.interface.ts"],"names":[],"mappings":"","sourcesContent":["export interface RedisCacheModuleOptions {\n  /**\n   * Hostname for the Redis endpoint.\n   * When omitted the module falls back to REDIS_HOST env variable.\n   */\n  host?: string;\n  /**\n   * Port for the Redis endpoint.\n   * Defaults to REDIS_PORT env variable or 6379.\n   */\n  port?: number;\n  /**\n   * Full connection url. Takes precedence over host/port when provided.\n   */\n  url?: string;\n  /**\n   * Optional username for Redis ACL based auth.\n   */\n  username?: string;\n  /**\n   * Optional password/token for Redis auth.\n   */\n  password?: string;\n  /**\n   * Database index to use. Defaults to 0.\n   */\n  db?: number;\n  /**\n   * TTL for cached entries in milliseconds. Defaults to 300_000 (5 minutes).\n   */\n  ttlMs?: number;\n  /**\n   * Max number of items to keep in local memory cache.\n   */\n  max?: number;\n  /**\n   * Optional Valkey/Redis cluster nodes in host[:port] format.\n   * Takes precedence over single host/port when provided.\n   */\n  clusterNodes?: Array<{\n    host: string;\n    port?: number;\n  }>;\n  /**\n   * Enable TLS when connecting to Redis.\n   */\n  tlsEnabled?: boolean;\n  /**\n   * Whether to register the CacheModule globally.\n   */\n  isGlobal?: boolean;\n}\n\nexport interface InternalRedisCacheOptions extends RedisCacheModuleOptions {\n  resolvedHost?: string;\n  resolvedPort?: number;\n  resolvedUrl?: string;\n  resolvedUsername?: string;\n  resolvedPassword?: string;\n  resolvedDb?: number;\n  resolvedTtlMs?: number;\n  resolvedMax?: number;\n  resolvedTlsEnabled?: boolean;\n  resolvedIsGlobal?: boolean;\n  resolvedClusterNodes?: Array<{\n    host: string;\n    port?: number;\n  }>;\n}\n"]}

package/dist/redis-cache.constants.d.ts

@@ -0,0 +1,2 @@
+export declare const REDIS_CACHE_OPTIONS: unique symbol;
+//# sourceMappingURL=redis-cache.constants.d.ts.map

package/dist/redis-cache.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.constants.d.ts","sourceRoot":"/","sources":["redis-cache.constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB,eAAgC,CAAC"}

package/dist/redis-cache.constants.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REDIS_CACHE_OPTIONS = void 0;
+exports.REDIS_CACHE_OPTIONS = Symbol('REDIS_CACHE_OPTIONS');
+//# sourceMappingURL=redis-cache.constants.js.map

package/dist/redis-cache.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.constants.js","sourceRoot":"/","sources":["redis-cache.constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC","sourcesContent":["export const REDIS_CACHE_OPTIONS = Symbol('REDIS_CACHE_OPTIONS');\n\n"]}

package/dist/redis-cache.module.d.ts

@@ -0,0 +1,6 @@
+import { DynamicModule } from '@nestjs/common';
+import { RedisCacheModuleOptions } from './interfaces/redis-cache-options.interface';
+export declare class RedisCacheModule {
+    static register(options?: RedisCacheModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=redis-cache.module.d.ts.map

package/dist/redis-cache.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.module.d.ts","sourceRoot":"/","sources":["redis-cache.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAEL,uBAAuB,EACxB,MAAM,4CAA4C,CAAC;AAGpD,qBAEa,gBAAgB;IAC3B,MAAM,CAAC,QAAQ,CAAC,OAAO,GAAE,uBAA4B,GAAG,aAAa;CAatE"}

package/dist/redis-cache.module.js

@@ -0,0 +1,79 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var RedisCacheModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCacheModule = void 0;
+const common_1 = require("@nestjs/common");
+const redis_cache_service_1 = require("./redis-cache.service");
+const redis_cache_constants_1 = require("./redis-cache.constants");
+let RedisCacheModule = RedisCacheModule_1 = class RedisCacheModule {
+    static register(options = {}) {
+        const resolvedOptions = resolveOptions(options);
+        const cacheOptionsProvider = {
+            provide: redis_cache_constants_1.REDIS_CACHE_OPTIONS,
+            useValue: resolvedOptions,
+        };
+        return {
+            module: RedisCacheModule_1,
+            providers: [cacheOptionsProvider, redis_cache_service_1.RedisCacheService],
+            exports: [redis_cache_service_1.RedisCacheService],
+        };
+    }
+};
+exports.RedisCacheModule = RedisCacheModule;
+exports.RedisCacheModule = RedisCacheModule = RedisCacheModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], RedisCacheModule);
+function resolveOptions(options) {
+    return {
+        ...options,
+        resolvedClusterNodes: options.clusterNodes ??
+            parseClusterNodes(process.env.VALKEY_CLUSTER_ENDPOINTS ??
+                process.env.REDIS_CLUSTER_ENDPOINTS ??
+                ''),
+        resolvedHost: options.host,
+        resolvedPort: options.port ?? 6379,
+        resolvedUrl: options.url,
+        resolvedUsername: options.username,
+        resolvedPassword: options.password,
+        resolvedDb: options.db ?? 0,
+        resolvedTtlMs: Number(options.ttlMs ?? process.env.REDIS_CACHE_TTL_MS ?? 300000),
+        resolvedMax: Number(options.max ?? process.env.REDIS_CACHE_MAX_ITEMS ?? 1000),
+        resolvedTlsEnabled: parseBoolean(options.tlsEnabled ?? process.env.REDIS_TLS_ENABLED ?? 'true'),
+        resolvedIsGlobal: options.isGlobal ?? true,
+    };
+}
+function parseBoolean(value) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'string') {
+        return ['true', '1', 'yes'].includes(value.toLowerCase());
+    }
+    return Boolean(value);
+}
+function parseClusterNodes(value) {
+    if (!value) {
+        return undefined;
+    }
+    const nodes = value
+        .split(',')
+        .map((token) => token.trim())
+        .filter(Boolean)
+        .map((token) => {
+        const [host, port] = token.split(':');
+        return {
+            host,
+            port: port ? Number(port) : undefined,
+        };
+    })
+        .filter((node) => node.host);
+    return nodes.length ? nodes : undefined;
+}
+//# sourceMappingURL=redis-cache.module.js.map

package/dist/redis-cache.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.module.js","sourceRoot":"/","sources":["redis-cache.module.ts"],"names":[],"mappings":"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","sourcesContent":["import { DynamicModule, Global, Module } from '@nestjs/common';\nimport { RedisCacheService } from './redis-cache.service';\nimport {\n  InternalRedisCacheOptions,\n  RedisCacheModuleOptions,\n} from './interfaces/redis-cache-options.interface';\nimport { REDIS_CACHE_OPTIONS } from './redis-cache.constants';\n\n@Global()\n@Module({})\nexport class RedisCacheModule {\n  static register(options: RedisCacheModuleOptions = {}): DynamicModule {\n    const resolvedOptions = resolveOptions(options);\n    const cacheOptionsProvider = {\n      provide: REDIS_CACHE_OPTIONS,\n      useValue: resolvedOptions,\n    };\n\n    return {\n      module: RedisCacheModule,\n      providers: [cacheOptionsProvider, RedisCacheService],\n      exports: [RedisCacheService],\n    };\n  }\n}\n\nfunction resolveOptions(\n  options: RedisCacheModuleOptions,\n): InternalRedisCacheOptions {\n  return {\n    ...options,\n    resolvedClusterNodes:\n      options.clusterNodes ??\n      parseClusterNodes(\n        process.env.VALKEY_CLUSTER_ENDPOINTS ??\n          process.env.REDIS_CLUSTER_ENDPOINTS ??\n          '',\n      ),\n    resolvedHost: options.host,\n    resolvedPort: options.port ?? 6379,\n    resolvedUrl: options.url,\n    resolvedUsername: options.username,\n    resolvedPassword: options.password,\n    resolvedDb: options.db ?? 0,\n    resolvedTtlMs: Number(\n      options.ttlMs ?? process.env.REDIS_CACHE_TTL_MS ?? 300000,\n    ),\n    resolvedMax: Number(\n      options.max ?? process.env.REDIS_CACHE_MAX_ITEMS ?? 1000,\n    ),\n    resolvedTlsEnabled: parseBoolean(\n      options.tlsEnabled ?? process.env.REDIS_TLS_ENABLED ?? 'true',\n    ),\n    resolvedIsGlobal: options.isGlobal ?? true,\n  };\n}\n\nfunction parseBoolean(value: unknown): boolean {\n  if (typeof value === 'boolean') {\n    return value;\n  }\n  if (typeof value === 'string') {\n    return ['true', '1', 'yes'].includes(value.toLowerCase());\n  }\n  return Boolean(value);\n}\n\nfunction parseClusterNodes(\n  value?: string,\n): Array<{ host: string; port?: number }> | undefined {\n  if (!value) {\n    return undefined;\n  }\n  const nodes = value\n    .split(',')\n    .map((token) => token.trim())\n    .filter(Boolean)\n    .map((token) => {\n      const [host, port] = token.split(':');\n      return {\n        host,\n        port: port ? Number(port) : undefined,\n      };\n    })\n    .filter((node) => node.host);\n  return nodes.length ? nodes : undefined;\n}\n"]}

package/dist/redis-cache.service.d.ts

@@ -0,0 +1,22 @@
+import { OnModuleDestroy } from '@nestjs/common';
+import { InternalRedisCacheOptions } from './interfaces/redis-cache-options.interface';
+export declare class RedisCacheService implements OnModuleDestroy {
+    private readonly options;
+    private readonly logger;
+    private readonly redisClient?;
+    private readonly proxyClient?;
+    private readonly memoryCache;
+    constructor(options: InternalRedisCacheOptions);
+    onModuleDestroy(): Promise<void>;
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    delMany(keys: string[]): Promise<void>;
+    wrap<T>(key: string, fn: () => Promise<T>, ttlMs?: number): Promise<T>;
+    private createRedisClient;
+    private attachLogging;
+    private serialize;
+    private deserialize;
+    private enforceMemoryLimit;
+}
+//# sourceMappingURL=redis-cache.service.d.ts.map

package/dist/redis-cache.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.service.d.ts","sourceRoot":"/","sources":["redis-cache.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAG7E,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AAUvF,qBACa,iBAAkB,YAAW,eAAe;IAQrD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAkB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;gBAIhD,OAAO,EAAE,yBAAyB;IA2B/C,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAahC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAwB3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB5D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB/B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBtC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAe5E,OAAO,CAAC,iBAAiB;IAyCzB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,kBAAkB;CAS3B"}

package/dist/redis-cache.service.js

@@ -0,0 +1,197 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var RedisCacheService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCacheService = void 0;
+const common_1 = require("@nestjs/common");
+const ioredis_1 = __importDefault(require("ioredis"));
+const redis_cache_constants_1 = require("./redis-cache.constants");
+const valkey_proxy_client_1 = require("./valkey-proxy-client");
+let RedisCacheService = RedisCacheService_1 = class RedisCacheService {
+    constructor(options) {
+        this.options = options;
+        this.logger = new common_1.Logger(RedisCacheService_1.name);
+        this.memoryCache = new Map();
+        if (process.env.VALKEY_PROXY_FUNCTION_NAME) {
+            try {
+                this.proxyClient = new valkey_proxy_client_1.ValkeyProxyClient();
+                this.logger.log('Using Valkey Lambda Proxy (no VPC needed!)');
+            }
+            catch (error) {
+                this.logger.warn(`Failed to initialize Valkey proxy: ${error.message}. Falling back to in-memory cache.`);
+            }
+        }
+        else if (options.resolvedUrl ||
+            options.resolvedHost ||
+            (options.resolvedClusterNodes && options.resolvedClusterNodes.length > 0)) {
+            this.redisClient = this.createRedisClient(options);
+        }
+        else {
+            this.logger.warn('Redis connection details missing. Falling back to in-memory cache.');
+        }
+    }
+    async onModuleDestroy() {
+        if (this.redisClient) {
+            if ('quit' in this.redisClient &&
+                typeof this.redisClient.quit === 'function') {
+                await this.redisClient.quit();
+            }
+            else {
+                this.redisClient.disconnect();
+            }
+        }
+    }
+    async get(key) {
+        if (this.proxyClient) {
+            return await this.proxyClient.get(key);
+        }
+        if (this.redisClient) {
+            const payload = await this.redisClient.get(key);
+            return payload ? this.deserialize(payload) : undefined;
+        }
+        const entry = this.memoryCache.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt && entry.expiresAt <= Date.now()) {
+            this.memoryCache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    async set(key, value, ttlMs) {
+        const ttl = ttlMs ?? this.options.resolvedTtlMs;
+        if (this.proxyClient) {
+            await this.proxyClient.set(key, value, ttl);
+            return;
+        }
+        if (this.redisClient) {
+            const serialized = this.serialize(value);
+            if (ttl) {
+                await this.redisClient.set(key, serialized, 'PX', ttl);
+            }
+            else {
+                await this.redisClient.set(key, serialized);
+            }
+            return;
+        }
+        const expiresAt = ttl ? Date.now() + ttl : undefined;
+        this.memoryCache.set(key, { value, expiresAt });
+        this.enforceMemoryLimit();
+    }
+    async del(key) {
+        if (this.proxyClient) {
+            await this.proxyClient.del(key);
+            return;
+        }
+        if (this.redisClient) {
+            await this.redisClient.del(key);
+            return;
+        }
+        this.memoryCache.delete(key);
+    }
+    async delMany(keys) {
+        if (this.proxyClient) {
+            await this.proxyClient.delMany(keys);
+            return;
+        }
+        if (this.redisClient) {
+            if (keys.length > 0) {
+                await this.redisClient.del(...keys);
+            }
+            return;
+        }
+        keys.forEach((key) => this.memoryCache.delete(key));
+    }
+    async wrap(key, fn, ttlMs) {
+        const cached = await this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const value = await fn();
+        if (value !== undefined) {
+            await this.set(key, value, ttlMs);
+        }
+        else {
+            this.logger.warn(`Computed cache value for key ${key} is undefined`);
+        }
+        return value;
+    }
+    createRedisClient(options) {
+        const clusterNodes = options.resolvedClusterNodes;
+        if (clusterNodes && clusterNodes.length > 0) {
+            const nodes = clusterNodes.map((node) => ({
+                host: node.host,
+                port: node.port ?? options.resolvedPort ?? 6379,
+            }));
+            const client = new ioredis_1.default.Cluster(nodes, {
+                dnsLookup: (address, callback) => callback(null, address),
+                redisOptions: {
+                    username: options.resolvedUsername,
+                    password: options.resolvedPassword,
+                    db: options.resolvedDb,
+                    tls: options.resolvedTlsEnabled ? {} : undefined,
+                },
+            });
+            this.attachLogging(client);
+            return client;
+        }
+        const client = options.resolvedUrl
+            ? new ioredis_1.default(options.resolvedUrl, options.resolvedTlsEnabled ? { tls: {} } : undefined)
+            : new ioredis_1.default({
+                host: options.resolvedHost,
+                port: options.resolvedPort,
+                username: options.resolvedUsername,
+                password: options.resolvedPassword,
+                db: options.resolvedDb,
+                tls: options.resolvedTlsEnabled ? {} : undefined,
+            });
+        this.attachLogging(client);
+        return client;
+    }
+    attachLogging(client) {
+        client.on('error', (err) => this.logger.error(`Redis cache connection error: ${err.message}`, err.stack));
+        client.on('ready', () => this.logger.log('Redis/Valkey cache connection ready'));
+    }
+    serialize(value) {
+        return JSON.stringify(value);
+    }
+    deserialize(payload) {
+        try {
+            return JSON.parse(payload);
+        }
+        catch (error) {
+            this.logger.error(`Failed to deserialize cached value: ${error.message}`);
+            return undefined;
+        }
+    }
+    enforceMemoryLimit() {
+        if (this.memoryCache.size <= this.options.resolvedMax) {
+            return;
+        }
+        const oldestKey = this.memoryCache.keys().next().value;
+        if (oldestKey) {
+            this.memoryCache.delete(oldestKey);
+        }
+    }
+};
+exports.RedisCacheService = RedisCacheService;
+exports.RedisCacheService = RedisCacheService = RedisCacheService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(redis_cache_constants_1.REDIS_CACHE_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], RedisCacheService);
+//# sourceMappingURL=redis-cache.service.js.map

package/dist/redis-cache.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-cache.service.js","sourceRoot":"/","sources":["redis-cache.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { Inject, Injectable, Logger, OnModuleDestroy } from '@nestjs/common';\nimport Redis, { Cluster } from 'ioredis';\nimport { REDIS_CACHE_OPTIONS } from './redis-cache.constants';\nimport { InternalRedisCacheOptions } from './interfaces/redis-cache-options.interface';\nimport { ValkeyProxyClient } from './valkey-proxy-client';\n\ntype MemoryCacheEntry = {\n  value: unknown;\n  expiresAt?: number;\n};\n\ntype RedisLikeClient = Redis | Cluster;\n\n@Injectable()\nexport class RedisCacheService implements OnModuleDestroy {\n  private readonly logger = new Logger(RedisCacheService.name);\n  private readonly redisClient?: RedisLikeClient;\n  private readonly proxyClient?: ValkeyProxyClient;\n  private readonly memoryCache = new Map<string, MemoryCacheEntry>();\n\n  constructor(\n    @Inject(REDIS_CACHE_OPTIONS)\n    private readonly options: InternalRedisCacheOptions,\n  ) {\n    // Check if we should use Lambda proxy (for VPC-less access to Valkey)\n    if (process.env.VALKEY_PROXY_FUNCTION_NAME) {\n      try {\n        this.proxyClient = new ValkeyProxyClient();\n        this.logger.log('Using Valkey Lambda Proxy (no VPC needed!)');\n      } catch (error) {\n        this.logger.warn(\n          `Failed to initialize Valkey proxy: ${error.message}. Falling back to in-memory cache.`,\n        );\n      }\n    }\n    // Otherwise use direct connection (requires VPC)\n    else if (\n      options.resolvedUrl ||\n      options.resolvedHost ||\n      (options.resolvedClusterNodes && options.resolvedClusterNodes.length > 0)\n    ) {\n      this.redisClient = this.createRedisClient(options);\n    } else {\n      this.logger.warn(\n        'Redis connection details missing. Falling back to in-memory cache.',\n      );\n    }\n  }\n\n  async onModuleDestroy(): Promise<void> {\n    if (this.redisClient) {\n      if (\n        'quit' in this.redisClient &&\n        typeof this.redisClient.quit === 'function'\n      ) {\n        await this.redisClient.quit();\n      } else {\n        this.redisClient.disconnect();\n      }\n    }\n  }\n\n  async get<T>(key: string): Promise<T | undefined> {\n    // Use Lambda proxy if available\n    if (this.proxyClient) {\n      return await this.proxyClient.get<T>(key);\n    }\n\n    // Use direct Redis connection\n    if (this.redisClient) {\n      const payload = await this.redisClient.get(key);\n      return payload ? this.deserialize<T>(payload) : undefined;\n    }\n\n    // Fall back to in-memory cache\n    const entry = this.memoryCache.get(key);\n    if (!entry) return undefined;\n\n    if (entry.expiresAt && entry.expiresAt <= Date.now()) {\n      this.memoryCache.delete(key);\n      return undefined;\n    }\n\n    return entry.value as T;\n  }\n\n  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {\n    const ttl = ttlMs ?? this.options.resolvedTtlMs;\n\n    // Use Lambda proxy if available\n    if (this.proxyClient) {\n      await this.proxyClient.set(key, value, ttl);\n      return;\n    }\n\n    // Use direct Redis connection\n    if (this.redisClient) {\n      const serialized = this.serialize(value);\n      if (ttl) {\n        await this.redisClient.set(key, serialized, 'PX', ttl);\n      } else {\n        await this.redisClient.set(key, serialized);\n      }\n      return;\n    }\n\n    const expiresAt = ttl ? Date.now() + ttl : undefined;\n    this.memoryCache.set(key, { value, expiresAt });\n    this.enforceMemoryLimit();\n  }\n\n  async del(key: string): Promise<void> {\n    // Use Lambda proxy if available\n    if (this.proxyClient) {\n      await this.proxyClient.del(key);\n      return;\n    }\n\n    // Use direct Redis connection\n    if (this.redisClient) {\n      await this.redisClient.del(key);\n      return;\n    }\n\n    // Fall back to in-memory cache\n    this.memoryCache.delete(key);\n  }\n\n  async delMany(keys: string[]): Promise<void> {\n    // Use Lambda proxy if available\n    if (this.proxyClient) {\n      await this.proxyClient.delMany(keys);\n      return;\n    }\n\n    // Use direct Redis connection\n    if (this.redisClient) {\n      if (keys.length > 0) {\n        await this.redisClient.del(...keys);\n      }\n      return;\n    }\n\n    // Fall back to in-memory cache\n    keys.forEach((key) => this.memoryCache.delete(key));\n  }\n\n  async wrap<T>(key: string, fn: () => Promise<T>, ttlMs?: number): Promise<T> {\n    const cached = await this.get<T>(key);\n    if (cached !== undefined) {\n      return cached;\n    }\n\n    const value = await fn();\n    if (value !== undefined) {\n      await this.set(key, value, ttlMs);\n    } else {\n      this.logger.warn(`Computed cache value for key ${key} is undefined`);\n    }\n    return value;\n  }\n\n  private createRedisClient(\n    options: InternalRedisCacheOptions,\n  ): RedisLikeClient {\n    const clusterNodes = options.resolvedClusterNodes;\n    if (clusterNodes && clusterNodes.length > 0) {\n      const nodes = clusterNodes.map((node) => ({\n        host: node.host,\n        port: node.port ?? options.resolvedPort ?? 6379,\n      }));\n      const client = new Redis.Cluster(nodes, {\n        dnsLookup: (address, callback) => callback(null, address),\n        redisOptions: {\n          username: options.resolvedUsername,\n          password: options.resolvedPassword,\n          db: options.resolvedDb,\n          tls: options.resolvedTlsEnabled ? {} : undefined,\n        },\n      });\n      this.attachLogging(client);\n      return client;\n    }\n\n    const client = options.resolvedUrl\n      ? new Redis(\n          options.resolvedUrl,\n          options.resolvedTlsEnabled ? { tls: {} } : undefined,\n        )\n      : new Redis({\n          host: options.resolvedHost,\n          port: options.resolvedPort,\n          username: options.resolvedUsername,\n          password: options.resolvedPassword,\n          db: options.resolvedDb,\n          tls: options.resolvedTlsEnabled ? {} : undefined,\n        });\n\n    this.attachLogging(client);\n\n    return client;\n  }\n\n  private attachLogging(client: RedisLikeClient): void {\n    client.on('error', (err: Error) =>\n      this.logger.error(\n        `Redis cache connection error: ${err.message}`,\n        err.stack,\n      ),\n    );\n\n    client.on('ready', () =>\n      this.logger.log('Redis/Valkey cache connection ready'),\n    );\n  }\n\n  private serialize(value: unknown): string {\n    return JSON.stringify(value);\n  }\n\n  private deserialize<T>(payload: string): T | undefined {\n    try {\n      return JSON.parse(payload) as T;\n    } catch (error) {\n      this.logger.error(\n        `Failed to deserialize cached value: ${(error as Error).message}`,\n      );\n      return undefined;\n    }\n  }\n\n  private enforceMemoryLimit(): void {\n    if (this.memoryCache.size <= this.options.resolvedMax) {\n      return;\n    }\n    const oldestKey = this.memoryCache.keys().next().value;\n    if (oldestKey) {\n      this.memoryCache.delete(oldestKey);\n    }\n  }\n}\n"]}

package/dist/valkey-proxy-client.d.ts

@@ -0,0 +1,10 @@
+export declare class ValkeyProxyClient {
+    private functionName;
+    constructor();
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    delMany(keys: string[]): Promise<void>;
+    private invoke;
+}
+//# sourceMappingURL=valkey-proxy-client.d.ts.map

package/dist/valkey-proxy-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valkey-proxy-client.d.ts","sourceRoot":"/","sources":["valkey-proxy-client.ts"],"names":[],"mappings":"AAoBA,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,YAAY,CAAS;;IASvB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAK3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAI9B,MAAM;CAsBrB"}

package/dist/valkey-proxy-client.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValkeyProxyClient = void 0;
+const client_lambda_1 = require("@aws-sdk/client-lambda");
+const lambdaClient = new client_lambda_1.Lambda({
+    region: process.env.CLIPPY_AWS_DEFAULT_REGION || 'ap-southeast-2',
+});
+class ValkeyProxyClient {
+    constructor() {
+        this.functionName = process.env.VALKEY_PROXY_FUNCTION_NAME;
+        if (!this.functionName) {
+            throw new Error('VALKEY_PROXY_FUNCTION_NAME environment variable not set');
+        }
+    }
+    async get(key) {
+        const response = await this.invoke({ operation: 'get', key });
+        return response.value;
+    }
+    async set(key, value, ttlMs) {
+        await this.invoke({ operation: 'set', key, value, ttlMs });
+    }
+    async del(key) {
+        await this.invoke({ operation: 'del', key });
+    }
+    async delMany(keys) {
+        await this.invoke({ operation: 'delMany', keys });
+    }
+    async invoke(payload) {
+        try {
+            const result = await lambdaClient.invoke({
+                FunctionName: this.functionName,
+                InvocationType: 'RequestResponse',
+                Payload: Buffer.from(JSON.stringify(payload)),
+            });
+            const responsePayload = JSON.parse(new TextDecoder().decode(result.Payload));
+            if (!responsePayload.success) {
+                throw new Error(`Valkey proxy error: ${responsePayload.error}`);
+            }
+            return responsePayload;
+        }
+        catch (error) {
+            console.error('Failed to invoke valkey-proxy:', error);
+            throw error;
+        }
+    }
+}
+exports.ValkeyProxyClient = ValkeyProxyClient;
+//# sourceMappingURL=valkey-proxy-client.js.map

package/dist/valkey-proxy-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"valkey-proxy-client.js","sourceRoot":"/","sources":["valkey-proxy-client.ts"],"names":[],"mappings":";;;AAAA,0DAAgD;AAEhD,MAAM,YAAY,GAAG,IAAI,sBAAM,CAAC;IAC9B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,gBAAgB;CAClE,CAAC,CAAC;AAgBH,MAAa,iBAAiB;IAG5B;QACE,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;QAC3D,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC7E,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,GAAW;QACtB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QAC9D,OAAO,QAAQ,CAAC,KAAU,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,KAAc;QAChD,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAc;QAC1B,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,OAAqB;QACxC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC;gBACvC,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,cAAc,EAAE,iBAAiB;gBACjC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;aAC9C,CAAC,CAAC;YAEH,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAChC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CACxB,CAAC;YAEnB,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,uBAAuB,eAAe,CAAC,KAAK,EAAE,CAAC,CAAC;YAClE,CAAC;YAED,OAAO,eAAe,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE,KAAK,CAAC,CAAC;YACvD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF;AAjDD,8CAiDC","sourcesContent":["import { Lambda } from '@aws-sdk/client-lambda';\n\nconst lambdaClient = new Lambda({\n  region: process.env.CLIPPY_AWS_DEFAULT_REGION || 'ap-southeast-2',\n});\n\ninterface CacheRequest {\n  operation: 'get' | 'set' | 'del' | 'delMany';\n  key?: string;\n  keys?: string[];\n  value?: unknown;\n  ttlMs?: number;\n}\n\ninterface CacheResponse {\n  success: boolean;\n  value?: unknown;\n  error?: string;\n}\n\nexport class ValkeyProxyClient {\n  private functionName: string;\n\n  constructor() {\n    this.functionName = process.env.VALKEY_PROXY_FUNCTION_NAME;\n    if (!this.functionName) {\n      throw new Error('VALKEY_PROXY_FUNCTION_NAME environment variable not set');\n    }\n  }\n\n  async get<T>(key: string): Promise<T | undefined> {\n    const response = await this.invoke({ operation: 'get', key });\n    return response.value as T;\n  }\n\n  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {\n    await this.invoke({ operation: 'set', key, value, ttlMs });\n  }\n\n  async del(key: string): Promise<void> {\n    await this.invoke({ operation: 'del', key });\n  }\n\n  async delMany(keys: string[]): Promise<void> {\n    await this.invoke({ operation: 'delMany', keys });\n  }\n\n  private async invoke(payload: CacheRequest): Promise<CacheResponse> {\n    try {\n      const result = await lambdaClient.invoke({\n        FunctionName: this.functionName,\n        InvocationType: 'RequestResponse',\n        Payload: Buffer.from(JSON.stringify(payload)),\n      });\n\n      const responsePayload = JSON.parse(\n        new TextDecoder().decode(result.Payload),\n      ) as CacheResponse;\n\n      if (!responsePayload.success) {\n        throw new Error(`Valkey proxy error: ${responsePayload.error}`);\n      }\n\n      return responsePayload;\n    } catch (error) {\n      console.error('Failed to invoke valkey-proxy:', error);\n      throw error;\n    }\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "clhq-cache-module",
+  "version": "1.1.0-alpha.90",
+  "description": "Reusable Redis cache module for NestJS services in the Clippy stack.",
+  "author": "Clippy Engineering",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/reacthub-pricematch/clhq-api-monorepo"
+  },
+  "registry": "https://registry.npmjs.org/",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/reacthub-pricematch/clhq-api-monorepo/issues"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "yarn exec tsc -p tsconfig.json",
+    "clean:dist": "rimraf dist",
+    "clean:all": "yarn run clean:dist",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint \"src/**/*.ts\" --fix",
+    "version:upgrade:alpha": "standard-version --prerelease alpha",
+    "release": "npm publish --tag alpha",
+    "release:alpha": "npm publish --tag alpha",
+    "release:prealpha": "",
+    "clean:build": "rimraf .build",
+    "clean:webpack": "rimraf .webpack",
+    "clean:serverless": "rimraf .serverless",
+    "sls:deploy": "sls deploy",
+    "sls:deploy:dev": "env-cmd -f ../../.env.dev sls deploy --stage dev",
+    "sls:remove:dev": "env-cmd -f ../../.env.dev sls remove --stage dev",
+    "sls:offline": "sls offline",
+    "sls:package": "sls package",
+    "sls:package2": "npm run clean:all&& npm run sls:package",
+    "sls:remove": "sls remove"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=11.0.0"
+  },
+  "dependencies": {
+    "ioredis": "^5.4.1"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.5",
+    "@nestjs/platform-express": "^11.1.5",
+    "class-transformer": "0.5.1",
+    "class-validator": "0.14.2",
+    "prettier": "^3.6.1",
+    "rimraf": "^6.0.1",
+    "standard-version": "^9.5.0",
+    "typescript": "^5.8.3"
+  }
+}