typespec-http-zod 0.11.0 → 0.12.0

package/dist/src/api.d.ts

@@ -43,6 +43,7 @@ export { EmitterOptionsSchema, type EmitterOptions } from "./lib.js";
  * independently.
  */
 export { objectKey } from "./zod.js";
+export declare function beginBanner(hint: string | undefined): void;
 /**
  * The status a row registers: the first non-error status the operation declares.
  *
@@ -328,6 +329,8 @@ export interface ResolvedServiceOptions {
     readonly sealObjectSchemas: boolean;
     readonly keyVocabularies: readonly string[];
     readonly runtimeModule: string;
+    /** The command that regenerates, for the banner. `undefined` keeps the generic line. */
+    readonly regenerateHint: string | undefined;
 }
 /** What the generated files import their runtime contract from when nothing says otherwise. */
 export declare const DEFAULT_RUNTIME_MODULE = "typespec-http-zod/runtime";

package/dist/src/api.js

@@ -60,9 +60,30 @@ const PACKAGE_NAME = "typespec-http-zod";
  * The package name stays, because that IS the answer to "what wrote this". The instruction becomes
  * the one thing true for every consumer: recompile the source, do not edit the output.
  */
-const GENERATED_BANNER = `// GENERATED by ${PACKAGE_NAME} from the TypeSpec service definition. DO NOT EDIT.
-// Recompile the spec that produced it; edits here are overwritten on the next run.
-`;
+/**
+ * How to regenerate, for the banner. Set per emission; `undefined` keeps the generic line.
+ *
+ * Module-scoped rather than threaded through four render functions, matching how the contracts
+ * package and the stream module are carried. The emission loop awaits each service to completion
+ * before the next begins, so nothing interleaves.
+ */
+let regenerateHint;
+export function beginBanner(hint) {
+    regenerateHint = hint;
+}
+/**
+ * The header every emitted file carries.
+ *
+ * **`DO NOT EDIT` says what not to do and not what to do instead**, and only the project knows the
+ * command that regenerates. Where it states one, the banner carries it; otherwise the generic line
+ * stands.
+ */
+function generatedBanner() {
+    const second = regenerateHint === undefined
+        ? "// Recompile the spec that produced it; edits here are overwritten on the next run."
+        : `// Regenerate with: ${regenerateHint}`;
+    return `// GENERATED by ${PACKAGE_NAME} from the TypeSpec service definition. DO NOT EDIT.\n${second}\n`;
+}
 /**
  * The status a row registers: the first non-error status the operation declares.
  *
@@ -1110,7 +1131,7 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
          * with no cycle emits byte-identical output to before.
          */
         if (d.structural === undefined) {
-            return `\nexport const ${d.identifier} = ${d.source};\nexport type ${d.typeName} = z.infer<typeof ${d.identifier}>;\n`;
+            return `\nexport const ${d.identifier} = ${d.source};\nexport type ${d.typeName} = Exact<z.infer<typeof ${d.identifier}>>;\n`;
         }
         const declared = d.structural.startsWith("{")
             ? `export interface ${d.typeName} ${d.structural}`
@@ -1134,8 +1155,28 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
      * inside `zValidator` or missed beside a bracket. `renderExternalImports` below reads the same
      * rendered content for the same reason.
      */
+    /**
+     * **`Exact` narrows an inferred optional to what the wire can carry.**
+     *
+     * `z.infer` of `.optional()` gives `p?: T | undefined`, which under `exactOptionalPropertyTypes`
+     * admits an explicitly-undefined property. **JSON has no `undefined`**, and the document says the
+     * same thing by leaving the property out of `required`, so the inferred type was wider than both
+     * the contract and the wire and a consumer had to strip it at the boundary.
+     *
+     * Derived from the same schema rather than hand-written beside it, so there is still one source of
+     * truth: a mapped type cannot drift from the thing it maps.
+     *
+     * Emitted only where a declaration names it, like the imports beside it.
+     */
+    const EXACT_HELPER = `
+/** An inferred type narrowed to what JSON can carry: an optional property is absent or a value. */
+type Exact<T> = { [K in keyof T as undefined extends T[K] ? never : K]: T[K] } & {
+	[K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
+};
+`;
+    const usesExact = declarations.some((d) => d.includes("Exact<"));
     const usesZod = new Set([...declarations, ...routeDeclarations].join("").match(/[A-Za-z_$][\w$]*/g) ?? []).has("z");
