@drhomet/mithaq 0.0.0-stage → 0.1.1

package/dist/asas/runner/bulk.d.ts

@@ -0,0 +1,20 @@
+import { type ResolvedOperation, type WriteTools } from './steps.ts';
+import { type Authorize, type ManagedAdmin, type Options } from './write.ts';
+import type { ResolvedKayan } from '../../mithaq/types.ts';
+import type { Store } from '../../mithaq/language.ts';
+export type SingleWrite<Actor> = (data: Record<string, unknown>, options?: Options<Actor>) => Promise<unknown>;
+export declare const bulk: <Actor = unknown>({ kayan, declaration, tools, store, single, cap, bulkLimit: ceiling, authorize, admin, tenantOf, }: {
+    kayan: ResolvedKayan;
+    declaration: ResolvedOperation;
+    tools: WriteTools<unknown, Actor>;
+    store: Store;
+    single: SingleWrite<Actor>;
+    cap: number;
+    /**
+     * The most rows one call may match, the service target's `bulkLimit`.
+     */
+    bulkLimit: number;
+    authorize: Authorize;
+    admin?: ManagedAdmin<Actor>;
+    tenantOf: (actor: unknown) => string | undefined;
+}) => (given: Record<string, unknown>, options?: Options<Actor>) => Promise<Record<string, unknown>>;

package/dist/asas/runner/bulk.js

