@kubb/core 4.38.1 → 4.39.1

package/dist/{types-BwL2CHjl.d.ts → types-DsJhzsHG.d.ts}

@@ -619,6 +619,26 @@ type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
   parse: (source: AdapterSource) => PossiblePromise<RootNode>;
 };
 type BarrelType = 'all' | 'named' | 'propagate';
+/**
+ * Object form of the barrel option, the forward-compatible replacement for `barrelType`.
+ *
+ * Available in v4 so a config can be migrated ahead of v5, where it becomes the only barrel option.
+ * See https://kubb.dev/docs/5.x/migration-guide
+ */
+type Barrel = {
+  /**
+   * How `index.ts` files re-export their files.
+   * - 'named' lists every export by name.
+   * - 'all' re-exports with a wildcard (`export *`).
+   * @default 'named'
+   */
+  type?: Exclude<BarrelType, 'propagate'>;
+  /**
+   * Re-export the nested barrel files instead of the individual files. Replaces the legacy `'propagate'` value of `barrelType`.
+   * @default false
+   */
+  nested?: boolean;
+};
 type DevtoolsOptions = {
   /**
    * Open the AST inspector view (`/ast`) in Kubb Studio.
@@ -719,8 +739,17 @@ type Config<TInput = Input> = {
     /**
      * Configures how `index.ts` files are created, including disabling barrel file generation. Each plugin has its own `barrelType` option; this setting controls the root barrel file (e.g., `src/gen/index.ts`).
      * @default 'named'
+     * @deprecated Use the `output.barrel` object instead. See https://kubb.dev/docs/5.x/migration-guide
      */
     barrelType?: Exclude<BarrelType, 'propagate'> | false;
+    /**
+     * Object form of {@link Config.output.barrelType} for the root barrel file (e.g., `src/gen/index.ts`). Prefer this over `barrelType`; it becomes the only barrel option in v5.
+     * - `{ type: 'named' }` lists every export by name.
+     * - `{ type: 'all' }` re-exports with a wildcard.
+     * - `false` disables the root barrel file.
+     * @default { type: 'named' }
+     */
+    barrel?: Omit<Barrel, 'nested'> | false;
     /**
      * Adds a default banner to the start of every generated file indicating it was generated by Kubb.
      * - 'simple' adds banner with link to Kubb.
@@ -734,6 +763,7 @@ type Config<TInput = Input> = {
      * When setting the option in the global configuration, all plugins inherit the same behavior by default.
      * However, all plugins also have an `output.override` option, which can be used to override the behavior for a specific plugin.
      * @default false
+     * @deprecated Removed in v5, where it no longer has any effect. See https://kubb.dev/docs/5.x/migration-guide
      */
     override?: boolean;
   };
@@ -938,8 +968,18 @@ type Output<TOptions> = {
   /**
    * Define what needs to be exported, here you can also disable the export of barrel files
    * @default 'named'
+   * @deprecated Use the `output.barrel` object instead. See https://kubb.dev/docs/5.x/migration-guide
    */
   barrelType?: BarrelType | false;
+  /**
+   * Object form of {@link Output.barrelType}. Prefer this over `barrelType`; it becomes the only barrel option in v5.
+   * - `{ type: 'named' }` lists every export by name.
+   * - `{ type: 'all' }` re-exports with a wildcard.
+   * - `{ type: 'named', nested: true }` replaces the legacy `'propagate'` value.
+   * - `false` disables the barrel file for this plugin.
+   * @default { type: 'named' }
+   */
+  barrel?: Barrel | false;
   /**
    * Add a banner text in the beginning of every file
    */
@@ -951,6 +991,7 @@ type Output<TOptions> = {
   /**
    * Whether to override existing external files if they already exist.
    * @default false
+   * @deprecated Removed in v5, where it no longer has any effect. See https://kubb.dev/docs/5.x/migration-guide
    */
   override?: boolean;
 };
@@ -987,5 +1028,5 @@ type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
 };
 type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Omit<Logger<TOptions>, 'logLevel'>;
 //#endregion
