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

package/dist/operations/index.js.map

@@ -1 +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"}
+{"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) && current) {\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 = current ? obj[current] : undefined;\n      if (isObjectOrArray(next) && current) {\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,IAAI,SACxB,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,UAAU,IAAI,WAAW;GACtC,IAAI,gBAAgB,KAAK,IAAI,SAC3B,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

@@ -2,12 +2,12 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.12.1-beta.0`
+*  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_parsers = require('../parsers-DXtpsDyj.cjs');
+const require_parsers = require('../parsers-OqDeffqc.cjs');
 exports.extractFileName = require_parsers.extractFileName;

package/dist/parsers/index.d.cts

@@ -2,238 +2,238 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.12.1-beta.0`
+*  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`
 * ========================================================================
 */
 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
-   */
+  * * ***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
-   */
+  * * ***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.
- */
+* * ***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 };