@aventara/core 1.0.0-rc.0 → 1.0.0-rc.2

package/dist/runtime/context-executor.runtime.js

@@ -0,0 +1,275 @@
+import { isOperationVariantAvailable } from "../contracts/resource-operations.js";
+import { parseOperationIdentity } from "../operations/operation-identity.js";
+import { validationIssue } from "../operations/validation-code.js";
+import { readSqlTemplate } from "../transactions/sql-statement.js";
+import { normalizeSqlValue } from "../transactions/sql-statement.validator.js";
+import { AvTransactionIntegrityError } from "../transactions/transaction-integrity-error.js";
+import { transactionInfrastructureFailure } from "../transactions/transaction-response.js";
+import { copyAtDoor, refuseCallerData } from "./caller-data.door.js";
+import { createReporter, } from "./diagnostics-reporter.js";
+import { AdapterBoundary, sanitizeOperationFailure } from "./error-boundary.js";
+import { thrownFailure } from "./framework-error.factory.js";
+import { operationFailure } from "./operation-response.js";
+import { mapValidationOutcome } from "./outcome-mapper.js";
+import { readonlyView } from "./readonly-value.js";
+const COMPUTE_STATE = "Compute's ctx.$state";
+const STATE = Symbol("aventara.context");
+const READ_FAMILY = "find";
+function readOnlyRefusal(member) {
+    return new TypeError(`Compute's ctx is read-only: ${member} is not available in a compute stage. Put effects on other rows in an after hook.`);
+}
+function refusedStatement(issues) {
+    return mapValidationOutcome(issues);
+}
+function unavailable(message) {
+    return operationFailure("A2002", {
+        message,
+        issues: [validationIssue("V1006", [], message)],
+    });
+}
+export function createContextExecutor(dependencies) {
+    const { adapter, misuse } = dependencies;
+    const model = dependencies.model;
+    const stateOf = (context) => context[STATE];
+    const reporterOf = (scope) => createReporter(dependencies.diagnostics, {
+        kind: "transaction",
+        origin: "application",
+        requestId: scope.requestId,
+    });
+    const call = async (scope, resource, identity, args) => {
+        const response = await dependencies.run({
+            ...identity,
+            origin: "application",
+            resource,
+            requestId: scope.requestId,
+            state: scope.state,
+            arguments: args === undefined ? {} : args,
+        }, scope.transaction);
+        if (response.cause !== null) {
+            throw thrownFailure(response);
+        }
+        return response.data;
+    };
+    const resourceTree = (scope, resource, readOnly) => {
+        const families = {};
+        const operations = model.resources[resource]?.operations ?? {};
+        for (const [family, variants] of Object.entries(operations)) {
+            if (readOnly && family !== READ_FAMILY) {
+                continue;
+            }
+            const leaves = {};
+            for (const [variant, availability] of Object.entries(variants ?? {})) {
+                const identity = parseOperationIdentity(family, variant);
+                if (identity !== undefined &&
+                    isOperationVariantAvailable(availability)) {
+                    leaves[variant] = (args) => call(scope, resource, identity, args);
+                }
+            }
+            families[family] = Object.freeze(leaves);
+        }
+        if (readOnly) {
+            const tree = Object.create(Object.prototype);
+            for (const [family, leaves] of Object.entries(families)) {
+                Object.defineProperty(tree, family, {
+                    value: leaves,
+                    enumerable: true,
+                });
+            }
+            for (const family of Object.keys(operations)) {
+                if (family === READ_FAMILY) {
+                    continue;
+                }
+                Object.defineProperty(tree, family, {
+                    get() {
+                        throw readOnlyRefusal(`ctx.${resource}.${family}`);
+                    },
+                    enumerable: false,
+                });
+            }
+            return Object.freeze(tree);
+        }
+        return Object.freeze(families);
+    };
+    const statementOf = (strings, values) => {
+        if (adapter.sqlStatements !== true) {
+            return {
+                ok: false,
+                response: unavailable("SQL statements are not available on this Adapter."),
+            };
+        }
+        const text = readSqlTemplate(strings, values.length);
+        if (text === undefined) {
+            return {
+                ok: false,
+                response: refusedStatement([
+                    validationIssue("V1001", ["strings"], "SQL must be written as a tagged template: ctx.$sql`…`."),
+                ]),
+            };
+        }
+        const copy = copyAtDoor([...values]);
+        if (!copy.ok) {
+            return {
+                ok: false,
+                response: refusedStatement([
+                    refuseCallerData(copy.error, ["values"], { origin: "application" }, misuse),
+                ]),
+            };
+        }
+        const bound = [];
+        const issues = [];
+        for (const [position, value] of copy.value.entries()) {
+            const normalized = normalizeSqlValue(value, ["values", position]);
+            if (normalized.ok) {
+                bound.push(normalized.value);
+            }
+            else {
+                issues.push(...normalized.issues);
+            }
+        }
+        if (issues.length > 0) {
+            return { ok: false, response: refusedStatement(issues) };
+        }
+        return { ok: true, statement: { strings: text, values: bound } };
+    };
+    const executeStatement = async (runner, inTransaction, statement, report) => {
+        if (inTransaction && typeof runner.executeSql !== "function") {
+            const error = new AvTransactionIntegrityError("statement-unavailable");
+            report(error, "A3002");
+            throw thrownFailure(transactionInfrastructureFailure());
+        }
+        const boundary = new AdapterBoundary();
+        try {
+            return await boundary.execute(async () => {
+                if (typeof runner.executeSql !== "function") {
+                    throw new TypeError("Adapter declares sqlStatements but has no executeSql.");
+                }
+                const rows = await runner.executeSql(statement);
+                if (!Array.isArray(rows)) {
+                    throw new TypeError("Adapter executeSql must resolve the statement's rows as an array.");
+                }
+                return [...rows];
+            });
+        }
+        catch (error) {
+            throw thrownFailure(sanitizeOperationFailure(error, boundary.originOf(error), report, {
+                path: ["values"],
+                arguments: statement.values,
+            }));
+        }
+    };
+    const openTransaction = async (scope, work) => {
+        if (typeof adapter.transaction !== "function") {
+            throw thrownFailure(unavailable("Transactions are not available on this Adapter."));
+        }
+        let thrown;
+        try {
+            return await adapter.transaction(async (executor) => {
+                try {
+                    return await work(executor);
+                }
+                catch (error) {
+                    thrown = { error };
+                    throw error;
+                }
+            });
+        }
+        catch (error) {
+            if (thrown !== undefined && error === thrown.error) {
+                throw error;
+            }
+            reporterOf(scope)(error, "A3002");
+            throw thrownFailure(transactionInfrastructureFailure());
+        }
+    };
+    const sql = async (scope, strings, values) => {
+        const prepared = statementOf(strings, values);
+        if (!prepared.ok) {
+            throw thrownFailure(prepared.response);
+        }
+        const report = reporterOf(scope);
+        const open = scope.transaction;
+        return open !== undefined
+            ? executeStatement(open, true, prepared.statement, report)
+            : executeStatement(adapter, false, prepared.statement, report);
+    };
+    const contextOf = (prototype, scope, facts, readOnly = false) => {
+        const context = Object.create(prototype);
+        Object.defineProperty(context, STATE, {
+            value: { scope, facts, resources: new Map() },
+        });
+        for (const [key, value] of Object.entries(facts)) {
+            if (value !== undefined) {
+                Object.defineProperty(context, key, { value, enumerable: true });
+            }
+        }
+        Object.defineProperty(context, "$state", {
+            value: readOnly ? readonlyView(scope.state, COMPUTE_STATE) : scope.state,
+            enumerable: true,
+        });
+        return context;
+    };
+    const transactionOf = (prototype) => (context, work) => {
+        const { scope, facts } = stateOf(context);
+        if (typeof work !== "function") {
+            return Promise.reject(new TypeError("ctx.$transaction takes an async callback: (tx) => …"));
+        }
+        const run = work;
+        if (scope.transaction !== undefined) {
+            return (async () => run(context))();
+        }
+        if (dependencies.application.transactions === "none") {
+            return Promise.reject(thrownFailure(unavailable("Transactions are not available on the application Contract.")));
+        }
+        return openTransaction(scope, (executor) => run(contextOf(prototype, {
+            requestId: scope.requestId,
+            transaction: executor,
+            state: scope.state,
+        }, facts)));
+    };
+    const prototypeOf = (readOnly) => {
+        const prototype = {};
+        for (const resource of Object.keys(model.resources)) {
+            Object.defineProperty(prototype, resource, {
+                get() {
+                    const state = stateOf(this);
+                    let tree = state.resources.get(resource);
+                    if (tree === undefined) {
+                        tree = resourceTree(state.scope, resource, readOnly);
+                        state.resources.set(resource, tree);
+                    }
+                    return tree;
+                },
+            });
+        }
+        if (readOnly) {
+            for (const member of ["$sql", "$transaction"]) {
+                Object.defineProperty(prototype, member, {
+                    get() {
+                        throw readOnlyRefusal(`ctx.${member}`);
+                    },
+                });
+            }
+            return Object.freeze(prototype);
+        }
+        const transaction = transactionOf(prototype);
+        Object.defineProperty(prototype, "$sql", {
+            get() {
+                const { scope } = stateOf(this);
+                return (strings, ...values) => sql(scope, strings, values);
+            },
+        });
+        Object.defineProperty(prototype, "$transaction", {
+            get() {
+                return (work) => transaction(this, work);
+            },
+        });
+        return Object.freeze(prototype);
+    };
+    const full = prototypeOf(false);
+    const reads = prototypeOf(true);
+    return {
+        operation: (scope, facts) => contextOf(full, scope, facts),
+        transaction: (scope, facts) => contextOf(full, scope, facts),
+        compute: (scope, facts) => contextOf(reads, scope, facts, true),
+    };
+}

