@affino/datagrid-formula-engine 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 affino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# `@affino/datagrid-formula-engine`
+
+Community formula engine package for Affino DataGrid.
+
+## Purpose
+
+This package establishes a dedicated formula-engine boundary without forcing a risky implementation move out of `@affino/datagrid-core` in one step.
+
+Current state:
+
+- community-safe formula parsing / analysis / compile APIs live here
+- graph / execution-plan APIs live here
+- low-level row-model integration still lives in `@affino/datagrid-core`
+
+## Community surface
+
+The package intentionally exposes the base formula-engine surface:
+
+- parse / diagnose / explain
+- compile formula field definitions and artifacts
+- formula value utilities
+- formula graph and execution-plan builders
+- formula-related type contracts
+
+## Planned enterprise surface
+
+These are reserved as future enterprise candidates and are intentionally not split into public package entrypoints yet:
+
+- premium worker-owned formula runtime
+- advanced fused / vector execution tiers
+- formula profiler / diagnostics UI
+- collaboration / snapshot / audit tooling around formula execution
+- premium performance policies and high-scale runtime orchestration
+
+## Boundary rule
+
+Use `@affino/datagrid-formula-engine` for formula APIs.
+Keep grid row-model orchestration and snapshot integration in `@affino/datagrid-core` until the next extraction phase.

package/dist/analysis/index.d.ts

