@kubb/ast 5.17.0 → 5.18.0

package/dist/index.d.ts

@@ -293,6 +293,16 @@ type SchemaNodeBase = BaseNode & {
    * Schema `format` value.
    */
   format?: string;
+  externalDocs?: ExternalDocs;
+  /**
+   * `if`/`then`/`else`, `dependentRequired` and `dependentSchemas`. A required `unknown` property in `if` means "key is present".
+   * Visitors do not walk it.
+   */
+  conditionals?: Array<{
+    if: SchemaNode;
+    then?: SchemaNode;
+    else?: SchemaNode;
+  }>;
 };
 /**
  * Object schema with ordered properties.
@@ -349,10 +359,18 @@ type ObjectSchemaNode = SchemaNodeBase & {
   /**
    * Minimum number of properties allowed.
    */
-  minProperties?: number;
+  min?: number;
   /**
    * Maximum number of properties allowed.
    */
+  max?: number;
+  /**
+   * @deprecated Use `min`. Removed in Kubb v6.
+   */
+  minProperties?: number;
+  /**
+   * @deprecated Use `max`. Removed in Kubb v6.
+   */
   maxProperties?: number;
 };
 /**
@@ -392,6 +410,14 @@ type ArraySchemaNode = SchemaNodeBase & {
    * Whether all items must be unique.
    */
   unique?: boolean;
+  /**
+   * At least `min` (default 1) and at most `max` items match `schema`. Visitors do not walk `schema`.
+   */
+  contains?: {
+    schema: SchemaNode;
+    min?: number;
+    max?: number;
+  };
 };
 /**
  * Shared shape for union and intersection schemas.
@@ -627,6 +653,14 @@ type StringSchemaNode = SchemaNodeBase & {
    * Regex pattern.
    */
   pattern?: string;
+  /**
+   * The value the string encodes, such as a JSON document or `base64` bytes. Visitors do not walk `schema`.
+   */
+  content?: {
+    mediaType?: string;
+    encoding?: string;
+    schema?: SchemaNode;
+  };
 };
 /**
  * Numeric schema (`number`, `integer`, or `bigint`).
@@ -650,11 +684,18 @@ type NumberSchemaNode = SchemaNodeBase & {
    */
   max?: number;
   /**
-   * Exclusive minimum value.
+   * Bounds the value may not equal: it must be greater than `min` and less than `max`.
+   */
+  exclusive?: {
+    min?: number;
+    max?: number;
+  };
+  /**
+   * @deprecated Use `exclusive.min`. Removed in Kubb v6.
    */
   exclusiveMinimum?: number;
   /**
-   * Exclusive maximum value.
+   * @deprecated Use `exclusive.max`. Removed in Kubb v6.
    */
   exclusiveMaximum?: number;
   /**
@@ -801,6 +842,7 @@ type InputServerVariable = {
  */
 type InputServer = {
   url: string;
+  name?: string;
   description?: string;
   /**
    * Variables of the source URL template, copied as-is. `url` already has their defaults filled in, so
@@ -808,18 +850,66 @@ type InputServer = {
    */
   variables?: Record<string, InputServerVariable>;
 };
+type ExternalDocs = {
+  url: string;
+  description?: string;
+};
+type InputTag = {
+  name: string;
+  summary?: string;
+  description?: string;
+  /**
+   * Name of the tag this tag nests under. `group: { type: 'tag' }` places its files in the parent's folder.
+   */
+  parent?: string;
+  kind?: string;
+  externalDocs?: ExternalDocs;
+};
+type OAuthFlow = {
+  authorizationUrl?: string;
+  deviceAuthorizationUrl?: string;
+  tokenUrl?: string;
+  refreshUrl?: string;
+  scopes?: Record<string, string>;
+};
+/**
+ * How a client sends a credential, in the same shape as the `Auth` object the generated clients pass to `auth`.
+ */
+type AuthCredential = {
+  type: 'http';
+  scheme: 'bearer' | 'basic' | (string & {});
+  bearerFormat?: string;
+} | {
+  type: 'apiKey';
+  in: 'header' | 'query' | 'cookie';
+  name: string;
+} | {
+  type: 'oauth2';
+  flows: Record<string, OAuthFlow>;
+  metadataUrl?: string;
+} | {
+  type: 'openIdConnect';
+  url?: string;
+} | {
+  type: 'mutualTLS';
+};
 /**
- * An authentication scheme from the source document, keyed by `name`. `parameterName` is the header, query, or cookie name of an `apiKey`.
+ * One way to authenticate, keyed by `name`, which operations refer to in `auth`.
  */
