@catbee/utils 0.0.1 → 0.0.3

package/build/esnext/utils/context-store.utils.js

@@ -1,11 +1,15 @@
-import { AsyncLocalStorage } from "async_hooks";
+import { AsyncLocalStorage } from 'async_hooks';
 /**
  * Predefined symbols used as keys in AsyncLocalStorage.
  * Add new symbols here to avoid duplication.
  */
 export const StoreKeys = {
-    LOGGER: Symbol("logger"),
-    REQUEST_ID: Symbol("requestId"),
+    LOGGER: Symbol('logger'),
+    REQUEST_ID: Symbol('requestId'),
+    USER_ID: Symbol('userId'),
+    TENANT_ID: Symbol('tenantId'),
+    TRACE_ID: Symbol('traceId'),
+    CORRELATION_ID: Symbol('correlationId')
 };
 /**
  * Retrieves the current request ID from the async context, if available.
@@ -15,6 +19,15 @@ export const StoreKeys = {
 export function getRequestId() {
     return ContextStore.get(StoreKeys.REQUEST_ID);
 }
+/**
+ * Type-safe getter for common context values.
+ *
+ * @param key The store key symbol
+ * @returns The typed value from the store
+ */
+export function getFromContext(key) {
+    return ContextStore.get(key);
+}
 /**
  * ContextStore manages per-request scoped context using AsyncLocalStorage.
  * It allows storing and retrieving data across async calls (e.g., request ID, logger).
@@ -86,10 +99,165 @@ export class ContextStore {
     static run(store, callback) {
         return this.storage.run(store, callback);
     }
+    /**
+     * Checks if a key exists in the current context store.
+     *
+     * @param {symbol} key - The symbol key to check.
+     * @returns {boolean} True if the key exists, false otherwise.
+     */
+    static has(key) {
+        const store = this.storage.getStore();
+        return store !== undefined && key in store;
+    }
+    /**
+     * Removes a value from the current context store by symbol key.
+     *
+     * @param {symbol} key - The symbol key to delete.
+     * @returns {boolean} True if the key was deleted, false if the key wasn't found or no active context.
+     * @throws {Error} If called outside an active context.
+     */
+    static delete(key) {
+        const store = this.storage.getStore();
+        if (!store) {
+            throw new Error(`Failed to delete ${String(key)}: AsyncLocalStorage store is not initialized.`);
+        }
+        return delete store[key];
+    }
+    /**
+     * Updates multiple values in the current context store at once.
+     *
+     * @param {Partial<Record<symbol, unknown>>} values - Object containing symbol keys and values to update.
+     * @throws {Error} If called outside an active context.
+     */
+    static patch(values) {
+        const store = this.storage.getStore();
+        if (!store) {
+            throw new Error('Failed to patch: AsyncLocalStorage store is not initialized.');
+        }
+        Object.getOwnPropertySymbols(values).forEach(key => {
+            store[key] = values[key];
+        });
+    }
+    /**
+     * Executes a callback with a temporary store value that only exists during execution.
+     * Original store is restored after callback completes.
+     *
+     * @typeParam T - The callback's return type.
+     * @param {symbol} key - The symbol key to temporarily set.
+     * @param {unknown} value - The temporary value.
+     * @param {() => T} callback - The function to execute with the temporary value.
+     * @returns {T} The result of the callback function.
+     * @throws {Error} If called outside an active context.
+     */
+    static withValue(key, value, callback) {
+        const store = this.storage.getStore();
+        if (!store) {
+            throw new Error(`Failed to set temporary value: AsyncLocalStorage store is not initialized.`);
+        }
+        // Save original value
+        const hasOriginal = key in store;
+        const originalValue = store[key];
+        // Set temporary value
+        store[key] = value;
+        try {
+            // Run callback
+            return callback();
+        }
+        finally {
+            // Restore original value
+            if (hasOriginal) {
+                store[key] = originalValue;
+            }
+            else {
+                delete store[key];
+            }
+        }
+    }
+    /**
+     * Creates a new context that inherits values from the current context.
+     *
+     * @typeParam T - The callback's return type.
+     * @param {Partial<Record<symbol, unknown>>} newValues - New values to add to or override in the context.
+     * @param {() => T} callback - The function to execute in the new context.
+     * @returns {T} The result of the callback function.
+     */
+    static extend(newValues, callback) {
+        const currentStore = this.storage.getStore() || {};
+        // Create new store with current values plus new ones
+        const newStore = Object.assign({}, currentStore);
+        // Add new values
+        Object.getOwnPropertySymbols(newValues).forEach(key => {
+            newStore[key] = newValues[key];
+        });
+        // Run with extended store
+        return this.storage.run(newStore, callback);
+    }
+    /**
+     * Creates Express middleware that initializes a context for each request.
+     *
+     * @param {(req: any) => Partial<Record<symbol, unknown>>} initialValuesFactory - Function that returns initial context values.
+     * @returns Express middleware function.
+     */
+    static createExpressMiddleware(initialValuesFactory = () => ({})) {
+        return (req, res, next) => {
+            const initialValues = initialValuesFactory(req);
+            ContextStore.run(initialValues, next);
+        };
+    }
 }
 /**
  * The underlying AsyncLocalStorage instance for context.
  * @private
  */
 ContextStore.storage = new AsyncLocalStorage();
