df-script 1.4.0 → 1.5.0

package/dist/utils/number.js

@@ -1,32 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BIGINT_RANGES = exports.INT_RANGES = exports.FLOAT_RANGES = exports.FLOAT_32_BOUNDARY = void 0;
+exports.BIGINT_RANGES = exports.INT_RANGES = void 0;
 exports.isValidNumber = isValidNumber;
 exports.toValidNumber = toValidNumber;
-exports.clamp = clamp;
+exports.formatNumber = formatNumber;
 exports.isValidFloat = isValidFloat;
 exports.toValidFloat = toValidFloat;
 exports.isValidInt = isValidInt;
-exports.isValidBigInt = isValidBigInt;
 exports.toValidInt = toValidInt;
+exports.isValidBigInt = isValidBigInt;
 exports.toValidBigInt = toValidBigInt;
 exports.isValidDecimal = isValidDecimal;
 exports.toValidDecimal = toValidDecimal;
+exports.clamp = clamp;
 exports.mulberry32 = mulberry32;
+exports.computeMedian = computeMedian;
+exports.computeQuantile = computeQuantile;
+exports.computeMode = computeMode;
+const guards_1 = require("./guards");
+const list_1 = require("./list");
 const NUMERIC_CLEAN_REGEX = /[,\s_]/g;
 const VALID_DECIMAL_REGEX = /^[+-]?\d+(?:\.\d+)?$/;
