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

package/build/src/utils/http-status-codes.d.ts

@@ -1,266 +0,0 @@
-/**
- * Complete HTTP status codes enum with descriptions.
- * For use with API responses and error handling.
- */
-export declare enum HttpStatusCodes {
-    /**
-     * The server has received the request headers and the client should proceed to send the request body.
-     */
-    CONTINUE = 100,
-    /**
-     * The server is switching protocols according to the client's request.
-     */
-    SWITCHING_PROTOCOLS = 101,
-    /**
-     * Server has received the request and is still processing it.
-     */
-    PROCESSING = 102,
-    /**
-     * The server is sending preliminary headers while preparing the final response.
-     */
-    EARLY_HINTS = 103,
-    /**
-     * The request succeeded. The result meaning depends on the HTTP method used.
-     */
-    OK = 200,
-    /**
-     * The request succeeded and a new resource was created as a result.
-     */
-    CREATED = 201,
-    /**
-     * The request has been received but not yet acted upon.
-     */
-    ACCEPTED = 202,
-    /**
-     * The returned information is from a third-party source, not the origin server.
-     */
-    NON_AUTHORITATIVE_INFORMATION = 203,
-    /**
-     * The request succeeded but there's no content to send in the response.
-     */
-    NO_CONTENT = 204,
-    /**
-     * The client should reset the document view that caused this request.
-     */
-    RESET_CONTENT = 205,
-    /**
-     * The server is delivering only part of the resource due to a range header sent by the client.
-     */
-    PARTIAL_CONTENT = 206,
-    /**
-     * Conveys information about multiple resources, for complex operations.
-     */
-    MULTI_STATUS = 207,
-    /**
-     * The members of a DAV binding have already been enumerated and are not included in the response.
-     */
-    ALREADY_REPORTED = 208,
-    /**
-     * The server has fulfilled a request for the resource, and the response represents the result of one or more instance-manipulations.
-     */
-    IM_USED = 226,
-    /**
-     * The request has more than one possible response and the client should choose one.
-     */
-    MULTIPLE_CHOICES = 300,
-    /**
-     * The resource has been permanently moved to a new URL.
-     */
-    MOVED_PERMANENTLY = 301,
-    /**
-     * The resource has been temporarily moved to another URL.
-     */
-    MOVED_TEMPORARILY = 302,
-    /**
-     * The response to the request can be found under another URI using the GET method.
-     */
-    SEE_OTHER = 303,
-    /**
-     * The resource hasn't been modified since the last request.
-     */
-    NOT_MODIFIED = 304,
-    /**
-     * @deprecated
-     * Response must be accessed through a proxy.
-     */
-    USE_PROXY = 305,
-    /**
-     * The resource is temporarily available at a different URI, using the same HTTP method.
-     */
-    TEMPORARY_REDIRECT = 307,
-    /**
-     * The resource has been permanently moved to another URL, using the same HTTP method.
-     */
-    PERMANENT_REDIRECT = 308,
-    /**
-     * The server cannot process the request due to a client error (malformed request).
-     */
-    BAD_REQUEST = 400,
-    /**
-     * Authentication is required and has failed or not been provided.
-     */
-    UNAUTHORIZED = 401,
-    /**
-     * Reserved for future use, originally intended for digital payment systems.
-     */
-    PAYMENT_REQUIRED = 402,
-    /**
-     * The client doesn't have permission to access the requested resource.
-     */
-    FORBIDDEN = 403,
-    /**
-     * The requested resource could not be found on the server.
-     */
-    NOT_FOUND = 404,
-    /**
-     * The request method is not supported for the requested resource.
-     */
-    METHOD_NOT_ALLOWED = 405,
-    /**
-     * The server can't provide a response matching the list of acceptable values in the client's headers.
-     */
-    NOT_ACCEPTABLE = 406,
-    /**
-     * Authentication by a proxy is required.
-     */
-    PROXY_AUTHENTICATION_REQUIRED = 407,
-    /**
-     * The server timed out waiting for the request.
-     */
-    REQUEST_TIMEOUT = 408,
-    /**
-     * The request conflicts with the current state of the server.
-     */
-    CONFLICT = 409,
-    /**
-     * The resource has been permanently deleted with no forwarding address.
-     */
-    GONE = 410,
-    /**
-     * The server requires a Content-Length header field.
-     */
-    LENGTH_REQUIRED = 411,
-    /**
-     * Preconditions in the client's headers failed.
-     */
-    PRECONDITION_FAILED = 412,
-    /**
-     * Request entity is larger than limits defined by server.
-     */
-    REQUEST_TOO_LONG = 413,
-    /**
-     * The request payload exceeds server size limits.
-     * Modern equivalent of REQUEST_TOO_LONG.
-     */
-    PAYLOAD_TOO_LARGE = 413,
-    /**
-     * The URI requested is too long for the server to interpret.
-     */
-    REQUEST_URI_TOO_LONG = 414,
-    /**
-     * The server does not support the media type requested by the client.
-     */
-    UNSUPPORTED_MEDIA_TYPE = 415,
-    /**
-     * The range specified by the Range header cannot be fulfilled.
-     */
-    REQUESTED_RANGE_NOT_SATISFIABLE = 416,
-    /**
-     * The server cannot meet the expectations given in the Expect header.
-     */
-    EXPECTATION_FAILED = 417,
-    /**
-     * The server refuses to brew coffee because it is a teapot. (April Fools' joke)
-     */
-    IM_A_TEAPOT = 418,
-    /**
-     * The server cannot store the representation needed to complete the request.
-     */
-    INSUFFICIENT_SPACE_ON_RESOURCE = 419,
-    /**
-     * @deprecated
-     * A method has failed - specific to Spring Framework.
-     */
-    METHOD_FAILURE = 420,
-    /**
-     * The server cannot produce a response for the requested URI scheme and authority.
-     */
-    MISDIRECTED_REQUEST = 421,
-    /**
-     * The request was well-formed but has semantic errors preventing processing.
-     */
-    UNPROCESSABLE_ENTITY = 422,
-    /**
-     * The requested resource is locked against access.
-     */
-    LOCKED = 423,
-    /**
-     * The request failed due to the failure of a previous request.
-     */
-    FAILED_DEPENDENCY = 424,
-    /**
-     * The client should switch to a different protocol.
-     */
-    UPGRADE_REQUIRED = 426,
-    /**
-     * The server requires conditional requests to prevent lost updates.
-     */
-    PRECONDITION_REQUIRED = 428,
-    /**
-     * The client has sent too many requests in a given time period (rate limiting).
-     */
-    TOO_MANY_REQUESTS = 429,
-    /**
-     * Request headers are too large for the server to process.
-     */
-    REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
-    /**
-     * Resource cannot be legally provided (e.g., censored by government).
-     */
-    UNAVAILABLE_FOR_LEGAL_REASONS = 451,
-    /**
-     * The server encountered an unexpected error preventing it from fulfilling the request.
-     */
-    INTERNAL_SERVER_ERROR = 500,
-    /**
-     * The server does not support the functionality required to fulfill the request.
-     */
-    NOT_IMPLEMENTED = 501,
-    /**
-     * The server, acting as a gateway, received an invalid response from an upstream server.
-     */
-    BAD_GATEWAY = 502,
-    /**
-     * The server is currently unable to handle the request due to temporary overload or maintenance.
-     */
-    SERVICE_UNAVAILABLE = 503,
-    /**
-     * The server, acting as a gateway, did not receive a timely response from an upstream server.
-     */
-    GATEWAY_TIMEOUT = 504,
-    /**
-     * The server does not support the HTTP protocol version used in the request.
-     */
-    HTTP_VERSION_NOT_SUPPORTED = 505,
-    /**
-     * Transparent content negotiation for the request resulted in circular reference.
-     */
-    VARIANT_ALSO_NEGOTIATES = 506,
-    /**
-     * The server cannot store the representation needed to complete the request.
-     */
-    INSUFFICIENT_STORAGE = 507,
-    /**
-     * The server detected an infinite loop while processing the request.
-     */
-    LOOP_DETECTED = 508,
-    /**
-     * Further extensions to the request are required for the server to fulfill it.
-     */
-    NOT_EXTENDED = 510,
-    /**
-     * The client needs to authenticate to gain network access.
-     */
-    NETWORK_AUTHENTICATION_REQUIRED = 511
-}
-//# sourceMappingURL=http-status-codes.d.ts.map

