Merge pull request #170 from particle-iot/feature/sc-121448/configure-typescript-with-just-checkjs

feature/sc-121448/configure-typescript-with-just-checkjs

Author: CarlosHdez

package-lock.json

@@ -7,12 +7,13 @@
     "babel-watch": "babel src -d lib --watch --source-maps",
     "prepublish": "npm run lint && npm run compile",
     "compile": "babel src -sd lib",
-    "test": "npm run lint && npm run test:unit",
+    "test": "npm run lint && npm run typecheck && npm run test:unit",
     "test:ci": "npm run lint && npm run test:unit -- --forbid-only && npm run coverage",
     "test:unit": "mocha test/ -R spec --compilers js:babel-register",
     "test:unit:silent": "npm run test:unit > tmp/test-unit-log.txt 2>&1",
     "test:browser": "karma start --single-run",
     "test:watch": "npm run test:unit -- --watch",
+    "typecheck": "tsc --noEmit",
     "coverage": "nyc --reporter=text --include='src/**/*.js' --temp-dir=./tmp/ --check-coverage --lines 91 npm run test:unit:silent",
     "lint": "eslint . --ext .js --format unix --ignore-path .gitignore --ignore-pattern \"dist/*\"",
     "lint:fix": "npm run lint -- --fix",
@@ -46,6 +47,7 @@
   ],
   "license": "Apache-2.0",
   "devDependencies": {
+    "@types/node": "^20.5.9",
     "babel-cli": "^6.9.0",
     "babel-eslint": "^6.0.4",
     "babel-plugin-add-module-exports": "^0.1.2",
@@ -73,6 +75,7 @@
     "should": "^9.0.0",
     "sinon": "^7.2.5",
     "sinon-chai": "^3.7.0",
+    "typescript": "^5.2.2",
     "watchify": "^3.7.0"
   },
   "dependencies": {

package.json

@@ -32,7 +32,7 @@ import packageJson from '../package.json';
 
 /**
  * The possible response from an API request
- * @typedef {JSONResponse|Buffer|arrayBuffer} RequestResponse	The type is based on
+ * @typedef {JSONResponse|Buffer|ArrayBuffer} RequestResponse	The type is based on
  * the request config and whether is on browser or node
  */
 
@@ -57,11 +57,12 @@ export default class Agent {
 
 	/**
 	 * Make a GET request
-	 * @param {string} uri		The URI to request
-	 * @param {string} [auth]	Authorization token to use
-	 * @param {object} [headers]	Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-	 * @param {object} [query] Key/Value pairs of query params
-	 * @param {object} [context]	The invocation context, describing the tool and project
+	 * @param {object} params		Configurations to customize the request
+	 * @param {string} params.uri		The URI to request
+	 * @param {string|object} [params.auth]	Authorization token to use
+	 * @param {object} [params.headers]	Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
+	 * @param {string|object} [params.query] Key/Value pairs of query params or a correctly formatted string
+	 * @param {object} [params.context]	The invocation context, describing the tool and project
 	 * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
 	 */
 	get({ uri, auth, headers, query, context }) {
@@ -70,11 +71,12 @@ export default class Agent {
 
 	/**
 	 * Make a HEAD request
-	 * @param {string} uri		The URI to request
-	 * @param {string} [auth]	Authorization token to use
-	 * @param {object} [headers]	Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-	 * @param {object} [query] Key/Value pairs of query params
-	 * @param {object} [context]	The invocation context, describing the tool and project
+	 * @param {object} params		Configurations to customize the request
+	 * @param {string} params.uri		The URI to request
+	 * @param {string|object} [params.auth]	Authorization token to use
+	 * @param {object} [params.headers]	Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
+	 * @param {string|object} [params.query] Key/Value pairs of query params or a correctly formatted string
+	 * @param {object} [params.context]	The invocation context, describing the tool and project
 	 * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
 	 */
 	head({ uri, auth, headers, query, context }) {
@@ -83,11 +85,12 @@ export default class Agent {
 
 	/**
 	 * Make a POST request
-	 * @param {string} uri		The URI to request
-	 * @param {string} [auth]	Authorization token to use
-	 * @param {object} [headers]	Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-	 * @param {object} [data] Payload to send in the request body in JSON format
-	 * @param {object} [context]	The invocation context, describing the tool and project
+	 * @param {object} params		Configurations to customize the request
+	 * @param {string} params.uri		The URI to request
+	 * @param {string|object} [params.auth]	Authorization token to use
+	 * @param {object} [params.headers]	Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
+	 * @param {object} [params.data]	Key/Value pairs of query params or a correctly formatted string
+	 * @param {object} [params.context]	The invocation context, describing the tool and project
 	 * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
 	 */
 	post({ uri, headers, data, auth, context }) {
@@ -96,11 +99,12 @@ export default class Agent {
 
 	/**
 	 * Make a PUT request
-	 * @param {string} uri		The URI to request
-	 * @param {string} [auth]	Authorization token to use
-	 * @param {object} [headers]	Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-	 * @param {object} [data] Payload to send in the request body in JSON format
-	 * @param {object} [context]	The invocation context, describing the tool and project
+	 * @param {object} params		Configurations to customize the request
+	 * @param {string} params.uri		The URI to request
+	 * @param {string|object} [params.auth]	Authorization token to use
+	 * @param {object} [params.headers]	Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
+	 * @param {object} [params.data]	Key/VAlue pairs of query params or a correctly formatted string
+	 * @param {object} [params.context]	The invocation context, describing the tool and project
 	 * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
 	 */
 	put({ uri, auth, headers, data, context }) {
@@ -109,11 +113,12 @@ export default class Agent {
 
 	/**
 	 * Make a DELETE request
-	 * @param {string} uri		The URI to request
-	 * @param {string} [auth]	Authorization token to use
-	 * @param {object} [headers]	Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-	 * @param {object} [data] Payload to send in the request body in JSON format
-	 * @param {object} [context]	The invocation context, describing the tool and project
+	 * @param {object} params		Configurations to customize the request
+	 * @param {string} params.uri		The URI to request
+	 * @param {string|object} [params.auth]	Authorization token to use
+	 * @param {object} [params.headers]	Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
+	 * @param {object} [params.data]	Key/Value pairs of query params or a correctly formatted string
+	 * @param {object} [params.context]	The invocation context, describing the tool and project
 	 * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
 	 */
 	delete({ uri, auth, headers, data, context }) {
@@ -122,17 +127,17 @@ export default class Agent {
 
 	/**
 	 *
-	 * @param {Object} config		An obj with all the possible request configurations
-	 * @param {String} config.uri		The URI to request
-	 * @param {String} config.method        The method used to request the URI, should be in uppercase.
-	 * @param {Object} config.headers       Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
-	 * @param {Object} config.data          Arbitrary data to send as the body.
-	 * @param {Object} config.auth          Authorization
-	 * @param {String} config.query         Query parameters
-	 * @param {Object} config.form          Form fields
-	 * @param {Object} config.files         array of file names and file content
-	 * @param {Object} config.context       the invocation context, describing the tool and project.
-	 * @param {boolean} config.isBuffer	Indicate if the response should be treated as Buffer instead of JSON
+	 * @param {object} config			An obj with all the possible request configurations
+	 * @param {string} config.uri			The URI to request
+	 * @param {string} config.method        	The method used to request the URI, should be in uppercase.
+	 * @param {object} [config.headers]		Key/Value pairs like `{ 'X-FOO': 'foo', X-BAR: 'bar' }` to send as headers.
+	 * @param {object} [config.data]		Arbitrary data to send as the body.
+	 * @param {string|object} [config.auth]         Authorization
+	 * @param {string|object} [config.query]	Query parameters
+	 * @param {object} [config.form]		Form fields
+	 * @param {object} [config.files]		Array of file names and file content
+	 * @param {object} [config.context]		The invocation context, describing the tool and project.
+	 * @param {boolean} [config.isBuffer=false]	Indicate if the response should be treated as Buffer instead of JSON
 	 * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
 	 */
 	request({
@@ -156,7 +161,7 @@ export default class Agent {
 	 * Promises to send the request and retreive the response.
 	 * @param {[string, object]} requestParams	First argument is the URI to request, the second one are the options.
 	 * @param {boolean} isBuffer Indicate if the response body should be returned as a Buffer (Node) / ArrayBuffer (browser) instead of JSON
-	 * @param {Fetch} [makerequest] The fetch function to use. Override for testing.
+	 * @param {function} [makerequest=fetch] The fetch function to use. Override for testing.
 	 * @returns {Promise<RequestResponse, RequestError>} A promise that resolves with either the requested data or an error object
 	 * @private
 	 */
@@ -213,6 +218,11 @@ export default class Agent {
 			});
 	}
 
+	/**
+	 * Generate the params in a format valid for 'fetch'
+	 * @returns {[string, object]} The uri to make the request too, and extra configs
+	 * @private
+	 */
 	_buildRequest({ uri, method, headers, data, auth, query, form, files, context }){
 		let actualUri = uri;
 		if (this.baseUrl && uri[0] === '/') {
@@ -228,6 +238,7 @@ export default class Agent {
 		let body;
 		let contentTypeHeader;
 		if (files){
+			// @ts-ignore
 			contentTypeHeader = {}; // Needed to allow fetch create its own
 			body = this._getFromData(files, form);
 		} else if (form){
@@ -352,7 +363,7 @@ export default class Agent {
 
 	/**
 	 * Adds an authorization header.
-	 * @param {string}  auth    The authorization bearer token.
+	 * @param {string|object}  auth    The authorization bearer token.
 	 * @returns {object} The original request.
 	 */
 	_getAuthorizationHeader(auth){

src/Agent.js

@@ -4,7 +4,8 @@ import Library from './Library';
 
 export default class Client {
 	constructor({ auth, api = new Particle() }){
-		Object.assign(this, { auth, api });
+		this.auth = auth;
+		this.api = api;
 	}
 
 	ready(){
@@ -84,8 +85,9 @@ export default class Client {
 
 	/**
 	 * Delete an entire published library
-	 * @param  {String} $0.name Name of the library to delete
-	 * @param  {String} $0.force Key to force deleting a public library
+	 * @param {object} params	Specific params of the library to delete
+	 * @param {string} params.name	Name of the library to delete
+	 * @param {string} params.force	Key to force deleting a public library
 	 * @returns {Promise} A promise
 	 */
 	deleteLibrary({ name, force }){
@@ -117,8 +119,9 @@ export default class Client {
 	}
 
 	/**
-	 * @param {String} $0.deviceId Device ID or Name
-	 * @param {Boolean} $0.signal   Signal on or off
+	 * @param {object} params
+	 * @param {string} params.deviceId	Device ID or Name
+	 * @param {boolean} params.signal	Signal on or off
 	 * @returns {Promise} A promise
 	 * @deprecated Will be removed in 6.5
 	 */
@@ -156,7 +159,7 @@ export default class Client {
 			}, () => {});
 	}
 
-	trackingIdentity({ full=false, context }={}){
+	trackingIdentity({ full = false, context = undefined }={}){
 		return this.api.trackingIdentity({ full, context, auth: this.auth })
 			.then(payload => {
 				return payload.body;

src/Client.js

@@ -32,6 +32,7 @@ class EventStream extends EventEmitter {
 				path: `${path}?access_token=${this.token}`,
 				method: 'get',
 				port: parseInt(port, 10) || (isSecure ? 443 : 80),
+				// @ts-ignore
 				mode: 'prefer-streaming'
 			});
 
@@ -70,7 +71,9 @@ class EventStream extends EventEmitter {
 							// since we are already about to reject the promise anyway
 						} finally {
 							let errorDescription = `HTTP error ${statusCode} from ${this.uri}`;
+							// @ts-ignore
 							if (body && body.error_description) {
+								// @ts-ignore
 								errorDescription += ' - ' + body.error_description;
 							}
 							reject({ statusCode, errorDescription, body });

src/EventStream.js

@@ -23,6 +23,7 @@ export default class Library {
 		if (!this.downloadUrl) {
 			return Promise.reject(new Error('No download URL for this library'));
 		}
+		// @ts-ignore
 		return this.client.downloadFile(this.downloadUrl);
 	}