df-script 1.4.0 → 1.5.0

package/dist/utils/json.js

@@ -2,32 +2,216 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isJsonString = isJsonString;
 exports.safeJsonParse = safeJsonParse;
-function isJsonString(input, allowPrimitives = false) {
-    if (typeof input !== "string")
-        return false;
-    const s = input.trim();
-    if (s === "")
+exports.createSafeJsonReplacer = createSafeJsonReplacer;
+const guards_1 = require("./guards");
+const date_1 = require("./date");
+const NEWLINE_REGEX = /\r\n|\n|\r/g;
+const NO_FALLBACK = Symbol("no_fallback");
+const isWrapped = (str) => {
+    const len = str.length;
+    if (len < 2)
         return false;
-    if (!allowPrimitives) {
-        const isWrapped = (s.startsWith("{") && s.endsWith("}")) || (s.startsWith("[") && s.endsWith("]"));
-        if (!isWrapped)
-            return false;
+    const fChar = str[0];
+    const lChar = str[len - 1];
+    return (fChar === "{" && lChar === "}") || (fChar === "[" && lChar === "]");
+};
+const isWrappedUntrimmed = (str) => {
+    let first = 0;
+    const len = str.length;
+    while (first < len && /\s/.test(str[first])) {
+        first++;
     }
-    try {
-        JSON.parse(s);
-        return true;
+    let last = len - 1;
+    while (last >= first && /\s/.test(str[last])) {
+        last--;
     }
-    catch {
+    if (first >= last)
         return false;
-    }
-}
-function safeJsonParse(input) {
+    const fChar = str[first];
+    const lChar = str[last];
+    return (fChar === "{" && lChar === "}") || (fChar === "[" && lChar === "]");
+};
+/**
+ * Validates whether the given value is a valid JSON or NDJSON string.
+ * Leverages single-pass parsing under the hood to ensure zero duplicate loops.
+ *
+ * @param input - The value to check.
+ * @param options - Configuration options for validation.
+ * @returns `true` if the input is a valid JSON or NDJSON string; `false` otherwise.
+ */
+function isJsonString(input, options = {}) {
     if (typeof input !== "string")
-        return input;
+        return false;
+    const sentinel = Symbol("invalid");
+    const result = safeJsonParse(input, {
+        ...options,
+        fallback: sentinel,
+        onError: () => { } // Silence errors during pure structural checking
+    });
+    return result !== sentinel;
+}
+/**
+ * Safely parses a string containing JSON or NDJSON content in a single pass, returning the parsed value if successful
+ * and passing the guard validation. If parsing or validation fails, returns the fallback value (if provided)
+ * or the original input.
+ *
+ * @param input - The value to parse.
+ * @param options - Configuration options for parsing and validation.
+ * @returns The parsed value, the fallback, or the original input.
+ */
+function safeJsonParse(input, { format = "json", allowPrimitives = false, trimBeforeParse = false, reviver, ndjson: { skipInvalidLines = false, maxLines, skipLines } = {}, guard, onError, fallback = NO_FALLBACK } = {}) {
+    if (typeof input !== "string") {
+        return fallback !== NO_FALLBACK ? fallback : input;
+    }
+    const s = trimBeforeParse ? input.trim() : input;
+    if (s === "") {
+        return fallback !== NO_FALLBACK ? fallback : input;
+    }
+    let result;
     try {
-        return JSON.parse(input);
+        if (format === "ndjson") {
+            const parsedData = [];
+            let nonEmptyCount = 0;
+            let parsedCount = 0;
+            let lastIndex = 0;
+            NEWLINE_REGEX.lastIndex = 0;
+            let match;
+            while (true) {
+                match = NEWLINE_REGEX.exec(s);
+                const line = match ? s.substring(lastIndex, match.index) : s.substring(lastIndex);
+                if (match) {
+                    lastIndex = NEWLINE_REGEX.lastIndex;
+                }
+                const trimmedLine = line.trim();
+                if (trimmedLine !== "") {
+                    nonEmptyCount++;
+                    if (skipLines === undefined || nonEmptyCount > skipLines) {
+                        if (!allowPrimitives && !isWrapped(trimmedLine)) {
+                            if (!skipInvalidLines) {
+                                throw new Error("NDJSON line is not wrapped and primitives are disallowed");
+                            }
+                        }
+                        else {
+                            try {
+                                parsedData.push(JSON.parse(trimmedLine, reviver));
+                                parsedCount++;
+                                if (maxLines !== undefined && parsedCount >= maxLines)
+                                    break;
+                            }
+                            catch (err) {
+                                if (!skipInvalidLines)
+                                    throw err;
+                            }
+                        }
+                    }
+                }
+                if (!match)
+                    break;
+            }
+            if (parsedData.length === 0) {
+                throw new Error("No valid NDJSON lines processed");
+            }
+            result = parsedData;
+        }
+        else {
+            if (!allowPrimitives && !isWrappedUntrimmed(s)) {
+                throw new Error("JSON string is not wrapped and primitives are disallowed");
+            }
+            result = JSON.parse(s, reviver);
+        }
     }
-    catch {
-        return input;
+    catch (err) {
+        onError?.(err);
+        return fallback !== NO_FALLBACK ? fallback : input;
     }
+    if (guard && !guard(result)) {
+        onError?.(new Error("Parsed value failed guard validation"));
+        return fallback !== NO_FALLBACK ? fallback : input;
+    }
+    return result;
+}
+function createSafeJsonReplacer(options = {}) {
+    const bigintStrat = options.bigintStrategy ?? "string";
+    let seen = options.handleCircular ? new WeakSet() : null;
+    const isArrayReplacer = Array.isArray(options.replacer);
+    const whitelist = isArrayReplacer ? options.replacer.map(String) : null;
+    const handleBigInt = (val) => {
+        if (bigintStrat === "number") {
+            return val <= BigInt(Number.MAX_SAFE_INTEGER) && val >= BigInt(Number.MIN_SAFE_INTEGER)
+                ? Number(val)
+                : val.toString();
+        }
+        return val.toString();
+    };
+    return function replacer(k, v) {
+        let val = v;
+        if (typeof options.replacer === "function") {
+            val = options.replacer.call(this, k, v);
+        }
+        else if (whitelist) {
+            if (k !== "" && !Array.isArray(this) && !whitelist.includes(k)) {
+                return undefined;
+            }
+        }
+        if (val === undefined)
+            return undefined;
+        const raw = (val === v && this != null) ? this[k] : val;
+        if (typeof options.onCustom === "function") {
+            const customVal = options.onCustom.call(this, k, raw);
+            if (customVal !== raw || (customVal === undefined && raw !== undefined)) {
+                return customVal;
+            }
+        }
+        if (raw !== null && typeof raw !== "object" && typeof raw !== "bigint") {
+            return val;
+        }
+        if (seen && raw !== null && typeof raw === "object") {
+            if (k === "") {
+                seen = new WeakSet();
+            }
+            if (seen.has(raw)) {
+                return options.onCircular ? options.onCircular.call(this, k, raw) : "[Circular]";
+            }
+            seen.add(raw);
+        }
+        if (typeof raw === "bigint") {
+            if (options.voidBigIntReplacement)
+                return val;
+            return options.onBigInt ? options.onBigInt(raw) : handleBigInt(raw);
+        }
+        if ((0, guards_1.isTypedArray)(raw)) {
+            if (options.voidTypedArrayReplacement)
+                return val;
+            return options.onTypedArray ? options.onTypedArray(raw) : Array.from(raw);
+        }
+        if (raw instanceof Set) {
+            if (options.voidSetReplacement)
+                return val;
+            return options.onSet ? options.onSet(raw) : Array.from(raw);
+        }
+        if (raw instanceof Map) {
+            if (options.voidMapReplacement)
+                return val;
+            return options.onMap ? options.onMap(raw) : Array.from(raw.entries());
+        }
+        if (raw instanceof RegExp) {
+            if (options.voidRegExpReplacement)
+                return val;
+            return options.onRegExp ? options.onRegExp(raw) : raw.toString();
+        }
+        if ((0, date_1.isValidDateObj)(raw)) {
+            if (options.voidDateReplacement)
+                return val;
+            if (options.onDate)
+                return options.onDate(raw);
+            return options.formatDate ? options.formatDate(raw) : raw.toISOString();
+        }
+        if (raw instanceof Error) {
+            return options.onError ? options.onError(raw) : { name: raw.name, message: raw.message, stack: raw.stack };
+        }
+        if (raw instanceof URLSearchParams) {
+            return options.onURLSearchParams ? options.onURLSearchParams(raw) : raw.toString();
+        }
+        return val;
+    };
 }

package/dist/utils/list.d.ts

@@ -1,4 +1,4 @@
-export type ArrayItemType = "string" | "number" | "boolean" | "bigint" | "object" | "plainObject" | "date" | (new (...args: any[]) => any) | ((v: unknown) => boolean);
+export type ArrayItemType = "string" | "number" | "boolean" | "bigint" | "object" | "plainObject" | "date" | "any" | "null" | "undefined" | "nullish" | (new (...args: any[]) => any) | ((v: unknown) => boolean);
 export type ArrayCheckMode = "every" | "some";
 export type IsArrayOfTypeOptionsParams = {
     mode?: ArrayCheckMode;
@@ -6,6 +6,7 @@ export type IsArrayOfTypeOptionsParams = {
     allowEmpty?: boolean;
 };
 export declare function toValidArray<T>(val: T | T[] | null | undefined): T[];
+export declare function toValidStringArray(val: unknown): string[];
 export declare function isArrayOfType(arr: unknown, type: ArrayItemType, { mode, allowNulls, allowEmpty }?: IsArrayOfTypeOptionsParams): boolean;
 export declare function sortList(arr: unknown, descending?: boolean): any[];
 export declare function getListStats(arr: unknown): {
@@ -21,3 +22,174 @@ export declare function getListStats(arr: unknown): {
     hasNulls: boolean;
     isNumeric: boolean;
 };
+/**
+ * Options configuration for the `getUniqueListStats` utility.
+ */
+export interface UniqueListStatsOptions {
+    /**
+     * If true, uses strict serialization comparison (via keySelector or toCanonicalString)
+     * to group complex nested types (like Arrays, Sets, Maps, and Dates) by value instead of reference.
+     * @default false
+     */
+    strict?: boolean;
+    /**
+     * Custom function to extract a unique comparison key from each element.
+     * If strict is true and no selector is provided, falls back to `toCanonicalString`.
+     */
+    keySelector?: (val: any) => any;
+}
+export declare function getUniqueListStats(arr: ArrayLike<any>, { strict, keySelector }?: UniqueListStatsOptions): {
+    values: any[];
+    count: number;
+    frequencies: Map<any, number>;
+};
+/**
+ * Options configuration for the `stepSliceList` utility.
+ */
+export interface StepSliceListOptions {
+    /**
+     * The step size to slice the list by. Cannot be zero.
+     * Positive values slice forward (left-to-right), negative values slice backward (right-to-left).
+     * @default 1
+     */
+    step?: number;
+    /**
+     * The index to start slicing from (inclusive).
+     * Supports negative values to start relative to the end of the array.
+     * @default 0
+     */
+    offsetStart?: number;
+    /**
+     * The index to end slicing at (exclusive).
+     * Supports negative values to end relative to the end of the array.
+     * Defaults to the end of the array (if step > 0) or -1 (if step < 0).
+     */
+    offsetEnd?: number;
+    /**
+     * Caps the maximum number of items gathered in the sliced result list.
+     * If specified, the slicing process stops once this limit is reached.
+     */
+    maxItemsGathered?: number;
+    /**
+     * If true, returns null when the starting offset is out of bounds.
+     * If false, throws an error when the starting offset is out of bounds.
+     * @default true
+     */
+    null_on_oob?: boolean;
+}
+export declare function stepSliceList<T>(arr: ArrayLike<T>, { step, offsetStart, offsetEnd, maxItemsGathered, null_on_oob }?: StepSliceListOptions): T[] | null;
+/**
+ * Options configuration for the `joinList` utility.
+ */
+export interface JoinListOptions {
+    /**
+     * If true, nullish elements (null and undefined) are completely ignored during joining.
+     * If false (default), nullish elements are serialized as empty strings or custom `nullValue`.
+     * @default false
+     */
+    ignoreNulls?: boolean;
+    /**
+     * Custom string representation for nullish values.
+     * Only applied if `ignoreNulls` is false.
+     * @default ""
+     */
+    nullValue?: string;
+    /**
+     * Optional prefix string prepended to the final joined result.
+     * @default ""
+     */
+    prefix?: string;
+    /**
+     * Optional suffix string appended to the final joined result.
+     * @default ""
+     */
+    suffix?: string;
+    /**
+     * Maximum number of list elements to join.
+     * If specified, elements beyond this limit are omitted and `truncationMarker` is appended.
+     */
+    limit?: number;
+    /**
+     * Custom placeholder string appended to the joined string when limit truncation occurs.
+     * Only applied if `limit` is specified and the list length exceeds it.
+     * @default "..."
+     */
+    truncationMarker?: string;
+    /**
+     * Callback function used to format each individual non-null element to a custom string representation.
+     */
+    valueFormatter?: (val: any, index: number) => string;
+}
+/**
+ * Joins the elements of an array-like structure into a string using a separator.
+ * Excludes nullish checks and formats nested arrays cleanly.
+ */
+export declare function joinList(arr: ArrayLike<any>, separator?: string, { ignoreNulls, nullValue, prefix, suffix, limit, truncationMarker, valueFormatter }?: JoinListOptions): string;
+export interface FillSeqBaseOptions {
+    /**
+     * Type coercion helper applied to each generated value before writing.
+     *
+     * @param v The newly generated candidate value.
+     * @returns The coerced value to write to the array.
+     */
+    coerce?: (v: any) => any;
+    /**
+     * Conditional predicate determining if a value should be replaced at a given index.
+     *
+     * @param v The original/current value at the target index.
+     * @param index The absolute index of the current element.
+     * @param array The entire target array.
+     * @returns True if the candidate value should overwrite the original value, false otherwise.
+     */
+    condition?: (v: any, index: number, array: any[]) => boolean;
+    /**
+     * If true, iterates and populates in reverse (from startIndex down to endIndex).
+     * @default false
+     */
+    reverse?: boolean;
+    /**
+     * The index at which array iteration and writing begins.
+     * @default reverse ? length - 1 : 0
+     */
+    startIndex?: number;
+    /**
+     * The exclusive boundary index at which iteration and writing stops.
+     * @default reverse ? -1 : length
+     */
+    endIndex?: number;
+}
+export interface CumulativeStepContext {
+    /** The accumulated value returned by the step function from the previous stepped index. */
+    prev: any;
+    /** The relative iteration counter of the stepping process (starts at 1). */
+    index: number;
+    /** The original value at the current index in the target array. */
+    originalValue: any;
+    /** The absolute index of the current element in the parent array. */
+    absoluteIndex: number;
+    /** The entire target array being populated/modified. */
+    targetArray: any;
+}
+export interface IndependentStepContext {
+    /** The relative iteration counter of the generation process (starts at 0). */
+    index: number;
+    /** The static starting value passed to the sequence generator. */
+    initialValue: any;
+    /** The original value at the current index in the target array. */
+    originalValue: any;
+    /** The absolute index of the current element in the parent array. */
+    absoluteIndex: number;
+    /** The entire target array being populated/modified. */
+    targetArray: any;
+}
+export type FillSeqOptions = FillSeqBaseOptions & ({
+    mode: "constant";
+    step?: never;
+} | {
+    mode?: "cumulative";
+    step?: number | ((context: CumulativeStepContext) => any);
+} | {
+    mode: "independent";
+    step?: number | ((context: IndependentStepContext) => any);
+});
+export declare function fillSequence(targetArray: any, initialValue: any, options?: FillSeqOptions): void;