@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.1

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

@@ -1,35 +0,0 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { AdapterFieldKey } from "../adapters/adapter-resource.js";
-import type { FrameworkResourceKey, FrameworkScalarFieldConfig, FrameworkScalarTypeRef } from "./framework-fields-config.js";
-/**
- * What a configuration may say about a field the adapter already discovered:
- * everything in {@link FrameworkScalarFieldConfig} except `type`.
- */
-export type KnownScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit<FrameworkScalarFieldConfig<M>, "type"> & {
-    readonly type?: never;
-};
-/**
- * A scalar field the configuration adds, which the adapter did not discover.
- * `type`, `nullable` and `list` are required.
- */
-export type AddedScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit<FrameworkScalarFieldConfig<M>, "type" | "nullable" | "list"> & {
-    readonly type: FrameworkScalarTypeRef<M>;
-    readonly nullable: boolean;
-    readonly list: boolean;
-};
-/** The shape one authored field name admits, by what the adapter knows of it. */
-type ScalarFieldConfigFor<M extends AdapterModel, R extends FrameworkResourceKey<M>, F> = string extends AdapterFieldKey<M, R> ? FrameworkScalarFieldConfig<M> : F extends AdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
-    readonly kind: "relation";
-} ? never : KnownScalarFieldConfig<M> : AddedScalarFieldConfig<M>;
-/** The shape an authored `fields` block is checked against, keyed on its own names. */
-export type FrameworkFieldsShape<M extends AdapterModel, Self> = {
-    readonly [R in keyof Self]: R extends FrameworkResourceKey<M> ? {
-        readonly [F in keyof Self[R]]: ScalarFieldConfigFor<M, R, F>;
-    } : never;
-};
-/**
- * Authors stage 1 of a configuration: the `fields` block, checked against
- * what the adapter discovered and returned unwidened.
- */
-export declare function defineFields<M extends AdapterModel, const Self extends FrameworkFieldsShape<M, Self>>(_model: M, fields: Self): Self;
-export {};

package/dist/config/define-fields.js

@@ -1,3 +0,0 @@
-export function defineFields(_model, fields) {
-    return fields;
-}

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

@@ -1,30 +0,0 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { ComputedReadBehavior, ComputeOnCreate, ComputeOnUpdate } from "../runtime/field-behavior.js";
-import type { AnyFrameworkConfig } from "./any-framework-config.js";
-import type { EffectiveFieldKey } from "./effective-fields.js";
-import type { FrameworkResourceKey } from "./framework-fields-config.js";
-/** A read behavior: a compute function, or one declaring the fields it reads. */
-export type FrameworkReadBehavior<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = ComputedReadBehavior<M, Cfg, R>;
-/**
- * A field's behaviors: a value computed on create, on update, or on read.
- * `false` turns off a behavior set at an outer layer.
- */
-export type FrameworkFieldBehaviorConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = {
-    /** Computes the field's value when a row is created. */
-    readonly create?: false | ComputeOnCreate<M, Cfg, R>;
-    /** Computes the field's value when a row is updated. */
-    readonly update?: false | ComputeOnUpdate<M, Cfg, R>;
-    /** Computes the field's value when a row is read. */
-    readonly read?: false | FrameworkReadBehavior<M, Cfg, R>;
-};
-/** Behaviors for one Resource's fields. */
-export type FrameworkResourceBehaviorsConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = {
-    /** Behaviors per field name. */
-    readonly fields: Readonly<Partial<{
-        [F in EffectiveFieldKey<M, Cfg, R>]: FrameworkFieldBehaviorConfig<M, Cfg, R>;
-    }>>;
-};
-/** Server-side behaviors, per Resource. */
-export type FrameworkBehaviorsConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = Readonly<Partial<{
-    [R in FrameworkResourceKey<M>]: FrameworkResourceBehaviorsConfig<M, Cfg, R>;
-}>>;

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