@@ -0,0 +1,191 @@
+// One transaction for every row: a row that cannot be written rolls the whole call
+// back, because a bulk that half happened is a state no client can undo.
+import { AfterCommitError, AsasError, invalid } from './errors.js';
+import { assertReadableWhere, checkedWhere } from './read.js';
+import { running } from './runtime.js';
+import { refuseTenantOption, writeTenant } from './tenant.js';
+import { atEffect, parse, validated } from './steps.js';
+import { aliveWhere, beginWrite, drain, ontoRow, projectReadableFields, publishedWhere, runOutside } from './write.js';
+import { combineWhere } from '../../mithaq/where.js';
+// The bulk's own key is asked once, then each row goes through the single-row
+// write, which asks its own key and field access: no key grants more through a bulk.
+export const bulk = ({ kayan, declaration, tools, store, single, cap, bulkLimit: ceiling, authorize, admin, tenantOf, }) => async (given, options) => {
+    const list = atEffect(declaration.steps);
+    // Each row lands on the row as it is, so `{ draft: true }` is refused rather than published.
+    if (kayan.versions?.drafts && options?.draft) {
+        throw invalid({
+            message: `Kayan "${kayan.name}" operation "${tools.operation}" writes each row as it is, so it saves no draft. Call it without draft.`,
+            key: 'error.invalid.draft_operation',
+            params: { kayan: kayan.name, operation: tools.operation },
+        });
+    }
+    const { actor, context, entry, open } = beginWrite({ kayan, operation: tools.operation, store, cap, options });
+    refuseTenantOption({ kayan, operation: tools.operation, options });
+    writeTenant({ kayan, active: tenantOf(actor), effect: tools.effect, data: given?.data });
+    // Asked once, before `beforeTransaction`, so a refused actor runs no outside step.
+    const accessWhere = await authorize({
+        admin,
+        actor,
+        data: {},
+        effect: tools.effect,
+        kayan,
+        kind: tools.kind,
+        operation: tools.operation,
+    });
+    // Checked before the transaction opens, so a value a column refuses is a 400 no store was asked for.
+    if (given?.where !== undefined)
+        await checkedWhere(kayan, given.where);
+    let values = given;
+    if (declaration.beforeTransaction.length) {
+        const before = await runOutside({
+            kayan,
+            tools,
+            slot: 'beforeTransaction',
+            list: atEffect(declaration.beforeTransaction),
+            start: { kayan, data: { ...given }, actor, user: actor, tx: undefined, context },
+            around: { context, user: actor },
+        });
+        values = before.data;
+    }
+    let committed;
+    const many = async (data, tx) => {
+        const callerWhere = await assertReadableWhere({ kayan, where: data.where, actor, authorize, admin });
+        // Required here: a bulk with no `where` would be every row the access admits.
+        if (!callerWhere) {
+            throw invalid({
+                message: `Kayan "${kayan.name}" operation "${tools.operation}" needs a "where", because a bulk write with none would change every row the access admits.`,
+                key: 'error.invalid.bulk_where',
+                params: { kayan: kayan.name, operation: tools.operation },
+            });
+        }
+        // An update naming no column would move each row's `updatedAt` and keep a version
+        // for no edit. Asked after the steps, since a step may fill `data`.
+        if (tools.kind === 'updateMany' && !Object.keys((data.data ?? {})).length) {
+            throw invalid({
+                message: `Kayan "${kayan.name}" operation "${tools.operation}" was handed no "data", so there is nothing to change.`,
+                key: 'error.invalid.empty_update',
+                params: { kayan: kayan.name, operation: tools.operation },
+            });
+        }
+        // The rows a plain read shows, so a bulk never reaches a draft that was never published.
+        const where = combineWhere(combineWhere(callerWhere, accessWhere), publishedWhere(kayan));
+        // `lock: 'update'` holds every matched row until commit; the limit is the ceiling,
+        // and `totalDocs` counts the whole matched set without reading it.
+        const found = await store.find({
+            kayan: kayan.name,
+            args: { limit: ceiling, page: 1, lock: 'update', sort: { field: 'id', direction: 'asc' }, where },
+            tx,
+        });
+        // Refused rather than written in part: a caller could not tell which rows a partial
+        // bulk wrote. The caller narrows its `where` instead.
+        if (found.totalDocs > ceiling) {
+            throw invalid({
+                message: `Kayan "${kayan.name}" operation "${tools.operation}" matched ${found.totalDocs} rows, and a bulk write holds at most ${ceiling} in one transaction. Narrow the "where" and run it again.`,
+                key: 'error.invalid.bulk_limit',
+                params: { kayan: kayan.name, operation: tools.operation, matched: found.totalDocs, ceiling },
+            });
+        }
+        const values = (data.data ?? {});
+        const docs = [];
+        // In order, not in parallel: each write joins this transaction, which is one connection.
+        for (const row of found.docs) {
+            // Onto the row as it is, never its pending draft.
+            docs.push((await single({ ...values, id: row.id }, { actor: actor ?? undefined, [ontoRow]: true })));
+        }
+        // Unpublished rows the `where` names are left alone and reported under `errors`, so a
+        // person who ticked one is told; only to an actor who may read drafts, and only rows its answer admits.
+        const admits = kayan.versions?.drafts
+            ? await authorize({ admin, actor, data: {}, effect: 'read', kayan, operation: 'findVersions' }).then((where) => ({ where }), (thrown) => {
+                if (thrown instanceof AsasError && thrown.status === 403)
+                    return undefined;
+                throw thrown;
+            })
+            : undefined;
+        const unpublished = admits
+            ? (await store.find({
+                kayan: kayan.name,
+                args: { limit: ceiling, page: 1, sort: { field: 'id', direction: 'asc' }, where: combineWhere(combineWhere(callerWhere, accessWhere), combineWhere(aliveWhere(kayan), combineWhere({ _status: { not_equals: 'published' } }, admits.where))) },
+                tx,
+            })).docs
+            : [];
+        return {
+            docs,
+            errors: unpublished.map((row) => ({ id: row.id, message: `Kayan "${kayan.name}" row is not published, so operation "${tools.operation}" left it as it is. Publish it first.` })),
+        };
+    };
+    const run = (tx) => {
+        entry.tx = tx;
+        return running.run({ context, transactions: new Map(open).set(store, entry), user: actor }, async () => {
+            const runTools = Object.freeze({ ...tools, many: (data) => many(data, tx) });
+            let ctx = { kayan, data: { ...values }, actor, user: actor, tx, context };
+            // No defaults here: each row's single-row write fills its own.
+            ctx = await parse({ schema: runTools.schema, ctx, tools: runTools });
+            for (const step of atEffect([
+                ...declaration.beforeSteps,
+                ...list,
+                ...declaration.afterSteps,
+            ]))
+                ctx = await step(ctx, runTools);
+            committed = ctx;
+            // Each document already passed its single-row output and read mask.
+            // The bulk contract validates the envelope after the steps have run.
+            if (!tools.publicOutput)
+                return ctx.data;
+            const parsed = await validated(tools.publicOutput, ctx.data);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new Error(`Kayan "${kayan.name}" custom bulk output must return an object.`);
+            }
+            const result = parsed;
+            if ('docs' in result) {
+                if (!Array.isArray(result.docs))
+                    throw new Error(`Kayan "${kayan.name}" custom bulk output must return docs as an array.`);
+                for (const doc of result.docs) {
+                    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+                        throw new Error(`Kayan "${kayan.name}" custom bulk output must return row objects.`);
+                    const visible = await projectReadableFields({ kayan, row: doc, actor });
+                    const protectedField = Object.keys(doc).find((key) => !(key in visible));
+                    if (protectedField)
+                        throw new Error(`Kayan "${kayan.name}" custom bulk output returned protected field "${protectedField}" after read projection.`);
+                }
+            }
+            return result;
+        });
+    };
+    const afterCommit = async () => {
+        if (!declaration.afterCommit.length || !committed)
+            return;
+        await runOutside({
+            kayan,
+            tools,
+            slot: 'afterCommit',
+            list: atEffect(declaration.afterCommit),
+            start: { ...committed, tx: undefined },
+            around: { context, user: actor },
+        });
+    };
+    const joined = open.get(store);
+    if (joined) {
+        const result = await run(joined.tx);
+        if (declaration.afterCommit.length)
+            joined.afterCommit = [...(joined.afterCommit ?? []), afterCommit];
+        return result;
+    }
+    let result;
+    try {
+        result = await store.transaction(run);
+    }
+    finally {
+        entry.settled = true;
+    }
+    try {
+        await drain([...(entry.afterCommit ?? []), afterCommit]);
+    }
+    catch (cause) {
+        // Only the outermost operation answers with what it committed; under an outer one
+        // the failure climbs as a plain `Error`.
+        if (running.getStore())
+            throw cause;
+        throw new AfterCommitError(result, cause);
+    }
+    return result;
+};

