@agentshouse/mdmodel 0.1.0-ccf1367190878 → 0.1.0-cdbd463e01dc2

package/dist/query/language.js

@@ -0,0 +1,565 @@
+import { crossedFacts, escapePointer, pointerFacts, pointerSegments, } from '../definition.js';
+import { fitsKind, kindOf, kindWords } from '../kinds.js';
+import { normalize } from '../paths.js';
+import { plain } from '../yaml.js';
+export class QueryError extends Error {
+    code;
+    place;
+    accepts;
+    retryable = false;
+    constructor(code, at, problem, accepts = []) {
+        super(`${code} at ${placeText(placed(at))}: ${problem}`);
+        this.code = code;
+        this.place = placed(at);
+        this.accepts = accepts;
+    }
+}
+const RANGE = ['$gt', '$gte', '$lt', '$lte'];
+const SINGLE = ['$eq', '$ne', '$in', '$nin', '$all', '$size', '$exists', '$prefix'];
+const FILTER = [
+    'rooms',
+    'types',
+    'where',
+    'pathPrefix',
+    'folder',
+    'paths',
+    'fileIds',
+    'hop',
+    'backlinks',
+    'text',
+];
+const RELATED = ['types', 'where', 'pathPrefix', 'field'];
+const PARTS = [
+    'fields',
+    'sections',
+    'preamble',
+    'markdown',
+    'backlinks',
+    'change',
+    'fileId',
+    'revision',
+];
+const ORDER = ['by', 'direction', 'nulls', 'stringSort', 'locale', 'localeOptions'];
+const STRAY_ESCAPE = /~(?![01])/u;
+export function bodied(shape) {
+    return shape.sections !== null || shape.preamble || shape.markdown;
+}
+export function invalid(at, problem, accepts = []) {
+    throw new QueryError('invalid-query', at, problem, accepts);
+}
+function placed(at) {
+    if (typeof at !== 'string')
+        return at;
+    return at === '' ? [] : [at];
+}
+export function placeText(at) {
+    return at.reduce((text, step) => {
+        if (typeof step === 'number')
+            return `${text}[${step}]`;
+        if (step.startsWith('/') || text === '')
+            return `${text}${step}`;
+        return `${text}.${step}`;
+    }, '');
+}
+function place(at, step) {
+    return [...placed(at), step];
+}
+export function known(value, allowed, at) {
+    for (const name of Object.keys(value)) {
+        if (!allowed.includes(name))
+            invalid(place(at, name), 'unknown part', allowed);
+    }
+}
+function list(input, at) {
+    if (!Array.isArray(input))
+        invalid(at, 'expects a list');
+    return input;
+}
+function value(input, at) {
+    if (Array.isArray(input))
+        invalid(at, 'a list is not a value');
+    if (input !== null &&
+        typeof input !== 'string' &&
+        typeof input !== 'boolean' &&
+        !(typeof input === 'number' && Number.isFinite(input))) {
+        invalid(at, 'not a value');
+    }
+    return input;
+}
+function values(input, at) {
+    return list(input, at).map((item, index) => value(item, place(at, index)));
+}
+function names(input, at) {
+    const listed = list(input, at);
+    if (listed.some((item) => typeof item !== 'string'))
+        invalid(at, 'expects a list of names');
+    return [...new Set(listed)].sort();
+}
+function pathsOf(input) {
+    const listed = list(input, 'paths');
+    if (listed.some((item) => typeof item !== 'string' || item === '' || normalize(item) !== item)) {
+        invalid('paths', 'expects a list of Paths');
+    }
+    return [...new Set(listed)].sort();
+}
+function fileIdsOf(input) {
+    const listed = list(input, 'fileIds');
+    if (listed.some((item) => typeof item !== 'string' || item === '')) {
+        invalid('fileIds', 'expects a list of file IDs');
+    }
+    return [...new Set(listed)].sort();
+}
+function phrase(input) {
+    if (typeof input !== 'string' || input === '')
+        invalid('text', 'expects a phrase');
+    return input;
+}
+function directory(input, at) {
+    if (typeof input !== 'string' || normalize(input) !== input) {
+        invalid(at, 'expects a normalized directory');
+    }
+    return input;
+}
+function itemOf(facts) {
+    return facts.type === 'array' ? facts.items : facts;
+}
+function fits(facts, value) {
+    const item = itemOf(facts);
+    if (item === undefined || (item.type === undefined && item.values === undefined))
+        return true;
+    const kind = kindOf(item);
+    return kind !== null && fitsKind(kind, item, value);
+}
+function textless(facts) {
+    const item = itemOf(facts);
+    if (item?.values !== undefined)
+        return !item.values.some((held) => typeof held === 'string');
+    return item?.type !== undefined && item.type !== 'string';
+}
+function typing(facts, rooms, types, at) {
+    const read = rooms === null ? facts.rooms : facts.rooms.filter((room) => rooms.includes(room.locator));
+    const acquiring = !facts.listed &&
+        (rooms === null ||
+            rooms.some((locator) => !facts.rooms.some((room) => room.locator === locator)));
+    const available = !acquiring && read.every((room) => room.available);
+    const declared = read.flatMap((room) => room.types);
+    for (const name of types ?? []) {
+        if (name === 'any' || !available || declared.some((type) => type.name === name))
+            continue;
+        throw new QueryError('unknown-type', place(at, 'types'), `no model it reads declares ${name}`, [...new Set(declared.map((type) => type.name))].sort());
+    }
+    return {
+        untyped: types === null || types.includes('any') || !available,
+        types: types === null ? declared : declared.filter((type) => types.includes(type.name)),
+    };
+}
+function pointer(input, at) {
+    if (typeof input !== 'string' || !input.startsWith('/') || STRAY_ESCAPE.test(input)) {
+        invalid(at, 'expects a JSON Pointer');
+    }
+    return input;
+}
+function specs(typed, input, at) {
+    const field = pointer(input, at);
+    const declared = typed.types.flatMap((type) => {
+        const spec = pointerFacts(type, field);
+        return spec === undefined ? [] : [spec];
+    });
+    if (declared.length === 0 && !typed.untyped) {
+        throw new QueryError('unknown-field', at, `no MD Type it reads declares ${field}`, nearby(typed.types, field));
+    }
+    if (!declared.some((spec) => spec.conditional))
+        return declared;
+    return declared.map((spec) => ({
+        facts: { prose: false },
+        through: several(spec),
+        conditional: true,
+    }));
+}
+function nearby(types, field) {
+    const segments = pointerSegments(field);
+    for (let length = segments.length - 1; length > 0; length -= 1) {
+        const prefix = segments
+            .slice(0, length)
+            .map((segment) => `/${escapePointer(segment)}`)
+            .join('');
+        const children = types.flatMap((type) => {
+            const reached = pointerFacts(type, prefix);
+            return (reached === undefined ? [] : crossedFacts(reached.facts)).flatMap((crossed) => Object.keys(crossed.properties ?? {}).map((key) => `${prefix}/${escapePointer(key)}`));
+        });
+        if (children.length > 0)
+            return [...new Set(children)].sort();
+    }
+    return [
+        ...new Set(types.flatMap((type) => Object.keys(type.fields).map((name) => `/${escapePointer(name)}`))),
+    ].sort();
+}
+function several(spec) {
+    return spec.through || spec.facts.type === 'array';
+}
+function single(spec) {
+    return spec.facts.type !== undefined && spec.facts.type !== 'array';
+}
+function every(declared, holds) {
+    return declared.length > 0 && declared.every(holds);
+}
+function kind(declared, checked, at) {
+    if (checked === null ||
+        declared.length === 0 ||
+        declared.some((spec) => fits(spec.facts, checked))) {
+        return;
+    }
+    throw new QueryError('wrong-kind', at, `${JSON.stringify(checked)} is not of its field's kind`, [
+        ...new Set(declared.flatMap((spec) => kindWords(itemOf(spec.facts)))),
+    ]);
+}
+function test(declared, input, at) {
+    if (!plain(input)) {
+        const equal = value(input, at);
+        kind(declared, equal, at);
+        return { op: 'eq', value: equal };
+    }
+    const operators = Object.keys(input);
+    if (operators.length === 0)
+        invalid(at, 'names no operator');
+    if (operators.some((operator) => RANGE.includes(operator))) {
+        const stray = operators.find((operator) => !RANGE.includes(operator));
+        if (stray !== undefined)
+            invalid(place(at, stray), 'cannot join a range');
+        if (every(declared, (spec) => spec.facts.type === 'array'))
+            invalid(at, 'a range on a list');
+        if (every(declared, (spec) => spec.facts.type === 'boolean' || spec.facts.type === 'object')) {
+            throw new QueryError('wrong-kind', at, 'its field does not compare in order');
+        }
+        return {
+            op: 'range',
+            bounds: RANGE.filter((operator) => operators.includes(operator)).map((operator) => {
+                const bound = value(input[operator], place(at, operator));
+                if (bound === null)
+                    invalid(place(at, operator), 'a range bound is never null');
+                kind(declared, bound, place(at, operator));
+                return [operator.slice(1), bound];
+            }),
+        };
+    }
+    if (operators.length > 1)
+        invalid(place(at, operators[1]), 'names a second operator');
+    const [operator] = operators;
+    const where = place(at, operator);
+    if (!SINGLE.includes(operator)) {
+        invalid(where, 'unknown operator', [...SINGLE, ...RANGE]);
+    }
+    const operand = input[operator];
+    if (operator === '$eq' || operator === '$ne') {
+        const compared = value(operand, where);
+        kind(declared, compared, where);
+        return operator === '$eq' ? { op: 'eq', value: compared } : { op: 'ne', value: compared };
+    }
+    if (operator === '$in' || operator === '$nin' || operator === '$all') {
+        const compared = values(operand, where);
+        compared.forEach((item, index) => kind(declared, item, place(where, index)));
+        if (operator === '$in')
+            return { op: 'in', values: compared };
+        if (operator === '$nin')
+            return { op: 'nin', values: compared };
+        if (compared.includes(null))
+            invalid(where, 'a list holds no null');
+        if (every(declared, single))
+            invalid(where, 'the field is not a list');
+        return { op: 'all', values: compared };
+    }
+    if (operator === '$size') {
+        if (!Number.isSafeInteger(operand) || operand < 0) {
+            invalid(where, 'expects a nonnegative integer');
+        }
+        if (every(declared, single))
+            invalid(where, 'the field is not a list');
+        return { op: 'size', size: operand };
+    }
+    if (operator === '$prefix') {
+        if (typeof operand !== 'string')
+            invalid(where, 'expects a string');
+        if (every(declared, (spec) => textless(spec.facts))) {
+            throw new QueryError('wrong-kind', where, 'its field holds no text');
+        }
+        return { op: 'prefix', prefix: operand };
+    }
+    if (typeof operand !== 'boolean')
+        invalid(where, 'expects true or false');
+    return { op: 'exists', exists: operand };
+}
+function condition(typed, input, at) {
+    if (!plain(input))
+        invalid(at, 'expects an object of field predicates');
+    const conditions = [];
+    for (const name of Object.keys(input).sort()) {
+        const where = place(at, name);
+        const entry = input[name];
+        if (name === '$and' || name === '$or') {
+            const nested = list(entry, where).map((item, index) => condition(typed, item, place(where, index)));
+            if (nested.length === 0)
+                invalid(where, 'expects a nonempty list');
+            conditions.push(name === '$and' ? { every: nested } : { some: nested });
+            continue;
+        }
+        if (name.startsWith('$'))
+            invalid(where, 'unknown operator');
+        conditions.push({ field: name, test: test(specs(typed, name, where), entry, where) });
+    }
+    if (conditions.length === 0)
+        invalid(at, 'names no field');
+    return conditions.length === 1 ? conditions[0] : { every: conditions };
+}
+function scope(facts, rooms, input, at) {
+    const types = input.types === undefined ? null : names(input.types, place(at, 'types'));
+    const typed = typing(facts, rooms, types, at);
+    return {
+        typed,
+        types,
+        where: input.where === undefined || (plain(input.where) && Object.keys(input.where).length === 0)
+            ? null
+            : condition(typed, input.where, place(at, 'where')),
+        pathPrefix: input.pathPrefix === undefined ? null : directory(input.pathPrefix, place(at, 'pathPrefix')),
+    };
+}
+function referenceName(typed, field, at) {
+    const declared = specs(typed, field, at);
+    if (declared.length > 0 &&
+        !declared.some((spec) => spec.conditional ||
+            spec.facts.reference !== undefined ||
+            spec.facts.items?.reference !== undefined)) {
+        invalid(at, 'not a reference field');
+    }
+    return field;
+}
+function hopOf(facts, rooms, root, input) {
+    if (!plain(input))
+        invalid('hop', 'expects an object');
+    known(input, RELATED, 'hop');
+    const field = referenceName(root, input.field, ['hop', 'field']);
+    const { types, where, pathPrefix } = scope(facts, rooms, input, 'hop');
+    return { types, where, pathPrefix, field };
+}
+function backlinksOf(facts, rooms, input) {
+    if (!plain(input))
+        invalid('backlinks', 'expects an object');
+    known(input, RELATED, 'backlinks');
+    const { typed, types, where, pathPrefix } = scope(facts, rooms, input, 'backlinks');
+    const field = input.field === undefined ? null : referenceName(typed, input.field, ['backlinks', 'field']);
+    return { types, where, pathPrefix, field };
+}
+function keyPlan(typed, input, at, path) {
+    if (input === 'room' || input === 'type' || input === 'folder' || (path && input === 'path')) {
+        return { of: input };
+    }
+    if (plain(input) && Object.hasOwn(input, 'field') && Object.keys(input).length === 1) {
+        if (specs(typed, input.field, place(at, 'field')).some(several)) {
+            invalid(place(at, 'field'), 'a path that can hold several values');
+        }
+        return { of: 'field', field: input.field };
+    }
+    return invalid(at, path ? 'expects room, path, type, folder or a field' : 'expects room, type, folder or a field');
+}
+function direction(input, at) {
+    if (input === undefined)
+        return 'asc';
+    if (input !== 'asc' && input !== 'desc')
+        invalid(at, 'expects asc or desc');
+    return input;
+}
+function orderOptions(input, at) {
+    const options = {
+        direction: direction(input.direction, place(at, 'direction')),
+    };
+    if (input.nulls !== undefined) {
+        if (input.nulls !== 'first' && input.nulls !== 'last') {
+            invalid(place(at, 'nulls'), 'expects first or last');
+        }
+        options.nulls = input.nulls;
+    }
+    if (input.stringSort !== undefined) {
+        if (input.stringSort !== 'lexical' && input.stringSort !== 'locale') {
+            invalid(place(at, 'stringSort'), 'expects lexical or locale');
+        }
+        options.stringSort = input.stringSort;
+    }
+    if (input.locale !== undefined) {
+        if (typeof input.locale !== 'string' || !collates(input.locale, undefined)) {
+            invalid(place(at, 'locale'), 'expects a locale name');
+        }
+        options.locale = input.locale;
+    }
+    if (input.localeOptions !== undefined) {
+        if (!plain(input.localeOptions) || !collates(options.locale, input.localeOptions)) {
+            invalid(place(at, 'localeOptions'), 'expects collation options');
+        }
+        options.localeOptions = input.localeOptions;
+    }
+    return options;
+}
+function collates(locale, options) {
+    try {
+        ''.localeCompare('', locale, options);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parts(typed, input, at, fields) {
+    if (input === undefined)
+        return null;
+    if (input === 'all')
+        return 'all';
+    const named = list(input, at);
+    named.forEach((name, index) => {
+        if (fields)
+            specs(typed, name, place(at, index));
+        else if (typeof name !== 'string')
+            invalid(place(at, index), 'expects a name');
+    });
+    return named;
+}
+function flag(input, at) {
+    if (input === undefined)
+        return false;
+    if (input !== true)
+        invalid(at, 'expects true');
+    return true;
+}
+function documentShape(typed, input) {
+    const orderBy = (input.orderBy === undefined ? [] : list(input.orderBy, 'orderBy')).map((clause, index) => {
+        const at = place('orderBy', index);
+        if (!plain(clause))
+            invalid(at, 'expects an order clause');
+        known(clause, ORDER, at);
+        return {
+            key: keyPlan(typed, clause.by, place(at, 'by'), true),
+            options: orderOptions(clause, at),
+        };
+    });
+    const select = input.select;
+    if (select === 'all') {
+        return {
+            kind: 'documents',
+            fields: 'all',
+            sections: 'all',
+            preamble: true,
+            markdown: true,
+            backlinks: true,
+            change: true,
+            fileId: true,
+            revision: true,
+            orderBy,
+        };
+    }
+    if (!plain(select))
+        invalid('select', "expects 'all' or the parts to return");
+    known(select, PARTS, 'select');
+    return {
+        kind: 'documents',
+        fields: parts(typed, select.fields, ['select', 'fields'], true),
+        sections: parts(typed, select.sections, ['select', 'sections'], false),
+        preamble: flag(select.preamble, ['select', 'preamble']),
+        markdown: flag(select.markdown, ['select', 'markdown']),
+        backlinks: flag(select.backlinks, ['select', 'backlinks']),
+        change: flag(select.change, ['select', 'change']),
+        fileId: flag(select.fileId, ['select', 'fileId']),
+        revision: flag(select.revision, ['select', 'revision']),
+        orderBy,
+    };
+}
+function groupShape(typed, input) {
+    const groupBy = list(input.groupBy, 'groupBy').map((key, index) => keyPlan(typed, key, place('groupBy', index), false));
+    if (groupBy.length === 0)
+        invalid('groupBy', 'names no key');
+    const grouped = groupBy.map((key) => JSON.stringify(key));
+    const orderBy = (input.orderBy === undefined ? [] : list(input.orderBy, 'orderBy')).map((clause, index) => {
+        const at = place('orderBy', index);
+        if (!plain(clause))
+            invalid(at, 'expects an order clause');
+        known(clause, ['by', 'direction'], at);
+        const by = clause.by === 'count'
+            ? 'count'
+            : grouped.indexOf(JSON.stringify(keyPlan(typed, clause.by, place(at, 'by'), false)));
+        if (by === -1)
+            invalid(place(at, 'by'), 'orders by a key the query does not group by');
+        return { by, direction: direction(clause.direction, place(at, 'direction')) };
+    });
+    return { kind: 'groups', groupBy, orderBy };
+}
+export function planOf(input, facts) {
+    if (!plain(input))
+        invalid('query', 'expects a query object');
+    const grouped = input.groupBy !== undefined;
+    if (grouped && input.select !== undefined)
+        invalid('select', 'a grouped query selects nothing');
+    if (!grouped && input.select === undefined)
+        invalid('select', 'a Document query must select');
+    known(input, [...FILTER, 'orderBy', 'limit', 'after', 'total', grouped ? 'groupBy' : 'select'], '');
+    const limit = limitOf(input.limit);
+    const rooms = input.rooms === undefined ? null : names(input.rooms, 'rooms');
+    const { typed, ...root } = scope(facts, rooms, input, '');
+    const shape = grouped ? groupShape(typed, input) : documentShape(typed, input);
+    return {
+        key: queryKey(input),
+        rooms,
+        root,
+        folder: input.folder === undefined ? null : directory(input.folder, 'folder'),
+        paths: input.paths === undefined ? null : pathsOf(input.paths),
+        fileIds: input.fileIds === undefined ? null : fileIdsOf(input.fileIds),
+        hop: input.hop === undefined ? null : hopOf(facts, rooms, typed, input.hop),
+        backlinks: input.backlinks === undefined ? null : backlinksOf(facts, rooms, input.backlinks),
+        text: input.text === undefined ? null : phrase(input.text),
+        shape,
+        limit,
+        after: continuationOf(input.after, shape.orderBy.length + 1),
+        total: flag(input.total, 'total'),
+    };
+}
+function continuationOf(input, arity) {
+    if (input === undefined)
+        return null;
+    const values = typeof input === 'string' ? decodedCursor(input) : null;
+    if (values === null || (values.length !== 0 && values.length !== arity)) {
+        invalid('after', 'expects the next an earlier result of this query returned');
+    }
+    return { text: input, values: values.length === 0 ? null : values };
+}
+function limitOf(input) {
+    if (input === undefined)
+        return null;
+    if (!Number.isSafeInteger(input) || input < 0) {
+        invalid('limit', 'expects a nonnegative integer');
+    }
+    return input;
+}
+export function cursorOf(values) {
+    return JSON.stringify(values);
+}
+export function decodedCursor(text) {
+    try {
+        const decoded = JSON.parse(text);
+        return Array.isArray(decoded) ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function queryKey(query) {
+    return canonical(query);
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((name) => `${JSON.stringify(name)}:${canonical(value[name])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+export function identityOf(plan) {
+    return canonical(plan);
+}

package/dist/query/match.d.ts

@@ -0,0 +1,14 @@
+import type { Definition } from '../definition.js';
+import { type QueryPlan } from './language.js';
+import { type HeldValue } from './rows.js';
+export type Candidate = {
+    readonly path: string;
+    readonly type: string | null;
+    readonly fileId: string | null;
+    readonly fields: Readonly<Record<string, unknown>>;
+    readonly definition?: Pick<Definition, 'frontmatter'>;
+    readonly text: string | null;
+};
+export declare function heldAt(candidate: Candidate, field: string): readonly HeldValue[];
+export declare function matches(plan: QueryPlan, candidate: Candidate): boolean;
+//# sourceMappingURL=match.d.ts.map

package/dist/query/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/query/match.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAGL,KAAK,SAAS,EAIf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAE9D,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAyHF,wBAAgB,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE,CAEhF;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAgBtE"}