@oazmi/superbuild 0.1.0

package/esm/esbuild/metafile.js

@@ -0,0 +1,275 @@
+/** utility submodule for converting esbuild's metafile and output file interfaces into more convenient and manageable format.
+ *
+ * @module
+*/
+import { ensureFile, ensureRelativeDotSlash, identifyCurrentRuntime, isAbsolutePath, object_entries, object_fromEntries, object_keys, pathToPosixPath, statEntry, writeFile } from "../deps.js";
+import { splitNamespacedPath } from "../funcdefs.js";
+import { OutputFileEntity } from "./outputfile.js";
+// regex for detecting if a path is an absolute windows path. copied from `@oazmi/kitchensink/pathman`.
+const windows_absolute_path_regex = /^[a-z]\:[\/\\]/i;
+/** normalize an esbuild resolved file path so that it:
+ * - uses posix `"/"` directory separators.
+ * - always has a leading `"./"` for relative paths.
+ * - is always in the `${namespace}:${path}` format, even when `namespace === "file".`
+*/
+const normalize_esbuild_filepath = (path) => {
+    const is_local_path = !path.includes(":") || windows_absolute_path_regex.test(path);
+    return is_local_path
+        ? "file:" + normalize_local_filepath(path)
+        : path;
+};
+const normalize_local_filepath = (path) => {
+    const is_abs_path = isAbsolutePath(path);
+    return pathToPosixPath(is_abs_path ? path : ensureRelativeDotSlash(path));
+};
+const file_namespace = "file:", file_namespace_length = file_namespace.length;
+const namespaced_path_to_abs_namespaced_path_factory = (resolve_path_fn) => {
+    return (namespaced_path) => {
+        if (!namespaced_path.startsWith(file_namespace)) {
+            return namespaced_path;
+        }
+        const abs_path = resolve_path_fn(namespaced_path.slice(file_namespace_length));
+        return file_namespace + abs_path;
+    };
+};
+export class Metafile {
+    value;
+    inputs;
+    outputs;
+    outputFileEntities = new Map();
+    /** a copy of the {@link SuperBuildContext.resolvedResourceRegistry}, where all keys use lower case characters.
+     * this is extremely important, as we've internally standardized to using only lower casing for namespaced resolved paths,
+     * in order to evade the filesystem case-insesnsitivity problem when matching strings.
+    */
+    resolvedResourceRegistry;
+    /** a function that resolves the given path segment to an absolute path, with respect to `cwd` or `absWorkingDir`. */
+    resolvePath;
+    /** holds all warnings that have occurred during method calls. */
+    warnings = [];
+    constructor(esbuild_metafile, config) {
+        const { resolvedResourceRegistry, resolvePath } = config;
+        esbuild_metafile = Metafile.asNormalized(esbuild_metafile);
+        esbuild_metafile = Metafile.asAbsolute(esbuild_metafile, { resolvePath: resolvePath });
+        esbuild_metafile = Metafile.asLowercased(esbuild_metafile, {
+            namespacedPaths: true,
+            outputPaths: true,
+            externalPaths: false,
+        });
+        const { result: registry_lowercase, warnings } = format_resolved_resource_registry(resolvedResourceRegistry);
+        this.value = esbuild_metafile;
+        this.resolvedResourceRegistry = registry_lowercase;
+        this.resolvePath = resolvePath;
+        this.inputs = new Map(object_entries(this.value.inputs));
+        this.outputs = new Map(object_entries(this.value.outputs).map(([output_path_lowercase, props]) => {
+            return [output_path_lowercase, {
+                    entryPoint: props.entryPoint,
+                    inputs: object_keys(props.inputs),
+                    imports: props.imports.map(({ path, kind, external = false }) => ({ path, kind, external })),
+                }];
+        }));
+        this.warnings.push(...warnings);
+    }
+    addFile(esbuild_file) {
+        const file_entity = new OutputFileEntity(this, esbuild_file), output_path_lowercase = (file_entity.initialPath ?? file_entity.outputPath).toLowerCase();
+        this.outputFileEntities.set(output_path_lowercase, file_entity);
+        return file_entity;
+    }
+    /** this function is intended to run _after_ you have added **all** of your {@link EsbuildOutputFile | esbuild output files} via {@link addFile}.
+     * what it does is that it simply calls the {@link OutputFileEntity.scanEsbuildImports} method of each {@link outputFileEntities | registered file},
+     * so that they can discover the file entity associated which each of their esbuild-based imports.
+    */
+    scanEsbuildImports() {
+        this.outputFileEntities.forEach((file_entity) => {
+            file_entity.scanEsbuildImports();
+        });
+    }
+    /** find the file entity corresponding to the given absolute output path. you won't receive entities associated with external paths/references. */
+    getFile(output_path_key) {
+        output_path_key = output_path_key.toLowerCase();
+        const file_entity = this.outputFileEntities.get(output_path_key);
+        if (file_entity) {
+            return file_entity;
+        }
+        this.warnings.push({ text: `[Metafile.getFile]: no file entity with the following path key was ever added: "${output_path_key}".` });
+    }
+    /** find all file entities that incorporate (i.e. originate from) certain namespaced source files/resources into their bundled form. */
+    findFileFromSources(predicate_fn) {
+        const file_entity_matches = [];
+        this.outputFileEntities.forEach((file_entity) => {
+            const file_sources = file_entity.inputs.map(({ namespace, path }) => ({ namespace, path }));
+            if (predicate_fn(file_sources)) {
+                file_entity_matches.push(file_entity);
+            }
+        });
+        return file_entity_matches;
+    }
+    /** prepares a dependency graph from the current list of {@link outputFileEntities}. */
+    createFileDependencyGraph() {
+        const graph = new Map();
+        for (const [output_path_key, entity] of this.outputFileEntities) {
+            const dependencies = entity.imports
+                // external resources do not contribute to dependency graph, as they themselves (the external resources) do not get emitted, nor do they go through the emission stage.
+                .filter((dep_node) => { return !("externalPath" in dep_node.entity); })
+                .map((dep_node) => { return dep_node.entity; });
+            graph.set(entity, new Set(dependencies));
+        }
+        return graph;
+    }
+    /** write all output file entities (those with `entity.write !== false`) to the filesystem. */
+    async writeFiles(allow_overwrite = false) {
+        const current_runtime = identifyCurrentRuntime(), write_file_fn = async (file_path, data) => {
+            // if overwriting is not permitted and an entry already exists at the given `file_path`, then skip writing.
+            if (!allow_overwrite && await statEntry(current_runtime, file_path)) {
+                return;
+            }
+            await ensureFile(current_runtime, file_path);
+            await writeFile(current_runtime, file_path, data);
+        };
+        const promises = [...this.outputFileEntities].map(async ([output_path_key, entity]) => {
+            const is_external_entity = "externalPath" in entity;
+            if (is_external_entity) {
+                return;
+            }
+            return entity.writeFile(write_file_fn);
+        });
+        await Promise.all(promises);
+    }
+    /** normalizes an esbuild metafile to use namespaced paths (`${namespace}:${resolved_path}`) for resolved paths,
+     * and absolute paths for output file paths.
+     *
+     * this function mutates the original metafile object passed to it.
+    */
+    static asNormalized(esbuild_metafile) {
+        const { inputs, outputs } = esbuild_metafile;
+        esbuild_metafile.inputs = object_fromEntries(object_entries(inputs).map(([resolved_path, props]) => {
+            // resolved path name of this input file.
+            resolved_path = normalize_esbuild_filepath(resolved_path);
+            // direct dependencies of this input file as resolved paths.
+            props.imports = props.imports.map((props) => {
+                props.path = normalize_esbuild_filepath(props.path);
+                return props;
+            });
+            return [resolved_path, props];
+        }));
+        esbuild_metafile.outputs = object_fromEntries(object_entries(outputs).map(([output_path, props]) => {
+            // path name of the output file (including the path to the `outdir` relative to the `cwd` or `absWorkingDir`).
+            output_path = normalize_local_filepath(output_path);
+            // list of linked output files that are referenced by this resource (but not bundled into it).
+            // even though the import paths are relative, they are relative to the `cwd` or `absWorkingDir`,
+            // and not relative to the `pathname`.
+            props.imports = props.imports.map((props) => {
+                props.path = normalize_local_filepath(props.path);
+                return props;
+            });
+            // list of files (as resolved paths) that were bundled into this resource.
+            props.inputs = object_fromEntries(object_entries(props.inputs).map(([resolved_path, props]) => {
+                return [normalize_esbuild_filepath(resolved_path), props];
+            }));
+            // entrypoint's resolved path corresponding to this output resource.
+            if (props.entryPoint) {
+                props.entryPoint = normalize_esbuild_filepath(props.entryPoint);
+            }
+            return [output_path, props];
+        }));
+        return esbuild_metafile;
+    }
+    /** lower the casing of an esbuild metafile's namespaced resolved paths,
+     * output file paths, and external paths, based on your `config` configuration.
+     *
+     * lower casing helps in ensuring that there won't be any casing conflicts when searching for a particular resource.
+     *
+     * this function mutates the original metafile object passed to it.
+    */
+    static asLowercased(esbuild_metafile, config) {
+        const { namespacedPaths, outputPaths, externalPaths } = config, { inputs, outputs } = esbuild_metafile;
+        esbuild_metafile.inputs = object_fromEntries(object_entries(inputs).map(([resolved_path, props]) => {
+            if (namespacedPaths) {
+                resolved_path = resolved_path.toLowerCase();
+                props.imports = props.imports.map((props) => {
+                    props.path = props.path.toLowerCase();
+                    return props;
+                });
+            }
+            return [resolved_path, props];
+        }));
+        esbuild_metafile.outputs = object_fromEntries(object_entries(outputs).map(([output_path, props]) => {
+            if (namespacedPaths) {
+                props.inputs = object_fromEntries(object_entries(props.inputs).map(([resolved_path, props]) => {
+                    return [resolved_path.toLowerCase(), props];
+                }));
+                if (props.entryPoint) {
+                    props.entryPoint = props.entryPoint.toLowerCase();
+                }
+            }
+            if (outputPaths) {
+                output_path = output_path.toLowerCase();
+                props.imports = props.imports.map((props) => {
+                    // only lower the casing of non-external paths if `externalPaths` is disabled.
+                    if (externalPaths || !(props.external ?? false)) {
+                        props.path = props.path.toLowerCase();
+                    }
+                    return props;
+                });
+            }
+            return [output_path, props];
+        }));
+        return esbuild_metafile;
+    }
+    /** resolve all relative file paths in a {@link asNormalized | **normalized**} esbuild metafile to absolute file paths.
+     *
+     * this function mutates the original metafile object passed to it.
+    */
+    static asAbsolute(esbuild_metafile, config) {
+        const { resolvePath } = config, namespaced_path_to_abs_namespaced_path = namespaced_path_to_abs_namespaced_path_factory(resolvePath), output_entries = object_entries(esbuild_metafile.outputs);
+        esbuild_metafile.outputs = object_fromEntries(output_entries.map(([output_path, props]) => {
+            output_path = resolvePath(output_path);
+            props.entryPoint = props.entryPoint ? namespaced_path_to_abs_namespaced_path(props.entryPoint) : undefined;
+            props.inputs = object_fromEntries(object_entries(props.inputs).map(([input_path, props]) => {
+                input_path = namespaced_path_to_abs_namespaced_path(input_path);
+                return [input_path, props];
+            }));
+            props.imports = props.imports.map((props) => {
+                // only non-external paths must be resolved to an absolute output local file path.
+                props.path = props.external
+                    ? props.path
+                    : resolvePath(props.path);
+                return props;
+            });
+            return [output_path, props];
+        }));
+        return esbuild_metafile;
+    }
+}
+/** turns all keys of {@link SuperBuildContext.resolvedResourceRegistry} to lower case, while documenting any key conflicts that occur as a result. */
+const format_resolved_resource_registry = (registry) => {
+    const warnings = [], registry_lowercase = new Map([...registry].map(([resolved_path, props]) => {
+        return [resolved_path.toLowerCase(), props];
+    }));
+    if (registry_lowercase.size < registry.size) {
+        const size_difference = registry.size - registry_lowercase.size, conflicting_keys = new Set(), encountered_lowercase_keys = new Map([...registry].map(([key, props]) => {
+            const key_lowercase = key.toLowerCase();
+            return [key_lowercase, key];
+        }));
+        for (const [key, props] of registry) {
+            const key_lowercase = key.toLowerCase(), key_original = encountered_lowercase_keys.get(key_lowercase);
+            if (key_original !== key) {
+                conflicting_keys.add(key);
+                conflicting_keys.add(key_original);
+            }
+        }
+        warnings.push({
+            text: `[format_resolved_resource_registry]: ${size_difference} resolved resources use the same name, but only differ in letter casing. `
+                + `right now, super-build is not able to distinguish between the two (in order to achieve path name casing insensitivity), `
+                + `so this problem will likely mess up your build. `
+                + `if it's possible, you should change the name of the duplicate resources. see the notes for the conflicting resource names:`,
+            notes: [...conflicting_keys].map((resolved_path) => {
+                const { path, namespace } = splitNamespacedPath(resolved_path);
+                return {
+                    text: `conflicting key: "${resolved_path.toLowerCase()}"`,
+                    location: { file: path, namespace: namespace },
+                };
+            }),
+        });
+    }
+    return { result: registry_lowercase, warnings };
+};

