@affino/datagrid-formula-engine 0.1.1

package/dist/syntax/functionHelpers.js

@@ -0,0 +1,553 @@
+import { areFormulaValuesEqual, compareFormulaValues, coerceFormulaValueToNumber, isFormulaErrorValue, isFormulaValuePresent, } from "./values.js";
+import { parseFormulaReferenceSegments } from "./tokenizer.js";
+const formulaTableLookupIndexCache = new WeakMap();
+function isFormulaTableRowsSource(value) {
+    return typeof value === "object"
+        && value !== null
+        && Array.isArray(value.rows);
+}
+function resolveFormulaTableRowsInput(rowsInput) {
+    if (Array.isArray(rowsInput)) {
+        return {
+            cacheKey: rowsInput,
+            rows: rowsInput,
+        };
+    }
+    if (isFormulaTableRowsSource(rowsInput)) {
+        return {
+            cacheKey: rowsInput,
+            rows: rowsInput.rows,
+            resolveRow: typeof rowsInput.resolveRow === "function"
+                ? rowsInput.resolveRow
+                : undefined,
+        };
+    }
+    return null;
+}
+export function normalizeFormulaTableName(value) {
+    var _a;
+    if (Array.isArray(value)) {
+        return normalizeFormulaTableName((_a = value[0]) !== null && _a !== void 0 ? _a : null);
+    }
+    return String(value !== null && value !== void 0 ? value : "").trim().toLowerCase();
+}
+export function coerceFormulaValueToText(value) {
+    const scalar = coerceFormulaValueToScalar(value);
+    if (scalar === null || isFormulaErrorValue(scalar)) {
+        return "";
+    }
+    if (scalar instanceof Date) {
+        return Number.isNaN(scalar.getTime()) ? "" : scalar.toISOString();
+    }
+    return String(scalar);
+}
+export function createFormulaTableContextKey(tableName) {
+    const normalized = tableName.trim().toLowerCase();
+    return normalized.length === 0 ? "tables" : `table:${normalized}`;
+}
+export function resolveFormulaLiteralText(node) {
+    if (!node) {
+        return null;
+    }
+    if (node.kind === "literal" && typeof node.value === "string") {
+        return node.value;
+    }
+    if (node.kind === "number") {
+        return String(node.value);
+    }
+    return null;
+}
+export function defineFormulaFunctions(entries) {
+    return entries;
+}
+function coerceFormulaValueToScalar(value) {
+    var _a;
+    if (Array.isArray(value)) {
+        return (_a = value[0]) !== null && _a !== void 0 ? _a : null;
+    }
+    return value;
+}
+function coerceUnknownToFormulaScalar(value) {
+    if (value === null || typeof value === "undefined") {
+        return null;
+    }
+    if (isFormulaErrorValue(value)) {
+        return value;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : 0;
+    }
+    if (typeof value === "string" || typeof value === "boolean") {
+        return value;
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value;
+    }
+    return null;
+}
+function normalizeFormulaLookupKey(value) {
+    const scalar = coerceUnknownToFormulaScalar(value);
+    if (scalar === null || isFormulaErrorValue(scalar)) {
+        return null;
+    }
+    if (scalar instanceof Date) {
+        return Number.isNaN(scalar.getTime()) ? null : `n:${scalar.getTime()}`;
+    }
+    if (typeof scalar === "number") {
+        return `n:${Number.isFinite(scalar) ? scalar : 0}`;
+    }
+    if (typeof scalar === "boolean") {
+        return `n:${scalar ? 1 : 0}`;
+    }
+    const numeric = scalar.trim().length > 0 ? Number(scalar) : Number.NaN;
+    if (Number.isFinite(numeric)) {
+        return `n:${numeric}`;
+    }
+    return `s:${scalar}`;
+}
+function readNestedFormulaTableValue(value, segments) {
+    let current = value;
+    for (const segment of segments) {
+        if (current === null || typeof current === "undefined") {
+            return null;
+        }
+        if (Array.isArray(current) && typeof segment === "number") {
+            current = current[segment];
+            continue;
+        }
+        if (typeof current === "object" && current !== null) {
+            current = current[segment];
+            continue;
+        }
+        return null;
+    }
+    return current;
+}
+function resolveFormulaTableFieldSegments(fieldValue) {
+    const field = typeof fieldValue === "undefined"
+        ? ""
+        : coerceFormulaValueToText(fieldValue).trim();
+    return field.length > 0 ? parseFormulaReferenceSegments(field) : [];
+}
+function resolveFormulaTableRowValue(input, row, index) {
+    return input.resolveRow
+        ? input.resolveRow(row, index)
+        : row;
+}
+function resolveFormulaTableFieldValue(rowValue, path) {
+    return path.length > 0
+        ? readNestedFormulaTableValue(rowValue, path)
+        : rowValue;
+}
+export function collectFormulaTableValues(rowsInput, fieldValue) {
+    const input = resolveFormulaTableRowsInput(rowsInput);
+    if (!input) {
+        return Object.freeze([]);
+    }
+    const path = resolveFormulaTableFieldSegments(fieldValue);
+    const values = [];
+    for (let index = 0; index < input.rows.length; index += 1) {
+        const row = input.rows[index];
+        const rowValue = resolveFormulaTableRowValue(input, row, index);
+        const resolved = resolveFormulaTableFieldValue(rowValue, path);
+        if (Array.isArray(resolved)) {
+            for (const entry of resolved) {
+                values.push(coerceUnknownToFormulaScalar(entry));
+            }
+            continue;
+        }
+        values.push(coerceUnknownToFormulaScalar(resolved));
+    }
+    return Object.freeze(values);
+}
+export function findFormulaTableRelatedRows(rowsInput, keyFieldValue, lookupValue) {
+    var _a, _b;
+    const input = resolveFormulaTableRowsInput(rowsInput);
+    if (!input) {
+        return Object.freeze([]);
+    }
+    const lookupKey = normalizeFormulaLookupKey(Array.isArray(lookupValue) ? (_a = lookupValue[0]) !== null && _a !== void 0 ? _a : null : lookupValue);
+    if (lookupKey === null) {
+        return Object.freeze([]);
+    }
+    const keyPath = resolveFormulaTableFieldSegments(keyFieldValue);
+    const cacheFieldKey = keyPath.length === 0
+        ? ""
+        : keyPath.map(segment => String(segment)).join(".");
+    let indexesByField = formulaTableLookupIndexCache.get(input.cacheKey);
+    if (!indexesByField) {
+        indexesByField = new Map();
+        formulaTableLookupIndexCache.set(input.cacheKey, indexesByField);
+    }
+    let lookupIndex = indexesByField.get(cacheFieldKey);
+    if (!lookupIndex) {
+        const nextLookupIndex = new Map();
+        for (let index = 0; index < input.rows.length; index += 1) {
+            const row = input.rows[index];
+            const rowValue = resolveFormulaTableRowValue(input, row, index);
+            const keyValue = resolveFormulaTableFieldValue(rowValue, keyPath);
+            const normalizedKey = normalizeFormulaLookupKey(keyValue);
+            if (normalizedKey === null) {
+                continue;
+            }
+            const bucket = nextLookupIndex.get(normalizedKey);
+            if (bucket) {
+                bucket.push(rowValue);
+                continue;
+            }
+            nextLookupIndex.set(normalizedKey, [rowValue]);
+        }
+        lookupIndex = new Map(nextLookupIndex);
+        indexesByField.set(cacheFieldKey, lookupIndex);
+    }
+    return (_b = lookupIndex.get(lookupKey)) !== null && _b !== void 0 ? _b : Object.freeze([]);
+}
+export function collectFormulaTableRelatedValues(rowsInput, keyFieldValue, lookupValue, returnFieldValue) {
+    const relatedRows = findFormulaTableRelatedRows(rowsInput, keyFieldValue, lookupValue);
+    if (relatedRows.length === 0) {
+        return Object.freeze([]);
+    }
+    const returnPath = resolveFormulaTableFieldSegments(returnFieldValue);
+    const values = [];
+    for (const relatedRow of relatedRows) {
+        const resolved = resolveFormulaTableFieldValue(relatedRow, returnPath);
+        if (Array.isArray(resolved)) {
+            for (const entry of resolved) {
+                values.push(coerceUnknownToFormulaScalar(entry));
+            }
+            continue;
+        }
+        values.push(coerceUnknownToFormulaScalar(resolved));
+    }
+    return Object.freeze(values);
+}
+export function expandFormulaValue(value) {
+    if (Array.isArray(value)) {
+        return value;
+    }
+    return [value];
+}
+export function expandFormulaArgs(args) {
+    const expanded = [];
+    for (const value of args) {
+        expanded.push(...expandFormulaValue(value));
+    }
+    return expanded;
+}
+export function coerceFormulaValueToDate(value) {
+    const scalarValue = coerceFormulaValueToScalar(value);
+    if (scalarValue === null) {
+        return null;
+    }
+    if (isFormulaErrorValue(scalarValue)) {
+        return null;
+    }
+    if (scalarValue instanceof Date) {
+        return Number.isNaN(scalarValue.getTime()) ? null : scalarValue;
+    }
+    if (typeof scalarValue === "number") {
+        if (!Number.isFinite(scalarValue)) {
+            return null;
+        }
+        const date = new Date(scalarValue);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    if (typeof scalarValue === "string") {
+        const text = scalarValue.trim();
+        if (text.length === 0) {
+            return null;
+        }
+        const timestamp = Date.parse(text);
+        if (!Number.isFinite(timestamp)) {
+            return null;
+        }
+        const date = new Date(timestamp);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    return null;
+}
+export function stringifyFormulaScalarValue(value) {
+    if (value === null) {
+        return "";
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? "" : value.toISOString();
+    }
+    if (isFormulaErrorValue(value)) {
+        return value.message;
+    }
+    return String(value);
+}
+export function flattenFormulaValuesToStrings(values) {
+    return expandFormulaArgs(values).map(value => stringifyFormulaScalarValue(value));
+}
+function tryCoerceComparableNumber(value) {
+    const scalarValue = coerceFormulaValueToScalar(value);
+    if (scalarValue === null) {
+        return null;
+    }
+    if (isFormulaErrorValue(scalarValue)) {
+        return null;
+    }
+    if (typeof scalarValue === "number") {
+        return Number.isFinite(scalarValue) ? scalarValue : 0;
+    }
+    if (typeof scalarValue === "boolean") {
+        return scalarValue ? 1 : 0;
+    }
+    if (scalarValue instanceof Date) {
+        return Number.isNaN(scalarValue.getTime()) ? null : scalarValue.getTime();
+    }
+    const text = scalarValue.trim();
+    if (text.length === 0) {
+        return null;
+    }
+    const parsed = Number(text);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function normalizeCriterionOperand(text) {
+    const trimmed = text.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+export function formulaValueMatchesCriterion(candidate, criterion) {
+    var _a, _b;
+    if (typeof criterion !== "string") {
+        return areFormulaValuesEqual(candidate, criterion);
+    }
+    const trimmedCriterion = criterion.trim();
+    const match = /^(<=|>=|<>|!=|=|<|>)(.*)$/.exec(trimmedCriterion);
+    const operator = (_a = match === null || match === void 0 ? void 0 : match[1]) !== null && _a !== void 0 ? _a : "=";
+    const rawOperand = normalizeCriterionOperand((_b = match === null || match === void 0 ? void 0 : match[2]) !== null && _b !== void 0 ? _b : trimmedCriterion);
+    const operandValue = rawOperand;
+    if (operator === "=" && !match) {
+        return areFormulaValuesEqual(candidate, operandValue);
+    }
+    if (operator === "=" || operator === "<>" || operator === "!=") {
+        const equals = areFormulaValuesEqual(candidate, operandValue);
+        return operator === "=" ? equals : !equals;
+    }
+    const compared = (() => {
+        const left = tryCoerceComparableNumber(candidate);
+        const right = tryCoerceComparableNumber(operandValue);
+        if (left !== null && right !== null) {
+            return left - right;
+        }
+        const candidateDate = coerceFormulaValueToDate(candidate);
+        const operandDate = coerceFormulaValueToDate(operandValue);
+        if (candidateDate && operandDate) {
+            return candidateDate.getTime() - operandDate.getTime();
+        }
+        return compareFormulaValues(candidate, operandValue);
+    })();
+    switch (operator) {
+        case ">":
+            return compared > 0;
+        case ">=":
+            return compared >= 0;
+        case "<":
+            return compared < 0;
+        case "<=":
+            return compared <= 0;
+        default:
+            return false;
+    }
+}
+export function collectFilteredValues(values, criteria) {
+    var _a;
+    const filtered = [];
+    for (let index = 0; index < values.length; index += 1) {
+        const matches = criteria.every(({ range, criterion }) => { var _a; return formulaValueMatchesCriterion((_a = range[index]) !== null && _a !== void 0 ? _a : null, criterion); });
+        if (matches) {
+            filtered.push((_a = values[index]) !== null && _a !== void 0 ? _a : null);
+        }
+    }
+    return filtered;
+}
+export function toDistinctFormulaValues(values) {
+    const distinct = [];
+    for (const value of values) {
+        if (distinct.some(entry => areFormulaValuesEqual(entry, value))) {
+            continue;
+        }
+        distinct.push(value);
+    }
+    return Object.freeze(distinct);
+}
+export function toNumericFormulaValues(values) {
+    return values.map(value => coerceFormulaValueToNumber(value !== null && value !== void 0 ? value : null));
+}
+export function toStrictNumericFormulaValues(values) {
+    const numeric = [];
+    for (const value of values) {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            numeric.push(value);
+            continue;
+        }
+        if (typeof value === "boolean") {
+            numeric.push(value ? 1 : 0);
+            continue;
+        }
+        if (value instanceof Date && !Number.isNaN(value.getTime())) {
+            numeric.push(value.getTime());
+        }
+    }
+    return numeric;
+}
+export function computeAverage(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const numeric = toNumericFormulaValues(values);
+    const total = numeric.reduce((sum, value) => sum + value, 0);
+    return total / numeric.length;
+}
+export function computeMedian(values) {
+    var _a, _b, _c;
+    const numeric = [...toNumericFormulaValues(values)].sort((left, right) => left - right);
+    if (numeric.length === 0) {
+        return 0;
+    }
+    const middle = Math.floor(numeric.length / 2);
+    if (numeric.length % 2 === 0) {
+        const left = (_a = numeric[middle - 1]) !== null && _a !== void 0 ? _a : 0;
+        const right = (_b = numeric[middle]) !== null && _b !== void 0 ? _b : left;
+        return (left + right) / 2;
+    }
+    return (_c = numeric[middle]) !== null && _c !== void 0 ? _c : 0;
+}
+export function computePercentile(values, percentile) {
+    var _a, _b, _c;
+    const numeric = [...toNumericFormulaValues(values)].sort((left, right) => left - right);
+    if (numeric.length === 0) {
+        return 0;
+    }
+    const clampedPercentile = Math.max(0, Math.min(1, percentile));
+    const position = (numeric.length - 1) * clampedPercentile;
+    const lowerIndex = Math.floor(position);
+    const upperIndex = Math.ceil(position);
+    if (lowerIndex === upperIndex) {
+        return (_a = numeric[lowerIndex]) !== null && _a !== void 0 ? _a : 0;
+    }
+    const lower = (_b = numeric[lowerIndex]) !== null && _b !== void 0 ? _b : 0;
+    const upper = (_c = numeric[upperIndex]) !== null && _c !== void 0 ? _c : lower;
+    const weight = position - lowerIndex;
+    return lower + (upper - lower) * weight;
+}
+function computeVariance(values, mode) {
+    if (values.length === 0 || (mode === "sample" && values.length < 2)) {
+        return 0;
+    }
+    const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+    const squared = values.reduce((sum, value) => sum + ((value - mean) ** 2), 0);
+    return squared / (mode === "sample" ? values.length - 1 : values.length);
+}
+export function computeStdDev(values, mode) {
+    const numeric = toNumericFormulaValues(values);
+    return Math.sqrt(computeVariance(numeric, mode));
+}
+export function isWeekday(date) {
+    const day = date.getUTCDay();
+    return day !== 0 && day !== 6;
+}
+export function normalizeHolidayTimes(values) {
+    const holidayTimes = new Set();
+    for (const value of values) {
+        for (const entry of expandFormulaValue(value)) {
+            const date = coerceFormulaValueToDate(entry);
+            if (!date) {
+                continue;
+            }
+            holidayTimes.add(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+        }
+    }
+    return holidayTimes;
+}
+function stripUtcTime(date) {
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+}
+export function addCalendarDays(date, days) {
+    const next = stripUtcTime(date);
+    next.setUTCDate(next.getUTCDate() + days);
+    return next;
+}
+export function countDaysBetween(start, end, inclusive) {
+    const left = stripUtcTime(start);
+    const right = stripUtcTime(end);
+    const diff = Math.round((right.getTime() - left.getTime()) / 86400000);
+    return inclusive ? diff + 1 : diff;
+}
+export function countWorkingDays(start, end, holidays) {
+    const direction = start.getTime() <= end.getTime() ? 1 : -1;
+    let cursor = stripUtcTime(start);
+    const target = stripUtcTime(end);
+    let count = 0;
+    while ((direction > 0 && cursor.getTime() <= target.getTime()) || (direction < 0 && cursor.getTime() >= target.getTime())) {
+        const time = cursor.getTime();
+        if (isWeekday(cursor) && !holidays.has(time)) {
+            count += direction;
+        }
+        cursor = addCalendarDays(cursor, direction);
+    }
+    return count;
+}
+export function addWorkingDays(start, days, holidays) {
+    let remaining = Math.trunc(days);
+    let cursor = stripUtcTime(start);
+    const direction = remaining >= 0 ? 1 : -1;
+    while (remaining !== 0) {
+        cursor = addCalendarDays(cursor, direction);
+        const time = cursor.getTime();
+        if (isWeekday(cursor) && !holidays.has(time)) {
+            remaining -= direction;
+        }
+    }
+    return cursor;
+}
+export function countPresentValues(values) {
+    return values.reduce((count, value) => (isFormulaValuePresent(value !== null && value !== void 0 ? value : null) ? count + 1 : count), 0);
+}
+export function booleanResult(value) {
+    return value;
+}
+export function normalizeTextSearch(value) {
+    const scalar = coerceFormulaValueToScalar(value);
+    if (scalar === null || isFormulaErrorValue(scalar)) {
+        return "";
+    }
+    return String(scalar).toLowerCase();
+}
+export function collectValuesFromArgs(args, startIndex = 0) {
+    return expandFormulaArgs(args.slice(startIndex));
+}
+export function defaultIfEmpty(value, fallback) {
+    return typeof value === "undefined" ? fallback : value;
+}
+export function parseTimeLikeValue(value) {
+    var _a;
+    const scalar = coerceFormulaValueToScalar(value);
+    if (scalar === null || isFormulaErrorValue(scalar)) {
+        return null;
+    }
+    if (scalar instanceof Date) {
+        return Number.isNaN(scalar.getTime()) ? null : scalar;
+    }
+    if (typeof scalar === "number") {
+        const date = new Date(scalar);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    const text = String(scalar).trim();
+    const match = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(text);
+    if (!match) {
+        return coerceFormulaValueToDate(text);
+    }
+    const hours = Number(match[1]);
+    const minutes = Number(match[2]);
+    const seconds = Number((_a = match[3]) !== null && _a !== void 0 ? _a : 0);
+    if (hours > 23 || minutes > 59 || seconds > 59) {
+        return null;
+    }
+    return new Date(Date.UTC(1970, 0, 1, hours, minutes, seconds));
+}

package/dist/syntax/functions.d.ts

@@ -0,0 +1,9 @@
+import type { DataGridFormulaAstNode, DataGridFormulaCompileOptions, DataGridFormulaFunctionDefinition, DataGridFormulaFunctionRegistry, DataGridFormulaFunctionRuntime as LegacyDataGridFormulaFunctionRuntime } from "./analysis.js";
+export type { DataGridFormulaFunctionArity, DataGridFormulaFunctionDefinition, DataGridFormulaFunctionRegistry, DataGridFormulaFunctionRuntime, } from "./analysis.js";
+export declare function normalizeFormulaText(value: unknown): string;
+export declare function normalizeFormulaFieldName(value: unknown, label: string): string;
+export declare function normalizeFormulaFunctionName(value: string): string;
+export declare function normalizeFormulaFunctionRegistry(input: DataGridFormulaFunctionRegistry | undefined, options?: Pick<DataGridFormulaCompileOptions, "onFunctionOverride">): ReadonlyMap<string, LegacyDataGridFormulaFunctionRuntime>;
+export declare function collectFormulaContextKeys(root: DataGridFormulaAstNode, functionRegistry: ReadonlyMap<string, LegacyDataGridFormulaFunctionRuntime>, output: string[]): void;
+export declare const DATAGRID_DEFAULT_FORMULA_FUNCTIONS: Readonly<Record<string, DataGridFormulaFunctionDefinition>>;
+//# sourceMappingURL=functions.d.ts.map

package/dist/syntax/functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../src/syntax/functions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,sBAAsB,EACtB,6BAA6B,EAE7B,iCAAiC,EACjC,+BAA+B,EAC/B,8BAA8B,IAAI,oCAAoC,EACvE,MAAM,eAAe,CAAA;AAUtB,YAAY,EACV,4BAA4B,EAC5B,iCAAiC,EACjC,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,eAAe,CAAA;AAEtB,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAS3D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAS/E;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElE;AAiDD,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,+BAA+B,GAAG,SAAS,EAClD,OAAO,GAAE,IAAI,CAAC,6BAA6B,EAAE,oBAAoB,CAAM,GACtE,WAAW,CAAC,MAAM,EAAE,oCAAoC,CAAC,CA6C3D;AAED,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,sBAAsB,EAC5B,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,oCAAoC,CAAC,EAC3E,MAAM,EAAE,MAAM,EAAE,GACf,IAAI,CAuBN;AAED,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iCAAiC,CAAC,CAM1G,CAAA"}