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

package/dist/emit/enum.emitter.js

@@ -1,24 +1,4 @@
 import { ownPropertyKey } from "./name.deriver.js";
-/**
- * `enums.ts`: per enum, a string-literal union type and a same-named `as const`
- * object (§15.4's "enum types"; architect decision, 2026-10-04):
- *
- * ```ts
- * export type Role = "ADMIN" | "USER";
- * export const Role = { ADMIN: "ADMIN", USER: "USER" } as const;
- * ```
- *
- * The type is what every later emitter references; the object gives a consumer a
- * value to name a member by and to enumerate. Both are declared under the enum's
- * emitted identifier, which differs from its contract name only when the name was
- * renamed (`name.deriver.ts`). The values are the wire values and are never
- * renamed.
- *
- * Enums come in the order `names` gives them — UTF-16 code units of the contract
- * name — so the key order a contract arrives in never reaches the bytes (C-843).
- * An enum's VALUES keep their declared order, in the type and in the object: that
- * order is meaning, and canonical form keeps it too.
- */
 export function emitEnumsModule(contract, names) {
     const declarations = names.enums.map(({ contractName, identifier }) => {
         const values = contract.enums[contractName]?.values ?? [];
@@ -33,10 +13,6 @@ export function emitEnumsModule(contract, names) {
     });
     return {
         path: "enums.ts",
-        // Without an import or export, a consumer whose config treats such a file
-        // as a script (`moduleResolution: "bundler"` outside a `"type": "module"`
-        // package, measured) fails `AvClient.ts`'s `export *` with TS2306 — so a
-        // contract without enums still emits a module.
         source: declarations.length === 0 ? "export {};\n" : declarations.join("\n"),
     };
 }

package/dist/emit/module-specifier.scanner.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which modules a file names, read without `typescript`: the derivation's copy
+ * walks core's declaration closure by it (`derivation.emitter.ts`), and the output
+ * validator checks by it that every module the emitted tree names is a file of the
+ * tree, spelled the project's way — with or without a compiler.
+ */
+export interface ScannedModule {
+    /**
+     * Every module specifier: a `from` clause's, a side-effect `import`'s, and an
+     * `import()` type query's.
+     */
+    readonly specifiers: readonly string[];
+    /** Whether the file carries a `/// <reference …/>` directive. */
+    readonly references: boolean;
+}
+/**
+ * The specifiers one module names — a declaration file or JavaScript — read by a
+ * small lexer rather than by `typescript` (an optional peer, absent from a
+ * consumer's install): comments, string literals, template literals and
+ * regular-expression literals are skipped as units, so text inside them is never
+ * mistaken for an import. Agrees with TypeScript's own pre-processor over core's
+ * closure (`derivation.emitter.spec.ts`) and over every emitted file
+ * (`module-specifier.scanner.spec.ts`).
+ */
+export declare function scanModuleSpecifiers(text: string): ScannedModule;

package/dist/emit/module-specifier.scanner.js

@@ -0,0 +1,160 @@
+const SPECIFIER_KEYWORD = /^(?:from|import)$/;
+const EXPRESSION_KEYWORDS = new Set([
+    "case",
+    "delete",
+    "do",
+    "else",
+    "in",
+    "instanceof",
+    "new",
+    "of",
+    "return",
+    "throw",
+    "typeof",
+    "void",
+    "yield",
+]);
+export function scanModuleSpecifiers(text) {
+    const tokens = [];
+    let references = false;
+    let index = 0;
+    const readQuoted = (quote) => {
+        let value = "";
+        index += 1;
+        while (index < text.length && text[index] !== quote) {
+            if (text[index] === "\\") {
+                value += text[index + 1] ?? "";
+                index += 2;
+                continue;
+            }
+            value += text[index];
+            index += 1;
+        }
+        index += 1;
+        return value;
+    };
+    const scanCode = (inPlaceholder) => {
+        let depth = 0;
+        while (index < text.length) {
+            const character = text[index];
+            const next = text[index + 1];
+            if (character === "/" && next === "/") {
+                const end = text.indexOf("\n", index);
+                const line = text.slice(index, end === -1 ? text.length : end);
+                if (/^\/\/\/\s*<reference\b/.test(line)) {
+                    references = true;
+                }
+                index = end === -1 ? text.length : end + 1;
+            }
+            else if (character === "/" && next === "*") {
+                const end = text.indexOf("*/", index + 2);
+                index = end === -1 ? text.length : end + 2;
+            }
+            else if (character === "/" && opensRegularExpression(tokens.at(-1))) {
+                skipRegularExpression();
+            }
+            else if (character === '"' || character === "'") {
+                tokens.push({ kind: "string", value: readQuoted(character) });
+            }
+            else if (character === "`") {
+                scanTemplate();
+            }
+            else if (/[A-Za-z_$]/.test(character)) {
+                const start = index;
+                while (index < text.length && /[\w$]/.test(text[index])) {
+                    index += 1;
+                }
+                tokens.push({ kind: "word", value: text.slice(start, index) });
+            }
+            else if (/\s/.test(character)) {
+                index += 1;
+            }
+            else {
+                if (inPlaceholder && character === "{") {
+                    depth += 1;
+                }
+                else if (inPlaceholder && character === "}") {
+                    if (depth === 0) {
+                        index += 1;
+                        return;
+                    }
+                    depth -= 1;
+                }
+                tokens.push({ kind: "punctuation", value: character });
+                index += 1;
+            }
+        }
+    };
+    const skipRegularExpression = () => {
+        index += 1;
+        let inClass = false;
+        while (index < text.length && text[index] !== "\n") {
+            const character = text[index];
+            if (character === "\\") {
+                index += 2;
+                continue;
+            }
+            index += 1;
+            if (character === "[") {
+                inClass = true;
+            }
+            else if (character === "]") {
+                inClass = false;
+            }
+            else if (character === "/" && !inClass) {
+                break;
+            }
+        }
+        while (index < text.length && /[a-z]/.test(text[index])) {
+            index += 1;
+        }
+        tokens.push({ kind: "punctuation", value: "/" });
+    };
+    const scanTemplate = () => {
+        index += 1;
+        while (index < text.length && text[index] !== "`") {
+            if (text[index] === "\\") {
+                index += 2;
+            }
+            else if (text[index] === "$" && text[index + 1] === "{") {
+                index += 2;
+                scanCode(true);
+            }
+            else {
+                index += 1;
+            }
+        }
+        index += 1;
+        tokens.push({ kind: "punctuation", value: "`" });
+    };
+    scanCode(false);
+    const specifiers = [];
+    tokens.forEach((token, at) => {
+        const following = tokens[at + 1];
+        if (token.kind !== "word") {
+            return;
+        }
+        if (SPECIFIER_KEYWORD.test(token.value) && following?.kind === "string") {
+            specifiers.push(following.value);
+        }
+        else if (token.value === "import" &&
+            following?.kind === "punctuation" &&
+            following.value === "(" &&
+            tokens[at + 2]?.kind === "string") {
+            specifiers.push(tokens[at + 2].value);
+        }
+    });
+    return { specifiers, references };
+}
+function opensRegularExpression(previous) {
+    if (previous === undefined) {
+        return true;
+    }
+    if (previous.kind === "word") {
+        return EXPRESSION_KEYWORDS.has(previous.value);
+    }
+    return (previous.kind === "punctuation" &&
+        previous.value !== ")" &&
+        previous.value !== "]" &&
+        previous.value !== "`");
+}

package/dist/emit/module-style.interface.d.ts

@@ -0,0 +1,58 @@
+/**
+ * How the generated client's modules are spelled for the project that compiles
+ * them. The client is TypeScript source — `.ts` files — and the developer's own
+ * toolchain compiles it like their own files, so the relative specifiers by which
+ * its modules name each other, and the module format they are checked in, follow
+ * that project's rules. The names and the rules are Prisma 7's `prisma-client`
+ * generator's (`importFileExtension`, `moduleFormat`), inferred from the project's
+ * `tsconfig.json` (`config/module-style.resolver.ts`).
+ */
+/**
+ * The extension a relative import inside the generated client is written with:
+ *
+ * - `""` — extensionless, `./generated/client`: a bundler (`moduleResolution:
+ *   "bundler"`) or CommonJS (`module: "commonjs"`) project, where the developer's
+ *   own imports carry none;
+ * - `"js"` — `./generated/client.js`: Node's ES module resolution
+ *   (`node16`/`nodenext`), where the import names the file `tsc` will emit;
+ * - `"ts"` — `./generated/client.ts`: a project that imports TypeScript files by
+ *   their own name (`allowImportingTsExtensions`, `rewriteRelativeImportExtensions`)
+ *   — Node's type stripping, Deno, Bun.
+ *
+ * Prisma's list is wider (`mts`, `cts`, `mjs`, `cjs`): those pair with a
+ * generated `.mts` or `.cts`, and this generator emits `.ts` only.
+ */
+export type ImportFileExtension = "" | "js" | "ts";
+/**
+ * The module format the project compiles the generated `.ts` files to: what
+ * its `tsconfig.json` says (`module`), or, under `node16`/`nodenext`, what the
+ * nearest `package.json`'s `"type"` says. The emitted bytes are the same in
+ * either — they use no construct one format lacks — but the output validator
+ * type-checks them in this one, as the project will.
+ */
+export type ModuleFormat = "esm" | "cjs";
+/** One project's spelling of the generated client, resolved once per run. */
+export interface ClientModuleStyle {
+    readonly importFileExtension: ImportFileExtension;
+    readonly moduleFormat: ModuleFormat;
+}
+/**
+ * A relative module path without an extension — `./contract`,
+ * `../metadata`, `./derivation/operations/operation-call` — as an emitter names
+ * the module it imports.
+ */
+export type ExtensionlessModulePath = `./${string}` | `../${string}`;
+/**
+ * The specifier a generated module imports `module` by, in this style. One rule
+ * for every target, `.ts` source and `.d.ts` declaration alike: TypeScript
+ * resolves an extensionless, a `.js` and a `.ts` specifier to either (measured
+ * under `nodenext` and `bundler`, TypeScript 5.9, 6 and 7).
+ */
+export declare function importSpecifier(module: ExtensionlessModulePath, style: Pick<ClientModuleStyle, "importFileExtension">): string;
+/**
+ * Writes the quoted specifier an emitted `import`/`export … from` names a
+ * module by: `importSpecifier`, as a string literal of the generated source.
+ */
+export type ModuleSpecifierWriter = (module: ExtensionlessModulePath) => string;
+/** The {@link ModuleSpecifierWriter} of one style. */
+export declare function moduleSpecifierWriter(style: Pick<ClientModuleStyle, "importFileExtension">): ModuleSpecifierWriter;

package/dist/emit/module-style.interface.js

@@ -0,0 +1,8 @@
+export function importSpecifier(module, style) {
+    return style.importFileExtension === ""
+        ? module
+        : `${module}.${style.importFileExtension}`;
+}
+export function moduleSpecifierWriter(style) {
+    return (module) => JSON.stringify(importSpecifier(module, style));
+}

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

@@ -2,15 +2,10 @@ 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.
+ * 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
@@ -20,66 +15,44 @@ import { type ClientContract, type OperationFamily } from "@aventara/core";
  * - 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
+ * 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).
+ * than repair one.
  *
  * # 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.
+ * 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).
+ * Names are case-sensitive.
  *
- * # Properties (Phase 12-rest Q12)
+ * 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).
  *
- * 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.
+ * 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.
+ * 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;
@@ -87,18 +60,17 @@ export interface ResourceNamedType {
     /** 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.
+ * The client's own members, which a Resource property must not shadow: `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. */
@@ -108,7 +80,7 @@ export interface EmittedName {
     /** 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). */
+/** A Resource's property on the client: its contract name unless a member owns it. */
 export interface EmittedProperty {
     /** The name the server uses. Never renamed. */
     readonly contractName: string;