@@ -1,36 +0,0 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { ScalarFieldCapabilities, ScalarFormat } from "../contracts/field.js";
-import type { LifecycleTrait } from "../contracts/lifecycle-trait.js";
-/** The lifecycle traits a configuration may set on a field. */
-export type FrameworkFieldLifecycleTrait = Extract<LifecycleTrait, "VIRTUAL">;
-/** The names of the Resources in adapter model `M`. */
-export type FrameworkResourceKey<M extends AdapterModel> = Extract<keyof M["resources"], string>;
-/** A scalar type or an enum of adapter model `M`, by name. */
-export type FrameworkScalarTypeRef<M extends AdapterModel> = {
-    readonly scalar: Extract<keyof M["scalars"], string>;
-} | {
-    readonly enum: Extract<keyof M["enums"], string>;
-};
-/**
- * A scalar field's settings. For a discovered field, the discovered values are
- * the baseline; a field the adapter did not discover must state `type`,
- * `nullable` and `list`.
- */
-export type FrameworkScalarFieldConfig<M extends AdapterModel = AdapterModel> = {
-    /** The field's scalar or enum type. */
-    readonly type?: FrameworkScalarTypeRef<M>;
-    /** The scalar's format name, carried in the Contract. */
-    readonly format?: ScalarFormat;
-    /** Whether the field may be `null`. */
-    readonly nullable?: boolean;
-    /** Whether the field holds a list of values. */
-    readonly list?: boolean;
-    /** Persistence traits: `"VIRTUAL"` marks a field the store does not hold. */
-    readonly lifecycle?: readonly FrameworkFieldLifecycleTrait[];
-    /** The field's capabilities; see {@link ScalarFieldCapabilities}. */
-    readonly capabilities?: Partial<ScalarFieldCapabilities>;
-};
-/** Field settings for one Resource, by field name. */
-export type FrameworkResourceFieldsConfig<M extends AdapterModel = AdapterModel> = Readonly<Record<string, FrameworkScalarFieldConfig<M>>>;
-/** Fields to add or describe, per Resource. */
-export type FrameworkFieldsConfig<M extends AdapterModel = AdapterModel> = Readonly<Partial<Record<FrameworkResourceKey<M>, FrameworkResourceFieldsConfig<M>>>>;

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

