@catbee/utils 0.0.8-rc.2 → 0.0.8-rc.3

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

@@ -0,0 +1,297 @@
+"use strict";
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypedContextKey = exports.ContextStore = exports.StoreKeys = void 0;
+exports.getRequestId = getRequestId;
+exports.getFromContext = getFromContext;
+const async_hooks_1 = require("async_hooks");
+/**
+ * Predefined symbols used as keys in AsyncLocalStorage.
+ * Add new symbols here to avoid duplication.
+ */
+exports.StoreKeys = {
+    LOGGER: Symbol('LOGGER'),
+    REQUEST_ID: Symbol('REQUEST_ID'),
+    USER: Symbol('USER'),
+    SESSION: Symbol('SESSION'),
+    TRANSACTION_ID: Symbol('TRANSACTION_ID'),
+    USER_ID: Symbol('USER_ID'),
+    TENANT_ID: Symbol('TENANT_ID'),
+    TRACE_ID: Symbol('TRACE_ID'),
+    CORRELATION_ID: Symbol('CORRELATION_ID')
+};
+/**
+ * Retrieves the current request ID from the async context, if available.
+ *
+ * @returns {string | undefined} The request ID string or undefined if not present in the current context.
+ */
+function getRequestId() {
+    return ContextStore.get(exports.StoreKeys.REQUEST_ID);
+}
+/**
+ * Type-safe getter for common context values.
+ *
+ * @param key The store key symbol
+ * @returns The typed value from the store
+ */
+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).
+ *
+ * Example (Express middleware):
+ * ```
+ * // Middleware to initialize context and logger
+ * app.use((req, res, next) => {
+ *   const requestId = req.headers["x-request-id"]?.toString() || crypto.randomUUID();
+ *   ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {
+ *     ContextStore.set(StoreKeys.LOGGER, getLogger().child({ requestId }));
+ *     next();
+ *   });
+ * });
+ * ```
+ */
+class ContextStore {
+    /**
+     * The underlying AsyncLocalStorage instance for context.
+     * @private
+     */
+    static storage = new async_hooks_1.AsyncLocalStorage();
+    /**
+     * Returns the raw AsyncLocalStorage instance for advanced access.
+     *
+     * @returns {AsyncLocalStorage<Store>} The AsyncLocalStorage instance.
+     */
+    static getInstance() {
+        return this.storage;
+    }
+    /**
+     * Retrieves a value from the async context store by symbol key.
+     *
+     * @typeParam T - The expected return type of the value.
+     * @param {symbol} key - Unique symbol used as the store key.
+     * @returns {T | undefined} The value found (typed) or undefined if not present.
+     */
+    static get(key) {
+        const store = this.storage.getStore();
+        return store?.[key];
+    }
+    /**
+     * Sets a value in the current context store by symbol key.
+     *
+     * @typeParam T - The value type to set.
+     * @param {symbol} key - Unique symbol key.
+     * @param {T} value - Value to set in context.
+     * @throws {Error} If called outside an active context (not within a .run call or in the wrong async boundaries).
+     */
+    static set(key, value) {
+        const store = this.storage.getStore();
+        if (!store) {
+            throw new Error(`Failed to set ${String(key)}: AsyncLocalStorage store is not initialized.`);
+        }
+        store[key] = value;
+    }
+    /**
+     * Retrieves the entire context store object for the current async context.
+     *
+     * @returns {Store | undefined} The current store object or undefined if called outside a context.
+     */
+    static getAll() {
+        return this.storage.getStore();
+    }
+    /**
+     * Initializes a new async context and executes a callback within it.
+     * This must be called at the beginning of a request or logical async flow.
+     *
+     * @typeParam T - The callback's return type.
+     * @param {Store} store - The initial key-value store object.
+     * @param {() => T} callback - The function to run within the new context.
+     * @returns {T} The result of the callback function.
+     */
+    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 = { ...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);
+        };
+    }
+}
+exports.ContextStore = ContextStore;
+/**
+ * Type-safe wrapper for accessing and modifying context values with specific types.
+ *
+ * @typeParam T - The value type.
+ */
+class TypedContextKey {
+    symbol;
+    defaultValue;
+    /**
+     * 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);
+    }
+}
+exports.TypedContextKey = TypedContextKey;

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

@@ -0,0 +1,159 @@
+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.
+ *
+ * @param {string} algorithm - The hashing algorithm (e.g., 'sha256', 'sha1').
+ * @param {string} input - The string to hash.
+ * @param {string} secret - The secret key for HMAC.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
+ * @returns {string} HMAC digest as a string.
+ */
+export declare function hmac(algorithm: string, input: string, secret: string, encoding?: BinaryToTextEncoding): string;
+/**
+ * Generates a hash digest using the specified algorithm.
+ *
+ * @param {string} algorithm - The hashing algorithm (e.g., 'sha256', 'md5').
+ * @param {string} input - The string to hash.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
+ * @returns {string} Hash digest as a string.
+ */
+export declare function hash(algorithm: string, input: string, encoding?: BinaryToTextEncoding): string;
+/**
+ * Generates an HMAC-SHA256 digest.
+ *
+ * @param {string} input - The string to hash.
+ * @param {string} secret - The secret key.
+ * @returns {string} SHA-256 HMAC digest as a string.
+ */
+export declare function sha256Hmac(input: string, secret: string): string;
+/**
+ * Generates a SHA1 hash digest.
+ *
+ * @param {string} input - The string to hash.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
+ * @returns {string} SHA-1 hash as a string.
+ */
+export declare function sha1(input: string, encoding?: BinaryToTextEncoding): string;
+/**
+ * Generates a SHA256 hash digest.
+ *
+ * @param {string} input - The string to hash.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
+ * @returns {string} SHA-256 hash as a 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 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 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;