@ya-modbus/driver-sdk 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.7.0](https://github.com/groupsky/ya-modbus/compare/@ya-modbus/driver-sdk@0.6.0...@ya-modbus/driver-sdk@0.7.0) (2026-01-11)
+
+### Features
+
+- **build:** add dual CommonJS/ESM package support ([#187](https://github.com/groupsky/ya-modbus/issues/187)) ([3d78130](https://github.com/groupsky/ya-modbus/commit/3d781304d42edba335cdc320ba25275f3b4ea6c9))
+
 # 0.6.0 (2026-01-04)
 
 ### Bug Fixes

package/dist/cjs/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/cjs/codec.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readScaledUInt16BE = readScaledUInt16BE;
+exports.readScaledInt16BE = readScaledInt16BE;
+exports.readScaledUInt32BE = readScaledUInt32BE;
+exports.writeScaledUInt16BE = writeScaledUInt16BE;
+exports.writeScaledInt16BE = writeScaledInt16BE;
+/**
+ * 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)
+ * ```
+ */
+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)
+ * ```
+ */
+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)
+ * ```
+ */
+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)
+ * ```
+ */
+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)
+ * ```
+ */
+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/cjs/codec.js.map

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

package/dist/cjs/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"}

package/dist/cjs/errors.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Error formatting utilities for consistent validation error messages
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatRangeError = formatRangeError;
+exports.formatEnumError = formatEnumError;
+function formatRangeError(name, ...args) {
+    if (args.length === 2) {
+        const [min, max] = args;
+        return `Invalid ${name}: must be between ${min} and ${max}`;
+    }
+    const [value, min, max] = args;
+    return `Invalid ${name}: received ${String(value)}, must be between ${min} and ${max}`;
+}
+function formatEnumError(name, ...args) {
+    if (args.length === 1) {
+        const [values] = args;
+        return `Invalid ${name}: must be one of ${values.join(', ')}`;
+    }
+    const [value, values] = args;
+    return `Invalid ${name}: received ${String(value)}, must be one of ${values.join(', ')}`;
+}
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAiCH,4CAUC;AA+BD,0CAUC;AAnDD,SAAgB,gBAAgB,CAC9B,IAAY,EACZ,GAAG,IAAkD;IAErD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;QACvB,OAAO,WAAW,IAAI,qBAAqB,GAAG,QAAQ,GAAG,EAAE,CAAA;IAC7D,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;IAC9B,OAAO,WAAW,IAAI,cAAc,MAAM,CAAC,KAAK,CAAC,qBAAqB,GAAG,QAAQ,GAAG,EAAE,CAAA;AACxF,CAAC;AA+BD,SAAgB,eAAe,CAC7B,IAAY,EACZ,GAAG,IAA0D;IAE7D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;QACrB,OAAO,WAAW,IAAI,oBAAoB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;IAC/D,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC5B,OAAO,WAAW,IAAI,cAAc,MAAM,CAAC,KAAK,CAAC,oBAAoB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;AAC1F,CAAC"}

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA"}

package/dist/cjs/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Runtime SDK for ya-modbus device drivers
+ *
+ * Provides utilities for common driver development tasks:
+ * - Buffer encoding/decoding for scaled register values
+ * - Configuration validation with type narrowing
+ * - Consistent error message formatting
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   readScaledUInt16BE,
+ *   createEnumValidator,
+ *   formatEnumError,
+ * } from '@ya-modbus/driver-sdk'
+ *
+ * // Read scaled temperature value
+ * const buffer = await transport.readInputRegisters(1, 1)
+ * const temperature = readScaledUInt16BE(buffer, 0, 10)
+ *
+ * // Validate baud rate
+ * const isValidBaudRate = createEnumValidator([9600, 14400, 19200] as const)
+ * if (!isValidBaudRate(value)) {
+ *   throw new Error(formatEnumError('baud rate', [9600, 14400, 19200]))
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// Re-export all utilities
+tslib_1.__exportStar(require("./codec.js"), exports);
+tslib_1.__exportStar(require("./validators.js"), exports);
+tslib_1.__exportStar(require("./errors.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAEH,0BAA0B;AAC1B,qDAA0B;AAC1B,0DAA+B;AAC/B,sDAA2B"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/validators.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EAC9D,MAAM,EAAE,CAAC,GACR,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC,CAIxC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,MAAM,CAIrC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE9D"}

package/dist/cjs/validators.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Validation utilities for driver configuration values
+ *
+ * These utilities provide type-safe validation with proper TypeScript
+ * type narrowing for common configuration values like baud rates,
+ * device addresses, and numeric ranges.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEnumValidator = createEnumValidator;
+exports.createRangeValidator = createRangeValidator;
+exports.isValidInteger = isValidInteger;
+/**
+ * Create a type-safe enum validator function
+ *
+ * Returns a type guard function that validates if a value is one of
+ * the allowed enum values. The returned function properly narrows
+ * TypeScript types.
+ *
+ * @param values - Readonly array of valid enum values
+ * @returns Type guard function that validates enum membership
+ *
+ * @example
+ * ```typescript
+ * import { createEnumValidator } 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)) {
+ *   // value is now typed as ValidBaudRate
+ *   const encoded = encodeBaudRate(value)
+ * }
+ * ```
+ */
+function createEnumValidator(values) {
+    return (value) => {
+        return values.includes(value);
+    };
+}
+/**
+ * Create a numeric range validator function
+ *
+ * Returns a function that validates if a value is a finite number
+ * within the specified range (inclusive).
+ *
+ * @param min - Minimum valid value (inclusive)
+ * @param max - Maximum valid value (inclusive)
+ * @returns Validator function that checks range membership
+ *
+ * @example
+ * ```typescript
+ * import { createRangeValidator } from '@ya-modbus/driver-sdk'
+ *
+ * const isValidAddress = createRangeValidator(1, 247)
+ *
+ * if (isValidAddress(value)) {
+ *   // value is a finite number between 1 and 247
+ *   await writeAddress(value)
+ * }
+ * ```
+ */
+function createRangeValidator(min, max) {
+    return (value) => {
+        return typeof value === 'number' && Number.isFinite(value) && value >= min && value <= max;
+    };
+}
+/**
+ * Validate that a value is a finite integer
+ *
+ * Checks if a value is a number, finite, and has no fractional part.
+ *
+ * @param value - Value to validate
+ * @returns 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')
+ * }
+ * ```
+ */
+function isValidInteger(value) {
+    return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value);
+}
+//# sourceMappingURL=validators.js.map

package/dist/cjs/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/validators.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AA2BH,kDAMC;AAwBD,oDAOC;AAmBD,wCAEC;AAnFD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,mBAAmB,CACjC,MAAS;IAET,OAAO,CAAC,KAAc,EAAsB,EAAE;QAC5C,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAkB,CAAC,CAAA;IAC5C,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,oBAAoB,CAClC,GAAW,EACX,GAAW;IAEX,OAAO,CAAC,KAAc,EAAmB,EAAE;QACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG,CAAA;IAC5F,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AACvF,CAAC"}

package/dist/esm/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/esm/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/esm/codec.js.map

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

package/dist/esm/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/esm/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"}

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiCH,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,GAAG,IAAkD;IAErD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;QACvB,OAAO,WAAW,IAAI,qBAAqB,GAAG,QAAQ,GAAG,EAAE,CAAA;IAC7D,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;IAC9B,OAAO,WAAW,IAAI,cAAc,MAAM,CAAC,KAAK,CAAC,qBAAqB,GAAG,QAAQ,GAAG,EAAE,CAAA;AACxF,CAAC;AA+BD,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,GAAG,IAA0D;IAE7D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;QACrB,OAAO,WAAW,IAAI,oBAAoB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;IAC/D,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC5B,OAAO,WAAW,IAAI,cAAc,MAAM,CAAC,KAAK,CAAC,oBAAoB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;AAC1F,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Runtime SDK for ya-modbus device drivers
+ *
+ * Provides utilities for common driver development tasks:
+ * - Buffer encoding/decoding for scaled register values
+ * - Configuration validation with type narrowing
+ * - Consistent error message formatting
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   readScaledUInt16BE,
+ *   createEnumValidator,
+ *   formatEnumError,
+ * } from '@ya-modbus/driver-sdk'
+ *
+ * // Read scaled temperature value
+ * const buffer = await transport.readInputRegisters(1, 1)
+ * const temperature = readScaledUInt16BE(buffer, 0, 10)
+ *
+ * // Validate baud rate
+ * const isValidBaudRate = createEnumValidator([9600, 14400, 19200] as const)
+ * if (!isValidBaudRate(value)) {
+ *   throw new Error(formatEnumError('baud rate', [9600, 14400, 19200]))
+ * }
+ * ```
+ */
+export * from './codec.js';
+export * from './validators.js';
+export * from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA"}

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,0BAA0B;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA"}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}