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

package/dist/config/define-resource.d.ts

@@ -0,0 +1,57 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvConfigAny } from "./any-framework-config.js";
+import type { ExactOverlayResource, ExactRootResource } from "./exact-framework-config.js";
+import type { AvConfigResourceKey } from "./framework-field-definition.js";
+import type { AvConfigResource } from "./framework-resources-config.js";
+import type { ErasedOverlayBlocks, ErasedResourceBlock } from "./stage-type.eraser.js";
+/** A configuration whose root `resources` is `{ [R]: Block }`. */
+type ResourceBlockConfig<R extends string, Block> = {
+    readonly resources: {
+        readonly [K in R]: Block;
+    };
+};
+/** The layers above the root a Resource may carry blocks for. */
+type OverlayLayer = "application" | "client" | "agent";
+/** A Resource's overlay blocks, as authored: either, both or neither. */
+type ResourceOverlays = {
+    readonly [L in OverlayLayer]?: unknown;
+};
+/** The overlay blocks `Overlays`, each checked against the root `Block`. */
+type CheckedOverlays<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, Block, Overlays> = {
+    readonly [L in keyof Overlays]: L extends OverlayLayer ? NoInfer<AvConfigResource<M, ResourceBlockConfig<R, Block>, R, "overlay"> & ExactOverlayResource<M, ResourceBlockConfig<R, Block>, R, Overlays[L]>> : never;
+};
+/**
+ * What {@link defineResource} returns: `root`, and `application`, `client` and
+ * `agent` exactly when they were given, each `{ [R]: block }` to spread into that
+ * layer's `resources`. Each block is as authored, with every stage list typed by
+ * its public stage type (`readonly AvGuard[]`, `readonly AvPipe[]`, …).
+ */
+export type AvDefinedResource<R extends string, Block, Overlays> = {
+    readonly [L in "root" | Extract<keyof Overlays, OverlayLayer>]: {
+        readonly [K in R]: L extends keyof Overlays ? Overlays[L] : Block;
+    };
+};
+/**
+ * Defines one Resource's configuration on its own: its root block (pipelines,
+ * operations, transactions and fields, typed as `resources.<R>` is typed in
+ * place) and, optionally, its `application`, `client` and `agent` blocks (typed
+ * as `application.resources.<R>`, `client.resources.<R>` and
+ * `agent.resources.<R>` are: stages only, no `definition`, and every field the
+ * model or the root block has). Returns
+ * `{ root, application?, client?, agent? }`, each `{ [R]: block }` to spread into its
+ * layer's `resources`; a layer without a block is left out.
+ *
+ * @example
+ * ```ts
+ * export const post = defineResource<Model>()(
+ *   "Post",
+ *   { fields: { title: { pipelines: { pipes: [trim] } } } },
+ *   { client: { pipelines: { guards: [signedIn] } } },
+ * );
+ * // aventara.config.ts
+ * resources: { ...post.root, ...payment.root },
+ * client: { resources: { ...post.client } },
+ * ```
+ */
+export declare function defineResource<M extends AvAdapterModel>(): <const R extends AvConfigResourceKey<M>, const Block = AvConfigResource<M, AvConfigAny, R, "root">, const Overlays extends ResourceOverlays = Record<never, never>>(resource: R, block: Block & NoInfer<AvConfigResource<M, ResourceBlockConfig<R, Block>, R, "root"> & ExactRootResource<M, R, Block>>, overlays?: Overlays & CheckedOverlays<M, R, Block, Overlays>) => AvDefinedResource<R, ErasedResourceBlock<Block>, ErasedOverlayBlocks<Overlays>>;
+export {};

package/dist/config/define-resource.js

@@ -0,0 +1,14 @@
+export function defineResource() {
+    return (resource, block, overlays) => {
+        const defined = {
+            root: { [resource]: block },
+        };
+        for (const layer of ["application", "client", "agent"]) {
+            const overlay = overlays?.[layer];
+            if (overlay !== undefined) {
+                defined[layer] = { [resource]: overlay };
+            }
+        }
+        return defined;
+    };
+}

