ultimabase 0.0.0-stage → 0.1.0

package/dist/recorder.js

@@ -0,0 +1,152 @@
+// The reads a caller's construction makes (D-154): `identify`, the plugins'
+// `caller` and `beforeFind` run inside `recording`, which keeps what each
+// read reached, so a write to one of them rebuilds the caller, and the
+// earliest time a plugin said the caller stops holding.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { modelOf } from './query-where.js';
+const recorder = new AsyncLocalStorage();
+/** Runs `run`, keeping each read the kernel makes until it settles. */
+export async function recording(run) {
+    const kept = { reads: [], expires: undefined };
+    const result = await recorder.run(kept, run);
+    const { reads, expires } = kept;
+    return {
+        result,
+        reads: [...reads],
+        ...(expires !== undefined && { expires: new Date(expires) }),
+    };
+}
+/** Keeps `at` when it is the earliest expiry, if a recording runs. */
+export function recordExpiry(at) {
+    const time = at.getTime();
+    if (Number.isNaN(time))
+        throw new TypeError('expires takes a valid date.');
+    const kept = recorder.getStore();
+    if (kept === undefined)
+        return;
+    if (kept.expires === undefined || time < kept.expires)
+        kept.expires = time;
+}
+/** The ids of `rows`, each once: included rows repeat a shared one. */
+const idsOf = (rows) => [
+    ...new Set(rows.flatMap((row) => {
+        const id = Reflect.get(Object(row), 'id');
+        return typeof id === 'string' ? [id] : [];
+    })),
+];
+/** Adds the fields `where` tests on its rows; false when it tests a text search. */
+function filtered(where, into) {
+    if (where === undefined)
+        return true;
+    for (const key of Object.keys(where)) {
+        if (key === '_search')
+            return false;
+        if (key !== 'AND' && key !== 'OR' && key !== 'NOT')
+            into.add(key);
+    }
+    const nested = [
+        ...(where.AND ?? []),
+        ...(where.OR ?? []),
+        ...(where.NOT ?? []),
+    ];
+    return nested.every((filter) => filtered(filter, into));
+}
+/** A sort's or a key's field on the row: the relation it goes through first. */
+const ownField = (key) => key.through?.[0]?.relation ?? key.field;
+/** The fields a read returned and the ones that chose its rows. */
+function dependsOn(read) {
+    const filters = new Set();
+    // A sort by relevance comes with a text search, which `filtered` refuses.
+    const known = filtered(read.where, filters) && filtered(read.cursor, filters);
+    for (const order of read.orderBy ?? [])
+        filters.add(ownField(order));
+    for (const key of read.distinct ?? [])
+        filters.add(ownField(key));
+    filters.delete('id');
+    return {
+        ...(read.fields && { fields: read.fields }),
+        ...(known && { filters: [...filters] }),
+    };
+}
+/** Keeps the relation `name` of `model` follows, and returns its target. */
+function follow(models, reads, model, name, reached = {}) {
+    const field = modelOf(models, model).fields.get(name);
+    if (field === undefined || field.kind === 'scalar')
+        return undefined;
+    reads.push({ model: field.target, ...reached, relation: `${model}.${name}` });
+    return field.target;
+}
+/** Keeps the `one` relations `steps` go through from `model`. */
+function through(models, reads, model, steps = []) {
+    let on = model;
+    for (const { relation, where } of steps) {
+        if (on === undefined)
+            return undefined;
+        on = follow(models, reads, on, relation, where && { where });
+    }
+    return on;
+}
+/** The relations `read` follows from `model`'s rows found as `rows`. */
+function followed(models, reads, model, read, rows) {
+    for (const order of read.orderBy ?? []) {
+        const on = through(models, reads, model, order.through);
+        if (on !== undefined && order.count !== undefined) {
+            follow(models, reads, on, order.field, { where: order.count });
+        }
+    }
+    for (const [name, where] of Object.entries(read.count ?? {})) {
+        follow(models, reads, model, name, { where });
+    }
+    for (const [name, nested] of Object.entries(read.include ?? {})) {
+        const found = rows.flatMap((row) => {
+            const value = Reflect.get(Object(row), name);
+            if (Array.isArray(value))
+                return value;
+            return value === null || value === undefined ? [] : [value];
+        });
+        const target = follow(models, reads, model, name, {
+            ...(nested.where && { where: nested.where }),
+            ids: idsOf(found),
+            ...dependsOn(nested),
+        });
+        if (target !== undefined)
+            followed(models, reads, target, nested, found);
+    }
+}
+/** Keeps a find, if a recording runs. */
+export function recordFind(models, read, rows) {
+    const reads = recorder.getStore()?.reads;
+    if (reads === undefined)
+        return;
+    const { model, where } = read;
+    reads.push({
+        model,
+        ...(where && { where }),
+        ids: idsOf(rows),
+        ...dependsOn(read),
+    });
+    followed(models, reads, model, read, rows);
+}
+/** Keeps a count or an aggregate, if a recording runs. */
+export function recordCount(models, read) {
+    const reads = recorder.getStore()?.reads;
+    if (reads === undefined)
+        return;
+    const { model, where } = read;
+    const filters = new Set();
+    const known = filtered(where, filters);
+    const by = 'by' in read ? (read.by ?? []) : [];
+    for (const key of by)
+        filters.add(ownField(key));
+    const aggregates = 'aggregates' in read ? read.aggregates : [];
+    const fields = aggregates.flatMap(({ field }) => field ?? []);
+    filters.delete('id');
+    reads.push({
+        model,
+        ...(where && { where }),
+        fields: [...new Set(fields)],
+        ...(known && { filters: [...filters] }),
+    });
+    for (const key of by)
+        through(models, reads, model, key.through);
+}

