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

package/dist/runtime/readonly-value.js

@@ -0,0 +1,150 @@
+import { AvDecimal } from "./decimal.js";
+function isContainer(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return true;
+    }
+    if (value instanceof AvDecimal) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+const DEEP_FROZEN = new WeakSet();
+export function deepFreeze(value) {
+    if (!isContainer(value) || DEEP_FROZEN.has(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    DEEP_FROZEN.add(value);
+    for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor !== undefined && "value" in descriptor) {
+            deepFreeze(descriptor.value);
+        }
+    }
+    return value;
+}
+function scalarCopy(value) {
+    if (value instanceof Date) {
+        return new Date(value.getTime());
+    }
+    if (value instanceof Uint8Array) {
+        return value.slice();
+    }
+    return undefined;
+}
+const SCALAR_FREE = new WeakSet();
+export function frozenCopy(value) {
+    const copies = new Map();
+    const walking = new Set();
+    let cycled = false;
+    const copy = (current) => {
+        const scalar = scalarCopy(current);
+        if (scalar !== undefined) {
+            return scalar;
+        }
+        if (!isContainer(current) || SCALAR_FREE.has(current)) {
+            return current;
+        }
+        if (copies.has(current)) {
+            cycled ||= walking.has(current);
+            return copies.get(current);
+        }
+        copies.set(current, current);
+        walking.add(current);
+        const entries = [];
+        let changed = !DEEP_FROZEN.has(current);
+        for (const key of Reflect.ownKeys(current)) {
+            const descriptor = Object.getOwnPropertyDescriptor(current, key);
+            if (descriptor === undefined ||
+                !("value" in descriptor) ||
+                (Array.isArray(current) && key === "length")) {
+                continue;
+            }
+            const next = copy(descriptor.value);
+            changed ||= next !== descriptor.value;
+            entries.push([key, descriptor, next]);
+        }
+        walking.delete(current);
+        if (!changed) {
+            copies.set(current, current);
+            if (!cycled) {
+                SCALAR_FREE.add(current);
+            }
+            return current;
+        }
+        const target = Array.isArray(current)
+            ? new Array(current.length)
+            : Object.create(Object.getPrototypeOf(current));
+        for (const [key, descriptor, next] of entries) {
+            Object.defineProperty(target, key, {
+                value: next,
+                enumerable: descriptor.enumerable ?? false,
+                writable: true,
+                configurable: true,
+            });
+        }
+        const frozen = deepFreeze(target);
+        copies.set(current, frozen);
+        return frozen;
+    };
+    return copy(value);
+}
+function readOnlyWrite(subject) {
+    return new TypeError(`${subject} is read-only here.`);
+}
+const VIEWS = new WeakMap();
+export function readonlyView(value, subject) {
+    if (!isContainer(value)) {
+        return value;
+    }
+    const known = VIEWS.get(value);
+    if (known !== undefined) {
+        return known;
+    }
+    const real = value;
+    const standIn = Array.isArray(value)
+        ? []
+        : Object.create(Object.getPrototypeOf(value));
+    const refuse = () => {
+        throw readOnlyWrite(subject);
+    };
+    const view = new Proxy(standIn, {
+        get: (_target, key) => readonlyView(real[key], subject),
+        has: (_target, key) => key in real,
+        ownKeys: () => Reflect.ownKeys(real),
+        getOwnPropertyDescriptor: (target, key) => {
+            const descriptor = Reflect.getOwnPropertyDescriptor(real, key);
+            if (descriptor === undefined) {
+                return undefined;
+            }
+            if (Reflect.getOwnPropertyDescriptor(target, key)?.configurable === false) {
+                return {
+                    value: descriptor.value,
+                    enumerable: false,
+                    writable: true,
+                    configurable: false,
+                };
+            }
+            return "value" in descriptor
+                ? {
+                    value: readonlyView(descriptor.value, subject),
+                    enumerable: descriptor.enumerable ?? false,
+                    writable: false,
+                    configurable: true,
+                }
+                : { ...descriptor, configurable: true };
+        },
+        getPrototypeOf: () => Object.getPrototypeOf(real),
+        set: refuse,
+        defineProperty: refuse,
+        deleteProperty: refuse,
+        setPrototypeOf: refuse,
+        preventExtensions: refuse,
+    });
+    VIEWS.set(value, view);
+    return view;
+}

