@hypernym/bundler 0.10.0 → 0.12.0

package/dist/types/index.d.ts

@@ -1,29 +1,24 @@
-import { OutputOptions, LogLevel, RollupLog, Plugin } from 'rollup';
+import { OutputOptions, Plugin, LogLevel, RollupLog } from 'rollup';
 import { RollupReplaceOptions } from '@rollup/plugin-replace';
 import { RollupJsonOptions } from '@rollup/plugin-json';
 import { RollupNodeResolveOptions } from '@rollup/plugin-node-resolve';
+import { RollupAliasOptions, Alias } from '@rollup/plugin-alias';
 import { TransformOptions } from 'esbuild';
 import { Options as Options$1 } from 'rollup-plugin-dts';
 
-interface PluginsInput {
+interface TransformersChunk {
     esbuild?: TransformOptions;
     resolve?: RollupNodeResolveOptions | true;
-    json?: RollupJsonOptions | true;
     replace?: RollupReplaceOptions;
+    json?: RollupJsonOptions | true;
+    alias?: RollupAliasOptions;
 }
-interface PluginsTypes {
+interface TransformersDeclaration {
     dts?: Options$1;
+    alias?: RollupAliasOptions;
 }
 
 interface EntryBase {
-    /**
-     * Specifies the path of the transformed module.
-     *
-     * If not specified, matches the `input` path with the appropriate extension.
-     *
-     * @default undefined
-     */
-    output?: string;
     /**
      * Specifies the format of the generated module.
      *
@@ -75,18 +70,40 @@ interface EntryBase {
      * @default undefined
      */
     logFilter?: string[];
+    /**
+     * Specifies `rollup` plugins.
+     *
+     * Adding custom plugins disables all built-in `transformers` for full customization.
+     *
+     * @default undefined
+     */
+    plugins?: Plugin[];
 }
-interface EntryInput extends EntryBase {
+interface EntryChunk extends EntryBase {
     /**
-     * Specifies the path of the module's build source.
+     * Specifies the path of the build source.
      */
-    input: string;
+    input?: string;
     /**
-     * Specifies plugin options.
+     * Specifies the path of the transformed file.
      *
      * @default undefined
      */
-    plugins?: PluginsInput;
+    output?: string;
+    /**
+     * Specifies the built-in `transformers` options.
+     *
+     * Available transformers:
+     *
+     * - `esbuild`
+     * - `resolve`
+     * - `replace`
+     * - `json`
+     * - `alias`
+     *
+     * @default undefined
+     */
+    transformers?: TransformersChunk;
     /**
      * Specifies the global variable name that representing exported bundle.
      *
@@ -109,24 +126,68 @@ interface EntryInput extends EntryBase {
      * Intended for `umd/iife` formats.
      */
     extend?: OutputOptions['extend'];
+    declaration?: never;
+    copy?: never;
+    template?: never;
+}
+interface EntryDeclaration extends EntryBase {
+    /**
+     * Specifies the path of the TypeScript `declaration` build source.
+     */
+    declaration?: string;
+    /**
+     * Specifies the path of the TypeScript  transformed `declaration` file.
+     *
+     * @default undefined
+     */
+    output?: string;
+    /**
+     * Specifies the built-in `transformers` options.
+     *
+     * Available transformers:
+     *
+     * - `dts`
+     * - `alias`
+     *
+     * @default undefined
+     */
+    transformers?: TransformersDeclaration;
+    input?: never;
+    copy?: never;
+    template?: never;
+    name?: never;
+    globals?: never;
+    extend?: never;
 }
-interface EntryTypes extends EntryBase {
+interface CopyOptions {
+    /**
+     * Specifies the path of the source.
+     */
+    input: string | string[];
     /**
-     * Specifies the path of the module's build source that contains only TS definitions.
+     * Specifies the path of the destination directory.
      */
-    types: string;
+    output: string;
     /**
-     * Specifies plugin options.
+     * Copy directories recursively.
+     *
+     * @default true
+     */
+    recursive?: boolean;
+    /**
+     * Filters copied `files/directories`.
+     *
+     * Returns `true` to copy the item, `false` to ignore it.
      *
      * @default undefined
      */
-    plugins?: PluginsTypes;
+    filter?(source: string, destination: string): boolean;
 }
-interface EntryTemplate extends Pick<EntryBase, 'logFilter'> {
+interface EntryCopy {
     /**
-     * Specifies the build entry as a module template.
+     * Copies the single `file` or entire `directory` structure from source to destination, including subdirectories and files.
      *
-     * Provides the ability to dynamically inject template content during the build phase.
+     * This can be very useful for copying some assets that don't need a transformation process, but a simple copy paste feature.
      *
      * @example
      *
@@ -134,25 +195,30 @@ interface EntryTemplate extends Pick<EntryBase, 'logFilter'> {
      * export default defineConfig({
      *   entries: [
      *     {
-     *       template: true,
-     *       output: './dist/template.ts',
-     *       content: '// TypeScript code...',
-     *     },
+     *       copy: {
+     *         input: './src/path/file.ts', // or ['path-dir', 'path-file.ts', ...]
+     *         output: './dist/out', // path to output dir
+     *       }
+     *     }
      *   ]
      * })
      * ```
+     *
+     * @default undefined
      */
-    template: true;
-    /**
-     * Specifies the path of the transformed module template.
-     */
-    output: string;
-    /**
-     * Specifies the content of the module template.
-     */
-    content: OutputOptions['intro'];
+    copy?: CopyOptions;
+    input?: never;
+    declaration?: never;
+    template?: never;
+    name?: never;
+    globals?: never;
+    extend?: never;
+}
+interface EntryTemplate {
     /**
-     * Specifies the format of the generated module template.
+     * Specifies the content of the `template` file.
+     *
+     * Provides the ability to dynamically inject template content during the build phase.
      *
      * @example
      *
@@ -160,26 +226,26 @@ interface EntryTemplate extends Pick<EntryBase, 'logFilter'> {
      * export default defineConfig({
      *   entries: [
      *     {
-     *       template: true,
-     *       output: './dist/template.json',
-     *       content: '{}',
-     *       format: 'json',
+     *       template: `// TypeScript code...`,
+     *       output: './dist/template.ts',
      *     },
      *   ]
      * })
      * ```
-     *
-     * @default 'esm'
      */
-    format?: string;
+    template: string;
     /**
-     * Specifies plugin options.
-     *
-     * @default undefined
+     * Specifies the path of the transformed `template` file.
      */
-    plugins?: Pick<PluginsInput, 'esbuild'>;
+    output: string;
+    input?: never;
+    declaration?: never;
+    copy?: never;
+    name?: never;
+    globals?: never;
+    extend?: never;
 }
-type EntryOptions = EntryInput | EntryTypes | EntryTemplate;
+type EntryOptions = EntryChunk | EntryDeclaration | EntryCopy | EntryTemplate;
 
 interface Options {
     /**
@@ -193,7 +259,7 @@ interface Options {
      * export default defineConfig({
      *   entries: [
      *     { input: './src/index.ts' }, // => './dist/index.mjs'
-     *     { types: './src/types.ts' }, // => './dist/types.d.ts'
+     *     { declaration: './src/types.ts' }, // => './dist/types.d.ts'
      *     // ...
      *   ]
      * })
@@ -203,6 +269,14 @@ interface Options {
     /**
      * Specifies the output directory for production bundle.
      *
+     * @example
+     *
+     * ```ts
+     * export default defineConfig({
+     *   outDir: 'output',
+     * })
+     * ```
+     *
      * @default 'dist'
      */
     outDir?: string;
@@ -214,6 +288,14 @@ interface Options {
      *
      * 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/, /^@hypernym/, /^rollup/, ...pkg.dependencies]
      */
     externals?: (string | RegExp)[];
@@ -236,23 +318,38 @@ interface Options {
      */
     hooks?: HooksOptions;
     /**
-     * Specifies global path alias support.
+     * Specifies prefixes that will resolve imports with custom paths.
+     *
+     * Enables these `alias` by default:
      *
-     * If true, it enables import prefixes:
+     * ```ts
+     * // Imports module from './src/utils/index.js'
+     * import { module } from '@/utils' // @
+     * import { module } from '~/utils' // ~
+     * ```
      *
-     * - `@/*`
-     * - `~/*`
+     * Also, it is possible to completely override the default aliases by setting custom ones.
      *
      * @example
      *
      * ```ts
+     * export default defineConfig({
+     *   alias: [
+     *     { find: /^#/, replacement: resolve('./src') },
+     *   ]
+     * })
+     * ```
+     *
+     * Now imports can be used like this:
+     *
+     * ```ts
      * // Imports module from './src/utils/index.js'
-     * import { module } from '@/utils/index.js'
+     * import { module } from '#/utils' // #
      * ```
      *
      * @default undefined
      */
-    alias?: true;
+    alias?: Alias[];
 }
 
 interface BuildLogs {
@@ -298,17 +395,17 @@ interface BuildStats {
         logs: BuildLogs[];
     }[];
 }
-interface BuildEntryOptions extends EntryBase, Partial<Omit<EntryInput, 'plugins'>>, Partial<Omit<EntryTypes, 'plugins'>> {
-    /**
-     * Specifies list of plugins.
-     */
-    plugins: Plugin[];
+interface BuildEntryOptions extends EntryBase {
     /**
      * Specifies options for default plugins.
      *
      * @default undefined
      */
-    pluginsOptions?: PluginsInput & PluginsTypes;
+    transformers?: TransformersChunk & TransformersDeclaration;
+    /**
+     * Specifies list of default plugins.
+     */
+    defaultPlugins: Plugin[];
 }
 
 interface HooksOptions {
@@ -356,26 +453,10 @@ interface HooksOptions {
      * @example
      *
      * ```ts
-     * import { plugin1, plugin2, plugin3 } from './plugins'
-     *
      * export default defineConfig({
      *   hooks: {
      *     'build:entry:start': async (options, stats) => {
-     *       // adds custom plugins for a specific entry only
-     *       if (options.input?.includes('./src/index.ts')) {
-     *         options.plugins = [
-     *           plugin1(), // adds a custom plugin before the default bundler plugins
-     *           ...options.plugins, // list of default bundler plugins
-     *           plugin2(), // adds a custom plugin after the default bundler plugins
-     *         ]
-     *       }
-     *       // adds custom plugins for a specific types only
-     *       if (options.types?.includes('./src/types.ts')) {
-     *         options.plugins = [
-     *           ...options.plugins, // list of default bundler plugins
-     *           plugin3(), // adds a custom plugin designed to work only with TS declarations
-     *         ]
-     *       }
+     *      // ...
      *     }
      *   }
      * })
@@ -440,6 +521,11 @@ interface HooksOptions {
     'bundle:end'?: (options: Options) => void | Promise<void>;
 }
 
+interface ConfigLoader {
+    options: Options;
+    path: string;
+}
+
 /**
  * List of global defaults for externals.
  *
@@ -462,26 +548,32 @@ declare const externals: RegExp[];
 declare function defineConfig(options: Options): Options;
 
 /**
- * Replaces the external module ID with a custom value.
+ * Resolves external module IDs into custom paths.
  *
  * @example
  *
  * ```ts
- * import { defineConfig, replacePath } from '@hypernym/bundler'
+ * import { defineConfig, resolvePaths } from '@hypernym/bundler'
  *
  * export default defineConfig({
  *   entries: [
  *     {
  *       input: './src/index.ts',
- *       output: './dist/index.mjs',
  *       externals: [/^@\/path/],
- *       // replaces `@/path` with `./path/index.mjs`
- *       paths: (id) => replacePath(/^@\/path/, './easing/index.mjs')(id),
+ *       paths: resolvePaths([
+ *         // replaces `@/path` with `./path/index.mjs`
+ *         { find: /^@\/path/, replacement: './path/index.mjs', }
+ *       ]),
  *     },
  *   ]
  * })
  * ```
  */
-declare function replacePath(path: RegExp | string, replace: string): (id: string) => string;
+declare function resolvePaths(options: ResolvePathsOptions[]): (id: string) => string;
+
+interface ResolvePathsOptions {
+    find: string | RegExp;
+    replacement: string;
+}
 
-export { type BuildLogs, type BuildStats, type EntryBase, type EntryInput, type EntryOptions, type EntryTemplate, type EntryTypes, type HooksOptions, type Options, type PluginsInput, type PluginsTypes, defineConfig, externals, replacePath };
+export { type BuildLogs, type BuildStats, type ConfigLoader, type CopyOptions, type EntryBase, type EntryChunk, type EntryCopy, type EntryDeclaration, type EntryOptions, type EntryTemplate, type HooksOptions, type Options, type ResolvePathsOptions, type TransformersChunk, type TransformersDeclaration, defineConfig, externals, resolvePaths };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypernym/bundler",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "author": "Hypernym Studio",
   "description": "ESM & TS module bundler.",
   "license": "MIT",
@@ -24,6 +24,7 @@
     "bundling",
     "javascript",
     "typescript",
+    "hyperbundler",
     "bundler",
     "builder",
     "package",
@@ -38,13 +39,13 @@
   },
   "scripts": {
     "build": "bun -b run ./src/bin/index.ts",
-    "lint": "eslint -c .config/eslint.config.js .",
-    "lint:fix": "eslint -c .config/eslint.config.js --fix .",
-    "format": "prettier --config .config/prettier.config.js --write .",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "format": "prettier --write .",
     "prepublishOnly": "npm run build"
   },
   "sideEffects": false,
-  "packageManager": "pnpm@9.9.0",
+  "packageManager": "pnpm@9.11.0",
   "engines": {
     "node": ">=20.0.0",
     "pnpm": ">=9.0.0"
@@ -62,24 +63,23 @@
     }
   },
   "dependencies": {
-    "@hypernym/args": "^0.2.1",
+    "@hypernym/args": "^0.3.0",
     "@hypernym/colors": "^1.0.1",
-    "@hypernym/spinner": "^0.2.0",
-    "@hypernym/utils": "^3.0.0",
+    "@hypernym/utils": "^3.4.0",
     "@rollup/plugin-alias": "^5.1.0",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-replace": "^5.0.7",
     "@rollup/pluginutils": "^5.1.0",
     "esbuild": "^0.23.1",
-    "rollup": "^4.21.2",
+    "rollup": "^4.22.2",
     "rollup-plugin-dts": "^6.1.1"
   },
   "devDependencies": {
     "@hypernym/eslint-config": "^3.5.0",
     "@hypernym/prettier-config": "^3.2.0",
-    "@hypernym/tsconfig": "^2.2.0",
-    "@types/node": "^22.5.4",
+    "@hypernym/tsconfig": "^2.4.0",
+    "@types/node": "^22.5.5",
     "eslint": "^9.10.0",
     "prettier": "^3.3.3",
     "typescript": "^5.5.4"

package/dist/bin/_empty.ts

@@ -1 +0,0 @@
-// Generated by @hypernym/bundler