df-script 1.4.0

package/dist/utils/list.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toValidArray = toValidArray;
+exports.isArrayOfType = isArrayOfType;
+exports.sortList = sortList;
+exports.getListStats = getListStats;
+const guards_1 = require("./guards");
+const date_1 = require("./date");
+const number_1 = require("./number");
+function toValidArray(val) {
+    if (val == null)
+        return [];
+    if (Array.isArray(val))
+        return val;
+    if ((0, guards_1.isTypedArray)(val))
+        return Array.from(val);
+    return [val];
+}
+function isArrayOfType(arr, type, { mode = "every", allowNulls = false, allowEmpty = true } = {}) {
+    if (!(0, guards_1.isArrayOrTypedArray)(arr))
+        return false;
+    const len = arr.length;
+    if (len === 0) {
+        if (!allowEmpty)
+            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;
+    };
+    if (mode === "every") {
+        for (let i = 0; i < len; i++) {
+            if (!check(arr[i]))
+                return false;
+        }
+        return true;
+    }
+    else {
+        for (let i = 0; i < len; i++) {
+            if (check(arr[i]))
+                return true;
+        }
+        return false;
+    }
+}
+function sortList(arr, descending = false) {
+    if (!(0, guards_1.isArrayOrTypedArray)(arr))
+        return [];
+    const list = Array.from(arr);
+    list.sort((a, b) => {
+        if (a == null && b == null)
+            return 0;
+        if (a == null)
+            return 1;
+        if (b == null)
+            return -1;
+        if (a < b)
+            return descending ? 1 : -1;
+        if (a > b)
+            return descending ? -1 : 1;
+        return 0;
+    });
+    return list;
+}
+const DEFAULT_STATS = { sum: null, count: 0, min: null, max: null, mean: null, variance: 0, std: 0, nullCount: 0, len: 0, hasNulls: false, isNumeric: false };
+function getListStats(arr) {
+    if (!(0, guards_1.isArrayOrTypedArray)(arr)) {
+        return { ...DEFAULT_STATS };
+    }
+    const len = arr.length;
+    if (len === 0) {
+        return { ...DEFAULT_STATS };
+    }
+    let minVal = null;
+    let maxVal = null;
+    let count = 0;
+    let nullCount = 0;
+    let total = 0;
+    let mean = 0;
+    let M2 = 0;
+    for (let i = 0; i < len; i++) {
+        const val = arr[i];
+        if (val == null) {
+            nullCount++;
+            continue;
+        }
+        if (minVal == null || val < minVal)
+            minVal = val;
+        if (maxVal == null || val > maxVal)
+            maxVal = val;
+        const n = (0, number_1.toValidNumber)(val);
+        if (n !== null) {
+            total += n;
+            count++;
+            const delta = n - mean;
+            mean += delta / count;
+            const delta2 = n - mean;
+            M2 += delta * delta2;
+        }
+    }
+    const variance = count > 1 ? M2 / (count - 1) : 0;
+    return {
+        sum: count > 0 ? total : null,
+        count,
+        min: minVal,
+        max: maxVal,
+        mean: count > 0 ? total / count : null,
+        variance,
+        std: Math.sqrt(variance),
+        nullCount,
+        len,
+        hasNulls: nullCount > 0,
+        isNumeric: count > 0 && count === (len - nullCount)
+    };
+}

package/dist/utils/number.d.ts

