@2702rebels/ntcore 1.0.0

package/dist/index.mjs

@@ -0,0 +1,816 @@
+import { Decoder, Encoder } from "@msgpack/msgpack";
+import { Logger } from "@2702rebels/logger";
+
+//#region src/NT4Spec.ts
+/**
+* Network constants.
+*/
+const NetworkSpecs = {
+	portUnsecure: 5810,
+	portSecure: 5811,
+	protocol41: "v4.1.networktables.first.wpi.edu",
+	protocol40: "networktables.first.wpi.edu",
+	protocolRTT: "rtt.networktables.first.wpi.edu",
+	pingPeriod40: 1e3,
+	pingTimeout40: 3e3,
+	pingPeriod41: 250,
+	pingTimeout41: 1e3
+};
+/**
+* Supported data types mapped to protocol identifiers.
+*
+* https://github.com/wpilibsuite/allwpilib/blob/main/ntcore/doc/networktables4.adoc#supported-data-types
+*/
+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
+};
+
+//#endregion
+//#region src/NT4Subscription.ts
+/** Contains information about NT4 subscription. */
+var NT4Subscription = class {
+	/** Subscription UID. */
+	uid;
+	/** Subscription options. */
+	options;
+	/** Subscribed topic names or prefixes. */
+	topics;
+	constructor(uid, topics, options) {
+		this.uid = uid;
+		this.topics = new Set(typeof topics === "string" ? [topics] : topics);
+		this.options = options ?? {};
+	}
+};
+
+//#endregion
+//#region src/NT4Topic.ts
+/** Contains information about NT4 topic. */
+var NT4Topic = class {
+	/** Topic UID. */
+	uid;
+	/** Topic name. */
+	name;
+	/** Topic data type. */
+	type;
+	/** Topic properties. */
+	properties;
+	/** Publisher UID. */
+	pubuid;
+	/** Last retained value. */
+	retainedValue;
+	/** Timestamp of {@link retainedValue}. */
+	retainedTimestamp;
+	constructor(uid, name, type, properties, pubuid) {
+		this.uid = uid;
+		this.name = name;
+		this.type = type;
+		this.properties = properties ?? {};
+		this.pubuid = pubuid;
+		this.typeCode = DataTypeCodes[type] ?? 5;
+	}
+	/** Merges properties with this topic. */
+	mergeProperties(properties) {
+		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). */
+	updateRetainedValue(value, timestamp) {
+		if (this.retainedTimestamp == null || timestamp >= this.retainedTimestamp) {
+			this.retainedValue = value;
+			this.retainedTimestamp = timestamp;
+		}
+	}
+	/** Removes retained value except for "weak" default value. */
+	removeRetainedValue() {
+		if (this.retainedTimestamp != 0) {
+			this.retainedValue = void 0;
+			this.retainedTimestamp = void 0;
+		}
+	}
+	/** Resets retained value timestamp except for "weak" default value. */
+	resetRetainedTimestamp() {
+		if (this.retainedTimestamp != null && this.retainedTimestamp > 1) this.retainedTimestamp = 1;
+	}
+	/** Topic type code. For internal use only. */
+	typeCode;
+};
+
+//#endregion
+//#region src/NT4WebSocketAsync.ts
+const PROTOCOL_DATA = [NetworkSpecs.protocol41, NetworkSpecs.protocol40];
+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.
+*/
+var NT4WebSocketAsync = class {
+	url;
+	rtt;
+	socket = null;
+	onMessage;
+	onClose;
+	/**
+	* 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, port, clientId, options) {
+		this.url = `${options.secure ? "wss" : "ws"}://${address}:${port}/nt/${clientId}`;
+		this.rtt = options.rtt ?? false;
+		this.onMessage = options.onMessage;
+		this.onClose = options.onClose;
+	}
+	onMessageLocal(ev, source) {
+		if (this.onMessage && this.socket === source) this.onMessage(ev);
+	}
+	onCloseLocal(ev, source) {
+		if (this.onClose && this.socket === source) this.onClose(ev);
+	}
+	/** Returns `true` if the socket is in the connected state. */
+	get connected() {
+		return this.socket != null && this.socket.readyState === WebSocket.OPEN;
+	}
+	/** Returns `true` if the socket is in the connecting state. */
+	get connecting() {
+		return this.socket != null && this.socket.readyState === WebSocket.CONNECTING;
+	}
+	/** Returns the subprotocol negotiated with the server. */
+	get protocol() {
+		return this.socket?.protocol;
+	}
+	/** Sends text data frame (JSON serialized). */
+	sendText(data) {
+		if (this.socket && this.socket.readyState === WebSocket.OPEN) this.socket.send(JSON.stringify(Array.isArray(data) ? data : [data]));
+	}
+	/** Sends binary data frame. */
+	sendBinary(data) {
+		if (this.socket && this.socket.readyState === WebSocket.OPEN) this.socket.send(data);
+	}
+	/**
+	* Asynchronously terminates the connection.
+	*
+	* @param code optional code
+	* @param reason optional reason
+	*/
+	async close(code, reason) {
+		if (this.socket) {
+			const socket = this.socket;
+			this.socket = null;
+			return new Promise((resolve) => {
+				socket.addEventListener("close", () => {
+					resolve();
+				});
+				socket.close(code, reason);
+			});
+		}
+		return Promise.resolve();
+	}
+	/** Asynchronously initiates the connection. */
+	async connect() {
+		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);
+			};
+		});
+	}
+};
+
+//#endregion
+//#region src/NT4Client.ts
+/** Determines whether the specified predicate callback returns true for any element of a map. */
+function some(map, predicate) {
+	for (const v of map.values()) if (predicate(v)) return true;
+	return false;
+}
+/**
+* Implements a NetworkTable4 client that is responsible for establishing and maintaining a connection.
+*/
+var NT4Client = class NT4Client {
+	port;
+	clientId;
+	dataChannel;
+	rttChannel;
+	decoder = new Decoder();
+	encoder = new Encoder();
+	onConnect;
+	onDisconnect;
+	onTopicAnnounced;
+	onTopicRemoved;
+	onTopicUpdated;
+	onDataReceived;
+	retryPolicy;
+	pingTimeoutOverride_ms;
+	subscriptions = /* @__PURE__ */ new Map();
+	publishedTopics = /* @__PURE__ */ new Map();
+	announcedTopics = /* @__PURE__ */ new Map();
+	announcedTopicsIndex = /* @__PURE__ */ new Map();
+	connectionEstablished = false;
+	connectionInitiated = false;
+	connectionAttempts = 0;
+	connectionState = "disconnected";
+	networkLatency_μs = null;
+	serverTimeOffset_μs = null;
+	pingTimeout_ms = 0;
+	pongTimestamp_μs = 0;
+	pingIntervalId = null;
+	pongIntervalId = null;
+	/** Truncated at 15 seconds exponential backoff retry policy starting at 1 second. */
+	static defaultRetryPolicy(attempts) {
+		return Math.round(Math.min(15, Math.max(1, 1.2 ** Math.min(15, attempts))) * 1e3);
+	}
+	/** Cleans up closed data channel. */
+	cleanup() {
+		Logger.Default.debug(`[NT4Client] cleaning up`);
+		if (this.pingIntervalId) {
+			clearInterval(this.pingIntervalId);
+			this.pingIntervalId = null;
+		}
+		if (this.pongIntervalId) {
+			clearInterval(this.pongIntervalId);
+			this.pongIntervalId = null;
+		}
+		this.rttChannel.close();
+		if (this.connectionEstablished && this.onDisconnect) this.onDisconnect();
+		this.connectionEstablished = false;
+		this.connectionState = "disconnected";
+		this.announcedTopics.clear();
+		this.announcedTopicsIndex.clear();
+		for (const topic of this.publishedTopics.values()) topic.resetRetainedTimestamp();
+		this.pongTimestamp_μs = 0;
+		this.serverTimeOffset_μs = null;
+		this.networkLatency_μs = null;
+	}
+	/** Attempts to establish a connection, continuously retrying using policy. */
+	async connectWithRetry() {
+		this.connectionState = "connecting";
+		if (!this.connectionInitiated) {
+			Logger.Default.debug(`[NT4Client] pending cancellation, aborting...`);
+			return;
+		}
+		let response = null;
+		try {
+			response = await fetch(`http://${this.serverAddress}:${this.port}`, { signal: AbortSignal.timeout(250) });
+		} catch {}
+		if (!this.connectionInitiated) {
+			Logger.Default.debug(`[NT4Client] pending cancellation, aborting...`);
+			return;
+		}
+		if (response && response.ok) try {
+			Logger.Default.debug(`[NT4Client] opening channel to ${this.serverAddress}:${this.port}`);
+			await this.dataChannel.connect();
+			this.connectionAttempts = 0;
+			if (!this.connectionInitiated) {
+				Logger.Default.debug(`[NT4Client] pending cancellation, aborting...`);
+				return;
+			}
+			this.connectionEstablished = true;
+			this.connectionState = "connected";
+			Logger.Default.debug(`[NT4Client] connected to ${this.serverAddress}:${this.port}, subprotocol = ${this.dataChannel.protocol}`);
+			let pingPeriod_ms = NetworkSpecs.pingPeriod40;
+			this.pingTimeout_ms = this.pingTimeoutOverride_ms ?? NetworkSpecs.pingTimeout40;
+			if (this.dataChannel.protocol === NetworkSpecs.protocol41) {
+				Logger.Default.debug(`[NT4Client] server speaks v4.1, creating separate RTT channel`);
+				await this.rttChannel.connect();
+				if (!this.connectionInitiated) {
+					Logger.Default.debug(`[NT4Client] pending cancellation, aborting...`);
+					return;
+				}
+				pingPeriod_ms = NetworkSpecs.pingPeriod41;
+				this.pingTimeout_ms = this.pingTimeoutOverride_ms ?? NetworkSpecs.pingTimeout41;
+			}
+			Logger.Default.debug(`[NT4Client] sending timestamp and re-establishing subscriptions`);
+			this.sendRTT();
+			this.pongTimestamp_μs = 0;
+			this.pingIntervalId = setInterval(() => this.sendRTT(), pingPeriod_ms);
+			this.pongIntervalId = setInterval(() => this.checkTimeout(), pingPeriod_ms);
+			for (const subscription of this.subscriptions.values()) this.subscribeCore(subscription);
+			for (const topic of this.publishedTopics.values()) this.publishCore(topic);
+			if (this.onConnect) this.onConnect();
+			return;
+		} catch (exception) {
+			Logger.Default.error(`[NT4Client] failed to open channel`, exception);
+			await this.rttChannel.close();
+			await this.dataChannel.close();
+		}
+		this.connectionAttempts++;
+		const timeout = this.retryPolicy(this.connectionAttempts);
+		if (timeout < 0) {
+			Logger.Default.debug(`[NT4Client] aborting per retry policy after ${this.connectionAttempts} attempts`);
+			this.disconnect();
+			return;
+		}
+		Logger.Default.debug(`[NT4Client] retrying connection in ${timeout.toFixed(0)}ms`);
+		setTimeout(() => this.connectWithRetry(), timeout);
+	}
+	/** Invoked once the client-server clock is synchronized. */
+	onClockSynchronized() {
+		Logger.Default.debug(`[NT4Client] clock synchronized, offset = ${this.serverTimeOffset_μs}`);
+		for (const topic of this.publishedTopics.values()) if (topic.retainedTimestamp != null && topic.retainedValue != null) this.sendValueCore(topic, topic.retainedValue, topic.retainedTimestamp === 1 ? this.serverTimeMicroseconds() ?? 1 : topic.retainedTimestamp);
+	}
+	/** Consumes received data frame. */
+	processDataFrame(data) {
+		if (typeof data === "string") {
+			let array;
+			try {
+				array = JSON.parse(data);
+				if (!Array.isArray(array)) {
+					Logger.Default.error(`[NT4Client] unexpected text frame, JSON must be an array, frame ignored`);
+					return;
+				}
+			} catch (exception) {
+				Logger.Default.error(`[NT4Client] unexpected text frame, JSON is malformed, frame ignored`, exception);
+				return;
+			}
+			array.forEach((d) => {
+				if (typeof d !== "object" || !("method" in d) || !("params" in d)) {
+					Logger.Default.error(`[NT4Client] malformed message in text frame, message ignored`);
+					return;
+				}
+				const { method, params } = d;
+				if (typeof method !== "string" || typeof params !== "object") {
+					Logger.Default.error(`[NT4Client] malformed message in text frame, message ignored`);
+					return;
+				}
+				switch (method) {
+					case "announce": {
+						const topic = new NT4Topic(params.id, params.name, params.type, params.properties, params.pubuid);
+						this.announcedTopics.set(topic.name, topic);
+						this.announcedTopicsIndex.set(topic.uid, topic);
+						if (this.onTopicAnnounced) this.onTopicAnnounced(topic);
+						return;
+					}
+					case "unannounce": {
+						const topic = this.announcedTopics.get(params.name);
+						if (topic) {
+							this.publishedTopics.get(topic.name)?.removeRetainedValue();
+							this.announcedTopics.delete(topic.name);
+							this.announcedTopicsIndex.delete(topic.uid);
+							if (this.onTopicRemoved) this.onTopicRemoved(topic);
+						}
+						return;
+					}
+					case "properties": {
+						const topic = this.announcedTopics.get(params.name);
+						if (topic) {
+							topic.mergeProperties(params.update);
+							if (this.onTopicUpdated) this.onTopicUpdated(topic);
+						}
+						return;
+					}
+					default:
+						Logger.Default.error(`[NT4Client] unexpected method '${method}' in text frame message, message ignored`);
+						return;
+				}
+			});
+		} else for (const d of this.decoder.decodeMulti(data)) {
+			const [topicId, timestamp, typeCode, value] = d;
+			if (typeof topicId !== "number") {
+				Logger.Default.error(`[NT4Client] unexpected non-numeric topic identifier, frame ignored`);
+				return;
+			}
+			if (typeof timestamp !== "number") {
+				Logger.Default.error(`[NT4Client] unexpected non-numeric timestamp, frame ignored`);
+				return;
+			}
+			if (typeof typeCode !== "number") {
+				Logger.Default.error(`[NT4Client] unexpected non-numeric typeCode, frame ignored`);
+				return;
+			}
+			if (topicId === -1) {
+				if (typeof value !== "number") {
+					Logger.Default.error(`[NT4Client] unexpected non-numeric value in RTT frame, message ignored`);
+					continue;
+				}
+				const clientTime_μs = this.getClientTimestamp_μs();
+				const latency_μs = (clientTime_μs - value) / 2;
+				if (this.networkLatency_μs == null || latency_μs < this.networkLatency_μs) {
+					const clockSynchronized = this.serverTimeOffset_μs == null;
+					this.serverTimeOffset_μs = Math.round(timestamp + latency_μs - clientTime_μs);
+					if (clockSynchronized) this.onClockSynchronized();
+				}
+				this.networkLatency_μs = latency_μs;
+				this.pongTimestamp_μs = clientTime_μs;
+			} else if (topicId > 0) {
+				const topic = this.announcedTopicsIndex.get(topicId);
+				if (topic == null) {
+					Logger.Default.error(`[NT4Client] unexpected topic identifier ${topicId}, message ignored`);
+					continue;
+				} else if (this.onDataReceived) {
+					this.publishedTopics.get(topic.name)?.updateRetainedValue(value, timestamp);
+					this.onDataReceived(topic, value, timestamp);
+				}
+			} else {
+				Logger.Default.error(`[NT4Client] invalid topic identifier ${topicId}, message ignored`);
+				continue;
+			}
+		}
+	}
+	/** Handles general data frame received. */
+	onChannelMessage = (ev) => {
+		this.processDataFrame(ev.data);
+	};
+	/** Handles RTT data frame received. */
+	onChannelMessageRTT = (ev) => {
+		if (typeof ev.data === "string") {
+			Logger.Default.debug(`[NT4Client] unexpected text data frame on RTT channel, frame ignored`);
+			return;
+		}
+		this.processDataFrame(ev.data);
+	};
+	/** Handles channel closing for whatever reason. */
+	onChannelClose = (ev) => {
+		Logger.Default.debug(`[NT4Client] channel closed`, ev);
+		this.cleanup();
+		this.connectWithRetry();
+	};
+	/** Returns current timestamp in microseconds. This is NOT wall clock time. */
+	getClientTimestamp_μs() {
+		return Math.round(performance.now() * 1e3);
+	}
+	/** Sends data frame to publish the topic. */
+	publishCore(topic) {
+		this.dataChannel.sendText({
+			method: "publish",
+			params: {
+				pubuid: topic.uid,
+				name: topic.name,
+				type: topic.type,
+				properties: topic.properties
+			}
+		});
+	}
+	/** Sends data frame to unpublish the topic. */
+	unpublishCore(topic) {
+		this.dataChannel.sendText({
+			method: "unpublish",
+			params: { pubuid: topic.uid }
+		});
+	}
+	/** Sends data frame to set topic properties. */
+	setPropertiesCore(name, properties) {
+		this.dataChannel.sendText({
+			method: "setproperties",
+			params: {
+				name,
+				update: properties
+			}
+		});
+	}
+	/** Sends data frame to subscribe the subscription. */
+	subscribeCore(subscription) {
+		this.dataChannel.sendText({
+			method: "subscribe",
+			params: {
+				subuid: subscription.uid,
+				topics: Array.from(subscription.topics),
+				options: subscription.options
+			}
+		});
+	}
+	/** Sends data frame to unsubscribe the subscription. */
+	unsubscribeCore(subscription) {
+		this.dataChannel.sendText({
+			method: "unsubscribe",
+			params: { subuid: subscription.uid }
+		});
+	}
+	/** Sends data frame to update topic value. */
+	sendValueCore(topic, value, timestamp) {
+		const frame = this.encoder.encode([
+			topic.uid,
+			timestamp,
+			topic.typeCode,
+			value
+		]);
+		this.dataChannel.sendBinary(frame);
+	}
+	/**
+	* Sends RTT measurement binary frame.
+	* Uses RTT channel if available, falls back to data channel in NT4.0.
+	*/
+	sendRTT() {
+		const timestamp = this.getClientTimestamp_μs();
+		const frame = this.encoder.encode([
+			-1,
+			0,
+			DataTypeCodes.double,
+			timestamp
+		]);
+		(this.rttChannel ?? this.dataChannel).sendBinary(frame);
+	}
+	/**
+	* Determines whether connection times out if no message has been received
+	* within the timeout interval since the last pong.
+	*/
+	async checkTimeout() {
+		if (!this.connectionEstablished || this.pongTimestamp_μs === 0) return;
+		const delta_μs = this.getClientTimestamp_μs() - this.pongTimestamp_μs;
+		if (delta_μs > this.pingTimeout_ms * 1e3) {
+			Logger.Default.debug(`[NT4Client] no data received in the last ${(delta_μs / 1e3).toFixed(0)}ms, connection timed out`);
+			await this.dataChannel.close(4001, "timeout");
+			this.cleanup();
+			this.connectWithRetry();
+		}
+	}
+	/** Generates random UID. */
+	generateUID() {
+		return Math.floor(Math.random() * 2147483647);
+	}
+	/** Generates random safe UID avoiding possible clashes. */
+	generateSafeUID(has) {
+		let uid;
+		for (uid = this.generateUID(); has(uid); uid = this.generateUID());
+		return uid;
+	}
+	/** Determines whether published topic with the specified identifier exists. */
+	hasPublishedTopicWithId = (id) => some(this.publishedTopics, (_) => _.uid === id);
+	/** Determines whether subscription with the specified identifier exists. */
+	hasSubscriptionWithId = (id) => this.subscriptions.has(id);
+	/**
+	* 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, clientId, options) {
+		if (clientId.includes("@")) throw new Error("Client identifier must not contain '@' character");
+		this.serverAddress = serverAddress;
+		this.port = options.secure ? NetworkSpecs.portSecure : NetworkSpecs.portUnsecure;
+		this.clientId = clientId;
+		this.onConnect = options.onConnect;
+		this.onDisconnect = options.onDisconnect;
+		this.onTopicAnnounced = options.onTopicAnnounced;
+		this.onTopicRemoved = options.onTopicRemoved;
+		this.onTopicUpdated = options.onTopicUpdated;
+		this.onDataReceived = options.onDataReceived;
+		this.retryPolicy = options.retryPolicy ?? NT4Client.defaultRetryPolicy;
+		this.pingTimeoutOverride_ms = options.pingTimeoutMilliseconds;
+		this.dataChannel = new NT4WebSocketAsync(this.serverAddress, this.port, this.clientId, {
+			secure: options.secure,
+			onMessage: this.onChannelMessage,
+			onClose: this.onChannelClose
+		});
+		this.rttChannel = new NT4WebSocketAsync(this.serverAddress, this.port, this.clientId, {
+			rtt: true,
+			secure: options.secure,
+			onMessage: this.onChannelMessageRTT
+		});
+	}
+	/**
+	* Returns NT4 server network address the client is using.
+	*/
+	serverAddress;
+	/**
+	* Returns current connection state.
+	*/
+	get state() {
+		return this.connectionState;
+	}
+	/**
+	* Returns current network latency in microseconds if known.
+	*/
+	get networkLatencyMicroseconds() {
+		return this.networkLatency_μs;
+	}
+	/**
+	* 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) {
+		return this.serverTimeOffset_μs != null ? Math.round((clientTimeMicroseconds != null ? clientTimeMicroseconds : this.getClientTimestamp_μs()) + this.serverTimeOffset_μs) : null;
+	}
+	/**
+	* Initiates the connection.
+	* Once established the connection will be automatically kept alive by reconnecting.
+	*/
+	connect() {
+		if (this.connectionInitiated) return;
+		Logger.Default.debug(`[NT4Client] connection initiated`);
+		this.connectionInitiated = true;
+		this.connectWithRetry();
+	}
+	/**
+	* Terminates the connection.
+	* The client can be reconnected manually by calling {@link connect} again.
+	*/
+	disconnect() {
+		if (!this.connectionInitiated) return;
+		Logger.Default.debug(`[NT4Client] connection cancelled`);
+		this.connectionInitiated = false;
+		this.dataChannel.close();
+		this.rttChannel.close();
+	}
+	/**
+	* 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, options) {
+		const subscription = new NT4Subscription(this.generateSafeUID(this.hasSubscriptionWithId), topics, options);
+		this.subscriptions.set(subscription.uid, subscription);
+		if (this.connectionEstablished) this.subscribeCore(subscription);
+		return subscription;
+	}
+	/**
+	* 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) {
+		const subscription = typeof arg === "number" ? this.subscriptions.get(arg) : arg;
+		if (!subscription) return false;
+		this.subscriptions.delete(subscription.uid);
+		if (this.connectionEstablished) this.unsubscribeCore(subscription);
+		return true;
+	}
+	/**
+	* Unsubscribes all existing subscriptions.
+	*/
+	unsubscribeAll() {
+		for (const subscription of this.subscriptions.values()) this.unsubscribe(subscription);
+	}
+	/**
+	* 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, type, properties) {
+		let publishedTopic = this.publishedTopics.get(topic);
+		if (publishedTopic) return publishedTopic;
+		const uid = this.generateSafeUID(this.hasPublishedTopicWithId);
+		publishedTopic = new NT4Topic(uid, topic, type, properties, uid);
+		this.publishedTopics.set(publishedTopic.name, publishedTopic);
+		if (this.connectionEstablished) this.publishCore(publishedTopic);
+		return publishedTopic;
+	}
+	/**
+	* 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) {
+		const publishedTopic = this.publishedTopics.get(topic);
+		if (!publishedTopic) return false;
+		this.publishedTopics.delete(publishedTopic.name);
+		if (this.connectionEstablished) this.unpublishCore(publishedTopic);
+		return true;
+	}
+	/**
+	* Determines whether client already publishes the topic.
+	*
+	* @param topic topic name
+	*/
+	isTopicPublished(topic) {
+		return this.publishedTopics.has(topic);
+	}
+	/**
+	* Sets properties for the specified topic.
+	*
+	* @param topic topic name
+	* @param properties new properties
+	*/
+	setTopicProperties(topic, properties) {
+		const publishedTopic = this.publishedTopics.get(topic);
+		if (publishedTopic) publishedTopic.mergeProperties(properties);
+		const announcedTopic = this.announcedTopics.get(topic);
+		if (announcedTopic) announcedTopic.mergeProperties(properties);
+		if (this.connectionEstablished) this.setPropertiesCore(topic, properties);
+	}
+	/**
+	* Sets persistent flag for the topic.
+	*
+	* @param topic topic name
+	* @param value value to set
+	*/
+	setTopicPersistent(topic, value) {
+		this.setTopicProperties(topic, { persistent: value });
+	}
+	/**
+	* Sets retained flag for the topic.
+	*
+	* @param topic topic name
+	* @param value value to set
+	*/
+	setTopicRetained(topic, value) {
+		this.setTopicProperties(topic, { retained: value });
+	}
+	/**
+	* 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, value) {
+		this.setValueAt(topic, value, this.serverTimeMicroseconds() ?? 1);
+	}
+	/**
+	* 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, value) {
+		this.setValueAt(topic, value, 0);
+	}
+	/**
+	* 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, value, timestamp) {
+		const publishedTopic = this.publishedTopics.get(topic);
+		if (!publishedTopic) throw new Error("Topic must be published first");
+		publishedTopic.updateRetainedValue(value, timestamp);
+		if (this.onDataReceived) {
+			const announcedTopic = this.announcedTopics.get(topic);
+			if (announcedTopic) this.onDataReceived(announcedTopic, value, timestamp);
+		}
+		if (this.connectionEstablished && this.serverTimeOffset_μs != null) this.sendValueCore(publishedTopic, value, timestamp);
+	}
+	/**
+	* Returns current ping timeout.
+	*
+	* @returns A value in milliseconds or 0 if the timeout has not been set yet.
+	*/
+	get pingTimeoutMilliseconds() {
+		return this.pingTimeout_ms;
+	}
+	/**
+	* Sets ping timeout.
+	*
+	* @param value Timeout in milliseconds or `undefined` to use default protocol timeout value.
+	*/
+	setPingTimeoutMilliseconds(value) {
+		Logger.Default.debug(value != null ? `[NT4Client] ping timeout is set to ${value.toFixed(0)}ms` : `[NT4Client] ping timeout is reset to protocol-based default`);
+		this.pingTimeoutOverride_ms = value;
+		if (value != null) this.pingTimeout_ms = value;
+		else this.pingTimeout_ms = this.dataChannel.protocol === NetworkSpecs.protocol41 ? NetworkSpecs.pingTimeout41 : NetworkSpecs.pingPeriod40;
+	}
+};
+
+//#endregion
+export { NT4Client, NT4Subscription, NT4Topic };
+//# sourceMappingURL=index.mjs.map