package/dist/relation-write.d.ts

@@ -0,0 +1,41 @@
+import type { Draft } from './write-data.ts';
+/** A `connectOrCreate`: the unique target it looks for, the row it creates. */
+export type OrCreate = {
+    readonly where: unknown;
+    readonly create: Draft;
+};
+/** A `many` relation's `update`: a unique target, and its data. */
+export type Updating = {
+    readonly where: unknown;
+    readonly data: Draft;
+};
+/** A `one` relation write. */
+export type OneWrite = {
+    readonly kind: 'connect';
+    readonly id: string;
+} | {
+    readonly kind: 'create';
+    readonly data: Draft;
+} | ({
+    readonly kind: 'connectOrCreate';
+} & OrCreate) | {
+    readonly kind: 'update';
+    readonly data: Draft;
+} | {
+    readonly kind: 'delete';
+} | {
+    readonly kind: 'disconnect';
+};
+export declare function oneWrite(value: unknown, path: string, model: string, creating: boolean): OneWrite;
+/** A `many` relation write, each operation's list. */
+export type ManyWrite = {
+    readonly connect: string[];
+    readonly disconnect: string[];
+    readonly create: Draft[];
+    readonly set: string[] | undefined;
+    readonly connectOrCreate: OrCreate[];
+    readonly update: Updating[];
+    readonly delete: unknown[];
+};
+export declare function manyWrite(value: unknown, path: string, model: string, creating: boolean): ManyWrite;
+//# sourceMappingURL=relation-write.d.ts.map

package/dist/relation-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-write.d.ts","sourceRoot":"","sources":["../src/relation-write.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAsE5C,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAA;CAAE,CAAA;AAU1E,mEAAmE;AACnE,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAA;AAgBxE,8BAA8B;AAC9B,MAAM,MAAM,QAAQ,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACjD,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAAG,QAAQ,CAAC,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAAA;AAElC,wBAAgB,QAAQ,CACvB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,GACf,QAAQ,CAkBV;AAED,sDAAsD;AACtD,MAAM,MAAM,SAAS,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,eAAe,EAAE,QAAQ,EAAE,CAAA;IACpC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAC1B,CAAA;AAED,wBAAgB,SAAS,CACxB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,GACf,SAAS,CAsBX"}

package/dist/relation-write.js