+/**
+ * Type-safe wrapper for accessing and modifying context values with specific types.
+ *
+ * @typeParam T - The value type.
+ */
+export class TypedContextKey {
+    /**
+     * Creates a new typed context key.
+     *
+     * @param symbol - The unique symbol for this key
+     * @param defaultValue - Optional default value if key is not found
+     */
+    constructor(symbol, defaultValue) {
+        this.symbol = symbol;
+        this.defaultValue = defaultValue;
+    }
+    /**
+     * Gets the current value for this key.
+     *
+     * @returns The value or defaultValue if not found
+     */
+    get() {
+        const value = ContextStore.get(this.symbol);
+        return value !== undefined ? value : this.defaultValue;
+    }
+    /**
+     * Sets the value for this key.
+     *
+     * @param value The value to set
+     */
+    set(value) {
+        ContextStore.set(this.symbol, value);
+    }
+    /**
+     * Checks if this key exists in the context.
+     *
+     * @returns True if the key exists
+     */
+    exists() {
+        return ContextStore.has(this.symbol);
+    }
+    /**
+     * Deletes this key from the context.
+     *
+     * @returns True if the key was deleted
+     */
+    delete() {
+        return ContextStore.delete(this.symbol);
+    }
+}
 //# sourceMappingURL=context-store.utils.js.map