-    const parts = [GENERATED_BANNER];
+    const parts = [generatedBanner()];
     if (usesZod)
         parts.push('\nimport { z } from "zod";\n');
     /**
@@ -1150,6 +1191,8 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
         parts.push(`import type { ResponseArm } from ${JSON.stringify(runtimeModule)};\n`);
     }
     parts.push(renderExternalImports(externals, [...declarations, ...routeDeclarations].join("")));
+    if (usesExact)
+        parts.push(EXACT_HELPER);
     parts.push(declarations.join(""));
     if (routeDeclarations.length > 0)
         parts.push(`\n${routeDeclarations.join("\n")}\n`);
@@ -1468,7 +1511,7 @@ function renderRequestTypes(entries, responses, registry) {
     const lookup = entries
         .map((entry) => `\t${entry.operationId}: ${upperFirst(entry.operationId)}Input;`)
         .join("\n");
-    return `${GENERATED_BANNER}
+    return `${generatedBanner()}
 /**
  * Flattens an intersection into a single object type.
  *
@@ -1549,7 +1592,7 @@ function renderWireAssertions(schemas, types, entries, contractsPackage) {
     if (paired.length === 0)
         return undefined;
     const assertions = paired.map((pair) => `export type Assert${pair.name} = MustHold<Identical<z.infer<typeof ${pair.identifier}>, Contracts.${pair.name}>>;`);
-    return `${GENERATED_BANNER}
+    return `${generatedBanner()}
 import type { z } from "zod";
 import type * as Contracts from "${contractsPackage}";
 import type {
@@ -1587,7 +1630,7 @@ function renderVocabularies(vocabularies) {
     const entries = [...vocabularies.entries()]
         .toSorted(([a], [b]) => a.localeCompare(b))
         .map(([name, values]) => `\t${name}: [${values.map((v) => JSON.stringify(v)).join(", ")}],`);
-    return `${GENERATED_BANNER}
+    return `${generatedBanner()}
 /**
  * The spec's vocabularies - every enum the surface reaches, and what each one contains.
  *
@@ -1671,7 +1714,9 @@ export async function emitHttpZod(context, wrapper = {}) {
             sealObjectSchemas: perService?.["seal-object-schemas"] ?? options["seal-object-schemas"] ?? false,
             keyVocabularies: perService?.["key-vocabularies"] ?? options["key-vocabularies"] ?? [],
             runtimeModule: perService?.["runtime-module"] ?? options["runtime-module"] ?? defaultRuntimeModule,
+            regenerateHint: perService?.["regenerate-hint"] ?? options["regenerate-hint"],
         };
+        beginBanner(resolved.regenerateHint);
         const registry = new SchemaRegistry(context.program);
         const { result: { routes }, imports: externals, vocabularies, } = collectExternalImports(() => withContractsPackage(resolved.contractsPackage, () => withSealedObjects(resolved.sealObjectSchemas, () => {
             // Declarations first: a vocabulary is a fact about the contract, so it is collected from

package/dist/src/lib.d.ts

@@ -78,6 +78,15 @@ export interface EmitterOptions {
      * package's own tests, where the package name does not resolve.
      */
     "runtime-module"?: string;
+    /**
+     * The command that regenerates these files, written into every banner.
+     *
+     * **`DO NOT EDIT` says what not to do and not what to do instead.** Only the project knows whether
+     * that is `pnpm generate`, `npm run api` or a `tsp compile` with three flags, so no emitter can
+     * supply it, and the generic line standing in its place lost the one thing a reader opening a
+     * generated file needs. Omitted, the generic line is kept.
+     */
+    "regenerate-hint"?: string;
     /**
      * Per-`@service` overrides, keyed by the service namespace name.
      *
@@ -93,6 +102,7 @@ export interface EmitterOptions {
         "seal-object-schemas"?: boolean;
         "key-vocabularies"?: string[];
         "runtime-module"?: string;
+        "regenerate-hint"?: string;
     }>;
 }
 /**

package/dist/src/lib.js

@@ -14,6 +14,7 @@ export const EmitterOptionsSchema = {
         "seal-object-schemas": { type: "boolean", nullable: true },
         "key-vocabularies": { type: "array", items: { type: "string" }, nullable: true },
         "runtime-module": { type: "string", nullable: true },
+        "regenerate-hint": { type: "string", nullable: true },
         services: {
             type: "object",
             nullable: true,
@@ -27,6 +28,7 @@ export const EmitterOptionsSchema = {
                     "seal-object-schemas": { type: "boolean", nullable: true },
                     "key-vocabularies": { type: "array", items: { type: "string" }, nullable: true },
                     "runtime-module": { type: "string", nullable: true },
+                    "regenerate-hint": { type: "string", nullable: true },
                 },
                 required: [],
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "TypeSpec emitter and library: turn an HTTP service definition into Zod validators and framework-free contract types that agree, keyword for keyword, with the OpenAPI document @typespec/openapi3 publishes from the same source.",
   "keywords": [
     "codegen",