@yarkivaev/scada-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# scada-server
+
+Composable SCADA server with REST and SSE endpoints.
+
+## Install
+
+```
+npm install scada-server
+```
+
+## Usage
+
+```javascript
+import http from 'http';
+import { scadaServer } from 'scada-server';
+
+const api = scadaServer('/api', plant);
+http.createServer((req, res) => api.handle(req, res)).listen(3000);
+```
+
+## Client
+
+```javascript
+import { scadaClient } from 'scada-server/client';
+
+const client = scadaClient('http://localhost:3000/api', fetch, EventSource);
+const machine = client.machine('icht1');
+const measurements = await machine.measurements({ from: 'now-1h', to: 'now' });
+```
+
+## Modules
+
+### Server
+- `scadaServer`
+- `routes`
+
+### Objects
+- `route`
+- `jsonResponse`
+- `sseResponse`
+- `errorResponse`
+- `timeExpression`
+- `pagination`
+- `cursor`
+
+### Client
+- `scadaClient`
+- `machineClient`
+- `sseConnection`
+
+## License
+
+MIT

package/client/index.js

@@ -0,0 +1,12 @@
+/**
+ * SCADA Server JS Client.
+ * Provides typed methods for all API endpoints.
+ *
+ * @example
+ *   import { scadaClient } from 'scada-server/client';
+ *   const client = scadaClient('http://localhost:3000/api/v1', fetch, EventSource);
+ */
+
+export { default as machineClient } from './machineClient.js';
+export { default as scadaClient } from './scadaClient.js';
+export { default as sseConnection } from './sseConnection.js';

package/client/machineClient.js

@@ -0,0 +1,143 @@
+import sseConnection from './sseConnection.js';
+
+/**
+ * Client for single machine endpoints.
+ * Returns object with methods for machine operations.
+ *
+ * @param {string} baseUrl - API base URL
+ * @param {string} machineId - machine identifier
+ * @param {function} fetcher - fetch function
+ * @param {function} eventSource - EventSource constructor
+ * @returns {object} client with info, measurements, alerts, meltings methods
+ *
+ * @example
+ *   const machine = machineClient(baseUrl, 'icht1', fetch, EventSource);
+ *   const info = await machine.info();
+ */
+export default function machineClient(baseUrl, machineId, fetcher, eventSource) {
+    const url = `${baseUrl}/machines/${machineId}`;
+    async function request(path, options) {
+        const response = await fetcher(`${url}${path}`, options);
+        const payload = await response.json();
+        if (!response.ok) {
+            throw payload;
+        }
+        return payload;
+    }
+    return {
+        async info() {
+            return request('');
+        },
+        async measurements(options) {
+            const params = new URLSearchParams();
+            if (options && options.keys) {
+                params.set('keys', options.keys.join(','));
+            }
+            if (options && options.from) {
+                params.set('from', options.from);
+            }
+            if (options && options.to) {
+                params.set('to', options.to);
+            }
+            if (options && options.step) {
+                params.set('step', String(options.step));
+            }
+            const qs = params.toString();
+            return request(`/measurements${qs ? `?${qs}` : ''}`);
+        },
+        measurementStream(options) {
+            const params = new URLSearchParams();
+            if (options && options.keys) {
+                params.set('keys', options.keys.join(','));
+            }
+            if (options && options.since) {
+                params.set('since', options.since);
+            }
+            if (options && options.step) {
+                params.set('step', String(options.step));
+            }
+            const qs = params.toString();
+            return sseConnection(
+                `${url}/measurements/stream${qs ? `?${qs}` : ''}`,
+                eventSource
+            );
+        },
+        async alerts(options) {
+            const params = new URLSearchParams();
+            if (options && options.page) {
+                params.set('page', String(options.page));
+            }
+            if (options && options.size) {
+                params.set('size', String(options.size));
+            }
+            if (options && Object.hasOwn(options, 'acknowledged')) {
+                params.set('acknowledged', String(options.acknowledged));
+            }
+            const qs = params.toString();
+            return request(`/alerts${qs ? `?${qs}` : ''}`);
+        },
+        alertStream() {
+            return sseConnection(`${url}/alerts/stream`, eventSource);
+        },
+        async acknowledge(alertId) {
+            return request(`/alerts/${alertId}`, {
+                method: 'PATCH',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ acknowledged: true })
+            });
+        },
+        async meltings(options) {
+            const params = new URLSearchParams();
+            if (options && options.after) {
+                params.set('after', options.after);
+            }
+            if (options && options.before) {
+                params.set('before', options.before);
+            }
+            if (options && options.limit) {
+                params.set('limit', String(options.limit));
+            }
+            if (options && options.active) {
+                params.set('active', 'true');
+            }
+            const qs = params.toString();
+            return request(`/meltings${qs ? `?${qs}` : ''}`);
+        },
+        async melting(meltingId) {
+            return request(`/meltings/${meltingId}`);
+        },
+        meltingStream() {
+            return sseConnection(`${url}/meltings/stream`, eventSource);
+        },
+        async startMelting() {
+            return request('/meltings/start', { method: 'POST' });
+        },
+        async stopMelting(meltingId) {
+            return request(`/meltings/${meltingId}/stop`, { method: 'POST' });
+        },
+        async weight() {
+            return request('/weight');
+        },
+        async setWeight(amount) {
+            return request('/weight', {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ amount })
+            });
+        },
+        async load(amount) {
+            return request('/load', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ amount })
+            });
+        },
+        async dispense(amount) {
+            return request('/dispense', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ amount })
+            });
+        }
+    };
+}

