@gesslar/toolkit 0.0.1

package/README.md

@@ -0,0 +1,20 @@
+# @gesslar/toolkit
+
+This package is intended to be a collection of useful utilities for any
+project's consumption. Not the kind that gives you bleeding, hacking coughs,
+but the kind that says "yumyum."
+
+There are file and directory abstractions, uhmm, there's also some terminal
+things and validity checkers, lots of data functions.
+
+Basically, if you want it, it is most definitely here, and working 100% and
+absolutely none of that is true. There are only a few classes here, but they're
+pretty. And if you bug-shame them, I will _come for you like_ ...
+
+nah. Just don't be a dick, okay? Play nice, share, lick a veggie and gentlemen,
+spend less than 5 minutes washing your pits, chest, and downstairs and maybe
+give some time to the other parts. Like the parts that walk on things, sit
+on things. Some things that enjoy being sat upon do not enjoy being sat upon
+by gross sitter-upon-things.
+
+Also,

package/UNLICENSE.txt

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@gesslar/toolkit",
+  "version": "0.0.1",
+  "description": "Get in, bitches, we're going toolkitting.",
+  "main": "./src/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "UNLICENSE.txt"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "lint": "eslint src/",
+    "submit": "npm publish --access public",
+    "update": "npx npm-check-updates -u && npm install",
+    "test": "node examples/FileSystem/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gesslar/toolkit.git"
+  },
+  "keywords": [
+    "toolkit",
+    "utilities",
+    "file",
+    "directory",
+    "data",
+    "flavaflav",
+    "chuck",
+    "norris",
+    "validation",
+    "typescript",
+    "nodejs",
+    "iwasbornonapirateship"
+  ],
+  "author": "gesslar",
+  "license": "Unlicense",
+  "homepage": "https://github.com/gesslar/toolkit#readme",
+  "dependencies": {
+    "globby": "^14.0.2",
+    "json5": "^2.2.3",
+    "yaml": "^2.4.5"
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "^4.4.0",
+    "@types/node": "^24.2.1",
+    "@typescript-eslint/eslint-plugin": "^8.33.0",
+    "@typescript-eslint/parser": "^8.33.0",
+    "eslint": "^9.28.0",
+    "eslint-plugin-jsdoc": "^50.6.17"
+  }
+}

package/src/index.js

@@ -0,0 +1,11 @@
+// Core file system abstractions
+export {default as FileObject} from "./lib/FileObject.js"
+export {default as DirectoryObject} from "./lib/DirectoryObject.js"
+export {default as File} from "./lib/File.js"
+
+// Utility classes
+export {default as Data} from "./lib/Data.js"
+export {default as Sass} from "./lib/Sass.js"
+export {default as Term} from "./lib/Term.js"
+export {default as Type} from "./lib/Type.js"
+export {default as Valid} from "./lib/Valid.js"

package/src/lib/Data.js