package/build/esnext/utils/context-store.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-store.utils.js","sourceRoot":"","sources":["../../../src/utils/context-store.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAUhD;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC;CAChC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,YAAY,CAAC,GAAG,CAAS,SAAS,CAAC,UAAU,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,YAAY;IAOvB;;;;OAIG;IACH,MAAM,CAAC,WAAW;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAI,GAAW;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAG,GAAG,CAAkB,CAAC;IACvC,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,GAAG,CAAC,+CAA+C,CAC5E,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,GAAG,CAAI,KAAY,EAAE,QAAiB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;;AAjED;;;GAGG;AACqB,oBAAO,GAAG,IAAI,iBAAiB,EAAS,CAAC","sourcesContent":["import { AsyncLocalStorage } from \"async_hooks\";\n\n/**\n * Type representing the store object used in AsyncLocalStorage.\n * Keys must be unique symbols to ensure isolation and prevent collisions.\n */\nexport interface Store {\n  [key: symbol]: unknown;\n}\n\n/**\n * Predefined symbols used as keys in AsyncLocalStorage.\n * Add new symbols here to avoid duplication.\n */\nexport const StoreKeys = {\n  LOGGER: Symbol(\"logger\"),\n  REQUEST_ID: Symbol(\"requestId\"),\n};\n\n/**\n * Retrieves the current request ID from the async context, if available.\n *\n * @returns {string | undefined} The request ID string or undefined if not present in the current context.\n */\nexport function getRequestId(): string | undefined {\n  return ContextStore.get<string>(StoreKeys.REQUEST_ID);\n}\n\n/**\n * ContextStore manages per-request scoped context using AsyncLocalStorage.\n * It allows storing and retrieving data across async calls (e.g., request ID, logger).\n *\n * Example (Express middleware):\n * ```\n * // Middleware to initialize context and logger\n * app.use((req, res, next) => {\n *   const requestId = req.headers[\"x-request-id\"]?.toString() || crypto.randomUUID();\n *   ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {\n *     ContextStore.set(StoreKeys.LOGGER, getLogger().child({ reqId: requestId }));\n *     next();\n *   });\n * });\n * ```\n */\nexport class ContextStore {\n  /**\n   * The underlying AsyncLocalStorage instance for context.\n   * @private\n   */\n  private static readonly storage = new AsyncLocalStorage<Store>();\n\n  /**\n   * Returns the raw AsyncLocalStorage instance for advanced access.\n   *\n   * @returns {AsyncLocalStorage<Store>} The AsyncLocalStorage instance.\n   */\n  static getInstance(): AsyncLocalStorage<Store> {\n    return this.storage;\n  }\n\n  /**\n   * Retrieves a value from the async context store by symbol key.\n   *\n   * @typeParam T - The expected return type of the value.\n   * @param {symbol} key - Unique symbol used as the store key.\n   * @returns {T | undefined} The value found (typed) or undefined if not present.\n   */\n  static get<T>(key: symbol): T | undefined {\n    const store = this.storage.getStore();\n    return store?.[key] as T | undefined;\n  }\n\n  /**\n   * Sets a value in the current context store by symbol key.\n   *\n   * @typeParam T - The value type to set.\n   * @param {symbol} key - Unique symbol key.\n   * @param {T} value - Value to set in context.\n   * @throws {Error} If called outside an active context (not within a .run call or in the wrong async boundaries).\n   */\n  static set<T>(key: symbol, value: T): void {\n    const store = this.storage.getStore();\n    if (!store) {\n      throw new Error(\n        `Failed to set ${String(key)}: AsyncLocalStorage store is not initialized.`,\n      );\n    }\n    store[key] = value;\n  }\n\n  /**\n   * Retrieves the entire context store object for the current async context.\n   *\n   * @returns {Store | undefined} The current store object or undefined if called outside a context.\n   */\n  static getAll(): Store | undefined {\n    return this.storage.getStore();\n  }\n\n  /**\n   * Initializes a new async context and executes a callback within it.\n   * This must be called at the beginning of a request or logical async flow.\n   *\n   * @typeParam T - The callback's return type.\n   * @param {Store} store - The initial key-value store object.\n   * @param {() => T} callback - The function to run within the new context.\n   * @returns {T} The result of the callback function.\n   */\n  static run<T>(store: Store, callback: () => T): T {\n    return this.storage.run(store, callback);\n  }\n}\n"]}
+{"version":3,"file":"context-store.utils.js","sourceRoot":"","sources":["../../../src/utils/context-store.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { AsyncLocalStorage } from 'async_hooks';\n\n/**\n * Type representing the store object used in AsyncLocalStorage.\n * Keys must be unique symbols to ensure isolation and prevent collisions.\n */\nexport interface Store {\n  [key: symbol]: unknown;\n}\n\n/**\n * Predefined symbols used as keys in AsyncLocalStorage.\n * Add new symbols here to avoid duplication.\n */\nexport const StoreKeys = {\n  LOGGER: Symbol('logger'),\n  REQUEST_ID: Symbol('requestId'),\n  USER_ID: Symbol('userId'),\n  TENANT_ID: Symbol('tenantId'),\n  TRACE_ID: Symbol('traceId'),\n  CORRELATION_ID: Symbol('correlationId')\n};\n\n/**\n * Retrieves the current request ID from the async context, if available.\n *\n * @returns {string | undefined} The request ID string or undefined if not present in the current context.\n */\nexport function getRequestId(): string | undefined {\n  return ContextStore.get<string>(StoreKeys.REQUEST_ID);\n}\n\n/**\n * Type-safe getter for common context values.\n *\n * @param key The store key symbol\n * @returns The typed value from the store\n */\nexport function getFromContext<T>(key: symbol): T | undefined {\n  return ContextStore.get<T>(key);\n}\n\n/**\n * ContextStore manages per-request scoped context using AsyncLocalStorage.\n * It allows storing and retrieving data across async calls (e.g., request ID, logger).\n *\n * Example (Express middleware):\n * ```\n * // Middleware to initialize context and logger\n * app.use((req, res, next) => {\n *   const requestId = req.headers[\"x-request-id\"]?.toString() || crypto.randomUUID();\n *   ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {\n *     ContextStore.set(StoreKeys.LOGGER, getLogger().child({ reqId: requestId }));\n *     next();\n *   });\n * });\n * ```\n */\nexport class ContextStore {\n  /**\n   * The underlying AsyncLocalStorage instance for context.\n   * @private\n   */\n  private static readonly storage = new AsyncLocalStorage<Store>();\n\n  /**\n   * Returns the raw AsyncLocalStorage instance for advanced access.\n   *\n   * @returns {AsyncLocalStorage<Store>} The AsyncLocalStorage instance.\n   */\n  static getInstance(): AsyncLocalStorage<Store> {\n    return this.storage;\n  }\n\n  /**\n   * Retrieves a value from the async context store by symbol key.\n   *\n   * @typeParam T - The expected return type of the value.\n   * @param {symbol} key - Unique symbol used as the store key.\n   * @returns {T | undefined} The value found (typed) or undefined if not present.\n   */\n  static get<T>(key: symbol): T | undefined {\n    const store = this.storage.getStore();\n    return store?.[key] as T | undefined;\n  }\n\n  /**\n   * Sets a value in the current context store by symbol key.\n   *\n   * @typeParam T - The value type to set.\n   * @param {symbol} key - Unique symbol key.\n   * @param {T} value - Value to set in context.\n   * @throws {Error} If called outside an active context (not within a .run call or in the wrong async boundaries).\n   */\n  static set<T>(key: symbol, value: T): void {\n    const store = this.storage.getStore();\n    if (!store) {\n      throw new Error(`Failed to set ${String(key)}: AsyncLocalStorage store is not initialized.`);\n    }\n    store[key] = value;\n  }\n\n  /**\n   * Retrieves the entire context store object for the current async context.\n   *\n   * @returns {Store | undefined} The current store object or undefined if called outside a context.\n   */\n  static getAll(): Store | undefined {\n    return this.storage.getStore();\n  }\n\n  /**\n   * Initializes a new async context and executes a callback within it.\n   * This must be called at the beginning of a request or logical async flow.\n   *\n   * @typeParam T - The callback's return type.\n   * @param {Store} store - The initial key-value store object.\n   * @param {() => T} callback - The function to run within the new context.\n   * @returns {T} The result of the callback function.\n   */\n  static run<T>(store: Store, callback: () => T): T {\n    return this.storage.run(store, callback);\n  }\n\n  /**\n   * Checks if a key exists in the current context store.\n   *\n   * @param {symbol} key - The symbol key to check.\n   * @returns {boolean} True if the key exists, false otherwise.\n   */\n  static has(key: symbol): boolean {\n    const store = this.storage.getStore();\n    return store !== undefined && key in store;\n  }\n\n  /**\n   * Removes a value from the current context store by symbol key.\n   *\n   * @param {symbol} key - The symbol key to delete.\n   * @returns {boolean} True if the key was deleted, false if the key wasn't found or no active context.\n   * @throws {Error} If called outside an active context.\n   */\n  static delete(key: symbol): boolean {\n    const store = this.storage.getStore();\n    if (!store) {\n      throw new Error(`Failed to delete ${String(key)}: AsyncLocalStorage store is not initialized.`);\n    }\n    return delete store[key];\n  }\n\n  /**\n   * Updates multiple values in the current context store at once.\n   *\n   * @param {Partial<Record<symbol, unknown>>} values - Object containing symbol keys and values to update.\n   * @throws {Error} If called outside an active context.\n   */\n  static patch(values: Partial<Record<symbol, unknown>>): void {\n    const store = this.storage.getStore();\n    if (!store) {\n      throw new Error('Failed to patch: AsyncLocalStorage store is not initialized.');\n    }\n    Object.getOwnPropertySymbols(values).forEach(key => {\n      store[key] = values[key];\n    });\n  }\n  /**\n   * Executes a callback with a temporary store value that only exists during execution.\n   * Original store is restored after callback completes.\n   *\n   * @typeParam T - The callback's return type.\n   * @param {symbol} key - The symbol key to temporarily set.\n   * @param {unknown} value - The temporary value.\n   * @param {() => T} callback - The function to execute with the temporary value.\n   * @returns {T} The result of the callback function.\n   * @throws {Error} If called outside an active context.\n   */\n  static withValue<T>(key: symbol, value: unknown, callback: () => T): T {\n    const store = this.storage.getStore();\n    if (!store) {\n      throw new Error(`Failed to set temporary value: AsyncLocalStorage store is not initialized.`);\n    }\n\n    // Save original value\n    const hasOriginal = key in store;\n    const originalValue = store[key];\n\n    // Set temporary value\n    store[key] = value;\n\n    try {\n      // Run callback\n      return callback();\n    } finally {\n      // Restore original value\n      if (hasOriginal) {\n        store[key] = originalValue;\n      } else {\n        delete store[key];\n      }\n    }\n  }\n\n  /**\n   * Creates a new context that inherits values from the current context.\n   *\n   * @typeParam T - The callback's return type.\n   * @param {Partial<Record<symbol, unknown>>} newValues - New values to add to or override in the context.\n   * @param {() => T} callback - The function to execute in the new context.\n   * @returns {T} The result of the callback function.\n   */\n  static extend<T>(newValues: Partial<Record<symbol, unknown>>, callback: () => T): T {\n    const currentStore = this.storage.getStore() || {};\n\n    // Create new store with current values plus new ones\n    const newStore: Store = { ...currentStore };\n\n    // Add new values\n    Object.getOwnPropertySymbols(newValues).forEach(key => {\n      newStore[key] = newValues[key];\n    });\n\n    // Run with extended store\n    return this.storage.run(newStore, callback);\n  }\n\n  /**\n   * Creates Express middleware that initializes a context for each request.\n   *\n   * @param {(req: any) => Partial<Record<symbol, unknown>>} initialValuesFactory - Function that returns initial context values.\n   * @returns Express middleware function.\n   */\n  static createExpressMiddleware(initialValuesFactory: (req: any) => Partial<Record<symbol, unknown>> = () => ({})) {\n    return (req: any, res: any, next: any) => {\n      const initialValues = initialValuesFactory(req);\n      ContextStore.run(initialValues as Store, next);\n    };\n  }\n}\n\n/**\n * Type-safe wrapper for accessing and modifying context values with specific types.\n *\n * @typeParam T - The value type.\n */\nexport class TypedContextKey<T> {\n  /**\n   * Creates a new typed context key.\n   *\n   * @param symbol - The unique symbol for this key\n   * @param defaultValue - Optional default value if key is not found\n   */\n  constructor(\n    private symbol: symbol,\n    private defaultValue?: T\n  ) {}\n\n  /**\n   * Gets the current value for this key.\n   *\n   * @returns The value or defaultValue if not found\n   */\n  get(): T | undefined {\n    const value = ContextStore.get<T>(this.symbol);\n    return value !== undefined ? value : this.defaultValue;\n  }\n\n  /**\n   * Sets the value for this key.\n   *\n   * @param value The value to set\n   */\n  set(value: T): void {\n    ContextStore.set<T>(this.symbol, value);\n  }\n\n  /**\n   * Checks if this key exists in the context.\n   *\n   * @returns True if the key exists\n   */\n  exists(): boolean {\n    return ContextStore.has(this.symbol);\n  }\n\n  /**\n   * Deletes this key from the context.\n   *\n   * @returns True if the key was deleted\n   */\n  delete(): boolean {\n    return ContextStore.delete(this.symbol);\n  }\n}\n"]}

