@jwc/jscad-utils 4.9.0 → 5.0.1

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@jwc/jscad-utils",
-  "version": "4.9.0",
+  "version": "5.0.1",
   "description": "Utilities for use in a jscad script.",
+  "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",
   "files": [
@@ -10,8 +11,7 @@
     "jscad.json"
   ],
   "scripts": {
-    "test": "ava -v",
-    "test:cov": "nyc --reporter=html --reporter=lcov --reporter=text ava",
+    "test": "vitest",
     "build": "gulp all",
     "start": "gulp"
   },
@@ -32,50 +32,22 @@
   "license": "ISC",
   "dependencies": {
     "@jscad/csg": "0.7.0",
-    "@jscad/scad-api": "0.5.1"
+    "@jscad/scad-api": "0.5.1",
+    "@jwc/jscad-test-utils": "3.0.1",
+    "@jwc/jscad2-regl-renderer": "3.0.0",
+    "gl": "8.1.6",
+    "vitepress": "1.6.4",
+    "vitest": "3.2.4"
   },
   "devDependencies": {
-    "@babel/core": "7.20.7",
-    "@babel/preset-env": "7.20.2",
-    "@babel/register": "7.18.9",
-    "ava": "3.15.0",
-    "del": "6.1.1",
-    "eslint": "7.32.0",
-    "eslint-plugin-ava": "11.0.0",
-    "gulp": "4.0.2",
-    "gulp-debug": "4.0.0",
+    "@rollup/plugin-babel": "6.0.4",
+    "@rollup/plugin-node-resolve": "16.0.1",
+    "gulp": "5.0.1",
+    "gulp-debug": "5.0.1",
     "gulp-eslint": "6.0.0",
     "gulp-inject": "5.0.5",
-    "gulp-jscad-files": "4.1.0",
-    "gulp-jsdoc-to-markdown": "1.2.2",
-    "gulp-load-plugins": "2.0.8",
     "gulp-plumber": "1.2.1",
-    "gulp-terser": "1.4.1",
-    "gulp-util": "3.0.8",
-    "gulp-watch": "5.0.1",
-    "nyc": "15.1.0",
-    "rollup": "2.79.1",
-    "rollup-plugin-babel": "4.4.0",
-    "rollup-plugin-commonjs": "4.1.0",
-    "rollup-plugin-node-resolve": "5.2.0",
-    "vitepress": "1.6.4",
-    "vitepress-jsdoc": "1.0.4"
-  },
-  "ava": {
-    "files": [
-      "test/**/*.js",
-      "!test/helpers/**/*.js"
-    ],
-    "require": [
-      "esm",
-      "@babel/register",
-      "babel-polyfill",
-      "./test/helpers/compat-env.js"
-    ]
-  },
-  "babel": {
-    "presets": [
-      "@babel/preset-env"
-    ]
+    "gulp-terser": "2.1.0",
+    "rollup": "4.52.3"
   }
 }

package/src/add-prototype.js

