@drhomet/mithaq 0.0.0-stage → 0.1.1

package/dist/mithaq/language.d.ts

@@ -0,0 +1,335 @@
+import { type CheckedTable, type RowTable, type Rows, type RowsOptions } from './rows.ts';
+import { type UserRefs } from './user.ts';
+import type { AccessTarget, CommandActor, SystemRoles } from '../rbac/index.ts';
+import type { ServiceTarget } from '../service/index.ts';
+import type { ScreenTarget } from '../screen/index.ts';
+import type { VersionsTarget } from '../versions/index.ts';
+import type { StorageTarget } from '../storage/storage.ts';
+import { buildAsas, type HttpPlug } from '../asas/build.ts';
+import type { AuthConfig } from '../asas/build.ts';
+import type { AuditHandler, Derives, DerivedShapes } from '../asas/runner/steps.ts';
+import type { Where } from './where.ts';
+import { defineGlobal, defineKayan } from './define.ts';
+import type { Kayan, ResolvedField, ResolvedKayan } from './types.ts';
+import type { Kind } from '../base/kinds.ts';
+import type { Rule, RuleValue } from '../base/rules.ts';
+import type { StandardSchemaV1 } from './standard-schema.ts';
+import { type ArkanOf, type ArkanRefusals, type Rukn } from './rukn.ts';
+type RuleHandler<Rules, Name extends keyof Rules, Built, Key extends string> = (args: {
+    [K in Key]: Built;
+} & {
+    value: RuleValue<Rules[Name]>;
+    field: ResolvedField;
+}) => Built;
+/** What a target's command receives: the built project, and the words after the command, `--check` among them. */
+export type CommandInput = {
+    asas: {
+        destroy(): Promise<void>;
+    };
+    flags: readonly string[];
+};
+/** What a command answers: the exit code the bin exits with, 0 for nothing to say. */
+export type Command = (input: CommandInput) => Promise<number>;
+export type Target<Kinds extends Record<string, Kind> = Record<string, Kind>, Rules extends Record<string, Rule> = Record<string, Rule>, Built = unknown, Key extends string = 'shape'> = {
+    readonly capability?: 'schema';
+    /** What this target is, by the constructor that made it: `'drizzle'`, `'zod'`, `'screen'`. Kinds' own implementations are keyed by it. */
+    readonly type?: string;
+    /** The commands this target answers, run as `mithaq <target> <name>` and swept with `--check` by `mithaq generate --check`. */
+    readonly commands?: Record<string, Command>;
+    /** The kinds this target builds an id of, so a fourth fails the build rather than the pushed schema. */
+    readonly idKinds?: readonly (keyof Kinds & string)[];
+    kinds: {
+        [Name in keyof Kinds]: (field: ResolvedField, ...rest: never[]) => Built;
+    };
+    rules: {
+        [Name in keyof Rules]: RuleHandler<Rules, Name, Built, Key>;
+    };
+};
+/** A target that shapes a field, and assembles the shapes a kayan's fields derive, so core never composes a schema itself. */
+export type SchemaTarget<Kinds extends Record<string, Kind> = Record<string, Kind>, Rules extends Record<string, Rule> = Record<string, Rule>, Built = unknown, Schema extends StandardSchemaV1 = StandardSchemaV1> = Target<Kinds, Rules, Built> & {
+    /** Declared, never sniffed, the same way a store declares its own. */
+    readonly capability: 'schema';
+    /** The create, update, row and other shapes a kayan's fields derive. */
+    derive<F extends Record<string, ResolvedField>>(fields: F): DerivedShapes<Schema>;
+    /** The same mapping written as a type, because a conditional type cannot read `derive`'s generic signature for one kayan. Never set at runtime. */
+    readonly derives?: Derives;
+};
+type RuntimeSchema = {
+    readonly capability?: 'schema';
+    readonly type?: string;
+    readonly derives?: Derives;
+    readonly commands?: Record<string, Command>;
+    readonly idKinds?: readonly string[];
+    kinds: Record<string, (field: ResolvedField, ...rest: never[]) => unknown>;
+    rules: Record<string, (...args: never[]) => unknown>;
+    derive(fields: Record<string, ResolvedField>): DerivedShapes;
+};
+type RuntimeStore = Omit<Store, 'kinds' | 'rules'> & {
+    kinds: RuntimeSchema['kinds'];
+    rules: RuntimeSchema['rules'];
+};
+type RuntimeAccess = Omit<AccessTarget, 'access' | 'roles' | 'rolesOf'> & {
+    access: RowTable;
+    roles: SystemRoles;
+    rolesOf?: (user: never) => readonly string[];
+};
+type RuntimeService = ServiceTarget;
+export type RuntimeTarget = RuntimeAccess | RuntimeSchema | RuntimeScreen | RuntimeService | RuntimeStore | StorageTarget | TenantTarget | VersionsTarget;
+/** The field a tenant-owned kayan places: one row of `RelationTo`, written by the application on create and never after. */
+export type TenantField<RelationTo extends string = string> = {
+    readonly kind: 'relationship';
+    readonly relationTo: RelationTo;
+    readonly rules: {
+        readonly required: true;
+        readonly index: true;
+        readonly providedBy: {
+            readonly create: 'application';
+            readonly update: 'never';
+        };
+        readonly onDelete: 'restrict';
+    };
+    readonly targets: {
+        readonly tenant: true;
+    };
+};
+/**
+ * Which kayan a row's tenant is, and the field a tenant-owned kayan places. A kayan carrying
+ * a field bound through `targets.tenant` is tenant-owned; one carrying none is shared.
+ */
+export type TenantTarget<RelationTo extends string = string> = {
+    readonly capability: 'tenant';
+    readonly relationTo: RelationTo;
+    readonly onDelete: 'restrict';
+    readonly field: TenantField<RelationTo>;
+    /**
+     * Whether this actor is platform staff in the trusted platform app, who may read every
+     * tenant's rows with `tenant: 'all'` and never write through it. Absent, no one may.
+     */
+    readonly platform?: (args: {
+        user: unknown;
+    }) => boolean | Promise<boolean>;
+};
+type RuntimeScreen = ScreenTarget;
+/** A target that shapes a field: a store or a schema target. */
+export type FieldTarget = RuntimeSchema | RuntimeStore;
+/** The runtime shape of the one target that says who may do what. */
+export type AccessCapability = RuntimeAccess;
+/**
+ * A target that also holds the rows: a database adapter, or anything else a write can land in.
+ * The writes take the transaction, so everything one write does commits or rolls back together.
+ */
+export type Store<Kinds extends Record<string, Kind> = Record<string, Kind>, Rules extends Record<string, Rule> = Record<string, Rule>, Built = unknown, Tx = unknown, Row extends Record<string, unknown> = Record<string, unknown>> = Omit<Target<Kinds, Rules, Built, 'column'>, 'capability'> & {
+    /** Declared, never sniffed: a target says which of the two things it is. */
+    readonly capability: 'store';
+    /** `'drizzle'` where this store's `db` and `tables` are drizzle's, which local auth reads its kayan through. */
+    readonly sql?: 'drizzle';
+    /** Builds what this store needs for one build, answering the store that build uses from then on. */
+    init(kayan: ResolvedKayan[]): void | Store<Kinds, Rules, Built, Tx, Row>;
+    /** Reaches the database and, unless `readOnly`, prepares it. `readOnly` writes nothing. */
+    connect(args?: {
+        readOnly?: boolean;
+    }): Promise<void>;
+    /** Run `fn` in one transaction. What it returns is what the write returns. */
+    transaction<Result>(fn: (tx: Tx) => Promise<Result>): Promise<Result>;
+    insert(args: {
+        tx: Tx;
+        kayan: string;
+        data: Record<string, unknown>;
+    }): Promise<Row>;
+    update(args: {
+        tx: Tx;
+        kayan: string;
+        id: unknown;
+        data: Record<string, unknown>;
+        where?: Where;
+    }): Promise<Row>;
+    remove(args: {
+        tx: Tx;
+        kayan: string;
+        id: unknown;
+        where?: Where;
+    }): Promise<Row>;
+    /** Required, so no store can exist that the managed reads cannot use. */
+    find(args: {
+        kayan: string;
+        args: {
+            limit: number;
+            /** A store must hold the rows it returns until the transaction ends: a step that compares a row, such as `expectedUpdatedAt`, relies on it. */
+            lock?: 'update';
+            page: number;
+            sort: {
+                field: string;
+                direction: 'asc' | 'desc';
+            };
+            where?: Where;
+        };
+        tx?: Tx;
+    }): Promise<{
+        docs: Row[];
+        totalDocs: number;
+    }>;
+    /** Counts matching rows without loading them. Without it, `find` with a limit of `0` is asked. */
+    count?(args: {
+        kayan: string;
+        args: {
+            where?: Where;
+        };
+        tx?: Tx;
+    }): Promise<number>;
+    destroy(): Promise<void>;
+};
+/** A target that holds rows. Takes `undefined`, so a caller can name the bad target in its own throw. */
+export declare const isStore: (target: RuntimeTarget | undefined) => target is RuntimeStore;
+/** A target that says who may do what. */
+export declare const isAccess: (target: RuntimeTarget | undefined) => target is RuntimeAccess;
+/** A place a build draws its kayan. */
+export declare const isScreen: (target: RuntimeTarget | undefined) => target is RuntimeScreen;
+/** The runner. */
+export declare const isService: (target: RuntimeTarget | undefined) => target is RuntimeService;
+/** A kayan's versions. */
+export declare const isVersions: (target: RuntimeTarget | undefined) => target is VersionsTarget;
+/** The target that says which kayan a row's tenant is. */
+export declare const isTenant: (target: RuntimeTarget | undefined) => target is TenantTarget;
+/**
+ * A field bound through `targets.tenant`, with the tenant target's own field under it, so one
+ * written by hand takes every key and rule it leaves out. Any other field is handed back as it is.
+ */
+export declare const tenantDefaults: <F extends {
+    targets?: Record<string, unknown>;
+    rules?: Record<string, unknown>;
+}>(language: Language, field: F) => F;
+/** Where a kayan's files are kept. */
+export declare const isStorage: (target: RuntimeTarget | undefined) => target is StorageTarget;
+export declare const serviceTargetOf: (language: Language) => RuntimeService | undefined;
+export declare const accessTargetOf: (language: Language) => RuntimeAccess | undefined;
+export declare const languageRows: (language: Language) => Rows | undefined;
+/** The language: the arkan, the locales and one entry per target. */
+export type Language = {
+    kinds: Record<string, Kind>;
+    rules: Record<string, Rule>;
+    targets: Record<string, RuntimeTarget>;
+    /** The arkan the kinds, rules and some targets came from. */
+    arkan?: readonly Rukn[];
+    /**
+     * The locales every piece of copy is written in. Every label then needs one string per locale,
+     * so a half-translated project fails to compile. mithaq resolves no locale.
+     */
+    locales?: readonly string[];
+};
+export declare const serviceKeys: readonly ['beforeSteps', 'afterSteps', 'afterCommit', 'authorize', 'softDelete', 'store', 'schema', 'audit', 'depth'];
+type StoreKeys<Targets> = {
+    [Name in keyof Targets]: Targets[Name] extends {
+        capability: 'store';
+    } ? Name : never;
+}[keyof Targets] & string;
+type SchemaKeys<Targets> = {
+    [Name in keyof Targets]: Targets[Name] extends {
+        capability: 'access' | 'screen' | 'service' | 'storage' | 'store' | 'tenant' | 'versions';
+    } ? never : Name;
+}[keyof Targets] & string;
+type Owned<Kinds, Name extends keyof Kinds, K, T> = Name extends keyof K ? Name : T extends {
+    readonly type: infer Type extends string;
+} ? Kinds[Name] extends {
+    readonly targets: {
+        readonly [P in Type]: unknown;
+    };
+} ? never : Name : Name;
+type CheckedTarget<Kinds extends Record<string, Kind>, Rules extends Record<string, Rule>, Targets, T> = T extends {
+    capability: 'access' | 'storage' | 'tenant' | 'versions';
+} ? T : T extends {
+    capability: 'service';
+} ? T & Omit<ServiceTarget, 'store' | 'schema'> & {
+    store: StoreKeys<Targets>;
+    schema: SchemaKeys<Targets>;
+    /** The audit sink, which takes every actor the runner hands it: the request's and `mithaq rbac assign`'s. */
+    audit?: AuditHandler<ActorOf<{
+        targets: Targets;
+    }> | CommandActor>;
+    http?: never;
+    orpc?: never;
+} : T extends {
+    capability: 'screen';
+    controls: infer K;
+} ? T & {
+    controls: {
+        [Name in keyof Kinds as string extends keyof K ? never : Owned<Kinds, Name, K, T>]: Name extends keyof K ? K[Name] : never;
+    } & {
+        [Name in string extends keyof K ? never : Exclude<keyof K, keyof Kinds>]: never;
+    };
+} : T extends {
+    kinds: infer K;
+    rules: infer R;
+} ? T & {
+    kinds: {
+        [Name in keyof Kinds as string extends keyof K ? never : Owned<Kinds, Name, K, T>]: Name extends keyof K ? K[Name] : never;
+    } & {
+        [Name in string extends keyof K ? never : Exclude<keyof K, keyof Kinds>]: never;
+    };
+    rules: {
+        [Name in keyof Rules as string extends keyof R ? never : Name]: Name extends keyof R ? R[Name] extends (args: infer Args) => infer Built ? (args: Omit<Args, 'value' | 'field'> & {
+            value: RuleValue<Rules[Name]>;
+            field: ResolvedField;
+        }) => Built : never : never;
+    };
+} & (T extends {
+    idKinds: readonly unknown[];
+} ? {
+    idKinds: readonly (keyof Kinds & string)[];
+} : unknown) : never;
+type CheckedLanguage<L> = L extends {
+    arkan: infer A extends readonly Rukn[];
+    targets: infer Targets extends Record<string, RuntimeTarget>;
+} ? [ArkanOf<A, 'kinds'>, ArkanOf<A, 'rules'>] extends [infer Kinds extends Record<string, Kind>, infer Rules extends Record<string, Rule>] ? L & {
+    kinds?: never;
+    rules?: never;
+    targets: Targets & {
+        [Name in keyof Targets]: CheckedTarget<Kinds, Rules, Targets & ArkanOf<A, 'targets'>, Targets[Name]>;
+    };
+} & {
+    [Key in Extract<keyof L, (typeof serviceKeys)[number] | 'operations'>]: never;
+} & {
+    [Stray in {
+        [Name in keyof Kinds]: `kind "${Name & string}" accepts rule "${Exclude<Kinds[Name]['rules'][number], keyof Rules> & string}", which no rukn brings`;
+    }[keyof Kinds]]: never;
+} & ArkanRefusals<A, Targets> & {
+    [Misnamed in {
+        [Name in keyof Targets]: [Targets[Name]] extends [never] ? never : Targets[Name] extends {
+            capability: 'tenant';
+        } ? Name extends 'tenant' ? never : `target "${Name & string}" declares capability "tenant" and is named "tenant" in targets` : never;
+    }[keyof Targets]]: never;
+} : never : never;
+/** The language the arkan make: their kinds and rules, and their targets beside the project's. */
+type Composed<L> = L extends {
+    arkan: infer A extends readonly Rukn[];
+    targets: infer Targets;
+} ? L & {
+    kinds: ArkanOf<A, 'kinds'>;
+    rules: ArkanOf<A, 'rules'>;
+    targets: Targets & ArkanOf<A, 'targets'>;
+} : never;
+/** The access target a language declared, or nothing where it declared none. */
+type AccessOf<L> = L extends {
+    targets: infer Targets;
+} ? Extract<Targets[keyof Targets], {
+    capability: 'access';
+}> : never;
+type RolesOf<L> = [AccessOf<L>] extends [never] ? string : AccessOf<L> extends {
+    roles: infer Roles;
+} ? '*' | (keyof Roles & string) : string;
+type ActorOf<L> = NonNullable<AccessOf<L> extends {
+    rolesOf?: infer Reader;
+} ? Reader : never> extends (user: infer Actor) => unknown ? Actor : Record<string, never>;
+type Defined<L extends Language> = L & {
+    defineKayan: ReturnType<typeof defineKayan<L>>;
+    /** `defineKayan` with the operations pinned: a kayan of one row. */
+    defineGlobal: ReturnType<typeof defineGlobal<L>>;
+    buildAsas: <const KayanList extends readonly Kayan[], const GlobalList extends readonly Kayan[] = readonly [], Auth extends AuthConfig = AuthConfig, Http extends HttpPlug = HttpPlug>(args: Parameters<typeof buildAsas<L, KayanList, GlobalList, Auth, Http>>[1]) => ReturnType<typeof buildAsas<L, KayanList, GlobalList, Auth, Http>>;
+    /** `rows`, with its role keys checked against the language's `roles`. */
+    rows: <const Table extends RowTable>(table: Table & CheckedTable<Table, RolesOf<L>>, options?: RowsOptions<ActorOf<L>>) => Rows<Table>;
+    /** `user`, with its keys checked against the actor this language's `rolesOf` takes. */
+    user: UserRefs<ActorOf<L>>;
+};
+/** The object `defineMithaq` received, given the `defineKayan` it returned, or nothing. */
+export declare const receivedLanguage: (define: unknown) => unknown;
+export declare function defineMithaq<const L>(language: L & CheckedLanguage<L>): Defined<Extract<Composed<L>, Language>>;
+export {};

