@gesslar/toolkit 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -49,16 +49,16 @@
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "dependencies": {
-    "globby": "^14.1.0",
+    "globby": "^15.0.0",
     "json5": "^2.2.3",
     "yaml": "^2.8.1"
   },
   "devDependencies": {
     "@stylistic/eslint-plugin": "^5.4.0",
-    "@types/node": "^24.5.2",
-    "@typescript-eslint/eslint-plugin": "^8.44.1",
-    "@typescript-eslint/parser": "^8.44.1",
+    "@types/node": "^24.6.2",
+    "@typescript-eslint/eslint-plugin": "^8.45.0",
+    "@typescript-eslint/parser": "^8.45.0",
     "eslint": "^9.36.0",
-    "eslint-plugin-jsdoc": "^60.4.1"
+    "eslint-plugin-jsdoc": "^60.7.1"
   }
 }

package/src/lib/Collection.js

@@ -139,6 +139,11 @@ export default class Collection {
 
     Valid.type(arr, req, `Invalid array. Expected '${req}', got '${arrType}'`)
 
+    // Validate type parameter if provided
+    if(type !== undefined) {
+      Valid.type(type, "string", `Invalid type parameter. Expected 'string', got '${Data.typeOf(type)}'`)
+    }
+
     const checkType = type ? Util.capitalize(type) : null
 
     return arr.every(
@@ -169,7 +174,7 @@ export default class Collection {
    * @param {Array} arr2 - The second array.
    * @returns {Array} The intersection of the two arrays.
    */
-  static arrayIntersection(arr1, arr2) {
+  static intersection(arr1, arr2) {
     const req = "Array"
     const arr1Type = Data.typeOf(arr1)
     const arr2Type = Data.typeOf(arr2)
@@ -190,14 +195,14 @@ export default class Collection {
    * array for efficiency.
    *
    * Example:
-   *   arrayIntersects([1, 2, 3], [3, 4, 5]) // returns true
-   *   arrayIntersects(["a", "b"], ["c", "d"]) // returns false
+   *   Collection.intersects([1, 2, 3], [3, 4, 5]) // returns true
+   *   Collection.intersects(["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) {
+  static intersects(arr1, arr2) {
     const req = "Array"
     const arr1Type = Data.typeOf(arr1)
     const arr2Type = Data.typeOf(arr2)
@@ -245,22 +250,6 @@ export default class Collection {
       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.
@@ -345,14 +334,11 @@ export default class Collection {
     let current = obj  // a moving reference to internal objects within obj
     const len = keys.length
 
+    Valid.prototypePollutionProtection(keys)
+
     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] = {}
 
@@ -383,10 +369,7 @@ export default class Collection {
     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`)
-    }
+    Valid.prototypePollutionProtection([finalKey])
 
     nested[finalKey] = value
   }
@@ -474,7 +457,6 @@ export default class Collection {
    * @returns {Promise<object>} The allocated object
    */
   static async allocateObject(source, spec) {
-  // Data
     const workSource = [],
       workSpec = [],
       result = {}
@@ -516,4 +498,65 @@ export default class Collection {
     return result
   }
 
+  static flattenObjectArray(objects) {
+    const req = "Array"
+    const type = Data.typeOf(objects)
+
+    Valid.type(objects, req, `Invalid objects array. Expected '${req}', got '${type}'`)
+
+    return objects.reduce((acc, curr) => {
+      const elemType = Data.typeOf(curr)
+
+      if(!Data.isPlainObject(curr))
+        throw Sass.new(`Invalid array element. Expected plain object, got '${elemType}'`)
+
+      Valid.prototypePollutionProtection(Object.keys(curr))
+
+      Object.entries(curr).forEach(([key, value]) => {
+        if(!acc[key])
+          acc[key] = []
+
+        acc[key].push(value)
+      })
+
+      return acc
+    }, {})
+  }
+
+  static trimArray(arr, except=[]) {
+    Valid.type(arr, "Array")
+    Valid.type(except, "Array")
+
+    Collection.trimArrayLeft(arr, except)
+    Collection.trimArrayRight(arr, except)
+
+    return arr
+  }
+
+  static trimArrayRight(arr, except=[]) {
+    Valid.type(arr, "Array")
+    Valid.type(except, "Array")
+
+    arr.reverse()
+    Collection.trimArrayLeft(arr, except)
+    arr.reverse()
+
+    return arr
+  }
+
+  static trimArrayLeft(arr, except=[]) {
+    Valid.type(arr, "Array")
+    Valid.type(except, "Array")
+
+    while(arr.length > 0) {
+      const value = arr[0]
+
+      if(value || except.includes(value))
+        break
+
+      arr.shift()
+    }
+
+    return arr
+  }
 }

package/src/lib/Data.js

@@ -323,19 +323,6 @@ export default class Data {
     }, {})
   }
 
-  /**
-   * 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.

package/src/lib/FS.js

@@ -3,7 +3,6 @@ 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"
 import Sass from "./Sass.js"
@@ -73,7 +72,7 @@ export default class FS {
       (
         (typeof glob === "string" && glob.length > 0) ||
         (
-          Array.isArray(glob) && Data.uniformStringArray(glob) &&
+          Collection.isArrayUniform(glob, "string") &&
           glob.length > 0
         )
       ),
@@ -92,7 +91,7 @@ export default class FS {
 
     if(
       Array.isArray(globbyArray) &&
-      Data.uniformStringArray(globbyArray) &&
+      Collection.isArrayUniform(globbyArray, "string") &&
       !globbyArray.length
     )
       throw Sass.new(

package/src/lib/Util.js

@@ -2,6 +2,8 @@ import {createHash} from "node:crypto"
 import {performance} from "node:perf_hooks"
 import {EventEmitter} from "node:events"
 import Sass from "./Sass.js"
+import Valid from "./Valid.js"
+import Collection from "./Collection.js"
 
 /**
  * Utility class providing common helper functions for string manipulation,
@@ -300,9 +302,18 @@ export default class Util {
   }
 
   static regexify(input, trim=true, flags=[]) {
+    Valid.type(input, "String")
+    Valid.type(trim, "Boolean")
+    Valid.type(flags, "Array")
+
+    Valid.assert(
+      flags.length === 0 ||
+      (flags.length > 0 && Collection.isArrayUniform(flags, "String")),
+      "All flags must be strings")
+
     return new RegExp(
       input
-        .split("\n")
+        .split(/\r\n|\r|\n/)
         .map(i => trim ? i.trim() : i)
         .filter(i => trim ? Boolean(i) : true)
         .join("")

package/src/lib/Valid.js

@@ -2,6 +2,7 @@ import _assert from "node:assert/strict"
 
 import Sass from "./Sass.js"
 import Data from "./Data.js"
+import Collection from "./Collection.js"
 
 export default class Valid {
 /**
@@ -46,4 +47,15 @@ export default class Valid {
       throw Sass.new(`${message}${arg ? `: ${arg}` : ""}`)
   }
 
+  static #restrictedProto = ["__proto__", "constructor", "prototype"]
+  static prototypePollutionProtection(keys) {
+    Valid.type(keys, "String[]")
+
+    const oopsIDidItAgain = Collection.intersection(this.#restrictedProto, keys)
+
+    Valid.assert(
+      oopsIDidItAgain.length === 0,
+      `We don't pee in your pool, don't pollute ours with your ${String(oopsIDidItAgain)}`
+    )
+  }
 }

package/src/types/Collection.d.ts

@@ -138,7 +138,7 @@ export default class Collection {
 
   /**
    * 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.
    *
@@ -174,17 +174,14 @@ export default class Collection {
   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>
+  static intersection<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
+  static intersects<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>>
 
@@ -215,4 +212,89 @@ export default class Collection {
 
   /** 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>>
+
+  /**
+   * Flattens an array of plain objects into a single object where each key contains
+   * an array of all values for that key across all input objects.
+   *
+   * @param objects - Array of plain objects to flatten
+   * @returns Object with keys mapped to arrays of values from all input objects
+   *
+   * @throws {Sass} If objects is not an Array or if any element is not a plain object
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * const objects = [
+   *   { name: 'Alice', age: 25 },
+   *   { name: 'Bob', age: 30 },
+   *   { name: 'Charlie', age: 35 }
+   * ]
+   *
+   * const result = Collection.flattenObjectArray(objects)
+   * // result: { name: ['Alice', 'Bob', 'Charlie'], age: [25, 30, 35] }
+   * ```
+   */
+  static flattenObjectArray(objects: Array<Record<string, unknown>>): Record<string, Array<unknown>>
+
+  /**
+   * Trims falsy values from both ends of an array.
+   *
+   * @param arr - The array to trim
+   * @param except - Array of values to exclude from trimming (default: [])
+   * @returns The trimmed array (modified in place)
+   *
+   * @throws {Sass} If arr or except is not an Array
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * const arr = [null, 0, 1, 2, "", undefined]
+   * Collection.trimArray(arr)
+   * console.log(arr) // [1, 2]
+   * ```
+   */
+  static trimArray<T>(arr: Array<T>, except?: Array<T>): Array<T>
+
+  /**
+   * Trims falsy values from the right end of an array.
+   *
+   * @param arr - The array to trim
+   * @param except - Array of values to exclude from trimming (default: [])
+   * @returns The trimmed array (modified in place)
+   *
+   * @throws {Sass} If arr or except is not an Array
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * const arr = [1, "", undefined]
+   * Collection.trimArrayRight(arr)
+   * console.log(arr) // [1]
+   * ```
+   */
+  static trimArrayRight<T>(arr: Array<T>, except?: Array<T>): Array<T>
+
+  /**
+   * Trims falsy values from the left end of an array.
+   *
+   * @param arr - The array to trim
+   * @param except - Array of values to exclude from trimming (default: [])
+   * @returns The trimmed array (modified in place)
+   *
+   * @throws {Sass} If arr or except is not an Array
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * const arr = [null, undefined, "value"]
+   * Collection.trimArrayLeft(arr)
+   * console.log(arr) // ["value"]
+   * ```
+   */
+  static trimArrayLeft<T>(arr: Array<T>, except?: Array<T>): Array<T>
 }

package/src/types/Data.d.ts

@@ -125,9 +125,6 @@ export default class Data {
   /** Deeply merge objects */
   static mergeObject<T extends Record<string, any>>(...sources: Array<T>): 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>>
 

package/src/types/Util.d.ts

@@ -224,10 +224,15 @@ declare class Util {
    * them to be written across multiple lines with proper formatting and indentation.
    * The resulting regex is functionally identical to writing it as a single line.
    *
-   * @param input - Multiline string containing the regex pattern
+   * @param input - Multiline string containing the regex pattern (required)
    * @param trim - Whether to trim whitespace from each line (default: true)
    * @param flags - Array of regex flags to apply (default: [])
    * @returns A new RegExp object with the processed pattern
+   * 
+   * @throws Will throw if input is not a string
+   * @throws Will throw if trim is not a boolean
+   * @throws Will throw if flags is not an array
+   * @throws Will throw if flags contains non-string elements
    *
    * @example
    * ```typescript

package/src/types/Valid.d.ts

@@ -7,4 +7,7 @@ export default class Valid {
 
   /** Assert a condition */
   static assert(condition: boolean, message: string, arg?: number | null): void
+
+  /** Protect against prototype pollution by checking for dangerous keys */
+  static prototypePollutionProtection(keys: string[]): void
 }