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

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

@@ -0,0 +1,79 @@
+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 = {
+    readonly pipelines: readonly ResolvedPipelineConfig[];
+    readonly forceTransaction: boolean;
+};
+/** One family's levels, its variants' and whether a layer forces the family. */
+export type ResolvedFamilyPipelines = ResolvedVariantPipelines & {
+    readonly variants: Readonly<Record<string, ResolvedVariantPipelines>>;
+};
+/** One field's stages for one origin: the root's, then the overlay's. */
+export type ResolvedFieldStages = {
+    readonly pipes: readonly AvFieldPipe[];
+    readonly guards: readonly AvFieldGuard[];
+    /**
+     * The field's validators as authored, root's then overlay's: the Contract compiler
+     * checks and compiles them; the runtime reads the compiled form
+     * (`field-validator.registry.ts`).
+     */
+    readonly validators: readonly unknown[];
+};
+/** One Resource's levels for one origin. */
+export type ResolvedResourcePipelines = {
+    readonly pipelines: readonly ResolvedPipelineConfig[];
+    readonly families: Readonly<Record<string, ResolvedFamilyPipelines>>;
+    readonly transactions: readonly ResolvedTransactionPipelineConfig[];
+    readonly fields: Readonly<Record<string, ResolvedFieldStages>>;
+};
+/** Every stage that runs for one origin, by level. */
+export type ResolvedPipelineTree = {
+    readonly layer: readonly ResolvedPipelineConfig[];
+    readonly resources: Readonly<Record<string, ResolvedResourcePipelines>>;
+};
+type UnknownRecord = Readonly<Record<string, unknown>>;
+/**
+ * The pipeline tree of one origin: each layer's registrations in turn, at every
+ * level — the root's, then the overlay's; for the agent, the root's, then the
+ * overlay it extends, then its own. The root layer alone (the Core Contract's)
+ * is one layer.
+ */
+export declare function resolvePipelineTree(layers: readonly UnknownRecord[]): ResolvedPipelineTree;
+/** The tree a raw ctx call runs over: `tree`'s field pipes, and nothing else. */
+export declare function rawPipelineTree(tree: ResolvedPipelineTree): ResolvedPipelineTree;
+/**
+ * The levels of one operation, outer to inner: root layer, overlay layer, root
+ * Resource, overlay Resource, root family, overlay family, root variant, overlay
+ * variant. A level no layer states is left out.
+ */
+export declare function operationLevels(tree: ResolvedPipelineTree, operation: AvOperationIdentity & {
+    readonly resource: string;
+}): readonly ResolvedPipelineConfig[];
+/**
+ * The levels a nested write's target runs, outer to inner: root Resource,
+ * overlay Resource, root family, overlay family. A level no layer states is
+ * left out.
+ */
+export declare function nestedTargetLevels(tree: ResolvedPipelineTree, resource: string, family: string): readonly ResolvedPipelineConfig[];
+/** Whether a layer sets `forceTransaction` on the operation's family or variant. */
+export declare function isForcedOperation(tree: ResolvedPipelineTree, operation: AvOperationIdentity & {
+    readonly resource: string;
+}): boolean;
+/** The field stages registered on one Resource's fields, by field name. */
+export declare function fieldStagesOf(tree: ResolvedPipelineTree, resource: string): Readonly<Record<string, ResolvedFieldStages>>;
+/** One Resource's transaction levels: the root's, then the overlay's. */
+export declare function transactionLevelsOf(tree: ResolvedPipelineTree, resource: string): readonly ResolvedTransactionPipelineConfig[];
+/**
+ * Every `forceTransaction` the tree states, as the configuration paths that set
+ * it (`resources.R.operations.F[.V]`), with the operation each one forces. Read
+ * once at construction, for the startup check against `transactionsStyle`.
+ */
+export declare function forcedOperationsOf(layer: UnknownRecord, prefix: string): readonly {
+    readonly path: string;
+    readonly resource: string;
+    readonly family: string;
+    readonly variant: string | undefined;
+}[];
+export {};

package/dist/config/pipeline-tree.resolver.js