-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-BwL2CHjl.d.ts.map
+export { UserLogger as A, logLevel as B, PluginWithLifeCycle as C, ResolvePathParams as D, ResolveNameParams as E, getMode as F, URLPath as H, DefineStorage as I, defineStorage as L, UserPluginWithLifeCycle as M, KubbEvents as N, UnknownUserPlugin as O, PluginManager as P, formatters as R, PluginParameter as S, PrinterFactoryOptions as T, AsyncEventEmitter as V, PluginContext as _, BarrelType as a, PluginLifecycle as b, GetPluginFactoryOptions as c, InputPath as d, Logger as f, Plugin as g, Output as h, Barrel as i, UserPlugin as j, UserConfig as k, Group as l, LoggerOptions as m, AdapterFactoryOptions as n, Config as o, LoggerContext as p, AdapterSource as r, DevtoolsOptions as s, Adapter as t, InputData as u, PluginFactoryOptions as v, Printer as w, PluginLifecycleHooks as x, PluginKey as y, linters as z };
+//# sourceMappingURL=types-DsJhzsHG.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "4.38.1",
+  "version": "4.39.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.37.0",
     "semver": "^7.8.2",
     "tinyexec": "^1.2.4",
-    "@kubb/ast": "4.38.1"
+    "@kubb/ast": "4.39.1"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/build.ts

@@ -13,6 +13,7 @@ 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'
+import { resolveBarrelType } from './utils/resolveBarrelType.ts'
 
 type BuildOptions = {
   config: UserConfig
@@ -161,7 +162,7 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
     logs: [
       '✓ Fabric initialized',
       `  • Storage: ${storage ? storage.name : 'disabled (dry-run)'}`,
-      `  • Barrel type: ${definedConfig.output.barrelType || 'none'}`,
+      `  • Barrel type: ${resolveBarrelType(definedConfig.output) || 'none'}`,
     ],
   })
 
@@ -286,14 +287,15 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       }
     }
 
