@gesslar/toolkit 0.1.6 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",

package/src/index.js

@@ -5,6 +5,7 @@ export {default as FS} from "./lib/FS.js"
 
 // Utility classes
 export {default as Cache} from "./lib/Cache.js"
+export {default as Collection} from "./lib/Collection.js"
 export {default as Data} from "./lib/Data.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Sass} from "./lib/Sass.js"

package/src/lib/Collection.js

@@ -0,0 +1,108 @@
+import Data from "./Data.js"
+import Valid from "./Valid.js"
+
+export default class Collection {
+  static evalArray(collection, predicate, forward=true) {
+    const req = "Array"
+    const type = Data.typeOf(collection)
+
+    Valid.type(collection, req, `Invalid collection. Expected '${req}, got ${type}`)
+    Valid.type(predicate, "Function",
+      `Invalid predicate, expected 'Function', got ${Data.typeOf(predicate)}`)
+
+    const work = forward
+      ? Array.from(collection)
+      : Array.from(collection).toReversed()
+
+    for(let i = 0; i < work.length; i++) {
+      const result = predicate(work[i], i, collection) ?? null
+
+      if(result)
+        return result
+    }
+  }
+
+  static evalObject(collection, predicate) {
+    const req = "Object"
+    const type = Data.typeOf(collection)
+
+    Valid.type(collection, req, `Invalid collection. Expected '${req}, got ${type}`)
+    Valid.type(predicate, "Function",
+      `Invalid predicate, expected 'Function', got ${Data.typeOf(predicate)}`)
+
+    const work = Object.entries(collection)
+
+    for(let i = 0; i < work.length; i++) {
+      const result = predicate(work[i][1], work[i][0], collection)
+
+      if(result)
+        return result
+    }
+  }
+
+  static evalSet(collection, predicate) {
+    const req = "Set"
+    const type = Data.typeOf(collection)
+
+    Valid.type(collection, req, `Invalid collection. Expected '${req}, got ${type}`)
+    Valid.type(predicate, "Function",
+      `Invalid predicate, expected 'Function', got ${Data.typeOf(predicate)}`)
+
+    const work = Array.from(collection)
+
+    for(let i = 0; i < work.length; i++) {
+      const result = predicate(work[i], collection)
+
+      if(result)
+        return result
+    }
+  }
+
+  static evalMap(collection, predicate, forward=true) {
+    const req = "Map"
+    const type = Data.typeOf(collection)
+
+    Valid.type(collection, req, `Invalid collection. Expected '${req}, got ${type}`)
+    Valid.type(predicate, "Function",
+      `Invalid predicate, expected 'Function', got ${Data.typeOf(predicate)}`)
+
+    const work = forward
+      ? Array.from(collection)
+      : Array.from(collection).toReversed()
+
+    for(let i = 0; i < work.length; i++) {
+      const result = predicate(work[i][1], work[i][0], collection) ?? null
+
+      if(result)
+        return result
+    }
+  }
+
+  static zip(array1, array2) {
+    const minLength = Math.min(array1.length, array2.length)
+
+    return Array.from({length: minLength}, (_, i) => [array1[i], array2[i]])
+  }
+
+  static unzip(array) {
+    if(!Array.isArray(array) || array.length === 0) {
+      return [] // Handle empty or invalid input
+    }
+
+    // Determine the number of "unzipped" arrays needed
+    // This assumes all inner arrays have the same length, or we take the max length
+    const numUnzippedArrays = Math.max(...array.map(arr => arr.length))
+
+    // Initialize an array of empty arrays to hold the unzipped results
+    const unzipped = Array.from({length: numUnzippedArrays}, () => [])
+
+    // Iterate through the zipped array and populate the unzipped arrays
+    for(let i = 0; i < array.length; i++) {
+      for(let j = 0; j < numUnzippedArrays; j++) {
+        unzipped[j].push(array[i][j])
+      }
+    }
+
+    return unzipped
+  }
+}

package/src/lib/Data.js

@@ -8,6 +8,7 @@
 
 import Sass from "./Sass.js"
 import TypeSpec from "./TypeSpec.js"
