@gesslar/bedoc 1.0.0

package/src/core/util/FDUtil.js

@@ -0,0 +1,322 @@
+import fs from "fs"
+import {globby} from "globby"
+import path from "node:path"
+import process from "node:process"
+import {fileURLToPath, pathToFileURL} from "node:url"
+
+import * as DataUtil from "./DataUtil.js"
+import * as ValidUtil from "./ValidUtil.js"
+
+const {isArrayUniform, isType, allocateObject} = DataUtil
+const {validType} = ValidUtil
+
+const freeze = (ob) => Object.freeze(ob)
+
+const fdTypes = freeze(["file", "directory"])
+const upperFdTypes = freeze(fdTypes.map((type) => type.toUpperCase()))
+const fdType = freeze(await allocateObject(upperFdTypes, fdTypes))
+
+/**
+ * Fix slashes in a path
+ *
+ * @param {string} pathName - The path to fix
+ * @returns {string} The fixed path
+ */
+function fixSlashes(pathName) {
+  return pathName.replace(/\\/g, "/")
+}
+
+/**
+ * Convert a path to a URI
+ *
+ * @param {string} pathName - The path to convert
+ * @returns {string} The URI
+ * @throws {Error} If the path is not a valid file path
+ */
+function pathToUri(pathName) {
+  try {
+    return pathToFileURL(pathName).href
+  } catch(e) {
+    void e // stfu linter
+    return pathName
+  }
+}
+
+/**
+ * Convert a URI to a path
+ *
+ * @param {string} pathName - The URI to convert
+ * @returns {string} The path
+ * @throws {Error} If the URI is not a valid file URL
+ */
+function uriToPath(pathName) {
+  try {
+    return fileURLToPath(pathName)
+  } catch(e) {
+    void e // did you hear me?? i said stfu!
+    return pathName
+  }
+}
+
+/**
+ * Resolves a file to an absolute path
+ *
+ * @param {string} fileName - The file to resolve
+ * @param {object} [directoryObject] - The directory object to resolve the
+ *                                     file in
+ * @returns {object} A file object (validated)
+ * @throws {Error}
+ */
+function resolveFilename(fileName, directoryObject = null) {
+  validType(fileName, "string", {allowEmpty: false}, 1)
+
+  fileName = uriToPath(fileName)
+  const fixedFileName = fixSlashes(fileName)
+  const directoryNamePart = fixedFileName.split("/").slice(0, -1).join("/")
+  const fileNamePart = fixedFileName.split("/").pop()
+  if(!directoryObject)
+    directoryObject = resolveDirectory(directoryNamePart)
+
+  const fileObject = composeFilename(directoryObject, fileNamePart)
+  try {
+    fs.opendirSync(directoryObject.absolutePath).closeSync()
+  } catch(e) {
+    void e
+    throw new Error(
+      `Failed to resolve directory: ${directoryObject.absolutePath}, looking for file: ${fileNamePart}`,
+    )
+  }
+
+  return {
+    ...fileObject,
+    directory: directoryObject,
+  }
+}
+
+/**
+ * Compose a file path from a directory and a file
+ *
+ * @param {string|object} directoryNameorObject - The directory
+ * @param {string} fileName - The file
+ * @returns {object} A file object
+ */
+function composeFilename(directoryNameorObject, fileName) {
+  let dirObject
+
+  if(isType(directoryNameorObject, "string|string[]")) {
+    dirObject = composeDirectory(directoryNameorObject)
+  } else {
+    if(!directoryNameorObject.isDirectory)
+      throw new Error("Directory object is not a directory")
+
+    dirObject = directoryNameorObject
+  }
+
+  fileName = path.resolve(dirObject.path, fileName)
+
+  return mapFilename(fileName)
+}
+
+/**
+ * Map a file to a FileMap
+ *
+ * @param {string} fileName - The file to map
+ * @returns {object} A file object
+ */
+function mapFilename(fileName) {
+  return {
+    path: fileName,
+    uri: pathToUri(fileName),
+    absolutePath: path.resolve(process.cwd(), fileName),
+    absoluteUri: pathToUri(path.resolve(process.cwd(), fileName)),
+    name: path.basename(fileName),
+    module: path.basename(fileName, path.extname(fileName)),
+    extension: path.extname(fileName),
+    isFile: true,
+    isDirectory: false,
+  }
+}
+
+/**
+ * Map a directory to a DirMap
+ *
+ * @param {string} directoryName - The directory to map
+ * @returns {object} A directory object
+ */
+function mapDirectory(directoryName) {
+  return {
+    path: directoryName,
+    uri: pathToUri(directoryName),
+    absolutePath: path.resolve(process.cwd(), directoryName),
+    absoluteUri: pathToUri(path.resolve(process.cwd(), directoryName)),
+    name: path.basename(directoryName),
+    separator: path.sep,
+    isFile: false,
+    isDirectory: true,
+  }
+}
+
+/**
+ * Deconstruct a filename into parts
+ *
+ * @param {string} fileName - The filename to deconstruct
+ * @returns {object} The filename parts
+ */
+function deconstructFilenameToParts(fileName) {
+  const {basename, dirname, extname} = path.parse(fileName)
+
+  return {basename, dirname, extname}
+}
+
+/**
+ * Retrieve all files matching a specific glob pattern.
+ *
+ * @param {string|string[]} globPattern - The glob pattern(s) to search.
+ * @returns {Promise<object[]>} An array of file objects
+ * @throws {Error} Throws an error for invalid input or search failure.
+ */
+async function getFiles(globPattern) {
+  // Validate input
+  validType(globPattern, "string|string[]", {allowEmpty: false})
+
+  const globbyArray = (
+    isType(globPattern, "array")
+      ? globPattern
+      : globPattern
+        .split("|")
+        .map((g) => g.trim())
+        .filter(Boolean)
+  ).map((g) => fixSlashes(g))
+
+  if(
+    Array.isArray(globbyArray) &&
+    isArrayUniform(globbyArray, "string", true) &&
+    !globbyArray.length
+  )
+    throw new Error(
+      "[getFiles] Invalid glob pattern: Array must contain only strings.",
+    )
+
+  // Use Globby to fetch matching files
+  const filesArray = await globby(globbyArray)
+  const files = filesArray.map((file) => mapFilename(file))
+
+  // Flatten the result and remove duplicates
+  return files
+}
+
+/**
+ * Resolves a path to an absolute path
+ *
+ * @param {string} directoryName - The path to resolve
+ * @returns {object} The directory object
+ * @throws {Error}
+ */
+function resolveDirectory(directoryName) {
+  validType(directoryName, "string", true)
+
+  const directoryObject = mapDirectory(directoryName)
+
+  try {
+    fs.opendirSync(directoryObject.absolutePath).closeSync()
+  } catch(e) {
+    throw new Error(
+      `Failed to resolve directory: ${directoryObject.absolutePath}, looking for file: ${directoryName}\n${e.message}`,
+    )
+  }
+
+  fs.opendirSync(directoryObject.absolutePath).closeSync()
+
+  return directoryObject
+}
+
+/**
+ * Compose a directory map from a path
+ *
+ * @param {string} directory - The directory
+ * @returns {object} A directory object
+ */
+function composeDirectory(directory) {
+  return mapDirectory(directory)
+}
+
+/**
+ * Lists the contents of a directory.
+ *
+ * @param {string} directory - The directory to list.
+ * @returns {Promise<{files: object[], directories: object[]}>} The files and
+ * directories in the directory.
+ */
+async function ls(directory) {
+  const found = await fs.promises.readdir(directory, {withFileTypes: true})
+  const results = await Promise.all(
+    found.map(async(dirent) => {
+      const fullPath = path.join(directory, dirent.name)
+      const stat = await fs.promises.stat(fullPath)
+      return {dirent, stat, fullPath}
+    }),
+  )
+
+  const files = results
+    .filter(({stat}) => stat.isFile())
+    .map(({fullPath}) => mapFilename(fullPath))
+
+  const directories = results
+    .filter(({stat}) => stat.isDirectory())
+    .map(({fullPath}) => mapDirectory(fullPath))
+
+  return {files, directories}
+}
+
+/**
+ * Reads the content of a file synchronously.
+ *
+ * @param {object} fileObject - The file map containing the file path
+ * @returns {Promise<string>} The file contents
+ */
+function readFile(fileObject) {
+  const {absolutePath} = fileObject
+
+  if(!absolutePath)
+    throw new Error("No absolute path in file map")
+
+  const content = fs.readFileSync(absolutePath, "utf8")
+
+  return content
+}
+
+/**
+ * Writes content to a file synchronously.
+ *
+ * @param {object} fileObject - The file map containing the file path
+ * @param {string} content - The content to write
+ */
+function writeFile(fileObject, content) {
+  const absolutePath = fileObject.absolutePath
+
+  if(!absolutePath)
+    throw new Error("No absolute path in file map")
+
+  fs.writeFileSync(absolutePath, content, "utf8")
+}
+
+export {
+  // Constants
+  fdType,
+  fdTypes,
+  // Functions
+  composeDirectory,
+  composeFilename,
+  deconstructFilenameToParts,
+  fixSlashes,
+  getFiles,
+  ls,
+  mapDirectory,
+  mapFilename,
+  pathToUri,
+  readFile,
+  resolveDirectory,
+  resolveFilename,
+  uriToPath,
+  writeFile,
+}

