refactor: Replace flow with type-check and docs

Author: trodrigues

.babelrc

@@ -3,8 +3,7 @@
     "es2015"
   ],
   "plugins": [
-    "transform-runtime",
-    "transform-flow-strip-types"
+    "transform-runtime"
   ],
   "env": {
     "test": {

lib/contentful.js

@@ -1,5 +1,3 @@
-/* @flow */
-
 /**
  * Contentful CDA SDK. Allows you to create instances of a client with access
  * to the Contentful Content Delivery API.
@@ -8,17 +6,17 @@
 
 import createHttpClient from './create-http-client'
 import createCdaApi from './create-cda-api'
-import type {ContentfulClient} from './create-cda-api'
+import {typeCheck} from './type-check'
 
-type ClientParams = {
-  space: string,
-  accessToken: string,
-  insecure?: boolean,
-  host?: string,
-  resolveLinks?: boolean,
-  agent?: Object,
-  headers?: Object
-}
+const ClientParams = `{
+  space: String,
+  accessToken: String,
+  insecure: Maybe Boolean,
+  host: Maybe String,
+  resolveLinks: Maybe Boolean,
+  agent: Maybe Object,
+  headers: Maybe Object
+}`
 
 /**
  * Create a client instance
@@ -39,7 +37,7 @@ type ClientParams = {
  *  space: 'mySpaceId'
  * })
  */
-export default function createClient (axios: Object, params: ClientParams) : ContentfulClient {
+export default function createClient (axios, params) {
   if (!params.accessToken) {
     throw new TypeError('Expected parameter accessToken')
   }
@@ -48,6 +46,8 @@ export default function createClient (axios: Object, params: ClientParams) : Con
     throw new TypeError('Expected parameter space')
   }
 
+  typeCheck(ClientParams, params)
+
   // Use resolveLinks param if specified, otherwise default to true
   const resolveLinks = !!('resolveLinks' in params ? params.resolveLinks : true)
 

lib/create-cda-api.js

@@ -1,5 +1,3 @@
-/* @flow */
-
 /**
  * Contentful CDA API
  * @namespace CDAClient
@@ -9,36 +7,10 @@
  * @namespace Entities
  */
 
-/**
- * Link to another entity. See <a href="https://www.contentful.com/developers/docs/concepts/links/">Links</a> for more details.
- * @memberof Entities
- * @typedef Link
- * @prop {string} type - type of this entity. Always link.
- * @prop {string} id
- * @prop {string} linkType - type of this link. If defined, either Entry or Asset
- */
-
-/**
- * System metadata. See <a href="https://www.contentful.com/developers/docs/references/content-delivery-api/#/introduction/common-resource-attributes">Common Resource Attributes</a> for more details.
- * @memberof Entities
- * @typedef Sys
- * @prop {string} type
- * @prop {string} id
- * @prop {Entities.Link} space
- * @prop {string} createdAt
- * @prop {string} updatedAt
- * @prop {number} revision
- */
-
-import type {Space} from './entities/space'
 import {wrapSpace} from './entities/space'
-import type {ContentType, ContentTypeCollection} from './entities/content-type'
 import {wrapContentType, wrapContentTypeCollection} from './entities/content-type'
-import type {Entry, EntryCollection} from './entities/entry'
 import {wrapEntry, wrapEntryCollection} from './entities/entry'
-import type {Asset, AssetCollection} from './entities/asset'
 import {wrapAsset, wrapAssetCollection} from './entities/asset'
-import type {SyncCollection} from './sync'
 import pagedSync from './sync'
 import createRequestConfig from './create-request-config'
 
@@ -54,33 +26,32 @@ import createRequestConfig from './create-request-config'
  * @prop {function} getAssets
  * @prop {function} sync
  */
-export type ContentfulClient = {
-  getSpace: (id: string) => Promise<Space>,
-  getContentType: (id: string) => Promise<ContentType>,
-  getContentTypes: (query?: Object) => Promise<ContentTypeCollection>,
-  getEntry: (id: string) => Promise<Entry>,
-  getEntries: (query?: Object) => Promise<EntryCollection>,
-  getAsset: (id: string) => Promise<Asset>,
-  getAssets: (query?: Object) => Promise<AssetCollection>,
-  sync: (query: Object) => Promise<SyncCollection>
-}
-function errorHandler (error: Object) {
+function errorHandler (error) {
   if (error.data) {
     throw error.data
   }
   throw error
 }
 
 /**
- * @private
  * Link resolution can be turned off for the methods that use it, or it can
  * be turned off globally. The local setting overrides the global setting.
+ * @private
+ * @param {Object} query - regular query object used for collection endpoints
+ * @param {boolean} globalSetting - Global library setting for link resolution
  */
-function shouldLinksResolve (query: Object, globalSetting: boolean): boolean {
+function shouldLinksResolve (query, globalSetting) {
   return !!('resolveLinks' in query ? query.resolveLinks : globalSetting)
 }
 
-export default function createCdaApi (http: Object, resolveLinksGlobalSetting: boolean): ContentfulClient {
+/**
+ * Creates CDA API object
+ * @private
+ * @param {Object} http - HTTP client instance
+ * @param {boolean} resolveLinksGlobalSetting - Global library setting for link resolution
+ * @return {ClientAPI}
+ */
+export default function createCdaApi (http, resolveLinksGlobalSetting) {
   /**
    * Gets the Space which the client is currently configured to use
    * @memberof CDAClient
@@ -89,7 +60,7 @@ export default function createCdaApi (http: Object, resolveLinksGlobalSetting: b
    * client.getSpace()
    * .then(space => console.log(space))
    */
-  function getSpace (): Promise<Space> {
+  function getSpace () {
     return http.get('')
     .then(response => wrapSpace(response.data), errorHandler)
   }
@@ -103,21 +74,21 @@ export default function createCdaApi (http: Object, resolveLinksGlobalSetting: b
    * client.getContentType('contentTypeId')
    * .then(contentType => console.log(contentType))
    */
-  function getContentType (id: string): Promise<ContentType> {
+  function getContentType (id) {
     return http.get('content_types/' + id)
     .then(response => wrapContentType(response.data), errorHandler)
   }
 
   /**
    * Gets a collection of Content Types
    * @memberof CDAClient
-   * @param  {Entities.Query} query
+   * @param  {Entities.Query=} query - Query object
    * @return {Promise<Entities.ContentTypeCollection>} Promise for a collection of Content Types
    * @example
    * client.getContentTypes()
    * .then(contentTypes => console.log(contentTypes.items))
    */
-  function getContentTypes (query?: Object = {}): Promise<ContentTypeCollection> {
+  function getContentTypes (query = {}) {
     return http.get('content_types', createRequestConfig({query: query}))
     .then(response => wrapContentTypeCollection(response.data), errorHandler)
   }
@@ -131,7 +102,7 @@ export default function createCdaApi (http: Object, resolveLinksGlobalSetting: b
    * client.getEntry('entryId')
    * .then(entry => console.log(entry))
    */
-  function getEntry (id: string): Promise<Entry> {
+  function getEntry (id) {
     return http.get('entries/' + id)
     .then(response => wrapEntry(response.data), errorHandler)
   }
@@ -146,7 +117,7 @@ export default function createCdaApi (http: Object, resolveLinksGlobalSetting: b
    * client.getEntries({content_type: 'contentTypeId'})
    * .then(entries => console.log(entries.items))
    */
-  function getEntries (query?: Object = {}): Promise<EntryCollection> {
+  function getEntries (query = {}) {
     const resolveLinks = shouldLinksResolve(query, resolveLinksGlobalSetting)
     return http.get('entries', createRequestConfig({query: query}))
     .then(response => wrapEntryCollection(response.data, resolveLinks), errorHandler)
@@ -161,7 +132,7 @@ export default function createCdaApi (http: Object, resolveLinksGlobalSetting: b
    * client.getAsset('assetId')
    * .then(asset => console.log(asset))
    */
-  function getAsset (id: string): Promise<Asset> {
+  function getAsset (id) {
     return http.get('assets/' + id)
     .then(response => wrapAsset(response.data), errorHandler)
   }
@@ -175,7 +146,7 @@ export default function createCdaApi (http: Object, resolveLinksGlobalSetting: b
    * client.getAssets()
    * .then(assets => console.log(assets.items))
    */
-  function getAssets (query?: Object = {}): Promise<AssetCollection> {
+  function getAssets (query = {}) {
     return http.get('assets', createRequestConfig({query: query}))
     .then(response => wrapAssetCollection(response.data), errorHandler)
   }
@@ -195,7 +166,7 @@ export default function createCdaApi (http: Object, resolveLinksGlobalSetting: b
    * client.sync()
    * .then(response => console.log(response.entries, response.assets, response.nextSyncToken))
    */
-  function sync (query?: Object = {}): Promise<SyncCollection> {
+  function sync (query = {}) {
     const resolveLinks = shouldLinksResolve(query, resolveLinksGlobalSetting)
     return pagedSync(http, query, resolveLinks)
   }

lib/create-http-client.js

@@ -1,21 +1,20 @@
-/* @flow */
 import qs from 'querystring'
 import version from '../version'
 
-type HttpClientParams = {
-  space: string,
-  accessToken: string,
-  insecure?: boolean,
-  host?: string,
-  agent?: Object,
-  headers?: Object
-}
-
 /**
- * @private
  * Create pre configured axios instance
+ * @private
+ * @param {Object} axios - Axios library
+ * @param {Object} HTTPClientParams - Initialization parameters for the HTTP client
+ * @prop {string} space - Space ID
+ * @prop {string} accessToken - Access Token
+ * @prop {boolean=} insecure - If we should use http instead
+ * @prop {string=} host - Alternate host
+ * @prop {Object=} agent - HTTP agent for node
+ * @prop {Object=} headers - Additional headers
+ * @return {Object} Initialized axios instance
  */
-export default function createHttpClient (axios: Object, {space, accessToken, insecure, host, agent, headers}: HttpClientParams): Object {
+export default function createHttpClient (axios, {space, accessToken, insecure, host, agent, headers}) {
   let [hostname, port] = (host && host.split(':')) || []
   hostname = hostname || 'cdn.contentful.com'
   port = port || (insecure ? 80 : 443)

lib/create-request-config.js

@@ -1,7 +1,12 @@
-/* @flow */
 import {cloneDeep} from 'lodash/lang'
 
-export default function createRequestConfig ({query}: {query: Object}): {params: Object} {
+/**
+ * Creates request parameters configuration by parsing an existing query object
+ * @private
+ * @param {Object} query
+ * @return {Object} Config object with `params` property, ready to be used in axios
+ */
+export default function createRequestConfig ({query}) {
   const config = {}
   delete query.resolveLinks
   config.params = cloneDeep(query)

lib/entities/asset.js

@@ -1,16 +1,9 @@
-/* @flow */
+import {typeCheck} from '../type-check'
 import {cloneDeep} from 'lodash/lang'
-import type {Sys} from './sys'
-import type {Field} from './field'
+import {SysProps} from './sys'
+import Field from './field'
 import mixinToPlainObject from '../mixins/to-plain-object'
 
-type AssetResponse = {
-  sys: Sys & {
-    locale: string
-  },
-  fields: { [key: string]: Field }
-}
-
 /**
  * @memberof Entities
  * @typedef Asset
@@ -26,21 +19,24 @@ type AssetResponse = {
  * @prop {Object} fields.file.details - Details for the file, depending on file type (example: image size in bytes, etc)
  * @prop {function(): Object} toPlainObject() - Returns this Asset as a plain JS object
  */
-export type Asset = {
-  sys: Sys & {
-    locale: string
+const Asset = `{
+  sys: {
+    ${SysProps},
+    locale: String
   },
-  fields: { [key: string]: Field },
-  toPlainObject: () => Object
-}
+  fields: Field
+}`
 
-export type DeletedAsset = Asset
+export default Asset
 
-type AssetCollectionResponse = {
-  total: number,
-  skip: number,
-  limit: number,
-  items: Array<AssetResponse>
+/**
+ * @private
+ * @param {Object} data - Raw asset data
+ * @return {Asset} Wrapped asset data
+ */
+export function wrapAsset (data) {
+  typeCheck(Asset, data, [Field])
+  return Object.freeze(mixinToPlainObject(cloneDeep(data)))
 }
 
 /**
@@ -52,18 +48,19 @@ type AssetCollectionResponse = {
  * @prop {Array<Entities.Asset>} items
  * @prop {function(): Object} toPlainObject() - Returns this Asset collection as a plain JS object
  */
-export type AssetCollection = {
-  total: number,
-  skip: number,
-  limit: number,
-  items: Array<Asset>,
-  toPlainObject: () => Object
-}
-
-export function wrapAsset (data: AssetResponse): Asset {
-  return Object.freeze(mixinToPlainObject(cloneDeep(data)))
-}
+const AssetCollection = `{
+  total: Number,
+  skip: Number,
+  limit: Number,
+  items: [${Asset}]
+}`
 
-export function wrapAssetCollection (data: AssetCollectionResponse): AssetCollection {
+/**
+ * @private
+ * @param {Object} data - Raw asset collection data
+ * @return {AssetCollection} Wrapped asset collection data
+ */
+export function wrapAssetCollection (data) {
+  typeCheck(AssetCollection, data, [Field])
   return Object.freeze(mixinToPlainObject(cloneDeep(data)))
 }