Promote array utils package

jsdoc.json

@@ -1,7 +1,7 @@
 {
   "source" : {
     "include": [
-      "packages/utils/array-utils/src",
+      "packages/array-utils/src",
 
       "packages/modeling/src/colors",
       "packages/modeling/src/curves",

package.json

@@ -4,6 +4,7 @@
   "description": "",
   "homepage": "https://openjscad.xyz/",
   "repository": "https://github.com/jscad/OpenJSCAD.org",
+  "type": "module",
   "scripts": {
     "docs": "jsdoc --configure jsdoc.json",
     "coverage": "lerna run --concurrency 1 --stream coverage",

packages/array-utils/src/coalesce.d.ts

@@ -0,0 +1,3 @@
+import type { RecursiveArray } from './recursiveArray.d.ts'
+
+export function coalesce<T>(arr: RecursiveArray<T>): Array<T>

packages/array-utils/src/coalesce.js

@@ -0,0 +1,24 @@
+/**
+ * Flattens and filters out nullish values from the given list of arguments.
+ *
+ * The arguments can be composed of multiple depths of objects and arrays.
+ * The output is a single flat array with no missing values.
+ *
+ * @param {Array} arr - list of arguments
+ * @returns {Array} a flat list of arguments
+ *
+ * @alias module:modeling/utils.coalesce
+ * @function
+ */
+export const coalesce = (arr) => flattenHelper(arr, [])
+
+// Helper to recursively append to a given list.
+// This is MUCH faster than other flatten methods.
+const flattenHelper = (arr, out) => {
+  if (Array.isArray(arr)) {
+    arr.forEach((child) => flattenHelper(child, out))
+  } else if (arr != null && arr !== undefined) {
+    out.push(arr)
+  }
+  return out
+}

packages/array-utils/src/coalesce.test.js

@@ -0,0 +1,35 @@
+import test from 'ava'
+
+import { coalesce } from './index.js'
+
+test('array-utils: coalesce() should coalesce arrays into an array', (t) => {
+  let obs = coalesce([1, 2, 3, 4])
+  let exp = [1, 2, 3, 4]
+  t.deepEqual(obs, exp)
+
+  obs = coalesce([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+  exp = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+  t.deepEqual(obs, exp)
+})
+
+test('array-utils: coalesce() should coalesce arrays with arrays and values into an array', (t) => {
+  let obs = coalesce([[1], 2, 3, [4]])
+  let exp = [1, 2, 3, 4]
+  t.deepEqual(obs, exp)
+
+  obs = coalesce([1, [2, 3], 4])
+  exp = [1, 2, 3, 4]
+  t.deepEqual(obs, exp)
+})
+
+test('array-utils: coalesce() should coalesce heiarchy of arrays and values into an array', (t) => {
+  const obs = coalesce([[1], [2, 3, [4, 5]], 6])
+  const exp = [1, 2, 3, 4, 5, 6]
+  t.deepEqual(obs, exp)
+})
+
+test('array-utils: coalesce() should coalesce arrays with nullish values into an array', (t) => {
+  const obs = coalesce([[1], [2, null, [4, undefined]], undefined])
+  const exp = [1, 2, 4]
+  t.deepEqual(obs, exp)
+})

packages/utils/array-utils/src/flatten.js → packages/array-utils/src/flatten.js

@@ -1,9 +1,14 @@
 /**
  * Flatten the given array into a single array of elements.
+ *
  * The given array can be composed of multiple depths of objects and or arrays.
+ *
  * @param {Array} array - array to flatten
  * @returns {Array} a flat array with a single list of elements
+ *
  * @alias module:array-utils.flatten
+ * @function
+ *
  * @example
  * const flat = flatten([[1], [2, 3, [4, 5]], 6]) // returns [1, 2, 3, 4, 5, 6]
  */

packages/utils/array-utils/src/fnNumberSort.js → packages/array-utils/src/fnNumberSort.js

@@ -1,9 +1,13 @@
 /**
  * Compare function for sorting arrays of numbers.
+ *
  * @param {number} a - first number
  * @param {number} b - second number
  * @return {number} result of a - b
+ *
  * @alias module:array-utils.fnNumberSort
+ * @function
+ *
  * @example
  * const numbers = [2, 1, 4, 3, 6, 5, 8, 7, 9, 0]
  * const sorted = numbers.sort(fnNumberSort)

packages/utils/array-utils/src/head.js → packages/array-utils/src/head.js

@@ -1,8 +1,12 @@
 /**
  * Return the first element of the given array.
+ *
  * @param {*} array - anything
  * @returns {*} first element of the array, or undefined
+ *
  * @alias module:array-utils.head
+ * @function
+ *
  * @example
  * let element = head([1, 2])
  */

packages/utils/array-utils/src/index.js → packages/array-utils/src/index.js

@@ -1,10 +1,13 @@
 /**
  * JSCAD Utility functions for arrays.
+ *
  * @module array-utils
+ *
  * @example
- * const { flatten, head } = require('@jscad/array-utils')
+ * import { flatten, head } from '@jscad/array-utils'
  */
 
+export { coalesce } from './coalesce.js'
 export { flatten } from './flatten.js'
 export { fnNumberSort } from './fnNumberSort.js'
 export { head } from './head.js'

packages/utils/array-utils/src/insertSorted.js → packages/array-utils/src/insertSorted.js

@@ -1,9 +1,13 @@
 /**
  * Insert the given element into the give array using the compareFunction.
+ *
  * @param {Array} array - array in which to insert
  * @param {*} element - element to insert into the array
  * @param {Function} compareFunction - a function that defines the sort order of elements
+ *
  * @alias module:array-utils.insertSorted
+ * @function
+ *
  * @example
  * const numbers = [1, 5]
  * const result = insertSorted(numbers, 3, fnNumberSort)

packages/utils/array-utils/src/nth.js → packages/array-utils/src/nth.js

@@ -1,9 +1,13 @@
 /**
  * Return the Nth element of the given array.
+ *
  * @param {*} array - anything
  * @param {number} index - index of the element to return
  * @returns {*} Nth element of the array, or undefined
+ *
  * @alias module:array-utils.nth
+ * @function
+ *
  * @example
  * let value = nth([1], 2) // undefined
  * let value = nth([1, 2, 3, 4, 5], 3) // 4

packages/utils/array-utils/src/padToLength.js → packages/array-utils/src/padToLength.js

@@ -1,11 +1,16 @@
 /**
  * Build an array of the given target length from an existing array and a padding value.
+ *
  * If the array is already larger than the target length, it will not be shortened.
+ *
  * @param {Array} anArray - the source array to copy into the result.
  * @param {*} padding - the value to add to the new array to reach the desired length.
  * @param {number} targetLength - The desired length of the returned array.
  * @returns {Array} an array with at least 'target length" elements
+ *
  * @alias module:array-utils.padToLength
+ * @function
+ *
  * @example
  * const srcArray = [2, 3, 4]
  * const paddedArray = padToLength(srcArray, 0, 5)

packages/utils/array-utils/src/toArray.js → packages/array-utils/src/toArray.js

@@ -1,8 +1,12 @@
 /**
  * Convert the given array to an array if not already an array.
+ *
  * @param {*} array - anything
  * @returns {Array} an array
+ *
  * @alias module:array-utils.toArray
+ * @function
+ *
  * @example
  * const array = toArray(1) // [1]
  */

pnpm-workspace.yaml

@@ -1,5 +1,6 @@
 prefer-workspace-packages: true
 packages:
+  - "packages/array-utils"
   - "packages/cli"
   - "packages/core"
   - "packages/io/io"
@@ -19,6 +20,5 @@ packages:
   - "packages/io/x3d-deserializer"
   - "packages/io/x3d-serializer"
   - "packages/modeling"
-  - "packages/utils/array-utils"
   - "packages/utils/img"
   - "packages/utils/regl-renderer"