ultimabase 0.0.0-stage → 0.1.0

package/dist/query-json.js

@@ -0,0 +1,66 @@
+import { InvalidQuery } from './errors.js';
+import { clean, cleanText, entries, isJson, isObject, unknownKey, } from './query-values.js';
+const json = (operand, at) => {
+    if (isJson(operand))
+        return operand;
+    throw new InvalidQuery(at, `${at} must be a JSON value.`);
+};
+const operands = {
+    equals: json,
+    not: json,
+    ...Object.fromEntries(['lt', 'lte', 'gt', 'gte'].map((operator) => [
+        operator,
+        (operand, at) => {
+            if (typeof operand === 'string' && clean(operand))
+                return operand;
+            if (typeof operand === 'number' && Number.isFinite(operand)) {
+                return operand;
+            }
+            throw new InvalidQuery(at, `${at} must be a number or a string.`);
+        },
+    ])),
+    ...Object.fromEntries(['stringContains', 'stringStartsWith', 'stringEndsWith'].map((operator) => [
+        operator,
+        cleanText,
+    ])),
+    mode: (operand, at) => {
+        if (operand === 'insensitive')
+            return operand;
+        throw new InvalidQuery(at, `${at} must be 'insensitive'.`);
+    },
+    // A value is a list of one, as in Prisma.
+    arrayContains: (operand, at) => {
+        const value = json(operand, at);
+        if (!Array.isArray(value))
+            return [value];
+        const items = value;
+        return items;
+    },
+    arrayStartsWith: json,
+    arrayEndsWith: json,
+};
+/** Whether a json field's filter is a path filter, which names `path`. */
+export const isPathFilter = (value) => isObject(value) && value['path'] !== undefined;
+/**
+ * A path filter of `model`'s json field, `undefined` when it has no operator,
+ * as `mode` alone (D-140).
+ */
+export function jsonCondition(model, value, path) {
+    const condition = {};
+    for (const [operator, operand] of entries(value, path)) {
+        const at = `${path}.${operator}`;
+        if (operator === 'path') {
+            if (!Array.isArray(operand)) {
+                throw new InvalidQuery(at, `${at} must be a list of keys.`);
+            }
+            condition['path'] = operand.map((key, index) => cleanText(key, `${at}.${index}`));
+            continue;
+        }
+        const check = operands[operator];
+        if (check === undefined)
+            throw unknownKey(at, model);
+        condition[operator] = check(operand, at);
+    }
+    const tested = Object.keys(condition).filter((operator) => operator !== 'path' && operator !== 'mode');
+    return tested.length === 0 ? undefined : condition;
+}

package/dist/query-order.d.ts

@@ -0,0 +1,15 @@
+import type { Order, Sort } from './adapter.ts';
+import type { ModelInfo } from './schema.ts';
+import type { Models, Scope } from './query-where.ts';
+export declare function direction(value: unknown, path: string): 'asc' | 'desc';
+/**
+ * A sort key's value: a direction, or on an optional field `{ sort, nulls }`
+ * (D-149).
+ */
+export declare function sortOf(value: unknown, path: string, optional: boolean): Sort;
+/**
+ * A read's sort keys, ending with `id` so the order is total; `search` is
+ * the text of its where's `_search`.
+ */
+export declare function orderBy(models: Models, model: ModelInfo, value: unknown, path: string, scope: Scope | undefined, search?: string): Order[];
+//# sourceMappingURL=query-order.d.ts.map

package/dist/query-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-order.d.ts","sourceRoot":"","sources":["../src/query-order.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAQ,MAAM,cAAc,CAAA;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AASrD,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAKtE;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAuB5E;AAiFD;;;GAGG;AACH,wBAAgB,OAAO,CACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,MAAM,CAAC,EAAE,MAAM,GACb,KAAK,EAAE,CAeT"}

package/dist/query-order.js

