@2702rebels/ntcore 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,428 @@
+//#region src/NT4Types.d.ts
+/**
+ * Topic properties, including well-known properties
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#properties
+ */
+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
+ */
+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;
+};
+//#endregion
+//#region src/NT4Subscription.d.ts
+/** Contains information about NT4 subscription. */
+declare class NT4Subscription {
+  /** Subscription UID. */
+  readonly uid: number;
+  /** Subscription options. */
+  readonly options: SubscriptionOptions;
+  /** Subscribed topic names or prefixes. */
+  readonly topics: Set<string>;
+  constructor(uid: number, topics: Iterable<string>, options?: SubscriptionOptions);
+}
+//#endregion
+//#region src/NT4Topic.d.ts
+/** Contains information about NT4 topic. */
+declare class NT4Topic {
+  /** Topic UID. */
+  readonly uid: number;
+  /** Topic name. */
+  readonly name: string;
+  /** Topic data type. */
+  readonly type: string;
+  /** Topic properties. */
+  readonly properties: TopicProperties;
+  /** Publisher UID. */
+  pubuid?: number;
+  /** Last retained value. */
+  retainedValue?: unknown;
+  /** Timestamp of {@link retainedValue}. */
+  retainedTimestamp?: number;
+  constructor(uid: number, name: string, type: string, properties?: TopicProperties, pubuid?: number);
+  /** Merges properties with this topic. */
+  mergeProperties(properties: TopicProperties): void;
+  /** Updates retained value if the incoming timestamp is newer (greater-than or equal-to). */
+  updateRetainedValue(value: unknown, timestamp: number): void;
+  /** Removes retained value except for "weak" default value. */
+  removeRetainedValue(): void;
+  /** Resets retained value timestamp except for "weak" default value. */
+  resetRetainedTimestamp(): void;
+  /** Topic type code. For internal use only. */
+  readonly typeCode: number;
+}
+//#endregion
+//#region src/NT4Spec.d.ts
+
+/**
+ * Supported data types mapped to protocol identifiers.
+ *
+ * https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#supported-data-types
+ */
+declare const DataTypeCodes: {
+  readonly boolean: 0;
+  readonly double: 1;
+  readonly int: 2;
+  readonly float: 3;
+  readonly string: 4;
+  readonly json: 4;
+  readonly raw: 5;
+  readonly rpc: 5;
+  readonly msgpack: 5;
+  readonly protobuf: 5;
+  readonly "boolean[]": 16;
+  readonly "double[]": 17;
+  readonly "int[]": 18;
+  readonly "float[]": 19;
+  readonly "string[]": 20;
+};
+type DataType = keyof typeof DataTypeCodes;
+//#endregion
+//#region src/NT4Client.d.ts
+type NT4ClientConnectionState = "disconnected" | "connecting" | "connected";
+type NT4ClientOptions = {
+  /** Indicates that secure channel should be used. */
+  secure?: boolean;
+  /**
+   * Invoked when the client connects.
+   */
+  onConnect?: () => void;
+  /**
+   * Invoked when the client disconnects.
+   */
+  onDisconnect?: () => void;
+  /**
+   * Invoked when new topic is announced by the server.
+   *
+   * @param topic topic announced
+   */
+  onTopicAnnounced?: (topic: NT4Topic) => void;
+  /**
+   * Invoked when a topic is removed by the server.
+   *
+   * @param topic topic removed
+   */
+  onTopicRemoved?: (topic: NT4Topic) => void;
+  /**
+   * Invoked when a topic properties are updated by the server.
+   *
+   * @param topic topic updated
+   */
+  onTopicUpdated?: (topic: NT4Topic) => void;
+  /**
+   * Invoked when the topic receives new data.
+   *
+   * @param topic topic receiving data
+   * @param value value received
+   * @param timestamp server timestamp in microseconds
+   */
+  onDataReceived?: (topic: NT4Topic, value: unknown, timestamp: number) => void;
+  /**
+   * Retry policy that accepts the current number of connection attempts
+   * and returns the timeout in milliseconds or -1 to abort.
+   *
+   * @param attempts number of subsequent connection attempts
+   * @returns timeout in milliseconds or -1 to abort
+   */
+  retryPolicy?: (attempts: number) => number;
+  /**
+   * Overrides default timeout for ping-pong packets.
+   *
+   * Defaults:
+   * - NT 4.0: 3000 milliseconds
+   * - NT 4.1: 1000 milliseconds
+   */
+  pingTimeoutMilliseconds?: number;
+};
+/**
+ * Implements a NetworkTable4 client that is responsible for establishing and maintaining a connection.
+ */
+declare class NT4Client {
+  private readonly port;
+  private readonly clientId;
+  private readonly dataChannel;
+  private readonly rttChannel;
+  private readonly decoder;
+  private readonly encoder;
+  private readonly onConnect?;
+  private readonly onDisconnect?;
+  private readonly onTopicAnnounced?;
+  private readonly onTopicRemoved?;
+  private readonly onTopicUpdated?;
+  private readonly onDataReceived?;
+  private readonly retryPolicy;
+  private pingTimeoutOverride_ms?;
+  private subscriptions;
+  private publishedTopics;
+  private announcedTopics;
+  private announcedTopicsIndex;
+  private connectionEstablished;
+  private connectionInitiated;
+  private connectionAttempts;
+  private connectionState;
+  private networkLatency_μs;
+  private serverTimeOffset_μs;
+  private pingTimeout_ms;
+  private pongTimestamp_μs;
+  private pingIntervalId;
+  private pongIntervalId;
+  /** Truncated at 15 seconds exponential backoff retry policy starting at 1 second. */
+  static defaultRetryPolicy(attempts: number): number;
+  /** Cleans up closed data channel. */
+  private cleanup;
+  /** Attempts to establish a connection, continuously retrying using policy. */
+  private connectWithRetry;
+  /** Invoked once the client-server clock is synchronized. */
+  private onClockSynchronized;
+  /** Consumes received data frame. */
+  private processDataFrame;
+  /** Handles general data frame received. */
+  private onChannelMessage;
+  /** Handles RTT data frame received. */
+  private onChannelMessageRTT;
+  /** Handles channel closing for whatever reason. */
+  private onChannelClose;
+  /** Returns current timestamp in microseconds. This is NOT wall clock time. */
+  private getClientTimestamp_μs;
+  /** Sends data frame to publish the topic. */
+  private publishCore;
+  /** Sends data frame to unpublish the topic. */
+  private unpublishCore;
+  /** Sends data frame to set topic properties. */
+  private setPropertiesCore;
+  /** Sends data frame to subscribe the subscription. */
+  private subscribeCore;
+  /** Sends data frame to unsubscribe the subscription. */
+  private unsubscribeCore;
+  /** Sends data frame to update topic value. */
+  private sendValueCore;
+  /**
+   * Sends RTT measurement binary frame.
+   * Uses RTT channel if available, falls back to data channel in NT4.0.
+   */
+  private sendRTT;
+  /**
+   * Determines whether connection times out if no message has been received
+   * within the timeout interval since the last pong.
+   */
+  private checkTimeout;
+  /** Generates random UID. */
+  private generateUID;
+  /** Generates random safe UID avoiding possible clashes. */
+  private generateSafeUID;
+  /** Determines whether published topic with the specified identifier exists. */
+  private readonly hasPublishedTopicWithId;
+  /** Determines whether subscription with the specified identifier exists. */
+  private readonly hasSubscriptionWithId;
+  /**
+   * Constructs an instance of NT4Client without initiating a connection.
+   *
+   * @param serverAddress NT4 server network address
+   * @param clientId this client identifier (cannot contain '@')
+   * @param options options
+   */
+  constructor(serverAddress: string, clientId: string, options: NT4ClientOptions);
+  /**
+   * Returns NT4 server network address the client is using.
+   */
+  readonly serverAddress: string;
+  /**
+   * Returns current connection state.
+   */
+  get state(): NT4ClientConnectionState;
+  /**
+   * Returns current network latency in microseconds if known.
+   */
+  get networkLatencyMicroseconds(): number | null;
+  /**
+   * Returns server time in microseconds that is current or
+   * based on the specified client (local) time.
+   *
+   * Returns `null` if the server time offset is not established.
+   */
+  serverTimeMicroseconds(clientTimeMicroseconds?: number): number | null;
+  /**
+   * Initiates the connection.
+   * Once established the connection will be automatically kept alive by reconnecting.
+   */
+  connect(): void;
+  /**
+   * Terminates the connection.
+   * The client can be reconnected manually by calling {@link connect} again.
+   */
+  disconnect(): void;
+  /**
+   * Creates a new subscription.
+   *
+   * The subscription can be created regardless of connectivity state.
+   * All client subscriptions are automatically restored once connection
+   * has been established. This is also true for reconnects following
+   * loss of connectivity or deliberate disconnects.
+   *
+   * Caller can {@link unsubscribe} by passing the return value of this call or
+   * invoke {@link unsubscribeAll} to remove all existing client subscriptions.
+   *
+   * @param topics topics or prefixes to include in the subscription
+   * @param options subscription options
+   * @returns A subscription instance
+   */
+  subscribe(topics: Iterable<string>, options: SubscriptionOptions): NT4Subscription;
+  /**
+   * Unsubscribes an existing subscription.
+   *
+   * @param arg subscription or subscription identifier
+   * @returns `true` if the subscription was successfully unsubscribed, `false` if the subscription was not found
+   */
+  unsubscribe(arg: NT4Subscription | number): boolean;
+  /**
+   * Unsubscribes all existing subscriptions.
+   */
+  unsubscribeAll(): void;
+  /**
+   * Publishes a topic with the specified name and type.
+   *
+   * This method registers this client as a publisher for the topic.
+   * It should be called before {@link setValue} or {@link setValueAt}
+   * can be used.
+   *
+   * Publishing a topic on a disconnected client is allowed.
+   * Client will automatically register such publishers once the connection
+   * has been established and send default or retained value as appropriate.
+   *
+   * @param topic topic name
+   * @param type data type
+   * @param properties properties
+   */
+  publishTopic(topic: string, type: DataType | string, properties?: TopicProperties): NT4Topic;
+  /**
+   * Un-publishes previously published topic.
+   *
+   * @param topic topic name
+   * @returns `true` if the topic was successfully unpublished, `false` if the topic was not published
+   */
+  unpublishTopic(topic: string): boolean;
+  /**
+   * Determines whether client already publishes the topic.
+   *
+   * @param topic topic name
+   */
+  isTopicPublished(topic: string): boolean;
+  /**
+   * Sets properties for the specified topic.
+   *
+   * @param topic topic name
+   * @param properties new properties
+   */
+  setTopicProperties(topic: string, properties: TopicProperties): void;
+  /**
+   * Sets persistent flag for the topic.
+   *
+   * @param topic topic name
+   * @param value value to set
+   */
+  setTopicPersistent(topic: string, value: boolean): void;
+  /**
+   * Sets retained flag for the topic.
+   *
+   * @param topic topic name
+   * @param value value to set
+   */
+  setTopicRetained(topic: string, value: boolean): void;
+  /**
+   * Sends a value to the published topic using the current time.
+   *
+   * This client must publish the topic with {@link publishTopic} first.
+   *
+   * @param topic topic name
+   * @param value value to send
+   */
+  setValue(topic: string, value: unknown): void;
+  /**
+   * Sends a default ("weak") value to the published topic.
+   *
+   * This client must publish the topic with {@link publishTopic} first.
+   *
+   * @param topic topic name
+   * @param value value to send
+   */
+  setDefaultValue(topic: string, value: unknown): void;
+  /**
+   * Sends a value to the published topic using the specified timestamp.
+   *
+   * This client must publish the topic with {@link publishTopic} first.
+   *
+   * @param topic topic name
+   * @param value value to send
+   * @param timestamp timestamp
+   */
+  setValueAt(topic: string, value: unknown, timestamp: number): void;
+  /**
+   * Returns current ping timeout.
+   *
+   * @returns A value in milliseconds or 0 if the timeout has not been set yet.
+   */
+  get pingTimeoutMilliseconds(): number;
+  /**
+   * Sets ping timeout.
+   *
+   * @param value Timeout in milliseconds or `undefined` to use default protocol timeout value.
+   */
+  setPingTimeoutMilliseconds(value: number | undefined): void;
+}
+//#endregion
+export { NT4Client, NT4ClientConnectionState, NT4ClientOptions, NT4Subscription, NT4Topic, SubscriptionOptions, TopicProperties };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/NT4Types.ts","../src/NT4Subscription.ts","../src/NT4Topic.ts","../src/NT4Spec.ts","../src/NT4Client.ts"],"sourcesContent":[],"mappings":";;AAKA;AA8BA;;;KA9BY,eAAA,GAAkB;ECFjB;;;;;;;;;ACGb;;;;;;;;ACiCA;AAkBA;;;;AC7CA,CAAA;AAEA;;;AAiC2B,KJZf,mBAAA,GAAsB,MIYP,CAAA,MAAA,EAAA,OAAA,CAAA,GAAA;EASA;;AAkC3B;;;;;EAomByE,QAAA,CAAA,EAAA,MAAA;EAkB/C;;;;;;;;;;;;;;;;;;;;;;;;;AJ3sB1B;AA8BY,cChCC,eAAA,CDgCqB;;;;EChCrB,SAAA,OAAA,EAKc,mBALC;EAKD;EAGD,SAAA,MAAA,EAAA,GAAA,CAAA,MAAA,CAAA;EAES,WAAA,CAAA,GAAA,EAAA,MAAA,EAAA,MAAA,EAAA,QAAA,CAAA,MAAA,CAAA,EAAA,OAAA,CAAA,EAA4B,mBAA5B;;;;ADRnC;AA8BY,cE7BC,QAAA,CF6BkB;;;;EChClB,SAAA,IAAA,EAAA,MAAe;EAKD;EAGD,SAAA,IAAA,EAAA,MAAA;EAES;EAA4B,SAAA,UAAA,ECIjC,eDJiC;EAAmB;;;;ECPrE;EAWiB,iBAAA,CAAA,EAAA,MAAA;EAWsC,WAAA,CAAA,GAAA,EAAA,MAAA,EAAA,IAAA,EAAA,MAAA,EAAA,IAAA,EAAA,MAAA,EAAA,UAAA,CAAA,EAAA,eAAA,EAAA,MAAA,CAAA,EAAA,MAAA;EAU/B;EAAe,eAAA,CAAA,UAAA,EAAf,eAAe,CAAA,EAAA,IAAA;;;;ECCvC,mBAgBH,CAAA,CAAA,EAAA,IAAA;EAEE;;;;AC7CZ;;;;AD6CA;;;;AC7CA;AAEY,cDyBC,aCzBe,EAAA;EAmBC,SAAA,OAAA,EAAA,CAAA;EAOF,SAAA,MAAA,EAAA,CAAA;EAOA,SAAA,GAAA,EAAA,CAAA;EASA,SAAA,KAAA,EAAA,CAAA;EAAQ,SAAA,MAAA,EAAA,CAAA;EAkCtB,SAAA,IAAS,EAAA,CAAA;EA+e0C,SAAA,GAAA,EAAA,CAAA;EA+C9C,SAAA,GAAA,EAAA,CAAA;EAsES,SAAA,OAAA,EAAA,CAAA;EAA2B,SAAA,QAAA,EAAA,CAAA;EAAmB,SAAA,WAAA,EAAA,EAAA;EAkB/C,SAAA,UAAA,EAAA,EAAA;EAsCiB,SAAA,OAAA,EAAA,EAAA;EAAgC,SAAA,SAAA,EAAA,EAAA;EAAe,SAAA,UAAA,EAAA,EAAA;CAoDnC;AAAe,KDjvB1D,QAAA,GCivB0D,MAAA,ODjvBlC,aCivBkC;;;KA9xB1D,wBAAA;KAEA,gBAAA;EHXC;EAKc,MAAA,CAAA,EAAA,OAAA;EAGD;;;EAEwD,SAAA,CAAA,EAAA,GAAA,GAAA,IAAA;;;;ECPrE,YAAQ,CAAA,EAAA,GAAA,GAAA,IAAA;EAWS;;;;;6BEgBD;;ADM7B;AAkBA;;;2BCjB2B;EA5Bf;AAEZ;;;;EA0C2B,cAAA,CAAA,EAAA,CAAA,KAAA,EATA,QASA,EAAA,GAAA,IAAA;EAAQ;AAkCnC;;;;;;EAsnB0B,cAAA,CAAA,EAAA,CAAA,KAAA,EAxpBC,QAwpBD,EAAA,KAAA,EAAA,OAAA,EAAA,SAAA,EAAA,MAAA,EAAA,GAAA,IAAA;EAsCiB;;;;;;;;;;;;;;;;;;;;cA5pB9B,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gEA+emD;;;;;;;;eA+C9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAsES,2BAA2B,sBAAmB;;;;;;;mBAkB/C;;;;;;;;;;;;;;;;;;;;oCAsCiB,gCAAgC,kBAAe;;;;;;;;;;;;;;;;;;;;gDAoDnC"}