@kubb/core 5.0.0-beta.41 → 5.0.0-beta.43

package/src/createKubb.ts

@@ -5,6 +5,7 @@ import type { FileNode, InputMeta, OperationNode, SchemaNode } from '@kubb/ast'
 import { HOOK_LISTENERS_PER_PLUGIN } from './constants.ts'
 import type { Adapter } from './createAdapter.ts'
 import { type Diagnostic, Diagnostics, type ProblemDiagnostic, type UpdateDiagnostic } from './diagnostics.ts'
+import type { Cache } from './createCache.ts'
 import { createStorage, type Storage } from './createStorage.ts'
 import type { GeneratorContext } from './defineGenerator.ts'
 import type { Middleware } from './defineMiddleware.ts'
@@ -233,6 +234,26 @@ export type Config<TInput = Input> = {
    * @see {@link Storage} interface for implementing custom backends.
    */
   storage: Storage
+  /**
+   * Incremental build cache. Kubb fingerprints the inputs (spec content, config, plugin options,
+   * versions) and, on an unchanged "hot" run, restores the previously generated output instead of
+   * regenerating it. Same idea as Nx's computation cache.
+   *
+   * `defineConfig` enables `fsCache()` (local disk under `node_modules/.cache/kubb`) by default.
+   * Pass another backend to change where snapshots live, or `false` to turn caching off. A bare
+   * `createKubb` leaves it off unless a cache is provided.
+   *
+   * @example
+   * ```ts
+   * import { fsCache } from '@kubb/core'
+   *
+   * cache: fsCache({ dir: '.kubb-cache' })
+   * cache: false
+   * ```
+   *
+   * @see {@link Cache} interface for implementing custom backends.
+   */
+  cache?: Cache
   /**
    * Plugins that run during the build to generate code and transform the AST. Each one processes
    * the adapter's AST and can emit files for a different target (TypeScript, Zod, Faker). A plugin
@@ -336,7 +357,12 @@ export type Config<TInput = Input> = {
  * })
  * ```
  */
-export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage' | 'reporters'> & {
+export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage' | 'reporters' | 'cache'> & {
+  /**
+   * Incremental build cache. Defaults to `fsCache()` (local disk). Pass another {@link Cache}
+   * backend, or `false` to turn caching off.
+   */
+  cache?: Cache | false
   /**
    * Project root directory, absolute or relative to the config file location.
    * @default process.cwd()
@@ -658,7 +684,7 @@ export type KubbDiagnosticContext = {
 
 export type KubbFilesProcessingStartContext = {
   /**
-   * Files about to be serialised and written.
+   * Files about to be serialized and written.
    */
   files: Array<FileNode>
 }
@@ -677,7 +703,7 @@ export type KubbFileProcessingUpdate = {
    */
   percentage: number
   /**
-   * Serialised file content, or `undefined` when the file produced no output.
+   * Serialized file content, or `undefined` when the file produced no output.
    */
   source?: string
   /**
@@ -699,7 +725,7 @@ export type KubbFilesProcessingUpdateContext = {
 
 export type KubbFilesProcessingEndContext = {
   /**
-   * All files that were serialised in this batch.
+   * All files that were serialized in this batch.
    */
   files: Array<FileNode>
 }
@@ -887,6 +913,9 @@ function resolveConfig(userConfig: UserConfig): Config {
       ...userConfig.output,
     },
     storage: userConfig.storage ?? fsStorage(),
+    // Resolve `false` to "no cache". The default `fsCache()` is applied by `defineConfig`, not here,
+    // so a raw `createKubb` stays deterministic (no surprise on-disk cache) unless a cache is passed.
+    cache: userConfig.cache === false ? undefined : userConfig.cache,
     reporters: userConfig.reporters ?? [],
     plugins: userConfig.plugins ?? [],
   }

package/src/createRenderer.ts

@@ -14,15 +14,6 @@ export type Renderer<TElement = unknown> = {
    * Called once per render cycle. Must resolve before {@link files} is read.
    */
   render(element: TElement): Promise<void>
-  /**
-   * Tears down the renderer and releases any held resources.
-   * Pass an `Error` to signal a failure, a number for an exit code, or omit for a clean shutdown.
-   */
-  unmount(error?: Error | number | null): void
-  /**
-   * Releases any held resources. `[Symbol.dispose]` delegates here.
-   */
-  dispose(): void
   /**
    * Accumulated {@link FileNode} results produced by the last {@link render} call.
    * Not populated when {@link stream} is implemented.
@@ -35,7 +26,7 @@ export type Renderer<TElement = unknown> = {
   stream?(element: TElement): Iterable<FileNode>
   /**
    * Disposer hook so renderers participate in `using` blocks: `using r = rendererFactory()`
-   * guarantees {@link dispose} runs on every exit path, including thrown errors.
+   * runs cleanup on every exit path, including thrown errors.
    */
   [Symbol.dispose](): void
 }