package/esm/esbuild/native.d.ts

@@ -0,0 +1,95 @@
+/** a submodule to mimic some of esbuild's native behavior.
+ *
+ * TODO: in the future, make this _version_ dependent, using your `semver` submodule from kitchensink to match the version to a behavior.
+ * also, use a factory function that takes in concrete semver version of esbuild, and then returns a function that matches the desired behavior.
+ *
+ * @module
+*/
+import type { EsbuildLoaderTypeOrEmpty, OnLoadArgs } from "./strongtypes.js";
+/** this function guesses which esbuild loader to use, based on the files extension of the file.
+ *
+ * the way it works is by finding the longest matching suffix defined in the list of user-defined file-extensions,
+ * and the predefined list of  known file-extensions ({@link defaultExtensionToLoaderMap}),
+ * while also taking into account any `with` attribute arguments that may be present when the import was being performed.
+ *
+ * this function is roughly based on the following esbuild function:
+ * [`"/internal/config/config.go":LoaderFromFileExtension`](https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/internal/config/config.go#L259)
+ *
+ * > [!important]
+ * > while esbuild generally gives priority to any import-attributes (`with_attr`) that may be present, over file-extension based loader guessing,
+ * > it makes an exception with regards to any file-extensions that uses the `"copy"` loader, giving it the highest priority.
+ * > you can see this behavior detailed in the following line of esbuild:
+ * > [`"/internal/bundler/bundler.go":parseFile`](https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/internal/bundler/bundler.go#L201)
+ *
+ * > [!note]
+ * > the only behavioral difference in this function and esbuild's own function is that the default loader
+ * > (for unidentified file-extensions, or those with none) resolves to `undefined` rather than `"js"`.
+ * >
+ * > the reason for this is because this information can be useful to the person using this function,
+ * > in addition to not causing any harm if this info is not utilized,
+ * > as passing an `undefined` loader to esbuild will cause it to use the `"js"` loader anyway.
+ *
+ * @param ext_to_loader_map a map tying file-extensions with loaders.
+ * @param with_attr_type_map a mapping between `with.type` attributes and their respective loaders.
+ * @param file_path the file path or url to guess the loader type from.
+ * @param with_attr specify an optional `with` attribute dictionary that might be present.
+ * @returns the appropriate esbuild loader type for the given file path.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals, assertThrows } from "jsr:@std/assert"
+ * import { EsbuildLoaderTypeOrEmpty } from "./strongtypes.ts"
+ *
+ * const my_loader_map: Record<string, EsbuildLoaderTypeOrEmpty> = {
+ *	"": undefined,
+ *	".js": "js",
+ *	".jsx": "jsx",
+ *	".ts": "ts",
+ *	".css": "css",
+ *	".module.css": "local-css",
+ *	".json": "json",
+ *	".txt.json": "text",
+ *	".txt.json.png": "copy",
+ * 	".png": "file",
+ * }
+ *
+ * const my_with_type_map: Record<string, EsbuildLoaderTypeOrEmpty> = {
+ * 	"json": "json",
+ * 	"bytes": "binary",
+ * 	"image": "binary",
+ * 	"empty": undefined,
+ * }
+ *
+ * // aliasing our function for brevity
+ * const fn = (path: string, with_attr?: Record<string, string>) => {
+ * 	return loaderFromFileExtension(my_loader_map, my_with_type_map, path, with_attr)
+ * }
+ *
+ * // non-with import attribute tests:
+ * assertEquals(fn("./hello/.world/.vscode/settings.json"), "json")
+ * assertEquals(fn("./settings.json"),                      "json")
+ * assertEquals(fn("./.settings.txt.json"),                 "text")
+ * assertEquals(fn("~/home/hello/meow.module.css"),         "local-css")
+ * assertEquals(fn("/some/dir/"),                           undefined)
+ * assertEquals(fn("/some/dir/file.js"),                    "js")
+ * assertEquals(fn("/some/dir/file.js.ts"),                 "ts")
+ *
+ * // with import attribute tests:
+ * assertEquals(fn("./settings.txt.json",     { type: "empty" }), undefined)
+ * assertEquals(fn("./settings.txt.json",     { type: "image" }), "binary")
+ * // below, notice that the "copy" loader gets a higher precedence than any import attribute.
+ * assertEquals(fn("./settings.txt.json.png", { type: "image" }), "copy")
+ * ```
+*/
+export declare const loaderFromFileExtension: (ext_to_loader_map: Record<string, EsbuildLoaderTypeOrEmpty>, with_attr_type_map: Record<string, EsbuildLoaderTypeOrEmpty>, file_path: string | URL, with_attr?: OnLoadArgs["with"]) => EsbuildLoaderTypeOrEmpty;
+/** the return type of {@link guessExtensionLoader_Factory},
+ * which guesses a file's loader based on its file-path and the import's `with` attributes,
+ * behaving similar to how esbuild behaves natively.
+*/
+export type GuessExtensionLoader = (file_path: string | URL, with_attr?: OnLoadArgs["with"]) => EsbuildLoaderTypeOrEmpty;
+/** returns a function that guesses the loader that esbuild would natively suggest for a given input file path.
+ *
+ * this factory function expects to be provided with the user's {@link EsbuildPluginBuild["initialOptions"]["loader"]} map.
+*/
+export declare const guessExtensionLoader_Factory: (user_ext_to_loader_map: Record<string, EsbuildLoaderTypeOrEmpty>) => GuessExtensionLoader;
+//# sourceMappingURL=native.d.ts.map

