@drhomet/mithaq 0.0.0-stage → 0.2.0

package/dist/mithaq/rows.d.ts

@@ -0,0 +1,87 @@
+import { type Ref } from './user.ts';
+import { type Operator, type Scalar } from './where.ts';
+import type { Access, FieldAccess } from './types.ts';
+export type RowOperation = 'create' | 'delete' | 'read' | 'update';
+/** What a row compares a field with: a literal, or a reference to the actor's value at one key, resolved before the store sees it. */
+export type RowFieldWhere = Partial<Record<Operator, Scalar | Scalar[] | boolean | Ref>>;
+/** A `Where` whose paths are the kayan's field names plus one relationship hop. */
+export type RowWhere<Paths extends string = string> = {
+    and: readonly RowWhere<Paths>[];
+} | {
+    or: readonly RowWhere<Paths>[];
+} | {
+    [Path in Paths]?: RowFieldWhere;
+};
+type NonEmpty<Answer> = Answer extends boolean | readonly unknown[] ? Answer : keyof Answer extends never ? never : Answer;
+/** A row table checked before it compiles: the role keys, and no empty `Where`. `'*'` is the row every assigned actor gets beside its own. */
+export type CheckedTable<Table, Role extends string = string> = {
+    [Key in keyof Table]: Key extends '*' | Role ? {
+        [Answer in keyof Table[Key]]: NonEmpty<Table[Key][Answer]>;
+    } : never;
+};
+/** `'*'`, a field name, or `!name`. A row that names no list means `['*']`. */
+export type FieldList<Names extends string = string> = '*' | Names | `!${Names}`;
+/** What one role may do. Every key is optional, and a missing one denies. */
+export type AccessRow<Paths extends string = string, Names extends string = string> = {
+    /** Only `true` allows: the runner denies any create answer that is not `true`. */
+    create?: boolean;
+    delete?: boolean | RowWhere<Paths>;
+    fields?: readonly FieldList<Names>[];
+    /**
+     * The catalog keys this role holds, `${kayan}.${operation}` or `${kayan}.fields.${field}`, or `'*'`.
+     * Read only where the build declares no access target; a key outside the catalog fails the build.
+     */
+    permissions?: '*' | readonly string[];
+    read?: boolean | RowWhere<Paths>;
+    update?: boolean | RowWhere<Paths>;
+};
+export type RowTable<Names extends string = string> = Record<string, AccessRow<string, Names>>;
+export type RowsOptions<Actor = unknown> = {
+    /** What the build's access target resolved this actor holds; where it answers, it decides. */
+    holds?: (user: Actor) => Held;
+    /** Where an actor's roles are read from. Defaults to `user.roles`. */
+    roles?: (user: Actor) => readonly string[];
+};
+/** What an actor holds: `true` for every key, a set of keys, or nothing where no store grades and the row answers decide alone. */
+export type Held = true | ReadonlySet<string> | undefined;
+/** What `rows()` returns: the floor's access object, and the rows it came from. */
+export type Rows<Table extends RowTable = RowTable> = {
+    create: Access;
+    delete: Access;
+    read: Access;
+    update: Access;
+    /** The three callbacks the field named `name` gets from these rows; without `kayan` a grading table denies the field. */
+    fields(name: string, kayan?: string): {
+        create: FieldAccess;
+        read: FieldAccess;
+        update: FieldAccess;
+    };
+    /** The keys this kayan's own rows hold for the actor. */
+    permissions(user: unknown): Held;
+    /** Which of these rows applied to an actor, so an error can name them. */
+    roles(user: unknown): string[];
+    /** The rows as written, so a tool can read them without running a callback. */
+    rows: Table;
+};
+/** The rows behind an access object, or nothing for hand-written callbacks. */
+export declare const rowsOf: (access: unknown) => Rows | undefined;
+/** The rows behind a field callback, or nothing for a hand-written one. */
+export declare const rowsOfField: (access: unknown) => Rows | undefined;
+export declare const declaredFieldAccess: (access: unknown) => unknown;
+export declare const admissions: (fields: readonly string[] | undefined) => readonly string[];
+/**
+ * Compiles a row per role onto the floor's callbacks: no applicable row denies, a `false` in any denies,
+ * a `true` with no `false` allows, and several filters admit a row any one of them admits.
+ */
+export declare const rows: <const Table extends RowTable>(table: Table & CheckedTable<Table>, options?: RowsOptions) => Rows<Table>;
+/** The access object a kayan gets from its rows, with the callbacks it declared beside them ANDed on. */
+export declare const applyRows: (compiled: Rows, declared?: Record<string, unknown>) => Record<string, unknown>;
+export declare const rowFields: ({ compiled, name, declared, kayan }: {
+    compiled: Rows;
+    name: string;
+    declared?: Record<string, unknown>;
+    kayan?: string;
+}) => {
+    [k: string]: FieldAccess;
+};
+export {};

