@rzl-zone/utils-js 3.12.0 → 3.12.1-beta.1

package/dist/safeStableStringify-CJtP89qn.cjs

@@ -0,0 +1,106 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+"use strict";
+const require_assertIsBoolean = require('./assertIsBoolean-C8WEXVr2.cjs');
+const require_isBigInt = require('./isBigInt-C4krUeAw.cjs');
+function isMap(value) {
+	return Object.prototype.toString.call(value) === "[object Map]" || value instanceof Map;
+}
+const isDate = (value, options = {}) => {
+	require_assertIsBoolean.assertIsPlainObject(options, { message: ({ currentType, validType }) => `Second parameter (\`options\`) must be of type \`${validType}\`, but received: \`${currentType}\`.` });
+	const skipInvalidDate = require_assertIsBoolean.isPlainObject(options) && require_assertIsBoolean.isBoolean(options.skipInvalidDate) ? options.skipInvalidDate : false;
+	const instanceDate = value instanceof Date;
+	if (skipInvalidDate) return instanceDate;
+	return instanceDate && !require_assertIsBoolean.isNaN(value.getTime());
+};
+const safeStableStringify = (value, options = {}) => {
+	require_assertIsBoolean.assertIsPlainObject(options, { message: ({ currentType, validType }) => `Second parameter (\`options\`) must be of type \`${validType}\`, but received: \`${currentType}\`.` });
+	const pretty = require_assertIsBoolean.hasOwnProp(options, "pretty") ? options.pretty : false;
+	const sortKeys = require_assertIsBoolean.hasOwnProp(options, "sortKeys") ? options.sortKeys : true;
+	const sortArray = require_assertIsBoolean.hasOwnProp(options, "sortArray") ? options.sortArray : false;
+	const keepUndefined = require_assertIsBoolean.hasOwnProp(options, "keepUndefined") ? options.keepUndefined : false;
+	if (!require_assertIsBoolean.isBoolean(sortKeys) || !require_assertIsBoolean.isBoolean(sortArray) || !require_assertIsBoolean.isBoolean(pretty) || !require_assertIsBoolean.isBoolean(keepUndefined)) throw new TypeError(`Parameters \`sortKeys\`, \`sortArray\`, \`keepUndefined\` and \`pretty\` property of the \`options\` (second parameter) must be of type \`boolean\`, but received: "['sortKeys': \`${require_assertIsBoolean.getPreciseType(sortKeys)}\`, 'sortArray': \`${require_assertIsBoolean.getPreciseType(sortArray)}\`, 'keepUndefined': \`${require_assertIsBoolean.getPreciseType(keepUndefined)}\`, 'pretty': \`${require_assertIsBoolean.getPreciseType(pretty)}\`]".`);
+	if (require_assertIsBoolean.isUndefined(value)) return keepUndefined ? "undefined" : "null";
+	const seen = /* @__PURE__ */ new WeakSet();
+	const isPrimitive = (val) => require_assertIsBoolean.isNull(val) || !require_assertIsBoolean.isObjectOrArray(val) && !require_assertIsBoolean.isFunction(val);
+	const deepProcess = (val) => {
+		if (require_assertIsBoolean.isNumberObject(val)) {
+			const valOf = val.valueOf();
+			return require_assertIsBoolean.isNaN(valOf) || require_assertIsBoolean.isInfinityNumber(valOf) ? null : valOf;
+		}
+		if (require_assertIsBoolean.isStringObject(val)) return val.valueOf();
+		if (require_assertIsBoolean.isBooleanObject(val)) return val.valueOf();
+		if (require_assertIsBoolean.isFunction(val) || require_assertIsBoolean.isSymbol(val)) return void 0;
+		if (require_isBigInt.isBigInt(val)) return val.toString();
+		if (require_assertIsBoolean.isNaN(val) || require_assertIsBoolean.isInfinityNumber(val)) return null;
+		if (require_assertIsBoolean.isUndefined(val)) return keepUndefined ? void 0 : null;
+		if (require_assertIsBoolean.isObjectOrArray(val)) {
+			if (seen.has(val)) return "[Circular]";
+			seen.add(val);
+			if (isDate(val)) return val.toISOString();
+			if (isMap(val)) return { map: Array.from(val.entries()).map(([k, v]) => [k, deepProcess(v)]) };
+			if (require_assertIsBoolean.isSet(val)) return { set: Array.from(val.values()).map(deepProcess) };
+			if (require_assertIsBoolean.isArray(val)) {
+				const processedArr = val.map(deepProcess);
+				if (sortArray) {
+					const primitives = [];
+					const nonPrimitives = [];
+					for (const item of processedArr) if (isPrimitive(item)) primitives.push(item);
+					else nonPrimitives.push(item);
+					primitives.sort((a, b) => {
+						if (require_assertIsBoolean.isNumber(a) && require_assertIsBoolean.isNumber(b)) return a - b;
+						return String(a).localeCompare(String(b));
+					});
+					return [...primitives, ...nonPrimitives];
+				}
+				return processedArr;
+			}
+			const keys = Object.keys(val);
+			if (sortKeys) keys.sort((a, b) => {
+				const na = Number(a);
+				const nb = Number(b);
+				if (!require_assertIsBoolean.isNaN(na) && !require_assertIsBoolean.isNaN(nb)) return na - nb;
+				return a.localeCompare(b);
+			});
+			const result = {};
+			if (require_assertIsBoolean.isObject(val)) for (const k of keys) {
+				const v = deepProcess(val[k]);
+				if (!require_assertIsBoolean.isUndefined(v)) result[k] = v;
+			}
+			return result;
+		}
+		return val;
+	};
+	try {
+		return JSON.stringify(deepProcess(value), null, pretty ? 2 : 0);
+	} catch (err) {
+		console.warn("Error in safeStableStringify:", err);
+		return "{}";
+	}
+};
+Object.defineProperty(exports, 'isDate', {
+  enumerable: true,
+  get: function () {
+    return isDate;
+  }
+});
+Object.defineProperty(exports, 'isMap', {
+  enumerable: true,
+  get: function () {
+    return isMap;
+  }
+});
+Object.defineProperty(exports, 'safeStableStringify', {
+  enumerable: true,
+  get: function () {
+    return safeStableStringify;
+  }
+});
+//# sourceMappingURL=safeStableStringify-CJtP89qn.cjs.map