package/client/scadaClient.js

@@ -0,0 +1,33 @@
+import machineClient from './machineClient.js';
+
+/**
+ * Main SCADA API client.
+ * Returns object with machines() and machine() methods.
+ *
+ * @param {string} baseUrl - server base URL
+ * @param {function} fetcher - fetch function
+ * @param {function} eventSource - EventSource constructor
+ * @returns {object} client with machines, machine methods
+ *
+ * @example
+ *   const client = scadaClient('http://localhost:3000/api/v1', fetch, EventSource);
+ *   const machines = await client.machines();
+ *   const machine = client.machine('icht1');
+ */
+export default function scadaClient(baseUrl, fetcher, eventSource) {
+    return {
+        async machines() {
+            const response = await fetcher(`${baseUrl}/machines`);
+            const payload = await response.json();
+            if (!response.ok) {
+                const error = new Error(payload.error.message);
+                error.code = payload.error.code;
+                throw error;
+            }
+            return payload;
+        },
+        machine(machineId) {
+            return machineClient(baseUrl, machineId, fetcher, eventSource);
+        }
+    };
+}

package/client/sseConnection.js

@@ -0,0 +1,30 @@
+/**
+ * SSE connection wrapper with event callbacks.
+ * Returns immutable object with on() and close() methods.
+ *
+ * @param {string} url - SSE endpoint URL
+ * @param {function} eventSource - EventSource constructor (for testing)
+ * @returns {object} connection with on, close methods
+ *
+ * @example
+ *   const conn = sseConnection(url, EventSource);
+ *   conn.on('measurement', data => console.log(data));
+ *   conn.close();
+ */
+export default function sseConnection(url, EventSourceCtor) {
+    const source = new EventSourceCtor(url);
+    const handlers = {};
+    return {
+        on(event, notify) {
+            handlers[event] = notify;
+            source.addEventListener(event, (ev) => {
+                const payload = JSON.parse(ev.data);
+                notify(payload);
+            });
+            return this;
+        },
+        close() {
+            source.close();
+        }
+    };
+}

package/index.js

@@ -0,0 +1,26 @@
+/**
+ * SCADA Server - Composable server implementing Supervisor API.
+ * Provides routes and scadaServer factory for integration with scada domain.
+ *
+ * @example
+ *   import http from 'http';
+ *   import { scadaServer } from 'scada-server';
+ *   import { plant, meltingShop, meltingMachine } from 'scada';
+ *
+ *   const p = createPlant(meltingMachine); // your plant factory
+ *   const server = scadaServer('/api/v1', p);
+ *   http.createServer((req, res) => server.handle(req, res)).listen(3000);
+ */
+
+// Server
+export { default as scadaServer } from './src/server/scadaServer.js';
+export { default as routes } from './src/server/routes.js';
+
+// Objects
+export { default as route } from './src/objects/route.js';
+export { default as jsonResponse } from './src/objects/jsonResponse.js';
+export { default as errorResponse } from './src/objects/errorResponse.js';
+export { default as sseResponse } from './src/objects/sseResponse.js';
+export { default as timeExpression } from './src/objects/timeExpression.js';
+export { default as pagination } from './src/objects/pagination.js';
+export { default as cursor } from './src/objects/cursor.js';

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@yarkivaev/scada-server",
+  "version": "1.0.0",
+  "description": "Composable SCADA server implementing Supervisor API",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yarkivaev/scada-server"
+  },
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "mocha --exit 'test/unit/**/*.js'",
+    "test:integration": "mocha --exit 'test/integration/**/*.js'",
+    "test:all": "mocha --exit 'test/**/*.js'",
+    "coverage": "c8 --all --src src npm test",
+    "coverage:integration": "c8 --all --src client npm run test:integration",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "c8": "^10.1.3",
+    "eslint": "^9.39.2",
+    "globals": "^17.0.0",
+    "mocha": "^10.2.0"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "client/"
+  ]
+}