@@ -0,0 +1,533 @@
+/**
+ * @file Data utility functions for type checking, object manipulation, and array operations.
+ * Provides comprehensive utilities for working with JavaScript data types and structures.
+ */
+
+import TypeSpec from "./Type.js"
+import Sass from "./Sass.js"
+import Valid from "./Valid.js"
+
+export default class Data {
+/**
+ * Array of JavaScript primitive type names.
+ * Includes basic types and object categories from the typeof operator.
+ *
+ * @type {string[]}
+ */
+  static primitives = Object.freeze([
+  // Primitives
+    "undefined",
+    "boolean",
+    "number",
+    "bigint",
+    "string",
+    "symbol",
+
+    // Object Categories from typeof
+    "object",
+    "function",
+  ])
+
+  /**
+   * Array of JavaScript constructor names for built-in objects.
+   * Includes common object types and typed arrays.
+   *
+   * @type {string[]}
+   */
+  static constructors = Object.freeze([
+  // Object Constructors
+    "Object",
+    "Array",
+    "Function",
+    "Date",
+    "RegExp",
+    "Error",
+    "Map",
+    "Set",
+    "WeakMap",
+    "WeakSet",
+    "Promise",
+    "Int8Array",
+    "Uint8Array",
+    "Float32Array",
+    "Float64Array",
+  ])
+
+  /**
+   * Combined array of all supported data types (primitives and constructors in lowercase).
+   * Used for type validation throughout the utility functions.
+   *
+   * @type {string[]}
+   */
+  static dataTypes = Object.freeze([
+    ...Data.primitives,
+    ...Data.constructors.map(c => c.toLowerCase())
+  ])
+
+  /**
+   * Array of type names that can be checked for emptiness.
+   * These types have meaningful empty states that can be tested.
+   *
+   * @type {string[]}
+   */
+  static emptyableTypes = Object.freeze(["string", "array", "object"])
+
+  /**
+   * Appends a string to another string if it does not already end with it.
+   *
+   * @param {string} string - The string to append to
+   * @param {string} append - The string to append
+   * @returns {string} The appended string
+   */
+  static appendString(string, append) {
+    return string.endsWith(append) ? string : `${string}${append}`
+  }
+
+  /**
+   * Prepends a string to another string if it does not already start with it.
+   *
+   * @param {string} string - The string to prepend to
+   * @param {string} prepend - The string to prepend
+   * @returns {string} The prepended string
+   */
+  static prependString(string, prepend) {
+    return string.startsWith(prepend) ? string : `${prepend}${string}`
+  }
+
+  /**
+   * Checks if all elements in an array are of a specified type
+   *
+   * @param {Array} arr - The array to check
+   * @param {string} type - The type to check for (optional, defaults to the
+   *                        type of the first element)
+   * @returns {boolean} Whether all elements are of the specified type
+   */
+  static isArrayUniform(arr, type) {
+    return arr.every(
+      (item, _index, arr) => typeof item === (type || typeof arr[0]),
+    )
+  }
+
+  /**
+   * Checks if an array is unique
+   *
+   * @param {Array} arr - The array of which to remove duplicates
+   * @returns {Array} The unique elements of the array
+   */
+  static isArrayUnique(arr) {
+    return arr.filter((item, index, self) => self.indexOf(item) === index)
+  }
+
+  /**
+   * Returns the intersection of two arrays.
+   *
+   * @param {Array} arr1 - The first array.
+   * @param {Array} arr2 - The second array.
+   * @returns {Array} The intersection of the two arrays.
+   */
+  static arrayIntersection(arr1, arr2) {
+    const [short,long] = [arr1,arr2].sort((a,b) => a.length - b.length)
+
+    return short.filter(value => long.includes(value))
+  }
+
+  /**
+   * Checks whether two arrays have any elements in common.
+   *
+   * This function returns `true` if at least one element from `arr1` exists in
+   * `arr2`, and `false` otherwise. It optimizes by iterating over the shorter
+   * array for efficiency.
+   *
+   * Example:
+   *   arrayIntersects([1, 2, 3], [3, 4, 5]) // returns true
+   *   arrayIntersects(["a", "b"], ["c", "d"]) // returns false
+   *
+   * @param {Array} arr1 - The first array to check for intersection.
+   * @param {Array} arr2 - The second array to check for intersection.
+   * @returns {boolean} True if any element is shared between the arrays, false otherwise.
+   */
+  static arrayIntersects(arr1, arr2) {
+    const [short,long] = [arr1,arr2].sort((a,b) => a.length - b.length)
+
+    return !!short.find(value => long.includes(value))
+  }
+
+  /**
+   * Pads an array to a specified length with a value. This operation
+   * occurs in-place.
+   *
+   * @param {Array} arr - The array to pad.
+   * @param {number} length - The length to pad the array to.
+   * @param {unknown} value - The value to pad the array with.
+   * @param {number} position - The position to pad the array at.
+   * @returns {Array} The padded array.
+   */
+  static arrayPad(arr, length, value, position = 0) {
+    const diff = length - arr.length
+
+    if(diff <= 0)
+      return arr
+
+    const padding = Array(diff).fill(value)
+
+    if(position === 0)
+    // prepend - default
+      return padding.concat(arr)
+    else if(position === -1)
+    // append
+      return arr.concat(padding) // somewhere in the middle - THAT IS ILLEGAL
+    else
+      throw Sass.new("Invalid position")
+  }
+
+  /**
+   * Clones an object
+   *
+   * @param {object} obj - The object to clone
+   * @param {boolean} freeze - Whether to freeze the cloned object
+   * @returns {object} The cloned object
+   */
+  static cloneObject(obj, freeze = false) {
+    const result = {}
+
+    for(const [key, value] of Object.entries(obj)) {
+      if(Data.isType(value, "object"))
+        result[key] = Data.cloneObject(value)
+      else
+        result[key] = value
+    }
+
+    return freeze ? Object.freeze(result) : result
+  }
+
+  /**
+   * Allocates an object from a source array and a spec array or function.
+   *
+   * @param {unknown} source The source array
+   * @param {Array|function(unknown): unknown} spec The spec array or function
+   * @returns {Promise<object>} The allocated object
+   */
+  static async allocateObject(source, spec) {
+  // Data
+    const workSource = [],
+      workSpec = [],
+      result = {}
+
+    if(!Data.isType(source, "array", {allowEmpty: false}))
+      throw Sass.new("Source must be an array.")
+
+    workSource.push(...source)
+
+    if(
+      !Data.isType(spec, "array", {allowEmpty: false}) &&
+      !Data.isType(spec, "function")
+    )
+      throw Sass.new("Spec must be an array or a function.")
+
+    if(Data.isType(spec, "function")) {
+      const specResult = await spec(workSource)
+
+      if(!Data.isType(specResult, "array"))
+        throw Sass.new("Spec resulting from function must be an array.")
+
+      workSpec.push(...specResult)
+    } else if(Data.isType(spec, "array", {allowEmpty: false})) {
+      workSpec.push(...spec)
+    }
+
+    if(workSource.length !== workSpec.length)
+      throw Sass.new("Source and spec must have the same number of elements.")
+
+    // Objects must always be indexed by strings.
+    workSource.map((element, index, arr) => (arr[index] = String(element)))
+
+    // Check that all keys are strings
+    if(!Data.isArrayUniform(workSource, "string"))
+      throw Sass.new("Indices of an Object must be of type string.")
+
+    workSource.forEach((element, index) => (result[element] = workSpec[index]))
+
+    return result
+  }
+
+  /**
+   * Maps an object using a transformer function
+   *
+   * @param {object} original The original object
+   * @param {function(unknown): unknown} transformer The transformer function
+   * @param {boolean} mutate Whether to mutate the original object
+   * @returns {Promise<object>} The mapped object
+   */
+  static async mapObject(original, transformer, mutate = false) {
+    Valid.validType(original, "object", {allowEmpty: true})
+    Valid.validType(transformer, "function")
+    Valid.validType(mutate, "boolean")
+
+    const result = mutate ? original : {}
+
+    for(const [key, value] of Object.entries(original))
+      result[key] = Data.isType(value, "object")
+        ? await Data.mapObject(value, transformer, mutate)
+        : (result[key] = await transformer(key, value))
+
+    return result
+  }
+
+  /**
+   * Checks if an object is empty
+   *
+   * @param {object} obj - The object to check
+   * @returns {boolean} Whether the object is empty
+   */
+  static isObjectEmpty(obj) {
+    return Object.keys(obj).length === 0
+  }
+
+  /**
+   * Creates a type spec from a string. A type spec is an array of objects
+   * defining the type of a value and whether an array is expected.
+   *
+   * @param {string} string - The string to parse into a type spec.
+   * @param {object} options - Additional options for parsing.
+   * @returns {object[]} An array of type specs.
+   */
+  static newTypeSpec(string, options) {
+    return new TypeSpec(string, options)
+  }
+
+  /**
+   * Checks if a value is of a specified type
+   *
+   * @param {unknown} value The value to check
+   * @param {string|TypeSpec} type The type to check for
+   * @param {object} options Additional options for checking
+   * @returns {boolean} Whether the value is of the specified type
+   */
+  static isType(value, type, options = {}) {
+    const typeSpec = type instanceof TypeSpec
+      ? type
+      : Data.newTypeSpec(type, options)
+
+    return typeSpec.match(value, options)
+  }
+
+  /**
+   * Checks if a type is valid
+   *
+   * @param {string} type - The type to check
+   * @returns {boolean} Whether the type is valid
+   */
+  static isValidType(type) {
+    return Data.dataTypes.includes(type)
+  }
+
+  /**
+   * Checks if a value is of a specified type. Unlike the type function, this
+   * function does not parse the type string, and only checks for primitive
+   * or constructor types.
+   *
+   * @param {unknown} value - The value to check
+   * @param {string} type - The type to check for
+   * @returns {boolean} Whether the value is of the specified type
+   */
+  static isBaseType(value, type) {
+    if(!Data.isValidType(type))
+      return false
+
+    const valueType = Data.typeOf(value)
+
+    switch(type.toLowerCase()) {
+      case "array":
+        return Array.isArray(value) // Native array check
+      case "string":
+        return valueType === "string"
+      case "boolean":
+        return valueType === "boolean"
+      case "number":
+        return valueType === "number" && !isNaN(value) // Excludes NaN
+      case "object":
+        return value !== null && valueType === "object" && !Array.isArray(value) // Excludes arrays and null
+      case "function":
+        return valueType === "function"
+      case "symbol":
+        return valueType === "symbol" // ES6 Symbol type
+      case "bigint":
+        return valueType === "bigint" // BigInt support
+      case "null":
+        return value === null // Explicit null check
+      case "undefined":
+        return valueType === "undefined" // Explicit undefined check
+      default:
+        return false // Unknown type
+    }
+  }
+
+  /**
+   * Returns the type of a value, whether it be a primitive, object, or function.
+   *
+   * @param {unknown} value - The value to check
+   * @returns {string} The type of the value
+   */
+  static typeOf(value) {
+    return Array.isArray(value) ? "array" : typeof value
+  }
+
+  /**
+   * Checks a value is undefined or null.
+   *
+   * @param {unknown} value The value to check
+   * @returns {boolean} Whether the value is undefined or null
+   */
+  static isNothing(value) {
+    return value === undefined || value === null
+  }
+
+  /**
+   * Checks if a value is empty. This function is used to check if an object,
+   * array, or string is empty. Null and undefined values are considered empty.
+   *
+   * @param {unknown} value The value to check
+   * @param {boolean} checkForNothing Whether to check for null or undefined
+   *                                  values
+   * @returns {boolean} Whether the value is empty
+   */
+  static isEmpty(value, checkForNothing = true) {
+    const type = Data.typeOf(value)
+
+    if(checkForNothing && Data.isNothing(value))
+      return true
+
+    if(!Data.emptyableTypes.includes(type))
+      return false
+
+    switch(type) {
+      case "array":
+        return value.length === 0
+      case "object":
+        return Object.keys(value).length === 0
+      case "string":
+        return value.trim().length === 0
+      default:
+        return false
+    }
+  }
+
+  /**
+   * Freezes an object and all of its properties recursively.
+   *
+   * @param {object} obj The object to freeze.
+   * @returns {object} The frozen object.
+   */
+  static deepFreezeObject(obj) {
+    if(obj === null || typeof obj !== "object")
+      return obj // Skip null and non-objects
+
+    // Retrieve and freeze properties
+    const propNames = Object.getOwnPropertyNames(obj)
+
+    for(const name of propNames) {
+      const value = obj[name]
+
+      // Recursively freeze nested objects
+      if(typeof value === "object" && value !== null)
+        Data.deepFreezeObject(value)
+    }
+
+    // Freeze the object itself
+    return Object.freeze(obj)
+  }
+
+  /**
+   * Ensures that a nested path of objects exists within the given object.
+   * Creates empty objects along the path if they don't exist.
+   *
+   * @param {object} obj - The object to check/modify
+   * @param {Array<string>} keys - Array of keys representing the path to ensure
+   * @returns {object} Reference to the deepest nested object in the path
+   */
+  static assureObjectPath(obj, keys) {
+    let current = obj  // a moving reference to internal objects within obj
+    const len = keys.length
+
+    for(let i = 0; i < len; i++) {
+      const elem = keys[i]
+
+      if(!current[elem])
+        current[elem] = {}
+
+      current = current[elem]
+    }
+
+    // Return the current pointer
+    return current
+  }
+
+  /**
+   * Sets a value in a nested object structure using an array of keys; creating
+   * the structure if it does not exist.
+   *
+   * @param {object} obj - The target object to set the value in
+   * @param {Array<string>} keys - Array of keys representing the path to the target property
+   * @param {unknown} value - The value to set at the target location
+   */
+  static setNestedValue(obj, keys, value) {
+    const nested = Data.assureObjectPath(obj, keys.slice(0, -1))
+
+    nested[keys[keys.length-1]] = value
+  }
+
+  /**
+   * Deeply merges two or more objects. Arrays are replaced, not merged.
+   *
+   * @param {...object} sources - Objects to merge (left to right)
+   * @returns {object} The merged object
+   */
+  static mergeObject(...sources) {
+    const isObject = obj => typeof obj === "object" && obj !== null && !Array.isArray(obj)
+
+    return sources.reduce((acc, obj) => {
+      if(!isObject(obj))
+        return acc
+
+      Object.keys(obj).forEach(key => {
+        const accVal = acc[key]
+        const objVal = obj[key]
+
+        if(isObject(accVal) && isObject(objVal))
+          acc[key] = Data.mergeObject(accVal, objVal)
+        else
+          acc[key] = objVal
+      })
+
+      return acc
+    }, {})
+  }
+
+  /**
+   * Checks if all elements in an array are strings.
+   *
+   * @param {Array} arr - The array to check.
+   * @returns {boolean} Returns true if all elements are strings, false otherwise.
+   * @example
+   * uniformStringArray(['a', 'b', 'c']) // returns true
+   * uniformStringArray(['a', 1, 'c']) // returns false
+   */
+  static uniformStringArray(arr) {
+    return Array.isArray(arr) && arr.every(item => typeof item === "string")
+  }
+
+  /**
+   * Filters an array asynchronously using a predicate function.
+   * Applies the predicate to all items in parallel and returns filtered results.
+   *
+   * @param {Array} arr - The array to filter
+   * @param {function(unknown): Promise<boolean>} predicate - Async predicate function that returns a promise resolving to boolean
+   * @returns {Promise<Array>} Promise resolving to the filtered array
+   */
+  static async asyncFilter(arr, predicate) {
+    const results = await Promise.all(arr.map(predicate))
+
+    return arr.filter((_, index) => results[index])
+  }
+
+}