package/dist/safeStableStringify-CJtP89qn.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeStableStringify-CJtP89qn.cjs","names":["isPlainObject","isBoolean","isNaN","hasOwnProp","isBoolean","getPreciseType","isUndefined","isNull","isObjectOrArray","isFunction","isNumberObject","isNaN","isInfinityNumber","isStringObject","isBooleanObject","isSymbol","isBigInt","isSet","isArray","isNumber","isObject"],"sources":["../src/predicates/is/isMap.ts","../src/predicates/is/isDate.ts","../src/conversions/stringify/safeStableStringify.ts"],"sourcesContent":["/** --------------------------------------------------\n * * ***Type guard: `isMap`.***\n * ----------------------------------------------------------\n * **Checks whether the given value is a **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object**.**\n * - **Behavior:**\n *    - Ensures that the provided value is an instance of **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)**.\n *    - Useful in TypeScript for narrowing types when working with collections.\n * @param {*} value The value to check.\n * @returns {boolean} Returns `true` if `value` is instance of **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)**, else `false`.\n * @example\n * isMap(new Map());\n * // ➔ true\n * isMap(new WeakMap());\n * // ➔ false\n * isMap({});\n * // ➔ false\n */\nexport function isMap<K = unknown, V = unknown>(\n  value: Map<K, V>\n): value is Map<K, V>;\nexport function isMap(value: unknown): value is Map<unknown, unknown>;\nexport function isMap(value: unknown): boolean {\n  return (\n    Object.prototype.toString.call(value) === \"[object Map]\" ||\n    value instanceof Map\n  );\n}\n","import { assertIsPlainObject } from \"@/assertions/objects/assertIsPlainObject\";\n\nimport { isNaN } from \"./isNaN\";\nimport { isPlainObject } from \"./isPlainObject\";\nimport { isBoolean } from \"./isBoolean\";\n\ntype isDateOptions = {\n  /** * ***Skip the validity check (`!isNaN(date.getTime())`).***\n   *\n   * When `true`, the function only checks that the value is an\n   * instance of `Date` without verifying that it represents a valid\n   * date value, default: `false`.\n   *\n   * @default false\n   */\n  skipInvalidDate?: boolean;\n};\n\n/** ----------------------------------------------------------\n * * ***Type guard: `isDate`.***\n * ----------------------------------------------------------\n * **Determines whether the given `value` is a real, valid JavaScript\n *   **[`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)** object.**\n * - **Behavior:**\n *    - Returns **true** only if:\n *      - `value` is an instance of `Date`.\n *      - and, unless `options.skipInvalidDate` is `true`,\n *        the underlying time value is valid (`!isNaN(value.getTime())`).\n *    - Returns **false** for:\n *      - non-Date values (strings, numbers, etc.).\n *      - `Date` instances that represent an invalid time value\n *        (e.g. `new Date(\"bad\")`), unless skipping is enabled.\n * @param {*} value - The value to check.\n * @param {isDateOptions} [options] - Optional settings.\n * @returns {boolean} Return `true` if value is a valid Date object.\n * @example\n * isDate(new Date());\n * // ➜ true\n * isDate(new Date(\"invalid\"));\n * // ➜ false\n * isDate(\"2024-01-01\");\n * // ➜ false\n *\n * // Skipping validity check:\n * isDate(new Date(\"invalid\"), { skipInvalidDate: true });\n * // ➜ true\n */\nexport const isDate = (\n  value: unknown,\n  options: isDateOptions = {}\n): value is Date => {\n  assertIsPlainObject(options, {\n    message: ({ currentType, validType }) =>\n      `Second parameter (\\`options\\`) must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`\n  });\n\n  const skipInvalidDate =\n    isPlainObject(options) && isBoolean(options.skipInvalidDate)\n      ? options.skipInvalidDate\n      : false;\n\n  const instanceDate = value instanceof Date;\n\n  if (skipInvalidDate) return instanceDate;\n  return instanceDate && !isNaN(value.getTime());\n};\n","import { assertIsPlainObject } from \"@/assertions/objects/assertIsPlainObject\";\n\nimport { isSet } from \"@/predicates/is/isSet\";\nimport { isMap } from \"@/predicates/is/isMap\";\nimport { isNaN } from \"@/predicates/is/isNaN\";\nimport { isDate } from \"@/predicates/is/isDate\";\nimport { isNull } from \"@/predicates/is/isNull\";\nimport { isArray } from \"@/predicates/is/isArray\";\nimport { isSymbol } from \"@/predicates/is/isSymbol\";\nimport { isNumber } from \"@/predicates/is/isNumber\";\nimport { isObject } from \"@/predicates/is/isObject\";\nimport { isBigInt } from \"@/predicates/is/isBigInt\";\nimport { isBoolean } from \"@/predicates/is/isBoolean\";\nimport { isFunction } from \"@/predicates/is/isFunction\";\nimport { hasOwnProp } from \"@/predicates/has/hasOwnProp\";\nimport { isUndefined } from \"@/predicates/is/isUndefined\";\nimport { isNumberObject } from \"@/predicates/is/isNumberObject\";\nimport { isStringObject } from \"@/predicates/is/isStringObject\";\nimport { isBooleanObject } from \"@/predicates/is/isBooleanObject\";\nimport { isObjectOrArray } from \"@/predicates/is/isObjectOrArray\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { isInfinityNumber } from \"@/predicates/is/isInfinityNumber\";\n\n/** -------------------------------------------------\n * * ***Type Options for **{@link safeStableStringify | `safeStableStringify`}**.***\n * -------------------------------------------------\n */\ntype SafeStableStringifyOptions = {\n  /** -------------------------------------------------\n   * * ***Whether to sort **object keys** alphabetically (recursively).***\n   * -------------------------------------------------\n   *\n   * - `true` (default): object keys are sorted to ensure stable output.\n   * - `false`: preserves original insertion order of keys.\n   *\n   * @default true\n   */\n  sortKeys?: boolean;\n  /** -------------------------------------------------\n   * * ***Whether to sort **primitive values inside arrays**.***\n   * -------------------------------------------------\n   *\n   * - `true`: primitive values in arrays are sorted to ensure stable output.\n   * - `false` (default): arrays retain their original order; objects and nested arrays are not reordered.\n   *\n   * @default false\n   */\n  sortArray?: boolean;\n  /** -------------------------------------------------\n   * * ***Whether to pretty-print JSON output with 2-space indentation.***\n   * -------------------------------------------------\n   *\n   * - `true`: output is formatted with indentation and newlines.\n   * - `false` (default): produces compact single-line JSON.\n   *\n   * @default false\n   */\n  pretty?: boolean;\n  /** -------------------------------------------------\n   * * ***Preserve `undefined` values instead of converting them to `null`.***\n   * -------------------------------------------------\n   * **Controls how the internal `deepProcess` step rewrites values\n   * **before** the final `JSON.stringify` call.**\n   * - **Default (`false`):**\n   *     * Every `undefined` value (object properties **and** array elements)\n   *       is replaced with `null` **before** serialization, because this happens\n   *       first, the key is **not removed** by `JSON.stringify`.\n   * - **`true`** – Leaves `undefined` untouched so the final\n   *   `JSON.stringify` call behaves natively:\n   *     * Object properties with `undefined` are **removed**.\n   *     * Array elements that are `undefined` become `null`.\n   * @default false\n   * @example\n   * // ✅ keepUndefined = true: behaves like native JSON.stringify\n   * safeStableStringify({ a: undefined }, { keepUndefined: true });\n   * // ➔ '{}' // key removed\n   *\n   * // ✅ Default (false): convert undefined to null, key kept\n   * safeStableStringify({ a: undefined });\n   * // ➔ '{\"a\":null}' // key present, value null\n   *\n   * // Arrays\n   * safeStableStringify([undefined]);\n   * // ➔ '[null]' // same, but via pre-replacement\n   * safeStableStringify([undefined], { keepUndefined: true });\n   * // ➔ '[null]' // element becomes null\n   */\n  keepUndefined?: boolean;\n};\n\n/** --------------------------------------------\n * * ***Utility: `safeStableStringify`.***\n * ---------------------------------------------\n * **Safely converts a JavaScript value into a stable, JSON-compatible string.**\n * - **This function is an enhanced version of `JSON.stringify` with additional guarantees:**\n *    - ***Features:***\n *        - Recursively sorts object keys **only if** `sortKeys` is `true` (default: `true`), to ensure stable\n *          key order.\n *          - If `sortKeys` is `false`, preserves the original insertion order of object keys.\n *        - Optionally sorts array primitive values **only if** `sortArray` is `true` (default: `false`).\n *        - Only primitive values in arrays are sorted.\n *        - Objects and nested arrays keep their original position and are appended after sorted primitives.\n *        - If `sortArray` is `false`, arrays retain their original order.\n *        - Converts JavaScript special values for JSON safety:\n *            - `undefined`, `NaN`, `Infinity`, `-Infinity` ➔ `null`.\n *            - `BigInt` ➔ string (JSON does not support BigInt).\n *        - Converts boxed primitives box into their primitive equivalents:\n *            - `new Number(42)` ➔ `Number(42)` ➔ `42`.\n *            - `new String(\"hi\")` ➔ `String(\"hi\")` ➔ `\"hi\"`.\n *            - `new Boolean(true)` ➔ `Boolean(true)` ➔ `true`.\n *        - Functions and Symbols are removed.\n *        - Circular references are replaced with the string `\"[Circular]\"`.\n *        - Serializes:\n *            - `Date` ➔ ISO string (`date.toISOString()`).\n *            - `Set` ➔ `{ set: [values...] }` (values are recursively processed).\n *            - `Map` ➔ `{ map: [ [key, value], ... ] }` (values are recursively processed).\n *        - Compared to `JSON.stringify`, this ensures **stable output**:\n *            - Same object structure always produces the same string.\n *            - Useful for deep equality checks, hashing, caching keys, or snapshot tests.\n *        - Controls how `undefined` is handled **before** the final `JSON.stringify` call, by `keepUndefined`\n *          options, default: `false`.\n *            - **false**: All `undefined` values (object properties and array elements) are replaced\n *            with `null`, so object keys remain.\n *            - **true**: Leaves `undefined` values as-is, and handling by native `JSON.stringify` then:\n *               1. Removes object properties that are `undefined`.\n *               2. Converts `undefined` array elements to `null`.\n *            - Use `true` when you need native removal of keys or to preserve sparse arrays\n *              exactly as `JSON.stringify` would.\n * @param {*} value\n *  ***Any JavaScript value to serialize, can be:***\n *    - Primitives (`number`, `string`, `boolean`, `bigint`, `null`, `undefined`).\n *    - Boxed primitives (`new Number()`, `new String()`, `new Boolean()`).\n *    - Arrays, plain objects, nested structures.\n *    - Date, Map, Set.\n *    - Circular structures.\n * @param {SafeStableStringifyOptions} [options]\n *   ***Configuration options for `safeStableStringify`:***\n *    - `keepUndefined` (boolean) – Control how `undefined` is handled **before** the final `JSON.stringify`\n *       call, default: `false`.\n *    - `sortKeys` (boolean) – Whether to sort object keys alphabetically (recursively), default: `true`.\n *    - `sortArray` (boolean) – Whether to sort primitive values inside arrays, default: `false`.\n *    - `pretty` (boolean) – Whether to pretty-print JSON output with 2-space indentation, default: `false`.\n * @returns {string}\n *   A stable JSON string representation of the input value.\n * @throws **{@link TypeError | `TypeError`}** if `sortKeys`, `sortArray`, or `pretty` are not strictly boolean.\n * @example\n * ```ts\n * // Basic object key sorting\n * safeStableStringify({ b: 2, a: 1 });\n * // ➔ '{\"a\":1,\"b\":2}'\n *\n * // Disable key sorting (preserve insertion order)\n * safeStableStringify({ b: 2, a: 1 }, {\n *    sortKeys:false\n * });\n * // ➔ '{\"b\":2,\"a\":1}'\n *\n * // Sorting arrays with sortArray\n * safeStableStringify([3, 1, 2], {\n *    sortArray:true\n * });\n * // ➔ '[1,2,3]'\n *\n * // keepUndefined = true (native removal of keys)\n * safeStableStringify({ a: undefined }, { keepUndefined: true });\n * // ➔ '{}'   // key `a` is removed, like native JSON.stringify\n *\n * // Default keepUndefined = false (convert to null, keep key)\n * safeStableStringify({ a: undefined });\n * // ➔ '{\"a\":null}'\n *\n * // Nested object + sortArray=true\n * safeStableStringify({ z: [3, 1, 2], x: { d: 4, c: 3 } }, {\n *    sortKeys:true,\n *    sortArray:true\n * });\n * // ➔ '{\"x\":{\"c\":3,\"d\":4},\"z\":[1,2,3]}'\n *\n * // sortKeys=false and sortArray=true\n * safeStableStringify({ z: [3, 1, 2], x: { d: 4, c: 3 } }, {\n *    sortKeys:false,\n *    sortArray:true\n * });\n * // ➔ '{\"z\":[1,2,3],\"x\":{\"d\":4,\"c\":3}}'\n *\n * // Pretty print output\n * safeStableStringify([3, 1, 2], {\n *    sortArray:true,\n *    pretty:true\n * });\n * // ➔ `[\n * //   1,\n * //   2,\n * //   3\n * // ]`\n *\n * // Boxed primitives converted to primitive\n * safeStableStringify({ n: new Number(42), s: new String(\"hi\"), b: new Boolean(true) });\n * // ➔ '{\"n\":42,\"s\":\"hi\",\"b\":true}'\n *\n * // Handles Date, BigInt, Map and Set\n * safeStableStringify({\n *   time: new Date(\"2025-01-01\"),\n *   big: BigInt(9007199254740991),\n *   data: new Map([[\"key\", new Set([1, 2])]])\n * });\n * // ➔ '{\"big\":\"9007199254740991\",\"data\":{\"map\":[[\"key\",{\"set\":[1,2]}]]},\"time\":\"2025-01-01T00:00:00.000Z\"}'\n *\n * // Functions and symbols are removed\n * safeStableStringify({ f: () => {}, s: Symbol(\"wow\") });\n * // ➔ '{}'\n *\n * // undefined, NaN, Infinity convert to null (keepUndefined = false or keepUndefined = true)\n * safeStableStringify([undefined, NaN, Infinity, -Infinity]);\n * // ➔ '[null,null,null,null]'\n *\n * // Circular reference\n * const obj = { name: \"A\" };\n * obj.self = obj;\n * safeStableStringify(obj);\n * // ➔ '{\"name\":\"A\",\"self\":\"[Circular]\"}'\n *\n * // Complex nested sortArray with objects\n * const arr = [9, 7, [4, 2, 3], { z: [5, 1, 6] }];\n * safeStableStringify(arr, { sortArray: true, sortKeys: true });\n * // ➔ '[7,9,[2,3,4],{\"z\":[1,5,6]}]'\n * ```\n */\nexport const safeStableStringify = (\n  value: unknown,\n  options: SafeStableStringifyOptions = {}\n): string => {\n  assertIsPlainObject(options, {\n    message: ({ currentType, validType }) =>\n      `Second parameter (\\`options\\`) must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`\n  });\n\n  const pretty = hasOwnProp(options, \"pretty\") ? options.pretty : false;\n  const sortKeys = hasOwnProp(options, \"sortKeys\") ? options.sortKeys : true;\n  const sortArray = hasOwnProp(options, \"sortArray\")\n    ? options.sortArray\n    : false;\n  const keepUndefined = hasOwnProp(options, \"keepUndefined\")\n    ? options.keepUndefined\n    : false;\n\n  if (\n    !isBoolean(sortKeys) ||\n    !isBoolean(sortArray) ||\n    !isBoolean(pretty) ||\n    !isBoolean(keepUndefined)\n  ) {\n    throw new TypeError(\n      `Parameters \\`sortKeys\\`, \\`sortArray\\`, \\`keepUndefined\\` and \\`pretty\\` property of the \\`options\\` (second parameter) must be of type \\`boolean\\`, but received: \"['sortKeys': \\`${getPreciseType(\n        sortKeys\n      )}\\`, 'sortArray': \\`${getPreciseType(\n        sortArray\n      )}\\`, 'keepUndefined': \\`${getPreciseType(\n        keepUndefined\n      )}\\`, 'pretty': \\`${getPreciseType(pretty)}\\`]\".`\n    );\n  }\n\n  if (isUndefined(value)) {\n    return keepUndefined ? \"undefined\" : \"null\";\n  }\n\n  const seen = new WeakSet();\n\n  const isPrimitive = (val: unknown): boolean =>\n    isNull(val) || (!isObjectOrArray(val) && !isFunction(val));\n\n  const deepProcess = (val: unknown): unknown => {\n    if (isNumberObject(val)) {\n      const valOf = val.valueOf();\n      return isNaN(valOf) || isInfinityNumber(valOf) ? null : valOf;\n    }\n    if (isStringObject(val)) return val.valueOf();\n    if (isBooleanObject(val)) return val.valueOf();\n    if (isFunction(val) || isSymbol(val)) return undefined;\n    if (isBigInt(val)) return val.toString();\n    if (isNaN(val) || isInfinityNumber(val)) return null;\n    if (isUndefined(val)) {\n      return keepUndefined ? undefined : null;\n    }\n\n    if (isObjectOrArray(val)) {\n      if (seen.has(val)) return \"[Circular]\";\n      seen.add(val);\n\n      if (isDate(val)) return val.toISOString();\n      if (isMap(val)) {\n        return {\n          map: Array.from(val.entries()).map(([k, v]) => [k, deepProcess(v)])\n        };\n      }\n      if (isSet(val)) return { set: Array.from(val.values()).map(deepProcess) };\n\n      if (isArray(val)) {\n        const processedArr = val.map(deepProcess);\n        if (sortArray) {\n          const primitives: unknown[] = [];\n          const nonPrimitives: unknown[] = [];\n\n          for (const item of processedArr) {\n            if (isPrimitive(item)) primitives.push(item);\n            else nonPrimitives.push(item);\n          }\n          primitives.sort((a, b) => {\n            if (isNumber(a) && isNumber(b)) return a - b;\n            return String(a).localeCompare(String(b));\n          });\n          return [...primitives, ...nonPrimitives];\n        }\n        return processedArr;\n      }\n\n      const keys = Object.keys(val);\n      if (sortKeys) {\n        keys.sort((a, b) => {\n          const na = Number(a);\n          const nb = Number(b);\n          if (!isNaN(na) && !isNaN(nb)) return na - nb;\n          return a.localeCompare(b);\n        });\n      }\n\n      const result: Record<string, unknown> = {};\n\n      if (isObject(val)) {\n        for (const k of keys) {\n          const v = deepProcess(val[k]);\n          if (!isUndefined(v)) result[k] = v;\n        }\n      }\n\n      return result;\n    }\n\n    return val;\n  };\n\n  try {\n    return JSON.stringify(deepProcess(value), null, pretty ? 2 : 0);\n  } catch (err) {\n    console.warn(\"Error in safeStableStringify:\", err);\n    return \"{}\";\n  }\n};\n"],"mappings":"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"}

