fix(global): changes exported types to have more unique names

BREAKING CHANGE: type names changes

ApolloClient.js

@@ -35,7 +35,7 @@ const defaultErrorCallback = ({ graphQLErrors, networkError }) => {
 import ApolloLink from 'apollo-link'
 import { ApolloCache } from 'apollo-cache'
 
-export type Options = {
+export type ApolloClientOptions = {
   uri?: string;
   browserUri?: string;
   serverUri?: string;
@@ -63,6 +63,50 @@ export type Options = {
 }
 */
 
+/**
+ * `ApolloLink` is a standard interface for modifying control flow of GraphQL
+ * requests and fetching GraphQL results.
+ *
+ * @external ApolloLink
+ * @see {@link https://www.apollographql.com/docs/link/index.html|ApolloLink}
+ */
+
+/**
+ * @external ApolloCache
+ * @see {@link https://www.apollographql.com/docs/angular/basics/caching.html|ApolloCache}
+ */
+
+/**
+ * {@link ApolloClient} configuration options
+ * @typedef {Object} ApolloClientOptions
+ * @param {string} [uri='/graphql']
+ * @param {string} [browserUri=uri] - used in the browser
+ * @param {string} [serverUri=browserUri] - used in Node.js
+ * @param {string} [wsUri] - if provided a WebSocketLink will be configured
+ * @param {Object} [cache={}] - use on the client to restore server state
+ * @param {Function} [onError] - by default prints errors to console
+ * @param {number} [ssrForceFetchDelay] - see {@link https://www.apollographql.com/docs/react/api/apollo-client.html|apollo-client}
+ * @param {boolean} [connectToDevTools] - see {@link https://www.apollographql.com/docs/react/api/apollo-client.html|apollo-client}
+ * @param {boolean} [queryDeduplication] - see {@link https://www.apollographql.com/docs/react/api/apollo-client.html|apollo-client}
+ * @param {string} [name] - see {@link https://www.apollographql.com/docs/react/api/apollo-client.html|apollo-client}
+ * @param {string} [version] - see {@link https://www.apollographql.com/docs/react/api/apollo-client.html|apollo-client}
+ * @param {Object} [defaultOptions] - see {@link https://www.apollographql.com/docs/react/api/apollo-client.html|apollo-client}
+ * @param {Object} [wsOptions={ reconnect: true }] - see {@link https://www.npmjs.com/package/apollo-link-ws|apollo-link-ws}
+ * @param {WebSocket} [webSocketImpl] - see {@link https://www.npmjs.com/package/apollo-link-ws|apollo-link-ws}
+ * @param {Object} [delay] - see {@link https://www.npmjs.com/package/apollo-link-retry|apollo-link-retry}
+ * @param {Object} [attempts] - see {@link https://www.npmjs.com/package/apollo-link-retry|apollo-link-retry}
+ * @param {boolean} [includeExtensions] - see {@link https://www.npmjs.com/package/apollo-link-batch-http|apollo-link-batch-http}
+ * @param {Object} [headers={}] - see {@link https://www.npmjs.com/package/apollo-link-batch-http|apollo-link-batch-http}
+ * @param {string} [credentials='same-origin'] - see {@link https://www.npmjs.com/package/apollo-link-batch-http|apollo-link-batch-http}
+ * @param {Object} [fetchOptions={}] - see {@link https://www.npmjs.com/package/apollo-link-batch-http|apollo-link-batch-http}
+ * @param {boolean} [useGETForQueries] - see {@link https://www.npmjs.com/package/apollo-link-batch-http|apollo-link-batch-http}
+ * @param {number} [batchMax] - see {@link https://www.npmjs.com/package/apollo-link-batch-http|apollo-link-batch-http}
+ * @param {number} [batchInterval] - see {@link https://www.npmjs.com/package/apollo-link-batch-http|apollo-link-batch-http}
+ * @param {Function} [batchKey] - see {@link https://www.npmjs.com/package/apollo-link-batch-http|apollo-link-batch-http}
+ * @example
+ * import type { ApolloClientOptions } from 'secondwheel/ApolloClient'
+ */
+
 /**
  * - like {@link https://www.npmjs.com/package/apollo-boost|apollo-boost}, but
  *   allows for a greater degree of configurability
@@ -75,48 +119,6 @@ export type Options = {
  *   functionality can be changed
  *
  * @example
- * export type Options = {
- *
- *   uri?: string = '/graphql';
- *   // used in the browser
- *   browserUri?: string = uri;
- *   // used in Node.js
- *   serverUri?: string = browserUri;
- *   // if provided a WebSocketLink will be configured
- *   wsUri?: string;
- *   // use on the client to restore server state, no the need to re-run queries
- *   cache?: Object = {};
- *   // by default prints errors to console
- *   onError?: error => void;
- *
- *   // "apollo-client" options
- *   ssrForceFetchDelay?: number;
- *   connectToDevTools?: boolean;
- *   queryDeduplication?: boolean;
- *   name?: string;
- *   version?: string;
- *   defaultOptions?: { watchQuery?: Object; query?: Object; mutate?: Object; };
- *
- *   // "apollo-link-ws" options
- *   wsOptions?: Object = { reconnect: true };
- *   webSocketImpl?: WebSocket;
- *
- *   // "apollo-link-retry" options
- *   delay?: { initial?: number; max?: number; jitter?: number; };
- *   attempts?: { max?: number; retryIf?: (error, operation) => boolean; };
- *
- *   // "apollo-link-batch-http" options
- *   includeExtensions?: boolean;
- *   headers?: Object = {};
- *   credentials?: string = 'same-origin';
- *   fetchOptions?: Object = {};
- *   useGETForQueries?: boolean;
- *   batchMax?: number;
- *   batchInterval?: number;
- *   batchKey?: () => string;
- *
- * }
- * @example
  * import ApolloClient from 'secondwheel/ApolloClient'
  *
  * // connecting to a simple "graphql-yoga" server with default options
@@ -126,7 +128,7 @@ export type Options = {
  * })
  */
 class ApolloClient extends Client {
-  constructor (options/*: Options */ = {}) {
+  constructor (options/*: ApolloClientOptions */ = {}) {
     const {
       ssrForceFetchDelay,
       connectToDevTools,
@@ -150,27 +152,27 @@ class ApolloClient extends Client {
   }
 
   /** creates the final instance of ApolloLink */
-  static createLink (options/*: Options */)/*: ApolloLink */ {
+  static createLink (options/*: ApolloClientOptions */)/*: ApolloLink */ {
     const httpLink = ApolloClient.createHttpLink(options)
     const wsLink = ApolloClient.createWSLink(options)
 
     return wsLink ? split(testOperation, wsLink, httpLink) : httpLink
   }
 
   /** creates an instance of ApolloCache */
-  static createCache (options/*: Options */)/*: ApolloCache */ {
+  static createCache (options/*: ApolloClientOptions */)/*: ApolloCache */ {
     const { cache = {} } = options
 
     return new InMemoryCache().restore(cache)
   }
 
   /** creates an instance of ApolloLink */
-  static createHttpLink (options/*: Options */)/*: ApolloLink */ {
+  static createHttpLink (options/*: ApolloClientOptions */)/*: ApolloLink */ {
     return from(compact(ApolloClient.getLinks(options)))
   }
 
   /** creates an instance of WebSocketLink */
-  static createWSLink (options/*: Options */)/*: ?ApolloLink */ {
+  static createWSLink (options/*: ApolloClientOptions */)/*: ?ApolloLink */ {
     const { wsUri, wsOptions = defaultWSOptions, webSocketImpl } = options
 
     return wsUri && (webSocketImpl || NativeWebSocket) && new WebSocketLink({
@@ -184,7 +186,7 @@ class ApolloClient extends Client {
    * returns an array of ApolloLink to be used in the creation of the final link
    * falsy values are filtered out
    */
-  static getLinks (options/*: Options */)/*: Array<?ApolloLink> */ {
+  static getLinks (options/*: ApolloClientOptions */)/*: Array<?ApolloLink> */ {
     return [
       ApolloClient.createErrorLink(options),
       ApolloClient.createRetryLink(options),
@@ -193,21 +195,21 @@ class ApolloClient extends Client {
   }
 
   /** creates an instance of ErrorLink */
-  static createErrorLink (options/*: Options */)/*: ?ApolloLink */ {
+  static createErrorLink (options/*: ApolloClientOptions */)/*: ?ApolloLink */ {
     const { onError: errorCallback = defaultErrorCallback } = options
 
     return onError(errorCallback)
   }
 
   /** creates an instance of RetryLink */
-  static createRetryLink (options/*: Options */)/*: ?ApolloLink */ {
+  static createRetryLink (options/*: ApolloClientOptions */)/*: ?ApolloLink */ {
     const { delay, attempts } = options
 
     return new RetryLink({ delay, attempts })
   }
 
   /** creates an instance of HttpLink */
-  static createBatchLink (options/*: Options */)/*: ?ApolloLink */ {
+  static createBatchLink (options/*: ApolloClientOptions */)/*: ?ApolloLink */ {
     const {
       uri = '/graphql',
       browserUri = uri,

README.md

@@ -1,11 +1,11 @@
 # secondwheel
 unopinionated library of functions for those tired of reinventing the wheel
 
-[![Build Status](https://travis-ci.com/thealjey/secondwheel.svg?branch=master)](https://travis-ci.com/thealjey/secondwheel)
+[![Build Status](https://travis-ci.com/thealjey/secondwheel.svg?branch=master)](https://travis-ci.com/thealjey/secondwheel) 
 [![Coverage Status](https://coveralls.io/repos/github/thealjey/secondwheel/badge.svg?branch=master)](https://coveralls.io/github/thealjey/secondwheel?branch=master)
 
 ## Philosophy:
-1. use [Yarn](https://yarnpkg.com/en/) for everything
+1. use [Yarn](https://yarnpkg.com/en/) for everything
 1. tiny, reusable, pure & side effect free functions (when possible),
    following a single responsibility principle
 1. no transpilation

assert.js

@@ -3,6 +3,15 @@
 const identity = require('lodash/identity')
 const { AssertionError } = require('assert')
 
+/**
+ * A subclass of {@link Error} that indicates the failure of an assertion.
+ * All errors thrown by the assert module will be instances of the
+ * `AssertionError` class.
+ *
+ * @external AssertionError
+ * @see {@link https://nodejs.org/api/assert.html#assert_class_assert_assertionerror|AssertionError}
+ */
+
 /**
  * verifies that executing `resolver` on `actual` results in a truthy value
  *

cookie.js

@@ -7,26 +7,55 @@ const isDate = require('lodash/isDate')
 const pick = require('lodash/pick')
 
 /**
- * tools for working with cookies
+ * The `req` object represents the HTTP request and has properties for the
+ * request query string, parameters, body, HTTP headers, and so on. In this
+ * documentation and by convention, the object is always referred to as `req`
+ * (and the HTTP response is `res`) but its actual name is determined by the
+ * parameters to the callback function in which you’re working.
  *
- * @namespace cookie
- * @example
- * import type { CookieOptions, $Response, $Request } from 'express'
+ * @external Request
+ * @see {@link http://expressjs.com/en/4x/api.html#req|Request}
+ */
+
+/**
+ * The `res` object represents the HTTP response that an Express app sends when
+ * it gets an HTTP request.
+ *
+ * In this documentation and by convention, the object is always referred to as
+ * `res` (and the HTTP request is `req`) but its actual name is determined by
+ * the parameters to the callback function in which you’re working.
  *
- * export type Options = {
- *   req?: $Request;
- *   res?: $Response;
- *   ...$Exact<CookieOptions>;
- * }
+ * @external Response
+ * @see {@link http://expressjs.com/en/4x/api.html#res|Response}
  */
 
+/**
+ * {@link cookie} configuration options
+ * @typedef {Object} CookieOptions
+ * @param {Request} [req]
+ * @param {Response} [res]
+ * @param {string} [domain=req.hostname || window.location.host] - see {@link http://expressjs.com/en/4x/api.html#res.cookie|res.cookie}
+ * @param {Function} [encode] - see {@link http://expressjs.com/en/4x/api.html#res.cookie|res.cookie}
+ * @param {Date} [expires] - see {@link http://expressjs.com/en/4x/api.html#res.cookie|res.cookie}
+ * @param {boolean} [httpOnly] - see {@link http://expressjs.com/en/4x/api.html#res.cookie|res.cookie}
+ * @param {number} [maxAge] - see {@link http://expressjs.com/en/4x/api.html#res.cookie|res.cookie}
+ * @param {string} [path='/'] - see {@link http://expressjs.com/en/4x/api.html#res.cookie|res.cookie}
+ * @param {boolean} [secure] - see {@link http://expressjs.com/en/4x/api.html#res.cookie|res.cookie}
+ * @param {boolean} [signed] - see {@link http://expressjs.com/en/4x/api.html#res.cookie|res.cookie}
+ * @param {boolean | string} [sameSite] - see {@link http://expressjs.com/en/4x/api.html#res.cookie|res.cookie}
+ * @example
+ * import type { CookieOptions } from 'secondwheel/cookie'
+ */
+
+/** @namespace cookie */
+
 /*::
-import type { CookieOptions, $Response, $Request } from 'express'
+import type { CookieOptions as Options, $Response, $Request } from 'express'
 
-export type Options = {
+export type CookieOptions = {
   req?: $Request;
   res?: $Response;
-  ...$Exact<CookieOptions>;
+  ...$Exact<Options>;
 }
 */
 
@@ -44,7 +73,7 @@ const allowed = [
   'signed'
 ]
 
-const getConfig = (options/*: ?Options */)/*: Options */ => {
+const getConfig = (options/*: ?CookieOptions */)/*: CookieOptions */ => {
   const { req, res, ...rest } = pick(options, allowed)
 
   return {
@@ -54,7 +83,7 @@ const getConfig = (options/*: ?Options */)/*: Options */ => {
   }
 }
 
-const serialize = (options/*: ?Options */)/*: string */ => reduce(
+const serialize = (options/*: ?CookieOptions */)/*: string */ => reduce(
   options,
   (result, value, key) =>
     `${result}${kebabCase(String(key))}=${isDate(value) ? value.toUTCString() : value};`,
@@ -64,7 +93,7 @@ const serialize = (options/*: ?Options */)/*: string */ => reduce(
 function set (
   name/*: string */,
   value/*: string */,
-  options/*: ?Options */
+  options/*: ?CookieOptions */
 ) {
   const res = get(options, 'res')
   const config = getConfig(options)
@@ -89,7 +118,7 @@ function set (
 const setCookie = (
   name/*: string */,
   value/*: string */,
-  options/*: ?Options */
+  options/*: ?CookieOptions */
 ) => set(name, value, { maxAge: 10 ** 10, ...options })
 
 exports.setCookie = setCookie
@@ -107,7 +136,7 @@ exports.setCookie = setCookie
 const setSessionCookie = (
   name/*: string */,
   value/*: string */,
-  options/*: ?Options */
+  options/*: ?CookieOptions */
 ) => set(name, value, options)
 
 exports.setSessionCookie = setSessionCookie
@@ -124,7 +153,7 @@ exports.setSessionCookie = setSessionCookie
  */
 const getCookie = (
   name/*: string */,
-  options/*: ?Options */
+  options/*: ?CookieOptions */
 )/*: string */ => {
   const req = get(options, 'req')
   let match
@@ -148,7 +177,7 @@ exports.getCookie = getCookie
  * removeCookie('cookie-name')               // browser
  * removeCookie('cookie-name', { req, res }) // server
  */
-const removeCookie = (name/*: string */, options/*: ?Options */) => {
+const removeCookie = (name/*: string */, options/*: ?CookieOptions */) => {
   const res = get(options, 'res')
   const config = getConfig({ expires, ...options })
 
@@ -171,7 +200,7 @@ exports.removeCookie = removeCookie
  * setReturnTo()             // browser
  * setReturnTo({ req, res }) // server
  */
-const setReturnTo = (options/*: ?Options */) => exports.setSessionCookie(
+const setReturnTo = (options/*: ?CookieOptions */) => exports.setSessionCookie(
   'return-to',
   get(options, 'req.originalUrl') || window.location.href,
   options
@@ -189,7 +218,7 @@ exports.setReturnTo = setReturnTo
  * const cookieValue = getReturnTo()             // browser
  * const cookieValue = getReturnTo({ req, res }) // server
  */
-const getReturnTo = (options/*: ?Options */)/*: string */ => {
+const getReturnTo = (options/*: ?CookieOptions */)/*: string */ => {
   const value = getCookie('return-to', options)
 
   removeCookie('return-to', options)