From 781c81c19210874d06aafb2b010d51f267884609 Mon Sep 17 00:00:00 2001
From: Omar Azmi <64020006+omar-azmi@users.noreply.github.com>
Date: Thu, 28 Nov 2024 09:46:44 -0500
Subject: [PATCH] - add missing type annotations to functions and missing doc
 comments, so that the jsr score is boosted to 100%. - ready for publishing
 version `0.1.0`.

---
 src/fs.ts       |  5 +++--
 src/funcdefs.ts | 13 ++++++++++++-
 src/typedefs.ts |  9 +++++++++
 3 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/src/fs.ts b/src/fs.ts
index 5536a37..4ce67d9 100644
--- a/src/fs.ts
+++ b/src/fs.ts
@@ -11,12 +11,12 @@ import { console_log, ensureEndSlash, pathToPosixPath, promise_all, resolvePathF
 
 
 /** get the current working directory (`Deno.cwd`) in posix path format. */
-export const getCwdPath = () => { return ensureEndSlash(pathToPosixPath(Deno.cwd())) }
+export const getCwdPath = (): string => { 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 = resolvePathFactory(getCwdPath)
+export const pathResolve: ((...segments: string[]) => string) = 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,
@@ -98,6 +98,7 @@ export const createFiles = async (virtual_files: Array<WritableFileConfig>, conf
 	}))
 }
 
+/** write `esbuild` output files (`BuildResult.outputFiles`) to the filesystem. */
 export const writeOutputFiles = async (virtual_files: Array<EsbuildOutputFile>, config: CreateFilesConfig = {}): Promise<void> => {
 	return createFiles(virtual_files.map((virtual_file): WritableFileConfig => {
 		const
diff --git a/src/funcdefs.ts b/src/funcdefs.ts
index 668341c..95c80d1 100644
--- a/src/funcdefs.ts
+++ b/src/funcdefs.ts
@@ -3,7 +3,18 @@ import { math_min } from "./deps.ts"
 
 const escape_regex_chars_regex = /[.*+?^${}()|[\]\\]/g
 
-export const escapeStringForRegex = (str: string) => (str.replaceAll(escape_regex_chars_regex, "\\$&"))
+/** escape a string so that it can be matched exactly in a regex constructor.
+ * 
+ * @example
+ * ```ts
+ * const
+ * 	substring = "(++h.e.l.l.o++)",
+ * 	my_regex = new RegExp(`${substring}\(world\)`),
+ * 	my_str = "this string consist of (++h.e.l.l.o++)(world) positioned somewhere in the middle"
+ * console.assert(my_regex.test(my_str) === true)
+ * ```
+*/
+export const escapeStringForRegex = (str: string): string => (str.replaceAll(escape_regex_chars_regex, "\\$&"))
 
 /** create a mapping function that operates on a list or array inputs that are zipped together as tuples. */
 export const zipArraysMapperFactory = <T extends Array<any>, V>(
diff --git a/src/typedefs.ts b/src/typedefs.ts
index 638c185..9207edd 100644
--- a/src/typedefs.ts
+++ b/src/typedefs.ts
@@ -27,15 +27,23 @@ export interface GenericLoaderConfig {
 	mode?: "bundle" | "inject" | "inject-link"
 }
 
+/** 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<string>
+	/** 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
@@ -49,4 +57,5 @@ export interface ImportMetadataEntry<K = string> {
 	out: string
 }
 
+/** an array of metadata entries {@link ImportMetadataEntry}. */
 export type ImportMetadata<K = string> = Array<ImportMetadataEntry<K>>