@agentshouse/mdruntime 0.1.0-alpha.9 → 0.1.0-c3903a68dcbbf

package/dist/query.js

@@ -1,18 +1,423 @@
-export function rawQuery(rooms) {
+import { normalize } from './paths.js';
+export class QueryError extends Error {
+    constructor(code, at, problem) {
+        super(`${code} at ${at}: ${problem}`);
+    }
+}
+const RANGE = ['$gt', '$gte', '$lt', '$lte'];
+const SINGLE = ['$eq', '$ne', '$in', '$nin', '$all', '$size', '$exists'];
+const FILTER = ['rooms', 'types', 'where', 'pathPrefix', 'hop', 'backlinks'];
+const RELATED = ['types', 'where', 'pathPrefix', 'field'];
+const PARTS = ['fields', 'sections', 'preamble', 'markdown', 'backlinks', 'change'];
+const ORDER = ['by', 'direction', 'nulls', 'stringSort', 'locale', 'localeOptions'];
+const CALENDAR_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+export function invalid(at, problem) {
+    throw new QueryError('invalid-query', at, problem);
+}
+function place(at, name) {
+    return at === '' ? name : `${at}.${name}`;
+}
+export function plain(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+export function known(value, allowed, at) {
+    for (const name of Object.keys(value)) {
+        if (!allowed.includes(name))
+            invalid(place(at, name), 'unknown part');
+    }
+}
+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, `${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 directory(input, at) {
+    if (typeof input !== 'string' || normalize(input) !== input) {
+        invalid(at, 'expects a normalized directory');
+    }
+    return input;
+}
+function calendarDate(value) {
+    const match = CALENDAR_DATE.exec(value);
+    if (match === null)
+        return false;
+    const [year, month, day] = match.slice(1).map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return (date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day);
+}
+function fits(spec, value) {
+    const item = spec.kind === 'list' ? spec.of : spec;
+    if (item.kind === 'number')
+        return typeof value === 'number';
+    if (typeof value !== 'string')
+        return false;
+    if (item.kind === 'enum')
+        return item.values.includes(value);
+    if (item.kind === 'date')
+        return calendarDate(value);
+    if (item.kind === 'reference')
+        return value !== '' && normalize(value) === value;
+    return true;
+}
+function reference(spec) {
+    return spec.kind === 'reference' || (spec.kind === 'list' && spec.of.kind === 'reference');
+}
+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}`);
+    }
+    return {
+        untyped: types === null || types.includes('any') || !available,
+        types: types === null ? declared : declared.filter((type) => types.includes(type.name)),
+    };
+}
+function specs(typed, field, at) {
+    const declared = typed.types.flatMap((type) => Object.hasOwn(type.fields, field) ? [type.fields[field]] : []);
+    if (declared.length === 0 && !typed.untyped) {
+        throw new QueryError('unknown-field', at, `no MD Type it reads declares ${field}`);
+    }
+    return declared;
+}
+function kind(declared, checked, at) {
+    if (checked === null || declared.length === 0 || declared.some((spec) => fits(spec, checked))) {
+        return;
+    }
+    throw new QueryError('wrong-kind', at, `${JSON.stringify(checked)} is not of its field's kind`);
+}
+function listed(declared, list) {
+    return declared.length > 0 && declared.every((spec) => (spec.kind === 'list') === list);
+}
+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 (listed(declared, true))
+            invalid(at, 'a range on a list');
+        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');
+    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, `${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 (listed(declared, false))
+            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 (listed(declared, false))
+            invalid(where, 'the field is not a list');
+        return { op: 'size', size: 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, `${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 {
-        roomVersions: Object.fromEntries(rooms.map((room)=>[
-                room.room,
-                room.roomVersion
-            ])),
-        groups: null,
-        documents: rooms.flatMap((room)=>Object.entries(room.documents).filter(([path])=>path.endsWith('.md')).map(([path, document])=>({
-                    ...structuredClone(document),
-                    type: document.type ?? 'any',
-                    room: room.room,
-                    path,
-                    backlinks: []
-                })))
+        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')),
     };
 }
-
-//# sourceMappingURL=query.js.map
+function referenceField(typed, field, at) {
+    if (typeof field !== 'string')
+        invalid(at, 'expects a field name');
+    const declared = specs(typed, field, at);
+    if (declared.length > 0 && !declared.some(reference))
+        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 = referenceField(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 : referenceField(typed, input.field, 'backlinks.field');
+    return { types, where, pathPrefix, field };
+}
+function keyPlan(typed, input, at, path) {
+    if (input === 'room' || input === 'type' || (path && input === 'path'))
+        return { of: input };
+    if (plain(input) && typeof input.field === 'string' && Object.keys(input).length === 1) {
+        specs(typed, input.field, place(at, 'field'));
+        return { of: 'field', field: input.field };
+    }
+    return invalid(at, path ? 'expects room, path, type or a field' : 'expects room, type 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 (typeof name !== 'string')
+            invalid(`${at}[${index}]`, 'expects a name');
+        if (fields)
+            specs(typed, name, `${at}[${index}]`);
+    });
+    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 = `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,
+            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'),
+        orderBy,
+    };
+}
+function groupShape(typed, input) {
+    const groupBy = list(input.groupBy, 'groupBy').map((key, index) => keyPlan(typed, key, `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 = `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', 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, '');
+    return {
+        rooms,
+        root,
+        hop: input.hop === undefined ? null : hopOf(facts, rooms, typed, input.hop),
+        backlinks: input.backlinks === undefined ? null : backlinksOf(facts, rooms, input.backlinks),
+        shape: grouped ? groupShape(typed, input) : documentShape(typed, input),
+        limit,
+    };
+}
+export function limitOf(input) {
+    if (input === undefined)
+        return null;
+    if (!Number.isSafeInteger(input) || input < 0) {
+        invalid('limit', 'expects a nonnegative integer');
+    }
+    return input;
+}
+export function filterOf(input, facts) {
+    if (!plain(input))
+        invalid('documents', 'expects a filter object');
+    known(input, FILTER, '');
+    return planOf({ ...input, select: {} }, facts);
+}
+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/read-side.d.ts

@@ -0,0 +1,14 @@
+import type { ChangeSet } from './change-set.js';
+import { type KeyedResult, type QueryChange } from './observation.js';
+import type { Plan, QueryResult } from './query.js';
+import type { SearchedDocument } from './search.js';
+export type ReadSide = {
+    apply(set: ChangeSet): void;
+    query(plan: Plan): Promise<QueryResult>;
+    watch(plan: Plan, identity: string, deliver: (message: KeyedResult | QueryChange) => void): () => void;
+    documents(): readonly SearchedDocument[];
+    document(room: string, path: string): SearchedDocument | null;
+    close(): void;
+};
+export declare function createReadSide(): ReadSide;
+//# sourceMappingURL=read-side.d.ts.map

package/dist/read-side.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-side.d.ts","sourceRoot":"","sources":["../src/read-side.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAU,KAAK,WAAW,EAAE,KAAK,WAAW,EAAe,MAAM,kBAAkB,CAAC;AAC3F,OAAO,KAAK,EAOV,IAAI,EAGJ,WAAW,EAIZ,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAqDpD,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACxC,KAAK,CACH,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,KAAK,IAAI,GACpD,MAAM,IAAI,CAAC;IACd,SAAS,IAAI,SAAS,gBAAgB,EAAE,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC9D,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAySF,wBAAgB,cAAc,IAAI,QAAQ,CA4HzC"}