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

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

@@ -2,8 +2,10 @@ import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvAdapterFieldKey } from "../adapters/adapter-resource.js";
 import type { AvZCheck } from "../avz/avz-check.registry.js";
 import type { AvOperationFamily } from "../operations/operation-identity.js";
-import type { AvStageArguments } from "../runtime/pipeline.js";
+import type { AvPreComputeStageArguments, AvStageArguments } from "../runtime/pipeline.js";
 import type { AvConfigAny } from "./any-framework-config.js";
+import type { AvPreComputeLift } from "./computed-fields.js";
+import type { AvConfigLayerName } from "./config-layer.js";
 import type { AvEffectiveFieldKey } from "./effective-fields.js";
 import type { AvRelationFieldPipeline, AvScalarFieldPipeline } from "./field-pipeline-config.js";
 import type { AvConfigAddedFieldDefinition, AvConfigFieldDefinition, AvConfigKnownFieldDefinition, AvConfigResourceKey } from "./framework-field-definition.js";
@@ -14,29 +16,29 @@ import type { AvPipeline, AvTransactionPipeline } from "./pipeline-config.js";
  */
 export type AvConfigLayerKind = "root" | "overlay";
 /** One operation variant's level: its stages and `forceTransaction`. */
-export type AvConfigVariant<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = NoInfer<AvStageArguments<M, R, F, V>>> = {
+export type AvConfigVariant<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = NoInfer<AvStageArguments<M, R, F, V>>, PreCompute = NoInfer<AvPreComputeStageArguments<M, R, F, V>>> = {
     /**
      * Stages that run for this one operation: at a variant, `ctx.$args` (and a
-     * pipe's arguments) are typed as the operation's arguments.
+     * pipe's arguments) are typed as the operation's arguments; in a guard, a
+     * pipe or a filter a create may lack the fields `compute.create` fills
+     * (write compute runs after them).
      */
-    readonly pipelines?: AvPipeline<NoInfer<M>, R, F, V, A>;
+    readonly pipelines?: AvPipeline<NoInfer<M>, R, F, V, A, PreCompute>;
     /** Runs a plain call of this operation as a one-step transaction. */
     readonly forceTransaction?: boolean;
 };
-/** The variants a family's stages are told: its own, and `"one"` for a nested target. */
-type FamilyStageVariant<F extends AvOperationFamily, V extends string> = F extends "create" | "update" | "delete" ? V | "one" : V;
 /**
  * One operation family's level: stages and `forceTransaction` for every variant
  * of it, and each variant's own level by name.
  */
 export type AvConfigFamily<M extends AvAdapterModel = AvAdapterModel, Variants = {
     readonly [V in "first" | "unique" | "many" | "count" | "one"]?: unknown;
-}, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily> = AvConfigVariant<M, R, F, FamilyStageVariant<F, Extract<keyof NonNullable<Variants>, string>>, unknown> & {
-    readonly [V in Extract<keyof NonNullable<Variants>, string>]?: AvConfigVariant<M, R, F, V> | undefined;
+}, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, Layer extends AvConfigLayerName = "root"> = AvConfigVariant<M, R, F, F extends "create" | "update" | "delete" ? Extract<keyof NonNullable<Variants>, string> | "one" : Extract<keyof NonNullable<Variants>, string>, unknown, unknown> & {
+    readonly [V in Extract<keyof NonNullable<Variants>, string>]?: AvConfigVariant<M, R, F, V, NoInfer<AvStageArguments<M, R, F, V>>, NoInfer<AvPreComputeStageArguments<M, R, F, V, AvPreComputeLift<M, Layer>>>> | undefined;
 };
 /** A Resource's families, as the adapter model offers them, each with its level. */
-export type AvConfigOperations<M extends AvAdapterModel = AvAdapterModel, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = {
-    readonly [F in Extract<keyof M["resources"][R]["operations"], AvOperationFamily>]?: AvConfigFamily<M, M["resources"][R]["operations"][F], R, F>;
+export type AvConfigOperations<M extends AvAdapterModel = AvAdapterModel, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>, Layer extends AvConfigLayerName = "root"> = {
+    readonly [F in Extract<keyof M["resources"][R]["operations"], AvOperationFamily>]?: AvConfigFamily<M, M["resources"][R]["operations"][F], R, F, Layer>;
 };
 /** A Resource's transaction level. */
 export type AvConfigResourceTransactions<M extends AvAdapterModel = AvAdapterModel> = {
@@ -99,18 +101,27 @@ export type AvConfigResourceFields<in out M extends AvAdapterModel = AvAdapterMo
     readonly [F in AvEffectiveFieldKey<M, Cfg, R>]?: Kind extends "root" ? RootFieldConfigFor<M, Cfg, R, F> : OverlayFieldConfigFor<M, Cfg, R, F>;
 };
 /** One Resource's tree: its stages, operations, transactions and fields. */
-export type AvConfigResource<in out M extends AvAdapterModel = AvAdapterModel, in out Cfg = AvConfigAny, in out R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>, Kind extends AvConfigLayerKind = "root"> = {
+export type AvConfigResource<in out M extends AvAdapterModel = AvAdapterModel, in out Cfg = AvConfigAny, in out R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>, Kind extends AvConfigLayerKind = "root", Layer extends AvConfigLayerName = LayerOfKind<Kind>> = {
     /** Stages that run for every operation of this Resource. */
     readonly pipelines?: AvPipeline<NoInfer<M>, R>;
     /** Per family, and per variant under its family. */
-    readonly operations?: AvConfigOperations<M, R>;
+    readonly operations?: AvConfigOperations<M, R, Layer>;
     /** Stages that run once per transaction with a top-level step on this Resource. */
     readonly transactions?: AvConfigResourceTransactions<M>;
     /** Per field: its definition (root only) and its stages. */
     readonly fields?: AvConfigResourceFields<M, Cfg, R, Kind>;
+    /**
+     * `true`: another service owns this Resource's table and migrates it. It is
+     * read and joined, never written: it has no write operation, no nested write
+     * reaches its rows, and the client and agent Contracts leave it out, with
+     * every relation to it. Root only.
+     */
+    readonly managedElsewhere?: Kind extends "root" ? boolean : never;
 };
 /** The `resources` tree of one layer, keyed by the adapter's Resource names. */
-export type AvConfigResources<in out M extends AvAdapterModel = AvAdapterModel, in out Cfg = AvConfigAny, in out Kind extends AvConfigLayerKind = "root"> = {
-    readonly [R in AvConfigResourceKey<M>]?: AvConfigResource<M, Cfg, R, Kind>;
+export type AvConfigResources<in out M extends AvAdapterModel = AvAdapterModel, in out Cfg = AvConfigAny, in out Kind extends AvConfigLayerKind = "root", in out Layer extends AvConfigLayerName = LayerOfKind<Kind>> = {
+    readonly [R in AvConfigResourceKey<M>]?: AvConfigResource<M, Cfg, R, Kind, Layer>;
 };
+/** The layers a tree of kind `Kind` may be written in, when it names none. */
+export type LayerOfKind<Kind extends AvConfigLayerKind> = Kind extends "root" ? "root" : Exclude<AvConfigLayerName, "root">;
 export {};

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

@@ -6,11 +6,11 @@ import type { AvConfigResourceKey } from "./framework-field-definition.js";
  * Pipeline registrations for one level of the configuration: a layer, a
  * Resource, a family or a variant. See {@link AvContext}.
  */
-export type AvPipeline<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown> = {
+export type AvPipeline<M extends AvAdapterModel = AvAdapterModel, R extends string = AvConfigResourceKey<M>, F extends AvOperationFamily = AvOperationFamily, V extends string = string, A = unknown, PreCompute = A> = {
     /** Run first; a guard returning `false` denies the operation with `A4001`. */
-    readonly guards?: readonly AvGuard<M, R, F, V, A>[];
+    readonly guards?: readonly AvGuard<M, R, F, V, PreCompute>[];
     /** Run in order on the arguments; a pipe may return replacement arguments. */
-    readonly pipes?: readonly AvPipe<M, R, F, V, A>[];
+    readonly pipes?: readonly AvPipe<M, R, F, V, PreCompute>[];
     /**
      * Run around the operation, inside every level's interceptors: `before`
      * hooks outer to inner, `after` hooks inner to outer.
@@ -22,7 +22,7 @@ export type AvPipeline<M extends AvAdapterModel = AvAdapterModel, R extends stri
     /** Wrap everything below this level; each calls `next()` to continue. */
     readonly interceptors?: readonly AvInterceptor<M, R, F, V, A>[];
     /** Turn a thrown error into a {@link AvError} outcome. */
-    readonly filters?: readonly AvFilter<M, R, F, V, A>[];
+    readonly filters?: readonly AvFilter<M, R, F, V, PreCompute>[];
 };
 /**
  * A Resource's transaction stages: they run once per transaction with a

package/dist/config/pipeline-tree.resolver.d.ts

@@ -2,12 +2,12 @@ import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { AvFieldGuard, AvFieldPipe } from "../runtime/pipeline.js";
 import type { ResolvedPipelineConfig, ResolvedTransactionPipelineConfig } from "./pipeline-config.js";
 /** One variant's levels and whether a layer forces it. */
-export type ResolvedVariantPipelines = {
+type ResolvedVariantPipelines = {
     readonly pipelines: readonly ResolvedPipelineConfig[];
     readonly forceTransaction: boolean;
 };
 /** One family's levels, its variants' and whether a layer forces the family. */
-export type ResolvedFamilyPipelines = ResolvedVariantPipelines & {
+type ResolvedFamilyPipelines = ResolvedVariantPipelines & {
     readonly variants: Readonly<Record<string, ResolvedVariantPipelines>>;
 };
 /** One field's stages for one origin: the root's, then the overlay's. */

package/dist/contracts/access-route.rules.d.ts

@@ -0,0 +1,10 @@
+/**
+ * An absolute `http:`/`https:` URL, or a root-relative path other than `"/"`:
+ * never `//host`, a backslash, a control character, a space or a dot segment.
+ */
+export declare function isAccessUrl(value: unknown): value is string;
+/**
+ * A verb's path under the section's `url`: starting with one `/`, never a
+ * backslash, a control character, a space or a dot segment.
+ */
+export declare function isAccessPath(value: unknown): value is string;

package/dist/contracts/access-route.rules.js

@@ -0,0 +1,45 @@
+function hasControlOrSpace(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x20 || code === 0x7f) {
+            return true;
+        }
+    }
+    return false;
+}
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/i;
+function hasDotSegment(path) {
+    const end = path.search(/[?#]/);
+    return (end === -1 ? path : path.slice(0, end))
+        .split("/")
+        .some((segment) => DOT_SEGMENT.test(segment));
+}
+export function isAccessUrl(value) {
+    if (typeof value !== "string" ||
+        value.includes("\\") ||
+        hasControlOrSpace(value)) {
+        return false;
+    }
+    if (value.startsWith("/")) {
+        return value !== "/" && !value.startsWith("//") && !hasDotSegment(value);
+    }
+    const authority = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*/i.exec(value)?.[0];
+    if (authority === undefined || hasDotSegment(value.slice(authority.length))) {
+        return false;
+    }
+    try {
+        const { protocol } = new URL(value);
+        return protocol === "https:" || protocol === "http:";
+    }
+    catch {
+        return false;
+    }
+}
+export function isAccessPath(value) {
+    return (typeof value === "string" &&
+        value.startsWith("/") &&
+        !value.startsWith("//") &&
+        !value.includes("\\") &&
+        !hasControlOrSpace(value) &&
+        !hasDotSegment(value));
+}

package/dist/contracts/capability.d.ts

@@ -1,11 +1,36 @@
 /** The operators a scalar field can be filtered with. */
 export type AvScalarFilterOperator = "equals" | "not" | "in" | "notIn" | "lt" | "lte" | "gt" | "gte" | "contains" | "startsWith" | "endsWith" | "mode" | "has" | "hasEvery" | "hasSome" | "isEmpty" | "path" | "stringContains" | "stringStartsWith" | "stringEndsWith" | "arrayContains" | "arrayStartsWith" | "arrayEndsWith";
+/**
+ * The case-sensitivity a text filter's `mode` asks for. `"default"` is whatever
+ * the database's own comparison does and is always available; `"sensitive"` and
+ * `"insensitive"` are an explicit promise, available on a field only where its
+ * `filterModes` lists them.
+ */
+export declare const FILTER_MODES: readonly ["default", "sensitive", "insensitive"];
+/** @see FILTER_MODES, the axis this union is derived from. */
+export type ScalarFilterMode = (typeof FILTER_MODES)[number];
 /** What an update can do to a scalar value besides setting it. */
 export type AvScalarMutationDirective = "$increment" | "$decrement" | "$multiply" | "$divide" | "$push" | "$unset";
 /** How a relation can be filtered on. */
 export type AvRelationFilterCapability = "nested" | "match" | "null" | "some" | "every" | "none";
 /** What a write can do to a relation: `$create`, `$connect` and the rest. */
 export type AvRelationMutationDirective = "$create" | "$connect" | "$connectOrCreate" | "$disconnect" | "$set" | "$update" | "$delete" | "$upsert";
+/** The to-one directives that change which row the relation links. */
+export declare const TO_ONE_RELINK_DIRECTIVES: readonly ["$connect", "$connectOrCreate", "$create", "$set", "$disconnect"];
+/** The to-one directives that write the row the relation links. */
+export declare const TO_ONE_REWRITE_DIRECTIVES: readonly ["$update", "$upsert"];
+/** @see TO_ONE_RELINK_DIRECTIVES */
+export type ToOneRelinkDirective = (typeof TO_ONE_RELINK_DIRECTIVES)[number];
+/** @see TO_ONE_REWRITE_DIRECTIVES */
+export type ToOneRewriteDirective = (typeof TO_ONE_REWRITE_DIRECTIVES)[number];
+/**
+ * A to-one operand's directives that both relink the relation and write the
+ * linked row, or `undefined` when it does not pair them.
+ */
+export declare function toOneRelinkWithRewrite(operand: Readonly<Record<string, unknown>>): {
+    readonly rewrite: readonly ToOneRewriteDirective[];
+    readonly relink: readonly ToOneRelinkDirective[];
+} | undefined;
 /** How a list of related rows can be paginated. */
 export type AvPaginationCapability = "limit" | "offset" | "cursor";
 /** What a projection can compute over a to-many relation. */
@@ -24,6 +49,6 @@ export type AvProjectionScope = (typeof PROJECTION_SCOPES)[number];
  * not the operation that carries it. The write counterpart of
  * {@link AvProjectionScope}.
  */
-export declare const WRITE_SCOPES: readonly ["nested", "bulkWrite"];
+export declare const WRITE_SCOPES: readonly ["nested", "bulkWrite", "loopback"];
 /** @see WRITE_SCOPES, the axis this union is derived from. */
 export type AvWriteScope = (typeof WRITE_SCOPES)[number];

package/dist/contracts/capability.js

@@ -1,3 +1,22 @@
+export const FILTER_MODES = ["default", "sensitive", "insensitive"];
+export const TO_ONE_RELINK_DIRECTIVES = [
+    "$connect",
+    "$connectOrCreate",
+    "$create",
+    "$set",
+    "$disconnect",
+];
+export const TO_ONE_REWRITE_DIRECTIVES = [
+    "$update",
+    "$upsert",
+];
+export function toOneRelinkWithRewrite(operand) {
+    const rewrite = TO_ONE_REWRITE_DIRECTIVES.filter((key) => Object.hasOwn(operand, key));
+    const relink = TO_ONE_RELINK_DIRECTIVES.filter((key) => Object.hasOwn(operand, key));
+    return rewrite.length === 0 || relink.length === 0
+        ? undefined
+        : { rewrite, relink };
+}
 export const PROJECTION_SCOPES = [
     "record",
     "bulkWrite",
@@ -5,4 +24,5 @@ export const PROJECTION_SCOPES = [
 export const WRITE_SCOPES = [
     "nested",
     "bulkWrite",
+    "loopback",
 ];