package/build/src/utils/http-status-codes.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"http-status-codes.js","sourceRoot":"","sources":["../../../src/utils/http-status-codes.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Complete HTTP status codes enum with descriptions.\n * For use with API responses and error handling.\n */\nexport enum HttpStatusCodes {\n  // 1xx Informational\n  /**\n   * The server has received the request headers and the client should proceed to send the request body.\n   */\n  CONTINUE = 100,\n\n  /**\n   * The server is switching protocols according to the client's request.\n   */\n  SWITCHING_PROTOCOLS = 101,\n\n  /**\n   * Server has received the request and is still processing it.\n   */\n  PROCESSING = 102,\n\n  /**\n   * The server is sending preliminary headers while preparing the final response.\n   */\n  EARLY_HINTS = 103,\n\n  // 2xx Success\n  /**\n   * The request succeeded. The result meaning depends on the HTTP method used.\n   */\n  OK = 200,\n\n  /**\n   * The request succeeded and a new resource was created as a result.\n   */\n  CREATED = 201,\n\n  /**\n   * The request has been received but not yet acted upon.\n   */\n  ACCEPTED = 202,\n\n  /**\n   * The returned information is from a third-party source, not the origin server.\n   */\n  NON_AUTHORITATIVE_INFORMATION = 203,\n\n  /**\n   * The request succeeded but there's no content to send in the response.\n   */\n  NO_CONTENT = 204,\n\n  /**\n   * The client should reset the document view that caused this request.\n   */\n  RESET_CONTENT = 205,\n\n  /**\n   * The server is delivering only part of the resource due to a range header sent by the client.\n   */\n  PARTIAL_CONTENT = 206,\n\n  /**\n   * Conveys information about multiple resources, for complex operations.\n   */\n  MULTI_STATUS = 207,\n\n  /**\n   * The members of a DAV binding have already been enumerated and are not included in the response.\n   */\n  ALREADY_REPORTED = 208,\n\n  /**\n   * The server has fulfilled a request for the resource, and the response represents the result of one or more instance-manipulations.\n   */\n  IM_USED = 226,\n\n  // 3xx Redirection\n  /**\n   * The request has more than one possible response and the client should choose one.\n   */\n  MULTIPLE_CHOICES = 300,\n\n  /**\n   * The resource has been permanently moved to a new URL.\n   */\n  MOVED_PERMANENTLY = 301,\n\n  /**\n   * The resource has been temporarily moved to another URL.\n   */\n  MOVED_TEMPORARILY = 302,\n\n  /**\n   * The response to the request can be found under another URI using the GET method.\n   */\n  SEE_OTHER = 303,\n\n  /**\n   * The resource hasn't been modified since the last request.\n   */\n  NOT_MODIFIED = 304,\n\n  /**\n   * @deprecated\n   * Response must be accessed through a proxy.\n   */\n  USE_PROXY = 305,\n\n  /**\n   * The resource is temporarily available at a different URI, using the same HTTP method.\n   */\n  TEMPORARY_REDIRECT = 307,\n\n  /**\n   * The resource has been permanently moved to another URL, using the same HTTP method.\n   */\n  PERMANENT_REDIRECT = 308,\n\n  // 4xx Client Error\n  /**\n   * The server cannot process the request due to a client error (malformed request).\n   */\n  BAD_REQUEST = 400,\n\n  /**\n   * Authentication is required and has failed or not been provided.\n   */\n  UNAUTHORIZED = 401,\n\n  /**\n   * Reserved for future use, originally intended for digital payment systems.\n   */\n  PAYMENT_REQUIRED = 402,\n\n  /**\n   * The client doesn't have permission to access the requested resource.\n   */\n  FORBIDDEN = 403,\n\n  /**\n   * The requested resource could not be found on the server.\n   */\n  NOT_FOUND = 404,\n\n  /**\n   * The request method is not supported for the requested resource.\n   */\n  METHOD_NOT_ALLOWED = 405,\n\n  /**\n   * The server can't provide a response matching the list of acceptable values in the client's headers.\n   */\n  NOT_ACCEPTABLE = 406,\n\n  /**\n   * Authentication by a proxy is required.\n   */\n  PROXY_AUTHENTICATION_REQUIRED = 407,\n\n  /**\n   * The server timed out waiting for the request.\n   */\n  REQUEST_TIMEOUT = 408,\n\n  /**\n   * The request conflicts with the current state of the server.\n   */\n  CONFLICT = 409,\n\n  /**\n   * The resource has been permanently deleted with no forwarding address.\n   */\n  GONE = 410,\n\n  /**\n   * The server requires a Content-Length header field.\n   */\n  LENGTH_REQUIRED = 411,\n\n  /**\n   * Preconditions in the client's headers failed.\n   */\n  PRECONDITION_FAILED = 412,\n\n  /**\n   * Request entity is larger than limits defined by server.\n   */\n  REQUEST_TOO_LONG = 413,\n\n  /**\n   * The request payload exceeds server size limits.\n   * Modern equivalent of REQUEST_TOO_LONG.\n   */\n  PAYLOAD_TOO_LARGE = 413,\n\n  /**\n   * The URI requested is too long for the server to interpret.\n   */\n  REQUEST_URI_TOO_LONG = 414,\n\n  /**\n   * The server does not support the media type requested by the client.\n   */\n  UNSUPPORTED_MEDIA_TYPE = 415,\n\n  /**\n   * The range specified by the Range header cannot be fulfilled.\n   */\n  REQUESTED_RANGE_NOT_SATISFIABLE = 416,\n\n  /**\n   * The server cannot meet the expectations given in the Expect header.\n   */\n  EXPECTATION_FAILED = 417,\n\n  /**\n   * The server refuses to brew coffee because it is a teapot. (April Fools' joke)\n   */\n  IM_A_TEAPOT = 418,\n\n  /**\n   * The server cannot store the representation needed to complete the request.\n   */\n  INSUFFICIENT_SPACE_ON_RESOURCE = 419,\n\n  /**\n   * @deprecated\n   * A method has failed - specific to Spring Framework.\n   */\n  METHOD_FAILURE = 420,\n\n  /**\n   * The server cannot produce a response for the requested URI scheme and authority.\n   */\n  MISDIRECTED_REQUEST = 421,\n\n  /**\n   * The request was well-formed but has semantic errors preventing processing.\n   */\n  UNPROCESSABLE_ENTITY = 422,\n\n  /**\n   * The requested resource is locked against access.\n   */\n  LOCKED = 423,\n\n  /**\n   * The request failed due to the failure of a previous request.\n   */\n  FAILED_DEPENDENCY = 424,\n\n  /**\n   * The client should switch to a different protocol.\n   */\n  UPGRADE_REQUIRED = 426,\n\n  /**\n   * The server requires conditional requests to prevent lost updates.\n   */\n  PRECONDITION_REQUIRED = 428,\n\n  /**\n   * The client has sent too many requests in a given time period (rate limiting).\n   */\n  TOO_MANY_REQUESTS = 429,\n\n  /**\n   * Request headers are too large for the server to process.\n   */\n  REQUEST_HEADER_FIELDS_TOO_LARGE = 431,\n\n  /**\n   * Resource cannot be legally provided (e.g., censored by government).\n   */\n  UNAVAILABLE_FOR_LEGAL_REASONS = 451,\n\n  // 5xx Server Error\n  /**\n   * The server encountered an unexpected error preventing it from fulfilling the request.\n   */\n  INTERNAL_SERVER_ERROR = 500,\n\n  /**\n   * The server does not support the functionality required to fulfill the request.\n   */\n  NOT_IMPLEMENTED = 501,\n\n  /**\n   * The server, acting as a gateway, received an invalid response from an upstream server.\n   */\n  BAD_GATEWAY = 502,\n\n  /**\n   * The server is currently unable to handle the request due to temporary overload or maintenance.\n   */\n  SERVICE_UNAVAILABLE = 503,\n\n  /**\n   * The server, acting as a gateway, did not receive a timely response from an upstream server.\n   */\n  GATEWAY_TIMEOUT = 504,\n\n  /**\n   * The server does not support the HTTP protocol version used in the request.\n   */\n  HTTP_VERSION_NOT_SUPPORTED = 505,\n\n  /**\n   * Transparent content negotiation for the request resulted in circular reference.\n   */\n  VARIANT_ALSO_NEGOTIATES = 506,\n\n  /**\n   * The server cannot store the representation needed to complete the request.\n   */\n  INSUFFICIENT_STORAGE = 507,\n\n  /**\n   * The server detected an infinite loop while processing the request.\n   */\n  LOOP_DETECTED = 508,\n\n  /**\n   * Further extensions to the request are required for the server to fulfill it.\n   */\n  NOT_EXTENDED = 510,\n\n  /**\n   * The client needs to authenticate to gain network access.\n   */\n  NETWORK_AUTHENTICATION_REQUIRED = 511\n}\n"]}