@@ -0,0 +1,112 @@
+// A relation write's operations (D-20, D-128, D-138), their shape checked:
+// `connect`, `connectOrCreate` and `create`, and in an update `delete`,
+// `disconnect`, `update` and, on a `many`, `set`.
+import { InvalidQuery } from './errors.js';
+import { clean, entries, isObject, unknownKey } from './query-where.js';
+/** `{ id }`, exactly. */
+function ref(value, path) {
+    const given = entries(value, path);
+    const [first] = given;
+    if (given.length !== 1 ||
+        first?.[0] !== 'id' ||
+        typeof first[1] !== 'string' ||
+        !clean(first[1])) {
+        throw new InvalidQuery(path, `${path} must be { id }.`);
+    }
+    return first[1];
+}
+/** The operations a relation write takes (D-128, D-138). */
+function allowed(kind, creating) {
+    if (creating)
+        return ['connect', 'connectOrCreate', 'create'];
+    const changing = kind === 'one' ? ['update'] : ['set', 'update'];
+    return [
+        'connect',
+        'connectOrCreate',
+        'create',
+        'delete',
+        'disconnect',
+        ...changing,
+    ].toSorted();
+}
+function operations(value, path, model, kind, creating) {
+    if (value === null) {
+        throw new InvalidQuery(path, `${path} cannot be null; use disconnect.`);
+    }
+    const given = new Map(entries(value, path));
+    for (const key of given.keys()) {
+        if (!allowed(kind, creating).includes(key))
+            throw unknownKey(`${path}.${key}`, model);
+    }
+    return given;
+}
+/** Data a nested `create` or `update` writes (D-128, D-138). */
+function made(value, path) {
+    if (!isObject(value)) {
+        throw new InvalidQuery(path, `${path} must be an object.`);
+    }
+    return value;
+}
+/** An object of exactly `keys`. */
+function exactly(value, path, keys) {
+    const given = new Map(entries(value, path));
+    if (given.size !== 2 || !keys.every((key) => given.has(key))) {
+        throw new InvalidQuery(path, `${path} must be { ${keys.join(', ')} }.`);
+    }
+    return given;
+}
+function orCreate(value, path) {
+    const given = exactly(value, path, ['where', 'create']);
+    return {
+        where: given.get('where'),
+        create: made(given.get('create'), `${path}.create`),
+    };
+}
+function updating(value, path) {
+    const given = exactly(value, path, ['where', 'data']);
+    return {
+        where: given.get('where'),
+        data: made(given.get('data'), `${path}.data`),
+    };
+}
+function list(value, path) {
+    if (!Array.isArray(value))
+        throw new InvalidQuery(path, `${path} must be a list.`);
+    return value;
+}
+export function oneWrite(value, path, model, creating) {
+    const given = operations(value, path, model, 'one', creating);
+    const [entry] = given;
+    if (entry === undefined || given.size !== 1) {
+        throw new InvalidQuery(path, `${path} takes one of ${allowed('one', creating).join(', ')}.`);
+    }
+    const [key, operand] = entry;
+    const at = `${path}.${key}`;
+    if (key === 'connect')
+        return { kind: key, id: ref(operand, at) };
+    if (key === 'create' || key === 'update') {
+        return { kind: key, data: made(operand, at) };
+    }
+    if (key === 'connectOrCreate')
+        return { kind: key, ...orCreate(operand, at) };
+    if (operand !== true)
+        throw new InvalidQuery(at, `${at} must be true.`);
+    return { kind: key === 'delete' ? 'delete' : 'disconnect' };
+}
+export function manyWrite(value, path, model, creating) {
+    const given = operations(value, path, model, 'many', creating);
+    const each = (key, read) => list(given.get(key) ?? [], `${path}.${key}`).map((item, index) => read(item, `${path}.${key}.${index}`));
+    if (given.has('set') && (given.has('connect') || given.has('disconnect'))) {
+        throw new InvalidQuery(`${path}.set`, `${path}.set cannot be used with connect or disconnect.`);
+    }
+    return {
+        // A row disconnected and connected again stays linked (D-101).
+        connect: each('connect', ref),
+        disconnect: each('disconnect', ref),
+        create: each('create', made),
+        set: given.has('set') ? each('set', ref) : undefined,
+        connectOrCreate: each('connectOrCreate', orCreate),
+        update: each('update', updating),
+        delete: each('delete', (item) => item),
+    };
+}