@@ -0,0 +1,220 @@
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function own(record, key) {
+    return record !== undefined && Object.hasOwn(record, key)
+        ? record[key]
+        : undefined;
+}
+function list(value) {
+    return Array.isArray(value) ? [...value] : [];
+}
+function levelOf(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const pipeline = value;
+    return {
+        guards: list(pipeline.guards),
+        pipes: list(pipeline.pipes),
+        hooks: {
+            before: list(pipeline.hooks?.before),
+            after: list(pipeline.hooks?.after),
+        },
+        interceptors: list(pipeline.interceptors),
+        filters: list(pipeline.filters),
+    };
+}
+function transactionLevelOf(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const pipeline = value;
+    return {
+        guards: list(pipeline.guards),
+        pipes: list(pipeline.pipes),
+        hooks: {
+            before: list(pipeline.hooks?.before),
+            after: list(pipeline.hooks?.after),
+        },
+        interceptors: list(pipeline.interceptors),
+        filters: list(pipeline.filters),
+    };
+}
+function levels(layers, read) {
+    return layers.flatMap((layer) => {
+        const level = read(layer);
+        return level === undefined ? [] : [level];
+    });
+}
+function child(value, key) {
+    return isRecord(value) && Object.hasOwn(value, key) ? value[key] : undefined;
+}
+function forced(layers) {
+    return layers.some((layer) => child(layer, "forceTransaction") === true);
+}
+function keysOf(layers, skip) {
+    const keys = new Set();
+    for (const layer of layers) {
+        if (!isRecord(layer)) {
+            continue;
+        }
+        for (const key of Object.keys(layer)) {
+            if (skip?.has(key) !== true) {
+                keys.add(key);
+            }
+        }
+    }
+    return keys;
+}
+const FAMILY_LEVEL_KEYS = new Set(["pipelines", "forceTransaction"]);
+function resolveVariant(layers) {
+    return {
+        pipelines: levels(layers, (layer) => levelOf(child(layer, "pipelines"))),
+        forceTransaction: forced(layers),
+    };
+}
+function resolveFamily(layers) {
+    const variants = {};
+    for (const variant of keysOf(layers, FAMILY_LEVEL_KEYS)) {
+        variants[variant] = resolveVariant(layers.map((layer) => child(layer, variant)));
+    }
+    return { ...resolveVariant(layers), variants };
+}
+function resolveFields(layers) {
+    const fields = {};
+    for (const field of keysOf(layers)) {
+        const pipelines = layers.map((layer) => child(child(layer, field), "pipelines"));
+        const pipes = pipelines.flatMap((stage) => list(child(stage, "pipes")));
+        const guards = pipelines.flatMap((stage) => list(child(stage, "guards")));
+        const validators = pipelines.flatMap((stage) => list(child(stage, "validators")));
+        if (pipes.length > 0 || guards.length > 0 || validators.length > 0) {
+            fields[field] = { pipes, guards, validators };
+        }
+    }
+    return fields;
+}
+function resolveResource(layers) {
+    const operations = layers.map((layer) => child(layer, "operations"));
+    const families = {};
+    for (const family of keysOf(operations)) {
+        families[family] = resolveFamily(operations.map((layer) => child(layer, family)));
+    }
+    return {
+        pipelines: levels(layers, (layer) => levelOf(child(layer, "pipelines"))),
+        families,
+        transactions: levels(layers, (layer) => transactionLevelOf(child(child(layer, "transactions"), "pipelines"))),
+        fields: resolveFields(layers.map((layer) => child(layer, "fields"))),
+    };
+}
+export function resolvePipelineTree(layers) {
+    const trees = layers.map((layer) => child(layer, "resources"));
+    const resources = {};
+    for (const resource of keysOf(trees)) {
+        resources[resource] = resolveResource(trees.map((tree) => child(tree, resource)));
+    }
+    return {
+        layer: levels(layers, (layer) => levelOf(child(layer, "pipelines"))),
+        resources,
+    };
+}
+const NO_LEVELS = Object.freeze([]);
+export function rawPipelineTree(tree) {
+    const resources = {};
+    for (const [name, resource] of Object.entries(tree.resources)) {
+        const fields = {};
+        for (const [field, stages] of Object.entries(resource.fields)) {
+            if (stages.pipes.length > 0) {
+                fields[field] = {
+                    pipes: stages.pipes,
+                    guards: [],
+                    validators: stages.validators,
+                };
+            }
+        }
+        resources[name] = {
+            pipelines: NO_LEVELS,
+            families: {},
+            transactions: [],
+            fields,
+        };
+    }
+    return { layer: NO_LEVELS, resources };
+}
+export function operationLevels(tree, operation) {
+    const resource = own(tree.resources, operation.resource);
+    if (resource === undefined) {
+        return tree.layer;
+    }
+    const family = own(resource.families, operation.family);
+    const variant = own(family?.variants, operation.variant);
+    return [
+        ...tree.layer,
+        ...resource.pipelines,
+        ...(family?.pipelines ?? NO_LEVELS),
+        ...(variant?.pipelines ?? NO_LEVELS),
+    ];
+}
+export function nestedTargetLevels(tree, resource, family) {
+    const found = own(tree.resources, resource);
+    if (found === undefined) {
+        return NO_LEVELS;
+    }
+    return [
+        ...found.pipelines,
+        ...(own(found.families, family)?.pipelines ?? NO_LEVELS),
+    ];
+}
+export function isForcedOperation(tree, operation) {
+    const family = own(own(tree.resources, operation.resource)?.families, operation.family);
+    return (family?.forceTransaction === true ||
+        own(family?.variants, operation.variant)?.forceTransaction === true);
+}
+const NO_FIELDS = Object.freeze({});
+export function fieldStagesOf(tree, resource) {
+    return own(tree.resources, resource)?.fields ?? NO_FIELDS;
+}
+export function transactionLevelsOf(tree, resource) {
+    return own(tree.resources, resource)?.transactions ?? [];
+}
+export function forcedOperationsOf(layer, prefix) {
+    const found = [];
+    const resources = child(layer, "resources");
+    if (!isRecord(resources)) {
+        return found;
+    }
+    for (const [resource, entry] of Object.entries(resources)) {
+        const operations = child(entry, "operations");
+        if (!isRecord(operations)) {
+            continue;
+        }
+        for (const [family, level] of Object.entries(operations)) {
+            const familyPath = `${prefix}resources.${resource}.operations.${family}`;
+            if (child(level, "forceTransaction") === true) {
+                found.push({
+                    path: `${familyPath}.forceTransaction`,
+                    resource,
+                    family,
+                    variant: undefined,
+                });
+            }
+            if (!isRecord(level)) {
+                continue;
+            }
+            for (const [variant, variantLevel] of Object.entries(level)) {
+                if (FAMILY_LEVEL_KEYS.has(variant)) {
+                    continue;
+                }
+                if (child(variantLevel, "forceTransaction") === true) {
+                    found.push({
+                        path: `${familyPath}.${variant}.forceTransaction`,
+                        resource,
+                        family,
+                        variant,
+                    });
+                }
+            }
+        }
+    }
+    return found;
+}

