@oazmi/superbuild 0.1.0

package/esm/super/plugin_build.js

@@ -0,0 +1,198 @@
+/** 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 { array_isEmpty, isNull, isRecord, pathToPosixPath } from "../deps.js";
+import { concatArrays } from "../funcdefs.js";
+import { SuperBuild } from "./build.js";
+import { INNER_PLUGIN_BUILD } from "./typedefs.js";
+/** holds the original user/plugin-provided `OnResolveArgs.pluginData` when the {@link SuperPluginBuild.resolve} method is invoked by some plugin.
+ *
+ * its presence signifies if the caller of the `onResolve` methods is actually `build.resolve(...)`,
+ * in order to hint that the resolved path should neither be cached, nor should the file counter be incremented,
+ * as there is no direct "resource loading" that will occur as a consequence of this path resolution.
+*/
+const ORIGINAL_PLUGINDATA = Symbol();
+/** in the context of {@link ORIGINAL_PLUGINDATA}, this symbol indicates that a plugin data does not exist inside the `options` passed to {@link SuperPluginBuild.resolve}. */
+const ORIGINAL_PLUGINDATA_DNE = Symbol();
+const wrap_resolve_call_options = (options = {}) => {
+    const original_plugindata = ("pluginData" in options) ? options.pluginData : ORIGINAL_PLUGINDATA_DNE, wrapped_options = { ...options, pluginData: { [ORIGINAL_PLUGINDATA]: original_plugindata } };
+    return wrapped_options;
+};
+const unwrap_resolve_call_options = (args) => {
+    const original_plugindata = args.pluginData[ORIGINAL_PLUGINDATA], unwrapped_args = { ...args, pluginData: original_plugindata };
+    if (original_plugindata === ORIGINAL_PLUGINDATA_DNE) {
+        delete unwrapped_args["pluginData"];
+    }
+    return unwrapped_args;
+};
+const is_wrapped_resolve_call = (args) => { return isRecord(args.pluginData) ? (ORIGINAL_PLUGINDATA in args.pluginData) : false; };
+/** this is the extension of `esbuild.PluginBuild` that introduces additional functionality to esbuild's plugin api. */
+export class SuperPluginBuild {
+    ctx;
+    basePluginBuild;
+    pluginName;
+    initialOptions;
+    esbuild;
+    /** 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.
+    */
+    [INNER_PLUGIN_BUILD];
+    constructor(ctx, base_plugin_build, plugin_name) {
+        this.ctx = ctx;
+        this.basePluginBuild = base_plugin_build;
+        this.pluginName = plugin_name;
+        this.initialOptions = base_plugin_build.initialOptions;
+        // the inner `PluginBuild["esbuild"]` gets replaced by a new `SuperBuild` wrapper.
+        // TODO: we might want to add a "parent" field to `SuperBuild`, so that it can communicate with the parent super-build,
+        // and also `resolve()` with respect to the parent's plugins and `pluginData` context.
+        this.esbuild = new SuperBuild(base_plugin_build.esbuild);
+        this[INNER_PLUGIN_BUILD] = base_plugin_build;
+    }
+    resolve(path, options = {}) {
+        // `SuperPluginBuild.resolve` calls should not influence the long-build plugin's `remainingFilesCounter` at all
+        // (nor should its result get cached by `LongBuildController.cacheResolvedResult(...)`).
+        // however, the `onResolve` hooks have no knowledge of where the path-resolution request comes from;
+        // it could either come directly from esbuild (after traversing the parent resource's imports),
+        // or it could come from a plugin utilizing `build.resolve(...)`.
+        // thus, in order to make `SuperPluginBuild.resolve` calls discoverable, we hijack the `options.pluginData` here,
+        // and keep a copy of the original `pluginData` by using the `wrap_resolve_call_options` function.
+        // then, the overloaded `onResolve` hook will first check to see if the special `options.pluginData[ORIGINAL_PLUGINDATA]` symbol is present:
+        // - if it is, then that will be an indication of `SuperPluginBuild.resolve` being used, in which case we skip caching altogether,
+        //   and also decrement the file counter once to compensate for the default increment performed by the long-build plugin's `onResolve` hook.
+        // - if the symbol is not present, then it will indicate that it is a natural path-resolution request coming from esbuild (i.e. imports traversal).
+        //   in such cases, we carry out our resolved-path cache registration like normal.
+        return this.basePluginBuild.resolve(path, wrap_resolve_call_options(options));
+    }
+    onStart(callback) {
+        return this.basePluginBuild.onStart(callback);
+    }
+    onEnd(callback) {
+        /** the {@link emissionsDriverPlugin | "emissions driver" plugin's} `onEnd` stage performs calling each of the registered callbacks. */
+        this.ctx.onEndHandlers.push({ pluginName: this.pluginName, callback });
+    }
+    onResolve(options, callback) {
+        // NOTE: esbuild's own native resolver never makes it to here because it gets resolved internally, bypassing the plugin api.
+        // hence, our cached resolved check is rendered useless because of it.
+        // however, this is where our `nativeReplicaPlugin` comes in; it mimics esbuild's native node-resolution through the api layer,
+        // and hence all path resolutions get intercepted here by super-build.
+        const long_build_controller = this.ctx.longBuildController;
+        const new_callback = async (args) => {
+            // see the long comment under `SuperPluginBuild.resolve` to understand why we try to detect if the caller of this `onResolve`
+            // hook comes naturally from esbuild, or if it is a plugin that is performing a `build.resolve` call.
+            const is_resolve_call = is_wrapped_resolve_call(args), result = await callback(is_resolve_call ? unwrap_resolve_call_options(args) : args), is_valid_result = !isNull(result?.path) || (result?.external === true);
+            if (is_valid_result) {
+                // if the caller was not esbuild (i.e. a `buildresolve(...)` was performed by a plugin),
+                // then we need only to decrement the file counter to compensate for the initial increment by the long-build plugin's `onResolve` hook.
+                // this is because the result of this path resolution will not directly result in the creation of a new file (i.e. an `onLoad` operation),
+                // nor will this resolved path contribute to any future path resolution in terms of path caching by esbuild.
+                if (is_resolve_call) {
+                    long_build_controller.decrementFilesCounter(result.path);
+                }
+                // but if the caller was esbuild, then the resolved path will get cached and esbuild will entirely skip loading (i.e. `onLoad` operation)
+                // the same file again if the resolved `namespace:path` pair had been encountered before (i.e. resource caching).
+                // thus, the file counter must be decremented immediately if the resolved path had been previously cached (since no loading will occur for it anymore),
+                // or if the resolved path points towards a new file, then the file counter's decrement will occur later after it has passed through its `onLoad` or `onTransform` stage.
+                else {
+                    long_build_controller.cacheResolvedResult(result);
+                }
+            }
+            return result;
+        };
+        return this.basePluginBuild.onResolve(options, new_callback);
+    }
+    onLoad(options, callback) {
+        const resolvedResourceRegistry = this.ctx.resolvedResourceRegistry, onTransformHandlers = this.ctx.onTransformHandlers, long_build_controller = this.ctx.longBuildController;
+        const transform_interceptor_callback = async (args) => {
+            const { namespace, path, suffix, with: with_attrs } = args, onload_result = await callback(args);
+            if (isNull(onload_result?.contents)) {
+                return;
+            }
+            // if any error occurs during the plugin's `onLoad` callback, we shall halt the build altogether by passing esbuild the error early.
+            // also, since generic `loader`s are not permitted by esbuild, so we'll use `as any` to bypass the type error, since the build has failed anyway.
+            if (!array_isEmpty(onload_result.errors ?? [])) {
+                return onload_result;
+            }
+            // TODO: inform the user that when `loader` is set to `undefined`, it will get set to an empty string before being transferred to their `onTransform` hook,
+            // instead of being converted into "js" (which is esbuild's default interpretation).
+            // this is to allow for more flexibility when a user explicitly decides to return a `"js"` loader content vs a more ambiguous empty `""` loader content.
+            const { contents, loader = "", resolveDir = "", pluginData } = onload_result;
+            for (const handler of onTransformHandlers) {
+                const { pluginName: transformerPluginName, filter, namespace: handler_ns, loader: handler_loader } = handler;
+                if (filter.test(path)
+                    && (handler_ns ? (handler_ns === namespace) : true)
+                    && (handler_loader ? handler_loader === loader : true)) {
+                    const { imports = [], emitData, ...transform_result } = await handler.callback({
+                        contents: contents,
+                        loader, namespace, path, pluginData, resolveDir, suffix, with: with_attrs,
+                    }) ?? {};
+                    // if the transformation did not generate any result (i.e. void) or generated no `content`, then we shall move to testing the next transformation handler.
+                    if (isNull(transform_result.contents)) {
+                        continue;
+                    }
+                    // there is no possibility of an error from the `onLoad` hook to be introduced, since we've already ruled it out before the loop.
+                    // transform_result.errors = concatArrays(transform_result.errors, onload_result.errors)
+                    transform_result.warnings = concatArrays(transform_result.warnings, onload_result.warnings);
+                    transform_result.watchDirs = concatArrays(transform_result.watchDirs, onload_result.watchDirs);
+                    transform_result.watchFiles = concatArrays(transform_result.watchDirs, onload_result.watchFiles);
+                    transform_result.pluginName ??= transformerPluginName;
+                    // NOTE: the plugin writer must ensure that their import paths are pre-resolved (not relative, nor contextually dependent).
+                    if (imports.length > 0) {
+                        const importer_path = namespace === "file" ? pathToPosixPath(path) : path, importer_key = namespace + ":" + importer_path;
+                        long_build_controller.steps.at(-1).pushImports(importer_key, imports);
+                    }
+                    return [
+                        transform_result,
+                        { loader, transformLoader: transform_result.loader ?? "", emitData },
+                    ];
+                }
+            }
+            // at this point, we've already tried all available transformation handlers, but none produced a viable result,
+            // hence we shall return the original result directly to esbuild.
+            return [
+                onload_result,
+                { emitData: undefined, loader: loader, transformLoader: loader },
+            ];
+        };
+        const resource_registry_interceptor_callback = async (args) => {
+            const [result, additional_info] = await transform_interceptor_callback(args) ?? [];
+            if (!isNull(result)) {
+                const { path: _path, namespace: _namespace, suffix, with: with_attrs } = args, { emitData, loader, transformLoader } = additional_info, path = pathToPosixPath(_path), namespace = _namespace ? _namespace : "file", key = namespace + ":" + path, contributing_emit_file = { path, namespace, suffix, loader, transformLoader, emitData };
+                resolvedResourceRegistry.set(key, contributing_emit_file);
+            }
+            return result;
+        };
+        const long_build_interceptor_callback = async (args) => {
+            const result = await resource_registry_interceptor_callback(args);
+            // every loaded result indicates that a file has gone out of circulation,
+            // and hence we must decrement the `remainingFilesCounter` of the long-build plugin.
+            if (!isNull(result)) {
+                long_build_controller.decrementFilesCounter(args.path);
+            }
+            // TODO: our `nativeReplicaPlugin` is expected to load everything that is left uncaptured/unloaded.
+            // yet, if something comes its way (i.e. the final loader) but fails to get loaded with a valid `result`,
+            // then our plugin should throw a warning to indicate that either something is wrong with our
+            // `nativeReplicaPlugin` itself, or if the input resolved path may be incorrect.
+            return result;
+        };
+        return this.basePluginBuild.onLoad(options, long_build_interceptor_callback);
+    }
+    onDispose(callback) {
+        return this.basePluginBuild.onDispose(callback);
+    }
+    /** TODO: add documentation and usage examples. */
+    onTransform(options, callback) {
+        const { filter, namespace, loader } = options;
+        this.ctx.onTransformHandlers.push({ pluginName: this.pluginName, filter, namespace, loader, callback });
+    }
+    /** TODO: add documentation and usage examples. */
+    onEmit(options, callback) {
+        const { filter, inputs } = options;
+        this.ctx.onEmitHandlers.push({ pluginName: this.pluginName, filter, inputs, callback });
+    }
+}

