- add a few missing doc comments to boost jsr score.

- in `/examples/1_html/build.ts`:
  - add option for dry-running the build script (no writes done to filesystem).
  - make sure that the output directory is first emptied.

examples/1_html/build.ts

@@ -1,4 +1,5 @@
 import { denoPlugins } from "jsr:@luca/[email protected]"
+import { emptyDir } from "jsr:@std/fs"
 import { fromFileUrl } from "jsr:@std/path"
 import esbuild from "npm:esbuild"
 import { resolveAsUrl } from "../../src/deps.ts"
@@ -7,6 +8,7 @@ import { HtmlLoader } from "./loader.ts"
 
 
 const
+	dryrun = false,
 	this_dir_path = resolveAsUrl("./", import.meta.url),
 	html_file_path = resolveAsUrl("./input/index.html", this_dir_path),
 	html_file_content = await (await fetch(html_file_path)).text()
@@ -46,13 +48,16 @@ other_output_files.forEach((js_file, index) => {
 	console.log(js_file.text)
 })
 
+const abs_output_dir = fromFileUrl(resolveAsUrl("./output/", this_dir_path))
+console.log(`clearing out the output directory: "${abs_output_dir}"`)
+if (!dryrun) { await emptyDir(abs_output_dir) }
 await writeOutputFiles([
 	{
 		path: html_in_js_compiled.path.replace(/\.js$/, ".html"),
 		text: html_compiled_text
 	}, ...other_output_files
 ], {
-	dir: "./output/",
+	dir: abs_output_dir,
 	log: "verbose",
-	dryrun: false,
+	dryrun,
 })

src/fs.ts

@@ -8,15 +8,14 @@
 
 import { ensureFile } from "jsr:@std/[email protected]"
 import { console_log, ensureEndSlash, pathToPosixPath, promise_all, resolvePathFactory } from "./deps.ts"
+import type { AbsolutePath, Path, RelativePath } from "./typedefs.ts"
 
 
 /** get the current working directory (`Deno.cwd`) in posix path format. */
-export const getCwdPath = (): string => { return ensureEndSlash(pathToPosixPath(Deno.cwd())) }
+export const getCwdPath = (): AbsolutePath => { return ensureEndSlash(pathToPosixPath(Deno.cwd())) }
 
-/** resolve a file path so that it becomes absolute, with unix directory separator ("/").
- * TODO: refactor the name `pathResolve` to `resolvePath`
-*/
-export const pathResolve: ((...segments: string[]) => string) = resolvePathFactory(getCwdPath)
+/** resolve a file path so that it becomes absolute, with unix directory separator ("/"). */
+export const resolvePath: ((...segments: Path[]) => AbsolutePath) = resolvePathFactory(getCwdPath)
 
 /** the tuple description of a writable (or appendable) file.
  * - the first entry of the array must describe the destination path of the file,
@@ -26,7 +25,7 @@ export const pathResolve: ((...segments: string[]) => string) = resolvePathFacto
  *   such as `"append"` the new text, or permit the creation (`"create"`) of new file if it doesn't exist, etc...
 */
 export type WritableFileConfig = [
-	destination: string,
+	destination: RelativePath,
 	content: string | Uint8Array,
 	options?: Deno.WriteFileOptions,
 ]
@@ -36,7 +35,7 @@ export interface CreateFilesConfig {
 	/** the desired output directory.
 	 * if a relative path is provided, then it will be resolved as a path relative to Deno's current working directory. (which is generally where `deno.json` resides.)
 	*/
-	dir?: string
+	dir?: Path
 
 	/** select logging level:
 	 * - `false` or `"none"`: skip logging.
@@ -56,7 +55,7 @@ export interface CreateFilesConfig {
 
 /** the in-memory output file description generated by `esbuild`. */
 export interface EsbuildOutputFile {
-	path: string
+	path: AbsolutePath
 	text?: string
 	contents?: Uint8Array
 	hash?: string
@@ -85,7 +84,7 @@ export const createFiles = async (virtual_files: Array<WritableFileConfig>, conf
 	// writing text or binary files
 	logBasic(log, "[in-fs] writing additional text/binary files to your build directory")
 	await promise_all(virtual_files.map(async ([dst_path, content, options]) => {
-		const abs_dst = pathResolve(dir, dst_path)
+		const abs_dst = resolvePath(dir, dst_path)
 		logVerbose(log, `[in-fs] writing file to: "${abs_dst}"`, "with the configuration:", options)
 		if (!dryrun) {
 			await ensureFile(abs_dst)

src/typedefs.ts

@@ -5,10 +5,18 @@
 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}.
 	 * 
@@ -32,7 +40,7 @@ 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<string>
+	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.
 	*/
@@ -52,9 +60,9 @@ 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: string
-	/** the output bundled path of the import link. */
-	out: string
+	in: Path
+	/** the output bundled path of the import link. typically generated by esbuild. */
+	out: AbsolutePath
 }
 
 /** an array of metadata entries {@link ImportMetadataEntry}. */