@bilig/formula 0.7.8 → 0.8.1

package/dist/js-evaluator.d.ts

@@ -1,182 +1,8 @@
-import { ErrorCode, type CellValue } from '@bilig/protocol';
+import { type CellValue } from '@bilig/protocol';
 import type { FormulaNode } from './ast.js';
-import { type LookupBuiltin } from './builtins/lookup.js';
-import { type ArrayValue, type EvaluationResult } from './runtime-values.js';
-export interface EvaluationContext {
-    sheetName: string;
-    currentAddress?: string;
-    resolveCell: (sheetName: string, address: string) => CellValue;
-    resolveRange: (sheetName: string, start: string, end: string, refKind: 'cells' | 'rows' | 'cols') => CellValue[];
-    resolveName?: (name: string) => CellValue;
-    resolveFormula?: (sheetName: string, address: string) => string | undefined;
-    resolvePivotData?: (request: {
-        dataField: string;
-        sheetName: string;
-        address: string;
-        filters: ReadonlyArray<{
-            field: string;
-            item: CellValue;
-        }>;
-    }) => CellValue | undefined;
-    resolveMultipleOperations?: (request: {
-        formulaSheetName: string;
-        formulaAddress: string;
-        rowCellSheetName: string;
-        rowCellAddress: string;
-        rowReplacementSheetName: string;
-        rowReplacementAddress: string;
-        columnCellSheetName?: string;
-        columnCellAddress?: string;
-        columnReplacementSheetName?: string;
-        columnReplacementAddress?: string;
-    }) => CellValue | undefined;
-    resolveExactVectorMatch?: (request: {
-        lookupValue: CellValue;
-        sheetName: string;
-        start: string;
-        end: string;
-        startRow: number;
-        endRow: number;
-        startCol: number;
-        endCol: number;
-        searchMode: 1 | -1;
-    }) => ExactVectorMatchResult;
-    resolveApproximateVectorMatch?: (request: {
-        lookupValue: CellValue;
-        sheetName: string;
-        start: string;
-        end: string;
-        startRow: number;
-        endRow: number;
-        startCol: number;
-        endCol: number;
-        matchMode: 1 | -1;
-    }) => ApproximateVectorMatchResult;
-    noteRangeMaterialization?: (cellCount: number) => void;
-    noteExactLookupDirect?: () => void;
-    noteExactLookupFallback?: () => void;
-    listSheetNames?: () => string[];
-    resolveBuiltin?: (name: string) => ((...args: CellValue[]) => EvaluationResult) | undefined;
-    resolveLookupBuiltin?: (name: string) => LookupBuiltin | undefined;
-}
-export type ExactVectorMatchResult = {
-    handled: false;
-} | {
-    handled: true;
-    position: number | undefined;
-};
-export type ApproximateVectorMatchResult = ExactVectorMatchResult;
-export interface ReferenceOperand {
-    kind: 'cell' | 'range' | 'row' | 'col';
-    sheetName?: string;
-    address?: string;
-    start?: string;
-    end?: string;
-    refKind?: 'cells' | 'rows' | 'cols';
-}
-export type JsPlanInstruction = {
-    opcode: 'push-number';
-    value: number;
-} | {
-    opcode: 'push-boolean';
-    value: boolean;
-} | {
-    opcode: 'push-string';
-    value: string;
-} | {
-    opcode: 'push-error';
-    code: ErrorCode;
-} | {
-    opcode: 'push-name';
-    name: string;
-} | {
-    opcode: 'push-cell';
-    sheetName?: string;
-    address: string;
-} | {
-    opcode: 'push-range';
-    sheetName?: string;
-    start: string;
-    end: string;
-    refKind: 'cells' | 'rows' | 'cols';
-} | {
-    opcode: 'lookup-exact-match';
-    callee: 'MATCH' | 'XMATCH';
-    sheetName?: string;
-    start: string;
-    end: string;
-    startRow: number;
-    endRow: number;
-    startCol: number;
-    endCol: number;
-    refKind: 'cells';
-    searchMode: 1 | -1;
-} | {
-    opcode: 'lookup-approximate-match';
-    callee: 'MATCH' | 'XMATCH';
-    sheetName?: string;
-    start: string;
-    end: string;
-    startRow: number;
-    endRow: number;
-    startCol: number;
-    endCol: number;
-    refKind: 'cells';
-    matchMode: 1 | -1;
-} | {
-    opcode: 'push-lambda';
-    params: string[];
-    body: JsPlanInstruction[];
-} | {
-    opcode: 'unary';
-    operator: '+' | '-';
-} | {
-    opcode: 'binary';
-    operator: '+' | '-' | '*' | '/' | '^' | '&' | '=' | '<>' | '>' | '>=' | '<' | '<=';
-} | {
-    opcode: 'call';
-    callee: string;
-    argc: number;
-    argRefs?: Array<ReferenceOperand | undefined>;
-} | {
-    opcode: 'invoke';
-    argc: number;
-} | {
-    opcode: 'begin-scope';
-} | {
-    opcode: 'bind-name';
-    name: string;
-} | {
-    opcode: 'end-scope';
-} | {
-    opcode: 'jump-if-false';
-    target: number;
-} | {
-    opcode: 'jump';
-    target: number;
-} | {
-    opcode: 'return';
-};
-export type StackValue = {
-    kind: 'scalar';
-    value: CellValue;
-} | {
-    kind: 'omitted';
-} | {
-    kind: 'range';
-    values: CellValue[];
-    refKind: 'cells' | 'rows' | 'cols';
-    rows: number;
-    cols: number;
-    sheetName?: string;
-    start?: string;
-    end?: string;
-} | {
-    kind: 'lambda';
-    params: string[];
-    body: JsPlanInstruction[];
-    scopes: Array<Map<string, StackValue>>;
-} | ArrayValue;
+import type { EvaluationContext, JsPlanInstruction } from './js-evaluator-types.js';
+import { type EvaluationResult } from './runtime-values.js';
+export type { ApproximateVectorMatchResult, EvaluationContext, ExactVectorMatchResult, JsPlanInstruction, ReferenceOperand, StackValue, } from './js-evaluator-types.js';
 export { lowerToPlan } from './js-plan-lowering.js';
 export declare function evaluatePlanResult(plan: readonly JsPlanInstruction[], context: EvaluationContext): EvaluationResult;
 export declare function evaluatePlan(plan: readonly JsPlanInstruction[], context: EvaluationContext): CellValue;