package/dist/config/stage-type.eraser.d.ts

@@ -0,0 +1,65 @@
+import type { AvComputeCreate, AvComputeRead, AvComputeUpdate } from "../runtime/field-compute.js";
+import type { AvScalarFieldPipeline } from "./field-pipeline-config.js";
+import type { AvPipeline, AvTransactionPipeline } from "./pipeline-config.js";
+/** Stage lists of one `pipelines` value as `Wide` states them; `validators` kept. */
+type ErasedPipelines<P, Wide> = P extends object ? {
+    [K in keyof P]: K extends "validators" ? P[K] : K extends "compute" ? ErasedCompute<P[K]> : K extends "hooks" ? ErasedStageGroup<P[K], NonNullable<Wide[K & keyof Wide]>> : K extends keyof Wide ? NonNullable<Wide[K]> : P[K];
+} : P;
+/** `hooks`, by phase (`before`, `after`). */
+type ErasedStageGroup<G, Wide> = G extends object ? {
+    [K in keyof G]: K extends keyof Wide ? NonNullable<Wide[K]> : G[K];
+} : G;
+/** A field's `compute`, by phase; a read stage's `dependsOn` kept. */
+type ErasedCompute<C> = C extends object ? {
+    [K in keyof C]: K extends "create" ? AvComputeCreate : K extends "update" ? AvComputeUpdate : K extends "read" ? C[K] extends {
+        readonly compute: unknown;
+    } ? {
+        [D in keyof C[K]]: D extends "compute" ? ComputeReadStage : C[K][D];
+    } : ComputeReadStage : C[K];
+} : C;
+/** A read compute stage's function form, for any model. */
+type ComputeReadStage = Parameters<Extract<AvComputeRead, (context: never) => unknown>>[0] extends infer Context ? (context: Context) => unknown : never;
+/** A variant's level: its `pipelines` erased, `forceTransaction` kept. */
+type ErasedVariant<V> = V extends object ? {
+    [K in keyof V]: K extends "pipelines" ? ErasedPipelines<V[K], AvPipeline> : V[K];
+} : V;
+/** A family's level: its own `pipelines` and each variant's. */
+type ErasedFamily<F> = F extends object ? {
+    [K in keyof F]: K extends "pipelines" ? ErasedPipelines<F[K], AvPipeline> : K extends "forceTransaction" ? F[K] : ErasedVariant<F[K]>;
+} : F;
+/** A field's entry: its `definition` kept, its `pipelines` erased. */
+type ErasedField<Field> = Field extends object ? {
+    [K in keyof Field]: K extends "pipelines" ? ErasedPipelines<Field[K], AvScalarFieldPipeline> : Field[K];
+} : Field;
+/**
+ * One Resource's block with every stage stated by its public type for any model.
+ */
+export type ErasedResourceBlock<B> = B extends object ? {
+    [K in keyof B]: K extends "pipelines" ? ErasedPipelines<B[K], AvPipeline> : K extends "operations" ? {
+        [F in keyof B[K]]: ErasedFamily<B[K][F]>;
+    } : K extends "transactions" ? {
+        [T in keyof B[K]]: T extends "pipelines" ? ErasedPipelines<B[K][T], AvTransactionPipeline> : B[K][T];
+    } : K extends "fields" ? {
+        [Name in keyof B[K]]: ErasedField<B[K][Name]>;
+    } : B[K];
+} : B;
+/** A Resource's overlay blocks (`application`, `client`, `agent`), each erased. */
+export type ErasedOverlayBlocks<Overlays> = Overlays extends object ? {
+    [L in keyof Overlays]: ErasedResourceBlock<Overlays[L]>;
+} : Overlays;
+/** A `resources` tree: each Resource's block erased. */
+export type ErasedResources<Resources> = Resources extends object ? {
+    [R in keyof Resources]: ErasedResourceBlock<Resources[R]>;
+} : Resources;
+/** One layer (the root's keys, `application`, `client`, `agent`): its stages erased. */
+type ErasedLayer<Layer> = Layer extends object ? {
+    [K in keyof Layer]: K extends "pipelines" ? ErasedPipelines<Layer[K], AvPipeline> : K extends "resources" ? ErasedResources<Layer[K]> : Layer[K];
+} : Layer;
+/**
+ * An authored configuration with every stage stated by its public type for any
+ * model: the `Cfg` a Framework carries (see the note above).
+ */
+export type ErasedConfig<Cfg> = Cfg extends object ? {
+    [K in keyof Cfg]: K extends "pipelines" ? ErasedPipelines<Cfg[K], AvPipeline> : K extends "resources" ? ErasedResources<Cfg[K]> : K extends "application" | "client" | "agent" ? ErasedLayer<Cfg[K]> : Cfg[K];
+} : Cfg;
+export {};