package/build/src/utils/id.utils.d.ts

@@ -1,36 +0,0 @@
-/**
- * Generates a UUID v4 string (RFC 4122).
- *
- * @returns {string} UUID v4 (e.g., 'c0de1234-5678-9abc-def0-123456789abc')
- */
-export declare function uuid(): string;
-/**
- * Generates a nanoid-style random ID (URL-safe, customizable length).
- *
- * @param {number} length - Length of the ID (default: 21).
- * @returns {string} Nanoid-style random string.
- */
-export declare function nanoId(length?: number): string;
-/**
- * Generates a cryptographically strong random hex string.
- *
- * @param {number} byteLength - Number of random bytes (default: 16 → 32 hex chars).
- * @returns {string} Random hex string.
- */
-export declare function randomHex(byteLength?: number): string;
-/**
- * Generates a random integer between min (inclusive) and max (inclusive).
- *
- * @param {number} min - Minimum value.
- * @param {number} max - Maximum value.
- * @returns {number} Random integer in range.
- */
-export declare function randomInt(min: number, max: number): number;
-/**
- * Generates a cryptographically strong random base64 string.
- *
- * @param {number} byteLength - Number of random bytes (default: 16).
- * @returns {string} Random base64 string (URL-safe, no padding).
- */
-export declare function randomBase64(byteLength?: number): string;
-//# sourceMappingURL=id.utils.d.ts.map

