@oazmi/superbuild 0.1.0

package/esm/plugins/long_build.d.ts

@@ -0,0 +1,138 @@
+/** an internal super-build plugin that enables the inclusion of additional imports dynamically,
+ * as esbuild is transforming the loaded content.
+ *
+ * the reason why this plugin is called "long build" is because it hangs up at its loader stage and waits for the import requests to come in,
+ * until all known entities that had entered the `onResolve` stage have exited through at least one `onLoad` hook.
+ *
+ * @module
+*/
+import type { EsbuildPartialMessage, EsbuildPlugin, EsbuildPluginSetup, OnResolveResult } from "../esbuild/strongtypes.js";
+import type { ImportEntity } from "../super/typedefs.js";
+import type { LoggerFunction } from "../typedefs.js";
+export interface LongBuildControllerConfig {
+    /** enable internal logging for the {@link LongBuildController}, when {@link DEBUG.LOG} is enabled.
+     *
+     * @defaultValue {@link noopLogger}
+    */
+    debuggingLogs?: LoggerFunction;
+}
+/** the controller used for commanding the state of the "long build" plugin. */
+export declare class LongBuildController {
+    /** the unique base filename that will be used by the {@link longBuildPluginSetup} plugin to insert its "long build" js file as an entry-point.
+     * the full filename format it will use will be: `${recursion_number}.(${uuid}).js`.
+    */
+    readonly uuid: string;
+    /** the unique filename(s) that will be used for the "long build" js files.
+     * it is a computed value that evaluates to `.(${uuid}).js`,
+     * and the actual filename that gets inserted/injected will also have a leading number, signifying the "build/recursion number".
+     *
+     * for instance, the entry-point long build js file will be named: `0.(${uuid}).js`,
+     * while the next recursive "long build" import within the `0.(${uuid}).js` file will be named `1.(${uuid}).js`,
+     * and so on (until a "long build" js file with zero external imports/includes is discovered, at which point we shall halt).
+    */
+    readonly baseFilename: string;
+    /** the name of the "long build dependency" file, as defined in {@link LONGBUILD.DEPS_FILE}.
+     *
+     * its value evaluates to `deps.(${uuid}).js`, and it is imported by each "long build step" js file as a dependency,
+     * in order to have a shared resource variable where all imports will get registered.
+    */
+    readonly depsFilename: string;
+    /** the namespace used by the {@link longBuildPlugin}.
+     * it is a computed value that evaluates to `oazmi-superbuild-long_build-plugin-${uuid}`.
+    */
+    readonly pluginNamespace: string;
+    /** the current build/recursion number. it starts with zero, and it is used for indicating the filename of the current "long build" file. */
+    readonly buildNumber: number;
+    /** the number of files in the esbuild build process that are currently in circulation.
+     *
+     * - everytime a new file hits the "long build" plugin's `onResolve` hook, this value gets incremented by one,
+     *   since a "new file is currently in circulation".
+     * - whenever a file gets successfully loaded via some plugin's `onLoad` hook,
+     *   the {@link SuperPluginBuild.onLoad} overload decrements this shared-state counter,
+     *   since a "file that was in circulation has exited".
+     * - a caveat to look out for is the fact that if any plugin calls {@link SuperPluginBuild.resolve},
+     *   this counter will get incremented again (double count),
+     *   since the resolve request will go through our "long build" plugin's `onResolve` hook once again.
+     *   to combat this double count, the {@link SuperPluginBuild.resolve} function decrements this counter whenever it gets called.
+    */
+    remainingFilesCounter: number;
+    /** esbuild caches the loaded result of an `onLoad` hook, based on the result of the `onResolve` hook's `result.path` and `result.namespace`
+     * (I don't know if esbuild also caches with respect to the `with` import attribute).
+     * but we don't want to count any cached paths towards {@link remainingFilesCounter}, since they won't be loaded again;
+     * which is why we need this hash-set to keep track of what has already been seen once.
+    */
+    protected encounteredPaths: Set<string>;
+    steps: Array<LongBuildStep>;
+    /** a logging function for internal debugging. it gets called only when {@link DEBUG.LOG} is enabled. */
+    log: LoggerFunction;
+    constructor(config?: LongBuildControllerConfig);
+    incrementBuild(): EsbuildPartialMessage[];
+    incrementFilesCounter(pathname?: string): void;
+    decrementFilesCounter(pathname?: string): void;
+    cacheResolvedResult(args: OnResolveResult): void;
+    /** this function does the inverse of {@link prepareLongBuildFileContent};
+     * it parses the js-transpiled contents of the "long build" file and extracts/reconstructs the resource import `Map` from it.
+     *
+     * since I plan on using a dynamic script `import()` to execute the contents of a modified version of the "long build" file content,
+     * this method has to be made asynchronous.
+     * I'm certainly not going to be using `eval` or the `Function` constructor, because they are often restricted in some js-environments.
+    */
+    parseLongBuildFileContent(longbuild_file_contents: string): Promise<Map<string, ImportEntity[]>>;
+}
+export declare class LongBuildStep {
+    /** the build number of this build step, starting with zero. */
+    readonly buildNumber: number;
+    /** the unique filename of this "long build step" js file.
+     * it is a computed value that evaluates to `${buildNumber}.(${uuid}).js`.
+    */
+    readonly filename: string;
+    readonly promise: Promise<void>;
+    readonly signalresolve: (() => void);
+    readonly cancelResolve: (() => void);
+    readonly resourceImports: Map<string, ImportEntity[]>;
+    protected readonly controller: LongBuildController;
+    constructor(parent_controller: LongBuildController, build_number: number);
+    /** register imports performed by some resource `importer_key`.
+     * the `importer_key` should be formatted as `${namespace}:${resolved_path}` of the resource performing the `imports`.
+    */
+    pushImports(importer_key: string, imports: ImportEntity[]): void;
+    /** prepares the file contents of the "long build" of this "long build step".
+     *
+     * you would use this once you have deduced that all files that were in circulation during this build step have exited,
+     * and therefore your long build plugin must also halt by loading the contents prepared here by this method.
+     *
+     * > [!caution]
+     * > the file's contents are in typescript rather than javascript.
+     * > so make sure to use the `"ts"` esbuild loader for it.
+    */
+    prepareLongBuildFileContent(): string;
+}
+export interface LongBuildPluginSetupConfig {
+    controller: LongBuildController;
+}
+/** this plugin that enables the inclusion of additional imports dynamically, as esbuild is transforming the loaded content.
+ *
+ * the reason why this plugin is called "long build" is because it hangs up at its loader stage and waits for the import requests to come in,
+ * until all known entities that had entered the `onResolve` stage have exited through at least one `onLoad` hook.
+ *
+ * > [!note]
+ * > this plugin should be placed at the very beginning, as it needs to inspect all incoming path-resolution requests,
+ * > in order to track if any unprocessed files still remain while bundling.
+ *
+ * > _Mr. Feast_: Hello everyone, it's your host jimmy neutrino,
+ * > and today we'll be trafficking 100 foreign slaves to compete against one another in building the longest pyramid.
+ * > whichever slave manages to build the tallest pyramid at the 100 hour mark will earn his freedom and a also a free bugatti**!
+ * >
+ * > _Lapdog #1_: the rules are simple: if a slave falls asleeps, or moves out of the red circle,
+ * > they'll get disqualified immediately and be deported back to their original owner.
+ * >
+ * > _Lapdog #2_: look at this wonderful art piece that I commissioned from epstien himself!
+ * > hey! stop criticizing me! I'm doing this for my son! also, I identify as they/them, so you can't criticize me now.
+ * >
+ * > **no auto insurance will be supplied, and state sales tax will be the responsibility of the winner.
+ * > failing to register your prize within 6 hours of winning will indicate that you wish to forfeit from owning it.
+*/
+export declare const longBuildPluginSetup: (config: LongBuildPluginSetupConfig) => EsbuildPluginSetup;
+/** {@inheritDoc longBuildPluginSetup} */
+export declare const longBuildPlugin: (config: LongBuildPluginSetupConfig) => EsbuildPlugin;
+//# sourceMappingURL=long_build.d.ts.map

