@affino/datagrid-formula-engine 0.1.1

package/dist/runtime/compile.js

@@ -0,0 +1,453 @@
+import {} from "../syntax/core.js";
+import { collectFormulaContextKeys, normalizeFormulaFieldName, normalizeFormulaFunctionRegistry, normalizeFormulaText, } from "../syntax/functions.js";
+import { foldFormulaConstants, collectFormulaIdentifiers, validateFormulaFunctions, } from "../syntax/optimizer.js";
+import { createFormulaErrorValue, normalizeFormulaRuntimeError, } from "../syntax/values.js";
+import { throwFormulaError, } from "../syntax/ast.js";
+import { parseFormula } from "../syntax/parser.js";
+import { parseDataGridFormulaIdentifier, tokenizeFormula } from "../syntax/tokenizer.js";
+import { compileFormulaAstBatchEvaluatorJit, compileFormulaAstColumnarBatchEvaluatorFused, compileFormulaAstColumnarBatchEvaluatorVector, compileFormulaAstColumnarBatchEvaluatorJit, compileFormulaAstEvaluator, compileFormulaAstEvaluatorJit, compileFormulaAstTokenIndexEvaluator, } from "./evaluators.js";
+function hasRowAwareFormulaIdentifiers(root) {
+    if (root.kind === "identifier") {
+        return root.rowSelector.kind !== "current";
+    }
+    if (root.kind === "call") {
+        return root.args.some(hasRowAwareFormulaIdentifiers);
+    }
+    if (root.kind === "unary") {
+        return hasRowAwareFormulaIdentifiers(root.value);
+    }
+    if (root.kind === "binary") {
+        return hasRowAwareFormulaIdentifiers(root.left) || hasRowAwareFormulaIdentifiers(root.right);
+    }
+    return false;
+}
+function hasRuntimeContextFormulaFunctions(root, functionRegistry) {
+    if (root.kind === "call") {
+        const functionDefinition = functionRegistry.get(root.name.trim().toUpperCase());
+        if (functionDefinition === null || functionDefinition === void 0 ? void 0 : functionDefinition.requiresRuntimeContext) {
+            return true;
+        }
+        return root.args.some(arg => hasRuntimeContextFormulaFunctions(arg, functionRegistry));
+    }
+    if (root.kind === "unary") {
+        return hasRuntimeContextFormulaFunctions(root.value, functionRegistry);
+    }
+    if (root.kind === "binary") {
+        return hasRuntimeContextFormulaFunctions(root.left, functionRegistry)
+            || hasRuntimeContextFormulaFunctions(root.right, functionRegistry);
+    }
+    return false;
+}
+function serializeFormulaValue(value) {
+    var _a, _b;
+    if (Array.isArray(value)) {
+        return `[${value.map(item => serializeFormulaValue(item)).join(",")}]`;
+    }
+    if (value == null) {
+        return "null";
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? `n:${value}` : `n:${String(value)}`;
+    }
+    if (typeof value === "string") {
+        return `s:${JSON.stringify(value)}`;
+    }
+    if (typeof value === "boolean") {
+        return value ? "b:1" : "b:0";
+    }
+    if (typeof value === "object" && "kind" in value && value.kind === "error") {
+        const errorValue = value;
+        return `e:${String((_a = errorValue.code) !== null && _a !== void 0 ? _a : "")}:${String((_b = errorValue.message) !== null && _b !== void 0 ? _b : "")}`;
+    }
+    return `u:${String(value)}`;
+}
+function serializeFormulaAstRowSelector(node) {
+    if (node.rowSelector.kind === "current") {
+        return "current";
+    }
+    if (node.rowSelector.kind === "absolute") {
+        return `absolute:${node.rowSelector.rowIndex}`;
+    }
+    if (node.rowSelector.kind === "absolute-window") {
+        return `absolute-window:${node.rowSelector.startRowIndex}:${node.rowSelector.endRowIndex}`;
+    }
+    if (node.rowSelector.kind === "relative") {
+        return `relative:${node.rowSelector.offset}`;
+    }
+    return `window:${node.rowSelector.startOffset}:${node.rowSelector.endOffset}`;
+}
+function serializeFormulaAst(node) {
+    var _a, _b;
+    switch (node.kind) {
+        case "number":
+            return `num(${node.value})`;
+        case "literal":
+            return `lit(${serializeFormulaValue(node.value)})`;
+        case "identifier":
+            return `id(${JSON.stringify((_a = node.sheetReference) !== null && _a !== void 0 ? _a : "")}:${JSON.stringify(node.referenceName)}:${JSON.stringify((_b = node.rangeReferenceName) !== null && _b !== void 0 ? _b : "")}:${serializeFormulaAstRowSelector(node)})`;
+        case "call":
+            return `call(${JSON.stringify(node.name)}:${node.args.map(arg => serializeFormulaAst(arg)).join(",")})`;
+        case "unary":
+            return `unary(${node.operator}:${serializeFormulaAst(node.value)})`;
+        case "binary":
+            return `binary(${node.operator}:${serializeFormulaAst(node.left)}:${serializeFormulaAst(node.right)})`;
+    }
+}
+function hashFormulaAst(node) {
+    const serialized = serializeFormulaAst(node);
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < serialized.length; index += 1) {
+        hash ^= serialized.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fnv1a:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+function normalizeFormulaIdentifierKey(identifier, referenceParserOptions) {
+    return parseDataGridFormulaIdentifier(identifier, referenceParserOptions).name.trim();
+}
+function analyzeFormulaExpression(formulaText, options = {}) {
+    var _a;
+    const formula = normalizeFormulaText(formulaText);
+    const tokens = tokenizeFormula(formula, options.referenceParserOptions);
+    const ast = parseFormula(tokens, options.referenceParserOptions);
+    const functionRegistry = normalizeFormulaFunctionRegistry(options.functionRegistry, {
+        onFunctionOverride: options.onFunctionOverride,
+    });
+    validateFormulaFunctions(ast, functionRegistry);
+    const optimizedAst = foldFormulaConstants(ast);
+    const references = [];
+    collectFormulaIdentifiers(optimizedAst, references);
+    const identifiers = [];
+    const seenIdentifiers = new Set();
+    for (const reference of references) {
+        const normalized = normalizeFormulaIdentifierKey(reference, options.referenceParserOptions);
+        if (normalized.length === 0 || seenIdentifiers.has(normalized)) {
+            continue;
+        }
+        seenIdentifiers.add(normalized);
+        identifiers.push(normalized);
+    }
+    const contextKeys = Array.from(new Set((() => {
+        const collected = [];
+        collectFormulaContextKeys(optimizedAst, functionRegistry, collected);
+        return collected.map(key => key.trim()).filter(key => key.length > 0);
+    })()));
+    const resolveDependencyToken = (_a = options.resolveDependencyToken) !== null && _a !== void 0 ? _a : ((identifier) => `field:${identifier}`);
+    const deps = [];
+    const dependencyTokenByIdentifier = new Map();
+    const seenDependencyTokens = new Set();
+    for (const identifier of identifiers) {
+        const token = resolveDependencyToken(identifier);
+        dependencyTokenByIdentifier.set(identifier, token);
+        if (seenDependencyTokens.has(token)) {
+            continue;
+        }
+        seenDependencyTokens.add(token);
+        deps.push(token);
+    }
+    return {
+        formula,
+        functionRegistry,
+        optimizedAst,
+        expressionHash: hashFormulaAst(optimizedAst),
+        identifiers,
+        deps,
+        contextKeys,
+        dependencyTokenByIdentifier,
+        hasRowAwareIdentifiers: hasRowAwareFormulaIdentifiers(optimizedAst),
+        hasRuntimeContextFunctions: hasRuntimeContextFormulaFunctions(optimizedAst, functionRegistry),
+    };
+}
+export function analyzeDataGridFormulaFieldDefinition(definition, options = {}) {
+    const analyzed = analyzeFormulaExpression(definition.formula, options);
+    return {
+        formula: analyzed.formula,
+        expressionHash: analyzed.expressionHash,
+        identifiers: analyzed.identifiers,
+        deps: analyzed.deps,
+        contextKeys: analyzed.contextKeys,
+    };
+}
+export function bindCompiledFormulaArtifactToFieldDefinition(artifact, definition, options = {}) {
+    return artifact.bind(definition, options);
+}
+export function compileDataGridFormulaFieldArtifact(definition, options = {}) {
+    const analyzed = analyzeFormulaExpression(definition.formula, options);
+    const dependencyTokenIndexByToken = new Map();
+    for (let tokenIndex = 0; tokenIndex < analyzed.deps.length; tokenIndex += 1) {
+        const token = analyzed.deps[tokenIndex];
+        if (typeof token !== "string") {
+            continue;
+        }
+        dependencyTokenIndexByToken.set(token, tokenIndex);
+    }
+    const resolveIdentifierToken = (identifier) => analyzed.dependencyTokenByIdentifier.get(identifier);
+    const resolveIdentifierTokenIndex = (identifier) => {
+        const token = resolveIdentifierToken(identifier);
+        if (!token) {
+            return undefined;
+        }
+        return dependencyTokenIndexByToken.get(token);
+    };
+    const compileStrategy = (options.compileStrategy === "ast"
+        || options.compileStrategy === "jit"
+        || options.compileStrategy === "auto")
+        ? options.compileStrategy
+        : "auto";
+    const allowDynamicCodegen = options.allowDynamicCodegen !== false;
+    let evaluator;
+    let activeFunctionContext;
+    let batchEvaluator = null;
+    let columnarBatchEvaluator = null;
+    const supportsBatchExecution = !analyzed.hasRowAwareIdentifiers && !analyzed.hasRuntimeContextFunctions;
+    const fusedColumnarBatchEvaluator = supportsBatchExecution
+        ? compileFormulaAstColumnarBatchEvaluatorFused(analyzed.optimizedAst, resolveIdentifierTokenIndex)
+        : null;
+    const vectorColumnarBatchEvaluator = supportsBatchExecution
+        ? compileFormulaAstColumnarBatchEvaluatorVector(analyzed.optimizedAst, resolveIdentifierTokenIndex)
+        : null;
+    const tokenIndexEvaluator = compileFormulaAstTokenIndexEvaluator(analyzed.optimizedAst, analyzed.functionRegistry, resolveIdentifierTokenIndex);
+    if (compileStrategy === "jit" && !allowDynamicCodegen) {
+        throwFormulaError(`Failed to compile JIT evaluator: dynamic code generation is disabled. Use compileStrategy 'ast' or allowDynamicCodegen: true.`);
+    }
+    if (analyzed.hasRowAwareIdentifiers || analyzed.hasRuntimeContextFunctions || compileStrategy === "ast" || !allowDynamicCodegen) {
+        evaluator = compileFormulaAstEvaluator(analyzed.optimizedAst, analyzed.functionRegistry, resolveIdentifierToken, () => activeFunctionContext);
+    }
+    else {
+        try {
+            evaluator = compileFormulaAstEvaluatorJit(analyzed.optimizedAst, analyzed.functionRegistry, resolveIdentifierTokenIndex, analyzed.deps);
+            batchEvaluator = compileFormulaAstBatchEvaluatorJit(analyzed.optimizedAst, analyzed.functionRegistry, resolveIdentifierTokenIndex);
+            columnarBatchEvaluator = compileFormulaAstColumnarBatchEvaluatorJit(analyzed.optimizedAst, analyzed.functionRegistry, resolveIdentifierTokenIndex);
+        }
+        catch (error) {
+            if (compileStrategy === "jit") {
+                const message = error instanceof Error
+                    ? error.message
+                    : String(error !== null && error !== void 0 ? error : "Unknown JIT compile error.");
+                throwFormulaError(`Failed to compile JIT evaluator: ${message}`);
+            }
+            evaluator = compileFormulaAstEvaluator(analyzed.optimizedAst, analyzed.functionRegistry, resolveIdentifierToken);
+        }
+    }
+    const rowFallbackChunkSize = 128;
+    const bind = (fieldDefinition, bindOptions = {}) => {
+        var _a, _b;
+        const name = normalizeFormulaFieldName(fieldDefinition.name, "Formula name");
+        const field = normalizeFormulaFieldName((_a = fieldDefinition.field) !== null && _a !== void 0 ? _a : name, "Formula target field");
+        const runtimeErrorPolicy = (_b = bindOptions.runtimeErrorPolicy) !== null && _b !== void 0 ? _b : "coerce-zero";
+        const batchExecutionMode = analyzed.hasRowAwareIdentifiers || analyzed.hasRuntimeContextFunctions
+            ? "row"
+            : fusedColumnarBatchEvaluator
+                ? "columnar-fused"
+                : columnarBatchEvaluator
+                    ? "columnar-jit"
+                    : vectorColumnarBatchEvaluator
+                        ? "columnar-vector"
+                        : "columnar-ast";
+        const evaluateWithRuntimePolicy = (evaluate, contextMeta) => {
+            var _a;
+            try {
+                return evaluate();
+            }
+            catch (error) {
+                const runtimeError = normalizeFormulaRuntimeError(error, {
+                    formulaName: name,
+                    field,
+                    formula: analyzed.formula,
+                    rowId: contextMeta.rowId,
+                    sourceIndex: contextMeta.sourceIndex,
+                });
+                (_a = bindOptions.onRuntimeError) === null || _a === void 0 ? void 0 : _a.call(bindOptions, runtimeError);
+                if (runtimeErrorPolicy === "throw") {
+                    throw new Error(`[DataGridFormula] ${runtimeError.message}`);
+                }
+                if (runtimeErrorPolicy === "error-value") {
+                    return createFormulaErrorValue(runtimeError);
+                }
+                return 0;
+            }
+        };
+        const evaluateRowWithTokenIndexReader = (contexts, contextIndex, readTokenAt) => {
+            const context = contexts[contextIndex];
+            if (!context) {
+                return 0;
+            }
+            return evaluateWithRuntimePolicy(() => tokenIndexEvaluator((tokenIndex) => readTokenAt(contextIndex, tokenIndex)), {
+                rowId: context.rowId,
+                sourceIndex: context.sourceIndex,
+            });
+        };
+        const buildRowWiseResults = (contexts, readTokenAt, startIndex = 0, endIndex = contexts.length, output) => {
+            const target = output !== null && output !== void 0 ? output : new Array(contexts.length);
+            for (let contextIndex = startIndex; contextIndex < endIndex; contextIndex += 1) {
+                target[contextIndex] = evaluateRowWithTokenIndexReader(contexts, contextIndex, readTokenAt);
+            }
+            return target;
+        };
+        const computeBatch = analyzed.hasRowAwareIdentifiers
+            ? undefined
+            : ((contexts, readTokenByIndex) => {
+                var _a;
+                if (contexts.length === 0) {
+                    return [];
+                }
+                if (batchEvaluator) {
+                    try {
+                        return batchEvaluator(contexts.length, readTokenByIndex);
+                    }
+                    catch {
+                        if (contexts.length > rowFallbackChunkSize) {
+                            const results = new Array(contexts.length);
+                            for (let start = 0; start < contexts.length; start += rowFallbackChunkSize) {
+                                const end = Math.min(start + rowFallbackChunkSize, contexts.length);
+                                const chunkLength = end - start;
+                                try {
+                                    const chunkResult = batchEvaluator(chunkLength, (contextIndex, tokenIndex) => readTokenByIndex(start + contextIndex, tokenIndex));
+                                    for (let offset = 0; offset < chunkLength; offset += 1) {
+                                        results[start + offset] = (_a = chunkResult[offset]) !== null && _a !== void 0 ? _a : 0;
+                                    }
+                                }
+                                catch {
+                                    buildRowWiseResults(contexts, readTokenByIndex, start, end, results);
+                                }
+                            }
+                            return results;
+                        }
+                    }
+                }
+                return buildRowWiseResults(contexts, readTokenByIndex);
+            });
+        const computeBatchColumnar = analyzed.hasRowAwareIdentifiers
+            ? undefined
+            : ((contexts, tokenColumns) => {
+                var _a, _b, _c;
+                if (contexts.length === 0) {
+                    return [];
+                }
+                if (fusedColumnarBatchEvaluator) {
+                    try {
+                        return fusedColumnarBatchEvaluator(contexts.length, tokenColumns);
+                    }
+                    catch {
+                        if (contexts.length > rowFallbackChunkSize) {
+                            const results = new Array(contexts.length);
+                            for (let start = 0; start < contexts.length; start += rowFallbackChunkSize) {
+                                const end = Math.min(start + rowFallbackChunkSize, contexts.length);
+                                const chunkLength = end - start;
+                                const chunkColumns = tokenColumns.map(column => (column ? column.slice(start, end) : []));
+                                try {
+                                    const chunkResult = fusedColumnarBatchEvaluator(chunkLength, chunkColumns);
+                                    for (let offset = 0; offset < chunkLength; offset += 1) {
+                                        results[start + offset] = (_a = chunkResult[offset]) !== null && _a !== void 0 ? _a : 0;
+                                    }
+                                }
+                                catch {
+                                    buildRowWiseResults(contexts, (contextIndex, tokenIndex) => {
+                                        const column = tokenColumns[tokenIndex];
+                                        return column ? column[contextIndex] : undefined;
+                                    }, start, end, results);
+                                }
+                            }
+                            return results;
+                        }
+                    }
+                }
+                if (columnarBatchEvaluator) {
+                    try {
+                        return columnarBatchEvaluator(contexts.length, tokenColumns);
+                    }
+                    catch {
+                        if (contexts.length > rowFallbackChunkSize) {
+                            const results = new Array(contexts.length);
+                            for (let start = 0; start < contexts.length; start += rowFallbackChunkSize) {
+                                const end = Math.min(start + rowFallbackChunkSize, contexts.length);
+                                const chunkLength = end - start;
+                                const chunkColumns = tokenColumns.map(column => (column ? column.slice(start, end) : []));
+                                try {
+                                    const chunkResult = columnarBatchEvaluator(chunkLength, chunkColumns);
+                                    for (let offset = 0; offset < chunkLength; offset += 1) {
+                                        results[start + offset] = (_b = chunkResult[offset]) !== null && _b !== void 0 ? _b : 0;
+                                    }
+                                }
+                                catch {
+                                    buildRowWiseResults(contexts, (contextIndex, tokenIndex) => {
+                                        const column = tokenColumns[tokenIndex];
+                                        return column ? column[contextIndex] : undefined;
+                                    }, start, end, results);
+                                }
+                            }
+                            return results;
+                        }
+                    }
+                }
+                if (vectorColumnarBatchEvaluator) {
+                    try {
+                        return vectorColumnarBatchEvaluator(contexts.length, tokenColumns);
+                    }
+                    catch {
+                        if (contexts.length > rowFallbackChunkSize) {
+                            const results = new Array(contexts.length);
+                            for (let start = 0; start < contexts.length; start += rowFallbackChunkSize) {
+                                const end = Math.min(start + rowFallbackChunkSize, contexts.length);
+                                const chunkLength = end - start;
+                                const chunkColumns = tokenColumns.map(column => (column ? column.slice(start, end) : []));
+                                try {
+                                    const chunkResult = vectorColumnarBatchEvaluator(chunkLength, chunkColumns);
+                                    for (let offset = 0; offset < chunkLength; offset += 1) {
+                                        results[start + offset] = (_c = chunkResult[offset]) !== null && _c !== void 0 ? _c : 0;
+                                    }
+                                }
+                                catch {
+                                    buildRowWiseResults(contexts, (contextIndex, tokenIndex) => {
+                                        const column = tokenColumns[tokenIndex];
+                                        return column ? column[contextIndex] : undefined;
+                                    }, start, end, results);
+                                }
+                            }
+                            return results;
+                        }
+                    }
+                }
+                return buildRowWiseResults(contexts, (contextIndex, tokenIndex) => {
+                    const column = tokenColumns[tokenIndex];
+                    return column ? column[contextIndex] : undefined;
+                });
+            });
+        return {
+            name,
+            field,
+            formula: analyzed.formula,
+            expressionHash: analyzed.expressionHash,
+            identifiers: analyzed.identifiers,
+            deps: analyzed.deps,
+            contextKeys: analyzed.contextKeys,
+            batchExecutionMode,
+            computeBatch,
+            computeBatchColumnar,
+            compute: (context) => evaluateWithRuntimePolicy(() => {
+                activeFunctionContext = context;
+                try {
+                    return evaluator(token => context.get(token));
+                }
+                finally {
+                    activeFunctionContext = undefined;
+                }
+            }, {
+                rowId: context.rowId,
+                sourceIndex: context.sourceIndex,
+            }),
+        };
+    };
+    return {
+        formula: analyzed.formula,
+        expressionHash: analyzed.expressionHash,
+        identifiers: analyzed.identifiers,
+        deps: analyzed.deps,
+        contextKeys: analyzed.contextKeys,
+        bind,
+    };
+}
+export function compileDataGridFormulaFieldDefinition(definition, options = {}) {
+    const artifact = compileDataGridFormulaFieldArtifact(definition, options);
+    return bindCompiledFormulaArtifactToFieldDefinition(artifact, definition, options);
+}

package/dist/runtime/evaluators.d.ts

@@ -0,0 +1,5 @@
+export { compileFormulaAstEvaluator, compileFormulaAstTokenIndexEvaluator, } from "../evaluators/interpreter.js";
+export { compileFormulaAstEvaluatorJit, compileFormulaAstBatchEvaluatorJit, compileFormulaAstColumnarBatchEvaluatorJit, } from "../evaluators/jit.js";
+export { compileFormulaAstColumnarBatchEvaluatorFused, } from "../evaluators/columnar.js";
+export { compileFormulaAstColumnarBatchEvaluatorVector, } from "../evaluators/vector.js";
+//# sourceMappingURL=evaluators.d.ts.map

package/dist/runtime/evaluators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluators.d.ts","sourceRoot":"","sources":["../../src/runtime/evaluators.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,0BAA0B,EAC1B,oCAAoC,GACrC,MAAM,8BAA8B,CAAA;AAErC,OAAO,EACL,6BAA6B,EAC7B,kCAAkC,EAClC,0CAA0C,GAC3C,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,4CAA4C,GAC7C,MAAM,2BAA2B,CAAA;AAElC,OAAO,EACL,6CAA6C,GAC9C,MAAM,yBAAyB,CAAA"}

package/dist/runtime/evaluators.js

@@ -0,0 +1,6 @@
+// Runtime evaluator entrypoints. Backend-specific implementation lives in
+// ../evaluators/* while this file stays a stable runtime-facing barrel.
+export { compileFormulaAstEvaluator, compileFormulaAstTokenIndexEvaluator, } from "../evaluators/interpreter.js";
+export { compileFormulaAstEvaluatorJit, compileFormulaAstBatchEvaluatorJit, compileFormulaAstColumnarBatchEvaluatorJit, } from "../evaluators/jit.js";
+export { compileFormulaAstColumnarBatchEvaluatorFused, } from "../evaluators/columnar.js";
+export { compileFormulaAstColumnarBatchEvaluatorVector, } from "../evaluators/vector.js";

package/dist/runtime/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./compile.js";
+export * from "./evaluators.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA"}