package/dist/js-evaluator.js

@@ -1,476 +1,16 @@
-import { ErrorCode, ValueTag, formatErrorCode } from '@bilig/protocol';
+import { ErrorCode, ValueTag } from '@bilig/protocol';
 import { parseRangeAddress } from './addressing.js';
 import { getBuiltin } from './builtins.js';
 import { getLookupBuiltin } from './builtins/lookup.js';
 import { evaluateArraySpecialCall } from './js-evaluator-array-special-calls.js';
+import { emptyValue, error, numberValue, stringValue } from './js-evaluator-cell-values.js';
 import { evaluateContextSpecialCall } from './js-evaluator-context-special-calls.js';
 import { absoluteAddress, cellTypeCode, currentCellReference, referenceColumnNumber, referenceRowNumber, referenceSheetName, referenceTopLeftAddress, sheetIndexByName, sheetNames, } from './js-evaluator-reference-context.js';
+import { cloneScopes, cloneStackValue, coerceOptionalBooleanArgument, coerceOptionalMatchModeArgument, coerceOptionalPositiveIntegerArgument, coerceOptionalTrimModeArgument, coerceScalarTextArgument, evaluateBinary, getBroadcastShape, getRangeCell, isCellValueError, isSingleCellValue, makeArrayStack, matrixFromStackValue, normalizeScopeName, popArgument, popScalar, scalarIntegerArgument, stackScalar, toEvaluationResult, toNumber, toPositiveInteger, toRangeArgument, toRangeLike, toStringValue, truthy, vectorIntegerArgument, } from './js-evaluator-runtime-helpers.js';
 import { evaluateWorkbookSpecialCall } from './js-evaluator-workbook-special-calls.js';
 import { lowerToPlan } from './js-plan-lowering.js';
 import { isArrayValue, scalarFromEvaluationResult } from './runtime-values.js';
 export { lowerToPlan } from './js-plan-lowering.js';
