@kubb/ast 5.0.0-alpha.3 → 5.0.0-alpha.30

package/src/nodes/property.ts

@@ -2,11 +2,33 @@ import type { BaseNode } from './base.ts'
 import type { SchemaNode } from './schema.ts'
 
 /**
- * A named property within an object schema.
+ * AST node representing one named object property.
+ *
+ * @example
+ * ```ts
+ * const property: PropertyNode = {
+ *   kind: 'Property',
+ *   name: 'id',
+ *   schema: createSchema({ type: 'integer' }),
+ *   required: true,
+ * }
+ * ```
  */
 export type PropertyNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Property'
+  /**
+   * Property key.
+   */
   name: string
+  /**
+   * Property schema.
+   */
   schema: SchemaNode
+  /**
+   * Whether the property is required.
+   */
   required: boolean
 }

package/src/nodes/response.ts

@@ -3,15 +3,41 @@ import type { MediaType, StatusCode } from './http.ts'
 import type { SchemaNode } from './schema.ts'
 
 /**
- * A single response variant for an operation.
+ * AST node representing one operation response variant.
+ *
+ * @example
+ * ```ts
+ * const response: ResponseNode = {
+ *   kind: 'Response',
+ *   statusCode: '200',
+ *   schema: createSchema({ type: 'string' }),
+ * }
+ * ```
  */
 export type ResponseNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Response'
   /**
    * HTTP status code or `'default'` for a fallback response.
    */
   statusCode: StatusCode
+  /**
+   * Optional response description.
+   */
   description?: string
-  schema?: SchemaNode
-  mediaType?: MediaType
+  /**
+   * Response body schema.
+   */
+  schema: SchemaNode
+  /**
+   * Response media type.
+   */
+  mediaType?: MediaType | null
+  /**
+   * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
+   * Set when a referenced schema has `writeOnly` fields that should not appear in response types.
+   */
+  keysToOmit?: Array<string>
 }

package/src/nodes/root.ts

@@ -3,30 +3,61 @@ import type { OperationNode } from './operation.ts'
 import type { SchemaNode } from './schema.ts'
 
 /**
- * Format-agnostic metadata about the API document.
- * Adapters populate whichever fields are available in their source format.
+ * Basic metadata for an API document.
+ * Adapters fill fields that exist in their source format.
+ *
+ * @example
+ * ```ts
+ * const meta: RootMeta = { title: 'Pet API', version: '1.0.0' }
+ * ```
  */
 export type RootMeta = {
-  /** API title (from `info.title` in OAS/AsyncAPI). */
+  /**
+   * API title (from `info.title` in OAS/AsyncAPI).
+   */
   title?: string
-  /** API version string (from `info.version` in OAS/AsyncAPI). */
+  /**
+   * API description (from `info.description` in OAS/AsyncAPI).
+   */
+  description?: string
+  /**
+   * API version string (from `info.version` in OAS/AsyncAPI).
+   */
   version?: string
   /**
-   * Resolved base URL for the API.
-   * OAS: derived from `servers[serverIndex].url` with variable substitution.
-   * AsyncAPI: derived from `servers[serverIndex].url`.
-   * Drizzle / schema-only formats: not set.
+   * Resolved API base URL.
+   * For OpenAPI and AsyncAPI, this comes from the selected server URL.
    */
   baseURL?: string
 }
 
 /**
- * Top-level container for all schemas and operations in a single API document.
+ * Root AST node that contains all schemas and operations for one API document.
+ *
+ * @example
+ * ```ts
+ * const root: RootNode = {
+ *   kind: 'Root',
+ *   schemas: [],
+ *   operations: [],
+ * }
+ * ```
  */
 export type RootNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Root'
+  /**
+   * All schema nodes in the document.
+   */
   schemas: Array<SchemaNode>
+  /**
+   * All operation nodes in the document.
+   */
   operations: Array<OperationNode>
-  /** Format-agnostic document metadata populated by the adapter. */
+  /**
+   * Optional document metadata populated by the adapter.
+   */
   meta?: RootMeta
 }