package/dist/asas/runner/errors.d.ts

@@ -0,0 +1,60 @@
+export declare const codes: {
+    readonly 400: 'BAD_REQUEST';
+    readonly 401: 'UNAUTHORIZED';
+    readonly 403: 'FORBIDDEN';
+    readonly 404: 'NOT_FOUND';
+    readonly 409: 'CONFLICT';
+    readonly 429: 'TOO_MANY_REQUESTS';
+    readonly 503: 'SERVICE_UNAVAILABLE';
+};
+/**
+ * A refusal the caller caused, with the HTTP status, a message `key` a client
+ * translates, and the `params` the message names. The English message is for logs.
+ */
+export declare class AsasError extends Error {
+    readonly status: 400 | 403 | 404 | 409;
+    readonly key: MessageKey;
+    readonly params: Readonly<Record<string, unknown>>;
+    constructor(message: string, status: 400 | 403 | 404 | 409, key: MessageKey, params?: Record<string, unknown>, cause?: unknown);
+}
+/** A write committed, but one or more callbacks that followed it failed. */
+export declare class AfterCommitError extends Error {
+    readonly committed = true;
+    readonly result: unknown;
+    constructor(result: unknown, cause: unknown);
+}
+/** Something a project is told that is expected rather than a failure, handed to the same `onError`. */
+export declare class Notice extends Error {
+    name: string;
+}
+/** A generic wire signal; callback details remain in the server reporter. */
+export declare const afterCommitHeader = "x-mithaq-after-commit";
+/** A refusal's key in the message namespace. */
+export type MessageKey = `error.${'conflict' | 'forbidden' | 'invalid' | 'not_found'}.${string}`;
+/** What every refusal takes: the English a log reads, the key a client translates, the values it names, and the cause. */
+export type Refusal = {
+    message: string;
+    key: MessageKey;
+    params?: Record<string, unknown>;
+    cause?: unknown;
+};
+/** The caller may not do this. */
+export declare const denied: ({ message, key, params, cause }: Refusal) => AsasError;
+/** The caller sent something the schema or the shape refuses. */
+export declare const invalid: ({ message, key, params, cause }: Refusal) => AsasError;
+/**
+ * The row the caller addressed is not there. An absent row and one access
+ * excludes answer alike, so a 404 never says which.
+ */
+export declare const missing: ({ message, key, params, cause }: Refusal) => AsasError;
+/**
+ * The write collides with a row already there, as a 409 so an offline client
+ * does not retry it. It never says which column or whose row it hit.
+ */
+export declare const conflict: ({ message, key, params, cause }: Refusal) => AsasError;
+export declare const localizedQuery: ({ kayan, field, what, locales, }: {
+    kayan: string;
+    field: string;
+    what: 'filter' | 'sort';
+    locales?: readonly string[];
+}) => string;

package/dist/asas/runner/errors.js

