@ya-modbus/driver-loader 0.8.0 → 0.9.0

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

@@ -0,0 +1,37 @@
+import { ValidationError } from './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.
+ */
+export const 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
+ */
+export 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
+ */
+export function assertValidDriverPackageName(name) {
+    if (!isValidDriverPackageName(name)) {
+        throw new ValidationError(`Invalid driver package name ${JSON.stringify(name)}: ${DRIVER_PACKAGE_NAME_RULE}`, 'driverPackage');
+    }
+}
+//# sourceMappingURL=driver-package-name.js.map

package/dist/esm/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":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,iGAAiG;IACjG,0EAA0E,CAAA;AAE5E;;;GAGG;AACH,MAAM,2BAA2B,GAC/B,iFAAiF,CAAA;AAEnF;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAa;IACpD,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC3E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAAY;IACvD,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,eAAe,CACvB,+BAA+B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,wBAAwB,EAAE,EAClF,eAAe,CAChB,CAAA;IACH,CAAC;AACH,CAAC"}

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

@@ -1,5 +1,8 @@
 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';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/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"}
+{"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/esm/src/index.js

@@ -1,4 +1,6 @@
 export { loadDriver, clearDriverCache, getDriverCacheStats } 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';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAQ/E,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAQ/E,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"}

package/dist/esm/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;
     /**

package/dist/esm/src/package-info.d.ts

@@ -0,0 +1,43 @@
+export interface PackageInfo {
+    version: string;
+    description: string;
+}
+type ReadTextFile = (path: string) => string;
+/**
+ * Read the version and description from the closest package.json above a file
+ *
+ * package.json files without a version are skipped. This passes over the
+ * `{"type": "module"}` and `{"type": "commonjs"}` markers in `dist/esm` and `dist/cjs`.
+ *
+ * @param file - Path or `file:` URL of a module inside the package
+ * @param readFile - Reads a file as text and throws if it does not exist (replaceable in tests)
+ * @throws Error if no package.json with a version is found
+ */
+export declare function readPackageInfo(file: string, readFile?: ReadTextFile): PackageInfo;
+/**
+ * Pick the calling module from the file names of a stack, innermost first
+ *
+ * The first frame is this module. The caller is the first frame from another file that is a
+ * real module path or `file:` URL, which skips frames such as `node:internal/timers`.
+ *
+ * @throws Error if the stack has no such frame
+ */
+export declare function findCallerFile(files: ReadonlyArray<string | undefined>): string;
+/**
+ * Get the version and description of the package that contains the calling module
+ *
+ * Lets a CLI report its own package.json values without hardcoding them. The caller's
+ * location comes from the call stack, so it works the same in ES module and CommonJS
+ * builds, where `import.meta.url` and `__dirname` are each available in only one.
+ *
+ * @example
+ * ```typescript
+ * const { version } = getCallerPackageInfo()
+ * program.version(version)
+ * ```
+ *
+ * @throws Error if the calling module cannot be determined or has no package.json with a version
+ */
+export declare function getCallerPackageInfo(): PackageInfo;
+export {};
+//# sourceMappingURL=package-info.d.ts.map

package/dist/esm/src/package-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-info.d.ts","sourceRoot":"","sources":["../../../src/package-info.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;CACpB;AAwBD,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;AAiB5C;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,YAA2B,GAAG,WAAW,CAehG;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAY/E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,IAAI,WAAW,CAIlD"}

package/dist/esm/src/package-info.js

@@ -0,0 +1,96 @@
+import { readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const MIN_STACK_TRACE_LIMIT = 10;
+/**
+ * Call sites of the current stack, innermost first.
+ *
+ * V8 formats `stack` lazily, so it must be read while the formatter is replaced.
+ */
+function getCallSites() {
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- only restored, never called
+    const originalPrepare = Error.prepareStackTrace;
+    const originalLimit = Error.stackTraceLimit;
+    try {
+        Error.prepareStackTrace = (_error, callSites) => callSites;
+        // An application can lower the limit so far that the caller is not on the stack
+        Error.stackTraceLimit = Math.max(originalLimit, MIN_STACK_TRACE_LIMIT);
+        return new Error().stack;
+    }
+    finally {
+        Error.prepareStackTrace = originalPrepare;
+        Error.stackTraceLimit = originalLimit;
+    }
+}
+const readUtf8File = (path) => readFileSync(path, 'utf-8');
+function readPackageJson(path, readFile) {
+    let content;
+    try {
+        content = readFile(path);
+    }
+    catch {
+        return undefined;
+    }
+    return JSON.parse(content);
+}
+/**
+ * Read the version and description from the closest package.json above a file
+ *
+ * package.json files without a version are skipped. This passes over the
+ * `{"type": "module"}` and `{"type": "commonjs"}` markers in `dist/esm` and `dist/cjs`.
+ *
+ * @param file - Path or `file:` URL of a module inside the package
+ * @param readFile - Reads a file as text and throws if it does not exist (replaceable in tests)
+ * @throws Error if no package.json with a version is found
+ */
+export function readPackageInfo(file, readFile = readUtf8File) {
+    const path = file.startsWith('file:') ? fileURLToPath(file) : file;
+    for (let dir = dirname(path);; dir = dirname(dir)) {
+        const packageJson = readPackageJson(join(dir, 'package.json'), readFile);
+        if (typeof packageJson?.version === 'string') {
+            return {
+                version: packageJson.version,
+                description: typeof packageJson.description === 'string' ? packageJson.description : '',
+            };
+        }
+        if (dirname(dir) === dir) {
+            throw new Error(`No package.json with a version found for ${path}`);
+        }
+    }
+}
+/**
+ * Pick the calling module from the file names of a stack, innermost first
+ *
+ * The first frame is this module. The caller is the first frame from another file that is a
+ * real module path or `file:` URL, which skips frames such as `node:internal/timers`.
+ *
+ * @throws Error if the stack has no such frame
+ */
+export function findCallerFile(files) {
+    const [ownFile] = files;
+    const callerFile = files.find((file) => file !== undefined && file !== ownFile && (file.startsWith('file:') || isAbsolute(file)));
+    if (callerFile === undefined) {
+        throw new Error('Cannot determine the calling module');
+    }
+    return callerFile;
+}
+/**
+ * Get the version and description of the package that contains the calling module
+ *
+ * Lets a CLI report its own package.json values without hardcoding them. The caller's
+ * location comes from the call stack, so it works the same in ES module and CommonJS
+ * builds, where `import.meta.url` and `__dirname` are each available in only one.
+ *
+ * @example
+ * ```typescript
+ * const { version } = getCallerPackageInfo()
+ * program.version(version)
+ * ```
+ *
+ * @throws Error if the calling module cannot be determined or has no package.json with a version
+ */
+export function getCallerPackageInfo() {
+    const files = getCallSites().map((callSite) => callSite.getFileName() ?? undefined);
+    return readPackageInfo(findCallerFile(files));
+}
+//# sourceMappingURL=package-info.js.map

package/dist/esm/src/package-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-info.js","sourceRoot":"","sources":["../../../src/package-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAOxC,MAAM,qBAAqB,GAAG,EAAE,CAAA;AAEhC;;;;GAIG;AACH,SAAS,YAAY;IACnB,4FAA4F;IAC5F,MAAM,eAAe,GAAG,KAAK,CAAC,iBAAiB,CAAA;IAC/C,MAAM,aAAa,GAAG,KAAK,CAAC,eAAe,CAAA;IAC3C,IAAI,CAAC;QACH,KAAK,CAAC,iBAAiB,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,CAAA;QAC1D,gFAAgF;QAChF,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,qBAAqB,CAAC,CAAA;QACtE,OAAO,IAAI,KAAK,EAAE,CAAC,KAAqC,CAAA;IAC1D,CAAC;YAAS,CAAC;QACT,KAAK,CAAC,iBAAiB,GAAG,eAAe,CAAA;QACzC,KAAK,CAAC,eAAe,GAAG,aAAa,CAAA;IACvC,CAAC;AACH,CAAC;AAID,MAAM,YAAY,GAAiB,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AAExE,SAAS,eAAe,CACtB,IAAY,EACZ,QAAsB;IAEtB,IAAI,OAAe,CAAA;IACnB,IAAI,CAAC;QACH,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgD,CAAA;AAC3E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,WAAyB,YAAY;IACjF,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAElE,KAAK,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAI,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACnD,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,QAAQ,CAAC,CAAA;QACxE,IAAI,OAAO,WAAW,EAAE,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC7C,OAAO;gBACL,OAAO,EAAE,WAAW,CAAC,OAAO;gBAC5B,WAAW,EAAE,OAAO,WAAW,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;aACxF,CAAA;QACH,CAAC;QACD,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,4CAA4C,IAAI,EAAE,CAAC,CAAA;QACrE,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAwC;IACrE,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,CAAA;IACvB,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAC3B,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAC3F,CAAA;IAED,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;IACxD,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,SAAS,CAAC,CAAA;IAEnF,OAAO,eAAe,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;AAC/C,CAAC"}