package/esm/plugins/long_build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"long_build.d.ts","sourceRoot":"","sources":["../../src/plugins/long_build.ts"],"names":[],"mappings":"AAAA;;;;;;;EAOE;AAGF,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAsB,kBAAkB,EAA6B,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAGzK,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAgDpD,MAAM,WAAW,yBAAyB;IACzC;;;MAGE;IACF,aAAa,CAAC,EAAE,cAAc,CAAA;CAC9B;AAED,+EAA+E;AAC/E,qBAAa,mBAAmB;IAC/B;;MAEE;IACF,SAAgB,IAAI,EAAE,MAAM,CAAA;IAE5B;;;;;;;MAOE;IACF,SAAgB,YAAY,EAAE,MAAM,CAAA;IAEpC;;;;MAIE;IACF,SAAgB,YAAY,EAAE,MAAM,CAAA;IAEpC;;MAEE;IACF,SAAgB,eAAe,EAAE,MAAM,CAAA;IAEvC,4IAA4I;IAC5I,SAAgB,WAAW,EAAE,MAAM,CAAA;IAEnC;;;;;;;;;;;MAWE;IACK,qBAAqB,EAAE,MAAM,CAAA;IAEpC;;;;MAIE;IACF,SAAS,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAY;IAE5C,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,CAAK;IAEvC,wGAAwG;IACjG,GAAG,EAAE,cAAc,CAAA;gBAEd,MAAM,CAAC,EAAE,yBAAyB;IAYvC,cAAc,IAAI,qBAAqB,EAAE;IAgBzC,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAO9C,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAU9C,mBAAmB,CAAC,IAAI,EAAE,eAAe;IAwBhD;;;;;;MAME;IACW,yBAAyB,CAAC,uBAAuB,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;CAW7G;AAED,qBAAa,aAAa;IACzB,+DAA+D;IAC/D,SAAgB,WAAW,EAAE,MAAM,CAAA;IAEnC;;MAEE;IACF,SAAgB,QAAQ,EAAE,MAAM,CAAA;IAEhC,SAAgB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtC,SAAgB,aAAa,EAAE,CAAC,MAAM,IAAI,CAAC,CAAA;IAE3C,SAAgB,aAAa,EAAE,CAAC,MAAM,IAAI,CAAC,CAAA;IAE3C,SAAgB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAY;IAExE,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAA;gBAEtC,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM;IASxE;;MAEE;IACK,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE;IAIhE;;;;;;;;MAQE;IACK,2BAA2B,IAAI,MAAM;CAoC5C;AAED,MAAM,WAAW,0BAA0B;IAC1C,UAAU,EAAE,mBAAmB,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;EAqBE;AACF,eAAO,MAAM,oBAAoB,WAAY,0BAA0B,KAAG,kBAgDzE,CAAA;AAED,yCAAyC;AACzC,eAAO,MAAM,eAAe,WAAY,0BAA0B,KAAG,aAKpE,CAAA"}

