@ya-modbus/driver-sdk 0.4.1-refactor-scope-driver-packages.0

package/README.md

@@ -0,0 +1,357 @@
+# @ya-modbus/driver-sdk
+
+Runtime SDK for ya-modbus device drivers with transformation utilities and helpers.
+
+## Overview
+
+This package provides reusable utilities for developing Modbus device drivers:
+
+- **Codec functions**: Read/write scaled integer values from/to register buffers
+- **Validators**: Type-safe configuration validation with TypeScript type narrowing
+- **Error formatting**: Consistent validation error messages
+
+## Installation
+
+```bash
+npm install @ya-modbus/driver-sdk
+```
+
+## API Reference
+
+### Codec Functions
+
+Utilities for reading and writing scaled integer values from Modbus register buffers.
+
+#### `readScaledUInt16BE(buffer, offset, scale)`
+
+Read and scale an unsigned 16-bit integer from a buffer.
+
+**Parameters:**
+
+- `buffer: Buffer` - Buffer containing register data
+- `offset: number` - Byte offset to start reading from
+- `scale: number` - Scale factor (e.g., 10 for ×10 values)
+
+**Returns:** `number` - Scaled floating-point value
+
+**Throws:** Error if scale is not a finite positive number
+
+**Example:**
+
+```typescript
+import { readScaledUInt16BE } from '@ya-modbus/driver-sdk'
+
+// Device stores temperature as integer ×10 (235 = 23.5°C)
+const buffer = await transport.readInputRegisters(0, 1)
+const temperature = readScaledUInt16BE(buffer, 0, 10)
+// temperature = 23.5
+```
+
+#### `readScaledInt16BE(buffer, offset, scale)`
+
+Read and scale a signed 16-bit integer from a buffer.
+
+**Parameters:**
+
+- `buffer: Buffer` - Buffer containing register data
+- `offset: number` - Byte offset to start reading from
+- `scale: number` - Scale factor (e.g., 10 for ×10 values)
+
+**Returns:** `number` - Scaled floating-point value
+
+**Throws:** Error if scale is not a finite positive number
+
+**Example:**
+
+```typescript
+import { readScaledInt16BE } from '@ya-modbus/driver-sdk'
+
+// Device stores correction offset as signed integer ×10 (-50 = -5.0°C)
+const buffer = await transport.readHoldingRegisters(0x103, 1)
+const correction = readScaledInt16BE(buffer, 0, 10)
+// correction = -5.0
+```
+
+#### `readScaledUInt32BE(buffer, offset, scale)`
+
+Read and scale an unsigned 32-bit integer from a buffer (2 consecutive registers).
+
+**Parameters:**
+
+- `buffer: Buffer` - Buffer containing register data
+- `offset: number` - Byte offset to start reading from
+- `scale: number` - Scale factor (e.g., 100 for ×100 values)
+
+**Returns:** `number` - Scaled floating-point value
+
+**Throws:** Error if scale is not a finite positive number
+
+**Example:**
+
+```typescript
+import { readScaledUInt32BE } from '@ya-modbus/driver-sdk'
+
+// Device stores total energy as 32-bit integer ×100 (1000000 = 10000.00 kWh)
+const buffer = await transport.readHoldingRegisters(0x0007, 2)
+const totalEnergy = readScaledUInt32BE(buffer, 0, 100)
+// totalEnergy = 10000.0
+```
+
+#### `writeScaledUInt16BE(value, scale)`
+
+Encode and scale a value to an unsigned 16-bit integer buffer.
+
+**Parameters:**
+
+- `value: number` - Value to encode
+- `scale: number` - Scale factor (e.g., 10 for ×10 values)
+
+**Returns:** `Buffer` - 2-byte buffer containing the scaled value
+
+**Throws:** Error if value is not finite, scale is invalid, or scaled value exceeds uint16 range
+
+**Example:**
+
+```typescript
+import { writeScaledUInt16BE } from '@ya-modbus/driver-sdk'
+
+// Write humidity correction of 5.5% (stored as 55)
+const buffer = writeScaledUInt16BE(5.5, 10)
+await transport.writeMultipleRegisters(0x104, buffer)
+```
+
+#### `writeScaledInt16BE(value, scale)`
+
+Encode and scale a value to a signed 16-bit integer buffer.
+
+**Parameters:**
+
+- `value: number` - Value to encode
+- `scale: number` - Scale factor (e.g., 10 for ×10 values)
+
+**Returns:** `Buffer` - 2-byte buffer containing the scaled value
+
+**Throws:** Error if value is not finite, scale is invalid, or scaled value exceeds int16 range
+
+**Example:**
+
+```typescript
+import { writeScaledInt16BE } from '@ya-modbus/driver-sdk'
+
+// Write temperature correction of -3.5°C (stored as -35)
+const buffer = writeScaledInt16BE(-3.5, 10)
+await transport.writeMultipleRegisters(0x103, buffer)
+```
+
+### Validation Functions
+
+Type-safe validators for configuration values with proper TypeScript type narrowing.
+
+#### `createEnumValidator(values)`
+
+Create a type-safe enum validator function.
+
+**Parameters:**
+
+- `values: readonly T[]` - Readonly array of valid enum values
+
+**Returns:** `(value: unknown) => value is T[number]` - Type guard function
+
+**Example:**
+
+```typescript
+import { createEnumValidator, formatEnumError } from '@ya-modbus/driver-sdk'
+
+const VALID_BAUD_RATES = [9600, 14400, 19200] as const
+type ValidBaudRate = (typeof VALID_BAUD_RATES)[number]
+
+const isValidBaudRate = createEnumValidator(VALID_BAUD_RATES)
+
+if (!isValidBaudRate(value)) {
+  throw new Error(formatEnumError('baud rate', VALID_BAUD_RATES))
+}
+// value is now typed as ValidBaudRate (9600 | 14400 | 19200)
+```
+
+#### `createRangeValidator(min, max)`
+
+Create a numeric range validator function.
+
+**Parameters:**
+
+- `min: number` - Minimum valid value (inclusive)
+- `max: number` - Maximum valid value (inclusive)
+
+**Returns:** `(value: unknown) => value is number` - Validator function
+
+**Example:**
+
+```typescript
+import { createRangeValidator, formatRangeError } from '@ya-modbus/driver-sdk'
+
+const isValidAddress = createRangeValidator(1, 247)
+
+if (!isValidAddress(value)) {
+  throw new Error(formatRangeError('device address', 1, 247))
+}
+// value is a finite number between 1 and 247
+```
+
+#### `isValidInteger(value)`
+
+Validate that a value is a finite integer.
+
+**Parameters:**
+
+- `value: unknown` - Value to validate
+
+**Returns:** `value is number` - True if value is a finite integer
+
+**Example:**
+
+```typescript
+import { isValidInteger } from '@ya-modbus/driver-sdk'
+
+if (!isValidInteger(value)) {
+  throw new Error('Device address must be an integer')
+}
+```
+
+### Error Formatting
+
+Utilities for consistent validation error messages.
+
+#### `formatRangeError(name, min, max)`
+
+Format a range validation error message.
+
+**Parameters:**
+
+- `name: string` - Field name for the error message
+- `min: number` - Minimum valid value
+- `max: number` - Maximum valid value
+
+**Returns:** `string` - Formatted error message
+
+**Example:**
+
+```typescript
+import { formatRangeError } from '@ya-modbus/driver-sdk'
+
+formatRangeError('device address', 1, 247)
+// => 'Invalid device address: must be between 1 and 247'
+```
+
+#### `formatEnumError(name, values)`
+
+Format an enum validation error message.
+
+**Parameters:**
+
+- `name: string` - Field name for the error message
+- `values: readonly unknown[]` - Valid enum values
+
+**Returns:** `string` - Formatted error message
+
+**Example:**
+
+```typescript
+import { formatEnumError } from '@ya-modbus/driver-sdk'
+
+formatEnumError('baud rate', [9600, 14400, 19200])
+// => 'Invalid baud rate: must be one of 9600, 14400, 19200'
+```
+
+## Edge Case Handling
+
+All codec functions include comprehensive edge case validation:
+
+- **Division by zero**: Scale must be greater than 0
+- **Non-finite values**: NaN and Infinity are rejected
+- **Integer overflow**: Values exceeding uint16/int16 ranges throw errors
+- **Negative scale**: Scale must be positive
+
+**Example:**
+
+```typescript
+// Throws: Invalid scale: must be greater than 0
+readScaledUInt16BE(buffer, 0, 0)
+
+// Throws: Invalid value: must be a finite number
+writeScaledUInt16BE(NaN, 10)
+
+// Throws: Invalid scaled value: 65536 is outside uint16 range (0 to 65535)
+writeScaledUInt16BE(6553.6, 10)
+```
+
+## TypeScript Support
+
+All functions include full TypeScript type definitions with type narrowing support:
+
+```typescript
+const isValidBaudRate = createEnumValidator([9600, 14400, 19200] as const)
+
+let value: unknown = getUserInput()
+
+if (isValidBaudRate(value)) {
+  // TypeScript knows: value is 9600 | 14400 | 19200
+  const encoded = encodeBaudRate(value)
+}
+```
+
+## Usage in Drivers
+
+Typical driver implementation pattern:
+
+```typescript
+import type { DeviceDriver } from '@ya-modbus/driver-types'
+import {
+  readScaledUInt16BE,
+  readScaledInt16BE,
+  writeScaledUInt16BE,
+  createEnumValidator,
+  formatEnumError,
+} from '@ya-modbus/driver-sdk'
+
+const VALID_BAUD_RATES = [9600, 14400, 19200] as const
+const isValidBaudRate = createEnumValidator(VALID_BAUD_RATES)
+
+export const createDriver = async (config): Promise<DeviceDriver> => {
+  // Validate configuration
+  if (!isValidBaudRate(config.baudRate)) {
+    throw new Error(formatEnumError('baud rate', VALID_BAUD_RATES))
+  }
+
+  return {
+    name: 'my-device',
+
+    async readDataPoint(id: string) {
+      if (id === 'temperature') {
+        const buffer = await transport.readInputRegisters(0, 1)
+        return readScaledUInt16BE(buffer, 0, 10)
+      }
+      if (id === 'correction') {
+        const buffer = await transport.readHoldingRegisters(0x103, 1)
+        return readScaledInt16BE(buffer, 0, 10)
+      }
+    },
+
+    async writeDataPoint(id: string, value: number) {
+      if (id === 'correction') {
+        const buffer = writeScaledInt16BE(value, 10)
+        await transport.writeMultipleRegisters(0x103, buffer)
+      }
+    },
+  }
+}
+```
+
+## See Also
+
+- [Driver Development Guide](../../docs/DRIVER-DEVELOPMENT.md)
+- [Driver Types](../driver-types/README.md)
+- [Example Drivers](../driver-xymd1/)
+
+## License
+
+GPL-3.0-or-later