package/dist/relations.d.ts

@@ -0,0 +1,42 @@
+import type { Filter } from './adapter.ts';
+import type { FieldOptions } from './definition.ts';
+import type { Models, Scope } from './query-where.ts';
+import type { Caller } from './rules.ts';
+import type { FieldInfo, ModelInfo } from './schema.ts';
+type Many = Extract<FieldInfo, {
+    readonly kind: 'many';
+}>;
+/**
+ * Stops startup on a filter that names no `many` of the model, or on a view
+ * without one (D-151).
+ */
+export declare function checkRelations(model: ModelInfo): void;
+/**
+ * A view (D-151): `source`, the `many` its `from` names, under its own name
+ * and options. Stops startup unless `from` names a `many` of the model to the
+ * same target that is no view.
+ */
+export declare function viewField(view: {
+    readonly model: string;
+    readonly name: string;
+    readonly target: string;
+    readonly options: FieldOptions;
+}, from: string, source: FieldInfo | 'view' | undefined): FieldInfo;
+/** Whether `.with({ relations })` filters `field` of `model`. */
+export declare function isFiltered(model: ModelInfo, field: string): boolean;
+/** Fails on a `set` of a filtered relation, which would detach hidden rows. */
+export declare function refuseSet(model: ModelInfo, field: string, path: string): void;
+/** The relation filters of one query, run once each for its caller. */
+export declare class Relations {
+    private readonly filters;
+    private readonly models;
+    private readonly caller;
+    constructor(models: Models, caller: Caller);
+    /** The rows of `model.field` its filter keeps; `undefined` for all. */
+    filter(model: ModelInfo, field: Many): Filter | undefined;
+    private run;
+}
+/** The scope of trusted filters: no access rule, relation filters only. */
+export declare function trusted(relations: Relations): Scope;
+export {};
+//# sourceMappingURL=relations.d.ts.map

package/dist/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../src/relations.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAErD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvD,KAAK,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAQzD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAmBrD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACxB,IAAI,EAAE;IACL,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAC9B,EACD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,GACpC,SAAS,CAkBX;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAM7E;AAMD,uEAAuE;AACvE,qBAAa,SAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGrB;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAE/B,YAAY,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAGzC;IAED,uEAAuE;IACvE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAcxD;IAED,OAAO,CAAC,GAAG;CA0BX;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,KAAK,CAOnD"}

package/dist/relations.js

