@gesslar/bedoc 1.11.0 → 2.1.0

package/src/core/util/FDUtil.js

@@ -1,388 +0,0 @@
-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
-  }
-}
-
-/**
- * Check if a file can be read. Returns true if the file can be read, false
- *
- * @param {FileMap} FileMap - The file map to check
- * @returns {boolean} Whether the file can be read
- */
-function canReadFile(FileMap) {
-  try {
-    fs.accessSync(FileMap.absolutePath, fs.constants.R_OK)
-    return true
-  } catch(_error) {
-    return false
-  }
-}
-
-/**
- * Check if a file can be written. Returns true if the file can be written,
- *
- * @param {FileMap} FileMap - The file map to check
- * @returns {boolean} Whether the file can be written
- */
-function canWriteFile(FileMap) {
-  try {
-    fs.accessSync(FileMap.absolutePath, fs.constants.W_OK)
-    return true
-  } catch(_error) {
-    return false
-  }
-}
-
-/**
- * Check if a file exists
- *
- * @param {FileMap} FileMap - The file map to check
- * @returns {boolean} Whether the file exists
- */
-function fileExists(FileMap) {
-  try {
-    fs.accessSync(FileMap.absolutePath)
-    return true
-  } catch(_error) {
-    return false
-  }
-}
-
-/**
- * Check if a directory exists
- *
- * @param {object} DirectoryMap - The directory map to check
- * @returns {boolean} Whether the directory exists
- */
-function directoryExists(DirectoryMap) {
-  try {
-    fs.accessSync(DirectoryMap.absolutePath)
-    return true
-  } catch(_error) {
-    return false
-  }
-}
-
-/**
- * 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)
-
-  if(!fileObject)
-    throw new Error(
-      `Failed to resolve file: ${fileName}, looking for file: ${fileNamePart}`,
-    )
-
-  if(!fileExists(fileObject))
-    throw new Error(
-      `Failed to resolve file: ${fileObject.absolutePath}`,
-    )
-
-  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(
-      `Invalid glob pattern: Array must contain only strings. Got ${JSON.stringify(globPattern)}`,
-    )
-
-  // 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 {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
-  canReadFile,
-  canWriteFile,
-  composeDirectory,
-  composeFilename,
-  deconstructFilenameToParts,
-  directoryExists,
-  fileExists,
-  fixSlashes,
-  getFiles,
-  ls,
-  mapDirectory,
-  mapFilename,
-  pathToUri,
-  readFile,
-  resolveDirectory,
-  resolveFilename,
-  uriToPath,
-  writeFile,
-}

package/src/core/util/StringUtil.js

@@ -1,11 +0,0 @@
-/**
- * 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

@@ -1,114 +0,0 @@
-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

@@ -1,50 +0,0 @@
-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}