package/esm/super/typedefs.d.ts

@@ -0,0 +1,323 @@
+/** this module contains type definitions for super-build's extended plugin api.
+ *
+ * @module
+*/
+import type { AutoSuggestOrString, MaybePromiseOrNull } from "../deps.js";
+import type { EsbuildLoaderType, EsbuildOnEndResult, OnLoadArgs as EsbuildOnLoadArgs, OnLoadOptions as EsbuildOnLoadOptions, OnLoadResult as EsbuildOnLoadResult, EsbuildOutputsImportKind, EsbuildPartialMessage } from "../esbuild/strongtypes.js";
+import type { AbsolutePath, Path, RelativePath, ResolvedPath } from "../typedefs.js";
+/** this symbol gives you access to the **true** internal `PluginBuild` object that was used for constructing a {@link SuperPluginBuild}.
+ * it can be used as a means to check whether you're inside super-build or not,
+ * or if you have a situation where it is necessary for super-build to be bypassed,
+ * such as in the case of {@link EsbuildNativeResolver}, which is spawned by {@link nativeReplicaPluginSetup}.
+*/
+export declare const INNER_PLUGIN_BUILD: unique symbol;
+/** type alias for `esbuild.OnLoadOptions`. */
+export type OnLoadOptions = EsbuildOnLoadOptions;
+/** type alias for `esbuild.OnLoadArgs`, slightly tweaked for this library's internal use. */
+export type OnLoadArgs = EsbuildOnLoadArgs;
+/** type alias for `esbuild.OnLoadResult`, except that the `loader` can be set to anything arbitrary. */
+export type OnLoadResult = Omit<EsbuildOnLoadResult, "loader"> & {
+    loader?: AutoSuggestOrString<EsbuildLoaderType>;
+};
+/** type alias for the callback function provided to the `OnLoad` function (aka `esbuild.PluginBuild["OnLoad"]`). */
+export type OnLoadCallback = (args: OnLoadArgs) => MaybePromiseOrNull<OnLoadResult>;
+export interface OnTransformOptions {
+    filter: RegExp;
+    namespace?: string;
+    loader?: AutoSuggestOrString<EsbuildLoaderType>;
+}
+export interface OnTransformArgs {
+    /** the resolved path of the {@link contents}. */
+    path: ResolvedPath;
+    /** the namespace inherited from the `onLoad` hook (which gets inherited from the `onResolve` hook). */
+    namespace: string;
+    /** the loader that is supposed to be used for this {@link contents} for the transformation. */
+    loader: AutoSuggestOrString<EsbuildLoaderType>;
+    /** any url-suffix string that is present in the {@link path}. */
+    suffix: string;
+    /** the loaded content that is to be transformed. */
+    contents: string | Uint8Array<ArrayBuffer>;
+    /** the plugin data returned by the `onLoad` hook.
+     *
+     * > [!important]
+     * > esbuild strips away any plugin-data when it resolves/loads natively.
+     * > hence, in order to preserve it during native loading,
+     * > we might have to instill a `"file"` namespace loader that will capture all native loading cases,
+     * > and then perform the loading ourselves, followed by preserving the plugin-data.
+     * >
+     * > TODO: actually, right now, I'm intentionally stripping away the `pluginData` in my "native loader".
+     * > I'll have to see how much of an inconvenience it becomes before I give in to preserving the plugin-data.
+     * > otherwise, if I can manage to write plugins without needing this feature, then there's no reason to add it.
+    */
+    pluginData: any;
+    /** the `resolveDir` (used for node-resolution) returned by the loader.
+     *
+     * > [!note]
+     * > when the `onLoad` hook function returns an empty/undefined `resolveDir`, this value turns into an empty string.
+    */
+    resolveDir: string;
+    /** the `with` attribute argument passed to the `onLoad` hook. */
+    with: Record<string, string>;
+}
+export interface OnTransformResult {
+    /** insert your plugin's name to override the current plugin name that will be used for error printing. */
+    pluginName?: string;
+    /** the transformed/transpiled contents that will be returned to esbuild. */
+    contents?: string | Uint8Array<ArrayBuffer>;
+    /** if the {@link contents} needs to be transformed/minified natively by esbuild again
+     * (in addition to discovering additional imports), use one of the native loaders provided by esbuild.
+    */
+    loader?: EsbuildLoaderType;
+    /** insert plugin-data to be passed onto the dependencies' `onResolve` hook's `arg.pluginData`.
+     *
+     * if you wish to pass on the incoming {@link OnTransformArgs.pluginData} from the prior `onLoad` hook,
+     * you will need to explicitly pass it over as a return argument, otherwise the plugin-data will get lost.
+     * so, keep this in mind when designing transformation hooks, because you wouldn't want to ruin any plugin-data that some plugin was anticipating.
+    */
+    pluginData?: any;
+    /** pass some arbitrary data from the transformation stage to the emit stage.
+     *
+     * this feature is handled by {@link SuperBuildContext.resolvedResourceRegistry}.
+    */
+    emitData?: any;
+    /** specify arbitrary resource imports that must be performed for this resource.
+     *
+     * while these resources will get bundled (via dynamic imports performed by {@link longBuildPluginSetup}, so long as they are not marked with `external: true`),
+     * they (i.e. their output paths) won't get automatically incorporated into your {@link contents};
+     * for that, you will have to use an {@link SuperPluginBuild.onEmit} hook to re-capture the output paths of the bundled imports specified here,
+     * and then re-incorporate those output paths into your {@link OnEmitArgs.contents},
+     * using the non-mutating {@link ImportEntity.key} trace which resource is being referenced by the {@link ImportedEntity.outputPath}.
+     *
+     * to skip an import from being bundled, you can either stay silent about it (i.e. not include it here),
+     * or mark that import with `external: true`, so that it still gets passed to {@link OnEmitArgs.imports},
+     * but will appear to esbuild as an external reference (and hence not resolved, nor bundled as an emitted output file).
+    */
+    imports?: ImportEntity[];
+    /** if any fatal error(s) occur during the transformation, pass it as a return value so that the build gets immediately halted. */
+    errors?: EsbuildPartialMessage[];
+    /** if any warning(s) occur during the transformation, pass it as a return value so that esbuild prints out a warning immediately. */
+    warnings?: EsbuildPartialMessage[];
+    /** add a list of local files to watch for mutation in order to trigger a reload of the original loader hook.
+     * (I think the paths need to be an absolute path.)
+     *
+     * any files added to this array will be combined with the {@link OnLoadResult.watchFiles} list of the prior `onLoad` hook function.
+    */
+    watchFiles?: string[];
+    /** add a list of directories to watch for mutation in order to trigger a reload.
+     * (I think the paths need to be an absolute path.)
+     *
+     * any directories added to this array will be combined with the {@link OnLoadResult.watchDirs} list of the prior `onLoad` hook function.
+    */
+    watchDirs?: string[];
+}
+/** this is your `onTransform` hook function that gets called,
+ * if the handler associated with it allows a certain result from an `onLoad` hook to pass through its filter ({@link OnTransformOptions}).
+ *
+ * if your return value is nullable (`null` or `undefined`), then the next matching `onTransform` hook function will try to transform the incoming loaded contents.
+ * if no transformation hook returns a non-nullable after all matches have been made,
+ * then the loaded contents from the `onLoad` hook will be passed to esbuild as is.
+*/
+export type OnTransformCallback = (args: OnTransformArgs) => MaybePromiseOrNull<OnTransformResult>;
+/** specify an entity/file that should be imported for a given loaded entity (during the transformation stage). */
+export interface ImportEntity<K = any> {
+    /** include a unique key that you can use to trace back the imported entity,
+     * because the `path` of the import in the bundled output will differ, whereas this key will remain the same.
+    */
+    key: K;
+    /** the **absolute/resolved** path of the resource.
+     *
+     * do not insert unresolved or relative paths!
+     * this is a strict design choice because you should ideally run a sub-build to acquire the resolved paths of your dependencies.
+     * of course, nothing is stopping your `onTransform` hook from either:
+     * - using the `build.resolve` of the sub-build's parent `PluginBuild` (thereby not requiring re-instantiation of the plugins).
+     * - re-instantiating the plugins in the sub-build, so that the path-resolution logic remains similar. although, this can have drawbacks;
+     *   for instance, my `esbuild-plugin-deno`'s `setup` method is _generated_ based on the user's initial config
+     *   (containing contextual information, such as the location of `deno.json`), which may not be desired in the sub-build
+     *   (if for instance, the thing being resolved for the sub-build is actually inside a different package/scope than the primary package).
+     *
+     * because there is a variablility in how you can potentially approach path resolution,
+     * we leave it up to the plugin designer to decide how they would want to resolve the paths in their `onTransform` hook's returned imports,
+     * rather than performing a default action ourselves.
+    */
+    path: AbsolutePath | ResolvedPath;
+    /** associate a `with` import attribute to the import. */
+    with?: Record<string, string>;
+    /** specify if this import should be marked as an external resource, so that it neither gets resolved, nor loaded/bundled as an output file.
+     *
+     * if you wish for your import's path to get resolved, but not loaded/bundled as a file, then you should either:
+     * 1. set `external: false` and then capture {@link path} during the `onResolve` stage,
+     *    followed by setting `external` to `true` in the returned `OnResolveResult`.
+     * 2. set `external: true` and make sure that your {@link path} is pre-resolved within the transformation stage,
+     *    by simply using {@link SuperPluginBuild.resolve | `build.resolve(...)`} to resolve its path in your plugin.
+    */
+    external?: boolean;
+}
+export type ImportedEntityKind = EsbuildOutputsImportKind | "user-import";
+/** a description of an entity that is imported by an output file (post-build, during the emission stage).
+ *
+ * - for user-specified `imports` performed in the transformation stage ({@link OnTransformResult}), the {@link key} will be supplied by the user,
+ *   and it will be up to the user to trace back the original linked resource that was being referenced.
+ * - for imports performed by esbuild (such as js and css imports), the {@link key} will be an array of namespaced resolved paths
+ *   (of the form `${namespace}:${resolved_path}`) that contributed to the creation of the imported (and possibly bundled) resource.
+ *
+ * TODO: the currently include `with` import attribute is defunct. should it have any built-in purpose,
+ * or should it be just left up to the user to decide what to do with that information?
+*/
+export interface ImportedEntity<K = any> extends Pick<NonNullable<ImportEntity<K>>, "key" | "with"> {
+    /** the **absolute** output path of the resource/entity that is being imported.
+     *
+     * to convert it to a relative path with respect to the entity that imports this resource,
+     * use the `relativePath` function from my `jsr:@oazmi/kitchensink/pathman` or `npm:@oazmi/kitchensink/pathman` libraries.
+    */
+    outputPath: AbsolutePath;
+    /** if the imported entity was renamed during the {@link SuperPluginBuild.onEmit, emission stage},
+     * then its original (absolute) {@link outputPath} will get saved here.
+     *
+     * this is to aid you with modifying/renaming import paths within your dependent entity's {@link OnEmitArgs.contents},
+     * when you cannot reliably use your {@link key} to identify the import statement corresponding to an imported entity.
+     *
+     * for instance, suppose your build emits a `./main.js` file that imports `./meow.worker.js`,
+     * and then during the emission stage, suppose you renamed the `./meow.worker.js` output file to `./workers/meow.js`.
+     * then, when `./main.js` enters the {@link SuperPluginBuild.onEmit | emission phase},
+     * the {@link OnEmitArgs.imports | import field} corresponding to the `./workers/meow.js` file (formerly `./meow.worker.js`)
+     * will have its {@link outputPath} set to `./workers/meow.js` (but as an absolute path),
+     * while its {@link initialPath} will get assigned `./meow.worker.js` (again, as an absolute path),
+     * so that you can scan the {@link OnEmitArgs.contents} of your `./main.js` file to find all references to `./meow.worker.js`,
+     * and then replace those statements with the updated `./workers/meow.js` path.
+     *
+     * > [!note]
+     * > this field is only assigned when the {@link OnEmitResult | emission stage result} of the dependency import changes the
+     * > {@link OnEmitResult.path} to something different from the original (case sensitive).
+    */
+    initialPath?: AbsolutePath;
+    /** indicates the kind of import that is being performed. all of these are inherited from esbuild metafile's
+     * {@link EsbuildMetafileImportProps.kind | `kind` field}, with the exception of `"user-import"`,
+     * which is assigned when the user specifies an import during the transformation stage ({@link OnTransformResult}).
+    */
+    kind: ImportedEntityKind;
+    /** indicates if this imported entity is an external resource (and hence not bundled). */
+    external: boolean;
+    /** this flag indicates if the imported file entity is being written at all into the filesystem (supposing that the `EsbuildBuildOptions.write` was not disabled).
+     *
+     * in general, this flag is set to `false` for entities with {@link external} set to `true`.
+     * but for non-external imported entities, when this flag is set to `false`,
+     * it can hint to the importer entity that they should probably remove the import statement associated with this import,
+     * in order not to get any runtime-import exceptions. or perhaps,
+     * it can hint that the imported entity should have its contents inlined into the importer, such as in the case of html's inline js and css.
+     * (TODO: currently, importers cannot read the `contents` of the imported entity, so this feature needs to be implemented).
+    */
+    write: boolean;
+}
+/** a single input file filteration rule used in {@link OnEmitOptions}. */
+export interface OnEmitOptions_InputFilter {
+    /** a resolved path name filter of the input resource that is to be matched by at least one of the emitted file's {@link OnEmitArgs.inputs | inputs}. */
+    filter: RegExp;
+    /** specify an optional namespace in which the loaded input file must be part of. */
+    namespace?: string;
+    /** specify an optional loader which should have been used to load this input file by the {@link SuperPluginBuild.onLoad} hook. */
+    loader?: AutoSuggestOrString<EsbuildLoaderType>;
+    /** specify an optional transform-loader which should have been used to load this input file during the transformation hook ({@link SuperPluginBuild.onTransform}).
+     * if no {@link SuperPluginBuild.onTransform} hook captured this input resource,
+     * then the `loader` value from the prior {@link SuperPluginBuild.onLoad} stage will be used to match against this option.
+    */
+    transformLoader?: EsbuildLoaderType;
+}
+export interface OnEmitOptions {
+    /** a filter for the {@link OnEmitArgs.outputPath | output filename} of a file that is to be emitted. */
+    filter: RegExp;
+    /** a filter for specifying which input resources should be part of what constitutes this output file.
+     *
+     * for instance, if one were to bundle entrypoints `A` and `B`, and `A` depended on `X` and `Y`, while `B` depended on `Y` and `Z`,
+     * then the emitted bundled file corresponding to entrypoint `A` will have all three `A`, `X`, and `Y` show up in its `inputs` array.
+     * similarly, the emitted bundled file corresponding to entrypoint `B` will have all three `B`, `Y`, and `Z` show up in its `inputs` array.
+     *
+     * when multiple input filters are specified, they (the filters) will all need to be satisfied simultaneously (logical AND)
+     * by the list of available {@link OnEmitArgs.inputs} of the emitted resource. for instance, for the scenario mentioned prior:
+     * - if `inputs = [{ filter: /A/ }, { filter: /Y/ }]`,
+     *   then the emitted file corresponding to entrypoint `A` will be matched, but not `B` (since it has no input with the name `A`).
+     * - if `inputs = [{ filter: /Y/ }]`,
+     *   then the emitted files corresponding to both entrypoints `A` and `B` will be matched (since they both incorporate the dependency file `Y`).
+     * - if `inputs = [{ filter: /Y/ }, { filter: /Z/ }]`,
+     *   then only the emitted file corresponding to entrypoint `B` will be matched, and not `A` (since `A` does not incorporate the dependency file `Z`).
+    */
+    inputs?: Array<OnEmitOptions_InputFilter>;
+}
+/** a description of an input file that was bundled into a physical output file ({@link OnEmitArgs}). */
+export interface BundledInputFile {
+    /** the original (absolute) resolved path (return value of the `onResolve` hook) of this bundled resource. */
+    path: ResolvedPath;
+    /** the namespace inherited from the `onTransform` hook
+     * (which gets inherited from the `onLoad` hook, and the `onResolve` hook prior to it).
+    */
+    namespace: string;
+    /** the `onLoad` loader that was used for this resource. equivalent to {@link OnEmitOptions.loader}. */
+    loader: string;
+    /** the `onTransform` loader that was used for this resource during its transformation stage.
+     * if the resource did not go through a transformation stage, then this value will be the same as {@link loader}.
+     * moreover, this value is equivalent to the {@link OnEmitOptions.transformLoader} provided in the filteration options.
+    */
+    transformLoader: NonNullable<OnTransformResult["loader"]> | "";
+    /** any url-suffix string that might present in the {@link path | resolved path}. */
+    suffix: string;
+    /** arbitrary data passed from the {@link OnTransformResult.emitData | transformation stage} to the emit stage. */
+    emitData: NonNullable<OnTransformResult["emitData"]>;
+}
+export interface OnEmitArgs {
+    /** the output path of this bundled resource, relative to the `cwd` or `absWorkingDir`
+     * (not the `outdir` directory!), and always in posix format.
+     *
+     * TODO: I actually don't provide a relative path right now. but should I even?
+    */
+    outputPath: RelativePath;
+    /** a list of input resources that were bundled into this resource (by esbuild), or were chunked by esbuild for this resource. */
+    inputs: Array<BundledInputFile>;
+    /** a list of resource imports that were included in the build for this resource.
+     * these, however, are not currently _bundled_ into the contents of your resource;
+     * they're still external resources that your transformed file will need to reference (re-incorporate) in order to import during runtime.
+    */
+    imports: Array<ImportedEntity>;
+    /** the transformed and/or bundled content that may need to have the linked {@link imports} re-incorporated into it. */
+    contents: Uint8Array<ArrayBuffer>;
+}
+export interface OnEmitResult extends EsbuildOnEndResult {
+    /** provide an alternate path to place this resource.
+     *
+     * if a relative path is provided (which is what is recommended),
+     * then this file will be placed relative to the `cwd` or `absWorkingDir` specified in the initial build options,
+     * which is different from the `outdir`. for providing paths relative to `outdir`, use an absolute path.
+     *
+     * TODO: in the future, consider adding a `pathRelativeTo` option, with the symbols `OUTDIR`, `CWD`, and `ABS_WORKING_DIR`,
+     * for specifying what is the `path` relative to.
+    */
+    path?: Path;
+    /** the contents of the file after you've re-incorporated the imported/dependency links into it.
+     * if left `undefined`, then the original {@link OnEmitArgs.contents} will be used as its value.
+    */
+    contents?: string | Uint8Array<ArrayBuffer>;
+    /** specify if the file should be written (i.e. emitted) at all.
+     *
+     * > [!note]
+     * > note that it is totally possible to delete an entity, but still have some {@link contents} assigned to it.
+     * > this way, you should be able to read the contents of the "deleted" file later on inside on of the dependent entities.
+     * >
+     * > this can be useful when you would like to code a plugin that takes in inlined code (such as inlined js or css inside an html),
+     * > then includes it in the bundle (by faking it as virtual files during resolutions/loading),
+     * > and then deletes the emitted files corresponding to the inlined code blocks, while retaining the minified/bundled {@link contents},
+     * > so that the original dependent entity (html file in this case) can read the minified/bundled {@link contents} and then re-incorporate them as inlined code.
+     * >
+     * > (TODO: though, right now, I don't currently give a global readonly access to the output files registry inside the {@link OnEmitCallback} function.
+     * > I should probably add the registry as a second argument to the callback function.)
+     *
+     * @defaultValue `true` (i.e. it'll be written if `EsbuildBuildOption.write` is enabled, otherwise it won't be.)
+    */
+    write?: boolean;
+}
+/** this is your `onEmit` hook function that gets called,
+ * if the handler associated with it allows a certain result from an `onLoad` hook to pass through its filter ({@link OnEmitOptions}).
+ *
+ * if your return value is nullable (`null` or `undefined`), then the next matching `onEmit` hook function will try to mutate the finalized loaded/transformed contents.
+ * if no emit hook returns a non-nullable after all matches have been made,
+ * then the transformed contents from the `onTransform` hook will be passed to esbuild as is.
+*/
+export type OnEmitCallback = (args: OnEmitArgs) => MaybePromiseOrNull<OnEmitResult>;
+//# sourceMappingURL=typedefs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"typedefs.d.ts","sourceRoot":"","sources":["../../src/super/typedefs.ts"],"names":[],"mappings":"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"}

