@tsplc/opcua 0.0.0-stage → 0.2.0

package/src/native.ts

@@ -0,0 +1,35 @@
+import "reflect-metadata";
+
+// Bun executable bundles can initialize ESM dependencies before CommonJS side effects.
+// Load the provider only after its required metadata polyfill has run.
+const [client, certificates] = await Promise.all([
+  import("node-opcua-client"),
+  import("node-opcua-certificate-manager"),
+]);
+export const {
+  AttributeIds,
+  DataType,
+  VariantArrayType,
+  MessageSecurityMode,
+  OPCUAClient,
+  SecurityPolicy,
+  UserTokenType,
+  TimestampsToReturn,
+  BrowseDirection,
+  makeResultMask,
+  NodeClass,
+  ObjectIds,
+  resolveNodeId,
+} = client;
+export const { OPCUACertificateManager } = certificates;
+export type DataType = import("node-opcua-client").DataType;
+export type {
+  ClientSession,
+  BrowseDescriptionOptions,
+  BrowseResult,
+  NodeIdLike,
+  DataValue,
+  ReadValueIdOptions,
+  StatusCode,
+  WriteValueOptions,
+} from "node-opcua-client";

package/src/plc.ts

@@ -0,0 +1,146 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { type ClientSession, type ConnectionOptions, connectPlc } from "./client";
+import { contractVariables, type PlcContract } from "./contract";
+import { discoverVariables } from "./discovery";
+import { createMachineClient, type MachineDefinition } from "./machines";
+import { type Snapshot, unavailableSnapshot } from "./snapshot";
+import { createVariableManager, type VariableBinding } from "./variable-manager";
+import { readVariables, writeVariables } from "./variables";
+
+export interface PlcLog {
+  info: (message: string) => void;
+  warn: (message: string, error: unknown) => void;
+}
+
+export interface PlcOptions extends ConnectionOptions {
+  contract: PlcContract;
+  /** Published symbols to poll, such as the generated `publication.production`. */
+  publication: readonly string[];
+  log?: PlcLog;
+}
+
+const pollIntervalMs = 1000;
+const reconnectDelayMs = 2000;
+const staleAfterMs = 5000;
+
+const sleep = (ms: number, signal: AbortSignal) =>
+  delay(ms, undefined, { signal }).catch(() => undefined);
+
+/**
+ * One reconnecting OPC UA session to a tsPLC application. `run` connects,
+ * discovers the published symbols and polls them into `snapshot()` until aborted;
+ * `get`/`set` read and write whole symbols through the current session.
+ */
+export const createPlc = <Globals>(options: PlcOptions) => {
+  const variables = contractVariables(options.contract, options.publication);
+  let state = unavailableSnapshot("Waiting for the PLC");
+  let binding: (VariableBinding & { session: ClientSession }) | null = null;
+
+  const currentBinding = () => {
+    if (!binding) throw new Error("PLC is not connected");
+    return binding;
+  };
+
+  /** The latest poll, or unavailable when disconnected or the last read is stale. */
+  const snapshot = (): Snapshot =>
+    state.updatedAt && Date.now() - Date.parse(state.updatedAt) > staleAfterMs
+      ? unavailableSnapshot("PLC data is stale; waiting for a fresh read")
+      : state;
+
+  const poll = async (signal: AbortSignal) => {
+    const client = await connectPlc(options);
+    const clear = () => {
+      binding = null;
+    };
+    signal.addEventListener("abort", clear, { once: true });
+    try {
+      client.session.on("session_closed", clear);
+      signal.throwIfAborted();
+      const nodes = await discoverVariables(
+        client.session,
+        variables.map(({ path }) => path),
+      );
+      if (!nodes.size)
+        throw new Error(
+          "No declared PLC symbols are published. Check the downloaded program and OPC UA symbol configuration.",
+        );
+      options.log?.info(`Connected to the PLC (${nodes.size} symbols)`);
+      signal.throwIfAborted();
+      binding = { nodes, session: client.session };
+      while (!signal.aborted) {
+        const values = await readVariables(client.session, nodes, variables);
+        signal.throwIfAborted();
+        state = { connected: true, error: null, updatedAt: new Date().toISOString(), values };
+        await sleep(pollIntervalMs, signal);
+      }
+    } finally {
+      clear();
+      signal.removeEventListener("abort", clear);
+      // disconnect also closes active sessions and disposes the certificate manager.
+      await client.disconnect();
+    }
+  };
+
+  const run = async (signal: AbortSignal) => {
+    while (!signal.aborted) {
+      try {
+        await poll(signal);
+      } catch (error) {
+        if (signal.aborted) return;
+        const message = error instanceof Error ? error.message : "OPC UA connection failed";
+        if (state.error !== message)
+          options.log?.warn("PLC connection unavailable; retrying", error);
+        state = unavailableSnapshot(message);
+      }
+      await sleep(reconnectDelayMs, signal);
+    }
+  };
+
+  return {
+    run,
+    snapshot,
+    ...createVariableManager<Globals>({ getVariableSession: currentBinding }, variables),
+    /** Reads these published paths now instead of from the last poll; fails if the session changes meanwhile. */
+    read: async (paths: Iterable<string>) => {
+      const selected = new Set(paths);
+      const current = currentBinding();
+      const readings = await readVariables(
+        current.session,
+        current.nodes,
+        variables.filter(({ path }) => selected.has(path)),
+      );
+      if (binding !== current) throw new Error("PLC session changed during read");
+      return readings;
+    },
+    /** Writes published variables by path; fails with `VariableWriteError` if any write fails. */
+    write: async (values: ReadonlyMap<string, unknown>) => {
+      const current = currentBinding();
+      const byPath = new Map(variables.map((variable) => [variable.path, variable]));
+      return writeVariables(
+        current.session,
+        current.nodes,
+        [...values].map(([path, value]) => {
+          const variable = byPath.get(path);
+          if (!variable) throw new Error(`Unknown or unpublished PLC variable ${path}`);
+          return { variable, value };
+        }),
+      );
+    },
+    /** The current session; it changes on every reconnect. */
+    session: () => currentBinding().session,
+    /** Reads exposed read-only telemetry from the latest poll. */
+    machine: <const Definition extends MachineDefinition>(definition: Definition) =>
+      createMachineClient(definition, {
+        read: (paths) => {
+          const { values } = snapshot();
+          return paths.map((path) => {
+            const reading = values[path];
+            if (reading?.quality !== "good") throw new Error(`PLC telemetry unavailable: ${path}`);
+            return reading.value;
+          });
+        },
+      }),
+  };
+};
+
+export type Plc<Globals> = ReturnType<typeof createPlc<Globals>>;