@@ -0,0 +1,119 @@
+import { InvalidQuery, Refused } from './errors.js';
+import { isObject, modelOf, normalizeWhere } from './query-where.js';
+import { filterOf, isReadFilter, readFilter } from './rules.js';
+function relationsOf(model) {
+    const { rules } = model.definition;
+    const relations = isObject(rules) ? rules['relations'] : undefined;
+    return isObject(relations) ? relations : {};
+}
+/**
+ * Stops startup on a filter that names no `many` of the model, or on a view
+ * without one (D-151).
+ */
+export function checkRelations(model) {
+    for (const [name, rule] of Object.entries(relationsOf(model))) {
+        const where = `${model.name}.with.relations.${name}`;
+        if (model.fields.get(name)?.kind !== 'many') {
+            throw new Refused(`${where}: ${name} is not a many relation.`);
+        }
+        if (!isObject(rule) || typeof rule['where'] !== 'function') {
+            throw new Refused(`${where} takes a where function.`);
+        }
+    }
+    for (const field of model.fields.values()) {
+        if (field.kind === 'many' && field.from !== undefined) {
+            if (!isFiltered(model, field.name)) {
+                throw new Refused(`${model.name}.${field.name} is a view; filter it in .with({ relations }).`);
+            }
+        }
+    }
+}
+/**
+ * A view (D-151): `source`, the `many` its `from` names, under its own name
+ * and options. Stops startup unless `from` names a `many` of the model to the
+ * same target that is no view.
+ */
+export function viewField(view, from, source) {
+    const { model, name, target, options } = view;
+    const at = `${model}.${name}`;
+    if (options['inverse'] !== undefined) {
+        throw new Refused(`${at} is a view and takes no inverse.`);
+    }
+    if (source === 'view') {
+        throw new Refused(`${at}: from '${from}' is a view; name its relation.`);
+    }
+    if (source?.kind !== 'many') {
+        throw new Refused(`${at}: from '${from}' is not a many relation.`);
+    }
+    if (source.target !== target) {
+        throw new Refused(`${at}: from '${from}' relates to ${source.target}, not ${target}.`);
+    }
+    return { ...source, name, from, options };
+}
+/** Whether `.with({ relations })` filters `field` of `model`. */
+export function isFiltered(model, field) {
+    return Object.hasOwn(relationsOf(model), field);
+}
+/** Fails on a `set` of a filtered relation, which would detach hidden rows. */
+export function refuseSet(model, field, path) {
+    if (!isFiltered(model, field))
+        return;
+    throw new InvalidQuery(path, `${model.name}.${field} is filtered; use connect and disconnect, not set.`);
+}
+/** No row passes: a filter that returns `false`. */
+const closed = { OR: [] };
+const pending = Symbol('pending');
+/** The relation filters of one query, run once each for its caller. */
+export class Relations {
+    filters = new Map();
+    models;
+    caller;
+    constructor(models, caller) {
+        this.models = models;
+        this.caller = caller;
+    }
+    /** The rows of `model.field` its filter keeps; `undefined` for all. */
+    filter(model, field) {
+        const key = `${model.name}.${field.name}`;
+        const known = this.filters.get(key);
+        if (known === pending) {
+            throw new TypeError(`${key}: its filter reads the relation itself.`);
+        }
+        if (this.filters.has(key))
+            return known;
+        const rule = relationsOf(model)[field.name];
+        this.filters.set(key, pending);
+        const filter = isObject(rule)
+            ? this.run(model, field, rule['where'])
+            : undefined;
+        this.filters.set(key, filter);
+        return filter;
+    }
+    run(model, field, rule) {
+        const path = `${model.name}.with.relations.${field.name}.where`;
+        if (typeof rule !== 'function')
+            throw new TypeError(`${path} is a function.`);
+        const result = Reflect.apply(rule, undefined, [
+            { caller: this.caller, where: readFilter },
+        ]);
+        if (result === true)
+            return undefined;
+        if (result === false)
+            return closed;
+        if (!isReadFilter(result)) {
+            throw new TypeError(`${path} returns where({ ... }) or a boolean.`);
+        }
+        const target = modelOf(this.models, field.target);
+        // Trusted server code, as a read rule's own filter (D-86).
+        return normalizeWhere(this.models, target, filterOf(result), path, trusted(this));
+    }
+}
+/** The scope of trusted filters: no access rule, relation filters only. */
+export function trusted(relations) {
+    return {
+        check: () => undefined,
+        ruled: () => false,
+        readable: () => undefined,
+        related: (model, field) => relations.filter(model, field),
+    };
+}

package/dist/rules.d.ts

