@2702rebels/ntcore 1.0.0

package/src/NT4Spec.ts

@@ -0,0 +1,291 @@
+import type { SubscriptionOptions, TopicProperties } from "./NT4Types";
+
+/**
+ * Network constants.
+ */
+export const NetworkSpecs = {
+  /** NT4 port for unsecure (ws://) connections */
+  portUnsecure: 5810,
+
+  /** NT4 port for secure (wss://) connections */
+  portSecure: 5811,
+
+  /** Subprotocol v4.1 */
+  protocol41: "v4.1.networktables.first.wpi.edu",
+
+  /** Subprotocol v4.0 */
+  protocol40: "networktables.first.wpi.edu",
+
+  /** Subprotocol RTT */
+  protocolRTT: "rtt.networktables.first.wpi.edu",
+
+  /** v4.0 ping period in milliseconds */
+  pingPeriod40: 1000,
+
+  /** v4.0 ping timeout in milliseconds */
+  pingTimeout40: 3000,
+
+  /** v4.1 ping period in milliseconds */
+  pingPeriod41: 250,
+
+  /** v4.1 ping timeout in milliseconds */
+  pingTimeout41: 1000,
+};
+
+/**
+ * Supported data types mapped to protocol identifiers.
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#supported-data-types
+ */
+export const DataTypeCodes = {
+  boolean: 0,
+  double: 1,
+  int: 2,
+  float: 3,
+  string: 4,
+  json: 4,
+  raw: 5,
+  rpc: 5,
+  msgpack: 5,
+  protobuf: 5,
+  "boolean[]": 16,
+  "double[]": 17,
+  "int[]": 18,
+  "float[]": 19,
+  "string[]": 20,
+} as const;
+
+export type DataType = keyof typeof DataTypeCodes;
+
+/**
+ * Publish Request Message (`publish`)
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#publish-request-message-publish
+ */
+export type PublishRequestMessage = {
+  /**
+   * **Publish name**
+   *
+   * The topic name being published.
+   */
+  name: string;
+
+  /**
+   * **Published UID**
+   *
+   * A client-generated unique identifier for this publisher. Use the same UID later to unpublish.
+   * This is also the identifier that the client will use in MessagePack messages for this topic.
+   */
+  pubuid: number;
+
+  /**
+   * **Type of data**
+   *
+   * The requested data type (as a string).
+   * If the topic is newly created (e.g. there are no other publishers) this sets the value type.
+   * If the topic was previously published, this is ignored.
+   */
+  type: string;
+
+  /**
+   * **Properties**
+   *
+   * Initial topic properties.
+   * If the topic is newly created (e.g. there are no other publishers) this sets the topic properties.
+   * If the topic was previously published, this is ignored.
+   */
+  properties: TopicProperties;
+};
+
+/**
+ * Publish Release Message (`unpublish`)
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#publish-release-message-unpublish
+ */
+export type PublishReleaseMessage = {
+  /**
+   * **Publisher UID**
+   *
+   * The same unique identifier passed to the `publish` message.
+   */
+  pubuid: number;
+};
+
+/**
+ * Set Properties Message (`setproperties`)
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#set-properties-message-setproperties
+ */
+export type SetPropertiesMessage = {
+  /**
+   * **Topic name**
+   */
+  name: string;
+
+  /**
+   * **Properties to update**
+   */
+  update: TopicProperties;
+};
+
+/**
+ * Subscribe Message (`subscribe`)
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#subscribe-message-subscribe
+ */
+export type SubscribeMessage = {
+  /**
+   * **Array of topic names or prefixes**
+   *
+   * One or more topic names or prefixes (if the `prefix` option is true) to start receiving messages for.
+   */
+  topics: Array<string>;
+
+  /**
+   * **Subscription UID**
+   *
+   * A client-generated unique identifier for this subscription. Use the same UID later to unsubscribe.
+   */
+  subuid: number;
+
+  /**
+   * **Options**
+   */
+  options: SubscriptionOptions;
+};
+
+/**
+ * Unsubscribe Message (`unsubscribe`)
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#unsubscribe-message-unsubscribe
+ */
+export type UnsubscribeMessage = {
+  /**
+   * **Subscription UID**
+   *
+   * The same unique identifier passed to the `subscribe` message.
+   */
+  subuid: number;
+};
+
+/**
+ * Topic Announcement Message (`announce`)
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#topic-announcement-message-announce
+ */
+export type TopicAnnouncementMessage = {
+  /**
+   * **Topic name**
+   */
+  name: string;
+
+  /**
+   * **Topic ID**
+   *
+   * The identifier that the server will use in MessagePack messages for this topic.
+   */
+  id: number;
+
+  /**
+   * **Data type**
+   *
+   * The data type for the topic (as a string).
+   */
+  type: string;
+
+  /**
+   * **Publisher UID**
+   *
+   * If this message was sent in response to a publish message,
+   * the Publisher UID provided in that message. Otherwise absent.
+   */
+  pubuid?: number;
+
+  /**
+   * **Properties**
+   */
+  properties: TopicProperties;
+};
+
+/**
+ * Topic Removed Message (`unannounce`)
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#topic-removed-message-unannounce
+ */
+export type TopicRemovedMessage = {
+  /**
+   * **Topic name**
+   */
+  name: string;
+
+  /**
+   * **Topic ID**
+   *
+   * The identifier that the server was using for value updates.
+   */
+  id: number;
+};
+
+/**
+ * Properties Update Message (`properties`)
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#properties-update-message-properties
+ */
+export type PropertiesUpdateMessage = {
+  /**
+   * **Topic name**
+   */
+  name: string;
+
+  /**
+   * **Acknowledgement**
+   *
+   * `True` if this message is in response to a `setproperties` message from the same client.
+   * Otherwise absent.
+   */
+  ack: boolean;
+
+  /**
+   * **Properties to set**
+   */
+  update: TopicProperties;
+};
+
+/**
+ * Supported text data frames.
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#text-data-frames
+ */
+export type TextDataFrame =
+  | {
+      method: "publish";
+      params: PublishRequestMessage;
+    }
+  | {
+      method: "unpublish";
+      params: PublishReleaseMessage;
+    }
+  | {
+      method: "setproperties";
+      params: SetPropertiesMessage;
+    }
+  | {
+      method: "subscribe";
+      params: SubscribeMessage;
+    }
+  | {
+      method: "unsubscribe";
+      params: UnsubscribeMessage;
+    }
+  | {
+      method: "announce";
+      params: TopicAnnouncementMessage;
+    }
+  | {
+      method: "unannounce";
+      params: TopicRemovedMessage;
+    }
+  | {
+      method: "properties";
+      params: PropertiesUpdateMessage;
+    };

