@catbee/utils 0.0.1

package/build/esm/utils/cache.utils.js

@@ -0,0 +1,294 @@
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+/**
+ * An in-memory cache with time-to-live (TTL) support for each entry.
+ *
+ * @typeParam K - Type of the key.
+ * @typeParam V - Type of the value.
+ *
+ * @example
+ * const cache = new TTLCache<string, number>(1000);
+ * cache.set("x", 123);
+ * const value = cache.get("x"); // 123
+ */
+var TTLCache = /** @class */ (function () {
+    /**
+     * @param ttlMs - Default time-to-live in milliseconds for cache entries.
+     */
+    function TTLCache(ttlMs) {
+        if (ttlMs === void 0) { ttlMs = 5 * 60 * 1000; }
+        this.ttlMs = ttlMs;
+        this.cache = new Map();
+    }
+    /**
+     * Sets a key-value pair in the cache with the default TTL.
+     *
+     * @param key - The key to set.
+     * @param value - The value to associate with the key.
+     */
+    TTLCache.prototype.set = function (key, value) {
+        var expiresAt = Date.now() + this.ttlMs;
+        this.cache.set(key, { value: value, expiresAt: expiresAt });
+    };
+    /**
+     * Sets a key-value pair in the cache with a custom TTL.
+     *
+     * @param key - The key to set.
+     * @param value - The value to associate with the key.
+     * @param ttlMs - Time-to-live in milliseconds.
+     */
+    TTLCache.prototype.setWithTTL = function (key, value, ttlMs) {
+        var expiresAt = Date.now() + ttlMs;
+        this.cache.set(key, { value: value, expiresAt: expiresAt });
+    };
+    /**
+     * Retrieves the value for a given key if it hasn't expired.
+     *
+     * @param key - The key to retrieve.
+     * @returns The cached value, or undefined if not found or expired.
+     */
+    TTLCache.prototype.get = function (key) {
+        var entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    };
+    /**
+     * Checks if the key exists and hasn't expired.
+     *
+     * @param key - The key to check.
+     * @returns `true` if key exists and is valid, otherwise `false`.
+     */
+    TTLCache.prototype.has = function (key) {
+        return this.get(key) !== undefined;
+    };
+    /**
+     * Deletes a key from the cache.
+     *
+     * @param key - The key to delete.
+     * @returns `true` if the key existed and was removed, `false` otherwise.
+     */
+    TTLCache.prototype.delete = function (key) {
+        return this.cache.delete(key);
+    };
+    /**
+     * Clears all entries from the cache.
+     */
+    TTLCache.prototype.clear = function () {
+        this.cache.clear();
+    };
+    /**
+     * Returns the number of entries currently in the cache (includes expired entries until next access/cleanup).
+     *
+     * @returns Number of items in the cache (may include expired keys).
+     */
+    TTLCache.prototype.size = function () {
+        return this.cache.size;
+    };
+    /**
+     * Removes all expired entries from the cache.
+     *
+     * @returns Number of entries removed.
+     */
+    TTLCache.prototype.cleanup = function () {
+        var e_1, _a;
+        var removed = 0;
+        var now = Date.now();
+        try {
+            for (var _b = __values(this.cache.entries()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var _d = __read(_c.value, 2), key = _d[0], entry = _d[1];
+                if (now > entry.expiresAt) {
+                    this.cache.delete(key);
+                    removed++;
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        return removed;
+    };
+    /**
+     * Returns an iterator of all current valid [key, value] pairs.
+     *
+     * @returns IterableIterator<[K, V]>
+     */
+    TTLCache.prototype.entries = function () {
+        var _a, _b, _c, key, entry, e_2_1;
+        var e_2, _d;
+        return __generator(this, function (_e) {
+            switch (_e.label) {
+                case 0:
+                    _e.trys.push([0, 5, 6, 7]);
+                    _a = __values(this.cache.entries()), _b = _a.next();
+                    _e.label = 1;
+                case 1:
+                    if (!!_b.done) return [3 /*break*/, 4];
+                    _c = __read(_b.value, 2), key = _c[0], entry = _c[1];
+                    if (!(Date.now() <= entry.expiresAt)) return [3 /*break*/, 3];
+                    return [4 /*yield*/, [key, entry.value]];
+                case 2:
+                    _e.sent();
+                    _e.label = 3;
+                case 3:
+                    _b = _a.next();
+                    return [3 /*break*/, 1];
+                case 4: return [3 /*break*/, 7];
+                case 5:
+                    e_2_1 = _e.sent();
+                    e_2 = { error: e_2_1 };
+                    return [3 /*break*/, 7];
+                case 6:
+                    try {
+                        if (_b && !_b.done && (_d = _a.return)) _d.call(_a);
+                    }
+                    finally { if (e_2) throw e_2.error; }
+                    return [7 /*endfinally*/];
+                case 7: return [2 /*return*/];
+            }
+        });
+    };
+    /**
+     * Returns an iterator of all current valid keys.
+     *
+     * @returns IterableIterator<K>
+     */
+    TTLCache.prototype.keys = function () {
+        var _a, _b, _c, key, entry, e_3_1;
+        var e_3, _d;
+        return __generator(this, function (_e) {
+            switch (_e.label) {
+                case 0:
+                    _e.trys.push([0, 5, 6, 7]);
+                    _a = __values(this.cache.entries()), _b = _a.next();
+                    _e.label = 1;
+                case 1:
+                    if (!!_b.done) return [3 /*break*/, 4];
+                    _c = __read(_b.value, 2), key = _c[0], entry = _c[1];
+                    if (!(Date.now() <= entry.expiresAt)) return [3 /*break*/, 3];
+                    return [4 /*yield*/, key];
+                case 2:
+                    _e.sent();
+                    _e.label = 3;
+                case 3:
+                    _b = _a.next();
+                    return [3 /*break*/, 1];
+                case 4: return [3 /*break*/, 7];
+                case 5:
+                    e_3_1 = _e.sent();
+                    e_3 = { error: e_3_1 };
+                    return [3 /*break*/, 7];
+                case 6:
+                    try {
+                        if (_b && !_b.done && (_d = _a.return)) _d.call(_a);
+                    }
+                    finally { if (e_3) throw e_3.error; }
+                    return [7 /*endfinally*/];
+                case 7: return [2 /*return*/];
+            }
+        });
+    };
+    /**
+     * Returns an iterator of all current valid values.
+     *
+     * @returns IterableIterator<V>
+     */
+    TTLCache.prototype.values = function () {
+        var _a, _b, entry, e_4_1;
+        var e_4, _c;
+        return __generator(this, function (_d) {
+            switch (_d.label) {
+                case 0:
+                    _d.trys.push([0, 5, 6, 7]);
+                    _a = __values(this.cache.values()), _b = _a.next();
+                    _d.label = 1;
+                case 1:
+                    if (!!_b.done) return [3 /*break*/, 4];
+                    entry = _b.value;
+                    if (!(Date.now() <= entry.expiresAt)) return [3 /*break*/, 3];
+                    return [4 /*yield*/, entry.value];
+                case 2:
+                    _d.sent();
+                    _d.label = 3;
+                case 3:
+                    _b = _a.next();
+                    return [3 /*break*/, 1];
+                case 4: return [3 /*break*/, 7];
+                case 5:
+                    e_4_1 = _d.sent();
+                    e_4 = { error: e_4_1 };
+                    return [3 /*break*/, 7];
+                case 6:
+                    try {
+                        if (_b && !_b.done && (_c = _a.return)) _c.call(_a);
+                    }
+                    finally { if (e_4) throw e_4.error; }
+                    return [7 /*endfinally*/];
+                case 7: return [2 /*return*/];
+            }
+        });
+    };
+    return TTLCache;
+}());
+export { TTLCache };
+//# sourceMappingURL=cache.utils.js.map

package/build/esm/utils/cache.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.utils.js","sourceRoot":"","sources":["../../../src/utils/cache.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Represents a cached entry with a value and an expiration timestamp.\n */\ntype CacheEntry<T> = {\n  value: T;\n  expiresAt: number;\n};\n\n/**\n * An in-memory cache with time-to-live (TTL) support for each entry.\n *\n * @typeParam K - Type of the key.\n * @typeParam V - Type of the value.\n *\n * @example\n * const cache = new TTLCache<string, number>(1000);\n * cache.set(\"x\", 123);\n * const value = cache.get(\"x\"); // 123\n */\nexport class TTLCache<K, V> {\n  private cache = new Map<K, CacheEntry<V>>();\n\n  /**\n   * @param ttlMs - Default time-to-live in milliseconds for cache entries.\n   */\n  constructor(private ttlMs: number = 5 * 60 * 1000) {}\n\n  /**\n   * Sets a key-value pair in the cache with the default TTL.\n   *\n   * @param key - The key to set.\n   * @param value - The value to associate with the key.\n   */\n  set(key: K, value: V): void {\n    const expiresAt = Date.now() + this.ttlMs;\n    this.cache.set(key, { value, expiresAt });\n  }\n\n  /**\n   * Sets a key-value pair in the cache with a custom TTL.\n   *\n   * @param key - The key to set.\n   * @param value - The value to associate with the key.\n   * @param ttlMs - Time-to-live in milliseconds.\n   */\n  setWithTTL(key: K, value: V, ttlMs: number): void {\n    const expiresAt = Date.now() + ttlMs;\n    this.cache.set(key, { value, expiresAt });\n  }\n\n  /**\n   * Retrieves the value for a given key if it hasn't expired.\n   *\n   * @param key - The key to retrieve.\n   * @returns The cached value, or undefined if not found or expired.\n   */\n  get(key: K): V | undefined {\n    const entry = this.cache.get(key);\n    if (!entry) return undefined;\n    if (Date.now() > entry.expiresAt) {\n      this.cache.delete(key);\n      return undefined;\n    }\n    return entry.value;\n  }\n\n  /**\n   * Checks if the key exists and hasn't expired.\n   *\n   * @param key - The key to check.\n   * @returns `true` if key exists and is valid, otherwise `false`.\n   */\n  has(key: K): boolean {\n    return this.get(key) !== undefined;\n  }\n\n  /**\n   * Deletes a key from the cache.\n   *\n   * @param key - The key to delete.\n   * @returns `true` if the key existed and was removed, `false` otherwise.\n   */\n  delete(key: K): boolean {\n    return this.cache.delete(key);\n  }\n\n  /**\n   * Clears all entries from the cache.\n   */\n  clear(): void {\n    this.cache.clear();\n  }\n\n  /**\n   * Returns the number of entries currently in the cache (includes expired entries until next access/cleanup).\n   *\n   * @returns Number of items in the cache (may include expired keys).\n   */\n  size(): number {\n    return this.cache.size;\n  }\n\n  /**\n   * Removes all expired entries from the cache.\n   *\n   * @returns Number of entries removed.\n   */\n  cleanup(): number {\n    let removed = 0;\n    const now = Date.now();\n    for (const [key, entry] of this.cache.entries()) {\n      if (now > entry.expiresAt) {\n        this.cache.delete(key);\n        removed++;\n      }\n    }\n    return removed;\n  }\n\n  /**\n   * Returns an iterator of all current valid [key, value] pairs.\n   *\n   * @returns IterableIterator<[K, V]>\n   */\n  *entries(): IterableIterator<[K, V]> {\n    for (const [key, entry] of this.cache.entries()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield [key, entry.value];\n      }\n    }\n  }\n\n  /**\n   * Returns an iterator of all current valid keys.\n   *\n   * @returns IterableIterator<K>\n   */\n  *keys(): IterableIterator<K> {\n    for (const [key, entry] of this.cache.entries()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield key;\n      }\n    }\n  }\n\n  /**\n   * Returns an iterator of all current valid values.\n   *\n   * @returns IterableIterator<V>\n   */\n  *values(): IterableIterator<V> {\n    for (const entry of this.cache.values()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield entry.value;\n      }\n    }\n  }\n}\n"]}

package/build/esm/utils/context-store.utils.d.ts

@@ -0,0 +1,85 @@
+import { AsyncLocalStorage } from "async_hooks";
+/**
+ * Type representing the store object used in AsyncLocalStorage.
+ * Keys must be unique symbols to ensure isolation and prevent collisions.
+ */
+export interface Store {
+    [key: symbol]: unknown;
+}
+/**
+ * Predefined symbols used as keys in AsyncLocalStorage.
+ * Add new symbols here to avoid duplication.
+ */
+export declare const StoreKeys: {
+    LOGGER: symbol;
+    REQUEST_ID: symbol;
+};
+/**
+ * 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.
+ */
+export declare function getRequestId(): string | undefined;
+/**
+ * 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({ reqId: requestId }));
+ *     next();
+ *   });
+ * });
+ * ```
+ */
+export declare class ContextStore {
+    /**
+     * The underlying AsyncLocalStorage instance for context.
+     * @private
+     */
+    private static readonly storage;
+    /**
+     * Returns the raw AsyncLocalStorage instance for advanced access.
+     *
+     * @returns {AsyncLocalStorage<Store>} The AsyncLocalStorage instance.
+     */
+    static getInstance(): AsyncLocalStorage<Store>;
+    /**
+     * 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<T>(key: symbol): T | undefined;
+    /**
+     * 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<T>(key: symbol, value: T): void;
+    /**
+     * 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(): Store | undefined;
+    /**
+     * 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<T>(store: Store, callback: () => T): T;
+}
+//# sourceMappingURL=context-store.utils.d.ts.map

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

@@ -0,0 +1,99 @@
+import { AsyncLocalStorage } from "async_hooks";
+/**
+ * Predefined symbols used as keys in AsyncLocalStorage.
+ * Add new symbols here to avoid duplication.
+ */
+export var StoreKeys = {
+    LOGGER: Symbol("logger"),
+    REQUEST_ID: Symbol("requestId"),
+};
+/**
+ * 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.
+ */
+export function getRequestId() {
+    return ContextStore.get(StoreKeys.REQUEST_ID);
+}
+/**
+ * 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({ reqId: requestId }));
+ *     next();
+ *   });
+ * });
+ * ```
+ */
+var ContextStore = /** @class */ (function () {
+    function ContextStore() {
+    }
+    /**
+     * Returns the raw AsyncLocalStorage instance for advanced access.
+     *
+     * @returns {AsyncLocalStorage<Store>} The AsyncLocalStorage instance.
+     */
+    ContextStore.getInstance = function () {
+        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.
+     */
+    ContextStore.get = function (key) {
+        var store = this.storage.getStore();
+        return store === null || store === void 0 ? void 0 : 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).
+     */
+    ContextStore.set = function (key, value) {
+        var store = this.storage.getStore();
+        if (!store) {
+            throw new Error("Failed to set ".concat(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.
+     */
+    ContextStore.getAll = function () {
+        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.
+     */
+    ContextStore.run = function (store, callback) {
+        return this.storage.run(store, callback);
+    };
+    /**
+     * The underlying AsyncLocalStorage instance for context.
+     * @private
+     */
+    ContextStore.storage = new AsyncLocalStorage();
+    return ContextStore;
+}());
+export { ContextStore };
+//# sourceMappingURL=context-store.utils.js.map

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

@@ -0,0 +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,IAAM,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;IAAA;IAmEA,CAAC;IA5DC;;;;OAIG;IACI,wBAAW,GAAlB;QACE,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACI,gBAAG,GAAV,UAAc,GAAW;QACvB,IAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAG,GAAG,CAAkB,CAAC;IACvC,CAAC;IAED;;;;;;;OAOG;IACI,gBAAG,GAAV,UAAc,GAAW,EAAE,KAAQ;QACjC,IAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,wBAAiB,MAAM,CAAC,GAAG,CAAC,kDAA+C,CAC5E,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACI,mBAAM,GAAb;QACE,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;IAED;;;;;;;;OAQG;IACI,gBAAG,GAAV,UAAc,KAAY,EAAE,QAAiB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAjED;;;OAGG;IACqB,oBAAO,GAAG,IAAI,iBAAiB,EAAS,CAAC;IA8DnE,mBAAC;CAAA,AAnED,IAmEC;SAnEY,YAAY","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"]}

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

@@ -0,0 +1,58 @@
+import { BinaryToTextEncoding } from "crypto";
+/**
+ * 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 const 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 const 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 const 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 const 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 const 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;
+/**
+ * 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;
+//# sourceMappingURL=crypto.utils.d.ts.map

package/build/esm/utils/crypto.utils.js

@@ -0,0 +1,76 @@
+import { createHmac, createHash, randomUUID, } from "crypto";
+/**
+ * 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 var hmac = function (algorithm, input, secret, encoding) {
+    if (encoding === void 0) { encoding = "hex"; }
+    return createHmac(algorithm, secret).update(input).digest(encoding);
+};
+/**
+ * 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 var hash = function (algorithm, input, encoding) {
+    if (encoding === void 0) { encoding = "hex"; }
+    return createHash(algorithm).update(input).digest(encoding);
+};
+/**
+ * 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 var sha256Hmac = function (input, secret) {
+    return hmac("sha256", input, secret);
+};
+/**
+ * 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 var sha1 = function (input, encoding) {
+    if (encoding === void 0) { encoding = "hex"; }
+    return hash("sha1", input, encoding);
+};
+/**
+ * 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 var sha256 = function (input, encoding) {
+    if (encoding === void 0) { 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 var md5 = function (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 var randomString = function () {
+    return sha256(randomUUID());
+};
+//# sourceMappingURL=crypto.utils.js.map

package/build/esm/utils/crypto.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.utils.js","sourceRoot":"","sources":["../../../src/utils/crypto.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,UAAU,EAEV,UAAU,GACX,MAAM,QAAQ,CAAC;AAEhB;;;;;;;;GAQG;AACH,MAAM,CAAC,IAAM,IAAI,GAAG,UAClB,SAAiB,EACjB,KAAa,EACb,MAAc,EACd,QAAsC;IAAtC,yBAAA,EAAA,gBAAsC;IAEtC,OAAO,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACtE,CAAC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,IAAM,IAAI,GAAG,UAClB,SAAiB,EACjB,KAAa,EACb,QAAsC;IAAtC,yBAAA,EAAA,gBAAsC;IAEtC,OAAO,UAAU,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC9D,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,IAAM,UAAU,GAAG,UAAC,KAAa,EAAE,MAAc;IACtD,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,IAAM,IAAI,GAAG,UAClB,KAAa,EACb,QAAsC;IAAtC,yBAAA,EAAA,gBAAsC;IAEtC,OAAO,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,IAAM,MAAM,GAAG,UACpB,KAAa,EACb,QAAsC;IAAtC,yBAAA,EAAA,gBAAsC;IAEtC,OAAO,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AACzC,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,IAAM,GAAG,GAAG,UAAC,KAAa;IAC/B,OAAO,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAC5B,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,IAAM,YAAY,GAAG;IAC1B,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;AAC9B,CAAC,CAAC","sourcesContent":["import {\n  createHmac,\n  createHash,\n  BinaryToTextEncoding,\n  randomUUID,\n} from \"crypto\";\n\n/**\n * Generates an HMAC digest using the specified algorithm and secret key.\n *\n * @param {string} algorithm - The hashing algorithm (e.g., 'sha256', 'sha1').\n * @param {string} input - The string to hash.\n * @param {string} secret - The secret key for HMAC.\n * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).\n * @returns {string} HMAC digest as a string.\n */\nexport const hmac = (\n  algorithm: string,\n  input: string,\n  secret: string,\n  encoding: BinaryToTextEncoding = \"hex\",\n): string => {\n  return createHmac(algorithm, secret).update(input).digest(encoding);\n};\n\n/**\n * Generates a hash digest using the specified algorithm.\n *\n * @param {string} algorithm - The hashing algorithm (e.g., 'sha256', 'md5').\n * @param {string} input - The string to hash.\n * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).\n * @returns {string} Hash digest as a string.\n */\nexport const hash = (\n  algorithm: string,\n  input: string,\n  encoding: BinaryToTextEncoding = \"hex\",\n): string => {\n  return createHash(algorithm).update(input).digest(encoding);\n};\n\n/**\n * Generates an HMAC-SHA256 digest.\n *\n * @param {string} input - The string to hash.\n * @param {string} secret - The secret key.\n * @returns {string} SHA-256 HMAC digest as a string.\n */\nexport const sha256Hmac = (input: string, secret: string): string => {\n  return hmac(\"sha256\", input, secret);\n};\n\n/**\n * Generates a SHA1 hash digest.\n *\n * @param {string} input - The string to hash.\n * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.\n * @returns {string} SHA-1 hash as a string.\n */\nexport const sha1 = (\n  input: string,\n  encoding: BinaryToTextEncoding = \"hex\",\n): string => {\n  return hash(\"sha1\", input, encoding);\n};\n\n/**\n * Generates a SHA256 hash digest.\n *\n * @param {string} input - The string to hash.\n * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.\n * @returns {string} SHA-256 hash as a string.\n */\nexport const sha256 = (\n  input: string,\n  encoding: BinaryToTextEncoding = \"hex\",\n): string => {\n  return hash(\"sha256\", input, encoding);\n};\n\n/**\n * Generates an MD5 hash digest.\n *\n * @param {string} input - The string to hash.\n * @returns {string} MD5 hash as a string.\n */\nexport const md5 = (input: string): string => {\n  return hash(\"md5\", input);\n};\n\n/**\n * Generates a cryptographically strong random string by hashing a random UUID with SHA-256.\n *\n * @returns {string} Random string hashed with SHA-256 (hex encoding).\n */\nexport const randomString = (): string => {\n  return sha256(randomUUID());\n};\n"]}