@gesslar/toolkit 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -56,9 +56,9 @@
   "devDependencies": {
     "@stylistic/eslint-plugin": "^5.4.0",
     "@types/node": "^24.5.2",
-    "@typescript-eslint/eslint-plugin": "^8.44.0",
-    "@typescript-eslint/parser": "^8.44.0",
+    "@typescript-eslint/eslint-plugin": "^8.44.1",
+    "@typescript-eslint/parser": "^8.44.1",
     "eslint": "^9.36.0",
-    "eslint-plugin-jsdoc": "^60.1.0"
+    "eslint-plugin-jsdoc": "^60.4.1"
   }
 }

package/src/lib/Collection.js

@@ -1,5 +1,7 @@
 import Data from "./Data.js"
 import Valid from "./Valid.js"
+import Sass from "./Sass.js"
+import Util from "./Util.js"
 
 export default class Collection {
   static evalArray(collection, predicate, forward=true) {
@@ -105,4 +107,413 @@ export default class Collection {
 
     return unzipped
   }
+
+  static async asyncMap(array, asyncFn) {
+    const req = "Array"
+    const type = Data.typeOf(array)
+
+    Valid.type(array, req, `Invalid array. Expected '${req}', got '${type}'`)
+    Valid.type(asyncFn, "Function",
+      `Invalid mapper function, expected 'Function', got '${Data.typeOf(asyncFn)}'`)
+
+    const results = []
+
+    for(const item of array) {
+      results.push(await asyncFn(item))
+    }
+
+    return results
+  }
+
+  /**
+   * 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) {
+    const req = "Array"
+    const arrType = Data.typeOf(arr)
+
+    Valid.type(arr, req, `Invalid array. Expected '${req}', got '${arrType}'`)
+
+    const checkType = type ? Util.capitalize(type) : null
+
+    return arr.every(
+      (item, _index, arr) =>
+        Data.typeOf(item) === (checkType || Data.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) {
+    const req = "Array"
+    const arrType = Data.typeOf(arr)
+
+    Valid.type(arr, req, `Invalid array. Expected '${req}', got '${arrType}'`)
+
+    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 req = "Array"
+    const arr1Type = Data.typeOf(arr1)
+    const arr2Type = Data.typeOf(arr2)
+
+    Valid.type(arr1, req, `Invalid first array. Expected '${req}', got '${arr1Type}'`)
+    Valid.type(arr2, req, `Invalid second array. Expected '${req}', got '${arr2Type}'`)
+
+    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 req = "Array"
+    const arr1Type = Data.typeOf(arr1)
+    const arr2Type = Data.typeOf(arr2)
+
+    Valid.type(arr1, req, `Invalid first array. Expected '${req}', got '${arr1Type}'`)
+    Valid.type(arr2, req, `Invalid second array. Expected '${req}', got '${arr2Type}'`)
+
+    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 req = "Array"
+    const arrType = Data.typeOf(arr)
+
+    Valid.type(arr, req, `Invalid array. Expected '${req}', got '${arrType}'`)
+    Valid.type(length, "Number", `Invalid length. Expected 'Number', got '${Data.typeOf(length)}'`)
+    Valid.type(position, "Number", `Invalid position. Expected 'Number', got '${Data.typeOf(position)}'`)
+
+    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")
+  }
+
+  /**
+   * 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) {
+    if(!Data.isType(arr, "Array"))
+      return false
+
+    return 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 req = "Array"
+    const arrType = Data.typeOf(arr)
+
+    Valid.type(arr, req, `Invalid array. Expected '${req}', got '${arrType}'`)
+    Valid.type(predicate, "Function",
+      `Invalid predicate function, expected 'Function', got '${Data.typeOf(predicate)}'`)
+
+    const results = await Promise.all(arr.map(predicate))
+
+    return arr.filter((_, index) => results[index])
+  }
+
+  /**
+   * 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, "Array")) {
+        // Clone arrays by mapping over them
+        result[key] = value.map(item =>
+          Data.isType(item, "object") || Data.isType(item, "Array")
+            ? Collection.cloneObject(item)
+            : item
+        )
+      } else if(Data.isType(value, "object")) {
+        result[key] = Collection.cloneObject(value)
+      } else {
+        result[key] = value
+      }
+    }
+
+    return freeze ? Object.freeze(result) : result
+  }
+
+  /**
+   * Checks if an object is empty
+   *
+   * @param {object} obj - The object to check
+   * @returns {boolean} Whether the object is empty
+   */
+  static isObjectEmpty(obj) {
+    const req = "Object"
+    const objType = Data.typeOf(obj)
+
+    Valid.type(obj, req, `Invalid object. Expected '${req}', got '${objType}'`)
+
+    return Object.keys(obj).length === 0
+  }
+
+  /**
+   * 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) {
+    const req = "Object"
+    const objType = Data.typeOf(obj)
+    const keysReq = "Array"
+    const keysType = Data.typeOf(keys)
+
+    Valid.type(obj, req, `Invalid object. Expected '${req}', got '${objType}'`)
+    Valid.type(keys, keysReq, `Invalid keys array. Expected '${keysReq}', got '${keysType}'`)
+
+    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]
+
+      // Prevent prototype pollution
+      if(elem === "__proto__" || elem === "constructor" || elem === "prototype") {
+        throw Sass.new(`Dangerous key "${elem}" not allowed in object path`)
+      }
+
+      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 req = "Object"
+    const objType = Data.typeOf(obj)
+    const keysReq = "Array"
+    const keysType = Data.typeOf(keys)
+
+    Valid.type(obj, req, `Invalid object. Expected '${req}', got '${objType}'`)
+    Valid.type(keys, keysReq, `Invalid keys array. Expected '${keysReq}', got '${keysType}'`)
+
+    const nested = Collection.assureObjectPath(obj, keys.slice(0, -1))
+    const finalKey = keys[keys.length-1]
+
+    // Prevent prototype pollution on final key too
+    if(finalKey === "__proto__" || finalKey === "constructor" || finalKey === "prototype") {
+      throw Sass.new(`Dangerous key "${finalKey}" not allowed in object path`)
+    }
+
+    nested[finalKey] = 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] = Collection.mergeObject(accVal, objVal)
+        else
+          acc[key] = objVal
+      })
+
+      return acc
+    }, {})
+  }
+
+  /**
+   * 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)
+        Collection.deepFreezeObject(value)
+    }
+
+    // Freeze the object itself
+    return Object.freeze(obj)
+  }
+
+  /**
+   * 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.type(original, "object", {allowEmpty: true})
+    Valid.type(transformer, "function")
+    Valid.type(mutate, "boolean")
+
+    const result = mutate ? original : {}
+
+    for(const [key, value] of Object.entries(original))
+      result[key] = Data.isType(value, "object")
+        ? await Collection.mapObject(value, transformer, mutate)
+        : (result[key] = await transformer(key, value))
+
+    return result
+  }
+
+  /**
+   * Allocates an object from a source array and a spec array or function.
+   *
+   * @param {unknown} source The source array
+   * @param {Array<unknown>|function(Array<unknown>): Promise<Array<unknown>>|Array<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(!Collection.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
+  }
+
 }

package/src/lib/Data.js

@@ -6,10 +6,7 @@
  * structures.
  */
 
-import Sass from "./Sass.js"
 import TypeSpec from "./TypeSpec.js"
-import Util from "./Util.js"
-import Valid from "./Valid.js"
 
 export default class Data {
 /**
@@ -101,206 +98,6 @@ export default class Data {
     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) {
-    const checkType = type ? Util.capitalize(type) : null
-
-    return arr.every(
-      (item, _index, arr) =>
-        Data.typeOf(item) === (checkType || Data.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, "Array")) {
-        // Clone arrays by mapping over them
-        result[key] = value.map(item =>
-          Data.isType(item, "object") || Data.isType(item, "Array")
-            ? Data.cloneObject(item)
-            : item
-        )
-      } else 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<unknown>|function(Array<unknown>): Promise<Array<unknown>>|Array<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.type(original, "object", {allowEmpty: true})
-    Valid.type(transformer, "function")
-    Valid.type(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.
@@ -381,9 +178,12 @@ export default class Data {
 
     const type = typeof value
 
-    return type === "object"
-      ? value.constructor.name
-      : type.charAt(0).toUpperCase() + type.slice(1)
+    if(type === "object")
+      return value.constructor.name
+
+    const [first, ...rest] = Array.from(type)
+
+    return `${first?.toLocaleUpperCase() ?? ""}${rest.join("")}`
   }
 
   /**

package/src/lib/FS.js

@@ -2,6 +2,7 @@ import {globby} from "globby"
 import path from "node:path"
 import url from "node:url"
 
+import Collection from "./Collection.js"
 import Data from "./Data.js"
 import DirectoryObject from "./DirectoryObject.js"
 import FileObject from "./FileObject.js"
@@ -10,7 +11,9 @@ import Valid from "./Valid.js"
 
 const fdTypes = Object.freeze(["file", "directory"])
 const upperFdTypes = Object.freeze(fdTypes.map(type => type.toUpperCase()))
-const fdType = Object.freeze(await Data.allocateObject(upperFdTypes, fdTypes))
+const fdType = Object.freeze(
+  await Collection.allocateObject(upperFdTypes, fdTypes)
+)
 
 export default class FS {
   static fdTypes = fdTypes
@@ -115,7 +118,11 @@ export default class FS {
    * @returns {string} The relative path from `from` to `to`, or the absolute path if not reachable
    */
   static relativeOrAbsolutePath(from, to) {
-    const relative = path.relative(from.path, to.path)
+    const fromBasePath = from.isDirectory
+      ? from.path
+      : from.directory?.path ?? path.dirname(from.path)
+
+    const relative = path.relative(fromBasePath, to.path)
 
     return relative.startsWith("..")
       ? to.path

package/src/lib/FileObject.js

@@ -385,12 +385,13 @@ export default class FileObject extends FS {
    */
   async loadData(type="any", encoding="utf8") {
     const content = await this.read(encoding)
+    const normalizedType = type.toLocaleLowerCase()
     const toTry = {
       json5: [JSON5],
       json: [JSON5],
       yaml: [YAML],
       any: [JSON5,YAML]
-    }[type.toLowerCase()]
+    }[normalizedType]
 
     if(!toTry) {
       throw Sass.new(`Unsupported data type '${type}'. Supported types: json, json5, yaml, any`)

package/src/lib/TypeSpec.js

@@ -4,8 +4,9 @@
  * including arrays, unions, and options.
  */
 
-import Sass from "./Sass.js"
+import Collection from "./Collection.js"
 import Data from "./Data.js"
+import Sass from "./Sass.js"
 import Util from "./Util.js"
 
 /**
@@ -180,7 +181,7 @@ export default class TypeSpec {
           return allowEmpty
 
         // Check if array elements match the required type
-        return Data.isArrayUniform(value, allowedType)
+        return Collection.isArrayUniform(value, allowedType)
       }
 
       return false

package/src/lib/Util.js

@@ -15,9 +15,15 @@ export default class Util {
    * @returns {string} Text with first letter capitalized
    */
   static capitalize(text) {
-    return typeof text === "string"
-      && `${text.slice(0,1).toUpperCase()}${text.slice(1)}`
-      || text
+    if(typeof text !== "string")
+      throw new TypeError("Util.capitalize expects a string")
+
+    if(text.length === 0)
+      return ""
+
+    const [first, ...rest] = Array.from(text)
+
+    return `${first.toLocaleUpperCase()}${rest.join("")}`
   }
 
   /**

package/src/types/Collection.d.ts

@@ -135,4 +135,84 @@ export default class Collection {
    * ```
    */
   static unzip<T>(array: T[][]): T[][]
+
+  /**
+   * Maps an array through an async function, executing operations sequentially.
+   * 
+   * Unlike Promise.all(array.map(fn)), this executes each async operation
+   * one at a time, maintaining order and preventing overwhelming external resources.
+   *
+   * @param array - The array to map over
+   * @param asyncFn - Async function called for each element: (element) => Promise<result>
+   * @returns Promise resolving to array of mapped results
+   *
+   * @throws {Sass} If array is not an Array or asyncFn is not a Function
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * // Sequential API calls (won't overwhelm server)
+   * const urls = ['url1', 'url2', 'url3']
+   * const responses = await Collection.asyncMap(urls, async (url) => {
+   *   return await fetch(url).then(r => r.json())
+   * })
+   * console.log(responses) // [data1, data2, data3]
+   *
+   * // Works with sync functions too
+   * const numbers = [1, 2, 3]
+   * const doubled = await Collection.asyncMap(numbers, async (n) => n * 2)
+   * console.log(doubled) // [2, 4, 6]
+   * ```
+   */
+  static asyncMap<T, R>(array: T[], asyncFn: (element: T) => Promise<R> | R): Promise<R[]>
+
+  /** Check if all elements in an array are of a specified type or all the same type */
+  static isArrayUniform(arr: Array<unknown>, type?: string): boolean
+
+  /** Remove duplicate elements from an array, returning a new array with unique values */
+  static isArrayUnique<T>(arr: Array<T>): Array<T>
+
+  /** Get the intersection of two arrays */
+  static arrayIntersection<T>(arr1: Array<T>, arr2: Array<T>): Array<T>
+
+  /** Check if two arrays have any elements in common */
+  static arrayIntersects<T>(arr1: Array<T>, arr2: Array<T>): boolean
+
+  /** Pad an array to a specified length */
+  static arrayPad<T>(arr: Array<T>, length: number, value: T, position?: number): Array<T>
+
+  /** Check if all elements in an array are strings */
+  static uniformStringArray(arr: Array<unknown>): arr is Array<string>
+
+  /** Filter an array asynchronously */
+  static asyncFilter<T>(arr: Array<T>, predicate: (item: T) => Promise<boolean>): Promise<Array<T>>
+
+  /** Clone an object */
+  static cloneObject<T extends Record<string, any>>(obj: T, freeze?: boolean): T
+
+  /** Check if an object is empty */
+  static isObjectEmpty(obj: Record<string, any>): boolean
+
+  /** Ensure a nested path of objects exists */
+  static assureObjectPath(obj: Record<string, any>, keys: Array<string>): Record<string, any>
+
+  /** Set a value in a nested object structure */
+  static setNestedValue(obj: Record<string, any>, keys: Array<string>, value: unknown): void
+
+  /** Deeply merge objects */
+  static mergeObject<T extends Record<string, any>>(...sources: Array<T>): T
+
+  /** Recursively freeze an object */
+  static deepFreezeObject<T>(obj: T): T
+
+  /** Map an object using a transformer function */
+  static mapObject<T extends Record<string, any>, R>(
+    original: T,
+    transformer: (key: string, value: any) => R | Promise<R>,
+    mutate?: boolean
+  ): Promise<Record<string, R>>
+
+  /** Allocate an object from a source array and spec */
+  static allocateObject(source: Array<unknown>, spec: Array<unknown> | ((source: Array<unknown>) => Promise<Array<unknown>> | Array<unknown>)): Promise<Record<string, unknown>>
 }

package/src/types/Data.d.ts

@@ -91,118 +91,6 @@ export default class Data {
    */
   static prependString(string: string, prepend: string): string
 
-  /**
-   * Check if all elements in an array are of a specified type or all the same type.
-   * 
-   * Performs type checking on every element in the array using the toolkit's type
-   * system. If no type is specified, checks that all elements are of the same type.
-   * Useful for validating data structures and ensuring type consistency before processing.
-   *
-   * @param arr - The array to check for type uniformity. Can be empty (returns true).
-   * @param type - Optional type name to check against. If not provided, checks that all
-   *              elements have the same type. Must be a valid type from Data.dataTypes.
-   * @returns True if all elements match the specified type or are all the same type,
-   *         false if there's any type mismatch or if type parameter is invalid
-   * 
-   * @example
-   * ```typescript
-   * import { Data } from '@gesslar/toolkit'
-   * 
-   * // Check for specific type uniformity
-   * const numbers = [1, 2, 3, 4, 5]
-   * const strings = ['a', 'b', 'c']
-   * const mixed = [1, 'a', true]
-   * 
-   * console.log(Data.isArrayUniform(numbers, 'number'))  // true
-   * console.log(Data.isArrayUniform(strings, 'string'))  // true
-   * console.log(Data.isArrayUniform(mixed, 'number'))    // false
-   * 
-   * // Check that all elements are the same type (any type)
-   * console.log(Data.isArrayUniform(numbers))     // true (all numbers)
-   * console.log(Data.isArrayUniform(strings))     // true (all strings) 
-   * console.log(Data.isArrayUniform(mixed))       // false (mixed types)
-   * console.log(Data.isArrayUniform([]))          // true (empty array)
-   * 
-   * // Useful for validation before processing
-   * function processNumbers(data: unknown[]) {
-   *   if (!Data.isArrayUniform(data, 'number')) {
-   *     throw new Error('Array must contain only numbers')
-   *   }
-   *   return data.reduce((sum, num) => sum + num, 0)
-   * }
-   * ```
-   */
-  static isArrayUniform(arr: Array<unknown>, type?: string): boolean
-
-  /**
-   * Remove duplicate elements from an array, returning a new array with unique values.
-   * 
-   * Creates a new array containing only the first occurrence of each unique value,
-   * preserving the original order of first appearances. Uses strict equality (===)
-   * for primitive comparisons and shallow comparison for objects.
-   *
-   * @param arr - The array to remove duplicates from. Can be empty or contain any types.
-   * @returns A new array with duplicate elements removed, preserving order of first occurrence
-   * 
-   * @example
-   * ```typescript
-   * import { Data } from '@gesslar/toolkit'
-   * 
-   * // Basic duplicate removal
-   * const numbers = [1, 2, 2, 3, 3, 4]
-   * const uniqueNumbers = Data.isArrayUnique(numbers)
-   * console.log(uniqueNumbers) // [1, 2, 3, 4]
-   * 
-   * // Mixed types
-   * const mixed = ['a', 1, 'a', 2, 1, 'b']
-   * const uniqueMixed = Data.isArrayUnique(mixed)
-   * console.log(uniqueMixed) // ['a', 1, 2, 'b']
-   * 
-   * // Object arrays (shallow comparison)
-   * const users = [
-   *   { id: 1, name: 'Alice' },
-   *   { id: 2, name: 'Bob' },
-   *   { id: 1, name: 'Alice' }  // Different object reference, not filtered
-   * ]
-   * const uniqueUsers = Data.isArrayUnique(users)
-   * console.log(uniqueUsers.length) // 3 (objects compared by reference)
-   * 
-   * // Empty and single element arrays
-   * console.log(Data.isArrayUnique([])) // []
-   * console.log(Data.isArrayUnique(['single'])) // ['single']
-   * 
-   * // String array deduplication
-   * const tags = ['javascript', 'node', 'javascript', 'typescript', 'node']
-   * const uniqueTags = Data.isArrayUnique(tags)
-   * console.log(uniqueTags) // ['javascript', 'node', 'typescript']
-   * ```
-   */
-  static isArrayUnique<T>(arr: Array<T>): Array<T>
-
-  /** Get the intersection of two arrays */
-  static arrayIntersection<T>(arr1: Array<T>, arr2: Array<T>): Array<T>
-
-  /** Check if two arrays have any elements in common */
-  static arrayIntersects<T>(arr1: Array<T>, arr2: Array<T>): boolean
-
-  /** Pad an array to a specified length */
-  static arrayPad<T>(arr: Array<T>, length: number, value: T, position?: number): Array<T>
-
-  /** Clone an object */
-  static cloneObject<T extends Record<string, any>>(obj: T, freeze?: boolean): T
-
-  /** Allocate an object from a source array and spec */
-  static allocateObject(source: Array<unknown>, spec: Array<unknown> | ((source: Array<unknown>) => Promise<Array<unknown>> | Array<unknown>)): Promise<Record<string, unknown>>
-
-  /** Map an object using a transformer function */
-  static mapObject<T extends Record<string, any>, R>(
-    original: T,
-    transformer: (key: string, value: any) => R | Promise<R>,
-    mutate?: boolean
-  ): Promise<Record<string, R>>
-
-  /** Check if an object is empty */
-  static isObjectEmpty(obj: Record<string, any>): boolean
 
   /** Create a type spec from a string */
   static newTypeSpec(string: string, options?: any): Type

package/src/types/Util.d.ts

@@ -10,6 +10,7 @@ declare class Util {
    *
    * @param text - The text to capitalize
    * @returns Text with first letter capitalized
+   * @throws {TypeError} If `text` is not a string
    *
    * @example
    * ```typescript