-type InputSecurityScheme = {
+type AuthScheme = {
   name: string;
-  type: string;
   description?: string;
-  scheme?: string;
-  bearerFormat?: string;
-  in?: string;
-  parameterName?: string;
+  deprecated?: boolean;
+  credential: AuthCredential;
 };
+/**
+ * One way to meet an operation's auth. Every scheme in it applies together. `scopes` are the OAuth2 or OpenID
+ * Connect scopes the call needs. An empty list means the call may be sent without credentials.
+ */
+type AuthRequirement = Array<{
+  scheme: string;
+  scopes?: Array<string>;
+}>;
 /**
  * Metadata for an API document, populated by the adapter and available to every generator.
  * Every field is a plain JSON value.
@@ -842,12 +932,26 @@ type InputMeta = {
    * API version string from `info.version` in the source document.
    */
   version?: string;
+  summary?: string;
+  termsOfService?: string;
+  contact?: {
+    name?: string;
+    url?: string;
+    email?: string;
+  };
+  license?: {
+    name: string;
+    identifier?: string;
+    url?: string;
+  };
+  externalDocs?: ExternalDocs;
   /**
    * Resolved base URL from the first matching server entry in the source document.
    */
   baseURL?: string | null;
   servers?: Array<InputServer>;
-  securitySchemes?: Array<InputSecurityScheme>;
+  tags?: Array<InputTag>;
+  auth?: Array<AuthScheme>;
   /**
    * Vendor extensions (`x-*` keys) from the document root, copied as-is. Absent when the root has none.
    */
@@ -896,83 +1000,6 @@ type InputNode = BaseNode & {
  * ```
  */
 declare function createInput(overrides?: Partial<Omit<InputNode, 'kind'>>): InputNode;
-/**
- * Where a parameter is sent. `querystring` carries the whole query string as one value, serialized per `contentType`.
- */
-type ParameterLocation = 'path' | 'query' | 'header' | 'cookie' | 'querystring';
-/**
- * Parameter serialization style, controlling how a parameter value is rendered into the request.
- */
-type ParameterStyle = 'matrix' | 'label' | 'form' | 'simple' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
-/**
- * AST node representing one operation parameter.
- *
- * @example
- * ```ts
- * const param: ParameterNode = {
- *   kind: 'Parameter',
- *   name: 'petId',
- *   in: 'path',
- *   schema: createSchema({ type: 'string' }),
- *   required: true,
- * }
- * ```
- */
-type ParameterNode = BaseNode & {
-  kind: 'Parameter';
-  /**
-   * Parameter name.
-   */
-  name: string;
-  /**
-   * Parameter location (`path`, `query`, `header`, `cookie`, or `querystring`).
-   */
-  in: ParameterLocation;
-  /**
-   * Parameter schema.
-   */
-  schema: SchemaNode;
-  /**
-   * Whether the parameter is required.
-   */
-  required: boolean;
-  /**
-   * Serialization style. Absent when the source omits it, leaving consumers to apply the
-   * per-location default.
-   */
-  style?: ParameterStyle;
-  /**
-   * Whether array and object values expand into separate values. Absent when the source omits it,
-   * leaving consumers to apply the default for the style.
-   */
-  explode?: boolean;
-  /**
-   * Whether reserved characters (RFC 3986 `:/?#[]@!$&'()*+,;=`) are sent as-is instead of
-   * percent-encoded. Only applies to query parameters. Absent when the source omits it.
-   */
-  allowReserved?: boolean;
-  /**
-   * Media type of a parameter described with `content` instead of `schema`, for example
-   * `application/json` when the value is sent as a JSON-encoded string. Absent for `schema` parameters.
-   */
-  contentType?: string;
-};
-type UserParameterNode = Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>;
-/**
- * Creates a `ParameterNode`. `required` defaults to `false`, and the schema's
- * `optional`/`nullish` flags are derived from it.
- *
- * @example
- * ```ts
- * const param = createParameter({
- *   name: 'petId',
- *   in: 'path',
- *   required: true,
- *   schema: createSchema({ type: 'string' }),
- * })
- * ```
- */
-declare function createParameter(input: UserParameterNode): ParameterNode;
 /**
  * How one body property is serialized, from the `encoding` entry of its media type.
  */
@@ -993,6 +1020,16 @@ type EncodingNode = {
    * Whether reserved characters are sent as-is instead of percent-encoded.
    */
   allowReserved?: boolean;
+  encoding?: Record<string, EncodingNode>;
+  prefixEncoding?: Array<EncodingNode>;
+  itemEncoding?: EncodingNode;
+};
+type ExampleNode = {
+  name?: string;
+  summary?: string;
+  description?: string;
+  value?: unknown;
+  serializedValue?: string;
 };
 /**
  * AST node representing one content-type entry of a request body or response.
@@ -1015,7 +1052,7 @@ type ContentNode = BaseNode & {
    */
   kind: 'Content';
   /**
-   * The content type for this entry (e.g. `'application/json'`).
+   * The content type for this entry (e.g. `'application/json'`), or `''` for a response without a body.
    */
   contentType: string;
   /**
@@ -1046,11 +1083,100 @@ type ContentNode = BaseNode & {
    * Serialization settings per body property that sets at least one field in the spec's `encoding`.
    */
   encoding?: Record<string, EncodingNode>;
+  examples?: Array<ExampleNode>;
+  /**
+   * Serialization of the first parts by position, for a body sent as an array of parts such as `multipart/mixed`.
+   */
+  prefixEncoding?: Array<EncodingNode>;
+  /**
+   * Serialization of every part after `prefixEncoding`, for a body sent as an array of parts such as `multipart/mixed`.
+   */
+  itemEncoding?: EncodingNode;
 };
 /**
  * Creates a `ContentNode` for a single request-body or response content type.
  */
 declare const createContent: (input: Omit<ContentNode, "kind">) => ContentNode;