@@ -0,0 +1,2 @@
+export type { DataGridFormulaDiagnosticsResult, DataGridFormulaExplainDependencyDomain, DataGridFormulaExplainDependency, DataGridFormulaExplainNode, DataGridFormulaExplainResult, DataGridFormulaFieldExplainResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analysis/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,gCAAgC,EAChC,sCAAsC,EACtC,gCAAgC,EAChC,0BAA0B,EAC1B,4BAA4B,EAC5B,iCAAiC,GAClC,MAAM,YAAY,CAAA"}

package/dist/analysis/index.js

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

package/dist/analysis/types.d.ts

@@ -0,0 +1,44 @@
+import type { DataGridComputedDependencyToken, DataGridFormulaValue } from "../coreTypes.js";
+import type { DataGridFormulaAstNode, DataGridFormulaDiagnostic, DataGridFormulaOperator, DataGridFormulaRowSelector, DataGridFormulaSourceSpan, DataGridFormulaToken } from "../syntax/types.js";
+export interface DataGridFormulaDiagnosticsResult {
+    ok: boolean;
+    formula: string;
+    diagnostics: readonly DataGridFormulaDiagnostic[];
+    tokens?: readonly DataGridFormulaToken[];
+    ast?: DataGridFormulaAstNode;
+}
+export type DataGridFormulaExplainDependencyDomain = "field" | "computed" | "meta" | "unknown";
+export interface DataGridFormulaExplainDependency {
+    identifier: string;
+    token: DataGridComputedDependencyToken;
+    domain: DataGridFormulaExplainDependencyDomain;
+    value: string;
+    rowSelector?: DataGridFormulaRowSelector;
+}
+export interface DataGridFormulaExplainNode {
+    kind: DataGridFormulaAstNode["kind"];
+    label: string;
+    span: DataGridFormulaSourceSpan;
+    children: readonly DataGridFormulaExplainNode[];
+    name?: string;
+    sheetReference?: string | null;
+    referenceName?: string;
+    rangeReferenceName?: string | null;
+    rowSelector?: DataGridFormulaRowSelector;
+    operator?: DataGridFormulaOperator | "CALL";
+    value?: DataGridFormulaValue;
+}
+export interface DataGridFormulaExplainResult {
+    formula: string;
+    tokens: readonly DataGridFormulaToken[];
+    ast: DataGridFormulaAstNode;
+    identifiers: readonly string[];
+    dependencies: readonly DataGridFormulaExplainDependency[];
+    contextKeys: readonly string[];
+    tree: DataGridFormulaExplainNode;
+}
+export interface DataGridFormulaFieldExplainResult extends DataGridFormulaExplainResult {
+    name: string;
+    field: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analysis/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAC5F,OAAO,KAAK,EACV,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACrB,MAAM,oBAAoB,CAAA;AAE3B,MAAM,WAAW,gCAAgC;IAC/C,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACjD,MAAM,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IACxC,GAAG,CAAC,EAAE,sBAAsB,CAAA;CAC7B;AAED,MAAM,MAAM,sCAAsC,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAA;AAE9F,MAAM,WAAW,gCAAgC;IAC/C,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,+BAA+B,CAAA;IACtC,MAAM,EAAE,sCAAsC,CAAA;IAC9C,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,0BAA0B,CAAA;CACzC;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,sBAAsB,CAAC,MAAM,CAAC,CAAA;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,yBAAyB,CAAA;IAC/B,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAA;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,WAAW,CAAC,EAAE,0BAA0B,CAAA;IACxC,QAAQ,CAAC,EAAE,uBAAuB,GAAG,MAAM,CAAA;IAC3C,KAAK,CAAC,EAAE,oBAAoB,CAAA;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAA;IACvC,GAAG,EAAE,sBAAsB,CAAA;IAC3B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,YAAY,EAAE,SAAS,gCAAgC,EAAE,CAAA;IACzD,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,IAAI,EAAE,0BAA0B,CAAA;CACjC;AAED,MAAM,WAAW,iCAAkC,SAAQ,4BAA4B;IACrF,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd"}

package/dist/analysis/types.js

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

package/dist/contracts.d.ts

@@ -0,0 +1,177 @@
+import type { DataGridFormulaExecutionPlanSnapshot, DataGridFormulaGraphSnapshot } from "./graph/index.js";
+export type DataGridRowId = string | number;
+export type DataGridComputedDependencyToken = `field:${string}` | `computed:${string}` | `meta:${string}` | (string & {});
+export type DataGridFormulaReferenceDomain = "field" | "computed" | "meta";
+export type DataGridFormulaReferenceRowDomain = {
+    kind: "current";
+} | {
+    kind: "absolute";
+    rowIndex: number;
+} | {
+    kind: "absolute-window";
+    startRowIndex: number;
+    endRowIndex: number;
+} | {
+    kind: "relative";
+    offset: number;
+} | {
+    kind: "window";
+    startOffset: number;
+    endOffset: number;
+};
+export interface DataGridFormulaReferenceDescriptor {
+    domain: DataGridFormulaReferenceDomain;
+    name: string;
+    rowDomain: DataGridFormulaReferenceRowDomain;
+}
+export declare function serializeDataGridComputedDependencyToken(reference: DataGridFormulaReferenceDescriptor): DataGridComputedDependencyToken;
+export declare function parseDataGridComputedDependencyToken(token: DataGridComputedDependencyToken): DataGridFormulaReferenceDescriptor | null;
+export type DataGridFormulaMetaField = "rowId" | "rowKey" | "sourceIndex" | "originalIndex" | "kind" | "isGroup";
+export declare const DATAGRID_FORMULA_META_FIELDS: readonly ["rowId", "rowKey", "sourceIndex", "originalIndex", "kind", "isGroup"];
+export declare function isDataGridFormulaMetaField(value: unknown): value is DataGridFormulaMetaField;
+export interface DataGridComputedFieldComputeContext<T = unknown> {
+    row: T;
+    rowId: DataGridRowId;
+    sourceIndex: number;
+    get: (token: DataGridComputedDependencyToken) => unknown;
+    getContextValue?: (key: string) => unknown;
+}
+export interface DataGridComputedFieldDefinition<T = unknown> {
+    name: string;
+    field?: string;
+    deps: readonly DataGridComputedDependencyToken[];
+    compute: (context: DataGridComputedFieldComputeContext<T>) => unknown;
+}
+export interface DataGridComputedFieldSnapshot {
+    name: string;
+    field: string;
+    deps: readonly DataGridComputedDependencyToken[];
+}
+export interface DataGridFormulaFieldDefinition {
+    name: string;
+    field?: string;
+    formula: string;
+}
+export interface DataGridFormulaFieldSnapshot {
+    name: string;
+    field: string;
+    formula: string;
+    deps: readonly DataGridComputedDependencyToken[];
+    contextKeys: readonly string[];
+}
+export interface DataGridFormulaTableRowsSource<Row = unknown> {
+    rows: readonly Row[];
+    resolveRow?: (row: Row, index: number) => unknown;
+}
+export type DataGridFormulaTableSource = readonly unknown[] | DataGridFormulaTableRowsSource;
+export interface DataGridFormulaContextRecomputeRequest {
+    contextKeys: readonly string[];
+    rowIds?: readonly DataGridRowId[];
+}
+export type DataGridFormulaCyclePolicy = "error" | "iterative";
+export interface DataGridFormulaIterativeCalculationOptions {
+    maxIterations?: number;
+    epsilon?: number;
+}
+export type DataGridFormulaRuntimeErrorCode = "DIV_ZERO" | "FUNCTION_UNKNOWN" | "FUNCTION_ARITY" | "EVAL_ERROR";
+export interface DataGridFormulaErrorValue {
+    kind: "error";
+    code: DataGridFormulaRuntimeErrorCode;
+    message: string;
+}
+export type DataGridFormulaScalarValue = number | string | boolean | Date | DataGridFormulaErrorValue | null;
+export type DataGridFormulaArrayValue = readonly DataGridFormulaScalarValue[];
+export type DataGridFormulaValue = DataGridFormulaScalarValue | DataGridFormulaArrayValue;
+export interface DataGridFormulaRuntimeError {
+    code: DataGridFormulaRuntimeErrorCode;
+    message: string;
+    formulaName?: string;
+    field?: string;
+    formula?: string;
+    functionName?: string;
+    operator?: string;
+    rowId?: DataGridRowId;
+    sourceIndex?: number;
+}
+export interface DataGridProjectionFormulaDiagnostics {
+    recomputedFields: readonly string[];
+    runtimeErrorCount: number;
+    runtimeErrors: readonly DataGridFormulaRuntimeError[];
+    compileCache?: {
+        hits: number;
+        misses: number;
+        size: number;
+    };
+}
+export interface DataGridFormulaDirtyCause {
+    kind: "all" | "field" | "computed" | "context";
+    value?: string;
+    rows: number;
+}
+export interface DataGridFormulaDirtyRowCause {
+    kind: "all" | "field" | "computed" | "context";
+    value?: string;
+}
+export interface DataGridFormulaRowNodeRecomputeDiagnostics {
+    name: string;
+    field: string;
+    causes: readonly DataGridFormulaDirtyRowCause[];
+}
+export interface DataGridFormulaRowRecomputeDiagnosticsEntry {
+    rowId: DataGridRowId;
+    sourceIndex: number;
+    nodes: readonly DataGridFormulaRowNodeRecomputeDiagnostics[];
+}
+export interface DataGridFormulaRowRecomputeDiagnostics {
+    rows: readonly DataGridFormulaRowRecomputeDiagnosticsEntry[];
+}
+export interface DataGridFormulaNodeComputeDiagnostics {
+    name: string;
+    field: string;
+    dirty: boolean;
+    touched: boolean;
+    runtimeMode?: "row" | "batch" | "columnar-ast" | "columnar-jit" | "columnar-fused" | "columnar-vector";
+    evaluations: number;
+    dirtyRows: number;
+    dirtyCauses: readonly DataGridFormulaDirtyCause[];
+    iterative?: boolean;
+    converged?: boolean;
+    iterationCount?: number;
+    cycleGroup?: readonly string[];
+}
+export interface DataGridFormulaComputeStageDiagnostics {
+    strategy?: "row" | "column-cache";
+    rowsTouched: number;
+    changedRows: number;
+    fieldsTouched: readonly string[];
+    evaluations: number;
+    skippedByObjectIs: number;
+    dirtyRows: number;
+    dirtyNodes: readonly string[];
+    nodes?: readonly DataGridFormulaNodeComputeDiagnostics[];
+}
+export interface DataGridFormulaRuntimeIntegration<T = unknown> {
+    registerComputedField?(definition: DataGridComputedFieldDefinition<T>): void;
+    getComputedFields?(): readonly DataGridComputedFieldSnapshot[];
+    recomputeComputedFields?(rowIds?: readonly DataGridRowId[]): number;
+    registerFormulaField?(definition: DataGridFormulaFieldDefinition): void;
+    getFormulaFields?(): readonly DataGridFormulaFieldSnapshot[];
+    recomputeFormulaContext?(request: DataGridFormulaContextRecomputeRequest): number;
+    setFormulaTable?(name: string, rows: readonly unknown[]): void;
+    removeFormulaTable?(name: string): boolean;
+    getFormulaTableNames?(): readonly string[];
+    registerFormulaFunction?(name: string, definition: {
+        arity?: number | {
+            min: number;
+            max?: number;
+        };
+        compute: (args: readonly DataGridFormulaValue[], context?: DataGridComputedFieldComputeContext<T>) => unknown;
+    } | ((args: readonly DataGridFormulaValue[], context?: DataGridComputedFieldComputeContext<T>) => unknown)): void;
+    unregisterFormulaFunction?(name: string): boolean;
+    getFormulaFunctionNames?(): readonly string[];
+    getFormulaExecutionPlan?(): DataGridFormulaExecutionPlanSnapshot | null;
+    getFormulaGraph?(): DataGridFormulaGraphSnapshot | null;
+    getFormulaComputeStageDiagnostics?(): DataGridFormulaComputeStageDiagnostics | null;
+    getFormulaRowRecomputeDiagnostics?(): DataGridFormulaRowRecomputeDiagnostics | null;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

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

package/dist/contracts.js

@@ -0,0 +1,140 @@
+const DATAGRID_FORMULA_ROW_TOKEN_SEPARATOR = "::row::";
+function normalizeDataGridFormulaReferenceName(value) {
+    const normalized = value.trim();
+    if (normalized.length === 0) {
+        throw new Error("[DataGridFormula] Reference name must be non-empty.");
+    }
+    return normalized;
+}
+function normalizeDataGridFormulaReferenceRowDomain(rowDomain) {
+    if (!rowDomain || rowDomain.kind === "current") {
+        return { kind: "current" };
+    }
+    if (rowDomain.kind === "absolute") {
+        return { kind: "absolute", rowIndex: Math.trunc(rowDomain.rowIndex) };
+    }
+    if (rowDomain.kind === "absolute-window") {
+        return {
+            kind: "absolute-window",
+            startRowIndex: Math.trunc(rowDomain.startRowIndex),
+            endRowIndex: Math.trunc(rowDomain.endRowIndex),
+        };
+    }
+    if (rowDomain.kind === "relative") {
+        return { kind: "relative", offset: Math.trunc(rowDomain.offset) };
+    }
+    return {
+        kind: "window",
+        startOffset: Math.trunc(rowDomain.startOffset),
+        endOffset: Math.trunc(rowDomain.endOffset),
+    };
+}
+function serializeDataGridFormulaReferenceRowDomain(rowDomain) {
+    if (rowDomain.kind === "current") {
+        return null;
+    }
+    if (rowDomain.kind === "absolute") {
+        return `absolute:${rowDomain.rowIndex}`;
+    }
+    if (rowDomain.kind === "absolute-window") {
+        return `absolute-window:${rowDomain.startRowIndex}:${rowDomain.endRowIndex}`;
+    }
+    if (rowDomain.kind === "relative") {
+        return `relative:${rowDomain.offset}`;
+    }
+    return `window:${rowDomain.startOffset}:${rowDomain.endOffset}`;
+}
+function parseDataGridFormulaReferenceRowDomain(value) {
+    const normalized = value.trim();
+    if (normalized.startsWith("absolute:")) {
+        const rowIndex = Number(normalized.slice("absolute:".length));
+        if (Number.isInteger(rowIndex)) {
+            return { kind: "absolute", rowIndex };
+        }
+        return null;
+    }
+    if (normalized.startsWith("relative:")) {
+        const offset = Number(normalized.slice("relative:".length));
+        if (Number.isInteger(offset)) {
+            return { kind: "relative", offset };
+        }
+        return null;
+    }
+    if (normalized.startsWith("absolute-window:")) {
+        const payload = normalized.slice("absolute-window:".length);
+        const separatorIndex = payload.indexOf(":");
+        if (separatorIndex <= 0) {
+            return null;
+        }
+        const startRowIndex = Number(payload.slice(0, separatorIndex));
+        const endRowIndex = Number(payload.slice(separatorIndex + 1));
+        if (Number.isInteger(startRowIndex) && Number.isInteger(endRowIndex)) {
+            return { kind: "absolute-window", startRowIndex, endRowIndex };
+        }
+        return null;
+    }
+    if (normalized.startsWith("window:")) {
+        const payload = normalized.slice("window:".length);
+        const separatorIndex = payload.indexOf(":");
+        if (separatorIndex <= 0) {
+            return null;
+        }
+        const startOffset = Number(payload.slice(0, separatorIndex));
+        const endOffset = Number(payload.slice(separatorIndex + 1));
+        if (Number.isInteger(startOffset) && Number.isInteger(endOffset)) {
+            return { kind: "window", startOffset, endOffset };
+        }
+        return null;
+    }
+    return null;
+}
+export function serializeDataGridComputedDependencyToken(reference) {
+    const name = normalizeDataGridFormulaReferenceName(reference.name);
+    const rowDomain = normalizeDataGridFormulaReferenceRowDomain(reference.rowDomain);
+    const serializedRowDomain = serializeDataGridFormulaReferenceRowDomain(rowDomain);
+    if (!serializedRowDomain) {
+        return `${reference.domain}:${name}`;
+    }
+    return `${reference.domain}:${name}${DATAGRID_FORMULA_ROW_TOKEN_SEPARATOR}${serializedRowDomain}`;
+}
+export function parseDataGridComputedDependencyToken(token) {
+    if (typeof token !== "string") {
+        return null;
+    }
+    const normalized = token.trim();
+    const separatorIndex = normalized.indexOf(":");
+    if (separatorIndex <= 0) {
+        return null;
+    }
+    const domain = normalized.slice(0, separatorIndex).trim();
+    if (domain !== "field" && domain !== "computed" && domain !== "meta") {
+        return null;
+    }
+    const payload = normalized.slice(separatorIndex + 1);
+    const rowSeparatorIndex = payload.indexOf(DATAGRID_FORMULA_ROW_TOKEN_SEPARATOR);
+    if (rowSeparatorIndex < 0) {
+        return {
+            domain,
+            name: normalizeDataGridFormulaReferenceName(payload),
+            rowDomain: { kind: "current" },
+        };
+    }
+    const name = normalizeDataGridFormulaReferenceName(payload.slice(0, rowSeparatorIndex));
+    const rowDomain = parseDataGridFormulaReferenceRowDomain(payload.slice(rowSeparatorIndex + DATAGRID_FORMULA_ROW_TOKEN_SEPARATOR.length));
+    if (!rowDomain) {
+        return null;
+    }
+    return { domain, name, rowDomain };
+}
+export const DATAGRID_FORMULA_META_FIELDS = Object.freeze([
+    "rowId",
+    "rowKey",
+    "sourceIndex",
+    "originalIndex",
+    "kind",
+    "isGroup",
+]);
+export function isDataGridFormulaMetaField(value) {
+    return typeof value === "string"
+        && DATAGRID_FORMULA_META_FIELDS.includes(value);
+}

package/dist/coreTypes.d.ts

@@ -0,0 +1,2 @@
+export type { DataGridComputedDependencyToken, DataGridFormulaReferenceDescriptor, DataGridFormulaReferenceDomain, DataGridFormulaReferenceRowDomain, DataGridComputedFieldComputeContext, DataGridComputedFieldDefinition, DataGridComputedFieldSnapshot, DataGridFormulaMetaField, DataGridFormulaContextRecomputeRequest, DataGridFormulaCyclePolicy, DataGridFormulaFieldDefinition, DataGridFormulaFieldSnapshot, DataGridFormulaTableRowsSource, DataGridFormulaTableSource, DataGridFormulaArrayValue, DataGridFormulaErrorValue, DataGridFormulaIterativeCalculationOptions, DataGridFormulaScalarValue, DataGridFormulaValue, DataGridFormulaRuntimeErrorCode, DataGridFormulaRuntimeError, DataGridFormulaDirtyCause, DataGridFormulaDirtyRowCause, DataGridProjectionFormulaDiagnostics, DataGridFormulaComputeStageDiagnostics, DataGridFormulaNodeComputeDiagnostics, DataGridFormulaRowNodeRecomputeDiagnostics, DataGridFormulaRowRecomputeDiagnosticsEntry, DataGridFormulaRowRecomputeDiagnostics, DataGridFormulaRuntimeIntegration, DataGridRowId, } from "./contracts.js";
+//# sourceMappingURL=coreTypes.d.ts.map

package/dist/coreTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coreTypes.d.ts","sourceRoot":"","sources":["../src/coreTypes.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,+BAA+B,EAC/B,kCAAkC,EAClC,8BAA8B,EAC9B,iCAAiC,EACjC,mCAAmC,EACnC,+BAA+B,EAC/B,6BAA6B,EAC7B,wBAAwB,EACxB,sCAAsC,EACtC,0BAA0B,EAC1B,8BAA8B,EAC9B,4BAA4B,EAC5B,8BAA8B,EAC9B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,0CAA0C,EAC1C,0BAA0B,EAC1B,oBAAoB,EACpB,+BAA+B,EAC/B,2BAA2B,EAC3B,yBAAyB,EACzB,4BAA4B,EAC5B,oCAAoC,EACpC,sCAAsC,EACtC,qCAAqC,EACrC,0CAA0C,EAC1C,2CAA2C,EAC3C,sCAAsC,EACtC,iCAAiC,EACjC,aAAa,GACd,MAAM,gBAAgB,CAAA"}

package/dist/coreTypes.js

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

package/dist/dependency/index.d.ts

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

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

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

package/dist/dependency/index.js

@@ -0,0 +1 @@
+export * from "../graph/index.js";

package/dist/evaluators/columnar.d.ts

@@ -0,0 +1,6 @@
+import type { DataGridFormulaColumnarBatchEvaluator } from "../runtime/types.js";
+import { type DataGridFormulaAstNode } from "../syntax/ast.js";
+import { type DataGridFormulaFusedColumnKernel } from "./shared.js";
+export declare function compileFormulaAstFusedColumnKernel(root: DataGridFormulaAstNode, resolveIdentifierTokenIndex: (identifier: string) => number | undefined): DataGridFormulaFusedColumnKernel | null;
+export declare function compileFormulaAstColumnarBatchEvaluatorFused(root: DataGridFormulaAstNode, resolveIdentifierTokenIndex: (identifier: string) => number | undefined): DataGridFormulaColumnarBatchEvaluator | null;
+//# sourceMappingURL=columnar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"columnar.d.ts","sourceRoot":"","sources":["../../src/evaluators/columnar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,qBAAqB,CAAA;AAChF,OAAO,EACL,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAKL,KAAK,gCAAgC,EACtC,MAAM,aAAa,CAAA;AAEpB,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,sBAAsB,EAC5B,2BAA2B,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACtE,gCAAgC,GAAG,IAAI,CAgCzC;AAED,wBAAgB,4CAA4C,CAC1D,IAAI,EAAE,sBAAsB,EAC5B,2BAA2B,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACtE,qCAAqC,GAAG,IAAI,CAM9C"}

package/dist/evaluators/columnar.js

@@ -0,0 +1,39 @@
+import {} from "../syntax/ast.js";
+import { createFormulaBinaryColumnKernel, createFormulaConstantColumnKernel, createFormulaIdentifierColumnKernel, createFormulaUnaryColumnKernel, } from "./shared.js";
+export function compileFormulaAstFusedColumnKernel(root, resolveIdentifierTokenIndex) {
+    if (root.kind === "number") {
+        return createFormulaConstantColumnKernel(root.value);
+    }
+    if (root.kind === "literal") {
+        return createFormulaConstantColumnKernel(root.value);
+    }
+    if (root.kind === "identifier") {
+        return createFormulaIdentifierColumnKernel(resolveIdentifierTokenIndex(root.name));
+    }
+    if (root.kind === "call") {
+        return null;
+    }
+    if (root.kind === "unary") {
+        const valueKernel = compileFormulaAstFusedColumnKernel(root.value, resolveIdentifierTokenIndex);
+        if (!valueKernel) {
+            return null;
+        }
+        return createFormulaUnaryColumnKernel(valueKernel, root.operator);
+    }
+    if (root.operator === "AND" || root.operator === "OR") {
+        return null;
+    }
+    const leftKernel = compileFormulaAstFusedColumnKernel(root.left, resolveIdentifierTokenIndex);
+    const rightKernel = compileFormulaAstFusedColumnKernel(root.right, resolveIdentifierTokenIndex);
+    if (!leftKernel || !rightKernel) {
+        return null;
+    }
+    return createFormulaBinaryColumnKernel(leftKernel, rightKernel, root.operator);
+}
+export function compileFormulaAstColumnarBatchEvaluatorFused(root, resolveIdentifierTokenIndex) {
+    const fusedKernel = compileFormulaAstFusedColumnKernel(root, resolveIdentifierTokenIndex);
+    if (!fusedKernel) {
+        return null;
+    }
+    return (contextsCount, tokenColumns) => fusedKernel(contextsCount, tokenColumns);
+}

package/dist/evaluators/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./interpreter.js";
+export * from "./jit.js";
+export * from "./columnar.js";
+export * from "./vector.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/evaluators/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA"}

package/dist/evaluators/index.js

@@ -0,0 +1,4 @@
+export * from "./interpreter.js";
+export * from "./jit.js";
+export * from "./columnar.js";
+export * from "./vector.js";

package/dist/evaluators/interpreter.d.ts

@@ -0,0 +1,6 @@
+import type { DataGridComputedDependencyToken } from "../coreTypes.js";
+import type { DataGridFormulaEvaluator, DataGridFormulaFunctionRuntime, DataGridFormulaTokenIndexEvaluator } from "../runtime/types.js";
+import { type DataGridFormulaAstNode } from "../syntax/ast.js";
+export declare function compileFormulaAstEvaluator(root: DataGridFormulaAstNode, functionRegistry: ReadonlyMap<string, DataGridFormulaFunctionRuntime>, resolveIdentifierToken: (identifier: string) => DataGridComputedDependencyToken | undefined, getFunctionContext?: () => import("../coreTypes.js").DataGridComputedFieldComputeContext<unknown> | undefined): DataGridFormulaEvaluator;
+export declare function compileFormulaAstTokenIndexEvaluator(root: DataGridFormulaAstNode, functionRegistry: ReadonlyMap<string, DataGridFormulaFunctionRuntime>, resolveIdentifierTokenIndex: (identifier: string) => number | undefined): DataGridFormulaTokenIndexEvaluator;
+//# sourceMappingURL=interpreter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interpreter.d.ts","sourceRoot":"","sources":["../../src/evaluators/interpreter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAA;AACtE,OAAO,KAAK,EACV,wBAAwB,EAExB,8BAA8B,EAC9B,kCAAkC,EACnC,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,KAAK,sBAAsB,EAAkC,MAAM,kBAAkB,CAAA;AAqJ9F,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,sBAAsB,EAC5B,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,8BAA8B,CAAC,EACrE,sBAAsB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,+BAA+B,GAAG,SAAS,EAC3F,kBAAkB,CAAC,EAAE,MAAM,OAAO,iBAAiB,EAAE,mCAAmC,CAAC,OAAO,CAAC,GAAG,SAAS,GAC5G,wBAAwB,CAE1B;AAED,wBAAgB,oCAAoC,CAClD,IAAI,EAAE,sBAAsB,EAC5B,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,8BAA8B,CAAC,EACrE,2BAA2B,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACtE,kCAAkC,CAEpC"}