package/dist/runtime/index.js

@@ -0,0 +1,2 @@
+export * from "./compile.js";
+export * from "./evaluators.js";

package/dist/runtime/types.d.ts

@@ -0,0 +1,63 @@
+import type { DataGridComputedDependencyToken, DataGridComputedFieldComputeContext, DataGridFormulaFieldDefinition, DataGridFormulaRuntimeError, DataGridFormulaValue } from "../coreTypes.js";
+import type { DataGridFormulaAstNode, DataGridFormulaFunctionArity, DataGridFormulaFunctionRegistry, DataGridFormulaReferenceParserOptions, DataGridFormulaToken } from "../syntax/types.js";
+export interface DataGridFormulaFunctionRuntime {
+    name: string;
+    arity?: DataGridFormulaFunctionArity;
+    contextKeys: readonly string[];
+    resolveContextKeys?: (args: readonly DataGridFormulaAstNode[]) => readonly string[];
+    requiresRuntimeContext: boolean;
+    compute: (args: readonly DataGridFormulaValue[], context?: DataGridComputedFieldComputeContext<unknown>) => unknown;
+}
+export type DataGridFormulaRuntimeErrorPolicy = "coerce-zero" | "throw" | "error-value";
+export type DataGridFormulaCompileStrategy = "auto" | "ast" | "jit";
+export interface DataGridFormulaCompileOptions {
+    resolveDependencyToken?: (identifier: string) => DataGridComputedDependencyToken;
+    functionRegistry?: DataGridFormulaFunctionRegistry;
+    referenceParserOptions?: DataGridFormulaReferenceParserOptions;
+    onFunctionOverride?: (functionName: string) => void;
+    runtimeErrorPolicy?: DataGridFormulaRuntimeErrorPolicy;
+    onRuntimeError?: (error: DataGridFormulaRuntimeError) => void;
+    compileStrategy?: DataGridFormulaCompileStrategy;
+    allowDynamicCodegen?: boolean;
+}
+export interface DataGridCompiledFormulaField<TRow = unknown> {
+    name: string;
+    field: string;
+    formula: string;
+    expressionHash: string;
+    identifiers: readonly string[];
+    deps: readonly DataGridComputedDependencyToken[];
+    contextKeys: readonly string[];
+    batchExecutionMode?: DataGridCompiledFormulaBatchExecutionMode;
+    compute: (context: DataGridComputedFieldComputeContext<TRow>) => DataGridFormulaValue;
+    computeBatch?: (contexts: readonly DataGridCompiledFormulaBatchContext<TRow>[], readTokenByIndex: (contextIndex: number, tokenIndex: number) => unknown) => readonly DataGridFormulaValue[];
+    computeBatchColumnar?: (contexts: readonly DataGridCompiledFormulaBatchContext<TRow>[], tokenColumns: readonly (readonly unknown[])[]) => readonly DataGridFormulaValue[];
+}
+export interface DataGridFormulaExpressionAnalysis {
+    formula: string;
+    expressionHash: string;
+    identifiers: readonly string[];
+    deps: readonly DataGridComputedDependencyToken[];
+    contextKeys: readonly string[];
+}
+export interface DataGridCompiledFormulaArtifact<TRow = unknown> extends DataGridFormulaExpressionAnalysis {
+    bind: (definition: DataGridFormulaFieldDefinition, options?: Pick<DataGridFormulaCompileOptions, "runtimeErrorPolicy" | "onRuntimeError">) => DataGridCompiledFormulaField<TRow>;
+}
+export interface DataGridCompiledFormulaBatchContext<TRow = unknown> {
+    row: TRow;
+    rowId: string | number;
+    sourceIndex: number;
+}
+export type DataGridCompiledFormulaBatchExecutionMode = "row" | "batch" | "columnar-ast" | "columnar-jit" | "columnar-fused" | "columnar-vector";
+export type DataGridFormulaTokenValueReader<TKey> = (token: TKey) => unknown;
+export type DataGridFormulaEvaluatorForToken<TKey> = (readTokenValue: DataGridFormulaTokenValueReader<TKey>) => DataGridFormulaValue;
+export type DataGridFormulaEvaluator = DataGridFormulaEvaluatorForToken<DataGridComputedDependencyToken>;
+export type DataGridFormulaTokenIndexEvaluator = DataGridFormulaEvaluatorForToken<number>;
+export type DataGridFormulaBatchEvaluator = (contextsCount: number, readTokenByIndex: (contextIndex: number, tokenIndex: number) => unknown) => readonly DataGridFormulaValue[];
+export type DataGridFormulaColumnarBatchEvaluator = (contextsCount: number, tokenColumns: readonly (readonly unknown[])[]) => readonly DataGridFormulaValue[];
+export interface DataGridFormulaParseResult {
+    formula: string;
+    tokens: readonly DataGridFormulaToken[];
+    ast: DataGridFormulaAstNode;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"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"}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/syntax/analysis.d.ts