package/dist/config/stage-type.eraser.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/capability.d.ts

@@ -1,15 +1,15 @@
 /** The operators a scalar field can be filtered with. */
-export type ScalarFilterOperator = "equals" | "not" | "in" | "notIn" | "lt" | "lte" | "gt" | "gte" | "contains" | "startsWith" | "endsWith" | "mode" | "has" | "hasEvery" | "hasSome" | "isEmpty" | "path" | "stringContains" | "stringStartsWith" | "stringEndsWith" | "arrayContains" | "arrayStartsWith" | "arrayEndsWith";
+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";
 /** What an update can do to a scalar value besides setting it. */
-export type ScalarMutationDirective = "$increment" | "$decrement" | "$multiply" | "$divide" | "$push" | "$unset";
+export type AvScalarMutationDirective = "$increment" | "$decrement" | "$multiply" | "$divide" | "$push" | "$unset";
 /** How a relation can be filtered on. */
-export type RelationFilterCapability = "nested" | "match" | "null" | "some" | "every" | "none";
+export type AvRelationFilterCapability = "nested" | "match" | "null" | "some" | "every" | "none";
 /** What a write can do to a relation: `$create`, `$connect` and the rest. */
-export type RelationMutationDirective = "$create" | "$connect" | "$connectOrCreate" | "$disconnect" | "$set" | "$update" | "$delete" | "$upsert";
+export type AvRelationMutationDirective = "$create" | "$connect" | "$connectOrCreate" | "$disconnect" | "$set" | "$update" | "$delete" | "$upsert";
 /** How a list of related rows can be paginated. */
-export type PaginationCapability = "limit" | "offset" | "cursor";
+export type AvPaginationCapability = "limit" | "offset" | "cursor";
 /** What a projection can compute over a to-many relation. */
-export type RelationReducer = "$count";
+export type AvRelationReducer = "$count";
 /**
  * Where a projected field may be asked for: the kind of argument POSITION a projection
  * sits in, not the operation that carries it. A variant states the position its
@@ -17,13 +17,13 @@ export type RelationReducer = "$count";
  * projectable in.
  */
 export declare const PROJECTION_SCOPES: readonly ["record", "bulkWrite"];
-/** @see PROJECTION_SCOPES — the axis this union is derived from. */
-export type ProjectionScope = (typeof PROJECTION_SCOPES)[number];
+/** @see PROJECTION_SCOPES, the axis this union is derived from. */
+export type AvProjectionScope = (typeof PROJECTION_SCOPES)[number];
 /**
  * Where a field may be written: the kind of argument POSITION a write sits in,
  * not the operation that carries it. The write counterpart of
- * {@link ProjectionScope}.
+ * {@link AvProjectionScope}.
  */
 export declare const WRITE_SCOPES: readonly ["nested", "bulkWrite"];
-/** @see WRITE_SCOPES — the axis this union is derived from. */
-export type WriteScope = (typeof WRITE_SCOPES)[number];
+/** @see WRITE_SCOPES, the axis this union is derived from. */
+export type AvWriteScope = (typeof WRITE_SCOPES)[number];