@oazmi/superbuild 0.1.0

package/esm/esbuild/outputfile.js

@@ -0,0 +1,221 @@
+/** 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 { array_isEmpty, isNull, isString, relativePath, textEncoder } from "../deps.js";
+export class OutputFileEntity {
+    /** the **absolute** output path of this resource entity. */
+    outputPath;
+    /** if this resource entity was renamed during the {@link SuperPluginBuild.onEmit, emission stage},
+     * then its original (absolute) {@link outputPath} will get saved here.
+    */
+    initialPath;
+    hash;
+    contents;
+    /** 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 = true;
+    /** an array of metadata on the loaded input files that were bundled into _this_ physical output file entity. */
+    inputs = [];
+    /** 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 = [];
+    metafile;
+    constructor(metafile, esbuild_file) {
+        this.metafile = metafile;
+        const output_path = metafile.resolvePath(esbuild_file.path), output_path_lowercase = output_path.toLowerCase(), metadata = metafile.outputs.get(output_path_lowercase);
+        if (!metadata) {
+            throw Error(`[OutputFileEntity.constructor]: no matching metadata for the file with the path "${output_path_lowercase}" could be found.`);
+        }
+        this.outputPath = output_path;
+        this.initialPath = undefined;
+        this.hash = esbuild_file.hash;
+        this.contents = esbuild_file.contents;
+        this.scanEsbuildInputs();
+    }
+    /** 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() {
+        const bundled_files = this.inputs;
+        if (!array_isEmpty(bundled_files)) {
+            return bundled_files;
+        } // if `inputs` were already added, then there's no scanning left to do.
+        const metafile = this.metafile, warnings = metafile.warnings, resolvedResourceRegistry = metafile.resolvedResourceRegistry, output_path_key = (this.initialPath ?? this.outputPath).toLowerCase(), metadata = metafile.outputs.get(output_path_key);
+        if (!metadata) {
+            throw Error(`[OutputFileEntity.scanEsbuildInputs]: no matching metadata for the file with the path "${output_path_key}" could be found.`);
+        }
+        // acquire the list of all bundled files which were included in the current output resource, that can be traced back from the resource registry.
+        for (const input_source_resolved_path of metadata.inputs) {
+            const bundled_file = resolvedResourceRegistry.get(input_source_resolved_path);
+            if (bundled_file) {
+                bundled_files.push(bundled_file);
+            }
+            else {
+                warnings.push({ text: `[OutputFileEntity.scanEsbuildInputs]: resource registry never encountered the resource: "${input_source_resolved_path}".` });
+            }
+        }
+        return bundled_files;
+    }
+    /** 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() {
+        const imported_entities = this.imports;
+        if (!array_isEmpty(imported_entities)) {
+            return imported_entities;
+        } // if `imports` were already added, then there's no scanning left to do.
+        const metafile = this.metafile, warnings = metafile.warnings, outputs = metafile.outputs, output_path_key = (this.initialPath ?? this.outputPath).toLowerCase(), metadata = outputs.get(output_path_key);
+        if (!metadata) {
+            throw Error(`[OutputFileEntity.scanEsbuildImports]: no matching metadata for the file with the path "${output_path_key}" could be found.`);
+        }
+        for (const import_props of metadata.imports) {
+            // here, we find the original namespaced resolved path of the file that resulted in the `import_output_path` file.
+            // since there could be multiple `inputs` that resulted in the creation of the file at `import_output_path`,
+            // we set the `key` to be an array of all `inputs`.
+            const { path: import_output_path, kind, external } = import_props;
+            // firstly though, esbuild based external imports have no output file associated with them, so they must not under go this process.
+            // for their keys, we simply set it to the their reference path/link.
+            if (external) {
+                const external_entity = { externalPath: import_output_path };
+                imported_entities.push({ key: [import_output_path], kind, external, entity: external_entity });
+                continue;
+            }
+            const import_output_path_key = import_output_path.toLowerCase(), entity = metafile.outputFileEntities.get(import_output_path_key);
+            if (!entity) {
+                throw Error(`[OutputFileEntity.scanEsbuildImports]: no matching output file entity for the path "${import_output_path_key}" could be found.`);
+            }
+            const import_sources = entity.inputs.map((props) => { return (props.namespace + ":" + props.path).toLowerCase(); });
+            if (array_isEmpty(import_sources)) {
+                // TODO: under this scenario, I can technically still construct a `key` if I were to inspect the `imports` of the `outputPath`,
+                // and then trace which of _its_ inputs correspond to this `import_output_path`,
+                // but that's just too convoluted and it'll still require a bunch of guessing, at which point it will not be worth the effort.
+                warnings.push({
+                    text: `[OutputFileEntity.scanEsbuildImports]: expected import file to be made out of at least one input resource. `
+                        + `but worry not, as this could happen when the emitted file is just a re-exporting chunk file.`,
+                    location: { file: import_output_path },
+                });
+            }
+            imported_entities.push({ key: import_sources, kind, external, entity });
+        }
+        return imported_entities;
+    }
+    /** test if an `onEmit` handler's filters apply to _this_ output file entity. */
+    matchOnEmitFilter(options) {
+        const { filter, inputs: input_filters } = options, output_path = this.outputPath;
+        // test the output file name filter first.
+        // the reason why `this.initialPath` is not used is because it is impossible for a file entity to be renamed before it goes through the `onEmit` stage.
+        // hence, `this.initialPath` is guaranteed to be `undefined`.
+        if (!filter.test(output_path)) {
+            return false;
+        }
+        // next we test if each input filter has been satisfied by at least one element in `this.inputs`
+        // (which is the list of all bundled source files which were included in the current file).
+        const bundled_files = this.inputs;
+        for (const input_filter of (input_filters ?? [])) {
+            const { filter, namespace, loader, transformLoader } = input_filter;
+            const at_least_one_file_satisfies_conditions = bundled_files.some((bundled_file) => {
+                return filter.test(bundled_file.path)
+                    && (namespace ? namespace === bundled_file.namespace : true)
+                    && (loader ? loader === bundled_file.loader : true)
+                    && (transformLoader ? transformLoader === bundled_file.transformLoader : true);
+            });
+            if (!at_least_one_file_satisfies_conditions) {
+                return false;
+            }
+        }
+        // if we've made it to here, then this entity has passed the filter test, and may proceed to the `onEmit` callback hook.
+        return true;
+    }
+    /** perform `onEmit` action on _this_ output file entity, based on the provided `onEmit` handlers. */
+    async performOnEmit(on_emit_handlers) {
+        const imported_entities = this.imports.map((imported_entity_node) => {
+            const { key, kind, external, entity, with: with_attr } = imported_entity_node, is_external_entity = "externalPath" in entity, outputPath = is_external_entity ? entity.externalPath : entity.outputPath, initialPath = is_external_entity ? undefined : entity.initialPath, write = is_external_entity ? false : entity.write;
+            return { key, outputPath, initialPath, kind, external, with: with_attr, write };
+        });
+        // attempt at matching the output file with all available `onEmit` hooks' filters,
+        // and stopping at the first match that yields a viable result.
+        for (const handler of on_emit_handlers) {
+            if (!this.matchOnEmitFilter(handler)) {
+                continue;
+            }
+            const on_emit_result = await handler.callback({
+                outputPath: this.outputPath,
+                contents: this.contents,
+                inputs: this.inputs,
+                imports: imported_entities,
+            });
+            if (isNull(on_emit_result)) {
+                continue;
+            }
+            // updating the emitted file `path` and `contents` from the `result`.
+            if (on_emit_result.contents) {
+                this.contents = isString(on_emit_result.contents)
+                    ? textEncoder.encode(on_emit_result.contents)
+                    : on_emit_result.contents;
+            }
+            if (on_emit_result.path) {
+                this.rename(on_emit_result.path);
+            }
+            if (!isNull(on_emit_result.write)) {
+                this.write = on_emit_result.write;
+            }
+            // TODO: what will happen to the files that depend on the deleted files?
+            // should I simply delete this resource from the dependency graph and call it a day?
+            // inserting the original plugin names of the plugins where the errors and warnings originated from.
+            const pluginName = handler.pluginName;
+            on_emit_result.warnings?.forEach((warning) => { if (!warning.pluginName) {
+                warning.pluginName = pluginName;
+            } });
+            on_emit_result.errors?.forEach((error) => { if (!error.pluginName) {
+                error.pluginName = pluginName;
+            } });
+            return on_emit_result;
+        }
+    }
+    /** 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) {
+        // save the original output path into `initialPath` if it has never been assigned before.
+        this.initialPath ??= this.outputPath;
+        this.outputPath = this.metafile.resolvePath(new_output_path);
+    }
+    /** 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 = "./") {
+        if (!this.write) {
+            return undefined;
+        }
+        const metafile = this.metafile;
+        outdir = metafile.resolvePath(outdir);
+        const relative_path = relativePath(this.outputPath, outdir); // TODO: letter casing inconsistency can pose an issue here.
+        return {
+            path: relative_path,
+            hash: this.hash,
+            contents: this.contents,
+        };
+    }
+    async writeFile(write_file_fn) {
+        if (!this.write) {
+            return;
+        }
+        return write_file_fn(this.outputPath, this.contents);
+    }
+}

package/esm/esbuild/strongtypes.d.ts

@@ -0,0 +1,90 @@
+/** this module contains esbuild type definitions of the latest esbuild version.
+ *
+ * this file is a partial copy from my `@oazmi/esbuild-plugin-deno` esbuild plugin's `typedefs` file.
+ * here's the original source: [github](https://github.com/oazmi/esbuild-plugin-deno/blob/b20109988a7245804b52e219ca0f2948fa4012ba/src/plugins/typedefs.ts).
+ *
+ * @module
+*/
+import type { esbuild, MaybePromiseOrNull, MaybePromiseOrVoid } from "../deps.js";
+import type { CommonPluginData } from "./typedefs.js";
+/** an interface representing the `esbuild` namespace. */
+export interface Esbuild {
+    /** this is only available at the top-level `esbuild` object, not in sub-builds residing inside of {@link EsbuildPluginBuild}. */
+    stop?: typeof esbuild.stop;
+    analyzeMetafile: typeof esbuild.analyzeMetafile;
+    analyzeMetafileSync: typeof esbuild.analyzeMetafileSync;
+    build: typeof esbuild.build;
+    buildSync: typeof esbuild.buildSync;
+    context: typeof esbuild.context;
+    formatMessages: typeof esbuild.formatMessages;
+    formatMessagesSync: typeof esbuild.formatMessagesSync;
+    initialize: typeof esbuild.initialize;
+    transform: typeof esbuild.transform;
+    transformSync: typeof esbuild.transformSync;
+    version: typeof esbuild.version;
+}
+/** type alias for `esbuild.OnResolveOptions`. */
+export type OnResolveOptions = esbuild.OnResolveOptions;
+/** type alias for `esbuild.OnResolveArgs`, slightly tweaked for this library's internal use. */
+export type OnResolveArgs = Omit<esbuild.OnResolveArgs, "pluginData"> & {
+    pluginData: undefined | CommonPluginData;
+};
+/** type alias for `esbuild.OnResolveResult`. */
+export type OnResolveResult = esbuild.OnResolveResult;
+/** type alias for the callback function provided to the `onResolve` function (aka `esbuild.PluginBuild["onResolve"]`). */
+export type OnResolveCallback = (args: OnResolveArgs) => MaybePromiseOrNull<OnResolveResult>;
+/** type alias for `esbuild.OnLoadOptions`. */
+export type OnLoadOptions = esbuild.OnLoadOptions;
+/** type alias for `esbuild.OnLoadArgs`, slightly tweaked for this library's internal use. */
+export type OnLoadArgs = Omit<esbuild.OnLoadArgs, "pluginData"> & {
+    pluginData: undefined | CommonPluginData;
+};
+/** type alias for `esbuild.OnLoadResult`. */
+export type OnLoadResult = esbuild.OnLoadResult;
+/** type alias for the callback function provided to the `OnLoad` function (aka `esbuild.PluginBuild["OnLoad"]`). */
+export type OnLoadCallback = (args: OnLoadArgs) => MaybePromiseOrNull<OnLoadResult>;
+/** type alias for `esbuild.ResolveOptions`. */
+export type EsbuildResolveOptions = esbuild.ResolveOptions;
+/** type alias for `esbuild.ResolveResult`. */
+export type EsbuildResolveResult = esbuild.ResolveResult;
+/** type alias for `esbuild.OnStartResult`. */
+export type EsbuildOnStartResult = esbuild.OnStartResult;
+/** type alias for the callback function provided to the `OnStart` function (aka `esbuild.PluginBuild["OnStart"]`). */
+export type EsbuildOnStartCallback = () => MaybePromiseOrVoid<EsbuildOnStartResult>;
+/** type alias for `esbuild.OnEndResult`. */
+export type EsbuildOnEndResult = esbuild.OnEndResult;
+/** type alias for the callback function provided to the `OnEnd` function (aka `esbuild.PluginBuild["OnEnd"]`). */
+export type EsbuildOnEndCallback<ProvidedOptions extends EsbuildBuildOptions = EsbuildBuildOptions> = (result: EsbuildBuildResult<ProvidedOptions>) => MaybePromiseOrVoid<EsbuildOnEndResult>;
+/** type alias for `esbuild.BuildOptions`. */
+export type EsbuildBuildOptions = esbuild.BuildOptions;
+/** type alias for `esbuild.BuildResult`. */
+export type EsbuildBuildResult<ProvidedOptions extends EsbuildBuildOptions = EsbuildBuildOptions> = esbuild.BuildResult<ProvidedOptions>;
+/** type alias for `esbuild.build`. */
+export type EsbuildBuild = typeof esbuild.build;
+/** type alias for `esbuild.Plugin`. */
+export type EsbuildPlugin = esbuild.Plugin;
+/** type alias for `esbuild.Plugin["setup"]`. */
+export type EsbuildPluginSetup = esbuild.Plugin["setup"];
+/** type alias for `esbuild.PluginBuild`. */
+export type EsbuildPluginBuild = esbuild.PluginBuild;
+/** type alias for `esbuild.Loader`. */
+export type EsbuildLoaderType = esbuild.Loader;
+/** type alias for `esbuild.Loader | undefined`. */
+export type EsbuildLoaderTypeOrEmpty = EsbuildLoaderType | undefined;
+/** type alias for `esbuild.ImportKind`. */
+export type EsbuildImportKind = esbuild.ImportKind;
+/** type alias for `esbuild.ImportKind | "file-loader"`. */
+export type EsbuildOutputsImportKind = EsbuildMetafileImportProps["kind"];
+/** type alias for `esbuild.Metafile`. */
+export type EsbuildMetafile = esbuild.Metafile;
+/** type alias for `esbuild.Metafile.outputs[number].imports[number]`. */
+export type EsbuildMetafileImportProps = Required<esbuild.Metafile["outputs"][number]["imports"][number]>;
+/** type alias for `esbuild.Message`. */
+export type EsbuildMessage = esbuild.Message;
+/** type alias for `esbuild.PartialMessage`. */
+export type EsbuildPartialMessage = esbuild.PartialMessage;
+/** useful non-public utility type copied from esbuild's source code. */
+export type SameShape<Out, In extends Out> = In & {
+    [Key in Exclude<keyof In, keyof Out>]: never;
+};
+//# sourceMappingURL=strongtypes.d.ts.map

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

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