package/esm/super/typedefs.js

@@ -0,0 +1,10 @@
+/** this module contains type definitions for super-build's extended plugin api.
+ *
+ * @module
+*/
+/** this symbol gives you access to the **true** internal `PluginBuild` object that was used for constructing a {@link SuperPluginBuild}.
+ * it can be used as a means to check whether you're inside super-build or not,
+ * or if you have a situation where it is necessary for super-build to be bypassed,
+ * such as in the case of {@link EsbuildNativeResolver}, which is spawned by {@link nativeReplicaPluginSetup}.
+*/
+export const INNER_PLUGIN_BUILD = Symbol();

package/esm/typedefs.d.ts

@@ -0,0 +1,21 @@
+/** this module contains base type definitions.
+ *
+ * @module
+*/
+/** type annotation for a relative path. */
+export type RelativePath = string;
+/** type annotation for an absolute path. */
+export type AbsolutePath = string;
+/** type annotation for a resolved path (that originates from the path resolver stage).
+ * it could either be an absolute path or an external absolute path.
+*/
+export type ResolvedPath = string;
+/** type annotation for a namespaced resolved path of the form `${namespace}:${resolved_path}`, all in lowercasing.
+ * this is often used as a key for various `Map`s to identify resources and references to resources.
+*/
+export type NamespacedPath = string;
+/** type annotation for any kind path. */
+export type Path = RelativePath | AbsolutePath;
+/** a logging function that can be used as an alternative to the default `console.log` logger function. */
+export type LoggerFunction = (...data: any[]) => void;
+//# sourceMappingURL=typedefs.d.ts.map

