@drhomet/mithaq 0.0.0-stage → 0.2.0

package/dist/base/decimal.d.ts

@@ -0,0 +1,9 @@
+/** Fixed-point text, held to what a Postgres `numeric` holds: 131072 digits before the point and 16383 after. */
+export declare const isDecimal: (value: unknown) => value is string;
+/** How many digits a decimal holds before and after its point, as `numeric(precision, scale)` counts them. */
+export declare const decimalDigits: (value: string) => {
+    whole: number;
+    fraction: number;
+};
+/** -1, 0 or 1 as `left` is below, equal to or above `right`, on two values `isDecimal` accepts. */
+export declare const compareDecimals: (left: string, right: string) => number;

package/dist/base/decimal.js

@@ -0,0 +1,16 @@
+// Read without passing a digit through a JS number, which would round a money
+// value past 15 significant digits. Imports nothing, so a browser can load it.
+/** Fixed-point text, held to what a Postgres `numeric` holds: 131072 digits before the point and 16383 after. */
+export const isDecimal = (value) => typeof value === 'string' && /^[+-]?\d{1,131072}(?:\.\d{1,16383})?$/.test(value);
+/** How many digits a decimal holds before and after its point, as `numeric(precision, scale)` counts them. */
+export const decimalDigits = (value) => {
+    const [whole = '', fraction = ''] = value.replace(/^[+-]/, '').split('.');
+    return { whole: whole.replace(/^0+/, '').length, fraction: fraction.length };
+};
+/** -1, 0 or 1 as `left` is below, equal to or above `right`, on two values `isDecimal` accepts. */
+export const compareDecimals = (left, right) => {
+    const [a, b] = [left, right].map((one) => /^([+-]?\d+)(?:\.(\d+))?$/.exec(one));
+    const scale = Math.max(a[2]?.length ?? 0, b[2]?.length ?? 0);
+    const [first, second] = [a, b].map((one) => BigInt(one[1] + (one[2] ?? '').padEnd(scale, '0')));
+    return first < second ? -1 : first > second ? 1 : 0;
+};