package/dist/safeStableStringify-CXOZ9Ub8.js

@@ -0,0 +1,88 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+import { A as isPlainObject, C as isSymbol, D as isNaN, E as isNull, F as isBoolean, M as isArray, O as isNumberObject, P as isFunction, S as isUndefined, T as assertIsPlainObject, b as hasOwnProp, f as isSet, g as isStringObject, h as isBooleanObject, j as isObject, m as isInfinityNumber, r as getPreciseType, w as isNumber, x as isObjectOrArray } from "./assertIsBoolean-DR1SaXPD.js";
+import { t as isBigInt } from "./isBigInt-DKe0M6hp.js";
+function isMap(value) {
+	return Object.prototype.toString.call(value) === "[object Map]" || value instanceof Map;
+}
+const isDate = (value, options = {}) => {
+	assertIsPlainObject(options, { message: ({ currentType, validType }) => `Second parameter (\`options\`) must be of type \`${validType}\`, but received: \`${currentType}\`.` });
+	const skipInvalidDate = isPlainObject(options) && isBoolean(options.skipInvalidDate) ? options.skipInvalidDate : false;
+	const instanceDate = value instanceof Date;
+	if (skipInvalidDate) return instanceDate;
+	return instanceDate && !isNaN(value.getTime());
+};
+const safeStableStringify = (value, options = {}) => {
+	assertIsPlainObject(options, { message: ({ currentType, validType }) => `Second parameter (\`options\`) must be of type \`${validType}\`, but received: \`${currentType}\`.` });
+	const pretty = hasOwnProp(options, "pretty") ? options.pretty : false;
+	const sortKeys = hasOwnProp(options, "sortKeys") ? options.sortKeys : true;
+	const sortArray = hasOwnProp(options, "sortArray") ? options.sortArray : false;
+	const keepUndefined = hasOwnProp(options, "keepUndefined") ? options.keepUndefined : false;
+	if (!isBoolean(sortKeys) || !isBoolean(sortArray) || !isBoolean(pretty) || !isBoolean(keepUndefined)) throw new TypeError(`Parameters \`sortKeys\`, \`sortArray\`, \`keepUndefined\` and \`pretty\` property of the \`options\` (second parameter) must be of type \`boolean\`, but received: "['sortKeys': \`${getPreciseType(sortKeys)}\`, 'sortArray': \`${getPreciseType(sortArray)}\`, 'keepUndefined': \`${getPreciseType(keepUndefined)}\`, 'pretty': \`${getPreciseType(pretty)}\`]".`);
+	if (isUndefined(value)) return keepUndefined ? "undefined" : "null";
+	const seen = /* @__PURE__ */ new WeakSet();
+	const isPrimitive = (val) => isNull(val) || !isObjectOrArray(val) && !isFunction(val);
+	const deepProcess = (val) => {
+		if (isNumberObject(val)) {
+			const valOf = val.valueOf();
+			return isNaN(valOf) || isInfinityNumber(valOf) ? null : valOf;
+		}
+		if (isStringObject(val)) return val.valueOf();
+		if (isBooleanObject(val)) return val.valueOf();
+		if (isFunction(val) || isSymbol(val)) return void 0;
+		if (isBigInt(val)) return val.toString();
+		if (isNaN(val) || isInfinityNumber(val)) return null;
+		if (isUndefined(val)) return keepUndefined ? void 0 : null;
+		if (isObjectOrArray(val)) {
+			if (seen.has(val)) return "[Circular]";
+			seen.add(val);
+			if (isDate(val)) return val.toISOString();
+			if (isMap(val)) return { map: Array.from(val.entries()).map(([k, v]) => [k, deepProcess(v)]) };
+			if (isSet(val)) return { set: Array.from(val.values()).map(deepProcess) };
+			if (isArray(val)) {
+				const processedArr = val.map(deepProcess);
+				if (sortArray) {
+					const primitives = [];
+					const nonPrimitives = [];
+					for (const item of processedArr) if (isPrimitive(item)) primitives.push(item);
+					else nonPrimitives.push(item);
+					primitives.sort((a, b) => {
+						if (isNumber(a) && isNumber(b)) return a - b;
+						return String(a).localeCompare(String(b));
+					});
+					return [...primitives, ...nonPrimitives];
+				}
+				return processedArr;
+			}
+			const keys = Object.keys(val);
+			if (sortKeys) keys.sort((a, b) => {
+				const na = Number(a);
+				const nb = Number(b);
+				if (!isNaN(na) && !isNaN(nb)) return na - nb;
+				return a.localeCompare(b);
+			});
+			const result = {};
+			if (isObject(val)) for (const k of keys) {
+				const v = deepProcess(val[k]);
+				if (!isUndefined(v)) result[k] = v;
+			}
+			return result;
+		}
+		return val;
+	};
+	try {
+		return JSON.stringify(deepProcess(value), null, pretty ? 2 : 0);
+	} catch (err) {
+		console.warn("Error in safeStableStringify:", err);
+		return "{}";
+	}
+};
+export { isDate as n, isMap as r, safeStableStringify as t };
+//# sourceMappingURL=safeStableStringify-CXOZ9Ub8.js.map

