ads-client 2.0.0-beta.2 → 2.0.0-beta.3

package/dist/types/ads-client-types.d.ts

@@ -1,75 +1,182 @@
 import ClientError from "../client-error";
 import { AdsDataType, AdsDeviceInfo, AdsRawAddress, AdsResponse, AdsState, AdsSymbol, AmsAddress, AmsRouterState, AmsTcpPacket, BaseAdsResponse } from "./ads-protocol-types";
+/**
+ * Possible debug levels
+ *
+ * @category Types
+ */
 export type DebugLevel = 0 | 1 | 2 | 3;
 /**
  * Events for the client, for example `client.on('connect', ...)`
+ *
+ * @category Types
  */
-export interface ClientEvents {
+export interface AdsClientEvents {
     /**
-     * Emitted when client has connected to the target
+     * Emitted when the client has connected to the target.
      *
+     * **Parameters:**
      * - `connection`: Active connection information
+     *
+     * @example
+     * ```js
+     * client.on('connect', (connection) => {
+     *  console.log('Connected:', connection);
+     * });
+     * ```
      */
     'connect': [connection: AdsClientConnection];
     /**
-     * Emitted when client has disconnected from the target
+     * Emitted when the client has disconnected from the target.
      *
+     * **Parameters:**
      * - `isReconnecting`: True if disconnect happened during reconnecting
+     *
+     * @example
+     * ```js
+     * client.on('disconnect', (isReconnecting) => {
+     *  console.log('Disconnected - is reconnecting:', isReconnecting);
+     * });
+     * ```
      */
     'disconnect': [isReconnecting: boolean];
     /**
-     * Emitted when client has reconnected to the target after a disconnection
+     * Emitted when the client has reconnected to the target after a disconnection.
      *
+     * **Parameters:**
      * - `allSubscriptionsRestored`: True if all subscriptions were restored successfully
      * - `unrestoredSubscriptions`: Array of subscription paths that failed to be restored
+     *
+     * @example
+     * ```js
+     * client.on('reconnect', (allSubscriptionsRestored, unrestoredSubscriptions) => {
+     *  if(allSubscriptionsRestored) {
+     *    console.log('Reconnected and all subscriptions restored');
+     *  } else {
+     *    console.log('Reconnected but following subscriptions were not restored:', unrestoredSubscriptions);
+     *  }
+     * });
+     * ```
      */
     'reconnect': [allSubscriptionsRestored: boolean, unrestoredSubscriptions: string[]];
     /**
-     * Emitted when client has lost the connection to the target
+     * Emitted when the client has lost the connection to the target.
      *
+     * **Parameters:**
      * - `socketFailure`: True if connection was lost due to a socket/tcp problem
+     *
+     * @example
+     * ```js
+     * client.on('connectionLost', (socketFailure) => {
+     *  console.log('Connection to the target was lost. TCP socket failure:', socketFailure);
+     * });
+     * ```
      */
     'connectionLost': [socketFailure: boolean];
     /**
-     * Emitted when PLC runtime symbol version has changed
+     * Emitted when the target PLC runtime symbol version has changed.
      *
+     * **Parameters:**
      * - `version`: New PLC runtime symbol version
      * - `previousVersion`: Previous PLC runtime symbol version (if known)
+     *
+     * @example
+     * ```js
+     * client.on('plcSymbolVersionChange', (version, previousVersion) => {
+     *  console.log(`Target PLC runtime symbol version changed from ${previousVersion} to ${version}`);
+     * });
+     * ```
      */
     'plcSymbolVersionChange': [version: number, previousVersion?: number];
     /**
-     * Emitted when PLC runtime state has changed
+     * Emitted when the target PLC runtime state has changed
      *
+     * **Parameters:**
      * - `state`: New PLC runtime state
      * - `previousState`: Previous PLC runtime state (if known)
+     *
+     * @example
+     * ```js
+     * client.on('plcRuntimeStateChange', (state, previousState) => {
+     *  console.log(`Target PLC state has changed from ${previousState} to ${state}`);
+     * });
+     * ```
      */
     'plcRuntimeStateChange': [state: AdsState, previousState?: AdsState];
     /**
-     * Emitted when TwinCAT system state has changed
+     * Emitted when the target TwinCAT system state has changed.
      *
+     * **Parameters:**
      * - `state`: New TwinCAT system state
      * - `previousState`: Previous TwinCAT system state (if known)
+     *
+     * @example
+     * ```js
+     * client.on('tcSystemStateChange', (state, previousState) => {
+     *  console.log(`Target TwinCAT system state has changed from ${previousState} to ${state}`);
+     * });
+     * ```
      */
     'tcSystemStateChange': [state: AdsState, previousState?: AdsState];
     /**
-     * Emitted when AMS router state has changed
+     * Emitted when the AMS router state has changed.
      *
+     * **Parameters:**
      * - `state`: New AMS router state
      * - `previousState`: Previous AMS router state (if known)
+     *
+     * @example
+     * ```js
+     * client.on('routerStateChange', (state, previousState) => {
+     *  console.log(`TwinCAT AMS router state has changed from ${previousState} to ${state}`);
+     * });
+     * ```
      */
     'routerStateChange': [state: AmsRouterState, previousState?: AmsRouterState];
     /**
-     * Emitted when the client has had an error, such as
-     *  - unknown ADS notification received
-     *  - handling ADS notification failed
-     *  - unknown ADS command received
+     * Emitted when the client has had an error, such as:
      *
+     * - handling received ADS notification failed
+     * - unknown ADS command received
+     *
+     * **Parameters:**
      * - `error`: Error that was thrown
+     *
+     * @example
+     * ```js
+     * client.on('client-error'', (error) => {
+     *  console.log('Error occured:', error);
+     * });
+     * ```
      */
     'client-error': [error: ClientError];
+    /**
+     * Emitted when the client encounters a non-critical abnormal event, such as:
+     *
+     * - connected to a non-running TwinCAT system
+     * - re-connection attempted after connection loss
+     * - lost connection re-established
+     * - unknown ADS notification received
+     *
+     * As default, the client writes these warnings to the console unless `settings.hideConsoleWarnings` is set.
+     * The setting does not disable the `warning` event.
+     *
+     * **Parameters:**
+     * - `message`: Warning message
+     *
+     * @example
+     * ```js
+     * client.on('warning', (message) => {
+     *  console.log('WARNING:', message);
+     * });
+     * ```
+     */
+    'warning': [message: string];
 }
 /**
  * Client settings
+ *
+ * @category Types
  */
 export interface AdsClientSettings {
     /**
@@ -226,9 +333,15 @@ export interface AdsClientSettings {
     /**
      * **Optional**: If set, no warnings are written to console using `console.log()` (default: `false`)
      *
-     * As default, the client writes some warnings to console, such as connection loss and reconnection information.
+     * As default, the client writes warnings to the console, such as
+     * - connected to a non-running TwinCAT system
+     * - re-connection attempted after connection loss
+     * - lost connection re-established
+     * - unknown ADS notification received
+     *
+     * The exact same warnings are emitted using the `warning` event. See {@link AdsClientEvents}.
      *
-     * If set, the client **never** writes anything to console.
+     * If this setting is set, the client never writes anything to the console.
      */
     hideConsoleWarnings?: boolean;
     /**
@@ -275,9 +388,23 @@ export interface AdsClientSettings {
      * As default, the client caches the results after reading them from the target.
      */
     disableCaching?: boolean;
+    /**
+     * **Optional**: If set, the client automatically deletes ADS notifications for unknown subscriptions (default: `true`).
+     *
+     * Otherwise, when a notification for an unknown subscription is received, the client will emit a warning.
+     *
+     * Unknown subscriptions can occur, if a previous subscription wasn't unsubscribed (using the `unsubscribe()` method)
+     * and the target keeps sending notifications.
+     *
+     * As default, the client automatically deletes unknown subscriptions on the PLC to conserve resources.
+     * A warning will be emitted when an unknown subscription is deleted.
+     */
+    deleteUnknownSubscriptions?: boolean;
 }
 /**
  * Internal timer object to keep the timer state saved
+ *
+ * @category Types
  */
 export interface TimerObject {
     /** Timer ID */
@@ -287,6 +414,8 @@ export interface TimerObject {
 }
 /**
  * Active client connection
+ *
+ * @category Types
  */
 export interface AdsClientConnection {
     /** Connection status of the client, true if connected */
@@ -306,6 +435,8 @@ export interface AdsClientConnection {
  * Object containing all active subscriptions for each target address
  *
  * Target address (`amsNetId:port`) is used as a key
+ *
+ * @category Types
  */
 export interface ActiveSubscriptionContainer {
     [K: string]: TargetActiveSubscriptionContainer;
@@ -314,12 +445,16 @@ export interface ActiveSubscriptionContainer {
  * Object containing all active subscriptions for each notification handle (for one target)
  *
  * Notification handle is used as a key
+ *
+ * @category Types
  */
 export interface TargetActiveSubscriptionContainer {
     [K: number]: ActiveSubscription;
 }
 /**
  * Object containing information for a single active subscription
+ *
+ * @category Types
  */
 export interface ActiveSubscription<T = any> {
     /** Settings for this subscription */
@@ -343,6 +478,8 @@ export interface ActiveSubscription<T = any> {
 }
 /**
  * Subscription data (value and timestamp)
+ *
+ * @category Types
  */
 export interface SubscriptionData<T = any> {
     timestamp: Date;
@@ -352,6 +489,8 @@ export interface SubscriptionData<T = any> {
  * Object containing all active ADS requests that are waiting for responses
  *
  * Invoke ID is used as a key
+ *
+ * @category Types
  */
 export interface ActiveAdsRequestContainer {
     [K: number]: ActiveAdsRequest;
@@ -359,6 +498,8 @@ export interface ActiveAdsRequestContainer {
 /**
  * Active ADS command that is waiting for answer
  * Callback is called when response is received
+ *
+ * @category Types
  */
 export interface ActiveAdsRequest {
     timeoutTimerHandle?: NodeJS.Timeout;
@@ -366,6 +507,8 @@ export interface ActiveAdsRequest {
 }
 /**
  * Client connection metadata
+ *
+ * @category Types
  */
 export interface ConnectionMetaData {
     /** Local AMS router state (if available) */
@@ -393,6 +536,8 @@ export interface ConnectionMetaData {
  * PLC runtime upload info
  *
  * Contains information about symbols and data types
+ *
+ * @category Types
  */
 export interface AdsUploadInfo {
     /** Number of symbols in the target runtime */
@@ -410,18 +555,24 @@ export interface AdsUploadInfo {
 }
 /**
  * Object containing PLC runtime symbol information objects
+ *
+ * @category Types
  */
 export interface AdsSymbolContainer {
     [K: string]: AdsSymbol;
 }
 /**
  * Object containing PLC runtime data type objects
+ *
+ * @category Types
  */
 export interface AdsDataTypeContainer {
     [K: string]: AdsDataType;
 }
 /**
  * ADS command
+ *
+ * @category Types
  */
 export interface AdsCommandToSend {
     /** Ads command (see `ADS.ADS_COMMAND`)*/
@@ -440,10 +591,14 @@ export interface AdsCommandToSend {
  *
  * @param data - The data received
  * @param subscription - The active subscription object
+ *
+ * @category Types
  */
 export type SubscriptionCallback<T = any> = (data: SubscriptionData<T>, subscription: ActiveSubscription<T>) => void;
 /**
  * Settings for a subscription
+ *
+ * @category Types
  */
 export interface SubscriptionSettings<T = any> {
     /**
@@ -486,12 +641,16 @@ export interface SubscriptionSettings<T = any> {
 }
 /**
  * PLC primitive types (not structs, function blocks etc.)
+ *
+ * @category Types
  */
 export type PlcPrimitiveType = string | boolean | number | Buffer | Date | BigInt;
 /**
  * Return value of `readValue()` and `readValueBySymbol()`
  *
  * @template T - Type of the value
+ *
+ * @category Types
  */
 export interface ReadValueResult<T = any> {
     /** Value of the symbol as converted Javascript object */
@@ -505,6 +664,8 @@ export interface ReadValueResult<T = any> {
 }
 /**
  * Return value of `writeValue()` and `writeValueBySymbol()`
+ *
+ * @category Types
  */
 export interface WriteValueResult<T = any> {
     /** Value of the symbol as converted Javascript object */
@@ -518,6 +679,8 @@ export interface WriteValueResult<T = any> {
 }
 /**
  * Return value of `convertObjectToBuffer()`
+ *
+ * @category Types
  */
 export interface ObjectToBufferConversionResult {
     /** Converted raw value */
@@ -527,6 +690,8 @@ export interface ObjectToBufferConversionResult {
 }
 /**
  * Variable handle object created using `createVariableHandle()` or `createVariableHandleMulti()`
+ *
+ * @category Types
  */
 export interface VariableHandle {
     /** Handle number */
@@ -543,6 +708,8 @@ export interface VariableHandle {
  *
  * @template T The type of method return value
  * @template U The type of method outputs
+ *
+ * @category Types
  */
 export interface RpcMethodCallResult<T = any, U = Record<string, any>> {
     /** Method return value (if any - `undefined` if none) */
@@ -552,11 +719,15 @@ export interface RpcMethodCallResult<T = any, U = Record<string, any>> {
 }
 /**
  * Parameter containing all read commands for `readRawMulti()`
+ *
+ * @category Types
  */
 export interface ReadRawMultiCommand extends Required<AdsRawAddress> {
 }
 /**
  * Return value of `readRawMulti()`
+ *
+ * @category Types
  */
 export interface ReadRawMultiResult extends BaseAdsResponse {
     /** Command */
@@ -568,6 +739,8 @@ export interface ReadRawMultiResult extends BaseAdsResponse {
 }
 /**
  * Parameter containing all write commands for `writeRawMulti()`
+ *
+ * @category Types
  */
 export interface WriteRawMultiCommand extends AdsRawAddress {
     /** Value to write */
@@ -577,6 +750,8 @@ export interface WriteRawMultiCommand extends AdsRawAddress {
 }
 /**
  * Return value of `writeRawMulti()`
+ *
+ * @category Types
  */
 export interface WriteRawMultiResult extends BaseAdsResponse {
     /** Command */
@@ -586,6 +761,8 @@ export interface WriteRawMultiResult extends BaseAdsResponse {
 }
 /**
  * Return value of `createVariableHandleMulti()`
+ *
+ * @category Types
  */
 export interface CreateVariableHandleMultiResult extends BaseAdsResponse {
     /** Full variable path in the PLC (such as `GVL_Test.ExampleStruct`) */
@@ -597,6 +774,8 @@ export interface CreateVariableHandleMultiResult extends BaseAdsResponse {
 }
 /**
  * Return value of `deleteVariableHandleMulti()`
+ *
+ * @category Types
  */
 export interface DeleteVariableHandleMultiResult extends BaseAdsResponse {
     /** Variable handle */
@@ -606,15 +785,19 @@ export interface DeleteVariableHandleMultiResult extends BaseAdsResponse {
 }
 /**
  * Parameter containing all read/write commands for `readWriteRawMulti()`
+ *
+ * @category Types
  */
 export interface ReadWriteRawMultiCommand extends Required<AdsRawAddress> {
-    /** Data to write */
-    writeData: Buffer;
+    /** Value to write */
+    value: Buffer;
     /** How many bytes to read */
     size: number;
 }
 /**
  * Return value of `readWriteRawMulti()`
+ *
+ * @category Types
  */
 export interface ReadWriteRawMultiResult extends BaseAdsResponse {
     /** Command */

package/dist/types/ads-client-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"ads-client-types.js","sourceRoot":"","sources":["../../src/types/ads-client-types.ts"],"names":[],"mappings":";;AAqZC,CAAC;AA0BD,CAAC"}
+{"version":3,"file":"ads-client-types.js","sourceRoot":"","sources":["../../src/types/ads-client-types.ts"],"names":[],"mappings":";;AAoiBC,CAAC;AA4BD,CAAC"}