@hypernym/bundler 0.3.0 → 0.4.0

package/README.md

@@ -62,6 +62,162 @@ export default defineConfig({
 npx hyperbundler
 ```
 
+## Hooks
+
+List of lifecycle hooks that are called at various phases:
+
+| Name                                    | Description                                                      |
+| --------------------------------------- | ---------------------------------------------------------------- |
+| [`bundle:start`](#bundlestart)          | Called at the beginning of bundling.                             |
+| [`build:start`](#buildstart)            | Called at the beginning of building.                             |
+| [`build:entry:start`](#buildentrystart) | Called on each entry just before the build process.              |
+| [`build:entry:end`](#buildentryend)     | Called on each entry right after the build process is completed. |
+| [`build:end`](#buildend)                | Called right after building is complete.                         |
+| [`bundle:end`](#bundleend)              | Called right after bundling is complete.                         |
+
+### bundle:start
+
+- Type: `(options: Options) => void | Promise<void>`
+- Default: `undefined`
+
+Called at the beginning of bundling.
+
+```ts
+// bundler.config.ts
+
+import { defineConfig } from '@hypernym/bundler'
+
+export default defineConfig({
+  hooks: {
+    'bundle:start': async (options) => {
+      // ...
+    },
+  },
+})
+```
+
+### build:start
+
+- Type: `(options: Options, stats: BuildStats) => void | Promise<void>`
+- Default: `undefined`
+
+Called at the beginning of building.
+
+```ts
+// bundler.config.ts
+
+import { defineConfig } from '@hypernym/bundler'
+
+export default defineConfig({
+  hooks: {
+    'build:start': async (options, stats) => {
+      // ...
+    },
+  },
+})
+```
+
+### build:entry:start
+
+- Type: `(options: BuildEntryOptions, stats: BuildStats) => void | Promise<void>`
+- Default: `undefined`
+
+Called on each entry just before the build process.
+
+Provides the ability to customize entry options before they are passed to the next phase.
+
+```ts
+// bundler.config.ts
+
+import { defineConfig } from '@hypernym/bundler'
+import { plugin1, plugin2, plugin3 } from './src/utils/plugins.js'
+
+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
+        ]
+      }
+    },
+  },
+})
+```
+
+### build:entry:end
+
+- Type: `(options: BuildEntryOptions, stats: BuildStats) => void | Promise<void>`
+- Default: `undefined`
+
+Called on each entry right after the build process is completed.
+
+```ts
+// bundler.config.ts
+
+import { defineConfig } from '@hypernym/bundler'
+
+export default defineConfig({
+  hooks: {
+    'build:entry:end': async (options, stats) => {
+      // ...
+    },
+  },
+})
+```
+
+### build:end
+
+- Type: `(options: Options, stats: BuildStats) => void | Promise<void>`
+- Default: `undefined`
+
+Called right after building is complete.
+
+```ts
+// bundler.config.ts
+
+import { defineConfig } from '@hypernym/bundler'
+
+export default defineConfig({
+  hooks: {
+    'build:end': async (options, stats) => {
+      // ...
+    },
+  },
+})
+```
+
+### bundle:end
+
+- Type: `(options: Options) => void | Promise<void>`
+- Default: `undefined`
+
+Called right after bundling is complete.
+
+```ts
+// bundler.config.ts
+
+import { defineConfig } from '@hypernym/bundler'
+
+export default defineConfig({
+  hooks: {
+    'bundle:end': async (options) => {
+      // ...
+    },
+  },
+})
+```
+
 ## Options
 
 ### outDir
@@ -74,11 +230,36 @@ Specifies the output directory for production bundle.
 ```ts
 // bundler.config.ts
 
