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

package/dist/adapters/adapter-field.d.ts

@@ -24,6 +24,28 @@ export type AvAdapterRelationField<M extends AvAdapterModel> = {
     readonly cardinality: "one" | "many";
     readonly nullable: boolean;
     readonly capabilities: AvRelationFieldCapabilities;
+    /**
+     * The target's relation field that is this relation's other end, when the data
+     * source pairs them (`User.posts` ↔ `Post.author`; a self-relation's two ends
+     * name each other). Absent: no pairing is stated, and no write is read as
+     * walking a relation back.
+     */
+    readonly inverse?: string;
+    /**
+     * The scalar fields of this Resource that hold the relation's reference, in
+     * the order the data source pairs them with the target's key
+     * (`Post.author` → `["authorId"]`), on an optional relation as on a required
+     * one. Absent on the end that holds no reference (`User.posts`); never empty.
+     */
+    readonly referenceFields?: readonly [string, ...string[]];
+    /**
+     * The target's scalar fields that `referenceFields` name, pair by pair in
+     * the same order (`Post.author`: `referenceFields: ["authorId"]`,
+     * `references: ["id"]`, so `Post.authorId` holds `User.id`). Stated only
+     * beside `referenceFields`, with as many entries; absent on the end that
+     * holds no reference, where the other end (`inverse`) states the pairs.
+     */
+    readonly references?: readonly [string, ...string[]];
 };
 /** One field the adapter discovered: a scalar or a relation. */
 export type AvAdapterField<M extends AvAdapterModel> = AvAdapterScalarField<M> | AvAdapterRelationField<M>;

package/dist/adapters/adapter-identifier.d.ts

@@ -13,3 +13,12 @@ export type AvAdapterIdentifier<TFields extends Readonly<Record<string, AvAdapte
     AvAdapterScalarFieldKey<TFields>,
     ...AvAdapterScalarFieldKey<TFields>[]
 ];
+/**
+ * The Resource's identifier as the Adapter states it first: in the Adapter's
+ * own order (an ORM adapter's is its schema's, so the primary key). The Core
+ * Contract sorts identifiers for its hash, so its first one is the
+ * alphabetically first (`email` before `id`) and says nothing about which is
+ * the primary key; the model keeps the order it declared. Empty for a Resource
+ * the model does not hold or that has no identifier.
+ */
+export declare function adapterPrimaryIdentifier(model: AvAdapterModel, resource: string): readonly string[];

package/dist/adapters/adapter-identifier.js

@@ -1 +1,6 @@
-export {};
+export function adapterPrimaryIdentifier(model, resource) {
+    const resources = model.resources;
+    return ((Object.hasOwn(resources, resource)
+        ? resources[resource]?.identifiers?.[0]
+        : undefined) ?? []);
+}

package/dist/adapters/adapter-model.d.ts

@@ -1,3 +1,4 @@
+import type { AvConfigComputedFields } from "../config/computed-fields.js";
 import type { AvEnumDefinition } from "../contracts/enum-definition.js";
 import type { ReferenceWriteLimit } from "../contracts/reference-write-limit.js";
 import type { AvScalarRegistry } from "../contracts/scalar.js";
@@ -23,4 +24,12 @@ export interface AvAdapterModel {
      * either way. Compiled into every Contract.
      */
     readonly referenceWrites?: ReferenceWriteLimit;
+    /**
+     * Type-only, never present at runtime: which fields the configuration's write
+     * compute fills, as an adapter's generate step read them off the
+     * configuration's type. A variant's guards, pipes and filters may leave
+     * exactly those out of a create. Absent: any create field may be computed, so
+     * those stages require none.
+     */
+    readonly "~computedFields"?: AvConfigComputedFields;
 }

package/dist/adapters/adapter-operation.d.ts