package/dist/base/fields.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The `id` field alone, for a kayan that keeps no timestamps:
+ * `fields: { ...defaultIdField, title }`.
+ */
+export declare const defaultIdField: {
+    /** A uuid Postgres fills when a create leaves it out; a client may send its own, so rows can be made offline. */
+    readonly id: {
+        readonly kind: 'uuid';
+        readonly label: {
+            readonly en: 'ID';
+            readonly ar: 'المعرف';
+        };
+    };
+};
+/** The `updatedAt` and `createdAt` fields the runner writes, spread beside an id. */
+export declare const defaultTimestampFields: {
+    /** Written by the runner on every write that changes a row, and drawn disabled in the form. */
+    readonly updatedAt: {
+        readonly kind: 'datetime';
+        readonly label: {
+            readonly en: 'Updated at';
+            readonly ar: 'تاريخ التعديل';
+        };
+        readonly rules: {
+            readonly required: true;
+            readonly defaultNow: true;
+            readonly nowOnUpdate: true;
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+    /** Written by the runner on insert, and indexed because a read that names no sort orders by it. */
+    readonly createdAt: {
+        readonly kind: 'datetime';
+        readonly label: {
+            readonly en: 'Created at';
+            readonly ar: 'تاريخ الإنشاء';
+        };
+        readonly rules: {
+            readonly required: true;
+            readonly defaultNow: true;
+            readonly index: true;
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+};
+/**
+ * The `id`, `updatedAt` and `createdAt` fields a kayan spreads into its own
+ * `fields`: `fields: { ...defaultFields, title }`. Spread order is column order, except that
+ * a new table puts the two timestamps after every other column.
+ */
+export declare const defaultFields: {
+    /** A uuid Postgres fills when a create leaves it out; a client may send its own, so rows can be made offline. */
+    readonly id: {
+        readonly kind: 'uuid';
+        readonly label: {
+            readonly en: 'ID';
+            readonly ar: 'المعرف';
+        };
+    };
+    /** Written by the runner on every write that changes a row, and drawn disabled in the form. */
+    readonly updatedAt: {
+        readonly kind: 'datetime';
+        readonly label: {
+            readonly en: 'Updated at';
+            readonly ar: 'تاريخ التعديل';
+        };
+        readonly rules: {
+            readonly required: true;
+            readonly defaultNow: true;
+            readonly nowOnUpdate: true;
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+    /** Written by the runner on insert, and indexed because a read that names no sort orders by it. */
+    readonly createdAt: {
+        readonly kind: 'datetime';
+        readonly label: {
+            readonly en: 'Created at';
+            readonly ar: 'تاريخ الإنشاء';
+        };
+        readonly rules: {
+            readonly required: true;
+            readonly defaultNow: true;
+            readonly index: true;
+            readonly providedBy: {
+                readonly create: 'application';
+                readonly update: 'application';
+            };
+        };
+    };
+};
+export declare const globalTypeLabel: {
+    readonly en: 'Global type';
+    readonly ar: 'النوع العام';
+};
+/**
+ * The field a global spreads into its own `fields`:
+ * `fields: { ...defaultFields, ...defaultGlobalFields, siteTitle }`.
+ */
+export declare const defaultGlobalFields: {
+    readonly globalType: {
+        readonly kind: 'text';
+        readonly label: {
+            readonly en: 'Global type';
+            readonly ar: 'النوع العام';
+        };
+        readonly rules: {
+            readonly required: true;
+            readonly unique: true;
+        };
+        readonly access: {
+            readonly update: () => false;
+        };
+    };
+};

package/dist/base/fields.js

@@ -0,0 +1,52 @@
+/**
+ * The `id` field alone, for a kayan that keeps no timestamps:
+ * `fields: { ...defaultIdField, title }`.
+ */
+export const defaultIdField = {
+    /** A uuid Postgres fills when a create leaves it out; a client may send its own, so rows can be made offline. */
+    id: { kind: 'uuid', label: { en: 'ID', ar: 'المعرف' } },
+};
+/** The `updatedAt` and `createdAt` fields the runner writes, spread beside an id. */
+export const defaultTimestampFields = {
+    /** Written by the runner on every write that changes a row, and drawn disabled in the form. */
+    updatedAt: {
+        kind: 'datetime',
+        label: { en: 'Updated at', ar: 'تاريخ التعديل' },
+        rules: {
+            required: true,
+            defaultNow: true,
+            nowOnUpdate: true,
+            providedBy: { create: 'application', update: 'application' },
+        },
+    },
+    /** Written by the runner on insert, and indexed because a read that names no sort orders by it. */
+    createdAt: {
+        kind: 'datetime',
+        label: { en: 'Created at', ar: 'تاريخ الإنشاء' },
+        rules: {
+            required: true,
+            defaultNow: true,
+            index: true,
+            providedBy: { create: 'application', update: 'application' },
+        },
+    },
+};
+/**
+ * The `id`, `updatedAt` and `createdAt` fields a kayan spreads into its own
+ * `fields`: `fields: { ...defaultFields, title }`. Spread order is column order, except that
+ * a new table puts the two timestamps after every other column.
+ */
+export const defaultFields = { ...defaultIdField, ...defaultTimestampFields };
+export const globalTypeLabel = { en: 'Global type', ar: 'النوع العام' };
+/**
+ * The field a global spreads into its own `fields`:
+ * `fields: { ...defaultFields, ...defaultGlobalFields, siteTitle }`.
+ */
+export const defaultGlobalFields = {
+    globalType: {
+        kind: 'text',
+        label: globalTypeLabel,
+        rules: { required: true, unique: true },
+        access: { update: () => false },
+    },
+};

package/dist/base/index.d.ts

@@ -0,0 +1,47 @@
+/** The rukn every project lays down first: the shipped kinds and rules. */
+export declare const base: {
+    readonly name: "base";
+    readonly kinds: {
+        text: import("./kinds.ts").Kind<string, "defaultValue" | "index" | "localized" | "lowercase" | "maxLength" | "minLength" | "pattern" | "providedBy" | "required" | "trim" | "unique" | "uppercase">;
+        email: import("./kinds.ts").Kind<string, "defaultValue" | "index" | "localized" | "lowercase" | "maxLength" | "minLength" | "pattern" | "providedBy" | "required" | "trim" | "unique" | "uppercase">;
+        number: import("./kinds.ts").Kind<number, "defaultValue" | "index" | "localized" | "max" | "min" | "providedBy" | "required" | "unique">;
+        integer: import("./kinds.ts").Kind<number, "defaultValue" | "index" | "localized" | "max" | "min" | "providedBy" | "required" | "unique">;
+        decimal: import("./kinds.ts").Kind<string, "defaultValue" | "index" | "localized" | "max" | "min" | "precision" | "providedBy" | "required" | "scale" | "unique">;
+        checkbox: import("./kinds.ts").Kind<boolean, "defaultValue" | "index" | "providedBy" | "required">;
+        datetime: import("./kinds.ts").Kind<Date, "defaultNow" | "defaultValue" | "index" | "localized" | "nowOnUpdate" | "providedBy" | "required">;
+        date: import("./kinds.ts").Kind<string, "defaultValue" | "index" | "localized" | "max" | "min" | "providedBy" | "required">;
+        textArray: import("./kinds.ts").Kind<string[], "defaultValue" | "maxRows" | "minRows" | "providedBy" | "required">;
+        uuid: import("./kinds.ts").Kind<string, "defaultValue" | "index" | "providedBy" | "required" | "unique">;
+        relationship: import("./kinds.ts").Kind<string | number, "defaultValue" | "index" | "onDelete" | "providedBy" | "required" | "unique"> & {
+            pointsAtRow: true;
+        };
+        json: import("./kinds.ts").Kind<import("./kinds.ts").Json, "defaultValue" | "providedBy" | "required">;
+        join: import("./kinds.ts").Kind<unknown[], "providedBy" | "required">;
+    };
+    readonly rules: {
+        required: import("./rules.ts").Rule<boolean>;
+        unique: import("./rules.ts").Rule<boolean>;
+        index: import("./rules.ts").Rule<boolean>;
+        defaultValue: import("./rules.ts").Rule<Date | readonly unknown[] | import("../index.ts").Ref | import("./kinds.ts").Json>;
+        defaultNow: import("./rules.ts").Rule<boolean>;
+        nowOnUpdate: import("./rules.ts").Rule<boolean>;
+        providedBy: import("./rules.ts").Rule<Readonly<{
+            create?: import("./rules.ts").Provider;
+            update?: import("./rules.ts").Provider;
+        }>>;
+        localized: import("./rules.ts").Rule<boolean>;
+        maxLength: import("./rules.ts").Rule<number>;
+        precision: import("./rules.ts").Rule<number>;
+        scale: import("./rules.ts").Rule<number>;
+        minLength: import("./rules.ts").Rule<number>;
+        pattern: import("./rules.ts").Rule<RegExp>;
+        min: import("./rules.ts").Rule<string | number>;
+        max: import("./rules.ts").Rule<string | number>;
+        minRows: import("./rules.ts").Rule<number>;
+        maxRows: import("./rules.ts").Rule<number>;
+        uppercase: import("./rules.ts").Rule<boolean>;
+        lowercase: import("./rules.ts").Rule<boolean>;
+        trim: import("./rules.ts").Rule<boolean>;
+        onDelete: import("./rules.ts").Rule<import("./kinds.ts").OnDelete>;
+    };
+};

package/dist/base/index.js

@@ -0,0 +1,5 @@
+import { defineRukn } from '../mithaq/rukn.js';
+import { defaultKinds } from './kinds.js';
+import { defaultRules } from './rules.js';
+/** The rukn every project lays down first: the shipped kinds and rules. */
+export const base = defineRukn({ name: 'base', kinds: defaultKinds, rules: defaultRules });

package/dist/base/json-schema.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedField } from '../mithaq/types.ts';
+/**
+ * Whether a value holds to a `json` field's `jsonSchema`. A schema that names draft-07, as Payload
+ * writes one it fetched, is read as draft-07; any other as 2020-12. Throws, naming the field, where
+ * the schema cannot be compiled, so a build refuses it rather than checking less than it says.
+ */
+export declare const jsonSchemaCheck: (field: ResolvedField) => ((value: unknown) => boolean);

package/dist/base/json-schema.js

@@ -0,0 +1,35 @@
+// Ajv, not zod's `fromJSONSchema`, which Payload uses: the converter passes over `required` without
+// `properties`, and every keyword of a schema that names no `type`, so a value it waves through would
+// break the schema the project wrote. Ajv holds a value to the whole schema, and refuses one it
+// cannot hold a value to (an unknown keyword or format, a reference it cannot resolve) when it compiles.
+import { Ajv } from 'ajv';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+// One compile per schema, though a schema target shapes each field more than once.
+const compiled = new WeakMap();
+/**
+ * Whether a value holds to a `json` field's `jsonSchema`. A schema that names draft-07, as Payload
+ * writes one it fetched, is read as draft-07; any other as 2020-12. Throws, naming the field, where
+ * the schema cannot be compiled, so a build refuses it rather than checking less than it says.
+ */
+export const jsonSchemaCheck = (field) => {
+    const jsonSchema = field.jsonSchema;
+    const held = compiled.get(jsonSchema);
+    if (held)
+        return held;
+    const { schema } = jsonSchema;
+    // `strictTypes` and `strictTuples` only ask a schema to say more than JSON Schema requires.
+    const options = { strictTypes: false, strictTuples: false };
+    const ajv = typeof schema === 'object' && /^http:\/\/json-schema\.org\/draft-07\/schema#?$/.test(String(schema.$schema)) ? new Ajv(options) : new Ajv2020(options);
+    addFormats.default(ajv);
+    let validate;
+    try {
+        validate = ajv.compile(schema);
+    }
+    catch (thrown) {
+        throw new Error(`Kayan "${field.kayan}" field "${field.name}" jsonSchema cannot be checked: ${thrown.message}.`, { cause: thrown });
+    }
+    const check = (value) => validate(value) === true;
+    compiled.set(jsonSchema, check);
+    return check;
+};

package/dist/base/kinds.d.ts

@@ -0,0 +1,75 @@
+import type { Localized } from '../mithaq/types.ts';
+import type { Operator } from '../mithaq/where.ts';
+/** A kind of field value: its label, its runtime check, the rules it accepts and what each target makes of it. */
+export type Kind<Value = unknown, RuleName extends string = string> = {
+    /** The name of the kind, shown wherever a kind is named to a person. */
+    label: Localized;
+    /** What a person reads where a value is not of this kind. */
+    message: Localized;
+    /** Compile-time value carried by fields of this kind; never read at runtime. */
+    value: Value;
+    /** Runtime check for dynamic field/default input where TypeScript is absent. */
+    accepts(value: unknown): value is Value;
+    /** Makes the write's moment, for a field that declares `defaultNow` or `nowOnUpdate`. */
+    now?: () => Value;
+    /** Rules fields of this kind may bind. Target order still decides application order. */
+    rules: readonly RuleName[];
+    /** What this kind is in each target, keyed by the target's `type`: a column, a shape, a control and a cell. */
+    targets?: Readonly<Record<string, unknown>>;
+    /** The `Where` operators a field of this kind takes; any other is refused. */
+    operators?: readonly Operator[];
+    /** `false` where a value of this kind cannot order a page. */
+    sortable?: false;
+    /** `true` where a value of this kind is the id of another row, named by `relationTo`. */
+    pointsAtRow?: true;
+    /** What a field of this kind does when the row it points at is deleted, unless it names its own `onDelete`. */
+    onDelete?: OnDelete;
+};
+/** Defines a project kind from its runtime check. */
+export declare const kind: <Value>(accepts: (value: unknown) => value is Value) => <const RuleName extends string, const Targets extends Readonly<Record<string, unknown>> = {}, const PointsAtRow extends true | undefined = undefined>(definition: Omit<Kind<Value, RuleName>, 'accepts' | 'value' | 'targets' | 'pointsAtRow'> & {
+    targets?: Targets;
+    pointsAtRow?: PointsAtRow;
+}) => Kind<Value, RuleName> & ({} extends Targets ? unknown : {
+    targets: Targets;
+}) & (PointsAtRow extends true ? {
+    pointsAtRow: true;
+} : unknown);
+/** A value `JSON.parse` could hand back. */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * The most UTF-8 bytes of JSON text a json field holds, which a field names as its `maxBytes`, so one write
+ * never stores a value every read of the row then carries.
+ */
+export declare const defaultJsonMaxBytes = 1000000;
+/** How deep a json value nests: past it every reader that walks it, this check first, would run out of stack. */
+export declare const jsonDepth = 64;
+/** Text Postgres holds: no NUL, which no `text` or `jsonb` takes, and no half of a surrogate pair. */
+export declare const isStorableText: (text: string) => boolean;
+/**
+ * Plain JSON, nested at most `jsonDepth` deep: no `undefined`, no number that is
+ * not finite, no `Date`, class instance or function, no cycle, and no string or key
+ * Postgres cannot store. A store would otherwise drop, rewrite or refuse it on the
+ * way in, and read back something else.
+ */
+export declare const isJson: (value: unknown, open?: object[]) => value is Json;
+/** What the database does to this row when the row it points at is deleted. */
+export type OnDelete = 'cascade' | 'restrict' | 'set null';
+export declare const defaultKinds: {
+    text: Kind<string, "defaultValue" | "index" | "localized" | "lowercase" | "maxLength" | "minLength" | "pattern" | "providedBy" | "required" | "trim" | "unique" | "uppercase">;
+    email: Kind<string, "defaultValue" | "index" | "localized" | "lowercase" | "maxLength" | "minLength" | "pattern" | "providedBy" | "required" | "trim" | "unique" | "uppercase">;
+    number: Kind<number, "defaultValue" | "index" | "localized" | "max" | "min" | "providedBy" | "required" | "unique">;
+    integer: Kind<number, "defaultValue" | "index" | "localized" | "max" | "min" | "providedBy" | "required" | "unique">;
+    decimal: Kind<string, "defaultValue" | "index" | "localized" | "max" | "min" | "precision" | "providedBy" | "required" | "scale" | "unique">;
+    checkbox: Kind<boolean, "defaultValue" | "index" | "providedBy" | "required">;
+    datetime: Kind<Date, "defaultNow" | "defaultValue" | "index" | "localized" | "nowOnUpdate" | "providedBy" | "required">;
+    date: Kind<string, "defaultValue" | "index" | "localized" | "max" | "min" | "providedBy" | "required">;
+    textArray: Kind<string[], "defaultValue" | "maxRows" | "minRows" | "providedBy" | "required">;
+    uuid: Kind<string, "defaultValue" | "index" | "providedBy" | "required" | "unique">;
+    relationship: Kind<string | number, "defaultValue" | "index" | "onDelete" | "providedBy" | "required" | "unique"> & {
+        pointsAtRow: true;
+    };
+    json: Kind<Json, "defaultValue" | "providedBy" | "required">;
+    join: Kind<unknown[], "providedBy" | "required">;
+};

package/dist/base/kinds.js

@@ -0,0 +1,123 @@
+import { isDecimal } from './decimal.js';
+/** Defines a project kind from its runtime check. */
+export const kind = (accepts) => (definition) => ({ ...definition, value: undefined, accepts });
+/**
+ * The most UTF-8 bytes of JSON text a json field holds, which a field names as its `maxBytes`, so one write
+ * never stores a value every read of the row then carries.
+ */
+export const defaultJsonMaxBytes = 1_000_000;
+/** How deep a json value nests: past it every reader that walks it, this check first, would run out of stack. */
+export const jsonDepth = 64;
+/** Text Postgres holds: no NUL, which no `text` or `jsonb` takes, and no half of a surrogate pair. */
+export const isStorableText = (text) => !text.includes('\u0000') && text.isWellFormed();
+/**
+ * Plain JSON, nested at most `jsonDepth` deep: no `undefined`, no number that is
+ * not finite, no `Date`, class instance or function, no cycle, and no string or key
+ * Postgres cannot store. A store would otherwise drop, rewrite or refuse it on the
+ * way in, and read back something else.
+ */
+export const isJson = (value, open = []) => {
+    if (typeof value === 'string')
+        return isStorableText(value);
+    if (value === null || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'object' || open.length >= jsonDepth || open.includes(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
+        return false;
+    open.push(value);
+    // `Object.values` skips a hole, which `JSON.stringify` would write as `null`, so the length is checked too.
+    const plain = (Array.isArray(value) ? Object.keys(value).length === value.length : Object.keys(value).every(isStorableText))
+        && Object.values(value).every((one) => isJson(one, open));
+    open.pop();
+    return plain;
+};
+export const defaultKinds = {
+    text: kind((value) => typeof value === 'string')({
+        label: { en: 'Text', ar: 'نص' },
+        message: { en: 'This is not text.', ar: 'هذا ليس نصا.' },
+        rules: ['providedBy', 'required', 'unique', 'index', 'defaultValue', 'localized', 'maxLength', 'minLength', 'pattern', 'uppercase', 'lowercase', 'trim'],
+    }),
+    email: kind((value) => typeof value === 'string')({
+        label: { en: 'Email', ar: 'بريد إلكتروني' },
+        message: { en: 'This is not an email address.', ar: 'هذا ليس بريدا إلكترونيا.' },
+        rules: ['providedBy', 'required', 'unique', 'index', 'defaultValue', 'localized', 'maxLength', 'minLength', 'pattern', 'uppercase', 'lowercase', 'trim'],
+    }),
+    number: kind((value) => typeof value === 'number')({
+        label: { en: 'Number', ar: 'رقم' },
+        message: { en: 'This is not a number.', ar: 'هذا ليس رقما.' },
+        rules: ['providedBy', 'required', 'unique', 'index', 'defaultValue', 'localized', 'min', 'max'],
+    }),
+    // Held to int4's range, because the column is a Postgres `integer`.
+    integer: kind((value) => Number.isInteger(value) && value >= -2147483648 && value <= 2147483647)({
+        label: { en: 'Integer', ar: 'عدد صحيح' },
+        message: { en: 'This is not a 32-bit integer.', ar: 'هذا ليس عددا صحيحا من 32 بت.' },
+        rules: ['providedBy', 'required', 'unique', 'index', 'defaultValue', 'localized', 'min', 'max'],
+    }),
+    // Carried as text, because a JS number would round money past 15 significant digits.
+    decimal: kind(isDecimal)({
+        label: { en: 'Decimal', ar: 'عدد عشري' },
+        message: { en: 'This is not a decimal number.', ar: 'هذا ليس عددا عشريا.' },
+        rules: ['providedBy', 'required', 'unique', 'index', 'defaultValue', 'localized', 'min', 'max', 'precision', 'scale'],
+    }),
+    checkbox: kind((value) => typeof value === 'boolean')({
+        label: { en: 'Checkbox', ar: 'خانة اختيار' },
+        message: { en: 'This is answered yes or no.', ar: 'يجاب على هذا بنعم أو لا.' },
+        rules: ['providedBy', 'required', 'index', 'defaultValue'],
+    }),
+    datetime: kind((value) => value instanceof Date)({
+        label: { en: 'Date and time', ar: 'التاريخ والوقت' },
+        message: { en: 'This is not a date and time.', ar: 'هذا ليس تاريخا ووقتا.' },
+        now: () => new Date(),
+        rules: ['providedBy', 'required', 'index', 'defaultValue', 'defaultNow', 'nowOnUpdate', 'localized'],
+    }),
+    // A string, not a `Date`: a day read in another zone as a moment is the day before.
+    // `Date.parse('2026-02-30')` rolls over to March 2, so a day must come back as itself.
+    date: kind((value) => typeof value === 'string' &&
+        /^\d{4}-\d{2}-\d{2}$/.test(value) &&
+        new Date(value).toJSON()?.startsWith(value) === true)({
+        label: { en: 'Date', ar: 'التاريخ' },
+        message: { en: 'This is not a date.', ar: 'هذا ليس تاريخا.' },
+        rules: ['providedBy', 'required', 'index', 'defaultValue', 'localized', 'min', 'max'],
+    }),
+    textArray: kind((value) => Array.isArray(value) && value.every((one) => typeof one === 'string'))({
+        label: { en: 'Text list', ar: 'قائمة نصوص' },
+        message: { en: 'This is not a list of text.', ar: 'هذه ليست قائمة نصوص.' },
+        rules: ['providedBy', 'required', 'defaultValue', 'minRows', 'maxRows'],
+    }),
+    // Named rather than `text` because a foreign key takes the type of the id it
+    // points at, and Postgres refuses a text reference to a uuid key.
+    uuid: kind((value) => typeof value === 'string')({
+        label: { en: 'UUID', ar: 'معرف فريد' },
+        message: { en: 'This is not a unique identifier.', ar: 'هذا ليس معرفا فريدا.' },
+        rules: ['providedBy', 'required', 'unique', 'index', 'defaultValue'],
+    }),
+    relationship: kind((value) => typeof value === 'number' || typeof value === 'string')({
+        label: { en: 'Relationship', ar: 'علاقة' },
+        message: { en: 'Pick one of the listed entries.', ar: 'اختر عنصرًا من القائمة.' },
+        rules: ['providedBy', 'required', 'unique', 'index', 'defaultValue', 'onDelete'],
+        pointsAtRow: true,
+        // A row another still names is never deleted from under it, its drafts included; a field says
+        // `set null` or `cascade` to let it go.
+        onDelete: 'restrict',
+    }),
+    // Payload's `json` field, unwrapped, so each reads a row the other wrote. Nothing orders by one:
+    // jsonb's order is no order a person reads.
+    json: kind(isJson)({
+        label: { en: 'JSON', ar: 'JSON' },
+        message: { en: 'This is not JSON this field takes.', ar: 'هذه ليست بيانات JSON يقبلها هذا الحقل.' },
+        rules: ['providedBy', 'required', 'defaultValue'],
+        operators: ['equals', 'not_equals', 'in', 'not_in', 'exists', 'like', 'contains'],
+        sortable: false,
+    }),
+    // The rows of another kayan whose `on` relationship points at this one. It builds
+    // no column: the id lives on the child, and a read populates it through the child's access.
+    join: kind((value) => Array.isArray(value))({
+        label: { en: 'Related rows', ar: 'صفوف مرتبطة' },
+        message: { en: 'This is not a list of related entries.', ar: 'هذه ليست قائمة عناصر مرتبطة.' },
+        rules: ['providedBy', 'required'],
+    }),
+};

package/dist/base/rules.d.ts

@@ -0,0 +1,73 @@
+import { type Ref } from '../mithaq/user.ts';
+import type { Localized } from '../mithaq/types.ts';
+import { type Json, type OnDelete } from './kinds.ts';
+export type Rule<Value = unknown> = {
+    /** Compile-time value carried by a binding; never read at runtime. */
+    value: Value;
+    /** Runtime check for dynamic declarations where TypeScript is absent. */
+    accepts(value: unknown): value is Value;
+    /** What a person reads where this rule refuses a value. A rule that never refuses one carries none. */
+    message?: Localized;
+    /** The rules a field may not declare beside this one, by name. */
+    excludes?: readonly string[];
+};
+export type RuleValue<R> = R extends Rule<infer Value> ? Value : never;
+/** Defines a project rule from its runtime check. */
+export declare const rule: <Value>({ accepts, message, excludes, }: {
+    accepts: (value: unknown) => value is Value;
+    message?: Localized;
+    excludes?: readonly string[];
+}) => Rule<Value>;
+declare const providers: readonly ['client', 'application', 'never'];
+export type Provider = (typeof providers)[number];
+export type ProvidedBy = Readonly<{
+    create?: Provider;
+    update?: Provider;
+}>;
+/** Who supplies a field's value on one operation; a field that declares nothing is the client's. */
+export declare const providerOf: (field: {
+    rules?: Record<string, unknown>;
+}, on: 'create' | 'update') => Provider;
+/** The shipped rules, which a project passes to `defineMithaq` and may add its own to. */
+export declare const defaultRules: {
+    required: Rule<boolean>;
+    unique: Rule<boolean>;
+    index: Rule<boolean>;
+    /** A literal, JSON for a `json` field, or `user.<key>` for the actor's value. Each row gets its own copy. */
+    defaultValue: Rule<Date | readonly unknown[] | Ref | Json>;
+    /** The moment of the write, on create. */
+    defaultNow: Rule<boolean>;
+    /** The moment of the write, on every update, whatever the column is called. */
+    nowOnUpdate: Rule<boolean>;
+    /** Who supplies the value on create and on update. A field declaring nothing is the client's on both. */
+    providedBy: Rule<Readonly<{
+        create?: Provider;
+        update?: Provider;
+    }>>;
+    /** One value per locale the language declares: one column per locale, and an object keyed by locale in every shape. */
+    localized: Rule<boolean>;
+    /** Length is a rule, not a kind: `text` with a maximum is `varchar(n)`. */
+    maxLength: Rule<number>;
+    /** A decimal's size, `numeric(precision, scale)`: declare both or neither. A value with more digits is refused, not rounded. */
+    precision: Rule<number>;
+    scale: Rule<number>;
+    minLength: Rule<number>;
+    pattern: Rule<RegExp>;
+    /** A bound on an ordered value: a number for `number`, an ISO day for `date`. */
+    min: Rule<string | number>;
+    max: Rule<string | number>;
+    /** How few and how many rows a list holds. A list that is not `required` may be left empty whatever its floor. */
+    minRows: Rule<number>;
+    maxRows: Rule<number>;
+    /** Rewrites the value's case before any check judges it; never refuses a value for its case. */
+    uppercase: Rule<boolean>;
+    lowercase: Rule<boolean>;
+    trim: Rule<boolean>;
+    /** What happens to this row when the row it points at is deleted. Left out, a required field and a set restrict and any other takes its kind's default. */
+    onDelete: Rule<OnDelete>;
+};
+/** The rule keys a field may carry, derived from the record the language names. */
+export type Rules = {
+    [Name in keyof typeof defaultRules]?: RuleValue<(typeof defaultRules)[Name]>;
+};
+export {};