+import { defineConfig } from '@hypernym/bundler'
+
 export default defineConfig({
   outDir: 'output',
 })
 ```
 
+### externals
+
+- Type: `(string | RegExp)[]`
+- Default: `[/^node:/, /^@types/, /^@rollup/, /^@hypernym/, /^rollup/, ...pkg.dependencies]`
+
+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`).
+
+```ts
+// bundler.config.ts
+
+import { defineConfig } from '@hypernym/bundler'
+
+export default defineConfig({
+  externals: ['id-1', 'id-2', /regexp/],
+})
+```
+
+## CLI
+
 ### Custom Config
 
 Set a custom config path via the CLI command:

package/dist/bin/index.mjs

@@ -25,7 +25,7 @@ const externals = [
 ];
 
 const name = "bundler";
-const version = `0.3.0`;
+const version = `0.4.0`;
 
 const cl = console.log;
 const logger = {
@@ -204,106 +204,114 @@ async function build(cwd, options) {
       const entryStart = Date.now();
       const logFilter = getLogFilter(entry.logFilter || []);
       if ("input" in entry) {
-        const { input, externals, plugins, banner, footer } = entry;
-        const buildLogs = [];
-        const _output = getOutputPath(outDir, input);
+        const _output = getOutputPath(outDir, entry.input);
         let _format = "esm";
         if (_output.endsWith(".cjs"))
           _format = "cjs";
-        const output = entry.output || _output;
-        const format = entry.format || _format;
-        const _plugins = [esbuild(plugins?.esbuild)];
-        if (plugins?.json) {
-          const jsonOptions = isObject(plugins.json) ? plugins.json : void 0;
-          _plugins.push(jsonPlugin(jsonOptions));
+        const buildLogs = [];
+        const _entry = {
+          input: entry.input,
+          output: entry.output || _output,
+          externals: entry.externals || options.externals,
+          format: entry.format || _format,
+          plugins: [esbuild(entry.plugins?.esbuild)],
+          pluginsOptions: entry.plugins,
+          banner: entry.banner,
+          footer: entry.footer
+        };
+        if (_entry.pluginsOptions?.json) {
+          const jsonOptions = isObject(_entry.pluginsOptions.json) ? _entry.pluginsOptions.json : void 0;
+          _entry.plugins.push(jsonPlugin(jsonOptions));
         }
-        if (plugins?.replace) {
-          _plugins.unshift(
+        if (_entry.pluginsOptions?.replace) {
+          _entry.plugins.unshift(
             replacePlugin({
               true: true,
-              ...plugins.replace
+              ..._entry.pluginsOptions.replace
             })
           );
         }
-        if (plugins?.resolve) {
-          const resolveOptions = isObject(plugins.resolve) ? plugins.resolve : void 0;
-          _plugins.unshift(resolvePlugin(resolveOptions));
+        if (_entry.pluginsOptions?.resolve) {
+          const resolveOptions = isObject(_entry.pluginsOptions.resolve) ? _entry.pluginsOptions.resolve : void 0;
+          _entry.plugins.unshift(resolvePlugin(resolveOptions));
         }
-        if (hooks?.["rollup:plugins"]) {
-          hooks["rollup:plugins"](_plugins, {
-            ...entry,
-            input,
-            output,
-            format
-          });
+        if (hooks?.["build:entry:start"]) {
+          await hooks["build:entry:start"](_entry, buildStats);
         }
-        const builder = await rollup({
-          input: resolve(cwd, input),
-          external: externals || options.externals,
-          plugins: _plugins,
+        const _build = await rollup({
+          input: resolve(cwd, _entry.input),
+          external: _entry.externals,
+          plugins: _entry.plugins,
           onLog: (level, log) => {
             if (logFilter(log))
               buildLogs.push({ level, log });
           }
         });
-        await builder.write({
-          file: resolve(cwd, output),
-          format,
-          banner,
-          footer
+        await _build.write({
+          file: resolve(cwd, _entry.output),
+          format: _entry.format,
+          banner: _entry.banner,
+          footer: _entry.footer
         });
-        const stats = await stat(resolve(cwd, output));
+        const stats = await stat(resolve(cwd, _entry.output));
         buildStats.files.push({
-          path: output,
+          path: _entry.output,
           size: stats.size,
           buildTime: Date.now() - entryStart,
-          format,
+          format: _entry.format,
           logs: buildLogs
         });
         buildStats.size = buildStats.size + stats.size;
+        if (hooks?.["build:entry:end"]) {
+          await hooks["build:entry:end"](_entry, buildStats);
+        }
       }
       if ("types" in entry) {
-        const { types, externals, plugins, banner, footer } = entry;
-        const buildLogs = [];
-        const _output = getOutputPath(outDir, types, true);
+        const _output = getOutputPath(outDir, entry.types, true);
         let _format = "esm";
         if (_output.endsWith(".d.cts"))
           _format = "cjs";
-        const output = entry.output || _output;
-        const format = entry.format || _format;
-        const _plugins = [dts(plugins?.dts)];
-        if (hooks?.["rollup:plugins"]) {
-          hooks["rollup:plugins"](_plugins, {
-            ...entry,
-            types,
-            output,
-            format
-          });
+        const buildLogs = [];
+        const _entry = {
+          types: entry.types,
+          output: entry.output || _output,
+          externals: entry.externals || options.externals,
+          format: entry.format || _format,
+          plugins: [dts(entry.plugins?.dts)],
+          pluginsOptions: entry.plugins,
+          banner: entry.banner,
+          footer: entry.footer
+        };
+        if (hooks?.["build:entry:start"]) {
+          await hooks["build:entry:start"](_entry, buildStats);
         }
-        const builder = await rollup({
-          input: resolve(cwd, types),
-          external: externals || options.externals,
-          plugins: _plugins,
+        const _build = await rollup({
+          input: resolve(cwd, _entry.types),
+          external: _entry.externals,
+          plugins: _entry.plugins,
           onLog: (level, log) => {
             if (logFilter(log))
               buildLogs.push({ level, log });
           }
         });
-        await builder.write({
-          file: resolve(cwd, output),
-          format,
-          banner,
-          footer
+        await _build.write({
+          file: resolve(cwd, _entry.output),
+          format: _entry.format,
+          banner: _entry.banner,
+          footer: _entry.footer
         });
-        const stats = await stat(resolve(cwd, output));
+        const stats = await stat(resolve(cwd, _entry.output));
         buildStats.files.push({
-          path: output,
+          path: _entry.output,
           size: stats.size,
           buildTime: Date.now() - entryStart,
-          format,
+          format: _entry.format,
           logs: buildLogs
         });
         buildStats.size = buildStats.size + stats.size;
+        if (hooks?.["build:entry:end"]) {
+          await hooks["build:entry:end"](_entry, buildStats);
+        }
       }
     }
     buildStats.buildTime = Date.now() - start;
@@ -356,7 +364,12 @@ async function createBuilder(cwd, args, options) {
         format = "dts";
       if (file.logs) {
         for (const log of file.logs) {
-          cl(magenta("!"), magenta(log.log.message));
+          cl(
+            magenta("!"),
+            dim("\u251C\u2500"),
+            magenta(`${log.level}:`),
+            magenta(log.log.message)
+          );
         }
       }
       cl(

package/dist/types/index.d.ts

@@ -5,13 +5,15 @@ import { RollupNodeResolveOptions } from '@rollup/plugin-node-resolve';
 import { TransformOptions } from 'esbuild';
 import { Options as Options$1 } from 'rollup-plugin-dts';
 
-interface BuildPlugins {
+interface PluginsInput {
     esbuild?: TransformOptions;
-    dts?: Options$1;
     resolve?: RollupNodeResolveOptions | true;
     json?: RollupJsonOptions | true;
     replace?: RollupReplaceOptions;
 }
+interface PluginsTypes {
+    dts?: Options$1;
+}
 
 interface EntryBase {
     /**
@@ -66,7 +68,7 @@ interface EntryInput extends EntryBase {
      *
      * @default undefined
      */
-    plugins?: BuildPlugins;
+    plugins?: PluginsInput;
 }
 interface EntryTypes extends EntryBase {
     /**
@@ -78,10 +80,66 @@ interface EntryTypes extends EntryBase {
      *
      * @default undefined
      */
-    plugins?: Pick<BuildPlugins, 'dts'>;
+    plugins?: PluginsTypes;
 }
 type EntryOptions = EntryInput | EntryTypes;
 
+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' }, // => './dist/index.mjs'
+     *     { types: './src/types.ts' }, // => './dist/types.d.ts'
+     *     // ...
+     *   ]
+     * })
+     * ```
+     */
+    entries: EntryOptions[];
+    /**
+     * Specifies the output directory for production bundle.
+     *
+     * @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`).
+     *
+     * @default [/^node:/, /^@types/, /^@rollup/, /^@hypernym/, /^rollup/, ...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;
+}
+
 interface BuildLogs {
     level: LogLevel;
     log: RollupLog;
@@ -125,10 +183,22 @@ interface BuildStats {
         logs: BuildLogs[];
     }[];
 }
+interface BuildEntryOptions extends EntryBase, Partial<Omit<EntryInput, 'plugins'>>, Partial<Omit<EntryTypes, 'plugins'>> {
+    /**
+     * Specifies list of plugins.
+     */
+    plugins: Plugin[];
+    /**
+     * Specifies options for default plugins.
+     *
+     * @default undefined
+     */
+    pluginsOptions?: PluginsInput & PluginsTypes;
+}
 
 interface HooksOptions {
     /**
-     * Called just before bundling started.
+     * Called at the beginning of bundling.
      *
      * @example
      *
@@ -144,16 +214,16 @@ interface HooksOptions {
      *
      * @default undefined
      */
-    'bundle:start'?: (options?: Options) => void | Promise<void>;
+    'bundle:start'?: (options: Options) => void | Promise<void>;
     /**
-     * Called just before building started.
+     * Called at the beginning of building.
      *
      * @example
      *
      * ```ts
      * export default defineConfig({
      *   hooks: {
-     *     'build:start': async (options, buildStats) => {
+     *     'build:start': async (options, stats) => {
      *       // ...
      *     }
      *   }
@@ -162,11 +232,11 @@ interface HooksOptions {
      *
      * @default undefined
      */
-    'build:start'?: (options?: Options, buildStats?: BuildStats) => void | Promise<void>;
+    'build:start'?: (options: Options, stats: BuildStats) => void | Promise<void>;
     /**
-     * Called just before the initialization of the Rollup plugin.
+     * Called on each entry just before the build process.
      *
-     * Provides the ability to add and manipulate custom plugins.
+     * Provides the ability to customize entry options before they are passed to the next phase.
      *
      * @example
      *
@@ -175,17 +245,22 @@ interface HooksOptions {
      *
      * export default defineConfig({
      *   hooks: {
-     *     'rollup:plugins': (plugins, entry) => {
-     *       // adds a custom plugin before the default bundler plugins
-     *       plugins.unshift(plugin1())
-     *       // adds a custom plugin after the default bundler plugins
-     *       plugins.push(plugin2())
-     *       // adds a custom plugin for a specific entry only
-     *       if (entry?.input?.includes('./src/index.ts')) {
-     *         plugins.push(plugin3())
+     *     '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
+     *         ]
      *       }
-     *       // returns the final list of plugins
-     *       return plugins
      *     }
      *   }
      * })
@@ -193,17 +268,17 @@ interface HooksOptions {
      *
      * @default undefined
      */
-    'rollup:plugins'?: (plugins: Plugin[], entry?: Partial<EntryInput> & Partial<Omit<EntryTypes, 'plugins'>>) => Plugin[];
+    'build:entry:start'?: (options: BuildEntryOptions, stats: BuildStats) => void | Promise<void>;
     /**
-     * Called right after building is complete.
+     * Called on each entry right after the build process is completed.
      *
      * @example
      *
      * ```ts
      * export default defineConfig({
      *   hooks: {
-     *     'build:end': async (options, buildStats) => {
-     *       // ...
+     *     'build:entry:end': async (options, stats) => {
+     *      // ...
      *     }
      *   }
      * })
@@ -211,16 +286,16 @@ interface HooksOptions {
      *
      * @default undefined
      */
-    'build:end'?: (options?: Options, buildStats?: BuildStats) => void | Promise<void>;
+    'build:entry:end'?: (options: BuildEntryOptions, stats: BuildStats) => void | Promise<void>;
     /**
-     * Called right after bundling is complete.
+     * Called right after building is complete.
      *
      * @example
      *
      * ```ts
      * export default defineConfig({
      *   hooks: {
-     *     'bundle:end': async (options) => {
+     *     'build:end': async (options, stats) => {
      *       // ...
      *     }
      *   }
@@ -229,54 +304,16 @@ interface HooksOptions {
      *
      * @default undefined
      */
-    'bundle:end'?: (options?: Options) => void | Promise<void>;
-}
-
-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' }, // => './dist/index.mjs'
-     *     { types: './src/types.ts' }, // => './dist/types.d.ts'
-     *     // ...
-     *   ]
-     * })
-     * ```
-     */
-    entries: EntryOptions[];
+    'build:end'?: (options: Options, stats: BuildStats) => void | Promise<void>;
     /**
-     * Specifies the output directory for production bundle.
-     *
-     * @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`).
-     *
-     * @default [/^node:/, /^@types/, /^@rollup/, /^@hypernym/, /^rollup/, ...pkg.dependencies]
-     */
-    externals?: (string | RegExp)[];
-    /**
-     * Provides a powerful hooking system to further expand bundling mode.
+     * Called right after bundling is complete.
      *
      * @example
      *
      * ```ts
      * export default defineConfig({
      *   hooks: {
-     *     'build:end': async (options, buildStats) => {
+     *     'bundle:end': async (options) => {
      *       // ...
      *     }
      *   }
@@ -285,7 +322,7 @@ interface Options {
      *
      * @default undefined
      */
-    hooks?: HooksOptions;
+    'bundle:end'?: (options: Options) => void | Promise<void>;
 }
 
 /**
@@ -309,4 +346,4 @@ interface Options {
 declare const externals: RegExp[];
 declare function defineConfig(options: Options): Options;
 
-export { defineConfig, externals };
+export { type BuildLogs, type BuildStats, type EntryBase, type EntryInput, type EntryOptions, type EntryTypes, type HooksOptions, type Options, type PluginsInput, type PluginsTypes, defineConfig, externals };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypernym/bundler",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": "Hypernym Studio",
   "description": "ESM & TS module bundler.",
   "license": "MIT",
@@ -63,7 +63,7 @@
     "@rollup/plugin-json": "^6.0.1",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@rollup/plugin-replace": "^5.0.4",
-    "esbuild": "^0.19.4",
+    "esbuild": "^0.19.5",
     "rollup": "^4.1.4",
     "rollup-plugin-dts": "^6.1.0"
   },
@@ -71,10 +71,10 @@
     "@hypernym/eslint-config": "^2.0.2",
     "@hypernym/prettier-config": "^2.0.2",
     "@hypernym/tsconfig": "^1.1.0",
-    "@types/node": "^20.8.6",
+    "@types/node": "^20.8.7",
     "eslint": "^8.51.0",
     "prettier": "^3.0.3",
-    "tsx": "^3.13.0",
+    "tsx": "^3.14.0",
     "typescript": "^5.2.2"
   },
   "engines": {