package/build/esnext/utils/crypto.utils.d.ts

@@ -1,4 +1,5 @@
-import { BinaryToTextEncoding } from "crypto";
+import { BinaryToTextEncoding, CipherGCMTypes } from 'crypto';
+export type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'utf-16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
 /**
  * Generates an HMAC digest using the specified algorithm and secret key.
  *
@@ -8,7 +9,7 @@ import { BinaryToTextEncoding } from "crypto";
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
  * @returns {string} HMAC digest as a string.
  */
-export declare const hmac: (algorithm: string, input: string, secret: string, encoding?: BinaryToTextEncoding) => string;
+export declare function hmac(algorithm: string, input: string, secret: string, encoding?: BinaryToTextEncoding): string;
 /**
  * Generates a hash digest using the specified algorithm.
  *
@@ -17,7 +18,7 @@ export declare const hmac: (algorithm: string, input: string, secret: string, en
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
  * @returns {string} Hash digest as a string.
  */
-export declare const hash: (algorithm: string, input: string, encoding?: BinaryToTextEncoding) => string;
+export declare function hash(algorithm: string, input: string, encoding?: BinaryToTextEncoding): string;
 /**
  * Generates an HMAC-SHA256 digest.
  *
@@ -25,7 +26,7 @@ export declare const hash: (algorithm: string, input: string, encoding?: BinaryT
  * @param {string} secret - The secret key.
  * @returns {string} SHA-256 HMAC digest as a string.
  */
