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

package/dist/runtime/computed-read-runtime.js

@@ -1,16 +1,15 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
-import { ComputedValueError } from "./computed-value.error.js";
+import { AvComputedValueError } from "./computed-value.error.js";
+import { frozenCopy } from "./readonly-value.js";
 import { normalizeScalarFieldValue } from "./scalar-runtime.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function readBehavior(value) {
+function readCompute(value) {
     if (typeof value === "function") {
         return { compute: value, dependsOn: [] };
     }
-    if (value === undefined ||
-        value === false ||
-        typeof value.compute !== "function") {
+    if (value === undefined || typeof value.compute !== "function") {
         return undefined;
     }
     return {
@@ -18,6 +17,16 @@ function readBehavior(value) {
         dependsOn: value.dependsOn ?? [],
     };
 }
+function storedScalar(model, resource, field) {
+    const resources = model.resources;
+    const fields = Object.hasOwn(resources, resource)
+        ? resources[resource]?.fields
+        : undefined;
+    const entry = fields !== undefined && Object.hasOwn(fields, field)
+        ? fields[field]
+        : undefined;
+    return isRecord(entry) && entry.kind === "scalar";
+}
 function appendUnique(values, value) {
     if (!values.includes(value)) {
         values.push(value);
@@ -28,24 +37,34 @@ function appendUniqueProjection(values, value) {
         values.push(value);
     }
 }
+function adapterIdentifier(model, resource) {
+    const resources = model.resources;
+    return ((Object.hasOwn(resources, resource)
+        ? resources[resource]?.identifiers?.[0]
+        : undefined) ?? []);
+}
 function supportsProjection(request) {
     if (request.family === "upsert") {
         return true;
     }
     return request.variant !== "count";
 }
-function addScalarProjection(core, active, behaviors, resourceName, fieldName, adapterSelect, requested, computed) {
+function addScalarProjection(core, model, active, compute, resourceName, fieldName, adapterSelect, requested, computed) {
     const activeField = lookupField(lookupResource(active, resourceName), fieldName);
     if (activeField?.kind !== "scalar") {
         return;
     }
     appendUnique(requested, fieldName);
-    const behavior = readBehavior(behaviors?.[resourceName]?.fields[fieldName]?.read);
-    if (behavior !== undefined) {
+    const stage = readCompute(compute?.[resourceName]?.[fieldName]?.read);
+    if (stage !== undefined) {
         appendUnique(computed, fieldName);
-        for (const dependency of behavior.dependsOn) {
-            const dependencyField = lookupField(lookupResource(core, resourceName), dependency);
-            if (dependencyField?.kind === "scalar") {
+        if (stage.dependsOn.length === 0) {
+            for (const member of adapterIdentifier(model, resourceName)) {
+                appendUniqueProjection(adapterSelect, member);
+            }
+        }
+        for (const dependency of stage.dependsOn) {
+            if (storedScalar(model, resourceName, dependency)) {
                 appendUniqueProjection(adapterSelect, dependency);
             }
         }
@@ -70,7 +89,7 @@ function projectionEntry(entry) {
 function withoutProjectionChoice(value) {
     return Object.fromEntries(Object.entries(value).filter(([key]) => key !== "select" && key !== "include"));
 }
-function defaultProjectionLevel(core, active, behaviors, resourceName) {
+function defaultProjectionLevel(core, model, active, compute, resourceName) {
     const activeResource = lookupResource(active, resourceName);
     const adapterSelect = [];
     const requested = [];
@@ -80,7 +99,7 @@ function defaultProjectionLevel(core, active, behaviors, resourceName) {
             if (field.kind !== "scalar" || field.capabilities.select !== true) {
                 continue;
             }
-            addScalarProjection(core, active, behaviors, resourceName, fieldName, adapterSelect, requested, computed);
+            addScalarProjection(core, model, active, compute, resourceName, fieldName, adapterSelect, requested, computed);
         }
     }
     return {
@@ -94,25 +113,25 @@ function defaultProjectionLevel(core, active, behaviors, resourceName) {
         },
     };
 }
-function planRelationProjection(core, active, behaviors, field, value) {
+function planRelationProjection(core, model, active, compute, field, value) {
     if (!isRecord(value)) {
-        return defaultProjectionLevel(core, active, behaviors, field.target);
+        return defaultProjectionLevel(core, model, active, compute, field.target);
     }
     if (Array.isArray(value.select)) {
-        return planSelectLevel(core, active, behaviors, field.target, value.select, true);
+        return planSelectLevel(core, model, active, compute, field.target, value.select, true);
     }
     if (Array.isArray(value.include)) {
-        return planIncludeLevel(core, active, behaviors, field.target, value.include);
+        return planIncludeLevel(core, model, active, compute, field.target, value.include);
     }
-    return defaultProjectionLevel(core, active, behaviors, field.target);
+    return defaultProjectionLevel(core, model, active, compute, field.target);
 }
-function planRelationEntry(core, active, behaviors, resourceName, fieldName, value) {
+function planRelationEntry(core, model, active, compute, resourceName, fieldName, value) {
     const activeField = lookupField(lookupResource(active, resourceName), fieldName);
     const coreField = lookupField(lookupResource(core, resourceName), fieldName);
     if (activeField?.kind !== "relation" || coreField?.kind !== "relation") {
         return undefined;
     }
-    const nested = planRelationProjection(core, active, behaviors, coreField, value);
+    const nested = planRelationProjection(core, model, active, compute, coreField, value);
     return {
         adapterEntry: {
             [fieldName]: {
@@ -127,7 +146,7 @@ function planRelationEntry(core, active, behaviors, resourceName, fieldName, val
         },
     };
 }
-function planSelectLevel(core, active, behaviors, resourceName, select, collectReducers = false) {
+function planSelectLevel(core, model, active, compute, resourceName, select, collectReducers = false) {
     const activeResource = lookupResource(active, resourceName);
     const coreResource = lookupResource(core, resourceName);
     const adapterSelect = [];
@@ -159,11 +178,11 @@ function planSelectLevel(core, active, behaviors, resourceName, select, collectR
             const activeField = lookupField(activeResource, entry);
             const coreField = lookupField(coreResource, entry);
             if (activeField?.kind === "scalar") {
-                addScalarProjection(core, active, behaviors, resourceName, entry, adapterSelect, requested, computed);
+                addScalarProjection(core, model, active, compute, resourceName, entry, adapterSelect, requested, computed);
                 continue;
             }
             if (activeField?.kind === "relation" && coreField?.kind === "relation") {
-                const plannedRelation = planRelationEntry(core, active, behaviors, resourceName, entry, undefined);
+                const plannedRelation = planRelationEntry(core, model, active, compute, resourceName, entry, undefined);
                 if (plannedRelation !== undefined) {
                     appendUnique(requested, entry);
                     adapterSelect.push(plannedRelation.adapterEntry);
@@ -180,7 +199,7 @@ function planSelectLevel(core, active, behaviors, resourceName, select, collectR
             continue;
         }
         const [fieldName, nestedValue] = relationEntry;
-        const plannedRelation = planRelationEntry(core, active, behaviors, resourceName, fieldName, nestedValue);
+        const plannedRelation = planRelationEntry(core, model, active, compute, resourceName, fieldName, nestedValue);
         if (plannedRelation === undefined) {
             adapterSelect.push(entry);
             continue;
@@ -194,15 +213,15 @@ function planSelectLevel(core, active, behaviors, resourceName, select, collectR
         plan: { resource: resourceName, requested, computed, relations, reducers },
     };
 }
-function planIncludeLevel(core, active, behaviors, resourceName, include) {
-    const defaults = defaultProjectionLevel(core, active, behaviors, resourceName);
+function planIncludeLevel(core, model, active, compute, resourceName, include) {
+    const defaults = defaultProjectionLevel(core, model, active, compute, resourceName);
     const adapterSelect = [...defaults.select];
     const requested = [...defaults.plan.requested];
     const computed = [...defaults.plan.computed];
     const relations = [];
     for (const entry of include) {
         if (typeof entry === "string") {
-            const plannedRelation = planRelationEntry(core, active, behaviors, resourceName, entry, undefined);
+            const plannedRelation = planRelationEntry(core, model, active, compute, resourceName, entry, undefined);
             if (plannedRelation === undefined) {
                 continue;
             }
@@ -216,7 +235,7 @@ function planIncludeLevel(core, active, behaviors, resourceName, include) {
             continue;
         }
         const [fieldName, nestedValue] = relationEntry;
-        const plannedRelation = planRelationEntry(core, active, behaviors, resourceName, fieldName, nestedValue);
+        const plannedRelation = planRelationEntry(core, model, active, compute, resourceName, fieldName, nestedValue);
         if (plannedRelation === undefined) {
             continue;
         }
@@ -241,7 +260,7 @@ function replaceWithInternalSelect(args, select) {
     internal.select = select;
     return internal;
 }
-export function planReadOperation(core, active, behaviors, request, args) {
+export function planReadOperation(core, model, active, compute, request, args) {
     if (!isRecord(args) || !supportsProjection(request)) {
         return { arguments: args, projection: undefined, materialize: false };
     }
@@ -251,7 +270,7 @@ export function planReadOperation(core, active, behaviors, request, args) {
         return { arguments: args, projection: undefined, materialize: false };
     }
     if (Array.isArray(args.select)) {
-        const planned = planSelectLevel(core, active, behaviors, request.resource, args.select);
+        const planned = planSelectLevel(core, model, active, compute, request.resource, args.select);
         return {
             arguments: replaceWithInternalSelect(args, planned.select),
             projection: planned.plan,
@@ -259,21 +278,21 @@ export function planReadOperation(core, active, behaviors, request, args) {
         };
     }
     if (Array.isArray(args.include)) {
-        const planned = planIncludeLevel(core, active, behaviors, request.resource, args.include);
+        const planned = planIncludeLevel(core, model, active, compute, request.resource, args.include);
         return {
             arguments: replaceWithInternalSelect(args, planned.select),
             projection: planned.plan,
             materialize: true,
         };
     }
-    const defaults = defaultProjectionLevel(core, active, behaviors, request.resource);
+    const defaults = defaultProjectionLevel(core, model, active, compute, request.resource);
     return {
         arguments: { ...args, select: defaults.select },
         projection: defaults.plan,
         materialize: defaults.plan.computed.length > 0,
     };
 }
-async function materializeRelation(active, behaviors, request, relation, value, contextFactory) {
+async function materializeRelation(active, compute, request, relation, value, contextFactory) {
     if (value === null || value === undefined) {
         return value;
     }
@@ -281,11 +300,11 @@ async function materializeRelation(active, behaviors, request, relation, value,
         if (!Array.isArray(value)) {
             return value;
         }
-        return Promise.all(value.map((entry) => materializeRecord(active, behaviors, request, relation.projection, entry, contextFactory)));
+        return Promise.all(value.map((entry) => materializeRecord(active, compute, request, relation.projection, entry, contextFactory)));
     }
-    return materializeRecord(active, behaviors, request, relation.projection, value, contextFactory);
+    return materializeRecord(active, compute, request, relation.projection, value, contextFactory);
 }
-async function materializeRecord(active, behaviors, request, plan, value, contextFactory) {
+async function materializeRecord(active, compute, request, plan, value, contextFactory) {
     if (!isRecord(value)) {
         return value;
     }
@@ -296,24 +315,31 @@ async function materializeRecord(active, behaviors, request, plan, value, contex
     const record = { ...value };
     for (const fieldName of plan.computed) {
         const field = lookupField(resource, fieldName);
-        const behavior = readBehavior(behaviors?.[plan.resource]?.fields[fieldName]?.read);
-        if (field?.kind !== "scalar" || behavior === undefined) {
+        const stage = readCompute(compute?.[plan.resource]?.[fieldName]?.read);
+        if (field?.kind !== "scalar" || stage === undefined) {
             continue;
         }
-        const computedValue = await behavior.compute({
-            origin: request.origin,
-            resource: plan.resource,
+        const view = frozenCopy(record);
+        const computedValue = await stage.compute({
             field: fieldName,
-            value: record[fieldName],
-            record,
-            operation: contextFactory(),
+            value: view[fieldName],
+            record: view,
+            ctx: contextFactory(),
         });
         if (computedValue === undefined) {
             continue;
         }
-        const validation = normalizeScalarFieldValue(active, field, computedValue, "runtime", ["behaviors", plan.resource, fieldName, "read"]);
+        const validation = normalizeScalarFieldValue(active, field, computedValue, "runtime", [
+            "resources",
+            plan.resource,
+            "fields",
+            fieldName,
+            "pipelines",
+            "compute",
+            "read",
+        ]);
         if (!validation.ok) {
-            throw new ComputedValueError(plan.resource, fieldName, "read", validation.issues);
+            throw new AvComputedValueError(plan.resource, fieldName, "read", validation.issues);
         }
         record[fieldName] = validation.value;
     }
@@ -321,19 +347,19 @@ async function materializeRecord(active, behaviors, request, plan, value, contex
         if (!Object.hasOwn(record, relation.field)) {
             continue;
         }
-        record[relation.field] = await materializeRelation(active, behaviors, request, relation, record[relation.field], contextFactory);
+        record[relation.field] = await materializeRelation(active, compute, request, relation, record[relation.field], contextFactory);
     }
     return Object.fromEntries(plan.requested
         .filter((fieldName) => Object.hasOwn(record, fieldName))
         .map((fieldName) => [fieldName, record[fieldName]]));
 }
-export async function materializeReadOperation(active, behaviors, request, plan, value, contextFactory) {
+export async function materializeReadOperation(active, compute, request, plan, value, contextFactory) {
     const projection = plan.projection;
     if (!plan.materialize || projection === undefined) {
         return value;
     }
     if (Array.isArray(value)) {
-        return Promise.all(value.map((entry) => materializeRecord(active, behaviors, request, projection, entry, contextFactory)));
+        return Promise.all(value.map((entry) => materializeRecord(active, compute, request, projection, entry, contextFactory)));
     }
-    return materializeRecord(active, behaviors, request, projection, value, contextFactory);
+    return materializeRecord(active, compute, request, projection, value, contextFactory);
 }

package/dist/runtime/computed-value.error.d.ts

@@ -1,13 +1,14 @@
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
 /**
  * What the diagnostics channel receives when a computed value — a read or write
- * behavior's return — is one its Contract refuses: the developer's broken code,
+ * compute stage's return — is one its Contract refuses, or a `compute.create`
+ * stage returned `undefined` for a field a create cannot do without (rc.2): the developer's broken code,
  * never the caller's. It is thrown, not a deliberate outcome, so the framework's
  * boundary answers the caller the generic `A3000` and reports this error, with the
  * issues, exactly once.
  */
-export declare class ComputedValueError extends Error {
-    readonly issues: readonly ValidationIssue[];
-    readonly name = "ComputedValueError";
-    constructor(resource: string, field: string, stage: "read" | "create" | "update", issues: readonly ValidationIssue[]);
+export declare class AvComputedValueError extends Error {
+    readonly issues: readonly AvValidationIssue[];
+    readonly name = "AvComputedValueError";
+    constructor(resource: string, field: string, stage: "read" | "create" | "update", issues: readonly AvValidationIssue[], message?: string);
 }

package/dist/runtime/computed-value.error.js

@@ -1,9 +1,10 @@
-export class ComputedValueError extends Error {
+export class AvComputedValueError extends Error {
     issues;
-    name = "ComputedValueError";
-    constructor(resource, field, stage, issues) {
+    name = "AvComputedValueError";
+    constructor(resource, field, stage, issues, message) {
         const [first] = issues;
-        super(`The ${stage} behavior of ${resource}.${field} returned a value its Contract refuses${first === undefined ? "." : ` (${first.code}: ${first.message})`}`);
+        super(message ??
+            `The compute.${stage} stage of ${resource}.${field} returned a value its Contract refuses${first === undefined ? "." : ` (${first.code}: ${first.message})`}`);
         this.issues = issues;
     }
 }

package/dist/runtime/context-executor.runtime.d.ts

@@ -0,0 +1,59 @@
+import type { AvAdapter } from "../adapters/adapter.interface.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterTransactionExecutor } from "../adapters/adapter-transaction-executor.interface.js";
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationFamily } from "../operations/operation-identity.js";
+import { type AvDiagnosticsSink } from "./diagnostics-reporter.js";
+import type { AvComputeContext } from "./field-compute.js";
+import type { MisuseReporter } from "./misuse-reporter.js";
+import type { ApplicationOperationRequest } from "./operation-request.js";
+import type { AvOperationResponse } from "./operation-response.js";
+import type { AvContext, AvTransactionContext, AvTransportContext } from "./pipeline.js";
+import type { AvState } from "./request-state.js";
+/** Where a ctx's calls run: inside the open transaction, or standalone. */
+export type ExecutorScope<M extends AvAdapterModel = AvAdapterModel> = {
+    /** The request id every call of this ctx carries: its stage's request's. */
+    readonly requestId: string;
+    /** The open transaction's executor; `undefined` outside any transaction. */
+    readonly transaction: AvAdapterTransactionExecutor<M> | undefined;
+    /** The request's state, which every call of this ctx inherits. */
+    readonly state: AvState;
+};
+/** The `$` facts a ctx states, as own data properties. */
+export type ContextFacts = {
+    readonly $origin: AvRequestOrigin;
+    readonly $requestId: string;
+    readonly $transport?: AvTransportContext;
+    readonly $contract: AvContract;
+    readonly $operation?: {
+        readonly resource: string;
+        readonly family: AvOperationFamily;
+        readonly variant: string;
+        readonly nested?: true;
+    };
+    readonly $args: unknown;
+};
+/** Runs one raw application-origin call in `transaction`, or standalone. Total. */
+export type RawOperationRunner<M extends AvAdapterModel> = (request: ApplicationOperationRequest, transaction: AvAdapterTransactionExecutor<M> | undefined) => Promise<AvOperationResponse>;
+export type ContextExecutorDependencies<M extends AvAdapterModel> = {
+    /** The model, as construction read it once: the ctx's Resources. */
+    readonly model: M;
+    readonly adapter: AvAdapter<M>;
+    /** The Application Contract: a `ctx.$transaction` needs its transactions. */
+    readonly application: AvContract;
+    readonly diagnostics: AvDiagnosticsSink | undefined;
+    readonly misuse: MisuseReporter;
+    readonly run: RawOperationRunner<M>;
+};
+/** Builds the ctx every stage is told. */
+export type ContextExecutor<M extends AvAdapterModel = AvAdapterModel> = {
+    /** An operation stage's ctx: its facts and the full executor. */
+    readonly operation: (scope: ExecutorScope<M>, facts: ContextFacts) => AvContext;
+    /** A Resource transaction stage's ctx: the plan as `$args`, the full executor. */
+    readonly transaction: (scope: ExecutorScope<M>, facts: ContextFacts) => AvTransactionContext;
+    /** Compute's read-only ctx: the facts, and `find.*` reads only. */
+    readonly compute: (scope: ExecutorScope<M>, facts: ContextFacts) => AvComputeContext;
+};
+/** Builds the ctx factory of one Framework over its model. */
+export declare function createContextExecutor<M extends AvAdapterModel>(dependencies: ContextExecutorDependencies<M>): ContextExecutor<M>;