package/esm/plugins/long_build.js

@@ -0,0 +1,288 @@
+/** an internal super-build plugin that enables the inclusion of additional imports dynamically,
+ * as esbuild is transforming the loaded content.
+ *
+ * the reason why this plugin is called "long build" is because it hangs up at its loader stage and waits for the import requests to come in,
+ * until all known entities that had entered the `onResolve` stage have exited through at least one `onLoad` hook.
+ *
+ * @module
+*/
+import { array_isEmpty, DEBUG, escapeLiteralStringForRegex, json_stringify, parseFilepathInfo, pathToPosixPath, promiseOutside } from "../deps.js";
+import { cancelableDelayedPromiseResolver, generateUuid, noopLogger } from "../funcdefs.js";
+var LONGBUILD;
+(function (LONGBUILD) {
+    /** the minimum amount of time (in ms) that the long build will wait before concluding its `contents`,
+     * after it has determined that no active files remain in circulation.
+     * if a new file is suddenly introduced while the longbuild is waiting for this delay to complete, it will halt the timer,
+     * and wait for all new files in the circulation to complete before beginning this countdown again.
+     *
+     * ideally, this should be set to a safe high value,
+     * where you can be certain that esbuild's go-side transpiler/transformer won't take any longer than that to transform a single file in your bundle.
+     * i.e. the lower bound of this enum value = `max(...all_bundled_files.map((file) => get_transpilation_time(file))`
+    */
+    LONGBUILD[LONGBUILD["ONLOAD_MIN_DELAY"] = 500] = "ONLOAD_MIN_DELAY";
+    /** the name of the resource-imports storage variable used across the "long build step" js files. */
+    LONGBUILD["RESOURCE_VAR_NAME"] = "resourceImports";
+    /** this will be common dependency file of each "long build step" js file, so that they all share the same `resourceImports` storage variable.
+     *
+     * the name of this file will be `deps.(${uuid}).js`, defined in the {@link LongBuildController}.
+    */
+    LONGBUILD["DEPS_FILE"] = "\nexport interface ImportEntity<K = any> {\n\tkey: K\n\tpath: string\n\twith: Record<string, string>\n\texternal: boolean\n}\n\nexport const resourceImports: Map<\n\tstring,        // the importer's key.\n\tImportEntity[] // all of the entities imported by the importer.\n> = new Map()\n\n// esbuild likes to add a \"@__PURE__\" annotation to the variable above.\n// hence, to ensure that it never gets stripped away (because we want to dynamically import it later),\n// we perform an action that has a potential for side-effect, preventing esbuild from ever dropping this variable in the bundle.\nresourceImports.size\n\nexport const console_log = (...args: any[]) => {\n\t// console.log(...args) // for debugging purposes.\n}\n";
+})(LONGBUILD || (LONGBUILD = {}));
+const import_statement_regex = new RegExp("await\\s+import\\s*\\(\\s*(?<quote>[\"'`])(?<importPath>.*?)\\k<quote>\\s*\\)", "g");
+/** the controller used for commanding the state of the "long build" plugin. */
+export class LongBuildController {
+    /** the unique base filename that will be used by the {@link longBuildPluginSetup} plugin to insert its "long build" js file as an entry-point.
+     * the full filename format it will use will be: `${recursion_number}.(${uuid}).js`.
+    */
+    uuid;
+    /** the unique filename(s) that will be used for the "long build" js files.
+     * it is a computed value that evaluates to `.(${uuid}).js`,
+     * and the actual filename that gets inserted/injected will also have a leading number, signifying the "build/recursion number".
+     *
+     * for instance, the entry-point long build js file will be named: `0.(${uuid}).js`,
+     * while the next recursive "long build" import within the `0.(${uuid}).js` file will be named `1.(${uuid}).js`,
+     * and so on (until a "long build" js file with zero external imports/includes is discovered, at which point we shall halt).
+    */
+    baseFilename;
+    /** the name of the "long build dependency" file, as defined in {@link LONGBUILD.DEPS_FILE}.
+     *
+     * its value evaluates to `deps.(${uuid}).js`, and it is imported by each "long build step" js file as a dependency,
+     * in order to have a shared resource variable where all imports will get registered.
+    */
+    depsFilename;
+    /** the namespace used by the {@link longBuildPlugin}.
+     * it is a computed value that evaluates to `oazmi-superbuild-long_build-plugin-${uuid}`.
+    */
+    pluginNamespace;
+    /** the current build/recursion number. it starts with zero, and it is used for indicating the filename of the current "long build" file. */
+    buildNumber;
+    /** the number of files in the esbuild build process that are currently in circulation.
+     *
+     * - everytime a new file hits the "long build" plugin's `onResolve` hook, this value gets incremented by one,
+     *   since a "new file is currently in circulation".
+     * - whenever a file gets successfully loaded via some plugin's `onLoad` hook,
+     *   the {@link SuperPluginBuild.onLoad} overload decrements this shared-state counter,
+     *   since a "file that was in circulation has exited".
+     * - a caveat to look out for is the fact that if any plugin calls {@link SuperPluginBuild.resolve},
+     *   this counter will get incremented again (double count),
+     *   since the resolve request will go through our "long build" plugin's `onResolve` hook once again.
+     *   to combat this double count, the {@link SuperPluginBuild.resolve} function decrements this counter whenever it gets called.
+    */
+    remainingFilesCounter;
+    /** esbuild caches the loaded result of an `onLoad` hook, based on the result of the `onResolve` hook's `result.path` and `result.namespace`
+     * (I don't know if esbuild also caches with respect to the `with` import attribute).
+     * but we don't want to count any cached paths towards {@link remainingFilesCounter}, since they won't be loaded again;
+     * which is why we need this hash-set to keep track of what has already been seen once.
+    */
+    encounteredPaths = new Set();
+    steps = [];
+    /** a logging function for internal debugging. it gets called only when {@link DEBUG.LOG} is enabled. */
+    log;
+    constructor(config) {
+        const uuid = generateUuid(2);
+        this.log = config?.debuggingLogs ?? noopLogger;
+        this.uuid = uuid;
+        this.baseFilename = `.(${uuid}).js`;
+        this.depsFilename = `deps.(${uuid}).js`;
+        this.pluginNamespace = `oazmi-superbuild-long_build-plugin-${uuid}`;
+        this.remainingFilesCounter = 0;
+        this.buildNumber = -1;
+        this.incrementBuild();
+    }
+    incrementBuild() {
+        const warnings = [];
+        if (this.remainingFilesCounter !== 0) {
+            warnings.push({
+                text: `[LongBuildController.incrementBuild]: the number of remaining files (${this.remainingFilesCounter}) in circulation during th current long-build (${this.buildNumber}) did not reach zero before the build was incremented!`
+            });
+        }
+        // hey! incrementing a readonly number is illegal, IN AMERICA! - bandit keith. (unless they pass the citizenship test)
+        this.steps.push(new LongBuildStep(this, ++this.buildNumber));
+        return warnings;
+    }
+    incrementFilesCounter(pathname) {
+        // cancel any prior resolve that may have been triggered.
+        this.steps[this.buildNumber].cancelResolve();
+        ++this.remainingFilesCounter;
+        if (DEBUG.LOG) {
+            this.log(`[LongBuildController]: increment for: "${pathname}". remaining files: ${this.remainingFilesCounter}.`);
+        }
+    }
+    decrementFilesCounter(pathname) {
+        // cancel any prior resolve that may have been triggered,
+        // so that we always ensure that the desired amount of time has been waited with absolutely no resource processing in between.
+        this.steps[this.buildNumber].cancelResolve();
+        if ((--this.remainingFilesCounter) <= 0) {
+            this.steps[this.buildNumber].signalresolve();
+        }
+        if (DEBUG.LOG) {
+            this.log(`[LongBuildController]: decrement for: "${pathname}". remaining files: ${this.remainingFilesCounter}.`);
+        }
+    }
+    cacheResolvedResult(args) {
+        // first we make sure that if the result is `external`, then we decrement the the file counter,
+        // as this resource will never go to the loading stage (never gets passed to an `onLoad`).
+        if (args.external) {
+            this.decrementFilesCounter(args.path);
+            return;
+        }
+        // for all other non-external cases, we expect an `args.path` to exist.
+        const path = pathToPosixPath(args.path), namespace = args.namespace ?? "file", key = namespace + ":" + path;
+        // if the resolved path has already been encountered once, then esbuild will have it cached, and so, no loader hooks will be called,
+        // therefore we must immediately decrement the files counter, since the loader can't do it any longer.
+        if (this.encounteredPaths.has(key)) {
+            if (DEBUG.LOG) {
+                this.log(`[LongBuildController]: already encountered: "${key}"`);
+            }
+            this.decrementFilesCounter(args.path);
+        }
+        else {
+            if (DEBUG.LOG) {
+                this.log(`[LongBuildController]: never encountered  : "${key}"`);
+            }
+            this.encounteredPaths.add(key);
+        }
+    }
+    /** this function does the inverse of {@link prepareLongBuildFileContent};
+     * it parses the js-transpiled contents of the "long build" file and extracts/reconstructs the resource import `Map` from it.
+     *
+     * since I plan on using a dynamic script `import()` to execute the contents of a modified version of the "long build" file content,
+     * this method has to be made asynchronous.
+     * I'm certainly not going to be using `eval` or the `Function` constructor, because they are often restricted in some js-environments.
+    */
+    async parseLongBuildFileContent(longbuild_file_contents) {
+        const 
+        // we first strip away all dynamic import statements and replace them with just the import string.
+        // for instance: `await import("./hello-world.xyz")` will transform to just "String.raw`./hello-world.xyz`".
+        js_content_without_imports = longbuild_file_contents.replaceAll(import_statement_regex, "String.raw`$<importPath>`"), js_blob = new Blob([js_content_without_imports], { type: "text/javascript" }), js_blob_url = URL.createObjectURL(js_blob), 
+        // now we dynamically load our bundled long-build js file that contains import statements, and then return them.
+        { [LONGBUILD.RESOURCE_VAR_NAME]: resourceImports } = await import(js_blob_url);
+        return resourceImports;
+    }
+}
+export class LongBuildStep {
+    /** the build number of this build step, starting with zero. */
+    buildNumber;
+    /** the unique filename of this "long build step" js file.
+     * it is a computed value that evaluates to `${buildNumber}.(${uuid}).js`.
+    */
+    filename;
+    promise;
+    signalresolve;
+    cancelResolve;
+    resourceImports = new Map();
+    controller;
+    constructor(parent_controller, build_number) {
+        this.controller = parent_controller;
+        this.buildNumber = build_number;
+        this.filename = `${build_number}${parent_controller.baseFilename}`;
+        const [promise, resolve, reject] = promiseOutside();
+        [this.signalresolve, this.cancelResolve] = cancelableDelayedPromiseResolver(resolve, LONGBUILD.ONLOAD_MIN_DELAY, parent_controller.log);
+        this.promise = promise;
+    }
+    /** register imports performed by some resource `importer_key`.
+     * the `importer_key` should be formatted as `${namespace}:${resolved_path}` of the resource performing the `imports`.
+    */
+    pushImports(importer_key, imports) {
+        this.resourceImports.set(importer_key, imports);
+    }
+    /** prepares the file contents of the "long build" of this "long build step".
+     *
+     * you would use this once you have deduced that all files that were in circulation during this build step have exited,
+     * and therefore your long build plugin must also halt by loading the contents prepared here by this method.
+     *
+     * > [!caution]
+     * > the file's contents are in typescript rather than javascript.
+     * > so make sure to use the `"ts"` esbuild loader for it.
+    */
+    prepareLongBuildFileContent() {
+        const all_imports_this_build = [...this.resourceImports];
+        const all_imports_js_str = all_imports_this_build.map(([importer_key, imports_arr]) => {
+            const imports_str_arr = imports_arr.map((import_entity) => {
+                const { key, path, with: with_attr = {}, external = false } = import_entity, key_str = json_stringify(key), path_str = json_stringify(path), with_str = json_stringify(with_attr), external_str = json_stringify(external), 
+                // to prevent resources marked as `external` from being discovered by esbuild, we don't wrap them around a dynamic `import(...)`.
+                import_statement = external ? path_str : `await import(${path_str})`;
+                // return `import(${path_str}, { with: { importer: "" } })`
+                return `{ key: ${key_str}, path: ${import_statement}, with: ${with_str}, external: ${external_str} }`;
+            });
+            const imports_str = imports_str_arr.join(",\n\t");
+            const importer_key_str = json_stringify(importer_key);
+            return `resourceImports.set(${importer_key_str}, [\n\t${imports_str}\n])`;
+        });
+        const deps_filename = this.controller.depsFilename, next_filename = `${this.buildNumber + 1}${this.controller.baseFilename}`, recursion_import_statement = !array_isEmpty(all_imports_this_build)
+            ? `import "${next_filename}" // recursion to the next long-build.`
+            : "// no imports were pushed this build-number. hence, this is the final long-build file.";
+        return `
+import { ${LONGBUILD.RESOURCE_VAR_NAME}, console_log } from "${deps_filename}"
+export { ${LONGBUILD.RESOURCE_VAR_NAME} } // export the "resourceImports" so that it can be imported by the parser.
+${recursion_import_statement}
+
+console_log("long build: ${this.buildNumber}")
+${all_imports_js_str}
+		`.trim();
+    }
+}
+/** this plugin that enables the inclusion of additional imports dynamically, as esbuild is transforming the loaded content.
+ *
+ * the reason why this plugin is called "long build" is because it hangs up at its loader stage and waits for the import requests to come in,
+ * until all known entities that had entered the `onResolve` stage have exited through at least one `onLoad` hook.
+ *
+ * > [!note]
+ * > this plugin should be placed at the very beginning, as it needs to inspect all incoming path-resolution requests,
+ * > in order to track if any unprocessed files still remain while bundling.
+ *
+ * > _Mr. Feast_: Hello everyone, it's your host jimmy neutrino,
+ * > and today we'll be trafficking 100 foreign slaves to compete against one another in building the longest pyramid.
+ * > whichever slave manages to build the tallest pyramid at the 100 hour mark will earn his freedom and a also a free bugatti**!
+ * >
+ * > _Lapdog #1_: the rules are simple: if a slave falls asleeps, or moves out of the red circle,
+ * > they'll get disqualified immediately and be deported back to their original owner.
+ * >
+ * > _Lapdog #2_: look at this wonderful art piece that I commissioned from epstien himself!
+ * > hey! stop criticizing me! I'm doing this for my son! also, I identify as they/them, so you can't criticize me now.
+ * >
+ * > **no auto insurance will be supplied, and state sales tax will be the responsibility of the winner.
+ * > failing to register your prize within 6 hours of winning will indicate that you wish to forfeit from owning it.
+*/
+export const longBuildPluginSetup = (config) => {
+    const controller = config.controller, longbuild_base_filename = controller.baseFilename, longbuild_deps_filename = controller.depsFilename, plugin_namespace = controller.pluginNamespace;
+    return (build) => {
+        const sbuild = build, // I can't think of a better way for annotating `build` as a `SuperPluginBuild` without getting a bunch of type errors.
+        filter = RegExp(escapeLiteralStringForRegex(longbuild_base_filename) + "$"), deps_file_filter = RegExp(escapeLiteralStringForRegex(longbuild_deps_filename) + "$");
+        build.onResolve({ filter: /.*/ }, (args) => {
+            // TODO: I believe `<stdin>` does not go through any `onResolve`, and jumps straight to `onLoad`. so, we must account for not decrementing the counter when it is `<stdin>`.
+            controller.incrementFilesCounter(args.path);
+            if (!args.path.endsWith(longbuild_base_filename)) {
+                return undefined;
+            }
+            const filename = parseFilepathInfo(args.path).filename; // this is to strip away any directory prefixes.
+            return { path: filename, namespace: plugin_namespace }; // TODO: should we set `sideEffects` to true?
+        });
+        build.onLoad({ filter: deps_file_filter, namespace: plugin_namespace }, (args) => {
+            return { contents: LONGBUILD.DEPS_FILE, loader: "ts" };
+        });
+        build.onLoad({ filter, namespace: plugin_namespace }, async (args) => {
+            // the "long build" js files need to temporarily remove themselves from the `remainingFilesCounter` circulation, otherwise it will never drop to zero
+            controller.decrementFilesCounter(args.path);
+            const filename = args.path, build_number = Number(filename.slice(0, -longbuild_base_filename.length)), build_step = controller.steps[build_number];
+            // wait for super-build to externally resolve the promise below to signal that the `remainingFilesCounter` has dropped to zero.
+            await build_step.promise;
+            const contents = build_step.prepareLongBuildFileContent(), warnings = controller.incrementBuild();
+            // we increment the `remainingFilesCounter` because returning from this function will cause it to drop to `-1` if we don't increment.
+            ++controller.remainingFilesCounter;
+            return { contents, loader: "ts", resolveDir: "./", warnings };
+        });
+        // long build file(s) should not be emitted into the filesystem.
+        sbuild.onEmit({
+            filter: /.*/,
+            inputs: [{ filter: /.*/, namespace: plugin_namespace }],
+        }, (args) => { return { write: false }; });
+    };
+};
+/** {@inheritDoc longBuildPluginSetup} */
+export const longBuildPlugin = (config) => {
+    return {
+        name: "oazmi-superbuild-long_build-plugin",
+        setup: longBuildPluginSetup(config),
+    };
+};

package/esm/plugins/native_replica.d.ts

@@ -0,0 +1,48 @@
+/** a plugin that replicates esbuild's native resource/path resolution and loading behavior through the plugin api layer.
+ *
+ * - for resolving paths, the plugin creates a sub-build that is free of any contaminating plugins to get esbuild to resolve the input resource naturally.
+ * - for loading content, the plugin places an `onLoad` hook to capture all file-namespace paths,
+ *   and then mimics esbuild's native loading behavior by guessing the loader it would use,
+ *   and then `fetch`es the content (without invoking esbuild's native loading in the process).
+ *
+ * @module
+*/
+import type { EsbuildBuildOptions, EsbuildPlugin, EsbuildPluginBuild, EsbuildPluginSetup, EsbuildResolveOptions, EsbuildResolveResult } from "../esbuild/strongtypes.js";
+/** this plugin replicates esbuild's native path resolution and loading behavior through the plugin api layer.
+ *
+ * > [!note]
+ * > you will probably want to place this as the last plugin, if you don't want it interfering with your other plugins' resolving and loading mechanisms.
+ *
+ * - for resolving paths, the plugin creates a sub-build that is free of any contaminating plugins to get esbuild to resolve the input resource naturally.
+ * - for loading content, the plugin places an `onLoad` hook to capture all file-namespace paths,
+ *   and then mimics esbuild's native loading behavior by guessing the loader it would use,
+ *   and then `fetch`es the content (without invoking esbuild's native loading in the process).
+ *
+ * > _Van_: It was Asche who was supposed to come here, not you, replica.
+ * >
+ * > _Luke_: Even if you refuse to acknowledge me, I am ME! Master... no, Van! Prepare to DIE!
+*/
+export declare const nativeReplicaPluginSetup: () => EsbuildPluginSetup;
+/** {@inheritDoc nativeReplicaPluginSetup} */
+export declare const nativeReplicaPlugin: () => EsbuildPlugin;
+/** this class provides {@link resolve} method that is capable of resolving paths using esbuild's node-resolution scanner.
+ *
+ * it works by invoking esbuild's `PluginBuild.resolve` function whenever the {@link resolve} method is called,
+ * and it holds an `onLoad` hook hostage by hanging forever,
+ * so that the internal sub-build does not conclude until the {@link stop} method has been called.
+*/
+export declare class EsbuildNativeResolver {
+    #private;
+    protected entryPoint: string;
+    protected namespace: string;
+    protected readonly startBuildPromise: Promise<void>;
+    protected readonly startBuildResolve: (() => void);
+    protected readonly stopBuildPromise: Promise<void>;
+    protected readonly stopBuildResolve: (() => void);
+    constructor(base_esbuild: EsbuildPluginBuild["esbuild"], build_options?: EsbuildBuildOptions);
+    resolve(path: string, options?: EsbuildResolveOptions): Promise<EsbuildResolveResult>;
+    stop(): Promise<void>;
+    protected initOptions(build_options?: EsbuildBuildOptions): EsbuildBuildOptions;
+    protected initPlugin(): EsbuildPlugin;
+}
+//# sourceMappingURL=native_replica.d.ts.map

package/esm/plugins/native_replica.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native_replica.d.ts","sourceRoot":"","sources":["../../src/plugins/native_replica.ts"],"names":[],"mappings":"AAAA;;;;;;;;EAQE;AAIF,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,oBAAoB,EAA6B,MAAM,2BAA2B,CAAA;AAKnM;;;;;;;;;;;;;EAaE;AACF,eAAO,MAAM,wBAAwB,QAAO,kBAqC3C,CAAA;AAED,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,QAAO,aAKtC,CAAA;AAYD;;;;;EAKE;AACF,qBAAa,qBAAqB;;IACjC,SAAS,CAAC,UAAU,SAA0B;IAC9C,SAAS,CAAC,SAAS,SAAa;IAChC,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,IAAI,CAAC,CAAA;IAClD,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAClD,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC,MAAM,IAAI,CAAC,CAAA;gBAKrC,YAAY,EAAE,kBAAkB,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,EAAE,mBAAmB;IAQ/E,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAKrF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC,SAAS,CAAC,WAAW,CAAC,aAAa,GAAE,mBAAwB,GAAG,mBAAmB;IAgBnF,SAAS,CAAC,UAAU,IAAI,aAAa;CA0BrC"}

package/esm/plugins/native_replica.js

@@ -0,0 +1,122 @@
+/** a plugin that replicates esbuild's native resource/path resolution and loading behavior through the plugin api layer.
+ *
+ * - for resolving paths, the plugin creates a sub-build that is free of any contaminating plugins to get esbuild to resolve the input resource naturally.
+ * - for loading content, the plugin places an `onLoad` hook to capture all file-namespace paths,
+ *   and then mimics esbuild's native loading behavior by guessing the loader it would use,
+ *   and then `fetch`es the content (without invoking esbuild's native loading in the process).
+ *
+ * @module
+*/
+import { escapeLiteralStringForRegex, fileUrlToLocalPath, json_stringify, promiseOutside, resolveAsUrl } from "../deps.js";
+import { guessExtensionLoader_Factory } from "../esbuild/native.js";
+import { INNER_PLUGIN_BUILD } from "../super/typedefs.js";
+/** this plugin replicates esbuild's native path resolution and loading behavior through the plugin api layer.
+ *
+ * > [!note]
+ * > you will probably want to place this as the last plugin, if you don't want it interfering with your other plugins' resolving and loading mechanisms.
+ *
+ * - for resolving paths, the plugin creates a sub-build that is free of any contaminating plugins to get esbuild to resolve the input resource naturally.
+ * - for loading content, the plugin places an `onLoad` hook to capture all file-namespace paths,
+ *   and then mimics esbuild's native loading behavior by guessing the loader it would use,
+ *   and then `fetch`es the content (without invoking esbuild's native loading in the process).
+ *
+ * > _Van_: It was Asche who was supposed to come here, not you, replica.
+ * >
+ * > _Luke_: Even if you refuse to acknowledge me, I am ME! Master... no, Van! Prepare to DIE!
+*/
+export const nativeReplicaPluginSetup = () => {
+    return async (build) => {
+        const user_ext_to_loader_map = build.initialOptions.loader ?? {}, guess_extension_loader = guessExtensionLoader_Factory(user_ext_to_loader_map), 
+        // if super-build is being used, we must extract the original hidden `esbuild` from it, otherwise the native-resolver won't work.
+        base_esbuild = INNER_PLUGIN_BUILD in build
+            ? build[INNER_PLUGIN_BUILD].esbuild
+            : build.esbuild, native_resolver = new EsbuildNativeResolver(base_esbuild, build.initialOptions);
+        build.onEnd(() => native_resolver.stop()); // stop the sub-build from hanging once the main build has concluded.
+        build.onResolve({ filter: /.*/ }, (args) => {
+            const { path, ...rest_args } = args;
+            return native_resolver.resolve(args.path, rest_args);
+        });
+        build.onLoad({ filter: /.*/, namespace: "file" }, async (args) => {
+            const path_url = resolveAsUrl(args.path), with_attr = args.with, loader = guess_extension_loader(path_url, with_attr), resolveDir = fileUrlToLocalPath(new URL("./", path_url)), path = fileUrlToLocalPath(path_url);
+            const response = await fetch(path_url, { method: "GET" });
+            if (!response.ok) {
+                const message = `ERROR: network fetch response for url "${path_url.href}" was not ok (${response.status}). response header:\n${json_stringify(response.headers)}`;
+                return { errors: [{ text: message }] };
+            }
+            const contents = await response.bytes();
+            // to mimic esbuild's native loader behavior, we don't pass the `args.pluginData` (even though, I'd like pass it).
+            // TODO: though, what if I were to pass it over? how bad would it be? will it realistically affect any existing popular plugin?
+            return { contents, loader, resolveDir, watchFiles: [path] };
+        });
+    };
+};
+/** {@inheritDoc nativeReplicaPluginSetup} */
+export const nativeReplicaPlugin = () => {
+    return {
+        name: "oazmi-superbuild-native_loader-plugin",
+        setup: nativeReplicaPluginSetup(),
+    };
+};
+/** this class provides {@link resolve} method that is capable of resolving paths using esbuild's node-resolution scanner.
+ *
+ * it works by invoking esbuild's `PluginBuild.resolve` function whenever the {@link resolve} method is called,
+ * and it holds an `onLoad` hook hostage by hanging forever,
+ * so that the internal sub-build does not conclude until the {@link stop} method has been called.
+*/
+export class EsbuildNativeResolver {
+    entryPoint = "<the-unloadable-void>";
+    namespace = "the-void";
+    startBuildPromise;
+    startBuildResolve;
+    stopBuildPromise;
+    stopBuildResolve;
+    #internal_resolve;
+    #build_result;
+    constructor(base_esbuild, build_options) {
+        [this.startBuildPromise, this.startBuildResolve] = promiseOutside();
+        [this.stopBuildPromise, this.stopBuildResolve] = promiseOutside();
+        build_options = this.initOptions(build_options);
+        build_options.plugins = [this.initPlugin()];
+        this.#build_result = base_esbuild.build(build_options);
+    }
+    async resolve(path, options) {
+        await this.startBuildPromise;
+        return this.#internal_resolve(path, options);
+    }
+    async stop() {
+        this.stopBuildResolve();
+        await this.#build_result;
+    }
+    initOptions(build_options = {}) {
+        const { absWorkingDir, alias, conditions, external, mainFields, nodePaths, packages, platform, resolveExtensions, tsconfig, tsconfigRaw, } = build_options;
+        const entrypoint = this.entryPoint;
+        return {
+            absWorkingDir, alias, conditions, external,
+            mainFields, nodePaths, packages, platform,
+            resolveExtensions, tsconfig, tsconfigRaw,
+            bundle: false, minify: false, write: false,
+            outdir: "./temp/", entryPoints: [entrypoint],
+        };
+    }
+    initPlugin() {
+        const self = this;
+        const setup_fn = (build) => {
+            const entrypoint = self.entryPoint, filter = RegExp(escapeLiteralStringForRegex(entrypoint) + "$"), namespace = self.namespace;
+            build.onResolve({ filter }, async (args) => {
+                return { path: entrypoint, namespace };
+            });
+            build.onLoad({ filter, namespace }, async (args) => {
+                self.startBuildResolve();
+                self.#internal_resolve = (path, args) => {
+                    return build.resolve(path, { kind: "entry-point", resolveDir: "./", ...args });
+                };
+                await self.stopBuildPromise;
+                return { contents: "", loader: "empty" };
+            });
+        };
+        return {
+            name: "native-esbuild-resolver-capture",
+            setup: setup_fn,
+        };
+    }
+}