@@ -1,142 +0,0 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
-import type { AdapterFieldKey } from "../adapters/adapter-resource.js";
-import type { PaginationCapability, ProjectionScope, RelationFilterCapability, RelationMutationDirective, RelationReducer, ScalarFilterOperator, ScalarMutationDirective, WriteScope } from "../contracts/capability.js";
-import type { AnyFrameworkConfig } from "./any-framework-config.js";
-import type { EffectiveFieldKey } from "./effective-fields.js";
-import type { FrameworkResourceKey } from "./framework-fields-config.js";
-/**
- * `true` keeps a capability, `false` removes it, and a list keeps only the
- * listed entries. Restrictions only narrow what the adapter offers.
- */
-export type FrameworkCapabilitySetRestriction<T extends string> = boolean | readonly T[];
-/**
- * A restriction on a relation's `select` or `include` capability: `true`,
- * `false`, or the projection positions to keep.
- */
-export type FrameworkProjectionScopeRestriction = boolean | readonly ProjectionScope[];
-/**
- * A restriction on a relation's `create` or `update` capability. A directive
- * list narrows the directives only; the object form can also narrow the write
- * positions (`scopes`).
- *
- * `directives: []` leaves the relation writable with no directive;
- * `scopes: []` or `false` makes it not writable.
- */
-export type FrameworkRelationMutationRestriction = boolean | readonly RelationMutationDirective[] | {
-    readonly directives?: readonly RelationMutationDirective[];
-    readonly scopes?: readonly WriteScope[];
-};
-/**
- * A restriction on a relation's `reducers` capability: `true`, `false`, a
- * reducer list, or an object narrowing reducers and projection positions.
- */
-export type FrameworkRelationReducerRestriction = boolean | readonly RelationReducer[] | {
-    readonly reducers?: readonly RelationReducer[];
-    readonly scopes?: readonly ProjectionScope[];
-};
-/** Restrictions on a scalar field's capabilities. */
-export type FrameworkScalarCapabilityRestrictions = {
-    /** Whether the field can be selected. */
-    readonly select?: boolean;
-    /** The filter operators to keep. */
-    readonly filter?: FrameworkCapabilitySetRestriction<ScalarFilterOperator>;
-    /** Whether results can be ordered by the field. */
-    readonly order?: boolean;
-    /** Whether ordering can place `null`s first or last. */
-    readonly orderNulls?: boolean;
-    /** The directives to keep when creating. */
-    readonly create?: FrameworkCapabilitySetRestriction<ScalarMutationDirective>;
-    /** The directives to keep when updating. */
-    readonly update?: FrameworkCapabilitySetRestriction<ScalarMutationDirective>;
-};
-/**
- * Restrictions on a relation field's capabilities. `select`, `include`,
- * `reducers`, `create` and `update` can also be narrowed by argument position.
- */
-export type FrameworkRelationCapabilityRestrictions = {
-    readonly select?: FrameworkProjectionScopeRestriction;
-    readonly include?: FrameworkProjectionScopeRestriction;
-    readonly filter?: FrameworkCapabilitySetRestriction<RelationFilterCapability>;
-    readonly order?: boolean;
-    readonly pagination?: FrameworkCapabilitySetRestriction<PaginationCapability>;
-    readonly reducers?: FrameworkRelationReducerRestriction;
-    readonly create?: FrameworkRelationMutationRestriction;
-    readonly update?: FrameworkRelationMutationRestriction;
-};
-/** Restrictions for one scalar field. */
-export type FrameworkScalarFieldRestrictions = {
-    /** `true` hides the field. */
-    readonly hidden?: boolean;
-    /** Capabilities to narrow. */
-    readonly capabilities?: FrameworkScalarCapabilityRestrictions;
-};
-/** Restrictions for one relation field. */
-export type FrameworkRelationFieldRestrictions = {
-    /** `true` hides the field. */
-    readonly hidden?: boolean;
-    /** Capabilities to narrow. */
-    readonly capabilities?: FrameworkRelationCapabilityRestrictions;
-};
-/** Restrictions for one field: scalar or relation. */
-export type FrameworkFieldRestrictions = FrameworkScalarFieldRestrictions | FrameworkRelationFieldRestrictions;
-/**
- * Standard operations to turn off, by family and variant: `false` removes
- * one the adapter offers.
- */
-export type FrameworkResourceOperationRestrictions = {
-    readonly find?: {
-        readonly first?: boolean;
-        readonly unique?: boolean;
-        readonly many?: boolean;
-        readonly count?: boolean;
-    };
-    readonly create?: {
-        readonly one?: boolean;
-        readonly many?: boolean;
-        readonly count?: boolean;
-    };
-    readonly update?: {
-        readonly first?: boolean;
-        readonly unique?: boolean;
-        readonly many?: boolean;
-        readonly count?: boolean;
-    };
-    readonly delete?: {
-        readonly first?: boolean;
-        readonly unique?: boolean;
-        readonly many?: boolean;
-        readonly count?: boolean;
-    };
-    readonly upsert?: {
-        readonly unique?: boolean;
-    };
-};
-/** The restriction shape an adapter-discovered field admits, by its kind. */
-type AdapterFieldRestrictionsFor<TField> = TField extends {
-    readonly kind: "scalar";
-} ? FrameworkScalarFieldRestrictions : TField extends {
-    readonly kind: "relation";
-} ? FrameworkRelationFieldRestrictions : FrameworkFieldRestrictions;
-/**
- * The restriction shape one effective field name admits. Three cases, in
- * order.
- */
-type FieldRestrictionsFor<M extends AdapterModel, R extends FrameworkResourceKey<M>, F extends string> = string extends F ? FrameworkFieldRestrictions : F extends AdapterFieldKey<M, R> ? AdapterFieldRestrictionsFor<M["resources"][R]["fields"][F]> : FrameworkScalarFieldRestrictions;
-/** Restrictions for one Resource's fields, by field name. */
-export type FrameworkResourceFieldRestrictions<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = Readonly<Partial<{
-    [F in EffectiveFieldKey<M, Cfg, R>]: FieldRestrictionsFor<M, R, F>;
-}>>;
-/** Restrictions for one Resource. */
-export type FrameworkResourceRestrictions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig, R extends FrameworkResourceKey<M> = FrameworkResourceKey<M>> = {
-    /** `true` hides the whole Resource. */
-    readonly hidden?: boolean;
-    /** Restrictions per field. */
-    readonly fields?: FrameworkResourceFieldRestrictions<M, Cfg, R>;
-    /** Standard operations to turn off. */
-    readonly operations?: FrameworkResourceOperationRestrictions;
-};
-/** What to hide or narrow, per Resource. */
-export type FrameworkRestrictionsConfig<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = Readonly<Partial<{
-    [R in FrameworkResourceKey<M>]: FrameworkResourceRestrictions<M, Cfg, R>;
-}>>;
-export {};