@@ -0,0 +1,115 @@
+import { InvalidQuery } from './errors.js';
+import { searchedFields } from './query-search.js';
+import { entries, isObject, modelOf, systemFields, unknownKey, } from './query-where.js';
+export function direction(value, path) {
+    if (value !== 'asc' && value !== 'desc') {
+        throw new InvalidQuery(path, `${path} must be 'asc' or 'desc'.`);
+    }
+    return value;
+}
+/**
+ * A sort key's value: a direction, or on an optional field `{ sort, nulls }`
+ * (D-149).
+ */
+export function sortOf(value, path, optional) {
+    if (!isObject(value))
+        return { direction: direction(value, path) };
+    if (!optional) {
+        throw new InvalidQuery(path, `${path} is required: it sorts by 'asc' or 'desc'.`);
+    }
+    const { sort, nulls, ...rest } = value;
+    const [extra] = Object.keys(rest);
+    if (extra !== undefined) {
+        throw new InvalidQuery(`${path}.${extra}`, `${path} takes sort and nulls only.`);
+    }
+    const sorted = direction(sort, `${path}.sort`);
+    if (nulls === undefined)
+        return { direction: sorted };
+    if (nulls !== 'first' && nulls !== 'last') {
+        const at = `${path}.nulls`;
+        throw new InvalidQuery(at, `${at} must be 'first' or 'last'.`);
+    }
+    return { direction: sorted, nulls };
+}
+/** A scalar field that sorts: no json, no list, no plugin field (D-94). */
+function sortable(model, field, path) {
+    const known = model.fields.get(field);
+    if (known === undefined) {
+        if (!systemFields.includes(field))
+            throw unknownKey(path, model.name);
+        return;
+    }
+    if (known.kind !== 'scalar')
+        return;
+    if (known.type !== 'json' && !known.list && known.codec === undefined) {
+        return;
+    }
+    const kind = known.codec !== undefined
+        ? `a ${known.codec.plugin} field`
+        : known.type === 'json'
+            ? 'a json field'
+            : 'a list';
+    throw new InvalidQuery(path, `${path} is ${kind}, which cannot be sorted.`);
+}
+/** The sort keys of one object of `orderBy`, in its keys' order. */
+function keys(models, model, part, at, scope, through, search) {
+    const order = [];
+    const path = through.length === 0 ? {} : { through };
+    const searched = searchedFields(model.fields.values()).length > 0;
+    for (const [field, value] of entries(part, at)) {
+        const where = `${at}.${field}`;
+        if (field === '_relevance' && through.length === 0 && searched) {
+            if (search === undefined) {
+                throw new InvalidQuery(where, `${where} sorts by the _search at the top of the read's where, which has none.`);
+            }
+            order.push({
+                field,
+                direction: direction(value, where),
+                relevance: search,
+            });
+            continue;
+        }
+        sortable(model, field, where);
+        scope?.check(model, field, where, 'sorts');
+        const known = model.fields.get(field);
+        if (known === undefined || known.kind === 'scalar') {
+            const optional = known?.optional === true;
+            order.push({ field, ...sortOf(value, where, optional), ...path });
+            continue;
+        }
+        const target = modelOf(models, known.target);
+        if (known.kind === 'one') {
+            const readable = scope?.readable(target.name);
+            const step = { relation: field, ...(readable && { where: readable }) };
+            const next = [...through, step];
+            order.push(...keys(models, target, value, where, scope, next, search));
+            continue;
+        }
+        const [only, ...rest] = isObject(value) ? Object.entries(value) : [];
+        if (only?.[0] !== '_count' || rest.length > 0) {
+            throw new InvalidQuery(where, `${where} is a many relation, sorted by { _count: 'asc' | 'desc' }.`);
+        }
+        const sorted = direction(only[1], `${where}._count`);
+        const count = scope?.related(model, known) ?? {};
+        order.push({ field, direction: sorted, ...path, count });
+    }
+    return order;
+}
+/**
+ * A read's sort keys, ending with `id` so the order is total; `search` is
+ * the text of its where's `_search`.
+ */
+export function orderBy(models, model, value, path, scope, search) {
+    const parts = Array.isArray(value) ? value : [value];
+    const order = parts.flatMap((part, index) => {
+        const at = Array.isArray(value) ? `${path}.${index}` : path;
+        return keys(models, model, part, at, scope, [], search);
+    });
+    // The order is total, so a cursor and a page are exact.
+    const total = order.some((each) => each.field === 'id' &&
+        each.through === undefined &&
+        each.count === undefined);
+    if (!total)
+        order.push({ field: 'id', direction: 'asc' });
+    return order;
+}

package/dist/query-project.d.ts

