typespec-http-zod 0.2.0 → 0.4.0

package/README.md

@@ -146,6 +146,8 @@ carries the whole id, so `op readWidget` in `namespace Widgets` becomes `Widgets
 - [Guides](docs/guides.md): installing, validating a request, answering with the right body, content
   types, and building an emitter on the API.
 - [Reference](docs/reference.md): every option, every diagnostic, and the known limits.
+- [Oracles](docs/oracles.md): every artefact this emitter produces, and what compares it to the
+  thing it has to agree with.
 
 ## Licence
 

package/dist/src/api.js

@@ -517,6 +517,20 @@ const COLLECTION_DELIMITERS = {
 function isCollectionParameter(property) {
     return isArrayType(property.type);
 }
+/**
+ * Whether the values arrive one per OCCURRENCE (RFC 6570 explode) rather than joined into one.
+ *
+ * The distinction matters because of what `zValidator` hands the schema: for a repeated key it
+ * builds an array, but for a single occurrence it hands the bare string - and one `key=value` pair
+ * is exactly what a one-member exploded array looks like on the wire. A bare `z.array()` therefore
+ * refused a conformant request while accepting the same list sent twice, which no document
+ * describes. Found by the first consumer's `?topics=ip` (#1).
+ */
+function isExplodedCollection(parameter) {
+    return (isCollectionParameter(parameter.param) &&
+        (parameter.type === "query" || parameter.type === "header") &&
+        parameter.explode === true);
+}
 /**
  * The delimiter a parameter's values were joined with, or `undefined` when they were not joined.
  *
@@ -675,9 +689,18 @@ function parameterSchemasOf(program, operation, registry) {
         const decoded = parameter.type === "header" && parameter.name.toLowerCase() === "content-type"
             ? mediaTypeDecoded(declared)
             : wireDecoded(declared);
-        const expression = delimiter === undefined
-            ? decoded
-            : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${JSON.stringify(delimiter)}) : raw), ${decoded})`;
+        /**
+         * 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
+         * schema runs - every constraint on the list still applies to the result. Several
+         * occurrences arrive already an array and pass through untouched, exactly as the delimiter
+         * arm leaves a pre-split value alone.
+         */
+        const expression = isExplodedCollection(parameter)
+            ? `z.preprocess((raw) => (typeof raw === "string" ? [raw] : raw), ${decoded})`
+            : delimiter === undefined
+                ? decoded
+                : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${JSON.stringify(delimiter)}) : raw), ${decoded})`;
         const entry = `\t${objectKey(parameter.name)}: ${expression},`;
         (byTarget[parameter.type] ??= []).push(entry);
         /**
@@ -1081,22 +1104,42 @@ function collectRequestTypes(program, registry, service) {
              */
             const extraProperties = operation.parameters.parameters
                 .filter((parameter) => parameter.type === "path" || parameter.type === "query" || parameter.type === "header")
-                .map((parameter) => registry.expressionForProperty(parameter.param));
+                /**
+                 * Named as the WIRE names it, which is what the emitted validator keys on.
+                 * `@header("x-thing") thing: string` is `"x-thing"` in `schemas.gen.ts`, so it has to be
+                 * `"x-thing"` here too: a consumer checking its handlers against these types otherwise
+                 * fails to typecheck against a server that is correct.
+                 */
+                .map((parameter) => registry.expressionForProperty(parameter.param, parameter.name));
             if (body === undefined && extraProperties.length === 0)
                 continue;
             /**
-             * A `bytes` body reaches the use-case as a NAMED property holding the unparsed text, not as
-             * a bare string - so the wire type is `{ rawBody: string }`, matching what a server
-             * actually builds. Referencing the scalar directly would type the whole input as `string`
-             * and quietly drop the headers beside it.
+             * A `bytes` body reaches the use-case as a NAMED property holding the unparsed body, not as
+             * a bare value, so the wire type is `{ rawBody: ... }`, matching what a server actually
+             * builds. Referencing the scalar directly would type the whole input as that value and
+             * quietly drop the headers beside it.
              */
             const rawBody = body?.kind === "Scalar" && body.name === "bytes"
                 ? (operation.parameters.body?.property?.name ?? "body")
                 : undefined;
+            /**
+             * **Raw binary is `ArrayBuffer`; base64 inside a JSON payload is `string`.** The same
+             * `isRawBinaryMediaType` rule the response side and the multipart parts already follow,
+             * applied here for the first time.
+             *
+             * This type said `string` for every `bytes` body whatever it was served as. A server reading
+             * an `application/octet-stream` body hands the handler bytes, so a consumer checking its
+             * handlers against these types could not typecheck against a correct server. It is the
+             * request half of the corruption already fixed on the reader: decoding raw bytes as text
+             * replaces every byte outside ASCII, and typing them as text is what invites it.
+             */
+            const rawBodyType = isRawBinaryMediaType([...(operation.parameters.body?.contentTypes ?? [])])
+                ? "ArrayBuffer"
+                : "string";
             entries.push({
                 operationId: resolveOperationId(program, operation.operation),
                 bodyRef: rawBody !== undefined
-                    ? `{\n\t${rawBody}: string;\n}`
+                    ? `{\n\t${rawBody}: ${rawBodyType};\n}`
                     : body === undefined
                         ? undefined
                         : registry.expressionFor(body),

package/dist/src/registry.d.ts

@@ -112,7 +112,8 @@ export declare class TypeRegistry {
      * `ModelProperty`s belonging to no model. Without routing them through the registry a named model
      * or enum in a parameter position is inlined rather than referenced.
      */
-    expressionForProperty(property: ModelProperty): string;
+    /** `wireName` names an HTTP parameter as the wire does - see {@link propertyToTs}. */
+    expressionForProperty(property: ModelProperty, wireName?: string): string;
     /** Every declaration, dependencies first. */
     declarations(): readonly TsDeclaration[];
 }

package/dist/src/registry.js

@@ -404,12 +404,13 @@ export class TypeRegistry {
      * `ModelProperty`s belonging to no model. Without routing them through the registry a named model
      * or enum in a parameter position is inlined rather than referenced.
      */
-    expressionForProperty(property) {
+    /** `wireName` names an HTTP parameter as the wire does - see {@link propertyToTs}. */
+    expressionForProperty(property, wireName) {
         return withTsRefResolver((candidate) => {
             if (declaredNameOf(candidate) === undefined)
                 return undefined;
             return this.expressionFor(candidate);
-        }, () => propertyToTs(this.#program, property));
+        }, () => propertyToTs(this.#program, property, wireName));
     }
     #inline(type) {
         return withTsRefResolver((candidate) => {

package/dist/src/types.d.ts

@@ -1,6 +1,15 @@
 import { type ModelProperty, type Program, type Type } from "@typespec/compiler";
-/** A property line, including its optionality marker. */
-export declare function propertyToTs(program: Program, property: ModelProperty): string;
+/**
+ * A property line, including its optionality marker.
+ *
+ * `wireName` overrides the key for an HTTP PARAMETER, whose wire name comes from `@header("x-thing")`
+ * or `@query("$select")` rather than from any JSON encoding. `resolveEncodedName` cannot see those,
+ * so a header renamed on the wire was keyed here by its TypeScript property name while the emitted
+ * validator keyed it by the wire name. A consumer checking its handlers against the generated input
+ * types then failed to typecheck against a server that was correct: `z.object({ "x-thing": ... })`
+ * on one side and `{ thing: string }` on the other.
+ */
+export declare function propertyToTs(program: Program, property: ModelProperty, wireName?: string): string;
 export declare function withTsRefResolver<T>(resolver: (type: Type) => string | undefined, run: () => T): T;
 export declare function typeToTs(program: Program, type: Type): string;
 /**

package/dist/src/types.js

@@ -199,11 +199,20 @@ function modelToTs(program, model) {
      */
     return entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
 }
-/** A property line, including its optionality marker. */
-export function propertyToTs(program, property) {
+/**
+ * A property line, including its optionality marker.
+ *
+ * `wireName` overrides the key for an HTTP PARAMETER, whose wire name comes from `@header("x-thing")`
+ * or `@query("$select")` rather than from any JSON encoding. `resolveEncodedName` cannot see those,
+ * so a header renamed on the wire was keyed here by its TypeScript property name while the emitted
+ * validator keyed it by the wire name. A consumer checking its handlers against the generated input
+ * types then failed to typecheck against a server that was correct: `z.object({ "x-thing": ... })`
+ * on one side and `{ thing: string }` on the other.
+ */
+export function propertyToTs(program, property, wireName) {
     // The WIRE name, resolved exactly as `zod.ts` resolves it - `wire-contract.gen.ts` asserts the
     // emitted Zod infers this type, so the two must name every property identically or it fails.
-    const key = objectKey(resolveEncodedName(program, property, "application/json"));
+    const key = objectKey(wireName ?? resolveEncodedName(program, property, "application/json"));
     // `@encode` changes the wire TYPE, resolved exactly as `zod.ts` resolves it - a property encoded as
     // a string on one side and an array on the other fails the emitted assertion, and deserves to.
     const encoded = getEncode(program, property)?.type;

package/package.json

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