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

package/dist/operations/operation-arguments.d.ts

@@ -335,7 +335,7 @@ type IncludeRelationProjectionEntry<C extends AvContract, K extends AvResourceKe
  * One entry of a `select` argument, at one projection position. The default is
  * the unrestricted position.
  */
-export type AvProjectionEntry<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = SelectableScalarKey<C, K, Scope> | SelectableRelationKey<C, K, Scope> | SelectRelationProjectionEntry<C, K, Scope, Forms> | (AllowCount extends true ? "$count" : never);
+export type AvProjectionEntry<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = SelectableScalarKey<C, K, Scope> | SelectableRelationKey<C, K, Scope> | SelectRelationProjectionEntry<C, K, Scope, Forms> | "$defaults" | (AllowCount extends true ? "$count" : never);
 /** A `select` argument: the fields to return. */
 export type AvSelectInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope = UnrestrictedProjection, AllowCount extends boolean = false, Forms extends ScalarForms = UnstatedForms> = readonly AvProjectionEntry<C, K, Scope, AllowCount, Forms>[];
 /** An `include` argument: the relations to return with each row. */

package/dist/operations/operation-call.d.ts

@@ -55,8 +55,10 @@ export type AvOperationGrammar<C extends AvContract> = {
 export type AvOperationSlot<I extends AvOperationIdentity, Result> = I["variant"] extends "first" ? Result | null : Result;
 /** What a direct call resolves: the slot, every failure thrown. */
 type Settled<I extends AvOperationIdentity, Result> = AvOperationSlot<I, Result>;
-type ProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: CallArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
-type PlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = (...args: CallArgumentList<Args, Args, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
+/** A direct call that projects: generic in its `select`/`include` literal. */
+export type ProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: CallArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
+/** A direct call that does not project. */
+export type PlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = (...args: CallArgumentList<Args, Args, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
 /**
  * One direct call: its arguments in `Forms`, its result in `ResultForms`,
  * resolving the slot and throwing every failure, taking `Options` per call. It is generic in its
@@ -68,9 +70,11 @@ export type AvOperationCall<C extends AvContract, R extends AvResourceKey<C>, I
  * `$ref` typed in `ResultForms` — the forms the source's final data is read in, so a
  * reference carries what its source resolves.
  */
-type DeferredArguments<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = ReferenceableArgumentsFor<C, R, I, Forms, ResultForms>;
-type DeferredProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>, Origin>;
-type DeferredPlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = (...args: ArgumentList<Args, Args>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>, Origin>;
+export type DeferredArguments<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = ReferenceableArgumentsFor<C, R, I, Forms, ResultForms>;
+/** A deferred operation that projects: generic in its `select`/`include` literal. */
+export type DeferredProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>, Origin>;
+/** A deferred operation that does not project. */
+export type DeferredPlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = (...args: ArgumentList<Args, Args>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>, Origin>;
 /**
  * One deferred operation: a handle typed `AvOperation<AvOperationSlot<…>, Origin>`,
  * with `$ref` present exactly where the result is one row. A handle is not a

package/dist/operations/operation-result.d.ts

@@ -6,7 +6,8 @@ import type { AvOperationIdentity } from "./operation-identity.js";
 type FieldOf<C extends AvContract, K extends AvResourceKey<C>, F extends AvFieldKey<C, K>> = C["resources"][K]["fields"][F];
 /**
  * The fields returned when no projection is given: the scalars whose `select`
- * is exactly `true`. A write-only field never appears.
+ * is exactly `true` and that the policy does not govern. A write-only field never
+ * appears, and a governed one appears only where a projection names it.
  */
 type DefaultKey<C extends AvContract, K extends AvResourceKey<C>> = {
     [F in AvFieldKey<C, K>]: FieldOf<C, K, F> extends {
@@ -14,6 +15,7 @@ type DefaultKey<C extends AvContract, K extends AvResourceKey<C>> = {
         readonly capabilities: {
             readonly select: true;
         };
+        readonly governed?: never;
     } ? F : never;
 }[AvFieldKey<C, K>];
 /** The field one projection entry names: a bare key, or a relation entry's key. */
@@ -40,7 +42,7 @@ type ProjectedFields<C extends AvContract, K extends AvResourceKey<C>, Keys exte
  */
 type ProjectedRecord<C extends AvContract, K extends AvResourceKey<C>, Arguments, Forms extends ScalarForms> = [Arguments] extends [never] ? ProjectedFields<C, K, DefaultKey<C, K>, never, Forms> : [Arguments] extends [{
     readonly select: readonly (infer Entry)[];
-}] ? ProjectedFields<C, K, Extract<EntryKey<Entry>, AvFieldKey<C, K>>, Entry, Forms> : [Arguments] extends [{
+}] ? ProjectedFields<C, K, Extract<EntryKey<Entry>, AvFieldKey<C, K>> | (Entry extends "$defaults" ? DefaultKey<C, K> : never), Entry, Forms> : [Arguments] extends [{
     readonly include: readonly (infer Entry)[];
 }] ? ProjectedFields<C, K, DefaultKey<C, K> | Extract<EntryKey<Entry>, AvFieldKey<C, K>>, Entry, Forms> : ProjectedFields<C, K, DefaultKey<C, K>, never, Forms>;
 /**
@@ -50,7 +52,7 @@ type ProjectedRecord<C extends AvContract, K extends AvResourceKey<C>, Arguments
 type CountEnvelope<C extends AvContract, Target extends AvResourceKey<C>, Entry, Forms extends ScalarForms> = [Exclude<Entry, "$count">] extends [never] ? {
     readonly count: number;
 } : {
-    readonly data: readonly ProjectedFields<C, Target, Extract<EntryKey<Entry>, AvFieldKey<C, Target>>, Exclude<Entry, "$count">, Forms>[];
+    readonly data: readonly ProjectedFields<C, Target, Extract<EntryKey<Entry>, AvFieldKey<C, Target>> | (Entry extends "$defaults" ? DefaultKey<C, Target> : never), Exclude<Entry, "$count">, Forms>[];
     readonly count: number;
 };
 /** The entries of an argument's own `select`, or `never` when it has none. */

package/dist/operations/operation-validator-core.js

@@ -304,6 +304,12 @@ const UNDEFINED_ARGUMENT_MESSAGES = {
     offset: "offset must not be undefined: leave the key out to mean no offset.",
     cursor: "cursor must not be undefined: leave the key out to mean no cursor.",
 };
+const EMPTY_BOOLEAN_NODE_MESSAGE = "A boolean node must hold a condition here: an empty one matches every row, and the write would reach more rows.";
+function isEmptyBooleanNode(value) {
+    return Array.isArray(value)
+        ? value.length === 0
+        : isRecord(value) && Object.keys(value).length === 0;
+}
 function validateWhere(contract, resourceName, where, path, state, depth) {
     if (!checkDepth(contract, state, depth)) {
         return;
@@ -322,6 +328,13 @@ function validateWhere(contract, resourceName, where, path, state, depth) {
         return;
     }
     for (const [key, value] of Object.entries(where)) {
+        if (state.refuseEmptyNodes === true &&
+            (key === "AND" || key === "OR" || key === "NOT") &&
+            isEmptyBooleanNode(value)) {
+            countFilterNode(contract, state);
+            addIssue(state.issues, "V1001", [...path, key], EMPTY_BOOLEAN_NODE_MESSAGE);
+            continue;
+        }
         if (key === "AND" || key === "OR") {
             countFilterNode(contract, state);
             if (!Array.isArray(value)) {
@@ -329,6 +342,10 @@ function validateWhere(contract, resourceName, where, path, state, depth) {
                 continue;
             }
             value.forEach((entry, index) => {
+                if (state.refuseEmptyNodes === true && isEmptyBooleanNode(entry)) {
+                    addIssue(state.issues, "V1001", [...path, key, index], EMPTY_BOOLEAN_NODE_MESSAGE);
+                    return;
+                }
                 validateWhere(contract, resourceName, entry, [...path, key, index], state, depth + 1);
             });
             continue;
@@ -507,6 +524,12 @@ function validateProjection(contract, resourceName, mode, value, scope, path, is
     }
     value.forEach((entry, index) => {
         const entryPath = [...path, index];
+        if (entry === "$defaults") {
+            if (mode !== "select") {
+                addIssue(issues, "V1008", entryPath, "$defaults is a select entry: include already returns the default fields.");
+            }
+            return;
+        }
         if (entry === "$count") {
             if (mode !== "select" ||
                 reducerOwner?.edge.cardinality !== "many" ||
@@ -687,8 +710,8 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
             addIssue(issues, "V1012", path, "To-many $disconnect requires one or more unique identifiers.");
             return;
         }
-        for (const selector of selectors) {
-            validateUniqueSelector(contract, target, selector, path, issues);
+        for (const { entry: selector, at } of entriesOf(edge, value, path)) {
+            validateUniqueSelector(contract, target, selector, at, issues);
         }
         return;
     }
@@ -703,84 +726,81 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
             addIssue(issues, "V1012", path, "To-many $set requires an identifier array.");
             return;
         }
-        for (const selector of value) {
-            validateUniqueSelector(contract, target, selector, path, issues);
+        for (const { entry: selector, at } of entriesOf(edge, value, path)) {
+            validateUniqueSelector(contract, target, selector, at, issues);
         }
         return;
     }
     if (directive === "$connect") {
-        const selectors = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const selector of selectors) {
-            validateUniqueSelector(contract, target, selector, path, issues);
+        for (const { entry: selector, at } of entriesOf(edge, value, path)) {
+            validateUniqueSelector(contract, target, selector, at, issues);
         }
         return;
     }
     if (directive === "$create") {
-        const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const entry of entries) {
-            validateMutationData(contract, target, entry, "create", NESTED_WRITE_SCOPE, path, issues, transactionReferences);
+        for (const { entry, at } of entriesOf(edge, value, path)) {
+            validateMutationData(contract, target, entry, "create", NESTED_WRITE_SCOPE, at, issues, transactionReferences);
         }
         return;
     }
     if (directive === "$connectOrCreate") {
-        const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const entry of entries) {
+        for (const { entry, at } of entriesOf(edge, value, path)) {
             if (!isRecord(entry) || !("where" in entry) || !("create" in entry)) {
-                addIssue(issues, "V1012", path, "$connectOrCreate requires where and create.");
+                addIssue(issues, "V1012", at, "$connectOrCreate requires where and create.");
                 continue;
             }
-            validateUniqueSelector(contract, target, entry.where, [...path, "where"], issues);
-            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...path, "create"], issues, transactionReferences);
+            validateUniqueSelector(contract, target, entry.where, [...at, "where"], issues);
+            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...at, "create"], issues, transactionReferences);
         }
         return;
     }
     if (directive === "$update") {
-        const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const entry of entries) {
+        for (const { entry, at } of entriesOf(edge, value, path)) {
             if (!isRecord(entry) || !("data" in entry)) {
-                addIssue(issues, "V1012", path, "$update requires a data object.");
+                addIssue(issues, "V1012", at, "$update requires a data object.");
                 continue;
             }
             if (edge.cardinality === "many" && !("where" in entry)) {
-                addIssue(issues, "V1012", path, "To-many $update requires where.");
+                addIssue(issues, "V1012", at, "To-many $update requires where.");
                 continue;
             }
             if ("where" in entry) {
                 const state = {
                     issues,
-                    structuralRoot: [...path, "where"],
+                    structuralRoot: [...at, "where"],
                     transactionReferences,
                     scalarOnly: edge.capabilities.nestedWriteFilter === "scalar",
+                    ...(edge.cardinality === "many" ? { refuseEmptyNodes: true } : {}),
                     booleanFilterNodes: 0,
                     nestingExceeded: false,
                     booleanNodesExceeded: false,
                 };
-                validateWhere(contract, target, entry.where, [...path, "where"], state, 1);
+                validateWhere(contract, target, entry.where, [...at, "where"], state, 1);
             }
             validateMutationData(contract, target, entry.data, "update", edge.cardinality === "many"
                 ? TO_MANY_UPDATE_WRITE_SCOPE
-                : NESTED_WRITE_SCOPE, [...path, "data"], issues, transactionReferences);
+                : NESTED_WRITE_SCOPE, [...at, "data"], issues, transactionReferences);
         }
         return;
     }
     if (directive === "$delete") {
-        const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const entry of entries) {
+        for (const { entry, at } of entriesOf(edge, value, path)) {
             if (edge.cardinality === "many") {
                 if (!isRecord(entry) || !("where" in entry)) {
-                    addIssue(issues, "V1012", path, "To-many $delete requires where.");
+                    addIssue(issues, "V1012", at, "To-many $delete requires where.");
                     continue;
                 }
                 const state = {
                     issues,
-                    structuralRoot: [...path, "where"],
+                    structuralRoot: [...at, "where"],
                     transactionReferences,
                     scalarOnly: edge.capabilities.nestedWriteFilter === "scalar",
+                    refuseEmptyNodes: true,
                     booleanFilterNodes: 0,
                     nestingExceeded: false,
                     booleanNodesExceeded: false,
                 };
-                validateWhere(contract, target, entry.where, [...path, "where"], state, 1);
+                validateWhere(contract, target, entry.where, [...at, "where"], state, 1);
             }
             else if (entry !== true &&
                 (!isRecord(entry) || Object.keys(entry).some((key) => key !== "where"))) {
@@ -802,23 +822,27 @@ function validateRelationMutationEntry(contract, edge, directive, value, path, i
         return;
     }
     if (directive === "$upsert") {
-        const entries = edge.cardinality === "many" && Array.isArray(value) ? value : [value];
-        for (const entry of entries) {
+        for (const { entry, at } of entriesOf(edge, value, path)) {
             if (!isRecord(entry) ||
                 !("create" in entry) ||
                 !("update" in entry) ||
                 (edge.cardinality === "many" && !("where" in entry))) {
-                addIssue(issues, "V1012", path, "$upsert requires create/update and requires where on to-many relations.");
+                addIssue(issues, "V1012", at, "$upsert requires create/update and requires where on to-many relations.");
                 continue;
             }
             if ("where" in entry) {
-                validateUniqueSelector(contract, target, entry.where, [...path, "where"], issues);
+                validateUniqueSelector(contract, target, entry.where, [...at, "where"], issues);
             }
-            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...path, "create"], issues, transactionReferences);
-            validateMutationData(contract, target, entry.update, "update", NESTED_WRITE_SCOPE, [...path, "update"], issues, transactionReferences);
+            validateMutationData(contract, target, entry.create, "create", NESTED_WRITE_SCOPE, [...at, "create"], issues, transactionReferences);
+            validateMutationData(contract, target, entry.update, "update", NESTED_WRITE_SCOPE, [...at, "update"], issues, transactionReferences);
         }
     }
 }
+function entriesOf(edge, value, path) {
+    return edge.cardinality === "many" && Array.isArray(value)
+        ? value.map((entry, index) => ({ entry, at: [...path, index] }))
+        : [{ entry: value, at: path }];
+}
 function validateRelationMutation(contract, fieldName, field, value, stage, scope, path, issues, transactionReferences) {
     const directives = advertisedDirectivesAt(field.capabilities[stage], scope);
     if (directives === undefined) {
@@ -896,6 +920,14 @@ function validateMutationArguments(contract, resourceName, request, args, issues
         }
     }
 }
+function emptyNodeRefusalOf(request) {
+    return (request.family === "update" || request.family === "delete") &&
+        (request.variant === "many" ||
+            request.variant === "count" ||
+            request.variant === "first")
+        ? { refuseEmptyNodes: true }
+        : {};
+}
 function isUniqueOperation(request) {
     return (request.variant === "unique" &&
         (request.family === "find" ||
@@ -941,6 +973,7 @@ export function validateOperationArguments(contract, request, options) {
                 issues,
                 structuralRoot: ["arguments", "where"],
                 transactionReferences: options?.transactionReferences === true,
+                ...emptyNodeRefusalOf(request),
                 booleanFilterNodes: 0,
                 nestingExceeded: false,
                 booleanNodesExceeded: false,

package/dist/operations/validation-code.guidance.js

@@ -4,7 +4,7 @@ export const VALIDATION_CODE_GUIDANCE = {
         fix: "Send the value at the issue's path. When the server must fill it, give the field a compute.create stage or a database default; a pipe cannot fill it.",
     },
     V1001: {
-        cause: "A value of the wrong type: a string where a number is expected, a negative limit, a non-integer id, null given to an operator with no null meaning (gt, contains, in), two directives in one scalar action object (`{ $increment: 1, $decrement: 2 }`), or a server-side value that is not plain data.",
+        cause: "A value of the wrong type: a string where a number is expected, a negative limit, a non-integer id, null given to an operator with no null meaning (gt, contains, in), two directives in one scalar action object (`{ $increment: 1, $decrement: 2 }`), or a server-side value that is not plain data. Also a value that would make the call reach more rows: `undefined` in a filter, a unique selector or a cursor, an empty boolean node (`NOT: {}`, `AND: []`, `OR: []`) in the where of a write (update or delete many, count or first, a to-many $update or $delete).",
         fix: "Send the type the contract states at that path (the generated client's types say it).",
     },
     V1002: {
@@ -16,7 +16,7 @@ export const VALIDATION_CODE_GUIDANCE = {
         fix: "Send the canonical encoding (ISO-8601 UTC datetime, decimal string, base64 bytes) and satisfy the validator that check and params name.",
     },
     V1004: {
-        cause: "A number, length or size outside its range: a failed bound, length or size validator, a BigInt outside signed 64 bits, an AvZ.int() outside the safe integer range, or a transaction with no operations.",
+        cause: "A number, length or size outside its range: a failed bound, length or size validator, a BigInt outside signed 64 bits, an AvZ.int() outside the safe integer range, or a transaction with no operations. Under A2004 it is also a value the database refused as too long or out of its range, a BigInt beyond what the data source's driver can bind among them (some bind at most ±(2^53 − 1)).",
         fix: "Send a value inside the range; check and params name the validator that failed.",
     },
     V1005: {

package/dist/policy/policy-admission.d.ts

@@ -0,0 +1,22 @@
+import type { AvContract, AvContractCore } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import { type PolicyAction, type PolicySession } from "./policy-session.js";
+/** The refusal every policy decision answers: `A4002`. */
+export declare function policyRefusal(message: string): AvOperationFailureResponse;
+/** The actions an operation family asks the engine about. */
+export declare function policyActionsOf(family: AvOperationIdentity["family"]): readonly PolicyAction[];
+/**
+ * Policy admission for one request (see the module comment): the refusal, or
+ * `undefined` when the request may go on to its guards.
+ */
+export declare function admitByPolicy(session: PolicySession, core: AvContractCore, active: AvContract, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown): Promise<AvOperationFailureResponse | undefined>;
+/**
+ * The write half of policy admission: every field the write sends against
+ * `fieldsOf(write)`, nested records included, the refusal or `undefined`.
+ */
+export declare function admitWriteByPolicy(session: PolicySession, core: AvContractCore, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown): Promise<AvOperationFailureResponse | undefined>;