@texuli/core 0.7.0 → 0.9.0

package/dist/data-source/schema.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Data-source declarations (ADR-015): the host names each source, types its
+ * fields and declares what agents may ask of it. A blueprint can only name a
+ * declared source and query declared fields with the operators the field
+ * allows; nothing here builds a URL, a query string or code.
+ */
+/** Field value types. The same five types as the `@texuli/data` grid (`GridValueType`). */
+export declare const SOURCE_FIELD_TYPES: readonly ["text", "enum", "number", "date", "boolean"];
+export type SourceFieldType = (typeof SOURCE_FIELD_TYPES)[number];
+/** What a source can do. `search` means `list` also accepts free search text. */
+export declare const SOURCE_OPERATIONS: readonly ["list", "get", "create", "update", "delete", "search"];
+export type SourceOperation = (typeof SOURCE_OPERATIONS)[number];
+/** How `list` pages: by an opaque cursor, by row offset, or not at all (one page). */
+export declare const SOURCE_PAGINATION_STYLES: readonly ["cursor", "offset", "none"];
+export type SourcePaginationStyle = (typeof SOURCE_PAGINATION_STYLES)[number];
+/**
+ * Filter operators: exactly the `@texuli/data` grid filter model's
+ * `FILTER_OPERATORS`, so a query's filter is the same data the grid and the
+ * filter builder store.
+ */
+export declare const SOURCE_FILTER_OPERATORS: readonly ["eq", "neq", "contains", "in", "between", "before", "after", "isEmpty", "isNotEmpty"];
+export type SourceFilterOperator = (typeof SOURCE_FILTER_OPERATORS)[number];
+/** Operators that apply to each field type (the grid's `OPERATORS_BY_TYPE`). */
+export declare const SOURCE_OPERATORS_BY_TYPE: Readonly<Record<SourceFieldType, readonly SourceFilterOperator[]>>;
+/** Every bound of the data-source vocabulary. Strings count UTF-16 units. */
+export declare const SOURCE_LIMITS: Readonly<{
+    /** Sources one registry holds. */
+    sources: 256;
+    /** Fields one source declares. */
+    fields: 64;
+    /** Options of an enum field. */
+    enumOptions: 100;
+    /** Fields one query may project. */
+    projection: 32;
+    /** Sort keys one query may carry. */
+    sort: 4;
+    /** Free search text. */
+    searchLength: 200;
+    /** Filter tree depth and node count (inside the grid model's 6 levels and 200 nodes). */
+    filterDepth: 6;
+    filterNodes: 64;
+    /** Values of an `in` list (the grid's limit). */
+    filterValues: 100;
+    /** A text value in a filter (the grid's limit). */
+    valueLength: 500;
+    /** The largest page any source may declare. */
+    pageSize: 500;
+    /** An opaque pagination cursor. */
+    cursorLength: 512;
+    /** Fields one create or update may change. */
+    changes: 64;
+}>;
+/** A source name: lowercase words joined by `.`, `_` or `-`, at most 64 characters. */
+export declare const SOURCE_NAME_PATTERN = "^[a-z][a-z0-9]*([._-][a-z0-9]+)*$";
+/** A field name: a letter, then letters, digits or `_`, at most 64 characters. */
+export declare const SOURCE_FIELD_PATTERN = "^[A-Za-z][A-Za-z0-9_]*$";
+/** Whether `value` is a well-formed source name. */
+export declare function isSourceName(value: unknown): value is string;
+/** Whether `value` is a well-formed field name. */
+export declare function isSourceFieldName(value: unknown): value is string;
+/** One field as the host declares it. */
+export interface SourceFieldDeclaration {
+    name: string;
+    type: SourceFieldType;
+    /** The closed values of an `enum` field. */
+    options?: readonly string[];
+    /**
+     * Filtering: `true` allows every operator of the type, a list allows only
+     * those, omitted or `false` allows none.
+     */
+    filter?: boolean | readonly SourceFilterOperator[];
+    /** Whether queries may sort by this field. Default `false`. */
+    sort?: boolean;
+    /** Whether create and update may set this field. Default `false`. The key never is. */
+    editable?: boolean;
+    /** Whether create needs a value for this field. Default `false`. */
+    required?: boolean;
+}
+/** A source's schema as the host declares it. */
+export interface SourceSchemaDeclaration {
+    /** The field that identifies a row (text or number). Default `id`. */
+    key?: string;
+    fields: readonly SourceFieldDeclaration[];
+    operations: readonly SourceOperation[];
+    /** Default `none`. */
+    pagination?: SourcePaginationStyle;
+    /** The largest page a query may ask for, at most {@link SOURCE_LIMITS.pageSize}. Default 100. */
+    maxPageSize?: number;
+    /** The page size when a query names none. Default the smaller of 25 and `maxPageSize`. */
+    defaultPageSize?: number;
+}
+/** One field, normalized: every flag explicit, operators resolved. */
+export interface SourceFieldDescriptor {
+    readonly name: string;
+    readonly type: SourceFieldType;
+    readonly options?: readonly string[];
+    readonly filter: readonly SourceFilterOperator[];
+    readonly sort: boolean;
+    readonly editable: boolean;
+    readonly required: boolean;
+}
+/**
+ * A source as plain JSON data: what validators (`@texuli/catalog`,
+ * `@texuli/spec`) and agents read. Never carries the adapter.
+ */
+export interface SourceDescriptor {
+    readonly name: string;
+    readonly key: string;
+    readonly fields: readonly SourceFieldDescriptor[];
+    readonly operations: readonly SourceOperation[];
+    readonly pagination: SourcePaginationStyle;
+    readonly maxPageSize: number;
+    readonly defaultPageSize: number;
+}
+/**
+ * Check a host declaration and return its frozen descriptor. Throws a
+ * `TypeError` for a declaration mistake (an unknown type, a duplicate
+ * field, an operator the type does not take, a page size over the cap).
+ */
+export declare function describeSource(name: string, declaration: SourceSchemaDeclaration): SourceDescriptor;
+/** The descriptor's field named `name`, by own lookup (never the prototype chain). */
+export declare function sourceField(descriptor: SourceDescriptor, name: string): SourceFieldDescriptor | undefined;