+/**
+ * Where a parameter is sent. `querystring` carries the whole query string as one value, serialized per `contentType`.
+ */
+type ParameterLocation = 'path' | 'query' | 'header' | 'cookie' | 'querystring';
+/**
+ * Parameter serialization style, controlling how a parameter value is rendered into the request.
+ */
+type ParameterStyle = 'matrix' | 'label' | 'form' | 'simple' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject' | 'cookie';
+/**
+ * AST node representing one operation parameter.
+ *
+ * @example
+ * ```ts
+ * const param: ParameterNode = {
+ *   kind: 'Parameter',
+ *   name: 'petId',
+ *   in: 'path',
+ *   schema: createSchema({ type: 'string' }),
+ *   required: true,
+ * }
+ * ```
+ */
+type ParameterNode = BaseNode & {
+  kind: 'Parameter';
+  /**
+   * Parameter name.
+   */
+  name: string;
+  /**
+   * Parameter location (`path`, `query`, `header`, `cookie`, or `querystring`).
+   */
+  in: ParameterLocation;
+  /**
+   * Parameter schema.
+   */
+  schema: SchemaNode;
+  /**
+   * Whether the parameter is required.
+   */
+  required: boolean;
+  /**
+   * Serialization style. Absent when the source omits it, leaving consumers to apply the
+   * per-location default.
+   */
+  style?: ParameterStyle;
+  /**
+   * Whether array and object values expand into separate values. Absent when the source omits it,
+   * leaving consumers to apply the default for the style.
+   */
+  explode?: boolean;
+  /**
+   * Whether reserved characters (RFC 3986 `:/?#[]@!$&'()*+,;=`) are sent as-is instead of
+   * percent-encoded. Absent when the source omits it.
+   */
+  allowReserved?: boolean;
+  /**
+   * Media type of a parameter described with `content` instead of `schema`, for example
+   * `application/json` when the value is sent as a JSON-encoded string. Absent for `schema` parameters.
+   */
+  contentType?: string;
+  examples?: Array<ExampleNode>;
+  deprecated?: boolean;
+  allowEmptyValue?: boolean;
+};
+type UserParameterNode = Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>;
+/**
+ * Creates a `ParameterNode`. `required` defaults to `false`, and the schema's
+ * `optional`/`nullish` flags are derived from it.
+ *
+ * @example
+ * ```ts
+ * const param = createParameter({
+ *   name: 'petId',
+ *   in: 'path',
+ *   required: true,
+ *   schema: createSchema({ type: 'string' }),
+ * })
+ * ```
+ */
+declare function createParameter(input: UserParameterNode): ParameterNode;
 /**
  * AST node representing an operation request body.
  *
@@ -1095,7 +1221,7 @@ type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
 /**
  * Response status code literal used by operations.
  *
- * Includes three-digit HTTP status code strings and `"default"` for catch-all responses.
+ * Includes three-digit HTTP status code strings, ranges such as `"2XX"`, and `"default"` for catch-all responses.
  *
  * @example
  * ```ts
@@ -1103,7 +1229,7 @@ type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
  * const fallback: StatusCode = 'default'
  * ```
  */
