@drhomet/mithaq 0.0.0-stage → 0.1.1

package/dist/mithaq/types.d.ts

@@ -0,0 +1,358 @@
+import type { KayanAuth } from '../asas/actor.ts';
+import type { Ref } from './user.ts';
+import type { AnyOperation, ResolvedOperation } from '../asas/runner/steps.ts';
+import type { Operator, Where } from './where.ts';
+import type { StandardSchemaV1 } from './standard-schema.ts';
+import type { Rules } from '../base/rules.ts';
+import type { Rule, RuleValue } from '../base/rules.ts';
+import type { Kind } from '../base/kinds.ts';
+import type { RichTextRead } from '../rich-text/rich-text.ts';
+import type { ResolvedStorage } from '../storage/storage.ts';
+import type { RefOf, ScreenField, ScreenKeys } from '../screen/index.ts';
+/** What a field access callback is handed. */
+export type FieldAccessArgs<User = unknown, Doc extends Record<string, unknown> = Record<string, unknown>, Id = unknown, Data extends Record<string, unknown> = Partial<Doc>> = {
+    data?: Data;
+    doc?: Doc;
+    id?: Id;
+    req?: unknown;
+    siblingData?: Record<string, unknown>;
+    user: User | null;
+};
+export type FieldAccess<User = unknown, Doc extends Record<string, unknown> = Record<string, unknown>, Id = unknown, Data extends Record<string, unknown> = Partial<Doc>> = (args: FieldAccessArgs<User, Doc, Id, Data>) => boolean | Promise<boolean>;
+type StoredFieldAccess = FieldAccess | (ActorBoundAccess<unknown> & {
+    readonly __mithaqFieldData: unknown;
+    readonly __mithaqFieldId: unknown;
+});
+type StoredAccess = {
+    create?: Access;
+    read?: Access;
+    update?: Access;
+    delete?: Access;
+} | (ActorBoundAccess<unknown> & {
+    create?: unknown;
+    read?: unknown;
+    update?: unknown;
+    delete?: unknown;
+});
+/** Copy in every locale a project declares, one string each. */
+export type Localized<Locale extends string = string> = Readonly<Record<Locale, string>>;
+/** A label a project resolves itself, such as a compiled paraglide message: `label: m.course_title`. It takes nothing. */
+export type LabelFunction = () => string;
+/** A scope's own copy, keyed flat: one entry per key, each a record per locale or a function. */
+export type MessageMap<Locale extends string = string> = Readonly<Record<string, Localized<Locale> | LabelFunction>>;
+/** A scope's copy as a declaration writes it, nested by the parts of the key, so a field's name is written once. */
+export interface MessageTree<Locale extends string = string> {
+    readonly [key: string]: Localized<Locale> | LabelFunction | MessageTree<Locale>;
+}
+/** The locales a language declared, or any string when it declared none. */
+export type LocalesOf<L> = L extends {
+    locales: readonly (infer Locale extends string)[];
+} ? Locale : string;
+/** The service target a language declares, found by its capability. */
+export type ServiceOf<L> = L extends {
+    targets: infer Targets;
+} ? Extract<Targets[keyof Targets], {
+    capability: 'service';
+}> : never;
+type Named<Locale extends string = string> = {
+    access?: {
+        create?: StoredFieldAccess;
+        read?: StoredFieldAccess;
+        update?: StoredFieldAccess;
+    };
+    /** One string per locale the language declares, every one required. */
+    label?: Localized<Locale> | LabelFunction;
+    /** What the field is, in a sentence, and the hint its empty control shows. */
+    description?: Localized<Locale> | LabelFunction;
+    placeholder?: Localized<Locale> | LabelFunction;
+    /** What a text or number field's input group draws before and after its value. */
+    prefix?: Localized<Locale>;
+    suffix?: Localized<Locale>;
+    /** The closed list a text field's value is one of. */
+    options?: readonly {
+        readonly value: string;
+        readonly label: Localized<Locale>;
+    }[];
+    /** The column name. A relationship without one gets `<snake_case name>_id`. */
+    dbName?: string;
+    /**
+     * One entry per target that has something to say about this field, by the target's name. A store's or
+     * a schema target's entry is the whole built thing, used as-is with the rules skipped; a screen's says how it draws the field.
+     */
+    targets?: Record<string, unknown>;
+    /** An open bag the project's own code reads; nothing in mithaq does, and it stays on the server. */
+    custom?: Record<string, unknown>;
+};
+type FieldKind<KindName extends string> = KindName extends 'join' ? {
+    kind: KindName;
+    /** The kayan whose rows this field holds, as a thunk or a name. */
+    relationTo: string | (() => Kayan);
+    /** The child's own relationship field that holds this row's id. */
+    on: string;
+    /** How many of the child's rows one populated read carries, over the service target's `joinLimit`. */
+    defaultLimit?: number;
+    /** The order the child's rows come back in: one field of the child, `-` for descending. */
+    defaultSort?: string;
+    hasMany?: never;
+} : KindName extends 'relationship' ? {
+    kind: KindName;
+    /** The kayan this field points at, as a thunk, so two kayan may point at each other, or as a name. */
+    relationTo: string | (() => Kayan);
+    /** Whether this field holds a set of rows rather than one, kept in a join table and read back as an array of ids. */
+    hasMany?: true;
+    on?: never;
+    defaultLimit?: never;
+    defaultSort?: never;
+} : {
+    kind: KindName;
+    relationTo?: never;
+    hasMany?: never;
+    on?: never;
+    defaultLimit?: never;
+    defaultSort?: never;
+};
+/** A field, open over locales: a project's own declaration goes through `FieldOf<L>`, which narrows them. */
+export type Field<KindName extends string = string, RuleValues = Rules> = KindName extends unknown ? Named & {
+    rules?: Partial<RuleValues>;
+} & FieldKind<KindName> : never;
+/** A field as it is after a build, open over locales for `Field`'s reason. */
+export type RuntimeField = Named & {
+    kind: string;
+    rules?: Record<string, unknown>;
+    relationTo?: string | (() => Kayan);
+    hasMany?: true;
+    /** A `join` field only: the child's relationship that points back at this kayan. */
+    on?: string;
+    /** A `join` field only: how many of the child's rows one populated read carries. */
+    defaultLimit?: number;
+    /** A `join` field only: the order the child's rows come back in. */
+    defaultSort?: string;
+};
+export type LanguageShape = {
+    kinds: Record<string, Kind>;
+    rules: Record<string, Rule>;
+    targets: Record<string, unknown>;
+    locales?: readonly string[];
+};
+type RuleNames<K> = K extends Kind<unknown, infer Name> ? Name : never;
+export type KindValue<K> = K extends Kind<infer Value, string> ? Value : never;
+type BoundRules<L extends LanguageShape, K extends keyof L['kinds']> = {
+    [Name in Extract<RuleNames<L['kinds'][K]>, keyof L['rules']>]?: RuleValue<L['rules'][Name]>;
+} & ('defaultValue' extends RuleNames<L['kinds'][K]> ? {
+    defaultValue?: KindValue<L['kinds'][K]> | Ref<KindValue<L['kinds'][K]>>;
+} : {});
+type BoundField<L extends LanguageShape, K extends keyof L['kinds'] & string> = Named<LocalesOf<L>> & {
+    kind: K;
+    rules?: BoundRules<L, K>;
+    targets?: Record<string, unknown> & {
+        [Screen in ScreenKeys<L['targets']>]?: ScreenField<RefOf<L['targets'][Screen], L['kinds']>>;
+    };
+} & (K extends 'join' ? {
+    relationTo: string | (() => Kayan);
+    on: string;
+    defaultLimit?: number;
+    defaultSort?: string;
+    hasMany?: never;
+} : L['kinds'][K] extends {
+    pointsAtRow: true;
+} ? {
+    relationTo: string | (() => Kayan);
+    hasMany?: true;
+    on?: never;
+    defaultLimit?: never;
+    defaultSort?: never;
+} : {
+    relationTo?: never;
+    hasMany?: never;
+    on?: never;
+    defaultLimit?: never;
+    defaultSort?: never;
+});
+/** Field union derived once from a concrete language's kind and rule registries. */
+export type FieldOf<L extends LanguageShape> = {
+    [K in keyof L['kinds'] & string]: BoundField<L, K>;
+}[keyof L['kinds'] & string];
+/** What a kayan writes under `targets.service`: its operations, and the store and schema target it runs them through. */
+export type KayanService = {
+    /** Every operation this kayan answers; one that declares none answers none. */
+    operations?: Record<string, AnyOperation>;
+    /** The store this kayan is written through. Defaults to the service target's. */
+    store?: string;
+    /** The target a write is validated against. Defaults to the service target's. */
+    schema?: string;
+};
+/** The three keys a kayan's `targets.service` may carry, in one place. */
+export declare const kayanServiceKeys: readonly ['operations', 'schema', 'store'];
+/**
+ * One index over the columns its fields name, in that order; `unique` is `false` when left out.
+ * `nullsNotDistinct`, on a unique index, makes rows whose columns are null collide.
+ */
+export type CompoundIndex<Field extends string = string> = {
+    fields: Field[];
+} & ({
+    unique?: boolean;
+    nullsNotDistinct?: never;
+} | {
+    unique: true;
+    nullsNotDistinct?: boolean;
+});
+type GroupEntry<Field extends string> = Field | [Field, ...Field[]];
+type GroupEntries<Field extends string> = [GroupEntry<Field>, ...GroupEntry<Field>[]];
+/**
+ * Indexes within a tenant-owned kayan's tenant field, each led by it: `{ within: 'organization',
+ * unique: ['title', ['code', 'term']], index: ['startsAt'] }` is unique `(organization, title)`,
+ * unique `(organization, code, term)` and plain `(organization, startsAt)`.
+ */
+export type IndexGroup<Field extends string = string, Within extends string = string> = {
+    within: Within;
+} & ({
+    unique: GroupEntries<Field>;
+    index?: GroupEntry<Field>[];
+} | {
+    unique?: GroupEntry<Field>[];
+    index: GroupEntries<Field>;
+});
+/**
+ * A kayan's indexes: a list built beside the defaults, or a function of the defaults that answers the whole list.
+ * The defaults are one unique index per `unique` field, over the field alone on a shared kayan and over the
+ * ownership field and the field on a tenant-owned one. A plain entry is over exactly its fields.
+ */
+export type Indexes<Field extends string = string, Within extends string = string> = (CompoundIndex<Field> | IndexGroup<Field, Within>)[] | ((args: {
+    defaults: CompoundIndex<Field>[];
+}) => (CompoundIndex<Field> | IndexGroup<Field, Within>)[]);
+export type Kayan = {
+    name: string;
+    fields: Record<string, RuntimeField>;
+    access?: StoredAccess;
+    /** The provider that authenticates this kayan: `betterAuth({ server })`, `local({ secret })`, or a strategy the project wrote. */
+    auth?: KayanAuth;
+    /** The table name. Defaults to the name. */
+    dbName?: string;
+    /** The Postgres schema this kayan's tables are built in. No key, or `'public'`, is `public`. */
+    schemaName?: string;
+    /** Indexes over this kayan's own columns; each field named must be one column of its own table. */
+    indexes?: (CompoundIndex | IndexGroup)[] | ((args: {
+        defaults: never;
+    }) => (CompoundIndex | IndexGroup)[]);
+    /** One entry per target with something to say about this kayan: `{ drizzle: pgTable(...) }`, `targets.<screen>`, `targets.service`. */
+    targets?: Record<string, unknown> & {
+        service?: KayanService;
+    };
+    /** This kayan's own copy, beside the labels its fields carry, nested by the parts of each key. */
+    messages?: MessageTree;
+    /** Where `mithaq generate messages` writes this kayan's file, if not the default. */
+    out?: string;
+    /** An open bag the project's own code reads; nothing in mithaq does, and it stays on the server. */
+    custom?: Record<string, unknown>;
+    /** A kayan of one row, which `defineGlobal` sets: it runs `findOne` and `update`, finds its row without an id and makes it when none. */
+    single?: true;
+};
+export type AccessArgs<User = unknown, Data extends Record<string, unknown> = Record<string, unknown>, Id = unknown> = {
+    data?: Data;
+    id?: Id;
+    req?: unknown;
+    slug: string;
+    user: User | null;
+};
+export type AccessResult = boolean | Where;
+export type Access<User = unknown, Data extends Record<string, unknown> = Record<string, unknown>, Id = unknown> = (args: AccessArgs<User, Data, Id>) => AccessResult | Promise<AccessResult>;
+export type AdminAccessArgs<User = unknown> = {
+    req?: unknown;
+    user: User;
+};
+export type AdminAccess<User = unknown> = (args: AdminAccessArgs<User>) => boolean | Promise<boolean>;
+export type ActorBoundAccess<Actor> = {
+    readonly __mithaqAccessActor: Actor;
+};
+export type ActorBoundFieldAccess<Actor, Doc extends Record<string, unknown>, Id> = FieldAccess<Actor, Doc, Id> & ActorBoundAccess<Actor> & {
+    readonly __mithaqFieldData: Doc;
+    readonly __mithaqFieldId: Id;
+};
+export declare const fieldAccessFor: <Actor>() => <Doc extends Record<string, unknown>, Id, Fn extends FieldAccess<Actor, Doc, Id> = FieldAccess<Actor, Doc, Id>>(access: Fn) => Fn & ActorBoundFieldAccess<Actor, Doc, Id>;
+type AccessReturnCheck<Map> = {
+    [Key in keyof Map]: Map[Key] extends (...args: infer Args) => infer Return ? (...args: Args) => Return extends AccessResult | Promise<AccessResult> ? Return : never : never;
+};
+export declare const accessFor: <Actor>() => <AccessMap extends {
+    create?: unknown;
+    read?: unknown;
+    update?: unknown;
+    delete?: unknown;
+}>(access: AccessMap & AccessReturnCheck<AccessMap>) => AccessMap & ActorBoundAccess<Actor>;
+/** A field after `buildAsas` has filled in what the kayan left implicit. */
+export type ResolvedField<F extends RuntimeField = RuntimeField> = F & {
+    name: string;
+    /** The SQL column name. */
+    column: string;
+    /** The name of the kayan this field belongs to, which the copy key a refusal carries names. */
+    kayan?: string;
+    /** The key this build gives the schema target of the field's kayan. */
+    schemaTarget?: string;
+    /** The language's locales in declared order, on a `localized` field only, so a target can build one thing per locale. */
+    locales?: readonly string[];
+    /** How this field's kind makes the write's moment, where it declares one. */
+    now?: () => unknown;
+    /** This field's kind's own implementations, keyed by target type. */
+    kindTargets?: Readonly<Record<string, unknown>>;
+    /** The `Where` operators this field's kind takes, where it names them. */
+    operators?: readonly Operator[];
+    /** `false` where this field's kind cannot order a page. */
+    sortable?: false;
+    /** The kayan of this build that hold files, which a value may point at from inside it. */
+    filesIn?: readonly string[];
+    /** How a schema target reads back a stored `richText` value: with its shape alone. */
+    richText?: (value: unknown) => RichTextRead;
+    /** Relationship only: the kayan this field points at. */
+    target?: ResolvedKayan;
+};
+export type ResolvedKayan<K extends Kayan = Kayan> = Omit<K, 'indexes' | 'messages' | 'operations'> & {
+    /** Every index the store builds: the declared list and the defaults, or what the kayan's function answered. */
+    indexes: CompoundIndex[];
+    /** The table name: the kayan's `dbName`, or its name. */
+    table: string;
+    /** The kayan's own copy, flattened by `resolve` to the keys a generated file carries. */
+    messages?: MessageMap;
+    /** The store and the schema target, the kayan's own or the service target's. */
+    store: string;
+    schema: string;
+    fields: {
+        [Name in keyof K['fields']]: ResolvedField<K['fields'][Name]>;
+    };
+    /** Every operation this kayan declared, and nothing merged in. */
+    operations: Record<string, ResolvedOperation>;
+    /** The name of the field that marks a row deleted, on a kayan that carries it. */
+    softDelete?: string;
+    /** The name of the field bound through `targets.tenant`, on a tenant-owned kayan. */
+    tenant?: string;
+    /** What this kayan keeps of its past, on a kayan that writes the versions target. */
+    versions?: ResolvedVersions;
+    /** The files this kayan holds and the storage they go through, on a kayan that writes the storage target. */
+    storage?: ResolvedStorage;
+    /** The schema target's `row` shape, so a caller's `where` is checked against each column's kind before any store is asked. */
+    rowShape?: StandardSchemaV1;
+};
+/** One kayan's versions, as `resolve` reads them off its own `targets.<versions>` and the target. */
+export type ResolvedVersions = {
+    /** The versions table, `_<table>_versions`. */
+    table: string;
+    /** That table as a kayan: `parent` a relationship back to this kayan. The `version` column is no field: nothing filters by what a version holds. */
+    kayan: ResolvedKayan;
+    /** Whether a write with `{ draft: true }` saves a version alone. */
+    drafts: boolean;
+    /**
+     * Whether a draft save with `{ autosave: true }` may overwrite the latest
+     * autosave in place, and the interval in milliseconds a screen autosaves at.
+     */
+    autosave: false | {
+        interval: number;
+    };
+    /** How many versions of one row are kept; `0` keeps every one. */
+    max: number;
+};
+export declare const resolvedKayans: WeakMap<object, Readonly<Record<string, ResolvedKayan<Kayan>>>>;
+export declare const sortableFields: (kayan: ResolvedKayan) => string[];
+/**
+ * Whether one field cannot order a page: a localized field or a set, a join,
+ * a field whose kind says it cannot, or one a screen took out of sorting.
+ */
+export declare const unsortable: (field: ResolvedField) => boolean;
+export {};

