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

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

@@ -0,0 +1,265 @@
+/**
+ * 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
+}

package/build/cjs/utils/http-status-codes.js

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

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

@@ -0,0 +1,35 @@
+/**
+ * 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;

package/build/cjs/utils/id.utils.js

@@ -0,0 +1,90 @@
+"use strict";
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uuid = uuid;
+exports.nanoId = nanoId;
+exports.randomHex = randomHex;
+exports.randomInt = randomInt;
+exports.randomBase64 = randomBase64;
+const crypto_1 = require("crypto");
+/**
+ * Generates a UUID v4 string (RFC 4122).
+ *
+ * @returns {string} UUID v4 (e.g., 'c0de1234-5678-9abc-def0-123456789abc')
+ */
+function uuid() {
+    return (0, crypto_1.randomUUID)();
+}
+/**
+ * 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.
+ */
+function nanoId(length = 21) {
+    if (length <= 0)
+        return '';
+    let id = '';
+    while (id.length < length) {
+        id += (0, crypto_1.randomBytes)(Math.ceil((length * 3) / 4))
+            .toString('base64url')
+            .replace(/[+/=]/g, '');
+    }
+    return id.slice(0, length);
+}
+/**
+ * Generates a cryptographically strong random hex string.
+ *
+ * @param {number} byteLength - Number of random bytes (default: 16 → 32 hex chars).
+ * @returns {string} Random hex string.
+ */
+function randomHex(byteLength = 16) {
+    // Use Node.js crypto for both Node and browser compatibility
+    // Prefer randomBytes if available (Node), fallback to getRandomValues for browser (not used here)
+    return (0, crypto_1.randomBytes)(byteLength)
+        .toString('hex')
+        .padStart(byteLength * 2, '0')
+        .slice(0, byteLength * 2);
+}
+/**
+ * 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.
+ */
+function randomInt(min, max) {
+    const range = max - min + 1;
+    return Math.floor(Math.random() * range) + min;
+}
+/**
+ * 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).
+ */
+function randomBase64(byteLength = 16) {
+    return (0, crypto_1.randomBytes)(byteLength).toString('base64url');
+}