-export declare const sha256Hmac: (input: string, secret: string) => string;
+export declare function sha256Hmac(input: string, secret: string): string;
 /**
  * Generates a SHA1 hash digest.
  *
@@ -33,7 +34,7 @@ export declare const sha256Hmac: (input: string, secret: string) => string;
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
  * @returns {string} SHA-1 hash as a string.
  */
-export declare const sha1: (input: string, encoding?: BinaryToTextEncoding) => string;
+export declare function sha1(input: string, encoding?: BinaryToTextEncoding): string;
 /**
  * Generates a SHA256 hash digest.
  *
@@ -41,18 +42,119 @@ export declare const sha1: (input: string, encoding?: BinaryToTextEncoding) => s
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
  * @returns {string} SHA-256 hash as a string.
  */
-export declare const sha256: (input: string, encoding?: BinaryToTextEncoding) => string;
+export declare function sha256(input: string, encoding?: BinaryToTextEncoding): string;
 /**
  * Generates an MD5 hash digest.
  *
  * @param {string} input - The string to hash.
  * @returns {string} MD5 hash as a string.
  */
-export declare const md5: (input: string) => string;
+export declare function md5(input: string): string;
 /**
  * Generates a cryptographically strong random string by hashing a random UUID with SHA-256.
  *
  * @returns {string} Random string hashed with SHA-256 (hex encoding).
  */
