fix(types): subscribe definition

[redboltz]

TypeScript definition of subscribe() has two functions.

MQTT.js/types/lib/client.d.ts

Lines 165 to 167 in aa49aaf

	public subscribe (topic:
	string
	| string[], opts: IClientSubscribeOptions, callback?: ClientSubscribeCallback): this

The type of the first parameter is string or string[].
The second parameter is opts. opts could have properties. e.g.)SubscriptionIdentifier

MQTT.js/types/lib/client.d.ts

Lines 168 to 171 in aa49aaf

	public subscribe (topic:
	string
	| string[]
	| ISubscriptionMap, callback?: ClientSubscribeCallback): this

The type of the first parameter is string, string[], or ISubscriptionMap.
ISubscriptionMap is defined as follows:

MQTT.js/types/lib/client.d.ts

Lines 57 to 67 in aa49aaf

	export interface ISubscriptionMap {
	/**
	* object which has topic names as object keys and as value the options, like {'test1': {qos: 0}, 'test2': {qos: 2}}.
	*/
	[topic: string]: {
	qos: QoS,
	nl?: boolean,
	rap?: boolean,
	rh?: number
	}
	}

MQTT spec defines properties are in common for all subscription entries on one subscription.
So ISubscriptionMap doesn't have properties.

When ISubscriptionMap is passed as the first argument, then the following code is processed:

MQTT.js/lib/client.js

Lines 760 to 780 in aa49aaf

	Object
	.keys(obj)
	.forEach(function (k) {
	debug('subscribe: object topic %s', k)
	if (!Object.prototype.hasOwnProperty.call(that._resubscribeTopics, k) ||
	that._resubscribeTopics[k].qos < obj[k].qos ||
	resubscribe) {
	const currentOpts = {
	topic: k,
	qos: obj[k].qos
	}
	if (version === 5) {
	currentOpts.nl = obj[k].nl
	currentOpts.rap = obj[k].rap
	currentOpts.rh = obj[k].rh
	currentOpts.properties = opts.properties
	}
	debug('subscribe: pushing `%s` to subs list', currentOpts)
	subs.push(currentOpts)
	}
	})

qos, nl, rap, and rh are extraced from ISubscriptionMap, but propertiy such as SubscriptionIdentifier are gotten from opts. Because properties are in common for subscribe entries.

However, the TypeScript definition doesn't have a combination of ISubscriptionMap and opts (for properties).
So this PR add it to the following definition:

MQTT.js/types/lib/client.d.ts

Lines 165 to 167 in aa49aaf

	public subscribe (topic:
	string
	| string[], opts: IClientSubscribeOptions, callback?: ClientSubscribeCallback): this

The type of opts is IClientSubscribeOptions that is defined as follows:

MQTT.js/types/lib/client-options.d.ts

Lines 170 to 194 in aa49aaf

	export interface IClientSubscribeOptions {
	/**
	* the QoS
	*/
	qos: QoS,
	/*
	* no local flag
	* */
	nl?: boolean,
	/*
	* Retain As Published flag
	* */
	rap?: boolean,
	/*
	* Retain Handling option
	* */
	rh?: number,
	/*
	* MQTT 5.0 properies object of subscribe
	* */
	properties?: {
	subscriptionIdentifier?: number,
	userProperties?: UserProperties
	}
	}

When opts is used with ISubscriptionMap, only properties field is required. So I added IClientSubscribeProperties.

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (d71b000) 85.74% compared to head (7e9089d) 85.74%.

❗ Current head 7e9089d differs from pull request most recent head 80f33c0. Consider uploading reports for the commit 80f33c0 to get more accurate results

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1527   +/-   ##
=======================================
  Coverage   85.74%   85.74%           
=======================================
  Files          13       13           
  Lines        1249     1249           
=======================================
  Hits         1071     1071           
  Misses        178      178           

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[robertsLando]

Are we actually handling this somewhere in code?

[redboltz]

What does "in code" mean? If it means MQTT.js internal code, the answer is no.
However, this is a part of public APIs. MQTT.js users that access MQTT.js APIs via TypeScript require it.
For example, my project using MQTT.js via TypeScript requires setting SubscriptionIdentifier property when subscrine() API calling. Lack of this TypeScript definition, I need to use type unsafe JavaScript code directly.
This definition improve type safety for TypeScript users.