package/build/src/utils/id.utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"id.utils.js","sourceRoot":"","sources":["../../../src/utils/id.utils.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;AASH,oBAEC;AAQD,wBASC;AAQD,8BAOC;AASD,8BAGC;AAQD,oCAEC;AA/DD,mCAAiD;AAEjD;;;;GAIG;AACH,SAAgB,IAAI;IAClB,OAAO,IAAA,mBAAU,GAAE,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,MAAM,CAAC,SAAiB,EAAE;IACxC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3B,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;QAC1B,EAAE,IAAI,IAAA,oBAAW,EAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;aAC3C,QAAQ,CAAC,WAAW,CAAC;aACrB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,SAAS,CAAC,aAAqB,EAAE;IAC/C,6DAA6D;IAC7D,kGAAkG;IAClG,OAAO,IAAA,oBAAW,EAAC,UAAU,CAAC;SAC3B,QAAQ,CAAC,KAAK,CAAC;SACf,QAAQ,CAAC,UAAU,GAAG,CAAC,EAAE,GAAG,CAAC;SAC7B,KAAK,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,GAAW,EAAE,GAAW;IAChD,MAAM,KAAK,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;IAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,aAAqB,EAAE;IAClD,OAAO,IAAA,oBAAW,EAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACvD,CAAC","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { randomUUID, randomBytes } from 'crypto';\n\n/**\n * Generates a UUID v4 string (RFC 4122).\n *\n * @returns {string} UUID v4 (e.g., 'c0de1234-5678-9abc-def0-123456789abc')\n */\nexport function uuid(): string {\n  return randomUUID();\n}\n\n/**\n * Generates a nanoid-style random ID (URL-safe, customizable length).\n *\n * @param {number} length - Length of the ID (default: 21).\n * @returns {string} Nanoid-style random string.\n */\nexport function nanoId(length: number = 21): string {\n  if (length <= 0) return '';\n  let id = '';\n  while (id.length < length) {\n    id += randomBytes(Math.ceil((length * 3) / 4))\n      .toString('base64url')\n      .replace(/[+/=]/g, '');\n  }\n  return id.slice(0, length);\n}\n\n/**\n * Generates a cryptographically strong random hex string.\n *\n * @param {number} byteLength - Number of random bytes (default: 16 → 32 hex chars).\n * @returns {string} Random hex string.\n */\nexport function randomHex(byteLength: number = 16): string {\n  // Use Node.js crypto for both Node and browser compatibility\n  // Prefer randomBytes if available (Node), fallback to getRandomValues for browser (not used here)\n  return randomBytes(byteLength)\n    .toString('hex')\n    .padStart(byteLength * 2, '0')\n    .slice(0, byteLength * 2);\n}\n\n/**\n * Generates a random integer between min (inclusive) and max (inclusive).\n *\n * @param {number} min - Minimum value.\n * @param {number} max - Maximum value.\n * @returns {number} Random integer in range.\n */\nexport function randomInt(min: number, max: number): number {\n  const range = max - min + 1;\n  return Math.floor(Math.random() * range) + min;\n}\n\n/**\n * Generates a cryptographically strong random base64 string.\n *\n * @param {number} byteLength - Number of random bytes (default: 16).\n * @returns {string} Random base64 string (URL-safe, no padding).\n */\nexport function randomBase64(byteLength: number = 16): string {\n  return randomBytes(byteLength).toString('base64url');\n}\n"]}

