@kubb/core 4.35.1 → 4.36.1

package/dist/{types-BPb8k77q.d.ts → types-D30QAz2y.d.ts}

@@ -23,6 +23,75 @@ declare var AsyncEventEmitter: {
     removeAll(): void;
   };
 };
+/**
+* Parses and transforms an OpenAPI/Swagger path string into various URL formats.
+*
+* @example
+* const p = new URLPath('/pet/{petId}')
+* p.URL      // '/pet/:petId'
+* p.template // '`/pet/${petId}`'
+*/
+declare var URLPath: {
+  new (path: any, options?: {}): {
+    /** The raw OpenAPI/Swagger path string, e.g. `/pet/{petId}`. */path: any;
+    "__#private@#options": {}; /** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`. */
+    get URL(): any; /** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`). */
+    get isURL(): boolean;
+    /**
+    * Converts the OpenAPI path to a TypeScript template literal string.
+    *
+    * @example
+    * new URLPath('/pet/{petId}').template              // '`/pet/${petId}`'
+    * new URLPath('/account/monetary-accountID').template // '`/account/${monetaryAccountId}`'
+    */
+    get template(): string; /** Returns the path and its extracted params as a structured `URLObject`, or as a stringified expression when `stringify` is set. */
+    get object(): string | {
+      url: any;
+      params: {} | undefined;
+    }; /** Returns a map of path parameter names, or `undefined` when the path has no parameters. */
+    get params(): {} | undefined;
+    "__#private@#transformParam"(raw: any): any; /** Iterates over every `{param}` token in `path`, calling `fn` with the raw token and transformed name. */
+    "__#private@#eachParam"(fn: any): void;
+    toObject({
+      type,
+      replacer,
+      stringify
+    }?: {
+      type?: string | undefined;
+    }): string | {
+      url: any;
+      params: {} | undefined;
+    };
+    /**
+    * Converts the OpenAPI path to a TypeScript template literal string.
+    * An optional `replacer` can transform each extracted parameter name before interpolation.
+    *
+    * @example
+    * new URLPath('/pet/{petId}').toTemplateString() // '`/pet/${petId}`'
+    */
+    toTemplateString({
+      prefix,
+      replacer
+    }?: {
+      prefix?: string | undefined;
+    }): string;
+    /**
+    * Extracts all `{param}` segments from the path and returns them as a key-value map.
+    * An optional `replacer` transforms each parameter name in both key and value positions.
+    * Returns `undefined` when no path parameters are found.
+    */
+    getParams(replacer: any): {} | undefined; /** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`. */
+    toURLPath(): any;
+  };
+};
+/**
+* Serializes a primitive value to a JSON string literal, stripping any surrounding quote characters first.
+*
+* @example
+* stringify('hello')   // '"hello"'
+* stringify('"hello"') // '"hello"'
+*/
+declare function stringify(value: any): string;
 //#endregion
 //#region src/constants.d.ts
 declare const DEFAULT_STUDIO_URL: "https://studio.kubb.dev";
@@ -69,6 +138,61 @@ declare const formatters: {
   };
 };
 //#endregion
