rclnodejs 1.6.0 → 1.7.0

package/lib/parameter.js

@@ -20,6 +20,12 @@
 'use strict';
 
 const { isClose } = require('./utils.js');
+const {
+  TypeValidationError,
+  RangeValidationError,
+  ParameterError,
+  ParameterTypeError,
+} = require('./errors.js');
 
 /**
  * The plus/minus tolerance for determining number equivalence.
@@ -184,17 +190,25 @@ class Parameter {
       typeof this.name !== 'string' ||
       this.name.trim().length === 0
     ) {
-      throw new TypeError('Invalid name');
+      throw new TypeValidationError('name', this.name, 'non-empty string', {
+        entityType: 'parameter',
+      });
     }
 
     // validate type
     if (!validType(this.type)) {
-      throw new TypeError('Invalid type');
+      throw new ParameterError('Invalid parameter type', this.name, {
+        details: { providedType: this.type },
+      });
     }
 
     // validate value
     if (!validValue(this.value, this.type)) {
-      throw new TypeError('Incompatible value.');
+      throw new ParameterTypeError(this.name, this.type, typeof this.value, {
+        details: {
+          providedValue: this.value,
+        },
+      });
     }
 
     this._dirty = false;
@@ -383,10 +397,23 @@ class ParameterDescriptor {
       return;
     }
     if (!(range instanceof Range)) {
-      throw TypeError('Expected instance of Range.');
+      throw new TypeValidationError('range', range, 'Range', {
+        entityType: 'parameter descriptor',
+        parameterName: this.name,
+      });
     }
     if (!range.isValidType(this.type)) {
-      throw TypeError('Incompatible Range');
+      throw new ParameterError(
+        'Incompatible Range for parameter type',
+        this.name,
+        {
+          entityType: 'parameter descriptor',
+          details: {
+            rangeType: range.constructor.name,
+            parameterType: this.type,
+          },
+        }
+      );
     }
 
     this._range = range;
@@ -405,22 +432,40 @@ class ParameterDescriptor {
       typeof this.name !== 'string' ||
       this.name.trim().length === 0
     ) {
-      throw new TypeError('Invalid name');
+      throw new TypeValidationError('name', this.name, 'non-empty string', {
+        entityType: 'parameter descriptor',
+      });
     }
 
     // validate type
     if (!validType(this.type)) {
-      throw new TypeError('Invalid type');
+      throw new ParameterError('Invalid parameter type', this.name, {
+        entityType: 'parameter descriptor',
+        details: { providedType: this.type },
+      });
     }
 
     // validate description
     if (this.description && typeof this.description !== 'string') {
-      throw new TypeError('Invalid description');
+      throw new TypeValidationError('description', this.description, 'string', {
+        entityType: 'parameter descriptor',
+        parameterName: this.name,
+      });
     }
 
     // validate rangeConstraint
     if (this.hasRange() && !this.range.isValidType(this.type)) {
-      throw new TypeError('Incompatible Range');
+      throw new ParameterError(
+        'Incompatible Range for parameter type',
+        this.name,
+        {
+          entityType: 'parameter descriptor',
+          details: {
+            rangeType: this.range.constructor.name,
+            parameterType: this.type,
+          },
+        }
+      );
     }
   }
 
@@ -433,27 +478,66 @@ class ParameterDescriptor {
    */
   validateParameter(parameter) {
     if (!parameter) {
-      throw new TypeError('Parameter is undefined');
+      throw new TypeValidationError('parameter', parameter, 'Parameter', {
+        entityType: 'parameter descriptor',
+        parameterName: this.name,
+      });
     }
 
     // ensure parameter is valid
     try {
       parameter.validate();
-    } catch {
-      throw new TypeError('Parameter is invalid');
+    } catch (err) {
+      throw new ParameterError('Parameter is invalid', parameter.name, {
+        cause: err,
+        details: { validationError: err.message },
+      });
     }
 
     // ensure this descriptor is valid
     try {
       this.validate();
-    } catch {
-      throw new Error('Descriptor is invalid.');
+    } catch (err) {
+      throw new ParameterError('Descriptor is invalid', this.name, {
+        entityType: 'parameter descriptor',
+        cause: err,
+        details: { validationError: err.message },
+      });
     }
 
-    if (this.name !== parameter.name) throw new Error('Name mismatch');
-    if (this.type !== parameter.type) throw new Error('Type mismatch');
+    if (this.name !== parameter.name) {
+      throw new ParameterError('Name mismatch', this.name, {
+        details: {
+          descriptorName: this.name,
+          parameterName: parameter.name,
+        },
+      });
+    }
+    if (this.type !== parameter.type) {
+      throw new ParameterTypeError(this.name, this.type, parameter.type, {
+        details: {
+          expectedType: this.type,
+          actualType: parameter.type,
+        },
+      });
+    }
     if (this.hasRange() && !this.range.inRange(parameter.value)) {
-      throw new RangeError('Parameter value is not in descriptor range');
+      throw new RangeValidationError(
+        'value',
+        parameter.value,
+        `${this.range.fromValue} to ${this.range.toValue}`,
+        {
+          entityType: 'parameter',
+          parameterName: parameter.name,
+          details: {
+            range: {
+              from: this.range.fromValue,
+              to: this.range.toValue,
+              step: this.range.step,
+            },
+          },
+        }
+      );
     }
   }
 