-export declare const randomString: () => string;
+export declare function randomString(): string;
+/**
+ * Generates a secure random buffer of specified byte length.
+ *
+ * @param {number} [byteLength=32] - Number of random bytes to generate.
+ * @returns {Buffer} Buffer containing random bytes.
+ */
+export declare function generateRandomBytes(byteLength?: number): Buffer;
+/**
+ * Generates a secure random string of specified byte length with specified encoding.
+ *
+ * @param {number} [byteLength=32] - Number of random bytes to generate.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
+ * @returns {string} Random string in specified encoding.
+ */
+export declare function generateRandomBytesAsString(byteLength?: number, encoding?: BinaryToTextEncoding): string;
+/**
+ * Generates a secure API key with a specified format.
+ *
+ * @param {string} [prefix=''] - Optional prefix for the key.
+ * @param {number} [byteLength=24] - Number of random bytes to generate.
+ * @returns {string} Formatted API key.
+ */
+export declare function generateApiKey(prefix?: string, byteLength?: number): string;
+/**
+ * Compares two strings, arrays, or buffers in constant time to prevent timing attacks.
+ *
+ * @param {string | Buffer | Uint8Array} a - First value to compare
+ * @param {string | Buffer | Uint8Array} b - Second value to compare
+ * @returns {boolean} True if values are equal
+ */
+export declare function safeCompare(a: string | Buffer | Uint8Array, b: string | Buffer | Uint8Array): boolean;
+/**
+ * Interface for encryption options
+ */
+export interface EncryptionOptions {
+    /** Algorithm to use (default: aes-256-gcm) */
+    algorithm?: CipherGCMTypes;
+    /** Input encoding for plaintext if string (default: utf8) */
+    inputEncoding?: BufferEncoding;
+    /** Output encoding for ciphertext (default: hex) */
+    outputEncoding?: BinaryToTextEncoding;
+}
+/**
+ * Interface for decryption options
+ */
+export interface DecryptionOptions {
+    /** Algorithm to use (default: aes-256-gcm) */
+    algorithm?: CipherGCMTypes;
+    /** Input encoding for ciphertext if string (default: hex) */
+    inputEncoding?: BinaryToTextEncoding;
+    /** Output encoding for plaintext (default: utf8) */
+    outputEncoding?: BufferEncoding;
+}
+/**
+ * Result of encryption operation including all data needed for decryption
+ */
+export interface EncryptionResult {
+    /** Encrypted data (string or Buffer based on options) */
+    ciphertext: string | Buffer;
+    /** Initialization vector */
+    iv: Buffer;
+    /** Authentication tag (for GCM mode) */
+    authTag?: Buffer;
+    /** Algorithm used */
+    algorithm: string;
+}
+/**
+ * Encrypts data using a symmetric key with secure defaults (AES-256-GCM).
+ *
+ * @param {string | Buffer} data - Data to encrypt
+ * @param {string | Buffer} key - Encryption key or passphrase
+ * @param {EncryptionOptions} [options] - Encryption options
+ * @returns {Promise<EncryptionResult>} Encrypted data with metadata
+ */
+export declare function encrypt(data: string | Buffer, key: string | Buffer, options?: EncryptionOptions): Promise<EncryptionResult>;
+/**
+ * Decrypts data that was encrypted with the encrypt function.
+ *
+ * @param {EncryptionResult} encryptedData - The encrypted data and metadata
+ * @param {string | Buffer} key - Decryption key or passphrase
+ * @param {DecryptionOptions} [options] - Decryption options
+ * @returns {Promise<string | Buffer>} Decrypted data
+ */
+export declare function decrypt(encryptedData: EncryptionResult, key: string | Buffer, options?: DecryptionOptions): Promise<string | Buffer>;
+/**
+ * Creates a signed token with an expiration time and payload.
+ *
+ * @param {object} payload - Data to include in the token
+ * @param {string} secret - Secret key for signing
+ * @param {number} [expiresInSeconds=3600] - Token expiration in seconds
+ * @returns {string} Signed token string
+ */
+export declare function createSignedToken(payload: Record<string, any>, secret: string, expiresInSeconds?: number): string;
+/**
+ * Verifies and decodes a signed token.
+ *
+ * @param {string} token - The token to verify
+ * @param {string} secret - Secret key for verification
+ * @returns {object | null} Decoded payload if valid, null if invalid
+ */
+export declare function verifySignedToken(token: string, secret: string): Record<string, any> | null;
 //# sourceMappingURL=crypto.utils.d.ts.map

package/build/esnext/utils/crypto.utils.js

@@ -1,4 +1,5 @@
-import { createHmac, createHash, randomUUID, } from "crypto";
+import { createHmac, createHash, randomUUID, randomBytes, createCipheriv, createDecipheriv, scrypt, timingSafeEqual } from 'crypto';
+import { promisify } from 'util';
 /**
  * Generates an HMAC digest using the specified algorithm and secret key.
  *
@@ -8,9 +9,9 @@ import { createHmac, createHash, randomUUID, } from "crypto";
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
  * @returns {string} HMAC digest as a string.
  */
-export const hmac = (algorithm, input, secret, encoding = "hex") => {
+export function hmac(algorithm, input, secret, encoding = 'hex') {
     return createHmac(algorithm, secret).update(input).digest(encoding);
-};
+}
 /**
  * Generates a hash digest using the specified algorithm.
  *
@@ -19,9 +20,9 @@ export const hmac = (algorithm, input, secret, encoding = "hex") => {
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
  * @returns {string} Hash digest as a string.
  */
