typespec-http-zod 0.29.0 → 0.31.0

package/dist/src/published.d.ts

@@ -0,0 +1,139 @@
+import { type Model, type ModelProperty, type Namespace, type Program, type Type } from "@typespec/compiler";
+import { Visibility, type HttpOperation } from "@typespec/http";
+export declare function withServiceView<T>(program: Program, service: Namespace, run: () => T): T;
+/** The same scope, held across an `await` - returns what puts the previous one back. */
+export declare function beginServiceView(program: Program, service: Namespace): () => void;
+/**
+ * **The types of the service no operation reaches, which openapi3 publishes as components all the
+ * same** - its `processUnreferencedSchemas`, with `omitUnreachableTypes` unset: every model, enum and
+ * union declared in the service namespace and below it (only the service's own, where the service is
+ * the global namespace), but not one an operation reaches, a model whose properties were spread as
+ * parameters (published as parameters), a type openapi3 inlines, an HTTP file, or an authentication
+ * scheme's model. Rendered at `All` by the caller, as openapi3 renders them. A scalar is validated
+ * inline wherever it is used, reached or not, so an unreached one has nothing to declare.
+ */
+export declare function unreachedTypes(): readonly Type[];
+/** Every type the service publishes, reached by an operation or not - read as {@link usageOf} reads it. */
+export declare function publishedTypes(): Iterable<Type>;
+/** Whether openapi3 suffixes this type's component with the visibility it is rendered at. */
+export declare function isSuffixedByUsage(type: Type): boolean;
+/**
+ * An operation's body, part or parameter a walk starts from: `where`, as the diagnostic says it, and
+ * `root`, the name of its type where it has one - wrapped in a visibility template, as
+ * `Create<Outer>`, the request is published from a model of its own and leaves the shared ones alone.
+ */
+interface Via {
+    readonly where: string;
+    readonly root: string | undefined;
+    /** Whether the root is a model, which a visibility template such as `Create<...>` takes. */
+    readonly model: boolean;
+    /** The root itself, where it is a named model or union - see {@link viewRemedyOf}. */
+    readonly type?: Type;
+}
+/**
+ * **The visibility openapi3 reads a model's own properties at, where it publishes the model at
+ * `at`: the visibility the reference it writes the schema from arrived at** - see
+ * {@link publicationOf}. Where nothing reshapes the model there, the two are one schema - anything
+ * else is `split-visibility` - but a type a property refers to is reached at the first, and a list
+ * or a union instance is not reduced: `Mid { tags: Tags }` first sent in a create body and also
+ * returned is published as `Mid`, its `tags` referring to `TagsCreate`. A component is read as
+ * `components.schemas` keeps it, the later of two metadata contexts; a model written out where it
+ * is used, as the context `ignore` writes it. Where no reference wrote it, at `at`.
+ */
+export declare function readVisibilityOf(program: Program, model: Model, at: Visibility, ignore: boolean): Visibility;
+/**
+ * **The visibility of the component the document keeps for a type rendered at `at`.** Where the type
+ * is published at several visibilities under one name - unsuffixed, as openapi3 names a type it
+ * counts at one - `components.schemas` keeps the one written last, and every `$ref` to the name is
+ * to it. `K extends P`, written at `All` by the pass over types no operation reaches and at `Read` by
+ * `P`'s discriminator mapping, is `K` at `Read` in the document; `G extends K`, written out from
+ * `K` at `All`, required a create-only `s` the `K` it refers to leaves out. Elsewhere, `at`.
+ */
+export declare function keptVisibilityOf(type: Type, at: Visibility): Visibility;
+/**
+ * **Every component openapi3 writes, at the visibility it publishes it at, in the metadata context
+ * `components.schemas` keeps** - declared after the routes, so a component no route renders by name
+ * is declared all the same. A model a merge holds is written into the merge here, and openapi3
+ * publishes it as a component of its own: `L1 extends L0 { m: B }` and `L2 extends L1 { m: Sub }`
+ * publish `B` and `Sub`, which had no validator.
+ */
+export declare function publishedComponents(program: Program): readonly {
+    readonly type: Type;
+    readonly at: Visibility;
+    readonly ignore: boolean;
+    readonly binary: boolean;
+}[];
+/**
+ * **The visibility openapi3 publishes a parameter at, where it is not the operation's.** A parameter
+ * spread from a named model is published once, as a shared parameter component, from the first
+ * operation that sends it, and every later one refers to it: `...CommonA` sent by a GET and then by a
+ * POST is read at `Query` for both. Read at each operation's own, the POST was held to a create view
+ * the document does not publish for it.
+ */
+/**
+ * Whether openapi3 publishes a shared route's parameter optional though it is declared required -
+ * see `resolveSharedRouteParameters` - asked of the declaration, before or after openapi3 sets its
+ * `optional`, with one answer.
+ */
+export declare function isSharedRouteOptional(property: ModelProperty): boolean;
+export declare function parameterVisibilityOf(property: ModelProperty): Visibility | undefined;
+/**
+ * **The visibility openapi3 publishes an operation's request at.** Its own, unless it shares its
+ * verb and path with another: openapi3 publishes one operation for the route, every body and
+ * parameter at the first one's visibility, and reports `inconsistent-shared-route-request-visibility`
+ * where they differ - graded against what it publishes, as the maintainer decided.
+ */
+export declare function requestVisibilityOf(program: Program, operation: HttpOperation): Visibility;
+/**
+ * **How openapi3's schema for a model differs from the schema of that model at the visibility it is
+ * rendered at.** openapi3 reads a model's properties at the visibility its first reference arrived
+ * at - `document` here - and its `required` at the one it reduces that to; the schema it means, and
+ * the one rendered here, reads both at the reduced one - `rendered`. Where no reduction intervenes
+ * they are one schema. Only the model's own properties are compared: a type a property refers to has
+ * a first reference of its own, and is judged by it where it is rendered - a component wherever it
+ * is declared, and a model expression where it is written out, as openapi3 writes it out from its
+ * cache. A base is part of the model's schema, through `allOf`.
+ */
+export interface Misreading {
+    /** The model whose properties openapi3 reads at {@link at}: the one judged, or a base of it. */
+    readonly model: Model;
+    /** The property its schema gets wrong. */
+    readonly property: ModelProperty;
+    /** The visibility openapi3 reads the properties at. */
+    readonly at: Visibility;
+    /** What openapi3 publishes for the property. */
+    readonly effect: "undeclared" | "dropped" | "added" | "reshaped";
+    /** Where the schema it is found in was first reached from. */
+    readonly via: Via;
+}
+/**
+ * **Whether the schema rendered for `type` here is one openapi3 publishes differently - and if so,
+ * `split-visibility`, an error, reported once per declaration.** Refused, as the maintainer decided,
+ * rather than validated against a schema the document does not hold: the document's `required` names
+ * a property its properties leave out, which no value satisfies under `seal-object-schemas`, or it
+ * leaves out an optional one, which a sealed schema then refuses.
+ *
+ * `declared` is the component's name, for a type published as a component; `type` is then its
+ * canonical type and `at` the visibility it is declared at. Otherwise `type` is written out where it
+ * is used - a model expression, an inlined template instance - and judged by the emission openapi3
+ * writes out in the metadata context `ignore`.
+ */
+export declare function isSplitByVisibility(program: Program, type: Type, at: Visibility, ignore: boolean, declared: string | undefined): boolean;
+/**
+ * Whether openapi3 publishes the component of `type` at `at` split - the refusal
+ * {@link isSplitByVisibility} reports, asked without reporting it. A dispatch leaves such a subtype
+ * out, as it leaves out one no value is: its validator is `z.never()`, which no
+ * `z.discriminatedUnion` can hold.
+ */
+export declare function isPublishedSplit(program: Program, type: Type, at: Visibility): boolean;
+/** The standard template that is a model's view at a request visibility, where there is one. */
+/**
+ * **The view a remedy names, declared so that it works where it is pasted**: a model of its own,
+ * `model OuterCreate is Create<Ns.Outer>;`, with the type spelled from the global namespace. Named
+ * `Create<Outer>`, the view inherited `Outer`'s `@friendlyName` and collided with it; spelled by the
+ * friendly name, or without its namespace from a sub-namespace, it named nothing; and sent through
+ * a spread, `...Create<O1>`, it left the body the document publishes as it was.
+ */
+export declare function viewRemedyOf(template: string, type: Type): string;
+export declare function viewTemplateOf(at: Visibility): string | undefined;
+export {};