package/dist/mithaq/rows.js

@@ -0,0 +1,174 @@
+import { isRef, refuseLiteral } from './user.js';
+import { combineWhere } from './where.js';
+// A marker, not a security boundary. A symbol, so no field name collides with it
+// and an object spread still carries it.
+const ROWS = Symbol('mithaq.rows');
+const rowFieldAccess = new WeakMap();
+/** The rows behind an access object, or nothing for hand-written callbacks. */
+export const rowsOf = (access) => access && typeof access === 'object' ? access[ROWS] : undefined;
+/** The rows behind a field callback, or nothing for a hand-written one. */
+export const rowsOfField = (access) => typeof access === 'function' ? rowFieldAccess.get(access) : undefined;
+const narrowedFrom = new WeakMap();
+// The narrowed callback never admits more than the declared one, so a check that
+// a field kept a shipped callback reads the declared one here.
+export const declaredFieldAccess = (access) => {
+    while (typeof access === 'function' && narrowedFrom.has(access))
+        access = narrowedFrom.get(access);
+    return access;
+};
+// A row naming nothing admits every field, and a list of only exclusions means every
+// other field. Shared with `buildAsas`, so a build and a request never read one list two ways.
+export const admissions = (fields) => {
+    const list = fields ?? ['*'];
+    return list.some((entry) => !entry.startsWith('!')) ? list : ['*', ...list];
+};
+const deepFreeze = (value, seen = new WeakSet()) => {
+    if (!value || typeof value !== 'object' || seen.has(value))
+        return;
+    seen.add(value);
+    Object.freeze(value);
+    for (const nested of Object.values(value))
+        deepFreeze(nested, seen);
+};
+const resolveValue = (value, user) => {
+    if (Array.isArray(value))
+        return value.map((one) => resolveValue(one, user));
+    refuseLiteral(value, 'An access row filter');
+    if (!isRef(value))
+        return value;
+    // An absent or `null` key throws: `{ organization: { equals: null } }` would read every
+    // row with no tenant. An own key only, since a JSON table could name `__proto__`.
+    const actor = user;
+    const found = actor && Object.hasOwn(actor, value.$user) ? actor[value.$user] : undefined;
+    if (found === null || found === undefined) {
+        throw new Error(`Access row filter "user.${value.$user}" found nothing on the actor, so there is no constraint to apply.`);
+    }
+    return found;
+};
+const resolveWhere = (where, user) => Object.fromEntries(Object.entries(where).map(([key, value]) => [
+    key,
+    key === 'and' || key === 'or'
+        ? value.map((one) => resolveWhere(one, user))
+        : Object.fromEntries(Object.entries(value).map(([operator, operand]) => [
+            operator,
+            resolveValue(operand, user),
+        ])),
+]));
+/** Both answers applied, so a callback beside rows may narrow and never widen. */
+const and = (left, right) => async (args) => {
+    const first = await left(args);
+    if (!first)
+        return false;
+    const second = await right(args);
+    if (!second)
+        return false;
+    if (first === true)
+        return second;
+    if (second === true)
+        return first;
+    return combineWhere(first, second);
+};
+const andField = (left, right) => async (args) => !!(await left(args)) && !!(await right(args));
+const operations = ['create', 'delete', 'read', 'update'];
+/**
+ * Compiles a row per role onto the floor's callbacks: no applicable row denies, a `false` in any denies,
+ * a `true` with no `false` allows, and several filters admit a row any one of them admits.
+ */
+export const rows = (table, options) => {
+    // Frozen, nested objects too: a tool handed the table cannot rewrite what the
+    // callbacks answer, and a row's `Where` is read live each time.
+    deepFreeze(table);
+    const written = table;
+    const roles = (user) => {
+        if (!user)
+            return [];
+        const found = options?.roles ? options.roles(user) : user.roles;
+        return Array.isArray(found) ? found.filter((role) => typeof role === 'string') : [];
+    };
+    // An actor with no role takes no row, `'*'` included, so a `Where` naming a key an
+    // anonymous caller does not carry is never resolved.
+    const applicable = (user) => {
+        const assigned = roles(user);
+        if (!assigned.length)
+            return [];
+        const every = written['*'];
+        // An own key only: `constructor` read through the prototype would hand back `Object` as a row.
+        const own = assigned
+            .map((role) => (Object.hasOwn(written, role) ? written[role] : undefined))
+            .filter((row) => !!row);
+        return every ? [every, ...own] : own;
+    };
+    const answer = (operation) => ({ user }) => {
+        const hits = applicable(user).map((row) => row[operation] ?? false);
+        if (!hits.length || hits.some((hit) => hit === false))
+            return false;
+        if (hits.some((hit) => hit === true))
+            return true;
+        const filters = hits.map((one) => resolveWhere(one, user));
+        return filters.length === 1 ? filters[0] : { or: filters };
+    };
+    const admits = (name, user) => {
+        const lists = applicable(user).map((row) => admissions(row.fields));
+        return (lists.length > 0 &&
+            lists.every((list) => list.includes('*') || list.includes(name)) &&
+            !lists.some((list) => list.includes(`!${name}`)));
+    };
+    // A table grades only when some row names `permissions`; otherwise row answers decide.
+    const grades = Object.values(written).some((row) => row.permissions !== undefined);
+    const held = (user) => {
+        if (!grades)
+            return undefined;
+        const hits = applicable(user);
+        if (hits.some((row) => row.permissions === '*'))
+            return true;
+        // Several roles union. A row that names no list contributes nothing rather than everything.
+        return new Set(hits.flatMap((row) => (row.permissions === '*' ? [] : (row.permissions ?? []))));
+    };
+    const heldOf = (user) => options?.holds?.(user) ?? held(user);
+    const holdsField = (kayan, name, user) => {
+        const keys = heldOf(user);
+        if (keys === undefined || keys === true)
+            return true;
+        // The key it would need is one nothing can name.
+        return kayan !== undefined && keys.has(`${kayan}.fields.${name}`);
+    };
+    const compiled = {
+        create: answer('create'),
+        delete: answer('delete'),
+        read: answer('read'),
+        update: answer('update'),
+        fields: (name, kayan) => {
+            const admit = ({ user }) => admits(name, user) && holdsField(kayan, name, user);
+            rowFieldAccess.set(admit, compiled);
+            return { create: admit, read: admit, update: admit };
+        },
+        permissions: held,
+        roles,
+        rows: table,
+    };
+    return Object.assign(compiled, { [ROWS]: compiled });
+};
+/** The access object a kayan gets from its rows, with the callbacks it declared beside them ANDed on. */
+export const applyRows = (compiled, declared) => {
+    const merged = { ...declared, [ROWS]: compiled, rows: compiled.rows };
+    delete merged.tenant;
+    for (const operation of operations) {
+        const own = declared?.[operation];
+        merged[operation] = own && own !== compiled[operation] ? and(compiled[operation], own) : compiled[operation];
+    }
+    return merged;
+};
+// Marked as coming from rows, so a write the field's own callback denies throws the
+// naming error rather than dropping silently.
+export const rowFields = ({ compiled, name, declared, kayan }) => {
+    const admit = compiled.fields(name, kayan);
+    return Object.fromEntries(Object.entries(admit).map(([operation, callback]) => {
+        const own = declared?.[operation];
+        if (!own)
+            return [operation, callback];
+        const narrowed = andField(callback, own);
+        rowFieldAccess.set(narrowed, compiled);
+        narrowedFrom.set(narrowed, own);
+        return [operation, narrowed];
+    }));
+};