package/dist/data-source/schema.js

@@ -0,0 +1,197 @@
+/**
+ * Data-source declarations (ADR-015): the host names each source, types its
+ * fields and declares what agents may ask of it. A blueprint can only name a
+ * declared source and query declared fields with the operators the field
+ * allows; nothing here builds a URL, a query string or code.
+ */
+/** Field value types. The same five types as the `@texuli/data` grid (`GridValueType`). */
+export const SOURCE_FIELD_TYPES = ['text', 'enum', 'number', 'date', 'boolean'];
+/** What a source can do. `search` means `list` also accepts free search text. */
+export const SOURCE_OPERATIONS = ['list', 'get', 'create', 'update', 'delete', 'search'];
+/** How `list` pages: by an opaque cursor, by row offset, or not at all (one page). */
+export const SOURCE_PAGINATION_STYLES = ['cursor', 'offset', 'none'];
+/**
+ * Filter operators: exactly the `@texuli/data` grid filter model's
+ * `FILTER_OPERATORS`, so a query's filter is the same data the grid and the
+ * filter builder store.
+ */
+export const SOURCE_FILTER_OPERATORS = [
+    'eq',
+    'neq',
+    'contains',
+    'in',
+    'between',
+    'before',
+    'after',
+    'isEmpty',
+    'isNotEmpty',
+];
+/** Operators that apply to each field type (the grid's `OPERATORS_BY_TYPE`). */
+export const SOURCE_OPERATORS_BY_TYPE = Object.freeze({
+    text: Object.freeze(['eq', 'neq', 'contains', 'in', 'isEmpty', 'isNotEmpty']),
+    enum: Object.freeze(['eq', 'neq', 'in', 'isEmpty', 'isNotEmpty']),
+    number: Object.freeze(['eq', 'neq', 'in', 'between', 'isEmpty', 'isNotEmpty']),
+    date: Object.freeze([
+        'eq',
+        'neq',
+        'between',
+        'before',
+        'after',
+        'isEmpty',
+        'isNotEmpty',
+    ]),
+    boolean: Object.freeze(['eq', 'neq', 'isEmpty', 'isNotEmpty']),
+});
+/** Every bound of the data-source vocabulary. Strings count UTF-16 units. */
+export const SOURCE_LIMITS = Object.freeze({
+    /** Sources one registry holds. */
+    sources: 256,
+    /** Fields one source declares. */
+    fields: 64,
+    /** Options of an enum field. */
+    enumOptions: 100,
+    /** Fields one query may project. */
+    projection: 32,
+    /** Sort keys one query may carry. */
+    sort: 4,
+    /** Free search text. */
+    searchLength: 200,
+    /** Filter tree depth and node count (inside the grid model's 6 levels and 200 nodes). */
+    filterDepth: 6,
+    filterNodes: 64,
+    /** Values of an `in` list (the grid's limit). */
+    filterValues: 100,
+    /** A text value in a filter (the grid's limit). */
+    valueLength: 500,
+    /** The largest page any source may declare. */
+    pageSize: 500,
+    /** An opaque pagination cursor. */
+    cursorLength: 512,
+    /** Fields one create or update may change. */
+    changes: 64,
+});
+/** A source name: lowercase words joined by `.`, `_` or `-`, at most 64 characters. */
+export const SOURCE_NAME_PATTERN = '^[a-z][a-z0-9]*([._-][a-z0-9]+)*$';
+/** A field name: a letter, then letters, digits or `_`, at most 64 characters. */
+export const SOURCE_FIELD_PATTERN = '^[A-Za-z][A-Za-z0-9_]*$';
+const NAME_RE = new RegExp(SOURCE_NAME_PATTERN);
+const FIELD_RE = new RegExp(SOURCE_FIELD_PATTERN);
+/** Whether `value` is a well-formed source name. */
+export function isSourceName(value) {
+    return typeof value === 'string' && value.length <= 64 && NAME_RE.test(value);
+}
+/** Whether `value` is a well-formed field name. */
+export function isSourceFieldName(value) {
+    return typeof value === 'string' && value.length <= 64 && FIELD_RE.test(value);
+}
+/** A thrown declaration mistake: the host's code, never agent data, gets this. */
+function declarationError(name, message) {
+    return new TypeError(`Data source "${name}": ${message}`);
+}
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+/**
+ * Check a host declaration and return its frozen descriptor. Throws a
+ * `TypeError` for a declaration mistake (an unknown type, a duplicate
+ * field, an operator the type does not take, a page size over the cap).
+ */
+export function describeSource(name, declaration) {
+    if (!isSourceName(name))
+        throw declarationError(String(name), 'the name is not a source name.');
+    const fields = Array.isArray(declaration.fields)
+        ? declaration.fields
+        : [];
+    if (fields.length === 0 || fields.length > SOURCE_LIMITS.fields) {
+        throw declarationError(name, `declare 1 to ${SOURCE_LIMITS.fields} fields.`);
+    }
+    const seen = new Set();
+    const out = [];
+    for (const field of fields) {
+        if (!isSourceFieldName(field?.name))
+            throw declarationError(name, 'a field name is malformed.');
+        if (seen.has(field.name))
+            throw declarationError(name, `"${field.name}" is declared twice.`);
+        seen.add(field.name);
+        if (!SOURCE_FIELD_TYPES.includes(field.type)) {
+            throw declarationError(name, `"${field.name}" has an unknown type.`);
+        }
+        const allowed = SOURCE_OPERATORS_BY_TYPE[field.type];
+        let filter = [];
+        if (field.filter === true)
+            filter = allowed;
+        else if (Array.isArray(field.filter)) {
+            const declared = field.filter;
+            for (const op of declared) {
+                if (!allowed.includes(op)) {
+                    throw declarationError(name, `"${field.name}" (${field.type}) cannot filter by "${op}".`);
+                }
+            }
+            filter = Object.freeze([...new Set(declared)]);
+        }
+        let options;
+        if (field.type === 'enum') {
+            const declared = Array.isArray(field.options) ? field.options : [];
+            if (declared.length === 0 ||
+                declared.length > SOURCE_LIMITS.enumOptions ||
+                declared.some((o) => typeof o !== 'string' || o.length > SOURCE_LIMITS.valueLength)) {
+                throw declarationError(name, `"${field.name}" needs 1 to 100 string options.`);
+            }
+            options = Object.freeze([...declared]);
+        }
+        else if (field.options !== undefined) {
+            throw declarationError(name, `"${field.name}" is not an enum and takes no options.`);
+        }
+        out.push(Object.freeze({
+            name: field.name,
+            type: field.type,
+            ...(options ? { options } : {}),
+            filter,
+            sort: field.sort === true,
+            editable: field.editable === true,
+            required: field.required === true,
+        }));
+    }
+    const key = declaration.key ?? 'id';
+    const keyField = out.find((field) => field.name === key);
+    if (!keyField)
+        throw declarationError(name, `the key "${key}" is not a declared field.`);
+    if (keyField.type !== 'text' && keyField.type !== 'number') {
+        throw declarationError(name, 'the key must be a text or number field.');
+    }
+    if (keyField.editable)
+        throw declarationError(name, 'the key cannot be editable.');
+    const operations = declaration.operations;
+    if (!Array.isArray(operations) ||
+        operations.some((op) => !SOURCE_OPERATIONS.includes(op))) {
+        throw declarationError(name, 'operations must come from SOURCE_OPERATIONS.');
+    }
+    const pagination = declaration.pagination ?? 'none';
+    if (!SOURCE_PAGINATION_STYLES.includes(pagination)) {
+        throw declarationError(name, 'pagination must be cursor, offset or none.');
+    }
+    const maxPageSize = declaration.maxPageSize ?? 100;
+    if (!isPositiveInteger(maxPageSize) || maxPageSize > SOURCE_LIMITS.pageSize) {
+        throw declarationError(name, `maxPageSize must be 1 to ${SOURCE_LIMITS.pageSize}.`);
+    }
+    const defaultPageSize = declaration.defaultPageSize ?? Math.min(25, maxPageSize);
+    if (!isPositiveInteger(defaultPageSize) || defaultPageSize > maxPageSize) {
+        throw declarationError(name, 'defaultPageSize must be 1 to maxPageSize.');
+    }
+    return Object.freeze({
+        name,
+        key,
+        fields: Object.freeze(out),
+        operations: Object.freeze(SOURCE_OPERATIONS.filter((op) => operations.includes(op))),
+        pagination,
+        maxPageSize,
+        defaultPageSize,
+    });
+}
+/** The descriptor's field named `name`, by own lookup (never the prototype chain). */
+export function sourceField(descriptor, name) {
+    for (const field of descriptor.fields)
+        if (field.name === name)
+            return field;
+    return undefined;
+}