@@ -0,0 +1,97 @@
+import type { RecordOf } from './record.ts';
+import type { modelFields } from './symbols.ts';
+export type Operation = 'read' | 'create' | 'update' | 'delete';
+/**
+ * The application declares its user model here, once; without it,
+ * `caller.user` is `{ id }` (D-24, D-62).
+ */
+export interface Register {
+}
+/** The user record a registry gives `caller.user`. */
+export type UserOf<R> = R extends {
+    readonly user: {
+        readonly [modelFields]: infer F;
+    };
+} ? RecordOf<F> : {
+    readonly id: string;
+};
+/**
+ * The keys plugins add to a user caller, each plugin declaring its own
+ * (D-121): `declare module 'ultimabase' { interface UserCallerKeys { ... } }`.
+ */
+export interface UserCallerKeys {
+}
+type Master = {
+    readonly kind: 'master';
+    readonly master: {
+        readonly source: 'code' | 'key';
+    };
+};
+/**
+ * Who code says sends an operation, as `as` and a plugin's `identify` give
+ * it: a user caller without the keys plugins add (D-121).
+ */
+export type Identity = {
+    readonly kind: 'anonymous';
+} | {
+    readonly kind: 'user';
+    readonly user: UserOf<Register>;
+} | Master;
+/** Who sends an operation, as rules, hooks and functions see it (D-19). */
+export type Caller = {
+    readonly kind: 'anonymous';
+} | ({
+    readonly kind: 'user';
+    readonly user: UserOf<Register>;
+} & UserCallerKeys) | Master;
+/** A Master caller; the kernel's code and transports only (D-19, D-49). */
+export declare function createMaster(source: 'code' | 'key'): Master;
+/** Whether a caller is a Master the kernel created. */
+export declare function isMaster(caller: object): caller is Master;
+/** Server code acting with every right; only the kernel creates it. */
+export declare const master: Master;
+/** A rule that reads only the caller and the operation fits any access key. */
+export type AnyRule = (facts: {
+    readonly caller: Caller;
+    readonly operation: Operation;
+}) => boolean;
+/** A rule that reads only the caller also fits a function's access (D-27). */
+export type CallerRule = (facts: {
+    readonly caller: Caller;
+}) => boolean;
+type Allow = {
+    readonly public: CallerRule;
+    readonly readOnly: AnyRule;
+    readonly private: CallerRule;
+};
+/** Open to everyone, open to reads, closed to everyone but Master (D-10). */
+export declare const allow: Allow;
+/** The read filter a read rule's `where` returns (D-10). */
+export declare function readFilter(where: unknown): object;
+/** Whether a rule's result is a read filter. */
+export declare function isReadFilter(value: unknown): value is object;
+/** The `where` a read filter holds. */
+export declare function filterOf(token: object): unknown;
+/** A rule already typed, such as a `const` holding `signedIn(...)`. */
+type Named = (facts: never) => unknown;
+type Both<U> = (U extends unknown ? (u: U) => void : never) extends (u: infer I) => void ? I : never;
+/** The rule combining named rules: it needs every rule's facts. */
+type Combined<Rules extends readonly Named[]> = (facts: Both<Parameters<Rules[number]>[0]>) => ReturnType<Rules[number]>;
+/**
+ * True when one of the rules is (D-10). The facts and the result come from
+ * where it is used, never from the rules, so each rule is typed by its place.
+ * In a read rule, the filters combine with `OR` (D-81): `true` from any rule
+ * lets every row through, `false` adds nothing.
+ */
+export declare function anyOf<Facts, R = boolean>(...rules: readonly NoInfer<(facts: Facts) => R>[]): (facts: Facts) => R;
+/** Outside any place, the facts are those every rule needs. */
+export declare function anyOf<const Rules extends readonly Named[]>(...rules: Rules): Combined<Rules>;
+/**
+ * True when every rule is (D-81), typed as `anyOf`. In a read rule, the
+ * filters combine with `AND`: `false` from any rule hides every row, `true`
+ * adds nothing.
+ */
+export declare function allOf<Facts, R = boolean>(...rules: readonly NoInfer<(facts: Facts) => R>[]): (facts: Facts) => R;
+export declare function allOf<const Rules extends readonly Named[]>(...rules: Rules): Combined<Rules>;
+export {};
+//# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE/D;;;GAGG;AACH,MAAM,WAAW,QAAQ;CAAG;AAE5B,sDAAsD;AACtD,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS;IACjC,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;KAAE,CAAA;CAClD,GACE,QAAQ,CAAC,CAAC,CAAC,GACX;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAA;AAE1B;;;GAGG;AACH,MAAM,WAAW,cAAc;CAAG;AAElC,KAAK,MAAM,GAAG;IACb,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAA;CACpD,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;CAAE,GAC1D,MAAM,CAAA;AAET,2EAA2E;AAC3E,MAAM,MAAM,MAAM,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B,CAAC;IACD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;CAC9B,GAAG,cAAc,CAAC,GACnB,MAAM,CAAA;AAIT,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAO3D;AAED,uDAAuD;AACvD,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,MAAM,CAEzD;AAED,uEAAuE;AACvE,eAAO,MAAM,MAAM,EAAE,MAA6B,CAAA;AAElD,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;CAC7B,KAAK,OAAO,CAAA;AAEb,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAA;AAExE,KAAK,KAAK,GAAG;IACZ,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAC5B,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,KAAK,EAAE,KAIlB,CAAA;AAIF,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIjD;AAED,gDAAgD;AAChD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE5D;AAED,uCAAuC;AACvC,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/C;AAsCD,uEAAuE;AACvE,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAA;AACtC,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CACnE,CAAC,EAAE,MAAM,CAAC,KACN,IAAI,GACN,CAAC,GACD,KAAK,CAAA;AACR,mEAAmE;AACnE,KAAK,QAAQ,CAAC,KAAK,SAAS,SAAS,KAAK,EAAE,IAAI,CAC/C,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KACrC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;AAE9B;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,EACvC,GAAG,KAAK,EAAE,SAAS,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,CAAC,EAAE,GAC/C,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,CAAA;AACtB,+DAA+D;AAC/D,wBAAgB,KAAK,CAAC,KAAK,CAAC,KAAK,SAAS,SAAS,KAAK,EAAE,EACzD,GAAG,KAAK,EAAE,KAAK,GACb,QAAQ,CAAC,KAAK,CAAC,CAAA;AAKlB;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,EACvC,GAAG,KAAK,EAAE,SAAS,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,CAAC,EAAE,GAC/C,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,CAAA;AACtB,wBAAgB,KAAK,CAAC,KAAK,CAAC,KAAK,SAAS,SAAS,KAAK,EAAE,EACzD,GAAG,KAAK,EAAE,KAAK,GACb,QAAQ,CAAC,KAAK,CAAC,CAAA"}

