opcjs-client 0.1.18-alpha → 0.1.26-alpha

package/dist/index.d.cts

@@ -1,8 +1,19 @@
-import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, ILoggerFactory, Encoder, Decoder, ExpandedNodeId, QualifiedName, LocalizedText, NodeClassEnum } from 'opcjs-base';
+import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, ILoggerFactory, Encoder, Decoder, ExpandedNodeId, QualifiedName, LocalizedText, NodeClassEnum, UaPrimitive } from 'opcjs-base';
 
 declare abstract class ServiceBase {
     private authToken;
     protected secureChannel: ISecureChannel;
+    /**
+     * Validates the `serviceResult` value from a response header.
+     *
+     * Throws `SessionInvalidError` for session-related status codes so callers
+     * can detect a dropped session and act accordingly (e.g. reconnect).
+     * Throws a generic `Error` for all other non-Good codes.
+     *
+     * @param result  - The `serviceResult` value from the response header.
+     * @param context - Short description used in the error message (e.g. "ReadRequest").
+     */
+    protected checkServiceResult(result: number | undefined, context: string): void;
     protected createRequestHeader(): RequestHeader;
     constructor(authToken: NodeId, secureChannel: ISecureChannel);
 }
@@ -10,11 +21,19 @@ declare abstract class ServiceBase {
 declare class SessionService extends ServiceBase {
     private configuration;
     private logger;
+    /**
+     * Creates a new session on the server (OPC UA Part 4, Section 5.7.2).
+     * @returns The session ID, authentication token, and selected server endpoint.
+     */
     createSession(): Promise<{
         sessionId: number;
         authToken: NodeId;
         endpoint: EndpointDescription;
     }>;
+    /**
+     * Activates an existing session using the supplied identity token (OPC UA Part 4, Section 5.7.3).
+     * @param identityToken - User identity token (anonymous, username/password, certificate, or issued token).
+     */
     activateSession(identityToken: UserIdentityToken): Promise<void>;
     recreate(authToken: NodeId): SessionService;
     constructor(authToken: NodeId, secureChannel: ISecureChannel, configuration: Configuration);
@@ -70,8 +89,8 @@ declare class Session {
 
 declare class ReadValueResult {
     value: unknown;
-    status: string;
-    constructor(value: unknown, status: string);
+    statusCode: number;
+    constructor(value: unknown, statusCode: number);
 }
 
 declare class ConfigurationClient extends Configuration {
@@ -81,8 +100,8 @@ declare class ConfigurationClient extends Configuration {
 
 declare class CallMethodResult {
     values: unknown[];
-    status: string;
-    constructor(values: unknown[], status: string);
+    statusCode: number;
+    constructor(values: unknown[], statusCode: number);
 }
 
 declare class BrowseNodeResult {
@@ -96,116 +115,6 @@ declare class BrowseNodeResult {
     constructor(referenceTypeId: NodeId, isForward: boolean, nodeId: ExpandedNodeId, browseName: QualifiedName, displayName: LocalizedText, nodeClass: NodeClassEnum, typeDefinition: ExpandedNodeId);
 }
 
-/**
- * Enumeration of variant types based on BuiltinType NodeIds.
- */
-declare enum BuiltInType {
-    Null = 0,
-    Boolean = 1,
-    SByte = 2,
-    Byte = 3,
-    Int16 = 4,
-    UInt16 = 5,
-    Int32 = 6,
-    UInt32 = 7,
-    Int64 = 8,
-    UInt64 = 9,
-    Float = 10,
-    Double = 11,
-    String = 12,
-    DateTime = 13,
-    Guid = 14,
-    ByteString = 15,
-    XmlElement = 16,
-    NodeId = 17,
-    ExpandedNodeId = 18,
-    StatusCode = 19,
-    QualifiedName = 20,
-    LocalizedText = 21,
-    ExtensionObject = 22,
-    DataValue = 23,
-    Variant = 24,
-    DiagnosticInfo = 25
-}
-
-/**
- * OPC UA Primitive Type Mappings
- *
- * We try to use the JS built in types wherever we can. But sometimes, often in the context
- * where Variant is involved, we need to have a wrapper type that includes the BuiltInType
- * for type checking and encoding purposes. In those cases, we define a wrapper type with a
- * value and a type field. For simple cases like boolean, we can just use the native boolean
- * type directly as UaBoolean.
- * @module primitives
- */
-
-type UaBoolean = boolean;
-/**
- * OPC UA Builtin Type Numeric IDs
- *
- * These correspond to the NodeId numeric identifiers defined in OPC UA Part 6, Table 1.
- */
-type UaSbyte = {
-    value: number;
-    readonly type: BuiltInType.SByte;
-};
-type UaByte = {
-    value: number;
-    readonly type: BuiltInType.Byte;
-};
-type UaInt16 = {
-    value: number;
-    readonly type: BuiltInType.Int16;
-};
-type UaUint16 = {
-    value: number;
-    readonly type: BuiltInType.UInt16;
-};
-type UaInt32 = {
-    value: number;
-    readonly type: BuiltInType.Int32;
-};
-type UaUint32 = {
-    value: number;
-    readonly type: BuiltInType.UInt32;
-};
-type UaInt64 = {
-    value: bigint;
-    readonly type: BuiltInType.Int64;
-};
-type UaUint64 = {
-    value: bigint;
-    readonly type: BuiltInType.UInt64;
-};
-type UaFloat = {
-    value: number;
-    readonly type: BuiltInType.Float;
-};
-type UaDouble = {
-    value: number;
-    readonly type: BuiltInType.Double;
-};
-/**
- * OPC UA String primitive type.
- *
- * A String in OPC UA can be null (encoded as length -1 in binary).
- * Using `string | null` instead of `string | undefined` aligns with the
- * OPC UA specification where null is an explicit, valid value distinct
- * from an empty string. Same is true for ByteString which can be null (length -1)
- * or a Uint8Array.
- */
-type UaString = string | null;
-type UaByteString = Uint8Array | null;
-type UaGuid = {
-    value: string;
-    readonly type: BuiltInType.Guid;
-};
-type UaDateTime = Date;
-/**
- * Union of all OPC UA primitive types accepted by {@link Variant.newFrom}.
- */
-type UaPrimitive = UaBoolean | UaSbyte | UaByte | UaInt16 | UaUint16 | UaInt32 | UaUint32 | UaInt64 | UaUint64 | UaFloat | UaDouble | UaString | UaDateTime | UaGuid | UaByteString;
-
 declare class Client {
     private configuration;
     private identity;
@@ -216,7 +125,23 @@ declare class Client {
     private session?;
     private subscriptionHandler?;
     private logger;
+    private secureChannel?;
+    private sessionHandler?;
     getSession(): Session;
+    /**
+     * (Re-)initialises all session-scoped services from the current `this.session`.
+     * Called both after the initial `connect()` and after a session refresh.
+     */
+    private initServices;
+    /**
+     * Executes `fn` and, if it throws a `SessionInvalidError`, creates a fresh
+     * session and retries the operation exactly once.
+     *
+     * This covers the reactive case: a service call reveals that the server has
+     * already dropped the session (e.g. due to timeout). The new session is
+     * established transparently before re-running the original operation.
+     */
+    private withSessionRefresh;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     read(ids: NodeId[]): Promise<ReadValueResult[]>;
@@ -237,4 +162,20 @@ declare class Client {
     constructor(endpointUrl: string, configuration: ConfigurationClient, identity: UserIdentity);
 }
 
-export { BrowseNodeResult, Client, ConfigurationClient, UserIdentity };
+/**
+ * Thrown when the server signals that the current Session is no longer valid.
+ *
+ * Callers that want to react to a dropped session (e.g. by creating a new one
+ * and retrying the operation) should catch this specific error type instead of
+ * the generic `Error` class.
+ *
+ * Relevant OPC UA status codes:
+ *  - `BadSessionIdInvalid` (0x80250000) – session no longer exists on the server
+ *  - `BadSessionClosed`    (0x80260000) – session was closed explicitly
+ */
+declare class SessionInvalidError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number);
+}
+
+export { BrowseNodeResult, Client, ConfigurationClient, SessionInvalidError, UserIdentity };

package/dist/index.d.ts

@@ -1,8 +1,19 @@
-import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, ILoggerFactory, Encoder, Decoder, ExpandedNodeId, QualifiedName, LocalizedText, NodeClassEnum } from 'opcjs-base';
+import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, ILoggerFactory, Encoder, Decoder, ExpandedNodeId, QualifiedName, LocalizedText, NodeClassEnum, UaPrimitive } from 'opcjs-base';
 
 declare abstract class ServiceBase {
     private authToken;
     protected secureChannel: ISecureChannel;
+    /**
+     * Validates the `serviceResult` value from a response header.
+     *
+     * Throws `SessionInvalidError` for session-related status codes so callers
+     * can detect a dropped session and act accordingly (e.g. reconnect).
+     * Throws a generic `Error` for all other non-Good codes.
+     *
+     * @param result  - The `serviceResult` value from the response header.
+     * @param context - Short description used in the error message (e.g. "ReadRequest").
+     */
+    protected checkServiceResult(result: number | undefined, context: string): void;
     protected createRequestHeader(): RequestHeader;
     constructor(authToken: NodeId, secureChannel: ISecureChannel);
 }
@@ -10,11 +21,19 @@ declare abstract class ServiceBase {
 declare class SessionService extends ServiceBase {
     private configuration;
     private logger;
+    /**
+     * Creates a new session on the server (OPC UA Part 4, Section 5.7.2).
+     * @returns The session ID, authentication token, and selected server endpoint.
+     */
     createSession(): Promise<{
         sessionId: number;
         authToken: NodeId;
         endpoint: EndpointDescription;
     }>;
+    /**
+     * Activates an existing session using the supplied identity token (OPC UA Part 4, Section 5.7.3).
+     * @param identityToken - User identity token (anonymous, username/password, certificate, or issued token).
+     */
     activateSession(identityToken: UserIdentityToken): Promise<void>;
     recreate(authToken: NodeId): SessionService;
     constructor(authToken: NodeId, secureChannel: ISecureChannel, configuration: Configuration);
@@ -70,8 +89,8 @@ declare class Session {
 
 declare class ReadValueResult {
     value: unknown;
-    status: string;
-    constructor(value: unknown, status: string);
+    statusCode: number;
+    constructor(value: unknown, statusCode: number);
 }
 
 declare class ConfigurationClient extends Configuration {
@@ -81,8 +100,8 @@ declare class ConfigurationClient extends Configuration {
 
 declare class CallMethodResult {
     values: unknown[];
-    status: string;
-    constructor(values: unknown[], status: string);
+    statusCode: number;
+    constructor(values: unknown[], statusCode: number);
 }
 
 declare class BrowseNodeResult {
@@ -96,116 +115,6 @@ declare class BrowseNodeResult {
     constructor(referenceTypeId: NodeId, isForward: boolean, nodeId: ExpandedNodeId, browseName: QualifiedName, displayName: LocalizedText, nodeClass: NodeClassEnum, typeDefinition: ExpandedNodeId);
 }
 
-/**
- * Enumeration of variant types based on BuiltinType NodeIds.
- */
-declare enum BuiltInType {
-    Null = 0,
-    Boolean = 1,
-    SByte = 2,
-    Byte = 3,
-    Int16 = 4,
-    UInt16 = 5,
-    Int32 = 6,
-    UInt32 = 7,
-    Int64 = 8,
-    UInt64 = 9,
-    Float = 10,
-    Double = 11,
-    String = 12,
-    DateTime = 13,
-    Guid = 14,
-    ByteString = 15,
-    XmlElement = 16,
-    NodeId = 17,
-    ExpandedNodeId = 18,
-    StatusCode = 19,
-    QualifiedName = 20,
-    LocalizedText = 21,
-    ExtensionObject = 22,
-    DataValue = 23,
-    Variant = 24,
-    DiagnosticInfo = 25
-}
-
-/**
- * OPC UA Primitive Type Mappings
- *
- * We try to use the JS built in types wherever we can. But sometimes, often in the context
- * where Variant is involved, we need to have a wrapper type that includes the BuiltInType
- * for type checking and encoding purposes. In those cases, we define a wrapper type with a
- * value and a type field. For simple cases like boolean, we can just use the native boolean
- * type directly as UaBoolean.
- * @module primitives
- */
-
-type UaBoolean = boolean;
-/**
- * OPC UA Builtin Type Numeric IDs
- *
- * These correspond to the NodeId numeric identifiers defined in OPC UA Part 6, Table 1.
- */
-type UaSbyte = {
-    value: number;
-    readonly type: BuiltInType.SByte;
-};
-type UaByte = {
-    value: number;
-    readonly type: BuiltInType.Byte;
-};
-type UaInt16 = {
-    value: number;
-    readonly type: BuiltInType.Int16;
-};
-type UaUint16 = {
-    value: number;
-    readonly type: BuiltInType.UInt16;
-};
-type UaInt32 = {
-    value: number;
-    readonly type: BuiltInType.Int32;
-};
-type UaUint32 = {
-    value: number;
-    readonly type: BuiltInType.UInt32;
-};
-type UaInt64 = {
-    value: bigint;
-    readonly type: BuiltInType.Int64;
-};
-type UaUint64 = {
-    value: bigint;
-    readonly type: BuiltInType.UInt64;
-};
-type UaFloat = {
-    value: number;
-    readonly type: BuiltInType.Float;
-};
-type UaDouble = {
-    value: number;
-    readonly type: BuiltInType.Double;
-};
-/**
- * OPC UA String primitive type.
- *
- * A String in OPC UA can be null (encoded as length -1 in binary).
- * Using `string | null` instead of `string | undefined` aligns with the
- * OPC UA specification where null is an explicit, valid value distinct
- * from an empty string. Same is true for ByteString which can be null (length -1)
- * or a Uint8Array.
- */
-type UaString = string | null;
-type UaByteString = Uint8Array | null;
-type UaGuid = {
-    value: string;
-    readonly type: BuiltInType.Guid;
-};
-type UaDateTime = Date;
-/**
- * Union of all OPC UA primitive types accepted by {@link Variant.newFrom}.
- */
-type UaPrimitive = UaBoolean | UaSbyte | UaByte | UaInt16 | UaUint16 | UaInt32 | UaUint32 | UaInt64 | UaUint64 | UaFloat | UaDouble | UaString | UaDateTime | UaGuid | UaByteString;
-
 declare class Client {
     private configuration;
     private identity;
@@ -216,7 +125,23 @@ declare class Client {
     private session?;
     private subscriptionHandler?;
     private logger;
+    private secureChannel?;
+    private sessionHandler?;
     getSession(): Session;
+    /**
+     * (Re-)initialises all session-scoped services from the current `this.session`.
+     * Called both after the initial `connect()` and after a session refresh.
+     */
+    private initServices;
+    /**
+     * Executes `fn` and, if it throws a `SessionInvalidError`, creates a fresh
+     * session and retries the operation exactly once.
+     *
+     * This covers the reactive case: a service call reveals that the server has
+     * already dropped the session (e.g. due to timeout). The new session is
+     * established transparently before re-running the original operation.
+     */
+    private withSessionRefresh;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     read(ids: NodeId[]): Promise<ReadValueResult[]>;
@@ -237,4 +162,20 @@ declare class Client {
     constructor(endpointUrl: string, configuration: ConfigurationClient, identity: UserIdentity);
 }
 
-export { BrowseNodeResult, Client, ConfigurationClient, UserIdentity };
+/**
+ * Thrown when the server signals that the current Session is no longer valid.
+ *
+ * Callers that want to react to a dropped session (e.g. by creating a new one
+ * and retrying the operation) should catch this specific error type instead of
+ * the generic `Error` class.
+ *
+ * Relevant OPC UA status codes:
+ *  - `BadSessionIdInvalid` (0x80250000) – session no longer exists on the server
+ *  - `BadSessionClosed`    (0x80260000) – session was closed explicitly
+ */
+declare class SessionInvalidError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number);
+}
+
+export { BrowseNodeResult, Client, ConfigurationClient, SessionInvalidError, UserIdentity };