@gesslar/toolkit 0.2.5 → 0.2.7

package/package.json

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

package/src/lib/Collection.js

@@ -498,7 +498,44 @@ export default class Collection {
     return result
   }
 
-  static flattenObjectArray(objects) {
+  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
+  }
+
+  static transposeObjects(objects) {
     const req = "Array"
     const type = Data.typeOf(objects)
 
@@ -522,4 +559,10 @@ export default class Collection {
       return acc
     }, {})
   }
+
+  static flattenObjectArray(input) {
+    const flattened = Array.isArray(input) ? input.flat() : input
+
+    return Collection.transposeObjects(flattened)
+  }
 }

package/src/types/Collection.d.ts

@@ -214,27 +214,103 @@ 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(
+    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.
+   *
+   * @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 flattenObjectArray(objects: Array<Record<string, unknown>>): Record<string, Array<unknown>>
+  static trimArrayLeft<T>(arr: Array<T>, except?: Array<T>): Array<T>
 }