Add TypeScript types

package.json

@@ -18,14 +18,16 @@
     "url": "git://github.com/mqttjs/MQTT.js.git"
   },
   "main": "mqtt.js",
+  "types": "types/index.d.ts",
   "scripts": {
     "test": "node_modules/.bin/istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- --bail",
     "pretest": "standard | snazzy",
+    "tslint": "tslint types/**/*.d.ts",
     "prepublish": "nsp check && npm run browser-build",
     "browser-build": "rimraf dist/ && mkdirp dist/ && browserify mqtt.js -s mqtt > dist/mqtt.js && uglifyjs --screw-ie8 < dist/mqtt.js > dist/mqtt.min.js",
     "browser-test": "zuul --server test/browser/server.js --local --open test/browser/test.js",
     "sauce-test": "zuul --server test/browser/server.js --tunnel ngrok -- test/browser/test.js",
-    "ci": "npm run test && codecov"
+    "ci": "npm run tslint && npm run test && codecov"
   },
   "pre-commit": [
     "test"
@@ -84,6 +86,9 @@
     "snazzy": "^6.0.0",
     "standard": "^8.6.0",
     "through2": "^2.0.3",
+    "tslint": "^4.5.1",
+    "tslint-config-standard": "^4.0.0",
+    "typescript": "^2.2.1",
     "uglify": "^0.1.5",
     "uglify-js": "^2.7.5",
     "ws": "^1.0.0",

tslint.json

@@ -0,0 +1,3 @@
+{
+    "extends": "tslint-config-standard"
+}

types/index.d.ts

@@ -0,0 +1,7 @@
+export * from './lib/client'
+export * from './lib/connect'
+export * from './lib/store'
+export * from './lib/types'
+export * from './lib/client-options'
+import { MqttClient } from './lib/client'
+export { MqttClient as Client }

types/lib/client-options.d.ts

@@ -0,0 +1,115 @@
+import { MqttClient } from './client'
+import { Store } from './store'
+import { QoS } from './types'
+
+export interface IClientOptions extends ISecureClientOptions {
+  port?: number // port is made into a number subsequently
+  host?: string // host does NOT include port
+  hostname?: string
+  path?: string
+  protocol?: 'wss' | 'ws' | 'mqtt' | 'mqtts' | 'tcp' | 'ssl'
+
+  wsOptions?: {
+    [x: string]: any;
+  }
+  /**
+   *  10 seconds, set to 0 to disable
+   */
+  keepalive?: number
+  /**
+   * 'mqttjs_' + Math.random().toString(16).substr(2, 8)
+   */
+  clientId?: string
+  /**
+   * 'MQTT'
+   */
+  protocolId?: string
+  /**
+   * 4
+   */
+  protocolVersion?: number
+  /**
+   * true, set to false to receive QoS 1 and 2 messages while offline
+   */
+  clean?: boolean
+  /**
+   * 1000 milliseconds, interval between two reconnections
+   */
+  reconnectPeriod?: number
+  /**
+   * 30 * 1000 milliseconds, time to wait before a CONNACK is received
+   */
+  connectTimeout?: number
+  /**
+   * the username required by your broker, if any
+   */
+  username?: string
+  /**
+   * the password required by your broker, if any
+   */
+  password?: string
+  /**
+   * a Store for the incoming packets
+   */
+  incomingStore?: Store
+  /**
+   * a Store for the outgoing packets
+   */
+  outgoingStore?: Store
+  queueQoSZero?: boolean
+  reschedulePings?: boolean
+  servers?: Array<{
+    host: string;
+    port: number;
+  }>
+  /**
+   * a message that will sent by the broker automatically when the client disconnect badly.
+   */
+  will?: {
+    /**
+     * the topic to publish
+     */
+    topic: string;
+    /**
+     * the message to publish
+     */
+    payload: string;
+    /**
+     * the QoS
+     */
+    qos: QoS;
+    /**
+     * the retain flag
+     */
+    retain: boolean;
+  }
+  transformWsUrl?: (url: string, options: IClientOptions, client: MqttClient) => string
+}
+export interface ISecureClientOptions {
+  /**
+   * path to private key
+   */
+  key?: string
+  /**
+   * path to corresponding public cert
+   */
+  cert?: string
+  ca?: string
+  rejectUnauthorized?: boolean
+}
+export interface IClientPublishOptions {
+  /**
+   * the QoS
+   */
+  qos?: QoS
+  /**
+   * the retain flag
+   */
+  retain?: boolean
+}
+export interface IClientSubscribeOptions {
+  /**
+   * the QoS
+   */
+  qos?: QoS
+}

types/lib/client.d.ts

@@ -0,0 +1,168 @@
+/// <reference types="node" />
+
+import * as events from 'events'
+import {
+  IClientOptions,
+  IClientPublishOptions,
+  IClientSubscribeOptions
+} from './client-options'
+import { Store } from './store'
+import { Packet, QoS } from './types'
+
+export interface ISubscriptionGrant {
+  /**
+   *  is a subscribed to topic
+   */
+  topic: string
+  /**
+   *  is the granted qos level on it, may return 128 on error
+   */
+  qos: QoS | number
+}
+export interface ISubscriptionRequest {
+  /**
+   *  is a subscribed to topic
+   */
+  topic: string
+  /**
+   *  is the granted qos level on it
+   */
+  qos: QoS
+}
+export interface ISubscriptionMap {
+  /**
+   * object which has topic names as object keys and as value the QoS, like {'test1': 0, 'test2': 1}.
+   */
+  [topic: string]: QoS
+}
+
+export declare type ClientSubscribeCallback = (err: Error, granted: ISubscriptionGrant[]) => void
+export declare type OnMessageCallback = (topic: string, payload: Buffer, packet: Packet) => void
+export declare type OnPacketCallback = (packet: Packet) => void
+export declare type OnErrorCallback = (error: Error) => void
+export declare type PacketCallback = (error?: Error, packet?: Packet) => any
+
+export interface IStream extends events.EventEmitter {
+  pipe (to: any): any
+  destroy (): any
+  end (): any
+}
+/**
+ * MqttClient constructor
+ *
+ * @param {Stream} stream - stream
+ * @param {Object} [options] - connection options
+ * (see Connection#connect)
+ */
+export declare class MqttClient extends events.EventEmitter {
+  public connected: boolean
+  public disconnecting: boolean
+  public disconnected: boolean
+  public reconnecting: boolean
+  public incomingStore: Store
+  public outgoingStore: Store
+  public options: IClientOptions
+  public queueQoSZero: boolean
+
+  constructor (streamBuilder: (MqttClient) => IStream, options: IClientOptions)
+
+  public on (event: 'message', cb: OnMessageCallback): this
+  public on (event: 'packetsend' | 'packetreceive', cb: OnPacketCallback): this
+  public on (event: 'error', cb: OnErrorCallback): this
+  public on (event: string, cb: Function): this
+
+  public once (event: 'message', cb: OnMessageCallback): this
+  public once (event:
+                'packetsend'
+                | 'packetreceive', cb: OnPacketCallback): this
+  public once (event: 'error', cb: OnErrorCallback): this
+  public once (event: string, cb: Function): this
+
+  /**
+   * publish - publish <message> to <topic>
+   *
+   * @param {String} topic - topic to publish to
+   * @param {(String|Buffer)} message - message to publish
+   *
+   * @param {Object}    [opts] - publish options, includes:
+   *   @param {Number}  [opts.qos] - qos level to publish on
+   *   @param {Boolean} [opts.retain] - whether or not to retain the message
+   *
+   * @param {Function} [callback] - function(err){}
+   *    called when publish succeeds or fails
+   * @returns {Client} this - for chaining
+   * @api public
+   *
+   * @example client.publish('topic', 'message')
+   * @example
+   *     client.publish('topic', 'message', {qos: 1, retain: true})
+   * @example client.publish('topic', 'message', console.log)
+   */
+  public publish (topic: string, message: string | Buffer,
+                 opts: IClientPublishOptions, callback?: PacketCallback): this
+  public publish (topic: string, message: string | Buffer,
+                 callback?: PacketCallback): this
+
+  /**
+   * subscribe - subscribe to <topic>
+   *
+   * @param {String, Array, Object} topic - topic(s) to subscribe to, supports objects in the form {'topic': qos}
+   * @param {Object} [opts] - optional subscription options, includes:
+   * @param  {Number} [opts.qos] - subscribe qos level
+   * @param {Function} [callback] - function(err, granted){} where:
+   *    {Error} err - subscription error (none at the moment!)
+   *    {Array} granted - array of {topic: 't', qos: 0}
+   * @returns {MqttClient} this - for chaining
+   * @api public
+   * @example client.subscribe('topic')
+   * @example client.subscribe('topic', {qos: 1})
+   * @example client.subscribe({'topic': 0, 'topic2': 1}, console.log)
+   * @example client.subscribe('topic', console.log)
+   */
+  public subscribe (topic:
+                     string
+                     | string[], opts: IClientSubscribeOptions, callback?: ClientSubscribeCallback): this
+  public subscribe (topic:
+                     string
+                     | string[]
+                     | ISubscriptionMap, callback?: ClientSubscribeCallback): this
+
+  /**
+   * unsubscribe - unsubscribe from topic(s)
+   *
+   * @param {String, Array} topic - topics to unsubscribe from
+   * @param {Function} [callback] - callback fired on unsuback
+   * @returns {MqttClient} this - for chaining
+   * @api public
+   * @example client.unsubscribe('topic')
+   * @example client.unsubscribe('topic', console.log)
+   */
+  public unsubscribe (topic: string | string[], callback: PacketCallback): this
+
+  /**
+   * end - close connection
+   *
+   * @returns {MqttClient} this - for chaining
+   * @param {Boolean} force - do not wait for all in-flight messages to be acked
+   * @param {Function} cb - called when the client has been closed
+   *
+   * @api public
+   */
+  public end (force?: boolean, cb?: boolean): this
+
+  /**
+   * Handle messages with backpressure support, one at a time.
+   * Override at will.
+   *
+   * @param packet packet the packet
+   * @param callback callback call when finished
+   * @api public
+   */
+  public handleMessage (packet: Packet, callback: PacketCallback): void
+
+  /**
+   * getLastMessageId
+   */
+  public getLastMessageId (): number
+}
+export { IClientOptions }

types/lib/connect/index.d.ts

@@ -0,0 +1,10 @@
+import { IClientOptions, MqttClient } from '../client'
+/**
+ * connect - connect to an MQTT broker.
+ *
+ * @param {String} [brokerUrl] - url of the broker, optional
+ * @param {Object} opts - see MqttClient#constructor
+ */
+declare function connect (brokerUrl?: string | any, opts?: IClientOptions): MqttClient
+export { connect }
+export { MqttClient }

types/lib/store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * In-memory implementation of the message store
+ * This can actually be saved into files.
+ *
+ */
+declare class Store {
+  constructor ()
+
+  /**
+   * Adds a packet to the store, a packet is
+   * anything that has a messageId property.
+   *
+   */
+  public put (packet: any, cb?: Function): this
+
+  /**
+   * Creates a stream with all the packets in the store
+   *
+   */
+  public createStream (): any
+
+  /**
+   * deletes a packet from the store.
+   */
+  public del (packet: any, cb: Function): this
+
+  /**
+   * get a packet from the store.
+   */
+  public get (packet: any, cb: Function): this
+
+  /**
+   * Close the store
+   */
+  public close (cb: Function): void
+}
+export { Store }