package/src/NT4Subscription.ts

@@ -0,0 +1,19 @@
+import type { SubscriptionOptions } from "./NT4Types";
+
+/** Contains information about NT4 subscription. */
+export class NT4Subscription {
+  /** Subscription UID. */
+  public readonly uid: number;
+
+  /** Subscription options. */
+  public readonly options: SubscriptionOptions;
+
+  /** Subscribed topic names or prefixes. */
+  public readonly topics: Set<string>;
+
+  constructor(uid: number, topics: Iterable<string>, options?: SubscriptionOptions) {
+    this.uid = uid;
+    this.topics = new Set(typeof topics === "string" ? [topics] : topics);
+    this.options = options ?? {};
+  }
+}

package/src/NT4Topic.ts

@@ -0,0 +1,74 @@
+import { DataTypeCodes } from "./NT4Spec";
+
+import type { DataType } from "./NT4Spec";
+import type { TopicProperties } from "./NT4Types";
+
+/** Contains information about NT4 topic. */
+export class NT4Topic {
+  /** Topic UID. */
+  public readonly uid: number;
+
+  /** Topic name. */
+  public readonly name: string;
+
+  /** Topic data type. */
+  public readonly type: string;
+
+  /** Topic properties. */
+  public readonly properties: TopicProperties;
+
+  /** Publisher UID. */
+  public pubuid?: number;
+
+  /** Last retained value. */
+  public retainedValue?: unknown;
+
+  /** Timestamp of {@link retainedValue}. */
+  public retainedTimestamp?: number;
+
+  constructor(uid: number, name: string, type: string, properties?: TopicProperties, pubuid?: number) {
+    this.uid = uid;
+    this.name = name;
+    this.type = type;
+    this.properties = properties ?? {};
+    this.pubuid = pubuid;
+    this.typeCode = DataTypeCodes[type as DataType] ?? 5; // defaults to binary
+  }
+
+  /** Merges properties with this topic. */
+  public mergeProperties(properties: TopicProperties) {
+    Object.entries(properties).forEach(([key, value]) => {
+      if (value === null) {
+        delete this.properties[key];
+      } else {
+        this.properties[key] = value;
+      }
+    });
+  }
+
+  /** Updates retained value if the incoming timestamp is newer (greater-than or equal-to). */
+  public updateRetainedValue(value: unknown, timestamp: number) {
+    if (this.retainedTimestamp == null || timestamp >= this.retainedTimestamp) {
+      this.retainedValue = value;
+      this.retainedTimestamp = timestamp;
+    }
+  }
+
+  /** Removes retained value except for "weak" default value. */
+  public removeRetainedValue() {
+    if (this.retainedTimestamp != 0) {
+      this.retainedValue = undefined;
+      this.retainedTimestamp = undefined;
+    }
+  }
+
+  /** Resets retained value timestamp except for "weak" default value. */
+  public resetRetainedTimestamp() {
+    if (this.retainedTimestamp != null && this.retainedTimestamp > 1) {
+      this.retainedTimestamp = 1;
+    }
+  }
+
+  /** Topic type code. For internal use only. */
+  public readonly typeCode: number;
+}