package/esm/esbuild/strongtypes.js

@@ -0,0 +1,8 @@
+/** this module contains esbuild type definitions of the latest esbuild version.
+ *
+ * this file is a partial copy from my `@oazmi/esbuild-plugin-deno` esbuild plugin's `typedefs` file.
+ * here's the original source: [github](https://github.com/oazmi/esbuild-plugin-deno/blob/b20109988a7245804b52e219ca0f2948fa4012ba/src/plugins/typedefs.ts).
+ *
+ * @module
+*/
+export {};

package/esm/esbuild/typedefs.d.ts

@@ -0,0 +1,121 @@
+/** additional type definitions and central enum/constants variable management.
+ *
+ * this file is a partial copy from my `@oazmi/esbuild-plugin-deno` esbuild plugin's `typedefs` file.
+ * here's the original source: [github](https://github.com/oazmi/esbuild-plugin-deno/blob/b20109988a7245804b52e219ca0f2948fa4012ba/src/plugins/typedefs.ts).
+ *
+ * @module
+*/
+import type { AbsolutePath } from "../typedefs.js";
+import type { EsbuildLoaderTypeOrEmpty } from "./strongtypes.js";
+import type { EsbuildLoaderTypeCompatible } from "./weaktypes.js";
+/** a central enum containing the list of esbuild namespaces used by the plugins in this library. */
+export declare const enum PLUGIN_NAMESPACE {
+    LOADER_GENERIC = "oazmi-loader-generic"
+}
+/** a list of default namespaces that esbuild uses for native/entry-point resolution. */
+export declare const defaultEsbuildNamespaces: (string | undefined)[];
+/** a list of all esbuild content type loaders. */
+export declare const allEsbuildLoaders: Array<EsbuildLoaderTypeCompatible>;
+/** this is the common plugin data utilized by this esbuild-plugin. */
+export type CommonPluginData = any;
+/** these are the various formats of input and output specification accepted by esbuild for a single entity. */
+export type EsbuildEntryPointType = string | {
+    in: string;
+    out: string;
+} | [input: string, output: string];
+/** these are the various formats of entry points accepted by esbuild. */
+export type EsbuildEntryPointsType = ImportMap | Array<EsbuildEntryPointType>;
+/** an import map is just a key-value dictionary, where the value is an absolute path to a package's resource,
+ * and the key associated with it is an alias used by your code to reference the resource's path.
+ *
+ * > [!note]
+ * > the all keys that are provided are normalized first, so that a key like "hello/earth/../world" would transform to "hello/world".
+ * > further reading on [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap).
+ *
+ * @example
+ * suppose that you have the following import map:
+ *
+ * ```ts
+ * const myImportMap: ImportMap = {
+ * 	"@scope/lib/some-entry": "https://jsr.io/@oazmi/kitchensink/0.9.2/src/array2d.ts", // this should require the http plugin to resolve
+ * 	"type-definitions"     : "jsr:@oazmi/kitchensink@0.9.2/typedefs", // this should require the jsr plugin to resolve
+ * 	"build-cli/"           : "jsr:@oazmi/build-tools@0.2.4/cli/",     // reference to a whole directory
+ * }
+ * ```
+ *
+ * then, with this import map, you should hypothetically be able to reference these libraries in your code as the following when bundling:
+ *
+ * ```ts ignore
+ * import { transposeArray2D }            from "@scope/lib/some-entry"
+ * import { Optional, MethodsOf }         from "type-definitions"
+ * import type { CliArgs as DocsCliArgs } from "build-cli/docs.ts" // the prefix is part of the import map
+ * import type { CliArgs as DistCliArgs } from "build-cli/dist.ts" // the prefix is part of the import map
+ *
+ * // your code...
+ * ```
+ *
+ * ### Rules for import maps
+ *
+ * here are some rules that your import map record should follow:
+ * (copied from [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap#module_specifier_map)):
+ * - none of the _keys_ may be empty.
+ * - all of the _values_ must be strings, defining either a valid absolute url or a valid relative url string that starts with `"/"`, `"./"`, or `"../"`.
+ * - if a _key_ ends with `"/"`, then the corresponding value must also end with `"/"`.
+ *   a key with a trailing `"/"` can be used as a prefix for when mapping (or remapping) modules addresses.
+ * - the object properties' ordering is irrelevant; if multiple keys can match the module specifier, the most specific key is used.
+ *   in other words, a specifier "olive/branch/" would match before "olive/".
+ * - any path that is being matched against an import-map _will_ be normalized before being matched.
+ *   this means that the path `"./foo/../js/app.js"` will be normalized and transformed to `"./js/app.js"`,
+ *   before a suitable match is looked up in the import-map.
+ * - your import-map's keys should be **always** be pre-normalized.
+ *   this is because a non-normalized key, such as `"hello/earth/../to/./this/world.txt"`, will never match any possible input path,
+ *   because the input path will always be normalized first, thereby becoming un-matchable with any un-normalized key.
+ *   so, the correct thing to do would be to ensure that your import-map keys are normalize before hand.
+ *   (in the example here, the normalized version of the key would be `"hello/to/this/world.txt"`)
+*/
+export type ImportMap = Record<string, string>;
+/** the in-memory output file description generated by `esbuild`. weakly similar to `esbuild.OutputFile`. */
+export interface EsbuildOutputFile {
+    /** the absolute output path of the file. */
+    path: AbsolutePath;
+    /** a "text" rendering of the {@link contents} property, which changes automatically with any modifications to the {@link contents}.
+     *
+     * I'm not certain how it works under the hood, but I assume that it relies on checking for a new assignment (in its `setter` function),
+     * and only then updates the {@link text} accordingly.
+     * if that is the case, then mutations to the {@link contents} buffer itself will not result in the {@link text} being updated.
+     * instead, we will have to assign a new array buffer to the {@link contents} property for the effect to take place.
+    */
+    text?: string;
+    /** the contents of the file to be written as a byte buffer.
+     * this is the single source of truth. the {@link text} property is merely a reflection of this property.
+     *
+     * TODO: this should ideally be set to `Uint8Array<ArrayBuffer>` instead of just `Uint8Array`,
+     * however, the typing on `esbuild.OutputFile.contents` still uses `Uint8Array`, causing type incompatibility issues.
+     * once esbuild has the typing fixed, I should update the type definition here as well.
+    */
+    contents?: Uint8Array;
+    /** the (unique?) hash generated for this output file by esbuild. */
+    hash?: string;
+}
+/** this dictates esbuild's default/native file-extension to loader mapping.
+ * it is roughly based on the following esbuild function:
+ * [`"/internal/bundler/bundler.go":DefaultExtensionToLoaderMap`](https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/internal/bundler/bundler.go#L2916)
+ *
+ * > [!note]
+ * > one important distinction to note down is the fact that the loader for the "no extension" case (`""` empty string) is `undefined`,
+ * > meaning that it will use esbuild's own default loader for it (which happens to be `"js"` for such cases).
+ * >
+ * > the reason why we don't directly assign a `"js"` loader to this case is because our super-build's transformer hooks may utilize the knowledge of whether a "default" was originally passed,
+ * > or if an actual "js" loader was intended to be used by the prior `onLoad` hook's callback.
+ *
+ * PERMANENT-TODO: periodically check if the definitions are up to date.
+ *
+ * TODO: also, in the future, define these extension loaders based on the version of esbuild that is being used,
+ * using my `semver` resolver library from kitchensink.
+ *
+ * TODO: `".cts"` and `".mts"` both internally use a `LoaderTSNoAmbiguousLessThan` loader, which is different from a `LoaderTS`.
+ * however, the former is not exposed as a loader in javascript, where as the latter is.
+ * for now, I'm setting both `".cts"` and `".mts"` to load via the `"ts"` loader, but I don't know if there will be any negative consequences of this later.
+*/
+export declare const defaultExtensionToLoaderMap: Record<string, EsbuildLoaderTypeOrEmpty>;
+//# sourceMappingURL=typedefs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"typedefs.d.ts","sourceRoot":"","sources":["../../src/esbuild/typedefs.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAClD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAA;AAGjE,oGAAoG;AACpG,0BAAkB,gBAAgB;IACjC,cAAc,yBAAyB;CACvC;AAED,wFAAwF;AACxF,eAAO,MAAM,wBAAwB,wBAA0B,CAAA;AAE/D,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,2BAA2B,CAIhE,CAAA;AAED,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAElC,+GAA+G;AAC/G,MAAM,MAAM,qBAAqB,GAC9B,MAAM,GACN;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC3B,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAElC,yEAAyE;AACzE,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,KAAK,CAAC,qBAAqB,CAAC,CAAA;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+CE;AACF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE9C,4GAA4G;AAC5G,MAAM,WAAW,iBAAiB;IACjC,4CAA4C;IAC5C,IAAI,EAAE,YAAY,CAAA;IAElB;;;;;;MAME;IACF,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;;;;;MAME;IACF,QAAQ,CAAC,EAAE,UAAU,CAAA;IAErB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;;;;;;;;;EAmBE;AACF,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAchF,CAAA"}

