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

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

@@ -1,12 +1,14 @@
-import type { Contract } from "../contracts/contract.js";
+import type { AvContract } from "../contracts/contract.js";
 import type { ScalarForms } from "../contracts/scalar-value-type.js";
-import type { OperationResponse } from "../runtime/operation-response.js";
-import type { Operation } from "../transactions/deferred-operation.js";
+import type { AvOperation } from "../transactions/deferred-operation.js";
 import type { ReferenceableArgumentsFor } from "../transactions/transaction-reference.js";
-import type { OperationArgumentsFor, ResourceKey } from "./operation-arguments.js";
-import type { OperationFamily, OperationIdentity, OperationVariant } from "./operation-identity.js";
+import type { AvOperationArgumentsFor, AvResourceKey } from "./operation-arguments.js";
+import type { AvOperationFamily, AvOperationIdentity, AvOperationVariant } from "./operation-identity.js";
 import type { AdmittedOperationResult } from "./operation-result.js";
 type ProjectionKey = "select" | "include";
+/** The origin of a deferred handle's builder (`AvOperationHandle`). */
+type HandleOrigin = "application" | "client";
+type AnyOrigin = any;
 type SelectOf<Args> = Args extends {
     readonly select?: infer Select;
 } ? Exclude<Select, undefined> : never;
@@ -30,15 +32,15 @@ type InferredProjection<Select, Include> = [Select] extends [never] ? [Include]
 type ArgumentList<Rest, Parameter> = Record<never, never> extends Rest ? [args?: Parameter] : [args: Parameter];
 /** A direct call's parameters: the argument, then the caller's per-call options. */
 type CallArgumentList<Rest, Parameter, Options> = Record<never, never> extends Rest ? [args?: Parameter, options?: Options] : [args: Parameter, options?: Options];
-type ResourceOperationsOf<C extends Contract, R extends ResourceKey<C>> = C["resources"][R]["operations"];
+type ResourceOperationsOf<C extends AvContract, R extends AvResourceKey<C>> = C["resources"][R]["operations"];
 /**
  * The operations Contract `C` advertises: one property per Resource, one per
  * family under it, one identity per variant under that.
  */