package/dist/expression/analyze.d.ts

@@ -0,0 +1,17 @@
+import type { Expression, ExpressionDiagnostic, ExpressionFunctionTable, ExpressionType } from './types.js';
+export interface ExpressionAnalysisOptions {
+    /** Declared field types; when given, a field outside it is `unknown-field`. */
+    readonly fields?: Readonly<Record<string, ExpressionType>>;
+    /** The function table calls are typed against (default `CORE_FUNCTIONS`). */
+    readonly functions?: ExpressionFunctionTable;
+    /** The type the whole expression must have (`boolean` for a condition). */
+    readonly expect?: ExpressionType;
+}
+export interface ExpressionAnalysis {
+    readonly type: ExpressionType;
+    readonly diagnostics: readonly ExpressionDiagnostic[];
+}
+/** Whether a value of type `actual` can stand where `expected` is needed. */
+export declare function isAssignable(actual: ExpressionType, expected: ExpressionType): boolean;
+/** Infer an expression's type and report type and field problems. */
+export declare function analyzeExpression(expression: Expression, options?: ExpressionAnalysisOptions): ExpressionAnalysis;

package/dist/expression/analyze.js

@@ -0,0 +1,151 @@
+import { CORE_FUNCTIONS } from "./functions.js";
+/** Whether a value of type `actual` can stand where `expected` is needed. */
+export function isAssignable(actual, expected) {
+    if (expected === 'any' || actual === 'any' || actual === 'null' || actual === expected) {
+        return true;
+    }
+    // Dates are ISO strings: a string may be a date and a date reads as a string.
+    return ((actual === 'date' && expected === 'string') || (actual === 'string' && expected === 'date'));
+}
+const NUMERIC = ['number', 'boolean'];
+const ORDERED = (a, b) => {
+    if (a === 'any' || b === 'any' || a === 'null' || b === 'null')
+        return true;
+    if (a === 'number' && b === 'number')
+        return true;
+    if (a === 'boolean' && b === 'boolean')
+        return true;
+    const textual = (t) => t === 'string' || t === 'date';
+    return textual(a) && textual(b);
+};
+/** Infer an expression's type and report type and field problems. */
+export function analyzeExpression(expression, options = {}) {
+    const functions = options.functions ?? CORE_FUNCTIONS;
+    const fields = options.fields;
+    const diagnostics = [];
+    const report = (path, message, code = 'type') => {
+        if (diagnostics.length < 20)
+            diagnostics.push(Object.freeze({ code, path, message }));
+    };
+    const need = (type, allowed, path, what) => {
+        if (type === 'any' || type === 'null' || allowed.includes(type))
+            return;
+        report(path, `${what} needs ${allowed.join(' or ')}, not ${type}.`);
+    };
+    const visit = (node, path) => {
+        switch (node.op) {
+            case 'num':
+                return 'number';
+            case 'str':
+                return 'string';
+            case 'bool':
+                return 'boolean';
+            case 'null':
+                return 'null';
+            case 'var':
+            case 'field': {
+                if (!fields)
+                    return 'any';
+                if (!Object.hasOwn(fields, node.name)) {
+                    report(`${path}.name`, `There is no field "${node.name}".`, 'unknown-field');
+                    return 'any';
+                }
+                return fields[node.name];
+            }
+            case 'ref':
+                return 'any';
+            case 'range':
+                return 'list';
+            case 'add':
+            case 'sub':
+            case 'mul':
+            case 'div':
+            case 'mod':
+                need(visit(node.left, `${path}.left`), NUMERIC, `${path}.left`, `"${node.op}"`);
+                need(visit(node.right, `${path}.right`), NUMERIC, `${path}.right`, `"${node.op}"`);
+                return 'number';
+            case 'pow':
+                need(visit(node.base, `${path}.base`), NUMERIC, `${path}.base`, '"pow"');
+                need(visit(node.exponent, `${path}.exponent`), NUMERIC, `${path}.exponent`, '"pow"');
+                return 'number';
+            case 'neg':
+                need(visit(node.value, `${path}.value`), NUMERIC, `${path}.value`, '"neg"');
+                return 'number';
+            case 'eq':
+            case 'neq':
+                visit(node.left, `${path}.left`);
+                visit(node.right, `${path}.right`);
+                return 'boolean';
+            case 'lt':
+            case 'lte':
+            case 'gt':
+            case 'gte': {
+                const a = visit(node.left, `${path}.left`);
+                const b = visit(node.right, `${path}.right`);
+                if (!ORDERED(a, b))
+                    report(path, `"${node.op}" cannot order ${a} and ${b}.`);
+                return 'boolean';
+            }
+            case 'and':
+            case 'or':
+                node.args.forEach((arg, index) => {
+                    const at = `${path}.args[${index}]`;
+                    need(visit(arg, at), ['boolean', 'number'], at, `"${node.op}"`);
+                });
+                return 'boolean';
+            case 'not':
+                need(visit(node.value, `${path}.value`), ['boolean', 'number'], `${path}.value`, '"not"');
+                return 'boolean';
+            case 'if': {
+                need(visit(node.test, `${path}.test`), ['boolean', 'number'], `${path}.test`, '"if"');
+                const a = visit(node.ifTrue, `${path}.ifTrue`);
+                const b = visit(node.ifFalse, `${path}.ifFalse`);
+                if (a === b || b === 'null')
+                    return a;
+                return a === 'null' ? b : 'any';
+            }
+            case 'min':
+            case 'max':
+                node.args.forEach((arg, index) => {
+                    const at = `${path}.args[${index}]`;
+                    need(visit(arg, at), ['number', 'boolean', 'list'], at, `"${node.op}"`);
+                });
+                return 'number';
+            case 'concat':
+                for (const [index, arg] of node.args.entries())
+                    visit(arg, `${path}.args[${index}]`);
+                return 'string';
+            case 'round':
+                need(visit(node.value, `${path}.value`), NUMERIC, `${path}.value`, '"round"');
+                return 'number';
+            case 'clamp':
+                need(visit(node.value, `${path}.value`), NUMERIC, `${path}.value`, '"clamp"');
+                need(visit(node.min, `${path}.min`), NUMERIC, `${path}.min`, '"clamp"');
+                need(visit(node.max, `${path}.max`), NUMERIC, `${path}.max`, '"clamp"');
+                return 'number';
+            case 'call': {
+                const fn = Object.hasOwn(functions, node.fn) ? functions[node.fn] : undefined;
+                node.args.forEach((arg, index) => {
+                    const at = `${path}.args[${index}]`;
+                    const type = visit(arg, at);
+                    if (!fn || fn.params.length === 0)
+                        return;
+                    const expected = fn.params[Math.min(index, fn.params.length - 1)];
+                    if (!isAssignable(type, expected)) {
+                        report(at, `"${node.fn}" argument ${index + 1} needs ${expected}, not ${type}.`);
+                    }
+                });
+                return fn?.returns ?? 'any';
+            }
+            default:
+                return 'any';
+        }
+    };
+    const type = visit(expression.ast, '$');
+    if (options.expect && !isAssignable(type, options.expect)) {
+        if (!(options.expect === 'boolean' && type === 'number')) {
+            report('$', `The expression is ${type}; ${options.expect} is needed here.`);
+        }
+    }
+    return Object.freeze({ type, diagnostics: Object.freeze(diagnostics) });
+}

