@catbee/utils 1.1.0 → 2.0.0-next.0

package/config/index.cjs

@@ -0,0 +1,136 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
+ */
+
+'use strict';
+
+var env = require('@catbee/utils/env');
+var id = require('@catbee/utils/id');
+var obj = require('@catbee/utils/obj');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var defaultCatbeeConfig = {
+  logger: {
+    level: env.Env.get("LOGGER_LEVEL", env.Env.isDev() ? "debug" : "info"),
+    name: env.Env.get("LOGGER_NAME", env.Env.get("npm_package_name", "@catbee/utils")),
+    pretty: env.Env.getBoolean("LOGGER_PRETTY", false),
+    colorize: env.Env.getBoolean("LOGGER_PRETTY_COLORIZE", true),
+    singleLine: env.Env.getBoolean("LOGGER_PRETTY_SINGLE_LINE", false),
+    dir: env.Env.getPath("LOGGER_DIR", "", {
+      mustExist: false
+    })
+  },
+  cache: {
+    defaultTtl: env.Env.getNumber("CACHE_DEFAULT_TTL_SECONDS", 3600) * 1e3
+  },
+  server: {
+    skipHealthz: env.Env.getBoolean("SERVER_SKIP_HEALTHZ", false)
+  }
+};
+var defaultServerConfig = {
+  port: 3e3,
+  host: "0.0.0.0",
+  cors: false,
+  helmet: false,
+  compression: false,
+  bodyParser: {
+    json: {
+      limit: "1mb"
+    },
+    urlencoded: {
+      extended: true,
+      limit: "1mb"
+    }
+  },
+  cookieParser: false,
+  isMicroservice: false,
+  appName: "express_app",
+  globalHeaders: {},
+  rateLimit: {
+    enable: false,
+    windowMs: 15 * 60 * 1e3,
+    max: 100,
+    message: "Too many requests",
+    standardHeaders: true,
+    legacyHeaders: false
+  },
+  requestLogging: {
+    enable: env.Env.isDev(),
+    ignorePaths: /* @__PURE__ */ __name((req, _res) => {
+      const skipPaths = [
+        "/healthz",
+        "/favicon.ico",
+        "/metrics",
+        "/docs",
+        "/.well-known"
+      ];
+      return skipPaths.some((path) => req.path.startsWith(path));
+    }, "ignorePaths"),
+    skipNotFoundRoutes: false
+  },
+  openApi: {
+    enable: false,
+    mountPath: "/docs",
+    verbose: false,
+    withGlobalPrefix: false
+  },
+  healthCheck: {
+    path: "/healthz",
+    detailed: true
+  },
+  requestTimeout: 3e4,
+  responseTime: {
+    enable: false,
+    addHeader: true,
+    logOnComplete: false
+  },
+  requestId: {
+    headerName: "x-request-id",
+    exposeHeader: true,
+    generator: /* @__PURE__ */ __name(() => id.uuid(), "generator")
+  },
+  metrics: {
+    enable: false,
+    path: "/metrics",
+    withGlobalPrefix: false
+  },
+  serviceVersion: {
+    enable: false,
+    headerName: "x-service-version",
+    version: "0.0.0"
+  }
+};
+function setConfig(value) {
+  obj.deepObjMerge(defaultCatbeeConfig, value);
+}
+__name(setConfig, "setConfig");
+function getConfig() {
+  return defaultCatbeeConfig;
+}
+__name(getConfig, "getConfig");
+
+exports.defaultCatbeeConfig = defaultCatbeeConfig;
+exports.defaultServerConfig = defaultServerConfig;
+exports.getConfig = getConfig;
+exports.setConfig = setConfig;

package/config/index.d.ts

@@ -0,0 +1,26 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
+ */
+
+export { setConfig, getConfig } from './config';
+export { defaultCatbeeConfig, defaultServerConfig } from './config';

package/config/index.mjs