@@ -1,18 +1,100 @@
+/** @typedef {object} ExtendedCSG
+ * @property {object} prototype 
+ * @property {function} prototype.color
+ * @property {function} prototype.flush
+ * @property {function} prototype.snap
+ * @property {function} prototype.calcSnap
+ * @property {function} prototype.midlineTo
+ * @property {function} prototype.calcmidlineTo
+ * @property {function} prototype.centerWith
+ * @property {function} prototype.calcCenter
+ * @property {function} prototype.align
+ * @property {function} prototype.calcAlign
+ * @property {function} prototype.enlarge
+ * @property {function} prototype.fit
+ * @property {function} prototype.size
+ * @property {function} prototype.centroid
+ * @property {function} prototype.Zero
+ * @property {function} prototype.Center
+ * @property {function} prototype.fillet
+ * @property {function} prototype.chamfer
+ * @property {function} prototype.bisect
+ * @property {function} prototype.slice
+ * @property {function} prototype.wedge
+ * @property {function} prototype.stretch
+ * @property {function} prototype.unionIf
+ * @property {function} prototype.subtractIf
+ * @property {function} prototype.translate
+ * @property {function} prototype.addConnector
+ * @property {function} prototype.connect
+ * @property {function} prototype.connectTo
+ * @property {object} Vector2D
+ * @property {function} Vector2D.prototype.map  
+ * @property {boolean} prototype._jscadutilsinit
+ * @property {function} result
+ * @property {function} array.addArray
+ * @property {function} unitCube
+ * @property {function} depreciated
+ * @property {function} error
+ * @property {function} size
+ * @property {function} centroid
+ * @property {function} zero
+ * @property {function} calcCenterWith
+ * @property {function} fillet
+ * @property {function} chamfer
+ * @property {function} bisect
+ * @property {function} slice
+ * @property {function} wedge
+ * @property {function} stretch
+ * @property {function} addConnector
+ * @property {function} echo 
+ * @property {function} log
+ * @property {function} warn
+ * @property {function} info
+ * @property {function} debug
+ * @property {function} table
+ * @property {function} dir
+ * @property {function} dirxml
+ * @property {function} trace
+ * @property {function} group
+ * @property {function} clear
+ * @property {function} count
+ * @property {function} countReset
+ * @property {function} time
+ * @property {function} timeLog
+ * @property {function} timeEnd
+ * @property {function} assert
+ * @property {function} profile
+ * @property {function} profileEnd
+ * @property {function} timeStamp
+ * @property {function} stackTrace
+ * @property {function} getConnector
+ */
+
+/** @typedef {import('./color').ColorName} ColorName */
+
+/** @typedef {import('@jscad/csg').CSG & ExtendedCSG} CSG */
 import { color } from './color';
 import * as util from './util';
 
 /**
  * Initialize `jscad-utils` and add utilities to the `proto` object.
- * @param  {proto} proto The global `proto` object
- * @augments proto
+ * @param  {CSG} proto The global `proto` object
  */
 export default function init(proto) {
   /**
-   * Short circut out if the prototypes have alrady been added.
+   * Short circuit out if the prototypes have already been added.
    */
   if (proto.prototype._jscadutilsinit) return;
 
-  // Colors.init(proto);
+  /**
+   * 
+   * @param {ColorName | number} r The red channel value (0.0 - 1.0) or a css color name
+   * @param {number} [g] The green channel value (0.0 - 1.0) or the alpha channel when used with a css color string
+   * @param {number} [b] The blue channel value (0.0 - 1.0)
+   * @param {number} [a] The alpha channel value (0.0 - 1.0) 
+   * @returns {CSG} The colored object
+   */
   proto.prototype.color = function (r, g, b, a) {
     if (!r) return this; // shortcut empty color values to do nothing.
     return color(this, r, g, b, a);
@@ -45,7 +127,6 @@ export default function init(proto) {
 
   if (proto.center) echo('proto already has .center');
   proto.prototype.center = function center(axis) {
-    // console.log('center', axis, this.getBounds());
     return util.centerWith(this, axis || 'xyz', util.unitCube(), 0);
   };
 
@@ -54,7 +135,6 @@ export default function init(proto) {
   };
 
   proto.prototype.align = function align(to, axis) {
-    // console.log('align', to.getBounds(), axis);
     return util.centerWith(this, axis, to);
   };
 
@@ -130,7 +210,7 @@ export default function init(proto) {
    * This modifies the normal `proto.translate` method to accept
    * multiple translations, adding the translations together.
    * The original translate is available on `proto._translate` and
-   * a short circut is applied when only one parameter is given.
+   * a short circuit is applied when only one parameter is given.
    * @return {proto} The resulting object.
    */
   proto.prototype.translate = function translate() {

package/src/color.js

@@ -1,3 +1,7 @@
+/** @typedef { import('@jscad/csg').CSG } CSG */
+
+/** @typedef {"aliceblue"|"antiquewhite"|"aqua"|"aquamarine"|"azure"|"beige"|"bisque"|"black"|"blanchedalmond"|"blue"|"blueviolet"|"brown"|"burlywood"|"cadetblue"|"chartreuse"|"chocolate"|"coral"|"cornflowerblue"|"cornsilk"|"crimson"|"cyan"|"darkblue"|"darkcyan"|"darkgoldenrod"|"darkgray"|"darkgrey"|"darkgreen"|"darkkhaki"|"darkmagenta"|"darkolivegreen"|"darkorange"|"darkorchid"|"darkred"|"darksalmon"|"darkseagreen"|"darkslateblue"|"darkslategray"|"darkslategrey"|"darkturquoise"|"darkviolet"|"deeppink"|"deepskyblue"|"dimgray"|"dimgrey"|"dodgerblue"|"firebrick"|"floralwhite"|"forestgreen"|"fuchsia"|"gainsboro"|"ghostwhite"|"gold"|"goldenrod"|"gray"|"grey"|"green"|"greenyellow"|"honeydew"|"hotpink"|"indianred"|"indigo"|"ivory"|"khaki"|"lavender"|"lavenderblush"|"lawngreen"|"lemonchiffon"|"lightblue"|"lightcoral"|"lightcyan"|"lightgoldenrodyellow"|"lightgray"|"lightgrey"|"lightgreen"|"lightpink"|"lightsalmon"|"lightseagreen"|"lightskyblue"|"lightslategray"|"lightslategrey"|"lightsteelblue"|"lightyellow"|"lime"|"limegreen"|"linen"|"magenta"|"maroon"|"mediumaquamarine"|"mediumblue"|"mediumorchid"|"mediumpurple"|"mediumseagreen"|"mediumslateblue"|"mediumspringgreen"|"mediumturquoise"|"mediumvioletred"|"midnightblue"|"mintcream"|"mistyrose"|"moccasin"|"navajowhite"|"navy"|"oldlace"|"olive"|"olivedrab"|"orange"|"orangered"|"orchid"|"palegoldenrod"|"palegreen"|"paleturquoise"|"palevioletred"|"papayawhip"|"peachpuff"|"peru"|"pink"|"plum"|"powderblue"|"purple"|"red"|"rosybrown"|"royalblue"|"saddlebrown"|"salmon"|"sandybrown"|"seagreen"|"seashell"|"sienna"|"silver"|"skyblue"|"slateblue"|"slategray"|"slategrey"|"snow"|"springgreen"|"steelblue"|"tan"|"teal"|"thistle"|"tomato"|"turquoise"|"violet"|"wheat"|"white"|"whitesmoke"|"yellow"|"yellowgreen"} ColorName */
+
 /**
  * Color utilities for jscad.  Makes setting colors easier using css color names.  Using `.init()` adds a `.color()` function to the CSG object.
  * > You must use `Colors.init(CSG)` in the `main()` function.  The `CSG` class is not available before
@@ -10,7 +14,7 @@
  *   // draws a purple cube
  *   return CSG.cube({radius: [10, 10, 10]}).color('purple');
  *}
- * @type {Object}
+ * @type {Record<ColorName, string>}
  */
 const nameArray = {
   aliceblue: '#f0f8ff',
@@ -162,12 +166,22 @@ const nameArray = {
   yellowgreen: '#9acd32'
 };
 
+/**
+ * Converts a css color name to a hex string.
+ * @param {ColorName} n A css color name
+ * @returns {string}
+ */
 export function name2hex(n) {
-  n = n.toLowerCase();
+  n = /** @type {ColorName} */ (n.toLowerCase());
   if (!nameArray[n]) return 'Invalid Color Name';
   return nameArray[n];
 }
 
+/**
+ * Converts a hex color string to an rgb array.
+ * @param {string} h
+ * @returns {number[]}
+ */
 export function hex2rgb(h) {
   h = h.replace(/^\#/, '');
 
@@ -177,65 +191,41 @@ export function hex2rgb(h) {
       parseInt(h.substr(2, 2), 16),
       parseInt(h.substr(4, 2), 16)
     ];
+  } else {
+    return [0, 0, 0];
   }
 }
 
+/**
+ * @type {Record<ColorName, number[]>}
+ */
 const _name2rgb = {};
 
+/**
+ * Converts a css color name to an rgb array.
+ * @param {ColorName} n A css color name
+ * @returns {number[]}
+ */
 export function name2rgb(n) {
   if (!_name2rgb[n]) _name2rgb[n] = hex2rgb(name2hex(n));
   return _name2rgb[n];
 }
 
+/**
+ *
+ * @param {CSG} o
+ * @param {number|string} r The red channel value (0.0 - 1.0) or a css color name
+ * @param {number} [g] The green channel value (0.0 - 1.0) or the alpha channel when used with a css color string
+ * @param {number} [b] The blue channel value (0.0 - 1.0)
+ * @param {number} [a] The alpha channel value (0.0 - 1.0)
+ * @returns {CSG}   Returns a `CSG` object set to the desired color.
+ */
 export function color(o, r, g, b, a) {
   if (typeof r !== 'string') return o.setColor(r, g, b, a);
   if (r === '') return o; // shortcut for no color
-  var c = name2rgb(r).map(function(x) {
+  var c = name2rgb(/** @type {ColorName} */(r)).map(function (x) {
     return x / 255;
   });
   c[3] = g || 1.0;
   return o.setColor(c);
 }
-
-/**
- * Initialize the Color utility.  This adds a `.color()` prototype to the `CSG` object.
- * @param  {CSG} CSG The global `CSG` object
- * @memberof module:jscad-utils-color
- * @augments CSG
- */
-// init: function init(proto) {
-//   // if (proto.setColor) {
-//   var _setColor = proto.setColor; // eslint-disable-line no-unused-vars
-
-//   /**
-//    * Set the color of a CSG object using a css color name.  Also accepts the normal `setColor()` values.
-//    * @example
-//    * // creates a red cube
-//    * var redcube = CSG.cube({radius: [1, 1, 1]}).color('red');
-//    *
-//    * // creates a blue cube with the alpha channel at 50%
-//    * var bluecube =  CSG.cube({radius: [1, 1, 1]}).color('blue', 0.5);
-//    *
-//    * // creates a green cube with the alpha channel at 25%
-//    * // this is the same as the standard setColor
-//    * var greencube =  proto.cube({radius: [1, 1, 1]}).color(0, 1, 0, 0.25);
-//    * @param  {(String | Number)} [red or css name] - Css color name or the red color channel value (0.0 - 1.0)
-//    * @param  {Number} [green or alpha] - green color channel value (0.0 - 1.0) or the alpha channel when used with a css color string
-//    * @param  {Number} [blue] - blue color channel value (0.0 - 1.0)
-//    * @param  {Number} [alpha] - alpha channel value (0.0 - 1.0)
-//    * @return {CSG}   Returns a `CSG` object set to the desired color.
-//    * @memberof module:CSG
-//    * @alias color
-//    * @chainable
-//    * @augments CSG
-//    */
-//   proto.prototype.color = function(r, g, b, a) {
-//     if (!r) return this; // shortcut empty color values to do nothing.
-//     return Colors.color(this, r, g, b, a);
-//   };
-//   // } else {
-//   //   console.error(
-//   //     `"${proto}" does not have a setColor function to add the Colors prototype to.  Make sure the object your trying to decorate with '.color' is correct.`
-//   //   );
-//   // }
-// }

package/src/util.js

@@ -1,3 +1,5 @@
+/** @typedef { import('@jscad/csg').CSG } CSG */
+
 import * as array from './array';
 import { Debug } from './debug';
 // import jsCadCSG from '@jscad/csg';
@@ -26,7 +28,7 @@ export const nearest = {
    * Return the largest number that is a multiple of the
    * nozzel size.
    * @param  {Number} desired                   Desired value
-   * @param  {Number} [nozzel=NOZZEL_SIZE] Nozel size, defaults to `NOZZEL_SIZE`
+   * @param  {Number} [nozzel=NOZZEL_SIZE] Nozzel size, defaults to `NOZZEL_SIZE`
    * @param  {Number} [nozzie=0]                Number of nozzel sizes to add to the value
    * @return {Number}                           Multiple of nozzel size
    */
@@ -34,10 +36,10 @@ export const nearest = {
     return (Math.floor(desired / nozzel) + nozzie) * nozzel;
   },
   /**
-   * Returns the largest number that is a multipel of the
+   * Returns the largest number that is a multiple of the
    * nozzel size, just over the desired value.
    * @param  {Number} desired                   Desired value
-   * @param  {Number} [nozzel=NOZZEL_SIZE] Nozel size, defaults to `NOZZEL_SIZE`
+   * @param  {Number} [nozzel=NOZZEL_SIZE] Nozzel size, defaults to `NOZZEL_SIZE`
    * @param  {Number} [nozzie=0]                Number of nozzel sizes to add to the value
    * @return {Number}                           Multiple of nozzel size
    */
@@ -47,9 +49,9 @@ export const nearest = {
 };
 
 /**
- * A function that reutrns the first argument.  Useful when
+ * A function that returns the first argument.  Useful when
  * passing in a callback to modify something, and you want a
- * default functiont hat does nothing.
+ * default function hat does nothing.
  * @param  {object} solid an object that will be returned
  * @return {object}       the first parameter passed into the function.
  * @function identity
@@ -59,13 +61,13 @@ export function identity(solid) {
 }
 
 /**
- * If `f` is a funciton, it is executed with `object` as the
+ * If `f` is a function, it is executed with `object` as the
  * parameter.  This is used in `CSG.unionIf` and `CSG.subtractIf`,
  * allowing you to pass a function instead of an object.  Since the
- * function isn't exeuted until called, the object to `union` or
+ * function isn't executed until called, the object to `union` or
  * `subtract` can be assembled only if the conditional is true.
  * @param  {object} object the context to run the function with.
- * @param  {function|object} f if a funciton it is executed, othewise the object is returned.
+ * @param  {function|object} f if a function it is executed, otherwise the object is returned.
  * @return {object}        the result of the function or the object.
  * @function result
  */
@@ -80,10 +82,10 @@ export function result(object, f) {
 /**
  * Returns target object with default values assigned. If values already exist, they are not set.
  * @param  {object} target   The target object to return.
- * @param  {object} defaults Defalut values to add to the object if they don't already exist.
+ * @param  {object} defaults Default values to add to the object if they don't already exist.
  * @return {object}          Target object with default values assigned.
  * @function defaults
- * @depricated
+ * @deprecated
  */
 export function defaults(target, defaults) {
   depreciated('defaults', true, 'use Object.assign instead');
@@ -99,11 +101,11 @@ export function isNegative(n) {
 }
 
 /**
- * Print a message and CSG object bounds and size to the conosle.
+ * Print a message and CSG object bounds and size to the console.
  * @param  {String} msg Message to print
  * @param  {CSG} o   A CSG object to print the bounds and size of.
  * @function
- * @depricated use Debug instead
+ * @deprecated use Debug instead
  */
 export function print(msg, o) {
   debug(
@@ -138,11 +140,11 @@ export function error(msg, name, error) {
 
 /**
  * Shows a warning or error message.  Used to indicate a method
- * has been depricated and what to use instead.
+ * has been deprecated and what to use instead.
  * @function depreciated
- * @param  {string} method  The name of the method being depricated.
+ * @param  {string} method  The name of the method being deprecated.
  * @param  {boolean} [error]  Throws an error if called when true.
- * @param  {string} [message] Instructions on what to use instead of the depricated method.
+ * @param  {string} [message] Instructions on what to use instead of the deprecated method.
  */
 export function depreciated(method, error, message) {
   var msg = method + ' is depreciated.' + (' ' + message || '');
@@ -243,7 +245,7 @@ export function ifArray(a, cb) {
  * Returns an array of positions along an object on a given axis.
  * @param  {CSG} object   The object to calculate the segments on.
  * @param  {number} segments The number of segments to create.
- * @param  {string} axis     Axis to create the sgements on.
+ * @param  {string} axis     Axis to create the segments on.
  * @return {Array}          An array of segment positions.
  * @function segment
  */
@@ -638,7 +640,7 @@ export function centroid(o, objectSize) {
  * @param  {CSG} o    A CSG object.
  * @param  {String} axis A string with the axis to operate on.
  * @param  {Number} to   Value to move the midline of the object to.
- * @return {Number[]} The tranform array needed to move the object.
+ * @return {Number[]} The transform array needed to move the object.
  */
 export function calcmidlineTo(o, axis, to) {
   var bounds = o.getBounds();
@@ -684,7 +686,7 @@ export function centerWith(o, axis, withObj) {
  * along the axis will be returned.  If no `offset`
  * is given, then the midway point on the axis is returned.
  * When the `offset` is positive, a point `offset` from the
- * mininum axis is returned.  When the `offset` is negative,
+ * minimum axis is returned.  When the `offset` is negative,
  * the `offset` is subtracted from the axis maximum.
  * @param  {Size} size    Size array of the object
  * @param  {Bounds} bounds  Bounds of the object
@@ -731,7 +733,7 @@ export function getDelta(size, bounds, axis, offset, nonzero) {
  */
 export function bisect(...args) {
   if (args.length < 2) {
-    error('bisect requries an object and an axis', 'JSCAD_UTILS_INVALID_ARGS');
+    error('bisect requires an object and an axis', 'JSCAD_UTILS_INVALID_ARGS');
   }
   var object = args[0];
   var axis = args[1];
@@ -944,7 +946,7 @@ export function wedge(object, start, end, axis) {
  * Wraps the `stretchAtPlane` call using the same
  * logic as `bisect`.
  * @param  {CSG} object   Object to stretch
- * @param  {String} axis     Axis to streatch along
+ * @param  {String} axis     Axis to stretch along
  * @param  {Number} distance Distance to stretch
  * @param  {Number} offset   Offset along the axis to cut the object
  * @return {CSG}          The stretched object.
@@ -1059,7 +1061,7 @@ export function slices2poly(slices, options, axis) {
     })
   );
 
-  // rotate with quick short circut
+  // rotate with quick short circuit
   var rotate =
     twistangle === 0
       ? function rotateZero(v) {
@@ -1178,7 +1180,7 @@ export function reShape(object, radius, orientation, options, slicer) {
 
   if (si.axis !== 'z')
     throw new Error(
-      'reShape error: CAG._toPlanePolytons only uses the "z" axis.  You must use the "z" axis for now.'
+      'reShape error: CAG._toPlanePolygons only uses the "z" axis.  You must use the "z" axis for now.'
     );
 
   var cutplane = CSG.OrthoNormalBasis.GetCartesian(