package/dist/expression/evaluate.d.ts

@@ -0,0 +1,55 @@
+import { type Expression, type ExpressionFunctionTable, type ExpressionValue } from './types.js';
+/**
+ * A step budget shared by every expression of one recalculation pass
+ * (default `EXPRESSION_LIMITS.passSteps`, 10,000,000). Once spent, every
+ * further evaluation in the pass is `#LIMIT!`.
+ */
+export interface ExpressionBudget {
+    readonly limit: number;
+    /** Steps spent so far. */
+    readonly used: number;
+    readonly exhausted: boolean;
+    /** Spend steps; returns false (and marks the budget exhausted) past the limit. */
+    spend(steps: number): boolean;
+}
+/** Make a budget for one recalculation pass. */
+export declare function createExpressionBudget(limit?: number): ExpressionBudget;
+/**
+ * Where an expression reads its inputs. Every method is optional; a
+ * missing `field` reads `null`, a missing `ref` or `range` is `#REF!`.
+ * Returned values are normalized: non-finite numbers become `null`,
+ * strings and lists past their caps become `#LIMIT!`, anything else that
+ * is not a scalar, a flat list or an error value becomes `#VALUE!`.
+ */
+export interface ExpressionEnv {
+    /** A `field` or `var` value by name. */
+    field?(name: string): unknown;
+    /** A dialect reference (`ref` node), such as a sheet cell. */
+    ref?(ref: string): unknown;
+    /** A dialect interval (`range` node) as a flat list, such as `A1:B3`. */
+    range?(from: string, to: string): unknown;
+    /** The host clock for `today()` (milliseconds or a Date). */
+    now?(): number | Date;
+}
+export interface ExpressionEvaluateOptions {
+    /** The closed function table (default `CORE_FUNCTIONS`); unknown names are `#NAME?`. */
+    readonly functions?: ExpressionFunctionTable;
+    /** The recalculation pass this evaluation belongs to. */
+    readonly budget?: ExpressionBudget;
+    /** Steps for this expression (default and maximum `EXPRESSION_LIMITS.steps`). */
+    readonly steps?: number;
+    /**
+     * How empty (`null`) operands behave in arithmetic and comparisons:
+     * `null` (default, forms) keeps them unknown; `zero` (spreadsheets) reads
+     * them as 0 or the empty string.
+     */
+    readonly blank?: 'null' | 'zero';
+    /** Compare strings ignoring case (spreadsheet `=` semantics). Default false. */
+    readonly caseInsensitive?: boolean;
+}
+/**
+ * Evaluate a validated expression (from `parseExpression` or
+ * `parseExpressionText`). Never throws: errors are values, and running past
+ * the per-expression or per-pass step limit is `#LIMIT!`.
+ */
+export declare function evaluateExpression(expression: Expression, env?: ExpressionEnv, options?: ExpressionEvaluateOptions): ExpressionValue;