package/esm/esbuild/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../../src/esbuild/native.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAGF,OAAO,KAAK,EAAE,wBAAwB,EAAsB,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAIhG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0EE;AACF,eAAO,MAAM,uBAAuB,sBAChB,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,sBACvC,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,aACjD,MAAM,GAAG,GAAG,cACX,UAAU,CAAC,MAAM,CAAC,KAC5B,wBAwBF,CAAA;AAED;;;EAGE;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,KAAK,wBAAwB,CAAA;AAExH;;;EAGE;AACF,eAAO,MAAM,4BAA4B,2BAA4B,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,KAAG,oBAW/G,CAAA"}

package/esm/esbuild/native.js

@@ -0,0 +1,127 @@
+/** a submodule to mimic some of esbuild's native behavior.
+ *
+ * TODO: in the future, make this _version_ dependent, using your `semver` submodule from kitchensink to match the version to a behavior.
+ * also, use a factory function that takes in concrete semver version of esbuild, and then returns a function that matches the desired behavior.
+ *
+ * @module
+*/
+import { DEBUG, isString, parseFilepathInfo, urlToString } from "../deps.js";
+import { defaultExtensionToLoaderMap } from "./typedefs.js";
+/** this function guesses which esbuild loader to use, based on the files extension of the file.
+ *
+ * the way it works is by finding the longest matching suffix defined in the list of user-defined file-extensions,
+ * and the predefined list of  known file-extensions ({@link defaultExtensionToLoaderMap}),
+ * while also taking into account any `with` attribute arguments that may be present when the import was being performed.
+ *
+ * this function is roughly based on the following esbuild function:
+ * [`"/internal/config/config.go":LoaderFromFileExtension`](https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/internal/config/config.go#L259)
+ *
+ * > [!important]
+ * > while esbuild generally gives priority to any import-attributes (`with_attr`) that may be present, over file-extension based loader guessing,
+ * > it makes an exception with regards to any file-extensions that uses the `"copy"` loader, giving it the highest priority.
+ * > you can see this behavior detailed in the following line of esbuild:
+ * > [`"/internal/bundler/bundler.go":parseFile`](https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/internal/bundler/bundler.go#L201)
+ *
+ * > [!note]
+ * > the only behavioral difference in this function and esbuild's own function is that the default loader
+ * > (for unidentified file-extensions, or those with none) resolves to `undefined` rather than `"js"`.
+ * >
+ * > the reason for this is because this information can be useful to the person using this function,
+ * > in addition to not causing any harm if this info is not utilized,
+ * > as passing an `undefined` loader to esbuild will cause it to use the `"js"` loader anyway.
+ *
+ * @param ext_to_loader_map a map tying file-extensions with loaders.
+ * @param with_attr_type_map a mapping between `with.type` attributes and their respective loaders.
+ * @param file_path the file path or url to guess the loader type from.
+ * @param with_attr specify an optional `with` attribute dictionary that might be present.
+ * @returns the appropriate esbuild loader type for the given file path.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals, assertThrows } from "jsr:@std/assert"
+ * import { EsbuildLoaderTypeOrEmpty } from "./strongtypes.ts"
+ *
+ * const my_loader_map: Record<string, EsbuildLoaderTypeOrEmpty> = {
+ *	"": undefined,
+ *	".js": "js",
+ *	".jsx": "jsx",
+ *	".ts": "ts",
+ *	".css": "css",
+ *	".module.css": "local-css",
+ *	".json": "json",
+ *	".txt.json": "text",
+ *	".txt.json.png": "copy",
+ * 	".png": "file",
+ * }
+ *
+ * const my_with_type_map: Record<string, EsbuildLoaderTypeOrEmpty> = {
+ * 	"json": "json",
+ * 	"bytes": "binary",
+ * 	"image": "binary",
+ * 	"empty": undefined,
+ * }
+ *
+ * // aliasing our function for brevity
+ * const fn = (path: string, with_attr?: Record<string, string>) => {
+ * 	return loaderFromFileExtension(my_loader_map, my_with_type_map, path, with_attr)
+ * }
+ *
+ * // non-with import attribute tests:
+ * assertEquals(fn("./hello/.world/.vscode/settings.json"), "json")
+ * assertEquals(fn("./settings.json"),                      "json")
+ * assertEquals(fn("./.settings.txt.json"),                 "text")
+ * assertEquals(fn("~/home/hello/meow.module.css"),         "local-css")
+ * assertEquals(fn("/some/dir/"),                           undefined)
+ * assertEquals(fn("/some/dir/file.js"),                    "js")
+ * assertEquals(fn("/some/dir/file.js.ts"),                 "ts")
+ *
+ * // with import attribute tests:
+ * assertEquals(fn("./settings.txt.json",     { type: "empty" }), undefined)
+ * assertEquals(fn("./settings.txt.json",     { type: "image" }), "binary")
+ * // below, notice that the "copy" loader gets a higher precedence than any import attribute.
+ * assertEquals(fn("./settings.txt.json.png", { type: "image" }), "copy")
+ * ```
+*/
+export const loaderFromFileExtension = (ext_to_loader_map, with_attr_type_map, file_path, with_attr) => {
+    // first, we check if any `withAttr.type` exists that matches with the provided `withAttr mapping`.
+    const with_attr_type = with_attr?.type;
+    if (isString(with_attr_type) && (with_attr_type in with_attr_type_map)) {
+        // we don't return immediately because esbuild makes an exception for the "copy" loader,
+        // giving it a higher precedence over any with-import attribute.
+        const suggested_loader_without_with_attr = loaderFromFileExtension(ext_to_loader_map, with_attr_type_map, file_path);
+        return suggested_loader_without_with_attr === "copy"
+            ? suggested_loader_without_with_attr
+            : with_attr_type_map[with_attr_type];
+    }
+    // next, we pick the longest matching extension by recursively trimming down the `".${remaining_ext}"` until a match is found.
+    const filename = parseFilepathInfo(urlToString(file_path)).filename;
+    let slice_idx = 0;
+    while (true) {
+        slice_idx = filename.indexOf(".", slice_idx);
+        const remaining_ext = (slice_idx >= 0) ? filename.slice(slice_idx) : "";
+        if (remaining_ext in ext_to_loader_map) {
+            return ext_to_loader_map[remaining_ext];
+        }
+        if (slice_idx < 0) {
+            break;
+        }
+        slice_idx++; // we must move the cursor forward by one, so that the starting `"."` is ignored.
+    }
+    // the above should eventually match all possible file-extensions if the `""` extension is also present there (which it is, in esbuild's default config).
+    // however, if for some reason we end up at this point, then we'll throw an error.
+    throw new Error(DEBUG.ERROR ? `[loaderFromFileExtension]: expected at least one file-extension to match with the path: "${file_path}".` : "");
+};
+/** returns a function that guesses the loader that esbuild would natively suggest for a given input file path.
+ *
+ * this factory function expects to be provided with the user's {@link EsbuildPluginBuild["initialOptions"]["loader"]} map.
+*/
+export const guessExtensionLoader_Factory = (user_ext_to_loader_map) => {
+    const ext_to_loader_map = { ...defaultExtensionToLoaderMap, ...user_ext_to_loader_map }, with_attr_type_map = {
+        "json": "json",
+        "bytes": "binary",
+        "text": "text",
+    };
+    return (file_path, with_attr) => {
+        return loaderFromFileExtension(ext_to_loader_map, with_attr_type_map, file_path, with_attr);
+    };
+};