@@ -0,0 +1,86 @@
+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 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 declare const INT_RANGES: {
+    readonly Int8: {
+        readonly min: -128;
+        readonly max: 127;
+    };
+    readonly Int16: {
+        readonly min: -32768;
+        readonly max: 32767;
+    };
+    readonly Int32: {
+        readonly min: -2147483648;
+        readonly max: 2147483647;
+    };
+    readonly UInt8: {
+        readonly min: 0;
+        readonly max: 255;
+    };
+    readonly UInt16: {
+        readonly min: 0;
+        readonly max: 65535;
+    };
+    readonly UInt32: {
+        readonly min: 0;
+        readonly max: 4294967295;
+    };
+};
+export type IntRangeType = keyof typeof INT_RANGES;
+export type IntRange = {
+    min: number;
+    max: number;
+} | IntRangeType;
+export declare const BIGINT_RANGES: {
+    readonly Int64: {
+        readonly min: -9223372036854775808n;
+        readonly max: 9223372036854775807n;
+    };
+    readonly UInt64: {
+        readonly min: 0n;
+        readonly max: 18446744073709551615n;
+    };
+};
+export type BigIntRangeType = keyof typeof BIGINT_RANGES;
+export type BigIntRange = {
+    min: bigint;
+    max: bigint;
+} | BigIntRangeType;
+export type IntCoerceType = "round" | "floor" | "ceil" | "truncate";
+export interface IntOptions {
+    coerce?: IntCoerceType;
+}
+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 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;
+/**
+ * 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;

package/dist/utils/number.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BIGINT_RANGES = exports.INT_RANGES = exports.FLOAT_RANGES = exports.FLOAT_32_BOUNDARY = void 0;
+exports.isValidNumber = isValidNumber;
+exports.toValidNumber = toValidNumber;
+exports.clamp = clamp;
+exports.isValidFloat = isValidFloat;
+exports.toValidFloat = toValidFloat;
+exports.isValidInt = isValidInt;
+exports.isValidBigInt = isValidBigInt;
+exports.toValidInt = toValidInt;
+exports.toValidBigInt = toValidBigInt;
+exports.isValidDecimal = isValidDecimal;
+exports.toValidDecimal = toValidDecimal;
+exports.mulberry32 = mulberry32;
+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 toValidNumber(v) {
+    if (v == null)
+        return null;
+    if (typeof v === "symbol")
+        return null;
+    if (isValidNumber(v)) {
+        return v;
+    }
+    if (typeof v === "boolean") {
+        return v ? 1 : 0;
+    }
+    if (typeof v === "bigint") {
+        const n = Number(v);
+        return isValidNumber(n) ? n : null;
+    }
+    if (v instanceof Date) {
+        const t = v.getTime();
+        return isValidNumber(t) ? 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;
+    }
+    return null;
+}
+function clamp(opts) {
+    const { val, min, max } = opts;
+    if (val < min)
+        return min;
+    if (val > max)
+        return max;
+    return val;
+}
+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))
+        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);
+    if (num === null)
+        return null;
+    return precision === "Float32" ? Math.fround(num) : num;
+}
+// ============================================================================
+// /** Integer & BigInt Functions */
+// ============================================================================
+exports.INT_RANGES = {
+    Int8: { min: -128, max: 127 },
+    Int16: { min: -32768, max: 32767 },
+    Int32: { min: -2147483648, max: 2147483647 },
+    UInt8: { min: 0, max: 255 },
+    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;
+    if (!Number.isInteger(v))
+        return false;
+    if (!range)
+        return true;
+    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 = {}) {
+    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);
+            break;
+        case "floor":
+            n = Math.floor(n);
+            break;
+        case "ceil":
+            n = Math.ceil(n);
+            break;
+        case "truncate":
+            n = Math.trunc(n);
+            break;
+    }
+    const limits = typeof range === "string" ? exports.INT_RANGES[range] : range;
+    return clamp({ val: n, min: limits.min, max: limits.max });
+}
+function toValidBigInt(v, range = "Int64") {
+    if (v == null)
+        return null;
+    if (typeof v === "symbol")
+        return null;
+    let bigintVal = null;
+    if (typeof v === "bigint") {
+        bigintVal = v;
+    }
+    else if (typeof v === "boolean") {
+        bigintVal = v ? 1n : 0n;
+    }
+    else if (typeof v === "string") {
+        const clean = v.trim().replace(NUMERIC_CLEAN_REGEX, "");
+        if (clean === "")
+            return null;
+        if (!VALID_DECIMAL_REGEX.test(clean)) {
+            const num = toValidNumber(v);
+            if (num === null)
+                return null;
+            bigintVal = BigInt(Math.trunc(num));
+        }
+        else {
+            bigintVal = BigInt(clean.split(".")[0]);
+        }
+    }
+    else {
+        const num = toValidNumber(v);
+        if (num === null)
+            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 });
+}
+function isValidDecimal(v, opts = {}) {
+    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) {
+            return false;
+        }
+    }
+    if (scale !== undefined) {
+        const str = v.toString();
+        const dotIdx = str.indexOf(".");
+        if (dotIdx !== -1 && str.slice(dotIdx + 1).length > scale) {
+            return false;
+        }
+    }
+    return true;
+}
+function toValidDecimal(v, opts = {}) {
+    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;
+    }
+    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 });
+        }
+    }
+    return n;
+}
+/**
+ * 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).
+ */
+function mulberry32(seed) {
+    let s = seed | 0;
+    return function () {
+        let t = s = (s + 0x6D2B79F5) | 0;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/utils/string.d.ts

@@ -0,0 +1,52 @@
+export type StripMode = "both" | "start" | "end";
+export type StripCharsOptions = {
+    /**
+     * The strip mode: "both" (default), "start", or "end".
+     */
+    mode?: StripMode;
+    /**
+     * If true, returns an empty string instead of null when the result is empty or input is null.
+     */
+    returnStringOnNull?: boolean;
+    /**
+     * The maximum number of non-matching characters allowed to be skipped from the start
+     * before a match block is found. Passing -1 or null means scan the full length.
+     */
+    maxScanStart?: number | null;
+    /**
+     * The maximum number of non-matching characters allowed to be skipped from the end
+     * before a match block is found. Passing -1 or null means scan the full length.
+     */
+    maxScanEnd?: number | null;
+    /**
+     * The maximum number of non-contiguous matching blocks allowed to be stripped from the start.
+     * Passing -1 or null means strip all matching blocks.
+     */
+    maxMatchesStart?: number | null;
+    /**
+     * The maximum number of non-contiguous matching blocks allowed to be stripped from the end.
+     * Passing -1 or null means strip all matching blocks.
+     */
+    maxMatchesEnd?: number | null;
+    /**
+     * If true, trims standard whitespace first before performing character stripping.
+     */
+    trimFirst?: boolean;
+    /**
+     * Options that apply only when the characters parameter is a string (and not a RegExp).
+     */
+    stringOptions?: {
+        /**
+         * If true, treats the characters string as a literal substring rather than a set of characters.
+         */
+        literal?: boolean;
+        /**
+         * If true, performs case-insensitive character and substring matching.
+         */
+        caseInsensitive?: boolean;
+    };
+};
+/**
+ * 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;

package/dist/utils/string.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripChars = stripChars;
+/**
+ * Strips characters from the start, end, or both ends of a string.
+ */
+function stripChars(str, characters = null, { mode = "both", returnStringOnNull = false, maxScanStart = 1, maxScanEnd = 1, maxMatchesStart = 1, maxMatchesEnd = 1, trimFirst = false, stringOptions: { literal = false, caseInsensitive = false } = {} } = {}) {
+    if (str == null) {
+        return returnStringOnNull ? "" : null;
+    }
+    const trimString = (s, m = "both") => {
+        if (m === "start")
+            return s.trimStart();
+        if (m === "end")
+            return s.trimEnd();
+        return s.trim();
+    };
+    let workStr = str;
+    if (trimFirst && characters != null) {
+        workStr = trimString(str, mode);
+    }
+    if (characters == null) {
+        const result = trimString(workStr, mode);
+        return (returnStringOnNull || result !== "") ? result : null;
+    }
+    const matches = characters instanceof RegExp
+        ? (char) => characters.test(char)
+        : (() => {
+            const targetSet = new Set(caseInsensitive ? characters.toLowerCase() : characters);
+            return (char) => targetSet.has(caseInsensitive ? char.toLowerCase() : char);
+        })();
+    const len = workStr.length;
+    const stripped = new Uint8Array(len);
+    const scanNonLiteral = ({ isStart, limit, maxMatches }) => {
+        if (len === 0 || maxMatches === 0) {
+            return;
+        }
+        const start = isStart ? 0 : len - 1;
+        const end = isStart ? len : -1;
+        const step = isStart ? 1 : -1;
+        let inBlock = false;
+        let matchesFound = 0;
+        let totalSkipped = 0;
+        for (let i = start; i !== end; i += step) {
+            if (matches(workStr[i])) {
+                if (!inBlock) {
+                    if (limit !== null && limit >= 0 && totalSkipped >= limit) {
+                        break;
+                    }
+                    if (maxMatches !== null && maxMatches >= 0 && matchesFound >= maxMatches) {
+                        break;
+                    }
+                    inBlock = true;
+                    matchesFound++;
+                }
+                stripped[i] = 1;
+            }
+            else {
+                inBlock = false;
+                totalSkipped++;
+            }
+        }
+    };
+    const scanLiteral = ({ isStart, limit, maxMatches }) => {
+        if (len === 0 || maxMatches === 0) {
+            return;
+        }
+        const patLen = characters.length;
+        if (patLen === 0) {
+            return;
+        }
+        const searchStr = caseInsensitive ? workStr.toLowerCase() : workStr;
+        const patStr = caseInsensitive ? characters.toLowerCase() : characters;
+        let currentIdx = isStart ? 0 : len - 1;
+        let matchesFound = 0;
+        let totalSkipped = 0;
+        while (currentIdx >= 0 && currentIdx < len) {
+            if (maxMatches !== null && maxMatches >= 0 && matchesFound >= maxMatches) {
+                break;
+            }
+            const searchStart = isStart ? currentIdx : (currentIdx - patLen + 1);
+            if (!isStart && searchStart < 0) {
+                break;
+            }
+            const matchIdx = isStart
+                ? searchStr.indexOf(patStr, searchStart)
+                : searchStr.lastIndexOf(patStr, searchStart);
+            if (matchIdx === -1) {
+                break;
+            }
+            const skippedInThisStep = isStart
+                ? (matchIdx - currentIdx)
+                : (currentIdx - (matchIdx + patLen - 1));
+            totalSkipped += skippedInThisStep;
+            if (limit !== null && limit >= 0 && totalSkipped >= limit) {
+                break;
+            }
+            for (let i = 0; i < patLen; i++) {
+                stripped[matchIdx + i] = 1;
+            }
+            matchesFound++;
+            currentIdx = isStart ? (matchIdx + patLen) : (matchIdx - 1);
+        }
+    };
+    const isLiteral = literal && typeof characters === "string";
+    const scan = isLiteral ? scanLiteral : scanNonLiteral;
+    if (mode === "both" || mode === "start") {
+        scan({ isStart: true, limit: maxScanStart, maxMatches: maxMatchesStart });
+    }
+    if (mode === "both" || mode === "end") {
+        scan({ isStart: false, limit: maxScanEnd, maxMatches: maxMatchesEnd });
+    }
+    let result = "";
+    for (let i = 0; i < len; i++) {
+        if (stripped[i] === 0) {
+            result += workStr[i];
+        }
+    }
+    return (returnStringOnNull || result !== "") ? result : null;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "df-script",
+  "version": "1.4.0",
+  "description": "A zero-dependency, high-performance, expression-based DataFrame library for TypeScript/JavaScript.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && esbuild src/index.ts --bundle --minify --outfile=dist/index.js --platform=node",
+    "test": "tsx _tests/run_all_project_tests.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "dataframe",
+    "polars",
+    "pandas",
+    "data-analysis",
+    "typescript",
+    "columnar",
+    "data-science",
+    "zero-dependency"
+  ],
+  "author": "Trent Morris",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "tsx": "^4.15.5",
+    "@types/node": "^20.14.2"
+  }
+}