df-script 1.4.0 → 1.5.0

package/dist/utils/list.js

@@ -1,21 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toValidArray = toValidArray;
+exports.toValidStringArray = toValidStringArray;
 exports.isArrayOfType = isArrayOfType;
 exports.sortList = sortList;
 exports.getListStats = getListStats;
+exports.getUniqueListStats = getUniqueListStats;
+exports.stepSliceList = stepSliceList;
+exports.joinList = joinList;
+exports.fillSequence = fillSequence;
 const guards_1 = require("./guards");
 const date_1 = require("./date");
 const number_1 = require("./number");
+const string_1 = require("./string");
 function toValidArray(val) {
     if (val == null)
         return [];
     if (Array.isArray(val))
-        return val;
+        return [...val];
     if ((0, guards_1.isTypedArray)(val))
         return Array.from(val);
     return [val];
 }
+function toValidStringArray(val) {
+    const arr = toValidArray(val);
+    const len = arr.length;
+    const res = new Array(len);
+    for (let i = 0; i < len; i++) {
+        res[i] = String(arr[i]);
+    }
+    return res;
+}
 function isArrayOfType(arr, type, { mode = "every", allowNulls = false, allowEmpty = true } = {}) {
     if (!(0, guards_1.isArrayOrTypedArray)(arr))
         return false;
@@ -25,32 +40,59 @@ function isArrayOfType(arr, type, { mode = "every", allowNulls = false, allowEmp
             return false;
         return mode === "every";
     }
-    const check = (v) => {
-        if (v == null)
-            return allowNulls;
-        if (typeof type === "function") {
-            return (0, guards_1.isClass)(type) ? v instanceof type : type(v);
-        }
-        if (type === "date")
-            return (0, date_1.isValidDateObj)(v);
-        if (type === "object")
-            return (0, guards_1.isObj)(v);
-        if (type === "plainObject")
-            return (0, guards_1.isPlainObj)(v);
-        if (type === "number")
-            return (0, number_1.isValidNumber)(v);
-        return typeof v === type;
-    };
+    const list = arr;
+    let check;
+    if (typeof type === "function") {
+        const isC = (0, guards_1.isClass)(type);
+        check = isC
+            ? (v) => v instanceof type
+            : type;
+    }
+    else {
+        switch (type) {
+            case "null":
+                check = (v) => v === null;
+                break;
+            case "undefined":
+                check = (v) => v === undefined;
+                break;
+            case "nullish":
+                check = (v) => v == null;
+                break;
+            case "any":
+                check = () => true;
+                break;
+            case "date":
+                check = date_1.isValidDateObj;
+                break;
+            case "object":
+                check = guards_1.isObj;
+                break;
+            case "plainObject":
+                check = guards_1.isPlainObj;
+                break;
+            case "number":
+                check = number_1.isValidNumber;
+                break;
+            default:
+                check = (v) => typeof v === type;
+                break;
+        }
+    }
+    if (allowNulls) {
+        const baseCheck = check;
+        check = (v) => v == null || baseCheck(v);
+    }
     if (mode === "every") {
         for (let i = 0; i < len; i++) {
-            if (!check(arr[i]))
+            if (!check(list[i]))
                 return false;
         }
         return true;
     }
     else {
         for (let i = 0; i < len; i++) {
-            if (check(arr[i]))
+            if (check(list[i]))
                 return true;
         }
         return false;
@@ -89,6 +131,7 @@ function getListStats(arr) {
     let count = 0;
     let nullCount = 0;
     let total = 0;
+    let sumCompensation = 0;
     let mean = 0;
     let M2 = 0;
     for (let i = 0; i < len; i++) {
@@ -103,7 +146,15 @@ function getListStats(arr) {
             maxVal = val;
         const n = (0, number_1.toValidNumber)(val);
         if (n !== null) {
-            total += n;
+            // Neumaier sum
+            const t = total + n;
+            if (Math.abs(total) >= Math.abs(n)) {
+                sumCompensation += (total - t) + n;
+            }
+            else {
+                sumCompensation += (n - t) + total;
+            }
+            total = t;
             count++;
             const delta = n - mean;
             mean += delta / count;
@@ -113,11 +164,11 @@ function getListStats(arr) {
     }
     const variance = count > 1 ? M2 / (count - 1) : 0;
     return {
-        sum: count > 0 ? total : null,
+        sum: count > 0 ? total + sumCompensation : null,
         count,
         min: minVal,
         max: maxVal,
-        mean: count > 0 ? total / count : null,
+        mean: count > 0 ? (total + sumCompensation) / count : null,
         variance,
         std: Math.sqrt(variance),
         nullCount,
@@ -126,3 +177,185 @@ function getListStats(arr) {
         isNumeric: count > 0 && count === (len - nullCount)
     };
 }
+function getUniqueListStats(arr, { strict = false, keySelector } = {}) {
+    const list = Array.from(arr);
+    const frequencies = new Map();
+    if (strict) {
+        const selector = keySelector ?? string_1.toCanonicalString;
+        const seen = new Map();
+        const len = list.length;
+        for (let i = 0; i < len; i++) {
+            const val = list[i];
+            const key = selector(val);
+            const entry = seen.get(key);
+            if (entry === undefined) {
+                seen.set(key, { val, count: 1 });
+            }
+            else {
+                entry.count++;
+            }
+        }
+        const values = [];
+        for (const entry of seen.values()) {
+            values.push(entry.val);
+        }
+        for (let i = 0; i < len; i++) {
+            const val = list[i];
+            const key = selector(val);
+            const entry = seen.get(key);
+            frequencies.set(val, entry.count);
+        }
+        return {
+            values,
+            count: values.length,
+            frequencies
+        };
+    }
+    const len = list.length;
+    for (let i = 0; i < len; i++) {
+        const val = list[i];
+        frequencies.set(val, (frequencies.get(val) ?? 0) + 1);
+    }
+    return {
+        values: Array.from(frequencies.keys()),
+        count: frequencies.size,
+        frequencies
+    };
+}
+function stepSliceList(arr, { step = 1, offsetStart = 0, offsetEnd, maxItemsGathered, null_on_oob = true } = {}) {
+    if (arr == null) {
+        return null;
+    }
+    if (maxItemsGathered !== undefined && maxItemsGathered <= 0) {
+        return [];
+    }
+    if (step === 0) {
+        throw new Error("Step size step cannot be zero");
+    }
+    const len = arr.length;
+    const isOob = len === 0
+        ? (offsetStart !== 0)
+        : (offsetStart >= len || offsetStart < -len);
+    if (isOob) {
+        if (!null_on_oob) {
+            throw new Error(`Start offset ${offsetStart} is out of bounds for list of length ${len}`);
+        }
+        return null;
+    }
+    const start = offsetStart < 0 ? len + offsetStart : offsetStart;
+    const end = offsetEnd !== undefined
+        ? (offsetEnd < 0 ? len + offsetEnd : offsetEnd)
+        : (step > 0 ? len : -1);
+    const res = [];
+    if (step > 0) {
+        for (let i = start; i < end && i < len; i += step) {
+            if (i >= 0) {
+                res.push(arr[i]);
+                if (maxItemsGathered !== undefined && res.length >= maxItemsGathered) {
+                    break;
+                }
+            }
+        }
+    }
+    else {
+        for (let i = start; i > end && i >= 0; i += step) {
+            if (i < len) {
+                res.push(arr[i]);
+                if (maxItemsGathered !== undefined && res.length >= maxItemsGathered) {
+                    break;
+                }
+            }
+        }
+    }
+    return res;
+}
+/**
+ * Joins the elements of an array-like structure into a string using a separator.
+ * Excludes nullish checks and formats nested arrays cleanly.
+ */
+function joinList(arr, separator = ",", { ignoreNulls = false, nullValue = "", prefix = "", suffix = "", limit, truncationMarker = "...", valueFormatter } = {}) {
+    const len = arr.length;
+    const strList = [];
+    const maxLimit = limit !== undefined ? Math.max(0, limit) : len;
+    let truncated = false;
+    for (let i = 0; i < len; i++) {
+        if (strList.length >= maxLimit) {
+            truncated = true;
+            break;
+        }
+        const x = arr[i];
+        if (x != null) {
+            strList.push(valueFormatter ? valueFormatter(x, i) : String(x));
+        }
+        else if (!ignoreNulls) {
+            strList.push(nullValue);
+        }
+    }
+    return prefix + strList.join(separator) + (truncated ? truncationMarker : "") + suffix;
+}
+function fillSequence(targetArray, initialValue, options = {}) {
+    const len = targetArray.length;
+    const { mode = "cumulative", step = 1, coerce = (v) => v, condition, reverse = false, startIndex = reverse ? len - 1 : 0, endIndex = reverse ? -1 : len } = options;
+    const increment = reverse ? -1 : 1;
+    const start = startIndex;
+    const end = endIndex;
+    const writeVal = (idx, val) => {
+        if (!condition || condition(targetArray[idx], idx, targetArray)) {
+            targetArray[idx] = coerce(val);
+        }
+    };
+    if (mode === "constant") {
+        const finalVal = coerce(initialValue);
+        for (let i = start; reverse ? i > end : i < end; i += increment) {
+            writeVal(i, finalVal);
+        }
+    }
+    else if (mode === "independent") {
+        if (typeof step === "function") {
+            let relativeIdx = 0;
+            for (let i = start; reverse ? i > end : i < end; i += increment) {
+                writeVal(i, step({
+                    index: relativeIdx,
+                    initialValue,
+                    originalValue: targetArray[i],
+                    absoluteIndex: i,
+                    targetArray
+                }));
+                relativeIdx++;
+            }
+        }
+        else {
+            for (let i = start; reverse ? i > end : i < end; i += increment) {
+                writeVal(i, initialValue + i * step);
+            }
+        }
+    }
+    else {
+        // cumulative mode
+        let current = initialValue;
+        let isFirst = true;
+        let relativeIdx = 0;
+        for (let i = start; reverse ? i > end : i < end; i += increment) {
+            if (isFirst) {
+                writeVal(i, current);
+                isFirst = false;
+            }
+            else {
+                if (typeof step === "function") {
+                    current = step({
+                        prev: current,
+                        index: relativeIdx,
+                        originalValue: targetArray[i],
+                        absoluteIndex: i,
+                        targetArray
+                    });
+                }
+                else {
+                    current = current + step;
+                }
+                writeVal(i, current);
+            }
+            relativeIdx++;
+        }
+    }
+}

package/dist/utils/number.d.ts

@@ -1,24 +1,32 @@
-export declare function isValidNumber(v: unknown): v is number;
-export declare function toValidNumber(v: unknown): number | null;
-export declare function clamp<T extends number | bigint>(opts: {
-    val: T;
-    min: T;
-    max: T;
-}): T;
+export interface NumericValidationOptions {
+    allowNonFiniteNumbers?: boolean;
+}
+export declare function isValidNumber(v: unknown, options?: NumericValidationOptions): v is number;
+export declare function toValidNumber(v: unknown, options?: NumericValidationOptions): number | null;
+export interface NumericFormatOptions extends Intl.NumberFormatOptions {
+    /** BCP 47 language tag (e.g., 'en-US' for dot, 'de-DE' for comma). Defaults to 'en-US'. */
+    locale?: string;
+    /** If true, formats negative numbers in parentheses e.g. (1.23) instead of -1.23. */
+    accountingNegatives?: boolean;
+    /** Fallback string if the value cannot be parsed into a formatable number. */
+    fallback?: string;
+}
+/**
+ * Formats any numeric value (number, bigint, numeric string, Date, etc.) for output,
+ * handling NaN, Infinity, scientific notation, precision, and accounting formats.
+ */
+export declare function formatNumber({ locale, accountingNegatives, fallback, ...intlOpts }?: NumericFormatOptions): (value: unknown) => string;
 export type FloatPrecision = "Float32" | "Float64";
-export declare const FLOAT_32_BOUNDARY = 3.4028234663852886e+38;
-export declare const FLOAT_RANGES: {
-    readonly Float32: {
-        readonly min: number;
-        readonly max: 3.4028234663852886e+38;
-    };
-    readonly Float64: {
-        readonly min: number;
-        readonly max: number;
-    };
-};
-export declare function isValidFloat(v: unknown, precision?: FloatPrecision): boolean;
-export declare function toValidFloat(v: unknown, precision?: FloatPrecision): number | null;
+export interface FloatOptions extends NumericValidationOptions {
+    floatPrecision?: FloatPrecision;
+    /**
+     * When true, explicitly accepts scientific notation strings (e.g. "1.23e+4").
+     * The result is still validated against the precision range.
+     */
+    floatScientific?: boolean;
+}
+export declare function isValidFloat(v: unknown, { floatPrecision, allowNonFiniteNumbers, floatScientific }?: FloatOptions): boolean;
+export declare function toValidFloat(v: unknown, { floatPrecision, allowNonFiniteNumbers, floatScientific }?: FloatOptions): number | null;
 export declare const INT_RANGES: {
     readonly Int8: {
         readonly min: -128;
@@ -50,6 +58,13 @@ export type IntRange = {
     min: number;
     max: number;
 } | IntRangeType;
+export type IntCoerceType = "round" | "floor" | "ceil" | "truncate";
+export interface IntOptions {
+    range?: IntRange;
+    coerce?: IntCoerceType;
+}
+export declare function isValidInt(v: unknown, range?: IntRange): v is number;
+export declare function toValidInt(v: unknown, { range, coerce }?: IntOptions): number | null;
 export declare const BIGINT_RANGES: {
     readonly Int64: {
         readonly min: -9223372036854775808n;
@@ -65,22 +80,40 @@ export type BigIntRange = {
     min: bigint;
     max: bigint;
 } | BigIntRangeType;
-export type IntCoerceType = "round" | "floor" | "ceil" | "truncate";
-export interface IntOptions {
-    coerce?: IntCoerceType;
+export interface BigIntOptions {
+    range?: BigIntRange;
+    truncate?: boolean;
 }
-export declare function isValidInt(v: unknown, range?: IntRange): v is number;
 export declare function isValidBigInt(v: unknown, range?: BigIntRange): v is bigint;
-export declare function toValidInt(v: unknown, range?: IntRange, opts?: IntOptions): number | null;
-export declare function toValidBigInt(v: unknown, range?: BigIntRange): bigint | null;
+export declare function toValidBigInt(v: unknown, { range, truncate }?: BigIntOptions): bigint | null;
 export interface DecimalOptions {
     precision?: number;
     scale?: number;
 }
-export declare function isValidDecimal(v: unknown, opts?: DecimalOptions): boolean;
-export declare function toValidDecimal(v: unknown, opts?: DecimalOptions): number | null;
+export declare function isValidDecimal(v: unknown, { precision, scale }?: DecimalOptions): boolean;
+export declare function toValidDecimal(v: unknown, { precision, scale }?: DecimalOptions): number | null;
+export declare function clamp<T extends number | bigint>(val: T, { min, max, safe }?: {
+    min?: T | null;
+    max?: T | null;
+    safe?: boolean;
+}): T;
 /**
  * Creates a seedable pseudo-random number generator using the Mulberry32 PRNG algorithm.
  * Returns a function that generates a pseudo-random float in the range [0, 1).
  */
 export declare function mulberry32(seed: number): () => number;
+/**
+ * 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;