package/dist/rules.js

@@ -0,0 +1,71 @@
+const masters = new WeakSet();
+/** A Master caller; the kernel's code and transports only (D-19, D-49). */
+export function createMaster(source) {
+    const caller = Object.freeze({
+        kind: 'master',
+        master: Object.freeze({ source }),
+    });
+    masters.add(caller);
+    return caller;
+}
+/** Whether a caller is a Master the kernel created. */
+export function isMaster(caller) {
+    return masters.has(caller);
+}
+/** Server code acting with every right; only the kernel creates it. */
+export const master = createMaster('code');
+/** Open to everyone, open to reads, closed to everyone but Master (D-10). */
+export const allow = Object.freeze({
+    public: () => true,
+    readOnly: ({ operation }) => operation === 'read',
+    private: () => false,
+});
+const filters = new WeakMap();
+/** The read filter a read rule's `where` returns (D-10). */
+export function readFilter(where) {
+    const token = Object.freeze({});
+    filters.set(token, where);
+    return token;
+}
+/** Whether a rule's result is a read filter. */
+export function isReadFilter(value) {
+    return typeof value === 'object' && value !== null && filters.has(value);
+}
+/** The `where` a read filter holds. */
+export function filterOf(token) {
+    return filters.get(token);
+}
+// A rule returns a boolean, or a filter in a read rule (D-76, D-81).
+function collect(rules, facts, decisive) {
+    const found = [];
+    for (const rule of rules) {
+        const result = Reflect.apply(rule, undefined, [facts]);
+        if (result === decisive)
+            return { decided: true, filters: [] };
+        if (isReadFilter(result))
+            found.push(result);
+        else if (typeof result !== 'boolean') {
+            throw new TypeError('A rule returns a boolean or a read filter.');
+        }
+    }
+    return { decided: false, filters: found };
+}
+function combine(rules, decisive, operator) {
+    return (facts) => {
+        const { decided, filters: found } = collect(rules, facts, decisive);
+        if (decided)
+            return decisive;
+        const [first, ...others] = found;
+        if (first === undefined)
+            return !decisive;
+        if (others.length === 0)
+            return first;
+        return readFilter({ [operator]: found.map(filterOf) });
+    };
+}
+export function anyOf(...rules) {
+    return combine(rules, true, 'OR');
+}
+export function allOf(...rules) {
+    return combine(rules, false, 'AND');
+}