package/dist/safeStableStringify-CXOZ9Ub8.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeStableStringify-CXOZ9Ub8.js","names":[],"sources":["../src/predicates/is/isMap.ts","../src/predicates/is/isDate.ts","../src/conversions/stringify/safeStableStringify.ts"],"sourcesContent":["/** --------------------------------------------------\n * * ***Type guard: `isMap`.***\n * ----------------------------------------------------------\n * **Checks whether the given value is a **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object**.**\n * - **Behavior:**\n *    - Ensures that the provided value is an instance of **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)**.\n *    - Useful in TypeScript for narrowing types when working with collections.\n * @param {*} value The value to check.\n * @returns {boolean} Returns `true` if `value` is instance of **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)**, else `false`.\n * @example\n * isMap(new Map());\n * // ➔ true\n * isMap(new WeakMap());\n * // ➔ false\n * isMap({});\n * // ➔ false\n */\nexport function isMap<K = unknown, V = unknown>(\n  value: Map<K, V>\n): value is Map<K, V>;\nexport function isMap(value: unknown): value is Map<unknown, unknown>;\nexport function isMap(value: unknown): boolean {\n  return (\n    Object.prototype.toString.call(value) === \"[object Map]\" ||\n    value instanceof Map\n  );\n}\n","import { assertIsPlainObject } from \"@/assertions/objects/assertIsPlainObject\";\n\nimport { isNaN } from \"./isNaN\";\nimport { isPlainObject } from \"./isPlainObject\";\nimport { isBoolean } from \"./isBoolean\";\n\ntype isDateOptions = {\n  /** * ***Skip the validity check (`!isNaN(date.getTime())`).***\n   *\n   * When `true`, the function only checks that the value is an\n   * instance of `Date` without verifying that it represents a valid\n   * date value, default: `false`.\n   *\n   * @default false\n   */\n  skipInvalidDate?: boolean;\n};\n\n/** ----------------------------------------------------------\n * * ***Type guard: `isDate`.***\n * ----------------------------------------------------------\n * **Determines whether the given `value` is a real, valid JavaScript\n *   **[`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)** object.**\n * - **Behavior:**\n *    - Returns **true** only if:\n *      - `value` is an instance of `Date`.\n *      - and, unless `options.skipInvalidDate` is `true`,\n *        the underlying time value is valid (`!isNaN(value.getTime())`).\n *    - Returns **false** for:\n *      - non-Date values (strings, numbers, etc.).\n *      - `Date` instances that represent an invalid time value\n *        (e.g. `new Date(\"bad\")`), unless skipping is enabled.\n * @param {*} value - The value to check.\n * @param {isDateOptions} [options] - Optional settings.\n * @returns {boolean} Return `true` if value is a valid Date object.\n * @example\n * isDate(new Date());\n * // ➜ true\n * isDate(new Date(\"invalid\"));\n * // ➜ false\n * isDate(\"2024-01-01\");\n * // ➜ false\n *\n * // Skipping validity check:\n * isDate(new Date(\"invalid\"), { skipInvalidDate: true });\n * // ➜ true\n */\nexport const isDate = (\n  value: unknown,\n  options: isDateOptions = {}\n): value is Date => {\n  assertIsPlainObject(options, {\n    message: ({ currentType, validType }) =>\n      `Second parameter (\\`options\\`) must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`\n  });\n\n  const skipInvalidDate =\n    isPlainObject(options) && isBoolean(options.skipInvalidDate)\n      ? options.skipInvalidDate\n      : false;\n\n  const instanceDate = value instanceof Date;\n\n  if (skipInvalidDate) return instanceDate;\n  return instanceDate && !isNaN(value.getTime());\n};\n","import { assertIsPlainObject } from \"@/assertions/objects/assertIsPlainObject\";\n\nimport { isSet } from \"@/predicates/is/isSet\";\nimport { isMap } from \"@/predicates/is/isMap\";\nimport { isNaN } from \"@/predicates/is/isNaN\";\nimport { isDate } from \"@/predicates/is/isDate\";\nimport { isNull } from \"@/predicates/is/isNull\";\nimport { isArray } from \"@/predicates/is/isArray\";\nimport { isSymbol } from \"@/predicates/is/isSymbol\";\nimport { isNumber } from \"@/predicates/is/isNumber\";\nimport { isObject } from \"@/predicates/is/isObject\";\nimport { isBigInt } from \"@/predicates/is/isBigInt\";\nimport { isBoolean } from \"@/predicates/is/isBoolean\";\nimport { isFunction } from \"@/predicates/is/isFunction\";\nimport { hasOwnProp } from \"@/predicates/has/hasOwnProp\";\nimport { isUndefined } from \"@/predicates/is/isUndefined\";\nimport { isNumberObject } from \"@/predicates/is/isNumberObject\";\nimport { isStringObject } from \"@/predicates/is/isStringObject\";\nimport { isBooleanObject } from \"@/predicates/is/isBooleanObject\";\nimport { isObjectOrArray } from \"@/predicates/is/isObjectOrArray\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\nimport { isInfinityNumber } from \"@/predicates/is/isInfinityNumber\";\n\n/** -------------------------------------------------\n * * ***Type Options for **{@link safeStableStringify | `safeStableStringify`}**.***\n * -------------------------------------------------\n */\ntype SafeStableStringifyOptions = {\n  /** -------------------------------------------------\n   * * ***Whether to sort **object keys** alphabetically (recursively).***\n   * -------------------------------------------------\n   *\n   * - `true` (default): object keys are sorted to ensure stable output.\n   * - `false`: preserves original insertion order of keys.\n   *\n   * @default true\n   */\n  sortKeys?: boolean;\n  /** -------------------------------------------------\n   * * ***Whether to sort **primitive values inside arrays**.***\n   * -------------------------------------------------\n   *\n   * - `true`: primitive values in arrays are sorted to ensure stable output.\n   * - `false` (default): arrays retain their original order; objects and nested arrays are not reordered.\n   *\n   * @default false\n   */\n  sortArray?: boolean;\n  /** -------------------------------------------------\n   * * ***Whether to pretty-print JSON output with 2-space indentation.***\n   * -------------------------------------------------\n   *\n   * - `true`: output is formatted with indentation and newlines.\n   * - `false` (default): produces compact single-line JSON.\n   *\n   * @default false\n   */\n  pretty?: boolean;\n  /** -------------------------------------------------\n   * * ***Preserve `undefined` values instead of converting them to `null`.***\n   * -------------------------------------------------\n   * **Controls how the internal `deepProcess` step rewrites values\n   * **before** the final `JSON.stringify` call.**\n   * - **Default (`false`):**\n   *     * Every `undefined` value (object properties **and** array elements)\n   *       is replaced with `null` **before** serialization, because this happens\n   *       first, the key is **not removed** by `JSON.stringify`.\n   * - **`true`** – Leaves `undefined` untouched so the final\n   *   `JSON.stringify` call behaves natively:\n   *     * Object properties with `undefined` are **removed**.\n   *     * Array elements that are `undefined` become `null`.\n   * @default false\n   * @example\n   * // ✅ keepUndefined = true: behaves like native JSON.stringify\n   * safeStableStringify({ a: undefined }, { keepUndefined: true });\n   * // ➔ '{}' // key removed\n   *\n   * // ✅ Default (false): convert undefined to null, key kept\n   * safeStableStringify({ a: undefined });\n   * // ➔ '{\"a\":null}' // key present, value null\n   *\n   * // Arrays\n   * safeStableStringify([undefined]);\n   * // ➔ '[null]' // same, but via pre-replacement\n   * safeStableStringify([undefined], { keepUndefined: true });\n   * // ➔ '[null]' // element becomes null\n   */\n  keepUndefined?: boolean;\n};\n\n/** --------------------------------------------\n * * ***Utility: `safeStableStringify`.***\n * ---------------------------------------------\n * **Safely converts a JavaScript value into a stable, JSON-compatible string.**\n * - **This function is an enhanced version of `JSON.stringify` with additional guarantees:**\n *    - ***Features:***\n *        - Recursively sorts object keys **only if** `sortKeys` is `true` (default: `true`), to ensure stable\n *          key order.\n *          - If `sortKeys` is `false`, preserves the original insertion order of object keys.\n *        - Optionally sorts array primitive values **only if** `sortArray` is `true` (default: `false`).\n *        - Only primitive values in arrays are sorted.\n *        - Objects and nested arrays keep their original position and are appended after sorted primitives.\n *        - If `sortArray` is `false`, arrays retain their original order.\n *        - Converts JavaScript special values for JSON safety:\n *            - `undefined`, `NaN`, `Infinity`, `-Infinity` ➔ `null`.\n *            - `BigInt` ➔ string (JSON does not support BigInt).\n *        - Converts boxed primitives box into their primitive equivalents:\n *            - `new Number(42)` ➔ `Number(42)` ➔ `42`.\n *            - `new String(\"hi\")` ➔ `String(\"hi\")` ➔ `\"hi\"`.\n *            - `new Boolean(true)` ➔ `Boolean(true)` ➔ `true`.\n *        - Functions and Symbols are removed.\n *        - Circular references are replaced with the string `\"[Circular]\"`.\n *        - Serializes:\n *            - `Date` ➔ ISO string (`date.toISOString()`).\n *            - `Set` ➔ `{ set: [values...] }` (values are recursively processed).\n *            - `Map` ➔ `{ map: [ [key, value], ... ] }` (values are recursively processed).\n *        - Compared to `JSON.stringify`, this ensures **stable output**:\n *            - Same object structure always produces the same string.\n *            - Useful for deep equality checks, hashing, caching keys, or snapshot tests.\n *        - Controls how `undefined` is handled **before** the final `JSON.stringify` call, by `keepUndefined`\n *          options, default: `false`.\n *            - **false**: All `undefined` values (object properties and array elements) are replaced\n *            with `null`, so object keys remain.\n *            - **true**: Leaves `undefined` values as-is, and handling by native `JSON.stringify` then:\n *               1. Removes object properties that are `undefined`.\n *               2. Converts `undefined` array elements to `null`.\n *            - Use `true` when you need native removal of keys or to preserve sparse arrays\n *              exactly as `JSON.stringify` would.\n * @param {*} value\n *  ***Any JavaScript value to serialize, can be:***\n *    - Primitives (`number`, `string`, `boolean`, `bigint`, `null`, `undefined`).\n *    - Boxed primitives (`new Number()`, `new String()`, `new Boolean()`).\n *    - Arrays, plain objects, nested structures.\n *    - Date, Map, Set.\n *    - Circular structures.\n * @param {SafeStableStringifyOptions} [options]\n *   ***Configuration options for `safeStableStringify`:***\n *    - `keepUndefined` (boolean) – Control how `undefined` is handled **before** the final `JSON.stringify`\n *       call, default: `false`.\n *    - `sortKeys` (boolean) – Whether to sort object keys alphabetically (recursively), default: `true`.\n *    - `sortArray` (boolean) – Whether to sort primitive values inside arrays, default: `false`.\n *    - `pretty` (boolean) – Whether to pretty-print JSON output with 2-space indentation, default: `false`.\n * @returns {string}\n *   A stable JSON string representation of the input value.\n * @throws **{@link TypeError | `TypeError`}** if `sortKeys`, `sortArray`, or `pretty` are not strictly boolean.\n * @example\n * ```ts\n * // Basic object key sorting\n * safeStableStringify({ b: 2, a: 1 });\n * // ➔ '{\"a\":1,\"b\":2}'\n *\n * // Disable key sorting (preserve insertion order)\n * safeStableStringify({ b: 2, a: 1 }, {\n *    sortKeys:false\n * });\n * // ➔ '{\"b\":2,\"a\":1}'\n *\n * // Sorting arrays with sortArray\n * safeStableStringify([3, 1, 2], {\n *    sortArray:true\n * });\n * // ➔ '[1,2,3]'\n *\n * // keepUndefined = true (native removal of keys)\n * safeStableStringify({ a: undefined }, { keepUndefined: true });\n * // ➔ '{}'   // key `a` is removed, like native JSON.stringify\n *\n * // Default keepUndefined = false (convert to null, keep key)\n * safeStableStringify({ a: undefined });\n * // ➔ '{\"a\":null}'\n *\n * // Nested object + sortArray=true\n * safeStableStringify({ z: [3, 1, 2], x: { d: 4, c: 3 } }, {\n *    sortKeys:true,\n *    sortArray:true\n * });\n * // ➔ '{\"x\":{\"c\":3,\"d\":4},\"z\":[1,2,3]}'\n *\n * // sortKeys=false and sortArray=true\n * safeStableStringify({ z: [3, 1, 2], x: { d: 4, c: 3 } }, {\n *    sortKeys:false,\n *    sortArray:true\n * });\n * // ➔ '{\"z\":[1,2,3],\"x\":{\"d\":4,\"c\":3}}'\n *\n * // Pretty print output\n * safeStableStringify([3, 1, 2], {\n *    sortArray:true,\n *    pretty:true\n * });\n * // ➔ `[\n * //   1,\n * //   2,\n * //   3\n * // ]`\n *\n * // Boxed primitives converted to primitive\n * safeStableStringify({ n: new Number(42), s: new String(\"hi\"), b: new Boolean(true) });\n * // ➔ '{\"n\":42,\"s\":\"hi\",\"b\":true}'\n *\n * // Handles Date, BigInt, Map and Set\n * safeStableStringify({\n *   time: new Date(\"2025-01-01\"),\n *   big: BigInt(9007199254740991),\n *   data: new Map([[\"key\", new Set([1, 2])]])\n * });\n * // ➔ '{\"big\":\"9007199254740991\",\"data\":{\"map\":[[\"key\",{\"set\":[1,2]}]]},\"time\":\"2025-01-01T00:00:00.000Z\"}'\n *\n * // Functions and symbols are removed\n * safeStableStringify({ f: () => {}, s: Symbol(\"wow\") });\n * // ➔ '{}'\n *\n * // undefined, NaN, Infinity convert to null (keepUndefined = false or keepUndefined = true)\n * safeStableStringify([undefined, NaN, Infinity, -Infinity]);\n * // ➔ '[null,null,null,null]'\n *\n * // Circular reference\n * const obj = { name: \"A\" };\n * obj.self = obj;\n * safeStableStringify(obj);\n * // ➔ '{\"name\":\"A\",\"self\":\"[Circular]\"}'\n *\n * // Complex nested sortArray with objects\n * const arr = [9, 7, [4, 2, 3], { z: [5, 1, 6] }];\n * safeStableStringify(arr, { sortArray: true, sortKeys: true });\n * // ➔ '[7,9,[2,3,4],{\"z\":[1,5,6]}]'\n * ```\n */\nexport const safeStableStringify = (\n  value: unknown,\n  options: SafeStableStringifyOptions = {}\n): string => {\n  assertIsPlainObject(options, {\n    message: ({ currentType, validType }) =>\n      `Second parameter (\\`options\\`) must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`\n  });\n\n  const pretty = hasOwnProp(options, \"pretty\") ? options.pretty : false;\n  const sortKeys = hasOwnProp(options, \"sortKeys\") ? options.sortKeys : true;\n  const sortArray = hasOwnProp(options, \"sortArray\")\n    ? options.sortArray\n    : false;\n  const keepUndefined = hasOwnProp(options, \"keepUndefined\")\n    ? options.keepUndefined\n    : false;\n\n  if (\n    !isBoolean(sortKeys) ||\n    !isBoolean(sortArray) ||\n    !isBoolean(pretty) ||\n    !isBoolean(keepUndefined)\n  ) {\n    throw new TypeError(\n      `Parameters \\`sortKeys\\`, \\`sortArray\\`, \\`keepUndefined\\` and \\`pretty\\` property of the \\`options\\` (second parameter) must be of type \\`boolean\\`, but received: \"['sortKeys': \\`${getPreciseType(\n        sortKeys\n      )}\\`, 'sortArray': \\`${getPreciseType(\n        sortArray\n      )}\\`, 'keepUndefined': \\`${getPreciseType(\n        keepUndefined\n      )}\\`, 'pretty': \\`${getPreciseType(pretty)}\\`]\".`\n    );\n  }\n\n  if (isUndefined(value)) {\n    return keepUndefined ? \"undefined\" : \"null\";\n  }\n\n  const seen = new WeakSet();\n\n  const isPrimitive = (val: unknown): boolean =>\n    isNull(val) || (!isObjectOrArray(val) && !isFunction(val));\n\n  const deepProcess = (val: unknown): unknown => {\n    if (isNumberObject(val)) {\n      const valOf = val.valueOf();\n      return isNaN(valOf) || isInfinityNumber(valOf) ? null : valOf;\n    }\n    if (isStringObject(val)) return val.valueOf();\n    if (isBooleanObject(val)) return val.valueOf();\n    if (isFunction(val) || isSymbol(val)) return undefined;\n    if (isBigInt(val)) return val.toString();\n    if (isNaN(val) || isInfinityNumber(val)) return null;\n    if (isUndefined(val)) {\n      return keepUndefined ? undefined : null;\n    }\n\n    if (isObjectOrArray(val)) {\n      if (seen.has(val)) return \"[Circular]\";\n      seen.add(val);\n\n      if (isDate(val)) return val.toISOString();\n      if (isMap(val)) {\n        return {\n          map: Array.from(val.entries()).map(([k, v]) => [k, deepProcess(v)])\n        };\n      }\n      if (isSet(val)) return { set: Array.from(val.values()).map(deepProcess) };\n\n      if (isArray(val)) {\n        const processedArr = val.map(deepProcess);\n        if (sortArray) {\n          const primitives: unknown[] = [];\n          const nonPrimitives: unknown[] = [];\n\n          for (const item of processedArr) {\n            if (isPrimitive(item)) primitives.push(item);\n            else nonPrimitives.push(item);\n          }\n          primitives.sort((a, b) => {\n            if (isNumber(a) && isNumber(b)) return a - b;\n            return String(a).localeCompare(String(b));\n          });\n          return [...primitives, ...nonPrimitives];\n        }\n        return processedArr;\n      }\n\n      const keys = Object.keys(val);\n      if (sortKeys) {\n        keys.sort((a, b) => {\n          const na = Number(a);\n          const nb = Number(b);\n          if (!isNaN(na) && !isNaN(nb)) return na - nb;\n          return a.localeCompare(b);\n        });\n      }\n\n      const result: Record<string, unknown> = {};\n\n      if (isObject(val)) {\n        for (const k of keys) {\n          const v = deepProcess(val[k]);\n          if (!isUndefined(v)) result[k] = v;\n        }\n      }\n\n      return result;\n    }\n\n    return val;\n  };\n\n  try {\n    return JSON.stringify(deepProcess(value), null, pretty ? 2 : 0);\n  } catch (err) {\n    console.warn(\"Error in safeStableStringify:\", err);\n    return \"{}\";\n  }\n};\n"],"mappings":"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"}

