typedefs.ts

/** this module contains base type definitions.
 * 
 * @module
*/
import type { GenericLoader } from "./loader.ts"


/** type annotation for a relative path. */
export type RelativePath = string

/** type annotation for an absolute path. */
export type AbsolutePath = string

/** type annotation for any kind path. */
export type Path = RelativePath | AbsolutePath

/** an interface for configuring subclasses of {@link GenericLoader}.
 * note that {@link GenericLoader} itself does not make use of any of this information, which is why they're optional.
*/
export interface GenericLoaderConfig {
	/** the absolute path of the file that you are providing the contents of to {@link GenericLoader}.
	 * 
	 * this value is used for deducing the directory in which the html exists, so that any relative references made in the html file will be discoverable. <br>
	 * if no path is provided, then it will be assumed that the html file exists in the current working directory (i.e. something like `"./index.html"`). <br>
	 * the absolute path can also use a uri scheme like `"http://"` or `"jsr:"` or `"file://"`, but if a relative path was provided,
	 * we would again assume that it is relative to the current working directory.
	*/
	path?: AbsolutePath

	/** TODO: define how the file should bundle its dependencies:
	 * - `"bundle"` | `undefined`: the file will reference its entry points will be bundled as separate files, inheriting the basename of the importer javascript.
	 * - `"inject"`: any referenced files via `<script src="./file.js">` or `<link rel="stylesheet" href="./file.css">` will get injected be bundled into a string literal, which will then get injected into your html `document`'s head as a `<style>` element.
	 * - `"inject-link"`: similar to `"bundle"`, but will also inject a `<link>` element into your `document`'s head that link's to the output bundled file.
	*/
	mode?: "bundle" | "inject" | "inject-link"

	/** enable or disable meta data generation and verification in {@link GenericLoader.meta}.
	 * 
	 * this is useful when developing plugins, because that way the {@link GenericLoader} baseclass can ensure that you are accounting for all dependencies when unparsing, based on the parsing step.
	 * however, this also means that you would be forced to use the same loader object for parsing and unparsing, even if the loader parsing and unparsing steps are functionally pure (the baseclass is also pure, unless `meta` is enabled).
	 * so, in order to use the {@link GenericLoader.parseToJs} and {@link GenericLoader.unparseFromJs} methods arbitrarily anywhere (i.e. stateless, loader-object wise) without having errors throw to you,
	 * you will have to explicitly disable this config option (i.e. set it to `false`).
	 * 
	 * @defaultValue `true`
	*/
	meta: boolean
}

/** an interface that describes the dependencies and contents of a single file that is parsed by your loader's {@link GenericLoader.extractDeps} method. */
export interface ContentDependencies<K = string> {
	/** an ordered list of unique json-encodable key assigned for each dependency path. */
	importKeys: Array<K>
	/** an ordered list of dependency paths that your file requires for bundling. */
	importPaths: Array<Path>
	/** the contents of your loaded file, further transformed to replace the {@link importPaths | import-paths}
	 * with {@link importKeys | unique-keys} that are easily identifiable and replaceable later on.
	*/
	content: string
}

/** an interface similar to {@link ContentDependencies}, but with its {@link content} now containing javascript code that can be dynamically imported. */
export interface ScriptWrappedContent<K = string> extends ContentDependencies<K> {
	content: string
}

/** an entry in {@link GenericLoader.meta["imports"]} that specifies the transformation of a dependency path, after the unparsing is complete.
 * 
 * @typeParam K the key `K` must be a json encodable key
*/
export interface ImportMetadataEntry<K = string> {
	/** unique key assigned by the dependency extractor method {@link GenericLoader.extractDeps}. */
	key: K
	/** the original path of the import link. */
	in: Path
	/** the output bundled path of the import link. typically generated by esbuild. */
	out: AbsolutePath
}

/** an array of metadata entries {@link ImportMetadataEntry}. */
export type ImportMetadata<K = string> = Array<ImportMetadataEntry<K>>