package/dist/config/effective-fields.d.ts

@@ -1,30 +1,26 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { AdapterFieldKey } from "../adapters/adapter-resource.js";
-import type { AnyFieldsBlock } from "./any-framework-config.js";
-import type { RequestOrigin } from "./config-layer.js";
-import type { FrameworkResourceKey } from "./framework-fields-config.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterFieldKey } from "../adapters/adapter-resource.js";
+import type { AvConfigResourceKey } from "./framework-field-definition.js";
 /**
- * The `fields` block a configuration layer owns, or `never` when it has none.
+ * The root `resources` block a configuration owns, or `never` when it has
+ * none.
  *
  * `Cfg` is an authored literal, not a validated shape, so the block is read
- * structurally. A layer without a `fields` property infers `unknown`, which
- * is not an {@link AnyFieldsBlock}, so it contributes nothing.
+ * structurally. A configuration without a `resources` property infers
+ * `unknown`, which is no object, so it contributes nothing.
  */
-type FieldsBlockOf<Layer> = Layer extends {
-    readonly fields?: infer Block;
-} ? Block extends AnyFieldsBlock ? Block : never : never;
-/** The field names a single `fields` block declares for `R`. */
-type FieldsBlockKey<Block, R extends string> = [Block] extends [never] ? never : R extends keyof Block ? Extract<keyof NonNullable<Block[R]>, string> : never;
-/** The field names the configuration's root `fields` block adds to Resource `R`. */
-export type ConfigFieldKey<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = FieldsBlockKey<FieldsBlockOf<Cfg>, R>;
-/** The single answer to "what are `R`'s field names under this configuration". */
-export type EffectiveFieldKey<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = AdapterFieldKey<M, R> | ConfigFieldKey<M, Cfg, R>;
-/** The overlay `Cfg` carries for `Origin`, or `never` when it declares none. */
-type OriginOverlayOf<Cfg, Origin extends RequestOrigin> = Origin extends keyof Cfg ? NonNullable<Cfg[Origin]> : never;
+type ResourcesBlockOf<Cfg> = Cfg extends {
+    readonly resources?: infer Block;
+} ? Block extends object ? Block : never : never;
+/** The field names the root `resources.<R>.fields` block names for `R`. */
+type ResourcesBlockFieldKey<Block, R extends string> = [Block] extends [never] ? never : R extends keyof Block ? NonNullable<Block[R]> extends {
+    readonly fields?: infer Fields;
+} ? Extract<keyof NonNullable<Fields>, string> : never : never;
 /**
- * `R`'s field names as seen from one request origin: the root layer plus
- * whatever the `application` or `client` overlay adds. A name added under
- * `client` is not visible under `application`, and the other way round.
+ * The field names the configuration's root `resources.<R>.fields` block
+ * names: its configured fields, and any discovered field it configures.
  */
-export type EffectiveFieldKeyAt<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>, Origin extends RequestOrigin> = EffectiveFieldKey<M, Cfg, R> | FieldsBlockKey<FieldsBlockOf<OriginOverlayOf<Cfg, Origin>>, R>;
+export type AvConfigFieldKey<M extends AvAdapterModel, Cfg, R extends AvConfigResourceKey<M>> = ResourcesBlockFieldKey<ResourcesBlockOf<Cfg>, R>;
+/** The single answer to "what are `R`'s field names under this configuration". */
+export type AvEffectiveFieldKey<M extends AvAdapterModel, Cfg, R extends AvConfigResourceKey<M>> = AvAdapterFieldKey<M, R> | AvConfigFieldKey<M, Cfg, R>;
 export {};

package/dist/config/entrypoint.normalizer.d.ts

