@scpxl/nodejs-framework 1.0.22 → 1.0.25

package/dist/cache/manager.d.ts

@@ -0,0 +1,107 @@
+import type RedisManager from '../redis/manager.js';
+/**
+ * CacheManager
+ *
+ * Thin abstraction over Redis for basic JSON value caching. Unifies all Redis
+ * access through the framework RedisManager / RedisInstance (ioredis) so we
+ * avoid maintaining a second client implementation (node-redis).
+ *
+ * Lazy acquisition: the first call to any cache method will either reuse an
+ * existing connected RedisInstance (if already established by application
+ * startup) or trigger a connection via RedisManager.
+ *
+ * **Important:** All values are stored as JSON strings. Only JSON-serializable
+ * values are supported. Complex types like Date, Map, Set, RegExp, etc. will
+ * lose their type information during serialization:
+ * - `Date` objects → ISO strings
+ * - `Map` / `Set` → empty objects `{}`
+ * - `undefined` → omitted from objects, `null` in arrays
+ * - Functions → omitted
+ *
+ * @example
+ * ```typescript
+ * // Supported types
+ * await cache.setItem({ key: 'user', value: { id: 1, name: 'John' } }); // ✓
+ * await cache.setItem({ key: 'count', value: 42 }); // ✓
+ * await cache.setItem({ key: 'tags', value: ['a', 'b', 'c'] }); // ✓
+ *
+ * // Unsupported types (will lose type information)
+ * await cache.setItem({ key: 'date', value: new Date() }); // → ISO string
+ * await cache.setItem({ key: 'map', value: new Map() }); // → {}
+ * ```
+ */
+export interface CacheManagerProps {
+    /** Redis manager (shared across the application) */
+    redisManager: RedisManager;
+}
+export default class CacheManager {
+    private redisManager;
+    private redisInstance?;
+    constructor({ redisManager }: CacheManagerProps);
+    /**
+     * Ensure we have a connected RedisInstance. Reuses the first existing
+     * instance if already connected by the application bootstrap.
+     */
+    private getRedisInstance;
+    /**
+     * Get a cached JSON value (deserialized) or null if not present.
+     *
+     * @param key - Cache key
+     * @returns Deserialized value or null if not found
+     * @throws {Error} If the cached value is not valid JSON
+     *
+     * @example
+     * ```typescript
+     * const user = await cache.getItem<{ id: number; name: string }>({ key: 'user:123' });
+     * if (user) {
+     *   console.log(user.name);
+     * }
+     * ```
+     */
+    getItem<T>({ key }: {
+        key: string;
+    }): Promise<T | null>;
+    /**
+     * Set a JSON-serializable value. Optionally specify lifetime (seconds).
+     *
+     * @param key - Cache key
+     * @param value - Value to cache (must be JSON-serializable)
+     * @param lifetime - Optional expiration in seconds
+     *
+     * @example
+     * ```typescript
+     * // Cache with no expiration
+     * await cache.setItem({ key: 'config', value: { theme: 'dark' } });
+     *
+     * // Cache with 1 hour expiration
+     * await cache.setItem({
+     *   key: 'session:abc',
+     *   value: { userId: 123 },
+     *   lifetime: 3600
+     * });
+     * ```
+     */
+    setItem<T>({ key, value, lifetime }: {
+        key: string;
+        value: T;
+        lifetime?: number;
+    }): Promise<void>;
+    /**
+     * Delete a cached value.
+     *
+     * @param key - Cache key to delete
+     *
+     * @example
+     * ```typescript
+     * await cache.clearItem({ key: 'session:abc' });
+     * ```
+     */
+    clearItem({ key }: {
+        key: string;
+    }): Promise<void>;
+    /**
+     * No-op: lifecycle handles Redis disconnection globally.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/cache/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/cache/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,qBAAqB,CAAC;AAIpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,MAAM,CAAC,OAAO,OAAO,YAAY;IAC/B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,aAAa,CAAC,CAAgB;gBAE1B,EAAE,YAAY,EAAE,EAAE,iBAAiB;IAI/C;;;OAGG;YACW,gBAAgB;IAa9B;;;;;;;;;;;;;;OAcG;IACU,OAAO,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAkBpE;;;;;;;;;;;;;;;;;;;OAmBG;IACU,OAAO,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9G;;;;;;;;;OASG;IACU,SAAS,CAAC,EAAE,GAAG,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGpC"}

package/dist/cache/manager.js

@@ -1,5 +1,6 @@
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+import { safeSerializeError } from "../error/error-reporter.js";
 class CacheManager {
   static {
     __name(this, "CacheManager");
@@ -47,7 +48,7 @@ class CacheManager {
     try {
       return JSON.parse(raw);
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorMessage = error instanceof Error ? error.message : safeSerializeError(error);
       throw new Error(`Failed to parse cached value for key "${key}": ${errorMessage}`);
     }
   }

package/dist/cache/manager.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/cache/manager.ts"],
-  "sourcesContent": ["import type RedisManager from '../redis/manager.js';\nimport type RedisInstance from '../redis/instance.js';\n\n/**\n * CacheManager\n *\n * Thin abstraction over Redis for basic JSON value caching. Unifies all Redis\n * access through the framework RedisManager / RedisInstance (ioredis) so we\n * avoid maintaining a second client implementation (node-redis).\n *\n * Lazy acquisition: the first call to any cache method will either reuse an\n * existing connected RedisInstance (if already established by application\n * startup) or trigger a connection via RedisManager.\n *\n * **Important:** All values are stored as JSON strings. Only JSON-serializable\n * values are supported. Complex types like Date, Map, Set, RegExp, etc. will\n * lose their type information during serialization:\n * - `Date` objects \u2192 ISO strings\n * - `Map` / `Set` \u2192 empty objects `{}`\n * - `undefined` \u2192 omitted from objects, `null` in arrays\n * - Functions \u2192 omitted\n *\n * @example\n * ```typescript\n * // Supported types\n * await cache.setItem({ key: 'user', value: { id: 1, name: 'John' } }); // \u2713\n * await cache.setItem({ key: 'count', value: 42 }); // \u2713\n * await cache.setItem({ key: 'tags', value: ['a', 'b', 'c'] }); // \u2713\n *\n * // Unsupported types (will lose type information)\n * await cache.setItem({ key: 'date', value: new Date() }); // \u2192 ISO string\n * await cache.setItem({ key: 'map', value: new Map() }); // \u2192 {}\n * ```\n */\n\nexport interface CacheManagerProps {\n  /** Redis manager (shared across the application) */\n  redisManager: RedisManager;\n}\n\nexport default class CacheManager {\n  private redisManager: RedisManager;\n  private redisInstance?: RedisInstance;\n\n  constructor({ redisManager }: CacheManagerProps) {\n    this.redisManager = redisManager;\n  }\n\n  /**\n   * Ensure we have a connected RedisInstance. Reuses the first existing\n   * instance if already connected by the application bootstrap.\n   */\n  private async getRedisInstance(): Promise<RedisInstance> {\n    if (this.redisInstance) return this.redisInstance;\n\n    if (this.redisManager.instances.length > 0) {\n      this.redisInstance = this.redisManager.instances[0];\n      return this.redisInstance;\n    }\n\n    // Lazily connect if no instances yet (e.g., used before app onBeforeStart)\n    this.redisInstance = await this.redisManager.connect();\n    return this.redisInstance;\n  }\n\n  /**\n   * Get a cached JSON value (deserialized) or null if not present.\n   *\n   * @param key - Cache key\n   * @returns Deserialized value or null if not found\n   * @throws {Error} If the cached value is not valid JSON\n   *\n   * @example\n   * ```typescript\n   * const user = await cache.getItem<{ id: number; name: string }>({ key: 'user:123' });\n   * if (user) {\n   *   console.log(user.name);\n   * }\n   * ```\n   */\n  public async getItem<T>({ key }: { key: string }): Promise<T | null> {\n    const instance = await this.getRedisInstance();\n    const raw = await instance.getCache({ key });\n    if (raw === null) return null;\n\n    // Validate that we received a string (Redis should always return string or null)\n    if (typeof raw !== 'string') {\n      throw new Error(`Cache value for key \"${key}\" must be a string, got ${typeof raw}`);\n    }\n\n    try {\n      return JSON.parse(raw) as T;\n    } catch (error) {\n      const errorMessage = error instanceof Error ? error.message : String(error);\n      throw new Error(`Failed to parse cached value for key \"${key}\": ${errorMessage}`);\n    }\n  }\n\n  /**\n   * Set a JSON-serializable value. Optionally specify lifetime (seconds).\n   *\n   * @param key - Cache key\n   * @param value - Value to cache (must be JSON-serializable)\n   * @param lifetime - Optional expiration in seconds\n   *\n   * @example\n   * ```typescript\n   * // Cache with no expiration\n   * await cache.setItem({ key: 'config', value: { theme: 'dark' } });\n   *\n   * // Cache with 1 hour expiration\n   * await cache.setItem({\n   *   key: 'session:abc',\n   *   value: { userId: 123 },\n   *   lifetime: 3600\n   * });\n   * ```\n   */\n  public async setItem<T>({ key, value, lifetime }: { key: string; value: T; lifetime?: number }): Promise<void> {\n    const instance = await this.getRedisInstance();\n    await instance.setCache({ key, value, expiration: lifetime });\n  }\n\n  /**\n   * Delete a cached value.\n   *\n   * @param key - Cache key to delete\n   *\n   * @example\n   * ```typescript\n   * await cache.clearItem({ key: 'session:abc' });\n   * ```\n   */\n  public async clearItem({ key }: { key: string }): Promise<void> {\n    const instance = await this.getRedisInstance();\n    await instance.deleteCache({ key });\n  }\n\n  /**\n   * No-op: lifecycle handles Redis disconnection globally.\n   */\n  public async close(): Promise<void> {\n    // Intentionally empty; RedisManager handles disconnect.\n  }\n}\n"],
-  "mappings": ";;AAwCA,MAAO,aAA2B;AAAA,EAxClC,OAwCkC;AAAA;AAAA;AAAA,EACxB;AAAA,EACA;AAAA,EAER,YAAY,EAAE,aAAa,GAAsB;AAC/C,SAAK,eAAe;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAc,mBAA2C;AACvD,QAAI,KAAK,cAAe,QAAO,KAAK;AAEpC,QAAI,KAAK,aAAa,UAAU,SAAS,GAAG;AAC1C,WAAK,gBAAgB,KAAK,aAAa,UAAU,CAAC;AAClD,aAAO,KAAK;AAAA,IACd;AAGA,SAAK,gBAAgB,MAAM,KAAK,aAAa,QAAQ;AACrD,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBA,MAAa,QAAW,EAAE,IAAI,GAAuC;AACnE,UAAM,WAAW,MAAM,KAAK,iBAAiB;AAC7C,UAAM,MAAM,MAAM,SAAS,SAAS,EAAE,IAAI,CAAC;AAC3C,QAAI,QAAQ,KAAM,QAAO;AAGzB,QAAI,OAAO,QAAQ,UAAU;AAC3B,YAAM,IAAI,MAAM,wBAAwB,GAAG,2BAA2B,OAAO,GAAG,EAAE;AAAA,IACpF;AAEA,QAAI;AACF,aAAO,KAAK,MAAM,GAAG;AAAA,IACvB,SAAS,OAAO;AACd,YAAM,eAAe,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC1E,YAAM,IAAI,MAAM,yCAAyC,GAAG,MAAM,YAAY,EAAE;AAAA,IAClF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,MAAa,QAAW,EAAE,KAAK,OAAO,SAAS,GAAgE;AAC7G,UAAM,WAAW,MAAM,KAAK,iBAAiB;AAC7C,UAAM,SAAS,SAAS,EAAE,KAAK,OAAO,YAAY,SAAS,CAAC;AAAA,EAC9D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAa,UAAU,EAAE,IAAI,GAAmC;AAC9D,UAAM,WAAW,MAAM,KAAK,iBAAiB;AAC7C,UAAM,SAAS,YAAY,EAAE,IAAI,CAAC;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA,EAKA,MAAa,QAAuB;AAAA,EAEpC;AACF;",
+  "sourcesContent": ["import type RedisManager from '../redis/manager.js';\nimport type RedisInstance from '../redis/instance.js';\nimport { safeSerializeError } from '../error/error-reporter.js';\n\n/**\n * CacheManager\n *\n * Thin abstraction over Redis for basic JSON value caching. Unifies all Redis\n * access through the framework RedisManager / RedisInstance (ioredis) so we\n * avoid maintaining a second client implementation (node-redis).\n *\n * Lazy acquisition: the first call to any cache method will either reuse an\n * existing connected RedisInstance (if already established by application\n * startup) or trigger a connection via RedisManager.\n *\n * **Important:** All values are stored as JSON strings. Only JSON-serializable\n * values are supported. Complex types like Date, Map, Set, RegExp, etc. will\n * lose their type information during serialization:\n * - `Date` objects \u2192 ISO strings\n * - `Map` / `Set` \u2192 empty objects `{}`\n * - `undefined` \u2192 omitted from objects, `null` in arrays\n * - Functions \u2192 omitted\n *\n * @example\n * ```typescript\n * // Supported types\n * await cache.setItem({ key: 'user', value: { id: 1, name: 'John' } }); // \u2713\n * await cache.setItem({ key: 'count', value: 42 }); // \u2713\n * await cache.setItem({ key: 'tags', value: ['a', 'b', 'c'] }); // \u2713\n *\n * // Unsupported types (will lose type information)\n * await cache.setItem({ key: 'date', value: new Date() }); // \u2192 ISO string\n * await cache.setItem({ key: 'map', value: new Map() }); // \u2192 {}\n * ```\n */\n\nexport interface CacheManagerProps {\n  /** Redis manager (shared across the application) */\n  redisManager: RedisManager;\n}\n\nexport default class CacheManager {\n  private redisManager: RedisManager;\n  private redisInstance?: RedisInstance;\n\n  constructor({ redisManager }: CacheManagerProps) {\n    this.redisManager = redisManager;\n  }\n\n  /**\n   * Ensure we have a connected RedisInstance. Reuses the first existing\n   * instance if already connected by the application bootstrap.\n   */\n  private async getRedisInstance(): Promise<RedisInstance> {\n    if (this.redisInstance) return this.redisInstance;\n\n    if (this.redisManager.instances.length > 0) {\n      this.redisInstance = this.redisManager.instances[0];\n      return this.redisInstance;\n    }\n\n    // Lazily connect if no instances yet (e.g., used before app onBeforeStart)\n    this.redisInstance = await this.redisManager.connect();\n    return this.redisInstance;\n  }\n\n  /**\n   * Get a cached JSON value (deserialized) or null if not present.\n   *\n   * @param key - Cache key\n   * @returns Deserialized value or null if not found\n   * @throws {Error} If the cached value is not valid JSON\n   *\n   * @example\n   * ```typescript\n   * const user = await cache.getItem<{ id: number; name: string }>({ key: 'user:123' });\n   * if (user) {\n   *   console.log(user.name);\n   * }\n   * ```\n   */\n  public async getItem<T>({ key }: { key: string }): Promise<T | null> {\n    const instance = await this.getRedisInstance();\n    const raw = await instance.getCache({ key });\n    if (raw === null) return null;\n\n    // Validate that we received a string (Redis should always return string or null)\n    if (typeof raw !== 'string') {\n      throw new Error(`Cache value for key \"${key}\" must be a string, got ${typeof raw}`);\n    }\n\n    try {\n      return JSON.parse(raw) as T;\n    } catch (error) {\n      const errorMessage = error instanceof Error ? error.message : safeSerializeError(error);\n      throw new Error(`Failed to parse cached value for key \"${key}\": ${errorMessage}`);\n    }\n  }\n\n  /**\n   * Set a JSON-serializable value. Optionally specify lifetime (seconds).\n   *\n   * @param key - Cache key\n   * @param value - Value to cache (must be JSON-serializable)\n   * @param lifetime - Optional expiration in seconds\n   *\n   * @example\n   * ```typescript\n   * // Cache with no expiration\n   * await cache.setItem({ key: 'config', value: { theme: 'dark' } });\n   *\n   * // Cache with 1 hour expiration\n   * await cache.setItem({\n   *   key: 'session:abc',\n   *   value: { userId: 123 },\n   *   lifetime: 3600\n   * });\n   * ```\n   */\n  public async setItem<T>({ key, value, lifetime }: { key: string; value: T; lifetime?: number }): Promise<void> {\n    const instance = await this.getRedisInstance();\n    await instance.setCache({ key, value, expiration: lifetime });\n  }\n\n  /**\n   * Delete a cached value.\n   *\n   * @param key - Cache key to delete\n   *\n   * @example\n   * ```typescript\n   * await cache.clearItem({ key: 'session:abc' });\n   * ```\n   */\n  public async clearItem({ key }: { key: string }): Promise<void> {\n    const instance = await this.getRedisInstance();\n    await instance.deleteCache({ key });\n  }\n\n  /**\n   * No-op: lifecycle handles Redis disconnection globally.\n   */\n  public async close(): Promise<void> {\n    // Intentionally empty; RedisManager handles disconnect.\n  }\n}\n"],
+  "mappings": ";;AAEA,SAAS,0BAA0B;AAuCnC,MAAO,aAA2B;AAAA,EAzClC,OAyCkC;AAAA;AAAA;AAAA,EACxB;AAAA,EACA;AAAA,EAER,YAAY,EAAE,aAAa,GAAsB;AAC/C,SAAK,eAAe;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAc,mBAA2C;AACvD,QAAI,KAAK,cAAe,QAAO,KAAK;AAEpC,QAAI,KAAK,aAAa,UAAU,SAAS,GAAG;AAC1C,WAAK,gBAAgB,KAAK,aAAa,UAAU,CAAC;AAClD,aAAO,KAAK;AAAA,IACd;AAGA,SAAK,gBAAgB,MAAM,KAAK,aAAa,QAAQ;AACrD,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBA,MAAa,QAAW,EAAE,IAAI,GAAuC;AACnE,UAAM,WAAW,MAAM,KAAK,iBAAiB;AAC7C,UAAM,MAAM,MAAM,SAAS,SAAS,EAAE,IAAI,CAAC;AAC3C,QAAI,QAAQ,KAAM,QAAO;AAGzB,QAAI,OAAO,QAAQ,UAAU;AAC3B,YAAM,IAAI,MAAM,wBAAwB,GAAG,2BAA2B,OAAO,GAAG,EAAE;AAAA,IACpF;AAEA,QAAI;AACF,aAAO,KAAK,MAAM,GAAG;AAAA,IACvB,SAAS,OAAO;AACd,YAAM,eAAe,iBAAiB,QAAQ,MAAM,UAAU,mBAAmB,KAAK;AACtF,YAAM,IAAI,MAAM,yCAAyC,GAAG,MAAM,YAAY,EAAE;AAAA,IAClF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,MAAa,QAAW,EAAE,KAAK,OAAO,SAAS,GAAgE;AAC7G,UAAM,WAAW,MAAM,KAAK,iBAAiB;AAC7C,UAAM,SAAS,SAAS,EAAE,KAAK,OAAO,YAAY,SAAS,CAAC;AAAA,EAC9D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAa,UAAU,EAAE,IAAI,GAAmC;AAC9D,UAAM,WAAW,MAAM,KAAK,iBAAiB;AAC7C,UAAM,SAAS,YAAY,EAAE,IAAI,CAAC;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA,EAKA,MAAa,QAAuB;AAAA,EAEpC;AACF;",
   "names": []
 }

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}