@@ -70,14 +61,8 @@ export type RendererFactory<TElement = unknown> = () => Renderer<TElement>
  *     get files() {
  *       return runtime.files
  *     },
- *     dispose() {
- *       runtime.dispose()
- *     },
- *     unmount(error) {
- *       runtime.dispose(error)
- *     },
  *     [Symbol.dispose]() {
- *       this.dispose()
+ *       runtime.dispose()
  *     },
  *   }
  * })

package/src/defineParser.ts

@@ -23,7 +23,7 @@ export type Parser<TMeta extends object = object, TNode = unknown> = {
    */
   extNames: Array<FileNode['extname']> | undefined
   /**
-   * Serialise the file's AST into source code.
+   * Serialize the file's AST into source code.
    */
   parse(file: FileNode<TMeta>, options?: PrintOptions): string
   /**

package/src/index.ts

@@ -1,6 +1,7 @@
 export { AsyncEventEmitter, URLPath } from '@internals/utils'
 export * as ast from '@kubb/ast'
 export { createAdapter } from './createAdapter.ts'
+export { createCache } from './createCache.ts'
 export { Diagnostics } from './diagnostics.ts'
 export { createKubb } from './createKubb.ts'
 export { createReporter, selectReporters } from './createReporter.ts'
@@ -17,6 +18,7 @@ export { defineParser } from './defineParser.ts'
 export { definePlugin } from './definePlugin.ts'
 export { defineResolver } from './defineResolver.ts'
 export { KubbDriver } from './KubbDriver.ts'
+export { fsCache } from './caches/fsCache.ts'
 export { fsStorage } from './storages/fsStorage.ts'
 export { memoryStorage } from './storages/memoryStorage.ts'
 export * from './types.ts'

package/src/storages/fsStorage.ts

@@ -1,7 +1,6 @@
-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 { access, glob, readFile, rm } from 'node:fs/promises'
+import { join, relative, resolve } from 'node:path'
+import { clean, isBun, toPosixPath, write } from '@internals/utils'
 import { createStorage } from '../createStorage.ts'
 
 /**
@@ -55,29 +54,22 @@ export const fsStorage = createStorage(() => ({
   async getKeys(base?: string) {
     const resolvedBase = resolve(base ?? process.cwd())
 
-    async function* walk(dir: string, prefix: string): AsyncGenerator<string, void, undefined> {
-      let entries: Array<Dirent>
-      try {
-        entries = (await readdir(dir, {
-          withFileTypes: true,
-        })) as Array<Dirent>
-      } catch (_error) {
-        return
-      }
-      for (const entry of entries) {
-        const rel = prefix ? `${prefix}/${entry.name}` : entry.name
-        if (entry.isDirectory()) {
-          yield* walk(join(dir, entry.name), rel)
-        } else {
-          yield rel
-        }
-      }
+    if (isBun()) {
+      const bunGlob = new Bun.Glob('**/*')
+      return Array.fromAsync(bunGlob.scan({ cwd: resolvedBase, onlyFiles: true, dot: true }))
     }
 
     const keys: Array<string> = []
-    for await (const key of walk(resolvedBase, '')) {
-      keys.push(key)
+    try {
+      for await (const entry of glob('**/*', { cwd: resolvedBase, withFileTypes: true })) {
+        if (entry.isFile()) {
+          keys.push(toPosixPath(relative(resolvedBase, join(entry.parentPath, entry.name))))
+        }
+      }
+    } catch (_error) {
+      // base directory does not exist yet
     }
+
     return keys
   },
   async clear(base?: string) {

package/src/types.ts

@@ -1,4 +1,6 @@
 export type { Adapter, AdapterFactoryOptions, AdapterSource } from './createAdapter.ts'
+export type { Cache, CachedSnapshot } from './createCache.ts'
+export type { FsCacheOptions } from './caches/fsCache.ts'
 export type {
   Diagnostic,
   DiagnosticByCode,