-// ============================================================================
-// /** Generic Number Helpers */
-// ============================================================================
-function isValidNumber(v) {
-    return typeof v === "number" && !Number.isNaN(v) && Number.isFinite(v);
+function isValidNumber(v, options) {
+    if (typeof v !== "number")
+        return false;
+    if (options && options.allowNonFiniteNumbers)
+        return true;
+    return !Number.isNaN(v) && Number.isFinite(v);
 }
-function toValidNumber(v) {
+function toValidNumber(v, options) {
     if (v == null)
         return null;
     if (typeof v === "symbol")
         return null;
-    if (isValidNumber(v)) {
+    if (isValidNumber(v, options)) {
         return v;
     }
     if (typeof v === "boolean") {
@@ -34,51 +41,104 @@ function toValidNumber(v) {
     }
     if (typeof v === "bigint") {
         const n = Number(v);
-        return isValidNumber(n) ? n : null;
+        return isValidNumber(n, options) ? n : null;
     }
     if (v instanceof Date) {
         const t = v.getTime();
-        return isValidNumber(t) ? t : null;
+        return isValidNumber(t, options) ? t : null;
     }
     if (typeof v === "string") {
         const clean = v.trim().replace(NUMERIC_CLEAN_REGEX, "");
         if (clean === "")
             return null;
         const n = Number(clean);
-        return isValidNumber(n) ? n : null;
+        if (Number.isNaN(n)) {
+            if (options?.allowNonFiniteNumbers && clean.toLowerCase() === "nan") {
+                return NaN;
+            }
+            return null;
+        }
+        return isValidNumber(n, options) ? n : null;
     }
     return null;
 }
-function clamp(opts) {
-    const { val, min, max } = opts;
-    if (val < min)
-        return min;
-    if (val > max)
-        return max;
-    return val;
+/**
+ * Formats any numeric value (number, bigint, numeric string, Date, etc.) for output,
+ * handling NaN, Infinity, scientific notation, precision, and accounting formats.
+ */
+function formatNumber({ locale = "en-US", accountingNegatives = false, fallback = "NaN", ...intlOpts } = {}) {
+    if (intlOpts.useGrouping === undefined) {
+        intlOpts.useGrouping = false;
+    }
+    if (intlOpts.maximumFractionDigits === undefined && intlOpts.maximumSignificantDigits === undefined) {
+        intlOpts.maximumFractionDigits = 20;
+    }
+    const formatter = new Intl.NumberFormat(locale, intlOpts);
+    return (value) => {
+        if (typeof value === "bigint") {
+            if (accountingNegatives && value < 0n) {
+                return `(${formatter.format(-value)})`;
+            }
+            return formatter.format(value);
+        }
+        const num = toValidNumber(value, { allowNonFiniteNumbers: true });
+        if (num === null || Number.isNaN(num)) {
+            return fallback;
+        }
+        if (!Number.isFinite(num)) {
+            if (accountingNegatives && num === -Infinity) {
+                return "(Infinity)";
+            }
+            return String(num);
+        }
+        if (accountingNegatives && num < 0) {
+            return `(${formatter.format(Math.abs(num))})`;
+        }
+        return formatter.format(num);
+    };
 }
-exports.FLOAT_32_BOUNDARY = 3.4028234663852886e+38;
-exports.FLOAT_RANGES = {
-    Float32: { min: -exports.FLOAT_32_BOUNDARY, max: exports.FLOAT_32_BOUNDARY },
-    Float64: { min: -Number.MAX_VALUE, max: Number.MAX_VALUE }
-};
-function isValidFloat(v, precision) {
-    if (!isValidNumber(v))
+function isValidFloat(v, { floatPrecision, allowNonFiniteNumbers = false, floatScientific = false } = {}) {
+    let num;
+    if (typeof v === "number") {
+        num = v;
+    }
+    else if (floatScientific && typeof v === "string") {
+        const parsed = parseFloat(v);
+        if (Number.isNaN(parsed))
+            return false;
+        num = parsed;
+    }
+    else {
+        return false;
+    }
+    if (floatPrecision === "Float32") {
+        num = Math.fround(num);
+    }
+    if (!allowNonFiniteNumbers && (Number.isNaN(num) || !Number.isFinite(num))) {
         return false;
-    if (precision) {
-        const limits = exports.FLOAT_RANGES[precision];
-        return v >= limits.min && v <= limits.max;
     }
     return true;
 }
-function toValidFloat(v, precision = "Float64") {
-    const num = toValidNumber(v);
+function toValidFloat(v, { floatPrecision = "Float64", allowNonFiniteNumbers = true, floatScientific = false } = {}) {
+    let num = toValidNumber(v, { allowNonFiniteNumbers });
+    if (num === null && floatScientific && typeof v === "string") {
+        const parsed = parseFloat(v);
+        if (isValidNumber(parsed, { allowNonFiniteNumbers })) {
+            num = parsed;
+        }
+    }
     if (num === null)
         return null;
-    return precision === "Float32" ? Math.fround(num) : num;
+    if (floatPrecision === "Float32") {
+        num = Math.fround(num);
+    }
+    if (!allowNonFiniteNumbers && !Number.isFinite(num)) {
+        return null;
+    }
+    return num;
 }
 // ============================================================================
-// /** Integer & BigInt Functions */
+// /** Integer Functions */
 // ============================================================================
 exports.INT_RANGES = {
     Int8: { min: -128, max: 127 },
@@ -88,10 +148,6 @@ exports.INT_RANGES = {
     UInt16: { min: 0, max: 65535 },
     UInt32: { min: 0, max: 4294967295 }
 };
-exports.BIGINT_RANGES = {
-    Int64: { min: -9223372036854775808n, max: 9223372036854775807n },
-    UInt64: { min: 0n, max: 18446744073709551615n }
-};
 function isValidInt(v, range) {
     if (!isValidNumber(v))
         return false;
@@ -102,20 +158,11 @@ function isValidInt(v, range) {
     const limits = typeof range === "string" ? exports.INT_RANGES[range] : range;
     return v >= limits.min && v <= limits.max;
 }
-function isValidBigInt(v, range) {
-    if (typeof v !== "bigint")
-        return false;
-    if (!range)
-        return true;
-    const limits = typeof range === "string" ? exports.BIGINT_RANGES[range] : range;
-    return v >= limits.min && v <= limits.max;
-}
-function toValidInt(v, range = "Int32", opts = {}) {
+function toValidInt(v, { range = "Int32", coerce = "truncate" } = {}) {
     const num = toValidNumber(v);
     if (num === null)
         return null;
     let n = num;
-    const coerce = opts.coerce || "truncate";
     switch (coerce) {
         case "round":
             n = Math.round(n);
@@ -131,9 +178,24 @@ function toValidInt(v, range = "Int32", opts = {}) {
             break;
     }
     const limits = typeof range === "string" ? exports.INT_RANGES[range] : range;
-    return clamp({ val: n, min: limits.min, max: limits.max });
+    return clamp(n, { min: limits.min, max: limits.max });
+}
+// ============================================================================
+// /** BigInt Functions */
+// ============================================================================
+exports.BIGINT_RANGES = {
+    Int64: { min: -9223372036854775808n, max: 9223372036854775807n },
+    UInt64: { min: 0n, max: 18446744073709551615n }
+};
+function isValidBigInt(v, range) {
+    if (typeof v !== "bigint")
+        return false;
+    if (!range)
+        return true;
+    const limits = typeof range === "string" ? exports.BIGINT_RANGES[range] : range;
+    return v >= limits.min && v <= limits.max;
 }
-function toValidBigInt(v, range = "Int64") {
+function toValidBigInt(v, { range = "Int64", truncate = false } = {}) {
     if (v == null)
         return null;
     if (typeof v === "symbol")
@@ -150,64 +212,104 @@ function toValidBigInt(v, range = "Int64") {
         if (clean === "")
             return null;
         if (!VALID_DECIMAL_REGEX.test(clean)) {
-            const num = toValidNumber(v);
+            const num = toValidNumber(clean);
             if (num === null)
                 return null;
+            if (!truncate && !Number.isInteger(num))
+                return null;
             bigintVal = BigInt(Math.trunc(num));
         }
         else {
-            bigintVal = BigInt(clean.split(".")[0]);
+            if (!truncate && clean.includes("."))
+                return null;
+            const dotIdx = clean.indexOf(".");
+            bigintVal = BigInt(dotIdx !== -1 ? clean.slice(0, dotIdx) : clean);
         }
     }
     else {
         const num = toValidNumber(v);
         if (num === null)
             return null;
+        if (!truncate && !Number.isInteger(num))
+            return null;
         bigintVal = BigInt(Math.trunc(num));
     }
     const limits = typeof range === "string" ? exports.BIGINT_RANGES[range] : range;
-    return clamp({ val: bigintVal, min: limits.min, max: limits.max });
+    return clamp(bigintVal, { min: limits.min, max: limits.max });
+}
+function getDecimalMaxVal(precision, scale) {
+    const integerDigits = precision - scale;
+    const maxVal = Math.pow(10, integerDigits) - Math.pow(10, -scale);
+    return maxVal > 0 ? maxVal : null;
 }
-function isValidDecimal(v, opts = {}) {
+function roundToScale(v, scale) {
+    const str = v.toString();
+    if (str.includes("e")) {
+        const factor = Math.pow(10, scale);
+        return Math.round(v * factor) / factor;
+    }
+    return Number(Math.round(Number(str + "e" + scale)) + "e-" + scale);
+}
+function isValidDecimal(v, { precision, scale = 0 } = {}) {
     if (!isValidNumber(v))
         return false;
-    const { precision, scale = 0 } = opts;
     if (precision !== undefined) {
-        const integerDigits = precision - scale;
-        const maxVal = Math.pow(10, integerDigits) - Math.pow(10, -scale);
-        if (integerDigits > 0 && Math.abs(v) > maxVal) {
+        const maxVal = getDecimalMaxVal(precision, scale);
+        if (maxVal !== null && Math.abs(v) > maxVal) {
             return false;
         }
     }
     if (scale !== undefined) {
-        const str = v.toString();
-        const dotIdx = str.indexOf(".");
-        if (dotIdx !== -1 && str.slice(dotIdx + 1).length > scale) {
+        const rounded = roundToScale(v, scale);
+        if (Math.abs(v - rounded) > 1e-12) {
             return false;
         }
     }
     return true;
 }
-function toValidDecimal(v, opts = {}) {
+function toValidDecimal(v, { precision, scale } = {}) {
     const num = toValidNumber(v);
     if (num === null)
         return null;
-    const { precision, scale } = opts;
     let n = num;
     if (scale !== undefined) {
-        const multiplier = Math.pow(10, scale);
-        n = Math.round(n * multiplier) / multiplier;
+        n = roundToScale(n, scale);
     }
     if (precision !== undefined) {
-        const scaleVal = scale || 0;
-        const integerDigits = precision - scaleVal;
-        if (integerDigits > 0) {
-            const maxVal = Math.pow(10, integerDigits) - Math.pow(10, -scaleVal);
-            n = clamp({ val: n, min: -maxVal, max: maxVal });
+        const scaleVal = scale ?? 0;
+        const maxVal = getDecimalMaxVal(precision, scaleVal);
+        if (maxVal !== null) {
+            n = clamp(n, { min: -maxVal, max: maxVal });
         }
     }
     return n;
 }
+// ============================================================================
+// /** Math & Stats Functions */
+// ============================================================================
+function clamp(val, { min = null, max = null, safe = true } = {}) {
+    if (min !== null && max !== null && min > max) {
+        return min;
+    }
+    let v = val;
+    if (safe && typeof v === "number") {
+        if (Number.isNaN(v)) {
+            // NaN can't be compared — coerce to the nearest boundary, preferring min
+            v = min !== null ? min : (max !== null ? max : val);
+        }
+        else if (v === Infinity) {
+            v = max !== null ? max : val;
+        }
+        else if (v === -Infinity) {
+            v = min !== null ? min : val;
+        }
+    }
+    if (min !== null && v < min)
+        return min;
+    if (max !== null && v > max)
+        return max;
+    return v;
+}
 /**
  * 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).
@@ -221,3 +323,79 @@ function mulberry32(seed) {
         return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     };
 }
+function getSortedValidNumbers(values) {
+    const len = values.length;
+    let validCount = 0;
+    const nums = new Float64Array(len);
+    for (let i = 0; i < len; i++) {
+        const val = values[i];
+        // Only include actual numbers that aren't NaN (but preserve Infinity for bounds)
+        if (typeof val === "number" && !Number.isNaN(val)) {
+            nums[validCount++] = val;
+        }
+    }
+    if (validCount === 0)
+        return null;
+    const validNums = nums.subarray(0, validCount);
+    validNums.sort();
+    return validNums;
+}
+/**
+ * Computes the median of a numeric array, filtering out non-numeric and NaN values.
+ * Returns null if no valid numbers remain.
+ */
+function computeMedian(values) {
+    const validNums = getSortedValidNumbers(values);
+    if (!validNums)
+        return null;
+    const len = validNums.length;
+    const mid = Math.floor(len / 2);
+    return len % 2 !== 0 ? validNums[mid] : (validNums[mid - 1] + validNums[mid]) / 2;
+}
+/**
+ * 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.
+ */
+function computeQuantile(values, q) {
+    if (q < 0 || q > 1)
+        return null;
+    const validNums = getSortedValidNumbers(values);
+    if (!validNums)
+        return null;
+    const len = validNums.length;
+    const idx = q * (len - 1);
+    const low = Math.floor(idx);
+    const high = Math.ceil(idx);
+    if (low === high)
+        return validNums[low];
+    return validNums[low] + (idx - low) * (validNums[high] - validNums[low]);
+}
+/**
+ * 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.
+ */
+function computeMode(values) {
+    if (!(0, guards_1.isArrayOrTypedArray)(values) || values.length === 0)
+        return null;
+    const counts = new Map();
+    const len = values.length;
+    let max = 0;
+    let modes = [];
+    for (let i = 0; i < len; i++) {
+        const val = values[i];
+        if (val == null)
+            continue;
+        const c = (counts.get(val) ?? 0) + 1;
+        counts.set(val, c);
+        if (c > max) {
+            max = c;
+            modes = [val];
+        }
+        else if (c === max) {
+            modes.push(val);
+        }
+    }
+    if (modes.length === 0)
+        return null;
+    return (0, list_1.sortList)(modes);
+}

package/dist/utils/string.d.ts

@@ -50,3 +50,8 @@ export type StripCharsOptions = {
  * Strips characters from the start, end, or both ends of a string.
  */
 export declare function stripChars(str: string | null | undefined, characters?: string | RegExp | null, { mode, returnStringOnNull, maxScanStart, maxScanEnd, maxMatchesStart, maxMatchesEnd, trimFirst, stringOptions: { literal, caseInsensitive } }?: StripCharsOptions): string | null;
+export declare function isBlankString(v: unknown): v is string;
+export declare function toCanonicalString(val: any, { depth, maxDepth }?: {
+    depth?: number;
+    maxDepth?: number;
+}): string;

package/dist/utils/string.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripChars = stripChars;
+exports.isBlankString = isBlankString;
+exports.toCanonicalString = toCanonicalString;
+const guards_1 = require("./guards");
+const date_1 = require("./date");
 /**
  * Strips characters from the start, end, or both ends of a string.
  */
@@ -118,3 +122,88 @@ function stripChars(str, characters = null, { mode = "both", returnStringOnNull
     }
     return (returnStringOnNull || result !== "") ? result : null;
 }
+function isBlankString(v) {
+    if (typeof v === "string") {
+        return v.trim().length === 0;
+    }
+    if (v instanceof String) {
+        return v.valueOf().trim().length === 0;
+    }
+    return false;
+}
+function toCanonicalString(val, { depth = 0, maxDepth = 50 } = {}) {
+    if (depth > maxDepth) {
+        return "v:circular";
+    }
+    if (val === null) {
+        return "v:null";
+    }
+    if (val === undefined) {
+        return "v:undefined";
+    }
+    if (val instanceof Date) {
+        return (0, date_1.isValidDateObj)(val) ? `d:${val.getTime()}` : "d:invalid";
+    }
+    if ((0, guards_1.isTypedArray)(val)) {
+        return `u:${val.constructor.name}:${val.toString()}`;
+    }
+    if (Array.isArray(val)) {
+        const len = val.length;
+        const parts = new Array(len);
+        const nextOpt = { depth: depth + 1, maxDepth };
+        for (let i = 0; i < len; i++) {
+            parts[i] = toCanonicalString(val[i], nextOpt);
+        }
+        return `a:[${parts.join(",")}]`;
+    }
+    if (val instanceof Set) {
+        const arr = Array.from(val);
+        const len = arr.length;
+        const parts = new Array(len);
+        const nextOpt = { depth: depth + 1, maxDepth };
+        for (let i = 0; i < len; i++) {
+            parts[i] = toCanonicalString(arr[i], nextOpt);
+        }
+        parts.sort();
+        return `set:[${parts.join(",")}]`;
+    }
+    if (val instanceof Map) {
+        const keys = Array.from(val.keys());
+        const len = keys.length;
+        const parts = new Array(len);
+        const nextOpt = { depth: depth + 1, maxDepth };
+        for (let i = 0; i < len; i++) {
+            const k = keys[i];
+            parts[i] = `${toCanonicalString(k, nextOpt)}:${toCanonicalString(val.get(k), nextOpt)}`;
+        }
+        parts.sort();
+        return `map:{${parts.join(",")}}`;
+    }
+    if (typeof val === "object" && typeof val.toJSON === "function") {
+        return `j:${toCanonicalString(val.toJSON(), { depth: depth + 1, maxDepth })}`;
+    }
+    if ((0, guards_1.isPlainObj)(val)) {
+        const keys = Object.keys(val).sort();
+        const len = keys.length;
+        const parts = new Array(len);
+        const nextOpt = { depth: depth + 1, maxDepth };
+        for (let i = 0; i < len; i++) {
+            const k = keys[i];
+            parts[i] = `${k}:${toCanonicalString(val[k], nextOpt)}`;
+        }
+        return `o:{${parts.join(",")}}`;
+    }
+    if (val instanceof RegExp) {
+        return `r:${val.toString()}`;
+    }
+    if (typeof val === "function") {
+        return `f:${val.toString()}`;
+    }
+    if (typeof val === "string") {
+        return `s:${val}`;
+    }
+    if (typeof val === "symbol") {
+        return `y:${val.toString()}`;
+    }
+    return `${typeof val}:${val}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "df-script",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A zero-dependency, high-performance, expression-based DataFrame library for TypeScript/JavaScript.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,10 @@
   ],
   "author": "Trent Morris",
   "license": "MIT",
+  "funding": {
+    "type": "custom",
+    "url": "https://github.com/trentamorris/df-script/blob/main/DONATIONS.md"
+  },
   "devDependencies": {
     "typescript": "^5.4.5",
     "tsx": "^4.15.5",