package/dist/mithaq/language.js

@@ -0,0 +1,76 @@
+import { rows } from './rows.js';
+import { actorPermissions } from '../asas/actor.js';
+import { user } from './user.js';
+import { buildAsas } from '../asas/build.js';
+import { defineGlobal, defineKayan } from './define.js';
+import { composeArkan } from './rukn.js';
+/** A target that holds rows. Takes `undefined`, so a caller can name the bad target in its own throw. */
+export const isStore = (target) => target?.capability === 'store';
+/** A target that says who may do what. */
+export const isAccess = (target) => target?.capability === 'access';
+/** A place a build draws its kayan. */
+export const isScreen = (target) => target?.capability === 'screen';
+/** The runner. */
+export const isService = (target) => target?.capability === 'service';
+/** A kayan's versions. */
+export const isVersions = (target) => target?.capability === 'versions';
+/** The target that says which kayan a row's tenant is. */
+export const isTenant = (target) => target?.capability === 'tenant';
+/**
+ * A field bound through `targets.tenant`, with the tenant target's own field under it, so one
+ * written by hand takes every key and rule it leaves out. Any other field is handed back as it is.
+ */
+export const tenantDefaults = (language, field) => {
+    const target = language.targets.tenant;
+    if (field.targets?.tenant === undefined || !isTenant(target))
+        return field;
+    return { ...target.field, ...field, rules: { ...target.field?.rules, ...field.rules } };
+};
+/** Where a kayan's files are kept. */
+export const isStorage = (target) => target?.capability === 'storage';
+// The one service target of a build; `buildAsas` refuses a build without one.
+export const serviceTargetOf = (language) => Object.values(language.targets).find((target) => isService(target));
+/** The compiled rows of the language's access target, kept off the public shape. */
+const LANGUAGE_ROWS = Symbol('mithaq.language.rows');
+// The one access target of a build, or nothing; `buildAsas` refuses two.
+export const accessTargetOf = (language) => Object.values(language.targets).find((target) => isAccess(target));
+// Compiled once by `defineMithaq`; every kayan that keeps the tenant field inherits it.
+export const languageRows = (language) => language[LANGUAGE_ROWS];
+// Keys of the service target, refused on the root by name.
+export const serviceKeys = ['beforeSteps', 'afterSteps', 'afterCommit', 'authorize', 'softDelete', 'store', 'schema', 'audit', 'depth'];
+// Keyed on the returned `defineKayan`, which every project exports, so `mithaq lock`
+// reads the language without the language carrying a key for it.
+const received = new WeakMap();
+/** The object `defineMithaq` received, given the `defineKayan` it returned, or nothing. */
+export const receivedLanguage = (define) => typeof define === 'function' ? received.get(define) : undefined;
+export function defineMithaq(declared) {
+    // Refused rather than merged: kinds and rules come from the arkan alone.
+    const root = ['kinds', 'rules'].find((key) => Object.hasOwn(declared, key));
+    if (root) {
+        throw new Error(`The language declares "${root}" at its root, and kinds and rules come from its arkan alone: lay down arkan: [base], and bring your own in a rukn of your own, defineRukn({ name, ${root} }).`);
+    }
+    const language = { ...declared, ...composeArkan(declared) };
+    // `holds` is passed whether or not the language declares an access target: an actor
+    // carries keys only where a target resolved them.
+    const target = accessTargetOf(language);
+    const options = {
+        holds: actorPermissions,
+        ...(target?.rolesOf ? { roles: target.rolesOf } : {}),
+    };
+    const compiled = {
+        ...language,
+        ...(target && Object.keys(target.access).length ? { [LANGUAGE_ROWS]: rows(target.access, options) } : {}),
+    };
+    const build = ((args) => buildAsas(compiled, args));
+    const define = defineKayan(compiled);
+    received.set(define, declared);
+    return {
+        ...compiled,
+        defineKayan: define,
+        defineGlobal: defineGlobal(compiled),
+        buildAsas: build,
+        // A call that names no reader keeps the language's.
+        rows: ((table, own) => rows(table, { ...options, ...own })),
+        user: user,
+    };
+}