package/dist/codec.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Buffer encoding/decoding utilities for Modbus register values
+ *
+ * These utilities handle common patterns in Modbus drivers like reading
+ * scaled integers (×10, ×100, ×1000) from register buffers.
+ */
+/**
+ * Read and scale an unsigned 16-bit integer from a buffer
+ *
+ * @param buffer - Buffer containing the register data
+ * @param offset - Byte offset to start reading from
+ * @param scale - Scale factor (e.g., 10 for ×10 values)
+ * @returns Scaled floating-point value
+ * @throws Error if scale is not a finite positive number
+ *
+ * @example
+ * ```typescript
+ * // Device stores temperature as integer ×10 (235 = 23.5°C)
+ * const buffer = await transport.readInputRegisters(0, 1)
+ * const temperature = readScaledUInt16BE(buffer, 0, 10)
+ * ```
+ */
+export declare function readScaledUInt16BE(buffer: Buffer, offset: number, scale: number): number;
+/**
+ * Read and scale a signed 16-bit integer from a buffer
+ *
+ * @param buffer - Buffer containing the register data
+ * @param offset - Byte offset to start reading from
+ * @param scale - Scale factor (e.g., 10 for ×10 values)
+ * @returns Scaled floating-point value
+ * @throws Error if scale is not a finite positive number
+ *
+ * @example
+ * ```typescript
+ * // Device stores correction offset as signed integer ×10 (-50 = -5.0°C)
+ * const buffer = await transport.readHoldingRegisters(0x103, 1)
+ * const correction = readScaledInt16BE(buffer, 0, 10)
+ * ```
+ */
+export declare function readScaledInt16BE(buffer: Buffer, offset: number, scale: number): number;
+/**
+ * Read and scale an unsigned 32-bit integer from a buffer
+ *
+ * @param buffer - Buffer containing the register data (2 consecutive registers)
+ * @param offset - Byte offset to start reading from
+ * @param scale - Scale factor (e.g., 100 for ×100 values)
+ * @returns Scaled floating-point value
+ * @throws Error if scale is not a finite positive number
+ *
+ * @example
+ * ```typescript
+ * // Device stores total energy as 32-bit integer ×100 (1000000 = 10000.00 kWh)
+ * const buffer = await transport.readHoldingRegisters(0x0007, 2)
+ * const totalEnergy = readScaledUInt32BE(buffer, 0, 100)
+ * ```
+ */
+export declare function readScaledUInt32BE(buffer: Buffer, offset: number, scale: number): number;
+/**
+ * Encode and scale a value to an unsigned 16-bit integer buffer
+ *
+ * @param value - Value to encode
+ * @param scale - Scale factor (e.g., 10 for ×10 values)
+ * @returns 2-byte buffer containing the scaled value
+ * @throws Error if value is not finite, scale is invalid, or scaled value exceeds uint16 range
+ *
+ * @example
+ * ```typescript
+ * // Write humidity correction of 5.5% (stored as 55)
+ * const buffer = writeScaledUInt16BE(5.5, 10)
+ * await transport.writeMultipleRegisters(0x104, buffer)
+ * ```
+ */
+export declare function writeScaledUInt16BE(value: number, scale: number): Buffer;
+/**
+ * Encode and scale a value to a signed 16-bit integer buffer
+ *
+ * @param value - Value to encode
+ * @param scale - Scale factor (e.g., 10 for ×10 values)
+ * @returns 2-byte buffer containing the scaled value
+ * @throws Error if value is not finite, scale is invalid, or scaled value exceeds int16 range
+ *
+ * @example
+ * ```typescript
+ * // Write temperature correction of -3.5°C (stored as -35)
+ * const buffer = writeScaledInt16BE(-3.5, 10)
+ * await transport.writeMultipleRegisters(0x103, buffer)
+ * ```
+ */
+export declare function writeScaledInt16BE(value: number, scale: number): Buffer;
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKvF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAWvE"}