@@ -0,0 +1,15 @@
+import type { Shape } from './query-args.ts';
+import type { ModelInfo } from './schema.ts';
+/** The fields of a row its field read rules hide (D-44). */
+export type Hidden = (model: ModelInfo, row: {
+    readonly [field: string]: unknown;
+}, fields: Iterable<string>) => ReadonlySet<string>;
+/** The values of each row's virtuals, as a read computed them (D-151). */
+export type Computed = WeakMap<object, Map<string, unknown>>;
+/** The virtuals of `shape` a field read rule hides, its own or a need's. */
+export declare function unseenVirtuals(shape: Shape, row: {
+    readonly [field: string]: unknown;
+}, hidden: Hidden | undefined): ReadonlySet<string>;
+/** A row as the query returns it, through the shape, without hidden fields. */
+export declare function project(row: unknown, shape: Shape, hidden?: Hidden, computed?: Computed): unknown;
+//# sourceMappingURL=query-project.d.ts.map

package/dist/query-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-project.d.ts","sourceRoot":"","sources":["../src/query-project.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAG5C,4DAA4D;AAC5D,MAAM,MAAM,MAAM,GAAG,CACpB,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE;IAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAC1C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,KACpB,WAAW,CAAC,MAAM,CAAC,CAAA;AAExB,0EAA0E;AAC1E,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAE5D,4EAA4E;AAC5E,wBAAgB,cAAc,CAC7B,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE;IAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAC1C,MAAM,EAAE,MAAM,GAAG,SAAS,GACxB,WAAW,CAAC,MAAM,CAAC,CASrB;AAED,+EAA+E;AAC/E,wBAAgB,OAAO,CACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,KAAK,EACZ,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAiCT"}

package/dist/query-project.js

@@ -0,0 +1,45 @@
+import { isObject } from './query-where.js';
+/** The virtuals of `shape` a field read rule hides, its own or a need's. */
+export function unseenVirtuals(shape, row, hidden) {
+    const reads = [...shape.virtuals.values()].map(({ info }) => info);
+    const names = reads.flatMap((info) => [info.name, ...info.needs]);
+    const unseen = hidden?.(shape.model, row, names);
+    return new Set(reads
+        .filter((info) => [info.name, ...info.needs].some((n) => unseen?.has(n)))
+        .map((info) => info.name));
+}
+/** A row as the query returns it, through the shape, without hidden fields. */
+export function project(row, shape, hidden, computed) {
+    if (Array.isArray(row)) {
+        return row.map((item) => project(item, shape, hidden, computed));
+    }
+    if (!isObject(row))
+        return null;
+    const names = [...shape.fields, ...shape.relations.keys(), ...shape.counts];
+    const unseen = hidden?.(shape.model, row, names);
+    const result = {};
+    for (const field of shape.fields) {
+        if (!unseen?.has(field))
+            result[field] = row[field] ?? null;
+    }
+    for (const [name, nested] of shape.relations) {
+        if (!unseen?.has(name)) {
+            result[name] = project(row[name], nested, hidden, computed);
+        }
+    }
+    const values = computed?.get(row);
+    const unseenVirtual = shape.virtuals.size > 0 ? unseenVirtuals(shape, row, hidden) : new Set();
+    for (const name of shape.virtuals.keys()) {
+        if (!unseenVirtual.has(name))
+            result[name] = values?.get(name) ?? null;
+    }
+    if (shape.counts.length > 0) {
+        const counts = isObject(row['_count'])
+            ? row['_count']
+            : {};
+        result['_count'] = Object.fromEntries(shape.counts
+            .filter((name) => !unseen?.has(name))
+            .map((name) => [name, counts[name] ?? 0]));
+    }
+    return result;
+}

package/dist/query-search.d.ts