package/esm/esbuild/typedefs.js

@@ -0,0 +1,55 @@
+/** additional type definitions and central enum/constants variable management.
+ *
+ * this file is a partial copy from my `@oazmi/esbuild-plugin-deno` esbuild plugin's `typedefs` file.
+ * here's the original source: [github](https://github.com/oazmi/esbuild-plugin-deno/blob/b20109988a7245804b52e219ca0f2948fa4012ba/src/plugins/typedefs.ts).
+ *
+ * @module
+*/
+/** a central enum containing the list of esbuild namespaces used by the plugins in this library. */
+export var PLUGIN_NAMESPACE;
+(function (PLUGIN_NAMESPACE) {
+    PLUGIN_NAMESPACE["LOADER_GENERIC"] = "oazmi-loader-generic";
+})(PLUGIN_NAMESPACE || (PLUGIN_NAMESPACE = {}));
+/** a list of default namespaces that esbuild uses for native/entry-point resolution. */
+export const defaultEsbuildNamespaces = [undefined, "", "file"];
+/** a list of all esbuild content type loaders. */
+export const allEsbuildLoaders = [
+    "base64", "binary", "copy", "css", "dataurl",
+    "default", "empty", "file", "js", "json",
+    "jsx", "local-css", "text", "ts", "tsx",
+];
+/** this dictates esbuild's default/native file-extension to loader mapping.
+ * it is roughly based on the following esbuild function:
+ * [`"/internal/bundler/bundler.go":DefaultExtensionToLoaderMap`](https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/internal/bundler/bundler.go#L2916)
+ *
+ * > [!note]
+ * > one important distinction to note down is the fact that the loader for the "no extension" case (`""` empty string) is `undefined`,
+ * > meaning that it will use esbuild's own default loader for it (which happens to be `"js"` for such cases).
+ * >
+ * > the reason why we don't directly assign a `"js"` loader to this case is because our super-build's transformer hooks may utilize the knowledge of whether a "default" was originally passed,
+ * > or if an actual "js" loader was intended to be used by the prior `onLoad` hook's callback.
+ *
+ * PERMANENT-TODO: periodically check if the definitions are up to date.
+ *
+ * TODO: also, in the future, define these extension loaders based on the version of esbuild that is being used,
+ * using my `semver` resolver library from kitchensink.
+ *
+ * TODO: `".cts"` and `".mts"` both internally use a `LoaderTSNoAmbiguousLessThan` loader, which is different from a `LoaderTS`.
+ * however, the former is not exposed as a loader in javascript, where as the latter is.
+ * for now, I'm setting both `".cts"` and `".mts"` to load via the `"ts"` loader, but I don't know if there will be any negative consequences of this later.
+*/
+export const defaultExtensionToLoaderMap = {
+    "": undefined,
+    ".js": "js",
+    ".mjs": "js",
+    ".cjs": "js",
+    ".jsx": "jsx",
+    ".ts": "ts",
+    ".cts": "ts",
+    ".mts": "js",
+    ".tsx": "tsx",
+    ".css": "css",
+    ".module.css": "local-css",
+    ".json": "json",
+    ".txt": "text",
+};

