@kubb/core 5.0.0-alpha.30 → 5.0.0-alpha.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "5.0.0-alpha.30",
+  "version": "5.0.0-alpha.31",
   "description": "Core functionality for Kubb's plugin-based code generation system, providing the foundation for transforming OpenAPI specifications.",
   "keywords": [
     "typescript",
@@ -71,7 +71,7 @@
     "remeda": "^2.33.7",
     "semver": "^7.7.4",
     "tinyexec": "^1.0.4",
-    "@kubb/ast": "5.0.0-alpha.30"
+    "@kubb/ast": "5.0.0-alpha.31"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/Kubb.ts

@@ -1,4 +1,4 @@
-import type { FabricFile } from '@kubb/fabric-core/types'
+import type * as KubbFile from './KubbFile.ts'
 import type { Strategy } from './PluginDriver.ts'
 import type { Config, Plugin, PluginLifecycleHooks } from './types'
 
@@ -76,7 +76,7 @@ export interface KubbEvents {
   /**
    * Emitted when code generation phase completes.
    */
-  'generation:end': [config: Config, files: Array<FabricFile.ResolvedFile>, sources: Map<FabricFile.Path, string>]
+  'generation:end': [config: Config, files: Array<KubbFile.ResolvedFile>, sources: Map<KubbFile.Path, string>]
   /**
    * Emitted with a summary of the generation results.
    * Contains summary lines, title, and success status.
@@ -160,7 +160,7 @@ export interface KubbEvents {
    * Emitted when file processing starts.
    * Contains the list of files to be processed.
    */
-  'files:processing:start': [files: Array<FabricFile.ResolvedFile>]
+  'files:processing:start': [files: Array<KubbFile.ResolvedFile>]
   /**
    * Emitted for each file being processed, providing progress updates.
    * Contains processed count, total count, percentage, and file details.
@@ -186,7 +186,7 @@ export interface KubbEvents {
       /**
        * The file being processed.
        */
-      file: FabricFile.ResolvedFile
+      file: KubbFile.ResolvedFile
       /**
        * Kubb configuration (not present in Fabric).
        * Provides access to the current config during file processing.
@@ -198,7 +198,7 @@ export interface KubbEvents {
    * Emitted when file processing completes.
    * Contains the list of processed files.
    */
-  'files:processing:end': [files: Array<FabricFile.ResolvedFile>]
+  'files:processing:end': [files: Array<KubbFile.ResolvedFile>]
 
   /**
    * Emitted when a plugin starts executing.

package/src/KubbFile.ts

@@ -0,0 +1,143 @@
+type ImportName =
+  | string
+  | Array<
+      | string
+      | {
+          propertyName: string
+          name?: string
+        }
+    >
+
+export type Import = {
+  /**
+   * Import name to be used.
+   * @example ["useState"]
+   * @example "React"
+   */
+  name: ImportName
+  /**
+   * Path for the import.
+   * @example '@kubb/core'
+   */
+  path: string
+  /**
+   * Add type-only import prefix.
+   * - `true` generates `import type { Type } from './path'`
+   * - `false` generates `import { Type } from './path'`
+   * @default false
+   */
+  isTypeOnly?: boolean
+  /**
+   * Import entire module as namespace.
+   * - `true` generates `import * as Name from './path'`
+   * - `false` generates standard import
+   * @default false
+   */
+  isNameSpace?: boolean
+  /**
+   * When root is set it will compute a relative path with `getRelativePath(root, path)`.
+   */
+  root?: string
+}
+
+export type Source = {
+  name?: string
+  value?: string
+  /**
+   * Make this source a type-only export.
+   * @default false
+   */
+  isTypeOnly?: boolean
+  /**
+   * Include export keyword in source.
+   * @default false
+   */
+  isExportable?: boolean
+  /**
+   * Include in barrel file generation.
+   * @default false
+   */
+  isIndexable?: boolean
+}
+
+export type Export = {
+  /**
+   * Export name to be used.
+   * @example ["useState"]
+   * @example "React"
+   */
+  name?: string | Array<string>
+  /**
+   * Path for the export.
+   * @example '@kubb/core'
+   */
+  path: string
+  /**
+   * Add type-only export prefix.
+   * - `true` generates `export type { Type } from './path'`
+   * - `false` generates `export { Type } from './path'`
+   * @default false
+   */
+  isTypeOnly?: boolean
+  /**
+   * Export as aliased namespace.
+   * - `true` generates `export * as aliasName from './path'`
+   * - `false` generates standard export
+   * @default false
+   */
+  asAlias?: boolean
+}
+
+export type Extname = '.ts' | '.js' | '.tsx' | '.json' | `.${string}`
+
+export type Mode = 'single' | 'split'
+
+/**
+ * Name to be used to dynamically create the baseName (based on input.path).
+ * Based on UNIX basename.
+ * @link https://nodejs.org/api/path.html#pathbasenamepath-suffix
+ */
+export type BaseName = `${string}.${string}`
+
+/**
+ * Fully qualified path to a specified file.
+ */
+export type Path = string
+
+export type File<TMeta extends object = object> = {
+  /**
+   * Name used to create the path.
+   * Based on UNIX basename, `${name}${extname}`.
+   * @link https://nodejs.org/api/path.html#pathbasenamepath-suffix
+   */
+  baseName: BaseName
+  /**
+   * Fully qualified path to the file.
+   */
+  path: Path
+  sources: Array<Source>
+  imports: Array<Import>
+  exports: Array<Export>
+  /**
+   * Extra metadata used for barrel/index file generation.
+   */
+  meta?: TMeta
+  banner?: string
+  footer?: string
+}
+
+export type ResolvedFile<TMeta extends object = object> = File<TMeta> & {
+  /**
+   * Unique identifier, generated from a hash.
+   * @default hash
+   */
+  id: string
+  /**
+   * First part of the `baseName`, derived from the file name.
+   * @link https://nodejs.org/api/path.html#pathformatpathobject
+   */
+  name: string
+  extname: Extname
+  imports: Array<Import>
+  exports: Array<Export>
+}

package/src/PluginDriver.ts

@@ -3,9 +3,10 @@ import { performance } from 'node:perf_hooks'
 import type { AsyncEventEmitter } from '@internals/utils'
 import { isPromiseRejectedResult, transformReservedWord } from '@internals/utils'
 import type { RootNode } from '@kubb/ast/types'
-import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
+import type { Fabric as FabricType } from '@kubb/fabric-core/types'
 import { DEFAULT_STUDIO_URL } from './constants.ts'
 import { openInStudio as openInStudioFn } from './devtools.ts'
+import type * as KubbFile from './KubbFile.ts'
 
 import type {
   Adapter,
@@ -59,8 +60,8 @@ type Options = {
  */
 export type GetFileOptions<TOptions = object> = {
   name: string
-  mode?: FabricFile.Mode
-  extname: FabricFile.Extname
+  mode?: KubbFile.Mode
+  extname: KubbFile.Extname
   pluginName: string
   options?: TOptions
 }
@@ -74,7 +75,7 @@ export type GetFileOptions<TOptions = object> = {
  * getMode('src/gen/types')     // 'split'
  * ```
  */
-export function getMode(fileOrFolder: string | undefined | null): FabricFile.Mode {
+export function getMode(fileOrFolder: string | undefined | null): KubbFile.Mode {
   if (!fileOrFolder) {
     return 'split'
   }
@@ -131,7 +132,7 @@ export class PluginDriver {
       get root(): string {
         return resolve(driver.config.root, driver.config.output.path)
       },
-      getMode(output: { path: string }): FabricFile.Mode {
+      getMode(output: { path: string }): KubbFile.Mode {
         return getMode(resolve(driver.config.root, driver.config.output.path, output.path))
       },
       events: driver.options.events,
@@ -139,10 +140,10 @@ export class PluginDriver {
       getPlugin: driver.getPlugin.bind(driver),
       requirePlugin: driver.requirePlugin.bind(driver),
       driver: driver,
-      addFile: async (...files: Array<FabricFile.File>) => {
+      addFile: async (...files: Array<KubbFile.File>) => {
         await this.options.fabric.addFile(...files)
       },
-      upsertFile: async (...files: Array<FabricFile.File>) => {
+      upsertFile: async (...files: Array<KubbFile.File>) => {
         await this.options.fabric.upsertFile(...files)
       },
       get rootNode(): RootNode | undefined {
@@ -206,7 +207,7 @@ export class PluginDriver {
   /**
    * @deprecated use resolvers context instead
    */
-  getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileOptions<TOptions>): FabricFile.File<{ pluginName: string }> {
+  getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileOptions<TOptions>): KubbFile.File<{ pluginName: string }> {
     const resolvedName = mode ? (mode === 'single' ? '' : this.resolveName({ name, pluginName, type: 'file' })) : name
 
     const path = this.resolvePath({
@@ -222,7 +223,7 @@ export class PluginDriver {
 
     return {
       path,
-      baseName: basename(path) as FabricFile.File['baseName'],
+      baseName: basename(path) as KubbFile.File['baseName'],
       meta: {
         pluginName,
       },
@@ -235,7 +236,7 @@ export class PluginDriver {
   /**
    * @deprecated use resolvers context instead
    */
-  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): FabricFile.Path => {
+  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): KubbFile.Path => {
     const root = resolve(this.config.root, this.config.output.path)
     const defaultPath = resolve(root, params.baseName)
 

package/src/build.ts

@@ -2,12 +2,12 @@ import { dirname, relative, resolve } from 'node:path'
 import { AsyncEventEmitter, BuildError, exists, formatMs, getElapsedMs, getRelativePath, URLPath } from '@internals/utils'
 import { transform, walk } from '@kubb/ast'
 import type { OperationNode } from '@kubb/ast/types'
-import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
+import type { Fabric as FabricType } from '@kubb/fabric-core/types'
 import { createFabric } from '@kubb/react-fabric'
-import { typescriptParser } from '@kubb/react-fabric/parsers'
 import { fsPlugin } from '@kubb/react-fabric/plugins'
-import { isInputPath } from './config.ts'
 import { BARREL_FILENAME, DEFAULT_BANNER, DEFAULT_CONCURRENCY, DEFAULT_EXTENSION, DEFAULT_STUDIO_URL } from './constants.ts'
+import { defineParser } from './defineParser.ts'
+import type * as KubbFile from './KubbFile.ts'
 import { PluginDriver } from './PluginDriver.ts'
 import { applyHookResult } from './renderNode.tsx'
 import { fsStorage } from './storages/fsStorage.ts'
@@ -15,6 +15,7 @@ import type { AdapterSource, Config, KubbEvents, Plugin, PluginContext, Storage,
 import { getDiagnosticInfo } from './utils/diagnostics.ts'
 import type { FileMetaBase } from './utils/getBarrelFiles.ts'
 import { getBarrelFiles } from './utils/getBarrelFiles.ts'
+import { isInputPath } from './utils/isInputPath.ts'
 
 type BuildOptions = {
   config: UserConfig
@@ -30,7 +31,7 @@ type BuildOutput = {
    */
   failedPlugins: Set<{ plugin: Plugin; error: Error }>
   fabric: FabricType
-  files: Array<FabricFile.ResolvedFile>
+  files: Array<KubbFile.ResolvedFile>
   driver: PluginDriver
   /**
    * Elapsed time in milliseconds for each plugin, keyed by plugin name.
@@ -40,7 +41,7 @@ type BuildOutput = {
   /**
    * Raw generated source, keyed by absolute file path.
    */
-  sources: Map<FabricFile.Path, string>
+  sources: Map<KubbFile.Path, string>
 }
 
 /**
@@ -50,7 +51,8 @@ type SetupResult = {
   events: AsyncEventEmitter<KubbEvents>
   fabric: FabricType
   driver: PluginDriver
-  sources: Map<FabricFile.Path, string>
+  sources: Map<KubbFile.Path, string>
+  config: Config
 }
 
 /**
@@ -60,6 +62,7 @@ type SetupResult = {
  * - Applies config defaults (`root`, `output.*`, `devtools`).
  * - Creates the Fabric instance and wires storage, format, and lint hooks.
  * - Runs the adapter (if configured) to produce the universal `RootNode`.
+ *   When no adapter is supplied and `@kubb/adapter-oas` is installed as an
  *
  * Pass the returned {@link SetupResult} directly to {@link safeBuild} or {@link build}
  * via the `overrides` argument to reuse the same infrastructure across multiple runs.
@@ -67,7 +70,7 @@ type SetupResult = {
 export async function setup(options: BuildOptions): Promise<SetupResult> {
   const { config: userConfig, events = new AsyncEventEmitter<KubbEvents>() } = options
 
-  const sources: Map<FabricFile.Path, string> = new Map<FabricFile.Path, string>()
+  const sources: Map<KubbFile.Path, string> = new Map<KubbFile.Path, string>()
   const diagnosticInfo = getDiagnosticInfo()
 
   if (Array.isArray(userConfig.input)) {
@@ -115,9 +118,15 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
     }
   }
 
-  const definedConfig: Config = {
+  if (!userConfig.adapter) {
+    throw new Error('Adapter should be defined')
+  }
+
+  const config: Config = {
     root: userConfig.root || process.cwd(),
     ...userConfig,
+    parsers: userConfig.parsers ?? [],
+    adapter: userConfig.adapter,
     output: {
       write: true,
       barrelType: 'named',
@@ -138,19 +147,35 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
   // storage or fall back to fsStorage (backwards-compatible default).
   // Keys are root-relative (e.g. `src/gen/api/getPets.ts`) so fsStorage()
   // needs no configuration — it resolves them against process.cwd().
-  const storage: Storage | null = definedConfig.output.write === false ? null : (definedConfig.output.storage ?? fsStorage())
+  const storage: Storage | null = config.output.write === false ? null : (config.output.storage ?? fsStorage())
 
-  if (definedConfig.output.clean) {
+  if (config.output.clean) {
     await events.emit('debug', {
       date: new Date(),
-      logs: ['Cleaning output directories', `  • Output: ${definedConfig.output.path}`],
+      logs: ['Cleaning output directories', `  • Output: ${config.output.path}`],
     })
-    await storage?.clear(resolve(definedConfig.root, definedConfig.output.path))
+    await storage?.clear(resolve(config.root, config.output.path))
   }
 
   const fabric = createFabric()
   fabric.use(fsPlugin)
-  fabric.use(typescriptParser)
+
+  for (const parser of config.parsers) {
+    fabric.use(parser)
+  }
+  // Catch-all fallback: joins all source values for any unhandled extension
+  fabric.use(
+    defineParser({
+      name: 'fallback',
+      extNames: undefined,
+      parse(file) {
+        return file.sources
+          .map((item) => item.value)
+          .filter((value): value is string => value != null)
+          .join('\n\n')
+      },
+    }),
+  )
 
   fabric.context.on('files:processing:start', (files) => {
     events.emit('files:processing:start', files)
@@ -164,13 +189,13 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
     const { file, source } = params
     await events.emit('file:processing:update', {
       ...params,
-      config: definedConfig,
+      config: config,
       source,
     })
 
     if (source) {
       // Key is root-relative so it's meaningful for any backend (fs, S3, Redis…)
-      const key = relative(resolve(definedConfig.root), file.path)
+      const key = relative(resolve(config.root), file.path)
       await storage?.setItem(key, source)
       sources.set(file.path, source)
     }
@@ -186,45 +211,45 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
 
   await events.emit('debug', {
     date: new Date(),
-    logs: [
-      '✓ Fabric initialized',
-      `  • Storage: ${storage ? storage.name : 'disabled (dry-run)'}`,
-      `  • Barrel type: ${definedConfig.output.barrelType || 'none'}`,
-    ],
+    logs: ['✓ Fabric initialized', `  • Storage: ${storage ? storage.name : 'disabled (dry-run)'}`, `  • Barrel type: ${config.output.barrelType || 'none'}`],
   })
 
-  const pluginDriver = new PluginDriver(definedConfig, {
+  const driver = new PluginDriver(config, {
     fabric,
     events,
     concurrency: DEFAULT_CONCURRENCY,
   })
 
-  // Run the adapter (if provided) to produce the universal RootNode
-  if (definedConfig.adapter) {
-    const source = inputToAdapterSource(definedConfig)
+  // Run the adapter to produce the universal RootNode.
 
-    await events.emit('debug', {
-      date: new Date(),
-      logs: [`Running adapter: ${definedConfig.adapter.name}`],
-    })
+  const adapter = config.adapter
+  if (!adapter) {
+    throw new Error('No adapter configured. Please provide an adapter in your kubb.config.ts.')
+  }
+  const source = inputToAdapterSource(config)
 
-    pluginDriver.adapter = definedConfig.adapter
-    pluginDriver.rootNode = await definedConfig.adapter.parse(source)
+  await events.emit('debug', {
+    date: new Date(),
+    logs: [`Running adapter: ${adapter.name}`],
+  })
 
-    await events.emit('debug', {
-      date: new Date(),
-      logs: [
-        `✓ Adapter '${definedConfig.adapter.name}' resolved RootNode`,
-        `  • Schemas: ${pluginDriver.rootNode.schemas.length}`,
-        `  • Operations: ${pluginDriver.rootNode.operations.length}`,
-      ],
-    })
-  }
+  driver.adapter = adapter
+  driver.rootNode = await adapter.parse(source)
+
+  await events.emit('debug', {
+    date: new Date(),
+    logs: [
+      `✓ Adapter '${adapter.name}' resolved RootNode`,
+      `  • Schemas: ${driver.rootNode.schemas.length}`,
+      `  • Operations: ${driver.rootNode.operations.length}`,
+    ],
+  })
 
   return {
+    config,
     events,
     fabric,
-    driver: pluginDriver,
+    driver,
     sources,
   }
 }
@@ -266,7 +291,7 @@ export async function build(options: BuildOptions, overrides?: SetupResult): Pro
  * - Each hook accepts a single handler **or an array** — all entries are called in sequence.
  * - Nodes that are excluded by `exclude`/`include` plugin options are skipped automatically.
  * - Return values are handled via `applyHookResult`: React elements are rendered,
- *   `FabricFile.File[]` are written via upsert, and `void` is a no-op (manual handling).
+ *   `KubbFile.File[]` are written via upsert, and `void` is a no-op (manual handling).
  * - Barrel files are generated automatically when `output.barrelType` is set.
  */
 async function runPluginAstHooks(plugin: Plugin, context: PluginContext): Promise<void> {
@@ -422,7 +447,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
         existingBarrel?.exports?.flatMap((e) => (Array.isArray(e.name) ? e.name : [e.name])).filter((n): n is string => Boolean(n)) ?? [],
       )
 
-      const rootFile: FabricFile.File = {
+      const rootFile: KubbFile.File = {
         path: rootPath,
         baseName: BARREL_FILENAME,
         exports: buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }),
@@ -473,14 +498,14 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
 }
 
 type BuildBarrelExportsParams = {
-  barrelFiles: FabricFile.ResolvedFile[]
+  barrelFiles: KubbFile.ResolvedFile[]
   rootDir: string
   existingExports: Set<string>
   config: Config
   driver: PluginDriver
 }
 
-function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }: BuildBarrelExportsParams): FabricFile.Export[] {
+function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }: BuildBarrelExportsParams): KubbFile.Export[] {
   const pluginNameMap = new Map<string, Plugin>()
   for (const plugin of driver.plugins.values()) {
     pluginNameMap.set(plugin.name, plugin)
@@ -512,7 +537,7 @@ function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, dri
           name: exportName,
           path: getRelativePath(rootDir, file.path),
           isTypeOnly: config.output.barrelType === 'all' ? containsOnlyTypes : source.isTypeOnly,
-        } satisfies FabricFile.Export,
+        } satisfies KubbFile.Export,
       ]
     })
   })

package/src/constants.ts

@@ -1,4 +1,4 @@
-import type { FabricFile } from '@kubb/fabric-core/types'
+import type * as KubbFile from './KubbFile.ts'
 
 /**
  * Base URL for the Kubb Studio web app.
@@ -23,7 +23,7 @@ export const DEFAULT_BANNER = 'simple' as const
 /**
  * Default file-extension mapping used when no explicit mapping is configured.
  */
-export const DEFAULT_EXTENSION: Record<FabricFile.Extname, FabricFile.Extname | ''> = { '.ts': '.ts' }
+export const DEFAULT_EXTENSION: Record<KubbFile.Extname, KubbFile.Extname | ''> = { '.ts': '.ts' }
 
 /**
  * Characters recognized as path separators on both POSIX and Windows.

package/src/{config.ts → defineConfig.ts}

@@ -1,5 +1,5 @@
 import type { PossiblePromise } from '@internals/utils'
-import type { InputPath, UserConfig } from './types.ts'
+import type { UserConfig } from './types.ts'
 
 /**
  * CLI options derived from command-line flags.
@@ -42,16 +42,10 @@ export type ConfigInput = PossiblePromise<UserConfig | UserConfig[]> | ((cli: CL
  *   root: 'src',
  *   plugins: [myPlugin()],
  * }))
+ * @deprecated as of Kubb v5, @kubb/core will not expose `defineConfig` anymore. use the `kubb` package instead
  */
 export function defineConfig(config: (cli: CLIOptions) => PossiblePromise<UserConfig | UserConfig[]>): typeof config
 export function defineConfig(config: PossiblePromise<UserConfig | UserConfig[]>): typeof config
 export function defineConfig(config: ConfigInput): ConfigInput {
   return config
 }
-
-/**
- * Type guard to check if a given config has an `input.path`.
- */
-export function isInputPath(config: UserConfig | undefined): config is UserConfig<InputPath> {
-  return typeof config?.input === 'object' && config.input !== null && 'path' in config.input
-}

package/src/defineGenerator.ts

@@ -1,7 +1,7 @@
 import type { PossiblePromise } from '@internals/utils'
 import type { OperationNode, SchemaNode } from '@kubb/ast/types'
-import type { FabricFile } from '@kubb/fabric-core/types'
 import type { FabricReactNode } from '@kubb/react-fabric/types'
+import type * as KubbFile from './KubbFile.ts'
 import { applyHookResult } from './renderNode.tsx'
 import type { GeneratorContext, PluginFactoryOptions } from './types.ts'
 
@@ -13,7 +13,7 @@ export type { GeneratorContext } from './types.ts'
  * giving full access to `this.config`, `this.resolver`, `this.adapter`, `this.fabric`,
  * `this.driver`, etc.
  *
- * Return a React element, an array of `FabricFile.File`, or `void` to handle file
+ * Return a React element, an array of `KubbFile.File`, or `void` to handle file
  * writing manually via `this.upsertFile`. Both React and core (non-React) generators
  * use the same method signatures — the return type determines how output is handled.
  *
@@ -43,7 +43,7 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
     this: GeneratorContext<TOptions>,
     node: SchemaNode,
     options: TOptions['resolvedOptions'],
-  ) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
+  ) => PossiblePromise<FabricReactNode | Array<KubbFile.File> | void>
   /**
    * Called for each operation node in the AST walk.
    * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
@@ -52,7 +52,7 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
     this: GeneratorContext<TOptions>,
     node: OperationNode,
     options: TOptions['resolvedOptions'],
-  ) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
+  ) => PossiblePromise<FabricReactNode | Array<KubbFile.File> | void>
   /**
    * Called once after all operations have been walked.
    * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
@@ -61,7 +61,7 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
     this: GeneratorContext<TOptions>,
     nodes: Array<OperationNode>,
     options: TOptions['resolvedOptions'],
-  ) => PossiblePromise<FabricReactNode | Array<FabricFile.File> | void>
+  ) => PossiblePromise<FabricReactNode | Array<KubbFile.File> | void>
 }
 
 /**

package/src/defineParser.ts

@@ -0,0 +1,57 @@
+import type * as KubbFile from './KubbFile.ts'
+
+type PrintOptions = {
+  extname?: KubbFile.Extname
+}
+
+export type Parser<TMeta extends object = any> = {
+  name: string
+  type: 'parser'
+  /**
+   * File extensions this parser handles.
+   * Use `undefined` to create a catch-all fallback parser.
+   *
+   * @example ['.ts', '.js']
+   */
+  extNames: Array<KubbFile.Extname> | undefined
+  /**
+   * @deprecated Will be removed once Fabric no longer requires it.
+   * @default () => {}
+   */
+  install(...args: unknown[]): void | Promise<void>
+  /**
+   * Convert a resolved file to a string.
+   */
+  parse(file: KubbFile.ResolvedFile<TMeta>, options?: PrintOptions): Promise<string> | string
+}
+
+export type UserParser<TMeta extends object = any> = Omit<Parser<TMeta>, 'type' | 'install'> & {
+  install?(...args: unknown[]): void | Promise<void>
+}
+
+/**
+ * Defines a parser with type safety.
+ *
+ * Use this function to create parsers that transform generated files to strings
+ * based on their extension.
+ *
+ * @example
+ * ```ts
+ * import { defineParser } from '@kubb/core'
+ *
+ * export const jsonParser = defineParser({
+ *   name: 'json',
+ *   extNames: ['.json'],
+ *   parse(file) {
+ *     return file.sources.map((s) => s.value).join('\n')
+ *   },
+ * })
+ * ```
+ */
+export function defineParser<TMeta extends object = any>(parser: UserParser<TMeta>): Parser<TMeta> {
+  return {
+    install() {},
+    type: 'parser',
+    ...parser,
+  }
+}