package/build/src/utils/logger.utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"logger.utils.js","sourceRoot":"","sources":["../../../src/utils/logger.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport pino, { LoggerOptions, stdTimeFunctions } from 'pino';\nimport type { Logger as PinoLogger } from 'pino'; // Type-only import\nimport { config } from '../config';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { Env } from './env.utils';\n\n/**\n * Symbol used to store the root logger in the Node.js global object.\n */\nconst GLOBAL_LOGGER_KEY = Symbol.for('logger');\n\n/**\n * Logger type for application-wide logging.\n */\nexport type Logger = pino.Logger;\n\n/**\n * Logger levels for application-wide logging.\n */\nexport type LoggerLevels = pino.Level;\n\n// Default sensitive fields\nexport const defaultSensitiveFields = [\n  'password',\n  'secret',\n  'token',\n  'apiKey',\n  'api_key',\n  'auth',\n  'jwt',\n  'access_token',\n  'client_secret',\n  'session_token',\n  'refresh_token'\n];\n\n/**\n * The global censor function used by the logger.\n */\nlet globalRedactCensor: (value: unknown, path: string[], sensitiveFields?: string[]) => string = (\n  value,\n  path,\n  sensitiveFields = defaultSensitiveFields\n) => {\n  if (typeof value !== 'string') return '***';\n\n  const lowerPath = path.map(p => p.toLowerCase());\n  const lowerSensitiveFields = sensitiveFields.map(f => f.toLowerCase());\n\n  if (lowerPath.some(p => lowerSensitiveFields.includes(p))) return '***';\n\n  // Redact URLs\n  if (lowerPath[0] === 'url') {\n    return value.replace(new RegExp(`([?&](${lowerSensitiveFields.join('|')})=)[^&#]*`, 'gi'), '$1***');\n  }\n\n  if (lowerPath.some(p => p.includes('authorization') || p.includes('auth'))) {\n    return value.replace(/^(\\S+)\\s+.+$/, '$1 ***') || '***';\n  }\n\n  // Redact sensitive fields - check each path segment against each sensitive field\n  if (lowerPath.some(pathPart => lowerSensitiveFields.some(field => pathPart.includes(field)))) {\n    return '***';\n  }\n\n  if (path.length > 0 && !['req', 'res', 'headers'].includes(lowerPath[0])) {\n    return value;\n  }\n\n  return value;\n};\n\n/**\n * Sets the global redaction censor function used throughout the application for log redaction.\n *\n * Use this function to customize how sensitive data is redacted in logs. The provided function\n * will replace the default censor implementation.\n *\n * @example\n * ```typescript\n * // Custom censor that redacts only specific values\n * setRedactCensor((value, path, sensitiveFields) => {\n *   if (path.includes('password')) return '***';\n *   return value;\n * });\n * ```\n *\n * @param fn - The redaction censor function to use globally. This function receives:\n *   - value: The data value to potentially redact\n *   - path: Array of strings representing the path to the value in the object\n *   - sensitiveFields: Optional array of field names to consider sensitive\n * @returns void\n */\nexport function setRedactCensor(fn: (value: unknown, path: string[], sensitiveFields?: string[]) => string) {\n  globalRedactCensor = fn;\n}\n\n/**\n * Gets the current global redaction censor function used for log redaction.\n *\n * This function is called internally by the logger when determining how to redact\n * sensitive information. It can also be used to access the current censor implementation\n * for composition or extension.\n *\n * @example\n * ```typescript\n * const currentCensor = getRedactCensor();\n * // Create an enhanced censor that extends the current one\n * setRedactCensor((value, path, fields) => {\n *   // Add custom logic before delegating to current censor\n *   if (someCondition) return customHandling();\n *   return currentCensor(value, path, fields);\n * });\n * ```\n *\n * @returns The current redaction censor function\n */\nexport function getRedactCensor() {\n  return globalRedactCensor;\n}\n\n/**\n * Convenience function to redact sensitive data using the current global redact censor.\n *\n * This is a direct wrapper around the global censor function that simplifies usage\n * in application code without needing to access the censor function directly.\n *\n * @example\n * ```typescript\n * // Redact a potential sensitive value\n * const safeValue = redact(value, ['user', 'apiKey']);\n * ```\n *\n * @param value - The value to potentially redact\n * @param path - Array of strings representing the path to the value in the object\n * @param sensitiveFields - Optional array of field names to consider sensitive\n * @returns The redacted string value or \"***\" for redacted content\n */\nexport function redact(value: unknown, path: string[], sensitiveFields?: string[]) {\n  return globalRedactCensor(value, path, sensitiveFields);\n}\n\n/**\n * Extends the current redaction function with additional fields to redact.\n *\n * This function wraps the existing censor while adding more fields to be considered\n * sensitive without replacing the entire redaction logic.\n *\n * @example\n * ```typescript\n * // Add custom fields to be redacted in all future redaction operations\n * addRedactFields(['customerId', 'accountNumber']);\n * ```\n *\n * @param fields - Array of additional field names to redact\n */\nexport function addRedactFields(fields: string[]) {\n  const prev = globalRedactCensor;\n  globalRedactCensor = (value, path, sensitiveFields = defaultSensitiveFields) =>\n    prev(value, path, [...(sensitiveFields || []), ...fields]);\n}\n\n/**\n * Replaces the default list of sensitive fields with a new list.\n *\n * This is useful when you want complete control over what fields are considered\n * sensitive by default, rather than using the library's built-in list.\n *\n * @example\n * ```typescript\n * // Replace default sensitive fields with a custom list\n * setSensitiveFields(['password', 'ssn', 'creditCard']);\n * ```\n *\n * @param fields - Array of field names to set as the new default sensitive fields\n */\nexport function setSensitiveFields(fields: string[]) {\n  defaultSensitiveFields.splice(0, defaultSensitiveFields.length, ...fields);\n}\n\n/**\n * Adds additional field names to the default sensitive fields list.\n *\n * This preserves the existing sensitive fields while adding new ones for\n * application-specific sensitive data.\n *\n * @example\n * ```typescript\n * // Add domain-specific sensitive fields to the default list\n * addSensitiveFields(['socialSecurityNumber', 'medicalRecordNumber']);\n * ```\n *\n * @param fields - Array of additional field names to add to the sensitive fields list\n */\nexport function addSensitiveFields(fields: string[]) {\n  defaultSensitiveFields.push(...fields);\n}\n\n/**\n * Use an object compatible with either modern or legacy global scopes.\n */\nexport const _globalThis = typeof globalThis === 'object' ? globalThis : global;\nconst _global = _globalThis as unknown as { [GLOBAL_LOGGER_KEY]: PinoLogger };\n\n/**\n * Initializes the global root logger according to app configuration.\n *\n * - Sets log name, level, timestamp, and redaction for sensitive fields.\n * - Uses singleton in global symbol registry.\n */\nfunction setupLogger(): void {\n  const logParams: LoggerOptions = {\n    name: config.logger.name || '@catbee/utils',\n    level: config.logger.level || 'info',\n    redact: {\n      paths: ['req.authorization', 'res.authorization', 'url', 'headers.authorization', 'headers.cookies'],\n      censor: (value, path) => redact(value, path)\n    },\n    // serializers: {\n    //   req: pino.stdSerializers.req,\n    //   request: pino.stdSerializers.req,\n    //   res: pino.stdSerializers.res,\n    //   response: pino.stdSerializers.res,\n    //   err: pino.stdSerializers.err,\n    //   error: pino.stdSerializers.err\n    // },\n    timestamp: stdTimeFunctions.isoTime\n  };\n\n  const logger =\n    config.logger.pretty && Env.isDev()\n      ? pino(\n          logParams,\n          pino.transport({\n            target: 'pino-pretty',\n            options: {\n              colorize: true,\n              translateTime: 'SYS:standard',\n              ignore: 'pid,hostname',\n              singleLine: config.logger.singleLine,\n              levelFirst: true\n            }\n          })\n        )\n      : pino(logParams);\n\n  _global[GLOBAL_LOGGER_KEY] = logger;\n  _global[GLOBAL_LOGGER_KEY]?.debug('Logger initialized');\n}\n\n/**\n * Retrieves the current logger instance:\n * - Returns a request-scoped logger from AsyncLocalStorage if available\n * - Falls back to the global (singleton) logger\n * - Initializes the global logger if not created yet\n *\n * @returns {Logger} The logger instance (request-bound or global root logger)\n */\nexport function getLogger(): PinoLogger {\n  const logger = ContextStore.get<PinoLogger>(StoreKeys.LOGGER);\n  if (logger) return logger;\n\n  if (!_global[GLOBAL_LOGGER_KEY]) {\n    setupLogger();\n  }\n\n  return _global[GLOBAL_LOGGER_KEY];\n}\n\n/**\n * Logger instance for the global context.\n * This logger is used for logging messages that are not tied to a specific request.\n */\nexport const logger = getLogger();\n\n/**\n * Creates a child logger with additional context.\n *\n * @param {Record<string, any>} bindings - Properties to attach to all log records\n * @param {Logger} [parentLogger] - Parent logger (defaults to current context logger or global)\n * @returns {Logger} Child logger with merged context\n */\nexport function createChildLogger(bindings: Record<string, any>, parentLogger?: PinoLogger): PinoLogger {\n  const logger = parentLogger || getLogger();\n  return logger.child(bindings);\n}\n\n/**\n * Creates a request-scoped logger with request ID and stores it in context\n *\n * @param {string} requestId - Unique request identifier\n * @param {object} [additionalContext] - Additional context to include in logs\n * @returns {Logger} Request-scoped logger instance\n */\nexport function createRequestLogger(requestId: string, additionalContext: Record<string, any> = {}): PinoLogger {\n  const logger = createChildLogger({\n    requestId,\n    ...additionalContext\n  });\n\n  try {\n    ContextStore.set(StoreKeys.LOGGER, logger);\n  } catch {\n    // Context not initialized, can't store logger\n    logger.debug('Failed to store logger in context - AsyncLocalStorage not initialized');\n  }\n\n  return logger;\n}\n\n/**\n * Utility to safely log errors with proper stack trace extraction\n *\n * @param {Error|unknown} error - Error object to log\n * @param {string} [message] - Optional message to include\n * @param {Record<string, any>} [context] - Additional context properties\n */\nexport function logError(error: Error | unknown, message?: string, context?: Record<string, any>): void {\n  const logger = getLogger();\n\n  const errObj = error instanceof Error ? error : new Error(String(error));\n  const logContext = {\n    ...context,\n    error: errObj\n  };\n\n  logger.error(logContext, message || errObj.message);\n}\n"]}