package/esm/typedefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typedefs.d.ts","sourceRoot":"","sources":["../src/typedefs.ts"],"names":[],"mappings":"AAAA;;;EAGE;AAGF,2CAA2C;AAC3C,MAAM,MAAM,YAAY,GAAG,MAAM,CAAA;AAEjC,4CAA4C;AAC5C,MAAM,MAAM,YAAY,GAAG,MAAM,CAAA;AAEjC;;EAEE;AACF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAA;AAEjC;;EAEE;AACF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAA;AAEnC,yCAAyC;AACzC,MAAM,MAAM,IAAI,GAAG,YAAY,GAAG,YAAY,CAAA;AAE9C,0GAA0G;AAC1G,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA"}

package/esm/typedefs.js

@@ -0,0 +1,5 @@
+/** this module contains base type definitions.
+ *
+ * @module
+*/
+export {};

package/license.md

@@ -0,0 +1,37 @@
+# Apache License, Version 2.0 (Modified)
+
+Copyright [2026] [Omar Azmi]
+
+This project is licensed under the Apache License, Version 2.0, with additional terms and restrictions.
+You may not use or view any file under this project except in compliance with this license.
+You may obtain a copy of the Apache License Version 2.0 at:
+
+> http://www.apache.org/licenses/LICENSE-2.0
+
+## Additional Terms and Restrictions
+
+Redistribution and use of this project, or any artifacts generated by it, in source or binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the disclaimer that follows.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the disclaimer that follows, in its documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+4. The software may be used in open source and closed source projects.
+   If used in a closed source project, the project must provide attribution to this software.
+
+5. Distributions of this software or its specifications in any form must not be used in the development, training, or operation of an Artificial Intelligence system.
+
+6. The software or its derivatives must not be used in any form of crawling or caching that is not directly related to code archiving.
+
+7. No portion of this software or its specifications may be copied or used in another codebase without proper attribution to the original work.
+
+8. Derivative works that directly compete with the original software are not permitted.
+   Major enhancements or modifications should ideally be contributed back to the original software's development.
+   This is to prevent the intent of diverting existing or potential users away from the original work.
+
+9. Redistribution for the sole purpose of competing with the original software is not permitted.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.