@aventara/client 1.0.0-rc.4 → 1.0.0-rc.9

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @aventara/client
 
+## 1.0.0-rc.9
+
+### Patch Changes
+
+- 99278e4: `aventara-build` reads a Next.js project's files from `src/aventara/` and, with `--client`, writes its browser client.
+
+  - A project whose `package.json` depends on `@aventara/next` keeps its configuration and adapter in
+    `src/aventara/config.ts` and `src/aventara/adapter.ts`; the build runs them there, and a configuration that imports no
+    Resource tree has its generated files in `src/aventara/generated/`. Every other project keeps
+    `src/aventara.config.ts` and `src/aventara.adapter.ts`, unchanged. A missing file is named with where the project's
+    host keeps it, and a project depending on both `@aventara/nest` and `@aventara/next` is refused in one sentence.
+  - `aventara-build --client` also writes the browser client from the ClientContract it has just compiled, with no
+    running server: `src/aventara/client.ts` and the client's modules under `src/aventara/generated/`, the same modules
+    `avclient generate` writes for that ClientContract except that the entrypoint is the app's own `api` on the page's
+    origin (`/api`) and the regenerate instructions. Its imports are spelled as the project's `tsconfig.json` says, and nothing it writes imports
+    `@aventara/client`.
+  - `src/aventara/client.ts` exports `avClient` and `avHydrate`, and re-exports every name `avclient generate`'s
+    `AvClient.ts` exports besides its default (`AvClient`, the Resource types, the enums, `AvDecimal`, the error
+    classes), so `import { AvDecimal } from "@/aventara/client"` works. The generated files and the contract-mismatch
+    error say to regenerate with `aventara-build --client` (the project's `aventara:prepare` script). `avClient` calls the API from the browser; a call made
+    on the server (a Client Component rendering there) rejects with one sentence pointing to `@/aventara/server` and
+    `@/aventara/universal`, and sends nothing. `avHydrate` revives data `avDehydrate` sends from the server: tagged
+    dates, `bigint`s, byte arrays and decimals become `Date`, `bigint`, `Uint8Array` and the client's own `AvDecimal`,
+    for TanStack Query's `deserializeData` or an SWR `fallback`.
+  - `aventara-build --check --client` checks those files too: a missing or stale one, or one an earlier ClientContract's
+    client left, exits 1 naming it. `--client` is refused in a NestJS project, whose frontends keep using
+    `avclient generate`, which is unchanged.
+  - `@aventara/client` gains an `@aventara/client/internal` entry, which `@aventara/build` reads the generator through.
+    It is not public API.
+
+- Updated dependencies [205a379]
+- Updated dependencies [a0bb05e]
+- Updated dependencies [86ab319]
+- Updated dependencies [fdf52e6]
+  - @aventara/core@1.0.0-rc.9
+
+## 1.0.0-rc.8
+
+1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- A generated client's results read as their value types in an editor: `body: string | null`, `published: boolean`,
+  `publishedAt: Date | null`, where a nullable, enum or `boolean` field was shown as `AvScalarValueType<…>` with the
+  client's Contract as its argument, and a result as `ProjectedFields<…>`. Run `avclient generate` again to pick it up.
+  What the client accepts and returns is unchanged.
+- Updated dependencies [1c8e4ee]
+  - @aventara/core@1.0.0-rc.8
+
+## 1.0.0-rc.7
+
+1.0.0-rc.5 and 1.0.0-rc.6 were tagged but never published; 1.0.0-rc.7 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- Updated dependencies [f917c1c]
+  - @aventara/core@1.0.0-rc.7
+
+## 1.0.0-rc.6
+
+1.0.0-rc.5 was tagged but never published. 1.0.0-rc.6 contains everything listed under 1.0.0-rc.5 and the fix below.
+
+### Patch Changes
+
+- Updated dependencies [1cf72e0]
+  - @aventara/core@1.0.0-rc.6
+
+## 1.0.0-rc.5
+
+### Patch Changes
+
+- Updated dependencies [4795ff1]
+- Updated dependencies [9e178ca]
+  - @aventara/core@1.0.0-rc.5
+
 ## 1.0.0-rc.4
 
 ### Patch Changes

package/dist/config/client-config.interface.d.ts

@@ -44,6 +44,14 @@ export interface ClientEntrypoint {
     readonly deployment: URL;
     readonly path: EntrypointPath;
 }
+/** An entrypoint on the page's own origin: its mount path alone, such as `/api`. */
+export interface SameOriginEntrypoint {
+    /** Absent: the deployment is whichever origin served the page. */
+    readonly deployment?: undefined;
+    readonly path: EntrypointPath;
+}
+/** The entrypoint a generated client embeds as its default: a deployment's, or the page's own origin. */
+export type EmittedEntrypoint = ClientEntrypoint | SameOriginEntrypoint;
 export interface ResolvedClientConfig {
     readonly entrypoint: ClientEntrypoint;
     /** `generateAt`, made absolute. */

package/dist/config/config.resolver.d.ts

@@ -1,4 +1,4 @@
-import type { AvClientConfigInput, AvEnvReference, ClientEntrypoint, ResolvedClientConfig } from "./client-config.interface.js";
+import type { AvClientConfigInput, AvEnvReference, ClientEntrypoint, EmittedEntrypoint, ResolvedClientConfig, SameOriginEntrypoint } from "./client-config.interface.js";
 import type { EnvCascadeResolution } from "./env.cascade.js";
 /** Gives a `framework.client.ts` its type: returns `config` unchanged. */
 export declare function defineClientConfig(config: AvClientConfigInput): AvClientConfigInput;
@@ -26,4 +26,10 @@ export declare function resolveClientConfig(input: ClientConfigResolutionInput):
  * @throws AvClientConfigError in one sentence that does not echo the value.
  */
 export declare function resolveEntrypoint(value: string): ClientEntrypoint;
-export declare function entrypointHref(entrypoint: ClientEntrypoint): string;
+/**
+ * The same-origin entrypoint of a framework mounted at `api`.
+ *
+ * @throws AvClientConfigError when `api` is not a mount path.
+ */
+export declare function sameOriginEntrypoint(api: string): SameOriginEntrypoint;
+export declare function entrypointHref(entrypoint: EmittedEntrypoint): string;

package/dist/config/config.resolver.js

@@ -77,7 +77,17 @@ export function resolveEntrypoint(value) {
 function writtenMountPath(value) {
     return value.replace(/^[A-Za-z][A-Za-z0-9+.-]*:[/\\]*[^/\\?#]*/u, "");
 }
+export function sameOriginEntrypoint(api) {
+    const normalized = AvProtocol.normalizeEntrypoint(api);
+    if (!normalized.ok) {
+        throw new AvClientConfigError(`api ${normalized.message}.`);
+    }
+    return { path: normalized.path };
+}
 export function entrypointHref(entrypoint) {
+    if (entrypoint.deployment === undefined) {
+        return entrypoint.path;
+    }
     const url = new URL(entrypoint.deployment.href);
     url.pathname = entrypoint.path === "" ? "/" : entrypoint.path;
     return url.href.replace(/\/$/, "");

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

@@ -1,7 +1,13 @@
 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;
+export declare function generatedBanner(regenerate?: RegenerateCommand): readonly string[];
+/** `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`";
+export 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-tree.emitter.d.ts

@@ -1,8 +1,13 @@
 import type { AvContractClient } from "@aventara/core";
-import type { ClientEntrypoint } from "../config/client-config.interface.js";
+import type { EmittedEntrypoint } from "../config/client-config.interface.js";
+import { type RegenerateCommand } from "./banner.emitter.js";
 import { type ClientEmission } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
 /**
  * @throws AvGeneratedNameError when a name cannot be emitted, even renamed.
  */
-export declare function emitClientTree(contract: AvContractClient, entrypoint: ClientEntrypoint, style: ClientModuleStyle): ClientEmission;
+export declare function emitClientTree(contract: AvContractClient, entrypoint: EmittedEntrypoint, style: ClientModuleStyle, regenerate?: RegenerateCommand): ClientEmission;
+/** How an entry re-exports `AvClient`: the class itself, or its type alone. */
+export type ClientClassExport = "value" | "type";
+/** The entry's re-exports, its default aside, as source: one statement per module. */
+export declare function clientEntryReExports(style: ClientModuleStyle, clientClass?: ClientClassExport): string;

package/dist/emit/client-tree.emitter.js

@@ -1,4 +1,4 @@
-import { withGeneratedBanner } from "./banner.emitter.js";
+import { AVCLIENT_REGENERATE, withGeneratedBanner, } from "./banner.emitter.js";
 import { emitClientSurfaceModule } from "./client-surface.emitter.js";
 import { emitContractCarrierModule } from "./contract-carrier.emitter.js";
 import { emitDerivationModules } from "./derivation.emitter.js";
@@ -12,7 +12,7 @@ import { emitNamedTypesModule } from "./named-type.emitter.js";
 import { emitDecimalModule, emitErrorsModule, emitMetadataModule, emitTransportModule, errorsModuleExports, } from "./runtime.emitter.js";
 import { emitScalarCodecModule } from "./scalar.codec.js";
 import { emitTransactionModules } from "./transaction.emitter.js";
-export function emitClientTree(contract, entrypoint, style) {
+export function emitClientTree(contract, entrypoint, style, regenerate = AVCLIENT_REGENERATE) {
     const names = deriveEmittedNames(contract);
     const derivation = emitDerivationModules();
     const generated = [
@@ -24,7 +24,7 @@ export function emitClientTree(contract, entrypoint, style) {
         emitMetadataModule(contract.protocol, entrypoint),
         emitScalarCodecModule(style),
         emitDecimalModule(),
-        emitErrorsModule(),
+        emitErrorsModule(regenerate),
         emitTransportModule(style),
         emitNamedTypesModule(contract, names, style),
         ...(contract.transactions === "interactive"
@@ -44,15 +44,22 @@ export function emitClientTree(contract, entrypoint, style) {
         .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
         .map((file) => ({
         path: file.path,
-        bytes: encoder.encode(withGeneratedBanner(file.source)),
+        bytes: encoder.encode(withGeneratedBanner(file.source, regenerate)),
     }));
     return { tree, style, warnings: names.warnings };
 }
 function clientEntrySource(style) {
-    const specifier = moduleSpecifierWriter(style);
-    const from = (module) => specifier(`./${GENERATED_DIRECTORY}/${module.replace(/\.d\.ts$|\.ts$/, "")}`);
-    return (`export { default } from ${from("client.ts")};\n` +
-        `export {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype AvCallOptions,\n} from ${from("client.ts")};\n` +
+    return (`export { default } from ${generatedModuleSpecifier(style, "client.ts")};\n` +
+        clientEntryReExports(style));
+}
+function generatedModuleSpecifier(style, module) {
+    return moduleSpecifierWriter(style)(`./${GENERATED_DIRECTORY}/${module.replace(/\.d\.ts$|\.ts$/, "")}`);
+}
+export function clientEntryReExports(style, clientClass = "value") {
+    const from = (module) => generatedModuleSpecifier(style, module);
+    return ((clientClass === "value"
+        ? `export {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype AvCallOptions,\n} from ${from("client.ts")};\n`
+        : `export type { AvClient, AvClientOptions, AvCallOptions } from ${from("client.ts")};\n`) +
         `export type { AvFetch } from ${from("runtime/transport.ts")};\n` +
         `export type { AvOperation } from ${from("derivation/transactions/deferred-operation.d.ts")};\n` +
         `export type * from ${from("types.d.ts")};\n` +

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

@@ -1,10 +1,11 @@
 import type { AvContractClient } from "@aventara/core";
-import type { ClientEntrypoint } from "../config/client-config.interface.js";
+import type { EmittedEntrypoint } from "../config/client-config.interface.js";
+import { type RegenerateCommand } from "./banner.emitter.js";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
 export declare function emitDecimalModule(): EmittedModule;
-export declare function emitMetadataModule(protocol: AvContractClient["protocol"], entrypoint: ClientEntrypoint): EmittedModule;
+export declare function emitMetadataModule(protocol: AvContractClient["protocol"], entrypoint: EmittedEntrypoint): EmittedModule;
 export declare const FRAMEWORK_ERROR_CLASS_NAMES: readonly string[];
 export declare function errorsModuleExports(): readonly string[];
-export declare function emitErrorsModule(): EmittedModule;
+export declare function emitErrorsModule(regenerate?: RegenerateCommand): EmittedModule;
 export declare function emitTransportModule(style: ClientModuleStyle): EmittedModule;

package/dist/emit/runtime.emitter.js

@@ -1,6 +1,7 @@
 import { FRAMEWORK_ERROR_CLASS_OF, OPERATION_CODES, VALIDATION_CODES, } from "@aventara/core/internal";
 import { AvProtocol } from "@aventara/core/protocol";
 import { entrypointHref } from "../config/config.resolver.js";
+import { AVCLIENT_REGENERATE, } from "./banner.emitter.js";
 import { moduleSpecifierWriter, } from "./module-style.interface.js";
 import { wireGrammarLiteral } from "./scalar.codec.js";
 export function emitDecimalModule() {
@@ -51,10 +52,13 @@ export function emitMetadataModule(protocol, entrypoint) {
             `export const DEFAULT_ENTRYPOINT = ${JSON.stringify(entrypointHref(entrypoint))};\n`,
     };
 }
+function contractMismatchSummary(regenerate) {
+    return `This client was generated against a ClientContract other than the one the server serves. Regenerate it with ${regenerate}.`;
+}
 const FRAMEWORK_ERROR_CLASSES = {
     AvAuthError: "The caller is not authenticated, or is not permitted to run the operation.",
     AvConflictError: "The operation conflicted with stored state, and nothing was written. A2008 fails the same way if sent again; A2013 and A2014 may succeed if sent again, and no retry is automatic.",
-    AvContractMismatchError: "This client was generated against a ClientContract other than the one the server serves. Regenerate it with `avclient generate`.",
+    AvContractMismatchError: contractMismatchSummary(AVCLIENT_REGENERATE),
     AvInternalError: "The server failed. Nothing in its cause is actionable; the diagnostics are in the server's logs.",
     AvNotFoundError: "A strict unique target does not exist.",
     AvProtocolError: "The request was not one the server could route or interpret: an unknown Resource or operation, a protocol version it does not speak, or a body, media type, size or method it refuses.",
@@ -152,8 +156,12 @@ export class AvTransportError extends Error {
 	}
 }
 `;
-export function emitErrorsModule() {
-    const classes = Object.entries(FRAMEWORK_ERROR_CLASSES).map(([name, summary]) => {
+export function emitErrorsModule(regenerate = AVCLIENT_REGENERATE) {
+    const summaries = {
+        ...FRAMEWORK_ERROR_CLASSES,
+        AvContractMismatchError: contractMismatchSummary(regenerate),
+    };
+    const classes = Object.entries(summaries).map(([name, summary]) => {
         const codes = ERROR_CODES.filter((code) => FRAMEWORK_ERROR_CLASS_OF[code] === name);
         return (`\n/** ${summary} Thrown for ${codes.join(", ")}. */\n` +
             `export class ${name} extends AvError<${codes.map((code) => JSON.stringify(code)).join(" | ")}> {\n` +

package/dist/hydration/hydration-tag.format.d.ts

@@ -0,0 +1,11 @@
+/** The tagged form a dehydrated value takes: `{ [tagKey]: <tag>, [valueKey]: <wire form> }`. */
+export declare const HYDRATION_FORMAT: {
+    /** The key a tag is under. */
+    readonly tagKey: "$av";
+    /** The key the tagged value's wire form is under. */
+    readonly valueKey: "v";
+    /** The tag of a plain object that holds `tagKey` as data. */
+    readonly objectTag: "object";
+    /** The scalars a value is tagged as: those whose runtime values JSON does not carry. */
+    readonly scalarTags: readonly ["bigint", "bytes", "datetime", "decimal"];
+};

package/dist/hydration/hydration-tag.format.js

@@ -0,0 +1,6 @@
+export const HYDRATION_FORMAT = {
+    tagKey: "$av",
+    valueKey: "v",
+    objectTag: "object",
+    scalarTags: ["bigint", "bytes", "datetime", "decimal"],
+};

package/dist/internal.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@aventara/client/internal` is not public API.
+ *
+ * It holds what Aventara's own packages need from the client generator and an
+ * application does not. It carries no stability promise: any export here may
+ * change or disappear in any release, including a patch release.
+ */
+export type { ClientEntrypoint, EmittedEntrypoint, SameOriginEntrypoint, } from "./config/client-config.interface.js";
+export { AvClientConfigError, sameOriginEntrypoint, } from "./config/config.resolver.js";
+export { resolveModuleStyle } from "./config/module-style.resolver.js";
+export type { ContractAcceptance } from "./contract/contract.acceptance.js";
+export { acceptClientContract } from "./contract/contract.acceptance.js";
+export type { RegenerateCommand } from "./emit/banner.emitter.js";
+export { carriesGeneratedOwnership } from "./emit/banner.emitter.js";
+export type { ClientClassExport } from "./emit/client-tree.emitter.js";
+export { clientEntryReExports, emitClientTree, } from "./emit/client-tree.emitter.js";
+export type { ClientEmission, EmittedFile, EmittedTree, } from "./emit/emitted-tree.interface.js";
+export { GENERATED_DIRECTORY } from "./emit/emitted-tree.interface.js";
+export type { ClientModuleStyle } from "./emit/module-style.interface.js";
+export { importSpecifier } from "./emit/module-style.interface.js";
+export { AvGeneratedNameError } from "./emit/name.deriver.js";
+export { HYDRATION_FORMAT } from "./hydration/hydration-tag.format.js";

package/dist/internal.js

@@ -0,0 +1,9 @@
+export { AvClientConfigError, sameOriginEntrypoint, } from "./config/config.resolver.js";
+export { resolveModuleStyle } from "./config/module-style.resolver.js";
+export { acceptClientContract } from "./contract/contract.acceptance.js";
+export { carriesGeneratedOwnership } from "./emit/banner.emitter.js";
+export { clientEntryReExports, emitClientTree, } from "./emit/client-tree.emitter.js";
+export { GENERATED_DIRECTORY } from "./emit/emitted-tree.interface.js";
+export { importSpecifier } from "./emit/module-style.interface.js";
+export { AvGeneratedNameError } from "./emit/name.deriver.js";
+export { HYDRATION_FORMAT } from "./hydration/hydration-tag.format.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/client",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.9",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Development-time generator for Aventara typed remote clients.",
   "type": "module",
@@ -16,6 +16,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
     }
   },
   "files": [
@@ -24,7 +28,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@aventara/core": "1.0.0-rc.4",
+    "@aventara/core": "1.0.0-rc.9",
     "c12": "3.3.4",
     "get-tsconfig": "4.10.0"
   },
@@ -40,7 +44,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/testing": "1.0.0-rc.4",
+    "@aventara/testing": "1.0.0-rc.9",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },