@oazmi/superbuild 0.1.0

package/esm/super/build.d.ts

@@ -0,0 +1,53 @@
+/** super-build lets you overload esbuild to expand what you're capable of doing in the plugin-api.
+ *
+ * @module
+*/
+import type { Esbuild, EsbuildBuildOptions, EsbuildBuildResult } from "../esbuild/strongtypes.js";
+import type { LoggerFunction } from "../typedefs.js";
+import { SuperBuildContext } from "./build_context.js";
+export interface SuperBuildOptions extends EsbuildBuildOptions {
+    /** enable internal logging of super-build for debugging, when {@link DEBUG.LOG} is enabled.
+     *
+     * when set to `true`, the logs will show up in your console via `console.log()`.
+     * you may also provide your own custom logger function if you wish.
+     *
+     * @defaultValue `false`
+    */
+    debuggingLogs?: boolean | LoggerFunction;
+}
+export type SuperBuildExclusiveOptions = Omit<SuperBuildOptions, keyof EsbuildBuildOptions>;
+/** super-build lets you overload esbuild to expand what you're capable of doing in the plugin-api.
+ *
+ * this class creates a mere wrapper over a base `esbuild` object (acquired from `import esbuild from "npm:esbuild"`).
+ * this class itself does not do anything interesting aside from overloading the `esbuild.build` and `esbuild.buildSync` methods,
+ * to pass a modified version of your `esbuild.BuildOptions` that alters the plugin api (which is performed by {@link SuperBuildContext}).
+*/
+export declare class SuperBuild implements Esbuild {
+    #private;
+    version: Esbuild["version"];
+    analyzeMetafile: Esbuild["analyzeMetafile"];
+    analyzeMetafileSync: Esbuild["analyzeMetafileSync"];
+    context: Esbuild["context"];
+    formatMessages: Esbuild["formatMessages"];
+    formatMessagesSync: Esbuild["formatMessagesSync"];
+    initialize: Esbuild["initialize"];
+    transform: Esbuild["transform"];
+    transformSync: Esbuild["transformSync"];
+    stop: Esbuild["stop"];
+    constructor(base_esbuild: Esbuild);
+    protected splitOptions(options: SuperBuildOptions): [
+        super_options: SuperBuildExclusiveOptions,
+        esbuild_options: EsbuildBuildOptions
+    ];
+    protected createContext(options: SuperBuildOptions): [
+        ctx: SuperBuildContext,
+        esbuild_options: EsbuildBuildOptions
+    ];
+    build<T extends SuperBuildOptions>(options: T & {
+        [Key in Exclude<keyof T, keyof SuperBuildOptions>]: never;
+    }): Promise<EsbuildBuildResult<T>>;
+    buildSync<T extends SuperBuildOptions>(options: T & {
+        [Key in Exclude<keyof T, keyof SuperBuildOptions>]: never;
+    }): EsbuildBuildResult<T>;
+}
+//# sourceMappingURL=build.d.ts.map

package/esm/super/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/super/build.ts"],"names":[],"mappings":"AAAA;;;EAGE;AAGF,OAAO,KAAK,EACX,OAAO,EACP,mBAAmB,EACnB,kBAAkB,EAClB,MAAM,2BAA2B,CAAA;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAGtD,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC7D;;;;;;MAME;IACF,aAAa,CAAC,EAAE,OAAO,GAAG,cAAc,CAAA;CACxC;AAED,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,mBAAmB,CAAC,CAAA;AAE3F;;;;;EAKE;AACF,qBAAa,UAAW,YAAW,OAAO;;IAC1B,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;IAC3B,eAAe,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC3C,mBAAmB,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAA;IAGnD,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;IAC3B,cAAc,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACzC,kBAAkB,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACjD,UAAU,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IACjC,SAAS,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;IAC/B,aAAa,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;IACvC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;gBAGxB,YAAY,EAAE,OAAO;IAMjC,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,iBAAiB,GAAG;QACnD,aAAa,EAAE,0BAA0B;QACzC,eAAe,EAAE,mBAAmB;KACpC;IAQD,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG;QACpD,GAAG,EAAE,iBAAiB;QACtB,eAAe,EAAE,mBAAmB;KACpC;IAOY,KAAK,CAAC,CAAC,SAAS,iBAAiB,EAAE,OAAO,EAAE,CAAC,GAAG;SAC3D,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,iBAAiB,CAAC,GAAG,KAAK;KACzD,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAK3B,SAAS,CAAC,CAAC,SAAS,iBAAiB,EAAE,OAAO,EAAE,CAAC,GAAG;SACzD,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,iBAAiB,CAAC,GAAG,KAAK;KACzD,GAAG,kBAAkB,CAAC,CAAC,CAAC;CAIzB"}

package/esm/super/build.js

@@ -0,0 +1,39 @@
+/** super-build lets you overload esbuild to expand what you're capable of doing in the plugin-api.
+ *
+ * @module
+*/
+import { object_assign } from "../deps.js";
+import { SuperBuildContext } from "./build_context.js";
+/** super-build lets you overload esbuild to expand what you're capable of doing in the plugin-api.
+ *
+ * this class creates a mere wrapper over a base `esbuild` object (acquired from `import esbuild from "npm:esbuild"`).
+ * this class itself does not do anything interesting aside from overloading the `esbuild.build` and `esbuild.buildSync` methods,
+ * to pass a modified version of your `esbuild.BuildOptions` that alters the plugin api (which is performed by {@link SuperBuildContext}).
+*/
+export class SuperBuild {
+    #esbuild;
+    constructor(base_esbuild) {
+        this.#esbuild = base_esbuild;
+        const { build, buildSync, ...rest_props } = base_esbuild;
+        object_assign(this, rest_props);
+    }
+    splitOptions(options) {
+        const { debuggingLogs, ...esbuild_options } = options;
+        const super_options = {
+            debuggingLogs
+        };
+        return [super_options, esbuild_options];
+    }
+    createContext(options) {
+        const [super_options, esbuild_options] = this.splitOptions(options), new_ctx = new SuperBuildContext(super_options);
+        return [new_ctx, esbuild_options];
+    }
+    async build(options) {
+        const [new_ctx, esbuild_options] = this.createContext(options);
+        return this.#esbuild.build(new_ctx.processPlugins(esbuild_options));
+    }
+    buildSync(options) {
+        const [new_ctx, esbuild_options] = this.createContext(options);
+        return this.#esbuild.buildSync(new_ctx.processPlugins(esbuild_options));
+    }
+}

package/esm/super/build_context.d.ts

@@ -0,0 +1,83 @@
+/** the {@link SuperBuildContext} is a centralized context that is created for each individual {@link SuperBuild.build} call.
+ *
+ * its main purpose is to inject some required plugins at their correct position, hold a few stateful objects,
+ * and create a wrapper on top of the user's provided plugins so that the extended plugin api becomes available to them.
+ *
+ * @module
+*/
+import { Metafile, type MetafileConfig } from "../esbuild/metafile.js";
+import type { EsbuildBuildOptions, EsbuildBuildResult, EsbuildOnEndCallback } from "../esbuild/strongtypes.js";
+import { LongBuildController } from "../plugins/long_build.js";
+import type { LoggerFunction, NamespacedPath } from "../typedefs.js";
+import type { SuperBuildExclusiveOptions } from "./build.js";
+import type { BundledInputFile, OnEmitCallback, OnEmitOptions, OnTransformCallback, OnTransformOptions } from "./typedefs.js";
+export interface OnTransformHandler extends OnTransformOptions {
+    pluginName: string;
+    callback: OnTransformCallback;
+}
+export interface OnEmitHandler extends OnEmitOptions {
+    pluginName: string;
+    callback: OnEmitCallback;
+}
+export interface OnEndHandler {
+    pluginName: string;
+    callback: EsbuildOnEndCallback;
+}
+/** a centralized context is created for each individual {@link SuperBuild.build} call. */
+export declare class SuperBuildContext {
+    /** contains a list of transformation handlers that will be used for matching contents returned by the plugins' `onLoad` hooks,
+     * in order to transfer them to the registered {@link SuperPluginBuild.onTransform} hooks.
+    */
+    onTransformHandlers: OnTransformHandler[];
+    /** contains a list of `onEmit` handlers that will be called once the file contents of the bundle has been finalized by esbuild,
+     * but additional actions (such as linking, and re-incorporating imports for generic loaders) still need to be taken care of by the user's plugins.
+     * the callbacks accumulated here are registered by {@link SuperPluginBuild.onEmit}.
+    */
+    onEmitHandlers: OnEmitHandler[];
+    /** contains a list of `onEnd` handlers that will be called at the end of the build,
+     * after we have modified the contents of the resulting in-memory files.
+     * the callbacks accumulated here are registered by {@link SuperPluginBuild.onEnd}.
+    */
+    onEndHandlers: OnEndHandler[];
+    /** holds all loaded resources, using `${namespace}:${resolved_path}` for the key.
+     * this registry is needed in order to trace back the loaded input file(s) from which an emitted file originates from,
+     * in order to make the functionality of {@link SuperPluginBuild.onEmit} possible.
+    */
+    resolvedResourceRegistry: Map<NamespacedPath, BundledInputFile>;
+    /** the controller used for commanding the state of the "long build" plugin. */
+    longBuildController: LongBuildController;
+    /** indicates the original `write` option specified by the user when instantiating the build. */
+    shouldWrite: boolean;
+    /** indicates if the original `allowOverwrite` option was enabled when the build was started. */
+    shouldOverwrite: boolean;
+    /** a logging function for internal debugging. it gets called only when {@link DEBUG.LOG} is enabled. */
+    log: LoggerFunction;
+    constructor(super_options: SuperBuildExclusiveOptions);
+    /** this method wraps a {@link SuperPlugin} on top of each of the user's base plugin,
+     * in addition to injecting two essential plugins at their correct position to make the new plugin apis work.
+     *
+     * the two internal plugins that get injected are:
+     * - {@link nativeReplicaPlugin}: this plugin mimics esbuild's native resource path resolution and loading,
+     *   and it gets injected at the last, since esbuild only performs its native actions when other plugins don't return a viable result.
+     * - {@link longBuildPlugin}: this plugin gets injected at the beginning,
+     *   and it book-keeps the number of resources/paths that have entered, the number of resources that have exited (i.e. loaded),
+     *   and the number of resources that have been cached, in order to determine when esbuild has concluded processing all inputs,
+     *   before esbuild exists out of the build and begins calling the `build.onEnd` callbacks.
+     *   once this plugin has determined that all files in the current scope have been processed, it gathers all `imports` from the {@link OnTransformResult}s,
+     *   and compiles/bundles them in a new recursive scope (hence the name "long-build").
+    */
+    processPlugins(options: EsbuildBuildOptions): EsbuildBuildOptions;
+    /** creates the the metafile object from esbuild's {@link EsbuildBuildResult},
+     * and registers all output files onto it for the {@link emissionsDriverPlugin} to initiate the next step (`onEmit` stage).
+    */
+    createMetafile(result: EsbuildBuildResult, config: Pick<MetafileConfig, "resolvePath">): Metafile;
+    /** concludes the build after the all registered {@link onEmitHandlers} and {@link onEndHandlers}
+     * have been executed by the {@link emissionsDriverPlugin} when it enters its `onEnd` stage (registered to the "true" `build` object).
+     *
+     * you must pass the mutated {@link Metafile} that you receive from calling the {@link createMetafile}
+     * method at the beginning of the {@link emissionsDriverPlugin}'s `onEnd` stage,
+     * so that if there's anything that should get written onto your filesystem, it will take place before the build concludes.
+    */
+    endBuild(metafile: Metafile): Promise<void>;
+}
+//# sourceMappingURL=build_context.d.ts.map

package/esm/super/build_context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build_context.d.ts","sourceRoot":"","sources":["../../src/super/build_context.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAGF,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAG9G,OAAO,EAAE,mBAAmB,EAAmB,MAAM,0BAA0B,CAAA;AAE/E,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AAG5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,mBAAmB,EAAE,kBAAkB,EAAqB,MAAM,eAAe,CAAA;AAGhJ,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC7D,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,mBAAmB,CAAA;CAC7B;AAED,MAAM,WAAW,aAAc,SAAQ,aAAa;IACnD,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,cAAc,CAAA;CACxB;AAED,MAAM,WAAW,YAAY;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,oBAAoB,CAAA;CAC9B;AAED,0FAA0F;AAC1F,qBAAa,iBAAiB;IAC7B;;MAEE;IACK,mBAAmB,EAAE,kBAAkB,EAAE,CAAK;IAErD;;;MAGE;IACK,cAAc,EAAE,aAAa,EAAE,CAAK;IAE3C;;;MAGE;IACK,aAAa,EAAE,YAAY,EAAE,CAAK;IAEzC;;;MAGE;IACK,wBAAwB,EAAE,GAAG,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAY;IAElF,+EAA+E;IACxE,mBAAmB,EAAE,mBAAmB,CAAA;IAE/C,gGAAgG;IACzF,WAAW,EAAE,OAAO,CAAO;IAElC,gGAAgG;IACzF,eAAe,EAAE,OAAO,CAAQ;IAEvC,wGAAwG;IACjG,GAAG,EAAE,cAAc,CAAA;gBAEd,aAAa,EAAE,0BAA0B;IAUrD;;;;;;;;;;;;MAYE;IACK,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB;IAgCxE;;MAEE;IACK,cAAc,CACpB,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,aAAa,CAAC,GACzC,QAAQ;IAYX;;;;;;MAME;IACW,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAKxD"}

package/esm/super/build_context.js

@@ -0,0 +1,124 @@
+/** the {@link SuperBuildContext} is a centralized context that is created for each individual {@link SuperBuild.build} call.
+ *
+ * its main purpose is to inject some required plugins at their correct position, hold a few stateful objects,
+ * and create a wrapper on top of the user's provided plugins so that the extended plugin api becomes available to them.
+ *
+ * @module
+*/
+import { isArray, parseFilepathInfo } from "../deps.js";
+import { Metafile } from "../esbuild/metafile.js";
+import { logLogger, noopLogger } from "../funcdefs.js";
+import { emissionsDriverPlugin } from "../plugins/emissions_driver.js";
+import { LongBuildController, longBuildPlugin } from "../plugins/long_build.js";
+import { nativeReplicaPlugin } from "../plugins/native_replica.js";
+import { SuperPlugin } from "./plugin.js";
+/** a centralized context is created for each individual {@link SuperBuild.build} call. */
+export class SuperBuildContext {
+    /** contains a list of transformation handlers that will be used for matching contents returned by the plugins' `onLoad` hooks,
+     * in order to transfer them to the registered {@link SuperPluginBuild.onTransform} hooks.
+    */
+    onTransformHandlers = [];
+    /** contains a list of `onEmit` handlers that will be called once the file contents of the bundle has been finalized by esbuild,
+     * but additional actions (such as linking, and re-incorporating imports for generic loaders) still need to be taken care of by the user's plugins.
+     * the callbacks accumulated here are registered by {@link SuperPluginBuild.onEmit}.
+    */
+    onEmitHandlers = [];
+    /** contains a list of `onEnd` handlers that will be called at the end of the build,
+     * after we have modified the contents of the resulting in-memory files.
+     * the callbacks accumulated here are registered by {@link SuperPluginBuild.onEnd}.
+    */
+    onEndHandlers = [];
+    /** holds all loaded resources, using `${namespace}:${resolved_path}` for the key.
+     * this registry is needed in order to trace back the loaded input file(s) from which an emitted file originates from,
+     * in order to make the functionality of {@link SuperPluginBuild.onEmit} possible.
+    */
+    resolvedResourceRegistry = new Map();
+    /** the controller used for commanding the state of the "long build" plugin. */
+    longBuildController;
+    /** indicates the original `write` option specified by the user when instantiating the build. */
+    shouldWrite = true;
+    /** indicates if the original `allowOverwrite` option was enabled when the build was started. */
+    shouldOverwrite = false;
+    /** a logging function for internal debugging. it gets called only when {@link DEBUG.LOG} is enabled. */
+    log;
+    constructor(super_options) {
+        const { debuggingLogs = false } = super_options, log = debuggingLogs === false ? noopLogger
+            : debuggingLogs === true ? logLogger
+                : debuggingLogs;
+        this.log = log;
+        this.longBuildController = new LongBuildController({ debuggingLogs: log });
+    }
+    /** this method wraps a {@link SuperPlugin} on top of each of the user's base plugin,
+     * in addition to injecting two essential plugins at their correct position to make the new plugin apis work.
+     *
+     * the two internal plugins that get injected are:
+     * - {@link nativeReplicaPlugin}: this plugin mimics esbuild's native resource path resolution and loading,
+     *   and it gets injected at the last, since esbuild only performs its native actions when other plugins don't return a viable result.
+     * - {@link longBuildPlugin}: this plugin gets injected at the beginning,
+     *   and it book-keeps the number of resources/paths that have entered, the number of resources that have exited (i.e. loaded),
+     *   and the number of resources that have been cached, in order to determine when esbuild has concluded processing all inputs,
+     *   before esbuild exists out of the build and begins calling the `build.onEnd` callbacks.
+     *   once this plugin has determined that all files in the current scope have been processed, it gathers all `imports` from the {@link OnTransformResult}s,
+     *   and compiles/bundles them in a new recursive scope (hence the name "long-build").
+    */
+    processPlugins(options) {
+        options.plugins ??= [];
+        // insert the "native loader" at the last, so that esbuild never gets to load natively
+        // (which would bypass our `onLoad` overload, making all `onTransform` hooks unreachable).
+        options.plugins.push(nativeReplicaPlugin());
+        // insert the "emissions driver" as the second plugin,
+        // so that it can drive all `onEmit` and `onEnd` callback hooks after the build has concluded.
+        options.plugins.unshift(emissionsDriverPlugin({ ctx: this }));
+        // insert a longbuild plugin at the very beginning so that it can intercept all incoming files.
+        const controller = this.longBuildController;
+        options.plugins.unshift(longBuildPlugin({ controller }));
+        options.plugins = options.plugins.map((plugin) => (new SuperPlugin(this, plugin)));
+        // we also insert the unique long build entry point to the options.
+        const long_build_filename = controller.steps.at(-1).filename, entryPoints = (options.entryPoints ??= []);
+        if (isArray(entryPoints)) {
+            entryPoints.push(long_build_filename);
+        }
+        else {
+            // stripping away the ".js" extension from the filename.
+            entryPoints[long_build_filename] = parseFilepathInfo(long_build_filename).basename;
+        }
+        this.shouldWrite = options.write ?? true;
+        this.shouldOverwrite = options.allowOverwrite ?? false;
+        // we are forced to enable `metafile` and disable `write` because our emissions driver plugin depends on these crucial options.
+        // once the build has concluded, the emissions driver plugin will call the `endBuild`
+        // method to take care of emitting the files to the filesystem if `this.shouldWrite` is set to `true`.
+        options.metafile = true;
+        options.write = false;
+        return options;
+    }
+    /** creates the the metafile object from esbuild's {@link EsbuildBuildResult},
+     * and registers all output files onto it for the {@link emissionsDriverPlugin} to initiate the next step (`onEmit` stage).
+    */
+    createMetafile(result, config) {
+        const metafile = new Metafile(result.metafile, {
+            resolvePath: config.resolvePath,
+            resolvedResourceRegistry: this.resolvedResourceRegistry,
+        });
+        for (const esbuild_file of result.outputFiles) {
+            metafile.addFile(esbuild_file);
+        }
+        // in order for all imports to get discovered and linked to each other's output file objects,
+        // we must run the method below after all output files have been added.
+        metafile.scanEsbuildImports();
+        return metafile;
+    }
+    /** concludes the build after the all registered {@link onEmitHandlers} and {@link onEndHandlers}
+     * have been executed by the {@link emissionsDriverPlugin} when it enters its `onEnd` stage (registered to the "true" `build` object).
+     *
+     * you must pass the mutated {@link Metafile} that you receive from calling the {@link createMetafile}
+     * method at the beginning of the {@link emissionsDriverPlugin}'s `onEnd` stage,
+     * so that if there's anything that should get written onto your filesystem, it will take place before the build concludes.
+    */
+    async endBuild(metafile) {
+        // if the user had originally set the `EsbuildBuildOption.write` to `true | undefined`,
+        // then we shall emit the files onto the filesystem, now that the build has concluded.
+        if (this.shouldWrite) {
+            await metafile.writeFiles(this.shouldOverwrite);
+        }
+    }
+}

package/esm/super/mod.d.ts

@@ -0,0 +1,12 @@
+/** super-build lets you overload esbuild to expand what you're capable of doing in the plugin-api.
+ *
+ * @module
+*/
+export type * from "./build.js";
+export { SuperBuild } from "./build.js";
+export { SuperBuildContext } from "./build_context.js";
+export { SuperPlugin, type SuperPluginSetup } from "./plugin.js";
+export { SuperPluginBuild } from "./plugin_build.js";
+export type * from "./typedefs.js";
+export { INNER_PLUGIN_BUILD } from "./typedefs.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/super/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/super/mod.ts"],"names":[],"mappings":"AAAA;;;EAGE;AAEF,mBAAmB,YAAY,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,mBAAmB,eAAe,CAAA;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA"}

package/esm/super/mod.js

@@ -0,0 +1,9 @@
+/** super-build lets you overload esbuild to expand what you're capable of doing in the plugin-api.
+ *
+ * @module
+*/
+export { SuperBuild } from "./build.js";
+export { SuperBuildContext } from "./build_context.js";
+export { SuperPlugin } from "./plugin.js";
+export { SuperPluginBuild } from "./plugin_build.js";
+export { INNER_PLUGIN_BUILD } from "./typedefs.js";

package/esm/super/plugin.d.ts

@@ -0,0 +1,23 @@
+/** the {@link SuperPlugin} class wraps over your regular esbuild plugins to swap the `build: esbuild.PluginBuild` object that esbuild passes,
+ * with a {@link SuperPluginBuild}, super-build lets you overload esbuild to expand what you're capable of doing in the plugin-api.
+ *
+ * @module
+*/
+import type { MaybePromise } from "../deps.js";
+import type { EsbuildPlugin, EsbuildPluginBuild } from "../esbuild/strongtypes.js";
+import type { SuperBuildContext } from "./build_context.js";
+import { SuperPluginBuild } from "./plugin_build.js";
+/** convenient type for annotating your plugin setup functions that use super-build's extended plugin api. */
+export type SuperPluginSetup = (build: SuperPluginBuild) => MaybePromise<void>;
+/** this class wraps over a base `esbuild.Plugin` to swap out the `build: esbuild.PluginBuild` that gets passed to its `setup` function with a {@link SuperPluginBuild},
+ * so that the plugin get access to all the exclusive features.
+ *
+ * expand your horizons by enrolling into jujutsu-highschool this summer and learning a new domain expansion technique; only for $15,000!
+*/
+export declare class SuperPlugin implements EsbuildPlugin {
+    #private;
+    name: string;
+    setup: (build: EsbuildPluginBuild | SuperPluginBuild) => MaybePromise<void>;
+    constructor(ctx: SuperBuildContext, base_plugin: EsbuildPlugin);
+}
+//# sourceMappingURL=plugin.d.ts.map

package/esm/super/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/super/plugin.ts"],"names":[],"mappings":"AAAA;;;;EAIE;AAEF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAClF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAGpD,6GAA6G;AAC7G,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,YAAY,CAAC,IAAI,CAAC,CAAA;AAE9E;;;;EAIE;AACF,qBAAa,WAAY,YAAW,aAAa;;IAOzC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,CAAC,KAAK,EAAE,kBAAkB,GAAG,gBAAgB,KAAK,YAAY,CAAC,IAAI,CAAC,CAAA;gBAEtE,GAAG,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa;CAW9D"}

package/esm/super/plugin.js

@@ -0,0 +1,31 @@
+/** the {@link SuperPlugin} class wraps over your regular esbuild plugins to swap the `build: esbuild.PluginBuild` object that esbuild passes,
+ * with a {@link SuperPluginBuild}, super-build lets you overload esbuild to expand what you're capable of doing in the plugin-api.
+ *
+ * @module
+*/
+import { SuperPluginBuild } from "./plugin_build.js";
+/** this class wraps over a base `esbuild.Plugin` to swap out the `build: esbuild.PluginBuild` that gets passed to its `setup` function with a {@link SuperPluginBuild},
+ * so that the plugin get access to all the exclusive features.
+ *
+ * expand your horizons by enrolling into jujutsu-highschool this summer and learning a new domain expansion technique; only for $15,000!
+*/
+export class SuperPlugin {
+    // unfortunately, esbuild disallows any enumerable custom property to be set on the plugin `Object`.
+    // hence, we declare all custom properties as private, so that esbuild does not discover them.
+    // in the future, I may consider turning it into non-enumerable properties rather than private ones, if class extensions are desired.
+    #basePlugin;
+    #ctx;
+    name;
+    setup;
+    constructor(ctx, base_plugin) {
+        this.#basePlugin = base_plugin;
+        this.#ctx = ctx;
+        this.name = base_plugin.name;
+        // esbuild strips away the setup function from its host object, effectively removing the `this` context.
+        // thus, we define the setup function as a closure rather than a method.
+        const self = this;
+        this.setup = (build) => {
+            return self.#basePlugin.setup(new SuperPluginBuild(self.#ctx, build, self.name));
+        };
+    }
+}

package/esm/super/plugin_build.d.ts

@@ -0,0 +1,38 @@
+/** the {@link SuperPluginBuild} class extends `esbuild.PluginBuild` to introduce additional functionality to esbuild's plugin api.
+ *
+ * TODO: I think I should begin adding new utility features to the superbuild plugin build, such as "resolvePath" and "resolveOutdirPath", etc...
+ *
+ * @module
+*/
+import type { EsbuildBuildOptions, EsbuildOnEndCallback, EsbuildOnStartCallback, EsbuildPluginBuild, EsbuildResolveOptions, EsbuildResolveResult, OnResolveCallback, OnResolveOptions } from "../esbuild/strongtypes.js";
+import { SuperBuild } from "./build.js";
+import type { SuperBuildContext } from "./build_context.js";
+import type { OnEmitCallback, OnEmitOptions, OnLoadCallback, OnLoadOptions, OnTransformCallback, OnTransformOptions } from "./typedefs.js";
+import { INNER_PLUGIN_BUILD } from "./typedefs.js";
+/** this is the extension of `esbuild.PluginBuild` that introduces additional functionality to esbuild's plugin api. */
+export declare class SuperPluginBuild implements EsbuildPluginBuild {
+    protected ctx: SuperBuildContext;
+    protected basePluginBuild: EsbuildPluginBuild;
+    protected readonly pluginName: string;
+    initialOptions: EsbuildBuildOptions;
+    readonly esbuild: SuperBuild;
+    /** a reference to the original {@link EsbuildPluginBuild} that was used to construct this class.
+     *
+     * its presence can be used to check whether or not your plugin is running inside a super-build.
+     * gaining access to esbuild's original `PluginBuild` can be useful in certain situations where bypassing super-build is necessary,
+     * such as in the case of the {@link nativeReplicaPlugin}, and the underlying {@link EsbuildNativeResolver} that it uses.
+    */
+    readonly [INNER_PLUGIN_BUILD]: EsbuildPluginBuild;
+    constructor(ctx: SuperBuildContext, base_plugin_build: EsbuildPluginBuild, plugin_name: string);
+    resolve(path: string, options?: EsbuildResolveOptions): Promise<EsbuildResolveResult>;
+    onStart(callback: EsbuildOnStartCallback): void;
+    onEnd(callback: EsbuildOnEndCallback): void;
+    onResolve(options: OnResolveOptions, callback: OnResolveCallback): void;
+    onLoad(options: OnLoadOptions, callback: OnLoadCallback): void;
+    onDispose(callback: () => void): void;
+    /** TODO: add documentation and usage examples. */
+    onTransform(options: OnTransformOptions, callback: OnTransformCallback): void;
+    /** TODO: add documentation and usage examples. */
+    onEmit(options: OnEmitOptions, callback: OnEmitCallback): void;
+}
+//# sourceMappingURL=plugin_build.d.ts.map

package/esm/super/plugin_build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin_build.d.ts","sourceRoot":"","sources":["../../src/super/plugin_build.ts"],"names":[],"mappings":"AAAA;;;;;EAKE;AAGF,OAAO,KAAK,EACX,mBAAmB,EAEnB,oBAAoB,EAGpB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EAEpB,iBAAiB,EACjB,gBAAgB,EAChB,MAAM,2BAA2B,CAAA;AAIlC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,KAAK,EAEX,cAAc,EACd,aAAa,EAEb,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAmClD,uHAAuH;AACvH,qBAAa,gBAAiB,YAAW,kBAAkB;IAC1D,SAAS,CAAC,GAAG,EAAE,iBAAiB,CAAA;IAChC,SAAS,CAAC,eAAe,EAAE,kBAAkB,CAAA;IAC7C,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC9B,cAAc,EAAE,mBAAmB,CAAA;IAC1C,SAAgB,OAAO,EAAE,UAAU,CAAA;IAEnC;;;;;MAKE;IACF,SAAgB,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;gBAE5C,GAAG,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM;IAYvF,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAgBzF,OAAO,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAI/C,KAAK,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAK3C,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IA8BvE,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI;IA6F9D,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAI5C,kDAAkD;IAC3C,WAAW,CAAC,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAKpF,kDAAkD;IAC3C,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI;CAIrE"}