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

package/dist/transactions/sql-statement.d.ts

@@ -0,0 +1,85 @@
+import type { AvAdapterSqlValue } from "../adapters/adapter-sql-statement.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
+import type { AvCallerDataError } from "../runtime/caller-data.copier.js";
+import type { AvOperation } from "./deferred-operation.js";
+import type { AvTransactionReference } from "./transaction-reference.js";
+/**
+ * One value an `appTx.$sql` template binds: a primitive, a `Date`, an `AvDecimal`, a
+ * `Uint8Array`, a JSON value (a plain object or array, bound as JSON text — cast it,
+ * `${value}::jsonb`), or a `$ref` to an earlier step's field, resolved when the
+ * earlier steps have run and then bound like any other value.
+ */
+export type AvSqlStatementValue = AvAdapterSqlValue | AvTransactionReference;
+/**
+ * `framework.appTx.$sql`: a developer SQL step, written only as a tagged template —
+ * ``framework.appTx.$sql`select pgmq.send('jobs', jsonb_build_object('id', ${ref}))` ``.
+ * Every interpolated value is bound as a parameter, never spliced into the text, so
+ * the text is static: a table or column name cannot come from a value.
+ *
+ * The step runs in plan order inside the same database transaction as the other
+ * steps; its entry in the committed `data` is the rows the statement returned,
+ * typed `Row[]` (`unknown[]` unless `Row` is given). A later step cannot `$ref` a
+ * SQL step's rows. No guard, pipe, hook, interceptor or filter runs around it: it
+ * has no Resource or operation for one to wrap.
+ */
+export type AvSqlStatementBuilder = <Row = unknown>(strings: TemplateStringsArray, ...values: readonly AvSqlStatementValue[]) => AvOperation<Row[], "application">;
+/** One value of a planned SQL step, as the typed runner bound it. */
+export type PlannedSqlValue = {
+    readonly kind: "value";
+    readonly value: unknown;
+}
+/** A `$ref` placeholder standing as the whole value: the source's position and field. */
+ | {
+    readonly kind: "reference";
+    readonly operation: number;
+    readonly field: string;
+}
+/**
+ * A whole value that is a `$ref` control object the caller wrote, mirrored at
+ * the builder: validated as an operation step's reference is.
+ */
+ | {
+    readonly kind: "candidate";
+    readonly candidate: unknown;
+}
+/** A `$ref` placeholder found inside a value, at `path` within it: refused. */
+ | {
+    readonly kind: "misplaced-reference";
+    readonly path: readonly (string | number)[];
+};
+/**
+ * A SQL step as the typed runner hands it to the validator, unvalidated: the
+ * template's static text (`undefined` when the call was no genuine tagged
+ * template), its values with each `$ref` bound to its source's position, or why the
+ * builder could not copy the values.
+ */
+export type PlannedSqlStatement = {
+    readonly strings: readonly string[] | undefined;
+    readonly values: readonly PlannedSqlValue[];
+    readonly refused?: AvCallerDataError;
+};
+/** One validated value of a SQL step: bound as it is, or resolved from a `$ref`. */
+export type ValidatedSqlValue = {
+    readonly kind: "value";
+    readonly value: AvAdapterSqlValue;
+} | {
+    readonly kind: "reference";
+    readonly operation: number;
+    readonly field: string;
+    /** The source field, under its own step's Contract: what the value is read as. */
+    readonly source: AvScalarField<AvContract>;
+};
+/** A SQL step the Framework Validation Layer accepted. */
+export type ValidatedSqlStatement = {
+    readonly kind: "sql";
+    readonly index: number;
+    readonly strings: readonly string[];
+    readonly values: readonly ValidatedSqlValue[];
+};
+/**
+ * The static text of a genuine tagged template, read once and copied, or
+ * `undefined` when `strings` is not one or does not fit `valueCount` values.
+ * Total: a hostile value is `undefined`, never a throw.
+ */
+export declare function readSqlTemplate(strings: unknown, valueCount: number): readonly string[] | undefined;

package/dist/transactions/sql-statement.js

