@texuli/blocks 0.0.0-stage → 0.1.0-next.0

package/dist/core/catalog/validate.js

@@ -0,0 +1,46 @@
+import { safeParseBlocks } from "../schema/blocks.js";
+import { toJsonPath } from "../schema/primitives.js";
+import { getCatalogEntry } from "./entries.js";
+/**
+ * Validate untrusted block author input and return path-addressed repair
+ * diagnostics. Never throws.
+ */
+export function validateBlocksForAuthoring(input) {
+    const parsed = safeParseBlocks(input);
+    if (!parsed.success) {
+        return {
+            valid: false,
+            diagnostics: parsed.issues.map((issue) => ({
+                code: 'invalid-block',
+                path: issue.path,
+                jsonPath: toJsonPath(issue.path),
+                message: issue.message,
+                hint: 'Compare the value to BLOCK_CATALOG for this type (useWhen, limits and examples).',
+            })),
+        };
+    }
+    const diagnostics = [];
+    for (const [index, block] of parsed.data.entries()) {
+        const entry = getCatalogEntry(block.type);
+        if (!entry) {
+            diagnostics.push({
+                code: 'unknown-type',
+                path: [index, 'type'],
+                jsonPath: toJsonPath([index, 'type']),
+                message: `No catalog entry for type "${block.type}"`,
+                hint: 'Use a type listed in BLOCK_CATALOG.',
+            });
+        }
+    }
+    return { valid: diagnostics.length === 0, diagnostics };
+}
+/** Re-export parsed blocks when authoring validation succeeds. */
+export function parseBlocksForAuthoring(input) {
+    const validation = validateBlocksForAuthoring(input);
+    if (!validation.valid)
+        return { success: false, validation };
+    const parsed = safeParseBlocks(input);
+    if (!parsed.success)
+        return { success: false, validation };
+    return { success: true, blocks: parsed.data };
+}

package/dist/core/formula/evaluate.d.ts

@@ -0,0 +1,14 @@
+import type { Condition, FormulaInputs, FormulaUnit, NumberFormula } from './types.js';
+/** Rounds half away from zero to `digits` decimals (negative: tens, hundreds…). */
+export declare function roundTo(value: number, digits?: number): number | null;
+/** Evaluates a formula (validate first with parseFormula). Never throws. */
+export declare function evaluateFormula(formula: NumberFormula, inputs: FormulaInputs): number | null;
+/** Evaluates a condition on its own, with the same rules. */
+export declare function evaluateCondition(test: Condition, inputs: FormulaInputs): boolean | null;
+export interface FormatFormulaOptions {
+    currency?: string;
+    locale?: string;
+    maximumFractionDigits?: number;
+    empty?: string;
+}
+export declare function formatFormulaValue(value: number | null, unit?: FormulaUnit, options?: FormatFormulaOptions): string;

package/dist/core/formula/evaluate.js