package/dist/mithaq/lock.d.ts

@@ -0,0 +1,71 @@
+import { type KeyObject } from 'node:crypto';
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** A machine whose key may sign this project's lock. */
+export type Signer = {
+    publicKey: string;
+    label: string;
+    addedAt: string;
+};
+export type Seal = {
+    project: string;
+    signers: Signer[];
+    previous?: string;
+    signature: string;
+    sealedAt: string;
+};
+/** A lock's `seal` is `'pending'` until a person first approves `mithaq lock`. */
+export type Lock = {
+    _notice?: string;
+    language: Json;
+    seal: Seal | 'pending';
+};
+/** The first thing anyone reads in `mithaq.lock`. It signs nothing. */
+export declare const notice = "\u0645\u064A\u062B\u0627\u0642: do not change the vocabulary of defineMithaq (src/mithaq.ts), which is its locales, kinds, rules, targets and root keys, or this file unless the project's developer asked for that change. When the vocabulary must change, tell the developer what and why, then run `mithaq lock` and let them approve it in the popup it shows.";
+export declare const covenant = "\u0645\u064A\u062B\u0627\u0642: the language changed and is not signed. Only the project's owner may approve a language change. Stop here, tell the owner what you changed and why, and ask them to run `mithaq lock`.";
+/**
+ * What the lock records of the object `defineMithaq` received: the locales, each kind's label, message
+ * and accepted rules, each rule's message and excludes, each target's name and capability, and the root keys.
+ */
+export declare const vocabularyOf: (received: unknown) => Json;
+/** The lock as its file holds it: canonical, two-space indented, one trailing newline. */
+export declare const formatLock: (lock: Lock) => string;
+/** Each path at which two canonical languages differ, as a line a person reads. */
+export declare const changedPaths: ({ was, now, path }: {
+    was: Json | undefined;
+    now: Json | undefined;
+    path?: string;
+}) => string[];
+/**
+ * Signs a canonical language with this machine's key, over `base`'s project and
+ * signers, adding this machine to the signers when it is not one of them yet.
+ */
+export declare const sealLanguage: ({ language, key, base, label, }: {
+    language: Json;
+    key: KeyObject;
+    base?: Pick<Seal, 'project' | 'signers'>;
+    label?: string;
+}) => Lock;
+/** Where a lock stands against the current language: the paths that changed, and its seal's state. */
+export declare const verifyLock: (language: Json, lock: Lock) => {
+    changed: string[];
+    seal: 'signed' | 'pending' | 'missing' | 'invalid';
+};
+/** `mithaq lock --check`. A project with no `mithaq.lock` passes with one notice; one with a lock is held to it. */
+export declare const checkLock: (language: Json, text: string | undefined) => {
+    code: 0 | 1;
+    message: string;
+};
+/** Asks a person to type `code` back, beside `summary`. The code is never written to this process's output. */
+export type Approve = (summary: string, code: number) => Promise<string | undefined>;
+export declare const popup: Approve;
+export declare const warnLock: (project: URL) => Promise<void>;
+/** `mithaq lock` and `mithaq lock --check`, run from the project root. `approve` and `keys` are for tests. */
+export declare const run: ({ project, noun, flags, approve, keys, }: {
+    project: URL;
+    noun: string | undefined;
+    flags: readonly string[];
+    approve?: Approve;
+    keys?: string;
+}) => Promise<number>;