@@ -0,0 +1,47 @@
+function ownData(target, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(target, key);
+    return descriptor !== undefined && "value" in descriptor
+        ? descriptor.value
+        : undefined;
+}
+function frozenStrings(value, length) {
+    if (!Array.isArray(value) || !Object.isFrozen(value)) {
+        return undefined;
+    }
+    const size = ownData(value, "length");
+    if (typeof size !== "number" ||
+        size < 1 ||
+        (length !== undefined && size !== length)) {
+        return undefined;
+    }
+    const strings = [];
+    for (let index = 0; index < size; index += 1) {
+        const entry = ownData(value, String(index));
+        if (typeof entry !== "string") {
+            return undefined;
+        }
+        strings.push(entry);
+    }
+    return strings;
+}
+export function readSqlTemplate(strings, valueCount) {
+    try {
+        if (typeof strings !== "object" || strings === null) {
+            return undefined;
+        }
+        const raw = Object.getOwnPropertyDescriptor(strings, "raw");
+        if (raw === undefined || raw.enumerable || !("value" in raw)) {
+            return undefined;
+        }
+        const cooked = frozenStrings(strings, valueCount + 1);
+        if (cooked === undefined) {
+            return undefined;
+        }
+        return frozenStrings(raw.value, cooked.length) === undefined
+            ? undefined
+            : Object.freeze(cooked);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/transactions/sql-statement.validator.d.ts

@@ -0,0 +1,44 @@
+import type { AvAdapterSqlValue } from "../adapters/adapter-sql-statement.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import type { MisuseReporter } from "../runtime/misuse-reporter.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import type { PlannedSqlStatement, ValidatedSqlStatement } from "./sql-statement.js";
+import type { ValidatedTransactionStep } from "./transaction-plan-validator.js";
+type Path = readonly (string | number)[];
+type SqlStatementValidation = {
+    readonly ok: true;
+    readonly statement: ValidatedSqlStatement;
+} | {
+    readonly ok: false;
+    readonly response: AvOperationFailureResponse;
+};
+/** What validating a SQL step needs from the plan around it. */
+type SqlStatementValidationContext = {
+    /** The step's position in the plan. */
+    readonly index: number;
+    /** The steps validated before it, by position. */
+    readonly earlier: readonly ValidatedTransactionStep[];
+    /** Whether the Adapter declares `sqlStatements`. */
+    readonly available: boolean;
+    readonly misuse: MisuseReporter;
+};
+/**
+ * One bindable value of a SQL step, in its runtime form, or the issues that refuse
+ * it: a primitive (a `number` only when finite), a valid `Date`, an `AvDecimal`, a
+ * `Uint8Array`, or a JSON value — a plain object or array, held to the same rules
+ * as a `json` field's value. `undefined` and anything else are no value to bind.
+ */
+export declare function normalizeSqlValue(value: unknown, path: Path): {
+    readonly ok: true;
+    readonly value: AvAdapterSqlValue;
+} | {
+    readonly ok: false;
+    readonly issues: readonly AvValidationIssue[];
+};
+/**
+ * Validates one SQL step: the Adapter runs SQL statements, the call was a genuine
+ * tagged template, its values could be copied, every value is bindable, and every
+ * `$ref` stands as a whole value and reads one field of an earlier single-row step.
+ */
+export declare function validateSqlStatement(statement: PlannedSqlStatement, context: SqlStatementValidationContext): SqlStatementValidation;
+export {};

package/dist/transactions/sql-statement.validator.js

@@ -0,0 +1,167 @@
+import { validationIssue } from "../operations/validation-code.js";
+import { AvCallerDataError, locateCallerDataError, } from "../runtime/caller-data.copier.js";
+import { refuseCallerData } from "../runtime/caller-data.door.js";
+import { isAvDecimal } from "../runtime/decimal.js";
+import { planStepPath } from "../runtime/error-boundary.js";
+import { operationFailure } from "../runtime/operation-response.js";
+import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
+import { isPlainRecord, normalizeJsonValue, } from "../runtime/scalar-runtime.js";
+import { inspectReferenceCandidate, invalidSourceIndexIssue, referenceSourceAt, referenceSourceField, } from "./transaction-reference-validator.js";
+import { transactionOperationFailure } from "./transaction-response.js";
+function refused(issue, index) {
+    return {
+        ok: false,
+        response: transactionOperationFailure(mapValidationOutcome([issue]), index),
+    };
+}
+export function normalizeSqlValue(value, path) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint" ||
+        isAvDecimal(value) ||
+        value instanceof Uint8Array) {
+        return { ok: true, value };
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value)
+            ? { ok: true, value }
+            : {
+                ok: false,
+                issues: [
+                    validationIssue("V1004", path, "Value must be a finite number."),
+                ],
+            };
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime())
+            ? {
+                ok: false,
+                issues: [
+                    validationIssue("V1003", path, "Value must use a valid Date value."),
+                ],
+            }
+            : { ok: true, value };
+    }
+    if (Array.isArray(value) || isPlainRecord(value)) {
+        const json = normalizeJsonValue(value, path, new Set());
+        return json.ok
+            ? { ok: true, value: json.value }
+            : { ok: false, issues: json.issues };
+    }
+    return {
+        ok: false,
+        issues: [
+            validationIssue("V1001", path, "Value must be a string, number, boolean, bigint, null, Date, Decimal, Uint8Array or JSON value."),
+        ],
+    };
+}
+export function validateSqlStatement(statement, context) {
+    const { index } = context;
+    if (!context.available) {
+        const message = "SQL statements are not available on this Adapter.";
+        return {
+            ok: false,
+            response: transactionOperationFailure(operationFailure("A2002", {
+                message,
+                issues: [validationIssue("V1006", [], message)],
+            }), index),
+        };
+    }
+    if (statement.strings === undefined) {
+        return refused(validationIssue("V1001", ["strings"], "SQL must be written as a tagged template: framework.appTx.$sql`…`."), index);
+    }
+    if (statement.refused !== undefined) {
+        return refused(refuseCallerData(statement.refused, [...planStepPath(index), "values"], { origin: "application", operation: index }, context.misuse), index);
+    }
+    try {
+        return validateSqlValues(statement, statement.strings, context);
+    }
+    catch (error) {
+        if (!(error instanceof AvCallerDataError)) {
+            throw error;
+        }
+        return refused(refuseCallerData(locateCallerDataError(error, statement.values.map((planned) => planned.kind === "value"
+            ? planned.value
+            : planned.kind === "candidate"
+                ? planned.candidate
+                : undefined)), [...planStepPath(index), "values"], { origin: "application", operation: index }, context.misuse), index);
+    }
+}
+function validateSqlValues(statement, strings, context) {
+    const { index, earlier } = context;
+    const values = [];
+    const issues = [];
+    for (const [position, planned] of statement.values.entries()) {
+        const path = ["values", position];
+        switch (planned.kind) {
+            case "misplaced-reference":
+                return refused(validationIssue("V1010", [...path, ...planned.path, "$ref"], "A transaction reference in a SQL step must be a whole value."), index);
+            case "candidate": {
+                const inspection = inspectReferenceCandidate(planned.candidate, path, earlier, index);
+                if (!inspection.ok) {
+                    return refused(inspection.issue, index);
+                }
+                if (inspection.field.kind !== "scalar" || inspection.field.list) {
+                    return refused(validationIssue("V1011", inspection.pathPath, "Transaction reference source is not a single scalar field."), index);
+                }
+                values.push({
+                    kind: "reference",
+                    operation: inspection.source.index,
+                    field: inspection.segment,
+                    source: inspection.field,
+                });
+                break;
+            }
+            case "reference": {
+                const source = referenceSourceAt(earlier, planned.operation, index);
+                if (source === undefined) {
+                    return refused(invalidSourceIndexIssue([...path, "$ref", "operation"]), index);
+                }
+                const read = referenceSourceField(source, planned.field, [
+                    ...path,
+                    "$ref",
+                    "path",
+                ]);
+                if (!read.ok) {
+                    return refused(read.issue, index);
+                }
+                if (read.field.kind !== "scalar" || read.field.list) {
+                    return refused(validationIssue("V1011", [...path, "$ref", "path"], "Transaction reference source is not a single scalar field."), index);
+                }
+                values.push({
+                    kind: "reference",
+                    operation: planned.operation,
+                    field: planned.field,
+                    source: read.field,
+                });
+                break;
+            }
+            case "value": {
+                const normalized = normalizeSqlValue(planned.value, path);
+                if (normalized.ok) {
+                    values.push({ kind: "value", value: normalized.value });
+                }
+                else {
+                    issues.push(...normalized.issues);
+                }
+                break;
+            }
+        }
+    }
+    if (issues.length > 0) {
+        return {
+            ok: false,
+            response: transactionOperationFailure(mapValidationOutcome(issues), index),
+        };
+    }
+    return {
+        ok: true,
+        statement: {
+            kind: "sql",
+            index,
+            strings,
+            values,
+        },
+    };
+}