package/dist/runtime/request-envelope.validator.d.ts

@@ -1,5 +1,5 @@
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
 /** The issues of one malformed operation request envelope; empty when well formed. */
-export declare function validateOperationEnvelope(request: unknown): readonly ValidationIssue[];
+export declare function validateOperationEnvelope(request: unknown): readonly AvValidationIssue[];
 /** The issues of one malformed transaction request envelope; empty when well formed. */
-export declare function validateTransactionEnvelope(request: unknown): readonly ValidationIssue[];
+export declare function validateTransactionEnvelope(request: unknown): readonly AvValidationIssue[];

package/dist/runtime/request-envelope.validator.js

@@ -1,4 +1,4 @@
-const ORIGINS = ["application", "client"];
+const ORIGINS = ["application", "client", "agent"];
 const OPERATION_IDENTITY_MEMBERS = ["resource", "family", "variant"];
 export function validateOperationEnvelope(request) {
     if (!isRecord(request)) {
@@ -29,7 +29,7 @@ function originAndIdentityIssues(request) {
         issues.push(issue(["origin"], "V1001", "Request origin must be a string."));
     }
     else if (!ORIGINS.includes(origin)) {
-        issues.push(issue(["origin"], "V1002", 'Request origin must be "application" or "client".'));
+        issues.push(issue(["origin"], "V1002", 'Request origin must be "application", "client" or "agent".'));
     }
     const requestId = request.requestId;
     if (requestId === undefined || requestId === "") {
@@ -38,8 +38,13 @@ function originAndIdentityIssues(request) {
     else if (typeof requestId !== "string") {
         issues.push(issue(["requestId"], "V1001", "Request id must be a string."));
     }
-    if (origin === "client") {
-        issues.push(...protocolIssues(request.protocol));
+    const state = request.state;
+    if (state !== undefined &&
+        (typeof state !== "object" || state === null || Array.isArray(state))) {
+        issues.push(issue(["state"], "V1001", "Request state must be an object."));
+    }
+    if (origin === "client" || origin === "agent") {
+        issues.push(...protocolIssues(request.protocol, origin));
         if (request.transport !== undefined) {
             issues.push(...transportIssues(request.transport));
         }
@@ -47,16 +52,16 @@ function originAndIdentityIssues(request) {
     else if (origin === "application") {
         for (const member of ["protocol", "transport"]) {
             if (request[member] !== undefined) {
-                issues.push(issue([member], "V1005", `Property "${member}" belongs to a client request, not an application one.`));
+                issues.push(issue([member], "V1005", `Property "${member}" belongs to a client or agent request, not an application one.`));
             }
         }
     }
     return issues;
 }
-function protocolIssues(protocol) {
+function protocolIssues(protocol, origin) {
     if (protocol === undefined) {
         return [
-            issue(["protocol"], "V1000", 'Required property "protocol" is missing from a client request.'),
+            issue(["protocol"], "V1000", `Required property "protocol" is missing from ${origin === "client" ? "a client" : "an agent"} request.`),
         ];
     }
     if (!isRecord(protocol)) {

package/dist/runtime/request-id.d.ts

@@ -1,6 +1,6 @@
 /**
  * The request id of one call or transaction run: the caller's
- * `ExecutionOptions.requestId` when it is a non-empty string, otherwise a new
+ * `AvExecutionOptions.requestId` when it is a non-empty string, otherwise a new
  * one. Any other value is ignored.
  */
 export declare function requestIdOf(options: unknown): string;

package/dist/runtime/request-state.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The per-request state every stage reads and writes as `ctx.$state`. Empty
+ * until the application declares its members by module augmentation:
+ *
+ * ```ts
+ * declare module "@aventara/core" {
+ *   interface AvState {
+ *     user?: { id: string; roles: string[] };
+ *   }
+ * }
+ * ```
+ */
+export interface AvState {
+}

package/dist/runtime/request-state.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/request-state.resolver.d.ts

@@ -0,0 +1,12 @@
+import type { AvState } from "./request-state.js";
+/**
+ * The state of one request: the seed when it is an object, otherwise a fresh
+ * `{}`. A seed that is not an object is ignored, as an unusable request id is.
+ */
+export declare function requestStateOf(seed: unknown): AvState;
+/**
+ * The state an in-process call's `AvExecutionOptions` seeds, or `undefined`.
+ * Read as `unknown`, like the request id: a façade is total for untyped
+ * callers, so a getter that throws or a value that is not an object is ignored.
+ */
+export declare function stateOptionOf(options: unknown): AvState | undefined;

package/dist/runtime/request-state.resolver.js

@@ -0,0 +1,20 @@
+export function requestStateOf(seed) {
+    return typeof seed === "object" && seed !== null && !Array.isArray(seed)
+        ? seed
+        : {};
+}
+export function stateOptionOf(options) {
+    if (typeof options !== "object" || options === null) {
+        return undefined;
+    }
+    let state;
+    try {
+        state = options.state;
+    }
+    catch {
+        return undefined;
+    }
+    return typeof state === "object" && state !== null && !Array.isArray(state)
+        ? state
+        : undefined;
+}

package/dist/runtime/scalar-runtime.d.ts

@@ -1,41 +1,60 @@
-import type { RequestOrigin } from "../config/config-layer.js";
-import type { ScalarFilterOperator } from "../contracts/capability.js";
-import type { Contract } from "../contracts/contract.js";
-import type { ScalarField } from "../contracts/field.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import { type AvScalarFilterOperator } from "../contracts/capability.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { OperationValidationOptions, SemanticOperationArguments } from "../operations/operation-validator.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
 import { type TransactionSlotShape } from "../transactions/transaction-reference.js";
 export type ScalarNormalizationResult = {
     readonly ok: true;
     readonly arguments: SemanticOperationArguments;
 } | {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
 export type ScalarValueNormalizationResult = {
     readonly ok: true;
     readonly value: unknown;
 } | {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
 type Path = readonly (string | number)[];
 /**
  * The one discriminant between an argument OBJECT and a VALUE wherever a position
  * admits both — a filter position above all: a **plain** record is an operator object,
- * and anything else — a `Date`, a core `Decimal`, a `Uint8Array` — is a value, which
+ * and anything else — a `Date`, a core `AvDecimal`, a `Uint8Array` — is a value, which
  * equality shorthand then holds to the field's scalar. The validator (`operation-
  * validator-core.ts`) reads a filter position through this same answer, and an
  * adapter's filter translation is expected to, so a position cannot be operators to
  * one reader and a value to another.
  */
 export declare function isPlainRecord(value: unknown): value is Readonly<Record<string, unknown>>;
+/** What a refused `undefined` the request reads with is told. */
+export declare const UNSENT_READ_VALUE_MESSAGE = "Value must not be undefined: it would be left out, and the request would reach more rows.";
+/** The `V1001` of an `undefined` the request reads with. */
+export declare function unsentReadValueIssue(path: Path): AvValidationIssue;
+/**
+ * An operation argument's JSON value is bounded by `maxJsonDepth`, which the
+ * structural walk enforces before this runs; a `$sql` step's parameter is not
+ * bounded by it. The traversal therefore carries its own stack on the heap: a
+ * payload deep enough to exhaust the call stack must still normalize rather
+ * than become an internal failure.
+ *
+ * `seen` holds the ancestors of the value being visited, so a repeated
+ * sibling reference is legal and only a genuine cycle is rejected.
+ *
+ * Every node it emits is typed {@link AvJsonValue}, so the public type and what
+ * this traversal produces are one fact: a branch that emitted anything else
+ * would not compile.
+ */
+export declare function normalizeJsonValue(value: unknown, path: Path, seen: Set<object>): ScalarValueNormalizationResult;
 /**
  * Normalizes one field value to Aventara's provider-neutral runtime form.
  * `runtime` is used for framework-produced values regardless of request origin.
  */
-export declare function normalizeScalarFieldValue(contract: Contract, field: ScalarField<Contract>, value: unknown, origin: RequestOrigin | "runtime", path: Path): ScalarValueNormalizationResult;
+export declare function normalizeScalarFieldValue(contract: AvContract, field: AvScalarField<AvContract>, value: unknown, origin: AvRequestOrigin | "runtime", path: Path): ScalarValueNormalizationResult;
 /**
  * Every way a normalized value written to `field` does not conform to the field's
  * Json Shape, each at its full path; none for an unshaped field or a `null`.
@@ -45,17 +64,17 @@ export declare function normalizeScalarFieldValue(contract: Contract, field: Sca
  * @throws Error when the field carries a shape no checker is bound to — a Contract
  *   the Framework did not compile.
  */
-export declare function jsonShapeIssues(field: ScalarField<Contract>, value: unknown, path: Path, position?: "value" | "entry"): readonly ValidationIssue[];
+export declare function jsonShapeIssues(field: AvScalarField<AvContract>, value: unknown, path: Path, position?: "value" | "entry"): readonly AvValidationIssue[];
 /**
  * Copies one validated runtime value of a scalar field into a value the framework
  * owns, per scalar codec: `datetime` → a new `Date`, `bytes` → a sliced `Uint8Array`,
  * `json` → a structured deep copy, and a list → a new array of copied items. `decimal`
  * keeps its identity, and strings, numbers, booleans, bigints, enum members and `null`
  * are immutable and returned unchanged. {@link SCALAR_ATOM_COPIERS} is exhaustive over
- * {@link BuiltInScalar}, so a new codec cannot reach this function without declaring
+ * {@link AvBuiltInScalar}, so a new codec cannot reach this function without declaring
  * its copy.
  */
-export declare function copyScalarFieldValue(field: ScalarField<Contract>, value: unknown): unknown;
+export declare function copyScalarFieldValue(field: AvScalarField<AvContract>, value: unknown): unknown;
 /**
  * The operators of a step's own filter whose operand is a reference position, and
  * the shape each holds — the one table the normalization below and the reference
@@ -63,7 +82,7 @@ export declare function copyScalarFieldValue(field: ScalarField<Contract>, value
  * nested operator object. Not here, so never a reference: `mode`, `isEmpty`, `path`
  * and a `json` field's `string*`/`array*` operators, which take no field value.
  */
-export declare const REFERENCE_OPERANDS: Readonly<Partial<Record<ScalarFilterOperator, TransactionSlotShape>>>;
+export declare const REFERENCE_OPERANDS: Readonly<Partial<Record<AvScalarFilterOperator, TransactionSlotShape>>>;
 /** The shape of `operator`'s operand when it is a reference position. */
 export declare function referenceOperandShape(operator: string): TransactionSlotShape | undefined;
 /**
@@ -76,8 +95,8 @@ export type NormalizationWrite = "copy" | "in-place";
  * Normalizes every scalar leaf in one structurally valid standard operation.
  * Client wire values are decoded; application values are validated in runtime form.
  */
-export declare function normalizeOperationScalarValues(contract: Contract, request: OperationIdentity & {
+export declare function normalizeOperationScalarValues(contract: AvContract, request: AvOperationIdentity & {
     readonly resource: string;
     readonly arguments: SemanticOperationArguments;
-}, origin: RequestOrigin, options?: OperationValidationOptions, write?: NormalizationWrite): ScalarNormalizationResult;
+}, origin: AvRequestOrigin, options?: OperationValidationOptions, write?: NormalizationWrite): ScalarNormalizationResult;
 export {};