package/build/src/utils/middleware.utils.d.ts

@@ -1,100 +0,0 @@
-import type { Request, Response, NextFunction } from 'express';
-export type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
-/**
- * Attaches a unique request ID to each request.
- * Useful for request tracing and correlation between logs.
- *
- * @param {object} [options] - Configuration options
- * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID
- * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response
- * @param {() => string} [options.generator] - Custom ID generator function
- * @returns {Middleware} Express-compatible middleware
- */
-export declare function requestId(options?: {
-    headerName?: string;
-    exposeHeader?: boolean;
-    generator?: () => string;
-}): Middleware;
-/**
- * Measures request processing time and logs or adds it to response headers.
- *
- * @param {object} [options] - Configuration options
- * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header
- * @param {boolean} [options.logOnComplete=false] - Whether to log timing info
- * @returns {Middleware} Express-compatible middleware
- */
-export declare function responseTime(options?: {
-    addHeader?: boolean;
-    logOnComplete?: boolean;
-}): (req: Request, res: Response, next: NextFunction) => void;
-/**
- * Request timeout middleware.
- * Aborts requests that take too long to process.
- *
- * @param {number} [timeoutMs=30000] - Timeout in milliseconds
- * @returns {Middleware} Express-compatible middleware
- */
-export declare function timeout(timeoutMs?: number): Middleware;
-/**
- * Creates an Express middleware that initializes a per-request context.
- *
- * @param {object} [options] - Optional configuration
- * @param {string} [options.headerName='x-request-id'] - Header to look for request ID
- * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized
- * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function
- */
-export declare function setupRequestContext(options?: {
-    headerName?: string;
-    autoLog?: boolean;
-}): Middleware;
-export interface ErrorHandlerOptions {
-    /** Whether to log errors (default: true) */
-    logErrors?: boolean;
-    /** Whether to include error details in non-production (default: false) */
-    includeDetails?: boolean;
-}
-/**
- * Global error handling middleware with enhanced features.
- *
- * @param {ErrorHandlerOptions} options - Error handler options
- * @param {boolean} [options.logErrors=true] - Whether to log errors
- * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production
- * @returns Error middleware
- *
- * @example
- * import express from 'express';
- * import { errorHandler } from '@catbee/utils';
- *
- * const app = express();
- *
- * // Your routes
- * app.get('/ping', (req, res) => {
- *   throw new Error('Something went wrong');
- * });
- *
- * // Error handler (must be last middleware)
- * app.use(errorHandler({ includeDetails: true }));
- *
- * app.listen(3000, () => {
- *   console.log('Server running on port 3000');
- * });
- */
-export declare function errorHandler(options?: ErrorHandlerOptions): (err: any, req: Request, res: Response, _next: NextFunction) => Response<any, Record<string, any>>;
-/**
- * Health check middleware for service status and custom checks.
- *
- * @param {object} [options] - Health check options
- * @param {string} [options.path='/healthz'] - Health check endpoint path
- * @param {Array<{name: string; check: () => Promise<boolean> | boolean}>} [options.checks] - Custom health checks
- * @param {boolean} [options.detailed=true] - Show detailed check results
- * @returns {Middleware} Express-compatible middleware
- */
-export declare function healthCheck(options?: {
-    path?: string;
-    checks?: Array<{
-        name: string;
-        check: () => Promise<boolean> | boolean;
-    }>;
-    detailed?: boolean;
-}): Middleware;
-//# sourceMappingURL=middleware.utils.d.ts.map