package/src/core/util/ModuleUtil.js

@@ -0,0 +1,39 @@
+import {createRequire} from "module"
+import FDUtil from "./FDUtil.js"
+
+export default class ModuleUtil {
+  /**
+   * Requires a module synchronously
+   *
+   * @param {object} fileObject - The file to require
+   * @returns {object} The required module
+   */
+  static require(fileObject) {
+    return createRequire(import.meta.url)(fileObject.absolutePath)
+  }
+
+  /**
+   * Loads a JSON file asynchronously
+   *
+   * @param {object} jsonFileObject - The JSON file to load
+   * @returns {Promise<object>} The parsed JSON content
+   */
+  static async loadJson(jsonFileObject) {
+    // Read the file
+    const jsonContent = await FDUtil.readFile(jsonFileObject)
+    const json = JSON.parse(jsonContent)
+    return json
+  }
+
+  /**
+   * Loads the package.json file asynchronously
+   *
+   * @returns {Promise<object>} The parsed package.json content
+   */
+  static async loadPackageJson() {
+    const packageJsonFileObject = FDUtil.resolveFilename("./package.json")
+    const jsonContent = await FDUtil.readFile(packageJsonFileObject)
+    const json = JSON.parse(jsonContent)
+    return json
+  }
+}

package/src/core/util/StringUtil.js

