@catbee/utils 0.0.1

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

@@ -0,0 +1,55 @@
+/**
+ * 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 const 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 const 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 const omit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+/**
+ * Deeply merges two objects (mutates and returns the target object, not pure).
+ *
+ * @template T
+ * @param {T} target - The object to merge into (will be mutated).
+ * @param {Partial<T>} source - The object to merge from.
+ * @returns {T} The merged object (same as target).
+ */
+export declare function deepObjMerge<T extends Record<string, any>>(target: T, source: Partial<T>): T;
+/**
+ * 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;
+//# sourceMappingURL=obj.utils.d.ts.map

package/build/esm/utils/obj.utils.js

@@ -0,0 +1,121 @@
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+/**
+ * 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 var isObjEmpty = function (obj) {
+    return !!obj && typeof obj === "object" && Object.keys(obj).length === 0;
+};
+/**
+ * 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 var pick = function (obj, keys) {
+    return Object.fromEntries(keys.map(function (key) { return [key, obj[key]]; }));
+};
+/**
+ * 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 var omit = function (obj, keys) {
+    return Object.fromEntries(Object.entries(obj).filter(function (_a) {
+        var _b = __read(_a, 1), key = _b[0];
+        return !keys.includes(key);
+    }));
+};
+/**
+ * Deeply merges two objects (mutates and returns the target object, not pure).
+ *
+ * @template T
+ * @param {T} target - The object to merge into (will be mutated).
+ * @param {Partial<T>} source - The object to merge from.
+ * @returns {T} The merged object (same as target).
+ */
+export function deepObjMerge(target, source) {
+    for (var key in source) {
+        var sourceVal = source[key];
+        var targetVal = target[key];
+        if (sourceVal &&
+            typeof sourceVal === "object" &&
+            !Array.isArray(sourceVal)) {
+            if (!targetVal ||
+                typeof targetVal !== "object" ||
+                Array.isArray(targetVal)) {
+                target[key] = {};
+            }
+            deepObjMerge(target[key], sourceVal);
+        }
+        else {
+            target[key] = sourceVal;
+        }
+    }
+    return target;
+}
+/**
+ * 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 function flattenObject(obj, prefix) {
+    if (prefix === void 0) { prefix = ""; }
+    return Object.entries(obj).reduce(function (acc, _a) {
+        var _b = __read(_a, 2), key = _b[0], value = _b[1];
+        var newKey = prefix ? "".concat(prefix, ".").concat(key) : key;
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            Object.assign(acc, flattenObject(value, newKey));
+        }
+        else {
+            acc[newKey] = value;
+        }
+        return acc;
+    }, {});
+}
+/**
+ * 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 function getValueByPath(obj, path) {
+    if (!obj || typeof obj !== "object")
+        return undefined;
+    // Convert path like "a.b[0].c" into ["a", "b", "0", "c"]
+    var parts = path
+        .replace(/\[(\d+)\]/g, ".$1") // convert [0] to .0
+        .split(".")
+        .filter(Boolean); // remove empty strings
+    return parts.reduce(function (acc, key) { return acc === null || acc === void 0 ? void 0 : acc[key]; }, obj);
+}
+//# sourceMappingURL=obj.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"obj.utils.js","sourceRoot":"","sources":["../../../src/utils/obj.utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;GAKG;AACH,MAAM,CAAC,IAAM,UAAU,GAAG,UAAC,GAAqB;IAC9C,OAAA,CAAC,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC;AAAjE,CAAiE,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,CAAC,IAAM,IAAI,GAAG,UAClB,GAAM,EACN,IAAS;IAET,OAAA,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,UAAC,GAAG,IAAK,OAAA,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,EAAf,CAAe,CAAC,CAAe;AAApE,CAAoE,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,CAAC,IAAM,IAAI,GAAG,UAClB,GAAM,EACN,IAAS;IAET,OAAA,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,UAAC,EAAK;YAAL,KAAA,aAAK,EAAJ,GAAG,QAAA;QAAM,OAAA,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAQ,CAAC;IAAxB,CAAwB,CAAC,CAClD;AAFf,CAEe,CAAC;AAElB;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAS,EACT,MAAkB;IAElB,KAAK,IAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,IAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAE9B,IACE,SAAS;YACT,OAAO,SAAS,KAAK,QAAQ;YAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EACzB,CAAC;YACD,IACE,CAAC,SAAS;gBACV,OAAO,SAAS,KAAK,QAAQ;gBAC7B,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EACxB,CAAC;gBACD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAS,CAAC;YAC1B,CAAC;YACD,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAgB,CAAC,CAAC;QAC9C,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,SAAwC,CAAC;QACzD,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAM,EACN,MAAW;IAAX,uBAAA,EAAA,WAAW;IAEX,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAC/B,UAAC,GAAwB,EAAE,EAAY;YAAZ,KAAA,aAAY,EAAX,GAAG,QAAA,EAAE,KAAK,QAAA;QACpC,IAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,UAAG,MAAM,cAAI,GAAG,CAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAEjD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAChE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC,EACD,EAAE,CACH,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAmB,GAAM,EAAE,IAAY;IACnE,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAEtD,yDAAyD;IACzD,IAAM,KAAK,GAAG,IAAI;SACf,OAAO,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,oBAAoB;SACjD,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB;IAE3C,OAAO,KAAK,CAAC,MAAM,CAAC,UAAC,GAAQ,EAAE,GAAW,IAAK,OAAA,GAAG,aAAH,GAAG,uBAAH,GAAG,CAAG,GAAG,CAAC,EAAV,CAAU,EAAE,GAAG,CAAC,CAAC;AAClE,CAAC","sourcesContent":["/**\n * Checks whether the object has no own enumerable properties.\n *\n * @param {Record<any, any>} obj - The object to check.\n * @returns {boolean} True if the object is empty, false otherwise.\n */\nexport const isObjEmpty = (obj: Record<any, any>): boolean =>\n  !!obj && typeof obj === \"object\" && Object.keys(obj).length === 0;\n\n/**\n * Returns a new object with only the specified keys picked.\n *\n * @template T\n * @template K\n * @param {T} obj - The source object.\n * @param {K[]} keys - Keys to pick from the object.\n * @returns {Pick<T, K>} New object with picked keys.\n */\nexport const pick = <T extends object, K extends keyof T>(\n  obj: T,\n  keys: K[],\n): Pick<T, K> =>\n  Object.fromEntries(keys.map((key) => [key, obj[key]])) as Pick<T, K>;\n\n/**\n * Returns a new object with the specified keys omitted.\n *\n * @template T\n * @template K\n * @param {T} obj - The source object.\n * @param {K[]} keys - Keys to omit from the object.\n * @returns {Omit<T, K>} New object without omitted keys.\n */\nexport const omit = <T extends object, K extends keyof T>(\n  obj: T,\n  keys: K[],\n): Omit<T, K> =>\n  Object.fromEntries(\n    Object.entries(obj).filter(([key]) => !keys.includes(key as K)),\n  ) as Omit<T, K>;\n\n/**\n * Deeply merges two objects (mutates and returns the target object, not pure).\n *\n * @template T\n * @param {T} target - The object to merge into (will be mutated).\n * @param {Partial<T>} source - The object to merge from.\n * @returns {T} The merged object (same as target).\n */\nexport function deepObjMerge<T extends Record<string, any>>(\n  target: T,\n  source: Partial<T>,\n): T {\n  for (const key in source) {\n    const sourceVal = source[key];\n    const targetVal = target[key];\n\n    if (\n      sourceVal &&\n      typeof sourceVal === \"object\" &&\n      !Array.isArray(sourceVal)\n    ) {\n      if (\n        !targetVal ||\n        typeof targetVal !== \"object\" ||\n        Array.isArray(targetVal)\n      ) {\n        target[key] = {} as any;\n      }\n      deepObjMerge(target[key], sourceVal as any);\n    } else {\n      target[key] = sourceVal as T[Extract<keyof T, string>];\n    }\n  }\n  return target;\n}\n\n/**\n * Flattens a nested object using dot notation for keys (e.g., `{a: {b: 1}}` → `{ \"a.b\": 1 }`).\n *\n * @template T\n * @param {T} obj - The object to flatten.\n * @param {string} [prefix=\"\"] - Optional prefix for nested keys (used internally).\n * @returns {Record<string, any>} A new object with flattened keys.\n */\nexport function flattenObject<T extends Record<string, any>>(\n  obj: T,\n  prefix = \"\",\n): Record<string, any> {\n  return Object.entries(obj).reduce(\n    (acc: Record<string, any>, [key, value]) => {\n      const newKey = prefix ? `${prefix}.${key}` : key;\n\n      if (value && typeof value === \"object\" && !Array.isArray(value)) {\n        Object.assign(acc, flattenObject(value, newKey));\n      } else {\n        acc[newKey] = value;\n      }\n\n      return acc;\n    },\n    {},\n  );\n}\n\n/**\n * Safely gets the value of a deeply nested key in an object using dot/bracket notation path.\n *\n * @template T\n * @param {T} obj - The object to extract from.\n * @param {string} path - String path using dot and/or bracket notation (e.g., 'user.friends[0].name').\n * @returns {any} The value at the given path, or undefined if not found.\n */\nexport function getValueByPath<T extends object>(obj: T, path: string) {\n  if (!obj || typeof obj !== \"object\") return undefined;\n\n  // Convert path like \"a.b[0].c\" into [\"a\", \"b\", \"0\", \"c\"]\n  const parts = path\n    .replace(/\\[(\\d+)\\]/g, \".$1\") // convert [0] to .0\n    .split(\".\")\n    .filter(Boolean); // remove empty strings\n\n  return parts.reduce((acc: any, key: string) => acc?.[key], obj);\n}\n"]}

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

