From 07aec00401c7fff6f9a8f07572490a5835dcec5c Mon Sep 17 00:00:00 2001 From: Omar Azmi <64020006+omar-azmi@users.noreply.github.com> Date: Fri, 29 Nov 2024 23:17:41 -0500 Subject: [PATCH] - 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 | 9 +++++++-- src/fs.ts | 17 ++++++++--------- src/typedefs.ts | 16 ++++++++++++---- 3 files changed, 27 insertions(+), 15 deletions(-) diff --git a/examples/1_html/build.ts b/examples/1_html/build.ts index 0608b29..c72c5eb 100644 --- a/examples/1_html/build.ts +++ b/examples/1_html/build.ts @@ -1,4 +1,5 @@ import { denoPlugins } from "jsr:@luca/esbuild-deno-loader@0.11.0" +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, }) diff --git a/src/fs.ts b/src/fs.ts index 4ce67d9..3c54c1e 100644 --- a/src/fs.ts +++ b/src/fs.ts @@ -8,15 +8,14 @@ import { ensureFile } from "jsr:@std/fs@1.0.6" 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, 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) diff --git a/src/typedefs.ts b/src/typedefs.ts index 9207edd..1ce2867 100644 --- a/src/typedefs.ts +++ b/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 { /** an ordered list of unique json-encodable key assigned for each dependency path. */ importKeys: Array /** an ordered list of dependency paths that your file requires for bundling. */ - importPaths: Array + importPaths: Array /** 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 { /** 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}. */