@@ -0,0 +1,181 @@
+import { FORMULA_LIMITS } from "./parse.js";
+/*
+ * Pure interpreter over the closed grammar. Never throws; null means undefined.
+ */
+function finite(value) {
+    if (!Number.isFinite(value))
+        return null;
+    return value === 0 ? 0 : value;
+}
+function readInput(inputs, name) {
+    if (!Object.hasOwn(inputs, name))
+        return null;
+    const value = inputs[name];
+    return typeof value === 'number' ? finite(value) : null;
+}
+/** Rounds half away from zero to `digits` decimals (negative: tens, hundreds…). */
+export function roundTo(value, digits = 0) {
+    const factor = 10 ** Math.abs(digits);
+    const scaled = digits >= 0 ? Math.abs(value) * factor : Math.abs(value) / factor;
+    const rounded = Math.round(scaled + scaled * Number.EPSILON);
+    const result = Math.sign(value) * (digits >= 0 ? rounded / factor : rounded * factor);
+    return finite(result);
+}
+function number(node, inputs, depth) {
+    if (node === null || typeof node !== 'object' || depth > FORMULA_LIMITS.depth)
+        return null;
+    const next = depth + 1;
+    switch (node.op) {
+        case 'num':
+            return typeof node.value === 'number' ? finite(node.value) : null;
+        case 'var':
+            return typeof node.name === 'string' ? readInput(inputs, node.name) : null;
+        case 'add':
+        case 'sub':
+        case 'mul':
+        case 'div': {
+            const left = number(node.left, inputs, next);
+            const right = number(node.right, inputs, next);
+            if (left === null || right === null)
+                return null;
+            if (node.op === 'add')
+                return finite(left + right);
+            if (node.op === 'sub')
+                return finite(left - right);
+            if (node.op === 'mul')
+                return finite(left * right);
+            return right === 0 ? null : finite(left / right);
+        }
+        case 'pow': {
+            const base = number(node.base, inputs, next);
+            const exponent = number(node.exponent, inputs, next);
+            if (base === null || exponent === null)
+                return null;
+            if (Math.abs(exponent) > FORMULA_LIMITS.exponent)
+                return null;
+            return finite(base ** exponent);
+        }
+        case 'min':
+        case 'max': {
+            if (!Array.isArray(node.args) || node.args.length === 0)
+                return null;
+            let result = null;
+            for (const arg of node.args.slice(0, FORMULA_LIMITS.args)) {
+                const value = number(arg, inputs, next);
+                if (value === null)
+                    return null;
+                if (result === null)
+                    result = value;
+                else
+                    result = node.op === 'min' ? Math.min(result, value) : Math.max(result, value);
+            }
+            return result;
+        }
+        case 'round': {
+            const value = number(node.value, inputs, next);
+            const digits = node.digits ?? 0;
+            if (value === null || !Number.isInteger(digits))
+                return null;
+            if (Math.abs(digits) > FORMULA_LIMITS.roundDigits)
+                return null;
+            return roundTo(value, digits);
+        }
+        case 'clamp': {
+            const value = number(node.value, inputs, next);
+            const min = number(node.min, inputs, next);
+            const max = number(node.max, inputs, next);
+            if (value === null || min === null || max === null || min > max)
+                return null;
+            return Math.min(max, Math.max(min, value));
+        }
+        case 'if': {
+            const test = condition(node.test, inputs, next);
+            if (test === null)
+                return null;
+            return number(test ? node.ifTrue : node.ifFalse, inputs, next);
+        }
+        default:
+            return null;
+    }
+}
+function condition(node, inputs, depth) {
+    if (node === null || typeof node !== 'object' || depth > FORMULA_LIMITS.depth)
+        return null;
+    const next = depth + 1;
+    switch (node.op) {
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+        case 'eq':
+        case 'neq': {
+            const left = number(node.left, inputs, next);
+            const right = number(node.right, inputs, next);
+            if (left === null || right === null)
+                return null;
+            if (node.op === 'lt')
+                return left < right;
+            if (node.op === 'lte')
+                return left <= right;
+            if (node.op === 'gt')
+                return left > right;
+            if (node.op === 'gte')
+                return left >= right;
+            if (node.op === 'eq')
+                return left === right;
+            return left !== right;
+        }
+        case 'and':
+        case 'or': {
+            if (!Array.isArray(node.args) || node.args.length === 0)
+                return null;
+            let unknown = false;
+            for (const arg of node.args.slice(0, FORMULA_LIMITS.args)) {
+                const value = condition(arg, inputs, next);
+                if (value === null)
+                    unknown = true;
+                else if (node.op === 'and' && !value)
+                    return false;
+                else if (node.op === 'or' && value)
+                    return true;
+            }
+            return unknown ? null : node.op === 'and';
+        }
+        case 'not': {
+            const value = condition(node.value, inputs, next);
+            return value === null ? null : !value;
+        }
+        default:
+            return null;
+    }
+}
+/** Evaluates a formula (validate first with parseFormula). Never throws. */
+export function evaluateFormula(formula, inputs) {
+    return number(formula, inputs, 1);
+}
+/** Evaluates a condition on its own, with the same rules. */
+export function evaluateCondition(test, inputs) {
+    return condition(test, inputs, 1);
+}
+export function formatFormulaValue(value, unit = 'number', options = {}) {
+    if (value === null || !Number.isFinite(value))
+        return options.empty ?? '—';
+    const locale = options.locale ?? 'en-US';
+    const digits = options.maximumFractionDigits;
+    switch (unit) {
+        case 'cents':
+            return new Intl.NumberFormat(locale, {
+                style: 'currency',
+                currency: options.currency ?? 'USD',
+            }).format(value / 100);
+        case 'percent':
+            return new Intl.NumberFormat(locale, {
+                style: 'percent',
+                maximumFractionDigits: digits ?? 1,
+            }).format(value);
+        case 'compact':
+            return new Intl.NumberFormat(locale, { notation: 'compact' }).format(value);
+        default:
+            return new Intl.NumberFormat(locale, { maximumFractionDigits: digits ?? 2 }).format(value);
+    }
+}

package/dist/core/formula/index.d.ts

@@ -0,0 +1,8 @@
+/// <reference path="../../css-modules.d.ts" />
+/**
+ * `@texuli/blocks` formula — closed AST for calculator blocks.
+ * Formulas are data, never code: no string syntax, no host objects.
+ */
+export { evaluateCondition, evaluateFormula, type FormatFormulaOptions, formatFormulaValue, roundTo, } from './evaluate.js';
+export { FORMULA_LIMITS, formulaJsonPath, formulaVariables, type ParseFormulaOptions, parseFormula, } from './parse.js';
+export type { ArithmeticOp, ComparisonOp, Condition, FormulaDiagnostic, FormulaInputs, FormulaParseResult, FormulaUnit, NumberFormula, } from './types.js';

package/dist/core/formula/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@texuli/blocks` formula — closed AST for calculator blocks.
+ * Formulas are data, never code: no string syntax, no host objects.
+ */
+export { evaluateCondition, evaluateFormula, formatFormulaValue, roundTo, } from "./evaluate.js";
+export { FORMULA_LIMITS, formulaJsonPath, formulaVariables, parseFormula, } from "./parse.js";

package/dist/core/formula/parse.d.ts

@@ -0,0 +1,19 @@
+import type { Condition, FormulaParseResult, NumberFormula } from './types.js';
+/** Caps that keep parsing and evaluation small and linear. */
+export declare const FORMULA_LIMITS: Readonly<{
+    nodes: 64;
+    depth: 12;
+    args: 8;
+    exponent: 64;
+    roundDigits: 6;
+    literal: 1000000000000000;
+}>;
+export declare function formulaJsonPath(path: readonly (string | number)[]): string;
+/** Variable names a formula reads, sorted and unique. */
+export declare function formulaVariables(formula: NumberFormula | Condition): string[];
+export interface ParseFormulaOptions {
+    /** Known input names. When given, any other variable is an unknown-variable diagnostic. */
+    variables?: readonly string[];
+}
+/** Validates untrusted formula JSON. Never throws and never executes anything. */
+export declare function parseFormula(input: unknown, options?: ParseFormulaOptions): FormulaParseResult;