@@ -0,0 +1,48 @@
+import { ApiResponse } from "../types/api-response";
+/**
+ * Standard HTTP response wrapper for successful responses.
+ * Implements the `ApiResponse<T>` interface and sets default values.
+ *
+ * @typeParam T - The shape of the data returned in the response.
+ */
+export declare class SuccessResponse<T> implements ApiResponse<T> {
+    /** Message describing the result of the operation. */
+    message: string;
+    /** Whether the response is an error. Always false in success responses. */
+    error: boolean;
+    /** The payload returned from the API. */
+    data: T | null;
+    /** Timestamp when the response was generated, in ISO format. */
+    timestamp: string;
+    /** Unique identifier for this response, useful for request tracing. */
+    requestId: string;
+    /**
+     * Constructs a new success response.
+     *
+     * @param {string} message - Optional message to override the default.
+     * @param {T} [data] - Optional data payload.
+     */
+    constructor(message: string, data?: T);
+}
+/**
+ * Wrapper for error responses that extends the native `Error` object.
+ * Implements `ApiResponse` but omits the `data` field (which should not be present in errors).
+ */
+export declare class ErrorResponse extends Error implements Omit<ApiResponse<never>, "data"> {
+    /** HTTP status code associated with the error (e.g., 404, 500). */
+    status: number;
+    /** Indicates that this is an error. Always true. */
+    error: boolean;
+    /** Timestamp when the error occurred, in ISO format. */
+    timestamp: string;
+    /** Unique identifier for this error instance. */
+    requestId: string;
+    /**
+     * Constructs a new error response.
+     *
+     * @param {string} message - The error message to display or log.
+     * @param {number} [status=500] - Optional HTTP status code (defaults to 500).
+     */
+    constructor(message: string, status?: number);
+}
+//# sourceMappingURL=response.utils.d.ts.map

