@turndown/library 0.1.23 → 0.1.28

package/dist/helpers/object/index.js

@@ -1,540 +0,0 @@
-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 {
-        const parsedValue = JSON.parse(jsonString);
-        return parsedValue;
-    }
-    catch {
-        return fallbackValue ?? {};
-    }
-}
-/**
- * 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 {unknown} value - Value to stringify.
- * @returns {string | undefined} JSON string with circulars omitted.
- * @example
- * const value: Record<string, unknown> = {}; value.self = value;
- * JSONStringify(value) // => "{}"
- */
-export const JSONStringify = (value) => {
-    const seenValues = new WeakSet();
-    try {
-        return JSON.stringify(value, (_key, nestedValue) => {
-            if (typeof nestedValue === "bigint") {
-                return nestedValue.toString();
-            }
-            if (typeof nestedValue === "object" && nestedValue !== null) {
-                if (seenValues.has(nestedValue)) {
-                    return undefined;
-                }
-                seenValues.add(nestedValue);
-            }
-            return nestedValue;
-        });
-    }
-    catch {
-        return undefined;
-    }
-};
-/**
- * Deep-remove `undefined` properties while preserving Dates and arrays.
- *
- * 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 = (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 {{ pathname?: string } | null | undefined} location - Object expected
- * to have a `pathname`.
- * @param {string} key - Path to compare.
- * @returns {boolean}
- * @example
- * validPath({ pathname: "/home" }, "/home") // true
- */
-export const validPath = (location, key) => {
-    return location?.pathname === key;
-};
-/**
- * Return the first element if the input is an array; otherwise return the value itself.
- *
- * @typeParam T - Element type.
- * @param {T | T[]} input - A single value or an array.
- * @returns {T} First element or the input value.
- * @example
- * returnObject([1,2,3]) // 1
- * returnObject(5) // 5
- */
-export const returnObject = (input) => {
-    return Array.isArray(input) ? input[0] : input;
-};
-/**
- * Filter out items from `array1` whose `id` appears in `array2`.
- *
- * @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 invalid input).
- */
-export const filterArrayById = (array1, array2) => {
-    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).
- *
- * Mutates the original array (uses `Array.prototype.sort`).
- *
- * @typeParam T - Object type.
- * @typeParam TKey - Sortable property key.
- * @param {T[]} array - Array to sort.
- * @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.isArray(array) || array.length === 0)
-        return [];
-    return array.sort((a, b) => {
-        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 (firstValue < secondValue)
-            return -1;
-        if (firstValue > secondValue)
-            return 1;
-        return 0;
-    });
-};
-/**
- * Recursively replace `null` values with empty strings.
- *
- * Works on primitives, arrays, Dates, and plain objects.
- *
- * @typeParam TValue - Input value type.
- * @param {TValue} value - Input value.
- * @returns {TReplaceNulls<TValue>} Value with all `null` replaced by `""`.
- */
-export const replaceNulls = (value) => {
-    if (value === null) {
-        return "";
-    }
-    if (Array.isArray(value)) {
-        return value.map((item) => replaceNulls(item));
-    }
-    if (isRecord(value)) {
-        const updatedValue = Object.entries(value).reduce((accumulator, [key, nestedValue]) => {
-            accumulator[key] = replaceNulls(nestedValue);
-            return accumulator;
-        }, {});
-        return updatedValue;
-    }
-    return value;
-};
-/**
- * Recursively remove object keys that contain a dot (`.`).
- *
- * @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 = (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 TValue - Input value type.
- * @param {TValue} value - Input object or array.
- * @returns {TValue} New value with boolean-like strings converted.
- */
-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 (`.`)
- *
- * @typeParam TObject - Form data object type.
- * @param {TObject} objectToClean - Input data.
- * @returns {Partial<TObject>} Cleaned clone.
- */
-export const cleanFormData = (objectToClean) => {
-    return removeFormProperties(convertStringBooleans(removeUndefined(objectToClean)));
-};
-/**
- * Return a default pagination object, allowing optional sort and filters.
- *
- * @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:[] }
- */
-export const resetPagination = (sort, filters) => {
-    return {
-        page: 1,
-        size: 25,
-        sort: sort || [],
-        filters: filters || [],
-    };
-};
-/**
- * Format a string of digits into a U.S. phone number.
- *
- * 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.
- * @example
- * formatPhoneNumber("1234567890") // "(123) 456-7890"
- * formatPhoneNumber(9876543210)   // "(987) 654-3210"
- * formatPhoneNumber("555")        // "555"
- */
-export const formatPhoneNumber = (value) => {
-    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}`;
-};
-/**
- * Format a number with thousands separators (commas).
- *
- * @param {number} value - Number to format.
- * @returns {string} String with commas.
- * @example
- * formatNumber(1234567) // "1,234,567"
- */
-export const formatNumber = (value) => {
-    return value.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
-};
-/**
- * Remove comma separators from a number-like value.
- *
- * @param {number | string} value - Number-like value.
- * @returns {string} Value without comma separators.
- */
-export const parseNumber = (value) => {
-    return value.toString().replace(/,/g, "");
-};
-/**
- * Delete a property from an object if it exists (no-op if it doesn't).
- *
- * @typeParam TObject - Object type.
- * @param {TObject} objectToUpdate - Target object (mutated).
- * @param {keyof TObject | string} propertyName - Property to delete.
- * @returns {void}
- */
-export const deletePropertyIfExists = (objectToUpdate, propertyName) => {
-    if (Object.prototype.hasOwnProperty.call(objectToUpdate, propertyName)) {
-        delete objectToUpdate[propertyName];
-    }
-};
-/**
- * Split an array into chunks of a given size.
- *
- * @typeParam T - Element type.
- * @param {T[]} array - Source array.
- * @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 = [];
-    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 `objectToOmitFrom` without the listed properties.
- *
- * @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 = (objectToOmitFrom, propsToOmit) => {
-    const updatedObject = { ...objectToOmitFrom };
-    propsToOmit.forEach((propertyName) => {
-        delete updatedObject[propertyName];
-    });
-    return updatedObject;
-};
-/**
- * Safe `hasOwnProperty` check.
- *
- * @param {unknown} value - Value to test.
- * @param {PropertyKey} key - Property name.
- * @returns {boolean}
- */
-export const hasProperty = (value, key) => {
-    if (value === null || value === undefined)
-        return false;
-    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 {unknown} value - Object to test.
- * @returns {boolean} `true` if there is at least one key.
- */
-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;
-};