@rzl-zone/utils-js 3.11.1 → 3.12.1-beta.0

package/dist/operations/index.js

@@ -1,18 +1,62 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.11.1.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
-export { findDuplicates, omitKeys, omitKeysDeep } from '../chunk-LJHPTLWB.js';
-import '../chunk-BOYP3ARU.js';
-import '../chunk-GXKQ3LHF.js';
-import '../chunk-GOFINGT6.js';
-import '../chunk-RZOGBYIS.js';
-import '../chunk-YWHHVDT4.js';
-import '../chunk-AXDYWO67.js';
-import '../chunk-QNKGP5DY.js';
-import '../chunk-MSUW5VHZ.js';
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.0`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+import { A as isPlainObject, D as isNaN, M as isArray, S as isUndefined, p as isNonEmptyArray, x as isObjectOrArray } from "../assertIsBoolean-BlBct0Fc.js";
+import { t as assertIsArray } from "../assertIsArray-BfAbIUfa.js";
+import { n as isEmptyArray } from "../isEmptyObject-DeLVIJpl.js";
+import { t as safeStableStringify } from "../safeStableStringify-BNh3D0K0.js";
+import { t as isEqual } from "../isEqual-DhyP8fB_.js";
+import { t as safeJsonParse } from "../safeJsonParse-CXruaP0p.js";
+const findDuplicates = (values) => {
+	assertIsArray(values, { message: ({ currentType, validType }) => `First parameter (\`values\`) must be of type \`${validType}\` (array literal or instance), but received: \`${currentType}\`.` });
+	const duplicates = [];
+	values.forEach((item, index) => {
+		for (let i = index + 1; i < values.length; i++) if (isEqual(item, values[i])) {
+			if (!duplicates.some((dup) => isEqual(dup, item))) duplicates.push(item);
+			break;
+		}
+	});
+	return duplicates;
+};
+const omitKeys = (object, keysToOmit) => {
+	if (!isPlainObject(object)) return {};
+	assertIsArray(keysToOmit, { message: ({ currentType, validType }) => `Second parameter (\`keysToOmit\`) must be of type \`${validType}\` (array literal or instance), but received: \`${currentType}\`.` });
+	const duplicates = findDuplicates(keysToOmit);
+	if (duplicates.length > 0) throw new Error(`Function "omitKeys" Error: Duplicate keys detected - \`${duplicates}\``);
+	return Object.fromEntries(Object.entries(object).filter(([key]) => !keysToOmit.includes(key)));
+};
+const omitKeysDeep = (object, keysToOmit) => {
+	if (!isPlainObject(object)) return {};
+	assertIsArray(keysToOmit, { message: ({ currentType, validType }) => `Second parameter (\`keysToOmit\`) must be of type \`${validType}\` (array literal or instance), but received: \`${currentType}\`.` });
+	const duplicates = findDuplicates(keysToOmit);
+	if (isNonEmptyArray(duplicates)) throw new Error(`Function "omitKeysDeep" Error: Duplicate keys detected - \`${safeStableStringify(duplicates, { keepUndefined: true })}\`.`);
+	const omitAtPath = (obj, pathParts) => {
+		if (!isObjectOrArray(obj)) return obj;
+		const [current, ...rest] = pathParts;
+		if (isEmptyArray(rest)) if (isArray(obj)) {
+			const index = parseInt(current);
+			if (!isNaN(index) && index in obj) obj.splice(index, 1);
+		} else delete obj[current];
+		else {
+			const next = obj[current];
+			if (isObjectOrArray(next)) obj[current] = omitAtPath(next, rest);
+		}
+		return obj;
+	};
+	const deepRemoveEmptyObjects = (obj) => {
+		if (isArray(obj)) return obj.map(deepRemoveEmptyObjects).filter((item) => !(isObjectOrArray(item) && Object.keys(item).length === 0));
+		if (isObjectOrArray(obj)) return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, deepRemoveEmptyObjects(v)]).filter(([, v]) => !isUndefined(v) && !(isObjectOrArray(v) && Object.keys(v).length === 0)));
+		return obj;
+	};
+	const result = safeJsonParse(safeStableStringify(object));
+	for (const key of keysToOmit) omitAtPath(result, key.split("."));
+	return deepRemoveEmptyObjects(result);
+};
+export { findDuplicates, omitKeys, omitKeysDeep };
+//# sourceMappingURL=index.js.map