package/build/esm/utils/response.utils.js

@@ -0,0 +1,80 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+import { randomUUID } from "crypto";
+import { getRequestId } from "./context-store.utils";
+/**
+ * Standard HTTP response wrapper for successful responses.
+ * Implements the `ApiResponse<T>` interface and sets default values.
+ *
+ * @typeParam T - The shape of the data returned in the response.
+ */
+var SuccessResponse = /** @class */ (function () {
+    /**
+     * Constructs a new success response.
+     *
+     * @param {string} message - Optional message to override the default.
+     * @param {T} [data] - Optional data payload.
+     */
+    function SuccessResponse(message, data) {
+        var _a;
+        /** Message describing the result of the operation. */
+        this.message = "Success";
+        /** Whether the response is an error. Always false in success responses. */
+        this.error = false;
+        /** The payload returned from the API. */
+        this.data = null;
+        /** Timestamp when the response was generated, in ISO format. */
+        this.timestamp = new Date().toISOString();
+        /** Unique identifier for this response, useful for request tracing. */
+        this.requestId = (_a = getRequestId()) !== null && _a !== void 0 ? _a : randomUUID();
+        if (message)
+            this.message = message;
+        this.data = data !== null && data !== void 0 ? data : null;
+    }
+    return SuccessResponse;
+}());
+export { SuccessResponse };
+/**
+ * Wrapper for error responses that extends the native `Error` object.
+ * Implements `ApiResponse` but omits the `data` field (which should not be present in errors).
+ */
+var ErrorResponse = /** @class */ (function (_super) {
+    __extends(ErrorResponse, _super);
+    /**
+     * Constructs a new error response.
+     *
+     * @param {string} message - The error message to display or log.
+     * @param {number} [status=500] - Optional HTTP status code (defaults to 500).
+     */
+    function ErrorResponse(message, status) {
+        if (status === void 0) { status = 500; }
+        var _a;
+        var _this = _super.call(this, message) || this;
+        /** Indicates that this is an error. Always true. */
+        _this.error = true;
+        /** Timestamp when the error occurred, in ISO format. */
+        _this.timestamp = new Date().toISOString();
+        /** Unique identifier for this error instance. */
+        _this.requestId = (_a = getRequestId()) !== null && _a !== void 0 ? _a : randomUUID();
+        _this.status = status;
+        _this.name = _this.constructor.name;
+        Error.captureStackTrace(_this, _this.constructor);
+        return _this;
+    }
+    return ErrorResponse;
+}(Error));
+export { ErrorResponse };
+//# sourceMappingURL=response.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"response.utils.js","sourceRoot":"","sources":["../../../src/utils/response.utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD;;;;;GAKG;AACH;IAgBE;;;;;OAKG;IACH,yBAAY,OAAe,EAAE,IAAQ;;QArBrC,sDAAsD;QACtD,YAAO,GAAW,SAAS,CAAC;QAE5B,2EAA2E;QAC3E,UAAK,GAAY,KAAK,CAAC;QAEvB,yCAAyC;QACzC,SAAI,GAAa,IAAI,CAAC;QAEtB,gEAAgE;QAChE,cAAS,GAAW,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAE7C,uEAAuE;QACvE,cAAS,GAAW,MAAA,YAAY,EAAE,mCAAI,UAAU,EAAE,CAAC;QASjD,IAAI,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,aAAJ,IAAI,cAAJ,IAAI,GAAI,IAAI,CAAC;IAC3B,CAAC;IACH,sBAAC;AAAD,CAAC,AA1BD,IA0BC;;AAED;;;GAGG;AACH;IACU,iCAAK;IAeb;;;;;OAKG;IACH,uBAAY,OAAe,EAAE,MAAoB;QAApB,uBAAA,EAAA,YAAoB;;QAC/C,YAAA,MAAK,YAAC,OAAO,CAAC,SAAC;QAhBjB,oDAAoD;QACpD,WAAK,GAAY,IAAI,CAAC;QAEtB,wDAAwD;QACxD,eAAS,GAAW,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAE7C,iDAAiD;QACjD,eAAS,GAAW,MAAA,YAAY,EAAE,mCAAI,UAAU,EAAE,CAAC;QAUjD,KAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,KAAI,CAAC,IAAI,GAAG,KAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,KAAK,CAAC,iBAAiB,CAAC,KAAI,EAAE,KAAI,CAAC,WAAW,CAAC,CAAC;;IAClD,CAAC;IACH,oBAAC;AAAD,CAAC,AA5BD,CACU,KAAK,GA2Bd","sourcesContent":["import { randomUUID } from \"crypto\";\nimport { ApiResponse } from \"../types/api-response\";\nimport { getRequestId } from \"./context-store.utils\";\n\n/**\n * Standard HTTP response wrapper for successful responses.\n * Implements the `ApiResponse<T>` interface and sets default values.\n *\n * @typeParam T - The shape of the data returned in the response.\n */\nexport class SuccessResponse<T> implements ApiResponse<T> {\n  /** Message describing the result of the operation. */\n  message: string = \"Success\";\n\n  /** Whether the response is an error. Always false in success responses. */\n  error: boolean = false;\n\n  /** The payload returned from the API. */\n  data: T | null = null;\n\n  /** Timestamp when the response was generated, in ISO format. */\n  timestamp: string = new Date().toISOString();\n\n  /** Unique identifier for this response, useful for request tracing. */\n  requestId: string = getRequestId() ?? randomUUID();\n\n  /**\n   * Constructs a new success response.\n   *\n   * @param {string} message - Optional message to override the default.\n   * @param {T} [data] - Optional data payload.\n   */\n  constructor(message: string, data?: T) {\n    if (message) this.message = message;\n    this.data = data ?? null;\n  }\n}\n\n/**\n * Wrapper for error responses that extends the native `Error` object.\n * Implements `ApiResponse` but omits the `data` field (which should not be present in errors).\n */\nexport class ErrorResponse\n  extends Error\n  implements Omit<ApiResponse<never>, \"data\">\n{\n  /** HTTP status code associated with the error (e.g., 404, 500). */\n  status: number;\n\n  /** Indicates that this is an error. Always true. */\n  error: boolean = true;\n\n  /** Timestamp when the error occurred, in ISO format. */\n  timestamp: string = new Date().toISOString();\n\n  /** Unique identifier for this error instance. */\n  requestId: string = getRequestId() ?? randomUUID();\n\n  /**\n   * Constructs a new error response.\n   *\n   * @param {string} message - The error message to display or log.\n   * @param {number} [status=500] - Optional HTTP status code (defaults to 500).\n   */\n  constructor(message: string, status: number = 500) {\n    super(message);\n    this.status = status;\n    this.name = this.constructor.name;\n    Error.captureStackTrace(this, this.constructor);\n  }\n}\n"]}

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