-type StatusCode = `${1 | 2 | 3 | 4 | 5}${Digit}${Digit}` | 'default';
+type StatusCode = `${1 | 2 | 3 | 4 | 5}${Digit}${Digit}` | `${1 | 2 | 3 | 4 | 5}XX` | 'default';
 /**
  * AST node representing one operation response variant.
  *
@@ -1129,6 +1255,7 @@ type ResponseNode = BaseNode & {
    * HTTP status code or `'default'` for a fallback response.
    */
   statusCode: StatusCode;
+  summary?: string;
   /**
    * Optional response description.
    */
@@ -1136,10 +1263,11 @@ type ResponseNode = BaseNode & {
   /**
    * All available content type entries for this response.
    *
-   * When the adapter `contentType` option is set, this array contains exactly one entry for that
-   * content type. Otherwise it contains one entry per content type declared in the spec, so that
-   * plugins can generate a union of response types (e.g. `application/json` and `application/xml`).
-   * Body-less responses keep a single entry whose `schema` is the empty/`void` placeholder.
+   * For a response that declares content, the array holds exactly one entry for the adapter
+   * `contentType` option when it is set. Otherwise it holds one entry per content type declared in
+   * the spec, so that plugins can generate a union of response types (e.g. `application/json` and
+   * `application/xml`). A body-less response always keeps a single entry whose `contentType` is `''`
+   * and whose `schema` is the empty/`void` placeholder, even when the option is set.
    *
    * @example
    * ```ts
@@ -1149,6 +1277,22 @@ type ResponseNode = BaseNode & {
    * ```
    */
   content?: Array<ContentNode>;
+  /**
+   * Response headers, as `in: 'header'` parameters. `Content-Type` is left out.
+   */
+  headers?: Array<ParameterNode>;
+  links?: Record<string, ResponseLink>;
+};
+/**
+ * A link to another operation. `parameters` and `requestBody` hold runtime expressions such as `$response.body#/id`.
+ */
+type ResponseLink = {
+  operationId?: string;
+  operationRef?: string;
+  parameters?: Record<string, unknown>;
+  requestBody?: unknown;
+  description?: string;
+  server?: InputServer;
 };
 type ResponseInput = Pick<ResponseNode, 'statusCode'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'content'>> & {
   content?: Array<ContentNode>;
@@ -1203,6 +1347,7 @@ type OperationNodeBase = BaseNode & {
    * Marks the operation as deprecated.
    */
   deprecated?: boolean;
+  externalDocs?: ExternalDocs;
   /**
    * Query, path, header, and cookie parameters for the operation.
    */
@@ -1221,6 +1366,10 @@ type OperationNodeBase = BaseNode & {
   extensions?: Record<string, unknown>;
   /** The operation's own `servers`, else its path item's, such as an upload host. Absent when neither declares any. */
   servers?: Array<InputServer>;
+  /**
+   * Ways to authenticate, from the operation or else the document. Any one entry is enough. `[]` means no auth.
+   */
+  auth?: Array<AuthRequirement>;
 };
 /**
  * Operation served over HTTP. `method` and `path` are guaranteed.
@@ -2672,7 +2821,7 @@ type ParserOptions = {
   enumSuffix: 'enum' | (string & {});
 };
 declare namespace index_d_exports {
-  export { ArraySchemaNode, ArrowFunctionNode, BreakNode, CodeNode, ConstNode, ContentNode, DateOnlyTypeValue, DateSchemaNode, DateTimeTypeValue, DateTypeOptions, DatetimeSchemaNode, DistributiveOmit, EncodingNode, Enforce, EnumSchemaNode, ExportNode, FileNode, FunctionNode, GenericOperationNode, HttpMethod, HttpOperationNode, ImportNode, InlineLanguage, InputMeta, InputNode, InputSecurityScheme, InputServer, IntersectionSchemaNode, JSDocNode, JsxNode, Macro, Node, NodeKind, NotSchemaNode, NumberSchemaNode, ObjectSchemaNode, OperationNode, ParameterLocation, ParameterNode, ParameterStyle, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, RequestBodyNode, ResponseNode, ScalarSchemaNode, ScalarSchemaType, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, applyMacros, index_d_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, compareEnforce, createPrinter, defineMacro, extractStringsFromNodes, index_d_exports$1 as factory, findCircularSchemas, findSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, inlineFiles, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, nodeKinds, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
+  export { ArraySchemaNode, ArrowFunctionNode, AuthCredential, AuthRequirement, AuthScheme, BreakNode, CodeNode, ConstNode, ContentNode, DateOnlyTypeValue, DateSchemaNode, DateTimeTypeValue, DateTypeOptions, DatetimeSchemaNode, DistributiveOmit, EncodingNode, Enforce, EnumSchemaNode, ExampleNode, ExportNode, ExternalDocs, FileNode, FunctionNode, GenericOperationNode, HttpMethod, HttpOperationNode, ImportNode, InlineLanguage, InputMeta, InputNode, InputServer, InputTag, IntersectionSchemaNode, JSDocNode, JsxNode, Macro, Node, NodeKind, NotSchemaNode, NumberSchemaNode, OAuthFlow, ObjectSchemaNode, OperationNode, ParameterLocation, ParameterNode, ParameterStyle, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, RequestBodyNode, ResponseLink, ResponseNode, ScalarSchemaNode, ScalarSchemaType, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, applyMacros, index_d_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, compareEnforce, createPrinter, defineMacro, extractStringsFromNodes, index_d_exports$1 as factory, findCircularSchemas, findSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, inlineFiles, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, nodeKinds, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
 }
-export { type ArraySchemaNode, type ArrowFunctionNode, type BreakNode, type CodeNode, type ConstNode, type ContentNode, type DateOnlyTypeValue, type DateSchemaNode, type DateTimeTypeValue, type DateTypeOptions, type DatetimeSchemaNode, type DistributiveOmit, type EncodingNode, type Enforce, type EnumSchemaNode, type ExportNode, type FileNode, type FunctionNode, type GenericOperationNode, type HttpMethod, type HttpOperationNode, type ImportNode, type InlineLanguage, type InputMeta, type InputNode, type InputSecurityScheme, type InputServer, type IntersectionSchemaNode, type JSDocNode, type JsxNode, type Macro, type Node, type NodeKind, type NotSchemaNode, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, type ParameterLocation, type ParameterNode, type ParameterStyle, type ParserOptions, type PrimitiveSchemaType, type Printer, type PrinterFactoryOptions, type PrinterPartial, type PropertyNode, type RefSchemaNode, type RequestBodyNode, type ResponseNode, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, type UserFileNode, type Visitor, type VisitorContext, index_d_exports as ast, index_d_exports$1 as factory };
+export { type ArraySchemaNode, type ArrowFunctionNode, type AuthCredential, type AuthRequirement, type AuthScheme, type BreakNode, type CodeNode, type ConstNode, type ContentNode, type DateOnlyTypeValue, type DateSchemaNode, type DateTimeTypeValue, type DateTypeOptions, type DatetimeSchemaNode, type DistributiveOmit, type EncodingNode, type Enforce, type EnumSchemaNode, type ExampleNode, type ExportNode, type ExternalDocs, type FileNode, type FunctionNode, type GenericOperationNode, type HttpMethod, type HttpOperationNode, type ImportNode, type InlineLanguage, type InputMeta, type InputNode, type InputServer, type InputTag, type IntersectionSchemaNode, type JSDocNode, type JsxNode, type Macro, type Node, type NodeKind, type NotSchemaNode, type NumberSchemaNode, type OAuthFlow, type ObjectSchemaNode, type OperationNode, type ParameterLocation, type ParameterNode, type ParameterStyle, type ParserOptions, type PrimitiveSchemaType, type Printer, type PrinterFactoryOptions, type PrinterPartial, type PropertyNode, type RefSchemaNode, type RequestBodyNode, type ResponseLink, type ResponseNode, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, type UserFileNode, type Visitor, type VisitorContext, index_d_exports as ast, index_d_exports$1 as factory };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -188,7 +188,7 @@ const VISITOR_KEYS = {
 	],
 	RequestBody: ["content"],
 	Content: ["schema", "stream"],
-	Response: ["content"],
+	Response: ["content", "headers"],
 	Schema: [
 		"properties",
 		"items",