package/build/src/utils/middleware.utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"middleware.utils.js","sourceRoot":"","sources":["../../../src/utils/middleware.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { uuid } from './id.utils';\nimport { HttpStatusCodes } from './http-status-codes';\nimport { createFinalErrorResponse, ErrorResponse } from './response.utils';\nimport { getLogger } from './logger.utils';\nimport type { Request, Response, NextFunction } from 'express';\nimport { ContextStore, StoreKeys } from './context-store.utils';\nimport { RequestTimeoutException } from './exception.utils';\nimport { ApiErrorResponse } from '../types/api-response';\n\nexport type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;\n\n/**\n * Attaches a unique request ID to each request.\n * Useful for request tracing and correlation between logs.\n *\n * @param {object} [options] - Configuration options\n * @param {string} [options.headerName='X-Request-ID'] - Header name for request ID\n * @param {boolean} [options.exposeHeader=true] - Whether to expose the header in response\n * @param {() => string} [options.generator] - Custom ID generator function\n * @returns {Middleware} Express-compatible middleware\n */\nexport function requestId(options?: {\n  headerName?: string;\n  exposeHeader?: boolean;\n  generator?: () => string;\n}): Middleware {\n  const headerName = options?.headerName || 'X-Request-ID';\n  const exposeHeader = options?.exposeHeader !== false;\n  const generateId = options?.generator || uuid;\n\n  return (req, res, next) => {\n    // Use existing request ID from header or generate a new one\n    const existingId = req.headers[headerName.toLowerCase()];\n    const id = (existingId as string) || generateId();\n\n    // Attach ID to request object\n    req.id = id;\n\n    // Add ID to response headers\n    if (exposeHeader) {\n      res.setHeader(headerName, id);\n    }\n\n    next();\n  };\n}\n\n/**\n * Measures request processing time and logs or adds it to response headers.\n *\n * @param {object} [options] - Configuration options\n * @param {boolean} [options.addHeader=true] - Whether to add X-Response-Time header\n * @param {boolean} [options.logOnComplete=false] - Whether to log timing info\n * @returns {Middleware} Express-compatible middleware\n */\nexport function responseTime(options?: { addHeader?: boolean; logOnComplete?: boolean }) {\n  const addHeader = options?.addHeader !== false;\n  const logOnComplete = options?.logOnComplete === true;\n\n  return (req: Request, res: Response, next: NextFunction) => {\n    const start = process.hrtime();\n\n    // Function to calculate duration\n    const getDuration = () => {\n      const diff = process.hrtime(start);\n      return (diff[0] * 1e3 + diff[1] * 1e-6).toFixed(2);\n    };\n\n    if (addHeader) {\n      // Ensure header is set before response is sent\n      const originalWriteHead = res.writeHead;\n      res.writeHead = function (...args: any[]) {\n        res.setHeader('X-Response-Time', `${getDuration()}ms`);\n        return originalWriteHead.apply(this, args as any);\n      };\n    }\n\n    if (logOnComplete) {\n      res.on('finish', () => {\n        getLogger().info(`${req.method} ${req.url} - ${getDuration()}ms`);\n      });\n    }\n\n    next();\n  };\n}\n\n/**\n * Request timeout middleware.\n * Aborts requests that take too long to process.\n *\n * @param {number} [timeoutMs=30000] - Timeout in milliseconds\n * @returns {Middleware} Express-compatible middleware\n */\nexport function timeout(timeoutMs: number = 30000): Middleware {\n  return (_req, res, next) => {\n    // Set timeout for the request\n    const timer = setTimeout(() => {\n      const response = new RequestTimeoutException('Request timed out');\n      res.status(HttpStatusCodes.REQUEST_TIMEOUT).json(response);\n    }, timeoutMs);\n\n    // Clear timeout when response is sent\n    res.on('finish', () => {\n      clearTimeout(timer);\n    });\n\n    next();\n  };\n}\n\n/**\n * Creates an Express middleware that initializes a per-request context.\n *\n * @param {object} [options] - Optional configuration\n * @param {string} [options.headerName='x-request-id'] - Header to look for request ID\n * @param {boolean} [options.autoLog=true] - Whether to log automatically when context is initialized\n * @returns {(req: Request, res: Response, next: NextFunction) => void} Express middleware function\n */\nexport function setupRequestContext(options: { headerName?: string; autoLog?: boolean } = {}): Middleware {\n  const { headerName = 'x-request-id', autoLog = true } = options;\n  return (req, _res, next) => {\n    // Generate or use existing request ID\n    const requestId = (req.headers[headerName] as string) || req?.['id'] || uuid();\n\n    ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {\n      // Create a child logger for this request\n      const childLogger = getLogger().child({\n        requestId,\n        method: req.method,\n        url: req.originalUrl || req.url\n      });\n\n      req.logger = childLogger;\n\n      // Store logger in context\n      ContextStore.set(StoreKeys.LOGGER, childLogger);\n\n      if (autoLog) {\n        req.logger.info('Request context initialized');\n      }\n\n      next();\n    });\n  };\n}\n\nexport interface ErrorHandlerOptions {\n  /** Whether to log errors (default: true) */\n  logErrors?: boolean;\n  /** Whether to include error details in non-production (default: false) */\n  includeDetails?: boolean;\n}\n\n/**\n * Global error handling middleware with enhanced features.\n *\n * @param {ErrorHandlerOptions} options - Error handler options\n * @param {boolean} [options.logErrors=true] - Whether to log errors\n * @param {boolean} [options.includeDetails=false] - Whether to include error details in non-production\n * @returns Error middleware\n *\n * @example\n * import express from 'express';\n * import { errorHandler } from '@catbee/utils';\n *\n * const app = express();\n *\n * // Your routes\n * app.get('/ping', (req, res) => {\n *   throw new Error('Something went wrong');\n * });\n *\n * // Error handler (must be last middleware)\n * app.use(errorHandler({ includeDetails: true }));\n *\n * app.listen(3000, () => {\n *   console.log('Server running on port 3000');\n * });\n */\nexport function errorHandler(options?: ErrorHandlerOptions) {\n  const logErrors = options?.logErrors !== false;\n  const includeDetails = options?.includeDetails === true;\n\n  return (err: any, req: Request, res: Response, _next: NextFunction) => {\n    // Determine status code\n    const status = err?.status || err?.statusCode || HttpStatusCodes.INTERNAL_SERVER_ERROR;\n\n    // Log error if enabled\n    if (logErrors) {\n      getLogger().error({ err }, `${err.message || 'Unknown error'}`);\n    }\n\n    // Handle ErrorResponse instances (our custom error class)\n    if (err instanceof ErrorResponse) {\n      const result: ApiErrorResponse = {\n        error: true,\n        message: err.message,\n        timestamp: err.timestamp,\n        requestId: err?.requestId || req?.id || uuid(),\n        status,\n        path: req.originalUrl || req.url\n      };\n\n      if (includeDetails && err?.stack) {\n        result.stack = err.stack.split('\\n').map((line: string) => line.trim());\n      }\n      return res.status(status).json(result);\n    }\n\n    // Handle any other errors\n    return res\n      .status(status)\n      .json(createFinalErrorResponse(req, status, err?.message || 'Internal Server Error', err, { includeDetails }));\n  };\n}\n\n/**\n * Health check middleware for service status and custom checks.\n *\n * @param {object} [options] - Health check options\n * @param {string} [options.path='/healthz'] - Health check endpoint path\n * @param {Array<{name: string; check: () => Promise<boolean> | boolean}>} [options.checks] - Custom health checks\n * @param {boolean} [options.detailed=true] - Show detailed check results\n * @returns {Middleware} Express-compatible middleware\n */\nexport function healthCheck(options?: {\n  path?: string;\n  checks?: Array<{ name: string; check: () => Promise<boolean> | boolean }>;\n  detailed?: boolean;\n}): Middleware {\n  const path = options?.path || '/healthz';\n  const checks = options?.checks || [];\n  const detailed = options?.detailed !== false;\n\n  return async (req, res, next) => {\n    if (req.path !== path) return next();\n    const results: Record<string, boolean> = {};\n    let allHealthy = true;\n    for (const check of checks) {\n      try {\n        const result = await Promise.resolve(check.check());\n        results[check.name] = !!result;\n        if (!result) allHealthy = false;\n      } catch {\n        results[check.name] = false;\n        allHealthy = false;\n      }\n    }\n    const status = allHealthy ? HttpStatusCodes.OK : HttpStatusCodes.SERVICE_UNAVAILABLE;\n    const response = detailed\n      ? { status: allHealthy ? 'ok' : 'unhealthy', checks: results, timestamp: new Date().toISOString() }\n      : { status: allHealthy ? 'ok' : 'unhealthy' };\n    res.status(status).json(response);\n  };\n}\n"]}