@@ -0,0 +1,37 @@
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The string with the first character in uppercase.
+ */
+export declare const capitalize: (str: string) => string;
+/**
+ * Converts a string to kebab-case (e.g., "FooBar test" → "foo-bar-test").
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The kebab-cased string.
+ */
+export declare const toKebabCase: (str: string) => string;
+/**
+ * Converts a kebab-case or snake_case string to camelCase.
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The camelCased string.
+ */
+export declare const toCamelCase: (str: string) => string;
+/**
+ * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The slugified string.
+ */
+export declare const slugify: (str: string) => string;
+/**
+ * Truncates a string to a specific length, appending '...' if truncated.
+ *
+ * @param {string} str - The input string.
+ * @param {number} len - The maximum length.
+ * @returns {string} The truncated string.
+ */
+export declare const truncate: (str: string, len: number) => string;
+//# sourceMappingURL=string.utils.d.ts.map

package/build/esm/utils/string.utils.js

@@ -0,0 +1,56 @@
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The string with the first character in uppercase.
+ */
+export var capitalize = function (str) {
+    return str.length === 0 ? "" : str.charAt(0).toUpperCase() + str.slice(1);
+};
+/**
+ * Converts a string to kebab-case (e.g., "FooBar test" → "foo-bar-test").
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The kebab-cased string.
+ */
+export var toKebabCase = function (str) {
+    return str
+        .replace(/([a-z])([A-Z])/g, "$1-$2") // camelCase -> camel-Case
+        .replace(/\s+/g, "-") // spaces to dash
+        .replace(/_+/g, "-") // underscores to dash
+        .toLowerCase();
+};
+/**
+ * Converts a kebab-case or snake_case string to camelCase.
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The camelCased string.
+ */
+export var toCamelCase = function (str) {
+    return str.replace(/[-_](.)/g, function (_, c) { return c.toUpperCase(); });
+};
+/**
+ * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).
+ *
+ * @param {string} str - The input string.
+ * @returns {string} The slugified string.
+ */
+export var slugify = function (str) {
+    return str
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "") // remove non-word
+        .replace(/\s+/g, "-") // spaces to dash
+        .replace(/-+/g, "-") // multiple dashes to one
+        .replace(/^-+|-+$/g, "");
+}; // trim leading/trailing dashes
+/**
+ * Truncates a string to a specific length, appending '...' if truncated.
+ *
+ * @param {string} str - The input string.
+ * @param {number} len - The maximum length.
+ * @returns {string} The truncated string.
+ */
+export var truncate = function (str, len) {
+    return str.length > len ? str.slice(0, len) + "..." : str;
+};
+//# sourceMappingURL=string.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"string.utils.js","sourceRoot":"","sources":["../../../src/utils/string.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,IAAM,UAAU,GAAG,UAAC,GAAW;IACpC,OAAA,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAAlE,CAAkE,CAAC;AAErE;;;;;GAKG;AACH,MAAM,CAAC,IAAM,WAAW,GAAG,UAAC,GAAW;IACrC,OAAA,GAAG;SACA,OAAO,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC,0BAA0B;SAC9D,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,iBAAiB;SACtC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,sBAAsB;SAC1C,WAAW,EAAE;AAJhB,CAIgB,CAAC;AAEnB;;;;;GAKG;AACH,MAAM,CAAC,IAAM,WAAW,GAAG,UAAC,GAAW;IACrC,OAAA,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,UAAC,CAAC,EAAE,CAAS,IAAK,OAAA,CAAC,CAAC,WAAW,EAAE,EAAf,CAAe,CAAC;AAA1D,CAA0D,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,IAAM,OAAO,GAAG,UAAC,GAAW;IACjC,OAAA,GAAG;SACA,WAAW,EAAE;SACb,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,kBAAkB;SAC3C,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,iBAAiB;SACtC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,yBAAyB;SAC7C,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;AAL1B,CAK0B,CAAC,CAAC,+BAA+B;AAE7D;;;;;;GAMG;AACH,MAAM,CAAC,IAAM,QAAQ,GAAG,UAAC,GAAW,EAAE,GAAW;IAC/C,OAAA,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG;AAAlD,CAAkD,CAAC","sourcesContent":["/**\n * Capitalizes the first character of a string.\n *\n * @param {string} str - The input string.\n * @returns {string} The string with the first character in uppercase.\n */\nexport const capitalize = (str: string): string =>\n  str.length === 0 ? \"\" : str.charAt(0).toUpperCase() + str.slice(1);\n\n/**\n * Converts a string to kebab-case (e.g., \"FooBar test\" → \"foo-bar-test\").\n *\n * @param {string} str - The input string.\n * @returns {string} The kebab-cased string.\n */\nexport const toKebabCase = (str: string): string =>\n  str\n    .replace(/([a-z])([A-Z])/g, \"$1-$2\") // camelCase -> camel-Case\n    .replace(/\\s+/g, \"-\") // spaces to dash\n    .replace(/_+/g, \"-\") // underscores to dash\n    .toLowerCase();\n\n/**\n * Converts a kebab-case or snake_case string to camelCase.\n *\n * @param {string} str - The input string.\n * @returns {string} The camelCased string.\n */\nexport const toCamelCase = (str: string): string =>\n  str.replace(/[-_](.)/g, (_, c: string) => c.toUpperCase());\n\n/**\n * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).\n *\n * @param {string} str - The input string.\n * @returns {string} The slugified string.\n */\nexport const slugify = (str: string): string =>\n  str\n    .toLowerCase()\n    .replace(/[^\\w\\s-]/g, \"\") // remove non-word\n    .replace(/\\s+/g, \"-\") // spaces to dash\n    .replace(/-+/g, \"-\") // multiple dashes to one\n    .replace(/^-+|-+$/g, \"\"); // trim leading/trailing dashes\n\n/**\n * Truncates a string to a specific length, appending '...' if truncated.\n *\n * @param {string} str - The input string.\n * @param {number} len - The maximum length.\n * @returns {string} The truncated string.\n */\nexport const truncate = (str: string, len: number): string =>\n  str.length > len ? str.slice(0, len) + \"...\" : str;\n"]}

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

