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

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

@@ -1,5 +1,7 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
 import { lookupField, lookupResource } from "../contracts/contract-lookup.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);
@@ -51,6 +53,11 @@ function addScalarProjection(core, model, active, compute, resourceName, fieldNa
     const stage = readCompute(compute?.[resourceName]?.[fieldName]?.read);
     if (stage !== undefined) {
         appendUnique(computed, fieldName);
+        if (stage.dependsOn.length === 0) {
+            for (const member of adapterPrimaryIdentifier(model, resourceName)) {
+                appendUniqueProjection(adapterSelect, member);
+            }
+        }
         for (const dependency of stage.dependsOn) {
             if (storedScalar(model, resourceName, dependency)) {
                 appendUniqueProjection(adapterSelect, dependency);
@@ -77,18 +84,27 @@ function projectionEntry(entry) {
 function withoutProjectionChoice(value) {
     return Object.fromEntries(Object.entries(value).filter(([key]) => key !== "select" && key !== "include"));
 }
-function defaultProjectionLevel(core, model, active, compute, resourceName) {
+export function defaultProjectionFields(active, resourceName) {
     const activeResource = lookupResource(active, resourceName);
+    if (activeResource === undefined) {
+        return [];
+    }
+    const fields = [];
+    for (const [fieldName, field] of Object.entries(activeResource.fields)) {
+        if (field.kind === "scalar" &&
+            field.capabilities.select === true &&
+            field.governed !== true) {
+            fields.push(fieldName);
+        }
+    }
+    return fields;
+}
+function defaultProjectionLevel(core, model, active, compute, resourceName) {
     const adapterSelect = [];
     const requested = [];
     const computed = [];
-    if (activeResource !== undefined) {
-        for (const [fieldName, field] of Object.entries(activeResource.fields)) {
-            if (field.kind !== "scalar" || field.capabilities.select !== true) {
-                continue;
-            }
-            addScalarProjection(core, model, active, compute, resourceName, fieldName, adapterSelect, requested, computed);
-        }
+    for (const fieldName of defaultProjectionFields(active, resourceName)) {
+        addScalarProjection(core, model, active, compute, resourceName, fieldName, adapterSelect, requested, computed);
     }
     return {
         select: adapterSelect,
@@ -156,6 +172,12 @@ function planSelectLevel(core, model, active, compute, resourceName, select, col
     }
     for (const entry of select) {
         if (typeof entry === "string") {
+            if (entry === "$defaults") {
+                for (const fieldName of defaultProjectionFields(active, resourceName)) {
+                    addScalarProjection(core, model, active, compute, resourceName, fieldName, adapterSelect, requested, computed);
+                }
+                continue;
+            }
             if (entry === "$count") {
                 adapterSelect.push(entry);
                 if (collectReducers) {
@@ -280,7 +302,175 @@ export function planReadOperation(core, model, active, compute, request, args) {
         materialize: defaults.plan.computed.length > 0,
     };
 }
-async function materializeRelation(active, compute, request, relation, value, contextFactory) {
+function resolveReadLevel(active, compute, plan, tail) {
+    const resource = lookupResource(active, plan.resource);
+    if (resource === undefined) {
+        return undefined;
+    }
+    const stages = [];
+    for (const fieldName of plan.computed) {
+        const field = lookupField(resource, fieldName);
+        const stage = readCompute(compute?.[plan.resource]?.[fieldName]?.read);
+        if (field?.kind !== "scalar" || stage === undefined) {
+            continue;
+        }
+        stages.push({
+            field: fieldName,
+            definition: field,
+            compute: stage.compute,
+        });
+    }
+    const relations = [];
+    let restFree = true;
+    for (const relation of [...plan.relations].reverse()) {
+        const level = resolveReadLevel(active, compute, relation.projection, tail && restFree);
+        relations.unshift({ relation, level });
+        restFree &&= level?.computeFree ?? true;
+    }
+    return {
+        plan,
+        stages,
+        relations,
+        computeFree: stages.length === 0 && restFree,
+        atOnce: tail && stages.length <= 1 && restFree,
+        plainKeys: plan.requested.every((field) => !(field in Object.prototype)),
+    };
+}
+function isNestedContainer(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !(value instanceof Date) &&
+        !(value instanceof Uint8Array));
+}
+function isThenable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
+function setOwn(target, key, value) {
+    if (key in target) {
+        Object.defineProperty(target, key, {
+            value,
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+        return;
+    }
+    target[key] = value;
+}
+function answerOf(level, record) {
+    const answer = {};
+    for (const fieldName of level.plan.requested) {
+        if (!Object.hasOwn(record, fieldName)) {
+            continue;
+        }
+        if (level.plainKeys) {
+            answer[fieldName] = record[fieldName];
+        }
+        else {
+            setOwn(answer, fieldName, record[fieldName]);
+        }
+    }
+    return answer;
+}
+function heldReadValue(active, level, stage, value) {
+    const validation = normalizeScalarFieldValue(active, stage.definition, value, "runtime", [
+        "resources",
+        level.plan.resource,
+        "fields",
+        stage.field,
+        "pipelines",
+        "compute",
+        "read",
+    ]);
+    if (!validation.ok) {
+        throw new AvComputedValueError(level.plan.resource, stage.field, "read", validation.issues);
+    }
+    return validation.value;
+}
+function projectedAtOnce(level, value) {
+    if (!isRecord(value) || level === undefined) {
+        return value;
+    }
+    const record = { ...value };
+    relationsAtOnce(level, record);
+    return answerOf(level, record);
+}
+function relationsAtOnce(level, record) {
+    for (const { relation, level: nested } of level.relations) {
+        if (!Object.hasOwn(record, relation.field)) {
+            continue;
+        }
+        const value = record[relation.field];
+        if (value === null || value === undefined) {
+            continue;
+        }
+        if (relation.cardinality === "many") {
+            if (Array.isArray(value)) {
+                record[relation.field] = Array.from(value, (entry) => projectedAtOnce(nested, entry));
+            }
+            continue;
+        }
+        record[relation.field] = projectedAtOnce(nested, value);
+    }
+}
+function computedAtOnce(active, level, stage, value, contextFactory) {
+    const record = { ...value };
+    const view = frozenCopy(record);
+    let computedValue;
+    try {
+        computedValue = stage.compute({
+            field: stage.field,
+            value: view[stage.field],
+            record: view,
+            ctx: contextFactory(),
+        });
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    const finish = (returned) => {
+        if (returned !== undefined) {
+            record[stage.field] = heldReadValue(active, level, stage, returned);
+        }
+        relationsAtOnce(level, record);
+        return answerOf(level, record);
+    };
+    const later = (error) => Promise.resolve().then(() => {
+        throw error;
+    });
+    let waits;
+    try {
+        waits = isThenable(computedValue);
+    }
+    catch (error) {
+        return later(error);
+    }
+    if (waits) {
+        const pending = computedValue;
+        return (async () => finish(await pending))();
+    }
+    try {
+        return finish(computedValue);
+    }
+    catch (error) {
+        return later(error);
+    }
+}
+function materializeRecord(active, level, value, contextFactory) {
+    if (level?.atOnce !== true) {
+        return materializeInTurn(active, level, value, contextFactory);
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    const [stage] = level.stages;
+    return stage === undefined
+        ? projectedAtOnce(level, value)
+        : computedAtOnce(active, level, stage, value, contextFactory);
+}
+async function materializeRelation(active, level, relation, value, contextFactory) {
     if (value === null || value === undefined) {
         return value;
     }
@@ -288,65 +478,62 @@ async function materializeRelation(active, compute, request, relation, value, co
         if (!Array.isArray(value)) {
             return value;
         }
-        return Promise.all(value.map((entry) => materializeRecord(active, compute, request, relation.projection, entry, contextFactory)));
+        return Promise.all(value.map((entry) => materializeRecord(active, level, entry, contextFactory)));
     }
-    return materializeRecord(active, compute, request, relation.projection, value, contextFactory);
+    return materializeRecord(active, level, value, contextFactory);
 }
-async function materializeRecord(active, compute, request, plan, value, contextFactory) {
-    if (!isRecord(value)) {
-        return value;
-    }
-    const resource = lookupResource(active, plan.resource);
-    if (resource === undefined) {
+async function materializeInTurn(active, level, value, contextFactory) {
+    if (!isRecord(value) || level === undefined) {
         return value;
     }
+    const { stages } = level;
     const record = { ...value };
-    for (const fieldName of plan.computed) {
-        const field = lookupField(resource, fieldName);
-        const stage = readCompute(compute?.[plan.resource]?.[fieldName]?.read);
-        if (field?.kind !== "scalar" || stage === undefined) {
-            continue;
+    let told;
+    if (stages.length > 1) {
+        told = { ...record };
+        for (const key of Object.keys(told)) {
+            const nested = told[key];
+            if (isNestedContainer(nested)) {
+                told[key] = frozenCopy(nested, true);
+            }
         }
+    }
+    for (const stage of stages) {
+        const view = frozenCopy(told ?? record);
         const computedValue = await stage.compute({
-            field: fieldName,
-            value: record[fieldName],
-            record,
+            field: stage.field,
+            value: view[stage.field],
+            record: view,
             ctx: contextFactory(),
         });
         if (computedValue === undefined) {
             continue;
         }
-        const validation = normalizeScalarFieldValue(active, field, computedValue, "runtime", [
-            "resources",
-            plan.resource,
-            "fields",
-            fieldName,
-            "pipelines",
-            "compute",
-            "read",
-        ]);
-        if (!validation.ok) {
-            throw new AvComputedValueError(plan.resource, fieldName, "read", validation.issues);
+        const held = heldReadValue(active, level, stage, computedValue);
+        record[stage.field] = held;
+        if (told !== undefined) {
+            told[stage.field] = held;
         }
-        record[fieldName] = validation.value;
     }
-    for (const relation of plan.relations) {
+    for (const { relation, level: nested } of level.relations) {
         if (!Object.hasOwn(record, relation.field)) {
             continue;
         }
-        record[relation.field] = await materializeRelation(active, compute, request, relation, record[relation.field], contextFactory);
+        record[relation.field] = await materializeRelation(active, nested, relation, record[relation.field], contextFactory);
     }
-    return Object.fromEntries(plan.requested
-        .filter((fieldName) => Object.hasOwn(record, fieldName))
-        .map((fieldName) => [fieldName, record[fieldName]]));
+    return answerOf(level, record);
 }
-export async function materializeReadOperation(active, compute, 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;
     }
+    const level = resolveReadLevel(active, compute, projection, true);
     if (Array.isArray(value)) {
-        return Promise.all(value.map((entry) => materializeRecord(active, compute, request, projection, entry, contextFactory)));
+        const rows = value.map((entry) => materializeRecord(active, level, entry, contextFactory));
+        return rows.some((row) => row instanceof Promise)
+            ? Promise.all(rows)
+            : Array.from(rows);
     }
-    return materializeRecord(active, compute, request, projection, value, contextFactory);
+    return materializeRecord(active, level, value, contextFactory);
 }

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

@@ -1,7 +1,8 @@
 import type { AvValidationIssue } from "../operations/validation-code.js";
 /**
  * What the diagnostics channel receives when a computed value — a read or write
- * compute stage'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.
@@ -9,5 +10,5 @@ import type { AvValidationIssue } from "../operations/validation-code.js";
 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[]);
+    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 AvComputedValueError extends Error {
     issues;
     name = "AvComputedValueError";
-    constructor(resource, field, stage, issues) {
+    constructor(resource, field, stage, issues, message) {
         const [first] = issues;
-        super(`The compute.${stage} stage 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

@@ -7,7 +7,7 @@ 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 { AvApplicationOperationRequest } 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";
@@ -35,8 +35,8 @@ export type ContextFacts = {
     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> = {
+type RawOperationRunner<M extends AvAdapterModel> = (request: AvApplicationOperationRequest, transaction: AvAdapterTransactionExecutor<M> | undefined) => Promise<AvOperationResponse>;
+type ContextExecutorDependencies<M extends AvAdapterModel> = {
     /** The model, as construction read it once: the ctx's Resources. */
     readonly model: M;
     readonly adapter: AvAdapter<M>;
@@ -57,3 +57,4 @@ export type ContextExecutor<M extends AvAdapterModel = AvAdapterModel> = {
 };
 /** Builds the ctx factory of one Framework over its model. */
 export declare function createContextExecutor<M extends AvAdapterModel>(dependencies: ContextExecutorDependencies<M>): ContextExecutor<M>;
+export {};

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

@@ -195,9 +195,10 @@ export function createContextExecutor(dependencies) {
     const contextOf = (prototype, scope, facts, readOnly = false) => {
         const context = Object.create(prototype);
         Object.defineProperty(context, STATE, {
-            value: { scope, facts, resources: new Map() },
+            value: { scope, facts, resources: undefined },
         });
-        for (const [key, value] of Object.entries(facts)) {
+        for (const key of Object.keys(facts)) {
+            const value = facts[key];
             if (value !== undefined) {
                 Object.defineProperty(context, key, { value, enumerable: true });
             }
@@ -232,6 +233,7 @@ export function createContextExecutor(dependencies) {
             Object.defineProperty(prototype, resource, {
                 get() {
                     const state = stateOf(this);
+                    state.resources ??= new Map();
                     let tree = state.resources.get(resource);
                     if (tree === undefined) {
                         tree = resourceTree(state.scope, resource, readOnly);

package/dist/runtime/core-class.brand.d.ts

@@ -0,0 +1,10 @@
+/** The registered symbol every copy of this major brands class `name` with. */
+export declare function coreBrandOf(name: string): symbol;
+/** Whether `value` carries `brand`, wherever it was made: one `in`. */
+export declare function hasCoreBrand(value: unknown, brand: symbol): boolean;
+/**
+ * Brands `type`'s prototype as `name` and makes `instanceof type` read the brand.
+ * A developer's own subclass of `type` inherits the static `Symbol.hasInstance`, so
+ * on any constructor but `type` itself it answers as `instanceof` always does.
+ */
+export declare function brandCoreClass(type: abstract new (...args: never[]) => object, name: string): symbol;

package/dist/runtime/core-class.brand.js

@@ -0,0 +1,21 @@
+import { CORE_VERSION } from "../prebuilt/core-version.generated.js";
+const CORE_MAJOR = CORE_VERSION.slice(0, CORE_VERSION.indexOf("."));
+export function coreBrandOf(name) {
+    return Symbol.for(`aventara.core.${name}@${CORE_MAJOR}`);
+}
+export function hasCoreBrand(value, brand) {
+    return typeof value === "object" && value !== null && brand in value;
+}
+const ordinaryHasInstance = Function.prototype[Symbol.hasInstance];
+export function brandCoreClass(type, name) {
+    const brand = coreBrandOf(name);
+    Object.defineProperty(type.prototype, brand, { value: true });
+    Object.defineProperty(type, Symbol.hasInstance, {
+        value: function hasInstance(value) {
+            return this === type
+                ? hasCoreBrand(value, brand)
+                : ordinaryHasInstance.call(this, value);
+        },
+    });
+    return brand;
+}

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

@@ -1,20 +1,32 @@
 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";
 type Path = readonly (string | number)[];
+/** One required field a `compute.create` stage was to fill and left missing. */
+type ComputedRequirementGap = {
+    readonly resource: string;
+    readonly field: string;
+    readonly issue: AvValidationIssue;
+};
 /**
- * What the Adapter stated beside its model that the check reads: its
- * referential edges, for the fields that hold each reference. Read once when
- * the Framework is constructed. The requirements themselves are the active
- * Contract's.
+ * 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 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 referentialActions?: ReferentialActionTable;
+    readonly model?: {
+        readonly resources: Readonly<Record<string, unknown>>;
+    };
 }): RecordWriteFacts;
 /**
  * The `V1000` issues for every create position in one operation's arguments
@@ -24,7 +36,21 @@ export declare function recordWriteFactsOf(adapter: {
  * reference both, in argument order. Empty when there are none. Total over
  * malformed input.
  */
-export declare function createRequirementIssues(contract: AvContract, facts: RecordWriteFacts, request: AvOperationIdentity & {
+export declare function createRequirementIssues(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, computed: (resource: string) => ReadonlySet<string>): readonly ComputedRequirementGap[];
 export {};