@@ -1,5 +1,5 @@
 /**
- * The framework entrypoint's mount path, in its one canonical form: `""` at the root,
+ * A mount path (the server's `api` or `mcp` path, a client entrypoint's path), in its one canonical form: `""` at the root,
  * otherwise `/seg(/seg)*` — one leading slash, no trailing slash, no empty segment.
  * Root is the empty string, not `"/"`, so a route joins onto it by concatenation with
  * no special case.

package/dist/config/exact-framework-config.d.ts

@@ -0,0 +1,280 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterFieldKey } from "../adapters/adapter-resource.js";
+import type { AvScalarFieldCapabilities } from "../contracts/field.js";
+import type { OverlayViewResources, RootViewResources } from "../framework/contract-view.js";
+import type { AvEffectiveFieldKey } from "./effective-fields.js";
+import type { AvConfigResourceKey } from "./framework-field-definition.js";
+import type { AvConfigLayerKind } from "./framework-resources-config.js";
+/** A key whose value this walk does not open. */
+type Leaf = true;
+type PipelinesSchema = {
+    readonly guards: Leaf;
+    readonly pipes: Leaf;
+    readonly hooks: {
+        readonly before: Leaf;
+        readonly after: Leaf;
+    };
+    readonly interceptors: Leaf;
+    readonly filters: Leaf;
+};
+type LimitsSchema = {
+    readonly maxRequestBytes: Leaf;
+    readonly maxNestingDepth: Leaf;
+    readonly maxListLimit: Leaf;
+    readonly maxTransactionOperations: Leaf;
+    readonly maxBooleanNodes: Leaf;
+    readonly maxJsonDepth: Leaf;
+};
+type LevelSchema = {
+    readonly pipelines: PipelinesSchema;
+    readonly forceTransaction: Leaf;
+};
+type Operations<M extends AvAdapterModel, R extends AvConfigResourceKey<M>> = M["resources"][R]["operations"];
+type OperationsSchema<M extends AvAdapterModel, R extends AvConfigResourceKey<M>> = {
+    readonly [F in keyof Operations<M, R>]: LevelSchema & {
+        readonly [V in keyof NonNullable<Operations<M, R>[F]>]: LevelSchema;
+    };
+};
+type CapabilitySchema<Capabilities> = {
+    readonly [K in keyof Capabilities]-?: Leaf;
+};
+type DefinitionSchema = {
+    readonly type: Leaf;
+    readonly nullable: Leaf;
+    readonly list: Leaf;
+    readonly lifecycle: Leaf;
+    readonly format: Leaf;
+    readonly capabilities: CapabilitySchema<AvScalarFieldCapabilities>;
+    readonly json: Leaf;
+};
+type ScalarPipelinesSchema = {
+    readonly validators: Leaf;
+    readonly pipes: Leaf;
+    readonly compute: {
+        readonly create: Leaf;
+        readonly read: {
+            readonly dependsOn: Leaf;
+            readonly compute: Leaf;
+        };
+        readonly update: Leaf;
+    };
+    readonly guards: Leaf;
+};
+type RelationPipelinesSchema = {
+    readonly guards: Leaf;
+};
+type ScalarFieldSchema = {
+    readonly pipelines: ScalarPipelinesSchema;
+};
+type RelationFieldSchema = {
+    readonly pipelines: RelationPipelinesSchema;
+};
+type RootScalarFieldSchema = ScalarFieldSchema & {
+    readonly definition: DefinitionSchema;
+};
+type RootRelationFieldSchema = RelationFieldSchema & {
+    readonly definition: DefinitionSchema;
+};
+/** A field entry's keys: a relation takes write guards only; only the root defines. */
+type FieldSchema<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, F, Kind extends AvConfigLayerKind> = F extends AvAdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
+    readonly kind: "relation";
+} ? Kind extends "root" ? RootRelationFieldSchema : RelationFieldSchema : Kind extends "root" ? RootScalarFieldSchema : ScalarFieldSchema : Kind extends "root" ? RootScalarFieldSchema : ScalarFieldSchema;
+declare const otherKeys: unique symbol;
+type ResourceSchema<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, Fields> = {
+    readonly pipelines: PipelinesSchema;
+    readonly operations: OperationsSchema<M, R>;
+    readonly transactions: {
+        readonly pipelines: PipelinesSchema;
+    };
+    readonly fields: Fields;
+};
+/** A layer's fields of Resource `R`, named by `FieldName`. */
+type FieldsSchema<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, Kind extends AvConfigLayerKind, FieldName> = {
+    readonly [F in FieldName & string]: FieldSchema<M, R, F, Kind>;
+};
+declare const listOf: unique symbol;
+/** The names a list at this place may hold. */
+type ListOf<Names> = {
+    readonly [listOf]: Names;
+};
+/** The tokens one capability member lists, its position qualifier aside. */
+type TokenOf<Member> = Member extends {
+    readonly scopes: unknown;
+} ? {
+    [K in keyof Member]: K extends "scopes" ? never : Member[K] extends readonly (infer Token)[] ? Token : never;
+}[keyof Member] : Member extends readonly (infer Token)[] ? Token : never;
+/** A field's exemption against its capabilities: their names, and each one's tokens. */
+type CapabilityExemptionSchema<Caps> = ListOf<Exclude<keyof Caps, "nestedWriteFilter">> & {
+    readonly [K in Exclude<keyof Caps, "nestedWriteFilter">]-?: ListOf<TokenOf<NonNullable<Caps[K]>>>;
+};
+type FieldExemptionSchema<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, F> = F extends AvAdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
+    readonly kind: "relation";
+    readonly capabilities: infer Caps;
+} ? CapabilityExemptionSchema<Caps> : M["resources"][R]["fields"][F] extends {
+    readonly capabilities: infer Caps;
+} ? CapabilityExemptionSchema<Caps & {
+    readonly select?: true;
+}> : ListOf<keyof AvScalarFieldCapabilities> & CapabilitySchema<AvScalarFieldCapabilities> : ListOf<keyof AvScalarFieldCapabilities> & CapabilitySchema<AvScalarFieldCapabilities>;
+/** A Resource's operations exemption against the operations it offers. */
+type OperationsExemptionSchema<Ops> = ListOf<keyof Ops> & {
+    readonly [F in keyof Ops]-?: ListOf<keyof NonNullable<Ops[F]>> & {
+        readonly [V in keyof NonNullable<Ops[F]>]: Leaf;
+    };
+};
+type ExemptionsSchema<M extends AvAdapterModel, Cfg> = {
+    readonly resources: {
+        readonly [R in AvConfigResourceKey<M>]: {
+            readonly operations: OperationsExemptionSchema<Operations<M, R>>;
+            readonly fields: {
+                readonly [F in AvEffectiveFieldKey<M, Cfg, R>]: FieldExemptionSchema<M, R, F>;
+            };
+        };
+    };
+};
+/** A Pick overlay's exemptions, against the root's view. */
+type PickExemptionsSchema<Resources> = {
+    readonly resources: {
+        readonly [R in keyof Resources]: {
+            readonly operations: OperationsExemptionSchema<Resources[R] extends {
+                readonly operations: infer Ops;
+            } ? Ops : never>;
+            readonly fields: {
+                readonly [F in keyof (Resources[R] extends {
+                    readonly fields: infer Fields;
+                } ? Fields : never)]: CapabilityExemptionSchema<(Resources[R] extends {
+                    readonly fields: infer Fields;
+                } ? Fields : never)[F] extends {
+                    readonly capabilities: infer Caps;
+                } ? Caps : never>;
+            };
+        };
+    };
+};
+/** A layer's own configuration: `application`, `client` or `agent`. */
+type OverlayOf<Cfg, Layer extends "application" | "client" | "agent"> = (Cfg & {
+    readonly [L in Layer]?: unknown;
+})[Layer];
+/** An overlay's exemptions schema, by the overlay's own `exposed`. */
+type OverlayExemptionsSchema<M extends AvAdapterModel, Cfg, Overlay> = Overlay extends {
+    readonly exposed: false;
+} ? PickExemptionsSchema<RootViewResources<M, Cfg>> : ExemptionsSchema<M, Cfg>;
+type LayerKeysSchema = {
+    readonly exposed: Leaf;
+    readonly transactionsStyle: Leaf;
+    readonly limits: LimitsSchema;
+    readonly pipelines: PipelinesSchema;
+};
+type RootResourcesSchema<M extends AvAdapterModel> = {
+    readonly [R in AvConfigResourceKey<M>]: ResourceSchema<M, R, FieldsSchema<M, R, "root", AvAdapterFieldKey<M, R>> & {
+        readonly [otherKeys]: RootScalarFieldSchema;
+    }>;
+};
+/**
+ * One root `resources.<R>` block, checked key by key as
+ * {@link AvConfigExact} checks it in place.
+ */
+export type ExactRootResource<M extends AvAdapterModel, R extends AvConfigResourceKey<M>, Block> = Exact<RootResourcesSchema<M>[R], Block>;
+/**
+ * One overlay `resources.<R>` block, checked key by key as
+ * {@link AvConfigExact} checks it in place, its field names read from `Cfg`.
+ */
+export type ExactOverlayResource<M extends AvAdapterModel, Cfg, R extends AvConfigResourceKey<M>, Block> = Exact<ResourceSchema<M, R, FieldsSchema<M, R, "overlay", AvEffectiveFieldKey<M, Cfg, R>>>, Block>;
+type OverlaySchema<M extends AvAdapterModel, Cfg, Layer extends "application" | "client"> = LayerKeysSchema & {
+    readonly resources: {
+        readonly [R in AvConfigResourceKey<M>]: ResourceSchema<M, R, FieldsSchema<M, R, "overlay", AvEffectiveFieldKey<M, Cfg, R>>>;
+    };
+    readonly exemptions: OverlayExemptionsSchema<M, Cfg, OverlayOf<Cfg, Layer>>;
+};
+type McpSchema = {
+    readonly path: Leaf;
+    readonly authorization: {
+        readonly servers: Leaf;
+        readonly verify: Leaf;
+    };
+};
+/** The layer the agent extends, as authored: `"client"` when it states none. */
+type AgentParentOf<Cfg> = OverlayOf<Cfg, "agent"> extends {
+    readonly extends: infer Parent;
+} ? Parent : "client";
+/** A Pick agent's exemptions, against the view of the layer it extends. */
+type AgentPickExemptionsSchema<M extends AvAdapterModel, Cfg, Parent> = Parent extends "application" | "client" ? [Parent] extends ["application"] | ["client"] ? PickExemptionsSchema<OverlayViewResources<M, Cfg, Parent>> : PickExemptionsSchema<RootViewResources<M, Cfg>> : PickExemptionsSchema<RootViewResources<M, Cfg>>;
+type AgentSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
+    readonly extends: Leaf;
+    readonly resources: {
+        readonly [R in AvConfigResourceKey<M>]: ResourceSchema<M, R, FieldsSchema<M, R, "overlay", AvEffectiveFieldKey<M, Cfg, R>>>;
+    };
+    readonly exemptions: OverlayOf<Cfg, "agent"> extends {
+        readonly exposed: false;
+    } ? AgentPickExemptionsSchema<M, Cfg, AgentParentOf<Cfg>> : ExemptionsSchema<M, Cfg>;
+};
+type RootSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
+    readonly api: Leaf;
+    readonly mcp: McpSchema;
+    readonly adapter: Leaf;
+    readonly diagnostics: Leaf;
+    readonly misuse: Leaf;
+    readonly resources: RootResourcesSchema<M>;
+    readonly exemptions: ExemptionsSchema<M, Cfg>;
+    readonly application: OverlaySchema<M, Cfg, "application">;
+    readonly client: OverlaySchema<M, Cfg, "client">;
+    readonly agent: AgentSchema<M, Cfg>;
+};
+/** `V` with every key schema `S` lacks mapped to `never`; every leaf `unknown`. */
+type Exact<S, V> = [S] extends [Leaf] ? unknown : V extends readonly unknown[] ? S extends ListOf<infer Names> ? readonly Names[] : unknown : V extends (...args: any) => any ? unknown : V extends object ? string extends keyof V ? unknown : {
+    readonly [K in keyof V]: K extends keyof S ? Exact<S[K], V[K]> : typeof otherKeys extends keyof S ? Exact<S[typeof otherKeys], V[K]> : never;
+} : unknown;
+/**
+ * The authored configuration `Cfg`, checked key by key: a key no level of the
+ * configuration admits is `never`, a type error at the key. Such a key is a moved
+ * rc.0 key, a `definition` in an overlay, a stage a relation field does not take,
+ * or a name the model and the root do not have.
+ */
+export type AvConfigExact<M extends AvAdapterModel, Cfg> = Exact<RootSchema<M, Cfg>, Cfg> & ExposedWithExemptions<Cfg, "application"> & ExposedWithExemptions<Cfg, "client"> & ExposedWithExemptions<Cfg, "agent"> & ForceNeedsTransactions<M, Cfg>;
+/** A layer's own literal `transactionsStyle`, `undefined` when it states none. */
+type StyleOf<Layer> = Layer extends {
+    readonly transactionsStyle: infer Style;
+} ? Style : undefined;
+/** Whether one origin's effective `transactionsStyle` is certainly `"none"`. */
+type CertainlyNone<M extends AvAdapterModel, Cfg, Layer extends "application" | "client"> = [M["transactions"]] extends ["none"] ? true : [StyleOf<OverlayOf<Cfg, Layer>>] extends [undefined] ? [StyleOf<Cfg>] extends ["none"] ? true : false : [StyleOf<OverlayOf<Cfg, Layer>>] extends ["none"] ? true : false;
+/** A `resources` tree in which no family or variant may set `forceTransaction: true`. */
+type UnforcedResources<M extends AvAdapterModel> = {
+    readonly resources?: {
+        readonly [R in AvConfigResourceKey<M>]?: {
+            readonly operations?: {
+                readonly [F in keyof Operations<M, R>]?: {
+                    readonly forceTransaction?: false;
+                } & {
+                    readonly [V in keyof NonNullable<Operations<M, R>[F]>]?: {
+                        readonly forceTransaction?: false;
+                    };
+                };
+            };
+        };
+    };
+};
+/** Refuses `forceTransaction: true` where the effective style is certainly `"none"`. */
+type ForceNeedsTransactions<M extends AvAdapterModel, Cfg> = string extends keyof Cfg ? unknown : ForcedLayers<M, Cfg>;
+/** Whether the agent's effective `transactionsStyle` is certainly `"none"`. */
+type AgentCertainlyNone<M extends AvAdapterModel, Cfg> = [
+    M["transactions"]
+] extends ["none"] ? true : [StyleOf<OverlayOf<Cfg, "agent">>] extends [undefined] ? [AgentParentOf<Cfg>] extends ["application"] ? CertainlyNone<M, Cfg, "application"> : [AgentParentOf<Cfg>] extends ["client"] ? CertainlyNone<M, Cfg, "client"> : [AgentParentOf<Cfg>] extends ["root"] ? [StyleOf<Cfg>] extends ["none"] ? true : false : false : [StyleOf<OverlayOf<Cfg, "agent">>] extends ["none"] ? true : false;
+type ForcedLayers<M extends AvAdapterModel, Cfg> = (AgentCertainlyNone<M, Cfg> extends true ? {
+    readonly agent?: UnforcedResources<M>;
+} : unknown) & (CertainlyNone<M, Cfg, "application"> extends true ? CertainlyNone<M, Cfg, "client"> extends true ? UnforcedResources<M> : unknown : unknown) & (CertainlyNone<M, Cfg, "application"> extends true ? {
+    readonly application?: UnforcedResources<M>;
+} : unknown) & (CertainlyNone<M, Cfg, "client"> extends true ? {
+    readonly client?: UnforcedResources<M>;
+} : unknown);
+/** Requires an overlay's `exposed` when the overlay states `exemptions`. */
+type ExposedWithExemptions<Cfg, Layer extends "application" | "client" | "agent"> = Cfg extends {
+    readonly [L in Layer]: infer Overlay;
+} ? Overlay extends {
+    readonly exemptions: unknown;
+} ? Overlay extends {
+    readonly exposed: unknown;
+} ? unknown : {
+    readonly [L in Layer]: {
+        readonly exposed: boolean;
+    };
+} : unknown : unknown;
+export {};