+//#region src/defineStorage.d.ts
+/**
+ * Storage interface for persisting Kubb output.
+ *
+ * Keys are root-relative forward-slash paths (e.g. `src/gen/api/getPets.ts`).
+ * Implement this interface to route generated files to any backend — filesystem,
+ * S3, Redis, in-memory, etc.
+ *
+ * Use `defineStorage` to create a typed storage driver.
+ */
+interface DefineStorage {
+  /** Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`). */
+  readonly name: string;
+  /** Returns `true` when an entry for `key` exists in storage. */
+  hasItem(key: string): Promise<boolean>;
+  /** Returns the stored string value, or `null` when `key` does not exist. */
+  getItem(key: string): Promise<string | null>;
+  /** Persists `value` under `key`, creating any required structure. */
+  setItem(key: string, value: string): Promise<void>;
+  /** Removes the entry for `key`. No-ops when the key does not exist. */
+  removeItem(key: string): Promise<void>;
+  /** Returns all keys, optionally filtered to those starting with `base`. */
+  getKeys(base?: string): Promise<Array<string>>;
+  /** Removes all entries, optionally scoped to those starting with `base`. */
+  clear(base?: string): Promise<void>;
+  /** Optional teardown hook called after the build completes. */
+  dispose?(): Promise<void>;
+}
+/**
+ * Wraps a storage builder so the `options` argument is optional, following the
+ * same factory pattern as `definePlugin`, `defineLogger`, and `defineAdapter`.
+ *
+ * The builder receives the resolved options object and must return a
+ * `DefineStorage`-compatible object that includes a `name` string.
+ *
+ * @example
+ * ```ts
+ * import { defineStorage } from '@kubb/core'
+ *
+ * export const memoryStorage = defineStorage((_options) => {
+ *   const store = new Map<string, string>()
+ *   return {
+ *     name: 'memory',
+ *     async hasItem(key) { return store.has(key) },
+ *     async getItem(key) { return store.get(key) ?? null },
+ *     async setItem(key, value) { store.set(key, value) },
+ *     async removeItem(key) { store.delete(key) },
+ *     async getKeys() { return [...store.keys()] },
+ *     async clear() { store.clear() },
+ *   }
+ * })
+ * ```
+ */
+declare function defineStorage<TOptions = Record<string, never>>(build: (options: TOptions) => DefineStorage): (options?: TOptions) => DefineStorage;
+//#endregion
 //#region src/PluginManager.d.ts
 type RequiredPluginLifecycle = Required<PluginLifecycle>;
 type Strategy = 'hookFirst' | 'hookForPlugin' | 'hookParallel' | 'hookSeq';