@@ -0,0 +1,131 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
+ */
+
+import { Env } from '@catbee/utils/env';
+import { uuid } from '@catbee/utils/id';
+import { deepObjMerge } from '@catbee/utils/obj';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var defaultCatbeeConfig = {
+  logger: {
+    level: Env.get("LOGGER_LEVEL", Env.isDev() ? "debug" : "info"),
+    name: Env.get("LOGGER_NAME", Env.get("npm_package_name", "@catbee/utils")),
+    pretty: Env.getBoolean("LOGGER_PRETTY", false),
+    colorize: Env.getBoolean("LOGGER_PRETTY_COLORIZE", true),
+    singleLine: Env.getBoolean("LOGGER_PRETTY_SINGLE_LINE", false),
+    dir: Env.getPath("LOGGER_DIR", "", {
+      mustExist: false
+    })
+  },
+  cache: {
+    defaultTtl: Env.getNumber("CACHE_DEFAULT_TTL_SECONDS", 3600) * 1e3
+  },
+  server: {
+    skipHealthz: Env.getBoolean("SERVER_SKIP_HEALTHZ", false)
+  }
+};
+var defaultServerConfig = {
+  port: 3e3,
+  host: "0.0.0.0",
+  cors: false,
+  helmet: false,
+  compression: false,
+  bodyParser: {
+    json: {
+      limit: "1mb"
+    },
+    urlencoded: {
+      extended: true,
+      limit: "1mb"
+    }
+  },
+  cookieParser: false,
+  isMicroservice: false,
+  appName: "express_app",
+  globalHeaders: {},
+  rateLimit: {
+    enable: false,
+    windowMs: 15 * 60 * 1e3,
+    max: 100,
+    message: "Too many requests",
+    standardHeaders: true,
+    legacyHeaders: false
+  },
+  requestLogging: {
+    enable: Env.isDev(),
+    ignorePaths: /* @__PURE__ */ __name((req, _res) => {
+      const skipPaths = [
+        "/healthz",
+        "/favicon.ico",
+        "/metrics",
+        "/docs",
+        "/.well-known"
+      ];
+      return skipPaths.some((path) => req.path.startsWith(path));
+    }, "ignorePaths"),
+    skipNotFoundRoutes: false
+  },
+  openApi: {
+    enable: false,
+    mountPath: "/docs",
+    verbose: false,
+    withGlobalPrefix: false
+  },
+  healthCheck: {
+    path: "/healthz",
+    detailed: true
+  },
+  requestTimeout: 3e4,
+  responseTime: {
+    enable: false,
+    addHeader: true,
+    logOnComplete: false
+  },
+  requestId: {
+    headerName: "x-request-id",
+    exposeHeader: true,
+    generator: /* @__PURE__ */ __name(() => uuid(), "generator")
+  },
+  metrics: {
+    enable: false,
+    path: "/metrics",
+    withGlobalPrefix: false
+  },
+  serviceVersion: {
+    enable: false,
+    headerName: "x-service-version",
+    version: "0.0.0"
+  }
+};
+function setConfig(value) {
+  deepObjMerge(defaultCatbeeConfig, value);
+}
+__name(setConfig, "setConfig");
+function getConfig() {
+  return defaultCatbeeConfig;
+}
+__name(getConfig, "getConfig");
+
+export { defaultCatbeeConfig, defaultServerConfig, getConfig, setConfig };

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

@@ -0,0 +1,212 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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.
+ */
+
+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;
+    USER: symbol;
+    SESSION: symbol;
+    TRANSACTION_ID: symbol;
+    USER_ID: symbol;
+    TENANT_ID: symbol;
+    TRACE_ID: symbol;
+    CORRELATION_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;
+/**
+ * Type-safe getter for common context values.
+ *
+ * @param key The store key symbol
+ * @returns The typed value from the store
+ */
+export declare function getFromContext<T>(key: symbol): T | 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({ 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;
+    /**
+     * 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: symbol): boolean;
+    /**
+     * 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: symbol): boolean;
+    /**
+     * 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: Partial<Record<symbol, unknown>>): void;
+    /**
+     * 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<T>(key: symbol, value: unknown, callback: () => T): T;
+    /**
+     * 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<T>(newValues: Partial<Record<symbol, unknown>>, callback: () => T): T;
+    /**
+     * 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?: (req: any) => Partial<Record<symbol, unknown>>): (req: any, _res: any, next: any) => void;
+}
+/**
+ * Type-safe wrapper for accessing and modifying context values with specific types.
+ *
+ * @typeParam T - The value type.
+ */
+export declare class TypedContextKey<T> {
+    private symbol;
+    private 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: symbol, defaultValue?: T | undefined);
+    /**
+     * Gets the current value for this key.
+     *
+     * @returns The value or defaultValue if not found
+     */
+    get(): T | undefined;
+    /**
+     * Sets the value for this key.
+     *
+     * @param value The value to set
+     */
+    set(value: T): void;
+    /**
+     * Checks if this key exists in the context.
+     *
+     * @returns True if the key exists
+     */
+    exists(): boolean;
+    /**
+     * Deletes this key from the context.
+     *
+     * @returns True if the key was deleted
+     */
+    delete(): boolean;
+}