package/esm/esbuild/outputfile.d.ts

@@ -0,0 +1,86 @@
+/** a utility submodule that works alongside {@link Metafile} to aid in holding onto a given file's contents, path, inputs, and imports,
+ * in addition to providing useful file-related methods, such as {@link OnEmitOptions} filter matching, and etc...
+ *
+ * @module
+*/
+import { type Require } from "../deps.js";
+import type { OnEmitHandler } from "../super/build_context.js";
+import type { BundledInputFile, ImportedEntity, OnEmitOptions, OnEmitResult } from "../super/typedefs.js";
+import type { AbsolutePath, Path } from "../typedefs.js";
+import type { Metafile } from "./metafile.js";
+import type { EsbuildOutputFile } from "./typedefs.js";
+/** an imported entity node, similar to {@link ImportedEntity}, but with a shared {@link entity} object field. */
+export interface ImportedEntityNode<K = any> extends Pick<ImportedEntity<K>, "key" | "with" | "kind" | "external"> {
+    /** the output file entity being referenced by this import.
+     * this is present even when resource being referenced is an external resource.
+    */
+    entity: OutputFileEntity | ExternalFileEntity;
+}
+export interface ExternalFileEntity {
+    /** the **absolute** external path of this external resource entity. */
+    externalPath: AbsolutePath;
+}
+/** this dictionary maps an output file's **original** absolute output path to its {@link OutputFileEntity} object.
+ *
+ * the keys of this map are always in **lower casing**, and never change, even after an output file has been renamed via {@link OnEmitResult.path}.
+ * the way to acquire a given {@link OutputFileEntity}'s original output path key is by simply performing:
+ * `original_path_key = (file_entity.initialPath ?? file_entity.outputPath).toLowerCase()`.
+*/
+export type OutputFileEntityMap = Map<string, OutputFileEntity>;
+export type WriteFileFn = (file_path: string | URL, data: ArrayBufferView) => Promise<void>;
+export declare class OutputFileEntity implements Require<Pick<EsbuildOutputFile, "contents" | "hash">, "contents"> {
+    /** the **absolute** output path of this resource entity. */
+    outputPath: AbsolutePath;
+    /** if this resource entity was renamed during the {@link SuperPluginBuild.onEmit, emission stage},
+     * then its original (absolute) {@link outputPath} will get saved here.
+    */
+    initialPath?: AbsolutePath;
+    hash?: string;
+    contents: Uint8Array<ArrayBuffer>;
+    /** specify if this file entry should be written.
+     *
+     * @defaultValue `true` (i.e. it'll be written if `EsbuildBuildOption.write` is enabled, otherwise it won't be.)
+    */
+    write: boolean;
+    /** an array of metadata on the loaded input files that were bundled into _this_ physical output file entity. */
+    inputs: Readonly<BundledInputFile>[];
+    /** an array of metadata on the output files that are imported by _this_ file entity during runtime.
+     *
+     * each of these is basically associated with a js (`import { x, y, z } from "abc"`), css (`@import url("./blahblah.css")`),
+     * or user-import (i.e. {@link OnTransformResult.imports}) statement.
+    */
+    imports: Readonly<ImportedEntityNode<any>>[];
+    protected metafile: Metafile;
+    constructor(metafile: Metafile, esbuild_file: EsbuildOutputFile);
+    /** scans esbuild's metafile outputs to find the input sources bundled into this output file.
+     * the input sources are presented with resolved path information, namespace, `onEmit` information,
+     * and other additional information acquired from the resource's resolver, loader, and transformer results.
+     * (the collection of this information is stored in {@link metafile.resolvedResourceRegistry},
+     * which is inherited from the {@link SuperBuildContext}.)
+    */
+    scanEsbuildInputs(): typeof this.inputs;
+    /** scans esbuild's metafile outputs to find all file imports performed by this output file.
+     * these only include entity imports found by esbuild natively (js imports, css imports, etc...), and not long-build plugin based imports.
+     *
+     * > [!important]
+     * > this function should be run _after_ all files have been added to your {@link metafile} via {@link metafile.addFile},
+     * > because the imports need to reference the {@link OutputFileEntity} associated with the imported file.
+    */
+    scanEsbuildImports(): typeof this.imports;
+    /** test if an `onEmit` handler's filters apply to _this_ output file entity. */
+    protected matchOnEmitFilter(options: OnEmitOptions): boolean;
+    /** perform `onEmit` action on _this_ output file entity, based on the provided `onEmit` handlers. */
+    performOnEmit(on_emit_handlers: Array<OnEmitHandler>): Promise<OnEmitResult | undefined>;
+    /** rename this file. you can either provide an absolute path, or a relative path.
+     * relative paths will be resolved with respect to the `cwd` or esbuild's `absWorkingDir`.
+    */
+    rename(new_output_path: Path): void;
+    /** convert an output file entity to an esbuild-compatible {@link EsbuildOutputFile | output file description}.
+     *
+     * (honestly, I don't see myself using it, and if we're overloading esbuild anyway, why don't we overload the `OutputFile`
+     * interface to include new fields, such as `write` and `external`, etc...?)
+    */
+    toEsbuildOutputFile(outdir?: Path): Require<EsbuildOutputFile, "path" | "contents"> | undefined;
+    writeFile(write_file_fn: WriteFileFn): Promise<void>;
+}
+//# sourceMappingURL=outputfile.d.ts.map