-export type OperationGrammar<C extends Contract> = {
-    readonly [R in ResourceKey<C>]: {
-        readonly [F in Extract<keyof ResourceOperationsOf<C, R>, OperationFamily>]: {
-            readonly [V in Extract<keyof NonNullable<ResourceOperationsOf<C, R>[F]>, OperationVariant<F>>]: Extract<OperationIdentity, {
+export type AvOperationGrammar<C extends AvContract> = {
+    readonly [R in AvResourceKey<C>]: {
+        readonly [F in Extract<keyof ResourceOperationsOf<C, R>, AvOperationFamily>]: {
+            readonly [V in Extract<keyof NonNullable<ResourceOperationsOf<C, R>[F]>, AvOperationVariant<F>>]: Extract<AvOperationIdentity, {
                 readonly family: F;
                 readonly variant: V;
             }>;
@@ -50,33 +52,34 @@ export type OperationGrammar<C extends Contract> = {
  * This is the value a committed transaction or a remote call returns for the
  * operation.
  */
-export type OperationSlot<I extends OperationIdentity, Result> = I["variant"] extends "first" ? Result | null : Result;
-/**
- * What a direct call resolves, by its `Settlement`: `"response"` — the whole
- * `OperationResponse`, as core's façades answer in process, never throwing;
- * `"data"` — the slot, as a remote client answers, every failure thrown.
- */
-type Settled<Settlement extends "response" | "data", I extends OperationIdentity, Result> = Settlement extends "data" ? OperationSlot<I, Result> : OperationResponse<Result>;
-type ProjectingCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Args, ResultForms extends ScalarForms, Settlement extends "response" | "data", 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<Settlement, I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
-type PlainCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Args, ResultForms extends ScalarForms, Settlement extends "response" | "data", Options> = (...args: CallArgumentList<Args, Args, Options>) => Promise<Settled<Settlement, I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
+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>;
+/** 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>, NoInfer<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 as `Settlement` says, taking `Options` per call — generic in its
+ * resolving the slot and throwing every failure, taking `Options` per call. It is generic in its
  * projection when it carries one.
  */
-export type OperationCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms, Settlement extends "response" | "data", Options> = "select" extends keyof OperationArgumentsFor<C, R, I, Forms> ? ProjectingCall<C, R, I, OperationArgumentsFor<C, R, I, Forms>, ResultForms, Settlement, Options> : PlainCall<C, R, I, OperationArgumentsFor<C, R, I, Forms>, ResultForms, Settlement, Options>;
+export type AvOperationCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms, Options> = "select" extends keyof AvOperationArgumentsFor<C, R, I, Forms> ? ProjectingCall<C, R, I, AvOperationArgumentsFor<C, R, I, Forms>, ResultForms, Options> : PlainCall<C, R, I, AvOperationArgumentsFor<C, R, I, Forms>, ResultForms, Options>;
 /**
  * A deferred operation's arguments: `Forms`, with reference positions opened to a
  * `$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 Contract, R extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = ReferenceableArgumentsFor<C, R, I, Forms, ResultForms>;
-type DeferredProjectingCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Args, ResultForms extends ScalarForms> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>>) => Operation<OperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
-type DeferredPlainCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Args, ResultForms extends ScalarForms> = (...args: ArgumentList<Args, Args>) => Operation<OperationSlot<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
+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>, NoInfer<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 `Operation<OperationSlot<…>>` — `$ref`
- * present exactly where the result is one row. A handle is not a request and takes no
- * options.
+ * One deferred operation: a handle typed `AvOperation<AvOperationSlot<…>, Origin>`,
+ * with `$ref` present exactly where the result is one row. A handle is not a
+ * request and takes no options. `Origin` is the builder's: a transaction's
+ * handles all share one.
  */
-export type DeferredOperationCall<C extends Contract, R extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = "select" extends keyof DeferredArguments<C, R, I, Forms, ResultForms> ? DeferredProjectingCall<C, R, I, DeferredArguments<C, R, I, Forms, ResultForms>, ResultForms> : DeferredPlainCall<C, R, I, DeferredArguments<C, R, I, Forms, ResultForms>, ResultForms>;
+export type AvDeferredOperationCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms, Origin extends HandleOrigin = AnyOrigin> = "select" extends keyof DeferredArguments<C, R, I, Forms, ResultForms> ? DeferredProjectingCall<C, R, I, DeferredArguments<C, R, I, Forms, ResultForms>, ResultForms, Origin> : DeferredPlainCall<C, R, I, DeferredArguments<C, R, I, Forms, ResultForms>, ResultForms, Origin>;
 export {};

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

@@ -1,18 +1,18 @@
-import type { ResourceOperations } from "../contracts/resource-operations.js";
+import type { AvResourceOperations } from "../contracts/resource-operations.js";
 /** A standard operation family: `find`, `create`, `update`, `delete` or `upsert`. */
-export type OperationFamily = Extract<keyof ResourceOperations, string>;
+export type AvOperationFamily = Extract<keyof AvResourceOperations, string>;
 /** The variants of operation family `F`, such as `many` or `unique`. */
-export type OperationVariant<F extends OperationFamily> = Extract<keyof NonNullable<ResourceOperations[F]>, string>;
+export type AvOperationVariant<F extends AvOperationFamily> = Extract<keyof NonNullable<AvResourceOperations[F]>, string>;
 /** A standard operation's `family` and `variant`. */
-export type OperationIdentity = {
-    [F in OperationFamily]: {
-        [V in OperationVariant<F>]: {
+export type AvOperationIdentity = {
+    [F in AvOperationFamily]: {
+        [V in AvOperationVariant<F>]: {
             readonly family: F;
             readonly variant: V;
         };
-    }[OperationVariant<F>];
-}[OperationFamily];
-/** Parses a family and variant into an {@link OperationIdentity}, or `undefined` when they name no standard operation. */
-export declare function parseOperationIdentity(family: string, variant: string): OperationIdentity | undefined;
+    }[AvOperationVariant<F>];
+}[AvOperationFamily];
+/** Parses a family and variant into an {@link AvOperationIdentity}, or `undefined` when they name no standard operation. */
+export declare function parseOperationIdentity(family: string, variant: string): AvOperationIdentity | undefined;
 /** Whether `family` names one of the standard operation families. */
 export declare function isOperationFamily(family: string): boolean;

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

@@ -1,21 +1,23 @@
-import type { Contract } from "../contracts/contract.js";
-import type { RelationField, ScalarField } from "../contracts/field.js";
-import type { ApplicationScalarForms, ScalarForms, ScalarValueType } from "../contracts/scalar-value-type.js";
-import type { FieldKey, OperationArgumentsFor, ResourceKey } from "./operation-arguments.js";
-import type { OperationIdentity } from "./operation-identity.js";
-type FieldOf<C extends Contract, K extends ResourceKey<C>, F extends FieldKey<C, K>> = C["resources"][K]["fields"][F];
+import type { AvContract } from "../contracts/contract.js";
+import type { AvRelationField, AvScalarField } from "../contracts/field.js";
+import type { AvApplicationScalarForms, AvScalarValueType, ScalarForms } from "../contracts/scalar-value-type.js";
+import type { AvFieldKey, AvOperationArgumentsFor, AvResourceKey } from "./operation-arguments.js";
+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 Contract, K extends ResourceKey<C>> = {
-    [F in FieldKey<C, K>]: FieldOf<C, K, F> extends {
+type DefaultKey<C extends AvContract, K extends AvResourceKey<C>> = {
+    [F in AvFieldKey<C, K>]: FieldOf<C, K, F> extends {
         readonly kind: "scalar";
         readonly capabilities: {
             readonly select: true;
         };
+        readonly governed?: never;
     } ? F : never;
-}[FieldKey<C, K>];
+}[AvFieldKey<C, K>];
 /** The field one projection entry names: a bare key, or a relation entry's key. */
 type EntryKey<Entry> = Entry extends string ? Entry : Entry extends object ? Extract<keyof Entry, string> : never;
 /**
@@ -31,26 +33,26 @@ type EntryArguments<Entry, F extends string> = Entry extends object ? Entry exte
  * `Entries` carries the relation entries' own arguments down; the scalar branch
  * ignores them.
  */
-type ProjectedFields<C extends Contract, K extends ResourceKey<C>, Keys extends FieldKey<C, K>, Entries, Forms extends ScalarForms> = {
-    readonly [F in Keys]: FieldOf<C, K, F> extends ScalarField<C> ? ScalarValueType<C, FieldOf<C, K, F>, Forms> : FieldOf<C, K, F> extends RelationField<C> ? RelationResult<C, Extract<FieldOf<C, K, F>["target"], ResourceKey<C>>, FieldOf<C, K, F>, EntryArguments<Entries, F>, Forms> : never;
-};
+type ProjectedFields<C extends AvContract, K extends AvResourceKey<C>, Keys extends AvFieldKey<C, K>, Entries, Forms extends ScalarForms> = {
+    readonly [F in Keys]: FieldOf<C, K, F> extends AvScalarField<C> ? AvScalarValueType<C, FieldOf<C, K, F>, Forms> : FieldOf<C, K, F> extends AvRelationField<C> ? RelationResult<C, Extract<FieldOf<C, K, F>["target"], AvResourceKey<C>>, FieldOf<C, K, F>, EntryArguments<Entries, F>, Forms> : never;
+} extends infer Fields ? Fields : never;
 /**
  * One projection level: `select` returns exactly its entries, `include` the
  * default fields plus the named relations, and no projection the default fields.
  */
-type ProjectedRecord<C extends Contract, K extends ResourceKey<C>, Arguments, Forms extends ScalarForms> = [Arguments] extends [never] ? ProjectedFields<C, K, DefaultKey<C, K>, never, Forms> : [Arguments] extends [{
+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>, FieldKey<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>, FieldKey<C, K>>, Entry, Forms> : ProjectedFields<C, K, DefaultKey<C, K>, never, Forms>;
+}] ? ProjectedFields<C, K, DefaultKey<C, K> | Extract<EntryKey<Entry>, AvFieldKey<C, K>>, Entry, Forms> : ProjectedFields<C, K, DefaultKey<C, K>, never, Forms>;
 /**
  * A to-many entry whose `select` asks for `$count`: the value is an object with
  * the rows and the count, not the row array.
  */
-type CountEnvelope<C extends Contract, Target extends ResourceKey<C>, Entry, Forms extends ScalarForms> = [Exclude<Entry, "$count">] extends [never] ? {
+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>, FieldKey<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. */
@@ -61,16 +63,16 @@ type SelectEntry<Arguments> = Arguments extends {
  * The value of one relation entry. A to-many entry is the rows-and-count object
  * when its own `select` asks for `$count`; otherwise the row array.
  */
-type RelationResult<C extends Contract, Target extends ResourceKey<C>, Relation extends RelationField<C>, Arguments, Forms extends ScalarForms> = Relation["cardinality"] extends "many" ? [Extract<SelectEntry<Arguments>, "$count">] extends [never] ? readonly ProjectedRecord<C, Target, Arguments, Forms>[] : CountEnvelope<C, Target, SelectEntry<Arguments>, Forms> : ProjectedRecord<C, Target, Arguments, Forms> | (true extends Relation["nullable"] ? null : never);
+type RelationResult<C extends AvContract, Target extends AvResourceKey<C>, Relation extends AvRelationField<C>, Arguments, Forms extends ScalarForms> = Relation["cardinality"] extends "many" ? [Extract<SelectEntry<Arguments>, "$count">] extends [never] ? readonly ProjectedRecord<C, Target, Arguments, Forms>[] : CountEnvelope<C, Target, SelectEntry<Arguments>, Forms> : ProjectedRecord<C, Target, Arguments, Forms> | (true extends Relation["nullable"] ? null : never);
 /**
- * The value a standard operation returns in `OperationResponse.data` on success,
+ * The value a standard operation returns in `AvOperationResponse.data` on success,
  * derived from the Contract, the Resource, the operation identity and the projection
  * argument.
  */
-export type OperationResultFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Args extends OperationArgumentsFor<C, K, I>, Forms extends ScalarForms = ApplicationScalarForms> = AdmittedOperationResult<C, K, I, Args, Forms>;
+export type AvOperationResultFor<C extends AvContract, K extends AvResourceKey<C>, I extends AvOperationIdentity, Args extends AvOperationArgumentsFor<C, K, I>, Forms extends ScalarForms = AvApplicationScalarForms> = AdmittedOperationResult<C, K, I, Args, Forms>;
 /**
- * {@link OperationResultFor}, for a projection already checked against the
+ * {@link AvOperationResultFor}, for a projection already checked against the
  * operation's argument type.
  */
-export type AdmittedOperationResult<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Args, Forms extends ScalarForms = ApplicationScalarForms> = I["variant"] extends "count" ? number : I["variant"] extends "many" ? readonly ProjectedRecord<C, K, Args, Forms>[] : ProjectedRecord<C, K, Args, Forms>;
+export type AdmittedOperationResult<C extends AvContract, K extends AvResourceKey<C>, I extends AvOperationIdentity, Args, Forms extends ScalarForms = AvApplicationScalarForms> = I["variant"] extends "count" ? number : I["variant"] extends "many" ? readonly ProjectedRecord<C, K, Args, Forms>[] : ProjectedRecord<C, K, Args, Forms>;
 export {};

package/dist/operations/operation-validator-core.d.ts

@@ -1,6 +1,6 @@
-import type { Contract } from "../contracts/contract.js";
-import { type OperationIdentity } from "./operation-identity.js";
-import type { ValidationIssue } from "./validation-code.js";
+import type { AvContract } from "../contracts/contract.js";
+import { type AvOperationIdentity } from "./operation-identity.js";
+import type { AvValidationIssue } from "./validation-code.js";
 /** An operation's arguments as an object, before validation. */
 export type SemanticOperationArguments = Readonly<Record<string, unknown>>;
 type OperationValidationSuccess = {
@@ -9,7 +9,7 @@ type OperationValidationSuccess = {
 };
 type OperationValidationFailure = {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
 /** The answer of {@link validateOperationArguments}: success, or the issues found. */
 export type OperationValidationResult = OperationValidationSuccess | OperationValidationFailure;
@@ -21,8 +21,8 @@ export type OperationValidationOptions = {
  * Contract does not have (`V1005` at `["resource"]`, rolling up to `A2001`). The one
  * spelling — the protocol's absence answers build theirs with it.
  */
-export declare function resourceUnavailableIssue(resource: string): ValidationIssue;
-export declare function validateOperationArguments(contract: Contract, request: OperationIdentity & {
+export declare function resourceUnavailableIssue(resource: string): AvValidationIssue;
+export declare function validateOperationArguments(contract: AvContract, request: AvOperationIdentity & {
     readonly resource: string;
     readonly arguments: unknown;
 }, options?: OperationValidationOptions): OperationValidationResult;