node-opcua-convert-nodeset-to-javascript 2.180.0 → 2.181.1

package/source/convert_to_typescript.ts

@@ -8,11 +8,11 @@ import type { IBasicSessionBrowseAsyncSimple, IBasicSessionReadAsyncSimple } fro
 import { type ReferenceDescription, StructureDefinition } from "node-opcua-types";
 import { LineFile } from "node-opcua-utils";
 import { DataType } from "node-opcua-variant";
-import { _exportDataTypeToTypescript } from "./_dataType";
-import type { Options } from "./options";
-import { type Cache, constructCache, type Import, makeTypeNameNew, type RequestedSubSymbol } from "./private/cache";
-import { getCorrespondingJavascriptType2 } from "./private/get_corresponding_data_type";
-import { toFilename } from "./private/to_filename";
+import { _exportDataTypeToTypescript } from "./_dataType.js";
+import type { Options } from "./options.js";
+import { type Cache, constructCache, type Import, makeTypeNameNew, type RequestedSubSymbol } from "./private/cache.js";
+import { getCorrespondingJavascriptType2 } from "./private/get_corresponding_data_type.js";
+import { toFilename } from "./private/to_filename.js";
 import {
     extractBasicDataType,
     getBrowseName,
@@ -26,8 +26,8 @@ import {
     getSubtypeNodeIdIfAny,
     getTypeDefOrBaseType,
     getValueRank
-} from "./private/utils";
-import { f1, f2, quotifyIfNecessary, toComment, toJavascritPropertyName } from "./utils2";
+} from "./private/utils.js";
+import { f1, f2, quotifyIfNecessary, toComment, toJavascritPropertyName } from "./utils2.js";
 
 const warningLog = make_warningLog("typescript");
 const debugLog = make_debugLog("typescript");