package/dist/mithaq/rukn.d.ts

@@ -0,0 +1,72 @@
+import type { Kind } from '../base/kinds.ts';
+import type { Rule } from '../base/rules.ts';
+import type { RuntimeTarget } from './language.ts';
+export type Rukn = {
+    readonly name: string;
+    readonly kinds?: Readonly<Record<string, Kind>>;
+    readonly rules?: Readonly<Record<string, Rule>>;
+    readonly targets?: Readonly<Record<string, RuntimeTarget>>;
+    readonly needs?: readonly string[];
+};
+/** Declares a rukn, one pillar of capability (kinds, rules, targets and what it needs), keeping its literal types. */
+export declare const defineRukn: <const R extends Rukn>(rukn: R) => R;
+/** What a kayan writes under one of the build's targets, by that target's `type`; each target's folder augments it. */
+export interface KayanConfigs<L, F, T> {
+}
+/** What a kayan writes under target `T` of language `L`, by `T`'s type. */
+export type KayanConfigOf<L, F, T> = T extends {
+    readonly type: infer Type;
+} ? Type extends keyof KayanConfigs<L, F, T> ? KayanConfigs<L, F, T>[Type] : unknown : unknown;
+type U2I<U> = (U extends unknown ? (u: U) => void : never) extends (i: infer I) => void ? I : never;
+type Index<A> = keyof A & `${number}`;
+type Brought<R, K extends 'kinds' | 'rules' | 'targets'> = R extends {
+    readonly [P in K]: infer X extends object;
+} ? X : {};
+/** Every rukn's `K`, as one record. */
+export type ArkanOf<A extends readonly Rukn[], K extends 'kinds' | 'rules' | 'targets'> = U2I<{
+    [I in Index<A>]: Brought<A[I], K>;
+}[Index<A>]> & Record<never, never>;
+/** The names of `K` that two arkan of `A` both bring. */
+type Twice<A extends readonly Rukn[], K extends 'kinds' | 'rules' | 'targets'> = {
+    [I in Index<A>]: keyof Brought<A[I], K> & {
+        [J in Index<A>]: J extends I ? never : keyof Brought<A[J], K>;
+    }[Index<A>];
+}[Index<A>] & string;
+type CapabilitiesOf<Targets> = {
+    [Name in keyof Targets]: Targets[Name] extends {
+        readonly capability: infer Capability extends string;
+    } ? Capability : never;
+}[keyof Targets];
+export type ArkanRefusals<A extends readonly Rukn[], Targets> = {
+    [Name in Twice<A, 'kinds'> as `kind "${Name}" is claimed by two arkan`]: never;
+} & {
+    [Name in Twice<A, 'rules'> as `rule "${Name}" is claimed by two arkan`]: never;
+} & {
+    [Name in Twice<A, 'targets'> as `target "${Name}" is built by two arkan`]: never;
+} & {
+    [Clash in {
+        [I in Index<A>]: `target "${keyof Brought<A[I], 'targets'> & keyof Targets & string}" is laid down by the project and built by rukn "${A[I]['name']}"`;
+    }[Index<A>]]: never;
+} & {
+    [Need in {
+        [I in Index<A>]: A[I] extends {
+            readonly needs: readonly (infer N extends string)[];
+        } ? `rukn "${A[I]['name']}" needs a target of capability "${Exclude<N, CapabilitiesOf<Targets & ArkanOf<A, 'targets'>>>}"` : never;
+    }[Index<A>]]: never;
+};
+export declare const composeArkan: ({ arkan, targets }: {
+    arkan?: readonly Rukn[];
+    targets?: Readonly<Record<string, RuntimeTarget>>;
+}) => {
+    kinds: Record<string, Kind>;
+    rules: Record<string, Rule>;
+    targets: Record<string, RuntimeTarget>;
+};
+export declare const implementationOf: <Built>({ table, shipped, name, own, type, }: {
+    table: Readonly<Record<string, Built>>;
+    shipped?: Readonly<Record<string, unknown>>;
+    name: string;
+    own: Readonly<Record<string, unknown>> | undefined;
+    type: string | undefined;
+}) => Built | undefined;
+export {};