package/dist/strings/index.cjs

@@ -1,82 +1,80 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.12.0.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
-'use strict';
-
-var chunk7Y6I2DSU_cjs = require('../chunk-7Y6I2DSU.cjs');
-var chunkF66VDYIZ_cjs = require('../chunk-F66VDYIZ.cjs');
-var chunkFLJX37EL_cjs = require('../chunk-FLJX37EL.cjs');
-var chunkEV4Y7HCY_cjs = require('../chunk-EV4Y7HCY.cjs');
-require('../chunk-4YLBKLGS.cjs');
-var chunkGKC3UDMC_cjs = require('../chunk-GKC3UDMC.cjs');
-
-Object.defineProperty(exports, "capitalizeFirst", {
-  enumerable: true,
-  get: function () { return chunk7Y6I2DSU_cjs.capitalizeFirst; }
-});
-Object.defineProperty(exports, "capitalizeWords", {
-  enumerable: true,
-  get: function () { return chunk7Y6I2DSU_cjs.capitalizeWords; }
-});
-Object.defineProperty(exports, "getInitialsName", {
-  enumerable: true,
-  get: function () { return chunk7Y6I2DSU_cjs.getInitialsName; }
-});
-Object.defineProperty(exports, "replaceAt", {
-  enumerable: true,
-  get: function () { return chunk7Y6I2DSU_cjs.replaceAt; }
-});
-Object.defineProperty(exports, "stripHtmlTags", {
-  enumerable: true,
-  get: function () { return chunk7Y6I2DSU_cjs.stripHtmlTags; }
-});
-Object.defineProperty(exports, "normalizeString", {
-  enumerable: true,
-  get: function () { return chunkF66VDYIZ_cjs.normalizeString; }
-});
-Object.defineProperty(exports, "normalizeSpaces", {
-  enumerable: true,
-  get: function () { return chunkFLJX37EL_cjs.normalizeSpaces; }
-});
-Object.defineProperty(exports, "removeSpaces", {
-  enumerable: true,
-  get: function () { return chunkEV4Y7HCY_cjs.removeSpaces; }
-});
-Object.defineProperty(exports, "slugify", {
-  enumerable: true,
-  get: function () { return chunkGKC3UDMC_cjs.slugify; }
-});
-Object.defineProperty(exports, "toCamelCase", {
-  enumerable: true,
-  get: function () { return chunkGKC3UDMC_cjs.toCamelCase; }
-});
-Object.defineProperty(exports, "toDotCase", {
-  enumerable: true,
-  get: function () { return chunkGKC3UDMC_cjs.toDotCase; }
-});
-Object.defineProperty(exports, "toKebabCase", {
-  enumerable: true,
-  get: function () { return chunkGKC3UDMC_cjs.toKebabCase; }
-});
-Object.defineProperty(exports, "toLowerCase", {
-  enumerable: true,
-  get: function () { return chunkGKC3UDMC_cjs.toLowerCase; }
-});
-Object.defineProperty(exports, "toPascalCase", {
-  enumerable: true,
-  get: function () { return chunkGKC3UDMC_cjs.toPascalCase; }
-});
-Object.defineProperty(exports, "toPascalCaseSpace", {
-  enumerable: true,
-  get: function () { return chunkGKC3UDMC_cjs.toPascalCaseSpace; }
-});
-Object.defineProperty(exports, "toSnakeCase", {
-  enumerable: true,
-  get: function () { return chunkGKC3UDMC_cjs.toSnakeCase; }
-});
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_assertIsBoolean = require('../assertIsBoolean-C8WEXVr2.cjs');
+const require_isEmptyString = require('../isEmptyString-UiiUsSQj.cjs');
+const require_normalizeSpaces = require('../normalizeSpaces-ZXnR4Qzp.cjs');
+const require_normalizeString = require('../normalizeString-BE6ELqEb.cjs');
+const require_removeSpaces = require('../removeSpaces-CWIvhZHg.cjs');
+const capitalizeFirst = (string, options = {
+	lowerCaseNextRest: true,
+	trim: false
+}) => {
+	if (!require_assertIsBoolean.isNonEmptyString(string)) return "";
+	if (!require_assertIsBoolean.isPlainObject(options)) options = {};
+	const lowerCaseNextRest = options.lowerCaseNextRest !== false;
+	if (options.trim === true) string = string.trim();
+	return (string[0] ? string[0].toUpperCase() : "") + (lowerCaseNextRest ? string.slice(1).toLowerCase() : string.slice(1));
+};
+const capitalizeWords = (value, options = {
+	collapseSpaces: false,
+	trim: false
+}) => {
+	if (!require_assertIsBoolean.isNonEmptyString(value)) return "";
+	let result = value;
+	if (!require_assertIsBoolean.isPlainObject(options)) options = {};
+	const collapseSpaces = options.collapseSpaces === true;
+	if (options.trim === true) result = result.trim();
+	if (collapseSpaces) {
+		const leadingSpaces = result.match(/^\s*/)?.[0] ?? "";
+		const trailingSpaces = result.match(/\s*$/)?.[0] ?? "";
+		result = result.trim().replace(/\s+/g, " ");
+		result = `${leadingSpaces}${result}${trailingSpaces}`;
+	}
+	return result.toLowerCase().split(" ").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+};
+function stripHtmlTags(input) {
+	if (!require_assertIsBoolean.isString(input)) return;
+	if (require_isEmptyString.isEmptyString(input)) return "";
+	return input.replace(/<\/?[a-zA-Z][^<>]*\/?>/g, " ").trim().replace(/\s+/g, " ").trim();
+}
+const getInitialsName = (name) => {
+	if (!require_assertIsBoolean.isNonEmptyString(name)) return "";
+	name = name.replace(/\s+/g, " ").trim();
+	const nameParts = name.split(" ");
+	if (nameParts.length > 1) {
+		if (!(nameParts[0] && nameParts[1] && nameParts[1][0])) return "";
+		return (nameParts[0][0] + nameParts[1][0]).toUpperCase();
+	}
+	return name.length > 1 ? name.substring(0, 2).toUpperCase() : name[0]?.toUpperCase() ?? "";
+};
+const replaceAt = (index, originalString, replaceTo) => {
+	if (!require_assertIsBoolean.isNumber(index) || !require_assertIsBoolean.isString(replaceTo) || !require_assertIsBoolean.isString(originalString)) throw new TypeError(`First parameter (\`index\`) must be of type \`number\`, second parameter (\`originalString\`) and third parameter (\`replaceTo\`) must be of type \`string\`, but received: "['index': \`${require_assertIsBoolean.getPreciseType(index)}\`, 'originalString': \`${require_assertIsBoolean.getPreciseType(originalString)}\`, 'replaceTo': \`${require_assertIsBoolean.getPreciseType(replaceTo)}\`]".`);
+	if (index < 0 || index >= originalString.length) throw new RangeError("First parameter (`index`) is out of range from second parameter (`originalString`).");
+	return originalString.slice(0, index) + replaceTo + originalString.slice(index + 1);
+};
+exports.capitalizeFirst = capitalizeFirst;
+exports.capitalizeWords = capitalizeWords;
+exports.getInitialsName = getInitialsName;
+exports.normalizeSpaces = require_normalizeSpaces.normalizeSpaces;
+exports.normalizeString = require_normalizeString.normalizeString;
+exports.removeSpaces = require_removeSpaces.removeSpaces;
+exports.replaceAt = replaceAt;
+exports.slugify = require_assertIsBoolean.slugify;
+exports.stripHtmlTags = stripHtmlTags;
+exports.toCamelCase = require_assertIsBoolean.toCamelCase;
+exports.toDotCase = require_assertIsBoolean.toDotCase;
+exports.toKebabCase = require_assertIsBoolean.toKebabCase;
+exports.toLowerCase = require_assertIsBoolean.toLowerCase;
+exports.toPascalCase = require_assertIsBoolean.toPascalCase;
+exports.toPascalCaseSpace = require_assertIsBoolean.toPascalCaseSpace;
+exports.toSnakeCase = require_assertIsBoolean.toSnakeCase;
+//# sourceMappingURL=index.cjs.map