package/src/snapshot.ts

@@ -0,0 +1,17 @@
+import type { Reading } from "./types";
+
+/** The latest poll of a PLC's published variables, keyed by symbol path. */
+export interface Snapshot {
+  connected: boolean;
+  error: string | null;
+  updatedAt: string | null;
+  values: Record<string, Reading>;
+}
+
+export const unavailableSnapshot = (error: string): Snapshot => ({
+  connected: false,
+  error,
+  updatedAt: null,
+  values: {},
+});
+export type { Reading };

package/src/types.ts

@@ -0,0 +1,10 @@
+export interface Variable {
+  path: string;
+  type: string;
+  field: string;
+}
+export interface Reading {
+  quality: "good" | "unavailable" | "bad";
+  status: string;
+  value: boolean | number | string | number[] | string[] | null;
+}

package/src/variable-manager.ts

@@ -0,0 +1,191 @@
+/**
+ * Typed access to whole PLC symbols (e.g. `LineIO.Conveyor_Inbound`).
+ *
+ * `get` reads every field of a symbol and assembles the generated ST shape.
+ * `set` takes a partial patch of that shape and writes only the given fields.
+ * Each symbol's fields are indexed once, at load, as a tree of structs/arrays.
+ */
+import type { Reading, Variable } from "./types";
+import { readVariables, type VariableSession, writeVariables } from "./variables";
+
+export type VariableName<PlcGlobals> = {
+  [G in keyof PlcGlobals & string]: `${G}.${Extract<keyof PlcGlobals[G], string>}`;
+}[keyof PlcGlobals & string];
+
+export type VariableValue<
+  PlcGlobals,
+  N extends VariableName<PlcGlobals>,
+> = N extends `${infer G extends keyof PlcGlobals & string}.${infer V}`
+  ? V extends keyof PlcGlobals[G]
+    ? PlcGlobals[G][V]
+    : never
+  : never;
+
+/** Struct arrays use zero-based index patches; primitive arrays are replaced whole. */
+export type VariablePatch<T> =
+  T extends Array<infer Item>
+    ? Item extends object
+      ? { readonly [index: number]: VariablePatch<Item> }
+      : ReadonlyArray<Item>
+    : T extends object
+      ? { [K in keyof T]?: VariablePatch<T[K]> }
+      : T;
+
+export interface VariableBinding {
+  nodes: ReadonlyMap<string, string>;
+  session: VariableSession;
+}
+
+export interface VariableConnection {
+  getVariableSession: () => VariableBinding;
+}
+
+interface Branch {
+  children: Map<string | number, Node>;
+  kind: "branch";
+}
+type Node = Branch | { kind: "leaf"; variable: Variable };
+
+const newBranch = (): Branch => ({ children: new Map(), kind: "branch" });
+
+/** Splits `Cards[1].Output.MotionAsserted` into `["Cards", 1, "Output", "MotionAsserted"]`. */
+const fieldKeys = (field: string) =>
+  (field.match(/[^.[\]]+|\[\d+\]/g) ?? []).map((part) =>
+    part.startsWith("[") ? Number(part.slice(1, -1)) : part,
+  );
+
+/**
+ * Indexes every contract variable under its symbol (e.g. `LineIO.Conveyor_Inbound`)
+ * as a tree of struct fields and array indexes, ending in leaf variables.
+ */
+const buildSchemas = (variables: readonly Variable[]) => {
+  const schemas = new Map<string, { root: Branch; fields: Array<Variable> }>();
+  for (const variable of variables) {
+    // Whole-array globals, such as service channels, are read by path rather than by symbol.
+    if (!variable.field) continue;
+    const name = variable.path.slice(0, -(variable.field.length + 1));
+    const schema = schemas.get(name) ?? { fields: [], root: newBranch() };
+    schemas.set(name, schema);
+    schema.fields.push(variable);
+
+    const keys = fieldKeys(variable.field);
+    const leafKey = keys.pop();
+    if (leafKey === undefined) {
+      throw new Error(`Empty PLC field: ${variable.path}`);
+    }
+    const parent = keys.reduce<Branch>((branch, key) => {
+      const child = branch.children.get(key) ?? newBranch();
+      if (child.kind !== "branch") {
+        throw new Error(`Conflicting PLC field: ${variable.path}`);
+      }
+      branch.children.set(key, child);
+      return child;
+    }, schema.root);
+    parent.children.set(leafKey, { kind: "leaf", variable });
+  }
+  return schemas;
+};
+
+const arrayKeys = (branch: Branch) =>
+  [...branch.children.keys()]
+    .filter((key): key is number => typeof key === "number")
+    .sort((a, b) => a - b);
+
+const assemble = (node: Node, readings: Record<string, Reading>): unknown => {
+  if (node.kind === "leaf") {
+    const reading = readings[node.variable.path];
+    if (reading?.quality !== "good" || reading.value === null) {
+      throw new Error(`Cannot read ${node.variable.path}: ${reading?.status ?? "Missing value"}`);
+    }
+    return reading.value;
+  }
+  const keys = arrayKeys(node);
+  if (keys.length) {
+    return keys.map((key) => {
+      const child = node.children.get(key);
+      if (!child) {
+        throw new Error(`Missing PLC array element: ${key}`);
+      }
+      return assemble(child, readings);
+    });
+  }
+  return Object.fromEntries(
+    [...node.children].map(([key, child]) => [key, assemble(child, readings)]),
+  );
+};
+
+const collectUpdates = (
+  node: Node,
+  patch: unknown,
+  path: string,
+): Array<{ variable: Variable; value: unknown }> => {
+  if (node.kind === "leaf") {
+    return [{ value: patch, variable: node.variable }];
+  }
+  if (
+    !patch ||
+    typeof patch !== "object" ||
+    (!Array.isArray(patch) &&
+      Object.getPrototypeOf(patch) !== Object.prototype &&
+      Object.getPrototypeOf(patch) !== null)
+  ) {
+    throw new Error(`Expected an object patch for ${path}`);
+  }
+  const keys = arrayKeys(node);
+  if (!keys.length && Array.isArray(patch)) {
+    throw new Error(`Expected a struct patch for ${path}`);
+  }
+  return Object.keys(patch).flatMap((key: string) => {
+    const value: unknown = Reflect.get(patch, key);
+    const index = Number(key);
+    const arrayKey =
+      keys.length && Number.isInteger(index) && index >= 0 && String(index) === key
+        ? keys[index]
+        : undefined;
+    const child = keys.length ? node.children.get(arrayKey ?? -1) : node.children.get(key);
+    if (!child) {
+      throw new Error(`Unknown PLC field or array index: ${path}.${key}`);
+    }
+    return collectUpdates(child, value, `${path}.${key}`);
+  });
+};
+
+/** Server-side API using the connection's current session and discovered node IDs. */
+export const createVariableManager = <PlcGlobals>(
+  connection: VariableConnection,
+  variables: readonly Variable[],
+) => {
+  const schemas = buildSchemas(variables);
+  const schemaFor = (name: string) => {
+    const schema = schemas.get(name);
+    if (!schema) {
+      throw new Error(`Unknown PLC variable: ${name}`);
+    }
+    return schema;
+  };
+
+  return {
+    async get<N extends VariableName<PlcGlobals>>(name: N): Promise<VariableValue<PlcGlobals, N>> {
+      const schema = schemaFor(name);
+      const binding = connection.getVariableSession();
+      const readings = await readVariables(binding.session, binding.nodes, schema.fields);
+      if (connection.getVariableSession() !== binding) {
+        throw new Error("PLC session changed during read");
+      }
+      // Every declared leaf is checked before returning the generated ST shape.
+      return assemble(schema.root, readings) as VariableValue<PlcGlobals, N>;
+    },
+    async set<N extends VariableName<PlcGlobals>>(
+      name: N,
+      patch: VariablePatch<VariableValue<PlcGlobals, NoInfer<N>>>,
+    ) {
+      const schema = schemaFor(name);
+      const updates = collectUpdates(schema.root, patch, name);
+      if (!updates.length) {
+        throw new Error(`Empty PLC patch: ${name}`);
+      }
+      const { session, nodes } = connection.getVariableSession();
+      return await writeVariables(session, nodes, updates);
+    },
+  };
+};