package/src/NT4Types.ts

@@ -0,0 +1,70 @@
+/**
+ * Topic properties, including well-known properties
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#properties
+ */
+export type TopicProperties = Record<string, unknown> & {
+  /**
+   * **Persistent flag**
+   *
+   * If `true`, the last set value will be periodically saved to persistent storage on the server
+   * and be restored during server startup. Topics with this property set to `true` will not
+   * be deleted by the server when the last publisher stops publishing.
+   */
+  persistent?: boolean;
+
+  /**
+   * **Retained flag**
+   *
+   * Topics with this property set to `true` will not be deleted by the server when
+   * the last publisher stops publishing.
+   */
+  retained?: boolean;
+
+  /**
+   * **Cached flag**
+   *
+   * If `false`, the server and clients will not store the value of the topic.
+   * This means that only value updates will be available for the topic.
+   */
+  cached?: boolean;
+};
+
+/**
+ * Subscription options, including well-known options
+ */
+export type SubscriptionOptions = Record<string, unknown> & {
+  /**
+   * **Periodic sweep time (in seconds)**
+   *
+   * How frequently the server should send changes. The server may send more frequently than this
+   * (e.g. use a combined minimum period for all values) or apply a restricted range to this value
+   * The default if unspecified is 100 ms (same as NT 3.0).
+   */
+  periodic?: number;
+
+  /**
+   * **All changes flag**
+   *
+   * If `true`, the server should send all value changes over the wire. If `false`, only
+   * the most recent value is sent (same as NT 3.0 behavior). If not specified, defaults to `false`.
+   */
+  all?: boolean;
+
+  /**
+   * **No value changes flag**
+   *
+   * If `true`, the server should not send any value changes over the wire regardless of other options.
+   * This is useful for only getting topic announcements. If `false`, value changes are sent in accordance
+   * with other options. If not specified, defaults to `false`.
+   */
+  topicsonly?: boolean;
+
+  /**
+   * **Prefix flag**
+   *
+   * If `true`, any topic starting with the name in the subscription topics list is subscribed to,
+   * not just exact matches. If not specified, defaults to `false`.
+   */
+  prefix?: boolean;
+};

package/src/NT4WebSocketAsync.ts