@@ -550,7 +634,9 @@ class Range {
         true
       );
     } else if (typeof value !== 'number' && typeof value !== 'bigint') {
-      throw new TypeError('Value must be a number or bigint');
+      throw new TypeValidationError('value', value, 'number or bigint', {
+        entityType: 'range',
+      });
     }
 
     return true;
@@ -693,30 +779,80 @@ class IntegerRange extends Range {
  * @param {any} value - The value to infer it's ParameterType
  * @returns {ParameterType} - The ParameterType that best scribes the value.
  */
-// eslint-disable-next-line no-unused-vars
 function parameterTypeFromValue(value) {
-  if (!value) return ParameterType.PARAMETER_NOT_SET;
-  if (typeof value === 'boolean') return ParameterType.PARAMETER_BOOL;
-  if (typeof value === 'string') return ParameterType.PARAMETER_STRING;
-  if (typeof value === 'number') return ParameterType.PARAMETER_DOUBLE;
-  if (Array.isArray(value)) {
+  if (value === null || value === undefined) {
+    return ParameterType.PARAMETER_NOT_SET;
+  }
+
+  if (typeof value === 'boolean') {
+    return ParameterType.PARAMETER_BOOL;
+  }
+
+  if (typeof value === 'string') {
+    return ParameterType.PARAMETER_STRING;
+  }
+
+  if (typeof value === 'bigint') {
+    return ParameterType.PARAMETER_INTEGER;
+  }
+
+  if (typeof value === 'number') {
+    // Distinguish between integer and double
+    return Number.isInteger(value)
+      ? ParameterType.PARAMETER_INTEGER
+      : ParameterType.PARAMETER_DOUBLE;
+  }
+
+  // Handle TypedArrays
+  if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+    if (value instanceof Uint8Array) {
+      return ParameterType.PARAMETER_BYTE_ARRAY;
+    }
+    // For other typed arrays, infer from first element
     if (value.length > 0) {
-      const elementType = parameterTypeFromValue(value[0]);
-      switch (elementType) {
-        case ParameterType.PARAMETER_BOOL:
-          return ParameterType.PARAMETER_BOOL_ARRAY;
-        case ParameterType.PARAMETER_DOUBLE:
-          return ParameterType.PARAMETER_DOUBLE_ARRAY;
-        case ParameterType.PARAMETER_STRING:
-          return ParameterType.PARAMETER_STRING_ARRAY;
+      const firstType = parameterTypeFromValue(value[0]);
+      if (firstType === ParameterType.PARAMETER_INTEGER) {
+        return ParameterType.PARAMETER_INTEGER_ARRAY;
       }
+      return ParameterType.PARAMETER_DOUBLE_ARRAY;
     }
-
     return ParameterType.PARAMETER_NOT_SET;
   }
 
-  // otherwise unrecognized value
-  throw new TypeError('Unrecognized parameter type.');
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return ParameterType.PARAMETER_NOT_SET;
+    }
+
+    const elementType = parameterTypeFromValue(value[0]);
+    switch (elementType) {
+      case ParameterType.PARAMETER_BOOL:
+        return ParameterType.PARAMETER_BOOL_ARRAY;
+      case ParameterType.PARAMETER_INTEGER:
+        return ParameterType.PARAMETER_INTEGER_ARRAY;
+      case ParameterType.PARAMETER_DOUBLE:
+        return ParameterType.PARAMETER_DOUBLE_ARRAY;
+      case ParameterType.PARAMETER_STRING:
+        return ParameterType.PARAMETER_STRING_ARRAY;
+      default:
+        return ParameterType.PARAMETER_NOT_SET;
+    }
+  }
+
+  // Unrecognized value type
+  throw new TypeValidationError('value', value, 'valid parameter type', {
+    entityType: 'parameter',
+    details: {
+      supportedTypes: [
+        'boolean',
+        'string',
+        'number',
+        'boolean[]',
+        'number[]',
+        'string[]',
+      ],
+    },
+  });
 }
 
 /**
@@ -826,4 +962,5 @@ module.exports = {
   FloatingPointRange,
   IntegerRange,
   DEFAULT_NUMERIC_RANGE_TOLERANCE,
+  parameterTypeFromValue,
 };