package/dist/mithaq/types.js

@@ -0,0 +1,15 @@
+/** The three keys a kayan's `targets.service` may carry, in one place. */
+export const kayanServiceKeys = ['operations', 'schema', 'store'];
+export const fieldAccessFor = () => (access) => access;
+export const accessFor = () => (access) => access;
+// A WeakMap rather than a key on the build, so a browser projection, a JSON
+// serialization and a caller enumerating the namespace all miss it.
+export const resolvedKayans = new WeakMap();
+// One function for the default sort and the copy scan's page, so the rule cannot drift between them.
+export const sortableFields = (kayan) => Object.keys(kayan.fields).filter((name) => !unsortable(kayan.fields[name]));
+/**
+ * Whether one field cannot order a page: a localized field or a set, a join,
+ * a field whose kind says it cannot, or one a screen took out of sorting.
+ */
+export const unsortable = (field) => !!field.rules?.localized || !!field.hasMany || field.kind === 'join' || field.sortable === false
+    || Object.values(field.targets ?? {}).some((one) => one?.sortable === false);

package/dist/mithaq/user.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A reference to the actor's value at one key. `T` is never written or read; it
+ * carries the value's type into the operator the reference is compared with.
+ */
+export type Ref<T = unknown> = {
+    $user: string;
+    __value?: T;
+};
+/** One reference per key of the actor. */
+export type UserRefs<Actor> = {
+    readonly [Key in keyof Actor]-?: Ref<NonNullable<Actor[Key]>>;
+};
+/** The actor accessor for a project's own shipped fields, typed by the actor the caller names. */
+export declare const userRefs: <Actor>() => UserRefs<Actor>;
+export declare const user: {
+    readonly [key: string]: Ref<never>;
+};
+export declare const isRef: (value: unknown) => value is Ref;
+export declare const refuseLiteral: (value: unknown, where: string) => void;

