@turndown/library 0.1.16 → 0.1.22

package/dist/helpers/object/index.js

@@ -1,61 +1,87 @@
-/**
- * Safely parse a JSON string into a value.
- *
- * Returns `{}` if parsing fails instead of throwing.
- *
- * @param {TurndownObject} jsonString - The JSON string to parse.
- * @returns {TurndownObject} Parsed value or `{}` on failure.
- * @example
- * parseJSON('{"a":1}') // => { a: 1 }
- * parseJSON('not json') // => {}
- */
-export const parseJSON = (jsonString) => {
+const unsafePathSegments = new Set(["__proto__", "prototype", "constructor"]);
+const isRecord = (value) => {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+};
+const isSafePathSegment = (segment) => {
+    return segment.length > 0 && !unsafePathSegments.has(segment);
+};
+const getPathSegments = (path) => {
+    return path.split(".").filter((segment) => segment.length > 0);
+};
+export function parseJSON(jsonString, fallbackValue) {
+    if (!jsonString) {
+        return fallbackValue ?? {};
+    }
     try {
-        return JSON.parse(jsonString);
+        const parsedValue = JSON.parse(jsonString);
+        return parsedValue;
     }
-    catch (error) {
-        return {};
+    catch {
+        return fallbackValue ?? {};
     }
-};
+}
 /**
- * Stringify an object to JSON while skipping circular references.
+ * Stringify a value to JSON while skipping circular references.
  *
  * Uses an internal cache to omit repeated object references that would
  * normally cause `JSON.stringify` to throw.
  *
- * @param {TurndownObject} obj - Value to stringify.
- * @returns {string} JSON string with circulars omitted.
+ * @param {unknown} value - Value to stringify.
+ * @returns {string | undefined} JSON string with circulars omitted.
  * @example
- * const a:any = {}; a.self = a;
- * JSONStringify(a) // => "{}"
+ * const value: Record<string, unknown> = {}; value.self = value;
+ * JSONStringify(value) // => "{}"
  */
-export const JSONStringify = (obj) => {
-    let cache = [];
-    let str = JSON.stringify(obj, function (_key, value) {
-        if (typeof value === "object" && value !== null) {
-            if (cache.indexOf(value) !== -1) {
-                return;
+export const JSONStringify = (value) => {
+    const seenValues = new WeakSet();
+    try {
+        return JSON.stringify(value, (_key, nestedValue) => {
+            if (typeof nestedValue === "bigint") {
+                return nestedValue.toString();
             }
-            cache.push(value);
-        }
-        return value;
-    });
-    cache = null;
-    return str;
+            if (typeof nestedValue === "object" && nestedValue !== null) {
+                if (seenValues.has(nestedValue)) {
+                    return undefined;
+                }
+                seenValues.add(nestedValue);
+            }
+            return nestedValue;
+        });
+    }
+    catch {
+        return undefined;
+    }
 };
 /**
- * Deep-remove `undefined` properties by serializing & parsing.
+ * Deep-remove `undefined` properties while preserving Dates and arrays.
  *
- * @param {TurndownObject} obj - Input object.
- * @returns {TurndownObject} Cleaned clone with `undefined` removed.
+ * Object properties with `undefined` values are removed. Array items are
+ * preserved so array indexes do not shift.
+ *
+ * @typeParam TValue - Input value type.
+ * @param {TValue} value - Input value.
+ * @returns {TValue} Cleaned clone with `undefined` object properties removed.
  */
-export const removeUndefined = (obj) => {
-    return JSON.parse(JSONStringify(obj));
+export const removeUndefined = (value) => {
+    if (Array.isArray(value)) {
+        return value.map((item) => removeUndefined(item));
+    }
+    if (isRecord(value)) {
+        const updatedValue = Object.entries(value).reduce((accumulator, [key, nestedValue]) => {
+            if (nestedValue !== undefined) {
+                accumulator[key] = removeUndefined(nestedValue);
+            }
+            return accumulator;
+        }, {});
+        return updatedValue;
+    }
+    return value;
 };
 /**
  * Test whether a location object's `pathname` equals a key.
  *
- * @param {TurndownObject} location - Object expected to have a `pathname`.
+ * @param {{ pathname?: string } | null | undefined} location - Object expected
+ * to have a `pathname`.
  * @param {string} key - Path to compare.
  * @returns {boolean}
  * @example
@@ -83,19 +109,14 @@ export const returnObject = (input) => {
  * @typeParam T - Object type with an `id` field.
  * @param {T[]} [array1] - Source array.
  * @param {T[]} [array2] - Items whose `id`s should be excluded.
- * @returns {T[]} Filtered array (or `[]` on errors/invalid input).
+ * @returns {T[]} Filtered array (or `[]` on invalid input).
  */
 export const filterArrayById = (array1, array2) => {
-    try {
-        if (!array1 || !array2)
-            return [];
-        const idsToExclude = new Set(array2.map((item) => item.id));
-        return array1.filter((item) => !idsToExclude.has(item.id));
-    }
-    catch (error) {
-        console.error("An error occurred:", error);
+    if (!Array.isArray(array1) || !Array.isArray(array2)) {
         return [];
     }
+    const idsToExclude = new Set(array2.map((item) => item.id));
+    return array1.filter((item) => !idsToExclude.has(item.id));
 };
 /**
  * Sort an array of objects by a given property (ascending).
@@ -103,17 +124,26 @@ export const filterArrayById = (array1, array2) => {
  * Mutates the original array (uses `Array.prototype.sort`).
  *
  * @typeParam T - Object type.
+ * @typeParam TKey - Sortable property key.
  * @param {T[]} array - Array to sort.
- * @param {keyof T} property - Property name to sort by.
+ * @param {TKey} property - Property name to sort by.
  * @returns {T[]} The same array instance, sorted (or empty array if input invalid).
  */
 export const sortArrayByProperty = (array, property) => {
-    if (!array || array.length === 0)
+    if (!Array.isArray(array) || array.length === 0)
         return [];
     return array.sort((a, b) => {
-        if (a[property] < b[property])
+        const firstValue = a[property];
+        const secondValue = b[property];
+        if (firstValue === secondValue)
+            return 0;
+        if (firstValue === null || firstValue === undefined)
+            return 1;
+        if (secondValue === null || secondValue === undefined)
             return -1;
-        if (a[property] > b[property])
+        if (firstValue < secondValue)
+            return -1;
+        if (firstValue > secondValue)
             return 1;
         return 0;
     });
@@ -121,109 +151,99 @@ export const sortArrayByProperty = (array, property) => {
 /**
  * Recursively replace `null` values with empty strings.
  *
- * Works on primitives, arrays, and plain objects.
+ * Works on primitives, arrays, Dates, and plain objects.
  *
- * @param {TurndownObject} obj - Input value.
- * @returns {TurndownObject} Value with all `null` replaced by `""`.
+ * @typeParam TValue - Input value type.
+ * @param {TValue} value - Input value.
+ * @returns {TReplaceNulls<TValue>} Value with all `null` replaced by `""`.
  */
-export const replaceNulls = (obj) => {
-    if (obj === null) {
+export const replaceNulls = (value) => {
+    if (value === null) {
         return "";
     }
-    else if (Array.isArray(obj)) {
-        return obj.map(replaceNulls);
+    if (Array.isArray(value)) {
+        return value.map((item) => replaceNulls(item));
     }
-    else if (typeof obj === "object" && obj !== null) {
-        const newObj = {};
-        for (const key in obj) {
-            if (obj.hasOwnProperty(key)) {
-                newObj[key] = replaceNulls(obj[key]);
-            }
-        }
-        return newObj;
+    if (isRecord(value)) {
+        const updatedValue = Object.entries(value).reduce((accumulator, [key, nestedValue]) => {
+            accumulator[key] = replaceNulls(nestedValue);
+            return accumulator;
+        }, {});
+        return updatedValue;
     }
-    return obj;
+    return value;
 };
 /**
  * Recursively remove object keys that contain a dot (`.`).
  *
- * @typeParam T - Object type.
- * @param {T} obj - Input object.
- * @returns {T} New object with dotted keys removed at all levels.
+ * @typeParam TValue - Input value type.
+ * @param {TValue} value - Input object or array.
+ * @returns {TValue} New value with dotted keys removed at all levels.
  */
-export const removeFormProperties = (obj) => {
-    const recursiveRemove = (input) => {
-        if (Array.isArray(input)) {
-            return input.map((item) => recursiveRemove(item));
-        }
-        else if (typeof input === "object" && input !== null) {
-            const newObj = { ...input };
-            Object.keys(newObj).forEach((key) => {
-                if (key.includes(".")) {
-                    delete newObj[key];
-                }
-                else {
-                    newObj[key] = recursiveRemove(newObj[key]);
-                }
-            });
-            return newObj;
-        }
-        return input;
-    };
-    return recursiveRemove(obj);
+export const removeFormProperties = (value) => {
+    if (Array.isArray(value)) {
+        return value.map((item) => removeFormProperties(item));
+    }
+    if (isRecord(value)) {
+        const updatedValue = Object.entries(value).reduce((accumulator, [key, nestedValue]) => {
+            if (!key.includes(".")) {
+                accumulator[key] = removeFormProperties(nestedValue);
+            }
+            return accumulator;
+        }, {});
+        return updatedValue;
+    }
+    return value;
 };
 /**
  * Recursively convert string booleans `"true"`/`"false"` to actual booleans.
  *
  * Leaves all other values unchanged.
  *
- * @typeParam T - Object type.
- * @param {T} obj - Input object or array.
- * @returns {T} New value with boolean-like strings converted.
+ * @typeParam TValue - Input value type.
+ * @param {TValue} value - Input object or array.
+ * @returns {TValue} New value with boolean-like strings converted.
  */
-export const convertStringBooleans = (obj) => {
-    const recursiveConvert = (input) => {
-        if (Array.isArray(input)) {
-            return input.map((item) => recursiveConvert(item));
-        }
-        else if (typeof input === "object" && input !== null) {
-            const newObj = { ...input };
-            Object.keys(newObj).forEach((key) => {
-                const value = newObj[key];
-                if (value === "true") {
-                    newObj[key] = true;
-                }
-                else if (value === "false") {
-                    newObj[key] = false;
-                }
-                else if (typeof value === "object" && value !== null) {
-                    newObj[key] = recursiveConvert(value);
-                }
-            });
-            return newObj;
-        }
-        return input;
-    };
-    return recursiveConvert(obj);
+export const convertStringBooleans = (value) => {
+    if (Array.isArray(value)) {
+        return value.map((item) => convertStringBooleans(item));
+    }
+    if (isRecord(value)) {
+        const updatedValue = Object.entries(value).reduce((accumulator, [key, nestedValue]) => {
+            if (nestedValue === "true") {
+                accumulator[key] = true;
+            }
+            else if (nestedValue === "false") {
+                accumulator[key] = false;
+            }
+            else {
+                accumulator[key] = convertStringBooleans(nestedValue);
+            }
+            return accumulator;
+        }, {});
+        return updatedValue;
+    }
+    return value;
 };
 /**
  * Convenience helper to clean form-like data:
  * - Removes `undefined` properties
  * - Converts string booleans to booleans
- * - Removes keys containing a dot ('.')
+ * - Removes keys containing a dot (`.`)
  *
- * @param {TurndownObject} obj - Input data.
- * @returns {TurndownObject} Cleaned clone.
+ * @typeParam TObject - Form data object type.
+ * @param {TObject} objectToClean - Input data.
+ * @returns {Partial<TObject>} Cleaned clone.
  */
-export const cleanFormData = (obj) => {
-    return removeFormProperties(convertStringBooleans(removeUndefined(obj)));
+export const cleanFormData = (objectToClean) => {
+    return removeFormProperties(convertStringBooleans(removeUndefined(objectToClean)));
 };
 /**
  * Return a default pagination object, allowing optional sort and filters.
  *
- * @param {SortCondition[]} [sort] - Optional sort conditions.
- * @param {FilterCondition[]} [filters] - Optional filter conditions.
- * @returns {{ page: number; size: number; sort: SortCondition[]; filters: FilterCondition[] }}
+ * @param {ISortCondition[]} [sort] - Optional sort conditions.
+ * @param {IFilterCondition[]} [filters] - Optional filter conditions.
+ * @returns {{ page: number; size: number; sort: ISortCondition[]; filters: IFilterCondition[] }}
  * @example
  * resetPagination() // => { page:1, size:25, sort:[], filters:[] }
  */
@@ -238,8 +258,9 @@ export const resetPagination = (sort, filters) => {
 /**
  * Format a string of digits into a U.S. phone number.
  *
- * Strips non-numeric characters and formats as `(XXX) XXX-XXXX`.
- * If fewer than 10 digits are provided, returns the input unchanged.
+ * Strips non-numeric characters and formats 10 digits as `(XXX) XXX-XXXX`.
+ * Strips a leading US country code when 11 digits are provided.
+ * If a value cannot be formatted, returns the original value as a string.
  *
  * @param {string | number} value - Phone number digits (string or number).
  * @returns {string} Formatted phone number, or original input if invalid length.
@@ -249,12 +270,16 @@ export const resetPagination = (sort, filters) => {
  * formatPhoneNumber("555")        // "555"
  */
 export const formatPhoneNumber = (value) => {
-    const digits = value.toString().replace(/\D/g, "");
-    if (digits.length !== 10)
-        return value.toString();
-    const area = digits.slice(0, 3);
-    const prefix = digits.slice(3, 6);
-    const line = digits.slice(6);
+    const originalValue = value.toString();
+    const digits = originalValue.replace(/\D/g, "");
+    const normalizedDigits = digits.length === 11 && digits.startsWith("1")
+        ? digits.slice(1)
+        : digits;
+    if (normalizedDigits.length !== 10)
+        return originalValue;
+    const area = normalizedDigits.slice(0, 3);
+    const prefix = normalizedDigits.slice(3, 6);
+    const line = normalizedDigits.slice(6);
     return `(${area}) ${prefix}-${line}`;
 };
 /**
@@ -269,29 +294,25 @@ export const formatNumber = (value) => {
     return value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
 };
 /**
- * Parse a number string (note: current implementation adds commas as well).
+ * Remove comma separators from a number-like value.
  *
- * @remarks
- * This function uses the same regex as `formatNumber`, so it **does not remove**
- * commas; it inserts them. If you intended to *strip* separators, consider:
- * `value.toString().replace(/,/g, "")`.
- *
- * @param {number} value - Number to "parse".
- * @returns {string} Currently returns a comma-formatted string.
+ * @param {number | string} value - Number-like value.
+ * @returns {string} Value without comma separators.
  */
 export const parseNumber = (value) => {
-    return value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, "");
+    return value.toString().replace(/,/g, "");
 };
 /**
  * Delete a property from an object if it exists (no-op if it doesn't).
  *
- * @param {TurndownObject} obj - Target object (mutated).
- * @param {string} propertyName - Property to delete.
+ * @typeParam TObject - Object type.
+ * @param {TObject} objectToUpdate - Target object (mutated).
+ * @param {keyof TObject | string} propertyName - Property to delete.
  * @returns {void}
  */
-export const deletePropertyIfExists = (obj, propertyName) => {
-    if (Object.prototype.hasOwnProperty.call(obj, propertyName)) {
-        delete obj[propertyName];
+export const deletePropertyIfExists = (objectToUpdate, propertyName) => {
+    if (Object.prototype.hasOwnProperty.call(objectToUpdate, propertyName)) {
+        delete objectToUpdate[propertyName];
     }
 };
 /**
@@ -299,52 +320,218 @@ export const deletePropertyIfExists = (obj, propertyName) => {
  *
  * @typeParam T - Element type.
  * @param {T[]} array - Source array.
- * @param {number} chunkSize - Size of each chunk (no validation performed).
+ * @param {number} chunkSize - Size of each chunk.
  * @returns {T[][]} Array of chunks (last one may be smaller).
  * @example
  * chunkArray([1,2,3,4,5], 2) // [[1,2],[3,4],[5]]
  */
 export const chunkArray = (array, chunkSize) => {
+    if (!Array.isArray(array) || chunkSize <= 0 || !Number.isFinite(chunkSize)) {
+        return [];
+    }
     const result = [];
-    for (let i = 0; i < array.length; i += chunkSize) {
-        result.push(array.slice(i, i + chunkSize));
+    const normalizedChunkSize = Math.floor(chunkSize);
+    for (let i = 0; i < array.length; i += normalizedChunkSize) {
+        result.push(array.slice(i, i + normalizedChunkSize));
     }
     return result;
 };
 /**
- * Return a shallow clone of `obj` without the listed properties.
+ * Return a shallow clone of `objectToOmitFrom` without the listed properties.
  *
- * @param {TurndownObject} obj - Source object.
- * @param {TurndownObject} propsToOmit - Iterable of property names (expects array-like).
- * @returns {TurndownObject} New object without omitted props.
+ * @typeParam TObject - Source object type.
+ * @typeParam TKey - Keys to omit.
+ * @param {TObject} objectToOmitFrom - Source object.
+ * @param {readonly TKey[]} propsToOmit - Property names to omit.
+ * @returns {Omit<TObject, TKey>} New object without omitted props.
  * @example
  * omitProperties({a:1,b:2}, ["b"]) // { a:1 }
  */
-export const omitProperties = (obj, propsToOmit) => {
-    const newObj = { ...obj };
-    propsToOmit.forEach((prop) => {
-        delete newObj[prop];
+export const omitProperties = (objectToOmitFrom, propsToOmit) => {
+    const updatedObject = { ...objectToOmitFrom };
+    propsToOmit.forEach((propertyName) => {
+        delete updatedObject[propertyName];
     });
-    return newObj;
+    return updatedObject;
 };
 /**
  * Safe `hasOwnProperty` check.
  *
- * @param {Record<string, any>} obj - Object to test.
- * @param {string} key - Property name.
+ * @param {unknown} value - Value to test.
+ * @param {PropertyKey} key - Property name.
  * @returns {boolean}
  */
-export const hasProperty = (obj, key) => {
-    if (!obj)
+export const hasProperty = (value, key) => {
+    if (value === null || value === undefined)
         return false;
-    return Object.prototype.hasOwnProperty.call(obj, key);
+    return Object.prototype.hasOwnProperty.call(value, key);
+};
+/**
+ * Safe `hasOwnProperty` alias from the reference utilities.
+ *
+ * @param {unknown} value - Value to test.
+ * @param {PropertyKey} key - Property name.
+ * @returns {boolean}
+ */
+export const hasOwnProp = (value, key) => {
+    return hasProperty(value, key);
 };
 /**
  * Determine if an object has at least one own enumerable property.
  *
- * @param {object} obj - Object to test.
+ * @param {unknown} value - Object to test.
  * @returns {boolean} `true` if there is at least one key.
  */
-export const hasProperties = (obj) => {
-    return Object.keys(obj || {}).length > 0;
+export const hasProperties = (value) => {
+    return isRecord(value) && Object.keys(value).length > 0;
+};
+/**
+ * Get the first own enumerable property value from an object.
+ *
+ * @typeParam TObject - Source object type.
+ * @param {TObject | null | undefined} value - Source object.
+ * @returns {TObject[keyof TObject] | null} First value, or null for empty/non-object input.
+ */
+export const getFirstPropertyValue = (value) => {
+    if (value === null || value === undefined || !hasProperties(value)) {
+        return null;
+    }
+    const source = value;
+    const keys = Object.keys(source);
+    return source[keys[0]];
+};
+/**
+ * Get a nested value from an object using dot notation.
+ *
+ * @param {unknown} value - Source object.
+ * @param {string} path - Dot-delimited path.
+ * @returns {unknown} Nested value, or undefined when the path cannot be resolved.
+ * @example
+ * getNestedValue({ user: { name: "John" } }, "user.name") // "John"
+ */
+export const getNestedValue = (value, path) => {
+    const pathSegments = getPathSegments(path);
+    if (pathSegments.length === 0) {
+        return value;
+    }
+    let currentValue = value;
+    for (const pathSegment of pathSegments) {
+        if (!isSafePathSegment(pathSegment)) {
+            return undefined;
+        }
+        if (currentValue === null || currentValue === undefined) {
+            return undefined;
+        }
+        if (typeof currentValue !== "object" && typeof currentValue !== "function") {
+            return undefined;
+        }
+        currentValue = currentValue[pathSegment];
+    }
+    return currentValue;
+};
+/**
+ * Set a nested value on an object using dot notation.
+ *
+ * Mutates and returns the provided object. Unsafe path segments are ignored to
+ * prevent prototype pollution.
+ *
+ * @typeParam TObject - Target object type.
+ * @param {TObject} objectToUpdate - Target object.
+ * @param {string} path - Dot-delimited path.
+ * @param {unknown} value - Value to set.
+ * @returns {TObject} The mutated target object.
+ * @example
+ * setNestedValue({}, "user.name", "John") // { user: { name: "John" } }
+ */
+export const setNestedValue = (objectToUpdate, path, value) => {
+    const pathSegments = getPathSegments(path);
+    if (pathSegments.length === 0 || pathSegments.some((pathSegment) => !isSafePathSegment(pathSegment))) {
+        return objectToUpdate;
+    }
+    let currentValue = objectToUpdate;
+    for (let i = 0; i < pathSegments.length - 1; i += 1) {
+        const pathSegment = pathSegments[i];
+        const nextValue = currentValue[pathSegment];
+        if (!isRecord(nextValue)) {
+            currentValue[pathSegment] = {};
+        }
+        currentValue = currentValue[pathSegment];
+    }
+    currentValue[pathSegments[pathSegments.length - 1]] = value;
+    return objectToUpdate;
+};
+/**
+ * Deep clone a value while preserving Dates and circular references.
+ *
+ * @typeParam TValue - Input value type.
+ * @param {TValue} value - Value to clone.
+ * @returns {TValue} Deep clone of the input.
+ */
+export const deepClone = (value) => {
+    const cloneValue = (nestedValue, seenValues) => {
+        if (nestedValue === null || typeof nestedValue !== "object") {
+            return nestedValue;
+        }
+        if (nestedValue instanceof Date) {
+            return new Date(nestedValue.getTime());
+        }
+        if (seenValues.has(nestedValue)) {
+            return seenValues.get(nestedValue);
+        }
+        if (Array.isArray(nestedValue)) {
+            const clonedArray = [];
+            seenValues.set(nestedValue, clonedArray);
+            nestedValue.forEach((item) => {
+                clonedArray.push(cloneValue(item, seenValues));
+            });
+            return clonedArray;
+        }
+        const clonedObject = Object.create(Object.getPrototypeOf(nestedValue));
+        seenValues.set(nestedValue, clonedObject);
+        Reflect.ownKeys(nestedValue).forEach((key) => {
+            clonedObject[key] = cloneValue(nestedValue[key], seenValues);
+        });
+        return clonedObject;
+    };
+    return cloneValue(value, new WeakMap());
+};
+/**
+ * Flatten a nested object into dot notation.
+ *
+ * Arrays and Dates are treated as leaf values.
+ *
+ * @param {TRecord} value - Source object.
+ * @param {string} [prefix] - Internal prefix for recursion.
+ * @returns {TRecord} Flattened object.
+ * @example
+ * flatten({ user: { name: "John" } }) // { "user.name": "John" }
+ */
+export const flatten = (value, prefix = "") => {
+    const result = {};
+    Object.entries(value).forEach(([key, nestedValue]) => {
+        const newKey = prefix ? `${prefix}.${key}` : key;
+        if (isRecord(nestedValue)) {
+            Object.assign(result, flatten(nestedValue, newKey));
+            return;
+        }
+        result[newKey] = nestedValue;
+    });
+    return result;
+};
+/**
+ * Convert a dot-notation object into a nested object.
+ *
+ * Unsafe path segments are ignored to prevent prototype pollution.
+ *
+ * @param {TRecord} value - Dot-notation source object.
+ * @returns {TRecord} Nested object.
+ * @example
+ * unflatten({ "user.name": "John" }) // { user: { name: "John" } }
+ */
+export const unflatten = (value) => {
+    const result = {};
+    Object.entries(value).forEach(([key, nestedValue]) => {
+        setNestedValue(result, key, nestedValue);
+    });
+    return result;
 };