@rsaf/bundler 0.0.4 → 0.0.5

package/dist/bundler/Bundler.d.ts

@@ -2,59 +2,71 @@ import esbuild from 'esbuild';
 import type { BuildResult } from 'esbuild';
 import type { ESBuildConfig } from '../types/config.js';
 /**
- * EsbuildCompiler
- *
- * Thin wrapper around esbuild that provides:
- * - build
- * - watch
- * - rebuild
- * - close
- *
- * It uses esbuild's `context()` + `watch()` APIs under the hood.
+ * A thin wrapper around the `esbuild` API designed to manage build lifecycles.
+ * The `Bundler` class abstracts the complexity of esbuild's `context()` and `watch()`
+ * APIs, providing a unified interface for initial builds, incremental rebuilds,
+ * and persistent file watching.
+ * @example
+ * ```ts
+ * const bundler = new Bundler(config);
+ * await bundler.build();
+ * ```
  */
 export declare class Bundler {
     private options;
     private context?;
     private lastResult?;
     private isWatching;
+    /**
+     * Creates an instance of the Bundler.
+     * @param options - Configuration options for the esbuild engine.
+     */
     constructor(options: ESBuildConfig);
     /**
-     * Adds an esbuild plugin to the compiler configuration.
+     * Injects an esbuild plugin into the current configuration.
+     * @param plugin - The esbuild plugin to add.
+     * @returns The current {@link Bundler} instance for method chaining.
      */
     addPlugin(plugin: esbuild.Plugin): this;
     /**
-     * Performs an initial build or rebuild depending on mode.
+     * Executes a build process.
+     * If the bundler is currently in watch mode, it performs an incremental
+     * rebuild using the existing context. Otherwise, it performs a fresh build.
+     * @returns A promise resolving to the {@link BuildResult}.
+     * @throws {@link AppError} with code `BUILD_FAILED` if the build process encounters errors.
      */
     build(): Promise<BuildResult>;
     /**
-     * Enables esbuild's internal watch mode.
-     *
-     * Note:
-     * If you're using chokidar for file watching,
-     * esbuild's onRebuild callback is NOT used anymore.
-     *
-     * Esbuild will still keep its rebuild context alive,
-     * but file watching is controlled externally.
+     * Initializes and starts esbuild's internal watch mode.
+     * This method creates a persistent build context. While esbuild's native
+     * watcher is activated, this setup is often used in conjunction with
+     * external watchers (like Chokidar) by calling {@link rebuild}.
+     * @remarks
+     * If a context already exists, it will be disposed of before creating a new one.
+     * @throws {@link AppError} if the context cannot be initialized.
      */
     watch(): Promise<void>;
     /**
-     * Manually trigger a rebuild.
-     *
-     * This is what chokidar will call when a file changes.
+     * Manually triggers an incremental rebuild.
+     * This is typically invoked by an external file watcher when changes are detected.
+     * @returns A promise resolving to the {@link BuildResult} of the increment.
+     * @throws {@link AppError} if called before {@link watch} has initialized a context.
      */
     rebuild(): Promise<BuildResult>;
     /**
-     * Dispose of resources.
-     *
-     * Releases esbuild’s internal rebuild/watcher context.
+     * Gracefully shuts down the bundler and releases system resources.
+     * This disposes of the esbuild context, stops watchers, and clears internal cache.
+     * @throws {@link AppError} if the disposal process fails.
      */
     dispose(): Promise<void>;
     /**
-     * Get last esbuild result.
+     * Retrieves the result of the most recent successful build or rebuild.
+     * @returns The {@link BuildResult} or `undefined` if no build has occurred yet.
      */
     getLastResult(): BuildResult | undefined;
     /**
-     * Whether the compiler is currently in watch mode.
+     * Indicates whether the bundler is currently in an active watch state.
+     * @returns `true` if watching, otherwise `false`.
      */
     isInWatchMode(): boolean;
 }

package/dist/bundler/Bundler.js

