opcua-snapshot 1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, do-
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,98 @@
+`node-opcua-snapshot` is a Node.js library that enables snapshot-based management of [OPC UA](https://opcfoundation.org/about/opc-technologies/opc-ua/) server address spaces. It provides two primary capabilities:
+
+* **Extraction**: Connect to an existing OPC UA server and capture its address space structure, node configurations, and relationships into a portable JSON format
+* **Recreation**: Load a JSON snapshot and populate a new OPC UA server with the captured configuration
+
+The library acts as a configuration management layer on top of the [node-opcua](https://node-opcua.github.io/) protocol implementation, enabling use cases such as:
+
+* Creating test servers with production-like configurations
+* Version-controlling OPC UA server structures
+* Cloning servers across different environments
+* Building mock servers for offline development
+
+# Installation
+
+```sh
+npm install opcua-snapshot
+```
+
+# Usage
+## Taking a Snapshot from an Existing Server
+
+```js
+const fs            = require ('node:fs')
+const {OPCUAClient} = require ('node-opcua')
+const {Dumper}      = require ('opcua-snapshot')
+
+async function dump (filePath, endpointUrl, rootNode) {
+
+    const client = OPCUAClient.create ({endpointMustExist: false})
+
+    try {
+
+        await client.connect (endpointUrl)
+
+        const session = await client.createSession ()
+
+        const dumper = new Dumper (session)
+
+        // dumper.on ('start',   _ => console.log (_))
+        // dumper.on ('warning', _ => console.log (_))
+        // dumper.on ('finish', _  => console.log ('finish'))
+
+        const snapshot = await dumper.dump (rootNode /* ?? {ns: 0, i: 85}*/) // `Objects` by default
+
+        fs.writeFileSync (filePath, JSON.stringify (snapshot, null, 2))
+
+    }
+    finally {
+
+        await client.disconnect ()
+
+    }
+
+}
+```
+
+## Using a Saved Snapshot to run a New Server
+
+```js
+
+const fs            = require ('node:fs')
+const {OPCUAServer} = require ('node-opcua')
+const {Loader}      = require ('opcua-snapshot')
+
+// mock history data
+const MS_IN_DAY     = 1000 * 60 * 60 * 24
+const values = [0.0], dates = [(new Date (new Date ().toJSON ().substring (0, 10) + 'T00:00:00')).getTime ()]
+for (let i = 0; i < 10; i ++) {
+    values.push (values [i] + Math.random ())
+    dates.unshift (dates [0] - MS_IN_DAY)
+}
+
+async function run (fn, port) {
+
+    const server = new OPCUAServer ({endpoints: [{port}]})
+
+    await server.initialize ()                      // prior to creating the Loader
+
+    const loader = new Loader (server)
+
+    loader.on ('var', varNode => {                  // will adjust variables upon creation:
+        if (!varNode.historizing) return            // for historical ones (in this example)...
+        varNode.accessLevel = 4                     // ... only allow HistoryRead
+        loader.setValues (varNode, values, dates)   // ... and set the generated values
+    })
+    
+    loader.load (JSON.parse (fs.readFileSync (fn))) // actually load the configuration
+
+    await server.start ()
+
+    loader.setValue ('ns=1;s=MyObj.MyProp', '1234') // at run time
+
+}
+```
+
+# See Also
+
+More documentaion available at https://deepwiki.com/do-/node-opcua-snapshot

package/index.js

@@ -0,0 +1,4 @@
+const Dumper = require ('./lib/Dumper')
+const Loader = require ('./lib/Loader')
+
+module.exports = {Dumper, Loader}

package/lib/Dumper.js

@@ -0,0 +1,149 @@
+const EventEmitter = require ('node:events')
+const opcua = require ('node-opcua')
+
+const DEFAUT_ROOT = {
+    ns   :  0,
+    id   : 'i=85',
+    type : 'FolderType',
+}
+
+const nodeId = ({ns, id}) => `ns=${ns};${id}`
+
+const NS0 = 'ns=0;i=', ns0id = (name, s, postfix = 'TypeIds') => {
+
+    const k = name + postfix; if (!(k in opcua)) return undefined
+
+    if (typeof s !== 'string' || !s.startsWith (NS0)) return undefined
+
+    return opcua [k] [parseInt (s.substring (NS0.length))]
+    
+}
+
+module.exports = class extends EventEmitter {
+
+    #session
+
+    constructor (session) {
+
+        super ()
+
+        this.#session = session
+
+    }
+
+    async browse (nodeId) {
+
+        this.emit ('start', nodeId)
+
+        try {
+
+            const {statusCode, references} = await this.#session.browse (nodeId); if (statusCode.isGoodish ()) return references
+
+            this.emit ('warning', statusCode); return []
+
+        }
+        finally {
+
+            this.emit ('finish')
+
+        }
+
+    }
+
+    async read (nodeIds) {
+
+        this.emit ('start', nodeIds)
+
+        try {
+
+            return await this.#session.read (nodeIds.map (nodeId => ({nodeId})))
+
+        }
+        finally {
+
+            this.emit ('finish')
+
+        }
+
+    }
+
+    async loadObject (parent) {
+
+        const references = await this.browse (nodeId (parent)), vars = []
+
+        for (const reference of references) if (reference.isForward) {
+
+            const {referenceTypeId, nodeClass, nodeId, browseName: {namespaceIndex, name}, typeDefinition} = reference.toJSON (), dst = {
+                class: nodeClass,
+                ns: namespaceIndex,
+                id: nodeId.substring (1 + nodeId.indexOf (';')),
+                name
+            }
+
+            dst.type = ns0id (nodeClass, typeDefinition)
+
+            if (dst.class === 'Variable') vars.push (dst)
+
+            await this.loadObject (dst)
+
+            {
+
+                const ref = ns0id ('Reference', referenceTypeId)
+
+                if (!(ref in parent)) parent [ref] = []; parent [ref].push (dst)
+
+            }
+            
+        }
+
+        {
+
+            const {length} = vars; if (length !== 0) {
+
+                const vals = await this.read (vars.map (nodeId))
+
+                for (let i = 0; i < length; i ++) {
+
+                    const v = vars [i], {dataType, value} = vals [i].value
+
+                    v.dataType = dataType
+
+                    if (value != null) v.value = value
+
+                }
+
+            }
+
+        }
+
+    }
+
+    toRootObject (arg = {}) {
+
+        if (typeof arg !== 'object') throw Error (`Not an object: ${arg}`)
+
+        if (arg.class != null && arg.class !== 'Object') throw Error (`root.class must be 'Object', found ${root.class}`)
+
+        const {ns, id, name, type} = {...DEFAUT_ROOT, ...arg}
+
+        return {
+            class: 'Object',
+            ns,
+            id,
+            name: name ?? ns0id ('Object', nodeId ({ns, id}), 'Ids'),
+            type
+        }
+
+    }
+
+    async dump (arg) {
+
+        const root = this.toRootObject (arg)
+
+        await this.loadObject (root)
+
+        return root
+
+    }
+
+}

package/lib/Loader.js

@@ -0,0 +1,136 @@
+const EventEmitter  = require ('node:events')
+const {StatusCodes} = require ('node-opcua')
+
+const Snapshot     = require('./Snapshot')
+    , {nodeId}    = Snapshot
+    ,  browseName = o => ({namespaceIndex : o.ns         , name   : o.name})
+    ,  idName     = o => ({browseName     : browseName(o), nodeId : nodeId (o)})
+
+const PROP = new Map ([
+    ['EngineeringUnits', 'engineeringUnits'],
+    ['EURange',          'engineeringUnitsRange'],
+    ['InstrumentRange',  'instrumentRange'],
+])
+
+const setValueFromSource = (node, value, status, date) => {
+
+    const dataType = node.dataType.value
+
+    if (dataType === 13) value = new Date (value)
+
+    if (date) date = new Date (date)
+
+    node.setValueFromSource ({dataType, value}, status, date)
+
+}
+
+module.exports = class extends EventEmitter {
+
+    #addressSpace
+
+    constructor (server) {
+
+        super ()
+
+        this.#addressSpace = server.engine.addressSpace
+
+    }
+
+    get NS () {
+
+        return this.#addressSpace.getNamespaceArray()
+
+    }
+
+    getNs (o) {
+
+        return this.NS [o.ns]
+
+    }
+
+    getNode (nodeOrId) {
+
+        if (typeof nodeOrId === 'object' && nodeOrId.nodeId) return nodeOrId
+
+        return this.#addressSpace.findNode (nodeOrId)
+
+    }
+
+    setNamespaceArray (namespaceArray) {
+
+        this.NS.splice (1, 1)
+
+        for (let i = 1; i < namespaceArray.length; i++)  this.#addressSpace.registerNamespace (namespaceArray [i])
+
+    }
+
+    setValue (nodeOrId, value, date, status = StatusCodes.Good) {
+
+        setValueFromSource (this.getNode (nodeOrId), value, status, date)
+
+    }
+
+    setValues (nodeOrId, values, dates, status = StatusCodes.Good) {
+
+        const node = this.getNode (nodeOrId)
+
+        for (let i = 0; i < dates.length; i ++) 
+            
+            setValueFromSource (node, values [i], status, dates [i])
+
+    }
+
+
+    addVariable (componentOf, o) {
+
+        let {dataType, value, HasHistoricalConfiguration} = o; if (dataType === 13) value = new Date (value)
+
+        const ns = this.getNs (o), options = {...idName (o), componentOf, dataType, minimumSamplingInterval: 1000}
+
+        if (!HasHistoricalConfiguration) options.value = {dataType, value}
+
+        switch (o.type) {
+            case 'BaseDataVariableType': return ns.addVariable (options)
+            case 'AnalogItemType'      : break  // see below
+            default                    : return // unsupported
+        }
+
+        if (Array.isArray (o.HasProperty)) for (const i of o.HasProperty) options [PROP.get (i.name)] = i.value
+
+        const node = ns.addAnalogDataItem (options)
+
+        if (HasHistoricalConfiguration) this.#addressSpace.installHistoricalDataNode (node)
+
+        return node
+
+    }
+
+    addObject (organizedBy, o) {
+
+        const {Organizes, HasComponent} = o
+
+        const node = this.getNs (o).addObject ({...idName(o), organizedBy})
+
+        if (Array.isArray (Organizes)) for (const i of Organizes) this.addObject (node, i)
+
+        if (Array.isArray (HasComponent)) for (const i of HasComponent) switch (i.class) {
+
+            case 'Variable':
+                this.emit ('var', this.addVariable (node, i))
+                break
+
+        }
+
+    }
+
+    load (root) {
+
+        const snapshot = new Snapshot (root)
+
+        this.setNamespaceArray (snapshot.namespaceArray)
+
+        for (const i of snapshot.objectsFolder) if (i.ns != 0) this.addObject (this.#addressSpace.rootFolder.objects, i)
+
+    }
+
+}

package/lib/Snapshot.js

@@ -0,0 +1,30 @@
+module.exports = class {
+
+    static nodeId = ({ns, id}) => `ns=${ns};${id}`
+
+    #root
+
+    constructor (root) {
+
+        this.#root = root
+
+    }
+
+    get objectsFolder () {
+
+        return this.#root
+            .Organizes.find (i => i.name === 'Objects')
+            .Organizes
+
+    }
+
+    get namespaceArray () {
+
+        return this.objectsFolder
+            .find (i => i.name === 'Server')
+            .HasProperty.find (i => i.name === 'NamespaceArray')
+                .value
+
+    }
+
+}