package/dist/operations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/operations/findDuplicates.ts","../../src/operations/omitKeys.ts","../../src/operations/omitKeysDeep.ts"],"sourcesContent":["import { isEqual } from \"@/predicates/is/isEqual\";\nimport { assertIsArray } from \"@/assertions/objects/assertIsArray\";\n\n/** ----------------------------------------------------------------------\n * * ***Utility: `findDuplicates`.***\n * ----------------------------------------------------------------------\n * **Finds duplicate values in an array by deep equality comparison.**\n * - **Behavior:**\n *    - Uses ***`isEqual` utility function*** to compare elements\n *      (handles objects, arrays, dates, NaN, etc.).\n *    - Returns a new array containing only the *first occurrences* of duplicated values.\n *    - Does **not mutate** the original array.\n *    - Throws ***{@link TypeError | `TypeError`}*** if input is not an array.\n * @template T Type of elements in the input array.\n * @param {T[]} values - The array to check for duplicates.\n * @returns {T[]} An array of the duplicate values found in the input,\n *                preserving order of their first duplicate appearance.\n * @throws **{@link TypeError | `TypeError`}** if the provided `values` argument is not an array.\n * @example\n * findDuplicates([1, 2, 2, 3, 4, 4]);\n * // ➔ [2, 4]\n * findDuplicates([\"apple\", \"banana\", \"apple\", \"orange\"]);\n * // ➔ [\"apple\"]\n * findDuplicates([{ a: 1 }, { a: 1 }, { a: 2 }]);\n * // ➔ [{ a: 1 }]\n * findDuplicates([NaN, NaN, 1]);\n * // ➔ [NaN]\n * findDuplicates([true, false, true]);\n * // ➔ [true]\n * findDuplicates([1, 2, 3]);\n * // ➔ []\n */\nexport const findDuplicates = <T>(values: T[]): T[] => {\n  assertIsArray(values, {\n    message: ({ currentType, validType }) =>\n      `First parameter (\\`values\\`) must be of type \\`${validType}\\` (array literal or instance), but received: \\`${currentType}\\`.`\n  });\n\n  const duplicates: T[] = [];\n  values.forEach((item, index) => {\n    for (let i = index + 1; i < values.length; i++) {\n      if (isEqual(item, values[i])) {\n        if (!duplicates.some((dup) => isEqual(dup, item))) {\n          duplicates.push(item);\n        }\n        break;\n      }\n    }\n  });\n\n  return duplicates;\n};\n","import { findDuplicates } from \"./findDuplicates\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { assertIsArray } from \"@/assertions/objects/assertIsArray\";\n\n/** --------------------------------\n * * ***Utility: `omitKeys`.***\n * --------------------------------\n * **This function creates a shallow copy of the given object omitting the\n *  specified keys.**\n * - **Behavior:**\n *    - It will return a new object without mutating the original.\n *    - It also validates that ***`keysToOmit`*** does not contain duplicate keys.\n * - **ℹ️ Internally:**\n *    - It uses ***`isEqual`*** to check for duplicates in\n *      the ***`keysToOmit`*** array.\n * @template I The type of the input object.\n * @template K The keys to omit from the object.\n * @param {I} object - The source object to omit keys from.\n * @param {K[]} keysToOmit - An array of keys to exclude from the returned object.\n * @returns {Omit<I, K>} A new object without the specified keys.\n * @throws **{@link TypeError | `TypeError`}** if `keysToOmit` is not an array.\n * @throws **{@link Error | `Error`}** if duplicate keys are found in `keysToOmit`.\n * @example\n * omitKeys({ a: 1, b: 2, c: 3 }, [\"b\", \"c\"]);\n * //➔ { a: 1 }\n * omitKeys({ name: \"John\", age: 30 }, [\"age\"]);\n * //➔ { name: \"John\" }\n * omitKeys({ a: 1, b: 2 }, []);\n * //➔ { a: 1, b: 2 } (no changes)\n */\nexport const omitKeys = <I extends Record<string, unknown>, K extends keyof I>(\n  object: I,\n  keysToOmit: K[]\n): Omit<I, K> => {\n  if (!isPlainObject(object)) return {} as Omit<I, K>;\n\n  assertIsArray(keysToOmit, {\n    message: ({ currentType, validType }) =>\n      `Second parameter (\\`keysToOmit\\`) must be of type \\`${validType}\\` (array literal or instance), but received: \\`${currentType}\\`.`\n  });\n\n  // Check for duplicate keys\n  const duplicates = findDuplicates(keysToOmit);\n  if (duplicates.length > 0) {\n    throw new Error(\n      `Function \"omitKeys\" Error: Duplicate keys detected - \\`${duplicates}\\``\n    );\n  }\n\n  // Remove specified keys\n  return Object.fromEntries(\n    Object.entries(object).filter(([key]) => !keysToOmit.includes(key as K))\n  ) as Omit<I, K>;\n};\n","import type { NumberRangeUnion } from \"@rzl-zone/ts-types-plus\";\n\nimport { findDuplicates } from \"./findDuplicates\";\n\nimport { isNaN } from \"@/predicates/is/isNaN\";\nimport { isArray } from \"@/predicates/is/isArray\";\nimport { isUndefined } from \"@/predicates/is/isUndefined\";\nimport { isEmptyArray } from \"@/predicates/is/isEmptyArray\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { isNonEmptyArray } from \"@/predicates/is/isNonEmptyArray\";\nimport { isObjectOrArray } from \"@/predicates/is/isObjectOrArray\";\n\nimport { assertIsArray } from \"@/assertions/objects/assertIsArray\";\n\nimport { safeJsonParse } from \"@/conversions/json/safeJsonParse\";\nimport { safeStableStringify } from \"@/conversions/stringify/safeStableStringify\";\n\ntype IndexArray = NumberRangeUnion<0, 30>;\ntype DotPath<T, Prev extends string = \"\"> =\n  T extends Array<infer U>\n    ? DotPath<U, `${Prev}${Prev extends \"\" ? \"\" : \".\"}${IndexArray}`>\n    : T extends object\n      ? {\n          [K in keyof T & string]:\n            | `${Prev}${Prev extends \"\" ? \"\" : \".\"}${K}`\n            | DotPath<T[K], `${Prev}${Prev extends \"\" ? \"\" : \".\"}${K}`>;\n        }[keyof T & string]\n      : never;\n\n/** ------------------------------------------------------\n * * ***Utility: `omitKeysDeep`.***\n * ------------------------------------------------------\n * **Recursively omits properties from an object using dot notation paths.**\n * - **Behavior:**\n *    - Removes resulting empty objects (`{}`) and arrays (`[]`), cascading upwards\n *      to remove empty parents until root if needed.\n * - **⚠️ Be careful:**\n *    - If after omission an object or array becomes empty, it will be removed entirely\n *      including all the way up to the root if necessary, resulting in `{}`.\n * - **ℹ️ Note:**\n *    - For array indices, TypeScript autocomplete only suggests `0`–`30`\n *      (to prevent editor lag on large unions).\n *      However, higher indices are still fully supported at runtime — you can\n *      manually type `\"arr.99.key\"` and it will work the same.\n * @template I - Type of the input object\n * @param {I} object\n *  The object to process, should be a plain nested object or array structure.\n * @param {DotPath<I>[]} keysToOmit\n *  An array of string paths in dot notation indicating the properties to remove, paths\n *  can include numeric indices to target array elements, e.g. `\"arr.0.x\"` to\n *  remove `x` from the first object inside the `arr` array.\n * @returns {Partial<I>}\n *  A new deeply cloned object with the specified keys omitted, with resulting\n *  empty objects or arrays fully removed (even if it collapses to `{}`).\n * @throws **{@link TypeError | `TypeError`}** if `keysToOmit` is not an array.\n * @throws **{@link Error | `Error`}** if `keysToOmit` contains duplicate paths.\n * @example\n * omitKeysDeep({ arr: [{ a: 1 }] }, [\"arr.0.a\"]);\n * // ➔ {} (array becomes empty and removed)\n * omitKeysDeep({ a: { b: { c: 1 }, d: 2 }, e: 3 }, [\"a.b.c\"]);\n * // ➔ { a: { d: 2 }, e: 3 }\n * omitKeysDeep({ a: [{ b: 1 }, { c: 2 }] }, [\"a.0.b\"]);\n * // ➔ { a: [{ c: 2 }] }\n * omitKeysDeep({ a: [{ b: 1 }] }, [\"a.0.b\"]);\n * // ➔ {} (array becomes empty and removed)\n * omitKeysDeep({ complex: [{ deep: [{ x: 1, y: 2 }] }] }, [\"complex.0.deep.0.x\"]);\n * // ➔ { complex: [{ deep: [{ y: 2 }] }] }\n * omitKeysDeep({ complex: [{ deep: [{ x: 1 }] }] }, [\"complex.0.deep.0.x\"]);\n * // ➔ {} (deep chain emptied and collapsed)\n * omitKeysDeep({ data: [[{ foo: 1, bar: 2 }]] }, [\"data.0.0.foo\"]);\n * // ➔ { data: [[{ bar: 2 }]] }\n * omitKeysDeep({ data: [[{ foo: 1 }]] }, [\"data.0.0.foo\"]);\n * // ➔ {} (nested arrays emptied completely)\n * omitKeysDeep({ x: [{ y: [{ z: 1 }, { w: 2 }] }] }, [\"x.0.y.0.z\"]);\n * // ➔ { x: [{ y: [{ w: 2 }] }] }\n * omitKeysDeep({ x: [{ y: [{ z: 1 }] }] }, [\"x.0.y.0.z\"]);\n * // ➔ {} (entire nested arrays removed)\n * omitKeysDeep({ p: { q: { r: 5 } }, s: 6 }, [\"p.q.r\"]);\n * // ➔ { s: 6 } (`p` removed because it becomes empty)\n * omitKeysDeep({ arr: [{ a: 1, b: 2 }, { c: 3 }] }, [\"arr.0.a\"]);\n * // ➔ { arr: [{ b: 2 }, { c: 3 }] }\n * omitKeysDeep({ root: [{ sub: [{ leaf: 10 }] }] }, [\"root.0.sub.0.leaf\"]);\n * // ➔ {} (deep nested arrays emptied to root)\n * omitKeysDeep({ meta: { tags: [\"x\", \"y\"], count: 2 } }, [\"meta.count\"]);\n * // ➔ { meta: { tags: [\"x\", \"y\"] } }\n * omitKeysDeep({ arr: [[{ a: 1 }, { b: 2 }]] }, [\"arr.0.0.a\"]);\n * // ➔ { arr: [[{ b: 2 }]] }\n * omitKeysDeep({ arr: [[{ a: 1 }]] }, [\"arr.0.0.a\"]);\n * // ➔ {} (double nested emptied)\n * omitKeysDeep({ nested: [{ list: [{ id: 1, val: 2 }] }] }, [\"nested.0.list.0.val\"]);\n * // ➔ { nested: [{ list: [{ id: 1 }] }] }\n * omitKeysDeep({ nested: [{ list: [{ id: 1 }] }] }, [\"nested.0.list.0.id\"]);\n * // ➔ {} (full collapse to empty)\n * omitKeysDeep({ mixed: { a: [1, 2, 3], b: { c: 4 } } }, [\"mixed.b.c\"]);\n * // ➔ { mixed: { a: [1, 2, 3] } }\n */\nexport const omitKeysDeep = <I extends Record<string, unknown>>(\n  object: I,\n  keysToOmit: DotPath<I>[]\n): Partial<I> => {\n  if (!isPlainObject(object)) return {} as Partial<I>;\n\n  assertIsArray(keysToOmit, {\n    message: ({ currentType, validType }) =>\n      `Second parameter (\\`keysToOmit\\`) must be of type \\`${validType}\\` (array literal or instance), but received: \\`${currentType}\\`.`\n  });\n\n  const duplicates = findDuplicates(keysToOmit);\n  if (isNonEmptyArray(duplicates)) {\n    throw new Error(\n      `Function \"omitKeysDeep\" Error: Duplicate keys detected - \\`${safeStableStringify(\n        duplicates,\n        {\n          keepUndefined: true\n        }\n      )}\\`.`\n    );\n  }\n\n  const omitAtPath = (obj: unknown, pathParts: string[]) => {\n    if (!isObjectOrArray(obj)) return obj;\n\n    const [current, ...rest] = pathParts;\n\n    if (isEmptyArray(rest)) {\n      if (isArray(obj)) {\n        // Support numeric index\n        const index = parseInt(current);\n        if (!isNaN(index) && index in obj) {\n          obj.splice(index, 1);\n        }\n      } else {\n        delete obj[current];\n      }\n    } else {\n      const next = obj[current];\n      if (isObjectOrArray(next)) {\n        obj[current] = omitAtPath(next, rest);\n      }\n    }\n    return obj;\n  };\n\n  const deepRemoveEmptyObjects = (obj: unknown): unknown => {\n    if (isArray(obj)) {\n      return obj\n        .map(deepRemoveEmptyObjects)\n        .filter(\n          (item) => !(isObjectOrArray(item) && Object.keys(item).length === 0)\n        );\n    }\n    if (isObjectOrArray(obj)) {\n      const cleaned = Object.fromEntries(\n        Object.entries(obj)\n          .map(([k, v]) => [k, deepRemoveEmptyObjects(v)])\n          .filter(\n            ([, v]) =>\n              !isUndefined(v) &&\n              !(isObjectOrArray(v) && Object.keys(v).length === 0)\n          )\n      );\n      return cleaned;\n    }\n    return obj;\n  };\n\n  const result = safeJsonParse(safeStableStringify(object)); // clone deep to avoid mutating original\n  for (const key of keysToOmit) {\n    const parts = key.split(\".\");\n    omitAtPath(result, parts);\n  }\n\n  return deepRemoveEmptyObjects(result) as Partial<I>;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAa,kBAAqB,WAAqB;CACrD,cAAc,QAAQ,EACpB,UAAU,EAAE,aAAa,gBACvB,kDAAkD,UAAU,kDAAkD,YAAY,MAC7H,CAAC;CAEF,MAAM,aAAkB,EAAE;CAC1B,OAAO,SAAS,MAAM,UAAU;EAC9B,KAAK,IAAI,IAAI,QAAQ,GAAG,IAAI,OAAO,QAAQ,KACzC,IAAI,QAAQ,MAAM,OAAO,GAAG,EAAE;GAC5B,IAAI,CAAC,WAAW,MAAM,QAAQ,QAAQ,KAAK,KAAK,CAAC,EAC/C,WAAW,KAAK,KAAK;GAEvB;;GAGJ;CAEF,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACpBT,MAAa,YACX,QACA,eACe;CACf,IAAI,CAAC,cAAc,OAAO,EAAE,OAAO,EAAE;CAErC,cAAc,YAAY,EACxB,UAAU,EAAE,aAAa,gBACvB,uDAAuD,UAAU,kDAAkD,YAAY,MAClI,CAAC;CAGF,MAAM,aAAa,eAAe,WAAW;CAC7C,IAAI,WAAW,SAAS,GACtB,MAAM,IAAI,MACR,0DAA0D,WAAW,IACtE;CAIH,OAAO,OAAO,YACZ,OAAO,QAAQ,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,SAAS,IAAS,CAAC,CACzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC4CH,MAAa,gBACX,QACA,eACe;CACf,IAAI,CAAC,cAAc,OAAO,EAAE,OAAO,EAAE;CAErC,cAAc,YAAY,EACxB,UAAU,EAAE,aAAa,gBACvB,uDAAuD,UAAU,kDAAkD,YAAY,MAClI,CAAC;CAEF,MAAM,aAAa,eAAe,WAAW;CAC7C,IAAI,gBAAgB,WAAW,EAC7B,MAAM,IAAI,MACR,8DAA8D,oBAC5D,YACA,EACE,eAAe,MAChB,CACF,CAAC,KACH;CAGH,MAAM,cAAc,KAAc,cAAwB;EACxD,IAAI,CAAC,gBAAgB,IAAI,EAAE,OAAO;EAElC,MAAM,CAAC,SAAS,GAAG,QAAQ;EAE3B,IAAI,aAAa,KAAK,EACpB,IAAI,QAAQ,IAAI,EAAE;GAEhB,MAAM,QAAQ,SAAS,QAAQ;GAC/B,IAAI,CAAC,MAAM,MAAM,IAAI,SAAS,KAC5B,IAAI,OAAO,OAAO,EAAE;SAGtB,OAAO,IAAI;OAER;GACL,MAAM,OAAO,IAAI;GACjB,IAAI,gBAAgB,KAAK,EACvB,IAAI,WAAW,WAAW,MAAM,KAAK;;EAGzC,OAAO;;CAGT,MAAM,0BAA0B,QAA0B;EACxD,IAAI,QAAQ,IAAI,EACd,OAAO,IACJ,IAAI,uBAAuB,CAC3B,QACE,SAAS,EAAE,gBAAgB,KAAK,IAAI,OAAO,KAAK,KAAK,CAAC,WAAW,GACnE;EAEL,IAAI,gBAAgB,IAAI,EAUtB,OATgB,OAAO,YACrB,OAAO,QAAQ,IAAI,CAChB,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,uBAAuB,EAAE,CAAC,CAAC,CAC/C,QACE,GAAG,OACF,CAAC,YAAY,EAAE,IACf,EAAE,gBAAgB,EAAE,IAAI,OAAO,KAAK,EAAE,CAAC,WAAW,GACrD,CAES;EAEhB,OAAO;;CAGT,MAAM,SAAS,cAAc,oBAAoB,OAAO,CAAC;CACzD,KAAK,MAAM,OAAO,YAEhB,WAAW,QADG,IAAI,MAAM,IACA,CAAC;CAG3B,OAAO,uBAAuB,OAAO"}