package/dist/mithaq/user.js

@@ -0,0 +1,16 @@
+// Frozen, so a row stays data that a query, a form and `JSON.stringify` read without executing anything.
+const refs = new Proxy(Object.freeze({}), {
+    // `refs[Symbol.iterator]` must be nothing, or the operand check reads it as a literal.
+    get: (_target, key) => (typeof key === 'symbol' ? undefined : Object.freeze({ $user: key })),
+});
+/** The actor accessor for a project's own shipped fields, typed by the actor the caller names. */
+export const userRefs = () => refs;
+export const user = refs;
+export const isRef = (value) => typeof value === 'object' && value !== null && typeof value.$user === 'string';
+// Refused, so a row still holding a `$CURRENT_USER.` string fails loudly rather than resolving to nothing.
+export const refuseLiteral = (value, where) => {
+    if (typeof value !== 'string' || !value.startsWith('$CURRENT_USER.'))
+        return;
+    const key = value.slice('$CURRENT_USER.'.length);
+    throw new Error(`${where} names the actor as the string "${value}". That form is gone: write \`user.${key}\`, with the \`user\` \`defineMithaq\` hands back, or \`userRefs<Actor>()\` where the language does not exist yet.`);
+};

package/dist/mithaq/where.d.ts

@@ -0,0 +1,32 @@
+export type Scalar = string | number | boolean | Date | null;
+export declare const operatorList: readonly ['contains', 'equals', 'exists', 'greater_than', 'greater_than_equal', 'in', 'less_than', 'less_than_equal', 'like', 'not_equals', 'not_in'];
+export type Operator = (typeof operatorList)[number];
+export type FieldWhere = Partial<Record<Operator, Scalar | readonly Scalar[] | boolean>>;
+export type Where = {
+    and: readonly Where[];
+} | {
+    or: readonly Where[];
+} | {
+    [field: string]: FieldWhere;
+};
+export declare const combineWhere: (left?: Where, right?: Where) => Where | undefined;
+/**
+ * Whether a `Where` holds, read in memory, with each operator meaning what the
+ * stores mean by it. `kindOf` lets a decimal compare by value, as Postgres does.
+ */
+export declare const matchesWhere: ({ where, valueOf, kindOf }: {
+    where: Where;
+    valueOf: (key: string) => unknown;
+    kindOf?: (key: string) => string | undefined;
+}) => boolean;
+/**
+ * Two stored values the same by what they hold: a moment by its time, an object
+ * whatever its key order, an absent value as `null`. No `node:util`: this runs in the browser.
+ */
+export declare const same: (left: unknown, right: unknown) => boolean;
+/** Where one value sorts against another, `null` last going up. */
+export declare const compareValues: ({ left, right, direction }: {
+    left: unknown;
+    right: unknown;
+    direction: 'asc' | 'desc';
+}) => number;