@@ -0,0 +1,24 @@
+import type { SchemaField } from './adapter.ts';
+import type { fieldType } from './symbols.ts';
+/** The fields of `F` built with `search: true`. */
+type Searched<F> = {
+    [K in keyof F]: F[K] extends {
+        readonly [fieldType]: {
+            readonly options: {
+                readonly search: true;
+            };
+        };
+    } ? K : never;
+}[keyof F];
+/** A model with a searched field takes `_search` in its `where`. */
+export type SearchWhere<F> = [Searched<F>] extends [never] ? unknown : {
+    readonly _search?: string | undefined;
+};
+/** And `_relevance` at the top of its `orderBy`. */
+export type Relevance<F> = [Searched<F>] extends [never] ? unknown : {
+    readonly _relevance?: 'asc' | 'desc' | undefined;
+};
+/** The names of a model's searched fields, in declaration order. */
+export declare const searchedFields: (fields: Iterable<SchemaField>) => readonly string[];
+export {};
+//# sourceMappingURL=query-search.d.ts.map

package/dist/query-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-search.d.ts","sourceRoot":"","sources":["../src/query-search.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE7C,mDAAmD;AACnD,KAAK,QAAQ,CAAC,CAAC,IAAI;KACjB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;QAC5B,QAAQ,CAAC,CAAC,SAAS,CAAC,EAAE;YAAE,QAAQ,CAAC,OAAO,EAAE;gBAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;aAAE,CAAA;SAAE,CAAA;KACrE,GACE,CAAC,GACD,KAAK;CACR,CAAC,MAAM,CAAC,CAAC,CAAA;AAEV,oEAAoE;AACpE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACvD,OAAO,GACP;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAE5C,oDAAoD;AACpD,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACrD,OAAO,GACP;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAEvD,oEAAoE;AACpE,eAAO,MAAM,cAAc,WAClB,QAAQ,CAAC,WAAW,CAAC,KAC3B,SAAS,MAAM,EAGhB,CAAA"}

package/dist/query-search.js

@@ -0,0 +1,2 @@
+/** The names of a model's searched fields, in declaration order. */
+export const searchedFields = (fields) => [...fields].flatMap((field) => field.kind === 'scalar' && field.search === true ? [field.name] : []);

package/dist/query-values.d.ts

@@ -0,0 +1,28 @@
+import { InvalidQuery } from './errors.ts';
+import type { FieldInfo } from './schema.ts';
+export type Scalar = Extract<FieldInfo, {
+    readonly kind: 'scalar';
+}>;
+/** What a scalar value is checked against (D-139). */
+export type ScalarCheck = Pick<Scalar, 'type' | 'list' | 'integer' | 'values' | 'precision' | 'scale'>;
+/** An integer field's values (D-132). */
+export declare const isInteger: (value: unknown) => boolean;
+export declare function isObject(value: unknown): value is {
+    readonly [key: string]: unknown;
+};
+/** The entries of an argument object, without `undefined` (D-84). */
+export declare function entries(value: unknown, path: string): [string, unknown][];
+/** A string PostgreSQL stores as written: no NUL, no lone surrogate (D-94). */
+export declare const clean: (value: string) => boolean;
+export declare const cleanText: (value: unknown, at: string) => string;
+/** A date of years 1 to 9999 in UTC, which PostgreSQL reads back (D-94). */
+export declare const storedDate: (value: unknown) => value is Date;
+/** A real day of years 1 to 9999, written `'2026-07-31'` (D-150). */
+export declare function isDay(value: unknown): boolean;
+/** JSON data whose strings and keys are clean (D-94). */
+export declare function isJson(value: unknown): boolean;
+export declare function unknownKey(path: string, model: string): InvalidQuery;
+export declare const integerRange = "from -2,147,483,648 to 2,147,483,647";
+/** The message of a value that does not fit `field`, if it does not. */
+export declare const misfit: (value: unknown, field: ScalarCheck) => string | undefined;
+//# sourceMappingURL=query-values.d.ts.map

package/dist/query-values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-values.d.ts","sourceRoot":"","sources":["../src/query-values.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,MAAM,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAA;AAEpE,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,IAAI,CAC7B,MAAM,EACN,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAC9D,CAAA;AAED,yCAAyC;AACzC,eAAO,MAAM,SAAS,UAAW,OAAO,KAAG,OAGZ,CAAA;AAE/B,wBAAgB,QAAQ,CACvB,KAAK,EAAE,OAAO,GACZ,KAAK,IAAI;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAO9C;AAED,qEAAqE;AACrE,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAIzE;AAED,+EAA+E;AAC/E,eAAO,MAAM,KAAK,UAAW,MAAM,KAAG,OACQ,CAAA;AAE9C,eAAO,MAAM,SAAS,UAAW,OAAO,MAAM,MAAM,KAAG,MAGtD,CAAA;AAED,4EAA4E;AAC5E,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,IAGpD,CAAA;AAED,qEAAqE;AACrE,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAS7C;AAED,yDAAyD;AACzD,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAW9C;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAEpE;AAED,eAAO,MAAM,YAAY,yCAAyC,CAAA;AA0ClE,wEAAwE;AACxE,eAAO,MAAM,MAAM,UACX,OAAO,SACP,WAAW,KAChB,MAAM,GAAG,SAA8C,CAAA"}