package/dist/parsers/index.cjs

@@ -1,20 +1,13 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.11.1.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
-'use strict';
-
-var chunkNLZLXWAU_cjs = require('../chunk-NLZLXWAU.cjs');
-require('../chunk-QYI2VJLS.cjs');
-require('../chunk-WXFTVXBF.cjs');
-require('../chunk-SYHPSOUU.cjs');
-
-Object.defineProperty(exports, "extractFileName", {
-  enumerable: true,
-  get: function () { return chunkNLZLXWAU_cjs.extractFileName; }
-});
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.0`
+*  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_parsers = require('../parsers-DXtpsDyj.cjs');
+exports.extractFileName = require_parsers.extractFileName;

package/dist/parsers/index.d.cts

@@ -0,0 +1,239 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.0`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+type ExtractFileNameOptions = {
+  /** ----------------------------------------------------------
+   * * ***Indicates whether the input should be treated as a potential domain string.***
+   * ----------------------------------------------------------
+   *
+   * - Behavior when `true`:
+   *    - The `domainName` option is required and must be a string and non-empty string.
+   *      If `domainName` is `undefined`, `null`, or an empty string, a `TypeError` will be thrown.
+   *    - The `domainName` is used to determine if the input is a domain-only string.
+   *    - Returns `null` if the input exactly matches `domainName` or any of its subdomains **and** has no additional path or filename.
+   *    - If the input does not match `domainName` or its subdomains, it will be processed as a regular file-like name.
+   *    - Supports **Unicode/IDN domains** (e.g., `tést-ドメイン.com`) and **ASCII filenames**, mixed safely.
+   *
+   * @default false
+   */
+  domainAware?: boolean;
+  /** ----------------------------------------------------------
+   * * ***The base domain name used for comparison (e.g., `"example.com"`).***
+   * ----------------------------------------------------------
+   *
+   * - Required when `domainAware` is `true`.
+   *    - Helps differentiate between a domain-only input (ignored) and a standalone file-like string (processed normally).
+   *    - Must be a string and non-empty string. Invalid values (`undefined`, `null`, or empty string) will trigger a `TypeError`.
+   *    - Works with both **ASCII domains** and **Unicode/IDN domains**.
+   *    - Example:
+   *      ```ts   *
+   *      // ASCII domain + ASCII filename
+   *      extractFileName("resume.com", {
+   *        domainAware: true,
+   *        domainName: "example.com"
+   *      });
+   *      // ➔ "resume"
+   *      extractFileName("example.com", {
+   *        domainAware: true,
+   *        domainName: "example.com"
+   *      });
+   *      // ➔ null (because input is treated as domain-name)
+   *
+   *      // Unicode domain + ASCII filename
+   *      extractFileName("tést-ドメイン.com/file.txt", {
+   *        domainAware: true,
+   *        domainName: "ドメイン.com"
+   *      });
+   *      // ➔ "file"
+   *
+   *      // Unicode domain + Unicode filename
+   *      extractFileName("tést-ドメイン.com/ファイル名.pdf", {
+   *        domainAware: true,
+   *        domainName: "ドメイン.com"
+   *      });
+   *      // ➔ "ファイル名"
+   *
+   *      // Invalid domainName, will throw TypeError
+   *      extractFileName("resume.com", {
+   *        domainAware: true,
+   *        domainName: ""
+   *      });
+   *      // ➔ TypeError
+   *      ```
+   *
+   * @default undefined
+   */
+  domainName?: string;
+};
+/** ----------------------------------------------------------
+ * * ***Utility: `extractFileName`.***
+ * ----------------------------------------------------------
+ *
+ * **Extracts the **clean base filename** from nearly any input string, including URLs, local file paths,
+ * UNC paths, and plain filenames.**
+ *
+ * - It automatically safely handles extracts the **base file name** (without extension) from:
+ *    - File system paths (Windows, Unix, UNC)
+ *    - Protocols like http, https, ftp, file, mailto, or custom schemes
+ *    - Percent-encoded, Unicode, and emoji characters
+ *    - Dotfiles, reserved OS names, multi-part extensions
+ *    - Data URIs
+ *    - Optional domain-aware mode to ignore domain-only inputs
+ *    - Plain filenames
+ *
+ * - Full support for:
+ *    - Unicode, emoji, percent-encoding
+ *    - Dotfiles (e.g., `.env`, `.gitignore`)
+ *    - Reserved/OS-protected filenames:
+ *      `CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`, `LPT1`–`LPT9`
+ *    - Known multi-part extensions:
+ *      `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.tar.lz`, `.tar.zst`, `.min.js`, `.js.map`, `.log.gz`, `.sql.gz`,
+ *      `.backup.tar`, etc.
+ *    - Data URIs (`data:[mime];base64,...` ➔ payload string)
+ *    - Domain-aware mode (optional)
+ *
+ * ----------------------------------------------------------
+ * - **Behavior / Features**
+ *    - Strips **known extensions**, including multi-part and common double/triple extensions.
+ *    - Leaves unknown/custom extensions intact.
+ *    - Preserves **dotfiles** as-is (leading dot preserved).
+ *    - Returns `null` if:
+ *      - input is `null`, `undefined`, or not a string
+ *      - input is empty, whitespace-only, or only slashes
+ *      - input represents a folder path (trailing slash/backslash, drive/folder only)
+ *    - input is a **domain-only string** in domain-aware mode
+ *    - Normalizes Windows-style backslashes (`\`) internally as `/`.
+ *    - Supports UNC paths, mixed slashes, and Windows drive letters safely.
+ *    - Handles URLs:
+ *      - Ignores query strings (`?v=1.2.3`) and hash fragments (`#section`)
+ *      - Decodes percent-encoded filenames (`my%20file.txt` ➔ `my file.txt`)
+ *      - Supports protocol-relative URLs (`//cdn.example.com/file.jpg`)
+ *      - Supports uncommon/custom protocols (`ftp://`, `file://`, `mailto:`, etc.)
+ *    - Handles **multiple dots**, **trailing dots**, **triple or more extensions**
+ *    - Supports filenames on mixed Unicode/ASCII domains:
+ *      - Domain names can include Unicode characters (IDN / punycode)
+ *      - Filenames may contain ASCII, Unicode, and emoji characters
+ *      - Works correctly when domain is Unicode and filename is ASCII, or vice versa
+ *    - Supports extremely long filenames safely (up to OS limits)
+ *    - Domain-aware mode (`domainAware: true` + `domainName`):
+ *      - Parameter `domainName` must be a string and non-empty string; otherwise a TypeError is thrown.
+ *      - Returns `null` if input equals `domainName` or any subdomain with no file path
+ *      - Extracts filename normally if path/file exists on domain or other domain
+ *    - Safe in Node.js and browsers
+ *
+ * ----------------------------------------------------------
+ * @param {string | null | undefined} input
+ *   URL, file path, or plain filename to extract from.
+ *
+ * @param {ExtractFileNameOptions} [options]
+ *   Optional configuration:
+ *   - `domainAware?: boolean` – treat input as a domain string. Requires `domainName` to be a string and non-empty string; otherwise, a TypeError is thrown.
+ *   - `domainName?: string` – base domain for comparison eg (`example.com`), required when `domainAware` is true.
+ *
+ * @returns {string | null}
+ *   - Base filename without known extensions
+ *   - Original filename if extension unknown
+ *   - `null` for invalid inputs, folder paths, or domain-only strings
+ *
+ * ----------------------------------------------------------
+ * @example
+ * ```ts
+ * // Basic files
+ * extractFileName("document.pdf"); // ➔ "document"
+ * extractFileName("/files/archive.tar.gz"); // ➔ "archive"
+ * extractFileName("C:\\path\\file.txt"); // ➔ "file"
+ * extractFileName(".env"); // ➔ ".env"
+ * extractFileName("folder/"); // ➔ null
+ *
+ * // Not a file
+ * extractFileName("not-file"); // ➔ null
+ * extractFileName("not-file/"); // ➔ null
+ * extractFileName("/not-file/"); // ➔ null
+ * extractFileName("/not-file"); // ➔ null
+ *
+ * // URLs with queries, hashes, protocols
+ * extractFileName("https://example.com/file.txt?ver=1"); // ➔ "file"
+ * extractFileName("https://example.com/archive.tar.gz#part"); // ➔ "archive"
+ * extractFileName("//cdn.example.com/image.png"); // ➔ "image"
+ *
+ *
+ * // Special protocol handling
+ * extractFileName("tel:+6212345678"); // ➔ "+6212345678"
+ * extractFileName("sms:+6212345678"); // ➔ "+6212345678"
+ * extractFileName("mailto:user@domain.com"); // ➔ "user@domain"
+ * extractFileName("data:text/plain;base64,SGVsbG8="); // ➔ "SGVsbG8="
+ * extractFileName("mailto:resume.com"); // ➔ "resume"
+ * extractFileName("ftp://example.com/image.jpeg"); // ➔ "image"
+ * extractFileName("ftp://files.example.com/app.min.js"); // ➔ "app.min"
+ * extractFileName("file:///C:/path/to/document.pdf"); // ➔ "document"
+ * extractFileName("custom-scheme://example.com/video.mp4"); // ➔ "video"
+ *
+ * // Unicode & emoji
+ * extractFileName("emoji-😊.png"); // ➔ "emoji-😊"
+ * extractFileName("🔥project.tar.gz"); // ➔ "🔥project"
+ *
+ * // Dotfiles
+ * extractFileName(".gitignore"); // ➔ ".gitignore"
+ * extractFileName("/path/.bashrc"); // ➔ ".bashrc"
+ *
+ * // Mixed Unicode domain and ASCII filename
+ * extractFileName("https://tést-ドメイン.com/file.txt"); // ➔ "file"
+ * extractFileName("https://example.com/ファイル名.pdf");    // ➔ "ファイル名"
+ * extractFileName("https://ドメイン例.com/emoji-🔥.png"); // ➔ "emoji-🔥"
+ *
+ * // Reserved filenames
+ * extractFileName("CON"); // ➔ "CON"
+ * extractFileName("NUL.txt"); // ➔ "NUL"
+ *
+ * // Domain-aware mode
+ * extractFileName("example.com", {
+ *    domainAware: true,
+ *    domainName: "example.com"
+ * });
+ * // ➔ null
+ * extractFileName("cdn.example.com", {
+ *    domainAware: true,
+ *    domainName: "example.com"
+ * });
+ * // ➔ null
+ * extractFileName("resume.com", {
+ *    domainAware: true,
+ *    domainName: "example.com"
+ * });
+ * // ➔ "resume"
+ * extractFileName("https://example.com/file.txt", {
+ *    domainAware: true,
+ *    domainName: "example.com"
+ * });
+ * // ➔ "file"
+ *
+ * // Windows & UNC paths
+ * extractFileName("C:\\Users\\rzl\\Documents\\file.txt"); // ➔ "file"
+ * extractFileName("\\\\SERVER\\share\\logs\\output.log"); // ➔ "output"
+ * extractFileName("C:/Users\\rzl/mix\\test.pdf"); // ➔ "test"
+ *
+ * // Edge / extreme cases
+ * extractFileName("https://example.com/my%20file%20name.txt"); // ➔ "my file name"
+ * extractFileName("app.min.js.map"); // ➔ "app.min"
+ * extractFileName("backup.tar.bak"); // ➔ "backup.tar.bak" (unknown double extension)
+ * extractFileName("filename."); // ➔ "filename."
+ * extractFileName("a".repeat(255) + ".txt"); // ➔ "a".repeat(255)
+ * ```
+ *
+ * ----------------------------------------------------------
+ * @note
+ * - Robust: never throws, handles unusual inputs safely.
+ * - Suitable for display, logging, or safe storage.
+ * - Normalizes slashes consistently.
+ * - Covers nearly all real-world filename, URL, path, data URI, and domain scenarios.
+ * - Handles Windows UNC paths, mixed slashes, percent-encoded, Unicode/emoji filenames.
+ * - Known multi-part extensions list can be extended without breaking functionality.
+ */
+declare const extractFileName: (input?: string | null, options?: ExtractFileNameOptions) => string | null;
+export { ExtractFileNameOptions, extractFileName };