package/dist/mithaq/where.js

@@ -0,0 +1,87 @@
+// Imports nothing but `../base/decimal.ts`, which imports nothing, so `mithaq/admin` can carry it to a browser.
+import { compareDecimals, isDecimal } from '../base/decimal.js';
+// The list is the source and the union is read off it, so the type and the set the runner admits cannot drift.
+export const operatorList = [
+    'contains',
+    'equals',
+    'exists',
+    'greater_than',
+    'greater_than_equal',
+    'in',
+    'less_than',
+    'less_than_equal',
+    'like',
+    'not_equals',
+    'not_in',
+];
+export const combineWhere = (left, right) => left && right ? { and: [left, right] } : left ?? right;
+/**
+ * Whether a `Where` holds, read in memory, with each operator meaning what the
+ * stores mean by it. `kindOf` lets a decimal compare by value, as Postgres does.
+ */
+export const matchesWhere = ({ where, valueOf, kindOf }) => Object.entries(where).every(([key, rules]) => key === 'and' ? rules.every((one) => matchesWhere({ where: one, valueOf, kindOf }))
+    : key === 'or' ? rules.some((one) => matchesWhere({ where: one, valueOf, kindOf }))
+        : Object.entries(rules).every(([operator, operand]) => fieldMatch({ value: valueOf(key), operator, operand, decimal: kindOf?.(key) === 'decimal' })));
+/**
+ * Two stored values the same by what they hold: a moment by its time, an object
+ * whatever its key order, an absent value as `null`. No `node:util`: this runs in the browser.
+ */
+export const same = (left, right) => {
+    const [a, b] = [left ?? null, right ?? null];
+    if (a instanceof Date || b instanceof Date)
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null || Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && same(a[key], b[key]));
+};
+const orderValue = (value) => (value instanceof Date ? value.getTime() : value);
+const less = (left, right) => typeof left === 'number' && typeof right === 'number' ? left < right : String(left) < String(right);
+/** Where one value sorts against another, `null` last going up. */
+export const compareValues = ({ left, right, direction }) => {
+    if (left === null && right === null)
+        return 0;
+    if (left === null)
+        return direction === 'asc' ? 1 : -1;
+    if (right === null)
+        return direction === 'asc' ? -1 : 1;
+    const a = orderValue(left);
+    const b = orderValue(right);
+    const order = a === b ? 0 : less(b, a) ? 1 : -1;
+    return direction === 'desc' ? -order : order;
+};
+const text = (value) => String(value ?? '').toLowerCase();
+const comparable = (value) => value !== null && value !== undefined;
+const fieldMatch = ({ value, operator, operand, decimal }) => {
+    const exact = (left, right) => decimal && isDecimal(left) && isDecimal(right);
+    const equal = (left, right) => (exact(left, right) ? compareDecimals(left, right) === 0 : same(left, right));
+    const order = (left, right) => (exact(left, right) ? compareDecimals(left, right) : compareValues({ left, right, direction: 'asc' }));
+    switch (operator) {
+        case 'contains':
+            return comparable(value) && text(value).includes(text(operand));
+        case 'like':
+            return comparable(value) && text(operand).trim().split(/\s+/).filter(Boolean).every((word) => text(value).includes(word));
+        case 'equals':
+            return equal(value, operand);
+        case 'exists':
+            return Boolean(operand) ? value !== null && value !== undefined : value === null || value === undefined;
+        case 'greater_than':
+            return comparable(value) && comparable(operand) && order(value, operand) > 0;
+        case 'greater_than_equal':
+            return comparable(value) && comparable(operand) && order(value, operand) >= 0;
+        case 'in':
+            return operand.some((one) => equal(value, one));
+        case 'less_than':
+            return comparable(value) && comparable(operand) && order(value, operand) < 0;
+        case 'less_than_equal':
+            return comparable(value) && comparable(operand) && order(value, operand) <= 0;
+        case 'not_equals':
+            return operand === null ? comparable(value) : comparable(value) && !equal(value, operand);
+        case 'not_in':
+            return comparable(value) && !operand.some((one) => equal(value, one));
+        default:
+            return false;
+    }
+};