@@ -2,9 +2,24 @@ import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
 import type { AvAdapterModel } from "./adapter-model.js";
 /**
- * Provider execution request after framework semantic validation.
- * Operation identity and arguments remain provider-neutral; adapters receive
- * only validated semantic argument objects, never raw transport input.
+ * Provider execution request after framework semantic validation. Operation
+ * identity and arguments remain provider-neutral; adapters receive only validated
+ * semantic argument objects, never raw transport input.
+ *
+ * Three shapes exist here only, each an `AND`: a list of conditions in the general
+ * `where` grammar the addressed row must also meet.
+ *
+ * - The flat unique selector of an `update.unique` or a `delete.unique` may carry
+ *   it. A row the selector names that misses them is a miss (the same `null` as a
+ *   row that is not there).
+ * - A `cursor` may carry it, at the root of a `find.many` and in a to-many
+ *   relation's arguments. A row the cursor names that misses them is a cursor that
+ *   names no row: the same answer as a cursor on a row that is not there.
+ * - A row the selector names that misses them, or no row, is refused: the adapter
+ *   fails the operation with `A4002`.
+ *
+ * An adapter must honour it or refuse the operation, never drop it: dropping it
+ * would write a row the conditions exclude, or position a page at one.
  */
 export type AvAdapterOperation<M extends AvAdapterModel = AvAdapterModel> = AvOperationIdentity & {
     readonly resource: Extract<keyof M["resources"], string>;

package/dist/adapters/adapter-resource.d.ts

@@ -26,4 +26,9 @@ export type AvAdapterResource<M extends AvAdapterModel, TFields extends AvAdapte
      * cannot say; nothing is then checked or typed before the store.
      */
     readonly createRequirements?: AvCreateRequirements;
+    /**
+     * The database schema the store keeps this Resource in (a PostgreSQL schema,
+     * say), when the store has schemas and the model names one. Absent otherwise.
+     */
+    readonly schema?: string;
 };

package/dist/adapters/adapter.interface.d.ts

