typespec-http-zod 0.28.0 → 0.30.0

package/dist/src/api.d.ts

@@ -48,6 +48,12 @@ export { EmitterOptionsSchema, type EmitterOptions } from "./lib.js";
  * independently.
  */
 export { jsDocComment, objectKey } from "./zod.js";
+/**
+ * And the same for a VALUE written into emitted code: a string, enum value or media type as a literal
+ * whose source is ASCII. Spec text outside ASCII is the case, and a sibling emitter spelling it with a
+ * bare `JSON.stringify` writes the character itself into a file its consumer commits.
+ */
+export { literal } from "./literal.js";
 export declare function beginBanner(hint: string | undefined): void;
 /**
  * The status a row registers: the first non-error status the operation declares.
@@ -238,6 +244,32 @@ export interface EmittedRoute {
      * `unsupported`: no segment router can split it.
      */
     readonly pathSegments: readonly EmittedPathSegment[];
+    /**
+     * **The path parameters whose validator undoes an RFC 6570 expansion**, by wire name.
+     *
+     * For these, the path validator's field is `z.preprocess(<decode>, <value schema>)`: it takes the
+     * TEXT of the segment a router extracts - `primitive.a` for `{.param}` - and hands on the value,
+     * `a`. A caller already holding the value, such as a tool call or a service-binding request, must
+     * validate it against the value schema, `pathSchema.shape[name].out`: through the decoder, the value
+     * `a` is refused as not the expansion the route declares, and a value that happens to start with
+     * the route's literal is rewritten without an error. Decided by the same rule the validator is
+     * built by: a prefix or suffix in the segment, the `.` or `;` operator, or a parameter that is not
+     * a scalar. Empty when there is none, never `undefined`.
+     */
+    readonly decodedPathParameters: readonly string[];
+    /**
+     * Every pair of inputs a handler would be handed under ONE key - `@header("x")` beside
+     * `@query("x")`, two `@query("x")`, a `@path id` beside a `@header("id")`, a parameter named as
+     * the body is. Empty for almost every operation.
+     *
+     * **A server emitter spreads the parameter groups into one input, so the later group's value
+     * silently replaced the earlier one**, after each had been validated against its own schema.
+     * `@typespec/http` refuses only a path and a query parameter of one name. The handler input has
+     * one value per key and cannot carry both, so a server should not mount such an operation; this
+     * package reports it as `shared-input-key`, and states the key as both declarations at once. See
+     * {@link SharedInputKey}.
+     */
+    readonly sharedInputKeys: readonly SharedInputKey[];
     /**
      * A query string written into the route itself, as the pairs it spells:
      * `/items?fixed=true{&param}` carries `[["fixed", "true"]]`. It identifies the route as much as
@@ -420,6 +452,17 @@ export interface EmittedRoute {
      */
     readonly security: readonly SecurityRequirement[];
 }
+/** Where a value reaches a handler's input from. */
+export type InputLocation = "path" | "query" | "header" | "cookie" | "body";
+/** Two inputs a handler would be handed under one key. See {@link EmittedRoute.sharedInputKeys}. */
+export interface SharedInputKey {
+    /** The key both arrive under, as the input spells it. */
+    readonly key: string;
+    /** Where the input declared first comes from. */
+    readonly first: InputLocation;
+    /** Where the input declared second comes from. */
+    readonly second: InputLocation;
+}
 export declare function collectRoutes(program: Program, registry: SchemaRegistry, service: HttpService): EmittedRoute[];
 /** Whether emitted source references `name` as an identifier rather than as part of a longer one. */
 export declare function referencedIn(source: string, name: string): boolean;