-function emptyValue() {
-    return { tag: ValueTag.Empty };
-}
-function error(code) {
-    return { tag: ValueTag.Error, code };
-}
-function numberValue(value) {
-    return { tag: ValueTag.Number, value };
-}
-function stringValue(value) {
-    return { tag: ValueTag.String, value, stringId: 0 };
-}
-function toNumber(value) {
-    switch (value.tag) {
-        case ValueTag.Number:
-            return value.value;
-        case ValueTag.Boolean:
-            return value.value ? 1 : 0;
-        case ValueTag.Empty:
-            return 0;
-        case ValueTag.String:
-        case ValueTag.Error:
-            return undefined;
-        default:
-            return undefined;
-    }
-}
-function toStringValue(value) {
-    switch (value.tag) {
-        case ValueTag.Empty:
-            return '';
-        case ValueTag.Number:
-            return String(value.value);
-        case ValueTag.Boolean:
-            return value.value ? 'TRUE' : 'FALSE';
-        case ValueTag.String:
-            return value.value;
-        case ValueTag.Error:
-            return formatErrorCode(value.code);
-    }
-}
-function isTextLike(value) {
-    return value.tag === ValueTag.String || value.tag === ValueTag.Empty;
-}
-function compareText(left, right) {
-    const normalizedLeft = left.toUpperCase();
-    const normalizedRight = right.toUpperCase();
-    if (normalizedLeft === normalizedRight) {
-        return 0;
-    }
-    return normalizedLeft < normalizedRight ? -1 : 1;
-}
-function compareScalars(left, right) {
-    if (isTextLike(left) && isTextLike(right)) {
-        return compareText(toStringValue(left), toStringValue(right));
-    }
-    const leftNum = comparableNumber(left);
-    const rightNum = comparableNumber(right);
-    if (leftNum === undefined || rightNum === undefined) {
-        return undefined;
-    }
-    if (leftNum === rightNum) {
-        return 0;
-    }
-    return leftNum < rightNum ? -1 : 1;
-}
-function comparableNumber(value) {
-    switch (value.tag) {
-        case ValueTag.Number:
-            return value.value;
-        case ValueTag.Boolean:
-            return value.value ? 1 : 0;
-        case ValueTag.Empty:
-            return 0;
-        case ValueTag.String: {
-            const trimmed = value.value.trim();
-            if (trimmed === '') {
-                return 0;
-            }
-            const parsed = Number(trimmed);
-            return Number.isFinite(parsed) ? parsed : undefined;
-        }
-        case ValueTag.Error:
-        default:
-            return undefined;
-    }
-}
-function truthy(value) {
-    return (toNumber(value) ?? 0) !== 0;
-}
-function popScalar(stack) {
-    const value = stack.pop();
-    if (!value) {
-        return error(ErrorCode.Value);
-    }
-    if (value.kind === 'scalar') {
-        return value.value;
-    }
-    if (value.kind === 'omitted') {
-        return error(ErrorCode.Value);
-    }
-    if (value.kind === 'lambda') {
-        return error(ErrorCode.Value);
-    }
-    return value.values[0] ?? emptyValue();
-}
-function popArgument(stack) {
-    return stack.pop() ?? { kind: 'scalar', value: error(ErrorCode.Value) };
-}
-function toEvaluationResult(value) {
-    if (!value) {
-        return error(ErrorCode.Value);
-    }
-    if (value.kind === 'scalar') {
-        return value.value;
-    }
-    if (value.kind === 'omitted') {
-        return error(ErrorCode.Value);
-    }
-    if (value.kind === 'lambda') {
-        return error(ErrorCode.Value);
-    }
-    if (value.kind === 'range') {
-        return {
-            kind: 'array',
-            rows: value.rows,
-            cols: value.cols,
-            values: value.values,
-        };
-    }
-    return value;
-}
-function cloneStackValue(value) {
-    if (value.kind === 'scalar') {
-        return { kind: 'scalar', value: value.value };
-    }
-    if (value.kind === 'omitted') {
-        return { kind: 'omitted' };
-    }
-    if (value.kind === 'range') {
-        return {
-            kind: 'range',
-            values: value.values,
-            refKind: value.refKind,
-            rows: value.rows,
-            cols: value.cols,
-            ...(value.sheetName ? { sheetName: value.sheetName } : {}),
-            ...(value.start ? { start: value.start } : {}),
-            ...(value.end ? { end: value.end } : {}),
-        };
-    }
-    if (value.kind === 'lambda') {
-        return {
-            kind: 'lambda',
-            params: [...value.params],
-            body: value.body,
-            scopes: cloneScopes(value.scopes),
-        };
-    }
-    return { kind: 'array', values: value.values, rows: value.rows, cols: value.cols };
-}
-function cloneScopes(scopes) {
-    return scopes.map((scope) => new Map([...scope.entries()].map(([name, value]) => [name, cloneStackValue(value)])));
-}
-function toRangeLike(value) {
-    if (value.kind === 'omitted') {
-        return { kind: 'range', values: [error(ErrorCode.Value)], rows: 1, cols: 1, refKind: 'cells' };
-    }
-    if (value.kind === 'lambda') {
-        return { kind: 'range', values: [error(ErrorCode.Value)], rows: 1, cols: 1, refKind: 'cells' };
-    }
-    if (value.kind === 'range') {
-        return value;
-    }
-    if (value.kind === 'array') {
-        return {
-            kind: 'range',
-            values: value.values,
-            rows: value.rows,
-            cols: value.cols,
-            refKind: 'cells',
-        };
-    }
-    return { kind: 'range', values: [value.value], rows: 1, cols: 1, refKind: 'cells' };
-}
-function scalarBinary(operator, leftValue, rightValue) {
-    if (leftValue.tag === ValueTag.Error) {
-        return leftValue;
-    }
-    if (rightValue.tag === ValueTag.Error) {
-        return rightValue;
-    }
-    if (operator === '&') {
-        return {
-            tag: ValueTag.String,
-            value: `${toStringValue(leftValue)}${toStringValue(rightValue)}`,
-            stringId: 0,
-        };
-    }
-    if (['+', '-', '*', '/', '^'].includes(operator)) {
-        const left = toNumber(leftValue);
-        const right = toNumber(rightValue);
-        if (left === undefined || right === undefined) {
-            return error(ErrorCode.Value);
-        }
-        if (operator === '/' && right === 0) {
-            return error(ErrorCode.Div0);
-        }
-        const value = operator === '+'
-            ? left + right
-            : operator === '-'
-                ? left - right
-                : operator === '*'
-                    ? left * right
-                    : operator === '/'
-                        ? left / right
-                        : left ** right;
-        return { tag: ValueTag.Number, value };
-    }
-    const comparison = compareScalars(leftValue, rightValue);
-    if (comparison === undefined) {
-        return error(ErrorCode.Value);
-    }
-    return {
-        tag: ValueTag.Boolean,
-        value: operator === '='
-            ? comparison === 0
-            : operator === '<>'
-                ? comparison !== 0
-                : operator === '>'
-                    ? comparison > 0
-                    : operator === '>='
-                        ? comparison >= 0
-                        : operator === '<'
-                            ? comparison < 0
-                            : comparison <= 0,
-    };
-}
-function evaluateBinary(operator, leftValue, rightValue) {
-    if (leftValue.kind === 'scalar' && rightValue.kind === 'scalar') {
-        return scalarBinary(operator, leftValue.value, rightValue.value);
-    }
-    const leftRange = toRangeLike(leftValue);
-    const rightRange = toRangeLike(rightValue);
-    const rows = leftRange.rows === rightRange.rows
-        ? leftRange.rows
-        : leftRange.rows === 1
-            ? rightRange.rows
-            : rightRange.rows === 1
-                ? leftRange.rows
-                : 0;
-    const cols = leftRange.cols === rightRange.cols
-        ? leftRange.cols
-        : leftRange.cols === 1
-            ? rightRange.cols
-            : rightRange.cols === 1
-                ? leftRange.cols
-                : 0;
-    if (rows === 0 || cols === 0) {
-        return error(ErrorCode.Value);
-    }
-    const values = [];
-    for (let row = 0; row < rows; row += 1) {
-        for (let col = 0; col < cols; col += 1) {
-            const leftIndex = Math.min(row, leftRange.rows - 1) * leftRange.cols + Math.min(col, leftRange.cols - 1);
-            const rightIndex = Math.min(row, rightRange.rows - 1) * rightRange.cols + Math.min(col, rightRange.cols - 1);
-            values.push(scalarBinary(operator, leftRange.values[leftIndex] ?? emptyValue(), rightRange.values[rightIndex] ?? emptyValue()));
-        }
-    }
-    return rows === 1 && cols === 1 ? (values[0] ?? emptyValue()) : { kind: 'array', values, rows, cols };
-}
-function stackScalar(value) {
-    return { kind: 'scalar', value };
-}
-function normalizeScopeName(name) {
-    return name.toUpperCase();
-}
-function isSingleCellValue(value) {
-    if (value.kind === 'scalar') {
-        return value.value;
-    }
-    if (value.kind === 'omitted') {
-        return undefined;
-    }
-    if (value.kind === 'lambda') {
-        return undefined;
-    }
-    return value.rows * value.cols === 1 ? (value.values[0] ?? emptyValue()) : undefined;
-}
-function toRangeArgument(value) {
-    if (value.kind === 'scalar') {
-        return value.value;
-    }
-    if (value.kind === 'omitted') {
-        return error(ErrorCode.Value);
-    }
-    if (value.kind === 'lambda') {
-        return error(ErrorCode.Value);
-    }
-    return {
-        kind: 'range',
-        values: value.values,
-        refKind: value.kind === 'range' ? value.refKind : 'cells',
-        rows: value.rows,
-        cols: value.cols,
-        ...(value.kind === 'range' && value.sheetName ? { sheetName: value.sheetName } : {}),
-        ...(value.kind === 'range' && value.start ? { start: value.start } : {}),
-        ...(value.kind === 'range' && value.end ? { end: value.end } : {}),
-    };
-}
-function toPositiveInteger(value) {
-    if (value === undefined) {
-        return undefined;
-    }
-    const scalar = isSingleCellValue(value);
-    const numeric = scalar ? toNumber(scalar) : undefined;
-    if (numeric === undefined || !Number.isFinite(numeric)) {
-        return undefined;
-    }
-    const integer = Math.trunc(numeric);
-    return integer >= 1 ? integer : undefined;
-}
-function getRangeCell(range, row, col) {
-    return range.values[row * range.cols + col] ?? emptyValue();
-}
-function getBroadcastShape(values) {
-    const ranges = values.map(toRangeLike);
-    const rows = Math.max(...ranges.map((range) => range.rows));
-    const cols = Math.max(...ranges.map((range) => range.cols));
-    const compatible = ranges.every((range) => (range.rows === rows || range.rows === 1) && (range.cols === cols || range.cols === 1));
-    return compatible ? { rows, cols } : undefined;
-}
-function coerceScalarTextArgument(value) {
-    if (value === undefined) {
-        return error(ErrorCode.Value);
-    }
-    const scalar = isSingleCellValue(value);
-    if (!scalar) {
-        return error(ErrorCode.Value);
-    }
-    if (scalar.tag === ValueTag.Error) {
-        return scalar;
-    }
-    return toStringValue(scalar);
-}
-function coerceOptionalBooleanArgument(value, fallback) {
-    if (value === undefined) {
-        return fallback;
-    }
-    const scalar = isSingleCellValue(value);
-    if (!scalar) {
-        return error(ErrorCode.Value);
-    }
-    if (scalar.tag === ValueTag.Error) {
-        return scalar;
-    }
-    if (scalar.tag === ValueTag.Boolean) {
-        return scalar.value;
-    }
-    const numeric = toNumber(scalar);
-    return numeric === undefined ? error(ErrorCode.Value) : numeric !== 0;
-}
-function coerceOptionalMatchModeArgument(value, fallback) {
-    if (value === undefined) {
-        return fallback;
-    }
-    const scalar = isSingleCellValue(value);
-    if (!scalar) {
-        return error(ErrorCode.Value);
-    }
-    if (scalar.tag === ValueTag.Error) {
-        return scalar;
-    }
-    const numeric = toNumber(scalar);
-    if (numeric === undefined || !Number.isFinite(numeric)) {
-        return error(ErrorCode.Value);
-    }
-    const integer = Math.trunc(numeric);
-    return integer === 0 || integer === 1 ? integer : error(ErrorCode.Value);
-}
-function coerceOptionalPositiveIntegerArgument(value, fallback) {
-    if (value === undefined) {
-        return fallback;
-    }
-    const scalar = isSingleCellValue(value);
-    if (!scalar) {
-        return error(ErrorCode.Value);
-    }
-    if (scalar.tag === ValueTag.Error) {
-        return scalar;
-    }
-    const numeric = toNumber(scalar);
-    if (numeric === undefined || !Number.isFinite(numeric)) {
-        return error(ErrorCode.Value);
-    }
-    const integer = Math.trunc(numeric);
-    return integer >= 1 ? integer : error(ErrorCode.Value);
-}
-function coerceOptionalTrimModeArgument(value, fallback) {
-    if (value === undefined) {
-        return fallback;
-    }
-    const scalar = isSingleCellValue(value);
-    if (!scalar) {
-        return error(ErrorCode.Value);
-    }
-    if (scalar.tag === ValueTag.Error) {
-        return scalar;
-    }
-    const numeric = toNumber(scalar);
-    if (numeric === undefined || !Number.isFinite(numeric)) {
-        return error(ErrorCode.Value);
-    }
-    const integer = Math.trunc(numeric);
-    switch (integer) {
-        case 0:
-        case 1:
-        case 2:
-        case 3:
-            return integer;
-        default:
-            return error(ErrorCode.Value);
-    }
-}
-function isCellValueError(value) {
-    return typeof value === 'object' && value !== null && 'tag' in value;
-}
-function makeArrayStack(rows, cols, values) {
-    return { kind: 'array', rows, cols, values };
-}
-function matrixFromStackValue(value) {
-    if (value.kind === 'omitted' || value.kind === 'lambda') {
-        return undefined;
-    }
-    if (value.kind === 'scalar') {
-        return { rows: 1, cols: 1, values: [value.value] };
-    }
-    return { rows: value.rows, cols: value.cols, values: value.values };
-}
-function scalarIntegerArgument(value) {
-    const scalar = value ? isSingleCellValue(value) : undefined;
-    const numeric = scalar ? toNumber(scalar) : undefined;
-    return numeric === undefined || !Number.isFinite(numeric) ? undefined : Math.trunc(numeric);
-}
-function vectorIntegerArgument(value) {
-    if (!value) {
-        return undefined;
-    }
-    const matrix = matrixFromStackValue(value);
-    if (!matrix || !(matrix.rows === 1 || matrix.cols === 1)) {
-        return undefined;
-    }
-    const values = [];
-    for (let index = 0; index < matrix.rows * matrix.cols; index += 1) {
-        const numeric = toNumber(matrix.values[index] ?? emptyValue());
-        if (numeric === undefined || !Number.isFinite(numeric)) {
-            return undefined;
-        }
-        values.push(Math.trunc(numeric));
-    }
-    return values;
-}
 function aggregateRangeSubset(functionArg, subset, context, totalSet) {
     if (functionArg.kind === 'lambda') {
         const args = [makeArrayStack(Math.max(subset.length, 1), 1, [...subset])];