package/dist/parsers/index.d.ts

@@ -1,75 +1,75 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.11.1.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.0`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
 type ExtractFileNameOptions = {
-    /** ----------------------------------------------------------
-     * * ***Indicates whether the input should be treated as a potential domain string.***
-     * ----------------------------------------------------------
-     *
-     * - Behavior when `true`:
-     *    - The `domainName` option is required and must be a string and non-empty string.
-     *      If `domainName` is `undefined`, `null`, or an empty string, a `TypeError` will be thrown.
-     *    - The `domainName` is used to determine if the input is a domain-only string.
-     *    - Returns `null` if the input exactly matches `domainName` or any of its subdomains **and** has no additional path or filename.
-     *    - If the input does not match `domainName` or its subdomains, it will be processed as a regular file-like name.
-     *    - Supports **Unicode/IDN domains** (e.g., `tést-ドメイン.com`) and **ASCII filenames**, mixed safely.
-     *
-     * @default false
-     */
-    domainAware?: boolean;
-    /** ----------------------------------------------------------
-     * * ***The base domain name used for comparison (e.g., `"example.com"`).***
-     * ----------------------------------------------------------
-     *
-     * - Required when `domainAware` is `true`.
-     *    - Helps differentiate between a domain-only input (ignored) and a standalone file-like string (processed normally).
-     *    - Must be a string and non-empty string. Invalid values (`undefined`, `null`, or empty string) will trigger a `TypeError`.
-     *    - Works with both **ASCII domains** and **Unicode/IDN domains**.
-     *    - Example:
-     *      ```ts   *
-     *      // ASCII domain + ASCII filename
-     *      extractFileName("resume.com", {
-     *        domainAware: true,
-     *        domainName: "example.com"
-     *      });
-     *      // ➔ "resume"
-     *      extractFileName("example.com", {
-     *        domainAware: true,
-     *        domainName: "example.com"
-     *      });
-     *      // ➔ null (because input is treated as domain-name)
-     *
-     *      // Unicode domain + ASCII filename
-     *      extractFileName("tést-ドメイン.com/file.txt", {
-     *        domainAware: true,
-     *        domainName: "ドメイン.com"
-     *      });
-     *      // ➔ "file"
-     *
-     *      // Unicode domain + Unicode filename
-     *      extractFileName("tést-ドメイン.com/ファイル名.pdf", {
-     *        domainAware: true,
-     *        domainName: "ドメイン.com"
-     *      });
-     *      // ➔ "ファイル名"
-     *
-     *      // Invalid domainName, will throw TypeError
-     *      extractFileName("resume.com", {
-     *        domainAware: true,
-     *        domainName: ""
-     *      });
-     *      // ➔ TypeError
-     *      ```
-     *
-     * @default undefined
-     */
-    domainName?: string;
+  /** ----------------------------------------------------------
+   * * ***Indicates whether the input should be treated as a potential domain string.***
+   * ----------------------------------------------------------
+   *
+   * - Behavior when `true`:
+   *    - The `domainName` option is required and must be a string and non-empty string.
+   *      If `domainName` is `undefined`, `null`, or an empty string, a `TypeError` will be thrown.
+   *    - The `domainName` is used to determine if the input is a domain-only string.
+   *    - Returns `null` if the input exactly matches `domainName` or any of its subdomains **and** has no additional path or filename.
+   *    - If the input does not match `domainName` or its subdomains, it will be processed as a regular file-like name.
+   *    - Supports **Unicode/IDN domains** (e.g., `tést-ドメイン.com`) and **ASCII filenames**, mixed safely.
+   *
+   * @default false
+   */
+  domainAware?: boolean;
+  /** ----------------------------------------------------------
+   * * ***The base domain name used for comparison (e.g., `"example.com"`).***
+   * ----------------------------------------------------------
+   *
+   * - Required when `domainAware` is `true`.
+   *    - Helps differentiate between a domain-only input (ignored) and a standalone file-like string (processed normally).
+   *    - Must be a string and non-empty string. Invalid values (`undefined`, `null`, or empty string) will trigger a `TypeError`.
+   *    - Works with both **ASCII domains** and **Unicode/IDN domains**.
+   *    - Example:
+   *      ```ts   *
+   *      // ASCII domain + ASCII filename
+   *      extractFileName("resume.com", {
+   *        domainAware: true,
+   *        domainName: "example.com"
+   *      });
+   *      // ➔ "resume"
+   *      extractFileName("example.com", {
+   *        domainAware: true,
+   *        domainName: "example.com"
+   *      });
+   *      // ➔ null (because input is treated as domain-name)
+   *
+   *      // Unicode domain + ASCII filename
+   *      extractFileName("tést-ドメイン.com/file.txt", {
+   *        domainAware: true,
+   *        domainName: "ドメイン.com"
+   *      });
+   *      // ➔ "file"
+   *
+   *      // Unicode domain + Unicode filename
+   *      extractFileName("tést-ドメイン.com/ファイル名.pdf", {
+   *        domainAware: true,
+   *        domainName: "ドメイン.com"
+   *      });
+   *      // ➔ "ファイル名"
+   *
+   *      // Invalid domainName, will throw TypeError
+   *      extractFileName("resume.com", {
+   *        domainAware: true,
+   *        domainName: ""
+   *      });
+   *      // ➔ TypeError
+   *      ```
+   *
+   * @default undefined
+   */
+  domainName?: string;
 };
 /** ----------------------------------------------------------
  * * ***Utility: `extractFileName`.***
@@ -236,5 +236,4 @@ type ExtractFileNameOptions = {
  * - Known multi-part extensions list can be extended without breaking functionality.
  */
 declare const extractFileName: (input?: string | null, options?: ExtractFileNameOptions) => string | null;
-
-export { type ExtractFileNameOptions, extractFileName };
+export { ExtractFileNameOptions, extractFileName };

package/dist/parsers/index.js

@@ -1,13 +1,11 @@
 /*!
- * ====================================================
- * Rzl Utils-JS.
- * ----------------------------------------------------
- * Version: 3.11.1.
- * Author: Rizalvin Dwiky.
- * Repository: https://github.com/rzl-zone/utils-js.
- * ====================================================
- */
-export { extractFileName } from '../chunk-JIE447J5.js';
-import '../chunk-6YGBRENU.js';
-import '../chunk-3T6VSWYX.js';
-import '../chunk-MSUW5VHZ.js';
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.0`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+import { t as extractFileName } from "../parsers-Dpuq-V4u.js";
+export { extractFileName };