package/esm/esbuild/weaktypes.d.ts

@@ -0,0 +1,46 @@
+/** this module contains esbuild type definitions that are compatible with multiple versions of esbuild.
+ *
+ * this file is a partial copy from my `@oazmi/esbuild-plugin-deno` esbuild plugin's `typedefs` file.
+ * here's the original source: [github](https://github.com/oazmi/esbuild-plugin-deno/blob/b20109988a7245804b52e219ca0f2948fa4012ba/src/plugins/typedefs.ts).
+ *
+ * @module
+*/
+import type { AutoSuggestOrString, MaybePromise } from "../deps.js";
+import type { EsbuildBuildOptions, EsbuildBuildResult, EsbuildLoaderType, EsbuildMessage, EsbuildPluginBuild, OnLoadResult, SameShape } from "./strongtypes.js";
+/** weakly typed alias for `esbuild.Plugin`, so that it is compatible over all versions of esbuild. */
+export type EsbuildPluginCompatible = {
+    name: string;
+    setup: EsbuildPluginSetupCompatible;
+};
+/** weakly typed alias for `esbuild.Plugin["setup"]`, so that it is compatible over all versions of esbuild. */
+export type EsbuildPluginSetupCompatible = (build: EsbuildPluginBuildCompatible) => MaybePromise<void>;
+/** weakly typed alias for `esbuild.PluginBuild`, so that it is compatible over all versions of esbuild. */
+export type EsbuildPluginBuildCompatible = Omit<{
+    [K in keyof EsbuildPluginBuild]: any;
+}, "onLoad"> & {
+    onLoad: (options: any, callback: (args: any) => MaybePromise<OnLoadResult | null | undefined>) => void;
+};
+/** weakly typed alias for `esbuild.BuildOptions`, so that it is compatible over all versions of esbuild. */
+export type EsbuildBuildOptionsCompatible = Omit<EsbuildBuildOptions, "alias" | "incremental" | "watch" | "packages" | "entryPoints" | "plugins"> & {
+    alias?: any;
+    incremental?: any;
+    watch?: any;
+    packages?: any;
+    entryPoints?: any;
+};
+/** weakly typed alias for `esbuild.BuildResult`, so that it is compatible over all versions of esbuild. */
+export type EsbuildBuildResultCompatible = EsbuildBuildResult<EsbuildBuildOptionsCompatible>;
+/** weakly typed alias for `esbuild.build`, so that it is compatible over all versions of esbuild. */
+export type EsbuildBuildCompatible = <T extends EsbuildBuildOptionsCompatible>(options: SameShape<EsbuildBuildOptionsCompatible, T>) => Promise<EsbuildBuildResult<T>>;
+/** weakly typed alias for `esbuild.Loader`.
+ * (though, technically it is a super-type, therefore incompatible with old esbuild versions.)
+*/
+export type EsbuildLoaderTypeCompatible = AutoSuggestOrString<EsbuildLoaderType>;
+/** weakly typed alias for `esbuild.Message`, so that it is compatible over all versions of esbuild.
+ *
+ * > [!note]
+ * > the type interface hasn't changed since `v0.15.0` through the current version (`v0.28.0`).
+ * > so for now, this type is exactly equivalent to `esbuild.Message` (i.e. not weakly typed at all).
+*/
+export type EsbuildMessageCompatible = EsbuildMessage;
+//# sourceMappingURL=weaktypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"weaktypes.d.ts","sourceRoot":"","sources":["../../src/esbuild/weaktypes.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAG/J,sGAAsG;AACtG,MAAM,MAAM,uBAAuB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,4BAA4B,CAAA;CACnC,CAAA;AAED,+GAA+G;AAC/G,MAAM,MAAM,4BAA4B,GAAG,CAAC,KAAK,EAAE,4BAA4B,KAAK,YAAY,CAAC,IAAI,CAAC,CAAA;AAEtG,2GAA2G;AAC3G,MAAM,MAAM,4BAA4B,GAAG,IAAI,CAAC;KAAG,CAAC,IAAI,MAAM,kBAAkB,GAAG,GAAG;CAAE,EAAE,QAAQ,CAAC,GAAG;IACrG,MAAM,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,YAAY,CAAC,YAAY,GAAG,IAAI,GAAG,SAAS,CAAC,KAAK,IAAI,CAAA;CACtG,CAAA;AAED,4GAA4G;AAC5G,MAAM,MAAM,6BAA6B,GAAG,IAAI,CAAC,mBAAmB,EAAE,OAAO,GAAG,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,CAAC,GAAG;IACnJ,KAAK,CAAC,EAAE,GAAG,CAAA;IACX,WAAW,CAAC,EAAE,GAAG,CAAA;IACjB,KAAK,CAAC,EAAE,GAAG,CAAA;IACX,QAAQ,CAAC,EAAE,GAAG,CAAA;IACd,WAAW,CAAC,EAAE,GAAG,CAAA;CACjB,CAAA;AAED,2GAA2G;AAC3G,MAAM,MAAM,4BAA4B,GAAG,kBAAkB,CAAC,6BAA6B,CAAC,CAAA;AAE5F,qGAAqG;AACrG,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,SAAS,6BAA6B,EAAE,OAAO,EAAE,SAAS,CAAC,6BAA6B,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAA;AAEtK;;EAEE;AACF,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,CAAC,iBAAiB,CAAC,CAAA;AAEhF;;;;;EAKE;AACF,MAAM,MAAM,wBAAwB,GAAG,cAAc,CAAA"}

package/esm/esbuild/weaktypes.js

@@ -0,0 +1,8 @@
+/** this module contains esbuild type definitions that are compatible with multiple versions of esbuild.
+ *
+ * this file is a partial copy from my `@oazmi/esbuild-plugin-deno` esbuild plugin's `typedefs` file.
+ * here's the original source: [github](https://github.com/oazmi/esbuild-plugin-deno/blob/b20109988a7245804b52e219ca0f2948fa4012ba/src/plugins/typedefs.ts).
+ *
+ * @module
+*/
+export {};