package/dist/codec.js

@@ -0,0 +1,177 @@
+/**
+ * Buffer encoding/decoding utilities for Modbus register values
+ *
+ * These utilities handle common patterns in Modbus drivers like reading
+ * scaled integers (×10, ×100, ×1000) from register buffers.
+ */
+/**
+ * Validate that a scale parameter is valid
+ *
+ * @param scale - Scale factor to validate
+ * @throws Error if scale is not finite or is not positive
+ */
+function validateScale(scale) {
+    if (!Number.isFinite(scale)) {
+        throw new Error('Invalid scale: must be a finite number');
+    }
+    if (scale <= 0) {
+        throw new Error('Invalid scale: must be greater than 0');
+    }
+}
+/**
+ * Validate that a value for writing is valid
+ *
+ * @param value - Value to validate
+ * @throws Error if value is not finite
+ */
+function validateWriteValue(value) {
+    if (!Number.isFinite(value)) {
+        throw new Error('Invalid value: must be a finite number');
+    }
+}
+/**
+ * Validate that a scaled value fits within the target integer range
+ *
+ * @param scaledValue - Scaled value to validate
+ * @param min - Minimum allowed value (inclusive)
+ * @param max - Maximum allowed value (inclusive)
+ * @param typeName - Name of the target type for error messages
+ * @throws Error if scaled value is outside the valid range
+ */
+function validateRange(scaledValue, min, max, typeName) {
+    if (scaledValue < min || scaledValue > max) {
+        throw new Error(`Invalid scaled value: ${scaledValue} is outside ${typeName} range (${min} to ${max})`);
+    }
+}
+/**
+ * Validate that buffer has sufficient bytes for reading at the given offset
+ *
+ * @param buffer - Buffer to validate
+ * @param offset - Byte offset to start reading from
+ * @param bytesNeeded - Number of bytes required
+ * @param typeName - Name of the type being read for error messages
+ * @throws Error if buffer doesn't have enough bytes
+ */
+function validateBufferBounds(buffer, offset, bytesNeeded, typeName) {
+    const available = buffer.length - offset;
+    if (available < bytesNeeded) {
+        throw new Error(`Insufficient buffer size for ${typeName}: need ${bytesNeeded} bytes at offset ${offset}, ` +
+            `but only ${available} bytes available (buffer length: ${buffer.length})`);
+    }
+}
+/**
+ * Read and scale an unsigned 16-bit integer from a buffer
+ *
+ * @param buffer - Buffer containing the register data
+ * @param offset - Byte offset to start reading from
+ * @param scale - Scale factor (e.g., 10 for ×10 values)
+ * @returns Scaled floating-point value
+ * @throws Error if scale is not a finite positive number
+ *
+ * @example
+ * ```typescript
+ * // Device stores temperature as integer ×10 (235 = 23.5°C)
+ * const buffer = await transport.readInputRegisters(0, 1)
+ * const temperature = readScaledUInt16BE(buffer, 0, 10)
+ * ```
+ */
+export function readScaledUInt16BE(buffer, offset, scale) {
+    validateScale(scale);
+    validateBufferBounds(buffer, offset, 2, 'uint16');
+    const rawValue = buffer.readUInt16BE(offset);
+    return rawValue / scale;
+}
+/**
+ * Read and scale a signed 16-bit integer from a buffer
+ *
+ * @param buffer - Buffer containing the register data
+ * @param offset - Byte offset to start reading from
+ * @param scale - Scale factor (e.g., 10 for ×10 values)
+ * @returns Scaled floating-point value
+ * @throws Error if scale is not a finite positive number
+ *
+ * @example
+ * ```typescript
+ * // Device stores correction offset as signed integer ×10 (-50 = -5.0°C)
+ * const buffer = await transport.readHoldingRegisters(0x103, 1)
+ * const correction = readScaledInt16BE(buffer, 0, 10)
+ * ```
+ */
+export function readScaledInt16BE(buffer, offset, scale) {
+    validateScale(scale);
+    validateBufferBounds(buffer, offset, 2, 'int16');
+    const rawValue = buffer.readInt16BE(offset);
+    return rawValue / scale;
+}
+/**
+ * Read and scale an unsigned 32-bit integer from a buffer
+ *
+ * @param buffer - Buffer containing the register data (2 consecutive registers)
+ * @param offset - Byte offset to start reading from
+ * @param scale - Scale factor (e.g., 100 for ×100 values)
+ * @returns Scaled floating-point value
+ * @throws Error if scale is not a finite positive number
+ *
+ * @example
+ * ```typescript
+ * // Device stores total energy as 32-bit integer ×100 (1000000 = 10000.00 kWh)
+ * const buffer = await transport.readHoldingRegisters(0x0007, 2)
+ * const totalEnergy = readScaledUInt32BE(buffer, 0, 100)
+ * ```
+ */
+export function readScaledUInt32BE(buffer, offset, scale) {
+    validateScale(scale);
+    validateBufferBounds(buffer, offset, 4, 'uint32');
+    const rawValue = buffer.readUInt32BE(offset);
+    return rawValue / scale;
+}
+/**
+ * Encode and scale a value to an unsigned 16-bit integer buffer
+ *
+ * @param value - Value to encode
+ * @param scale - Scale factor (e.g., 10 for ×10 values)
+ * @returns 2-byte buffer containing the scaled value
+ * @throws Error if value is not finite, scale is invalid, or scaled value exceeds uint16 range
+ *
+ * @example
+ * ```typescript
+ * // Write humidity correction of 5.5% (stored as 55)
+ * const buffer = writeScaledUInt16BE(5.5, 10)
+ * await transport.writeMultipleRegisters(0x104, buffer)
+ * ```
+ */
+export function writeScaledUInt16BE(value, scale) {
+    validateWriteValue(value);
+    validateScale(scale);
+    const scaledValue = Math.trunc(value * scale);
+    validateRange(scaledValue, 0, 0xffff, 'uint16');
+    const buffer = Buffer.allocUnsafe(2);
+    buffer.writeUInt16BE(scaledValue, 0);
+    return buffer;
+}
+/**
+ * Encode and scale a value to a signed 16-bit integer buffer
+ *
+ * @param value - Value to encode
+ * @param scale - Scale factor (e.g., 10 for ×10 values)
+ * @returns 2-byte buffer containing the scaled value
+ * @throws Error if value is not finite, scale is invalid, or scaled value exceeds int16 range
+ *
+ * @example
+ * ```typescript
+ * // Write temperature correction of -3.5°C (stored as -35)
+ * const buffer = writeScaledInt16BE(-3.5, 10)
+ * await transport.writeMultipleRegisters(0x103, buffer)
+ * ```
+ */
+export function writeScaledInt16BE(value, scale) {
+    validateWriteValue(value);
+    validateScale(scale);
+    // Use Math.trunc for predictable rounding toward zero (avoids floating-point precision issues)
+    const scaledValue = Math.trunc(value * scale);
+    validateRange(scaledValue, -0x8000, 0x7fff, 'int16');
+    const buffer = Buffer.allocUnsafe(2);
+    buffer.writeInt16BE(scaledValue, 0);
+    return buffer;
+}
+//# sourceMappingURL=codec.js.map

