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

package/dist/index.d.ts

@@ -1,44 +1,310 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
-import { D as OperationNode, J as SchemaNodeByType, N as ParameterNode, O as ResponseNode, S as createSchema, T as RootNode, _ as createOperation, a as transform, at as mediaTypes, b as createResponse, c as buildRefMap, et as PropertyNode, h as definePrinter, i as collect, it as httpMethods, l as refMapToObject, o as walk, ot as nodeKinds, q as SchemaNode, st as schemaTypes, u as resolveRef, v as createParameter, x as createRoot, y as createProperty } from "./visitor-oFfdU8QA.js";
+import { A as createTypeNode, At as schemaTypes, C as createOperation, D as createResponse, Dt as httpMethods, E as createProperty, G as ParameterNode, O as createRoot, Ot as isScalarPrimitive, P as ParserOptions, S as createFunctionParameters, T as createParameterGroup, Tt as ScalarPrimitive, _ as PrinterPartial, bt as FunctionParametersNode, ct as SchemaNode, d as transform, f as walk, g as PrinterFactoryOptions, h as Printer, j as syncOptionality, k as createSchema, kt as mediaTypes, l as collect, lt as SchemaNodeByType, m as extractRefName, u as composeTransformers, v as createPrinterFactory, w as createParameter, x as createFunctionParameter, xt as ParameterGroupNode, y as definePrinter, yt as FunctionParameterNode, z as OperationNode } from "./visitor-z-5U8NoF.js";
 
 //#region src/guards.d.ts
 /**
- * Narrows a `SchemaNode` to the specific variant matching `type`.
+ * Narrows a `SchemaNode` to the variant that matches `type`.
+ *
+ * @example
+ * ```ts
+ * const schema = createSchema({ type: 'string' })
+ * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | undefined
+ * ```
  */
 declare function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | undefined;
 /**
- * Type guard for `RootNode`.
- */
-declare const isRootNode: (node: unknown) => node is RootNode;
-/**
- * Type guard for `OperationNode`.
+ * Returns `true` when the input is an `OperationNode`.
+ *
+ * @example
+ * ```ts
+ * if (isOperationNode(node)) {
+ *   console.log(node.operationId)
+ * }
+ * ```
  */
 declare const isOperationNode: (node: unknown) => node is OperationNode;
 /**
- * Type guard for `SchemaNode`.
+ * Returns `true` when the input is a `SchemaNode`.
+ *
+ * @example
+ * ```ts
+ * if (isSchemaNode(node)) {
+ *   console.log(node.type)
+ * }
+ * ```
  */
 declare const isSchemaNode: (node: unknown) => node is SchemaNode;
+//#endregion
+//#region src/resolvers.d.ts
+declare function findDiscriminator(mapping: Record<string, string> | undefined, ref: string | undefined): string | null;
+declare function childName(parentName: string | null | undefined, propName: string): string | null;
+declare function enumPropName(parentName: string | null | undefined, propName: string, enumSuffix: string): string;
+/**
+ * Collects import entries for all `ref` schema nodes in `node`.
+ */
+declare function collectImports<TImport>({
+  node,
+  nameMapping,
+  resolve
+}: {
+  node: SchemaNode;
+  nameMapping: Map<string, string>;
+  resolve: (schemaName: string) => TImport | undefined;
+}): Array<TImport>;
+//#endregion
+//#region src/transformers.d.ts
 /**
- * Type guard for `PropertyNode`.
+ * Replaces a discriminator property's schema with a string enum of allowed values.
+ *
+ * If `node` is not an object schema, or if the property does not exist, the input
+ * node is returned as-is.
+ *
+ * @example
+ * ```ts
+ * const schema = createSchema({
+ *   type: 'object',
+ *   properties: [createProperty({ name: 'type', required: true, schema: createSchema({ type: 'string' }) })],
+ * })
+ * const result = setDiscriminatorEnum({ node: schema, propertyName: 'type', values: ['dog', 'cat'] })
+ * ```
  */
-declare const isPropertyNode: (node: unknown) => node is PropertyNode;
+declare function setDiscriminatorEnum({
+  node,
+  propertyName,
+  values,
+  enumName
+}: {
+  node: SchemaNode;
+  propertyName: string;
+  values: Array<string>;
+  enumName?: string;
+}): SchemaNode;
 /**
- * Type guard for `ParameterNode`.
+ * Merges adjacent anonymous object members into a single anonymous object member.
+ *
+ * @example
+ * ```ts
+ * const merged = mergeAdjacentObjects([
+ *   createSchema({ type: 'object', properties: [createProperty({ name: 'a', schema: createSchema({ type: 'string' }) })] }),
+ *   createSchema({ type: 'object', properties: [createProperty({ name: 'b', schema: createSchema({ type: 'number' }) })] }),
+ * ])
+ * ```
  */