-export const hash = (algorithm, input, encoding = "hex") => {
+export function hash(algorithm, input, encoding = 'hex') {
     return createHash(algorithm).update(input).digest(encoding);
-};
+}
 /**
  * Generates an HMAC-SHA256 digest.
  *
@@ -29,9 +30,9 @@ export const hash = (algorithm, input, encoding = "hex") => {
  * @param {string} secret - The secret key.
  * @returns {string} SHA-256 HMAC digest as a string.
  */
-export const sha256Hmac = (input, secret) => {
-    return hmac("sha256", input, secret);
-};
+export function sha256Hmac(input, secret) {
+    return hmac('sha256', input, secret);
+}
 /**
  * Generates a SHA1 hash digest.
  *
@@ -39,9 +40,9 @@ export const sha256Hmac = (input, secret) => {
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
  * @returns {string} SHA-1 hash as a string.
  */
-export const sha1 = (input, encoding = "hex") => {
-    return hash("sha1", input, encoding);
-};
+export function sha1(input, encoding = 'hex') {
+    return hash('sha1', input, encoding);
+}
 /**
  * Generates a SHA256 hash digest.
  *
@@ -49,24 +50,203 @@ export const sha1 = (input, encoding = "hex") => {
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
  * @returns {string} SHA-256 hash as a string.
  */
-export const sha256 = (input, encoding = "hex") => {
-    return hash("sha256", input, encoding);
-};
+export function sha256(input, encoding = 'hex') {
+    return hash('sha256', input, encoding);
+}
 /**
  * Generates an MD5 hash digest.
  *
  * @param {string} input - The string to hash.
  * @returns {string} MD5 hash as a string.
  */
-export const md5 = (input) => {
-    return hash("md5", input);
-};
+export function md5(input) {
+    return hash('md5', input);
+}
 /**
  * Generates a cryptographically strong random string by hashing a random UUID with SHA-256.
  *
  * @returns {string} Random string hashed with SHA-256 (hex encoding).
  */