@@ -0,0 +1,14 @@
+import type { DataGridFormulaDiagnosticsResult, DataGridFormulaExplainResult, DataGridFormulaFieldExplainResult } from "../analysis/types.js";
+export type { DataGridFormulaDiagnosticsResult, DataGridFormulaExplainDependency, DataGridFormulaExplainDependencyDomain, DataGridFormulaExplainNode, DataGridFormulaExplainResult, DataGridFormulaFieldExplainResult, } from "../analysis/types.js";
+import type { DataGridFormulaCompileOptions, DataGridFormulaParseResult } from "../runtime/types.js";
+export type { DataGridCompiledFormulaArtifact, DataGridCompiledFormulaBatchContext, DataGridCompiledFormulaBatchExecutionMode, DataGridCompiledFormulaField, DataGridFormulaBatchEvaluator, DataGridFormulaColumnarBatchEvaluator, DataGridFormulaCompileOptions, DataGridFormulaCompileStrategy, DataGridFormulaEvaluator, DataGridFormulaEvaluatorForToken, DataGridFormulaExpressionAnalysis, DataGridFormulaFunctionRuntime, DataGridFormulaParseResult, DataGridFormulaRuntimeErrorPolicy, DataGridFormulaTokenIndexEvaluator, DataGridFormulaTokenValueReader, } from "../runtime/types.js";
+export type { DataGridFormulaAstNode, DataGridFormulaDiagnostic, DataGridFormulaFunctionArity, DataGridFormulaFunctionDefinition, DataGridFormulaFunctionRegistry, DataGridFormulaOperator, DataGridFormulaReferenceSegment, DataGridFormulaSourceSpan, DataGridFormulaToken, } from "./types.js";
+export declare function parseDataGridFormulaExpression(formula: string, options?: Pick<DataGridFormulaCompileOptions, "referenceParserOptions">): DataGridFormulaParseResult;
+export declare function diagnoseDataGridFormulaExpression(formula: string, options?: Pick<DataGridFormulaCompileOptions, "functionRegistry" | "onFunctionOverride" | "referenceParserOptions">): DataGridFormulaDiagnosticsResult;
+export declare function explainDataGridFormulaExpression(formula: string, options?: Pick<DataGridFormulaCompileOptions, "resolveDependencyToken" | "functionRegistry" | "onFunctionOverride" | "referenceParserOptions">): DataGridFormulaExplainResult;
+export declare function explainDataGridFormulaFieldDefinition(definition: {
+    name: string;
+    field?: string;
+    formula: string;
+}, options?: Pick<DataGridFormulaCompileOptions, "resolveDependencyToken" | "functionRegistry" | "onFunctionOverride">): DataGridFormulaFieldExplainResult;
+//# sourceMappingURL=analysis.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../../src/syntax/analysis.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,gCAAgC,EAGhC,4BAA4B,EAC5B,iCAAiC,EAClC,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,gCAAgC,EAChC,gCAAgC,EAChC,sCAAsC,EACtC,0BAA0B,EAC1B,4BAA4B,EAC5B,iCAAiC,GAClC,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EACV,6BAA6B,EAE7B,0BAA0B,EAC3B,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,+BAA+B,EAC/B,mCAAmC,EACnC,yCAAyC,EACzC,4BAA4B,EAC5B,6BAA6B,EAC7B,qCAAqC,EACrC,6BAA6B,EAC7B,8BAA8B,EAC9B,wBAAwB,EACxB,gCAAgC,EAChC,iCAAiC,EACjC,8BAA8B,EAC9B,0BAA0B,EAC1B,iCAAiC,EACjC,kCAAkC,EAClC,+BAA+B,GAChC,MAAM,qBAAqB,CAAA;AAU5B,YAAY,EACV,sBAAsB,EACtB,yBAAyB,EACzB,4BAA4B,EAC5B,iCAAiC,EACjC,+BAA+B,EAC/B,uBAAuB,EACvB,+BAA+B,EAC/B,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,YAAY,CAAA;AAwHnB,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,IAAI,CAAC,6BAA6B,EAAE,wBAAwB,CAAM,GAC1E,0BAA0B,CAK5B;AAED,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,IAAI,CAAC,6BAA6B,EAAE,kBAAkB,GAAG,oBAAoB,GAAG,wBAAwB,CAAM,GACtH,gCAAgC,CAalC;AAED,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,IAAI,CAAC,6BAA6B,EAAE,wBAAwB,GAAG,kBAAkB,GAAG,oBAAoB,GAAG,wBAAwB,CAAM,GACjJ,4BAA4B,CAyB9B;AAED,wBAAgB,qCAAqC,CACnD,UAAU,EAAE;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,EACD,OAAO,GAAE,IAAI,CAAC,6BAA6B,EAAE,wBAAwB,GAAG,kBAAkB,GAAG,oBAAoB,CAAM,GACtH,iCAAiC,CASnC"}