package/dist/strings/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["isNonEmptyString","isPlainObject","isNonEmptyString","isPlainObject","isString","isEmptyString","isNonEmptyString","isNumber","isString","getPreciseType"],"sources":["../../src/strings/capitalizations/capitalizeFirst.ts","../../src/strings/capitalizations/capitalizeWords.ts","../../src/strings/sanitizations/stripHtmlTags.ts","../../src/strings/utils/getInitialsName.ts","../../src/strings/utils/replaceAt.ts"],"sourcesContent":["import { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { isNonEmptyString } from \"@/predicates/is/isNonEmptyString\";\n\ntype CapitalizeFirstOptions = {\n  /** If true **(default)**, the rest of the string will be converted to lowercase after capitalizing the first letter.\n   *\n   * @default true\n   */\n  lowerCaseNextRest?: boolean;\n  /** If true, the string will trimmed, default: `false`.\n   *\n   * @default false\n   */\n  trim?: boolean;\n};\n\n/** ----------------------------------------------------------\n * * ***Utility: `capitalizeFirst`.***\n * ----------------------------------------------------------\n * **Capitalizes the first letter of a string, with optionally lowercases the rest and trims whitespace.**\n * @param {string | null | undefined} string - The string to be processed.\n * @param {CapitalizeFirstOptions} [options] - Options to control behavior.\n * @param {CapitalizeFirstOptions[\"lowerCaseNextRest\"]} [options.lowerCaseNextRest=true] - If true, lowercases the rest (next first letter), default: `true`.\n * @param {CapitalizeFirstOptions[\"trim\"]} [options.trim=false] - If true, trims the string before processing, default: `false`.\n * @returns {string} The processed string, returns `\"\"` if input is `null`, `undefined`, or `not a valid string`.\n * @example\n * ```ts\n * capitalizeFirst(\" hello WORLD \");\n * // ➔ \" Hello world\"\n * capitalizeFirst(\" hello WORLD \", { trim: true });\n * // ➔ \"Hello world\"\n * capitalizeFirst(\"FOO\", { lowerCaseNextRest: false });\n * // ➔ \"FOO\"\n * capitalizeFirst(\"   foo BAR   \", { trim: true, lowerCaseNextRest: false });\n * // ➔ \"Foo BAR\"\n * ```\n * #### ℹ️ If null, undefined, or not a valid string input, return `\"\"`.\n * ```ts\n * capitalizeFirst(123);\n * capitalizeFirst(null);\n * capitalizeFirst(undefined);\n * // ➔ \"\"\n * ```\n */\nexport const capitalizeFirst = (\n  string: string | null | undefined,\n  options: CapitalizeFirstOptions = {\n    lowerCaseNextRest: true,\n    trim: false\n  }\n): string => {\n  if (!isNonEmptyString(string)) return \"\";\n\n  if (!isPlainObject(options)) {\n    options = {};\n  }\n\n  const lowerCaseNextRest = options.lowerCaseNextRest !== false;\n  const trim = options.trim === true;\n\n  if (trim) string = string.trim();\n\n  return (\n    (string[0] ? string[0].toUpperCase() : \"\") +\n    (lowerCaseNextRest ? string.slice(1).toLowerCase() : string.slice(1))\n  );\n};\n","import { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { isNonEmptyString } from \"@/predicates/is/isNonEmptyString\";\n\ntype CapitalizeWordsOptions = {\n  /** If `true`, removes leading and trailing spaces, default `false`.\n   *\n   * @default false\n   */\n  trim?: boolean;\n  /** If `true`, collapses multiple spaces **between words** into a single space (while preserving leading/trailing spaces), default `false`.\n   *\n   * @default false\n   */\n  collapseSpaces?: boolean;\n};\n\n/** ----------------------------------------------------------\n * * ***Utility: `capitalizeWords`.***\n * ----------------------------------------------------------\n * **Capitalizes the first letter of each word in a string while converting the rest to lowercase.**\n * @param {string | null | undefined} value\n *  ***The input string to be processed.***\n *   - If `null` or `undefined`, returns an empty-string (`\"\"`).\n * @param {CapitalizeWordsOptions} [options]\n *  ***Optional settings to control the output:***\n *   - `trim`: If `true`, removes leading and trailing spaces, defaultValue: `false`.\n *   - `collapseSpaces`: If `true`, collapses multiple spaces **between words** into a single space (while preserving leading/trailing spaces), defaultValue: `false`.\n * @returns {string} A new string where each word starts with an uppercase letter\n * and the remaining letters are lowercase.\n *  - If `value` is `empty`, `null`, or `undefined`, returns an `empty-string`.\n * @example\n * ```ts\n * capitalizeWords(\"  hello   world  \");\n * // ➔ \"  Hello   World  \"\n * capitalizeWords(\"  hello   world  \", { trim: true });\n * // ➔ \"Hello   World\"\n * capitalizeWords(\"  hello   world  \", { collapseSpaces: true });\n * // ➔ \"  Hello World  \"\n * capitalizeWords(\"  hello   world  \", { trim: true, collapseSpaces: true });\n * // ➔ \"Hello World\"\n * ```\n * #### ℹ️ If null, undefined, or not a valid string input, return \"\".\n * ```ts\n * capitalizeWords(123);\n * capitalizeWords(null);\n * capitalizeWords(undefined);\n * // ➔ \"\"\n * ```\n */\nexport const capitalizeWords = (\n  value: string | null | undefined,\n  options: CapitalizeWordsOptions = {\n    collapseSpaces: false,\n    trim: false\n  }\n): string => {\n  if (!isNonEmptyString(value)) return \"\";\n\n  let result = value;\n\n  if (!isPlainObject(options)) {\n    options = {};\n  }\n\n  const collapseSpaces = options.collapseSpaces === true;\n  const trim = options.trim === true;\n\n  if (trim) {\n    result = result.trim();\n  }\n\n  if (collapseSpaces) {\n    const leadingSpaces = result.match(/^\\s*/)?.[0] ?? \"\";\n    const trailingSpaces = result.match(/\\s*$/)?.[0] ?? \"\";\n    result = result.trim().replace(/\\s+/g, \" \");\n    result = `${leadingSpaces}${result}${trailingSpaces}`;\n  }\n\n  return result\n    .toLowerCase()\n    .split(\" \")\n    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))\n    .join(\" \");\n};\n","import type { Extends } from \"@rzl-zone/ts-types-plus\";\nimport { isString } from \"@/predicates/is/isString\";\nimport { isEmptyString } from \"@/predicates/is/isEmptyString\";\n\n/** ----------------------------------------------------------\n * * ***Utility: `stripHtmlTags`.***\n * ----------------------------------------------------------\n * **This function removes valid HTML tags (including nested and self-closing ones)\n * by replacing them with spaces, then collapses multiple whitespaces into a single space.**\n * - **It handles the following cases:**\n *    - If the input is not a string (`null`, `undefined`, or any non-string), it is returned as undefined.\n *    - If the input is an empty or whitespace-only string, it returns an empty string (`\"\"`).\n *    - Otherwise, it returns the cleaned string with tags removed and normalized whitespace.\n * @template T - Input string type (string | null | undefined).\n * @param {string | null | undefined} input - A string potentially containing HTML tags.\n * @returns {string | undefined} Cleaned string if input is string, or original input otherwise.\n * @example\n * stripHtmlTags(\"<p>Hello</p>\");\n * // ➔ \"Hello\"\n * stripHtmlTags(\"<div><b>Bold</b> text</div>\");\n * // ➔ \"Bold text\"\n * stripHtmlTags(\"Line<br/>Break\");\n * // ➔ \"Line Break\"\n * stripHtmlTags(\"2 < 5 and 5 > 2\");\n * // ➔ \"2 < 5 and 5 > 2\"\n * stripHtmlTags(\"\");\n * // ➔ \"\"\n * stripHtmlTags(\"   \");\n * // ➔ \"\"\n * stripHtmlTags(null);\n * // ➔ undefined\n * stripHtmlTags(undefined);\n * // ➔ undefined\n */\nexport function stripHtmlTags(input: string): string;\nexport function stripHtmlTags<T>(\n  input: T\n): Extends<string, T> extends true ? string | undefined : undefined;\nexport function stripHtmlTags(input: unknown) {\n  if (!isString(input)) {\n    return undefined;\n  }\n\n  if (isEmptyString(input)) {\n    return \"\";\n  }\n\n  // return input.replace(/<[^>]*>/g, \"\");\n  const stripped = input.replace(/<\\/?[a-zA-Z][^<>]*\\/?>/g, \" \").trim();\n\n  const cleaned = stripped.replace(/\\s+/g, \" \").trim();\n\n  return cleaned;\n}\n","import { isNonEmptyString } from \"@/predicates/is/isNonEmptyString\";\n\n/** ----------------------------------------------------------\n * * ***Utility: `getInitialsName`.***\n * ----------------------------------------------------------\n * **Extracts initials from the given name string.**\n * - **Behavior:**\n *    - For names with two or more words, returns the first letter of the first and second words.\n *    - For a single word with 2+ characters, returns the first two letters.\n *    - For a single character, returns that character.\n *    - For `empty`, `null`, `undefined` or `whitespace-only input`, returns an empty string (`\"\"`).\n * @param {string | null | undefined} name - The name to extract initials from.\n * @returns {string} The extracted initials (e.g., \"JD\" for \"John Doe\").\n * @example\n * getInitialsName(\"Alice\");             // ➔ \"AL\"\n * getInitialsName(\"John Doe\");          // ➔ \"JD\"\n * getInitialsName(\" Bob Marley \");      // ➔ \"BM\"\n * getInitialsName(\"John Ronald Donal\"); // ➔ \"JR\"\n * getInitialsName(\"Lord John Doe Moe\"); // ➔ \"LJ\"\n * getInitialsName(\"X\");                 // ➔ \"X\"\n * getInitialsName(\"\");                  // ➔ \"\" (empty string)\n * getInitialsName(\"  \");                // ➔ \"\" (empty string)\n * getInitialsName(null);                // ➔ \"\" (null input)\n * getInitialsName(undefined);           // ➔ \"\" (undefined input)\n */\nexport const getInitialsName = (name: string | null | undefined): string => {\n  if (!isNonEmptyString(name)) return \"\"; // Handle empty string case\n\n  // Trim spaces and remove duplicate spaces\n  name = name.replace(/\\s+/g, \" \").trim();\n\n  const nameParts = name.split(\" \");\n\n  if (nameParts.length > 1) {\n    if (!(nameParts[0] && nameParts[1] && nameParts[1][0])) return \"\";\n\n    // First letter of first and second words\n    return (nameParts[0][0] + nameParts[1][0]).toUpperCase();\n  }\n\n  return name.length > 1\n    ? name.substring(0, 2).toUpperCase()\n    : // First two letters for single-word names\n      (name[0]?.toUpperCase() ?? \"\");\n};\n","import { isNumber } from \"@/predicates/is/isNumber\";\nimport { isString } from \"@/predicates/is/isString\";\nimport { getPreciseType } from \"@/predicates/type/getPreciseType\";\n\n/** ----------------------------------------------------------\n *  * ***Utility: `replaceAt`.***\n * ----------------------------------------------------------\n * **Replaces exactly one character at the specified index in the original string\n * with the provided `replaceTo` string.**\n * - **Behavior:**\n *    - If `replaceTo` has more than one character,\n * the result will expand accordingly.\n * @param {number} index - The starting index where the replacement should occur.\n * @param {string} originalString - The original string to modify.\n * @param {string} replaceTo - The string to insert at the specified index.\n * @returns {string} The modified string with the replacement applied.\n * @example\n * replaceAt(3, \"hello\", \"X\");\n * // ➔ \"helXo\"\n * replaceAt(1, \"world\", \"AB\");\n * // ➔ \"wABrld\"\n * replaceAt(0, \"cat\", \"br\");\n * // ➔ \"brat\"\n * replaceAt(2, \"12345\", \"-\");\n * // ➔ \"12-45\"\n * replaceAt(4, \"ABCDE\", \"Z\");\n * // ➔ \"ABCDZ\"\n * // ❌ Examples that throw:\n * replaceAt(10, \"short\", \"X\");\n * // ➔ ❌ RangeError: First parameter (`index`) is out of range from second parameter `originalString`.\n * replaceAt(-1, \"test\", \"X\");\n * // ➔ ❌ RangeError: First parameter (`index`) is out of range from second parameter `originalString`.\n * replaceAt(\"1\", \"test\", \"X\");\n * // ➔ ❌ TypeError: First parameter `index` must be of type `number`, second parameter `originalString` and third parameter `replaceTo` must be of type `string`, but received: \"['index': `string`,...].\"\n * replaceAt(2, null, \"X\");\n * // ➔ ❌ TypeError: First parameter `index` must be of type `number`, second parameter `originalString` and third parameter `replaceTo` must be of type `string`, but received: \"['index': `string`,...].\"\n */\nexport const replaceAt = (\n  index: number,\n  originalString: string,\n  replaceTo: string\n): string => {\n  if (!isNumber(index) || !isString(replaceTo) || !isString(originalString)) {\n    throw new TypeError(\n      `First parameter (\\`index\\`) must be of type \\`number\\`, second parameter (\\`originalString\\`) and third parameter (\\`replaceTo\\`) must be of type \\`string\\`, but received: \"['index': \\`${getPreciseType(\n        index\n      )}\\`, 'originalString': \\`${getPreciseType(\n        originalString\n      )}\\`, 'replaceTo': \\`${getPreciseType(replaceTo)}\\`]\".`\n    );\n  }\n\n  // Handle edge cases\n  if (index < 0 || index >= originalString.length) {\n    throw new RangeError(\n      \"First parameter (`index`) is out of range from second parameter (`originalString`).\"\n    );\n  }\n\n  return (\n    originalString.slice(0, index) + // Extract before the index\n    replaceTo + // Insert replacement\n    originalString.slice(index + 1) // Extract after replacement\n  );\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,MAAa,mBACX,QACA,UAAkC;CAChC,mBAAmB;CACnB,MAAM;CACP,KACU;CACX,IAAI,CAACA,yCAAiB,OAAO,EAAE,OAAO;CAEtC,IAAI,CAACC,sCAAc,QAAQ,EACzB,UAAU,EAAE;CAGd,MAAM,oBAAoB,QAAQ,sBAAsB;CAGxD,IAFa,QAAQ,SAAS,MAEpB,SAAS,OAAO,MAAM;CAEhC,QACG,OAAO,KAAK,OAAO,GAAG,aAAa,GAAG,OACtC,oBAAoB,OAAO,MAAM,EAAE,CAAC,aAAa,GAAG,OAAO,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACfxE,MAAa,mBACX,OACA,UAAkC;CAChC,gBAAgB;CAChB,MAAM;CACP,KACU;CACX,IAAI,CAACC,yCAAiB,MAAM,EAAE,OAAO;CAErC,IAAI,SAAS;CAEb,IAAI,CAACC,sCAAc,QAAQ,EACzB,UAAU,EAAE;CAGd,MAAM,iBAAiB,QAAQ,mBAAmB;CAGlD,IAFa,QAAQ,SAAS,MAG5B,SAAS,OAAO,MAAM;CAGxB,IAAI,gBAAgB;EAClB,MAAM,gBAAgB,OAAO,MAAM,OAAO,GAAG,MAAM;EACnD,MAAM,iBAAiB,OAAO,MAAM,OAAO,GAAG,MAAM;EACpD,SAAS,OAAO,MAAM,CAAC,QAAQ,QAAQ,IAAI;EAC3C,SAAS,GAAG,gBAAgB,SAAS;;CAGvC,OAAO,OACJ,aAAa,CACb,MAAM,IAAI,CACV,KAAK,SAAS,KAAK,OAAO,EAAE,CAAC,aAAa,GAAG,KAAK,MAAM,EAAE,CAAC,CAC3D,KAAK,IAAI;;;;;AC5Cd,SAAgB,cAAc,OAAgB;CAC5C,IAAI,CAACC,iCAAS,MAAM,EAClB;CAGF,IAAIC,oCAAc,MAAM,EACtB,OAAO;CAQT,OAJiB,MAAM,QAAQ,2BAA2B,IAAI,CAAC,MAEvC,CAAC,QAAQ,QAAQ,IAAI,CAAC,MAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC3BhB,MAAa,mBAAmB,SAA4C;CAC1E,IAAI,CAACC,yCAAiB,KAAK,EAAE,OAAO;CAGpC,OAAO,KAAK,QAAQ,QAAQ,IAAI,CAAC,MAAM;CAEvC,MAAM,YAAY,KAAK,MAAM,IAAI;CAEjC,IAAI,UAAU,SAAS,GAAG;EACxB,IAAI,EAAE,UAAU,MAAM,UAAU,MAAM,UAAU,GAAG,KAAK,OAAO;EAG/D,QAAQ,UAAU,GAAG,KAAK,UAAU,GAAG,IAAI,aAAa;;CAG1D,OAAO,KAAK,SAAS,IACjB,KAAK,UAAU,GAAG,EAAE,CAAC,aAAa,GAEjC,KAAK,IAAI,aAAa,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACNjC,MAAa,aACX,OACA,gBACA,cACW;CACX,IAAI,CAACC,iCAAS,MAAM,IAAI,CAACC,iCAAS,UAAU,IAAI,CAACA,iCAAS,eAAe,EACvE,MAAM,IAAI,UACR,4LAA4LC,uCAC1L,MACD,CAAC,0BAA0BA,uCAC1B,eACD,CAAC,qBAAqBA,uCAAe,UAAU,CAAC,OAClD;CAIH,IAAI,QAAQ,KAAK,SAAS,eAAe,QACvC,MAAM,IAAI,WACR,sFACD;CAGH,OACE,eAAe,MAAM,GAAG,MAAM,GAC9B,YACA,eAAe,MAAM,QAAQ,EAAE"}

package/dist/strings/index.d.cts

@@ -0,0 +1,12 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+
+import { a as normalizeString, c as toPascalCaseSpace, d as toKebabCase, f as toDotCase, g as capitalizeFirst, h as capitalizeWords, i as removeSpaces, l as toPascalCase, m as slugify, n as getInitialsName, o as normalizeSpaces, p as toCamelCase, r as stripHtmlTags, s as toSnakeCase, t as replaceAt, u as toLowerCase } from "../index-DsGxO31H.cjs";
+export { capitalizeFirst, capitalizeWords, getInitialsName, normalizeSpaces, normalizeString, removeSpaces, replaceAt, slugify, stripHtmlTags, toCamelCase, toDotCase, toKebabCase, toLowerCase, toPascalCase, toPascalCaseSpace, toSnakeCase };