@@ -399,7 +399,10 @@ async function _extractLocalMembers(
         if (!browseName.name) {
             throw new Error(`Expecting a browseName.name for node ${nodeId.toString()}`);
         }
-        const name = toJavascritPropertyName(browseName.name, { ignoreConflictingName: true });
+        const name = toJavascritPropertyName(browseName.name, {
+            ignoreConflictingName: true,
+            parentNodeClass: classMember.nodeClass
+        });
 
         const description = await getDescription(session, nodeId);
         const modellingRule = await getModellingRule(session, nodeId);
@@ -533,12 +536,26 @@ async function extractVariableExtra(
 }
 
 interface ClassDefinitionB {
+    /** the class of the type; its instances are of the matching instance class */
+    nodeClass?: NodeClass.VariableType | NodeClass.ObjectType;
     superType?: {
         nodeId: NodeId;
     };
     interfaceName: Import;
     baseClassDef?: ClassDefinition | null;
 }
+
+/** the class of the instances of a type: what a generated interface describes */
+function instanceNodeClass(typeNodeClass: NodeClass | undefined): NodeClass | undefined {
+    switch (typeNodeClass) {
+        case NodeClass.ObjectType:
+            return NodeClass.Object;
+        case NodeClass.VariableType:
+            return NodeClass.Variable;
+        default:
+            return typeNodeClass;
+    }
+}
 export async function extractClassMemberDef(
     session: IBasicSessionReadAsyncSimple & IBasicSessionBrowseAsyncSimple,
     nodeId: NodeId,
@@ -551,7 +568,10 @@ export async function extractClassMemberDef(
     if (!browseName.name) {
         throw new Error(`Expecting a browseName.name for node ${nodeId.toString()}`);
     }
-    const name = toJavascritPropertyName(browseName.name, { ignoreConflictingName: true });
+    const name = toJavascritPropertyName(browseName.name, {
+        ignoreConflictingName: true,
+        parentNodeClass: instanceNodeClass(parentDef.nodeClass)
+    });
 
     if (nodeClass !== NodeClass.Method && nodeClass !== NodeClass.Object && nodeClass !== NodeClass.Variable) {
         throw new Error(`Invalid property ${NodeClass[nodeClass]} ${browseName?.toString()} ${nodeId.toString()}`);
@@ -740,6 +760,8 @@ function dumpChildren(padding: string, children: ClassMemberBasic[], f: LineFile
             continue;
         }
         cache.ensureImported(childType);
+        // name went through the rule already, with its parent class known; this is the same
+        // transformation applied to an already adjusted name, hence no parent class here
         const adjustedName = toJavascritPropertyName(name, { ignoreConflictingName: true });
         if (description.text) {
             f.write(`${padding}/**`);
@@ -807,7 +829,10 @@ function dumpUsedExport(currentType: string, namespaceIndex: number, cache: Cach
             )) {
                 const filename = toFilename(symbol);
                 const subSymbolList = getSubSymbolList(s);
-                f.write(`import { ${subSymbolList.join(", ")} } from "./${filename}"`);
+                // ".js": ESM has no extension search, and the generated files are shipped
+                // source. Without it every regeneration would undo the extensions across
+                // ~1000 nodeset files and fail the drift check.
+                f.write(`import { ${subSymbolList.join(", ")} } from "./${filename}.js"`);
             }
         } else {
             if (cache.requestedSymbols.namespace[ns]) {

package/source/index.ts

@@ -1,3 +1,3 @@
-export * from "./convert_namespace_to_typescript";
-export * from "./convert_to_typescript";
-export * from "./walk_through";
+export * from "./convert_namespace_to_typescript.js";
+export * from "./convert_to_typescript.js";
+export * from "./walk_through.js";

package/source/main.ts

@@ -2,13 +2,16 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { AddressSpace, PseudoSession } from "node-opcua-address-space";
+import { AddressSpace, type BaseNode, childAccessorNamesShadowedBy, PseudoSession, type UAObject } from "node-opcua-address-space";
 import { generateAddressSpace } from "node-opcua-address-space/nodeJS";
+import { NodeClass } from "node-opcua-data-model";
 import { constructNodesetFilename, nodesetCatalog } from "node-opcua-nodesets";
 
-import { convertNamespaceTypeToTypescript } from "./convert_namespace_to_typescript";
-import { cleanUpTypescriptModule } from "./remove_unused";
-import { updateParentTSConfig } from "./update_parent_tsconfig";
+import { convertNamespaceTypeToTypescript } from "./convert_namespace_to_typescript.js";
+import { packagesFolder } from "./package_root.js";
+import { cleanUpTypescriptModule } from "./remove_unused.js";
+import { updateParentTSConfig } from "./update_parent_tsconfig.js";
+import { setChildAccessorShadowing } from "./utils2.js";
 
 async function runWithConcurrency<T>(items: T[], limit: number, fn: (item: T) => Promise<void>): Promise<void> {
     let cursor = 0;
@@ -28,9 +31,31 @@ async function main() {
     const xmlFiles = nodesetCatalog.map((set) => constructNodesetFilename(set.xmlFile));
     await generateAddressSpace(addressSpace, xmlFiles);
 
+    // the names a generated interface must escape are the ones the runtime cannot expose on a
+    // node of that class, read off a node of each class rather than listed here
+    const server = addressSpace.rootFolder.objects.getFolderElementByName("Server") as UAObject | null;
+    const sampleNode: Partial<Record<NodeClass, BaseNode | null | undefined>> = {
+        [NodeClass.Object]: server,
+        [NodeClass.Variable]: server?.getPropertyByName("NamespaceArray"),
+        [NodeClass.Method]: server?.getMethodByName("GetMonitoredItems")
+    };
+    const shadowedByClass = new Map<NodeClass, ReadonlySet<string>>();
+    setChildAccessorShadowing((nodeClass) => {
+        let shadowed = shadowedByClass.get(nodeClass);
+        if (!shadowed) {
+            const node = sampleNode[nodeClass];
+            if (!node) {
+                return undefined;
+            }
+            shadowed = childAccessorNamesShadowedBy(node);
+            shadowedByClass.set(nodeClass, shadowed);
+        }
+        return shadowed;
+    });
+
     const session = new PseudoSession(addressSpace);
     const options = {
-        baseFolder: path.join(__dirname, "../../"),
+        baseFolder: packagesFolder,
         prefix: "node-opcua-nodeset-"
     };
     // const nodesetCatalog2 = nodesetCatalog.filter((meta) => meta.name == "scales");

package/source/package_root.ts

@@ -0,0 +1,21 @@
+import path from "node:path";
+
+/**
+ * The one place this package learns where it sits on disk.
+ *
+ * Everything else derives from `packagesFolder` rather than recomputing it, so the
+ * ESM migration has a single line to change here instead of five scattered across
+ * four files. `import.meta.dirname` cannot be used while this package emits CommonJS
+ * (TS1470), which is why the flip has to wait for the package to become "type": "module".
+ *
+ * Deliberately not `process.cwd()`: this package declares a `bin`, so it can be invoked
+ * as a CLI from any directory, and cwd would then resolve somewhere else entirely.
+ * A tool has to find its own files relative to itself.
+ */
+const here = __dirname;
+
+/** this package's own root, one level above the compiled output */
+export const packageRoot = path.join(here, "..");
+
+/** the monorepo's packages/ folder, which is where generated nodeset packages are written */
+export const packagesFolder = path.join(here, "../../");

package/source/private/cache.ts

@@ -5,8 +5,8 @@ import { AttributeIds, NodeClass, QualifiedName } from "node-opcua-data-model";
 import { type NodeId, resolveNodeId } from "node-opcua-nodeid";
 import type { IBasicSessionReadAsyncSimple } from "node-opcua-pseudo-session";
 import { type DataTypeDefinition, EnumDefinition } from "node-opcua-types";
-import type { Options } from "../options";
-import { getBrowseName, getDefinition } from "./utils";
+import type { Options } from "../options.js";
+import { getBrowseName, getDefinition } from "./utils.js";
 
 export interface Import {
     name: string;

package/source/private/get_corresponding_data_type.ts

@@ -1,9 +1,9 @@
 import type { NodeId } from "node-opcua-nodeid";
 import type { IBasicSessionBrowseAsyncSimple, IBasicSessionReadAsyncSimple } from "node-opcua-pseudo-session";
 import { DataType } from "node-opcua-variant";
-import type { Cache } from "./cache";
-import { type Import, referenceEnumeration, referenceExtensionObject } from "./cache";
-import { _convertNodeIdToDataTypeAsync, getValueRank } from "./utils";
+import type { Cache } from "./cache.js";
+import { type Import, referenceEnumeration, referenceExtensionObject } from "./cache.js";
+import { _convertNodeIdToDataTypeAsync, getValueRank } from "./utils.js";
 
 export async function getCorrespondingJavascriptType2(
     session: IBasicSessionReadAsyncSimple & IBasicSessionBrowseAsyncSimple,

package/source/private/utils.ts

@@ -7,8 +7,8 @@ import type { IBasicSessionBrowseAsyncSimple, IBasicSessionReadAsyncSimple } fro
 import { type BrowseResult, type DataTypeDefinition, ReferenceDescription } from "node-opcua-types";
 import { DataType } from "node-opcua-variant";
 
-const debugLog = make_debugLog(__filename);
-const doDebug = checkDebugFlag(__filename);
+const debugLog = make_debugLog("utils");
+const doDebug = checkDebugFlag("utils");
 
 export async function getDefinition(session: IBasicSessionReadAsyncSimple, nodeId: NodeId): Promise<DataTypeDefinition | null> {
     const dataValue = await session.read({ nodeId, attributeId: AttributeIds.DataTypeDefinition });

package/source/private-stuff.ts

@@ -1,4 +1,4 @@
-export * from "./index";
-export * from "./options";
-export * from "./private/cache";
-export * from "./private/utils";
+export * from "./index.js";
+export * from "./options.js";
+export * from "./private/cache.js";
+export * from "./private/utils.js";

package/source/remove_unused.ts

@@ -4,7 +4,7 @@ import path from "node:path";
 import type { ImportDeclarationStructure, OptionalKind, SourceFile } from "ts-morph";
 import { Node, Project, SyntaxKind } from "ts-morph";
 
-import { retryOnTransientWrite } from "./private/fs_retry";
+import { retryOnTransientWrite } from "./private/fs_retry.js";
 
 const dryRun = false;
 
@@ -133,7 +133,12 @@ function regroupImports(file: SourceFile) {
         const ga = importGroup(a.moduleSpecifier);
         const gb = importGroup(b.moduleSpecifier);
         if (ga !== gb) return ga - gb;
-        return a.moduleSpecifier.localeCompare(b.moduleSpecifier);
+        // Code point, not localeCompare. Two reasons. localeCompare is locale-dependent,
+        // so generated output committed from one machine could differ on another, and
+        // this output is committed and drift-checked. And its collation ranks "." after
+        // "_", which flips "./x.js" past "./x_y.js" the moment extensions are added,
+        // disagreeing with biome's ordering and taking the lint gate red.
+        return a.moduleSpecifier < b.moduleSpecifier ? -1 : a.moduleSpecifier > b.moduleSpecifier ? 1 : 0;
     });
 
     file.insertImportDeclarations(0, structures);

package/source/update_parent_tsconfig.ts

@@ -6,14 +6,12 @@ import { existsSync, promises as fsPromises } from "node:fs";
 const { readFile, writeFile } = fsPromises;
 
 import path from "node:path";
-// Uncomment the following to get __dirname equivalent when compiling to ESM
-//import { fileURLToPath } from 'url';
-//const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 import { nodesetCatalog } from "node-opcua-nodesets";
 
+import { packagesFolder } from "./package_root.js";
+
 export async function updateParentTSConfig() {
-    const packagesFolder = path.join(__dirname, "..", "..");
     const parentTSConfigFile = path.join(packagesFolder, "tsconfig.json");
     console.log(`Updating parent tsconfig.json file: ${parentTSConfigFile}`);
     const content = await readFile(parentTSConfigFile, "utf8");

package/source/utils2.ts

@@ -1,3 +1,4 @@
+import type { NodeClass } from "node-opcua-data-model";
 import { lowerFirstLetter } from "node-opcua-utils";
 import wrap from "wordwrap";
 
@@ -11,31 +12,48 @@ export function toComment(prefix: string, description: string) {
         .join("\n");
 }
 
-// to avoid clashes
-export function toJavascritPropertyName(childName: string, { ignoreConflictingName }: { ignoreConflictingName: boolean }): string {
+/**
+ * the names under which the runtime never exposes a child of a node of the given class, by the
+ * rule node-opcua-address-space applies (`childAccessorNamesShadowedBy`); registered by main()
+ * once the address space is loaded, absent in a unit test
+ */
+export type ChildAccessorShadowing = (parentNodeClass: NodeClass) => ReadonlySet<string> | undefined;
+
+let childAccessorShadowing: ChildAccessorShadowing | undefined;
+
+export function setChildAccessorShadowing(provider: ChildAccessorShadowing | undefined): void {
+    childAccessorShadowing = provider;
+}
+
+/**
+ * the names the generated interfaces have always escaped: kept whatever the runtime rule says, so
+ * that an interface published under one of them does not change under its users
+ */
+const historicallyEscaped = new Set([
+    "namespaceUri",
+    "rolePermissions",
+    "displayName",
+    "eventNotifier",
+    "description",
+    "decode",
+    "encode"
+]);
+
+/**
+ * the TypeScript property name of a child: its browse name lower-cased the way the runtime does,
+ * and `$`-prefixed when the runtime could not expose it under that name on a node of
+ * `parentNodeClass` (a child named NamespaceUri, DataType on a variable, Then on anything)
+ */
+export function toJavascritPropertyName(
+    childName: string,
+    { ignoreConflictingName, parentNodeClass }: { ignoreConflictingName: boolean; parentNodeClass?: NodeClass }
+): string {
     childName = lowerFirstLetter(childName);
 
     if (ignoreConflictingName) {
-        if (childName === "namespaceUri") {
-            childName = "$namespaceUri";
-        }
-        if (childName === "rolePermissions") {
-            childName = "$rolePermissions";
-        }
-        if (childName === "displayName") {
-            childName = "$displayName";
-        }
-        if (childName === "eventNotifier") {
-            childName = "$eventNotifier";
-        }
-        if (childName === "description") {
-            childName = "$description";
-        }
-        if (childName === "decode") {
-            childName = "$decode";
-        }
-        if (childName === "encode") {
-            childName = "$encode";
+        const shadowed = parentNodeClass === undefined ? undefined : childAccessorShadowing?.(parentNodeClass);
+        if (historicallyEscaped.has(childName) || shadowed?.has(childName)) {
+            childName = `$${childName}`;
         }
     }
     return childName.replace(/</g, "$").replace(/>/g, "$").replace(/ |\./g, "_").replace(/#/g, "_");