@@ -0,0 +1,11 @@
+/**
+ * Capitalizes the first letter of a string
+ *
+ * @param {string} str - The string to capitalize
+ * @returns {string} The capitalized string
+ */
+function capitalize(str) {
+  return `${str.charAt(0).toUpperCase()}${str.slice(1)}`
+}
+
+export {capitalize}

package/src/core/util/TypeSpec.js

@@ -0,0 +1,114 @@
+import * as DataUtil from "./DataUtil.js"
+
+const {isEmpty, typeOf, isArrayUniform, isValidType} = DataUtil
+
+export default class TypeSpec {
+  #specs
+
+  constructor(string, options) {
+    this.#specs = []
+    this.#parse(string, options)
+    Object.freeze(this.#specs)
+    this.specs = this.#specs
+    this.length = this.#specs.length
+    this.stringRepresentation = this.toString()
+    Object.freeze(this)
+  }
+
+  toString() {
+    return this.#specs
+      .map((spec) => {
+        return `${spec.typeName}${spec.array ? "[]" : ""}`
+      })
+      .join("|")
+  }
+
+  toJSON() {
+    // Serialize as a string representation or as raw data
+    return {
+      specs: this.#specs,
+      length: this.length,
+      stringRepresentation: this.toString(),
+    }
+  }
+
+  forEach(callback) {
+    this.#specs.forEach(callback)
+  }
+  every(callback) {
+    return this.#specs.every(callback)
+  }
+  some(callback) {
+    return this.#specs.some(callback)
+  }
+  filter(callback) {
+    return this.#specs.filter(callback)
+  }
+  map(callback) {
+    return this.#specs.map(callback)
+  }
+  reduce(callback, initialValue) {
+    return this.#specs.reduce(callback, initialValue)
+  }
+  find(callback) {
+    return this.#specs.find(callback)
+  }
+
+  match(value, options) {
+    const allowEmpty = options?.allowEmpty ?? true
+    const empty = isEmpty(value)
+
+    // If we have a list of types, because the string was validly parsed,
+    // we need to ensure that all of the types that were parsed are valid types
+    // in JavaScript.
+    if(this.length && !this.every((t) => isValidType(t.typeName)))
+      return false
+
+    // Now, let's do some checking with the types, respecting the array flag
+    // with the value
+    const valueType = typeOf(value)
+    const isArray = valueType === "array"
+
+    // We need to ensure that we match the type and the consistency of the types
+    // in an array, if it is an array and an array is allowed.
+    const matchingTypeSpec = this.filter((spec) => {
+      const {typeName: allowedType, array: allowedArray} = spec
+
+      if(valueType === allowedType && !isArray && !allowedArray)
+        return !allowEmpty ? !empty : true
+
+      if(isArray) {
+        if(allowedType === "array")
+          if(!allowedArray)
+            return true
+
+        if(empty)
+          if(allowEmpty)
+            return true
+
+        return isArrayUniform(value, allowedType)
+      }
+    })
+
+    return matchingTypeSpec.length > 0
+  }
+
+  #parse(string, options) {
+    const delimiter = options?.delimiter ?? "|"
+    const parts = string.split(delimiter)
+
+    this.#specs = parts.map((part) => {
+      const typeMatches = /(\w+)(\[\])?/.exec(part)
+      if(!typeMatches || typeMatches.length !== 3)
+        throw new TypeError(`Invalid type: ${part}`)
+
+      if(!isValidType(typeMatches[1]))
+        throw new TypeError(`Invalid type: ${typeMatches[1]}`)
+
+      return {
+        typeName: typeMatches[1],
+        array: typeMatches[2] === "[]",
+      }
+    })
+  }
+}