package/dist/rbac/index.d.ts

@@ -0,0 +1,105 @@
+import { type CheckedTable, type Held, type RowTable } from '../mithaq/rows.ts';
+import { type Command, type Store } from '../mithaq/language.ts';
+import type { Where } from '../mithaq/where.ts';
+/** One system role, written in code: the copy a screen shows it under and the keys it holds. `'*'` is every key. */
+export type SystemRole = {
+    label: Readonly<Record<string, string>>;
+    permissions: '*' | readonly string[];
+};
+/** Every system role of a project, slug to role. Its keys are the row keys. */
+export type SystemRoles = Readonly<Record<string, SystemRole>>;
+/** What one actor is assigned in one tenant, and every key those roles hold. */
+export type Assigned = {
+    /** `'*'` is every key of the project, which is what a root granter holds. */
+    permissions: '*' | readonly string[];
+    roles: readonly string[];
+};
+/** The access target: it names the system roles, reads which an actor is assigned, and answers what they hold. */
+export type AccessTarget<Roles extends SystemRoles = SystemRoles, Table extends RowTable = RowTable, Actor = unknown> = {
+    readonly capability: 'access';
+    /** `'rbac'` from `rbacTarget`, `'betterAuth'` from `betterAuthTarget`. */
+    readonly type?: 'rbac' | 'betterAuth';
+    /** The system roles, which are also the names a row table may be keyed on. */
+    readonly roles: Roles;
+    /** The slugs this actor is assigned, read from the trusted snapshot, so an actor naming its own roles is a claim. Absent is `user.roles`. */
+    readonly rolesOf?: (user: Actor) => readonly string[];
+    /** The rows every tenant-owned kayan inherits. */
+    readonly access: Table;
+    /** The kayan this target reads rows out of; none may carry a soft-delete mark, or a marked role row would keep granting. */
+    readonly reads: readonly string[];
+    /**
+     * A member's slugs and their keys, in one tenant. `ownership` names the field bound to the
+     * tenant on a kayan the target reads, and nothing for a shared one.
+     */
+    resolve(args: {
+        store: Store;
+        tenant: unknown;
+        member: unknown;
+        actor: object;
+        ownership: (kayan: string) => string | undefined;
+    }): Promise<Assigned>;
+    readonly commands?: Record<string, Command>;
+};
+/**
+ * The keys an actor holds for a kayan: what the build's access target resolved,
+ * or the kayan's own rows where no target answered. Precedence, never a union.
+ */
+export declare const heldPermissions: ({ access, user }: {
+    access: unknown;
+    user: unknown;
+}) => Held;
+/** One page of every row a filter matches, which is how each table is read. */
+export declare const allRows: ({ store, kayan, where }: {
+    store: Store;
+    kayan: string;
+    where: Where;
+}) => Promise<{
+    docs: Record<string, unknown>[];
+    totalDocs: number;
+}>;
+/** A tenant a row can be filtered by. Nothing else scopes a read, so nothing else reads. */
+export declare const scoped: (value: unknown) => value is number | string;
+/** The actor a command hands an audit sink: the command and the operating-system user who ran it. */
+export type CommandActor = {
+    command: string;
+    osUser: string;
+};
+export type AccessOptions<Roles extends SystemRoles, Table extends RowTable, Actor> = {
+    /** The system roles, which are code and never rows. */
+    roles: Roles;
+    /** How the actor's assigned slugs are read. Absent is `user.roles`. */
+    rolesOf?: (user: Actor) => readonly string[];
+    /** The row table, keyed on `'*'` and on the slugs `roles` names. */
+    access?: Table & CheckedTable<Table, '*' | (keyof Roles & string)>;
+    /** Where the target reads and seeds: `memberRoles` is the assignment, `roles` the custom roles. */
+    kayan: {
+        memberRoles: string;
+        roles: string;
+    };
+};
+export declare const assignedSlugs: ({ store, kayan, field, tenant, member }: {
+    store: Store;
+    kayan: string;
+    field: string | undefined;
+    tenant: unknown;
+    member: unknown;
+}) => Promise<string[]>;
+/**
+ * A role slug that is one of the project's own, whose keys are code. The rest
+ * are rows, and a target reads them from wherever it holds them.
+ */
+export declare const systemKeys: (roles: SystemRoles, slugs: readonly string[]) => {
+    custom: string[];
+    everything: boolean;
+    keys: Set<string>;
+};
+export declare const heldSlugs: ({ roles, rolesOf, slugs, actor }: {
+    roles: SystemRoles;
+    rolesOf: ((user: never) => readonly string[]) | undefined;
+    slugs: readonly string[];
+    actor: object | undefined;
+}) => readonly string[];
+/** The access target whose custom roles are rows of a kayan the project ships, beside its system roles in code. */
+export declare const rbacTarget: <const Roles extends SystemRoles, const Table extends RowTable, Actor>({ roles, rolesOf, access, kayan, }: AccessOptions<Roles, Table, Actor>) => AccessTarget<Roles, Table, Actor> & {
+    readonly type: 'rbac';
+};