+import Util from "./Util.js"
 import Valid from "./Valid.js"
 
 export default class Data {
@@ -19,17 +20,17 @@ export default class Data {
  */
   static primitives = Object.freeze([
   // Primitives
-    "undefined",
-    "null",
-    "boolean",
-    "number",
-    "bigint",
-    "string",
-    "symbol",
+    "Undefined",
+    "Null",
+    "Boolean",
+    "Number",
+    "Bigint",
+    "String",
+    "Symbol",
 
     // Object Categories from typeof
-    "object",
-    "function",
+    "Object",
+    "Function",
   ])
 
   /**
@@ -67,7 +68,7 @@ export default class Data {
    */
   static dataTypes = Object.freeze([
     ...Data.primitives,
-    ...Data.constructors.map(c => c.toLowerCase())
+    ...Data.constructors
   ])
 
   /**
@@ -76,7 +77,7 @@ export default class Data {
    *
    * @type {Array<string>}
    */
-  static emptyableTypes = Object.freeze(["string", "array", "object"])
+  static emptyableTypes = Object.freeze(["String", "Array", "Object"])
 
   /**
    * Appends a string to another string if it does not already end with it.
@@ -109,8 +110,11 @@ export default class Data {
    * @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) => typeof item === (type || typeof arr[0]),
+      (item, _index, arr) =>
+        Data.typeOf(item) === (checkType || Data.typeOf(arr[0])),
     )
   }
 
@@ -197,10 +201,10 @@ export default class Data {
     const result = {}
 
     for(const [key, value] of Object.entries(obj)) {
-      if(Data.isType(value, "array")) {
+      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.isType(item, "object") || Data.isType(item, "Array")
             ? Data.cloneObject(item)
             : item
         )
@@ -227,25 +231,25 @@ export default class Data {
       workSpec = [],
       result = {}
 
-    if(!Data.isType(source, "array", {allowEmpty: false}))
+    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, "Array", {allowEmpty: false}) &&
       !Data.isType(spec, "function")
     )
       throw Sass.new("Spec must be an array or a function.")
 
-    if(Data.isType(spec, "function")) {
+    if(Data.isType(spec, "Function")) {
       const specResult = await spec(workSource)
 
-      if(!Data.isType(specResult, "array"))
+      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})) {
+    } else if(Data.isType(spec, "Array", {allowEmpty: false})) {
       workSpec.push(...spec)
     }
 
@@ -256,7 +260,7 @@ export default class Data {
     workSource.map((element, index, arr) => (arr[index] = String(element)))
 
     // Check that all keys are strings
-    if(!Data.isArrayUniform(workSource, "string"))
+    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]))
@@ -332,7 +336,13 @@ export default class Data {
    * @returns {boolean} Whether the type is valid
    */
   static isValidType(type) {
-    return Data.dataTypes.includes(type)
+    // Allow built-in types
+    if(Data.dataTypes.includes(type)) {
+      return true
+    }
+
+    // Allow custom classes (PascalCase starting with capital letter)
+    return /^[A-Z][a-zA-Z0-9]*$/.test(type)
   }
 
   /**
@@ -349,16 +359,13 @@ export default class Data {
       return false
 
     const valueType = Data.typeOf(value)
-    const normalizedType = type.toLowerCase()
 
     // Special cases that need extra validation
-    switch(normalizedType) {
-      case "number":
-        return valueType === "number" && !isNaN(value) // Excludes NaN
-      case "object":
-        return valueType === "object" && value !== null && !Array.isArray(value) // Excludes arrays and null
+    switch(valueType) {
+      case "Number":
+        return valueType === "Number" && !isNaN(value) // Excludes NaN
       default:
-        return valueType === normalizedType
+        return valueType === type
     }
   }
 
@@ -370,12 +377,13 @@ export default class Data {
    */
   static typeOf(value) {
     if(value === null)
-      return "null"
+      return "Null"
 
-    if(Array.isArray(value))
-      return "array"
+    const type = typeof value
 
-    return typeof value
+    return type === "object"
+      ? value.constructor.name
+      : type.charAt(0).toUpperCase() + type.slice(1)
   }
 
   /**
@@ -412,12 +420,12 @@ export default class Data {
       return false
 
     switch(type) {
-      case "array":
+      case "Array":
         return value.length === 0
-      case "object":
+      case "Object":
         // null was already handled above, so this should only be real objects
         return Object.keys(value).length === 0
-      case "string":
+      case "String":
         return value.trim().length === 0
       default:
         return false

package/src/lib/TypeSpec.js

@@ -6,6 +6,7 @@
 
 import Sass from "./Sass.js"
 import Data from "./Data.js"
+import Util from "./Util.js"
 
 /**
  * Type specification class for parsing and validating complex type definitions.
@@ -149,7 +150,7 @@ export default class TypeSpec {
     // Now, let's do some checking with the types, respecting the array flag
     // with the value
     const valueType = Data.typeOf(value)
-    const isArray = valueType === "array"
+    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.
@@ -166,8 +167,8 @@ export default class TypeSpec {
 
       // Handle array values
       if(isArray) {
-        // Special case for generic "array" type
-        if(allowedType === "array" && !allowedArray)
+        // Special case for generic "Array" type
+        if(allowedType === "Array" && !allowedArray)
           return allowEmpty || !empty
 
         // Must be an array type specification
@@ -203,16 +204,18 @@ export default class TypeSpec {
     const parts = string.split(delimiter)
 
     this.#specs = parts.map(part => {
-      const typeMatches = /(\w+)(\[\])?/.exec(part)
+      const typeMatches = /^(\w+)(\[\])?$/.exec(part)
 
       if(!typeMatches || typeMatches.length !== 3)
         throw Sass.new(`Invalid type: ${part}`)
 
-      if(!Data.isValidType(typeMatches[1]))
+      const typeName = Util.capitalize(typeMatches[1])
+
+      if(!Data.isValidType(typeName))
         throw Sass.new(`Invalid type: ${typeMatches[1]}`)
 
       return {
-        typeName: typeMatches[1],
+        typeName,
         array: typeMatches[2] === "[]",
       }
     })

package/src/types/Collection.d.ts

@@ -0,0 +1,138 @@
+// Implementation: ../lib/Collection.js
+// Type definitions for Collection utilities
+
+/**
+ * Collection utility functions for evaluating and manipulating arrays, objects, sets, and maps.
+ * Provides functional programming patterns for collection processing with consistent error handling.
+ */
+export default class Collection {
+  /**
+   * Evaluates an array with a predicate function, returning the first truthy result.
+   *
+   * @param collection - The array to evaluate
+   * @param predicate - Function called for each element: (element, index, array) => result
+   * @param forward - Whether to iterate forward (true) or backward (false). Default: true
+   * @returns The first truthy result from the predicate, or undefined if none found
+   *
+   * @throws {Sass} If collection is not an Array or predicate is not a Function
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Collection.evalArray(numbers, (n, i) => n > 3 ? n * 2 : null)
+   * console.log(result) // 8 (first element > 3, doubled)
+   * ```
+   */
+  static evalArray<T, R>(
+    collection: T[],
+    predicate: (element: T, index: number, array: T[]) => R | null | undefined,
+    forward?: boolean
+  ): R | undefined
+
+  /**
+   * Evaluates an object with a predicate function, returning the first truthy result.
+   *
+   * @param collection - The object to evaluate
+   * @param predicate - Function called for each property: (value, key, object) => result
+   * @returns The first truthy result from the predicate, or undefined if none found
+   *
+   * @throws {Sass} If collection is not an Object or predicate is not a Function
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * const obj = {a: 1, b: 2, c: 3}
+   * const result = Collection.evalObject(obj, (value, key) => value > 2 ? `${key}:${value}` : null)
+   * console.log(result) // "c:3"
+   * ```
+   */
+  static evalObject<T, R>(
+    collection: Record<string, T>,
+    predicate: (value: T, key: string, object: Record<string, T>) => R | null | undefined
+  ): R | undefined
+
+  /**
+   * Evaluates a Set with a predicate function, returning the first truthy result.
+   *
+   * @param collection - The Set to evaluate
+   * @param predicate - Function called for each element: (element, set) => result
+   * @returns The first truthy result from the predicate, or undefined if none found
+   *
+   * @throws {Sass} If collection is not a Set or predicate is not a Function
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * const set = new Set([1, 2, 3, 4, 5])
+   * const result = Collection.evalSet(set, (n, s) => n > 3 ? n * 2 : null)
+   * console.log(result) // 8
+   * ```
+   */
+  static evalSet<T, R>(
+    collection: Set<T>,
+    predicate: (element: T, set: Set<T>) => R | null | undefined
+  ): R | undefined
+
+  /**
+   * Evaluates a Map with a predicate function, returning the first truthy result.
+   *
+   * @param collection - The Map to evaluate
+   * @param predicate - Function called for each entry: (value, key, map) => result
+   * @param forward - Whether to iterate forward (true) or backward (false). Default: true
+   * @returns The first truthy result from the predicate, or undefined if none found
+   *
+   * @throws {Sass} If collection is not a Map or predicate is not a Function
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * const map = new Map([['a', 1], ['b', 2], ['c', 3]])
+   * const result = Collection.evalMap(map, (value, key) => value > 2 ? `${key}:${value}` : null)
+   * console.log(result) // "c:3"
+   * ```
+   */
+  static evalMap<K, V, R>(
+    collection: Map<K, V>,
+    predicate: (value: V, key: K, map: Map<K, V>) => R | null | undefined,
+    forward?: boolean
+  ): R | undefined
+
+  /**
+   * Zips two arrays together into an array of pairs.
+   *
+   * @param array1 - The first array
+   * @param array2 - The second array
+   * @returns Array of [element1, element2] pairs, length of shorter input array
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * const result = Collection.zip([1, 2, 3], ['a', 'b', 'c'])
+   * console.log(result) // [[1, 'a'], [2, 'b'], [3, 'c']]
+   * ```
+   */
+  static zip<T, U>(array1: T[], array2: U[]): [T, U][]
+
+  /**
+   * Unzips an array of arrays into separate arrays.
+   *
+   * @param array - Array of arrays to unzip
+   * @returns Array of separate arrays, one for each position
+   *
+   * @example
+   * ```typescript
+   * import { Collection } from '@gesslar/toolkit'
+   *
+   * const zipped = [[1, 'a'], [2, 'b'], [3, 'c']]
+   * const result = Collection.unzip(zipped)
+   * console.log(result) // [[1, 2, 3], ['a', 'b', 'c']]
+   * ```
+   */
+  static unzip<T>(array: T[][]): T[][]
+}

package/src/types/index.d.ts

@@ -6,6 +6,7 @@ export { default as FS } from './FS.js'
 
 // Utility classes
 export { default as Cache } from './Cache.js'
+export { default as Collection } from './Collection.js'
 export { default as Data } from './Data.js'
 export { default as Glog } from './Glog.js'
 export { default as Sass } from './Sass.js'