package/dist/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Error formatting utilities for consistent validation error messages
+ */
+/**
+ * Format a range validation error message
+ *
+ * @param name - Field name for the error message
+ * @param min - Minimum valid value
+ * @param max - Maximum valid value
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * formatRangeError('device address', 1, 247)
+ * // => 'Invalid device address: must be between 1 and 247'
+ * ```
+ */
+export declare function formatRangeError(name: string, min: number, max: number): string;
+/**
+ * Format a range validation error message with the actual value
+ *
+ * @param name - Field name for the error message
+ * @param value - Actual value that was rejected
+ * @param min - Minimum valid value
+ * @param max - Maximum valid value
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * formatRangeError('device address', 256, 1, 247)
+ * // => 'Invalid device address: received 256, must be between 1 and 247'
+ * ```
+ */
+export declare function formatRangeError(name: string, value: unknown, min: number, max: number): string;
+/**
+ * Format an enum validation error message
+ *
+ * @param name - Field name for the error message
+ * @param values - Valid enum values
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * formatEnumError('baud rate', [9600, 14400, 19200])
+ * // => 'Invalid baud rate: must be one of 9600, 14400, 19200'
+ * ```
+ */
+export declare function formatEnumError(name: string, values: readonly unknown[]): string;
+/**
+ * Format an enum validation error message with the actual value
+ *
+ * @param name - Field name for the error message
+ * @param value - Actual value that was rejected
+ * @param values - Valid enum values
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * formatEnumError('baud rate', 115200, [9600, 14400, 19200])
+ * // => 'Invalid baud rate: received 115200, must be one of 9600, 14400, 19200'
+ * ```
+ */
+export declare function formatEnumError(name: string, value: unknown, values: readonly unknown[]): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;AAChF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;AAahG;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAAA;AACjF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAAA"}