@ya-modbus/driver-loader 0.8.1 → 0.9.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.9.0](https://github.com/groupsky/ya-modbus/compare/@ya-modbus/driver-loader@0.8.1...@ya-modbus/driver-loader@0.9.0) (2026-10-12)
+
+### Features
+
+- **driver-loader:** allow scoped third-party driver packages ([#573](https://github.com/groupsky/ya-modbus/issues/573)) ([63b2b83](https://github.com/groupsky/ya-modbus/commit/63b2b833dbb0b5198e8df7135f419793e32d95c3)), closes [#565](https://github.com/groupsky/ya-modbus/issues/565)
+
 ## [0.8.1](https://github.com/groupsky/ya-modbus/compare/@ya-modbus/driver-loader@0.8.0...@ya-modbus/driver-loader@0.8.1) (2026-10-12)
 
 ### Bug Fixes

package/README.md

@@ -192,6 +192,29 @@ import { getCallerPackageInfo } from '@ya-modbus/driver-loader'
 program.version(getCallerPackageInfo().version)
 ```
 
+### `isValidDriverPackageName(name: unknown): boolean`
+
+Checks a driver package name against the shared naming rule for applications that read the driver name from a configuration, such as the MQTT bridge. Allowed forms:
+
+- `@ya-modbus/driver-<name>`
+- `ya-modbus-driver-<name>`
+- `@<scope>/ya-modbus-driver-<name>`
+
+`<name>` and `<scope>` use only lowercase letters, numbers and hyphens. Paths (`../x`, `/opt/x`), sub paths, backslashes and any other package name are rejected. `loadDriver` does not check this rule. If your tool reads the driver name from a config file, call `assertValidDriverPackageName` before `loadDriver`.
+
+### `assertValidDriverPackageName(name: string): void`
+
+Same check as `isValidDriverPackageName`. Throws a `ValidationError` (field `driverPackage`) that shows the rejected name and lists the allowed forms.
+
+`DRIVER_PACKAGE_NAME_RULE` is the text of the rule ("must be ..."), for applications that build their own error message.
+
+```typescript
+import { assertValidDriverPackageName, loadDriver } from '@ya-modbus/driver-loader'
+
+assertValidDriverPackageName(config.driver)
+await loadDriver({ driverPackage: config.driver })
+```
+
 ## Testing Utilities
 
 The package provides testing utilities for applications using driver-loader.
@@ -255,7 +278,7 @@ If you encounter `Driver package not found` errors:
 
 3. **Check the package name:**
    - Ensure the package name in your code matches the actual npm package name
-   - Driver packages typically follow the naming convention: `ya-modbus-driver-<device>`
+   - Driver packages follow the naming rule described under `isValidDriverPackageName` (for example `ya-modbus-driver-<device>` or `@<scope>/ya-modbus-driver-<device>`)
 
 ### Module Resolution Issues
 

package/dist/cjs/src/driver-package-name.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Describes the allowed driver package names, for error messages.
+ * Written to follow "name must be ...", so callers can put their own words in front.
+ */
+export declare const DRIVER_PACKAGE_NAME_RULE: string;
+/**
+ * Check a driver package name against the shared naming rule for drivers that are loaded
+ * from a configured name, such as in the MQTT bridge.
+ *
+ * Allowed forms: `@ya-modbus/driver-<name>`, `ya-modbus-driver-<name>` and
+ * `@<scope>/ya-modbus-driver-<name>`.
+ *
+ * @param name - Value to check
+ * @returns true if the value is an allowed driver package name
+ */
+export declare function isValidDriverPackageName(name: unknown): boolean;
+/**
+ * Throw if a driver package name does not follow the naming rule.
+ *
+ * @param name - Driver package name to check
+ * @throws ValidationError (field `driverPackage`) listing the allowed forms
+ */
+export declare function assertValidDriverPackageName(name: string): void;
+//# sourceMappingURL=driver-package-name.d.ts.map

package/dist/cjs/src/driver-package-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-package-name.d.ts","sourceRoot":"","sources":["../../../src/driver-package-name.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAEuC,CAAA;AAS5E;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAO/D"}

package/dist/cjs/src/driver-package-name.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DRIVER_PACKAGE_NAME_RULE = void 0;
+exports.isValidDriverPackageName = isValidDriverPackageName;
+exports.assertValidDriverPackageName = assertValidDriverPackageName;
+const errors_js_1 = require("./errors.js");
+/**
+ * Describes the allowed driver package names, for error messages.
+ * Written to follow "name must be ...", so callers can put their own words in front.
+ */
+exports.DRIVER_PACKAGE_NAME_RULE = 'must be @ya-modbus/driver-<name>, ya-modbus-driver-<name> or @<scope>/ya-modbus-driver-<name>, ' +
+    'where <name> and <scope> use only lowercase letters, numbers and hyphens';
+/**
+ * The three allowed forms. Only lowercase letters, numbers and hyphens can follow the prefix,
+ * so a name can never contain a path separator, a dot, a backslash or a whitespace.
+ */
+const DRIVER_PACKAGE_NAME_PATTERN = /^(?:@ya-modbus\/driver-|(?:@[a-z0-9][a-z0-9-]*\/)?ya-modbus-driver-)[a-z0-9-]+$/;
+/**
+ * Check a driver package name against the shared naming rule for drivers that are loaded
+ * from a configured name, such as in the MQTT bridge.
+ *
+ * Allowed forms: `@ya-modbus/driver-<name>`, `ya-modbus-driver-<name>` and
+ * `@<scope>/ya-modbus-driver-<name>`.
+ *
+ * @param name - Value to check
+ * @returns true if the value is an allowed driver package name
+ */
+function isValidDriverPackageName(name) {
+    return typeof name === 'string' && DRIVER_PACKAGE_NAME_PATTERN.test(name);
+}
+/**
+ * Throw if a driver package name does not follow the naming rule.
+ *
+ * @param name - Driver package name to check
+ * @throws ValidationError (field `driverPackage`) listing the allowed forms
+ */
+function assertValidDriverPackageName(name) {
+    if (!isValidDriverPackageName(name)) {
+        throw new errors_js_1.ValidationError(`Invalid driver package name ${JSON.stringify(name)}: ${exports.DRIVER_PACKAGE_NAME_RULE}`, 'driverPackage');
+    }
+}
+//# sourceMappingURL=driver-package-name.js.map

package/dist/cjs/src/driver-package-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-package-name.js","sourceRoot":"","sources":["../../../src/driver-package-name.ts"],"names":[],"mappings":";;;AA2BA,4DAEC;AAQD,oEAOC;AA5CD,2CAA6C;AAE7C;;;GAGG;AACU,QAAA,wBAAwB,GACnC,iGAAiG;IACjG,0EAA0E,CAAA;AAE5E;;;GAGG;AACH,MAAM,2BAA2B,GAC/B,iFAAiF,CAAA;AAEnF;;;;;;;;;GASG;AACH,SAAgB,wBAAwB,CAAC,IAAa;IACpD,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC3E,CAAC;AAED;;;;;GAKG;AACH,SAAgB,4BAA4B,CAAC,IAAY;IACvD,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,2BAAe,CACvB,+BAA+B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,gCAAwB,EAAE,EAClF,eAAe,CAChB,CAAA;IACH,CAAC;AACH,CAAC"}

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

@@ -1,6 +1,7 @@
 export { loadDriver, clearDriverCache, getDriverCacheStats } from './loader.js';
 export type { LoadedDriver, LoadDriverOptions, SystemDependencies, DriverCacheStats, Logger, } from './loader.js';
 export { validateDefaultConfig, validateSupportedConfig, validateDevices, crossValidateConfigs, } from './config-validator.js';
+export { DRIVER_PACKAGE_NAME_RULE, assertValidDriverPackageName, isValidDriverPackageName, } from './driver-package-name.js';
 export { ValidationError, DriverNotFoundError, PackageJsonError } from './errors.js';
 export { getCallerPackageInfo } from './package-info.js';
 export type { PackageInfo } from './package-info.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC/E,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,MAAM,GACP,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,GACrB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC/E,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,MAAM,GACP,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,GACrB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/cjs/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCallerPackageInfo = exports.PackageJsonError = exports.DriverNotFoundError = exports.ValidationError = exports.crossValidateConfigs = exports.validateDevices = exports.validateSupportedConfig = exports.validateDefaultConfig = exports.getDriverCacheStats = exports.clearDriverCache = exports.loadDriver = void 0;
+exports.getCallerPackageInfo = exports.PackageJsonError = exports.DriverNotFoundError = exports.ValidationError = exports.isValidDriverPackageName = exports.assertValidDriverPackageName = exports.DRIVER_PACKAGE_NAME_RULE = exports.crossValidateConfigs = exports.validateDevices = exports.validateSupportedConfig = exports.validateDefaultConfig = exports.getDriverCacheStats = exports.clearDriverCache = exports.loadDriver = void 0;
 var loader_js_1 = require("./loader.js");
 Object.defineProperty(exports, "loadDriver", { enumerable: true, get: function () { return loader_js_1.loadDriver; } });
 Object.defineProperty(exports, "clearDriverCache", { enumerable: true, get: function () { return loader_js_1.clearDriverCache; } });
@@ -10,6 +10,10 @@ Object.defineProperty(exports, "validateDefaultConfig", { enumerable: true, get:
 Object.defineProperty(exports, "validateSupportedConfig", { enumerable: true, get: function () { return config_validator_js_1.validateSupportedConfig; } });
 Object.defineProperty(exports, "validateDevices", { enumerable: true, get: function () { return config_validator_js_1.validateDevices; } });
 Object.defineProperty(exports, "crossValidateConfigs", { enumerable: true, get: function () { return config_validator_js_1.crossValidateConfigs; } });
+var driver_package_name_js_1 = require("./driver-package-name.js");
+Object.defineProperty(exports, "DRIVER_PACKAGE_NAME_RULE", { enumerable: true, get: function () { return driver_package_name_js_1.DRIVER_PACKAGE_NAME_RULE; } });
+Object.defineProperty(exports, "assertValidDriverPackageName", { enumerable: true, get: function () { return driver_package_name_js_1.assertValidDriverPackageName; } });
+Object.defineProperty(exports, "isValidDriverPackageName", { enumerable: true, get: function () { return driver_package_name_js_1.isValidDriverPackageName; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
 Object.defineProperty(exports, "DriverNotFoundError", { enumerable: true, get: function () { return errors_js_1.DriverNotFoundError; } });

package/dist/cjs/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAA+E;AAAtE,uGAAA,UAAU,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAAE,gHAAA,mBAAmB,OAAA;AAQ1D,6DAK8B;AAJ5B,4HAAA,qBAAqB,OAAA;AACrB,8HAAA,uBAAuB,OAAA;AACvB,sHAAA,eAAe,OAAA;AACf,2HAAA,oBAAoB,OAAA;AAEtB,yCAAoF;AAA3E,4GAAA,eAAe,OAAA;AAAE,gHAAA,mBAAmB,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAC/D,qDAAwD;AAA/C,uHAAA,oBAAoB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAA+E;AAAtE,uGAAA,UAAU,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAAE,gHAAA,mBAAmB,OAAA;AAQ1D,6DAK8B;AAJ5B,4HAAA,qBAAqB,OAAA;AACrB,8HAAA,uBAAuB,OAAA;AACvB,sHAAA,eAAe,OAAA;AACf,2HAAA,oBAAoB,OAAA;AAEtB,mEAIiC;AAH/B,kIAAA,wBAAwB,OAAA;AACxB,sIAAA,4BAA4B,OAAA;AAC5B,kIAAA,wBAAwB,OAAA;AAE1B,yCAAoF;AAA3E,4GAAA,eAAe,OAAA;AAAE,gHAAA,mBAAmB,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAC/D,qDAAwD;AAA/C,uHAAA,oBAAoB,OAAA"}

package/dist/cjs/src/loader.d.ts

@@ -59,7 +59,7 @@ export interface Logger {
 export interface LoadDriverOptions {
     /**
      * Explicit driver package name
-     * e.g., 'ya-modbus-driver-xymd1' or '@org/driver-pkg'
+     * e.g., 'ya-modbus-driver-xymd1' or '@org/ya-modbus-driver-xymd1'
      */
     driverPackage?: string;
     /**