-export const randomString = () => {
+export function randomString() {
     return sha256(randomUUID());
-};
+}
+/**
+ * Generates a secure random buffer of specified byte length.
+ *
+ * @param {number} [byteLength=32] - Number of random bytes to generate.
+ * @returns {Buffer} Buffer containing random bytes.
+ */
+export function generateRandomBytes(byteLength = 32) {
+    return randomBytes(byteLength);
+}
+/**
+ * Generates a secure random string of specified byte length with specified encoding.
+ *
+ * @param {number} [byteLength=32] - Number of random bytes to generate.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
+ * @returns {string} Random string in specified encoding.
+ */
+export function generateRandomBytesAsString(byteLength = 32, encoding = 'hex') {
+    return randomBytes(byteLength).toString(encoding);
+}
+/**
+ * Generates a secure API key with a specified format.
+ *
+ * @param {string} [prefix=''] - Optional prefix for the key.
+ * @param {number} [byteLength=24] - Number of random bytes to generate.
+ * @returns {string} Formatted API key.
+ */
+export function generateApiKey(prefix = '', byteLength = 24) {
+    const randomString = generateRandomBytesAsString(byteLength, 'base64');
+    const key = randomString
+        .replace(/[+/=]/g, '') // Remove non-URL-safe characters
+        .substring(0, 32); // Limit length
+    return prefix ? `${prefix}_${key}` : key;
+}
+/**
+ * Compares two strings, arrays, or buffers in constant time to prevent timing attacks.
+ *
+ * @param {string | Buffer | Uint8Array} a - First value to compare
+ * @param {string | Buffer | Uint8Array} b - Second value to compare
+ * @returns {boolean} True if values are equal
+ */
+export function safeCompare(a, b) {
+    if (typeof a === 'string' && typeof b === 'string') {
+        // Convert strings to buffers
+        const bufA = Buffer.from(a);
+        const bufB = Buffer.from(b);
+        // Compare lengths first (not constant time, but prevents timing attack on contents)
+        if (bufA.length !== bufB.length)
+            return false;
+        return timingSafeEqual(bufA, bufB);
+    }
+    else if ((a instanceof Buffer || a instanceof Uint8Array) && (b instanceof Buffer || b instanceof Uint8Array)) {
+        // Compare lengths first
+        if (a.length !== b.length)
+            return false;
+        return timingSafeEqual(a instanceof Buffer ? a : Buffer.from(a), b instanceof Buffer ? b : Buffer.from(b));
+    }
+    throw new Error('Cannot compare: inputs must be strings, Buffers, or Uint8Arrays');
+}
+// Promisified version of scrypt for key derivation
+const scryptAsync = promisify(scrypt);
+/**
+ * Encrypts data using a symmetric key with secure defaults (AES-256-GCM).
+ *
+ * @param {string | Buffer} data - Data to encrypt
+ * @param {string | Buffer} key - Encryption key or passphrase
+ * @param {EncryptionOptions} [options] - Encryption options
+ * @returns {Promise<EncryptionResult>} Encrypted data with metadata
+ */
+export async function encrypt(data, key, options = {}) {
+    const algorithm = options.algorithm || 'aes-256-gcm';
+    const inputEncoding = options.inputEncoding || 'utf8';
+    const outputEncoding = options.outputEncoding || 'hex';
+    // Generate a random IV
+    const iv = randomBytes(16);
+    // Derive key using scrypt if key is a string (passphrase)
+    const derivedKey = typeof key === 'string' ? await scryptAsync(key, iv.slice(0, 8), 32) : key;
+    // Create cipher
+    const cipher = createCipheriv(algorithm, derivedKey, iv);
+    // Encrypt the data
+    let ciphertext;
+    if (typeof data === 'string') {
+        ciphertext = cipher.update(data, inputEncoding, outputEncoding);
+        ciphertext += cipher.final(outputEncoding);
+    }
+    else {
+        const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+        ciphertext = outputEncoding ? encrypted.toString(outputEncoding) : encrypted;
+    }
+    // Get authentication tag if using GCM mode
+    const authTag = algorithm.includes('gcm') ? cipher.getAuthTag() : undefined;
+    return {
+        ciphertext,
+        iv,
+        authTag,
+        algorithm
+    };
+}
+/**
+ * Decrypts data that was encrypted with the encrypt function.
+ *
+ * @param {EncryptionResult} encryptedData - The encrypted data and metadata
+ * @param {string | Buffer} key - Decryption key or passphrase
+ * @param {DecryptionOptions} [options] - Decryption options
+ * @returns {Promise<string | Buffer>} Decrypted data
+ */
+export async function decrypt(encryptedData, key, options = {}) {
+    const algorithm = options.algorithm || encryptedData.algorithm || 'aes-256-gcm';
+    const inputEncoding = options.inputEncoding || 'hex';
+    const outputEncoding = options.outputEncoding || 'utf8';
+    // Derive key using scrypt if key is a string (passphrase)
+    const derivedKey = typeof key === 'string' ? await scryptAsync(key, encryptedData.iv.slice(0, 8), 32) : key;
+    // Create decipher
+    const decipher = createDecipheriv(algorithm, derivedKey, encryptedData.iv);
+    // Set auth tag if using GCM mode
+    if (encryptedData.authTag && algorithm.includes('gcm')) {
+        decipher.setAuthTag(encryptedData.authTag);
+    }
+    // Decrypt the data
+    let decrypted;
+    if (typeof encryptedData.ciphertext === 'string') {
+        decrypted = decipher.update(encryptedData.ciphertext, inputEncoding, outputEncoding);
+        decrypted += decipher.final(outputEncoding);
+    }
+    else {
+        const result = Buffer.concat([decipher.update(encryptedData.ciphertext), decipher.final()]);
+        decrypted = outputEncoding ? result.toString(outputEncoding) : result;
+    }
+    return decrypted;
+}
+/**
+ * Creates a signed token with an expiration time and payload.
+ *
+ * @param {object} payload - Data to include in the token
+ * @param {string} secret - Secret key for signing
+ * @param {number} [expiresInSeconds=3600] - Token expiration in seconds
+ * @returns {string} Signed token string
+ */
+export function createSignedToken(payload, secret, expiresInSeconds = 3600) {
+    // Create payload with expiration
+    const tokenPayload = Object.assign(Object.assign({}, payload), { exp: Math.floor(Date.now() / 1000) + expiresInSeconds });
+    // Convert to string
+    const payloadStr = JSON.stringify(tokenPayload);
+    // Base64 encode the payload
+    const base64Payload = Buffer.from(payloadStr).toString('base64url');
+    // Create signature
+    const signature = hmac('sha256', base64Payload, secret, 'base64url');
+    // Combine payload and signature
+    return `${base64Payload}.${signature}`;
+}
+/**
+ * Verifies and decodes a signed token.
+ *
+ * @param {string} token - The token to verify
+ * @param {string} secret - Secret key for verification
+ * @returns {object | null} Decoded payload if valid, null if invalid
+ */
+export function verifySignedToken(token, secret) {
+    try {
+        // Split token into parts
+        const [payloadB64, signature] = token.split('.');
+        if (!payloadB64 || !signature)
+            return null;
+        // Verify signature
+        const expectedSignature = hmac('sha256', payloadB64, secret, 'base64url');
+        if (!safeCompare(signature, expectedSignature))
+            return null;
+        // Decode payload
+        const payloadStr = Buffer.from(payloadB64, 'base64url').toString('utf8');
+        const payload = JSON.parse(payloadStr);
+        // Check expiration
+        if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
+            return null;
+        }
+        return payload;
+    }
+    catch (_a) {
+        return null;
+    }
+}
 //# sourceMappingURL=crypto.utils.js.map