@@ -1,3 +1,4 @@
+import type { AvConfigComputedFields } from "../config/computed-fields.js";
 import type { ReferentialActionTable } from "../runtime/referential-action.js";
 import type { AvAdapterModel } from "./adapter-model.js";
 import type { AvAdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
@@ -30,6 +31,15 @@ export interface AvAdapter<M extends AvAdapterModel = AvAdapterModel> extends Av
      * or `$set` runs the target's `update` guards.
      */
     readonly referentialActions?: ReferentialActionTable;
+    /**
+     * Optional: which fields the configuration's write compute fills, as the
+     * Adapter's generate step read them when it wrote the model's type (the same
+     * statement as the type's `"~computedFields"`). When the Framework is
+     * constructed it is compared with the configuration, and a difference is a
+     * warning that the generated types are stale (`aventara:prepare` regenerates
+     * them); it changes no behaviour. Never part of a Contract or its hash.
+     */
+    readonly computedFields?: AvConfigComputedFields;
     /**
      * Optional: `true` when the Adapter runs developer SQL statements: standalone
      * through its own {@link executeSql}, and, when it has `transaction`, inside a

package/dist/avz/avz.d.ts

@@ -49,7 +49,7 @@ export interface AvZOptional<Inner extends AvZShape = AvZShape> extends AvZShape
 /** A shape that also admits `null`. */
 export type AvZNullable<Inner extends AvZShape = AvZShape> = AvZShape<JsonShapeValue<Inner> | null, "nullable"> & (Inner extends AvZOptionalKey ? AvZOptionalKey : unknown);
 /** A value a literal shape may hold. */
-export type AvZLiteralValue = JsonSchemaPrimitive;
+type AvZLiteralValue = JsonSchemaPrimitive;
 /** What keys a record shape: any string, an enum's values or one literal. */
 type AvZRecordKey = AvZShape<string, "string"> | AvZShape<string, "enum"> | AvZShape<string, "literal">;
 /** An option of a discriminated union: an object whose discriminator is a literal or an enum. */

package/dist/avz/json-shape.registry.d.ts

@@ -3,7 +3,7 @@ import type { AvScalarField } from "../contracts/field.js";
 import type { JsonSchema } from "../contracts/json-shape.js";
 import type { AvValidationIssue } from "../operations/validation-code.js";
 /** What core may do with a Json Shape: read its Contract form, check a value. */
-export type JsonShapeRuntime = {
+type JsonShapeRuntime = {
     /** The shape's Contract form. */
     readonly schema: JsonSchema;
     /**
@@ -20,3 +20,4 @@ export declare function jsonShapeOf(value: unknown): JsonShapeRuntime | undefine
 export declare function bindShapedField(field: AvScalarField<AvContract>, shape: JsonShapeRuntime): void;
 /** The shape a compiled Contract field enforces, or `undefined`. */
 export declare function shapeOfField(field: AvScalarField<AvContract>): JsonShapeRuntime | undefined;
+export {};

package/dist/compiler/contract-compiler-diagnostic.guidance.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorCodeDescription } from "../runtime/error-guidance.js";
+import type { AvContractCompilerDiagnosticCode } from "./contract-compiler-diagnostic.js";
+/** Meaning, cause and fix of every contract-compilation diagnostic code. */
+export declare const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE: {
+    readonly [C in AvContractCompilerDiagnosticCode]: ErrorCodeDescription;
+};

package/dist/compiler/contract-compiler-diagnostic.guidance.js

@@ -0,0 +1,97 @@
+export const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE = {
+    COMPILER_UNKNOWN_RESOURCE: {
+        message: "Unknown Resource.",
+        cause: "A Resource name the adapter's model does not have, in resources or in exemptions; or a client or agent entry for a Resource managed elsewhere, which those layers never have.",
+        fix: "Use the model's exact name. After a schema change run `npm run aventara:prepare`. Configure a Resource managed elsewhere at the root or in application only.",
+    },
+    COMPILER_UNKNOWN_FIELD: {
+        message: "Unknown field.",
+        cause: "A field that is neither in the schema nor defined at the root.",
+        fix: "Fix the name, run aventara:prepare after a schema change, or add the field with a root definition.",
+    },
+    COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED: {
+        message: "A relation field takes write guards only.",
+        cause: "Field pipes or compute on a relation field.",
+        fix: "Put the stage on the relation's reference field, or use an operation pipe.",
+    },
+    COMPILER_INCOMPLETE_FIELD: {
+        message: "An added field is incomplete.",
+        cause: "A definition that adds a field leaves out type, nullable or list.",
+        fix: 'Spell out type, nullable and list, with lifecycle: ["VIRTUAL"] for a field that has no column.',
+    },
+    COMPILER_STRUCTURAL_FIELD_OVERRIDE: {
+        message: "A discovered field's structure was redefined.",
+        cause: "A definition on a field the adapter discovered changes its type, format or capabilities.",
+        fix: "Restate only its type, nullable and list. Change capabilities through exemptions and the column through the schema.",
+    },
+    COMPILER_MISSING_SCALAR: {
+        message: "Unknown scalar type.",
+        cause: "A definition names a scalar type that does not exist.",
+        fix: "Use a built-in scalar: string, boolean, int, float, bigint, decimal, datetime, bytes or json.",
+    },
+    COMPILER_MISSING_ENUM: {
+        message: "Unknown enum.",
+        cause: "A definition names an enum the model does not have.",
+        fix: "Use an enum of the schema, and run aventara:prepare after adding one.",
+    },
+    COMPILER_DANGLING_RELATION: {
+        message: "A visible relation points at a hidden Resource.",
+        cause: "A layer hides a Resource but still exposes a relation field that targets it.",
+        fix: "Hide the relation field too (`exemptions.resources.<R>.fields.<relation>: true`), or expose the target.",
+    },
+    COMPILER_UNAVAILABLE_OPERATION: {
+        message: "Operation not available.",
+        cause: "An operation the adapter does not offer (such as delete.many), or an overlay granting one that its parent hid.",
+        fix: "Remove it. To reach an operation from one overlay only, expose it at the root and hide it in the other overlay.",
+    },
+    COMPILER_UNAVAILABLE_CAPABILITY: {
+        message: "Capability not available.",
+        cause: "A capability or token the field does not offer, or an overlay (or the agent layer) granting one its parent hid. Overlays only narrow.",
+        fix: "Remove it, or expose it in the parent layer and hide it in the layer it must not reach.",
+    },
+    COMPILER_INVALID_LIFECYCLE: {
+        message: "Invalid field lifecycle.",
+        cause: "An added field declares a lifecycle other than VIRTUAL, a VIRTUAL field claims a database-generated lifecycle or a provider-side capability, or a definition redefines a discovered field's lifecycle.",
+        fix: 'Give an added field lifecycle: ["VIRTUAL"] and only the capabilities it can serve; computed lifecycles come from compute stages.',
+    },
+    COMPILER_MISSING_READ_COMPUTE: {
+        message: "A selectable virtual field has no compute.read.",
+        cause: "A VIRTUAL field that can be selected has no pipelines.compute.read stage.",
+        fix: "Add a compute.read stage, or make the field write-only with capabilities.select: false.",
+    },
+    COMPILER_INVALID_COMPUTE_DEPENDENCY: {
+        message: "Invalid compute.read dependency.",
+        cause: "A dependsOn entry that is not a stored scalar field of the same Resource.",
+        fix: "List only stored scalar fields of the Resource in dependsOn.",
+    },
+    COMPILER_RESERVED_RESOURCE_NAME: {
+        message: "Reserved Resource name.",
+        cause: "A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref), or is the name of a member beside the Resources: all on serverClient (and so on Next.js's avClient), and on a host that adds its own, one of those (on Next.js: tx and transaction on avClient, appTx and transaction on avApp).",
+        fix: "Rename the model; the table it maps to can keep its name. A host member's name is also left free when the layer it belongs to hides the Resource.",
+    },
+    COMPILER_MISSING_IDENTIFIER: {
+        message: "A unique operation has no identifier.",
+        cause: "A layer exposes a unique variant (find.unique, update.unique, delete.unique, upsert.unique) and no complete identifier of the Resource: a Pick that did not pick one, or an Omit that hid every one.",
+        fix: "Expose an identifier field (id, or every field of one unique), or exempt the unique variants.",
+    },
+    COMPILER_HIDDEN_REQUIRED_FIELD: {
+        message: "A layer that creates a Resource hides a required field.",
+        cause: "A layer still creates the Resource (a create or upsert variant, or a nested create) while a required field, or a required relation's reference field, is hidden or has its create capability exempted, and no compute.create fills it.",
+        fix: "Expose the field, give it a compute.create stage, or exempt the layer's create operations.",
+    },
+    COMPILER_INVALID_VALIDATOR: {
+        message: "A field validator cannot apply.",
+        cause: "A validator that is not built with AvZ, does not fit the field's type (AvZ.maxLength on an int, AvZ.maxItems on a field that is not a list), or sits on a relation or Json field.",
+        fix: "Use an AvZ check that fits the field's type; a Json field's checks go in its json shape.",
+    },
+    COMPILER_INVALID_JSON_SHAPE: {
+        message: "A Json shape cannot apply.",
+        cause: "A json shape on a field that is not a discovered Json field, a shape not built with AvZ, or one that admits null or absence at its top level.",
+        fix: "Put the shape on a Json field, build it with AvZ, and keep its top level non-null (the column's nullability decides null).",
+    },
+    COMPILER_INVALID_CLIENT_CONTRACT: {
+        message: "The compiled client contract is invalid.",
+        cause: "The finished client contract failed its own structural check: a framework defect.",
+        fix: "Report it with the diagnostic's path and message.",
+    },
+};

package/dist/compiler/contract.compiler.d.ts

@@ -30,3 +30,9 @@ export type ContractCompilationResult = {
  * Agent Contract from the view of the layer it extends.
  */
 export declare function compileContracts<M extends AvAdapterModel>(model: M, config: ResolvedFrameworkConfig<M>): Promise<ContractCompilationResult>;
+/**
+ * Binds Contracts loaded from a prebuilt file to the runtime pieces
+ * {@link compileContracts} binds to the ones it compiles, from the live
+ * `config` and `model` they were compiled from.
+ */
+export declare function bindPrebuiltContracts<M extends AvAdapterModel>(model: M, config: ResolvedFrameworkConfig<M>, contracts: AvContracts): void;