Deprecate DataStore

docs/_reference/BaseAPIClient.md

@@ -12,7 +12,7 @@ permalink: /reference/BaseAPIClient
     * [.transport](#BaseAPIClient+transport) : <code>BaseAPIClient~transportFn</code>
     * [.retryConfig](#BaseAPIClient+retryConfig) : <code>Object</code>
     * [._createFacets()](#BaseAPIClient+_createFacets)
-    * [.registerDataStore(dataStore)](#BaseAPIClient+registerDataStore)
+    * ~~[.registerDataStore(dataStore)](#BaseAPIClient+registerDataStore)~~
     * [._callTransport(task, queueCb)](#BaseAPIClient+_callTransport)
 
 <a name="new_BaseAPIClient_new"></a>
@@ -27,10 +27,10 @@ Base client for both the RTM and web APIs.
 | [opts] | <code>Object</code> |  |  |
 | [opts.slackAPIUrl] | <code>string</code> | <code>&quot;https://slack.com/api/&quot;</code> | The Slack API URL. |
 | [opts.transport] | <code>BaseAPIClient~transportFn</code> |  | Function to call to make an HTTP call to the Slack API. |
-| [opts.logLevel] | <code>string</code> |  | The log level for the logger. |
+| [opts.logLevel] | <code>string</code> | <code>&quot;info&quot;</code> | The log level for the logger. |
 | [opts.logger] | <code>BaseAPIClient~logFn</code> |  | Function to use for log calls, takes (logLevel, logString) params. |
-| opts.maxRequestConcurrency | <code>number</code> |  | The max # of concurrent requests to make to Slack's     API's, defaults to 3. |
-| opts.retryConfig | <code>Object</code> |  | The configuration to use for the retry operation,     {@see https://github.com/tim-kos/node-retry} |
+| [opts.maxRequestConcurrency] | <code>number</code> | <code>3</code> | The max # of concurrent requests to make to Slack's API |
+| [opts.retryConfig] | <code>Object</code> |  | The configuration to use for the retry operation, see [node-retry](https://github.com/tim-kos/node-retry) for more details. |
 
 <a name="BaseAPIClient+slackAPIUrl"></a>
 
@@ -62,10 +62,10 @@ Initializes each of the API facets.
 **Access:** protected  
 <a name="BaseAPIClient+registerDataStore"></a>
 
-### baseAPIClient.registerDataStore(dataStore)
-Attaches a data-store to the client instance.
+### ~~baseAPIClient.registerDataStore(dataStore)~~
+***Deprecated***
 
-NOTE: In next major version, remove from BaseAPIClient. Only used in RTMClient.
+Attaches a data-store to the client instance.
 
 **Kind**: instance method of <code>[BaseAPIClient](#BaseAPIClient)</code>  
 

docs/_reference/RTMClient.md

@@ -6,7 +6,7 @@ permalink: /reference/RTMClient
 **Kind**: global class  
 
 * [RTMClient](#RTMClient)
-    * [new RTMClient(token, opts)](#new_RTMClient_new)
+    * [new RTMClient(token, [opts])](#new_RTMClient_new)
     * [._socketFn](#RTMClient+_socketFn) : <code>function</code>
     * [.ws](#RTMClient+ws) : <code>Object</code>
     * [.connected](#RTMClient+connected) : <code>boolean</code>
@@ -38,25 +38,25 @@ permalink: /reference/RTMClient
 
 <a name="new_RTMClient_new"></a>
 
-### new RTMClient(token, opts)
+### new RTMClient(token, [opts])
 Creates a new instance of RTM client.
 
 
-| Param | Type | Description |
-| --- | --- | --- |
-| token | <code>String</code> | The token to use for connecting |
-| opts | <code>Object</code> |  |
-| opts.socketFn | <code>function</code> | A function to call, passing in a websocket URL, that should return a websocket instance connected to that URL |
-| opts.dataStore | <code>Object</code> | A store to cache Slack info, e.g. channels, users etc. in. Pass null or false to use no store |
-| opts.autoReconnect | <code>Boolean</code> | Whether or not to automatically reconnect when the connection closes. Defaults to true |
-| opts.useRtmConnect | <code>Boolean</code> | True to use rtm.connect rather than rtm.start |
-| opts.retryConfig | <code>Object</code> | The retry policy to use, defaults to forever with exponential backoff {@see https://github.com/SEAPUNK/node-retry} |
-| opts.maxReconnectionAttempts | <code>Number</code> | DEPRECATED: Use retryConfig instead |
-| opts.reconnectionBackoff | <code>Number</code> | DEPRECATED: Use retryConfig instead |
-| opts.wsPingInterval | <code>Number</code> | The time to wait between pings with the server |
-| opts.maxPongInterval | <code>Number</code> | The max time (in ms) to wait for a pong before reconnecting |
-| opts.logLevel | <code>String</code> | The log level for the logger |
-| opts.logger | <code>function</code> | Function to use for log calls, takes (logLevel, logString) parameters |
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| token | <code>string</code> |  | The token to use for connecting |
+| [opts] | <code>Object</code> |  |  |
+| [opts.socketFn] | <code>RTMClient~socketFn</code> |  | A function to call, passing in a websocket URL, that should return a websocket instance connected to that URL |
+| [opts.dataStore] | <code>[SlackDataStore](#SlackDataStore)</code> &#124; <code>null</code> &#124; <code>false</code> |  | A store to cache Slack info. Recommended value is `false`. Default value is an instance of [SlackMemoryDataStore](#SlackMemoryDataStore). |
+| [opts.autoReconnect] | <code>boolean</code> | <code>true</code> | Whether or not to automatically reconnect when the connection closes |
+| [opts.useRtmConnect] | <code>boolean</code> | <code>false</code> | Whether to use rtm.connect rather than rtm.start. Recommended value is `true`. |
+| [opts.retryConfig] | <code>Object</code> |  | The retry policy to use, defaults to forever with exponential backoff, see [node-retry](https://github.com/SEAPUNK/node-retry) for more details. |
+| [opts.maxReconnectionAttempts] | <code>number</code> |  | DEPRECATED: Use retryConfig instead |
+| [opts.reconnectionBackoff] | <code>number</code> |  | DEPRECATED: Use retryConfig instead |
+| [opts.wsPingInterval] | <code>number</code> | <code>5000</code> | The time (in ms) to wait between pings with the server |
+| [opts.maxPongInterval] | <code>number</code> |  | The max time (in ms) to wait for a pong before reconnecting |
+| [opts.logLevel] | <code>string</code> | <code>&quot;info&quot;</code> | The log level for the logger |
+| [opts.logger] | <code>RTMClient~logFn</code> |  | Function to use for log calls, takes (logLevel, logString) parameters |
 
 <a name="RTMClient+_socketFn"></a>
 

docs/_reference/SlackDataStore.md

@@ -3,9 +3,11 @@ layout: page
 title: SlackDataStore
 permalink: /reference/SlackDataStore
 ---
+***Deprecated***
+
 **Kind**: global class  
 
-* [SlackDataStore](#SlackDataStore)
+* ~~[SlackDataStore](#SlackDataStore)~~
     * [new SlackDataStore(opts)](#new_SlackDataStore_new)
     * [.logger](#SlackDataStore+logger) : <code>function</code>
     * [.registerMessageHandler(event, handler)](#SlackDataStore+registerMessageHandler)

docs/_reference/SlackMemoryDataStore.md

@@ -3,9 +3,11 @@ layout: page
 title: SlackMemoryDataStore
 permalink: /reference/SlackMemoryDataStore
 ---
+***Deprecated***
+
 **Kind**: global class  
 
-* [SlackMemoryDataStore](#SlackMemoryDataStore)
+* ~~[SlackMemoryDataStore](#SlackMemoryDataStore)~~
     * [.users](#SlackMemoryDataStore+users) : <code>Object</code>
     * [.channels](#SlackMemoryDataStore+channels) : <code>Object</code>
     * [.dms](#SlackMemoryDataStore+dms) : <code>Object</code>

docs/_reference/WebAPIClient.md

@@ -19,7 +19,7 @@ Slack Web API client.
 | --- | --- | --- |
 | token |  | The Slack API token to use with this client. |
 | [opts] | <code>Object</code> |  |
-| opts.retryConfig | <code>Object</code> | The configuration to use for the retry operation,     {@see https://github.com/tim-kos/node-retry} |
+| [opts.retryConfig] | <code>Object</code> | The configuration to use for the retry operation, see [node-retry](https://github.com/tim-kos/node-retry) for more details. |
 
 <a name="WebAPIClient+_createFacets"></a>
 

lib/clients/client.js

@@ -26,12 +26,12 @@ var retryPolicies = require('./retry-policies');
  * @param {string} [opts.slackAPIUrl=https://slack.com/api/] - The Slack API URL.
  * @param {BaseAPIClient~transportFn} [opts.transport] - Function to call to make an HTTP call to
  * the Slack API.
- * @param {string} [opts.logLevel] The log level for the logger.
+ * @param {string} [opts.logLevel=info] The log level for the logger.
  * @param {BaseAPIClient~logFn} [opts.logger] Function to use for log calls, takes (logLevel, logString) params.
- * @param {number} opts.maxRequestConcurrency The max # of concurrent requests to make to Slack's
- *     API's, defaults to 3.
- * @param {Object} opts.retryConfig The configuration to use for the retry operation,
- *     {@see https://github.com/tim-kos/node-retry}
+ * @param {number} [opts.maxRequestConcurrency=3] The max # of concurrent requests to make to Slack's
+ * API
+ * @param {Object} [opts.retryConfig] The configuration to use for the retry operation,
+ * see {@link https://github.com/tim-kos/node-retry|node-retry} for more details.
  * @constructor
  */
 function BaseAPIClient(token, opts) {
@@ -92,11 +92,14 @@ BaseAPIClient.prototype._createFacets = function _createFacets() {
 /**
  * Attaches a data-store to the client instance.
  *
- * NOTE: In next major version, remove from BaseAPIClient. Only used in RTMClient.
- *
+ * @deprecated SlackDataStore interface will be removed in v4.0.0. See
+ * {@link https://github.com/slackapi/node-slack-sdk/wiki/DataStore-v3.x-Migration-Guide|the migration guide}
+ * for details.
  * @param {SlackDataStore} dataStore
  */
 BaseAPIClient.prototype.registerDataStore = function registerDataStore(dataStore) {
+  this.logger('warn', 'SlackDataStore is deprecated and will be removed in the next major ' +
+    'version. See project documentation for a migration guide.');
   this.dataStore = dataStore;
   this.logger('debug', 'BaseAPIClient registerDataStore end');
 };

lib/clients/rtm/client.js

@@ -40,24 +40,27 @@ var retryPolicyFromOptions = require('../retry-policies').retryPolicyFromOptions
 
 /**
  * Creates a new instance of RTM client.
- * @param {String} token                The token to use for connecting
- * @param {Object} opts
- * @param {Function} opts.socketFn      A function to call, passing in a websocket URL, that should
- * return a websocket instance connected to that URL
- * @param {Object} opts.dataStore       A store to cache Slack info, e.g. channels, users etc. in.
- * Pass null or false to use no store
- * @param {Boolean} opts.autoReconnect  Whether or not to automatically reconnect when the connection
- * closes. Defaults to true
- * @param {Boolean} opts.useRtmConnect  True to use rtm.connect rather than rtm.start
- * @param {Object} opts.retryConfig     The retry policy to use, defaults to forever with exponential
- * backoff {@see https://github.com/SEAPUNK/node-retry}
- * @param {Number} opts.maxReconnectionAttempts DEPRECATED: Use retryConfig instead
- * @param {Number} opts.reconnectionBackoff     DEPRECATED: Use retryConfig instead
- * @param {Number} opts.wsPingInterval  The time to wait between pings with the server
- * @param {Number} opts.maxPongInterval The max time (in ms) to wait for a pong before reconnecting
- * @param {String} opts.logLevel        The log level for the logger
- * @param {Function} opts.logger        Function to use for log calls, takes (logLevel, logString)
- * parameters
+ * @param {string} token - The token to use for connecting
+ * @param {Object} [opts]
+ * @param {RTMClient~socketFn} [opts.socketFn] - A function to call, passing in a websocket URL,
+ * that should return a websocket instance connected to that URL
+ * @param {SlackDataStore|null|false} [opts.dataStore] - A store to cache Slack info. Recommended
+ * value is `false`. Default value is an instance of {@link SlackMemoryDataStore}.
+ * @param {boolean} [opts.autoReconnect=true] - Whether or not to automatically reconnect when the
+ * connection closes
+ * @param {boolean} [opts.useRtmConnect=false] - Whether to use rtm.connect rather than rtm.start.
+ * Recommended value is `true`.
+ * @param {Object} [opts.retryConfig] - The retry policy to use, defaults to forever with
+ * exponential backoff, see {@link https://github.com/SEAPUNK/node-retry|node-retry} for more details.
+ * @param {number} [opts.maxReconnectionAttempts] - DEPRECATED: Use retryConfig instead
+ * @param {number} [opts.reconnectionBackoff] - DEPRECATED: Use retryConfig instead
+ * @param {number} [opts.wsPingInterval=5000] - The time (in ms) to wait between pings with the
+ * server
+ * @param {number} [opts.maxPongInterval] - The max time (in ms) to wait for a pong before
+ * reconnecting
+ * @param {string} [opts.logLevel=info] - The log level for the logger
+ * @param {RTMClient~logFn} [opts.logger] - Function to use for log calls, takes
+ * (logLevel, logString) parameters
  * @constructor
  */
 function RTMClient(token, opts) {
@@ -169,7 +172,7 @@ RTMClient.prototype.activeTeamId = undefined;
 
 
 /**
- * @type {SlackDataStore}
+ * @type {?SlackDataStore}
  */
 RTMClient.prototype.dataStore = undefined;
 

lib/clients/web/client.js

@@ -13,10 +13,10 @@ var facets = require('./facets/index');
 /**
  * Slack Web API client.
  *
- * @param token The Slack API token to use with this client.
- * @param {Object=} opts
- * @param {Object} opts.retryConfig The configuration to use for the retry operation,
- *     {@see https://github.com/tim-kos/node-retry}
+ * @param token - The Slack API token to use with this client.
+ * @param {Object} [opts]
+ * @param {Object} [opts.retryConfig] - The configuration to use for the retry operation,
+ * see {@link https://github.com/tim-kos/node-retry|node-retry} for more details.
  * @constructor
  */
 function WebAPIClient(token, opts) {

lib/data-store/data-store.js

@@ -17,6 +17,9 @@ var models = require('../models');
 
 /**
  *
+ * @deprecated SlackDataStore interface will be removed in v4.0.0. See
+ * {@link https://github.com/slackapi/node-slack-sdk/wiki/DataStore-v3.x-Migration-Guide|the migration guide}
+ * for details.
  * @param {Object} opts
  * @param {string=} opts.logLevel The log level for the logger.
  * @param {Function=} opts.logger Function to use for log calls, takes (logLevel, logString) params.
@@ -31,6 +34,9 @@ function SlackDataStore(opts) {
    */
   this.logger = dataStoreOpts.logger || getLogger(dataStoreOpts.logLevel);
 
+  this.logger('warn', 'SlackDataStore is deprecated and will be removed in the next major ' +
+  'version. See project documentation for a migration guide.');
+
   forEach(messageHandlers, bind(function anonRegisterMessageHandler(handler, event) {
     this.registerMessageHandler(event, handler);
   }, this));

lib/data-store/memory-data-store.js

@@ -13,6 +13,9 @@ var models = require('../models');
 
 /**
  *
+ * @deprecated SlackMemoryDataStore will be removed in v4.0.0. See
+ * {@link https://github.com/slackapi/node-slack-sdk/wiki/DataStore-v3.x-Migration-Guide|the migration guide}
+ * for details.
  * @constructor
  */
 function SlackMemoryDataStore(opts) {