@kubb/core 5.0.0-beta.3 → 5.0.0-beta.31

package/src/constants.ts

@@ -3,12 +3,7 @@ import type { FileNode } from '@kubb/ast'
 /**
  * Base URL for the Kubb Studio web app.
  */
-export const DEFAULT_STUDIO_URL = 'https://studio.kubb.dev' as const
-
-/**
- * Maximum number of files processed in parallel by FileProcessor.
- */
-export const PARALLEL_CONCURRENCY_LIMIT = 100
+export const DEFAULT_STUDIO_URL = 'https://kubb.studio' as const
 
 /**
  * Default banner style written at the top of every generated file.
@@ -20,6 +15,16 @@ export const DEFAULT_BANNER = 'simple' as const
  */
 export const DEFAULT_EXTENSION: Record<FileNode['extname'], FileNode['extname'] | ''> = { '.ts': '.ts' }
 
+/**
+ * Number of file writes to batch in parallel during `flushPendingFiles`.
+ */
+export const STREAM_FLUSH_EVERY = 50
+
+/**
+ * Number of schema/operation nodes to dispatch concurrently during generation.
+ */
+export const SCHEMA_PARALLEL = 8
+
 /**
  * Numeric log-level thresholds used internally to compare verbosity.
  *

package/src/createAdapter.ts

@@ -1,30 +1,126 @@
-import type { Adapter, AdapterFactoryOptions } from './types.ts'
+import type { PossiblePromise } from '@internals/utils'
+import type { ImportNode, InputNode, InputStreamNode, SchemaNode } from '@kubb/ast'
 
-type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>
+/**
+ * Source data handed to an adapter's `parse` function. Mirrors the config
+ * input shape with paths resolved to absolute.
+ *
+ * - `{ type: 'path' }`: single file on disk.
+ * - `{ type: 'paths' }`: multiple files (e.g. split spec).
+ * - `{ type: 'data' }`: raw string or parsed object provided inline.
+ */
+export type AdapterSource = { type: 'path'; path: string } | { type: 'data'; data: string | unknown } | { type: 'paths'; paths: Array<string> }
 
 /**
- * Factory for implementing custom adapters that translate non-OpenAPI specs into Kubb's AST.
+ * Generic parameters used by `createAdapter` and the resulting `Adapter` type.
  *
- * Use this to support GraphQL schemas, gRPC definitions, AsyncAPI, or custom domain-specific languages.
- * Built-in adapters include `@kubb/adapter-oas` for OpenAPI and Swagger documents.
+ * - `TName`: unique adapter identifier (`'oas'`, `'asyncapi'`, ...).
+ * - `TOptions`: user-facing options accepted by the adapter factory.
+ * - `TResolvedOptions`: options after defaults are applied.
+ * - `TDocument`: type of the parsed source document.
+ */
+export type AdapterFactoryOptions<
+  TName extends string = string,
+  TOptions extends object = object,
+  TResolvedOptions extends object = TOptions,
+  TDocument = unknown,
+> = {
+  name: TName
+  options: TOptions
+  resolvedOptions: TResolvedOptions
+  document: TDocument
+}
+
+/**
+ * Converts input files or inline data into Kubb's universal AST `InputNode`.
  *
- * @note Adapters must parse their input format to Kubb's `InputNode` structure.
+ * Adapters live between the spec format and the plugins. The built-in
+ * `@kubb/adapter-oas` handles OpenAPI 2.0, 3.0, and 3.1; custom adapters can
+ * support GraphQL, gRPC, AsyncAPI, or any domain-specific schema language.
  *
  * @example
  * ```ts
- * export const myAdapter = createAdapter<MyAdapter>((options) => {
- *   return {
- *     name: 'my-adapter',
- *     options,
- *     async parse(source) {
- *       // Transform source format to InputNode
- *       return { ... }
- *     },
- *   }
+ * import { defineConfig } from 'kubb'
+ * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas(),
+ *   plugins: [pluginTs()],
  * })
+ * ```
+ */
+export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
+  /**
+   * Human-readable adapter identifier (e.g. `'oas'`, `'asyncapi'`).
+   */
+  name: TOptions['name']
+  /**
+   * Resolved adapter options after defaults have been applied.
+   */
+  options: TOptions['resolvedOptions']
+  /**
+   * Parsed source document after the first `parse()` call. `null` before parsing.
+   */
+  document: TOptions['document'] | null
+  /**
+   * Parse the source into a universal `InputNode`.
+   */
+  parse: (source: AdapterSource) => PossiblePromise<InputNode>
+  /**
+   * Extract `ImportNode` entries for a schema tree.
+   * Returns an empty array before the first `parse()` call.
+   *
+   * The `resolve` callback receives the collision-corrected schema name and must
+   * return `{ name, path }` for the import, or `undefined` to skip it.
+   */
+  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string }) => Array<ImportNode>
+  /**
+   * Validate the document at the given path or URL.
+   */
+  validate: (input: string, options?: { throwOnError?: boolean }) => Promise<void>
+  /**
+   * Memory-efficient streaming variant of `parse()`.
+   *
+   * Returns an `InputStreamNode` whose `schemas` and `operations` are `AsyncIterable`.
+   * Each `for await` loop creates a fresh parse pass over the cached in-memory document.
+   * No pre-built arrays are held in memory.
+   */
+  stream?: (source: AdapterSource) => Promise<InputStreamNode>
+}
+
+type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>
+
+/**
+ * Defines a custom adapter that translates a spec format into Kubb's universal
+ * AST. Use this when you need to consume GraphQL, gRPC, AsyncAPI, or another
+ * domain-specific schema. Built-in adapters: `@kubb/adapter-oas` for
+ * OpenAPI/Swagger documents.
+ *
+ * Adapters must return an `InputNode` from `parse`. That node is what every
+ * plugin in the build consumes.
+ *
+ * @example
+ * ```ts
+ * import { createAdapter, ast, type AdapterFactoryOptions } from '@kubb/core'
+ *
+ * type MyAdapter = AdapterFactoryOptions<'my-adapter', { validate?: boolean }>
  *
- * // Instantiate:
- * const adapter = myAdapter({ validate: true })
+ * export const myAdapter = createAdapter<MyAdapter>((options) => ({
+ *   name: 'my-adapter',
+ *   options,
+ *   document: null,
+ *   async parse(_source) {
+ *     // Convert `source` (path or inline data) into an InputNode.
+ *     return ast.createInput()
+ *   },
+ *   getImports: () => [],
+ *   async validate() {
+ *     // Throw or call ctx.error here when the spec is invalid.
+ *   },
+ * }))
  * ```
  */
 export function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T> {