package/esm/esbuild/outputfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputfile.d.ts","sourceRoot":"","sources":["../../src/esbuild/outputfile.ts"],"names":[],"mappings":"AAAA;;;;EAIE;AAEF,OAAO,EAA8D,KAAK,OAAO,EAAE,MAAM,YAAY,CAAA;AACrG,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,2BAA2B,CAAA;AAEjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAqB,MAAM,sBAAsB,CAAA;AAC5H,OAAO,KAAK,EAAE,YAAY,EAAkB,IAAI,EAAE,MAAM,gBAAgB,CAAA;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGtD,iHAAiH;AACjH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;IACjH;;MAEE;IACF,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,CAAA;CAC7C;AAED,MAAM,WAAW,kBAAkB;IAClC,uEAAuE;IACvE,YAAY,EAAE,YAAY,CAAA;CAC1B;AAED;;;;;EAKE;AACF,MAAM,MAAM,mBAAmB,GAAG,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;AAE/D,MAAM,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAE3F,qBAAa,gBAAiB,YAAW,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,UAAU,GAAG,MAAM,CAAC,EAAE,UAAU,CAAC;IACzG,4DAA4D;IACrD,UAAU,EAAE,YAAY,CAAA;IAE/B;;MAEE;IACK,WAAW,CAAC,EAAE,YAAY,CAAA;IAE1B,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC,CAAA;IAExC;;;MAGE;IACK,KAAK,EAAE,OAAO,CAAO;IAE5B,gHAAgH;IACzG,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAK;IAEhD;;;;MAIE;IACK,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,EAAE,CAAK;IAExD,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAA;gBAEhB,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB;IAc/D;;;;;MAKE;IACK,iBAAiB,IAAI,OAAO,IAAI,CAAC,MAAM;IAmB9C;;;;;;MAME;IACK,kBAAkB,IAAI,OAAO,IAAI,CAAC,OAAO;IA6ChD,gFAAgF;IAChF,SAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO;IA2B5D,qGAAqG;IACxF,aAAa,CAAC,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IA0CrG;;MAEE;IACK,MAAM,CAAC,eAAe,EAAE,IAAI;IAMnC;;;;MAIE;IACK,mBAAmB,CAAC,MAAM,GAAE,IAAW,GAAG,OAAO,CAAC,iBAAiB,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG,SAAS;IAY/F,SAAS,CAAC,aAAa,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAIjE"}