df-script 1.4.0 → 1.5.0

package/dist/utils/csv.js

@@ -0,0 +1,313 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCsvValue = formatCsvValue;
+exports.stringifyCSV = stringifyCSV;
+exports.parseCSV = parseCSV;
+exports.inferAndCoerceCSVColumn = inferAndCoerceCSVColumn;
+const date_1 = require("./date");
+const json_1 = require("./json");
+const number_1 = require("./number");
+const constants_1 = require("../dataframe/constants");
+const datatypes_1 = require("../datatypes");
+// Removed stringifyCsvObject
+function formatCsvValueInternal(options = {}) {
+    const nullValue = options.nullValue !== undefined ? options.nullValue : "";
+    const formatNum = (0, number_1.formatNumber)(options.numericFormatOptions);
+    const replacerOptions = options.replacerOptions || {};
+    const formatDate = (v) => {
+        if (options.datetimeFormat)
+            return (0, date_1.strftime)(v, options.datetimeFormat);
+        if (options.dateFormat)
+            return (0, date_1.strftime)(v, options.dateFormat);
+        if (options.timeFormat)
+            return (0, date_1.strftime)(v, options.timeFormat);
+        return v.toISOString();
+    };
+    const replacer = (0, json_1.createSafeJsonReplacer)({
+        formatDate,
+        ...replacerOptions
+    });
+    const hasCustomBigInt = typeof replacerOptions.onBigInt === "function";
+    return (val) => {
+        if (val === null || val === undefined || typeof val === "symbol" || typeof val === "function") {
+            return { str: nullValue, isNumeric: false };
+        }
+        if (typeof val === "bigint" && !hasCustomBigInt && !replacerOptions.voidBigIntReplacement) {
+            return { str: formatNum(val), isNumeric: true };
+        }
+        const processed = replacer.call(null, "", val);
+        if (processed === null || processed === undefined || typeof processed === "symbol" || typeof processed === "function") {
+            return { str: nullValue, isNumeric: false };
+        }
+        if (typeof processed === "string")
+            return { str: processed, isNumeric: false };
+        if (typeof processed === "number" || typeof processed === "bigint") {
+            return { str: formatNum(processed), isNumeric: true };
+        }
+        if (typeof processed === "boolean")
+            return { str: processed ? "true" : "false", isNumeric: false };
+        if (processed instanceof Number)
+            return { str: formatNum(processed.valueOf()), isNumeric: true };
+        if (processed instanceof String)
+            return { str: processed.valueOf(), isNumeric: false };
+        if (processed instanceof Boolean)
+            return { str: processed.valueOf() ? "true" : "false", isNumeric: false };
+        if (typeof processed === "object") {
+            // Instantiate a fresh replacer specifically for nested stringification
+            // to avoid state carry-over (such as visited circular reference sets)
+            return {
+                str: JSON.stringify(processed, (0, json_1.createSafeJsonReplacer)({
+                    formatDate,
+                    ...replacerOptions
+                })),
+                isNumeric: false
+            };
+        }
+        return { str: String(processed), isNumeric: false };
+    };
+}
+function formatCsvValue(options = {}) {
+    const formatted = formatCsvValueInternal(options);
+    return (val) => formatted(val).str;
+}
+function stringifyCSV(columns, height, options = {}) {
+    const { separator = ",", quoteChar = '"', includeHeader = true, lineTerminator = constants_1.NEWLINE, quoteStyle = "necessary", includeBom = false, onRow, ...formatOptions } = options;
+    const keys = Object.keys(columns);
+    const numKeys = keys.length;
+    const lines = [];
+    let isFirstRow = true;
+    const formatValue = formatCsvValueInternal(formatOptions);
+    const escapeAndQuote = (val, isHeader = false) => {
+        let strVal;
+        let isNumeric = false;
+        if (isHeader) {
+            strVal = String(val);
+        }
+        else {
+            const formatted = formatValue(val);
+            strVal = formatted.str;
+            isNumeric = formatted.isNumeric;
+        }
+        if (quoteStyle === "never") {
+            return strVal;
+        }
+        if (quoteStyle === "always") {
+            const escaped = strVal.split(quoteChar).join(quoteChar + quoteChar);
+            return quoteChar + escaped + quoteChar;
+        }
+        if (quoteStyle === "non_numeric") {
+            if (!isNumeric && val != null) {
+                const escaped = strVal.split(quoteChar).join(quoteChar + quoteChar);
+                return quoteChar + escaped + quoteChar;
+            }
+        }
+        // Default: "necessary"
+        const needsQuoting = strVal.includes(separator) ||
+            strVal.includes(quoteChar) ||
+            strVal.includes(constants_1.NEWLINE) ||
+            strVal.includes(constants_1.CARRIAGE_RETURN);
+        if (needsQuoting) {
+            const escaped = strVal.split(quoteChar).join(quoteChar + quoteChar);
+            return quoteChar + escaped + quoteChar;
+        }
+        return strVal;
+    };
+    const outputLine = (line) => {
+        if (isFirstRow) {
+            const initial = includeBom ? constants_1.UTF8_BOM + line : line;
+            if (onRow) {
+                onRow(initial);
+            }
+            else {
+                lines.push(initial);
+            }
+            isFirstRow = false;
+        }
+        else {
+            if (onRow) {
+                onRow(lineTerminator + line);
+            }
+            else {
+                lines.push(line);
+            }
+        }
+    };
+    // Headers
+    if (includeHeader) {
+        const headerRow = new Array(numKeys);
+        for (let i = 0; i < numKeys; i++) {
+            headerRow[i] = escapeAndQuote(keys[i], true);
+        }
+        outputLine(headerRow.join(separator));
+    }
+    // Rows
+    for (let r = 0; r < height; r++) {
+        const row = new Array(numKeys);
+        for (let i = 0; i < numKeys; i++) {
+            row[i] = escapeAndQuote(columns[keys[i]][r], false);
+        }
+        outputLine(row.join(separator));
+    }
+    return onRow ? (includeBom ? constants_1.UTF8_BOM : "") : lines.join(lineTerminator);
+}
+function parseCSV(content, options = {}) {
+    const separator = options.separator || ",";
+    const quoteChar = options.quoteChar || '"';
+    let csvContent = content;
+    if (csvContent.startsWith(constants_1.UTF8_BOM)) {
+        csvContent = csvContent.substring(constants_1.UTF8_BOM.length);
+    }
+    const rows = [];
+    let currentRow = [];
+    let currentCell = "";
+    let inQuotes = false;
+    let hasAnyData = false;
+    let lastCharWasSeparator = false;
+    const len = csvContent.length;
+    for (let i = 0; i < len; i++) {
+        const char = csvContent[i];
+        if (inQuotes) {
+            hasAnyData = true;
+            lastCharWasSeparator = false;
+            if (char === quoteChar) {
+                if (i + 1 < len && csvContent[i + 1] === quoteChar) {
+                    currentCell += quoteChar;
+                    i++; // Skip escaped quote
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                currentCell += char;
+            }
+        }
+        else {
+            if (char === quoteChar) {
+                hasAnyData = true;
+                lastCharWasSeparator = false;
+                inQuotes = true;
+            }
+            else if (char === separator) {
+                currentRow.push(currentCell);
+                currentCell = "";
+                lastCharWasSeparator = true;
+            }
+            else {
+                let isLineBreak = false;
+                if (char === constants_1.CARRIAGE_RETURN) {
+                    isLineBreak = true;
+                    if (i + 1 < len && csvContent[i + 1] === constants_1.NEWLINE) {
+                        i++;
+                    }
+                }
+                else if (char === constants_1.NEWLINE) {
+                    isLineBreak = true;
+                }
+                if (isLineBreak) {
+                    if (hasAnyData || currentRow.length > 0 || currentCell !== "" || lastCharWasSeparator) {
+                        currentRow.push(currentCell);
+                        rows.push(currentRow);
+                        currentRow = [];
+                        currentCell = "";
+                        hasAnyData = false;
+                        lastCharWasSeparator = false;
+                    }
+                }
+                else {
+                    hasAnyData = true;
+                    lastCharWasSeparator = false;
+                    currentCell += char;
+                }
+            }
+        }
+    }
+    if (hasAnyData || currentRow.length > 0 || currentCell !== "" || lastCharWasSeparator) {
+        currentRow.push(currentCell);
+        rows.push(currentRow);
+    }
+    return rows;
+}
+function inferAndCoerceCSVColumn(values, options = {}) {
+    const nullValues = new Set(options.nullValues ?? ["", "NA", "null", "NaN"]);
+    const len = values.length;
+    let isAllBoolean = true;
+    let isAllNumber = true;
+    let isAllBigInt = true;
+    let isAllDate = true;
+    let hasValidData = false;
+    for (let i = 0; i < len; i++) {
+        const val = values[i].trim();
+        if (nullValues.has(val))
+            continue;
+        hasValidData = true;
+        if (isAllBoolean) {
+            const lower = val.toLowerCase();
+            if (lower !== "true" && lower !== "false" && lower !== "1" && lower !== "0") {
+                isAllBoolean = false;
+            }
+        }
+        if (isAllBigInt) {
+            if ((0, number_1.toValidBigInt)(val, { truncate: false }) === null) {
+                isAllBigInt = false;
+            }
+        }
+        if (isAllNumber) {
+            if ((0, number_1.toValidNumber)(val, { allowNonFiniteNumbers: true }) === null) {
+                isAllNumber = false;
+            }
+        }
+        if (isAllDate) {
+            if ((0, date_1.toValidDate)(val) === null) {
+                isAllDate = false;
+            }
+        }
+        // Fast exit if it's strictly a string column
+        if (!isAllBoolean && !isAllNumber && !isAllBigInt && !isAllDate) {
+            break;
+        }
+    }
+    const out = new Array(len);
+    if (!hasValidData || (!isAllBoolean && !isAllNumber && !isAllBigInt && !isAllDate)) {
+        for (let i = 0; i < len; i++) {
+            const val = values[i];
+            out[i] = nullValues.has(val.trim()) ? null : val;
+        }
+        return { type: datatypes_1.Utf8, values: out };
+    }
+    if (isAllBoolean) {
+        for (let i = 0; i < len; i++) {
+            const val = values[i].trim();
+            if (nullValues.has(val)) {
+                out[i] = null;
+            }
+            else {
+                const lower = val.toLowerCase();
+                out[i] = (lower === "true" || lower === "1");
+            }
+        }
+        return { type: datatypes_1.Boolean, values: out };
+    }
+    if (isAllBigInt) {
+        for (let i = 0; i < len; i++) {
+            const val = values[i].trim();
+            out[i] = nullValues.has(val) ? null : (0, number_1.toValidBigInt)(val, { truncate: false });
+        }
+        return { type: datatypes_1.Int64, values: out };
+    }
+    if (isAllNumber) {
+        for (let i = 0; i < len; i++) {
+            const val = values[i].trim();
+            out[i] = nullValues.has(val) ? null : (0, number_1.toValidNumber)(val, { allowNonFiniteNumbers: true });
+        }
+        return { type: datatypes_1.Float64, values: out };
+    }
+    if (isAllDate) {
+        for (let i = 0; i < len; i++) {
+            const val = values[i].trim();
+            out[i] = nullValues.has(val) ? null : (0, date_1.toValidDate)(val);
+        }
+        return { type: datatypes_1.Datetime, values: out };
+    }
+    return { type: datatypes_1.Utf8, values: out };
+}

package/dist/utils/date.js

@@ -18,6 +18,7 @@ exports.strftime = strftime;
 exports.strptime = strptime;
 exports.toValidDate = toValidDate;
 const number_1 = require("./number");
+const string_1 = require("./string");
 /**
  * Matches string values beginning with standard hour-and-minute formatting.
  * Examples:
@@ -129,10 +130,9 @@ function isValidDate(v) {
         return isValidDateObj(new Date(normalizeEpochToMs(Number(v))));
     }
     if (typeof v === "string") {
-        const s = v.trim();
-        if (s === "")
+        if ((0, string_1.isBlankString)(v))
             return false;
-        return isValidDateObj(new Date(s));
+        return isValidDateObj(new Date(v));
     }
     return false;
 }
@@ -339,10 +339,9 @@ function toValidDate(input) {
         return isValidDateObj(d) ? d : null;
     }
     if (typeof input === "string") {
-        const s = input.trim();
-        if (s === "")
+        if ((0, string_1.isBlankString)(input))
             return null;
-        const d = new Date(s);
+        const d = new Date(input);
         return isValidDateObj(d) ? d : null;
     }
     return null;

package/dist/utils/guards.d.ts

@@ -10,5 +10,3 @@ export declare function isScalar(v: unknown): v is string | number | boolean | b
 export declare function isValidBinary(v: unknown): v is Uint8Array | string | ArrayLike<any>;
 export declare function toValidBinary(v: unknown): Uint8Array | null;
 export declare function tryParseBoolean(v: unknown): boolean | undefined;
-export declare function isJsonString(input: unknown, allowPrimitives?: boolean): input is string;
-export declare function safeJsonParse(input: unknown): unknown;

package/dist/utils/guards.js

@@ -12,8 +12,6 @@ exports.isScalar = isScalar;
 exports.isValidBinary = isValidBinary;
 exports.toValidBinary = toValidBinary;
 exports.tryParseBoolean = tryParseBoolean;
-exports.isJsonString = isJsonString;
-exports.safeJsonParse = safeJsonParse;
 const date_1 = require("./date");
 const number_1 = require("./number");
 function isTypedArray(v) {
@@ -112,32 +110,3 @@ function tryParseBoolean(v) {
         return undefined;
     return boolMap[v.trim().toLowerCase()];
 }
-function isJsonString(input, allowPrimitives = false) {
-    if (typeof input !== "string")
-        return false;
-    const s = input.trim();
-    if (s === "")
-        return false;
-    if (!allowPrimitives) {
-        const isWrapped = (s.startsWith("{") && s.endsWith("}")) || (s.startsWith("[") && s.endsWith("]"));
-        if (!isWrapped)
-            return false;
-    }
-    try {
-        JSON.parse(s);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function safeJsonParse(input) {
-    if (typeof input !== "string")
-        return input;
-    try {
-        return JSON.parse(input);
-    }
-    catch {
-        return input;
-    }
-}

package/dist/utils/index.d.ts

@@ -3,3 +3,5 @@ export * from "./number";
 export * from "./date";
 export * from "./list";
 export * from "./string";
+export * from "./json";
+export * from "./csv";

package/dist/utils/index.js

@@ -19,3 +19,5 @@ __exportStar(require("./number"), exports);
 __exportStar(require("./date"), exports);
 __exportStar(require("./list"), exports);
 __exportStar(require("./string"), exports);
+__exportStar(require("./json"), exports);
+__exportStar(require("./csv"), exports);

package/dist/utils/json.d.ts

@@ -1,2 +1,120 @@
-export declare function isJsonString(input: unknown, allowPrimitives?: boolean): input is string;
-export declare function safeJsonParse(input: unknown): unknown;
+import type { JSONFormat } from "../types";
+export interface NDJSONParseOptions {
+    /**
+     * Skip malformed or invalid lines instead of failing the entire parse.
+     * @default false
+     */
+    skipInvalidLines?: boolean;
+    /**
+     * Maximum number of non-empty lines to validate or parse. Lines beyond this limit are ignored.
+     */
+    maxLines?: number;
+    /**
+     * Number of non-empty lines to skip at the beginning of the content.
+     * @default 0
+     */
+    skipLines?: number;
+}
+export interface JSONParseOptions {
+    /**
+     * The format of the JSON content, either "json" (standard JSON) or "ndjson" (Newline Delimited JSON).
+     * @default "json"
+     */
+    format?: JSONFormat;
+    /**
+     * Whether to allow JSON primitives (like numbers, booleans, strings, or null) instead of requiring wrapped arrays/objects.
+     * @default false
+     */
+    allowPrimitives?: boolean;
+    /**
+     * Whether to trim leading and trailing whitespace from the outermost input before validating/parsing.
+     * @default false
+     */
+    trimBeforeParse?: boolean;
+    /**
+     * A reviver function passed directly to JSON.parse for custom value transformation.
+     */
+    reviver?: Parameters<typeof JSON.parse>[1];
+    /**
+     * Options specific to NDJSON parsing. Only applicable when format is "ndjson".
+     */
+    ndjson?: NDJSONParseOptions;
+}
+export type SafeJsonParseOptions<T = unknown, F = T> = JSONParseOptions & {
+    /**
+     * A guard function to validate the shape of the parsed result. If the guard returns false,
+     * `onError` is called and the fallback (or original input) is returned.
+     */
+    guard?: ((value: unknown) => value is T) | ((value: unknown) => boolean);
+    /**
+     * Called when parsing succeeds but the guard check fails.
+     */
+    onError?: (err: unknown) => void;
+    /**
+     * A fallback value to return if parsing fails or the guard check fails.
+     * If not specified, the original input is returned.
+     */
+    fallback?: F;
+};
+/**
+ * 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.
+ */
+export declare function isJsonString(input: unknown, options?: JSONParseOptions): input is string;
+/**
+ * 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.
+ */
+export declare function safeJsonParse<T = unknown, I = unknown, F = T>(input: I, { format, allowPrimitives, trimBeforeParse, reviver, ndjson: { skipInvalidLines, maxLines, skipLines }, guard, onError, fallback }?: SafeJsonParseOptions<T, F>): T | I | F;
+export interface SafeJsonReplacerOptions {
+    /** Custom formatter function for Date objects. Ignored if onDate is specified. */
+    formatDate?: (v: Date) => string;
+    /** Convert BigInts to numeric strings ("123") or numbers if safe. Defaults to "string". */
+    bigintStrategy?: "string" | "number";
+    /** Custom serialization override for BigInt values. */
+    onBigInt?: (v: bigint) => any;
+    /** Custom serialization override for TypedArray values. */
+    onTypedArray?: (v: any) => any;
+    /** Custom serialization override for Set objects. */
+    onSet?: (v: Set<any>) => any;
+    /** Custom serialization override for Map objects. */
+    onMap?: (v: Map<any, any>) => any;
+    /** Custom serialization override for RegExp objects. */
+    onRegExp?: (v: RegExp) => any;
+    /** Custom serialization override for Date objects. Takes precedence over formatDate. */
+    onDate?: (v: Date) => any;
+    /** Custom serialization override for Error objects. Prevents empty {} strings. */
+    onError?: (v: Error) => any;
+    /** Custom serialization override for URLSearchParams objects. */
+    onURLSearchParams?: (v: URLSearchParams) => any;
+    /** Catch-all serialization override for custom types. Runs after native type checks. */
+    onCustom?: (this: any, k: string, v: any) => any;
+    /** If true, handles circular references by replacing them with a string/override instead of throwing. */
+    handleCircular?: boolean;
+    /** Custom fallback string or value when a circular reference is found. Defaults to "[Circular]" */
+    onCircular?: (this: any, k: string, v: any) => any;
+    /** If true, disables/voids the default safe serialization for BigInt values. */
+    voidBigIntReplacement?: boolean;
+    /** If true, disables/voids the default safe serialization for TypedArray values. */
+    voidTypedArrayReplacement?: boolean;
+    /** If true, disables/voids the default safe serialization for Set objects. */
+    voidSetReplacement?: boolean;
+    /** If true, disables/voids the default safe serialization for Map objects. */
+    voidMapReplacement?: boolean;
+    /** If true, disables/voids the default safe serialization for RegExp objects. */
+    voidRegExpReplacement?: boolean;
+    /** If true, disables/voids the default safe serialization for Date objects. */
+    voidDateReplacement?: boolean;
+    /** A custom replacer function or array whitelist that runs first for pre-processing keys/values. */
+    replacer?: ((this: any, k: string, v: any) => any) | (string | number)[] | null;
+}
+export declare function createSafeJsonReplacer(options?: SafeJsonReplacerOptions): (this: any, k: string, v: any) => any;