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

package/dist/contracts/json-shape.d.ts

@@ -1,3 +1,4 @@
+import type { AvJsonListCheck, AvJsonNumberCheck, AvJsonStringCheck } from "./field-check.js";
 /**
  * The phantom key a Json Shape's TypeScript type travels under. Type-level only:
  * no value ever holds it.
@@ -20,7 +21,15 @@ export type JsonSchemaPrimitive = string | number | boolean | null;
  * the forms Aventara emits.
  */
 export type JsonSchema = {
-    readonly type: "string" | "number" | "integer" | "boolean" | "null";
+    readonly type: "boolean" | "null";
+} | {
+    readonly type: "string";
+    /** The node's checks, in the order they were added. */
+    readonly checks?: readonly AvJsonStringCheck[];
+} | {
+    readonly type: "number" | "integer";
+    /** The node's checks, in the order they were added. */
+    readonly checks?: readonly AvJsonNumberCheck[];
 } | {
     readonly const: JsonSchemaPrimitive;
 } | {
@@ -39,6 +48,8 @@ export type JsonSchema = {
 } | {
     readonly type: "array";
     readonly items: JsonSchema;
+    /** The list's length checks, in the order they were added. */
+    readonly checks?: readonly AvJsonListCheck[];
 } | {
     readonly type: "array";
     readonly prefixItems: readonly [JsonSchema, ...JsonSchema[]];

package/dist/contracts/lifecycle-trait.d.ts

@@ -1,8 +1,8 @@
 /**
  * Where a field's value comes from, without saying whether it is writable:
  * `DEFAULTED` and `GENERATED_ON_*` by the data source, `COMPUTED_ON_*` by a
- * framework behavior; `VIRTUAL` marks a field that is not stored.
+ * compute stage; `VIRTUAL` marks a field that is not stored.
  */
 export declare const LIFECYCLE_TRAITS: readonly ["DEFAULTED", "GENERATED_ON_CREATE", "GENERATED_ON_UPDATE", "COMPUTED_ON_CREATE", "COMPUTED_ON_UPDATE", "COMPUTED_ON_READ", "VIRTUAL"];
 /** One of {@link LIFECYCLE_TRAITS}. */
-export type LifecycleTrait = (typeof LIFECYCLE_TRAITS)[number];
+export type AvLifecycleTrait = (typeof LIFECYCLE_TRAITS)[number];

package/dist/contracts/resource-operations.d.ts

@@ -1,62 +1,62 @@
-import type { ProjectionScope, WriteScope } from "./capability.js";
+import type { AvProjectionScope, AvWriteScope } from "./capability.js";
 /**
  * The argument scopes one advertised operation variant qualifies its arguments
  * with: which projection position its projection arguments sit in, and which write
  * position its data argument sits in.
  */
-export type OperationVariantScopes = {
-    readonly projection: ProjectionScope;
-    readonly write?: WriteScope;
+export type AvOperationVariantScopes = {
+    readonly projection: AvProjectionScope;
+    readonly write?: AvWriteScope;
 } | {
-    readonly projection?: ProjectionScope;
-    readonly write: WriteScope;
+    readonly projection?: AvProjectionScope;
+    readonly write: AvWriteScope;
 };
 /**
  * Availability of one standard operation variant: `true` for "available, with no
  * scope qualification stated", or the scopes the variant qualifies its arguments
  * with.
  */
-export type OperationAvailability = true | OperationVariantScopes;
+export type AvOperationAvailability = true | AvOperationVariantScopes;
 /** Availability of protocol-defined standard operations for one Resource. */
-export type ResourceOperations = {
+export type AvResourceOperations = {
     readonly find?: {
-        readonly first?: OperationAvailability;
-        readonly unique?: OperationAvailability;
-        readonly many?: OperationAvailability;
-        readonly count?: OperationAvailability;
+        readonly first?: AvOperationAvailability;
+        readonly unique?: AvOperationAvailability;
+        readonly many?: AvOperationAvailability;
+        readonly count?: AvOperationAvailability;
     };
     readonly create?: {
-        readonly one?: OperationAvailability;
-        readonly many?: OperationAvailability;
-        readonly count?: OperationAvailability;
+        readonly one?: AvOperationAvailability;
+        readonly many?: AvOperationAvailability;
+        readonly count?: AvOperationAvailability;
     };
     readonly update?: {
-        readonly first?: OperationAvailability;
-        readonly unique?: OperationAvailability;
-        readonly many?: OperationAvailability;
-        readonly count?: OperationAvailability;
+        readonly first?: AvOperationAvailability;
+        readonly unique?: AvOperationAvailability;
+        readonly many?: AvOperationAvailability;
+        readonly count?: AvOperationAvailability;
     };
     readonly delete?: {
-        readonly first?: OperationAvailability;
-        readonly unique?: OperationAvailability;
-        readonly many?: OperationAvailability;
-        readonly count?: OperationAvailability;
+        readonly first?: AvOperationAvailability;
+        readonly unique?: AvOperationAvailability;
+        readonly many?: AvOperationAvailability;
+        readonly count?: AvOperationAvailability;
     };
     readonly upsert?: {
-        readonly unique?: OperationAvailability;
+        readonly unique?: AvOperationAvailability;
     };
 };
 /**
- * Whether one `ResourceOperations` entry marks its variant available: it is
+ * Whether one `AvResourceOperations` entry marks its variant available: it is
  * `true` or an argument-position descriptor.
  */
-export declare function isOperationVariantAvailable(availability: unknown): availability is OperationAvailability;
+export declare function isOperationVariantAvailable(availability: unknown): availability is AvOperationAvailability;
 /**
  * The projection position one advertised variant's projection arguments sit in.
  */
-export declare function projectionScopeOf(availability: unknown): ProjectionScope;
+export declare function projectionScopeOf(availability: unknown): AvProjectionScope;
 /**
  * The write position one advertised variant's data argument sits in, and the write
  * mirror of {@link projectionScopeOf}.
  */
-export declare function writeScopeOf(availability: unknown): WriteScope;
+export declare function writeScopeOf(availability: unknown): AvWriteScope;

package/dist/contracts/resource.d.ts

@@ -1,12 +1,18 @@
-import type { Contract } from "./contract.js";
-import type { Field } from "./field.js";
-import type { Identifier } from "./identifier.js";
-import type { ResourceOperations } from "./resource-operations.js";
+import type { AvContract } from "./contract.js";
+import type { AvCreateRequirements } from "./create-requirements.js";
+import type { AvField } from "./field.js";
+import type { AvIdentifier } from "./identifier.js";
+import type { AvResourceOperations } from "./resource-operations.js";
 /** A Resource's fields, by name. */
-export type ResourceFieldMap<C extends Contract> = Readonly<Record<string, Field<C>>>;
-/** One Resource: its fields, identifiers and available operations. */
-export type Resource<C extends Contract, TFields extends ResourceFieldMap<C> = ResourceFieldMap<C>> = {
+export type AvResourceFieldMap<C extends AvContract> = Readonly<Record<string, AvField<C>>>;
+/**
+ * One Resource: its fields, identifiers and available operations, and what a
+ * create of it cannot do without.
+ */
+export type AvResource<C extends AvContract, TFields extends AvResourceFieldMap<C> = AvResourceFieldMap<C>> = {
     readonly fields: TFields;
-    readonly identifiers: readonly Identifier<TFields>[];
-    readonly operations: ResourceOperations;
+    readonly identifiers: readonly AvIdentifier<TFields>[];
+    readonly operations: AvResourceOperations;
+    /** What a create must write; absent when it requires nothing. */
+    readonly createRequirements?: AvCreateRequirements;
 };

package/dist/contracts/scalar-value-type.d.ts

@@ -1,42 +1,42 @@
-import type { Decimal } from "../runtime/decimal.js";
-import type { JsonValue } from "../runtime/json-value.js";
-import type { Contract } from "./contract.js";
-import type { ScalarField } from "./field.js";
+import type { AvDecimal } from "../runtime/decimal.js";
+import type { AvJsonValue } from "../runtime/json-value.js";
+import type { AvContract } from "./contract.js";
+import type { AvScalarField } from "./field.js";
 import type { JsonFieldType } from "./json-shape.js";
-import type { BuiltInScalar } from "./scalar.js";
+import type { AvBuiltInScalar } from "./scalar.js";
 /**
  * A scalar-form map: the TypeScript type each built-in scalar takes on one side
  * of a boundary. Every built-in must be listed.
  */
 export type ScalarForms = {
-    readonly [Scalar in BuiltInScalar]: unknown;
+    readonly [Scalar in AvBuiltInScalar]: unknown;
 };
 /**
  * The TypeScript form each built-in scalar takes in process: in results of
  * either origin, and in `framework.application` arguments. `decimal` is
- * Aventara's own {@link Decimal}.
+ * Aventara's own {@link AvDecimal}.
  */
-export type ApplicationScalarForms = {
+export type AvApplicationScalarForms = {
     readonly string: string;
     readonly boolean: boolean;
     readonly int: number;
     readonly float: number;
     readonly bigint: bigint;
-    readonly decimal: Decimal;
+    readonly decimal: AvDecimal;
     readonly datetime: Date;
     readonly bytes: Uint8Array;
     /**
      * Any JSON value. A field-level `null` is the field's absence and is allowed
      * only where the field is nullable; a `null` inside the value is JSON's own.
      */
-    readonly json: Exclude<JsonValue, null>;
+    readonly json: Exclude<AvJsonValue, null>;
 };
 /**
  * The encoded forms of the built-in scalars: base-10 bigint strings, decimal strings,
  * canonical ISO-8601 UTC datetimes and RFC 4648 base64 bytes. For a transport or a
  * generated client to pass as `Forms`.
  */
-export type WireScalarForms = {
+export type AvWireScalarForms = {
     readonly string: string;
     readonly boolean: boolean;
     readonly int: number;
@@ -46,10 +46,10 @@ export type WireScalarForms = {
     readonly datetime: string;
     readonly bytes: string;
     /** The same as in process: a JSON value needs no encoding to cross a JSON wire. */
-    readonly json: Exclude<JsonValue, null>;
+    readonly json: Exclude<AvJsonValue, null>;
 };
 /** One value of a scalar field, before `list` and `nullable` apply. */
-export type ScalarAtom<C extends Contract, Type, Forms extends ScalarForms> = Type extends {
+export type ScalarAtom<C extends AvContract, Type, Forms extends ScalarForms> = Type extends {
     readonly enum: infer Enum extends keyof C["enums"];
 } ? C["enums"][Enum]["values"][number] : Type extends {
     readonly scalar: infer Scalar;
@@ -58,7 +58,7 @@ export type ScalarAtom<C extends Contract, Type, Forms extends ScalarForms> = Ty
  * One value of a scalar field, before `list` and `nullable` apply: its Json
  * Shape's type where the field is shaped, otherwise {@link ScalarAtom}.
  */
-export type FieldAtom<C extends Contract, Field extends {
+export type FieldAtom<C extends AvContract, Field extends {
     readonly type: unknown;
     readonly json?: unknown;
 }, Forms extends ScalarForms> = Field extends {
@@ -78,5 +78,7 @@ type ListValue<List, Atom> = [List] extends [false] ? Atom : [List] extends [tru
  * - `list: true` → `readonly T[]`, whose entries are never `null`;
  * - `nullable: true` → `| null`, on the whole value, list or not.
  */
-export type ScalarValueType<C extends Contract, Field extends ScalarField<C>, Forms extends ScalarForms = ApplicationScalarForms> = ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never);
+export type AvScalarValueType<C extends AvContract, Field extends AvScalarField<C>, Forms extends ScalarForms = AvApplicationScalarForms> = [
+    ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never)
+] extends [infer Value] ? Value : never;
 export {};

package/dist/contracts/scalar.d.ts

@@ -1,10 +1,10 @@
 /** The built-in scalar types of the Aventara protocol. */
 export declare const BUILT_IN_SCALARS: readonly ["string", "boolean", "int", "float", "bigint", "decimal", "datetime", "bytes", "json"];
 /** One of {@link BUILT_IN_SCALARS}. */
-export type BuiltInScalar = (typeof BUILT_IN_SCALARS)[number];
+export type AvBuiltInScalar = (typeof BUILT_IN_SCALARS)[number];
 /** One entry of a scalar registry. */
-export type ScalarDefinition = {
+export type AvScalarDefinition = {
     readonly builtin: true;
 };
 /** The scalar types an adapter model or Contract supports, by name. */
-export type ScalarRegistry = Readonly<Record<string, ScalarDefinition>>;
+export type AvScalarRegistry = Readonly<Record<string, AvScalarDefinition>>;

package/dist/contracts/transaction-capability.d.ts

@@ -1,4 +1,4 @@
 /** The transaction capabilities. */
 export declare const TRANSACTION_CAPABILITIES: readonly ["none", "interactive"];
 /** `"none"` or `"interactive"`: whether transactions can run. */
-export type TransactionCapability = (typeof TRANSACTION_CAPABILITIES)[number];
+export type AvTransactionCapability = (typeof TRANSACTION_CAPABILITIES)[number];

package/dist/contracts/wire-scalar-format.d.ts

@@ -1,5 +1,5 @@
-import type { BuiltInScalar } from "./scalar.js";
-import type { ApplicationScalarForms, WireScalarForms } from "./scalar-value-type.js";
+import type { AvBuiltInScalar } from "./scalar.js";
+import type { AvApplicationScalarForms, AvWireScalarForms } from "./scalar-value-type.js";
 /**
  * The built-in scalars whose wire form is not their runtime form — the ones a JSON
  * wire carries as a string with a grammar of its own. Derived from the two form maps
@@ -7,8 +7,8 @@ import type { ApplicationScalarForms, WireScalarForms } from "./scalar-value-typ
  * compile below until its grammar is written.
  */
 type WireEncodedScalar = {
-    readonly [S in BuiltInScalar]: WireScalarForms[S] extends ApplicationScalarForms[S] ? never : S;
-}[BuiltInScalar];
+    readonly [S in AvBuiltInScalar]: AvWireScalarForms[S] extends AvApplicationScalarForms[S] ? never : S;
+}[AvBuiltInScalar];
 /**
  * `AvProtocol.scalarFormats` — the wire grammars of protocol version 1, as passive
  * data: one anchored pattern SOURCE string per wire-encoded scalar, in

package/dist/framework/access-facade.d.ts

@@ -0,0 +1,116 @@
+import type { AvContract } from "../contracts/contract.js";
+import type { AvApplicationScalarForms } from "../contracts/scalar-value-type.js";
+import type { AvResourceKey, AvUniqueWhereInput } from "../operations/operation-arguments.js";
+import type { AvAccessProvider } from "../policy/access-provider.interface.js";
+import type { AvAccessQuestion } from "../policy/access-question.js";
+import type { AccessQuestionsAnswerer } from "../policy/access-question.runtime.js";
+import type { AvAccessVerbs } from "../policy/access-verbs.js";
+import type { AvState } from "../runtime/request-state.js";
+/** The questions a client of `C` may ask: one per Resource, with its own unique `where` in the application forms. */
+export type AccessQuestionOf<C extends AvContract> = C extends AvContract ? {
+    readonly [R in AvResourceKey<C>]: AvAccessQuestion<R, AvUniqueWhereInput<C, R, AvApplicationScalarForms>>;
+}[AvResourceKey<C>] : never;
+/** The headers a server-side `$access` call hands Access: a Web `Headers`, or a Node request's `headers`. */
+type AccessHeadersInput = {
+    get(name: string): string | null;
+    has(name: string): boolean;
+    forEach(callback: (value: string, name: string) => void): void;
+} | {
+    readonly [name: string]: string | readonly string[] | undefined;
+};
+/** A server-side `$access` call's options. */
+type ServerAccessOptions = {
+    /** As `AvExecutionOptions.requestId`: `can`'s request id. */
+    readonly requestId?: string;
+    /**
+     * As `AvExecutionOptions.state`: the state `can` is answered under. Left out,
+     * `can` is answered under the state the provider seeds from `headers`, or
+     * anonymously without them.
+     */
+    readonly state?: AvState & object;
+    /**
+     * The request's headers, which Access reads the session from: a Web
+     * `Headers`, or a Node request's `headers` (`req.headers`). Omitted, none.
+     */
+    readonly headers?: AccessHeadersInput;
+    /** The host's own request, handed to Access as `state` is. */
+    readonly request?: unknown;
+    /**
+     * The host's own response (Express's `res`, Fastify's `reply`): Access sets
+     * a sign-in's or sign-out's cookie on it. Under Next, a Server Action needs
+     * none: Access sets it through Next's `cookies()`.
+     */
+    readonly response?: unknown;
+};
+/** What a verb's `call` resolves, `null` and `undefined` taken out. */
+type CallResult<Verb> = Verb extends {
+    call(input: never): Promise<infer Result>;
+} ? Exclude<Result, null | undefined> : unknown;
+/** The `args` a verb's `call` reads. */
+type CallArgs<Verb> = Verb extends {
+    call(input: infer Input): Promise<unknown>;
+} ? Input extends {
+    readonly args: infer Args;
+} ? Args : unknown : unknown;
+/** The provider's `client`, when its type states one. */
+type ClientOf<A> = A extends {
+    readonly client: infer Client;
+} ? Exclude<Client, undefined> : never;
+/** The verbs a provider's `verbs` type states as present (an optional one is no verb). */
+type PresentVerbs<Verbs> = {
+    [V in keyof Verbs]-?: undefined extends Verbs[V] ? never : V;
+}[keyof Verbs] & ProviderVerbName;
+/** The verbs a provider's `client` may state. */
+type ProviderVerbName = keyof NonNullable<AvAccessProvider["client"]>["verbs"];
+/** `$access` of a client of `C` whose provider is `A`: `can`, and the verbs its `client` offers. */
+type ServerAccess<C extends AvContract, A> = [ClientOf<A>] extends [never] ? Pick<AvAccessVerbs<AccessQuestionOf<C>, never, {
+    signIn: never;
+    signUp: never;
+    resetPassword: never;
+    switchUser: never;
+    setPin: never;
+    enrollDevice: never;
+    revokeDevice: never;
+}, ServerAccessOptions>, "can"> : ClientOf<A> extends {
+    readonly verbs: infer Verbs;
+} ? Pick<AvAccessVerbs<AccessQuestionOf<C>, CallResult<VerbOf<Verbs, "me">>, {
+    signIn: CallArgs<VerbOf<Verbs, "signIn">>;
+    signUp: CallArgs<VerbOf<Verbs, "signUp">>;
+    resetPassword: CallArgs<VerbOf<Verbs, "resetPassword">>;
+    switchUser: CallArgs<VerbOf<Verbs, "switchUser">>;
+    setPin: CallArgs<VerbOf<Verbs, "setPin">>;
+    enrollDevice: CallArgs<VerbOf<Verbs, "enrollDevice">>;
+    revokeDevice: CallArgs<VerbOf<Verbs, "revokeDevice">>;
+}, ServerAccessOptions>, "can" | PresentVerbs<Verbs>> : never;
+/** One verb of a provider's `verbs` type, or `never` when it states none. */
+type VerbOf<Verbs, V extends string> = V extends keyof Verbs ? Exclude<Verbs[V], undefined> : never;
+/** The configuration's `access` provider; `undefined` without one. */
+export type AccessProviderOf<Cfg> = Cfg extends {
+    readonly access: infer A extends AvAccessProvider;
+} ? A : undefined;
+/**
+ * `framework.serverClient`'s `$access` member over the Client Contract's view
+ * `C`: `{ $access }` with `access`, nothing (`unknown`) without it.
+ */
+export type ServerClientAccess<C, A> = [A] extends [undefined] ? unknown : C extends AvContract ? {
+    /**
+     * The policy's answers for the UI (`can`) and, when the provider
+     * states its `client`, the Aventara Access verbs, each run in
+     * process with the headers the call names.
+     */
+    readonly $access: ServerAccess<C, A>;
+} : unknown;
+/** What `$access` reads off the Framework. */
+type ServerClientAccessDependencies = {
+    /** The Client Contract, whose unique `where`s a question's is encoded by. */
+    readonly contract: AvContract;
+    /** The `can` route's answerer. */
+    readonly answer: AccessQuestionsAnswerer;
+    /** The provider's `client`, when it has one. */
+    readonly client: AvAccessProvider["client"];
+    /** The provider's `state`, called on the provider: `can`'s state from a call's `headers`. */
+    readonly state: AvAccessProvider["state"];
+};
+/** A server-side `$access`, as `serverClient` carries it. */
+export declare function createServerClientAccess(dependencies: ServerClientAccessDependencies): object;
+export {};

package/dist/framework/access-facade.js

@@ -0,0 +1,120 @@
+import { projectJsonValue } from "../contracts/json-schema.projector.js";
+import { ACCESS_VERB_NAMES, ACCESS_VERBS, providerVerb, } from "../policy/access-verb.table.js";
+import { copyAtDoor } from "../runtime/caller-data.door.js";
+import { requestIdOf } from "../runtime/request-id.js";
+import { stateOptionOf } from "../runtime/request-state.resolver.js";
+import { encodeOperationArgumentsForWire } from "../transactions/operation-arguments-encoder.js";
+import { settleOperation } from "./operation-facade.js";
+export function createServerClientAccess(dependencies) {
+    const { contract, answer, client } = dependencies;
+    const stateFor = async (options) => {
+        if (options?.state !== undefined || options?.headers === undefined) {
+            return stateOf(options);
+        }
+        return {
+            state: await dependencies.state({
+                headers: requestHeadersOf(options.headers),
+                ...(options.request === undefined ? {} : { request: options.request }),
+            }),
+        };
+    };
+    const can = async (questions, options) => settleOperation(await answer({
+        origin: "client",
+        requestId: requestIdOf(options),
+        ...(await stateFor(options)),
+        body: wireQuestions(contract, questions),
+    }));
+    if (client === undefined) {
+        return Object.freeze({ can });
+    }
+    const verbs = { can };
+    for (const name of ACCESS_VERB_NAMES) {
+        const verb = providerVerb(client.verbs, name);
+        if (verb !== undefined) {
+            verbs[name] = serverVerb(verb, ACCESS_VERBS[name]);
+        }
+    }
+    return Object.freeze(verbs);
+}
+function serverVerb(verb, shape) {
+    const run = async (args, options) => {
+        const answer = await verb.call({
+            args,
+            headers: requestHeadersOf(options?.headers),
+            ...(options?.request === undefined ? {} : { request: options.request }),
+            ...(options?.response === undefined
+                ? {}
+                : { response: options.response }),
+        });
+        switch (shape.resolves) {
+            case "nothing":
+                return undefined;
+            default:
+                return answer === null || answer === undefined
+                    ? null
+                    : projectJsonValue(answer, verb.result);
+        }
+    };
+    return shape.args
+        ? (args, options) => run(args, options)
+        : (options) => run(undefined, options);
+}
+function stateOf(options) {
+    const state = stateOptionOf(options);
+    return state === undefined ? {} : { state };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function wireQuestions(contract, questions) {
+    const copy = copyAtDoor({ questions });
+    if (!copy.ok) {
+        return { questions };
+    }
+    const body = copy.value;
+    if (!Array.isArray(body.questions)) {
+        return body;
+    }
+    return {
+        questions: body.questions.map((question) => {
+            if (!isRecord(question) ||
+                !Object.hasOwn(question, "where") ||
+                typeof question.resource !== "string" ||
+                !Object.hasOwn(contract.resources, question.resource)) {
+                return question;
+            }
+            const encoded = encodeOperationArgumentsForWire(contract, { family: "find", variant: "unique", resource: question.resource }, { where: question.where });
+            return { ...question, where: encoded.where };
+        }),
+    };
+}
+function requestHeadersOf(headers) {
+    if (headers !== undefined &&
+        typeof headers.get === "function") {
+        return headers;
+    }
+    const lowered = new Map();
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        const values = typeof value === "string"
+            ? [value]
+            : Array.isArray(value)
+                ? value
+                : [];
+        if (values.length > 0) {
+            const key = name.toLowerCase();
+            const before = lowered.get(key);
+            lowered.set(key, before === undefined
+                ? values.join(", ")
+                : `${before}, ${values.join(", ")}`);
+        }
+    }
+    return Object.freeze({
+        get: (name) => lowered.get(name.toLowerCase()) ?? null,
+        has: (name) => lowered.has(name.toLowerCase()),
+        forEach: (callback) => {
+            for (const [name, value] of lowered) {
+                callback(value, name);
+            }
+        },
+    });
+}