@aventara/client 0.1.0-pilot.1 → 0.1.0-pilot.2

package/dist/emit/name.deriver.js

@@ -1,80 +1,5 @@
 import { isOperationVariantAvailable, } from "@aventara/core";
 import { FRAMEWORK_ERROR_CLASS_NAMES } from "./runtime.emitter.js";
-/**
- * Name derivation and the rename ladder for the emitted tree.
- *
- * # Renamed, not refused (architect decision, 2026-10-04)
- *
- * S4 shipped "verbatim, or refused — never renamed". The architect overturned it:
- * a Contract name the emitted TypeScript cannot declare as-is is RENAMED, and the
- * rename is the TypeScript identifier's alone. The name the server uses — the
- * wire name a Resource is addressed by — is kept beside it unchanged
- * (`EmittedName.contractName`), so a later emitter that sends a request reads that,
- * never the identifier. Every rename is one warning line on the result; generation
- * does not print.
- *
- * A name is unusable as-is when it is not an identifier, is a reserved word, is a
- * predefined type's name, is a name the generated runtime owns, or — an enum only
- * — is also a Resource's name. Its ladder is tried in order and the first rung
- * that is usable AND free of every other emitted name (verbatim or renamed) wins:
- *
- * - Resource `X`: `XModel` → `ResourceX` → `X_` → `_X` → `_X_` → refused;
- * - enum `X`: `XEnum` → `EnumX` → `X_` → refused.
- *
- * Only a name whose whole ladder is unusable or taken is refused, in one sentence —
- * and a name no rename can repair, which is refused without trying a rung: the
- * empty name. Every rung of its ladder is a bare affix (`Model`, `Enum`, `_`) that
- * names nothing on the server, so "renaming" it would invent an identifier rather
- * than repair one (architect's rule, 2026-10-04: refuse when unrepairable).
- *
- * # Determinism
- *
- * The same Contract always yields the same names, whatever order its keys arrive
- * in: every name usable as-is is claimed first (so a usable name is never displaced
- * by another's rename), then Resources are renamed, then enums, each registry in
- * UTF-16 code-unit order of its contract names. An enum sharing a Resource's name
- * walks its ladder and the Resource keeps the name.
- *
- * # One namespace
- *
- * Enum and Resource identifiers share the generated client's root namespace with
- * each other and with the runtime's own exports. §15.6 names a Resource's type by
- * the Resource's name (`Spell`), so that namespace is claimed now, before the
- * Resource types are emitted. Names are case-sensitive.
- *
- * # Derived names (Phase 12-rest Q10; the ladder rule, a plan ruling)
- *
- * §15.6 derives named types from a Resource (`SpellWhere`, `SpellOrderBy`, …;
- * {@link RESOURCE_NAMED_TYPES}), each only when the operation it reads is
- * advertised. A Resource's base name is taken at the first rung — its own name
- * first, when usable — where the base AND every name derived from it are free of
- * every other emitted name: `User` beside a Resource `UserWhere` walks to
- * `UserModel`, one warning. Derived names a Resource claims are claimed for good,
- * so a later Resource or enum never takes one. The generated modules that declare
- * these names use no global type a Resource could shadow (`types.d.ts` imports two
- * helpers, which are reserved).
- *
- * # Properties (Phase 12-rest Q12)
- *
- * A Resource is reached as a property of the client, named by its contract name.
- * A contract name equal to one of the client's own members
- * ({@link CLIENT_MEMBER_NAMES}) walks the Resource ladder for its PROPERTY only,
- * one warning; the wire name, and the TypeScript type names, are unaffected.
- *
- * Reads registry KEYS and which operations are advertised. No capability member.
- */
-/**
- * The names the generated client declares in the root namespace: those §15.4
- * and §13.4 give it, under the architect's names (Phase 12-rest Q7–Q9) — the
- * `avClient` singleton, `AvClient`, `AvClientOptions`, `CallOptions`, `Fetch`,
- * `Decimal`, `FrameworkError`, `NotFoundError`, `TransportError`,
- * `OperationCode`/`ValidationCode` and `Operation<T>`, plus `Cause` and
- * `ValidationIssue` (public by the architect's decision of 2026-10-04) — every
- * `FrameworkError` subclass Q2 adds, read from the runtime emitter that declares
- * them, and the two helpers `types.d.ts` imports to declare the named types
- * (`ResourceArgument`, `ResourceRecord`). A Contract name equal to one of them
- * walks its rename ladder. In UTF-16 code-unit order.
- */
 export const RESERVED_EMITTED_NAMES = [
     ...new Set([
         "AvClient",
@@ -96,7 +21,6 @@ export const RESERVED_EMITTED_NAMES = [
         ...FRAMEWORK_ERROR_CLASS_NAMES,
     ]),
 ].sort();
-/** §15.6's set exactly (Q10 = a), in §15.6's order. */
 export const RESOURCE_NAMED_TYPES = [
     { suffix: "", family: "find", variant: "unique" },
     { suffix: "Where", family: "find", variant: "many", argument: "where" },
@@ -117,20 +41,10 @@ export const RESOURCE_NAMED_TYPES = [
     { suffix: "Select", family: "find", variant: "many", argument: "select" },
     { suffix: "Include", family: "find", variant: "many", argument: "include" },
 ];
-/** The named types a Resource with `operations` gets: those whose operation it advertises. */
 export function namedTypesOf(operations) {
     const families = (operations ?? {});
     return RESOURCE_NAMED_TYPES.filter((named) => isOperationVariantAvailable(families[named.family]?.[named.variant]));
 }
-/**
- * The client's own members, which a Resource property must not shadow (Q12):
- * `tx` and `transaction` (reserved whether or not the contract advertises
- * transactions, so a property never moves with `transactions`), `then` — a client
- * with a `then` is a thenable, and `await` would call it — and every name
- * `Object.prototype` carries in ES2022, `constructor` among them. Fixed here, not
- * read from the running Node, so the output never moves with the generator's
- * runtime. In UTF-16 code-unit order.
- */
 export const CLIENT_MEMBER_NAMES = [
     "__defineGetter__",
     "__defineSetter__",
@@ -148,25 +62,10 @@ export const CLIENT_MEMBER_NAMES = [
     "tx",
     "valueOf",
 ];
-/**
- * A TypeScript identifier: ID_Start, `$` or `_`, then ID_Continue, `$`, ZWNJ, ZWJ —
- * ECMAScript's IdentifierName. ZWNJ and ZWJ are ID_Continue since Unicode 15.1, so
- * on this repository's Node (Unicode 17.0, measured) their explicit escapes are
- * redundant; they stay so the rule does not depend on the runtime's tables.
- */
 const IDENTIFIER = /^[\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*$/u;
-/** Whether `text` is an IdentifierName — the rule above, for every emitter. */
 export function isIdentifierName(text) {
     return IDENTIFIER.test(text);
 }
-/**
- * Words `export type <name> = …` or `export const <name> = …` does not accept in a
- * module, measured against this repository's `tsc` (2026-10-04, NodeNext strict):
- * ECMAScript's reserved words, the strict-mode reserved words (a module is
- * strict), `await` (a module may await at top level), `as`, which is not reserved
- * but does not parse after `type`, and `arguments`/`eval`, which strict code
- * cannot bind (TS1215) — measured again when enums gained their const.
- */
 const RESERVED_WORDS = new Set([
     "arguments",
     "as",
@@ -218,7 +117,6 @@ const RESERVED_WORDS = new Set([
     "with",
     "yield",
 ]);
-/** TS2457: a type alias cannot take a predefined type's name. */
 const PREDEFINED_TYPES = new Set([
     "any",
     "bigint",
@@ -232,7 +130,6 @@ const PREDEFINED_TYPES = new Set([
     "unknown",
 ]);
 const RESERVED_EMITTED = new Set(RESERVED_EMITTED_NAMES);
-/** The rungs a name of `kind` tries, in order (architect decision, 2026-10-04). */
 const LADDERS = {
     Resource: (name) => [
         `${name}Model`,
@@ -243,12 +140,6 @@ const LADDERS = {
     ],
     enum: (name) => [`${name}Enum`, `Enum${name}`, `${name}_`],
 };
-/**
- * The emitted names of a Contract's enums and Resources, renamed where a name
- * cannot be declared as-is.
- *
- * @throws GeneratedNameError naming every name no rung of its ladder can repair.
- */
 export function deriveEmittedNames(contract) {
     const resourceNames = Object.keys(contract.resources).sort();
     const enumNames = Object.keys(contract.enums).sort();
@@ -257,15 +148,11 @@ export function deriveEmittedNames(contract) {
         (kind === "enum" && resourceSet.has(name)
             ? "shares its name with a Resource"
             : undefined);
-    // Every name usable as-is is claimed before any rename picks a rung, so a
-    // usable name is never displaced by another's rename.
     const taken = new Set([
         ...resourceNames.filter((name) => reasonOf("Resource", name) === undefined),
         ...enumNames.filter((name) => reasonOf("enum", name) === undefined),
     ]);
-    // The names Resources derive (Q10), claimed as each Resource settles.
     const derivedTaken = new Set();
-    /** `base`'s derived names for Resource `name`, or the first that is not free. */
     const derivedNames = (name, base) => namedTypesOf(contract.resources[name]?.operations)
         .filter((named) => named.suffix !== "")
         .map((named) => `${base}${named.suffix}`);
@@ -323,8 +210,6 @@ export function deriveEmittedNames(contract) {
         });
         return settle(identifier);
     };
-    // Resources first: in a clash the Resource keeps the name, and a Resource's
-    // rename is settled before any enum's.
     const resources = resourceNames.map((name) => resolve("Resource", name));
     const enums = enumNames.map((name) => resolve("enum", name));
     const properties = resourceProperties(resourceNames, warnings, refusals);
@@ -334,12 +219,6 @@ export function deriveEmittedNames(contract) {
     return { enums, resources, properties, warnings: byName(warnings) };
 }
 const CLIENT_MEMBERS = new Set(CLIENT_MEMBER_NAMES);
-/**
- * Each Resource's property on the client (Q12): its contract name, unless that is
- * one of the client's members — then the first rung of the Resource ladder that is
- * neither a member nor another Resource's property. A property need not be an
- * identifier (it is a key, quoted where needed), so only those two tests apply.
- */
 function resourceProperties(resourceNames, warnings, refusals) {
     const claimed = new Set(resourceNames.filter((name) => !CLIENT_MEMBERS.has(name)));
     return resourceNames.map((name) => {
@@ -364,7 +243,6 @@ function resourceProperties(resourceNames, warnings, refusals) {
         return { contractName: name, property };
     });
 }
-/** Why `name` cannot be declared as-is in any position, or `undefined`. */
 function unusableBecause(name) {
     return !isIdentifierName(name)
         ? "is not a TypeScript identifier"
@@ -376,20 +254,14 @@ function unusableBecause(name) {
                     ? "is the generated client's own name for its runtime"
                     : undefined;
 }
-/**
- * The lines' texts by name in UTF-16 code units. The sort is stable and lines are
- * collected Resources first, so a Resource precedes an enum of the same name.
- */
 function byName(lines) {
     return [...lines]
         .sort((left, right) => compareCodeUnits(left.name, right.name))
         .map((line) => line.text);
 }
-/** `Array.prototype.sort`'s default order, stated: UTF-16 code units. */
 function compareCodeUnits(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }
-/** The refusal that stops generation over names no rename can repair. */
 export class GeneratedNameError extends Error {
     name = "GeneratedNameError";
     constructor(problems) {
@@ -397,12 +269,6 @@ export class GeneratedNameError extends Error {
             `Rename ${problems.length === 1 ? "it" : "them"} on the server, then generate again.`);
     }
 }
-/**
- * `value` as an object-literal key that makes it an OWN property: bare when it is
- * an IdentifierName (reserved words included — a property name may be one), a
- * string literal otherwise — except `__proto__`, which bare or quoted sets the
- * prototype instead (measured on Node 24), so it is computed.
- */
 export function ownPropertyKey(value) {
     if (value === "__proto__") {
         return '["__proto__"]';

package/dist/emit/named-type.emitter.d.ts

@@ -1,32 +1,25 @@
 import type { ClientContract } 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";
 /**
- * `generated/types.d.ts` — §15.6's named Resource types (Q10 = a): `X`, `XWhere`,
- * `XUniqueWhere`, `XOrderBy`, `XCreateData`, `XUpdateData`, `XSelect`,
- * `XInclude`, each only when the operation it reads is advertised, `X` being the
- * Resource's emitted name (`name.deriver.ts`'s ladder, which keeps every derived
- * name free).
- *
  * Each is an ALIAS over the copied derivation — `ResourceRecord` /
  * `ResourceArgument`, declared in `client.ts` — never a walked-out literal type:
- * the derivation stays one. A Resource is addressed by its contract name, a
- * string literal type, so nothing here depends on how it was renamed.
- *
- * The module declares no name but these, and uses no global type a Resource
- * named like one could shadow.
+ * the derivation stays one. A Resource is addressed by its contract name, a string
+ * literal type, so nothing here depends on how it was renamed.
  *
- * # A declaration file (architect, 2026-10-05)
+ * The module declares no name but these, and uses no global type a Resource named
+ * like one could shadow.
  *
  * TypeScript resolves a type alias where it is DECLARED, so a consumer pays for
  * every Resource's named types whether it uses them or not — measured ≈2,800
- * instantiations per Resource (plan §21). Emitted as `types.d.ts`, they cost
- * nothing under `skipLibCheck: true` (the common default) until used, and the
- * same as a `.ts` under `skipLibCheck: false`. It is live, not a dead
- * declaration: nothing else declares these names, and no `types.ts` sits beside
- * it to shadow it (`client-tree.emitter.spec.ts`). Only types are declared here,
- * so nothing a bundler needs lives in it; `AvClient.ts` re-exports it by
- * `export type *` (TypeScript 5.0, inside the 5.5 peer floor) — an `export *`
- * would survive to the JavaScript and import a `types.js` that does not exist.
+ * instantiations per Resource. Emitted as `types.d.ts`, they cost nothing under
+ * `skipLibCheck: true` (the common default) until used, and the same as a `.ts`
+ * under `skipLibCheck: false`. It is live, not a dead declaration: nothing else
+ * declares these names, and no `types.ts` sits beside it to shadow it
+ * (`client-tree.emitter.spec.ts`). Only types are declared here, so nothing a
+ * bundler needs lives in it; `AvClient.ts` re-exports it by `export type *`
+ * (TypeScript 5.0, inside the 5.5 peer floor) — an `export *` would survive to the
+ * JavaScript and import a `types.js` that does not exist.
  */
-export declare function emitNamedTypesModule(contract: ClientContract, names: EmittedNames): EmittedModule;
+export declare function emitNamedTypesModule(contract: ClientContract, names: EmittedNames, style: ClientModuleStyle): EmittedModule;

package/dist/emit/named-type.emitter.js

@@ -1,33 +1,6 @@
+import { importSpecifier, } from "./module-style.interface.js";
 import { namedTypesOf } from "./name.deriver.js";
-/**
- * `generated/types.d.ts` — §15.6's named Resource types (Q10 = a): `X`, `XWhere`,
- * `XUniqueWhere`, `XOrderBy`, `XCreateData`, `XUpdateData`, `XSelect`,
- * `XInclude`, each only when the operation it reads is advertised, `X` being the
- * Resource's emitted name (`name.deriver.ts`'s ladder, which keeps every derived
- * name free).
- *
- * Each is an ALIAS over the copied derivation — `ResourceRecord` /
- * `ResourceArgument`, declared in `client.ts` — never a walked-out literal type:
- * the derivation stays one. A Resource is addressed by its contract name, a
- * string literal type, so nothing here depends on how it was renamed.
- *
- * The module declares no name but these, and uses no global type a Resource
- * named like one could shadow.
- *
- * # A declaration file (architect, 2026-10-05)
- *
- * TypeScript resolves a type alias where it is DECLARED, so a consumer pays for
- * every Resource's named types whether it uses them or not — measured ≈2,800
- * instantiations per Resource (plan §21). Emitted as `types.d.ts`, they cost
- * nothing under `skipLibCheck: true` (the common default) until used, and the
- * same as a `.ts` under `skipLibCheck: false`. It is live, not a dead
- * declaration: nothing else declares these names, and no `types.ts` sits beside
- * it to shadow it (`client-tree.emitter.spec.ts`). Only types are declared here,
- * so nothing a bundler needs lives in it; `AvClient.ts` re-exports it by
- * `export type *` (TypeScript 5.0, inside the 5.5 peer floor) — an `export *`
- * would survive to the JavaScript and import a `types.js` that does not exist.
- */
-export function emitNamedTypesModule(contract, names) {
+export function emitNamedTypesModule(contract, names, style) {
     const declarations = names.resources.flatMap(({ contractName, identifier }) => {
         const resource = JSON.stringify(contractName);
         return namedTypesOf(contract.resources[contractName]?.operations).map((named) => {
@@ -45,6 +18,6 @@ export function emitNamedTypesModule(contract, names) {
         path: "types.d.ts",
         source: declarations.length === 0
             ? "export {};\n"
-            : `import type { ${imported.join(", ")} } from "./client.js";\n\n${declarations.join("")}`,
+            : `import type { ${imported.join(", ")} } from ${JSON.stringify(importSpecifier("./client", style))};\n\n${declarations.join("")}`,
     };
 }

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

@@ -1,45 +1,41 @@
 import { type ClientContract } from "@aventara/core";
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
 import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.interface.js";
 /**
  * The runtime modules the generated client carries: `metadata.ts`, the
  * framework `Decimal`, the outcome codes and error classes, and the transport
  * here; the scalar codec in `scalar.codec.ts`.
  */
 /**
- * `runtime/decimal.ts` — the framework-owned `Decimal` of §6.2, the generated
- * runtime value of the `decimal` scalar. Bundled with the client and imported
- * from nothing: its public type is its own, never an ORM's (§6.2, C-801).
+ * Bundled with the client and imported from nothing: its public type is its own,
+ * never an ORM's.
  *
  * It holds the decimal string it was made from, digit for digit, and does no
  * arithmetic — the surface is core's `Decimal` (a string constructor and
  * `toString`) plus `toJSON`, so a value means the same on both sides of the wire.
- * A proven decimal library may later sit behind it (§6.2); none is needed to
- * carry digits.
+ * A proven decimal library may later sit behind it; none is needed to carry
+ * digits.
  *
- * `toJSON` is the architect's (2026-10-04, S6 answers): it returns the decimal
- * string, so a Decimal in a consumer's own JSON — a log line, a cache entry — is
- * its digits rather than `{}`. No `equals`, no arithmetic. The request body never
- * relies on it: `serializeWireBody` refuses an unencoded Decimal regardless, so a
- * value the codec did not encode cannot slip onto the wire through `toJSON`.
+ * No `equals`, no arithmetic. The request body never relies on it:
+ * `serializeWireBody` refuses an unencoded Decimal regardless, so a value the
+ * codec did not encode cannot slip onto the wire through `toJSON`.
  *
  * The grammar is core's `Decimal` grammar, read from `AvProtocol.scalarFormats`
- * and emitted by value (C2, R7; `protocol-parity.spec.ts`). Unlike
- * core's, the constructor refuses a non-string outright: a pattern test coerces
- * its argument, so `5` would otherwise pass as `"5"` and be kept as a number.
+ * and emitted by value. Unlike core's, the constructor refuses a non-string
+ * outright: a pattern test coerces its argument, so `5` would otherwise pass as
+ * `"5"` and be kept as a number.
  */
 export declare function emitDecimalModule(): EmittedModule;
 /**
- * `metadata.ts` — what this client was generated against: the ClientContract
- * hash and the protocol version (Phase 12-partial Q4 = A), and the resolved
- * entrypoint as the client's default (§15.2; Phase 12-rest Q5 = A). Nothing else:
- * no driver, no timestamp, no generator version, no host path — anything a re-run
- * over the same inputs could change breaks byte-equality (§19.3's spirit). The
+ * `metadata.ts` — what this client was generated against: the ClientContract hash
+ * and the protocol version, and the resolved entrypoint as the client's default.
+ * Nothing else: no driver, no timestamp, no generator version, no host path —
+ * anything a re-run over the same inputs could change breaks byte-equality. The
  * entrypoint is an input like the contract: changing it regenerates different
- * bytes and leaves the hash alone (§15.2), and it never carries credentials
- * (refused at resolution, Q5).
+ * bytes and leaves the hash alone, and it never carries credentials.
  *
- * The hash and the version are what every operation request sends (§12.4), from
+ * The hash and the version are what every operation request sends, from
  * `runtime/transport.ts`; all three are internal — `AvClient.ts` exports none.
  */
 export declare function emitMetadataModule(protocol: ClientContract["protocol"], entrypoint: ClientEntrypoint): EmittedModule;
@@ -48,40 +44,17 @@ export declare function emitMetadataModule(protocol: ClientContract["protocol"],
  * code-unit order — names the root namespace reserves (`name.deriver.ts`).
  */
 export declare const FRAMEWORK_ERROR_CLASS_NAMES: readonly string[];
-/**
- * The names `AvClient.ts` re-exports from `generated/runtime/errors.ts`: the classes and the
- * two code unions §15.4 requires, and `Cause` and `ValidationIssue` — the types a
- * thrown FrameworkError carries, public by the architect's decision of
- * 2026-10-04 — in UTF-16 code-unit order.
- */
 export declare function errorsModuleExports(): readonly string[];
 /**
- * `runtime/errors.ts` — §13's vocabulary as the generated client carries it.
- *
- * Both code unions are emitted from core's exported arrays (Q3), so the emitted
- * tree states each code exactly once and core stays their one source; the
- * subclass set and the code each one throws are Q2's (above), accepted as-is by
- * the architect on 2026-10-04. Exported beyond what `AvClient.ts` re-exports: the
- * two arrays, `OperationErrorCode` and `frameworkErrorOf`, which
- * `runtime/transport.ts` reads.
+ * Exported beyond what `AvClient.ts` re-exports: the two arrays,
+ * `OperationErrorCode` and `frameworkErrorOf`, which `runtime/transport.ts` reads.
  */
 export declare function emitErrorsModule(): EmittedModule;
 /**
- * `runtime/transport.ts` — the happy path of §12 and §13.5, above Phase
- * 12-partial's boundary: one POST per operation to
- * `<entrypoint>/_resources/<resource>/<family>/<variant>` (§12.1–§12.3), the
- * identity headers on every request (§12.4), per-request options that are never
- * serialized (§15.7), and the envelope read back by §13.5's rule.
- *
- * `execute` is Q1 = B's primitive: exported from this module for the
- * per-variant methods to wrap, and re-exported from nowhere — it is not public
- * surface. It reads no capability and no operation descriptor; the caller names
- * the operation.
+ * It reads no capability and no operation descriptor; the caller names the
+ * operation.
  *
  * Fetch and AbortSignal are the platform's, reached through the structural types
- * below so the module compiles with neither DOM nor Node types (§15.7, U5).
- *
- * Stale-route recovery is not here: it is F-716, Phase 10's, and the emitted
- * module documents it as a hole in its own doc comment (S9).
+ * below so the module compiles with neither DOM nor Node types.
  */
-export declare function emitTransportModule(): EmittedModule;
+export declare function emitTransportModule(style: ClientModuleStyle): EmittedModule;