package/dist/transactions/transaction-envelope.d.ts

@@ -1,31 +1,31 @@
-import type { ValidationIssue } from "../operations/validation-code.js";
-export type TransactionEnvelopeSchema = {
+import type { AvValidationIssue } from "../operations/validation-code.js";
+type TransactionEnvelopeSchema = {
     readonly required: readonly string[];
     readonly optional?: readonly string[];
     readonly invalidContainerPath: readonly (string | number)[];
     readonly invalidContainerMessage: string;
 };
-export type TransactionEnvelopeInspection = {
+type TransactionEnvelopeInspection = {
     readonly ok: true;
     readonly values: ReadonlyMap<string, unknown>;
 } | {
     readonly ok: false;
-    readonly issue: ValidationIssue;
+    readonly issue: AvValidationIssue;
 };
-export type TransactionOperationsInspection = {
+type TransactionOperationsInspection = {
     readonly ok: true;
     readonly value: object;
     readonly length: number;
 } | {
     readonly ok: false;
-    readonly issue: ValidationIssue;
+    readonly issue: AvValidationIssue;
 };
-export type TransactionOperationEntryInspection = {
+type TransactionOperationEntryInspection = {
     readonly ok: true;
     readonly value: unknown;
 } | {
     readonly ok: false;
-    readonly issue: ValidationIssue;
+    readonly issue: AvValidationIssue;
 };
 /**
  * The caller uses the returned length and per-index inspector rather than
@@ -39,3 +39,4 @@ export declare function inspectTransactionOperationEntry(operations: object, ind
  * Proxies are unsupported; reflection failures are contained as envelope issues.
  */
 export declare function inspectTransactionEnvelope(value: unknown, schema: TransactionEnvelopeSchema): TransactionEnvelopeInspection;
+export {};

package/dist/transactions/transaction-integrity-error.d.ts

@@ -1,13 +1,13 @@
 /**
- * The ways an Adapter transaction can break the framework's transaction
- * contract. Each is answered `A3002`.
+ * The ways an Adapter transaction, or a stage running inside it, can break the
+ * framework's transaction contract. Each is answered `A3002` and rolls back.
  */
-export type TransactionIntegrityViolation = "transaction-unavailable" | "resolved-after-abort" | "resolved-incomplete" | "foreign-abort";
+export type AvTransactionIntegrityViolation = "transaction-unavailable" | "resolved-after-abort" | "resolved-incomplete" | "foreign-abort" | "statement-unavailable" | "next-called-twice" | "steps-not-run";
 /**
  * Reported to diagnostics when an Adapter transaction breaks the framework's
  * transaction contract. The caller receives `A3002`.
  */
-export declare class TransactionIntegrityError extends Error {
-    readonly violation: TransactionIntegrityViolation;
-    constructor(violation: TransactionIntegrityViolation);
+export declare class AvTransactionIntegrityError extends Error {
+    readonly violation: AvTransactionIntegrityViolation;
+    constructor(violation: AvTransactionIntegrityViolation);
 }

package/dist/transactions/transaction-integrity-error.js

@@ -1,14 +1,19 @@
+import { brandCoreClass } from "../runtime/core-class.brand.js";
 const TRANSACTION_INTEGRITY_MESSAGES = {
     "transaction-unavailable": "Adapter transaction function is unavailable.",
     "resolved-after-abort": "Adapter transaction resolved after the framework requested rollback.",
     "resolved-incomplete": "Adapter transaction resolved before the plan completed.",
     "foreign-abort": "Adapter transaction rejected with a rollback request this plan never made.",
+    "statement-unavailable": "Adapter declares sqlStatements but its transaction executor has no executeSql.",
+    "next-called-twice": "A transaction interceptor called next() more than once; next() runs the plan's steps once.",
+    "steps-not-run": "A transaction interceptor resolved without calling next(); the plan's steps never ran.",
 };
-export class TransactionIntegrityError extends Error {
+export class AvTransactionIntegrityError extends Error {
     violation;
     constructor(violation) {
         super(TRANSACTION_INTEGRITY_MESSAGES[violation]);
-        this.name = "TransactionIntegrityError";
+        this.name = "AvTransactionIntegrityError";
         this.violation = violation;
     }
 }
+brandCoreClass(AvTransactionIntegrityError, "AvTransactionIntegrityError");

package/dist/transactions/transaction-plan-assembler.d.ts

@@ -1,12 +1,16 @@
-import type { FrameworkContracts } from "../compiler/contract.compiler.js";
-import type { RequestOrigin } from "../config/config-layer.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { CallerDataError } from "../runtime/caller-data.copier.js";
+import type { AvContracts } from "../compiler/contract.compiler.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import { AvCallerDataError } from "../runtime/caller-data.copier.js";
 import type { MisuseReporter } from "../runtime/misuse-reporter.js";
-import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
-import type { OperationFailureResponse } from "../runtime/operation-response.js";
-import type { Operation, OperationFingerprint } from "./deferred-operation.js";
+import type { AvRequestProtocol } from "../runtime/operation-request.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import type { AvOperation, OperationFingerprint } from "./deferred-operation.js";
+import type { PlannedSqlStatement } from "./sql-statement.js";
 import type { TransactionOperationOrigin } from "./transaction-request.js";
+/** The origin a handle's builder gives it. */
+type HandleOrigin = "application" | "client";
+/** The scalar forms a builder takes its arguments in. */
+type ArgumentForms = "wire" | "application";
 /** One wire node, exactly as the transaction runtime receives it. */
 type WireOperationNode = {
     readonly resource: string;
@@ -15,22 +19,35 @@ type WireOperationNode = {
     readonly args: unknown;
     readonly fingerprint: OperationFingerprint | null;
 };
+declare const SQL_STEP_NODE: Readonly<{
+    fingerprint: null;
+}>;
+type PlanNode = WireOperationNode | typeof SQL_STEP_NODE;
 export type AssembledTransactionPlan = {
     readonly ok: true;
     readonly plan: {
-        readonly operations: readonly WireOperationNode[];
+        readonly operations: readonly PlanNode[];
     };
     /** Each operation's own origin, by index (mixed plans). */
     readonly origins: readonly TransactionOperationOrigin[];
     /** The steps whose arguments their builder could not copy, by index. */
-    readonly refused: ReadonlyMap<number, CallerDataError>;
+    readonly refused: ReadonlyMap<number, AvCallerDataError>;
+    /** The `appTx.$sql` steps, by index, with each `$ref` bound to its source's position. */
+    readonly statements: ReadonlyMap<number, PlannedSqlStatement>;
 } | {
     readonly ok: false;
-    readonly response: OperationFailureResponse;
+    readonly response: AvOperationFailureResponse;
 };
 export type TransactionPlanAssembler = {
-    /** Defers one operation into a handle; nothing runs. */
-    defer(origin: RequestOrigin, resource: string, identity: OperationIdentity, args: unknown): Operation<unknown>;
+    /**
+     * Defers one operation into a handle; nothing runs. `forms` says which scalar
+     * forms a client-origin handle's arguments are in: `"wire"` (`clientTx`, the
+     * default) or `"application"` (`serverClientTx`), encoded into the wire forms
+     * from the builder's copy.
+     */
+    defer(origin: HandleOrigin, resource: string, identity: AvOperationIdentity, args: unknown, forms?: ArgumentForms): AvOperation<unknown>;
+    /** Defers one `appTx.$sql` statement into a handle; nothing runs. */
+    deferSql(strings: unknown, values: readonly unknown[]): AvOperation<unknown>;
     /** Binds a list of handles into the passive plan, or refuses it. */
     assemble(operations: unknown): Promise<AssembledTransactionPlan>;
 };
@@ -39,5 +56,5 @@ export type TransactionPlanAssembler = {
  * handle, so a handle another instance built — typed against another model,
  * bound to other Contracts — is refused rather than run.
  */
-export declare function createTransactionPlanAssembler(contracts: FrameworkContracts, protocol: ClientProtocolIdentity, misuse: MisuseReporter): TransactionPlanAssembler;
+export declare function createTransactionPlanAssembler(contracts: AvContracts, protocol: AvRequestProtocol, misuse: MisuseReporter): TransactionPlanAssembler;
 export {};