diff --git a/jsdoc.json b/jsdoc.json index 7024999c9..0026a24c9 100644 --- a/jsdoc.json +++ b/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", diff --git a/package.json b/package.json index 541c2c6d0..79b807f34 100644 --- a/package.json +++ b/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", diff --git a/packages/utils/array-utils/CHANGELOG.md b/packages/array-utils/CHANGELOG.md similarity index 100% rename from packages/utils/array-utils/CHANGELOG.md rename to packages/array-utils/CHANGELOG.md diff --git a/packages/utils/array-utils/README.md b/packages/array-utils/README.md similarity index 100% rename from packages/utils/array-utils/README.md rename to packages/array-utils/README.md diff --git a/packages/utils/array-utils/dist/jscad-array-utils.es.js b/packages/array-utils/dist/jscad-array-utils.es.js similarity index 100% rename from packages/utils/array-utils/dist/jscad-array-utils.es.js rename to packages/array-utils/dist/jscad-array-utils.es.js diff --git a/packages/utils/array-utils/dist/jscad-array-utils.min.js b/packages/array-utils/dist/jscad-array-utils.min.js similarity index 100% rename from packages/utils/array-utils/dist/jscad-array-utils.min.js rename to packages/array-utils/dist/jscad-array-utils.min.js diff --git a/packages/utils/array-utils/package.json b/packages/array-utils/package.json similarity index 100% rename from packages/utils/array-utils/package.json rename to packages/array-utils/package.json diff --git a/packages/utils/array-utils/rollup.config.js b/packages/array-utils/rollup.config.js similarity index 100% rename from packages/utils/array-utils/rollup.config.js rename to packages/array-utils/rollup.config.js diff --git a/packages/array-utils/src/coalesce.d.ts b/packages/array-utils/src/coalesce.d.ts new file mode 100644 index 000000000..aa4dcc6e7 --- /dev/null +++ b/packages/array-utils/src/coalesce.d.ts @@ -0,0 +1,3 @@ +import type { RecursiveArray } from './recursiveArray.d.ts' + +export function coalesce(arr: RecursiveArray): Array diff --git a/packages/array-utils/src/coalesce.js b/packages/array-utils/src/coalesce.js new file mode 100644 index 000000000..52145d4cf --- /dev/null +++ b/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 +} diff --git a/packages/array-utils/src/coalesce.test.js b/packages/array-utils/src/coalesce.test.js new file mode 100644 index 000000000..7f2e644a3 --- /dev/null +++ b/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) +}) diff --git a/packages/utils/array-utils/src/flatten.d.ts b/packages/array-utils/src/flatten.d.ts similarity index 100% rename from packages/utils/array-utils/src/flatten.d.ts rename to packages/array-utils/src/flatten.d.ts diff --git a/packages/utils/array-utils/src/flatten.js b/packages/array-utils/src/flatten.js similarity index 95% rename from packages/utils/array-utils/src/flatten.js rename to packages/array-utils/src/flatten.js index fd1640927..e8ad277b5 100644 --- a/packages/utils/array-utils/src/flatten.js +++ b/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] */ diff --git a/packages/utils/array-utils/src/flatten.test.js b/packages/array-utils/src/flatten.test.js similarity index 100% rename from packages/utils/array-utils/src/flatten.test.js rename to packages/array-utils/src/flatten.test.js diff --git a/packages/utils/array-utils/src/fnNumberSort.d.ts b/packages/array-utils/src/fnNumberSort.d.ts similarity index 100% rename from packages/utils/array-utils/src/fnNumberSort.d.ts rename to packages/array-utils/src/fnNumberSort.d.ts diff --git a/packages/utils/array-utils/src/fnNumberSort.js b/packages/array-utils/src/fnNumberSort.js similarity index 94% rename from packages/utils/array-utils/src/fnNumberSort.js rename to packages/array-utils/src/fnNumberSort.js index a97a31238..e7d7b0a9c 100644 --- a/packages/utils/array-utils/src/fnNumberSort.js +++ b/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) diff --git a/packages/utils/array-utils/src/fnNumberSort.test.js b/packages/array-utils/src/fnNumberSort.test.js similarity index 100% rename from packages/utils/array-utils/src/fnNumberSort.test.js rename to packages/array-utils/src/fnNumberSort.test.js diff --git a/packages/utils/array-utils/src/head.d.ts b/packages/array-utils/src/head.d.ts similarity index 100% rename from packages/utils/array-utils/src/head.d.ts rename to packages/array-utils/src/head.d.ts diff --git a/packages/utils/array-utils/src/head.js b/packages/array-utils/src/head.js similarity index 94% rename from packages/utils/array-utils/src/head.js rename to packages/array-utils/src/head.js index 4bdff6e3a..21ba9d665 100644 --- a/packages/utils/array-utils/src/head.js +++ b/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]) */ diff --git a/packages/utils/array-utils/src/head.test.js b/packages/array-utils/src/head.test.js similarity index 100% rename from packages/utils/array-utils/src/head.test.js rename to packages/array-utils/src/head.test.js diff --git a/packages/utils/array-utils/src/index.d.ts b/packages/array-utils/src/index.d.ts similarity index 100% rename from packages/utils/array-utils/src/index.d.ts rename to packages/array-utils/src/index.d.ts diff --git a/packages/utils/array-utils/src/index.js b/packages/array-utils/src/index.js similarity index 78% rename from packages/utils/array-utils/src/index.js rename to packages/array-utils/src/index.js index 2c0a3156e..6917d8986 100644 --- a/packages/utils/array-utils/src/index.js +++ b/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' diff --git a/packages/utils/array-utils/src/index.test-d.ts b/packages/array-utils/src/index.test-d.ts similarity index 100% rename from packages/utils/array-utils/src/index.test-d.ts rename to packages/array-utils/src/index.test-d.ts diff --git a/packages/utils/array-utils/src/insertSorted.d.ts b/packages/array-utils/src/insertSorted.d.ts similarity index 100% rename from packages/utils/array-utils/src/insertSorted.d.ts rename to packages/array-utils/src/insertSorted.d.ts diff --git a/packages/utils/array-utils/src/insertSorted.js b/packages/array-utils/src/insertSorted.js similarity index 97% rename from packages/utils/array-utils/src/insertSorted.js rename to packages/array-utils/src/insertSorted.js index 09388b175..b20444de3 100644 --- a/packages/utils/array-utils/src/insertSorted.js +++ b/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) diff --git a/packages/utils/array-utils/src/insertSorted.test.js b/packages/array-utils/src/insertSorted.test.js similarity index 100% rename from packages/utils/array-utils/src/insertSorted.test.js rename to packages/array-utils/src/insertSorted.test.js diff --git a/packages/utils/array-utils/src/nth.d.ts b/packages/array-utils/src/nth.d.ts similarity index 100% rename from packages/utils/array-utils/src/nth.d.ts rename to packages/array-utils/src/nth.d.ts diff --git a/packages/utils/array-utils/src/nth.js b/packages/array-utils/src/nth.js similarity index 95% rename from packages/utils/array-utils/src/nth.js rename to packages/array-utils/src/nth.js index 1cdd32c69..b108b82cb 100644 --- a/packages/utils/array-utils/src/nth.js +++ b/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 diff --git a/packages/utils/array-utils/src/nth.test.js b/packages/array-utils/src/nth.test.js similarity index 100% rename from packages/utils/array-utils/src/nth.test.js rename to packages/array-utils/src/nth.test.js diff --git a/packages/utils/array-utils/src/padToLength.d.ts b/packages/array-utils/src/padToLength.d.ts similarity index 100% rename from packages/utils/array-utils/src/padToLength.d.ts rename to packages/array-utils/src/padToLength.d.ts diff --git a/packages/utils/array-utils/src/padToLength.js b/packages/array-utils/src/padToLength.js similarity index 96% rename from packages/utils/array-utils/src/padToLength.js rename to packages/array-utils/src/padToLength.js index 33744f658..65d6bebf5 100644 --- a/packages/utils/array-utils/src/padToLength.js +++ b/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) diff --git a/packages/utils/array-utils/src/padToLength.test.js b/packages/array-utils/src/padToLength.test.js similarity index 100% rename from packages/utils/array-utils/src/padToLength.test.js rename to packages/array-utils/src/padToLength.test.js diff --git a/packages/utils/array-utils/src/recursiveArray.d.ts b/packages/array-utils/src/recursiveArray.d.ts similarity index 100% rename from packages/utils/array-utils/src/recursiveArray.d.ts rename to packages/array-utils/src/recursiveArray.d.ts diff --git a/packages/utils/array-utils/src/toArray.d.ts b/packages/array-utils/src/toArray.d.ts similarity index 100% rename from packages/utils/array-utils/src/toArray.d.ts rename to packages/array-utils/src/toArray.d.ts diff --git a/packages/utils/array-utils/src/toArray.js b/packages/array-utils/src/toArray.js similarity index 94% rename from packages/utils/array-utils/src/toArray.js rename to packages/array-utils/src/toArray.js index 2290ef5ba..63fc5a547 100644 --- a/packages/utils/array-utils/src/toArray.js +++ b/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] */ diff --git a/packages/utils/array-utils/src/toArray.test.js b/packages/array-utils/src/toArray.test.js similarity index 100% rename from packages/utils/array-utils/src/toArray.test.js rename to packages/array-utils/src/toArray.test.js diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index bac776f8e..6fc3ac10c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -30,6 +30,20 @@ importers: standardx: 7.0.0 tsd: 0.28.1 + packages/array-utils: + specifiers: + '@rollup/plugin-terser': ^0.4.3 + ava: ^4.3.3 + c8: ^8.0.0 + rollup: ^2.79.1 + rollup-plugin-banner: ^0.2.1 + devDependencies: + '@rollup/plugin-terser': 0.4.3_rollup@2.79.1 + ava: 4.3.3 + c8: 8.0.1 + rollup: 2.79.1 + rollup-plugin-banner: 0.2.1 + packages/cli: specifiers: '@jscad/array-utils': workspace:3.0.1-alpha.0 @@ -41,7 +55,7 @@ importers: c8: ^8.0.0 jszip: ^3.10.1 dependencies: - '@jscad/array-utils': link:../utils/array-utils + '@jscad/array-utils': link:../array-utils '@jscad/core': link:../core '@jscad/io': link:../io/io '@jscad/io-utils': link:../io/io-utils @@ -62,7 +76,7 @@ importers: json5: 2.2.3 strip-bom: 4.0.0 dependencies: - '@jscad/array-utils': link:../utils/array-utils + '@jscad/array-utils': link:../array-utils '@jscad/io': link:../io/io '@jscad/io-utils': link:../io/io-utils '@jscad/modeling': link:../modeling @@ -87,7 +101,7 @@ importers: rollup-plugin-version-injector: ^1.3.3 saxes: ^6.0.0 dependencies: - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/modeling': link:../../modeling fflate: 0.7.3 saxes: 6.0.0 @@ -116,7 +130,7 @@ importers: rollup: ^2.79.1 rollup-plugin-banner: ^0.2.1 dependencies: - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/io-utils': link:../io-utils '@jscad/modeling': link:../../modeling fflate: 0.7.3 @@ -164,7 +178,7 @@ importers: rollup: ^2.79.1 rollup-plugin-banner: ^0.2.1 dependencies: - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/modeling': link:../../modeling devDependencies: '@rollup/plugin-node-resolve': 15.2.1_rollup@2.79.1 @@ -198,7 +212,7 @@ importers: dependencies: '@jscad/3mf-deserializer': link:../3mf-deserializer '@jscad/3mf-serializer': link:../3mf-serializer - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/dxf-deserializer': link:../dxf-deserializer '@jscad/dxf-serializer': link:../dxf-serializer '@jscad/io-utils': link:../io-utils @@ -240,7 +254,7 @@ importers: rollup-plugin-banner: ^0.2.1 rollup-plugin-version-injector: ^1.3.3 dependencies: - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/io-utils': link:../io-utils devDependencies: '@jscad/modeling': link:../../modeling @@ -263,7 +277,7 @@ importers: rollup: ^2.79.1 rollup-plugin-banner: ^0.2.1 dependencies: - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/modeling': link:../../modeling devDependencies: '@rollup/plugin-node-resolve': 15.2.1_rollup@2.79.1 @@ -307,7 +321,7 @@ importers: rollup: ^2.79.1 rollup-plugin-banner: ^0.2.1 dependencies: - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/modeling': link:../../modeling devDependencies: '@rollup/plugin-node-resolve': 15.0.1_rollup@2.79.1 @@ -351,7 +365,7 @@ importers: rollup: ^2.79.1 rollup-plugin-banner: ^0.2.1 dependencies: - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/modeling': link:../../modeling devDependencies: '@rollup/plugin-node-resolve': 15.0.1_rollup@2.79.1 @@ -376,7 +390,7 @@ importers: rollup-plugin-version-injector: ^1.3.3 saxes: 6.0.0 dependencies: - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/io-utils': link:../io-utils '@jscad/modeling': link:../../modeling saxes: 6.0.0 @@ -428,7 +442,7 @@ importers: rollup-plugin-version-injector: ^1.3.3 saxes: ^6.0.0 dependencies: - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/io-utils': link:../io-utils '@jscad/modeling': link:../../modeling saxes: 6.0.0 @@ -455,7 +469,7 @@ importers: rollup: ^2.79.1 rollup-plugin-banner: ^0.2.1 dependencies: - '@jscad/array-utils': link:../../utils/array-utils + '@jscad/array-utils': link:../../array-utils '@jscad/io-utils': link:../io-utils '@jscad/modeling': link:../../modeling onml: 1.3.0 @@ -481,20 +495,6 @@ importers: rollup: 2.79.1 rollup-plugin-banner: 0.2.1 - packages/utils/array-utils: - specifiers: - '@rollup/plugin-terser': ^0.4.3 - ava: ^4.3.3 - c8: ^8.0.0 - rollup: ^2.79.1 - rollup-plugin-banner: ^0.2.1 - devDependencies: - '@rollup/plugin-terser': 0.4.3_rollup@2.79.1 - ava: 4.3.3 - c8: 8.0.0 - rollup: 2.79.1 - rollup-plugin-banner: 0.2.1 - packages/utils/img: specifiers: pngjs: ^6.0.0 @@ -519,7 +519,7 @@ importers: rollup: ^2.79.1 rollup-plugin-banner: ^0.2.1 dependencies: - '@jscad/array-utils': link:../array-utils + '@jscad/array-utils': link:../../array-utils camera-unproject: 1.0.1 gl-mat4: 1.2.0 gl-vec3: 1.1.3 @@ -7404,7 +7404,7 @@ packages: dev: true github.com/jscad/sample-files/f6f6485e7286a50c4c304d697be9cc9f7e64beb6: - resolution: {tarball: https://codeload.github.com/jscad/sample-files/tar.gz/f6f6485e7286a50c4c304d697be9cc9f7e64beb6} + resolution: {commit: f6f6485e7286a50c4c304d697be9cc9f7e64beb6, repo: git+ssh://git@github.com/jscad/sample-files.git, type: git} name: '@jscad/sample-files' version: 0.0.0 dev: true diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 6b491fc94..271bebdc4 100644 --- a/pnpm-workspace.yaml +++ b/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"