@texuli/core 0.7.0 → 0.9.0

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

@@ -0,0 +1,78 @@
+/**
+ * The closed query model (ADR-015): projection, a filter tree in the
+ * `@texuli/data` grid filter model's shape, sort keys, search text and a
+ * page size. `checkSourceQuery` validates untrusted input against a source
+ * descriptor without recursion past the depth cap and in time linear in the
+ * input; the adapter receives the validated copy, never the input.
+ */
+import { type SourceDescriptor, type SourceFieldDescriptor, type SourceFilterOperator } from './schema.js';
+/** A value a row field or a filter holds. */
+export type SourceValue = string | number | boolean | null;
+/** One filter condition (the grid model's `FilterCondition`). */
+export interface SourceFilterCondition {
+    readonly type: 'condition';
+    readonly field: string;
+    readonly operator: SourceFilterOperator;
+    /** eq/neq: a scalar; contains: text; in: a list; between: [low, high]; before/after: a date. */
+    readonly value?: SourceValue | readonly SourceValue[];
+}
+/** An and/or group (the grid model's `FilterGroup`). */
+export interface SourceFilterGroup {
+    readonly type: 'group';
+    readonly op: 'and' | 'or';
+    readonly children: readonly SourceFilterNode[];
+}
+export type SourceFilterNode = SourceFilterCondition | SourceFilterGroup;
+export interface SourceSort {
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+/** A validated query. Every member is optional. */
+export interface SourceQuery {
+    /** Fields to return; the key always comes back. Omitted: every field. */
+    readonly fields?: readonly string[];
+    readonly filter?: SourceFilterNode;
+    readonly sort?: readonly SourceSort[];
+    /** Free text for a source that declares `search`. Passed to the adapter as data. */
+    readonly search?: string;
+    /** Rows per page, at most the source's `maxPageSize`. Omitted: its `defaultPageSize`. */
+    readonly pageSize?: number;
+}
+/** The query members, in canonical order. Anything else is refused. */
+export declare const SOURCE_QUERY_KEYS: readonly ["fields", "filter", "sort", "search", "pageSize"];
+export type SourceQueryIssueCode = 'shape' | 'limit' | 'unknown-field' | 'operator' | 'value' | 'sort' | 'search' | 'page-size' | 'operation';
+export interface SourceQueryIssue {
+    readonly code: SourceQueryIssueCode;
+    /** A JSON path into the query (`$.filter.children[0].value`). */
+    readonly path: string;
+    readonly message: string;
+}
+export type SourceQueryCheck = {
+    readonly ok: true;
+    readonly query: SourceQuery;
+} | {
+    readonly ok: false;
+    readonly issues: readonly SourceQueryIssue[];
+};
+/** Whether `value` is a date: an ISO 8601 date or date-time string, or epoch milliseconds. */
+export declare function isSourceDate(value: unknown): boolean;
+/** Whether `value` is a legal value of `field` (`null` is always legal: no value). */
+export declare function fitsSourceField(field: SourceFieldDescriptor, value: unknown): boolean;
+/**
+ * Validate an untrusted query against a source. On success the query is a
+ * frozen copy holding only checked members; on failure every issue (up to
+ * 32) has a code and a path. Strings are data: they reach the adapter as
+ * they came, and nothing here concatenates them into anything.
+ */
+export declare function checkSourceQuery(descriptor: SourceDescriptor, input: unknown): SourceQueryCheck;
+/**
+ * Canonical JSON of plain data: object keys sorted at every depth, arrays in
+ * order. Two equal queries give the same string, whatever their key order.
+ * Only call it on validated data (the depth is already bounded).
+ */
+export declare function stableJson(value: unknown): string;
+/** The cache and deduplication key of one page of one validated query. */
+export declare function sourceQueryKey(source: string, query: SourceQuery, page?: {
+    readonly cursor?: string | null;
+    readonly offset?: number | null;
+}): string;

package/dist/data-source/query.js

@@ -0,0 +1,339 @@
+/**
+ * The closed query model (ADR-015): projection, a filter tree in the
+ * `@texuli/data` grid filter model's shape, sort keys, search text and a
+ * page size. `checkSourceQuery` validates untrusted input against a source
+ * descriptor without recursion past the depth cap and in time linear in the
+ * input; the adapter receives the validated copy, never the input.
+ */
+import { isSourceFieldName, SOURCE_FILTER_OPERATORS, SOURCE_LIMITS, sourceField, } from "./schema.js";
+/** The query members, in canonical order. Anything else is refused. */
+export const SOURCE_QUERY_KEYS = ['fields', 'filter', 'sort', 'search', 'pageSize'];
+function isBag(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const DATE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?$/;
+/** Whether `value` is a date: an ISO 8601 date or date-time string, or epoch milliseconds. */
+export function isSourceDate(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    return (typeof value === 'string' &&
+        value.length <= 35 &&
+        DATE_RE.test(value) &&
+        !Number.isNaN(Date.parse(value)));
+}
+/** Whether `value` is a legal value of `field` (`null` is always legal: no value). */
+export function fitsSourceField(field, value) {
+    if (value === null)
+        return true;
+    switch (field.type) {
+        case 'text':
+            return typeof value === 'string';
+        case 'enum':
+            return typeof value === 'string' && (field.options ?? []).includes(value);
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'date':
+            return isSourceDate(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        default:
+            return false;
+    }
+}
+function isScalar(value) {
+    return (value === null ||
+        typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value)) ||
+        (typeof value === 'string' && value.length <= SOURCE_LIMITS.valueLength));
+}
+/**
+ * Whether the input filter is over the depth or node caps, measured without
+ * recursion so a tree nested thousands of levels deep is refused before
+ * anything recurses into it. Stops at the first excess.
+ */
+function filterOverLimits(input) {
+    const stack = [{ node: input, depth: 1 }];
+    let nodes = 0;
+    while (stack.length > 0) {
+        const { node, depth } = stack.pop();
+        nodes += 1;
+        if (depth > SOURCE_LIMITS.filterDepth || nodes > SOURCE_LIMITS.filterNodes)
+            return true;
+        const children = isBag(node) ? node.children : undefined;
+        if (!Array.isArray(children))
+            continue;
+        if (nodes + stack.length + children.length > SOURCE_LIMITS.filterNodes)
+            return true;
+        for (const child of children)
+            stack.push({ node: child, depth: depth + 1 });
+    }
+    return false;
+}
+function report(checker, code, path, message) {
+    // One bad query can say a lot; the first 32 issues are enough to fix it.
+    if (checker.issues.length < 32)
+        checker.issues.push(Object.freeze({ code, path, message }));
+}
+/** An object with exactly the allowed own keys (a JSON `__proto__` key is an own key, and refused). */
+function closedKeys(checker, value, allowed, path) {
+    let ok = true;
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            report(checker, 'shape', `${path}.${key}`, `"${key}" is not part of a query here.`);
+            ok = false;
+        }
+    }
+    return ok;
+}
+function knownField(checker, name, path) {
+    if (!isSourceFieldName(name)) {
+        report(checker, 'shape', path, 'A field is named by a field name.');
+        return undefined;
+    }
+    const field = sourceField(checker.descriptor, name);
+    if (!field) {
+        report(checker, 'unknown-field', path, `"${checker.descriptor.name}" has no "${name}" field.`);
+    }
+    return field;
+}
+function checkCondition(checker, input, path) {
+    if (!closedKeys(checker, input, ['type', 'field', 'operator', 'value'], path))
+        return null;
+    const field = knownField(checker, input.field, `${path}.field`);
+    const operator = input.operator;
+    if (!SOURCE_FILTER_OPERATORS.includes(operator)) {
+        report(checker, 'operator', `${path}.operator`, 'The operator is not a filter operator.');
+        return null;
+    }
+    if (!field)
+        return null;
+    const op = operator;
+    if (!field.filter.includes(op)) {
+        report(checker, 'operator', `${path}.operator`, `"${field.name}" cannot be filtered by "${op}".`);
+        return null;
+    }
+    const here = `${path}.value`;
+    const has = Object.hasOwn(input, 'value');
+    const value = input.value;
+    const fail = (message) => {
+        report(checker, 'value', here, message);
+        return null;
+    };
+    // A list value is checked item by item against the field's type.
+    const fitsAll = (list) => list.every((item) => isScalar(item) && fitsSourceField(field, item));
+    if (op === 'isEmpty' || op === 'isNotEmpty') {
+        if (has)
+            return fail(`${op} takes no value.`);
+        return Object.freeze({ type: 'condition', field: field.name, operator: op });
+    }
+    if (op === 'in') {
+        if (!Array.isArray(value) || value.length === 0 || value.length > SOURCE_LIMITS.filterValues) {
+            return fail(`in needs a list of 1 to ${SOURCE_LIMITS.filterValues} values.`);
+        }
+        if (!fitsAll(value))
+            return fail(`Every value must fit "${field.name}" (${field.type}).`);
+        return Object.freeze({
+            type: 'condition',
+            field: field.name,
+            operator: op,
+            value: Object.freeze([...value]),
+        });
+    }
+    if (op === 'between') {
+        if (!Array.isArray(value) || value.length !== 2 || value.includes(null) || !fitsAll(value)) {
+            return fail(`between needs [low, high] values of "${field.name}" (${field.type}).`);
+        }
+        return Object.freeze({
+            type: 'condition',
+            field: field.name,
+            operator: op,
+            value: Object.freeze([...value]),
+        });
+    }
+    if (op === 'contains' && (typeof value !== 'string' || value === '')) {
+        return fail('contains needs text.');
+    }
+    if ((op === 'before' || op === 'after') && !isSourceDate(value)) {
+        return fail(`${op} needs a date.`);
+    }
+    if (!has || !isScalar(value) || !fitsSourceField(field, value)) {
+        return fail(`${op} needs one value of "${field.name}" (${field.type}).`);
+    }
+    return Object.freeze({ type: 'condition', field: field.name, operator: op, value });
+}
+/** Recursion is safe here: `filterOverLimits` capped the depth at 6 first. */
+function checkFilter(checker, input, path) {
+    if (!isBag(input)) {
+        report(checker, 'shape', path, 'A filter node is an object.');
+        return null;
+    }
+    if (input.type === 'group') {
+        if (!closedKeys(checker, input, ['type', 'op', 'children'], path))
+            return null;
+        if (input.op !== 'and' && input.op !== 'or') {
+            report(checker, 'shape', `${path}.op`, 'A group is "and" or "or".');
+            return null;
+        }
+        if (!Array.isArray(input.children) || input.children.length === 0) {
+            report(checker, 'shape', `${path}.children`, 'A group needs at least one child.');
+            return null;
+        }
+        const children = [];
+        input.children.forEach((child, index) => {
+            const checked = checkFilter(checker, child, `${path}.children[${index}]`);
+            if (checked)
+                children.push(checked);
+        });
+        if (children.length !== input.children.length)
+            return null;
+        return Object.freeze({ type: 'group', op: input.op, children: Object.freeze(children) });
+    }
+    if (input.type !== 'condition') {
+        report(checker, 'shape', `${path}.type`, 'A filter node is a "condition" or a "group".');
+        return null;
+    }
+    return checkCondition(checker, input, path);
+}
+function checkFields(checker, input) {
+    if (!Array.isArray(input) || input.length === 0 || input.length > SOURCE_LIMITS.projection) {
+        report(checker, 'shape', '$.fields', `fields lists 1 to ${SOURCE_LIMITS.projection} field names.`);
+        return null;
+    }
+    const out = [];
+    input.forEach((name, index) => {
+        const field = knownField(checker, name, `$.fields[${index}]`);
+        if (field && !out.includes(field.name))
+            out.push(field.name);
+    });
+    // A repeated name is dropped; an unknown one was reported and fails the query.
+    return Object.freeze(out);
+}
+function checkSort(checker, input) {
+    if (!Array.isArray(input) || input.length === 0 || input.length > SOURCE_LIMITS.sort) {
+        report(checker, 'shape', '$.sort', `sort lists 1 to ${SOURCE_LIMITS.sort} keys.`);
+        return null;
+    }
+    const out = [];
+    input.forEach((entry, index) => {
+        const path = `$.sort[${index}]`;
+        if (!isBag(entry) || !closedKeys(checker, entry, ['field', 'direction'], path)) {
+            if (!isBag(entry))
+                report(checker, 'shape', path, 'A sort key is an object.');
+            return;
+        }
+        const direction = entry.direction ?? 'asc';
+        if (direction !== 'asc' && direction !== 'desc') {
+            report(checker, 'shape', `${path}.direction`, 'direction is "asc" or "desc".');
+            return;
+        }
+        const field = knownField(checker, entry.field, `${path}.field`);
+        if (!field)
+            return;
+        if (!field.sort) {
+            report(checker, 'sort', `${path}.field`, `"${field.name}" is not sortable.`);
+            return;
+        }
+        if (out.some((sort) => sort.field === field.name)) {
+            report(checker, 'sort', `${path}.field`, `"${field.name}" is sorted twice.`);
+            return;
+        }
+        out.push(Object.freeze({ field: field.name, direction }));
+    });
+    return Object.freeze(out);
+}
+/**
+ * Validate an untrusted query against a source. On success the query is a
+ * frozen copy holding only checked members; on failure every issue (up to
+ * 32) has a code and a path. Strings are data: they reach the adapter as
+ * they came, and nothing here concatenates them into anything.
+ */
+export function checkSourceQuery(descriptor, input) {
+    const checker = { descriptor, issues: [] };
+    const lists = descriptor.operations.includes('list') || descriptor.operations.includes('search');
+    if (!lists) {
+        report(checker, 'operation', '$', `"${descriptor.name}" cannot list rows.`);
+        return { ok: false, issues: checker.issues };
+    }
+    if (input === undefined)
+        return { ok: true, query: Object.freeze({}) };
+    if (!isBag(input)) {
+        report(checker, 'shape', '$', 'A query is an object.');
+        return { ok: false, issues: checker.issues };
+    }
+    closedKeys(checker, input, SOURCE_QUERY_KEYS, '$');
+    const query = {};
+    if (Object.hasOwn(input, 'fields')) {
+        const fields = checkFields(checker, input.fields);
+        if (fields)
+            query.fields = fields;
+    }
+    if (Object.hasOwn(input, 'filter')) {
+        if (filterOverLimits(input.filter)) {
+            report(checker, 'limit', '$.filter', `A filter has at most ${SOURCE_LIMITS.filterDepth} levels and ${SOURCE_LIMITS.filterNodes} nodes.`);
+        }
+        else {
+            const filter = checkFilter(checker, input.filter, '$.filter');
+            if (filter)
+                query.filter = filter;
+        }
+    }
+    if (Object.hasOwn(input, 'sort')) {
+        const sort = checkSort(checker, input.sort);
+        if (sort)
+            query.sort = sort;
+    }
+    if (Object.hasOwn(input, 'search')) {
+        const search = input.search;
+        if (!descriptor.operations.includes('search')) {
+            report(checker, 'search', '$.search', `"${descriptor.name}" does not search.`);
+        }
+        else if (typeof search !== 'string' || search.length > SOURCE_LIMITS.searchLength) {
+            report(checker, 'shape', '$.search', `search is text of at most ${SOURCE_LIMITS.searchLength} characters.`);
+        }
+        else if (search !== '') {
+            query.search = search;
+        }
+    }
+    if (Object.hasOwn(input, 'pageSize')) {
+        const size = input.pageSize;
+        if (typeof size !== 'number' || !Number.isInteger(size) || size < 1) {
+            report(checker, 'page-size', '$.pageSize', 'pageSize is a positive integer.');
+        }
+        else if (size > descriptor.maxPageSize) {
+            report(checker, 'page-size', '$.pageSize', `"${descriptor.name}" pages at most ${descriptor.maxPageSize} rows.`);
+        }
+        else {
+            query.pageSize = size;
+        }
+    }
+    if (checker.issues.length > 0)
+        return { ok: false, issues: checker.issues };
+    return { ok: true, query: Object.freeze(query) };
+}
+/**
+ * Canonical JSON of plain data: object keys sorted at every depth, arrays in
+ * order. Two equal queries give the same string, whatever their key order.
+ * Only call it on validated data (the depth is already bounded).
+ */
+export function stableJson(value) {
+    if (value === undefined)
+        return 'null';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableJson(item)).join(',')}]`;
+    const keys = Object.keys(value)
+        .filter((key) => value[key] !== undefined)
+        .sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+}
+/** The cache and deduplication key of one page of one validated query. */
+export function sourceQueryKey(source, query, page = {}) {
+    const projection = query.fields ? [...query.fields].sort() : undefined;
+    return stableJson({
+        source,
+        query: { ...query, ...(projection ? { fields: projection } : {}) },
+        cursor: page.cursor ?? null,
+        offset: page.offset ?? null,
+    });
+}

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

@@ -0,0 +1,83 @@
+/**
+ * The host's source registry: the only place a blueprint's source name
+ * resolves. A source is a declaration plus an adapter the host writes; the
+ * adapter alone decides how to reach the data (memory, `fetch`, a client
+ * SDK). Texuli never builds a URL, SQL or code from a query, and agents
+ * never see an adapter, only {@link SourceDescriptor}s.
+ */
+import type { SourceQuery, SourceValue } from './query.js';
+import { type SourceDescriptor, type SourceSchemaDeclaration } from './schema.js';
+/** A row's identity: the value of its key field. */
+export type SourceRowId = string | number;
+/** One row: field name → scalar. */
+export type SourceRow = Readonly<Record<string, SourceValue>>;
+/** Which page `list` asks for. `cursor` or `offset` follows the source's pagination style. */
+export interface SourcePageRequest {
+    readonly size: number;
+    readonly cursor?: string;
+    readonly offset?: number;
+}
+export interface SourceListRequest {
+    /** The validated query (a frozen copy; never the agent's input). */
+    readonly query: SourceQuery;
+    readonly page: SourcePageRequest;
+    readonly signal: AbortSignal;
+}
+/** What an adapter's `list` resolves to. */
+export interface SourcePage<Row = SourceRow> {
+    readonly rows: readonly Row[];
+    /** `cursor` sources: the next page's cursor, `null` or omitted at the end. */
+    readonly nextCursor?: string | null;
+    /** `offset` sources: whether rows follow. Default: a full page means maybe. */
+    readonly hasMore?: boolean;
+    /** The total row count, when the source knows it. */
+    readonly total?: number;
+}
+/**
+ * The host's code for one source. Each method backs the operation of the
+ * same name (`list` also backs `search`); a missing method for a declared
+ * operation is a declaration error. Every request carries an `AbortSignal`.
+ */
+export interface SourceAdapter<Row = SourceRow> {
+    list?(request: SourceListRequest): Promise<SourcePage<Row>>;
+    get?(request: {
+        readonly id: SourceRowId;
+        readonly signal: AbortSignal;
+    }): Promise<Row | null>;
+    create?(request: {
+        readonly values: Readonly<Record<string, SourceValue>>;
+        readonly signal: AbortSignal;
+    }): Promise<Row>;
+    update?(request: {
+        readonly id: SourceRowId;
+        readonly changes: Readonly<Record<string, SourceValue>>;
+        readonly signal: AbortSignal;
+    }): Promise<Row>;
+    delete?(request: {
+        readonly id: SourceRowId;
+        readonly signal: AbortSignal;
+    }): Promise<void>;
+}
+/** A declared source: its descriptor and the host's adapter. */
+export interface DataSource {
+    readonly descriptor: SourceDescriptor;
+    readonly adapter: SourceAdapter;
+}
+/**
+ * Declare a source. Throws a `TypeError` for a declaration mistake,
+ * including a declared operation without its adapter method.
+ */
+export declare function defineSource(name: string, schema: SourceSchemaDeclaration, adapter: SourceAdapter): DataSource;
+export interface SourceRegistry {
+    has(name: string): boolean;
+    get(name: string): DataSource | undefined;
+    /** Every registered name, sorted. */
+    names(): readonly string[];
+    /** One source's descriptor, or every descriptor (sorted by name): what validators and agents read. */
+    describe(name: string): SourceDescriptor | undefined;
+    describe(): readonly SourceDescriptor[];
+    /** Add a source; returns its removal. Throws on a taken name or past 256 sources. */
+    register(source: DataSource): () => void;
+}
+/** A registry seeded with `sources`. Lookups never reach the prototype chain. */
+export declare function createSourceRegistry(sources?: readonly DataSource[]): SourceRegistry;

package/dist/data-source/registry.js

@@ -0,0 +1,63 @@
+/**
+ * The host's source registry: the only place a blueprint's source name
+ * resolves. A source is a declaration plus an adapter the host writes; the
+ * adapter alone decides how to reach the data (memory, `fetch`, a client
+ * SDK). Texuli never builds a URL, SQL or code from a query, and agents
+ * never see an adapter, only {@link SourceDescriptor}s.
+ */
+import { describeSource, SOURCE_LIMITS, } from "./schema.js";
+const METHOD = Object.freeze({
+    list: 'list',
+    search: 'list',
+    get: 'get',
+    create: 'create',
+    update: 'update',
+    delete: 'delete',
+});
+/**
+ * Declare a source. Throws a `TypeError` for a declaration mistake,
+ * including a declared operation without its adapter method.
+ */
+export function defineSource(name, schema, adapter) {
+    const descriptor = describeSource(name, schema);
+    for (const op of descriptor.operations) {
+        if (typeof adapter?.[METHOD[op]] !== 'function') {
+            throw new TypeError(`Data source "${name}": "${op}" needs adapter.${METHOD[op]}().`);
+        }
+    }
+    return Object.freeze({ descriptor, adapter });
+}
+/** A registry seeded with `sources`. Lookups never reach the prototype chain. */
+export function createSourceRegistry(sources = []) {
+    const map = new Map();
+    const registry = {
+        has: (name) => typeof name === 'string' && map.has(name),
+        get: (name) => (typeof name === 'string' ? map.get(name) : undefined),
+        names: () => [...map.keys()].sort(),
+        describe: ((name) => {
+            if (name !== undefined)
+                return map.get(name)?.descriptor;
+            return Object.freeze([...map.values()]
+                .map((source) => source.descriptor)
+                .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)));
+        }),
+        register(source) {
+            const name = source?.descriptor?.name;
+            if (typeof name !== 'string')
+                throw new TypeError('Register a source made by defineSource.');
+            if (map.has(name))
+                throw new TypeError(`Data source "${name}" is already registered.`);
+            if (map.size >= SOURCE_LIMITS.sources) {
+                throw new TypeError(`A registry holds at most ${SOURCE_LIMITS.sources} sources.`);
+            }
+            map.set(name, source);
+            return () => {
+                if (map.get(name) === source)
+                    map.delete(name);
+            };
+        },
+    };
+    for (const source of sources)
+        registry.register(source);
+    return Object.freeze(registry);
+}