@gesslar/toolkit 0.2.6 → 0.2.8

package/package.json

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

package/src/lib/Collection.js

@@ -498,31 +498,6 @@ 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")
@@ -559,4 +534,35 @@ export default class Collection {
 
     return arr
   }
+
+  static transposeObjects(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 flattenObjectArray(input) {
+    const flattened = Array.isArray(input) ? input.flat() : input
+
+    return Collection.transposeObjects(flattened)
+  }
 }

package/src/lib/FileObject.js

@@ -353,12 +353,12 @@ export default class FileObject extends FS {
   async read(encoding="utf8") {
     const filePath = this.path
 
-    if(!(await this.exists))
-      throw Sass.new(`No such file '${filePath}'`)
-
     if(!filePath)
       throw Sass.new("No absolute path in file map")
 
+    if(!(await this.exists))
+      throw Sass.new(`No such file '${filePath}'`)
+
     return await fs.readFile(filePath, encoding)
   }
 
@@ -409,4 +409,21 @@ export default class FileObject extends FS {
 
     throw Sass.new(`Content is neither valid JSON5 nor valid YAML:\n'${this.path}'`)
   }
+
+  /**
+   * Loads a file as a module and returns it.
+   *
+   * @returns {Promise<object>} The file contents as a module.
+   */
+  async import() {
+    const fileUri = this.uri
+
+    if(!fileUri)
+      throw Sass.new("No URI in file map")
+
+    if(!(await this.exists))
+      throw Sass.new(`No such file '${fileUri}'`)
+
+    return await import(fileUri)
+  }
 }

package/src/types/Collection.d.ts

@@ -214,29 +214,45 @@ export default class Collection {
   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.
+   * Flattens one level of an array of plain objects, transposing values so each
+   * key maps to the collected values from every object.
    *
-   * @param objects - Array of plain objects to flatten
+   * Accepts either a simple array of objects or an array that mixes objects and
+   * nested object arrays (one level deep). Nested arrays are flattened before
+   * transposition.
+   *
+   * @param input - Array of plain objects (optionally containing nested arrays)
    * @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
+   * @throws {Sass} If input is not an Array or if any element is not a plain object after flattening
    *
    * @example
    * ```typescript
    * import { Collection } from '@gesslar/toolkit'
    *
    * const objects = [
-   *   { name: 'Alice', age: 25 },
-   *   { name: 'Bob', age: 30 },
-   *   { name: 'Charlie', age: 35 }
+   *   [{ name: 'Alice', age: 25 }],
+   *   { name: 'Bob', age: 30 }
    * ]
    *
    * const result = Collection.flattenObjectArray(objects)
-   * // result: { name: ['Alice', 'Bob', 'Charlie'], age: [25, 30, 35] }
+   * // result: { name: ['Alice', 'Bob'], age: [25, 30] }
    * ```
    */
-  static flattenObjectArray(objects: Array<Record<string, unknown>>): Record<string, Array<unknown>>
+  static flattenObjectArray(
+    input: Array<Record<string, unknown> | Array<Record<string, unknown>>>
+  ): Record<string, Array<unknown>>
+
+  /**
+   * Transposes an array of plain objects into an object of arrays, keyed by the
+   * original object keys.
+   *
+   * @param objects - Array of plain objects to transpose
+   * @returns Object with keys mapped to arrays of values from the input objects
+   *
+   * @throws {Sass} If objects is not an Array or if any element is not a plain object
+   */
+  static transposeObjects(objects: Array<Record<string, unknown>>): Record<string, Array<unknown>>
 
   /**
    * Trims falsy values from both ends of an array.

package/src/types/FileObject.d.ts

@@ -326,4 +326,27 @@ export default class FileObject extends FS {
 
   /** Load an object from JSON5 or YAML file with type specification */
   loadData(type?: 'json' | 'json5' | 'yaml' | 'any', encoding?: string): Promise<unknown>
+
+  /**
+   * Dynamically import the file using the resolved file URI.
+   *
+   * Uses Node.js' native dynamic `import()` under the hood, allowing consumers to load
+   * ESM modules from disk with full path resolution handled by FileObject. The method
+   * verifies the file exists before attempting the import to provide clearer error
+   * messaging and prevent low-level loader failures.
+   *
+   * @typeParam TModule - Expected module shape. Defaults to a loose record to help with
+   * module namespace typing.
+   *
+   * @returns The imported module namespace object.
+   *
+   * @throws {Error} When the file does not exist or the path cannot be converted to a URI.
+   *
+   * @example
+   * ```typescript
+   * const configModule = await file.import<{ default: Config }>()
+   * const config = configModule.default
+   * ```
+   */
+  import<TModule = Record<string, unknown>>(): Promise<TModule>
 }