@drhomet/mithaq 0.0.0-stage → 0.2.0

package/dist/asas/runner/errors.js

@@ -0,0 +1,75 @@
+// 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',
+    413: 'PAYLOAD_TOO_LARGE',
+    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 cannot complete, as a 409. Its key says whether trying again can help.
+ * It never says which column or whose row it hit.
+ */
+export const conflict = ({ message, key, params, cause }) => new AsasError(message, 409, key, params, cause);
+/** A transaction the database rolled back may be retried, without exposing its query or rows. */
+export const retryConflict = (thrown) => {
+    if (thrown instanceof AsasError || thrown instanceof AfterCommitError)
+        return thrown;
+    const seen = new Set();
+    for (let cause = thrown; cause && typeof cause === 'object' && !seen.has(cause); cause = cause.cause) {
+        if (cause instanceof AfterCommitError)
+            return thrown;
+        seen.add(cause);
+        if (['40P01', '40001'].includes(String(cause.code))) {
+            return conflict({ message: 'The transaction conflicted with another write. Try again.', key: 'error.conflict.retry', cause: thrown });
+        }
+    }
+    return thrown;
+};
+// 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,72 @@
+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 ResolvedField, 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, tenantOf, pickers, }: {
+    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>;
+    /** The organization the actor's session names, which a step reads as `ctx.tenant`. */
+    tenantOf: (actor: unknown) => string | undefined;
+    /** Every relationship field pointing at this kayan, by `<kayan>.<field>`, which a picker's read names as `for`. */
+    pickers?: Readonly<Record<string, ResolvedField>>;
+}) => ReaderMap<Actor>;