@@ -2,26 +2,32 @@
 import { AppError } from '@rsaf/core';
 import esbuild from 'esbuild';
 /**
- * EsbuildCompiler
- *
- * Thin wrapper around esbuild that provides:
- * - build
- * - watch
- * - rebuild
- * - close
- *
- * It uses esbuild's `context()` + `watch()` APIs under the hood.
+ * A thin wrapper around the `esbuild` API designed to manage build lifecycles.
+ * The `Bundler` class abstracts the complexity of esbuild's `context()` and `watch()`
+ * APIs, providing a unified interface for initial builds, incremental rebuilds,
+ * and persistent file watching.
+ * @example
+ * ```ts
+ * const bundler = new Bundler(config);
+ * await bundler.build();
+ * ```
  */
 export class Bundler {
     options;
     context;
     lastResult;
     isWatching = false;
+    /**
+     * Creates an instance of the Bundler.
+     * @param options - Configuration options for the esbuild engine.
+     */
     constructor(options) {
         this.options = options;
     }
     /**
-     * Adds an esbuild plugin to the compiler configuration.
+     * Injects an esbuild plugin into the current configuration.
+     * @param plugin - The esbuild plugin to add.
+     * @returns The current {@link Bundler} instance for method chaining.
      */
     addPlugin(plugin) {
         if (!this.options.plugins) {
@@ -31,16 +37,18 @@ export class Bundler {
         return this;
     }
     /**
-     * Performs an initial build or rebuild depending on mode.
+     * Executes a build process.
+     * If the bundler is currently in watch mode, it performs an incremental
+     * rebuild using the existing context. Otherwise, it performs a fresh build.
+     * @returns A promise resolving to the {@link BuildResult}.
+     * @throws {@link AppError} with code `BUILD_FAILED` if the build process encounters errors.
      */
     async build() {
         try {
             if (this.isWatching && this.context) {
-                // In watch mode, we can use rebuild
                 this.lastResult = await this.context.rebuild();
             }
             else {
-                // Initial build
                 this.lastResult = await esbuild.build(this.options);
             }
             return this.lastResult;
@@ -55,27 +63,23 @@ export class Bundler {
         }
     }
     /**
-     * Enables esbuild's internal watch mode.
-     *
-     * Note:
-     * If you're using chokidar for file watching,
-     * esbuild's onRebuild callback is NOT used anymore.
-     *
-     * Esbuild will still keep its rebuild context alive,
-     * but file watching is controlled externally.
+     * Initializes and starts esbuild's internal watch mode.
+     * This method creates a persistent build context. While esbuild's native
+     * watcher is activated, this setup is often used in conjunction with
+     * external watchers (like Chokidar) by calling {@link rebuild}.
+     * @remarks
+     * If a context already exists, it will be disposed of before creating a new one.
+     * @throws {@link AppError} if the context cannot be initialized.
      */
     async watch() {
         if (this.isWatching)
             return;
         this.isWatching = true;
-        // If an old context exists, dispose it
         if (this.context) {
             await this.dispose();
         }
         try {
-            // Create a new esbuild build context
             this.context = await esbuild.context(this.options);
-            // Start esbuild's watch mode with no onRebuild handlers
             await this.context.watch();
         }
         catch (error // eslint-disable-line
@@ -88,13 +92,14 @@ export class Bundler {
         }
     }
     /**
-     * Manually trigger a rebuild.
-     *
-     * This is what chokidar will call when a file changes.
+     * Manually triggers an incremental rebuild.
+     * This is typically invoked by an external file watcher when changes are detected.
+     * @returns A promise resolving to the {@link BuildResult} of the increment.
+     * @throws {@link AppError} if called before {@link watch} has initialized a context.
      */
     async rebuild() {
         if (!this.context) {
-            throw new AppError('You must call "watch()" before usinf "rebuild()', {
+            throw new AppError('You must call "watch()" before using "rebuild()"', {
                 code: 'BUILD_FAILED',
                 category: 'build',
             });
@@ -103,7 +108,7 @@ export class Bundler {
             this.lastResult = await this.context.rebuild();
             return this.lastResult;
         }
-        catch (error //eslint-disable-line
+        catch (error // eslint-disable-line
         ) {
             throw new AppError('Looks like there is some errors while rebuilding', {
                 code: 'BUILD_FAILED',
@@ -113,9 +118,9 @@ export class Bundler {
         }
     }
     /**
-     * Dispose of resources.
-     *
-     * Releases esbuild’s internal rebuild/watcher context.
+     * Gracefully shuts down the bundler and releases system resources.
+     * This disposes of the esbuild context, stops watchers, and clears internal cache.
+     * @throws {@link AppError} if the disposal process fails.
      */
     async dispose() {
         if (!this.context)
@@ -123,7 +128,7 @@ export class Bundler {
         try {
             await this.context.dispose();
         }
-        catch (error //eslint-disable-line
+        catch (error // eslint-disable-line
         ) {
             throw new AppError('Failed to stop. Try again', {
                 code: 'BUILD_FAILED',
@@ -136,13 +141,15 @@ export class Bundler {
         this.isWatching = false;
     }
     /**
-     * Get last esbuild result.
+     * Retrieves the result of the most recent successful build or rebuild.
+     * @returns The {@link BuildResult} or `undefined` if no build has occurred yet.
      */
     getLastResult() {
         return this.lastResult;
     }
     /**
-     * Whether the compiler is currently in watch mode.
+     * Indicates whether the bundler is currently in an active watch state.
+     * @returns `true` if watching, otherwise `false`.
      */
     isInWatchMode() {
         return this.isWatching;

package/dist/bundler/config.d.ts

@@ -1,10 +1,36 @@
 import type { ESBuildClientDevConfig, ESBuildClientProdConfig, ESBuildServerDevConfig, ESBuildServerProdConfig } from '../types/config.js';
+/**
+ * Generates an esbuild configuration specifically for the Client (browser) environment.
+ * * @remarks
+ * The client configuration differs from the server in several key ways:
+ * - **Platform**: Targeted for the `browser`.
+ * - **Asset Loaders**: Includes loaders for images/styles (`ASSET_LOADERS`).
+ * - **Bundling**: `bundle: true` is used to resolve all dependencies for the browser.
+ * - **Write Mode**: In `dev`, `write` is set to `false` to support in-memory serving.
+ * * @param env - The build environment: `'dev'` for development or `'prod'` for production.
+ * @param options - Configuration details.
+ * @param options.absWorkingDir - The absolute path to the project root.
+ * @param options.entryPoints - File paths or a mapping for the entry points to be bundled.
+ * * @returns A configuration object typed for either {@link ESBuildClientDevConfig} or {@link ESBuildClientProdConfig}.
+ */
 export declare function createClientConfig(env: 'dev' | 'prod', options: {
     absWorkingDir: string;
     entryPoints: string[] | Record<string, string>;
 }): ESBuildClientDevConfig | ESBuildClientProdConfig;
 /**
- * Return configuration to create server bundler
+ * Generates an esbuild configuration specifically for the Server (Node.js) environment.
+ * * @remarks
+ * The server configuration is optimized for SSR and runtime execution:
+ * - **Platform**: Targeted for `node`.
+ * - **Asset Loaders**: Uses `NO_ASSET_LOADERS` as assets are typically handled by the client build.
+ * - **Externalization**: Automatically marks `react` and `react-dom` as external to avoid
+ * duplicate instances during server-side rendering.
+ * - **Bundling**: `bundle: false` and `packages: 'external'` are used to leverage Node's native module resolution.
+ * * @param env - The build environment: `'dev'` for development or `'prod'` for production.
+ * @param options - Configuration details.
+ * @param options.absWorkingDir - The absolute path to the project root.
+ * @param options.entryPoints - File paths or a mapping for the entry points (e.g., the SSR entry).
+ * * @returns A configuration object typed for either {@link ESBuildServerDevConfig} or {@link ESBuildServerProdConfig}.
  */
 export declare function createServerConfig(env: 'dev' | 'prod', options: {
     absWorkingDir: string;

package/dist/bundler/config.js

@@ -1,18 +1,31 @@
+import { join } from 'node:path';
 import { ASSET_LOADERS, BASE_LOADERS, ESBUILD_BASE_CONFIG, NO_ASSET_LOADERS, } from '../config/esbuild.js';
-import { DEV_CLIENT_DIR } from '../config/path.js';
-// Create compiler configuration
+import { CACHE_DIR } from '../utils/constants.js';
+/**
+ * Generates an esbuild configuration specifically for the Client (browser) environment.
+ * * @remarks
+ * The client configuration differs from the server in several key ways:
+ * - **Platform**: Targeted for the `browser`.
+ * - **Asset Loaders**: Includes loaders for images/styles (`ASSET_LOADERS`).
+ * - **Bundling**: `bundle: true` is used to resolve all dependencies for the browser.
+ * - **Write Mode**: In `dev`, `write` is set to `false` to support in-memory serving.
+ * * @param env - The build environment: `'dev'` for development or `'prod'` for production.
+ * @param options - Configuration details.
+ * @param options.absWorkingDir - The absolute path to the project root.
+ * @param options.entryPoints - File paths or a mapping for the entry points to be bundled.
+ * * @returns A configuration object typed for either {@link ESBuildClientDevConfig} or {@link ESBuildClientProdConfig}.
+ */
 export function createClientConfig(env, options) {
     const isDev = env === 'dev';
-    // Base config with required properties
+    const cwd = process.cwd();
     const baseConfig = {
         ...ESBUILD_BASE_CONFIG,
         absWorkingDir: options.absWorkingDir,
         entryPoints: options.entryPoints,
-        outdir: DEV_CLIENT_DIR,
+        outdir: join(cwd, CACHE_DIR, 'client'),
         plugins: [],
     };
     if (isDev) {
-        // Dev configuration
         return {
             ...baseConfig,
             platform: 'browser',
@@ -33,7 +46,6 @@ export function createClientConfig(env, options) {
         };
     }
     else {
-        // Prod configuration
         return {
             ...baseConfig,
             platform: 'browser',
@@ -55,20 +67,31 @@ export function createClientConfig(env, options) {
     }
 }
 /**
- * Return configuration to create server bundler
+ * Generates an esbuild configuration specifically for the Server (Node.js) environment.
+ * * @remarks
+ * The server configuration is optimized for SSR and runtime execution:
+ * - **Platform**: Targeted for `node`.
+ * - **Asset Loaders**: Uses `NO_ASSET_LOADERS` as assets are typically handled by the client build.
+ * - **Externalization**: Automatically marks `react` and `react-dom` as external to avoid
+ * duplicate instances during server-side rendering.
+ * - **Bundling**: `bundle: false` and `packages: 'external'` are used to leverage Node's native module resolution.
+ * * @param env - The build environment: `'dev'` for development or `'prod'` for production.
+ * @param options - Configuration details.
+ * @param options.absWorkingDir - The absolute path to the project root.
+ * @param options.entryPoints - File paths or a mapping for the entry points (e.g., the SSR entry).
+ * * @returns A configuration object typed for either {@link ESBuildServerDevConfig} or {@link ESBuildServerProdConfig}.
  */
 export function createServerConfig(env, options) {
     const isDev = env === 'dev';
-    // Base config with required properties
+    const cwd = process.cwd();
     const baseConfig = {
         ...ESBUILD_BASE_CONFIG,
         absWorkingDir: options.absWorkingDir,
         entryPoints: options.entryPoints,
-        outdir: DEV_CLIENT_DIR,
+        outdir: join(cwd, CACHE_DIR, 'server'),
         plugins: [],
     };
     if (isDev) {
-        // Dev configuration
         return {
             ...baseConfig,
             platform: 'node',
@@ -90,7 +113,6 @@ export function createServerConfig(env, options) {
         };
     }
     else {
-        // Prod configuration
         return {
             ...baseConfig,
             platform: 'node',

package/dist/bundler/create-plugin.d.ts

@@ -0,0 +1,85 @@
+import type { BuildResult, OnLoadArgs, OnLoadOptions, OnResolveArgs, OnResolveOptions, Plugin, OnLoadResult, OnResolveResult, PluginBuild } from 'esbuild';
+/**
+ * Defines the execution logic for various stages of the esbuild bundling process.
+ * * This interface provides a structured, declarative way to tap into the
+ * {@link https://esbuild.github.io/plugins/#build-callbacks | esbuild plugin lifecycle}.
+ */
+interface PluginLifecycleHooks {
+    /**
+     * Invoked at the very beginning of every build or rebuild.
+     * * @remarks
+     * Use this for setup logic, initializing build-specific state, or clear/prepare output directories.
+     * If this function returns a `Promise`, esbuild will wait for it to resolve before starting the build.
+     */
+    onStart?: (this: PluginBuild) => void | Promise<void>;
+    /**
+     * Invoked at the end of every build or rebuild.
+     * * @param result - The outcome of the build, including errors, warnings, and the metafile (if enabled).
+     * @remarks
+     * Ideal for post-processing tasks, such as generating manifest files,
+     * triggering notifications, or cleaning up temporary files.
+     */
+    onEnd?: (this: PluginBuild, result: BuildResult) => void | Promise<void>;
+    /**
+     * Invoked when the plugin is disposed of, usually when the {@link Bundler.dispose} is called.
+     * * @remarks
+     * Use this to close file watchers, database connections, or long-lived child processes
+     * created within the plugin.
+     */
+    onDispose?: (this: PluginBuild) => void;
+    /**
+     * Intercepts the loading of files that match specific criteria.
+     */
+    onLoad?: {
+        /** Configuration object defining the `filter` regex and `namespace`. */
+        options: OnLoadOptions;
+        /** * Executed when a file matches the filter.
+         * @returns The content and loader type for the file.
+         */
+        callback: (args: OnLoadArgs) => OnLoadResult | Promise<OnLoadResult>;
+    };
+    /**
+     * Intercepts the resolution of import paths.
+     */
+    onResolve?: {
+        /** Configuration object defining the `filter` regex and `namespace`. */
+        options: OnResolveOptions;
+        /** * Executed when an import matches the filter.
+         * @returns The resolved path or instructions to externalize the module.
+         */
+        callback: (args: OnResolveArgs) => OnResolveResult | Promise<OnResolveResult>;
+    };
+}
+/**
+ * A factory function that creates a declarative esbuild plugin.
+ * * This utility abstracts the imperative nature of the `setup(build)` function,
+ * making plugin code more readable and easier to maintain.
+ * * @example
+ * **Basic Usage (Logging)**
+ * ```ts
+ * const loggerPlugin = createDeclarativePlugin('rsaf-logger', {
+ * onStart: () => console.log('Building...'),
+ * onEnd: (res) => console.log(`Done with ${res.errors.length} errors.`),
+ * });
+ * ```
+ * * @example
+ * **Advanced Usage (Virtual Modules)**
+ * ```ts
+ * const virtualModule = createDeclarativePlugin('virtual-config', {
+ * onResolve: {
+ * options: { filter: /^virtual:config$/ },
+ * callback: () => ({ path: 'config', namespace: 'v-space' })
+ * },
+ * onLoad: {
+ * options: { filter: /*.ts., namespace: 'v-space' },
+ * callback: () => ({ contents: 'export const val = 42;', loader: 'js' })
+ * }
+ * });
+ * ```
+ * * @param pluginName - A unique name for the plugin (used for error reporting and debugging).
+ * @param lifecycleHooks - An object containing the hooks to be registered.
+ * @returns A standard esbuild {@link Plugin} object.
+ * * @throws {TypeError} If `pluginName` is empty or not a string.
+ */
+export declare function createDeclarativePlugin(pluginName: string, lifecycleHooks: PluginLifecycleHooks): Plugin;
+export {};

package/dist/bundler/create-plugin.js

@@ -0,0 +1,58 @@
+/**
+ * A factory function that creates a declarative esbuild plugin.
+ * * This utility abstracts the imperative nature of the `setup(build)` function,
+ * making plugin code more readable and easier to maintain.
+ * * @example
+ * **Basic Usage (Logging)**
+ * ```ts
+ * const loggerPlugin = createDeclarativePlugin('rsaf-logger', {
+ * onStart: () => console.log('Building...'),
+ * onEnd: (res) => console.log(`Done with ${res.errors.length} errors.`),
+ * });
+ * ```
+ * * @example
+ * **Advanced Usage (Virtual Modules)**
+ * ```ts
+ * const virtualModule = createDeclarativePlugin('virtual-config', {
+ * onResolve: {
+ * options: { filter: /^virtual:config$/ },
+ * callback: () => ({ path: 'config', namespace: 'v-space' })
+ * },
+ * onLoad: {
+ * options: { filter: /*.ts., namespace: 'v-space' },
+ * callback: () => ({ contents: 'export const val = 42;', loader: 'js' })
+ * }
+ * });
+ * ```
+ * * @param pluginName - A unique name for the plugin (used for error reporting and debugging).
+ * @param lifecycleHooks - An object containing the hooks to be registered.
+ * @returns A standard esbuild {@link Plugin} object.
+ * * @throws {TypeError} If `pluginName` is empty or not a string.
+ */
+export function createDeclarativePlugin(pluginName, lifecycleHooks) {
+    if (typeof pluginName !== 'string' || pluginName.trim().length === 0) {
+        throw new TypeError('[createDeclarativePlugin]: Plugin name must be a non-empty string');
+    }
+    return {
+        name: pluginName,
+        setup(build) {
+            if (lifecycleHooks.onStart) {
+                build.onStart(lifecycleHooks.onStart.bind(build));
+            }
+            if (lifecycleHooks.onEnd) {
+                build.onEnd(lifecycleHooks.onEnd.bind(build));
+            }
+            if (lifecycleHooks.onDispose) {
+                build.onDispose(lifecycleHooks.onDispose.bind(build));
+            }
+            if (lifecycleHooks.onLoad) {
+                const { options, callback } = lifecycleHooks.onLoad;
+                build.onLoad(options, callback);
+            }
+            if (lifecycleHooks.onResolve) {
+                const { options, callback } = lifecycleHooks.onResolve;
+                build.onResolve(options, callback);
+            }
+        },
+    };
+}

package/dist/cache/cache-store.d.ts

@@ -1,64 +1,69 @@
 /**
- * A type-safe cache that stores values with keys matching a given type structure.
- * @template T - The type defining the cache's structure: keys as property names and values as corresponding types.
+ * A type-safe, generic cache store that enforces structural integrity based on a provided interface.
+ * * * This class provides a wrapper around the native `Map` API, ensuring that keys and values
+ * are strictly typed according to the shape of {@link T}.
+ * * @template T - An object-like type where keys represent the cache keys and values represent
+ * the corresponding data types.
+ * * @example
+ * ```ts
+ * interface AppCache {
+ * port: number;
+ * isReady: boolean;
+ * config: { debug: boolean };
+ * }
+ * * const cache = new CacheStore<AppCache>();
+ * cache.set('port', 3000); // Type-safe
+ * // cache.set('port', '3000'); // Static type error
+ * ```
  */
 export declare class CacheStore<T extends Record<string, any>> {
+    /**
+     * Internal storage mechanism.
+     * @internal
+     */
     private store;
     /**
-     * Retrieves a value from the cache by key.
-     * @template K - The specific key type (extends keyof T).
-     * @param key - The key to look up in the cache.
-     * @returns The value associated with the key, or undefined if not found.
-     * @example
-     * // Given T = { name: string, age: number }
-     * cache.get('name'); // Returns string | undefined
+     * Retrieves a value from the cache associated with the specified key.
+     * * @template K - A specific property key within type {@link T}.
+     * @param key - The identifier to look up.
+     * @returns The stored value of type `T[K]`, or `undefined` if the key does not exist.
+     * * @remarks
+     * If you require a guarantee that the value exists (and want to avoid manual `undefined` checks),
+     * consider using {@link require} instead.
      */
     get<K extends keyof T>(key: K): T[K] | undefined;
     /**
-     * Retrieves a value from the cache, throwing an error if the key doesn't exist.
-     * Useful when you expect a key to always be present.
-     * @template K - The specific key type (extends keyof T).
-     * @param key - The key to look up in the cache.
-     * @returns The value associated with the key.
-     * @throws {Error} If the key is not found in the cache.
-     * @example
-     * // Given T = { name: string, age: number }
-     * cache.require('name'); // Returns string, throws if 'name' not found
+     * Retrieves a value from the cache, throwing a runtime error if the key is missing.
+     * * * Use this method when a key is expected to be initialized during a bootstrap phase
+     * and its absence indicates a critical logic error.
+     * * @template K - A specific property key within type {@link T}.
+     * @param key - The identifier to look up.
+     * @returns The strictly-typed value associated with the key.
+     * * @throws {Error} If the key has not been set in the store.
      */
     require<K extends keyof T>(key: K): T[K];
     /**
-     * Sets a value in the cache for the given key.
-     * @template K - The specific key type (extends keyof T).
-     * @param key - The key to associate with the value.
-     * @param value - The value to store (must match the type T[K]).
-     * @example
-     * // Given T = { name: string, age: number }
-     * cache.set('name', 'Alice'); // OK
-     * cache.set('age', 'thirty'); // Type error: string not assignable to number
+     * Inserts or updates a value in the cache.
+     * * @template K - A specific property key within type {@link T}.
+     * @param key - The identifier to associate the value with.
+     * @param value - The data to store, matching the type defined in {@link T} for this key.
      */
     set<K extends keyof T>(key: K, value: T[K]): void;
     /**
-     * Checks if a key exists in the cache.
-     * @template K - The specific key type (extends keyof T).
-     * @param key - The key to check.
-     * @returns True if the key exists in the cache, false otherwise.
-     * @example
-     * cache.has('name'); // Returns boolean
+     * Determines whether a specific key exists in the store.
+     * * @param key - The identifier to check.
+     * @returns `true` if the key is present; otherwise `false`.
      */
     has<K extends keyof T>(key: K): boolean;
     /**
-     * Removes a key-value pair from the cache.
-     * @template K - The specific key type (extends keyof T).
-     * @param key - The key to remove.
-     * @returns True if the key existed and was removed, false otherwise.
-     * @example
-     * cache.delete('name'); // Returns boolean
+     * Removes the specified key and its associated value from the cache.
+     * * @param key - The identifier to remove.
+     * @returns `true` if an element in the CacheStore existed and has been removed,
+     * or `false` if the element does not exist.
      */
     delete<K extends keyof T>(key: K): boolean;
     /**
-     * Removes all key-value pairs from the cache.
-     * @example
-     * cache.clear(); // Empties the entire cache
+     * Clears all entries from the cache store, resetting it to an empty state.
      */
     clear(): void;
 }

package/dist/cache/cache-store.js

@@ -1,81 +1,84 @@
 /**
- * A type-safe cache that stores values with keys matching a given type structure.
- * @template T - The type defining the cache's structure: keys as property names and values as corresponding types.
+ * A type-safe, generic cache store that enforces structural integrity based on a provided interface.
+ * * * This class provides a wrapper around the native `Map` API, ensuring that keys and values
+ * are strictly typed according to the shape of {@link T}.
+ * * @template T - An object-like type where keys represent the cache keys and values represent
+ * the corresponding data types.
+ * * @example
+ * ```ts
+ * interface AppCache {
+ * port: number;
+ * isReady: boolean;
+ * config: { debug: boolean };
+ * }
+ * * const cache = new CacheStore<AppCache>();
+ * cache.set('port', 3000); // Type-safe
+ * // cache.set('port', '3000'); // Static type error
+ * ```
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export class CacheStore {
-    // Internal storage using Map to maintain key-value pairs
+    /**
+     * Internal storage mechanism.
+     * @internal
+     */
     store = new Map();
     /**
-     * Retrieves a value from the cache by key.
-     * @template K - The specific key type (extends keyof T).
-     * @param key - The key to look up in the cache.
-     * @returns The value associated with the key, or undefined if not found.
-     * @example
-     * // Given T = { name: string, age: number }
-     * cache.get('name'); // Returns string | undefined
+     * Retrieves a value from the cache associated with the specified key.
+     * * @template K - A specific property key within type {@link T}.
+     * @param key - The identifier to look up.
+     * @returns The stored value of type `T[K]`, or `undefined` if the key does not exist.
+     * * @remarks
+     * If you require a guarantee that the value exists (and want to avoid manual `undefined` checks),
+     * consider using {@link require} instead.
      */
     get(key) {
-        // Type assertion is safe because we only store T[keyof T] values
         return this.store.get(key);
     }
     /**
-     * Retrieves a value from the cache, throwing an error if the key doesn't exist.
-     * Useful when you expect a key to always be present.
-     * @template K - The specific key type (extends keyof T).
-     * @param key - The key to look up in the cache.
-     * @returns The value associated with the key.
-     * @throws {Error} If the key is not found in the cache.
-     * @example
-     * // Given T = { name: string, age: number }
-     * cache.require('name'); // Returns string, throws if 'name' not found
+     * Retrieves a value from the cache, throwing a runtime error if the key is missing.
+     * * * Use this method when a key is expected to be initialized during a bootstrap phase
+     * and its absence indicates a critical logic error.
+     * * @template K - A specific property key within type {@link T}.
+     * @param key - The identifier to look up.
+     * @returns The strictly-typed value associated with the key.
+     * * @throws {Error} If the key has not been set in the store.
      */
     require(key) {
         const value = this.store.get(key);
         if (value === undefined) {
-            throw new Error(`Cache key '${String(key)}' is not initialized`);
+            throw new Error(`[CacheStore]: Accessing uninitialized key '${String(key)}'. Ensure it is set before calling require().`);
         }
         return value;
     }
     /**
-     * Sets a value in the cache for the given key.
-     * @template K - The specific key type (extends keyof T).
-     * @param key - The key to associate with the value.
-     * @param value - The value to store (must match the type T[K]).
-     * @example
-     * // Given T = { name: string, age: number }
-     * cache.set('name', 'Alice'); // OK
-     * cache.set('age', 'thirty'); // Type error: string not assignable to number
+     * Inserts or updates a value in the cache.
+     * * @template K - A specific property key within type {@link T}.
+     * @param key - The identifier to associate the value with.
+     * @param value - The data to store, matching the type defined in {@link T} for this key.
      */
     set(key, value) {
         this.store.set(key, value);
     }
     /**
-     * Checks if a key exists in the cache.
-     * @template K - The specific key type (extends keyof T).
-     * @param key - The key to check.
-     * @returns True if the key exists in the cache, false otherwise.
-     * @example
-     * cache.has('name'); // Returns boolean
+     * Determines whether a specific key exists in the store.
+     * * @param key - The identifier to check.
+     * @returns `true` if the key is present; otherwise `false`.
      */
     has(key) {
         return this.store.has(key);
     }
     /**
-     * Removes a key-value pair from the cache.
-     * @template K - The specific key type (extends keyof T).
-     * @param key - The key to remove.
-     * @returns True if the key existed and was removed, false otherwise.
-     * @example
-     * cache.delete('name'); // Returns boolean
+     * Removes the specified key and its associated value from the cache.
+     * * @param key - The identifier to remove.
+     * @returns `true` if an element in the CacheStore existed and has been removed,
+     * or `false` if the element does not exist.
      */
     delete(key) {
         return this.store.delete(key);
     }
     /**
-     * Removes all key-value pairs from the cache.
-     * @example
-     * cache.clear(); // Empties the entire cache
+     * Clears all entries from the cache store, resetting it to an empty state.
      */
     clear() {
         this.store.clear();

package/dist/config/esbuild.d.ts

@@ -1,4 +1,8 @@
 import type { ESBuildConfig } from '../types/config.js';
+/**
+ * Standard loaders for source code files.
+ * * Maps common ECMAScript and TypeScript extensions to their respective esbuild parsers.
+ */
 export declare const BASE_LOADERS: {
     readonly '.js': "js";
     readonly '.jsx': "jsx";
@@ -6,6 +10,13 @@ export declare const BASE_LOADERS: {
     readonly '.tsx': "tsx";
     readonly '.json': "json";
 };
+/**
+ * Loaders for static assets and styling.
+ * * Used primarily in Client builds to ensure that CSS and media files are
+ * processed and emitted to the output directory.
+ * - **CSS**: Processed as standard stylesheets.
+ * - **Images/Fonts**: Handled using the `file` loader (emits a file and returns a URL).
+ */
 export declare const ASSET_LOADERS: {
     readonly '.css': "css";
     readonly '.png': "file";
@@ -17,6 +28,13 @@ export declare const ASSET_LOADERS: {
     readonly '.woff': "file";
     readonly '.woff2': "file";
 };
+/**
+ * "Null" loaders used to ignore static assets during specific build phases.
+ * * @remarks
+ * This is primarily used in **Server (SSR)** builds. On the server, we want to
+ * resolve imports for assets (so the code doesn't throw) but we don't want to
+ * actually process or emit those files, as the Client build handles them.
+ */
 export declare const NO_ASSET_LOADERS: {
     readonly '.css': "empty";
     readonly '.png': "empty";
@@ -28,4 +46,10 @@ export declare const NO_ASSET_LOADERS: {
     readonly '.woff': "empty";
     readonly '.woff2': "empty";
 };
+/**
+ * The default base configuration shared across all build targets.
+ * * This configuration prioritizes modern standards (ESM) and silent execution
+ * to allow the parent CLI or framework to manage logging.
+ * * @see {@link createClientConfig} and {@link createServerConfig} for how this is extended.
+ */
 export declare const ESBUILD_BASE_CONFIG: Partial<ESBuildConfig>;

package/dist/config/esbuild.js

@@ -1,4 +1,7 @@
-// Base loader configurations
+/**
+ * Standard loaders for source code files.
+ * * Maps common ECMAScript and TypeScript extensions to their respective esbuild parsers.
+ */
 export const BASE_LOADERS = {
     '.js': 'js',
     '.jsx': 'jsx',
@@ -6,6 +9,13 @@ export const BASE_LOADERS = {
     '.tsx': 'tsx',
     '.json': 'json',
 };
+/**
+ * Loaders for static assets and styling.
+ * * Used primarily in Client builds to ensure that CSS and media files are
+ * processed and emitted to the output directory.
+ * - **CSS**: Processed as standard stylesheets.
+ * - **Images/Fonts**: Handled using the `file` loader (emits a file and returns a URL).
+ */
 export const ASSET_LOADERS = {
     '.css': 'css',
     '.png': 'file',
@@ -17,6 +27,13 @@ export const ASSET_LOADERS = {
     '.woff': 'file',
     '.woff2': 'file',
 };
+/**
+ * "Null" loaders used to ignore static assets during specific build phases.
+ * * @remarks
+ * This is primarily used in **Server (SSR)** builds. On the server, we want to
+ * resolve imports for assets (so the code doesn't throw) but we don't want to
+ * actually process or emit those files, as the Client build handles them.
+ */
 export const NO_ASSET_LOADERS = {
     '.css': 'empty',
     '.png': 'empty',
@@ -28,16 +45,25 @@ export const NO_ASSET_LOADERS = {
     '.woff': 'empty',
     '.woff2': 'empty',
 };
-// Base configuration
+/**
+ * The default base configuration shared across all build targets.
+ * * This configuration prioritizes modern standards (ESM) and silent execution
+ * to allow the parent CLI or framework to manage logging.
+ * * @see {@link createClientConfig} and {@link createServerConfig} for how this is extended.
+ */
 export const ESBUILD_BASE_CONFIG = {
-    // Build optimizations
+    /** Generates a JSON file for bundle analysis and size tracking. */
     metafile: true,
+    /** Enables terminal colors for errors and warnings. */
     color: true,
+    /** Disables esbuild's default logging to favor custom application error handling. */
     logLevel: 'silent',
-    // Performance
+    /** Removes unreachable code to reduce bundle size. */
     treeShaking: true,
-    // Code splitting
+    /** * Disabled by default. Only enabled for Client Production builds
+     * where browser-native ESM loading is required.
+     */
     splitting: false,
-    // Format
+    /** Standardizes on ECMAScript Modules for modern Node.js and Browser environments. */
     format: 'esm',
 };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './bundler/Bundler.js';
 export * from './bundler/config.js';
+export * from './bundler/create-plugin.js';
 export * from './cache/cache-store.js';
 export * from './types/config.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 // Bundler
 export * from './bundler/Bundler.js';
 export * from './bundler/config.js';
+export * from './bundler/create-plugin.js';
 //Cache
 export * from './cache/cache-store.js';
 // Types

package/dist/types/config.d.ts

@@ -1,53 +1,120 @@
 import type { Loader, Plugin } from 'esbuild';
+/**
+ * The foundational configuration shared by all build targets (Client, Server, Dev, Prod).
+ * * Defines the environment-agnostic settings such as project paths,
+ * tree-shaking logic, and the default JSX transformation.
+ */
 export interface ESBuildBaseConfig {
+    /** Enables terminal colors for errors and warnings. */
     color: true;
+    /** Disables esbuild's default logging to favor custom application error handling. */
     logLevel: 'silent';
+    /** Removes unreachable code to reduce bundle size across all platforms. */
     treeShaking: true;
+    /** Standardizes on ECMAScript Modules (ESM) for modern runtime support. */
     format: 'esm';
+    /** The absolute path to the project root directory. */
     absWorkingDir: string;
+    /** The output directory for the build artifacts. Optional if `write` is false. */
     outdir?: string;
+    /** The specific output file path. Alternative to `outdir`. */
     outfile?: string;
+    /** The entry file(s) where esbuild starts the bundling process. */
     entryPoints: string[];
+    /** An array of {@link Plugin} instances to extend esbuild functionality. */
     plugins: Plugin[];
+    /** Configures the React transformation to use the modern 'automatic' runtime. */
     jsx: 'automatic';
 }
+/**
+ * A dictionary mapping file extensions (e.g., `.png`) to their respective esbuild {@link Loader}.
+ */
 export type LoaderFiles = Record<string, Loader>;
+/**
+ * Configuration specific to Browser-targeted builds.
+ * * Sets the platform to `browser` and ensures all packages are bundled
+ * to be compatible with client-side execution.
+ */
 export interface ESBuildClientConfig {
+    /** Targets the browser environment. */
     platform: 'browser';
+    /** Specifies the ECMAScript version for the output. */
     target: ['es2022'];
+    /** Loaders for client-side assets (CSS, Images, etc.). */
     loader: LoaderFiles;
+    /** Ensures dependencies are bundled into the final output. */
     bundle: true;
+    /** Aggressively bundles all node_modules into the browser chunks. */
     packages: 'bundle';
 }
+/**
+ * Configuration specific to Node.js-targeted builds.
+ * * Optimized for Server-Side Rendering (SSR) where `node_modules` should
+ * remain external for faster execution and compatibility.
+ */
 export interface ESBuildServerConfig {
+    /** Targets the Node.js environment. */
     platform: 'node';
+    /** Specifies the minimum supported Node version. */
     target: ['node18'];
+    /** Loaders for server-side assets (often uses 'empty' for styles). */
     loader: LoaderFiles;
+    /** Prevents node_modules from being bundled into the server file. */
     packages: 'external';
+    /** Specific package names to explicitly exclude from the bundle. */
     external: string[];
+    /** Disabled for server to leverage native Node module resolution. */
     bundle: false;
 }
+/**
+ * Settings applied during local development.
+ * * Focuses on build speed and debuggability rather than file size.
+ */
 export interface ESBuildDevConfig {
+    /** Disables minification for readable source code. */
     minify: false;
     minifyWhitespace: false;
     minifyIdentifiers: false;
     minifySyntax: false;
+    /** Keeps output in memory to speed up hot-reloading/serving. */
     write: false;
+    /** Code splitting is disabled in dev to simplify module resolution. */
     splitting: false;
+    /** Generates a metafile for real-time dependency analysis. */
     metafile: true;
 }
+/**
+ * Settings applied during production builds.
+ * * Focuses on aggressive optimization, minification, and disk-ready output.
+ */
 export interface ESBuildProdConfig {
+    /** Enables full minification suite for smallest possible file size. */
     minify: true;
     minifyWhitespace: true;
     minifyIdentifiers: true;
     minifySyntax: true;
+    /** Writes files to the `outdir` for deployment. */
     write: true;
+    /** Enables ESM-based code splitting for lazy loading. */
     splitting: true;
+    /** Metafile is typically disabled in production to save build time. */
     metafile: false;
 }
+/** Intersection type for a Client-side Development build. */
 export type ESBuildClientDevConfig = ESBuildBaseConfig & ESBuildClientConfig & ESBuildDevConfig;
+/** Intersection type for a Client-side Production build. */
 export type ESBuildClientProdConfig = ESBuildBaseConfig & ESBuildClientConfig & ESBuildProdConfig;
+/** Intersection type for a Server-side Development build. */
 export type ESBuildServerDevConfig = ESBuildBaseConfig & ESBuildServerConfig & ESBuildDevConfig;
+/** Intersection type for a Server-side Production build. */
 export type ESBuildServerProdConfig = ESBuildBaseConfig & ESBuildServerConfig & ESBuildProdConfig;
+/**
+ * A exhaustive union of all valid configuration states for the Bundler.
+ * * Using this type ensures that a configuration cannot have invalid
+ * property combinations (e.g., a Server build cannot accidentally have 'bundle: true').
+ */
 export type ESBuildConfig = ESBuildClientDevConfig | ESBuildClientProdConfig | ESBuildServerDevConfig | ESBuildServerProdConfig;
+/**
+ * Type alias for a map of file extensions to esbuild Loaders.
+ */
 export type Loaders = Record<string, Loader>;

package/dist/utils/constants.d.ts

@@ -0,0 +1 @@
+export declare const CACHE_DIR = "/.rsaf";

package/dist/utils/constants.js

@@ -0,0 +1 @@
+export const CACHE_DIR = '/.rsaf';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsaf/bundler",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Bundler package for rsaf",
   "type": "module",
   "files": [

package/dist/config/path.d.ts

@@ -1,38 +0,0 @@
-/**
- * @param  path  - The path to normalize
- * @returns Normalized Path
- */
-export declare const normalizePath: (path: string) => string;
-/**
- * Generates the correct relative path to the static directory based on the current URL depth
- * @param currentPath - The current page URL path
- * @param staticDir - The static directory name (default: "static")
- * @returns The relative path to the static directory
- */
-export declare function getStaticPath(currentPath: string, staticDir?: string): string;
-export declare const DEV_RUNTIME_DIR: string;
-export declare const DEV_CLIENT_DIR: string;
-export declare const DEV_SERVER_DIR: string;
-export declare const DEV_SERVER_ENTRY: string;
-export declare const DEV_CLIENT_ENTRY: string;
-export declare const DEV_CLIENT_STATIC_DIR: string;
-export declare const DEV_CLIENT_APP_ENTRY: string;
-export declare const DEV_CLIENT_STYLES_ENTRY: string;
-export declare const DEV_CLIENT_HYDRATE_ENTRY: string;
-export declare const DEV_SERVER_RENDERER_ENTRY: string;
-export declare const DEV_SERVER_APP_ENTRY: string;
-export declare const DEV_SERVER_ROUTER_ENTRY: string;
-export declare const DEV_SSR_CACHE_DIR: string;
-export declare const DEV_SSR_TEMP_MODULE_DIR: string;
-export declare const DEV_CLIENT_MANIFEST_PATH: string;
-export declare const DEV_SERVER_MANIFEST_PATH: string;
-export declare const APP_CONFIG_FILE_PATH: string;
-export declare const APP_STYLESHEET_PATH: string;
-export declare const PATH_PATTERNS: {
-    STATIC_FILES: RegExp;
-    API_ROUTES: RegExp;
-    JS_FILES: RegExp;
-    CSS_FILES: RegExp;
-    ASSET_FILES: RegExp;
-    CONFIG_FILES: RegExp;
-};

package/dist/config/path.js

@@ -1,67 +0,0 @@
-/**
- * @param  path  - The path to normalize
- * @returns Normalized Path
- */
-export const normalizePath = (path) => '/' + (path || '').replace(/\/+/g, '/').replace(/^\/+|\/+$/g, '');
-/**
- * Generates the correct relative path to the static directory based on the current URL depth
- * @param currentPath - The current page URL path
- * @param staticDir - The static directory name (default: "static")
- * @returns The relative path to the static directory
- */
-export function getStaticPath(currentPath, staticDir = 'static') {
-    // Normalize path: remove leading/trailing slashes
-    const segments = currentPath
-        .replace(/^\/+|\/+$/g, '')
-        .split('/')
-        .filter(p => p);
-    const depth = segments.length;
-    // Build the relative path
-    if (depth === 0) {
-        // Root level
-        return `./${staticDir}`;
-    }
-    else {
-        // Go up one level for each directory segment
-        const upLevels = '../'.repeat(depth);
-        return `${upLevels}${staticDir}`;
-    }
-}
-// Root runtime directories
-export const DEV_RUNTIME_DIR = normalizePath('.nexus');
-export const DEV_CLIENT_DIR = normalizePath('.nexus/client');
-export const DEV_SERVER_DIR = normalizePath('.nexus/server');
-// App Entry Paths
-export const DEV_SERVER_ENTRY = normalizePath('.nexus/server/entry.tsx');
-export const DEV_CLIENT_ENTRY = normalizePath('.nexus/client/entry.tsx');
-// Client build outputs
-export const DEV_CLIENT_STATIC_DIR = normalizePath('.nexus/client/static');
-export const DEV_CLIENT_APP_ENTRY = normalizePath('.nexus/client/hydrate.js');
-export const DEV_CLIENT_STYLES_ENTRY = normalizePath('.nexus/client/styles.css');
-export const DEV_CLIENT_HYDRATE_ENTRY = normalizePath('.nexus/client/hydrate.tsx');
-export const DEV_SERVER_RENDERER_ENTRY = normalizePath('.nexus/server/renderer.tsx');
-// Server build outputs
-export const DEV_SERVER_APP_ENTRY = normalizePath('.nexus/server/App.ssr.js');
-export const DEV_SERVER_ROUTER_ENTRY = normalizePath('.nexus/server/router.js');
-// Runtime + SSR state
-export const DEV_SSR_CACHE_DIR = normalizePath('.nexus/cache');
-export const DEV_SSR_TEMP_MODULE_DIR = normalizePath('.nexus/runtime/modules');
-// Build result manifests
-export const DEV_CLIENT_MANIFEST_PATH = normalizePath('.nexus/client/manifest.json');
-export const DEV_SERVER_MANIFEST_PATH = normalizePath('.nexus/server/manifest.json');
-// App Config paths
-export const APP_CONFIG_FILE_PATH = normalizePath('nexus.config.ts');
-// Server Paths
-export const APP_STYLESHEET_PATH = normalizePath('static/styles.css');
-// Constants for common path patterns
-export const PATH_PATTERNS = {
-    // Pattern matchers for routes
-    STATIC_FILES: /^\/static\//,
-    API_ROUTES: /^\/api\//,
-    // File extensions
-    JS_FILES: /\.(js|mjs|cjs|jsx|ts|tsx)$/,
-    CSS_FILES: /\.(css|scss|sass|less)$/,
-    ASSET_FILES: /\.(png|jpg|jpeg|gif|svg|ico|webp|avif|woff|woff2|ttf|eot)$/,
-    // Configuration files
-    CONFIG_FILES: /\.config\.(js|ts|json)$/,
-};