package/src/objects/cursor.js

@@ -0,0 +1,50 @@
+/**
+ * Cursor-based pagination for meltings.
+ * Items must have a 'start' property with ISO8601 timestamp.
+ *
+ * @param {string} after - ISO8601 cursor (fetch after this time)
+ * @param {string} before - ISO8601 cursor (fetch before this time)
+ * @param {number} limit - max items to return
+ * @param {array} items - full item collection sorted by start desc
+ * @param {boolean} active - filter to show only active items (no end property)
+ * @returns {object} cursored with result() method
+ *
+ * @example
+ *   const cs = cursor(undefined, undefined, 10, items);
+ *   cs.result(); // { items: [...], nextCursor: '...', hasMore: true }
+ */
+export default function cursor(after, before, limit, items, active) {
+    const lim = Math.max(1, limit);
+    return {
+        result() {
+            let filtered = items;
+            if (after) {
+                const afterTime = new Date(after).getTime();
+                filtered = filtered.filter((item) => {
+                    return new Date(item.start).getTime() > afterTime;
+                });
+            }
+            if (before) {
+                const beforeTime = new Date(before).getTime();
+                filtered = filtered.filter((item) => {
+                    return new Date(item.start).getTime() < beforeTime;
+                });
+            }
+            if (active) {
+                filtered = filtered.filter((item) => {
+                    return !item.end;
+                });
+            }
+            const sliced = filtered.slice(0, lim);
+            const hasMore = filtered.length > lim;
+            const nextCursor = sliced.length > 0
+                ? sliced[sliced.length - 1].start
+                : undefined;
+            return {
+                items: sliced,
+                nextCursor,
+                hasMore
+            };
+        }
+    };
+}

package/src/objects/errorResponse.js

@@ -0,0 +1,20 @@
+import jsonResponse from './jsonResponse.js';
+
+/**
+ * Structured error response per API contract.
+ * Returns immutable object with send() method.
+ *
+ * @param {string} code - error code (NOT_FOUND, BAD_REQUEST, etc)
+ * @param {string} message - human-readable message
+ * @param {number} statusCode - HTTP status
+ * @returns {object} error with send method
+ *
+ * @example
+ *   errorResponse('NOT_FOUND', "Machine 'icht99' not found", 404).send(res);
+ */
+export default function errorResponse(code, message, statusCode) {
+    const payload = {
+        error: { code, message }
+    };
+    return jsonResponse(payload, statusCode);
+}

package/src/objects/jsonResponse.js

@@ -0,0 +1,24 @@
+/**
+ * JSON response formatter for HTTP.
+ * Returns immutable object with send() method.
+ *
+ * @param {object} payload - JSON-serializable data
+ * @param {number} statusCode - HTTP status (default 200)
+ * @returns {object} response with send method
+ *
+ * @example
+ *   jsonResponse({ items: [] }).send(response);
+ *   jsonResponse({ error: {...} }, 404).send(response);
+ */
+export default function jsonResponse(payload, statusCode) {
+    const code = statusCode || 200;
+    return {
+        send(response) {
+            response.writeHead(code, {
+                'Content-Type': 'application/json',
+                'Access-Control-Allow-Origin': '*'
+            });
+            response.end(JSON.stringify(payload));
+        }
+    };
+}

package/src/objects/pagination.js

@@ -0,0 +1,29 @@
+/**
+ * Page-based pagination for alerts.
+ * Returns immutable object with result() method.
+ *
+ * @param {number} page - 1-based page number
+ * @param {number} size - items per page
+ * @param {array} items - full item collection
+ * @returns {object} paginated with result() method
+ *
+ * @example
+ *   const pg = pagination(1, 10, items);
+ *   pg.result(); // { items: [...], page: 1, size: 10, total: 100 }
+ */
+export default function pagination(page, size, items) {
+    const pg = Math.max(1, page);
+    const sz = Math.max(1, size);
+    const start = (pg - 1) * sz;
+    const end = start + sz;
+    return {
+        result() {
+            return {
+                items: items.slice(start, end),
+                page: pg,
+                size: sz,
+                total: items.length
+            };
+        }
+    };
+}