package/dist/config/field-compute.resolver.d.ts

@@ -0,0 +1,19 @@
+import type { AvComputeCreate, AvComputeRead, AvComputeUpdate } from "../runtime/field-compute.js";
+/** One field's compute stages for one origin, each phase already chained. */
+export type ResolvedFieldCompute = {
+    readonly create?: AvComputeCreate;
+    readonly update?: AvComputeUpdate;
+    readonly read?: AvComputeRead;
+};
+/** Compute stages for one origin, by Resource and field name. */
+export type ResolvedComputeConfig = Readonly<Record<string, Readonly<Record<string, ResolvedFieldCompute>>>>;
+/**
+ * One layer's compute stages, read off its `resources` tree: per Resource, per
+ * field, its `pipelines.compute`. Only phases a layer states are present.
+ */
+export declare function computeOfLayer(resources: unknown): ResolvedComputeConfig;
+/**
+ * The compute stages that run for one origin: the root's, then the overlay's,
+ * chained phase by phase. Nothing is disabled from below.
+ */
+export declare function chainCompute(root: ResolvedComputeConfig, overlay: ResolvedComputeConfig): ResolvedComputeConfig;

package/dist/config/field-compute.resolver.js

@@ -0,0 +1,115 @@
+function chainWrite(root, overlay) {
+    if (root === undefined || overlay === undefined) {
+        return root ?? overlay;
+    }
+    return async (context) => {
+        const first = await root(context);
+        if (first === undefined) {
+            return overlay(context);
+        }
+        const second = await overlay({
+            ...context,
+            value: first,
+            data: { ...context.data, [context.field]: first },
+        });
+        return second === undefined ? first : second;
+    };
+}
+function readCompute(stage) {
+    return typeof stage === "function" ? stage : stage.compute;
+}
+function readDependencies(stage) {
+    return typeof stage === "function" ? [] : (stage.dependsOn ?? []);
+}
+function chainRead(root, overlay) {
+    if (root === undefined || overlay === undefined) {
+        return root ?? overlay;
+    }
+    const rootCompute = readCompute(root);
+    const overlayCompute = readCompute(overlay);
+    const compute = async (context) => {
+        const first = await rootCompute(context);
+        if (first === undefined) {
+            return overlayCompute(context);
+        }
+        const second = await overlayCompute({
+            ...context,
+            value: first,
+            record: { ...context.record, [context.field]: first },
+        });
+        return second === undefined ? first : second;
+    };
+    const dependsOn = [
+        ...new Set([...readDependencies(root), ...readDependencies(overlay)]),
+    ];
+    return typeof root === "function" && typeof overlay === "function"
+        ? compute
+        : { dependsOn, compute };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function computeOfLayer(resources) {
+    const result = {};
+    if (!isRecord(resources)) {
+        return result;
+    }
+    for (const [resourceName, resource] of Object.entries(resources)) {
+        if (!isRecord(resource) || !isRecord(resource.fields)) {
+            continue;
+        }
+        for (const [fieldName, field] of Object.entries(resource.fields)) {
+            if (!isRecord(field) || !isRecord(field.pipelines)) {
+                continue;
+            }
+            const compute = field.pipelines.compute;
+            if (!isRecord(compute)) {
+                continue;
+            }
+            const phases = {};
+            if (compute.create !== undefined) {
+                phases.create = compute.create;
+            }
+            if (compute.update !== undefined) {
+                phases.update = compute.update;
+            }
+            if (compute.read !== undefined) {
+                phases.read = compute.read;
+            }
+            if (Object.keys(phases).length === 0) {
+                continue;
+            }
+            result[resourceName] ??= {};
+            result[resourceName][fieldName] = phases;
+        }
+    }
+    return result;
+}
+export function chainCompute(root, overlay) {
+    const result = {};
+    for (const resourceName of new Set([
+        ...Object.keys(root),
+        ...Object.keys(overlay),
+    ])) {
+        const rootFields = root[resourceName] ?? {};
+        const overlayFields = overlay[resourceName] ?? {};
+        const fields = {};
+        for (const fieldName of new Set([
+            ...Object.keys(rootFields),
+            ...Object.keys(overlayFields),
+        ])) {
+            const rootField = rootFields[fieldName] ?? {};
+            const overlayField = overlayFields[fieldName] ?? {};
+            const create = chainWrite(rootField.create, overlayField.create);
+            const update = chainWrite(rootField.update, overlayField.update);
+            const read = chainRead(rootField.read, overlayField.read);
+            fields[fieldName] = {
+                ...(create !== undefined ? { create } : {}),
+                ...(update !== undefined ? { update } : {}),
+                ...(read !== undefined ? { read } : {}),
+            };
+        }
+        result[resourceName] = fields;
+    }
+    return result;
+}

package/dist/config/field-pipeline-config.d.ts

@@ -0,0 +1,47 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvZCheck } from "../avz/avz-check.registry.js";
+import type { AvComputeCreate, AvComputeRead, AvComputeUpdate } from "../runtime/field-compute.js";
+import type { AvFieldGuard, AvFieldPipe } from "../runtime/pipeline.js";
+import type { AvConfigAny } from "./any-framework-config.js";
+import type { AvConfigResourceKey } from "./framework-field-definition.js";
+export type { AvZCheck } from "../avz/avz-check.registry.js";
+/**
+ * A scalar field's computed values, one stage per phase: `create` and `update`
+ * run before the write, `read` on each returned record.
+ */
+export type AvFieldCompute<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = {
+    /** Computes the value on every create; an upsert's create branch included. */
+    readonly create?: AvComputeCreate<M>;
+    /** Computes the value on every read of a returned record. */
+    readonly read?: AvComputeRead<M, Cfg, R>;
+    /** Computes the value on every update; an upsert's update branch included. */
+    readonly update?: AvComputeUpdate<M>;
+};
+/**
+ * A scalar field's stages: validators, field pipes, compute and write guards.
+ * `Check` is the checks the field takes (any, when the field's type is not
+ * known here).
+ */
+export type AvScalarFieldPipeline<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>, Check extends AvZCheck = AvZCheck> = {
+    /**
+     * Declarative checks on the value, built with `AvZ` and carried in the Contract;
+     * root's, then the overlay's. On a list field `AvZ.minItems` and `AvZ.maxItems`
+     * check the list and every other check each entry.
+     */
+    readonly validators?: readonly Check[];
+    /**
+     * Pure transforms of the sent value: value in, value out, no context. They run
+     * after the operation's pipes and before the validators; in a transaction, on
+     * literal values before it opens and on a `$ref` value at its step.
+     */
+    readonly pipes?: readonly AvFieldPipe[];
+    /** The field's computed values. */
+    readonly compute?: AvFieldCompute<M, Cfg, R>;
+    /** Write-only admission: run when the caller sends the field. */
+    readonly guards?: readonly AvFieldGuard<NoInfer<M>, R>[];
+};
+/** A relation field's stages: write guards only. */
+export type AvRelationFieldPipeline<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>> = {
+    /** Write-only admission: run for every write through the relation. */
+    readonly guards?: readonly AvFieldGuard<NoInfer<M>, R>[];
+};

package/dist/config/forced-operation.validator.d.ts

@@ -0,0 +1,10 @@
+import type { AvContracts } from "../compiler/contract.compiler.js";
+import type { AvConfigDiagnostic } from "./config-diagnostic.js";
+type LayerRecord = Readonly<Record<string, unknown>>;
+/**
+ * The `forceTransaction` settings a forced call could not honour: one
+ * `CONFIG_INVALID_VALUE` per configuration path, naming every origin whose
+ * Contract offers the operation without transactions.
+ */
+export declare function validateForcedOperations(config: LayerRecord, contracts: AvContracts): readonly AvConfigDiagnostic[];
+export {};