@hypernym/bundler/dist/index.d.ts

ESM & TS module bundler.

import { InputOptions, LogLevel, LogOrStringHandler, OutputOptions, RolldownPluginOption, RollupLog } from "rolldown";
import { Options as Options$1 } from "rolldown-plugin-dts";

//#region src/bin/build.d.ts
declare function build(options: Options): Promise<BuildStats>;
//#endregion
//#region src/types/build.d.ts
interface BuildLogs {
  level: LogLevel;
  log: RollupLog;
}
interface BuildEntryStats {
  /**
   * The root path of the project.
   */
  cwd: string;
  /**
   * Module output path.
   */
  path: string;
  /**
   * Module size.
   */
  size: number;
  /**
   * Build time of individual module.
   */
  buildTime: number;
  /**
   * Module format.
   */
  format: string;
  /**
   * List of warnings from build plugins.
   */
  logs: BuildLogs[];
}
interface BuildStats {
  /**
   * The root path of the project.
   */
  cwd: string;
  /**
   * Final bundle size.
   */
  size: number;
  /**
   * Total bundle build time.
   */
  buildTime: number;
  /**
   * List of generated bundle modules.
   */
  files: BuildEntryStats[];
}
type PickEntryChunkOptions = 'input' | 'name' | 'globals' | 'extend' | 'minify';
type PickEntryDtsOptions = 'dts' | 'dtsPlugin';
interface BuildEntryOptions extends EntryBase, Partial<Pick<EntryChunk, PickEntryChunkOptions>>, Partial<Pick<EntryDts, PickEntryDtsOptions>> {
  /**
   * Specifies the path to the processed file.
   *
   * @default undefined
   */
  output?: string;
}
//#endregion
//#region src/types/entries.d.ts
interface EntryBase {
  /**
   * Specifies the format of the generated module.
   *
   * - `'es'`, `'esm'` and `'module'` are the same format, all stand for ES module.
   * - `'cjs'` and `'commonjs'` are the same format, all stand for CommonJS module.
   * - `'iife'` stands for [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE).
   * - `'umd'` stands for [Universal Module Definition](https://github.com/umdjs/umd).
   *
   * @default 'esm'
   */
  format?: OutputOptions['format'];
  /**
   * Specifies the module IDs or regular expressions that match module IDs to be treated as external and excluded from the bundle.
   *
   * The IDs and regular expressions provided in this option are applied globally across all entries.
   *
   * Alternatively, externals can be defined individually for each entry using the `entry.externals` property.
   *
   * @default undefined
   */
  externals?: (string | RegExp)[];
  /**
   * Maps external module IDs to paths.
   *
   * @default undefined
   */
  paths?: {
    find: string | RegExp;
    replacement: string | ((path: string, match: RegExpExecArray | null) => string);
  }[];
  /**
   * Specifies the string to be inserted at the beginning of the module.
   *
   * @default undefined
   */
  banner?: OutputOptions['banner'];
  /**
   * Specifies the string to be inserted at the beginning of the module after minification
   *
   * @default undefined
   */
  postBanner?: OutputOptions['postBanner'];
  /**
   * Specifies the string to be inserted at the end of the module.
   *
   * @default undefined
   */
  footer?: OutputOptions['footer'];
  /**
   * Specifies the string to be inserted at the end of the module after minification.
   *
   * @default undefined
   */
  postFooter?: OutputOptions['postFooter'];
  /**
   * Specifies the code at the beginning that goes inside any _format-specific_ wrapper.
   *
   * @default undefined
   */
  intro?: OutputOptions['intro'];
  /**
   * Specifies the code at the end that goes inside any _format-specific_ wrapper.
   *
   * @default undefined
   */
  outro?: OutputOptions['outro'];
  /**
   * Intercepts log messages. If not supplied, logs are printed to the console.
   *
   * @default undefined
   */
  onLog?: (level: LogLevel, log: RollupLog, defaultHandler: LogOrStringHandler, buildLogs: BuildLogs[]) => void;
  /**
   * Specifies Rolldown `resolve` options.
   *
   * @default undefined
   */
  resolve?: InputOptions['resolve'];
  /**
   * Specifies Rolldown `define` options.
   *
   * @default undefined
   */
  define?: NonNullable<InputOptions['transform']>['define'];
  /**
   * Specifies Rolldown `inject` options.
   *
   * @default undefined
   */
  inject?: NonNullable<InputOptions['transform']>['inject'];
  /**
   * Specifies Rolldown plugins.
   *
   * @default undefined
   */
  plugins?: RolldownPluginOption;
  /**
   * Specifies the path to the `tsconfig` file.
   *
   * By default, if the file `tsconfig.json` exists in the project root, it will be used as the default config file.
   *
   * @default undefined
   */
  tsconfig?: InputOptions['tsconfig'];
  /**
   * Specifies which comments are preserved in the output.
   *
   * - `true` - Preserve legal, annotation, and JSDoc comments.
   * - `false` - Strip all comments.
   * - `object` - Granular control over comment categories:
   *   - `legal` - `@license`, `@preserve`, `//!`, `/*!`.
   *   - `annotation` - `@__PURE__`, `@__NO_SIDE_EFFECTS__`, `@vite-ignore`.
   *   - `jsdoc` - JSDoc comments.
   *
   * @default { legal: true, annotation: true, jsdoc: false }
   */
  comments?: OutputOptions['comments'];
}
interface EntryChunk extends EntryBase {
  /**
   * Specifies the path to the build source.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   entries: [
   *     { input: './src/index.ts' }, // outputs './dist/index.js'
   *   ]
   * })
   * ```
   */
  input: string;
  /**
   * Specifies the path to the processed file.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   entries: [
   *     {
   *       input: './src/index.ts',
   *       output: './out/index.js', // outputs './out/index.js'
   *     },
   *   ]
   * })
   * ```
   *
   * @default undefined
   */
  output?: string;
  /**
   * Specifies the global variable name that representing exported bundle.
   *
   * Intended for `umd/iife` formats.
   *
   * @default undefined
   */
  name?: OutputOptions['name'];
  /**
   * Specifies global _module ID_ and _variable name_ pairs necessary for external imports.
   *
   * Intended for `umd/iife` formats.
   *
   * @default undefined
   */
  globals?: OutputOptions['globals'];
  /**
   * Specifies whether to extend the global variable defined by the `name` option.
   *
   * Intended for `umd/iife` formats.
   */
  extend?: OutputOptions['extend'];
  /**
   * Controls code minification.
   *
   * - `true`: Enable full minification including code compression and dead code elimination.
   * - `false`: Disable minification (default).
   * - `'dce-only'`: Only perform dead code elimination without code compression.
   * - `MinifyOptions`: Fine-grained control over minification settings.
   *
   * @default undefined
   */
  minify?: OutputOptions['minify'];
  dts?: never;
  dtsPlugin?: never;
  copy?: never;
  recursive?: never;
  filter?: never;
  template?: never;
}
interface EntryDts extends EntryBase {
  /**
   * Specifies the path to the TypeScript `declaration` build source.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   entries: [
   *     { dts: './src/types.ts' }, // outputs './dist/types.d.ts'
   *   ]
   * })
   * ```
   */
  dts: string;
  /**
   * Specifies the path to the processed file.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   entries: [
   *     {
   *       dts: './src/types.ts',
   *       output: './out/types.d.ts', // outputs './out/types.d.ts'
   *     },
   *   ]
   * })
   * ```
   *
   * @default undefined
   */
  output?: string;
  /**
   * Specifies options for the `rolldown-plugin-dts` plugin.
   */
  dtsPlugin?: Options$1;
  input?: never;
  name?: never;
  globals?: never;
  extend?: never;
  minify?: never;
  copy?: never;
  recursive?: never;
  filter?: never;
  template?: never;
}
interface EntryCopy {
  /**
   * Copies either a single `file` or an entire `directory` structure from the source to the destination, including all subdirectories and files.
   *
   * This is especially useful for transferring assets that don't require any transformation, just a straightforward copy-paste operation.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   entries: [
   *     {
   *       // copies a single file
   *       copy: './src/path/file.ts', // outputs './dist/path/file.ts'
   *     },
   *     {
   *       // copies a single file
   *       copy: './src/path/file.ts',
   *       output: './dist/subdir/custom-file-name.ts',
   *     },
   *     {
   *       // copies the entire directory
   *       input: './src/path/srcdir',
   *       output: './dist/outdir',
   *     },
   *   ]
   * })
   * ```
   *
   * @default undefined
   */
  copy: string;
  /**
   * Specifies the path to the destination file or directory.
   */
  output?: string;
  /**
   * Copy directories recursively.
   *
   * @default true
   */
  recursive?: boolean;
  /**
   * Filters copied `files/directories`.
   *
   * Returns `true` to copy the item, `false` to ignore it.
   *
   * @default undefined
   */
  filter?(source: string, destination: string): boolean;
  input?: never;
  name?: never;
  globals?: never;
  extend?: never;
  minify?: never;
  dts?: never;
  dtsPlugin?: never;
  template?: never;
}
interface EntryTemplate {
  /**
   * Specifies the content of the `template` file.
   *
   * Provides the ability to dynamically inject template content during the build phase.
   *
   * @example
   *
   * ```ts
   * import { name, version } from './package.json'
   *
   * export default defineConfig({
   *   entries: [
   *     {
   *       template: `// Package ${name} v${version} ...`,
   *       output: './dist/template.ts',
   *     },
   *   ]
   * })
   * ```
   */
  template: string;
  /**
   * Specifies the path to the destination file.
   */
  output: string;
  input?: never;
  name?: never;
  globals?: never;
  extend?: never;
  minify?: never;
  dts?: never;
  dtsPlugin?: never;
  copy?: never;
  recursive?: never;
  filter?: never;
}
type EntryOptions = EntryChunk | EntryDts | EntryCopy | EntryTemplate;
//#endregion
//#region src/types/options.d.ts
interface Options {
  /**
   * Specifies the bundle's entry points.
   *
   * It allows you to manually set all build entries and adjust options for each one individually.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   entries: [
   *     { input: './src/index.ts' }, // outputs './dist/index.js'
   *     { dts: './src/types.ts' }, // outputs './dist/types.d.ts'
   *     // ...
   *   ]
   * })
   * ```
   */
  entries: EntryOptions[];
  /**
   * Specifies the output directory for production bundle.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   outDir: './output',
   * })
   * ```
   *
   * @default 'dist'
   */
  outDir?: string;
  /**
   * Specifies the module IDs, or regular expressions to match module IDs,
   * that should remain external to the bundle.
   *
   * IDs and regexps from this option are applied globally to all entries.
   *
   * Also, it is possible to define externals individually per entry (`entry.externals`).
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   externals: ['id-1', 'id-2', /regexp/],
   * })
   * ```
   *
   * @default [/^node:/,/^@types/,/^@rollup/,/^@rolldown/,/^@hypernym/,/^rollup/,/^rolldown/,...pkg.dependencies]
   */
  externals?: (string | RegExp)[];
  /**
   * Provides a powerful hooking system to further expand bundling mode.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   hooks: {
   *     'build:end': async (options, buildStats) => {
   *       // ...
   *     }
   *   }
   * })
   * ```
   *
   * @default undefined
   */
  hooks?: HooksOptions;
  /**
   * Controls code minification for all `chunk` entries.
   *
   * - `true` - Enable full minification including code compression and dead code elimination.
   * - `false` - Disable minification (default).
   * - `'dce-only'` - Only perform dead code elimination without code compression.
   * - `MinifyOptions` - Fine-grained control over minification settings.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   minify: true,
   * })
   * ```
   *
   * It can also be set per entry.
   *
   * ```ts
   * export default defineConfig({
   *   entries: [
   *     {
   *       input: './src/index.ts',
   *       minify: true,
   *     },
   *   ],
   * })
   * ```
   *
   * @default undefined
   */
  minify?: OutputOptions['minify'];
  /**
   * Specifies the path to the project root (current working directory).
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   cwd: './dir',
   * })
   * ```
   *
   * @default undefined
   */
  cwd?: string;
  /**
   * Specifies the path to the `tsconfig` file.
   *
   * By default, if the file `tsconfig.json` exists in the project root, it will be used as the default config file.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   tsconfig: './path/to/tsconfig.json',
   * })
   * ```
   *
   * @default undefined
   */
  tsconfig?: string;
  /**
   * Specifies which comments are preserved in the output.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   comments: true,
   * })
   * ```
   *
   * @default { legal: true, annotation: true, jsdoc: false }
   */
  comments?: OutputOptions['comments'];
}
//#endregion
//#region src/types/hooks.d.ts
interface HooksOptions {
  /**
   * Called at the beginning of bundling.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   hooks: {
   *     'bundle:start': async (options) => {
   *       // ...
   *     }
   *   }
   * })
   * ```
   *
   * @default undefined
   */
  'bundle:start'?: (options: Options) => void | Promise<void>;
  /**
   * Called at the beginning of building.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   hooks: {
   *     'build:start': async (options, stats) => {
   *       // ...
   *     }
   *   }
   * })
   * ```
   *
   * @default undefined
   */
  'build:start'?: (options: Options, stats: BuildStats) => void | Promise<void>;
  /**
   * Called on each entry just before the build process.
   *
   * Provides the ability to customize entry options before they are passed to the next phase.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   hooks: {
   *     'build:entry:start': async (entry, stats) => {
   *      // ...
   *     }
   *   }
   * })
   * ```
   *
   * @default undefined
   */
  'build:entry:start'?: (entry: BuildEntryOptions, stats: BuildEntryStats) => void | Promise<void>;
  /**
   * Called on each entry right after the build process is completed.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   hooks: {
   *     'build:entry:end': async (entry, stats) => {
   *      // ...
   *     }
   *   }
   * })
   * ```
   *
   * @default undefined
   */
  'build:entry:end'?: (entry: BuildEntryOptions, stats: BuildEntryStats) => void | Promise<void>;
  /**
   * Called right after building is complete.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   hooks: {
   *     'build:end': async (options, stats) => {
   *       // ...
   *     }
   *   }
   * })
   * ```
   *
   * @default undefined
   */
  'build:end'?: (options: Options, stats: BuildStats) => void | Promise<void>;
  /**
   * Called right after bundling is complete.
   *
   * @example
   *
   * ```ts
   * export default defineConfig({
   *   hooks: {
   *     'bundle:end': async (options) => {
   *       // ...
   *     }
   *   }
   * })
   * ```
   *
   * @default undefined
   */
  'bundle:end'?: (options: Options) => void | Promise<void>;
}
//#endregion
//#region src/types/loader.d.ts
interface ConfigLoader {
  options: Options;
  path: string;
}
//#endregion
//#region src/config.d.ts
/**
 * List of global default patterns for external module identifiers.
 *
 * @example
 *
 * ```ts
 * import { externals } from '@hypernym/bundler'
 *
 * export default defineConfig({
 *   entries: [
 *     {
 *       input: './src/index.ts',
 *       externals: [...externals, 'id', /regexp/]
 *     },
 *   ]
 * })
 * ```
 */
declare const externals: RegExp[];
/**
 * ESM & TS module bundler.
 *
 * Automatically detects a custom configuration file at the project root, which can override or extend the build behavior.
 *
 * Configuration file also accepts `.js`, `.mjs`, `.ts`, `.mts` formats.
 *
 * @example
 *
 * ```ts
 * import { defineConfig } from '@hypernym/bundler'
 *
 * export default defineConfig({
 *   // ...
 * })
 * ```
 *
 * @see [Repository](https://github.com/hypernym-studio/bundler)
 */
declare function defineConfig(options: Options): Options;
//#endregion
export { BuildEntryOptions, BuildEntryStats, BuildLogs, BuildStats, ConfigLoader, EntryBase, EntryChunk, EntryCopy, EntryDts, EntryOptions, EntryTemplate, HooksOptions, Options, build, defineConfig, externals };