package/src/objects/route.js

@@ -0,0 +1,54 @@
+/**
+ * HTTP route with path matching and parameter extraction.
+ * Returns immutable object with matches() and handle() methods.
+ *
+ * @param {string} method - HTTP method (GET, PATCH, etc)
+ * @param {string} path - URL pattern with :param placeholders
+ * @param {function} action - receives (request, response, params, query)
+ * @returns {object} route with matches, handle methods
+ *
+ * @example
+ *   const rt = route('GET', '/machines/:id', action);
+ *   rt.matches(request); // boolean
+ *   rt.handle(request, response);
+ */
+export default function route(method, path, action) {
+    const parts = path.split('/');
+    const params = parts
+        .map((part, index) => {
+            return { part, index };
+        })
+        .filter((item) => {
+            return item.part.startsWith(':');
+        })
+        .map((item) => {
+            return { name: item.part.slice(1), index: item.index };
+        });
+    const pattern = parts
+        .map((part) => {
+            return part.startsWith(':') ? '[^/]+' : part;
+        })
+        .join('/');
+    const regex = new RegExp(`^${pattern}$`, 'u');
+    return {
+        matches(request) {
+            const url = request.url.split('?')[0];
+            return request.method === method && regex.test(url);
+        },
+        handle(request, response) {
+            const url = request.url.split('?')[0];
+            const urlParts = url.split('/');
+            const extracted = params.reduce((acc, param) => {
+                return { ...acc, [param.name]: urlParts[param.index] };
+            }, {});
+            const queryString = request.url.split('?')[1];
+            const query = queryString
+                ? queryString.split('&').reduce((acc, pair) => {
+                    const [key, val] = pair.split('=');
+                    return { ...acc, [key]: decodeURIComponent(val || '') };
+                }, {})
+                : {};
+            return action(request, response, extracted, query);
+        }
+    };
+}

package/src/objects/sseResponse.js

@@ -0,0 +1,34 @@
+/**
+ * Server-Sent Events response.
+ * Returns immutable object with emit(), heartbeat(), close() methods.
+ *
+ * @param {object} response - HTTP response object
+ * @param {function} clock - time provider for heartbeats
+ * @returns {object} sse with emit, heartbeat, close methods
+ *
+ * @example
+ *   const sse = sseResponse(response, () => new Date());
+ *   sse.emit('measurement', { key: 'voltage', value: 380 });
+ *   sse.heartbeat();
+ *   sse.close();
+ */
+export default function sseResponse(response, clock) {
+    response.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'Access-Control-Allow-Origin': '*'
+    });
+    return {
+        emit(event, payload) {
+            response.write(`event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`);
+        },
+        heartbeat() {
+            const timestamp = clock().toISOString();
+            response.write(`event: heartbeat\ndata: ${JSON.stringify({ timestamp })}\n\n`);
+        },
+        close() {
+            response.end();
+        }
+    };
+}

package/src/objects/timeExpression.js

@@ -0,0 +1,47 @@
+/**
+ * Parser for time expressions per API contract.
+ * Supports: now, beginning, ISO8601, with +/- duration operators.
+ *
+ * @param {string} expression - time expression string
+ * @param {function} clock - provides current time
+ * @param {function} beginning - provides first data timestamp
+ * @returns {object} parsed time with resolve() method
+ *
+ * @example
+ *   const te = timeExpression('now-1h', clock, beginning);
+ *   te.resolve(); // Date object 1 hour ago
+ */
+export default function timeExpression(expression, clock, beginning) {
+    const durations = {
+        s: 1000,
+        m: 60 * 1000,
+        h: 60 * 60 * 1000,
+        d: 24 * 60 * 60 * 1000,
+        w: 7 * 24 * 60 * 60 * 1000,
+        M: 30 * 24 * 60 * 60 * 1000
+    };
+    return {
+        resolve() {
+            const match = expression.match(/^(now|beginning|[\dT:.Z-]+)([+-]\d+[smhdwM])?$/u);
+            if (!match) {
+                return clock();
+            }
+            const [, base, delta] = match;
+            let time;
+            if (base === 'now') {
+                time = clock().getTime();
+            } else if (base === 'beginning') {
+                time = beginning().getTime();
+            } else {
+                time = new Date(base).getTime();
+            }
+            if (delta) {
+                const sign = delta[0] === '+' ? 1 : -1;
+                const amount = parseInt(delta.slice(1, -1), 10);
+                const unit = delta.slice(-1);
+                time += sign * amount * durations[unit];
+            }
+            return new Date(time);
+        }
+    };
+}