@@ -0,0 +1,145 @@
+import { NetworkSpecs } from "./NT4Spec";
+
+import type { TextDataFrame } from "./NT4Spec";
+
+// version 4.1 -- v4.1.networktables.first.wpi.edu
+// version 4.0 -- networktables.first.wpi.edu
+const PROTOCOL_DATA = [NetworkSpecs.protocol41, NetworkSpecs.protocol40];
+
+// https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#rtt-subprotocol
+const PROTOCOL_RTT = [NetworkSpecs.protocolRTT];
+
+/**
+ * A wrapper for `WebSocket` that implements async `connect` and `close` methods.
+ *
+ * This class manages the lifecycle of the raw websocket internally, creating and
+ * destroying the websocket as necessary when establishing and closing the connection.
+ */
+export class NT4WebSocketAsync {
+  private url: string;
+  private rtt: boolean;
+  private socket: WebSocket | null = null;
+  private onMessage?: (_: MessageEvent) => void;
+  private onClose?: (_: CloseEvent) => void;
+
+  /**
+   * Creates a `WebSocket` wrapper to be used for NT4 communication channel.
+   * This constructor does not initiate the connection, see `connect`.
+   *
+   * @param address server network address
+   * @param port sever port
+   * @param clientId client identifier
+   * @param options connection options
+   */
+  constructor(
+    address: string,
+    port: number,
+    clientId: string,
+    options: {
+      /** Callback invoked when socket receives message. */
+      onMessage?: (ev: MessageEvent) => void;
+      /** Callback invoked when socket closes. */
+      onClose?: (ev: CloseEvent) => void;
+      /** `true` to use secure protocol/port; `false` to use unsecure protocol/port (default). */
+      secure?: boolean;
+      /** `true` to create RTT subprotocol channel; `false` to create default data channel (default). */
+      rtt?: boolean;
+    }
+  ) {
+    const schema = options.secure ? "wss" : "ws";
+
+    this.url = `${schema}://${address}:${port}/nt/${clientId}`;
+    this.rtt = options.rtt ?? false;
+    this.onMessage = options.onMessage;
+    this.onClose = options.onClose;
+  }
+
+  private onMessageLocal(ev: MessageEvent, source: WebSocket) {
+    if (this.onMessage && this.socket === source) {
+      this.onMessage(ev);
+    }
+  }
+
+  private onCloseLocal(ev: CloseEvent, source: WebSocket) {
+    if (this.onClose && this.socket === source) {
+      this.onClose(ev);
+    }
+  }
+
+  /** Returns `true` if the socket is in the connected state. */
+  public get connected() {
+    return this.socket != null && this.socket.readyState === WebSocket.OPEN;
+  }
+
+  /** Returns `true` if the socket is in the connecting state. */
+  public get connecting() {
+    return this.socket != null && this.socket.readyState === WebSocket.CONNECTING;
+  }
+
+  /** Returns the subprotocol negotiated with the server. */
+  public get protocol() {
+    return this.socket?.protocol;
+  }
+
+  /** Sends text data frame (JSON serialized). */
+  public sendText(data: TextDataFrame | Array<TextDataFrame>) {
+    if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+      this.socket.send(JSON.stringify(Array.isArray(data) ? data : [data]));
+    }
+  }
+
+  /** Sends binary data frame. */
+  public sendBinary(data: Uint8Array) {
+    if (this.socket && this.socket.readyState === WebSocket.OPEN) {
+      this.socket.send(data);
+    }
+  }
+
+  /**
+   * Asynchronously terminates the connection.
+   *
+   * @param code optional code
+   * @param reason optional reason
+   */
+  public async close(code?: number, reason?: string): Promise<void> {
+    if (this.socket) {
+      const socket = this.socket;
+      this.socket = null;
+
+      // websocket is closing asynchronously, we need to wait
+      // for the corresponding onclose to fire:
+      // attach another listener here and promisify
+      return new Promise((resolve) => {
+        socket.addEventListener("close", () => {
+          resolve();
+        });
+
+        socket.close(code, reason);
+      });
+    }
+
+    return Promise.resolve();
+  }
+
+  /** Asynchronously initiates the connection. */
+  public async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const socket = new WebSocket(this.url, this.rtt ? PROTOCOL_RTT : PROTOCOL_DATA);
+
+      socket.binaryType = "arraybuffer";
+
+      this.socket = socket;
+
+      socket.addEventListener("message", (_) => this.onMessageLocal(_, socket));
+      socket.addEventListener("close", (_) => this.onCloseLocal(_, socket));
+
+      socket.onopen = () => {
+        resolve();
+      };
+
+      socket.onerror = (event) => {
+        reject(event);
+      };
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./NT4Types";
+export * from "./NT4Client";
+export * from "./NT4Topic";
+export * from "./NT4Subscription";