package/dist/runtime/create-requirement.d.ts

@@ -1,101 +1,66 @@
-import type { Contract } from "../contracts/contract.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvCreateRequirements } from "../contracts/create-requirements.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
 import type { ReferentialActionTable } from "./referential-action.js";
-/**
- * Core's create-requirement vocabulary, and the check that reads it.
- *
- * **The facts are an Adapter's.** Which values a store cannot create a row
- * without is a property of the store's schema — a column with no default, a
- * reference that must point somewhere — and only the Adapter can read it. The
- * words are Aventara's, so an Adapter translates its provider's facts into them,
- * and the reasoning over them is core's, so no Adapter re-implements it.
- *
- * None of this enters a Contract. A Contract carries no foreign-key detail and
- * no knowledge of which relation is the other end of which, and a requirement
- * needs both; it is a server-side fact, read once when the Framework is
- * constructed, like the referential actions.
- *
- * **When the check runs.** After guards, pipes and computed write behaviours —
- * the moment the arguments are what the Adapter will be handed — and before
- * any `before` hook or Adapter work. Earlier would refuse a value a pipe or a
- * computed behaviour was about to supply; later is the store's own refusal,
- * which reaches the caller as an internal failure. A missing value is the
- * caller's to fix, so it answers `A2004` with a `V1000` issue at the path where
- * the value belongs.
- *
- * **One value, two spellings.** A relation that holds a reference has scalar
- * fields that hold it too — the Adapter states which, on the relation's
- * referential edge (`ReferentialEdge.references`), for every such relation,
- * required or optional. A write that sets both — `authorId` and
- * `author: { $connect: … }` in one record, at create or update — names the
- * reference twice. No store can honour both, and which one the caller meant is
- * not the framework's to guess, so it is the caller's `A2004` too: a `V1012`
- * issue at the relation, in every record the check walks, before any Adapter
- * work. The same edge is what a required relation may instead be written
- * through, so the pairing has one source.
- *
- * **One store, one spelling per record.** A store may take a record's
- * references only one way at a time — every relation that holds one written as
- * a relation, or every one through its fields — and state it as the Contract's
- * `referenceWrites: "uniform"`. Under it, a record that writes a relation
- * holding a reference beside another relation's reference field is the caller's
- * `A2004` as well: a `V1012` issue at the relation write.
- */
-/** A relation edge, named by the Resource that holds it and its field there. */
-export type CreateRequirementEdge = {
+type Path = readonly (string | number)[];
+/** One required field a `compute.create` stage was to fill and left missing. */
+export type ComputedRequirementGap = {
     readonly resource: string;
-    readonly relation: string;
-};
-/**
- * One value a create of a Resource cannot do without.
- *
- * - `field` — a scalar with no default, generated value or other source: it
- *   must be written.
- * - `relation` — a required to-one relation: it must be written (connected or
- *   created), or every field that holds its reference must be — the
- *   `references` of the relation's referential edge, less any the store fills
- *   itself (`DEFAULTED` or `GENERATED_ON_CREATE`). When the row is created
- *   **through** the relation's other end (`inverse`), the parent supplies it,
- *   and it is not required.
- */
-export type CreateRequirement = {
-    readonly kind: "field";
     readonly field: string;
-} | {
-    readonly kind: "relation";
-    readonly relation: string;
-    readonly inverse?: CreateRequirementEdge;
+    readonly issue: AvValidationIssue;
 };
 /**
- * Every Resource's create requirements, keyed by Resource. A Resource that is
- * absent, or carries an empty list, requires nothing core can check.
- */
-export type CreateRequirementTable = Readonly<Record<string, readonly CreateRequirement[]>>;
-type Path = readonly (string | number)[];
-/**
- * What the Adapter stated that the check reads: its create requirements, and
- * its referential edges for the fields that hold each reference. Read once when
- * the Framework is constructed.
+ * What the Adapter stated that the checks read: its referential edges, for the
+ * fields that hold each reference, and its own create requirements per
+ * Resource, before any layer projected them (what write compute must not leave
+ * missing). Read once when the Framework is constructed. The requirements the
+ * caller is held to are the active Contract's.
  */
 export type RecordWriteFacts = {
-    readonly requirements: CreateRequirementTable;
     readonly references: ReferentialActionTable;
+    readonly stated: (resource: string) => AvCreateRequirements | undefined;
 };
 /** The facts an Adapter stated, read off it once; an absent table states nothing. */
 export declare function recordWriteFactsOf(adapter: {
-    readonly createRequirements?: CreateRequirementTable;
     readonly referentialActions?: ReferentialActionTable;
+    readonly model?: {
+        readonly resources: Readonly<Record<string, unknown>>;
+    };
 }): RecordWriteFacts;
 /**
  * The `V1000` issues for every create position in one operation's arguments
- * that lacks a value the Adapter requires — `create.*`'s `data`, `upsert`'s
+ * that lacks a value the active Contract requires — `create.*`'s `data`, `upsert`'s
  * `create`, and every nested create under any write — and the `V1012` issues
  * for every write record, create or update, that sets a relation and its
  * reference both, in argument order. Empty when there are none. Total over
  * malformed input.
  */
-export declare function createRequirementIssues(contract: Contract, facts: RecordWriteFacts, request: OperationIdentity & {
+export declare function createRequirementIssues(contract: AvContract, facts: Pick<RecordWriteFacts, "references">, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown, argumentsPath: Path): readonly AvValidationIssue[];
+/**
+ * The `V1000` issues for every create position of one operation's arguments
+ * that lacks a value the active Contract requires, and the `V1012` issues for
+ * every write record that sets a relation and its reference both, on the
+ * arguments as the caller sent them, before any pipeline stage runs. Empty when
+ * there are none.
+ */
+export declare function preliminaryRecordIssues(contract: AvContract, facts: Pick<RecordWriteFacts, "references">, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown, argumentsPath: Path): readonly AvValidationIssue[];
+/**
+ * Every required field a `compute.create` stage was to fill and that is still
+ * missing after write compute, at every create position of one operation's
+ * arguments (`create.*`'s `data`, `upsert`'s `create`, every nested create),
+ * in argument order, read against the Adapter's own statement of each
+ * Resource's create requirements; `computed` names the fields a Resource's
+ * `compute.create` stages fill.
+ * A field the parent supplies to a nested create, a group whose relation the
+ * record writes, and a value the caller sent are not missing. Empty when
+ * nothing is.
+ */
+export declare function computedRequirementGapsOf(contract: AvContract, facts: RecordWriteFacts, request: AvOperationIdentity & {
     readonly resource: string;
-}, args: unknown, argumentsPath: Path): readonly ValidationIssue[];
+}, args: unknown, argumentsPath: Path, computed: (resource: string) => ReadonlySet<string>): readonly ComputedRequirementGap[];
 export {};