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

package/dist/config/tsconfig.locator.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { createFilesMatcher, getTsconfig, parseTsconfig, } from "get-tsconfig";
-import { ClientConfigError } from "./config.resolver.js";
+import { AvClientConfigError } from "./config.resolver.js";
 export function locateTsconfig(location) {
     if (location.tsconfigFile !== undefined) {
         return namedTsconfig(location.tsconfigFile);
@@ -11,18 +11,30 @@ export function locateTsconfig(location) {
         return undefined;
     }
     if (found.config.references === undefined ||
-        createFilesMatcher(found)(location.entryFile) !== undefined) {
+        includesEntry(found, location.entryFile)) {
         return found;
     }
     for (const reference of found.config.references) {
         const referenced = referencedTsconfig(found.path, reference.path);
         if (referenced !== undefined &&
-            createFilesMatcher(referenced)(location.entryFile) !== undefined) {
+            includesEntry(referenced, location.entryFile)) {
             return referenced;
         }
     }
     return found;
 }
+function includesEntry(tsconfig, file) {
+    const directory = path.dirname(tsconfig.path);
+    const local = (entries) => entries.map((entry) => path.isAbsolute(entry) ? path.relative(directory, entry) || "." : entry);
+    const { files, include, exclude } = tsconfig.config;
+    const config = {
+        ...tsconfig.config,
+        ...(files === undefined ? {} : { files: local(files) }),
+        ...(include === undefined ? {} : { include: local(include) }),
+        ...(exclude === undefined ? {} : { exclude: local(exclude) }),
+    };
+    return (createFilesMatcher({ path: tsconfig.path, config })(file) !== undefined);
+}
 function namedTsconfig(file) {
     try {
         readFileSync(file, "utf8");
@@ -34,7 +46,7 @@ function namedTsconfig(file) {
             : error instanceof Error
                 ? error.message
                 : String(error);
-        throw new ClientConfigError(`tsconfigFile names ${file}, which could not be read (${reason}); it must name the tsconfig.json your project compiles the generated client with.`);
+        throw new AvClientConfigError(`tsconfigFile names ${file}, which could not be read (${reason}); it must name the tsconfig.json your project compiles the generated client with.`);
     }
 }
 function referencedTsconfig(from, reference) {

package/dist/contract/contract.acceptance.d.ts

@@ -1,9 +1,8 @@
-import type { ClientContract } from "@aventara/core";
-export declare const SUPPORTED_PROTOCOL_VERSIONS: ReadonlySet<number>;
+import type { AvContractClient } from "@aventara/core";
 export type ContractRejectionReason = "protocol-unsupported" | "hash-mismatch" | "structure-invalid";
 export type ContractAccepted = {
     readonly accepted: true;
-    readonly contract: ClientContract;
+    readonly contract: AvContractClient;
 };
 export type ContractRejected = {
     readonly accepted: false;
@@ -16,8 +15,8 @@ export type ContractRejected = {
 export type ContractAcceptance = ContractAccepted | ContractRejected;
 export declare function acceptClientContract(body: unknown): Promise<ContractAcceptance>;
 /** The refusal that stops generation, carrying the rejection's reason and sentence. */
-export declare class ContractProtocolError extends Error {
-    readonly name = "ContractProtocolError";
+export declare class AvContractProtocolError extends Error {
+    readonly name = "AvContractProtocolError";
     readonly reason: ContractRejectionReason;
     readonly exitCode: number;
     constructor(rejection: ContractRejected, contractUrl: string);

package/dist/contract/contract.acceptance.js

@@ -1,5 +1,5 @@
-import { AVENTARA_PROTOCOL_VERSION, CanonicalJsonError, computeClientContractHash, validateClientContractStructure, } from "@aventara/core/internal";
-export const SUPPORTED_PROTOCOL_VERSIONS = new Set([
+import { AVENTARA_PROTOCOL_VERSION, AvCanonicalJsonError, computeClientContractHash, validateClientContractStructure, } from "@aventara/core/internal";
+const SUPPORTED_PROTOCOL_VERSIONS = new Set([
     AVENTARA_PROTOCOL_VERSION,
 ]);
 const REFUSED_EXIT_CODE = 1;
@@ -22,7 +22,7 @@ export async function acceptClientContract(body) {
         recomputed = await computeClientContractHash(contract);
     }
     catch (error) {
-        if (!(error instanceof CanonicalJsonError)) {
+        if (!(error instanceof AvCanonicalJsonError)) {
             throw error;
         }
         return reject("hash-mismatch", `it holds a value canonical JSON cannot represent (${error.message}), so its ` +
@@ -36,8 +36,8 @@ export async function acceptClientContract(body) {
     }
     return { accepted: true, contract };
 }
-export class ContractProtocolError extends Error {
-    name = "ContractProtocolError";
+export class AvContractProtocolError extends Error {
+    name = "AvContractProtocolError";
     reason;
     exitCode;
     constructor(rejection, contractUrl) {

package/dist/contract/contract.fetcher.d.ts

@@ -7,7 +7,7 @@ export type ContractFetch = (url: URL, init: {
     readonly headers?: Readonly<Record<string, string>>;
 }) => Promise<ContractResponse>;
 export declare const CONTRACT_NOT_MODIFIED: unique symbol;
-export type ContractTransportFailureReason = 
+type ContractTransportFailureReason = 
 /** No response at all: DNS, refused connection, TLS, abort. */
 "request-failed"
 /** A response that is not 2xx — nothing was served for the protocol to judge. */
@@ -16,15 +16,16 @@ export type ContractTransportFailureReason =
  | "body-unreadable"
 /** A body that is not JSON — an HTML page, an empty body, a truncation. */
  | "body-not-json";
-export declare class ContractTransportError extends Error {
+export declare class AvContractTransportError extends Error {
     readonly reason: ContractTransportFailureReason;
-    readonly name = "ContractTransportError";
+    readonly name = "AvContractTransportError";
     constructor(reason: ContractTransportFailureReason, message: string, options?: ErrorOptions);
 }
 export declare function contractUrlOf(entrypoint: ClientEntrypoint): URL;
 /** The URL as it may be printed: credentials in the entrypoint never are. */
 export declare function displayUrl(url: URL): string;
 /**
- * @throws ContractTransportError when no JSON value arrives.
+ * @throws AvContractTransportError when no JSON value arrives.
  */
 export declare function fetchClientContractBody(entrypoint: ClientEntrypoint, fetch?: ContractFetch, ifNoneMatch?: string): Promise<unknown>;
+export {};

package/dist/contract/contract.fetcher.js

@@ -1,7 +1,7 @@
 export const CONTRACT_NOT_MODIFIED = Symbol("aventara.contract-not-modified");
-export class ContractTransportError extends Error {
+export class AvContractTransportError extends Error {
     reason;
-    name = "ContractTransportError";
+    name = "AvContractTransportError";
     constructor(reason, message, options) {
         super(message, options);
         this.reason = reason;
@@ -29,26 +29,26 @@ export async function fetchClientContractBody(entrypoint, fetch = globalThis.fet
             : { method: "GET", headers: { "If-None-Match": ifNoneMatch } });
     }
     catch (error) {
-        throw new ContractTransportError("request-failed", `Could not fetch the ClientContract from ${shown}: ${describeCause(error)}. ${remedy}`, { cause: error });
+        throw new AvContractTransportError("request-failed", `Could not fetch the ClientContract from ${shown}: ${describeCause(error)}. ${remedy}`, { cause: error });
     }
     if (response.status === 304 && ifNoneMatch !== undefined) {
         return CONTRACT_NOT_MODIFIED;
     }
     if (!response.ok) {
-        throw new ContractTransportError("http-status", `GET ${shown} answered HTTP ${response.status}, not the ClientContract. ${remedy}`);
+        throw new AvContractTransportError("http-status", `GET ${shown} answered HTTP ${response.status}, not the ClientContract. ${remedy}`);
     }
     let text;
     try {
         text = await response.text();
     }
     catch (error) {
-        throw new ContractTransportError("body-unreadable", `The response from ${shown} could not be read: ${describeCause(error)}. ${remedy}`, { cause: error });
+        throw new AvContractTransportError("body-unreadable", `The response from ${shown} could not be read: ${describeCause(error)}. ${remedy}`, { cause: error });
     }
     try {
         return JSON.parse(text);
     }
     catch (error) {
-        throw new ContractTransportError("body-not-json", `The response from ${shown} is not JSON, so it is not a ClientContract. ${remedy}`, { cause: error });
+        throw new AvContractTransportError("body-not-json", `The response from ${shown} is not JSON, so it is not a ClientContract. ${remedy}`, { cause: error });
     }
 }
 function describeCause(error) {

package/dist/contract/contract.loader.d.ts

@@ -1,17 +1,17 @@
-import type { ClientContract } from "@aventara/core";
+import type { AvContractClient } from "@aventara/core";
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
 import { type ContractFetch } from "./contract.fetcher.js";
-export interface ClientContractLoadInput {
+interface ClientContractLoadInput {
     readonly entrypoint: ClientEntrypoint;
     readonly fetch?: ContractFetch;
 }
 /**
- * @throws ContractTransportError when no JSON value arrives.
- * @throws ContractProtocolError when what arrived is refused.
+ * @throws AvContractTransportError when no JSON value arrives.
+ * @throws AvContractProtocolError when what arrived is refused.
  */
-export declare function loadClientContract(input: ClientContractLoadInput): Promise<ClientContract>;
-export interface ClientContractSince {
-    readonly contract: ClientContract;
+export declare function loadClientContract(input: ClientContractLoadInput): Promise<AvContractClient>;
+interface ClientContractSince {
+    readonly contract: AvContractClient;
     /** The deployment answered `304`: `contract` is the one the caller held. */
     readonly notModified: boolean;
 }
@@ -21,4 +21,5 @@ export interface ClientContractSince {
  * `If-None-Match: "<its hash>"`, and a `304` answers with `stored` itself. Without
  * `stored` the GET is unconditional.
  */
-export declare function loadClientContractSince(input: ClientContractLoadInput, stored: ClientContract | undefined): Promise<ClientContractSince>;
+export declare function loadClientContractSince(input: ClientContractLoadInput, stored: AvContractClient | undefined): Promise<ClientContractSince>;
+export {};

package/dist/contract/contract.loader.js

@@ -1,4 +1,4 @@
-import { acceptClientContract, ContractProtocolError, } from "./contract.acceptance.js";
+import { AvContractProtocolError, acceptClientContract, } from "./contract.acceptance.js";
 import { CONTRACT_NOT_MODIFIED, contractUrlOf, displayUrl, fetchClientContractBody, } from "./contract.fetcher.js";
 export async function loadClientContract(input) {
     return accepted(await fetchClientContractBody(input.entrypoint, input.fetch), input);
@@ -16,7 +16,7 @@ export async function loadClientContractSince(input, stored) {
 async function accepted(body, input) {
     const acceptance = await acceptClientContract(body);
     if (!acceptance.accepted) {
-        throw new ContractProtocolError(acceptance, displayUrl(contractUrlOf(input.entrypoint)));
+        throw new AvContractProtocolError(acceptance, displayUrl(contractUrlOf(input.entrypoint)));
     }
     return acceptance.contract;
 }

package/dist/emit/access.emitter.d.ts

@@ -0,0 +1,12 @@
+import type { AvContractClient } from "@aventara/core";
+import { ACCESS_VERB_NAMES, ACCESS_VERBS } from "@aventara/core/internal";
+import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.interface.js";
+/** One verb `$access` offers beside `can`. */
+export type AccessVerbName = (typeof ACCESS_VERB_NAMES)[number];
+/** Whether a verb takes arguments, and what it resolves (core's verb table). */
+export declare function accessVerbShape(name: AccessVerbName): (typeof ACCESS_VERBS)[AccessVerbName];
+/** The verbs the section states, in `$access`'s order; none without `verbs`. */
+export declare function accessVerbsOf(contract: AvContractClient): readonly AccessVerbName[];
+/** `runtime/access.ts`, or nothing when the section states no verb. */
+export declare function emitAccessModules(contract: AvContractClient, style: ClientModuleStyle): readonly EmittedModule[];

package/dist/emit/access.emitter.js

@@ -0,0 +1,263 @@
+import { ACCESS_VERB_NAMES, ACCESS_VERBS } from "@aventara/core/internal";
+import { importSpecifier, } from "./module-style.interface.js";
+export function accessVerbShape(name) {
+    return ACCESS_VERBS[name];
+}
+export function accessVerbsOf(contract) {
+    const verbs = contract.access?.verbs;
+    return verbs === undefined
+        ? []
+        : ACCESS_VERB_NAMES.filter((name) => verbs[name] !== undefined);
+}
+export function emitAccessModules(contract, style) {
+    const verbs = contract.access?.verbs;
+    const names = accessVerbsOf(contract);
+    if (verbs === undefined || names.length === 0) {
+        return [];
+    }
+    const from = (module) => JSON.stringify(importSpecifier(module, style));
+    const table = names
+        .map((name) => {
+        const verb = verbs[name];
+        return `\t${name}: { method: ${JSON.stringify(verb?.method)}, path: ${JSON.stringify(verb?.path)}, result: ${JSON.stringify(verb?.result)} },\n`;
+    })
+        .join("");
+    return [
+        {
+            path: "runtime/access.ts",
+            source: `import { AvTransportError } from ${from("./errors")};
+import type { AvCallOptions, PlatformSignal, TransportConnection } from ${from("./transport")};
+
+/**
+ * Aventara Access's verbs, as this deployment's ClientContract states them:
+ * each one a request to Access's own route, its result projected onto the
+ * schema the ClientContract promises.
+ */
+
+/**
+ * Aventara Access answered a verb with a status that is not 2xx. It carries the
+ * status and Access's own code and message; it is no AvError, because Access's
+ * answers are not framework envelopes.
+ */
+export class AvAccessError extends Error {
+	override readonly name: string = "AvAccessError";
+	/** The HTTP status Access answered. */
+	readonly status: number;
+	/** Access's own error code, or null when its answer named none. */
+	readonly code: string | null;
+
+	constructor(message: string, status: number, code: string | null) {
+		super(message);
+		this.status = status;
+		this.code = code;
+	}
+}
+
+/** Where the app mounted Aventara Access. */
+const ACCESS_URL = ${JSON.stringify(contract.access?.url ?? "")};
+
+/** Each verb this client offers: its route under ACCESS_URL and its result's schema. */
+const VERBS = {
+${table}} as const;
+
+/** One verb this client offers. */
+export type AccessVerb = keyof typeof VERBS;
+
+/** A schema node, as the projection reads it. */
+type Schema = { readonly [key: string]: unknown };
+
+/** What a verb hands fetch. */
+interface AccessInit {
+	readonly method: "GET" | "POST";
+	readonly headers: Readonly<Record<string, string>>;
+	readonly body?: string;
+	readonly cache?: "no-store";
+	readonly signal?: PlatformSignal;
+}
+
+/** What a verb reads of fetch's answer. */
+interface AccessAnswer {
+	readonly status: number;
+	text(): Promise<string>;
+}
+
+/** The URL of a verb's route: a root-relative ACCESS_URL put under an absolute entrypoint's origin. */
+function routeOf(entrypoint: string, path: string): string {
+	const base = ACCESS_URL.replace(/\\/+$/, "");
+	const origin = /^[a-z][a-z0-9+.-]*:\\/\\/[^/?#]*/i.exec(entrypoint)?.[0];
+	return base.startsWith("/") && origin !== undefined ? origin + base + path : base + path;
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * \`schema\` as a member's schema.
+ *
+ * @throws TypeError when it is none (a free-form object or list, a tuple read
+ *   past its length): outside the forms a ClientContract states.
+ */
+function memberSchema(schema: unknown): Schema {
+	if (!isRecord(schema)) {
+		throw new TypeError("the schema is not one of the forms a ClientContract states");
+	}
+	return schema as Schema;
+}
+
+/** Whether \`value\` can be read by \`schema\` at all: its JSON type. */
+function fits(value: unknown, schema: Schema): boolean {
+	if (Object.hasOwn(schema, "const")) {
+		return value === schema["const"];
+	}
+	if (Array.isArray(schema["enum"])) {
+		return schema["enum"].includes(value);
+	}
+	for (const keyword of ["anyOf", "oneOf"]) {
+		const options = schema[keyword];
+		if (Array.isArray(options)) {
+			return options.some((option) => fits(value, option as Schema));
+		}
+	}
+	switch (schema["type"]) {
+		case "null":
+			return value === null;
+		case "boolean":
+			return typeof value === "boolean";
+		case "string":
+			return typeof value === "string";
+		case "number":
+			return typeof value === "number";
+		case "integer":
+			return Number.isInteger(value);
+		case "array":
+			return Array.isArray(value);
+		case "object":
+			return isRecord(value);
+		default:
+			return false;
+	}
+}
+
+/**
+ * \`value\` projected onto \`schema\`: every object down to the members the schema
+ * declares, a list member by member. The schema is the promise.
+ *
+ * @throws TypeError when the value is not one the schema describes.
+ */
+function projected(value: unknown, schema: Schema): unknown {
+	if (!fits(value, schema)) {
+		throw new TypeError("the value is not the one the ClientContract describes");
+	}
+	for (const keyword of ["anyOf", "oneOf"]) {
+		const options = schema[keyword];
+		if (Array.isArray(options)) {
+			const option = options.find((candidate) => fits(value, candidate as Schema)) as Schema;
+			return projected(value, option);
+		}
+	}
+	if (Array.isArray(value)) {
+		const prefix = schema["prefixItems"];
+		const items = Array.isArray(prefix) ? undefined : memberSchema(schema["items"]);
+		return Object.freeze(
+			value.map((member: unknown, index: number) =>
+				projected(member, items ?? memberSchema((prefix as readonly unknown[])[index])),
+			),
+		);
+	}
+	if (isRecord(value)) {
+		const properties = schema["properties"];
+		if (isRecord(properties)) {
+			const copy: Record<string, unknown> = {};
+			for (const [key, member] of Object.entries(properties)) {
+				if (Object.hasOwn(value, key) && value[key] !== undefined) {
+					copy[key] = projected(value[key], member as Schema);
+				}
+			}
+			return Object.freeze(copy);
+		}
+		const values = memberSchema(schema["additionalProperties"]);
+		return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, member]) => [key, projected(member, values)])));
+	}
+	return value;
+}
+
+/** Access's error answer, read for its code and message. */
+function refusalOf(verb: AccessVerb, status: number, text: string): AvAccessError {
+	let body: unknown;
+	try {
+		body = JSON.parse(text);
+	} catch {
+		body = undefined;
+	}
+	const code = isRecord(body) && typeof body["code"] === "string" ? body["code"] : null;
+	const message =
+		isRecord(body) && typeof body["message"] === "string" ? body["message"] : "Aventara Access refused $access." + verb + " (HTTP " + status + ").";
+	return new AvAccessError(message, status, code);
+}
+
+/**
+ * Runs one Access verb: one request to its route, its 2xx answer projected onto
+ * its result schema (\`null\` stays \`null\`: no one is signed in).
+ *
+ * @throws AvAccessError on a non-2xx answer; AvTransportError when no answer
+ *   arrived, or the answer is not the value the ClientContract describes. A
+ *   caller's abort rejects with what fetch rejected with.
+ */
+export async function callAccess(
+	connection: TransportConnection,
+	verb: AccessVerb,
+	args: unknown,
+	options: AvCallOptions = {},
+): Promise<unknown> {
+	const { method, path, result } = VERBS[verb];
+	const operation = "$access." + verb;
+	const headers: Record<string, string> = { ...options.headers };
+	let init: AccessInit;
+	if (method === "GET") {
+		init = { method, headers, cache: "no-store" };
+	} else {
+		headers["Content-Type"] = "application/json";
+		init = { method, headers, body: JSON.stringify(args ?? {}) };
+	}
+	if (options.signal !== undefined) {
+		init = { ...init, signal: options.signal };
+	}
+	const fetch = connection.fetch as unknown as (url: string, init: AccessInit) => Promise<AccessAnswer>;
+	let answer: AccessAnswer;
+	let text: string;
+	try {
+		answer = await fetch(routeOf(connection.entrypoint, path), init);
+		text = await answer.text();
+	} catch (error) {
+		if (options.signal?.aborted === true) {
+			throw error;
+		}
+		throw new AvTransportError("The request for " + operation + " failed before any answer arrived.", null);
+	}
+	if (answer.status < 200 || answer.status > 299) {
+		throw refusalOf(verb, answer.status, text);
+	}
+	let value: unknown;
+	try {
+		value = text.trim() === "" ? null : JSON.parse(text);
+	} catch {
+		throw new AvTransportError("The answer to " + operation + " (HTTP " + answer.status + ") is not JSON.", answer.status);
+	}
+	if (value === null) {
+		return null;
+	}
+	try {
+		return projected(value, result as Schema);
+	} catch (error) {
+		throw new AvTransportError(
+			"The answer to " + operation + " (HTTP " + answer.status + ") holds a value this client cannot read: " +
+				(error instanceof Error ? error.message : String(error)),
+			answer.status,
+		);
+	}
+}
+`,
+        },
+    ];
+}

package/dist/emit/banner.emitter.d.ts

@@ -1,7 +1,12 @@
 export declare const GENERATED_OWNERSHIP_LINE = "/* !!! Generated by @aventara/client. Do not edit. !!! */";
+/** The command a generated file says to regenerate it with: a command in backticks, then any words about it. */
+export type RegenerateCommand = `\`${string}\`${string}`;
+/** `avclient generate`'s own: what its banner and errors say. */
+export declare const AVCLIENT_REGENERATE: RegenerateCommand;
+/** `avclient generate`'s banner. */
 export declare const GENERATED_BANNER: readonly string[];
 /** `source` with the banner before it and one blank line between. */
-export declare function withGeneratedBanner(source: string): string;
+export declare function withGeneratedBanner(source: string, regenerate?: RegenerateCommand): string;
 /**
  * How far into a file the ownership line is looked for. The banner opens every
  * emitted file, so the line sits well inside this; a reader never has to read a

package/dist/emit/banner.emitter.js

@@ -1,12 +1,16 @@
 export const GENERATED_OWNERSHIP_LINE = "/* !!! Generated by @aventara/client. Do not edit. !!! */";
-export const GENERATED_BANNER = [
-    "// biome-ignore-all format: generated output",
-    "// biome-ignore-all lint: generated output",
-    GENERATED_OWNERSHIP_LINE,
-    "/* Regenerate with `avclient generate`. */",
-];
-export function withGeneratedBanner(source) {
-    return `${GENERATED_BANNER.join("\n")}\n\n${source}`;
+export const AVCLIENT_REGENERATE = "`avclient generate`";
+function generatedBanner(regenerate = AVCLIENT_REGENERATE) {
+    return [
+        "// biome-ignore-all format: generated output",
+        "// biome-ignore-all lint: generated output",
+        GENERATED_OWNERSHIP_LINE,
+        `/* Regenerate with ${regenerate}. */`,
+    ];
+}
+export const GENERATED_BANNER = generatedBanner();
+export function withGeneratedBanner(source, regenerate = AVCLIENT_REGENERATE) {
+    return `${generatedBanner(regenerate).join("\n")}\n\n${source}`;
 }
 export const GENERATED_OWNERSHIP_HEAD_BYTES = 1024;
 export function carriesGeneratedOwnership(head) {

package/dist/emit/client-surface.emitter.d.ts

@@ -1,5 +1,5 @@
-import type { ClientContract } from "@aventara/core";
+import type { AvContractClient } from "@aventara/core";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
 import { type EmittedNames } from "./name.deriver.js";
-export declare function emitClientSurfaceModule(contract: ClientContract, names: EmittedNames, style: ClientModuleStyle): EmittedModule;
+export declare function emitClientSurfaceModule(contract: AvContractClient, names: EmittedNames, style: ClientModuleStyle): EmittedModule;