@@ -551,8 +675,22 @@ type Config<TInput = Input> = {
     /**
      * Save files to the file system.
      * @default true
+     * @deprecated Use `storage` to control where files are written.
      */
     write?: boolean;
+    /**
+     * Storage backend for generated files.
+     * Defaults to `fsStorage()` — the built-in filesystem driver.
+     * Accepts any object implementing the {@link DefineStorage} interface.
+     * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
+     * @default fsStorage()
+     * @example
+     * ```ts
+     * import { defineStorage, fsStorage } from '@kubb/core'
+     * storage: defineStorage(fsStorage())
+     * ```
+     */
+    storage?: DefineStorage;
     /**
      * Specifies the formatting tool to be used.
      * - 'auto' automatically detects and uses biome or prettier (in that order of preference).
@@ -849,5 +987,5 @@ type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
 };
 type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Omit<Logger<TOptions>, 'logLevel'>;
 //#endregion
-export { UserPlugin as A, Printer as C, UnknownUserPlugin as D, ResolvePathParams as E, formatters as F, linters as I, logLevel as L, KubbEvents as M, PluginManager as N, UserConfig as O, getMode as P, AsyncEventEmitter as R, PluginWithLifeCycle as S, ResolveNameParams as T, PluginFactoryOptions as _, Config as a, PluginLifecycleHooks as b, Group as c, Logger as d, LoggerContext as f, PluginContext as g, Plugin as h, BarrelType as i, UserPluginWithLifeCycle as j, UserLogger as k, InputData as l, Output as m, AdapterFactoryOptions as n, DevtoolsOptions as o, LoggerOptions as p, AdapterSource as r, GetPluginFactoryOptions as s, Adapter as t, InputPath as u, PluginKey as v, PrinterFactoryOptions as w, PluginParameter as x, PluginLifecycle as y };
-//# sourceMappingURL=types-BPb8k77q.d.ts.map
+export { UserPlugin as A, AsyncEventEmitter as B, Printer as C, UnknownUserPlugin as D, ResolvePathParams as E, DefineStorage as F, defineStorage as I, formatters as L, KubbEvents as M, PluginManager as N, UserConfig as O, getMode as P, linters as R, PluginWithLifeCycle as S, ResolveNameParams as T, URLPath as V, PluginFactoryOptions as _, Config as a, PluginLifecycleHooks as b, Group as c, Logger as d, LoggerContext as f, PluginContext as g, Plugin as h, BarrelType as i, UserPluginWithLifeCycle as j, UserLogger as k, InputData as l, Output as m, AdapterFactoryOptions as n, DevtoolsOptions as o, LoggerOptions as p, AdapterSource as r, GetPluginFactoryOptions as s, Adapter as t, InputPath as u, PluginKey as v, PrinterFactoryOptions as w, PluginParameter as x, PluginLifecycle as y, logLevel as z };
+//# sourceMappingURL=types-D30QAz2y.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "4.35.1",
+  "version": "4.36.1",
   "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.6",
     "semver": "^7.7.4",
     "tinyexec": "^1.0.4",
-    "@kubb/ast": "4.35.1"
+    "@kubb/ast": "4.36.1"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/build.ts

@@ -1,5 +1,5 @@
-import { dirname, resolve } from 'node:path'
-import { AsyncEventEmitter, clean, exists, formatMs, getElapsedMs, getRelativePath, URLPath, write } from '@internals/utils'
+import { dirname, relative, resolve } from 'node:path'
+import { AsyncEventEmitter, exists, formatMs, getElapsedMs, getRelativePath, URLPath } from '@internals/utils'
 import type { KubbFile } from '@kubb/fabric-core/types'
 import type { Fabric } from '@kubb/react-fabric'
 import { createFabric } from '@kubb/react-fabric'
@@ -9,7 +9,8 @@ import { isInputPath } from './config.ts'
 import { BARREL_FILENAME, DEFAULT_BANNER, DEFAULT_CONCURRENCY, DEFAULT_EXTENSION, DEFAULT_STUDIO_URL } from './constants.ts'
 import { BuildError } from './errors.ts'
 import { PluginManager } from './PluginManager.ts'
-import type { AdapterSource, Config, KubbEvents, Output, Plugin, UserConfig } from './types.ts'
+import { fsStorage } from './storages/fsStorage.ts'
+import type { AdapterSource, Config, DefineStorage, KubbEvents, Output, Plugin, UserConfig } from './types.ts'
 import { getDiagnosticInfo } from './utils/diagnostics.ts'
 import type { FileMetaBase } from './utils/getBarrelFiles.ts'
 
@@ -54,7 +55,7 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
       `  • Output: ${userConfig.output?.path || 'not specified'}`,
       `  • Plugins: ${userConfig.plugins?.length || 0}`,
       'Output Settings:',
-      `  • Write: ${userConfig.output?.write !== false ? 'enabled' : 'disabled'}`,
+      `  • Storage: ${userConfig.output?.storage ? `custom(${userConfig.output.storage.name})` : userConfig.output?.write === false ? 'disabled' : 'filesystem (default)'}`,
       `  • Formatter: ${userConfig.output?.format || 'none'}`,
       `  • Linter: ${userConfig.output?.lint || 'none'}`,
       'Environment:',
@@ -105,12 +106,18 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
     plugins: userConfig.plugins as Config['plugins'],
   }
 
+  // write: false is the explicit dry-run opt-out; otherwise use the provided
+  // 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: DefineStorage | null = definedConfig.output.write === false ? null : (definedConfig.output.storage ?? fsStorage())
+
   if (definedConfig.output.clean) {
     await events.emit('debug', {
       date: new Date(),
       logs: ['Cleaning output directories', `  • Output: ${definedConfig.output.path}`],
     })
-    await clean(definedConfig.output.path)
+    await storage?.clear(resolve(definedConfig.root, definedConfig.output.path))
   }
 
   const fabric = createFabric()
@@ -134,10 +141,9 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
     })
 
     if (source) {
-      if (definedConfig.output.write) {
-        await write(file.path, source, { sanity: false })
-      }
-
+      // Key is root-relative so it's meaningful for any backend (fs, S3, Redis…)
+      const key = relative(resolve(definedConfig.root), file.path)
+      await storage?.setItem(key, source)
       sources.set(file.path, source)
     }
   })
@@ -154,7 +160,7 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
     date: new Date(),
     logs: [
       '✓ Fabric initialized',
-      `  • File writing: ${definedConfig.output.write ? 'enabled' : 'disabled (dry-run)'}`,
+      `  • Storage: ${storage ? storage.name : 'disabled (dry-run)'}`,
       `  • Barrel type: ${definedConfig.output.barrelType || 'none'}`,
     ],
   })

package/src/defineStorage.ts

@@ -0,0 +1,56 @@
+/**
+ * Storage interface for persisting Kubb output.
+ *
+ * Keys are root-relative forward-slash paths (e.g. `src/gen/api/getPets.ts`).
+ * Implement this interface to route generated files to any backend — filesystem,
+ * S3, Redis, in-memory, etc.
+ *
+ * Use `defineStorage` to create a typed storage driver.
+ */
+export interface DefineStorage {
+  /** Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`). */
+  readonly name: string
+  /** Returns `true` when an entry for `key` exists in storage. */
+  hasItem(key: string): Promise<boolean>
+  /** Returns the stored string value, or `null` when `key` does not exist. */
+  getItem(key: string): Promise<string | null>
+  /** Persists `value` under `key`, creating any required structure. */
+  setItem(key: string, value: string): Promise<void>
+  /** Removes the entry for `key`. No-ops when the key does not exist. */
+  removeItem(key: string): Promise<void>
+  /** Returns all keys, optionally filtered to those starting with `base`. */
+  getKeys(base?: string): Promise<Array<string>>
+  /** Removes all entries, optionally scoped to those starting with `base`. */
+  clear(base?: string): Promise<void>
+  /** Optional teardown hook called after the build completes. */
+  dispose?(): Promise<void>
+}
+
+/**
+ * Wraps a storage builder so the `options` argument is optional, following the
+ * same factory pattern as `definePlugin`, `defineLogger`, and `defineAdapter`.
+ *
+ * The builder receives the resolved options object and must return a
+ * `DefineStorage`-compatible object that includes a `name` string.
+ *
+ * @example
+ * ```ts
+ * import { defineStorage } from '@kubb/core'
+ *
+ * export const memoryStorage = defineStorage((_options) => {
+ *   const store = new Map<string, string>()
+ *   return {
+ *     name: 'memory',
+ *     async hasItem(key) { return store.has(key) },
+ *     async getItem(key) { return store.get(key) ?? null },
+ *     async setItem(key, value) { store.set(key, value) },
+ *     async removeItem(key) { store.delete(key) },
+ *     async getKeys() { return [...store.keys()] },
+ *     async clear() { store.clear() },
+ *   }
+ * })
+ * ```
+ */
+export function defineStorage<TOptions = Record<string, never>>(build: (options: TOptions) => DefineStorage): (options?: TOptions) => DefineStorage {
+  return (options) => build(options ?? ({} as TOptions))
+}

package/src/index.ts

@@ -1,4 +1,4 @@
-export { AsyncEventEmitter } from '@internals/utils'
+export { AsyncEventEmitter, URLPath } from '@internals/utils'
 export { definePrinter } from '@kubb/ast'
 export { build, build as default, safeBuild, setup } from './build.ts'
 export { type CLIOptions, type ConfigInput, defineConfig, isInputPath } from './config.ts'
@@ -6,9 +6,12 @@ export { formatters, linters, logLevel } from './constants.ts'
 export { defineAdapter } from './defineAdapter.ts'
 export { defineLogger } from './defineLogger.ts'
 export { definePlugin } from './definePlugin.ts'
+export { defineStorage } from './defineStorage.ts'
 export { PackageManager } from './PackageManager.ts'
 export { getMode, PluginManager } from './PluginManager.ts'
 export { PromiseManager } from './PromiseManager.ts'
+export { fsStorage } from './storages/fsStorage.ts'
+export { memoryStorage } from './storages/memoryStorage.ts'
 export * from './types.ts'
 export type { FunctionParamsAST } from './utils/FunctionParams.ts'
 export { FunctionParams } from './utils/FunctionParams.ts'

package/src/storages/fsStorage.ts

@@ -0,0 +1,84 @@
+import type { Dirent } from 'node:fs'
+import { access, readdir, readFile, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { clean, write } from '@internals/utils'
+import { defineStorage } from '../defineStorage.ts'
+
+/**
+ * Built-in filesystem storage driver.
+ *
+ * This is the default storage when no `storage` option is configured in `output`.
+ * Keys are resolved against `process.cwd()`, so root-relative paths such as
+ * `src/gen/api/getPets.ts` are written to the correct location without extra configuration.
+ *
+ * Internally uses the `write` utility from `@internals/utils`, which:
+ * - trims leading/trailing whitespace before writing
+ * - skips the write when file content is already identical (deduplication)
+ * - creates missing parent directories automatically
+ * - supports Bun's native file API when running under Bun
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, fsStorage } from '@kubb/core'
+ *
+ * export default defineConfig({
+ *   input:  { path: './petStore.yaml' },
+ *   output: { path: './src/gen', storage: fsStorage() },
+ * })
+ * ```
+ */
+export const fsStorage = defineStorage(() => ({
+  name: 'fs',
+  async hasItem(key: string) {
+    try {
+      await access(resolve(key))
+      return true
+    } catch {
+      return false
+    }
+  },
+  async getItem(key: string) {
+    try {
+      return await readFile(resolve(key), 'utf8')
+    } catch {
+      return null
+    }
+  },
+  async setItem(key: string, value: string) {
+    await write(resolve(key), value, { sanity: false })
+  },
+  async removeItem(key: string) {
+    await rm(resolve(key), { force: true })
+  },
+  async getKeys(base?: string) {
+    const keys: Array<string> = []
+
+    async function walk(dir: string, prefix: string): Promise<void> {
+      let entries: Array<Dirent>
+      try {
+        entries = (await readdir(dir, { withFileTypes: true })) as Array<Dirent>
+      } catch {
+        return
+      }
+      for (const entry of entries) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name
+        if (entry.isDirectory()) {
+          await walk(join(dir, entry.name), rel)
+        } else {
+          keys.push(rel)
+        }
+      }
+    }
+
+    await walk(resolve(base ?? process.cwd()), '')
+
+    return keys
+  },
+  async clear(base?: string) {
+    if (!base) {
+      return
+    }
+
+    await clean(resolve(base))
+  },
+}))

package/src/storages/memoryStorage.ts

@@ -0,0 +1,53 @@
+import { defineStorage } from '../defineStorage.ts'
+
+/**
+ * In-memory storage driver. Useful for testing and dry-run scenarios where
+ * generated output should be captured without touching the filesystem.
+ *
+ * All data lives in a `Map` scoped to the storage instance and is discarded
+ * when the instance is garbage-collected.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, memoryStorage } from '@kubb/core'
+ *
+ * export default defineConfig({
+ *   input:  { path: './petStore.yaml' },
+ *   output: { path: './src/gen', storage: memoryStorage() },
+ * })
+ * ```
+ */
+export const memoryStorage = defineStorage(() => {
+  const store = new Map<string, string>()
+
+  return {
+    name: 'memory',
+    async hasItem(key: string) {
+      return store.has(key)
+    },
+    async getItem(key: string) {
+      return store.get(key) ?? null
+    },
+    async setItem(key: string, value: string) {
+      store.set(key, value)
+    },
+    async removeItem(key: string) {
+      store.delete(key)
+    },
+    async getKeys(base?: string) {
+      const keys = [...store.keys()]
+      return base ? keys.filter((k) => k.startsWith(base)) : keys
+    },
+    async clear(base?: string) {
+      if (!base) {
+        store.clear()
+        return
+      }
+      for (const key of store.keys()) {
+        if (key.startsWith(base)) {
+          store.delete(key)
+        }
+      }
+    },
+  }
+})

package/src/types.ts

@@ -3,6 +3,7 @@ import type { RootNode } from '@kubb/ast/types'
 import type { KubbFile } from '@kubb/fabric-core/types'
 import type { Fabric } from '@kubb/react-fabric'
 import type { DEFAULT_STUDIO_URL, logLevel } from './constants.ts'
+import type { DefineStorage } from './defineStorage.ts'
 import type { KubbEvents } from './Kubb.ts'
 import type { PluginManager } from './PluginManager.ts'
 
@@ -158,8 +159,22 @@ export type Config<TInput = Input> = {
     /**
      * Save files to the file system.
      * @default true
+     * @deprecated Use `storage` to control where files are written.
      */
     write?: boolean
+    /**
+     * Storage backend for generated files.
+     * Defaults to `fsStorage()` — the built-in filesystem driver.
+     * Accepts any object implementing the {@link DefineStorage} interface.
+     * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
+     * @default fsStorage()
+     * @example
+     * ```ts
+     * import { defineStorage, fsStorage } from '@kubb/core'
+     * storage: defineStorage(fsStorage())
+     * ```
+     */
+    storage?: DefineStorage
     /**
      * Specifies the formatting tool to be used.
      * - 'auto' automatically detects and uses biome or prettier (in that order of preference).
@@ -483,4 +498,5 @@ export type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
 
 export type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Omit<Logger<TOptions>, 'logLevel'>
 
+export type { DefineStorage } from './defineStorage.ts'
 export type { KubbEvents } from './Kubb.ts'