package/src/core/util/ValidUtil.js

@@ -0,0 +1,50 @@
+import _assert from "node:assert/strict"
+
+import * as DataUtil from "./DataUtil.js"
+
+const {isType} = DataUtil
+
+/**
+ * Validates a value against a type
+ *
+ * @param {*} value - The value to validate
+ * @param {string} type - The expected type in the form of "object",
+ *                        "object[]", "object|object[]"
+ * @param {object} [options] - Additional options for validation.
+ */
+function validType(value, type, options) {
+  assert(
+    isType(value, type, options),
+    `Invalid type. Expected ${type}, got ${JSON.stringify(value)}`,
+    1,
+  )
+}
+
+/**
+ * Asserts a condition
+ *
+ * @param {boolean} condition - The condition to assert
+ * @param {string} message - The message to display if the condition is not
+ *                           met
+ * @param {number} [arg] - The argument to display if the condition is not
+ *                         met (optional)
+ */
+function assert(condition, message, arg = null) {
+  _assert(
+    isType(condition, "boolean"),
+    `Condition must be a boolean, got ${condition}`,
+  )
+  _assert(
+    isType(message, "string"),
+    `Message must be a string, got ${message}`,
+  )
+  _assert(
+    arg !== null && isType(arg, "number"),
+    `Arg must be a number, got ${arg}`,
+  )
+
+  if(!condition)
+    throw new Error(`${message}${arg ? `: ${arg}` : ""}`)
+}
+
+export {assert, validType}