-    if (config.output.barrelType) {
+    const rootBarrelType = resolveBarrelType(config.output)
+    if (rootBarrelType) {
       const root = resolve(config.root)
       const rootPath = resolve(root, config.output.path, BARREL_FILENAME)
       const rootDir = dirname(rootPath)
 
       await events.emit('debug', {
         date: new Date(),
-        logs: ['Generating barrel file', `  • Type: ${config.output.barrelType}`, `  • Path: ${rootPath}`],
+        logs: ['Generating barrel file', `  • Type: ${rootBarrelType}`, `  • Path: ${rootPath}`],
       })
 
       const barrelFiles = fabric.files.filter((file) => {
@@ -361,6 +363,7 @@ type BuildBarrelExportsParams = {
 }
 
 function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, pluginManager }: BuildBarrelExportsParams): KubbFile.Export[] {
+  const rootBarrelType = resolveBarrelType(config.output)
   const pluginKeyMap = new Map<string, Plugin>()
   for (const plugin of pluginManager.plugins) {
     pluginKeyMap.set(JSON.stringify(plugin.key), plugin)
@@ -378,11 +381,11 @@ function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, plu
       const plugin = meta?.pluginKey ? pluginKeyMap.get(JSON.stringify(meta.pluginKey)) : undefined
       const pluginOptions = plugin?.options as { output?: Output<unknown> } | undefined
 
-      if (!pluginOptions || pluginOptions.output?.barrelType === false) {
+      if (!pluginOptions || resolveBarrelType(pluginOptions.output) === false) {
         return []
       }
 
-      const exportName = config.output.barrelType === 'all' ? undefined : source.name ? [source.name] : undefined
+      const exportName = rootBarrelType === 'all' ? undefined : source.name ? [source.name] : undefined
       if (exportName?.some((n) => existingExports.has(n))) {
         return []
       }
@@ -391,7 +394,7 @@ function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, plu
         {
           name: exportName,
           path: getRelativePath(rootDir, file.path),
-          isTypeOnly: config.output.barrelType === 'all' ? containsOnlyTypes : source.isTypeOnly,
+          isTypeOnly: rootBarrelType === 'all' ? containsOnlyTypes : source.isTypeOnly,
         } satisfies KubbFile.Export,
       ]
     })

package/src/config.ts

@@ -36,6 +36,14 @@ export type ConfigInput = PossiblePromise<UserConfig | UserConfig[]> | ((cli: CL
  * - A function returning the config(s), optionally async,
  *   receiving the CLI options as argument
  *
+ * @deprecated Import `defineConfig` from `kubb` instead of `@kubb/core`. The `kubb`
+ * package wires up the OpenAPI adapter, the TypeScript parsers, and the barrel plugin
+ * for you. See the v5 migration guide: https://kubb.dev/docs/5.x/migration-guide
+ *
+ * ```ts
+ * import { defineConfig } from '@kubb/core' // [!code --]
+ * import { defineConfig } from 'kubb' // [!code ++]
+ * ```
  * @example
  * export default defineConfig(({ logLevel }) => ({
  *   root: 'src',

package/src/index.ts

@@ -20,3 +20,4 @@ export type { FileMetaBase } from './utils/getBarrelFiles.ts'
 export { getBarrelFiles } from './utils/getBarrelFiles.ts'
 export { getConfigs } from './utils/getConfigs.ts'
 export { detectLinter } from './utils/linters.ts'
+export { resolveBarrelType } from './utils/resolveBarrelType.ts'

package/src/types.ts

@@ -102,6 +102,27 @@ export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptio
 
 export type BarrelType = 'all' | 'named' | 'propagate'
 
+/**
+ * Object form of the barrel option, the forward-compatible replacement for `barrelType`.
+ *
+ * Available in v4 so a config can be migrated ahead of v5, where it becomes the only barrel option.
+ * See https://kubb.dev/docs/5.x/migration-guide
+ */
+export type Barrel = {
+  /**
+   * How `index.ts` files re-export their files.
+   * - 'named' lists every export by name.
+   * - 'all' re-exports with a wildcard (`export *`).
+   * @default 'named'
+   */
+  type?: Exclude<BarrelType, 'propagate'>
+  /**
+   * Re-export the nested barrel files instead of the individual files. Replaces the legacy `'propagate'` value of `barrelType`.
+   * @default false
+   */
+  nested?: boolean
+}
+
 export type DevtoolsOptions = {
   /**
    * Open the AST inspector view (`/ast`) in Kubb Studio.
@@ -203,8 +224,17 @@ export type Config<TInput = Input> = {
     /**
      * Configures how `index.ts` files are created, including disabling barrel file generation. Each plugin has its own `barrelType` option; this setting controls the root barrel file (e.g., `src/gen/index.ts`).
      * @default 'named'
+     * @deprecated Use the `output.barrel` object instead. See https://kubb.dev/docs/5.x/migration-guide
      */
     barrelType?: Exclude<BarrelType, 'propagate'> | false
+    /**
+     * Object form of {@link Config.output.barrelType} for the root barrel file (e.g., `src/gen/index.ts`). Prefer this over `barrelType`; it becomes the only barrel option in v5.
+     * - `{ type: 'named' }` lists every export by name.
+     * - `{ type: 'all' }` re-exports with a wildcard.
+     * - `false` disables the root barrel file.
+     * @default { type: 'named' }
+     */
+    barrel?: Omit<Barrel, 'nested'> | false
     /**
      * Adds a default banner to the start of every generated file indicating it was generated by Kubb.
      * - 'simple' adds banner with link to Kubb.
@@ -218,6 +248,7 @@ export type Config<TInput = Input> = {
      * When setting the option in the global configuration, all plugins inherit the same behavior by default.
      * However, all plugins also have an `output.override` option, which can be used to override the behavior for a specific plugin.
      * @default false
+     * @deprecated Removed in v5, where it no longer has any effect. See https://kubb.dev/docs/5.x/migration-guide
      */
     override?: boolean
   }
@@ -442,8 +473,18 @@ export type Output<TOptions> = {
   /**
    * Define what needs to be exported, here you can also disable the export of barrel files
    * @default 'named'
+   * @deprecated Use the `output.barrel` object instead. See https://kubb.dev/docs/5.x/migration-guide
    */
   barrelType?: BarrelType | false
+  /**
+   * Object form of {@link Output.barrelType}. Prefer this over `barrelType`; it becomes the only barrel option in v5.
+   * - `{ type: 'named' }` lists every export by name.
+   * - `{ type: 'all' }` re-exports with a wildcard.
+   * - `{ type: 'named', nested: true }` replaces the legacy `'propagate'` value.
+   * - `false` disables the barrel file for this plugin.
+   * @default { type: 'named' }
+   */
+  barrel?: Barrel | false
   /**
    * Add a banner text in the beginning of every file
    */
@@ -455,6 +496,7 @@ export type Output<TOptions> = {
   /**
    * Whether to override existing external files if they already exist.
    * @default false
+   * @deprecated Removed in v5, where it no longer has any effect. See https://kubb.dev/docs/5.x/migration-guide
    */
   override?: boolean
 }

package/src/utils/getBarrelFiles.ts

@@ -1,14 +1,18 @@
 import { join } from 'node:path'
 import type { KubbFile } from '@kubb/fabric-core/types'
 import { BarrelManager } from '../BarrelManager.ts'
-import type { BarrelType, Plugin } from '../types.ts'
+import type { Barrel, BarrelType, Plugin } from '../types.ts'
+import { resolveBarrelType } from './resolveBarrelType.ts'
 
 export type FileMetaBase = {
   pluginKey?: Plugin['key']
 }
 
 type AddIndexesProps = {
-  type: BarrelType | false | undefined
+  /**
+   * Explicit barrel strategy. When omitted it is resolved from `output.barrel` (preferred) or the legacy `output.barrelType`.
+   */
+  type?: BarrelType | false
   /**
    * Root based on root and output.path specified in the config
    */
@@ -18,6 +22,8 @@ type AddIndexesProps = {
    */
   output: {
     path: string
+    barrel?: Barrel | false
+    barrelType?: BarrelType | false
   }
   group?: {
     output: string
@@ -38,7 +44,9 @@ function trimExtName(text: string): string {
 }
 
 export async function getBarrelFiles(files: Array<KubbFile.ResolvedFile>, { type, meta = {}, root, output }: AddIndexesProps): Promise<KubbFile.File[]> {
-  if (!type || type === 'propagate') {
+  const resolvedType = type ?? resolveBarrelType(output) ?? 'named'
+
+  if (!resolvedType || resolvedType === 'propagate') {
     return []
   }
 
@@ -56,7 +64,7 @@ export async function getBarrelFiles(files: Array<KubbFile.ResolvedFile>, { type
     meta,
   })
 
-  if (type === 'all') {
+  if (resolvedType === 'all') {
     return barrelFiles.map((file) => {
       return {
         ...file,

package/src/utils/resolveBarrelType.ts

@@ -0,0 +1,32 @@
+import type { Barrel, BarrelType } from '../types.ts'
+
+type BarrelOutput = {
+  barrel?: Barrel | false
+  barrelType?: BarrelType | false
+}
+
+/**
+ * Resolve the effective barrel strategy from an output config.
+ *
+ * Prefers the object `barrel` option and falls back to the legacy `barrelType`.
+ * `barrel: { nested: true }` maps to the legacy `'propagate'` value, and
+ * `barrel: false` disables the barrel file.
+ */
+export function resolveBarrelType(output: BarrelOutput | undefined): BarrelType | false | undefined {
+  if (!output) {
+    return undefined
+  }
+
+  const { barrel } = output
+  if (barrel !== undefined) {
+    if (barrel === false) {
+      return false
+    }
+    if (barrel.nested) {
+      return 'propagate'
+    }
+    return barrel.type ?? 'named'
+  }
+
+  return output.barrelType
+}