typespec-http-zod 0.5.0 → 0.6.0

package/dist/src/api.d.ts

@@ -211,6 +211,34 @@ export interface EmittedRoute {
     readonly alternateResponseSchema: string | undefined;
 }
 export declare function collectRoutes(program: Program, registry: SchemaRegistry, service: HttpService): EmittedRoute[];
+/**
+ * Emit only the external names a given file actually references.
+ *
+ * Both generated files can need them - `schemas.gen.ts` for the vocabulary tuples and `@refine`
+ * predicates, and `routes.gen.ts` when an inline params schema carries a refined scalar.
+ * Emitting the whole set into both would leave unused imports (which lint rejects); emitting it into
+ * neither is what left `routes.gen.ts` referencing `isParsableInstant` with no import at all.
+ */
+/**
+ * Whether emitted source references `name` as an identifier.
+ *
+ * **The name is ESCAPED before it becomes a pattern, and skipping that is a silent build break.**
+ * This was `new RegExp(`\\b${name}\\b`)`, interpolating an identifier straight into a pattern.
+ * `$` is a valid identifier character in JavaScript and in TypeSpec, and an anchor in a regular
+ * expression, so a name containing one fails to match ITSELF: measured, `foo$bar` and `$select` both
+ * report absent from source that references them verbatim.
+ *
+ * The direction matters. Reporting a name present that is absent yields an unused import, which lint
+ * refuses loudly. Reporting a name ABSENT that is present drops the import and leaves the emitted
+ * module referencing an undeclared identifier - the failure this function exists to prevent, which is
+ * how `routes.gen.ts` once referenced `isParsableInstant` with no import at all.
+ *
+ * Only `SPEC_VOCABULARIES` reaches here today, so the hole was latent rather than live. It sits on a
+ * general seam that any future name flows through, and the reasoning that made it look safe - an
+ * identifier absent from the text is genuinely not needed - is true of the QUESTION and false of the
+ * way it was being asked.
+ */
+export declare function referencedIn(source: string, name: string): boolean;
 /**
  * The identifiers a route's validators are declared under, by what the DOCUMENT calls each one.
  *

package/dist/src/api.js

@@ -5,7 +5,7 @@ import { reportDiagnostic } from "./lib.js";
 import { SchemaRegistry, TypeRegistry } from "./registry.js";
 import { resolveStreamModule, streamedTypeOf, withStreamModule } from "./streams.js";
 import { resolveVersioningModule, serviceSnapshots } from "./versioning.js";
-import { collectExternalImports, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
+import { collectExternalImports, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
 /**
  * `typespec-http-zod` - Zod validators and framework-free contract types from a TypeSpec HTTP
  * service, agreeing with the OpenAPI document `@typespec/openapi3` publishes from the same source.
@@ -365,6 +365,21 @@ function responseContentTypesOf(operation, status) {
     }
     return [...types];
 }
+/** The type a parameter actually crosses the wire as, after any `@encode` on the property. */
+function encodedParameterType(program, property) {
+    return getEncode(program, property)?.type ?? property.type;
+}
+/**
+ * The wire kind of an ARRAY parameter's elements, or `undefined` where it is not such an array.
+ *
+ * `?ids=1,2,3` splits into strings, so each element needs the same decoding a lone scalar would.
+ */
+function elementKindOf(program, type) {
+    if (!isArrayType(type) || type.kind !== "Model")
+        return undefined;
+    const element = type.indexer?.value;
+    return element === undefined ? undefined : wireKindOf(program, element);
+}
 /** Whether a type is an array - TypeSpec models one as a `Model` carrying an integer indexer. */
 function isArrayType(type) {
     return type.kind === "Model" && type.indexer?.key.name === "integer";
@@ -583,12 +598,12 @@ function collectionDelimiterOf(program, parameter) {
  * `zod.ts` decides what becomes `z.number()`, and a second copy of that list here would stop agreeing
  * with it silently.
  */
-function wireDecoded(declared) {
+function wireDecoded(declared, kind, elementKind) {
     const NUMBER = '(raw) => (typeof raw === "string" && raw.trim() !== "" && Number.isFinite(Number(raw)) ? Number(raw) : raw)';
     const BOOLEAN = '(raw) => (raw === "true" ? true : raw === "false" ? false : raw)';
-    if (declared.startsWith("z.number()"))
+    if (kind === "number")
         return `z.preprocess(${NUMBER}, ${declared})`;
-    if (declared.startsWith("z.boolean()"))
+    if (kind === "boolean")
         return `z.preprocess(${BOOLEAN}, ${declared})`;
     /**
      * A list whose ELEMENTS are numeric or boolean - `?ids=1,2,3` after the collection split, or a
@@ -596,10 +611,8 @@ function wireDecoded(declared) {
      * the same decoder applies per element. A non-array value is left alone; the split that produces
      * the array runs outside this and may not have happened.
      */
-    const element = /^z\.array\((z\.(?:number|boolean)\(\).*)\)$/s.exec(declared);
-    if (element !== null) {
-        const inner = element[1] ?? "";
-        const decoder = inner.startsWith("z.number()") ? NUMBER : BOOLEAN;
+    if (elementKind !== undefined) {
+        const decoder = elementKind === "number" ? NUMBER : BOOLEAN;
         return `z.preprocess((raw) => (Array.isArray(raw) ? raw.map(${decoder}) : raw), ${declared})`;
     }
     return declared;
@@ -688,7 +701,14 @@ function parameterSchemasOf(program, operation, registry) {
          */
         const decoded = parameter.type === "header" && parameter.name.toLowerCase() === "content-type"
             ? mediaTypeDecoded(declared)
-            : wireDecoded(declared);
+            : wireDecoded(declared, 
+            /**
+             * `@encode` on the PROPERTY changes what crosses the wire, so the encoded type is
+             * the one to read. `@encode("unixTimestamp", int32) value: utcDateTime` is a number
+             * on the wire and a date in the spec, and reading the declared type alone stopped
+             * eighteen such parameters being decoded.
+             */
+            wireKindOf(program, encodedParameterType(program, parameter.param)), elementKindOf(program, encodedParameterType(program, parameter.param)));
         /**
          * The boxing half of the same principle: an exploded array's single occurrence arrives as a
          * bare string, so it is boxed into the one-element array the document describes before the
@@ -875,11 +895,40 @@ export function collectRoutes(program, registry, service) {
  * Emitting the whole set into both would leave unused imports (which lint rejects); emitting it into
  * neither is what left `routes.gen.ts` referencing `isParsableInstant` with no import at all.
  */
+/**
+ * Whether emitted source references `name` as an identifier.
+ *
+ * **The name is ESCAPED before it becomes a pattern, and skipping that is a silent build break.**
+ * This was `new RegExp(`\\b${name}\\b`)`, interpolating an identifier straight into a pattern.
+ * `$` is a valid identifier character in JavaScript and in TypeSpec, and an anchor in a regular
+ * expression, so a name containing one fails to match ITSELF: measured, `foo$bar` and `$select` both
+ * report absent from source that references them verbatim.
+ *
+ * The direction matters. Reporting a name present that is absent yields an unused import, which lint
+ * refuses loudly. Reporting a name ABSENT that is present drops the import and leaves the emitted
+ * module referencing an undeclared identifier - the failure this function exists to prevent, which is
+ * how `routes.gen.ts` once referenced `isParsableInstant` with no import at all.
+ *
+ * Only `SPEC_VOCABULARIES` reaches here today, so the hole was latent rather than live. It sits on a
+ * general seam that any future name flows through, and the reasoning that made it look safe - an
+ * identifier absent from the text is genuinely not needed - is true of the QUESTION and false of the
+ * way it was being asked.
+ */
+export function referencedIn(source, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    /**
+     * Bounded by IDENTIFIER characters rather than `\b`, because `$` is one in JavaScript and not a
+     * word character in a regular expression - so `\b$select\b` never matches `$select`, there being
+     * no word boundary before a `$`. The two failure modes have to be closed together or the fix for
+     * one leaves the other.
+     */
+    return new RegExp(`(?<![A-Za-z0-9_$])${escaped}(?![A-Za-z0-9_$])`).test(source);
+}
 function renderExternalImports(externals, ...bodies) {
     const haystack = bodies.join("\n");
     const lines = [];
     for (const [module, names] of externals) {
-        const used = [...names].filter((name) => new RegExp(`\\b${name}\\b`).test(haystack));
+        const used = [...names].filter((name) => referencedIn(haystack, name));
         if (used.length > 0) {
             lines.push(`import { ${used.toSorted().join(", ")} } from ${JSON.stringify(module)};\n`);
         }

package/dist/src/zod.d.ts

@@ -93,6 +93,24 @@ export declare function effectiveIndexer(model: Model): Model["indexer"];
  * for a real subtype - the same rule that decides whether a base may be sealed.
  */
 export declare function discriminatedSubtypes(program: Program, model: Model): readonly Model[];
+/**
+ * **What JSON kind a value of this type arrives as, for a parameter carried in text.**
+ *
+ * A path, query or header value is always a string on the wire, so a numeric or boolean parameter has
+ * to be decoded before the document's schema runs. Deciding WHICH decoder applies used to be done by
+ * inspecting the emitted Zod - `declared.startsWith("z.number()")` - which is a string about a string
+ * and fails silently the moment the expression is spelled any other way.
+ *
+ * It did. `@query size: 10 | 25 | 50` emits `z.union([z.literal(10), ...])`, which starts with
+ * neither, so no decoder was wrapped around it and the validator required the NUMBER 25 from a wire
+ * that can only deliver `"25"`. Measured: `?size=25` rejected, `size: 25` accepted. Every conformant
+ * caller got a 400, and no document comparison could see it, because both sides agree the parameter
+ * is a number - the disagreement is with the wire.
+ *
+ * Reading the TYPE answers the question the emitted text was standing in for. `SCALARS` remains the
+ * single list of what becomes a number, so this cannot drift from what `scalarToZod` emits.
+ */
+export declare function wireKindOf(program: Program, type: Type): "number" | "boolean" | undefined;
 /**
  * A name as an object key - quoted when it is not a legal JavaScript identifier.
  *

package/dist/src/zod.js

@@ -787,6 +787,59 @@ function modelToZod(program, model) {
         : `z.object(${shape})${suffix}${strict}`;
     return applyConstraints(program, body, model);
 }
+/**
+ * **What JSON kind a value of this type arrives as, for a parameter carried in text.**
+ *
+ * A path, query or header value is always a string on the wire, so a numeric or boolean parameter has
+ * to be decoded before the document's schema runs. Deciding WHICH decoder applies used to be done by
+ * inspecting the emitted Zod - `declared.startsWith("z.number()")` - which is a string about a string
+ * and fails silently the moment the expression is spelled any other way.
+ *
+ * It did. `@query size: 10 | 25 | 50` emits `z.union([z.literal(10), ...])`, which starts with
+ * neither, so no decoder was wrapped around it and the validator required the NUMBER 25 from a wire
+ * that can only deliver `"25"`. Measured: `?size=25` rejected, `size: 25` accepted. Every conformant
+ * caller got a 400, and no document comparison could see it, because both sides agree the parameter
+ * is a number - the disagreement is with the wire.
+ *
+ * Reading the TYPE answers the question the emitted text was standing in for. `SCALARS` remains the
+ * single list of what becomes a number, so this cannot drift from what `scalarToZod` emits.
+ */
+export function wireKindOf(program, type) {
+    if (type.kind === "Scalar") {
+        const encoded = encodedTypeOf(program, type);
+        if (encoded !== undefined && encoded !== type)
+            return wireKindOf(program, encoded);
+        for (let current = type; current !== undefined; current = current.baseScalar) {
+            const mapped = SCALARS[current.name];
+            if (mapped === undefined)
+                continue;
+            if (mapped.startsWith("z.number()"))
+                return "number";
+            if (mapped === "z.boolean()")
+                return "boolean";
+            return undefined;
+        }
+        return undefined;
+    }
+    // A literal is its own type, and a union of them is the enum form a parameter commonly takes.
+    if (type.kind === "Number")
+        return "number";
+    if (type.kind === "Boolean")
+        return "boolean";
+    if (type.kind === "Union") {
+        const kinds = new Set();
+        for (const variant of type.variants.values()) {
+            // `T | null` is still a T on the wire; the null arm needs no decoding.
+            if (variant.type.kind === "Intrinsic" && variant.type.name === "null")
+                continue;
+            kinds.add(wireKindOf(program, variant.type));
+        }
+        if (kinds.size !== 1)
+            return undefined;
+        return [...kinds][0];
+    }
+    return undefined;
+}
 /**
  * A name as an object key - quoted when it is not a legal JavaScript identifier.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.5.0",
+  "version": "0.6.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",