@@ -0,0 +1,59 @@
+// Both HTTP plugs read the code from here, so a refusal answers the same through either.
+export const codes = {
+    400: 'BAD_REQUEST',
+    401: 'UNAUTHORIZED',
+    403: 'FORBIDDEN',
+    404: 'NOT_FOUND',
+    409: 'CONFLICT',
+    429: 'TOO_MANY_REQUESTS',
+    503: 'SERVICE_UNAVAILABLE',
+};
+/**
+ * A refusal the caller caused, with the HTTP status, a message `key` a client
+ * translates, and the `params` the message names. The English message is for logs.
+ */
+export class AsasError extends Error {
+    status;
+    key;
+    params;
+    constructor(message, status, key, params = {}, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.status = status;
+        this.key = key;
+        this.params = params;
+    }
+}
+/** A write committed, but one or more callbacks that followed it failed. */
+export class AfterCommitError extends Error {
+    committed = true;
+    result;
+    constructor(result, cause) {
+        super('The write committed, but an afterCommit step failed.', { cause });
+        this.result = result;
+    }
+}
+/** Something a project is told that is expected rather than a failure, handed to the same `onError`. */
+export class Notice extends Error {
+    name = 'Notice';
+}
+/** A generic wire signal; callback details remain in the server reporter. */
+export const afterCommitHeader = 'x-mithaq-after-commit';
+/** The caller may not do this. */
+export const denied = ({ message, key, params, cause }) => new AsasError(message, 403, key, params, cause);
+/** The caller sent something the schema or the shape refuses. */
+export const invalid = ({ message, key, params, cause }) => new AsasError(message, 400, key, params, cause);
+/**
+ * The row the caller addressed is not there. An absent row and one access
+ * excludes answer alike, so a 404 never says which.
+ */
+export const missing = ({ message, key, params, cause }) => new AsasError(message, 404, key, params, cause);
+/**
+ * The write collides with a row already there, as a 409 so an offline client
+ * does not retry it. It never says which column or whose row it hit.
+ */
+export const conflict = ({ message, key, params, cause }) => new AsasError(message, 409, key, params, cause);
+// Shared by the read layer, which answers the caller with a 400, and the drizzle
+// store, which throws at the access callback that built the query.
+export const localizedQuery = ({ kayan, field, what, locales = [], }) => what === 'sort'
+    ? `Kayan "${kayan}" field "${field}" is localized, so it is one column per locale and no sort can name it. A sort that names one locale is not built. Name a field that is not localized, or read the rows and pick the locale in the app.`
+    : `Kayan "${kayan}" field "${field}" is localized, so it is one column per locale and no filter can name the field itself. Name the locale as a second path segment instead, ${locales.map((locale) => `"${field}.${locale}"`).join(' or ')}. That path is one hop only, so a localized field reached across a relationship cannot name its locale.`;

package/dist/asas/runner/read.d.ts

@@ -0,0 +1,68 @@
+import { type Authorize, type ManagedAdmin, type ReadOptions } from './write.ts';
+import { type Where } from '../../mithaq/where.ts';
+import { type AuditHandler, type ReadTools, type ResolvedOperation } from './steps.ts';
+import type { StandardSchemaV1 } from '../../mithaq/standard-schema.ts';
+import { type ResolvedKayan } from '../../mithaq/types.ts';
+import type { Store } from '../../mithaq/language.ts';
+import { type TenantScope } from './tenant.ts';
+/** What a `find` list takes where it declares no input of its own. */
+export type FindInput = {
+    /** How far a read populates its `join` fields: 0 populates nothing, each level through the child kayan's own managed read. */
+    depth?: number;
+    limit?: number;
+    page?: number;
+    sort?: string;
+    where?: Where;
+};
+export type Paginated<Row> = {
+    docs: Row[];
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+    limit: number;
+    nextPage: number | null;
+    page: number;
+    pagingCounter: number;
+    prevPage: number | null;
+    totalDocs: number;
+    totalPages: number;
+};
+export type ReaderMap<Actor = unknown> = {
+    operation: (args: {
+        name: string;
+        declaration: ResolvedOperation;
+        input: StandardSchemaV1;
+        output: StandardSchemaV1;
+        /** What a draft or a version is read back through, where the kayan keeps drafts or versions. */
+        draftOutput?: StandardSchemaV1;
+    }) => (data?: Record<string, unknown>, options?: ReadOptions<Actor>) => Promise<Record<string, unknown> | null | Paginated<Record<string, unknown>>>;
+};
+export declare const assertReadableWhere: <Actor>({ kayan, where, actor, authorize, admin, }: {
+    kayan: ResolvedKayan;
+    where: Where | undefined;
+    actor: Actor | null;
+    authorize: Authorize;
+    admin?: ManagedAdmin<Actor>;
+}) => Promise<Where | undefined>;
+/** The caller's own `where`, refused as a 400 where its grammar is malformed or a value is not of its column's kind. */
+export declare const checkedWhere: (kayan: ResolvedKayan, where: unknown) => Promise<Where>;
+export declare const readers: <Actor>({ kayan, store, cap, defaultLimit, joinLimit, admin, authorize, kayans, of, audit, catalog, openTenant, }: {
+    kayan: ResolvedKayan;
+    store: Store;
+    cap: number;
+    /** The service target's page where a caller names none. */
+    defaultLimit: number;
+    /** The service target's join page where a join field names none. */
+    joinLimit: number;
+    admin: ManagedAdmin<Actor> | undefined;
+    authorize: Authorize;
+    kayans: (effect: 'read') => unknown;
+    of: ReadTools['of'];
+    audit?: AuditHandler<Actor>;
+    catalog?: readonly string[];
+    /** Reads a read's `tenant` option into the scope every managed call under it keeps. */
+    openTenant: (args: {
+        actor: unknown;
+        reach: unknown;
+        kayan: ResolvedKayan;
+    }) => Promise<TenantScope | undefined>;
+}) => ReaderMap<Actor>;