package/dist/mithaq/rukn.js

@@ -0,0 +1,15 @@
+/** Declares a rukn, one pillar of capability (kinds, rules, targets and what it needs), keeping its literal types. */
+export const defineRukn = (rukn) => rukn;
+// Refuses nothing, so a clash still reaches `buildAsas`, which names both sides.
+export const composeArkan = ({ arkan = [], targets }) => ({
+    kinds: Object.assign({}, ...arkan.map((rukn) => rukn.kinds)),
+    rules: Object.assign({}, ...arkan.map((rukn) => rukn.rules)),
+    targets: Object.assign({}, ...arkan.map((rukn) => rukn.targets), targets),
+});
+// First match wins: the project's own entry in the target's table, then the kind's own, then the shipped one.
+export const implementationOf = ({ table, shipped, name, own, type, }) => {
+    const entry = Object.hasOwn(table, name) ? table[name] : undefined;
+    if (entry !== undefined && entry !== shipped?.[name])
+        return entry;
+    return (type !== undefined && own && Object.hasOwn(own, type) ? own[type] : undefined) ?? entry;
+};

package/dist/mithaq/standard-schema.d.ts

@@ -0,0 +1,38 @@
+/** Anything a schema target derives or a developer writes: one `~standard` member. */
+export type StandardSchemaV1<Input = unknown, Output = Input> = {
+    readonly '~standard': StandardSchemaProps<Input, Output>;
+};
+/**
+ * What `~standard` carries: the version of the interface, the name of the
+ * library that made the schema, the one call that validates, and the two types
+ * the schema names for a reader, which exist only at compile time.
+ */
+export type StandardSchemaProps<Input = unknown, Output = Input> = {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown, options?: {
+        readonly libraryOptions?: Record<string, unknown> | undefined;
+    }) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    readonly types?: {
+        readonly input: Input;
+        readonly output: Output;
+    } | undefined;
+};
+/** The value, or the reasons there is none. The absence of issues is success. */
+export type StandardSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly StandardSchemaIssue[];
+};
+/** One reason: the message a caller reads, and where in the value it happened. */
+export type StandardSchemaIssue = {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        readonly key: PropertyKey;
+    })[] | undefined;
+};
+/** The value a schema takes, before its own transforms run. */
+export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+/** The value a schema returns, after them. */
+export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];

package/dist/mithaq/standard-schema.js

@@ -0,0 +1,2 @@
+// The Standard Schema v1 types, vendored: the spec package ships nothing but these.
+export {};