@aventara/client 0.0.0-stage → 0.1.0-pilot.0

package/dist/emit/name.deriver.d.ts

@@ -0,0 +1,153 @@
+import { type ClientContract, type OperationFamily } from "@aventara/core";
+/**
+ * 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 declare const RESERVED_EMITTED_NAMES: readonly string[];
+/**
+ * One of §15.6's named Resource types (Q10 = a): the suffix it adds to the
+ * Resource's name, the operation it reads — it exists only when that operation is
+ * advertised — and the argument it names, or none for the default record.
+ */
+export interface ResourceNamedType {
+    readonly suffix: string;
+    readonly family: OperationFamily;
+    readonly variant: string;
+    /** The argument it names; absent for `X`, the default record. */
+    readonly argument?: "where" | "orderBy" | "data" | "select" | "include";
+}
+/** §15.6's set exactly (Q10 = a), in §15.6's order. */
+export declare const RESOURCE_NAMED_TYPES: readonly ResourceNamedType[];
+/** The named types a Resource with `operations` gets: those whose operation it advertises. */
+export declare function namedTypesOf(operations: unknown): readonly ResourceNamedType[];
+/**
+ * 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 declare const CLIENT_MEMBER_NAMES: readonly string[];
+/** One Contract name and the TypeScript identifier the tree declares it under. */
+export interface EmittedName {
+    /** The name the server uses — what a request addresses. Never renamed. */
+    readonly contractName: string;
+    /** The identifier the emitted TypeScript declares; `contractName` unless renamed. */
+    readonly identifier: string;
+}
+/** A Resource's property on the client: its contract name unless a member owns it (Q12). */
+export interface EmittedProperty {
+    /** The name the server uses. Never renamed. */
+    readonly contractName: string;
+    /** The client's property for it; `contractName` unless it is a client member's. */
+    readonly property: string;
+}
+/** The emitted names, and one warning per rename. */
+export interface EmittedNames {
+    /** In UTF-16 code-unit order of `contractName` — RFC 8785's order. */
+    readonly enums: readonly EmittedName[];
+    /** In UTF-16 code-unit order of `contractName`. */
+    readonly resources: readonly EmittedName[];
+    /** Each Resource's client property, in UTF-16 code-unit order of `contractName`. */
+    readonly properties: readonly EmittedProperty[];
+    /**
+     * One line per renamed name, in UTF-16 code-unit order of the contract name, a
+     * Resource before an enum of the same name. Returned, never printed: the caller
+     * that owns the terminal decides where diagnostics go.
+     */
+    readonly warnings: readonly string[];
+}
+/** Whether `text` is an IdentifierName — the rule above, for every emitter. */
+export declare function isIdentifierName(text: string): boolean;
+/**
+ * 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 declare function deriveEmittedNames(contract: Pick<ClientContract, "enums" | "resources">): EmittedNames;
+/** The refusal that stops generation over names no rename can repair. */
+export declare class GeneratedNameError extends Error {
+    readonly name = "GeneratedNameError";
+    constructor(problems: readonly string[]);
+}
+/**
+ * `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 declare function ownPropertyKey(value: string): string;

package/dist/emit/name.deriver.js

@@ -0,0 +1,411 @@
+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",
+        "AvClientOptions",
+        "CallOptions",
+        "Cause",
+        "Decimal",
+        "Fetch",
+        "FrameworkError",
+        "NotFoundError",
+        "Operation",
+        "OperationCode",
+        "ResourceArgument",
+        "ResourceRecord",
+        "TransportError",
+        "ValidationCode",
+        "ValidationIssue",
+        "avClient",
+        ...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" },
+    {
+        suffix: "UniqueWhere",
+        family: "find",
+        variant: "unique",
+        argument: "where",
+    },
+    { suffix: "OrderBy", family: "find", variant: "many", argument: "orderBy" },
+    { suffix: "CreateData", family: "create", variant: "one", argument: "data" },
+    {
+        suffix: "UpdateData",
+        family: "update",
+        variant: "unique",
+        argument: "data",
+    },
+    { 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__",
+    "__lookupGetter__",
+    "__lookupSetter__",
+    "__proto__",
+    "constructor",
+    "hasOwnProperty",
+    "isPrototypeOf",
+    "propertyIsEnumerable",
+    "then",
+    "toLocaleString",
+    "toString",
+    "transaction",
+    "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",
+    "await",
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "eval",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "implements",
+    "import",
+    "in",
+    "instanceof",
+    "interface",
+    "let",
+    "new",
+    "null",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "return",
+    "static",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+]);
+/** TS2457: a type alias cannot take a predefined type's name. */
+const PREDEFINED_TYPES = new Set([
+    "any",
+    "bigint",
+    "boolean",
+    "never",
+    "number",
+    "object",
+    "string",
+    "symbol",
+    "undefined",
+    "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`,
+        `Resource${name}`,
+        `${name}_`,
+        `_${name}`,
+        `_${name}_`,
+    ],
+    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();
+    const resourceSet = new Set(resourceNames);
+    const reasonOf = (kind, name) => unusableBecause(name) ??
+        (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}`);
+    const takenDerived = (name, base) => derivedNames(name, base).find((derived) => taken.has(derived) || derivedTaken.has(derived));
+    const warnings = [];
+    const refusals = [];
+    const resolve = (kind, name) => {
+        if (name === "") {
+            refusals.push({
+                name,
+                text: `${kind} "" is empty, which no rename repairs`,
+            });
+            return { contractName: name, identifier: name };
+        }
+        const settle = (identifier) => {
+            if (kind === "Resource") {
+                for (const derived of derivedNames(name, identifier)) {
+                    derivedTaken.add(derived);
+                }
+            }
+            return { contractName: name, identifier };
+        };
+        const usable = reasonOf(kind, name);
+        const blockedBy = usable !== undefined || kind === "enum"
+            ? undefined
+            : derivedTaken.has(name)
+                ? name
+                : takenDerived(name, name);
+        const reason = usable ??
+            (blockedBy === undefined
+                ? undefined
+                : blockedBy === name
+                    ? "is a name another Resource's type takes"
+                    : `would derive ${JSON.stringify(blockedBy)}, which another emitted name takes`);
+        if (reason === undefined) {
+            return settle(name);
+        }
+        const rungs = LADDERS[kind](name);
+        const identifier = rungs.find((rung) => unusableBecause(rung) === undefined &&
+            !taken.has(rung) &&
+            !derivedTaken.has(rung) &&
+            (kind === "enum" || takenDerived(name, rung) === undefined));
+        const subject = `${kind} ${JSON.stringify(name)} ${reason}`;
+        if (identifier === undefined) {
+            refusals.push({
+                name,
+                text: `${subject}, and none of its renames (${rungs.map((rung) => JSON.stringify(rung)).join(", ")}) is free`,
+            });
+            return { contractName: name, identifier: name };
+        }
+        taken.add(identifier);
+        warnings.push({
+            name,
+            text: `${subject}, so it is emitted as ${JSON.stringify(identifier)}`,
+        });
+        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);
+    if (refusals.length > 0) {
+        throw new GeneratedNameError(byName(refusals));
+    }
+    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) => {
+        if (!CLIENT_MEMBERS.has(name)) {
+            return { contractName: name, property: name };
+        }
+        const rungs = LADDERS.Resource(name);
+        const property = rungs.find((rung) => !CLIENT_MEMBERS.has(rung) && !claimed.has(rung));
+        const subject = `Resource ${JSON.stringify(name)} is the name of the client's own member ${JSON.stringify(name)}`;
+        if (property === undefined) {
+            refusals.push({
+                name,
+                text: `${subject}, and none of its property renames (${rungs.map((rung) => JSON.stringify(rung)).join(", ")}) is free`,
+            });
+            return { contractName: name, property: name };
+        }
+        claimed.add(property);
+        warnings.push({
+            name,
+            text: `${subject}, so the client reaches it as ${JSON.stringify(property)}; its wire name is kept`,
+        });
+        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"
+        : RESERVED_WORDS.has(name)
+            ? "is a reserved word"
+            : PREDEFINED_TYPES.has(name)
+                ? "is the name of a predefined TypeScript type"
+                : RESERVED_EMITTED.has(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) {
+        super(`the ClientContract's names cannot all be emitted: ${problems.join("; ")}. ` +
+            `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__"]';
+    }
+    return isIdentifierName(value) ? value : JSON.stringify(value);
+}

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

@@ -0,0 +1,32 @@
+import type { ClientContract } from "@aventara/core";
+import type { EmittedModule } from "./emitted-tree.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.
+ *
+ * # 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 declare function emitNamedTypesModule(contract: ClientContract, names: EmittedNames): EmittedModule;

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

@@ -0,0 +1,50 @@
+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) {
+    const declarations = names.resources.flatMap(({ contractName, identifier }) => {
+        const resource = JSON.stringify(contractName);
+        return namedTypesOf(contract.resources[contractName]?.operations).map((named) => {
+            const operation = `${named.family}.${named.variant}`;
+            return named.argument === undefined
+                ? `/** \`${contractName}\`'s default record: \`${operation}\` with no projection. */\n` +
+                    `export type ${identifier} = ResourceRecord<${resource}>;\n`
+                : `/** \`${contractName}\`'s \`${operation}\` \`${named.argument}\`. */\n` +
+                    `export type ${identifier}${named.suffix} = ResourceArgument<${resource}, ${JSON.stringify(named.family)}, ${JSON.stringify(named.variant)}, ${JSON.stringify(named.argument)}>;\n`;
+        });
+    });
+    const uses = (helper) => declarations.some((declaration) => declaration.includes(` = ${helper}<`));
+    const imported = ["ResourceArgument", "ResourceRecord"].filter(uses);
+    return {
+        path: "types.d.ts",
+        source: declarations.length === 0
+            ? "export {};\n"
+            : `import type { ${imported.join(", ")} } from "./client.js";\n\n${declarations.join("")}`,
+    };
+}