-declare const isParameterNode: (node: unknown) => node is ParameterNode;
+declare function mergeAdjacentObjects(members: Array<SchemaNode>): Array<SchemaNode>;
 /**
- * Type guard for `ResponseNode`.
+ * Removes enum members that are covered by broader scalar primitives in the same union.
+ *
+ * @example
+ * ```ts
+ * const simplified = simplifyUnion([
+ *   createSchema({ type: 'enum', primitive: 'string', enumValues: ['active'] }),
+ *   createSchema({ type: 'string' }),
+ * ])
+ * // keeps only string member
+ * ```
  */
-declare const isResponseNode: (node: unknown) => node is ResponseNode;
+declare function simplifyUnion(members: Array<SchemaNode>): Array<SchemaNode>;
+declare function setEnumName(propNode: SchemaNode, parentName: string | null | undefined, propName: string, enumSuffix: string): SchemaNode;
 //#endregion
 //#region src/utils.d.ts
 /**
- * Returns `true` when a schema node will be represented as a plain string in generated code.
+ * Returns a merged schema view for a ref node, combining the resolved `node.schema`
+ * (base from the referenced definition) with any usage-site sibling fields set directly
+ * on the ref node (description, readOnly, nullable, deprecated, etc.).
+ *
+ * Usage-site fields take precedence over the resolved schema's own fields when both are defined.
+ *
+ * For non-ref nodes the node itself is returned unchanged.
+ */
+declare function syncSchemaRef(node: SchemaNode): SchemaNode;
+/**
+ * Returns `true` when a schema is emitted as a plain `string` type.
  *
  * - `string`, `uuid`, `email`, `url`, `datetime` are always plain strings.
  * - `date` and `time` are plain strings when their `representation` is `'string'` rather than `'date'`.
+ *
+ * @example
+ * ```ts
+ * isStringType(createSchema({ type: 'uuid' }))                          // true
+ * isStringType(createSchema({ type: 'date', representation: 'date' }))  // false
+ * ```
+ */
+declare function isStringType(node: SchemaNode): boolean;
+/**
+ * Applies casing rules to parameter names and returns a new parameter array.
+ *
+ * The input array is not mutated.
+ * If `casing` is not set, the original array is returned unchanged.
+ *
+ * Use this before passing parameters to schema builders so that property keys
+ * in generated output match the desired casing while preserving
+ * `OperationNode.parameters` for other consumers.
+ *
+ * @example
+ * ```ts
+ * const params = [createParameter({ name: 'pet_id', in: 'query', schema: createSchema({ type: 'string' }) })]
+ * const cased = caseParams(params, 'camelcase')
+ * // cased[0].name === 'petId'
+ * ```
+ */
+declare function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode>;
+/**
+ * Creates a single-property object schema used as a discriminator literal.
+ *
+ * @example
+ * ```ts
+ * createDiscriminantNode({ propertyName: 'type', value: 'dog' })
+ * // -> { type: 'object', properties: [{ name: 'type', required: true, schema: enum('dog') }] }
+ * ```
+ */
+declare function createDiscriminantNode({
+  propertyName,
+  value
+}: {
+  propertyName: string;
+  value: string;
+}): SchemaNode;
+/**
+ * Resolver interface for {@link createOperationParams}.
+ *
+ * `ResolverTs` from `@kubb/plugin-ts` satisfies this interface and can be passed directly.
+ */
+type OperationParamsResolver = {
+  /**
+   * Resolves the type name for an individual parameter.
+   *
+   * @example Individual path parameter name
+   * `resolver.resolveParamName(node, param) // → 'DeletePetPathPetId'`
+   */
+  resolveParamName(node: OperationNode, param: ParameterNode): string;
+  /**
+   * Resolves the request body type name.
+   *
+   * @example Request body type name
+   * `resolver.resolveDataName(node) // → 'CreatePetData'`
+   */
+  resolveDataName(node: OperationNode): string;
+  /**
+   * Resolves the grouped path parameters type name.
+   * When the return value equals `resolveParamName`, no indexed access is emitted.
+   *
+   * @example Grouped path params type name
+   * `resolver.resolvePathParamsName(node, param) // → 'DeletePetPathParams'`
+   */
+  resolvePathParamsName(node: OperationNode, param: ParameterNode): string;
+  /**
+   * Resolves the grouped query parameters type name.
+   * When the return value equals `resolveParamName`, an inline struct type is emitted instead.
+   *
+   * @example Grouped query params type name
+   * `resolver.resolveQueryParamsName(node, param) // → 'FindPetsByStatusQueryParams'`
+   */
+  resolveQueryParamsName(node: OperationNode, param: ParameterNode): string;
+  /**
+   * Resolves the grouped header parameters type name.
+   * When the return value equals `resolveParamName`, an inline struct type is emitted instead.
+   *
+   * @example Grouped header params type name
+   * `resolver.resolveHeaderParamsName(node, param) // → 'DeletePetHeaderParams'`
+   */
+  resolveHeaderParamsName(node: OperationNode, param: ParameterNode): string;
+};
+/**
+ * Options for {@link createOperationParams}.
+ */
+type CreateOperationParamsOptions = {
+  /**
+   * How all operation parameters are grouped in the function signature.
+   * - `'object'` wraps all params into a single destructured object `{ petId, data, params }`
+   * - `'inline'` emits each param category as a separate top-level parameter
+   */
+  paramsType: 'object' | 'inline';
+  /**
+   * How path parameters are emitted when `paramsType` is `'inline'`.
+   * - `'object'` groups them as `{ petId, storeId }: PathParams`
+   * - `'inline'` spreads them as individual parameters `petId: string, storeId: string`
+   * - `'inlineSpread'` emits a single rest parameter `...pathParams: PathParams`
+   */
+  pathParamsType: 'object' | 'inline' | 'inlineSpread';
+  /**
+   * Converts parameter names to camelCase before output.
+   */
+  paramsCasing?: 'camelcase';
+  /**
+   * Resolver for parameter and request body type names.
+   * Pass `ResolverTs` from `@kubb/plugin-ts` directly.
+   * When omitted, falls back to the schema primitive or `'unknown'`.
+   */
+  resolver?: OperationParamsResolver;
+  /**
+   * Default value for the path parameters binding when `pathParamsType` is `'object'`.
+   * Falls back to `'{}'` when all path params are optional.
+   */
+  pathParamsDefault?: string;
+  /**
+   * Extra parameters appended after the standard operation parameters.
+   *
+   * @example Plugin-specific trailing parameter
+   * ```ts
+   * extraParams: [createFunctionParameter({ name: 'options', type: 'Partial<RequestOptions>', default: '{}' })]
+   * ```
+   */
+  extraParams?: Array<FunctionParameterNode | ParameterGroupNode>;
+  /**
+   * Override the default parameter names used for body, query, header, and rest-path groups.
+   *
+   * Useful when targeting languages or frameworks with different naming conventions.
+   *
+   * @default { data: 'data', params: 'params', headers: 'headers', path: 'pathParams' }
+   */
+  paramNames?: {
+    /**
+     * Name for the request body parameter.
+     * @default 'data'
+     */
+    data?: string;
+    /**
+     * Name for the query parameters group parameter.
+     * @default 'params'
+     */
+    params?: string;
+    /**
+     * Name for the header parameters group parameter.
+     * @default 'headers'
+     */
+    headers?: string;
+    /**
+     * Name for the rest path-parameters parameter when `pathParamsType` is `'inlineSpread'`.
+     * @default 'pathParams'
+     */
+    path?: string;
+  };
+  /**
+   * Applies a uniform transformation to every resolved type name before it is used
+   * in a parameter node. Use this for framework-level type wrappers.
+   *
+   * @example Vue Query — wrap every parameter type with `MaybeRefOrGetter`
+   * `typeWrapper: (t) => \`MaybeRefOrGetter<${t}>\``
+   */
+  typeWrapper?: (type: string) => string;
+};
+/**
+ * Converts an {@link OperationNode} into a {@link FunctionParametersNode}.
+ *
+ * Centralizes the per-plugin `getParams()` pattern. Provide a `resolver` for
+ * type resolution and `extraParams` for plugin-specific trailing parameters.
+ *
+ * @example
+ * ```ts
+ * const params = createOperationParams(node, {
+ *   paramsType: 'inline',
+ *   pathParamsType: 'inline',
+ *   resolver: tsResolver,
+ *   extraParams: [createFunctionParameter({ name: 'options', type: createTypeNode({ variant: 'reference', name: 'Partial<RequestOptions>' }), default: '{}' })],
+ * })
+ * ```
  */
-declare function isPlainStringType(node: SchemaNode): boolean;
+declare function createOperationParams(node: OperationNode, options: CreateOperationParamsOptions): FunctionParametersNode;
 //#endregion
-export { buildRefMap, collect, createOperation, createParameter, createProperty, createResponse, createRoot, createSchema, definePrinter, httpMethods, isOperationNode, isParameterNode, isPlainStringType, isPropertyNode, isResponseNode, isRootNode, isSchemaNode, mediaTypes, narrowSchema, nodeKinds, refMapToObject, resolveRef, schemaTypes, transform, walk };
+export { type OperationParamsResolver, type ParserOptions, type Printer, type PrinterFactoryOptions, type PrinterPartial, type ScalarPrimitive, caseParams, childName, collect, collectImports, composeTransformers, createDiscriminantNode, createFunctionParameter, createFunctionParameters, createOperation, createOperationParams, createParameter, createParameterGroup, createPrinterFactory, createProperty, createResponse, createRoot, createSchema, createTypeNode, definePrinter, enumPropName, extractRefName, findDiscriminator, httpMethods, isOperationNode, isScalarPrimitive, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, narrowSchema, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, walk };
 //# sourceMappingURL=index.d.ts.map