package/build/src/utils/obj.utils.d.ts

@@ -1,124 +0,0 @@
-/**
- * Checks whether the object has no own enumerable properties.
- *
- * @param {Record<any, any>} obj - The object to check.
- * @returns {boolean} True if the object is empty, false otherwise.
- */
-export declare function isObjEmpty(obj: Record<any, any>): boolean;
-/**
- * Returns a new object with only the specified keys picked.
- *
- * @template T
- * @template K
- * @param {T} obj - The source object.
- * @param {K[]} keys - Keys to pick from the object.
- * @returns {Pick<T, K>} New object with picked keys.
- */
-export declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
-/**
- * Returns a new object with the specified keys omitted.
- *
- * @template T
- * @template K
- * @param {T} obj - The source object.
- * @param {K[]} keys - Keys to omit from the object.
- * @returns {Omit<T, K>} New object without omitted keys.
- */
-export declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
-/**
- * Deeply merges multiple objects into the target object (mutates and returns the target object, not pure).
- *
- * @template T
- * @param {T} target - The object to merge into (will be mutated).
- * @param {...any[]} sources - The objects to merge from.
- * @returns {T} The merged object (same as target).
- */
-export declare function deepObjMerge<T extends object>(target: T, ...sources: any[]): T;
-/**
- * Checks if a value is a plain object (i.e., not an array, null, or a built-in object).
- *
- * @param value - The value to check.
- * @returns True if the value is a plain object, false otherwise.
- */
-export declare function isPlainObject(value: any): value is Record<string, any>;
-/**
- * Flattens a nested object using dot notation for keys (e.g., `{a: {b: 1}}` → `{ "a.b": 1 }`).
- *
- * @template T
- * @param {T} obj - The object to flatten.
- * @param {string} [prefix=""] - Optional prefix for nested keys (used internally).
- * @returns {Record<string, any>} A new object with flattened keys.
- */
-export declare function flattenObject<T extends Record<string, any>>(obj: T, prefix?: string): Record<string, any>;
-/**
- * Safely gets the value of a deeply nested key in an object using dot/bracket notation path.
- *
- * @template T
- * @param {T} obj - The object to extract from.
- * @param {string} path - String path using dot and/or bracket notation (e.g., 'user.friends[0].name').
- * @returns {any} The value at the given path, or undefined if not found.
- */
-export declare function getValueByPath<T extends object>(obj: T, path: string): any;
-/**
- * Sets a value at a deeply nested key in an object using dot/bracket notation path.
- * Creates intermediate objects and arrays as needed.
- *
- * @template T
- * @param {T} obj - The object to modify.
- * @param {string} path - String path using dot and/or bracket notation (e.g., 'user.friends[0].name').
- * @param {any} value - The value to set at the path.
- * @returns {T} The modified object.
- */
-export declare function setValueByPath<T extends object>(obj: T, path: string, value: any): T;
-/**
- * Performs a deep equality check between two objects.
- *
- * @param {any} a - First value to compare.
- * @param {any} b - Second value to compare.
- * @returns {boolean} True if values are deeply equal.
- */
-export declare function isEqual(a: any, b: any): boolean;
-/**
- * Filters object properties based on a predicate function.
- *
- * @template T
- * @param {T} obj - The source object.
- * @param {(value: any, key: string, obj: T) => boolean} predicate - Filter function.
- * @returns {Partial<T>} New object with filtered properties.
- */
-export declare function filterObject<T extends object>(obj: T, predicate: (value: any, key: string, obj: T) => boolean): Partial<T>;
-/**
- * Maps object values to new values using a mapping function.
- *
- * @template T
- * @template U
- * @param {T} obj - The source object.
- * @param {(value: any, key: string, obj: T) => U} mapFn - Mapping function.
- * @returns {Record<keyof T, U>} New object with mapped values.
- */
-export declare function mapObject<T extends object, U>(obj: T, mapFn: (value: any, key: string, obj: T) => U): Record<keyof T, U>;
-/**
- * Recursively freezes an object and all its properties.
- * Makes an object immutable.
- *
- * @template T
- * @param {T} obj - The object to freeze.
- * @returns {Readonly<T>} The frozen object.
- */
-export declare function deepFreeze<T extends object>(obj: T): Readonly<T>;
-/**
- * Safely checks if a value is an object (not null, not array).
- *
- * @param {unknown} value - Value to check.
- * @returns {boolean} True if value is a non-null, non-array object.
- */
-export declare function isObject(value: unknown): value is Record<string, any>;
-/**
- * Gets all paths in an object using dot notation.
- *
- * @param {Record<string, any>} obj - Object to analyze.
- * @param {string} [parentPath=""] - Internal param for recursion.
- * @returns {string[]} Array of all paths in dot notation.
- */
-export declare function getAllPaths(obj: Record<string, any>, parentPath?: string): string[];
-//# sourceMappingURL=obj.utils.d.ts.map