package/dist/operations/operation-boolean-nodes.d.ts

@@ -1,11 +0,0 @@
-import type { Contract } from "../contracts/contract.js";
-import type { OperationIdentity } from "./operation-identity.js";
-import type { ValidationIssue } from "./validation-code.js";
-/**
- * Enforces maxBooleanNodes across every general where tree in one semantic
- * operation, including root filters, returned-relation filters, and nested
- * relation mutation filters. Unique selectors are intentionally excluded.
- */
-export declare function findOperationBooleanNodeIssue(contract: Contract, request: OperationIdentity & {
-    readonly resource: string;
-}, args: Readonly<Record<string, unknown>>): ValidationIssue | undefined;

package/dist/operations/operation-boolean-nodes.js

@@ -1,283 +0,0 @@
-import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
-import { advertisedDirectives, holdsAt, } from "../contracts/field.js";
-import { NESTED_PROJECTION_SCOPE, resolveProjectionScope, } from "./projection-scope.resolver.js";
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function booleanNodeIssue(contract, path) {
-    return {
-        path,
-        code: "V1015",
-        message: `Boolean/filter node count exceeds maxBooleanNodes (${contract.limits.maxBooleanNodes}).`,
-    };
-}
-function countNode(state, path) {
-    state.count += 1;
-    return state.count > state.contract.limits.maxBooleanNodes
-        ? booleanNodeIssue(state.contract, path)
-        : undefined;
-}
-function walkWhere(state, resourceName, value, path) {
-    if (!isRecord(value)) {
-        return undefined;
-    }
-    const resource = lookupResource(state.contract, resourceName);
-    if (resource === undefined) {
-        return undefined;
-    }
-    for (const [key, child] of Object.entries(value)) {
-        const exceeded = countNode(state, [...path, key]);
-        if (exceeded !== undefined) {
-            return exceeded;
-        }
-        if (key === "AND" || key === "OR") {
-            if (!Array.isArray(child)) {
-                continue;
-            }
-            for (let index = 0; index < child.length; index += 1) {
-                const issue = walkWhere(state, resourceName, child[index], [
-                    ...path,
-                    key,
-                    index,
-                ]);
-                if (issue !== undefined) {
-                    return issue;
-                }
-            }
-            continue;
-        }
-        if (key === "NOT") {
-            const issue = walkWhere(state, resourceName, child, [...path, key]);
-            if (issue !== undefined) {
-                return issue;
-            }
-            continue;
-        }
-        const field = lookupField(resource, key);
-        if (field?.kind !== "relation") {
-            continue;
-        }
-        if (field.cardinality === "one") {
-            if (child === null || !isRecord(child)) {
-                continue;
-            }
-            const issue = walkWhere(state, field.target, child, [...path, key]);
-            if (issue !== undefined) {
-                return issue;
-            }
-            continue;
-        }
-        if (!isRecord(child)) {
-            continue;
-        }
-        for (const relationOperator of ["some", "every", "none"]) {
-            if (!(relationOperator in child)) {
-                continue;
-            }
-            const issue = walkWhere(state, field.target, child[relationOperator], [
-                ...path,
-                key,
-                relationOperator,
-            ]);
-            if (issue !== undefined) {
-                return issue;
-            }
-        }
-    }
-    return undefined;
-}
-function projectionRelation(contract, resourceName, entry, mode, scope) {
-    if (Object.keys(entry).length !== 1) {
-        return undefined;
-    }
-    const name = Object.keys(entry)[0];
-    const field = lookupField(lookupResource(contract, resourceName), name);
-    if (field?.kind !== "relation") {
-        return undefined;
-    }
-    if (mode === "select" && !holdsAt(field.capabilities.select, scope)) {
-        return undefined;
-    }
-    if (mode === "include" && !holdsAt(field.capabilities.include, scope)) {
-        return undefined;
-    }
-    return { name, edge: field, value: entry[name] };
-}
-function walkProjection(state, resourceName, value, mode, scope, path) {
-    if (!Array.isArray(value)) {
-        return undefined;
-    }
-    for (let index = 0; index < value.length; index += 1) {
-        const entry = value[index];
-        if (!isRecord(entry)) {
-            continue;
-        }
-        const relation = projectionRelation(state.contract, resourceName, entry, mode, scope);
-        if (relation === undefined || !isRecord(relation.value)) {
-            continue;
-        }
-        const relationPath = [...path, index, relation.name];
-        if ("where" in relation.value &&
-            relation.edge.capabilities.filter?.includes("nested") === true) {
-            const issue = walkWhere(state, relation.edge.target, relation.value.where, [...relationPath, "where"]);
-            if (issue !== undefined) {
-                return issue;
-            }
-        }
-        for (const nestedMode of ["select", "include"]) {
-            if (!(nestedMode in relation.value)) {
-                continue;
-            }
-            const issue = walkProjection(state, relation.edge.target, relation.value[nestedMode], nestedMode, NESTED_PROJECTION_SCOPE, [...relationPath, nestedMode]);
-            if (issue !== undefined) {
-                return issue;
-            }
-        }
-    }
-    return undefined;
-}
-function relationEntries(value) {
-    return Array.isArray(value) ? value : [value];
-}
-function walkMutationData(state, resourceName, value, stage, path) {
-    if (!isRecord(value)) {
-        return undefined;
-    }
-    const resource = lookupResource(state.contract, resourceName);
-    if (resource === undefined) {
-        return undefined;
-    }
-    for (const [fieldName, fieldValue] of Object.entries(value)) {
-        const edge = lookupField(resource, fieldName);
-        if (edge?.kind !== "relation" || !isRecord(fieldValue)) {
-            continue;
-        }
-        const supported = advertisedDirectives(edge.capabilities[stage]);
-        for (const [directive, directiveValue] of Object.entries(fieldValue)) {
-            if (supported?.includes(directive) !== true) {
-                continue;
-            }
-            const entries = relationEntries(directiveValue);
-            for (let index = 0; index < entries.length; index += 1) {
-                const entry = entries[index];
-                const indexPath = Array.isArray(directiveValue) ? [index] : [];
-                const directivePath = [...path, fieldName, directive, ...indexPath];
-                if (directive === "$create") {
-                    const issue = walkMutationData(state, edge.target, entry, "create", directivePath);
-                    if (issue !== undefined) {
-                        return issue;
-                    }
-                    continue;
-                }
-                if (!isRecord(entry)) {
-                    continue;
-                }
-                if (directive === "$connectOrCreate" && "create" in entry) {
-                    const issue = walkMutationData(state, edge.target, entry.create, "create", [...directivePath, "create"]);
-                    if (issue !== undefined) {
-                        return issue;
-                    }
-                    continue;
-                }
-                if (directive === "$update") {
-                    if ("where" in entry) {
-                        const issue = walkWhere(state, edge.target, entry.where, [
-                            ...directivePath,
-                            "where",
-                        ]);
-                        if (issue !== undefined) {
-                            return issue;
-                        }
-                    }
-                    if ("data" in entry) {
-                        const issue = walkMutationData(state, edge.target, entry.data, "update", [...directivePath, "data"]);
-                        if (issue !== undefined) {
-                            return issue;
-                        }
-                    }
-                    continue;
-                }
-                if (directive === "$delete" && "where" in entry) {
-                    const issue = walkWhere(state, edge.target, entry.where, [
-                        ...directivePath,
-                        "where",
-                    ]);
-                    if (issue !== undefined) {
-                        return issue;
-                    }
-                    continue;
-                }
-                if (directive === "$upsert") {
-                    for (const branch of ["create", "update"]) {
-                        if (!(branch in entry)) {
-                            continue;
-                        }
-                        const issue = walkMutationData(state, edge.target, entry[branch], branch, [...directivePath, branch]);
-                        if (issue !== undefined) {
-                            return issue;
-                        }
-                    }
-                }
-            }
-        }
-    }
-    return undefined;
-}
-function isUniqueOperation(request) {
-    return (request.variant === "unique" &&
-        (request.family === "find" ||
-            request.family === "update" ||
-            request.family === "delete" ||
-            request.family === "upsert"));
-}
-export function findOperationBooleanNodeIssue(contract, request, args) {
-    const state = { contract, count: 0 };
-    const projectionScope = resolveProjectionScope(lookupResource(contract, request.resource), request);
-    if ("where" in args && !isUniqueOperation(request)) {
-        const issue = walkWhere(state, request.resource, args.where, [
-            "arguments",
-            "where",
-        ]);
-        if (issue !== undefined) {
-            return issue;
-        }
-    }
-    for (const mode of ["select", "include"]) {
-        if (!(mode in args)) {
-            continue;
-        }
-        const issue = walkProjection(state, request.resource, args[mode], mode, projectionScope, ["arguments", mode]);
-        if (issue !== undefined) {
-            return issue;
-        }
-    }
-    if (request.family === "create" && "data" in args) {
-        const entries = Array.isArray(args.data) ? args.data : [args.data];
-        for (let index = 0; index < entries.length; index += 1) {
-            const issue = walkMutationData(state, request.resource, entries[index], "create", Array.isArray(args.data)
-                ? ["arguments", "data", index]
-                : ["arguments", "data"]);
-            if (issue !== undefined) {
-                return issue;
-            }
-        }
-    }
-    if (request.family === "update" && "data" in args) {
-        const issue = walkMutationData(state, request.resource, args.data, "update", ["arguments", "data"]);
-        if (issue !== undefined) {
-            return issue;
-        }
-    }
-    if (request.family === "upsert") {
-        for (const branch of ["create", "update"]) {
-            if (!(branch in args)) {
-                continue;
-            }
-            const issue = walkMutationData(state, request.resource, args[branch], branch, ["arguments", branch]);
-            if (issue !== undefined) {
-                return issue;
-            }
-        }
-    }
-    return undefined;
-}

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

@@ -1,8 +0,0 @@
-import type { Contract } from "../contracts/contract.js";
-import type { ValidationIssue } from "./validation-code.js";
-/**
- * Enforces the Contract's semantic nesting limit across where, projection,
- * orderBy, mutation data, and relation traversal before deeper argument
- * validation.
- */
-export declare function findOperationNestingIssue(contract: Contract, resourceName: string, args: Readonly<Record<string, unknown>>): ValidationIssue | undefined;