From 65f231a4f97454c8071909c6f5a3b4eb45452a69 Mon Sep 17 00:00:00 2001 From: philippschulte Date: Thu, 21 Dec 2017 21:57:04 -0800 Subject: [PATCH] refactor(package): Rename three package methods Rename #serviceList, #versionList, and #domainList methods to #readServices, #readVersions, and #readDomains --- README.md | 103 +++++++++-------- src/index.js | 105 +++++------------- ...domainList.test.js => readDomains.test.js} | 8 +- ...rviceList.test.js => readServices.test.js} | 8 +- ...rsionList.test.js => readVersions.test.js} | 8 +- ...st.response.js => readDomains.response.js} | 2 +- ...t.response.js => readServices.response.js} | 2 +- ...t.response.js => readVersions.response.js} | 2 +- 8 files changed, 100 insertions(+), 138 deletions(-) rename test/{domainList.test.js => readDomains.test.js} (85%) rename test/{serviceList.test.js => readServices.test.js} (85%) rename test/{versionList.test.js => readVersions.test.js} (87%) rename test/response/{domainList.response.js => readDomains.response.js} (81%) rename test/response/{serviceList.response.js => readServices.response.js} (94%) rename test/response/{versionList.response.js => readVersions.response.js} (91%) diff --git a/README.md b/README.md index d4c3416c..9a928206 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,13 @@ [![NPM](https://nodei.co/npm/fastly-promises.png)](https://nodei.co/npm/fastly-promises/) +## Problem + +There are already some promise based clients on [NPM](https://www.npmjs.com/) for the [Fastly](https://docs.fastly.com/api/) API but either way there are not well documented, tested, or don't provide the functionality I needed. The callback based [fastly](https://www.npmjs.com/package/fastly) package is still the most used client on [NPM](https://www.npmjs.com/). However, I needed a client which allows me to perform request sequentially and parallelly without ending up in an untamable [callback hell](http://callbackhell.com/)! + +## Solution + +The `fastly-promises` package uses the promise based HTTP client [Axios](https://www.npmjs.com/package/axios) to perform requests to the [Fastly](https://docs.fastly.com/api/) API. [Axios](https://www.npmjs.com/package/axios) supports the native JavaScript [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) API and automatically transforms the data into JSON. Each `fastly-promises` API method returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) which represents either the completion or failure of the request. This allows us to implement modern JavaScript asynchronous programming patterns like `async/await` for a clean and simple control flow! ## Table of Contents @@ -77,7 +84,7 @@ Each `fastly-promises` API method returns the following response object: ### Promises -This example does the following: +The following example does the following: 1. Get all the versions 2. Filter out the active version @@ -87,10 +94,10 @@ This example does the following: ```javascript function handler() { - service_1.versionList() + service_1.readVersions() .then(versions => { - const active = versions.data.filter(version => version.active === true)[0]; - return service_1.domainList(active.number); + const active = versions.data.filter(version => version.active)[0]; + return service_1.readDomains(active.number); }) .then(domains => { return Promise.all(domains.data.map(domain => service_1.purgeIndividual(domain.name))); @@ -111,9 +118,9 @@ This is the same example but uses the `async/await` syntax instead! ```javascript async function handler() { try { - const versions = await serivce_2.versionList(); - const active = versions.data.filter(version => version.active === true)[0]; - const domains = await serivce_2.domainList(active.number); + const versions = await serivce_2.readVersions(); + const active = versions.data.filter(version => version.active)[0]; + const domains = await serivce_2.readDomains(active.number); const purges = await Promise.all(domains.data.map(domain => serivce_2.purgeIndividual(domain.name))); purges.forEach(purge => console.log(purge.statusText)); @@ -137,14 +144,14 @@ async function handler() { - [.dataCenters()](#dataCenters) - [.publicIpList()](#publicIpList) - [.edgeCheck(url)](#edgeCheck) - - [.serviceList()](#serviceList) - - [.versionList()](#versionList) - - [.domainList(version)](#domainList) + - [.readServices()](#readServices) + - [.readVersions()](#readVersions) + - [.readDomains(version)](#readDomains) - [.domainCheckAll(version)](#domainCheckAll) -### [constructor(token, service_id)](https://github.com/philippschulte/fastly-promises/blob/a9ca4b9f69bca63c62ca2be0ee5e8752c4536adf/src/index.js#L15) +### [constructor(token, service_id)](https://github.com/philippschulte/fastly-promises/blob/a9ca4b9f69bca63c62ca2be0ee5e8752c4536adf/src/index.js#L12) *Method for creating and initializing a new fastly-promises instance.* @@ -158,13 +165,13 @@ const instance = fastly('token', 'service_id'); ``` **Kind**: method -**Param**: token => `string` -**Param**: service_id => `string` -**Return**: instance => `object` +**Param**: token {string} The Fastly API token. +**Param**: service_id {string} The Fastly service ID. +**Return**: instance {object} A new fastly-promises instance. -### [.request.defaults.baseURL](https://github.com/philippschulte/fastly-promises/blob/a9ca4b9f69bca63c62ca2be0ee5e8752c4536adf/src/index.js#L18) +### [.request.defaults.baseURL](https://github.com/philippschulte/fastly-promises/blob/a9ca4b9f69bca63c62ca2be0ee5e8752c4536adf/src/index.js#L15) *The main entry point for the Fastly API.* @@ -179,11 +186,11 @@ instance.request.defaults.baseURL = 'https://api.fastly.com/v1'; ``` **Kind**: property -**Return**: url => `string` +**Return**: url {string} The main entry point for the Fastly API. -### [.request.defaults.timeout](https://github.com/philippschulte/fastly-promises/blob/a9ca4b9f69bca63c62ca2be0ee5e8752c4536adf/src/index.js#L19) +### [.request.defaults.timeout](https://github.com/philippschulte/fastly-promises/blob/a9ca4b9f69bca63c62ca2be0ee5e8752c4536adf/src/index.js#L16) *The number of milliseconds before the request times out.* @@ -197,7 +204,7 @@ instance.request.defaults.timeout = 5000; ``` **Kind**: property -**Return**: milliseconds => `number` +**Return**: milliseconds {number} The number of milliseconds before the request times out. @@ -218,8 +225,8 @@ instance.purgeIndividual('www.example.com') ``` **Kind**: method -**Param**: url => `string` -**Return**: schema => `promise` +**Param**: url {string} The URL to purge. +**Return**: schema {promise} The response object representing the completion or failure. @@ -240,7 +247,7 @@ instance.purgeAll() ``` **Kind**: method -**Return**: schema => `promise` +**Return**: schema {promise} The response object representing the completion or failure. @@ -261,8 +268,8 @@ instance.purgeKey('key_1') ``` **Kind**: method -**Param**: key => `string` -**Return**: schema => `promise` +**Param**: key {string} The surrogate key to purge. +**Return**: schema {promise} The response object representing the completion or failure. @@ -283,8 +290,8 @@ instance.purgeKeys(['key_2', 'key_3', 'key_4']) ``` **Kind**: method -**Param**: keys => `array` -**Return**: schema => `promise` +**Param**: keys {array} The array of surrogate keys to purge. +**Return**: schema {promise} The response object representing the completion or failure. @@ -305,8 +312,8 @@ instance.softPurgeIndividual('www.example.com/images') ``` **Kind**: method -**Param**: url => `string` -**Return**: schema => `promise` +**Param**: url {string} The URL to soft purge. +**Return**: schema {promise} The response object representing the completion or failure. @@ -327,8 +334,8 @@ instance.softPurgeKey('key_5') ``` **Kind**: method -**Param**: key => `string` -**Return**: schema => `promise` +**Param**: key {string} The surrogate key to soft purge. +**Return**: schema {promise} The response object representing the completion or failure. @@ -349,7 +356,7 @@ instance.dataCenters() ``` **Kind**: method -**Return**: schema => `promise` +**Return**: schema {promise} The response object representing the completion or failure. @@ -370,7 +377,7 @@ instance.publicIpList() ``` **Kind**: method -**Return**: schema => `promise` +**Return**: schema {promise} The response object representing the completion or failure. @@ -391,19 +398,19 @@ instance.edgeCheck('api.example.com') ``` **Kind**: method -**Param**: url => `string` -**Return**: schema => `promise` +**Param**: url {string} Full URL (host and path) to check on all nodes. If protocol is omitted, http will be assumed. +**Return**: schema {promise} The response object representing the completion or failure. - + -### [.serviceList()](https://docs.fastly.com/api/config#service_74d98f7e5d018256e44d1cf820388ef8) +### [.readServices()](https://docs.fastly.com/api/config#service_74d98f7e5d018256e44d1cf820388ef8) *List all services.* **Example**: ```javascript -instance.serviceList() +instance.readServices() .then(res => { console.log(res.data); }) @@ -413,18 +420,18 @@ instance.serviceList() ``` **Kind**: method -**Return**: schema => `promise` +**Return**: schema {promise} The response object representing the completion or failure. - + -### [.versionList()](https://docs.fastly.com/api/config#version_dfde9093f4eb0aa2497bbfd1d9415987) +### [.readVersions()](https://docs.fastly.com/api/config#version_dfde9093f4eb0aa2497bbfd1d9415987) *List the versions for a particular service.* **Example**: ```javascript -instance.versionList() +instance.readVersions() .then(res => { const active = res.data.filter(version => version.active === true); console.log(active); @@ -435,18 +442,18 @@ instance.versionList() ``` **Kind**: method -**Return**: schema => `promise` +**Return**: schema {promise} The response object representing the completion or failure. - + -### [.domainList(version)](https://docs.fastly.com/api/config#domain_6d340186666771f022ca20f81609d03d) +### [.readDomains(version)](https://docs.fastly.com/api/config#domain_6d340186666771f022ca20f81609d03d) *List all the domains for a particular service and version.* **Example**: ```javascript -instance.domainList('182') +instance.readDomains('182') .then(res => { console.log(res.data); }) @@ -456,8 +463,8 @@ instance.domainList('182') ``` **Kind**: method -**Param**: version => `string` -**Return**: schema => `promise` +**Param**: version {string} The current version of a service. +**Return**: schema {promise} The response object representing the completion or failure. @@ -478,8 +485,8 @@ instance.domainCheckAll('182') ``` **Kind**: method -**Param**: version => `string` -**Return**: schema => `promise` +**Param**: version {string} The current version of a service. +**Return**: schema {promise} The response object representing the completion or failure. ## Tests diff --git a/src/index.js b/src/index.js index d18b4941..bc637ef8 100644 --- a/src/index.js +++ b/src/index.js @@ -6,11 +6,8 @@ const config = require('./config'); class Fastly { /** * The constructor method for creating a fastly-promises instance. - * - * @name constructor - * @method - * @param token {Sting} - * @param service_id {String} + * @param token {String} The Fastly API token. + * @param service_id {String} The Fastly service ID. */ constructor(token, service_id) { this.service_id = service_id; @@ -23,11 +20,8 @@ class Fastly { /** * Instant Purge an individual URL. - * - * @name purgeIndividual - * @method - * @param url {String} - * @return {Promise} + * @param url {String} The URL to purge. + * @return {Promise} The response object representing the completion or failure. */ purgeIndividual(url = '') { return this.request.post(`/purge/${url}`); @@ -35,10 +29,7 @@ class Fastly { /** * Instant Purge everything from a service. - * - * @name purgeAll - * @method - * @return {Promise} + * @return {Promise} The response object representing the completion or failure. */ purgeAll() { return this.request.post(`/service/${this.service_id}/purge_all`); @@ -46,11 +37,8 @@ class Fastly { /** * Instant Purge a particular service of items tagged with a Surrogate Key. - * - * @name purgeKey - * @method - * @param key {String} - * @return {Promise} + * @param key {String} The surrogate key to purge. + * @return {Promise} The response object representing the completion or failure. */ purgeKey(key = '') { return this.request.post(`/service/${this.service_id}/purge/${key}`); @@ -58,11 +46,8 @@ class Fastly { /** * Instant Purge a particular service of items tagged with Surrogate Keys in a batch. - * - * @name purgeKeys - * @method - * @param keys {Array} - * @return {Promise} + * @param keys {Array} The array of surrogate keys to purge. + * @return {Promise} The response object representing the completion or failure. */ purgeKeys(keys = []) { return this.request.post(`/service/${this.service_id}/purge`, { 'surrogate_keys': keys }); @@ -70,11 +55,8 @@ class Fastly { /** * Soft Purge an individual URL. - * - * @name softPurgeIndividual - * @method - * @param url {String} - * @return {Promise} + * @param url {String} The URL to soft purge. + * @return {Promise} The response object representing the completion or failure. */ softPurgeIndividual(url = '') { return this.request.post(`/purge/${url}`, undefined, { headers: { 'Fastly-Soft-Purge': 1 } }); @@ -82,11 +64,8 @@ class Fastly { /** * Soft Purge a particular service of items tagged with a Surrogate Key. - * - * @name softPurgeKey - * @method - * @param key {String} - * @return {Promise} + * @param key {String} The surrogate key to soft purge. + * @return {Promise} The response object representing the completion or failure. */ softPurgeKey(key = '') { return this.request.post(`/service/${this.service_id}/purge/${key}`, undefined, { headers: { 'Fastly-Soft-Purge': 1 } }); @@ -94,10 +73,7 @@ class Fastly { /** * Get a list of all Fastly datacenters. - * - * @name dataCenters - * @method - * @return {Promise} + * @return {Promise} The response object representing the completion or failure. */ dataCenters() { return this.request.get('/datacenters'); @@ -105,10 +81,7 @@ class Fastly { /** * Fastly's services IP ranges. - * - * @name publicIpList - * @method - * @return {Promise} + * @return {Promise} The response object representing the completion or failure. */ publicIpList() { return this.request.get('/public-ip-list'); @@ -116,11 +89,8 @@ class Fastly { /** * Retrieve headers and MD5 hash of the content for a particular URL from each Fastly edge server. - * - * @name edgeCheck - * @method - * @param url {String} - * @return {Promise} + * @param url {String} Full URL (host and path) to check on all nodes. If protocol is omitted, http will be assumed. + * @return {Promise} The response object representing the completion or failure. */ edgeCheck(url = '') { return this.request.get(`/content/edge_check?url=${url}`); @@ -128,45 +98,33 @@ class Fastly { /** * List all services. - * - * @name serviceList - * @method - * @return {Promise} + * @return {Promise} The response object representing the completion or failure. */ - serviceList() { + readServices() { return this.request.get(`/service`); } /** * List the versions for a particular service. - * - * @name versionList - * @method - * @return {Promise} + * @return {Promise} The response object representing the completion or failure. */ - versionList() { + readVersions() { return this.request.get(`/service/${this.service_id}/version`); } /** * List all the domains for a particular service and version. - * - * @name domainList - * @method - * @param version {String} - * @return {Promise} + * @param version {String} The current version of a service. + * @return {Promise} The response object representing the completion or failure. */ - domainList(version = '') { + readDomains(version = '') { return this.request.get(`/service/${this.service_id}/version/${version}/domain`); } /** * Checks the status of all domains for a particular service and version. - * - * @name domainCheckAll - * @method - * @param version {String} - * @return {Promise} + * @param version {String} The current version of a service. + * @return {Promise} The response object representing the completion or failure. */ domainCheckAll(version = '') { return this.request.get(`/service/${this.service_id}/version/${version}/domain/check_all`); @@ -175,14 +133,11 @@ class Fastly { /** * Function to create a new fastly-promises instance. - * - * @name anonymous - * @function - * @param token {String} - * @param service_id {String} + * @param token {String} The Fastly API token. + * @param service_id {String} The Fastly service ID. * @return {Object} { - * service_id : the alphanumeric string identifying a service - * request : instance of axios with a custom config + * service_id : The alphanumeric string identifying a service + * request : Axios instance * } */ module.exports = (token = '', service_id = '') => { diff --git a/test/domainList.test.js b/test/readDomains.test.js similarity index 85% rename from test/domainList.test.js rename to test/readDomains.test.js index 17fe8c1e..be9c85f3 100644 --- a/test/domainList.test.js +++ b/test/readDomains.test.js @@ -4,18 +4,18 @@ const nock = require('nock'); const expect = require('expect'); const config = require('../src/config'); const fastlyPromises = require('../src/index'); -const response = require('./response/domainList.response'); +const response = require('./response/readDomains.response'); -describe('#domainList', () => { +describe('#readDomains', () => { const fastly = fastlyPromises('923b6bd5266a7f932e41962755bd4254', 'SU1Z0isxPaozGVKXdv0eY'); let res; nock(config.mainEntryPoint) .get('/service/SU1Z0isxPaozGVKXdv0eY/version/182/domain') - .reply(200, response.domainList); + .reply(200, response.readDomains); before(async () => { - res = await fastly.domainList('182'); + res = await fastly.readDomains('182'); }); it('response should be a status 200', () => { diff --git a/test/serviceList.test.js b/test/readServices.test.js similarity index 85% rename from test/serviceList.test.js rename to test/readServices.test.js index 37fddb65..3538fe05 100644 --- a/test/serviceList.test.js +++ b/test/readServices.test.js @@ -4,18 +4,18 @@ const nock = require('nock'); const expect = require('expect'); const config = require('../src/config'); const fastlyPromises = require('../src/index'); -const response = require('./response/serviceList.response'); +const response = require('./response/readServices.response'); -describe('#serviceList', () => { +describe('#readServices', () => { const fastly = fastlyPromises('923b6bd5266a7f932e41962755bd4254', 'SU1Z0isxPaozGVKXdv0eY'); let res; nock(config.mainEntryPoint) .get('/service') - .reply(200, response.serviceList); + .reply(200, response.readServices); before(async () => { - res = await fastly.serviceList(); + res = await fastly.readServices(); }); it('response should be a status 200', () => { diff --git a/test/versionList.test.js b/test/readVersions.test.js similarity index 87% rename from test/versionList.test.js rename to test/readVersions.test.js index c549aac2..b5f620b9 100644 --- a/test/versionList.test.js +++ b/test/readVersions.test.js @@ -4,18 +4,18 @@ const nock = require('nock'); const expect = require('expect'); const config = require('../src/config'); const fastlyPromises = require('../src/index'); -const response = require('./response/versionList.response'); +const response = require('./response/readVersions.response'); -describe('#versionList', () => { +describe('#readVersions', () => { const fastly = fastlyPromises('923b6bd5266a7f932e41962755bd4254', 'SU1Z0isxPaozGVKXdv0eY'); let res; nock(config.mainEntryPoint) .get('/service/SU1Z0isxPaozGVKXdv0eY/version') - .reply(200, response.versionList); + .reply(200, response.readVersions); before(async () => { - res = await fastly.versionList(); + res = await fastly.readVersions(); }); it('response should be a status 200', () => { diff --git a/test/response/domainList.response.js b/test/response/readDomains.response.js similarity index 81% rename from test/response/domainList.response.js rename to test/response/readDomains.response.js index 273f214b..9dd764c6 100644 --- a/test/response/domainList.response.js +++ b/test/response/readDomains.response.js @@ -1,6 +1,6 @@ 'use strict'; -module.exports.domainList = [ +module.exports.readDomains = [ { 'comment': '', 'name': 'www.example.com', diff --git a/test/response/serviceList.response.js b/test/response/readServices.response.js similarity index 94% rename from test/response/serviceList.response.js rename to test/response/readServices.response.js index 77dd0b03..17b3c9cc 100644 --- a/test/response/serviceList.response.js +++ b/test/response/readServices.response.js @@ -1,6 +1,6 @@ 'use strict'; -module.exports.serviceList = [ +module.exports.readServices = [ { 'comment': '', 'customer_id': 'x4xCwxxJxGCx123Rx5xTx', diff --git a/test/response/versionList.response.js b/test/response/readVersions.response.js similarity index 91% rename from test/response/versionList.response.js rename to test/response/readVersions.response.js index a648fe39..9dd0e501 100644 --- a/test/response/versionList.response.js +++ b/test/response/readVersions.response.js @@ -1,6 +1,6 @@ 'use strict'; -module.exports.versionList = [ +module.exports.readVersions = [ { 'active': true, 'comment': '',