@kubb/core 5.0.0-alpha.72 → 5.0.0-alpha.74

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <a href="https://kubb.dev/kubb" target="_blank" rel="noopener noreferrer">
+  <a href="https://kubb.dev" target="_blank" rel="noopener noreferrer">
     <img width="180" src="https://raw.githubusercontent.com/kubb-labs/kubb/main/assets/logo.png" alt="Kubb logo">
   </a>
 
@@ -9,10 +9,12 @@
 [![License][license-src]][license-href]
 [![Sponsors][sponsors-src]][sponsors-href]
 
+### The meta framework for code generation
+
+**Stop writing glue code. Define your API once and Kubb generates types, clients, hooks, validators, mocks and more.**
+
 <h4>
-<a href="https://codesandbox.io/s/github/kubb-labs/kubb/tree/main/examples/typescript" target="_blank">View Demo</a>
-<span> · </span>
-<a href="https://kubb.dev/kubb" target="_blank">Documentation</a>
+<a href="https://kubb.dev" target="_blank">Documentation</a>
 <span> · </span>
 <a href="https://github.com/kubb-labs/kubb/issues/" target="_blank">Report Bug</a>
 <span> · </span>
@@ -22,6 +24,14 @@
 
 <br />
 
+## Installation
+
+```bash
+npm install @kubb/core
+# or
+pnpm add @kubb/core
+```
+
 ## Quick Start
 
 Get started with Kubb in seconds:
@@ -47,14 +57,13 @@ See the [documentation](https://kubb.dev) for detailed usage and advanced featur
 
 ## Features
 
-- Works with Node.js 20+.
-- Convert Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1 to TypeScript, Zod, React-Query, ...
-- Plugin ecosystem to extend beyond the default plugins we provide.
-- CLI support with progress bar and detailed logs.
+- Works with Node.js 22+ and TypeScript 6.
+- Convert Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1 to TypeScript types, API clients, and more via the [plugin ecosystem](https://github.com/kubb-labs/kubb-plugins).
+- Extensible plugin and middleware system for customizing and composing code generation.
+- CLI support with interactive setup, progress bar, and detailed logs.
 - Model Context Protocol (MCP) server for AI assistants like [Claude](https://claude.ai), [Cursor](https://cursor.sh), and other MCP-compatible tools.
-- Debug tools with React DevTools.
-- Generates barrel files (index.ts).
-- And so much more ...
+- JSX-based renderer (`@kubb/renderer-jsx`) for building custom plugin output.
+- Barrel file generation via the `@kubb/middleware-barrel` middleware.
 
 ## Supporting Kubb
 
@@ -151,13 +160,6 @@ Kubb is an open source project with its ongoing development made possible entire
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 
-<!-- ALL-CONTRIBUTORS-LIST:END -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-disable -->
-
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
-
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 ## License

package/dist/index.cjs

@@ -496,19 +496,29 @@ var URLPath = class {
 //#endregion
 //#region src/createAdapter.ts
 /**
-* 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 })
+* ```
 */
 function createAdapter(build) {
 	return (options) => build(options ?? {});
@@ -688,9 +698,17 @@ var FileProcessor = class {
 //#endregion
 //#region src/createStorage.ts
 /**
-* Creates a storage factory. Call the returned function with optional options to get the storage instance.
+* Factory for implementing custom storage backends that control where generated files are written.
+*
+* Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
+* Kubb provides filesystem and in-memory implementations out of the box.
+*
+* @note Call the returned factory with optional options to instantiate the storage adapter.
 *
 * @example
+* ```ts
+* import { createStorage } from '@kubb/core'
+*
 * export const memoryStorage = createStorage(() => {
 *   const store = new Map<string, string>()
 *   return {
@@ -706,6 +724,10 @@ var FileProcessor = class {
 *     async clear(base) { if (!base) store.clear() },
 *   }
 * })
+*
+* // Instantiate:
+* const storage = memoryStorage()
+* ```
 */
 function createStorage(build) {
 	return (options) => build(options ?? {});
@@ -795,7 +817,7 @@ const fsStorage = createStorage(() => ({
 }));
 //#endregion
 //#region package.json
-var version = "5.0.0-alpha.72";
+var version = "5.0.0-alpha.74";
 //#endregion
 //#region src/utils/diagnostics.ts
 /**
@@ -862,6 +884,8 @@ async function setup(userConfig, options = {}) {
 		parsers: userConfig.parsers ?? [],
 		adapter: userConfig.adapter,
 		output: {
+			format: false,
+			lint: false,
 			write: true,
 			extension: require_PluginDriver.DEFAULT_EXTENSION,
 			defaultBanner: require_PluginDriver.DEFAULT_BANNER,
@@ -1273,14 +1297,17 @@ function defineLogger(logger) {
 //#endregion
 //#region src/defineMiddleware.ts
 /**
-* Creates a middleware factory using the hook-style (`hooks:`) API.
+* Creates a middleware factory using the hook-style `hooks` API.
 *
-* Mirrors `definePlugin`: the factory is called with optional options and returns a
-* fresh `Middleware` instance. Placing per-build state (e.g. accumulators) inside the
-* factory closure ensures each `createKubb` invocation gets its own isolated instance.
+* Middleware handlers fire after all plugin handlers for any given event, making them ideal for post-processing, logging, and auditing.
+* Per-build state (such as accumulators) belongs inside the factory closure so each `createKubb` invocation gets its own isolated instance.
+*
+* @note The factory can accept typed options. See examples for using options and per-build state patterns.
 *
 * @example
 * ```ts
+* import { defineMiddleware } from '@kubb/core'
+*
 * // Stateless middleware
 * export const logMiddleware = defineMiddleware(() => ({
 *   name: 'log-middleware',
@@ -1292,10 +1319,10 @@ function defineLogger(logger) {
 * }))
 *
 * // Middleware with options and per-build state
-* export const myMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
+* export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
 *   const seen = new Set<string>()
 *   return {
-*     name: 'my-middleware',
+*     name: 'prefix-middleware',
 *     hooks: {
 *       'kubb:plugin:end'({ plugin }) {
 *         seen.add(`${options.prefix}${plugin.name}`)
@@ -1303,11 +1330,6 @@ function defineLogger(logger) {
 *     },
 *   }
 * })
-*
-* // Usage in kubb.config.ts:
-* export default defineConfig({
-*   middleware: [logMiddleware(), myMiddleware({ prefix: 'pfx:' })],
-* })
 * ```
 */
 function defineMiddleware(factory) {
@@ -1316,10 +1338,9 @@ function defineMiddleware(factory) {
 //#endregion
 //#region src/defineParser.ts
 /**
-* Defines a parser with type safety.
+* Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
 *
-* Use this function to create parsers that transform generated files to strings
-* based on their extension.
+* @note Call the returned factory with optional options to instantiate the parser.
 *
 * @example
 * ```ts
@@ -1341,23 +1362,23 @@ function defineParser(parser) {
 //#endregion
 //#region src/definePlugin.ts
 /**
-* Creates a plugin factory using the hook-style (`hooks:`) API.
+* Wraps a factory function and returns a typed `Plugin` with lifecycle handlers grouped under `hooks`.
 *
-* The returned factory is called with optional options and produces a `Plugin`
-* that coexists with plugins created via the legacy `createPlugin` API in the same
-* `kubb.config.ts`.
+* Handlers live in a single `hooks` object (inspired by Astro integrations).
+* All lifecycle events from `KubbHooks` are available for subscription.
 *
-* Lifecycle handlers are registered on the `PluginDriver`'s `AsyncEventEmitter`, enabling
-* both the plugin's own handlers and external tooling (CLI, devtools) to observe every event.
+* @note For real plugins, use a `PluginFactoryOptions` type parameter to get type-safe context in `kubb:plugin:setup`.
+* Plugin names should follow the convention `plugin-<feature>` (e.g., `plugin-react-query`, `plugin-zod`).
 *
 * @example
 * ```ts
-* // With PluginFactoryOptions (recommended for real plugins)
-* export const pluginTs = definePlugin<PluginTs>((options) => ({
+* import { definePlugin } from '@kubb/core'
+*
+* export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
 *   name: 'plugin-ts',
 *   hooks: {
 *     'kubb:plugin:setup'(ctx) {
-*       ctx.setResolver(resolverTs)  // typed as Partial<ResolverTs>
+*       ctx.setResolver(resolverTs)
 *     },
 *   },
 * }))