@@ -0,0 +1,24 @@
+/**
+ * Appends query parameters to a given URL.
+ *
+ * @param {string} url - The base URL to which query parameters will be appended.
+ * @param {Record<string, string | number>} params - Key-value pairs to add as query parameters.
+ * @returns {string} The new URL string with query parameters appended.
+ *
+ * @example
+ * appendQueryParams('https://example.com', { page: 1, limit: 10 });
+ * // → 'https://example.com/?page=1&limit=10'
+ */
+export declare function appendQueryParams(url: string, params: Record<string, string | number>): string;
+/**
+ * Parses a query string into a key-value object.
+ *
+ * @param {string} query - The query string (with or without leading '?').
+ * @returns {Record<string, string>} Object representing parsed query parameters.
+ *
+ * @example
+ * parseQueryString('?page=1&limit=10');
+ * // → { page: '1', limit: '10' }
+ */
+export declare function parseQueryString(query: string): Record<string, string>;
+//# sourceMappingURL=url.utils.d.ts.map

package/build/esm/utils/url.utils.js

@@ -0,0 +1,73 @@
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+import { URL, URLSearchParams } from "url";
+/**
+ * Appends query parameters to a given URL.
+ *
+ * @param {string} url - The base URL to which query parameters will be appended.
+ * @param {Record<string, string | number>} params - Key-value pairs to add as query parameters.
+ * @returns {string} The new URL string with query parameters appended.
+ *
+ * @example
+ * appendQueryParams('https://example.com', { page: 1, limit: 10 });
+ * // → 'https://example.com/?page=1&limit=10'
+ */
+export function appendQueryParams(url, params) {
+    var e_1, _a;
+    var urlObj = new URL(url);
+    try {
+        for (var _b = __values(Object.entries(params)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var _d = __read(_c.value, 2), key = _d[0], value = _d[1];
+            urlObj.searchParams.set(key, value.toString());
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return urlObj.toString();
+}
+/**
+ * Parses a query string into a key-value object.
+ *
+ * @param {string} query - The query string (with or without leading '?').
+ * @returns {Record<string, string>} Object representing parsed query parameters.
+ *
+ * @example
+ * parseQueryString('?page=1&limit=10');
+ * // → { page: '1', limit: '10' }
+ */
+export function parseQueryString(query) {
+    var cleanQuery = query.startsWith("?") ? query.slice(1) : query;
+    // Object.fromEntries guarantees string values in result
+    return Object.fromEntries(new URLSearchParams(cleanQuery));
+}
+//# sourceMappingURL=url.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"url.utils.js","sourceRoot":"","sources":["../../../src/utils/url.utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,EAAE,GAAG,EAAE,eAAe,EAAE,MAAM,KAAK,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAW,EACX,MAAuC;;IAEvC,IAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;;QAC5B,KAA2B,IAAA,KAAA,SAAA,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA,gBAAA,4BAAE,CAAC;YAAzC,IAAA,KAAA,mBAAY,EAAX,GAAG,QAAA,EAAE,KAAK,QAAA;YACpB,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjD,CAAC;;;;;;;;;IACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,wDAAwD;IACxD,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,eAAe,CAAC,UAAU,CAAC,CAGxD,CAAC;AACJ,CAAC","sourcesContent":["import { URL, URLSearchParams } from \"url\";\n\n/**\n * Appends query parameters to a given URL.\n *\n * @param {string} url - The base URL to which query parameters will be appended.\n * @param {Record<string, string | number>} params - Key-value pairs to add as query parameters.\n * @returns {string} The new URL string with query parameters appended.\n *\n * @example\n * appendQueryParams('https://example.com', { page: 1, limit: 10 });\n * // → 'https://example.com/?page=1&limit=10'\n */\nexport function appendQueryParams(\n  url: string,\n  params: Record<string, string | number>,\n): string {\n  const urlObj = new URL(url);\n  for (const [key, value] of Object.entries(params)) {\n    urlObj.searchParams.set(key, value.toString());\n  }\n  return urlObj.toString();\n}\n\n/**\n * Parses a query string into a key-value object.\n *\n * @param {string} query - The query string (with or without leading '?').\n * @returns {Record<string, string>} Object representing parsed query parameters.\n *\n * @example\n * parseQueryString('?page=1&limit=10');\n * // → { page: '1', limit: '10' }\n */\nexport function parseQueryString(query: string): Record<string, string> {\n  const cleanQuery = query.startsWith(\"?\") ? query.slice(1) : query;\n  // Object.fromEntries guarantees string values in result\n  return Object.fromEntries(new URLSearchParams(cleanQuery)) as Record<\n    string,\n    string\n  >;\n}\n"]}

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

@@ -0,0 +1,60 @@
+/**
+ * Collection of common validation helpers for strings, numbers, email, UUID, etc.
+ */
+/**
+ * Checks if a string is a valid email address.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid email, else false.
+ */
+export declare function isEmail(str: string): boolean;
+/**
+ * Checks if a string is a valid UUID (versions 1-5).
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid UUID, else false.
+ */
+export declare function isUUID(str: string): boolean;
+/**
+ * Checks if a string is a valid URL.
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if valid URL, else false.
+ */
+export declare function isURL(str: string): boolean;
+/**
+ * Checks if a string is a valid international phone number (E.164 or common patterns).
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if looks like a phone number.
+ */
+export declare function isPhone(str: string): boolean;
+/**
+ * Checks if a string is strictly alphanumeric (letters/numbers only).
+ *
+ * @param {string} str - The input string.
+ * @returns {boolean} True if alphanumeric.
+ */
+export declare function isAlphanumeric(str: string): boolean;
+/**
+ * Checks if a string or number can be safely parsed to a number.
+ *
+ * @param {string | number} value - The value to check.
+ * @returns {boolean} True if the value is numeric.
+ */
+export declare function isNumeric(value: string | number): boolean;
+/**
+ * Checks if a string is a valid hex color code (e.g. #FFF or #FFFFFF).
+ *
+ * @param {string} str - Input string.
+ * @returns {boolean}
+ */
+export declare function isHexColor(str: string): boolean;
+/**
+ * Checks if a string is a valid date string.
+ *
+ * @param {string} str - Input string.
+ * @returns {boolean}
+ */
+export declare function isISODate(str: string): boolean;
+//# sourceMappingURL=validate.utils.d.ts.map