package/dist/query-values.js

@@ -0,0 +1,91 @@
+import { decimalIssue } from './decimal.js';
+import { InvalidQuery } from './errors.js';
+/** An integer field's values (D-132). */
+export const isInteger = (value) => Number.isInteger(value) &&
+    Number(value) >= -2_147_483_648 &&
+    Number(value) <= 2_147_483_647;
+export function isObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Date));
+}
+/** The entries of an argument object, without `undefined` (D-84). */
+export function entries(value, path) {
+    if (!isObject(value))
+        throw new InvalidQuery(path, `${path} must be an object.`);
+    return Object.entries(value).filter(([, item]) => item !== undefined);
+}
+/** A string PostgreSQL stores as written: no NUL, no lone surrogate (D-94). */
+export const clean = (value) => value.isWellFormed() && !value.includes('\0');
+export const cleanText = (value, at) => {
+    if (typeof value === 'string' && clean(value))
+        return value;
+    throw new InvalidQuery(at, `${at} must be a clean string.`);
+};
+/** A date of years 1 to 9999 in UTC, which PostgreSQL reads back (D-94). */
+export const storedDate = (value) => {
+    const year = value instanceof Date ? value.getUTCFullYear() : Number.NaN;
+    return year >= 1 && year <= 9999;
+};
+/** A real day of years 1 to 9999, written `'2026-07-31'` (D-150). */
+export function isDay(value) {
+    const match = typeof value === 'string' && /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!match)
+        return false;
+    const [year = 0, month = 0, day = 0] = match.slice(1).map(Number);
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = month === 2 ? (leap ? 29 : 28) : [4, 6, 9, 11].includes(month) ? 30 : 31;
+    return year >= 1 && month >= 1 && month <= 12 && day >= 1 && day <= days;
+}
+/** JSON data whose strings and keys are clean (D-94). */
+export function isJson(value) {
+    if (value === null || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'string')
+        return clean(value);
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJson);
+    if (!isObject(value) || Object.getPrototypeOf(value) !== Object.prototype) {
+        return false;
+    }
+    return Object.entries(value).every(([key, item]) => clean(key) && isJson(item));
+}
+export function unknownKey(path, model) {
+    return new InvalidQuery(path, `Unknown key '${path}' on ${model}.`);
+}
+export const integerRange = 'from -2,147,483,648 to 2,147,483,647';
+/** Each scalar type's check, and its message when a value does not fit. */
+const misfits = {
+    string: (value) => {
+        if (typeof value !== 'string')
+            return 'Expected a string.';
+        return clean(value)
+            ? undefined
+            : 'Expected a string without a NUL or a lone surrogate.';
+    },
+    number: (value, field) => {
+        if (field.integer !== true) {
+            return typeof value === 'number' && Number.isFinite(value)
+                ? undefined
+                : 'Expected a finite number.';
+        }
+        return isInteger(value)
+            ? undefined
+            : `Expected a whole number ${integerRange}.`;
+    },
+    decimal: decimalIssue,
+    boolean: (value) => typeof value === 'boolean' ? undefined : 'Expected a boolean.',
+    dateTime: (value) => storedDate(value) ? undefined : 'Expected a Date of years 1 to 9999.',
+    date: (value) => isDay(value) ? undefined : "Expected a day written '2026-07-31'.",
+    json: (value) => isJson(value)
+        ? undefined
+        : 'Expected JSON data, its strings without a NUL or a lone surrogate.',
+    enum: (value, field) => typeof value === 'string' && (field.values ?? []).includes(value)
+        ? undefined
+        : `Expected one of ${(field.values ?? []).join(', ')}.`,
+};
+/** The message of a value that does not fit `field`, if it does not. */
+export const misfit = (value, field) => misfits[field.type](value, field);

