@kubb/core 5.0.0-alpha.9 → 5.0.0-beta.10

package/src/constants.ts

@@ -1,21 +1,30 @@
-import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FileNode } from '@kubb/ast'
 
-export const DEFAULT_STUDIO_URL = 'https://studio.kubb.dev' as const
+/**
+ * Base URL for the Kubb Studio web app.
+ */
+export const DEFAULT_STUDIO_URL = 'https://kubb.studio' as const
 
-export const CORE_PLUGIN_NAME = 'core' as const
-
-export const DEFAULT_MAX_LISTENERS = 100
-
-export const DEFAULT_CONCURRENCY = 15
-
-export const BARREL_FILENAME = 'index.ts' as const
+/**
+ * Maximum number of files processed in parallel by FileProcessor.
+ */
+export const PARALLEL_CONCURRENCY_LIMIT = 100
 
+/**
+ * Default banner style written at the top of every generated file.
+ */
 export const DEFAULT_BANNER = 'simple' as const
 
-export const DEFAULT_EXTENSION: Record<KubbFile.Extname, KubbFile.Extname | ''> = { '.ts': '.ts' }
-
-export const PATH_SEPARATORS = new Set(['/', '\\'] as const)
+/**
+ * Default file-extension mapping used when no explicit mapping is configured.
+ */
+export const DEFAULT_EXTENSION: Record<FileNode['extname'], FileNode['extname'] | ''> = { '.ts': '.ts' }
 
+/**
+ * Numeric log-level thresholds used internally to compare verbosity.
+ *
+ * Higher numbers are more verbose.
+ */
 export const logLevel = {
   silent: Number.NEGATIVE_INFINITY,
   error: 0,
@@ -24,39 +33,3 @@ export const logLevel = {
   verbose: 4,
   debug: 5,
 } as const
-
-export const linters = {
-  eslint: {
-    command: 'eslint',
-    args: (outputPath: string) => [outputPath, '--fix'],
-    errorMessage: 'Eslint not found',
-  },
-  biome: {
-    command: 'biome',
-    args: (outputPath: string) => ['lint', '--fix', outputPath],
-    errorMessage: 'Biome not found',
-  },
-  oxlint: {
-    command: 'oxlint',
-    args: (outputPath: string) => ['--fix', outputPath],
-    errorMessage: 'Oxlint not found',
-  },
-} as const
-
-export const formatters = {
-  prettier: {
-    command: 'prettier',
-    args: (outputPath: string) => ['--ignore-unknown', '--write', outputPath],
-    errorMessage: 'Prettier not found',
-  },
-  biome: {
-    command: 'biome',
-    args: (outputPath: string) => ['format', '--write', outputPath],
-    errorMessage: 'Biome not found',
-  },
-  oxfmt: {
-    command: 'oxfmt',
-    args: (outputPath: string) => [outputPath],
-    errorMessage: 'Oxfmt not found',
-  },
-} as const

package/src/createAdapter.ts

@@ -1,24 +1,107 @@
-import type { Adapter, AdapterFactoryOptions } from './types.ts'
+import type { PossiblePromise } from '@internals/utils'
+import type { ImportNode, InputNode, SchemaNode } from '@kubb/ast'
 
 /**
- * Builder type for an {@link Adapter} — takes options and returns the adapter instance.
+ * Source data passed to an adapter's `parse` function.
+ * Mirrors the config input shape with paths resolved to absolute.
  */
+export type AdapterSource = { type: 'path'; path: string } | { type: 'data'; data: string | unknown } | { type: 'paths'; paths: Array<string> }
+
+/**
+ * Generic type parameters for an adapter definition.
+ *
+ * - `TName` — unique identifier (e.g. `'oas'`, `'asyncapi'`)
+ * - `TOptions` — user-facing options passed to the adapter factory
+ * - `TResolvedOptions` — options after defaults 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
+}
+
+/**
+ * Adapter that converts input files or data into an `InputNode`.
+ *
+ * Adapters parse different schema formats (OpenAPI, AsyncAPI, Drizzle, etc.) into Kubb's
+ * universal intermediate representation that all plugins consume.
+ *
+ * @example
+ * ```ts
+ * import { adapterOas } from '@kubb/adapter-oas'
+ *
+ * export default defineConfig({
+ *   adapter: adapterOas(),
+ *   input: { path: './openapi.yaml' },
+ *   plugins: [pluginTs(), pluginZod()],
+ * })
+ * ```
+ */
+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
+  inputNode: InputNode | 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>
+}
+
 type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>
 
 /**
- * Creates an adapter factory. Call the returned function with optional options to get the adapter instance.
+ * Factory for implementing custom adapters that translate non-OpenAPI specs into Kubb's AST.
+ *
+ * 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.
+ *
+ * @note Adapters must parse their input format to Kubb's `InputNode` structure.
  *
  * @example
+ * ```ts
  * export const myAdapter = createAdapter<MyAdapter>((options) => {
  *   return {
  *     name: 'my-adapter',
  *     options,
- *     async parse(source) { ... },
+ *     async parse(source) {
+ *       // Transform source format to InputNode
+ *       return { ... }
+ *     },
  *   }
  * })
  *
- * // instantiate
+ * // Instantiate:
  * const adapter = myAdapter({ validate: true })
+ * ```
  */
 export function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T> {
   return (options) => build(options ?? ({} as T['options']))