df-script 1.4.0 → 1.6.0

package/dist/utils/array.d.ts

@@ -0,0 +1,217 @@
+import type { AnyTypedArray } from "../types";
+export declare function isTypedArray(v: unknown): v is AnyTypedArray;
+export declare function isArrayOrTypedArray(v: unknown): v is any[] | AnyTypedArray;
+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;
+    allowNulls?: boolean;
+    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 interface SortArrayOptions {
+    descending?: boolean;
+    nullsLast?: boolean;
+}
+export declare function sortArray(arr: unknown, { descending, nullsLast }?: SortArrayOptions): any[];
+export declare function getArrayStats(arr: unknown): {
+    sum: number | null;
+    count: number;
+    min: any;
+    max: any;
+    mean: number | null;
+    variance: number;
+    std: number;
+    nullCount: number;
+    len: number;
+    hasNulls: boolean;
+    isNumeric: boolean;
+};
+/**
+ * Options configuration for the `getUniqueArrayStats` utility.
+ */
+export interface UniqueArrayStatsOptions {
+    /**
+     * 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 getUniqueArrayStats(arr: ArrayLike<any>, { strict, keySelector }?: UniqueArrayStatsOptions): {
+    values: any[];
+    count: number;
+    frequencies: Map<any, number>;
+};
+/**
+ * Options configuration for the `stepSliceArray` utility.
+ */
+export interface StepSliceArrayOptions {
+    /**
+     * The step size to slice the array 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 array.
+     * 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 stepSliceArray<T>(arr: ArrayLike<T>, { step, offsetStart, offsetEnd, maxItemsGathered, null_on_oob }?: StepSliceArrayOptions): T[] | null;
+/**
+ * Options configuration for the `joinArray` utility.
+ */
+export interface JoinArrayOptions {
+    /**
+     * 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 array 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 array 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 joinArray(arr: ArrayLike<any>, separator?: string, { ignoreNulls, nullValue, prefix, suffix, limit, truncationMarker, valueFormatter }?: JoinArrayOptions): 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;
+/**
+ * Computes the median of a numeric array, filtering out non-numeric and NaN values.
+ * Returns null if no valid numbers remain.
+ */
+export declare function computeMedian(values: ArrayLike<any>): number | null;
+/**
+ * Computes the quantile of a numeric array using linear interpolation, filtering out non-numeric and NaN values.
+ * q must be in [0, 1]. Returns null if no valid numbers remain or q is out of bounds.
+ */
+export declare function computeQuantile(values: ArrayLike<any>, q: number): number | null;
+/**
+ * Computes the mode(s) of an array, filtering out null/undefined values.
+ * Returns an array of the most frequent values, sorted, or null if empty/no mode.
+ */
+export declare function computeMode(values: ArrayLike<any>): any[] | null;

package/dist/utils/binary.d.ts

@@ -0,0 +1,3 @@
+import type { AnyTypedArray } from "../types";
+export declare function isValidBinary(v: unknown): v is string | any[] | AnyTypedArray;
+export declare function toValidBinary(v: unknown): Uint8Array | null;

package/dist/utils/csv.d.ts

@@ -0,0 +1,77 @@
+import type { ColumnDict } from "../types";
+import { type SafeJsonReplacerOptions } from "./json";
+import { type NumericFormatOptions } from "./number";
+import { DataType } from "../datatypes";
+import type { ReadCSVOptions } from "../dataframe/types";
+export interface FormatCSVValueOptions {
+    /**
+     * The string representation to use for null/missing values.
+     * @default ""
+     */
+    nullValue?: string;
+    /**
+     * Custom format string for Date values (e.g. "%Y-%m-%d").
+     */
+    dateFormat?: string;
+    /**
+     * Custom format string for Time values (e.g. "%H:%M:%S").
+     */
+    timeFormat?: string;
+    /**
+     * Custom format string for Datetime values (e.g. "%Y-%m-%d %H:%M:%S").
+     */
+    datetimeFormat?: string;
+    /**
+     * Options for numeric formatting (floats, ints, bigints).
+     */
+    numericFormatOptions?: NumericFormatOptions;
+    /**
+     * Options for the safe JSON replacer used when formatting objects/arrays.
+     */
+    replacerOptions?: SafeJsonReplacerOptions;
+}
+export interface WriteCSVOptions extends FormatCSVValueOptions {
+    /**
+     * Whether to write the header row.
+     * @default true
+     */
+    includeHeader?: boolean;
+    /**
+     * Character that separates fields.
+     * @default ","
+     */
+    separator?: string;
+    /**
+     * The string used to end each row.
+     * @default "\n"
+     */
+    lineTerminator?: string;
+    /**
+     * The character used for quoting fields.
+     * @default '"'
+     */
+    quoteChar?: string;
+    /**
+     * Defines when to use quotes.
+     * - "necessary": Quotes only when required (e.g., value contains separator, quote_char, or newlines).
+     * - "always": Quotes every field.
+     * - "never": Never quotes fields.
+     * - "non_numeric": Quotes all fields that are non-numeric.
+     * @default "necessary"
+     */
+    quoteStyle?: "necessary" | "always" | "never" | "non_numeric";
+    /**
+     * Whether to include a Byte Order Mark (BOM) at the start of the file.
+     * @default false
+     */
+    includeBom?: boolean;
+}
+export declare function formatCsvValue(options?: FormatCSVValueOptions): (val: any) => string;
+export declare function stringifyCSV(columns: ColumnDict, height: number, options?: WriteCSVOptions & {
+    onRow?: (rowStr: string) => void;
+}): string;
+export declare function parseCSV(content: string, options?: ReadCSVOptions): string[][];
+export declare function inferAndCoerceCSVColumn(values: string[], options?: ReadCSVOptions): {
+    type: DataType;
+    values: any[];
+};

package/dist/utils/date.d.ts

@@ -5,7 +5,7 @@ import type { TimeUnit } from "../types";
  * - "12:34" (matches "12:34")
  * - "10:37:16.123" (matches "10:37")
  * - "2026-05-25" (does not match)
- */
+ * */
 export declare const TIME_PREFIX_REGEX: RegExp;
 /**
  * Matches timezone offset indicators at the end of a string.
@@ -18,40 +18,26 @@ export declare const TIME_PREFIX_REGEX: RegExp;
  */
 export declare const ZONE_OFFSET_REGEX: RegExp;
 /**
- * Matches only UTC offset indicators at the end of a string.
+ * Matches strict ISO 8601 date-only format (YYYY-MM-DD).
  * Examples:
- * - "12:34:56Z" (matches "Z")
- * - "12:34:56+00:00" (matches "+00:00")
- * - "12:34:56-0000" (matches "-0000")
- * - "12:34:56+02:00" (does not match)
+ * - "2026-05-25" (matches)
+ * - "2026-05-25T10:37:16Z" (does not match)
  */
-export declare const UTC_INDICATOR_REGEX: RegExp;
-export declare const MS_PER_SECOND = 1000;
-export declare const MS_PER_MINUTE = 60000;
-export declare const MS_PER_HOUR = 3600000;
-export declare const MS_PER_DAY = 86400000;
-export declare const US_PER_MS = 1000;
-export declare const NS_PER_MS = 1000000;
-export interface UtcOffsetResult {
-    timeZoneTime: Date;
-    utcTime: Date;
-    offset: number;
-    formatted: string;
-}
-export declare function toEpoch(d: Date, unit?: TimeUnit): number;
-export declare function getCentury(d: Date): number;
-export declare function getISOWeek(d: Date): number;
-export declare function getMillennium(d: Date): number;
-export declare function getMonthOffset(d: Date, monthOffset: number, day?: number): Date;
-export declare function getOrdinalDay(d: Date): number;
-export declare function getQuarter(d: Date): number;
-export declare function getUtcOffset(timeZone: string): UtcOffsetResult;
+export declare const ISO_DATE_ONLY_REGEX: RegExp;
+export declare function toValidDate(input: unknown, options?: {
+    dateOnly?: boolean;
+}): Date | null;
+export declare function toValidTime(val: unknown): string | null;
+export declare function toEpoch(d: Date, unit?: TimeUnit): number | bigint;
+export declare function normalizeEpochToMs(n: number | bigint): number;
+export declare function getCentury(d: Date): number | null;
+export declare function getISOWeek(d: Date): number | null;
+export declare function getMillennium(d: Date): number | null;
+export declare function getMonthOffset(d: Date, monthOffset: number, day?: number): Date | null;
+export declare function getOrdinalDay(d: Date): number | null;
+export declare function getQuarter(d: Date): number | null;
 export declare function isLeapYear(yOrDate: number | Date): boolean;
-export declare function isUtcString(timestamp: string | null | undefined): boolean;
-export declare function isValidDate(v: unknown): v is string | number | bigint | Date;
-export declare function isValidDateObj(d: unknown): d is Date;
-export declare function normalizeEpochToMs(n: number): number;
-export declare const STRFTIME_DIRECTIVES: readonly ["%ms", "%f", "%Y", "%y", "%m", "%d", "%e", "%H", "%I", "%p", "%M", "%S", "%A", "%a", "%B", "%b", "%h", "%j", "%u", "%w", "%Z", "%z"];
-export declare function strftime(d: Date, format: string, locale?: string): string;
-export declare function strptime(str: string, format: string, strict?: boolean): Date | null;
-export declare function toValidDate(input: unknown): Date | null;
+export declare const FORMAT_REGEX: RegExp;
+export declare function expandFormatShorthands(format: string): string;
+export declare function strftime(d: Date, format: string, locale?: string, timeZone?: string): string;
+export declare function strptime(str: string, format: string, strict?: boolean, defaultTimeZone?: string): Date | null;

package/dist/utils/guards.d.ts

@@ -1,14 +1,13 @@
-export declare function isTypedArray(v: unknown): v is ArrayBufferView;
-export declare function isArrayOrTypedArray(v: unknown): v is ArrayLike<any> & Iterable<any>;
-export declare function isNonEmptyArray<T = unknown>(arr: unknown): arr is ArrayLike<T>;
-export declare function isNonEmptyArrayObjs<T extends object>(arr: unknown): arr is T[];
-export declare function isNonEmptyObj(v: unknown): v is Record<string, unknown>;
-export declare function isObj(v: unknown): v is Record<string, unknown>;
-export declare function isPlainObj(v: unknown): v is Record<string, unknown>;
+import type { ValidScalarTypes } from "../types";
+/** Array Guards **/
+export type AnyTypedArray = ArrayBufferView & ArrayLike<number | bigint> & Iterable<number | bigint>;
+export declare function isTypedArray(v: unknown): v is AnyTypedArray;
+export declare function isArrayOrTypedArray(v: unknown): v is any[] | AnyTypedArray;
+export declare function isObj(v: unknown): v is Record<PropertyKey, unknown>;
+export declare function isPlainObj(v: unknown): v is Record<PropertyKey, unknown>;
+/** Class Guards **/
 export declare function isClass(v: unknown): v is new (...args: any[]) => any;
-export declare function isScalar(v: unknown): v is string | number | boolean | bigint | Date | Uint8Array;
-export declare function isValidBinary(v: unknown): v is Uint8Array | string | ArrayLike<any>;
+/** Scalar & Conversion Guards **/
+export declare function isScalar<V>(v: V): v is Extract<V, Exclude<ValidScalarTypes, null | undefined>>;
+export declare function isValidBinary(v: unknown): v is string | any[] | AnyTypedArray;
 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/index.d.ts

@@ -1,5 +1,8 @@
-export * from "./guards";
+export * from "./object";
 export * from "./number";
 export * from "./date";
-export * from "./list";
+export * from "./array";
 export * from "./string";
+export * from "./json";
+export * from "./csv";
+export * from "./binary";

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;