package/dist/query-where.d.ts

@@ -0,0 +1,46 @@
+import type { Condition, Filter, ScalarType } from './adapter.ts';
+import type { FieldInfo, ModelInfo } from './schema.ts';
+export type { Scalar, ScalarCheck } from './query-values.ts';
+export { clean, entries, integerRange, isInteger, isJson, isObject, misfit, storedDate, unknownKey, } from './query-values.ts';
+export type Models = ReadonlyMap<string, ModelInfo>;
+/** The model, or the table, of `name`; another name is a kernel bug. */
+export declare function modelOf<T>(models: ReadonlyMap<string, T>, name: string): T;
+export declare const byId: (id: string) => Filter;
+export declare const byIds: (ids: readonly string[]) => Filter;
+/** What a query does with a field: a read rule refuses each (D-44, D-143, D-147). */
+export type Verb = 'filters' | 'sorts' | 'aggregates' | 'compares';
+/** What a caller other than Master may filter on and see (D-86). */
+export type Scope = {
+    /** Fails on a field with a read rule (D-44). */
+    readonly check: (model: ModelInfo, field: string, path: string, verb: Verb) => void;
+    /** Whether the caller runs a field read rule on it (D-44). */
+    readonly ruled: (model: ModelInfo, field: string) => boolean;
+    /** A model's read filter; `undefined` when every row passes. */
+    readonly readable: (model: string) => Filter | undefined;
+    /**
+     * The rows a `many` relation reads: its filter (D-151) and its target's
+     * read filter; `undefined` when every row passes.
+     */
+    readonly related: (model: ModelInfo, field: Extract<FieldInfo, {
+        readonly kind: 'many';
+    }>) => Filter | undefined;
+};
+export declare const systemFields: readonly string[];
+/**
+ * The operands of a value other than the field's, as an aggregate's in a
+ * `having` (D-149): their type, and their check, which stores each.
+ */
+export type Operand = {
+    readonly type: ScalarType;
+    readonly check: (item: unknown, at: string) => unknown;
+};
+/** A scalar field's condition, or with `operand` another value's of it. */
+export declare function fieldCondition(model: ModelInfo, name: string, value: unknown, path: string, operand?: Operand): Condition | undefined;
+/**
+ * A `where` of `model`, normalized; `path` names it in errors. With a
+ * `scope`, relation filters see readable rows only (D-86). Only a
+ * `beforeFind`'s, `stored`, filters a plugin field, in its stored form
+ * (D-122).
+ */
+export declare function normalizeWhere(models: Models, model: ModelInfo, where: unknown, path: string, scope?: Scope, stored?: boolean): Filter;
+//# sourceMappingURL=query-where.d.ts.map

package/dist/query-where.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-where.d.ts","sourceRoot":"","sources":["../src/query-where.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAGjE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAcvD,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,EACN,KAAK,EACL,OAAO,EACP,YAAY,EACZ,SAAS,EACT,MAAM,EACN,QAAQ,EACR,MAAM,EACN,UAAU,EACV,UAAU,GACV,MAAM,mBAAmB,CAAA;AAE1B,MAAM,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAEnD,wEAAwE;AACxE,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAI1E;AAED,eAAO,MAAM,IAAI,OAAQ,MAAM,KAAG,MAAkC,CAAA;AACpE,eAAO,MAAM,KAAK,QAAS,SAAS,MAAM,EAAE,KAAG,MAA+B,CAAA;AAE9E,qFAAqF;AACrF,MAAM,MAAM,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,CAAA;AAElE,oEAAoE;AACpE,MAAM,MAAM,KAAK,GAAG;IACnB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,CACf,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,IAAI,KACN,IAAI,CAAA;IACT,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAA;IAC5D,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IACxD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,CACjB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,KAChD,MAAM,GAAG,SAAS,CAAA;CACvB,CAAA;AAQD,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAuB,CAAA;AAkCjE;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAA;CACtD,CAAA;AAqDD,2EAA2E;AAC3E,wBAAgB,cAAc,CAC7B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,GACf,SAAS,GAAG,SAAS,CAIvB;AAuED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,KAAK,EACb,MAAM,UAAQ,GACZ,MAAM,CAmDR"}