adjust exported API

- adjust API to be more simple, move extra non-essential functions off and mark as ‘internal’ - prep v0.2.0
spirit-js · Aug 19, 2016 · 69d80f1 · 69d80f1
1 parent 49104b1
commit 69d80f1
Show file tree

Hide file tree

Showing 12 changed files with 134 additions and 95 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,12 +1,16 @@
-= v0.1.2
-#### Release Date: 08-18-2016
+## v0.2.0
+#### Release Date: - In Progress -
+The API has underwent minor changes:
+- `spirit.is_promise` is still there, but no longer covered under docs (considered internal api)
+- _All_ API under `spirit.node.utils` is now considered internal, they are still documented however
+- `spirit.node.is_Response` has moved to `spirit.node.utils.is_Response`
 
-#### Added:
-- Response.cookie
+The reason for the change is to slim down the public API to only the essentials. The functions affected were all utility functions (and simple in functionality) and mostly used internally, but was and still is provided as a convienance.
 
-#### Removed:
-- Response.location
 
-#### Bug Fixes:
-- Response.attachment wasn’t returning itself (this)
-- When production ENV was set and an error occured in which http adapter had to handle, it would strip the body but not it’s Content-Length. This would make it seem like the request froze (or client froze).
+## v0.1.2
+#### Release Date: 08-18-2016
+- Added Response.cookie
+- Removed Response.location
+- Fix Response.attachment wasn’t returning itself (this)
+- Fix When production ENV was set and an error occured in which http adapter had to handle, it would strip the body but not it’s Content-Length. This would make it seem like the request froze (or client froze).
diff --git a/docs/api/README.md b/docs/api/README.md
@@ -1,11 +1,10 @@
 ## spirit API
 This covers spirit's exported API.
 
-When using the node http adapter (`spirit.node`) be sure to become familiar with [request map](request-response-map.md#request-map) and [response map](request-response-map.md#response-map).
-
 - [compose](spirit.md#compose)
 - [callp](spirit.md#callp)
-- [is_promise](spirit.md#is_promise)
+
+node http adapter (`spirit.node`) requires you to be familiar with [request map](request-response-map.md#request-map) and [response map](request-response-map.md#response-map).
 
 - node
   * [adapter](node.md#adapter)
@@ -15,15 +14,19 @@ When using the node http adapter (`spirit.node`) be sure to become familiar with
   * [err_response](node.md#err_response)
   * [redirect](node.md#redirect)
   * [Response](Response.md)
-  * [is_Response](node.md#is_Response)
   * [is_response](node.md#is_response)
-
-  * utils
-    - [size_of](node-utils.md#size_of)
-    - [type_of](node-utils.md#type_of)
-    - [resolve_response](node-utils.md#resolve_response)
-
   * middleware
     - [if-modified](node-middleware.md#if-modified)
     - [log](node-middleware.md#log)
     - [proxy](node-middleware.md#proxy)
+
+
+#### Internal API
+The following are internal API that are exported and documented.
+
+`spirit.node.utils` namespace:
+
+- [is_Response](internal.md#is_Response)
+- [size_of](internal.md#size_of)
+- [type_of](internal.md#type_of)
+- [resolve_response](internal.md#resolve_response)]
diff --git a/docs/api/node-utils.md → docs/api/internal.md b/docs/api/node-utils.md → docs/api/internal.md
@@ -1,7 +1,10 @@
-Internal APIs
+Internal API
 
-** denotes a high probablity of change
+Considered stable unless denoted with "**".
 
+NOTE: Unlike the rest of the spirit API, there are no camelCase variants.
+
+- [is_Response](#is_Response)
 - [size_of](#size_of)
 - [type_of **](#type_of)
 - [resolve_response](#resolve_response)
@@ -10,6 +13,25 @@ Internal APIs
 -------------------------------------------
 
 
+# is_Response
+##### (spirit.node.utils.is_Response)
+
+Returns `true` or `false` depending on if `v` is a instance of [Response](Response.md)
+
+Does not return true for a response map, this is a specific check.
+
+[Source: src/http/response-class.js (is_Response)](../../src/http/response-class.js#L4)
+
+#### Arguments
+* v {*} 
+
+#### Return
+{boolean} 
+
+
+-------------------------------------------
+
+
 # size_of
 ##### (spirit.node.utils.size_of)
 

diff --git a/docs/api/node.md b/docs/api/node.md
@@ -9,7 +9,6 @@ Functions for creating common responses with chainable helpers:
 - [redirect](#redirect)
 
 For checking if an object is a valid response:
-- [is_Response](#is_Response)
 - [is_response](#is_response)
 
 
@@ -206,25 +205,6 @@ err_response(new Error("oops"))
 -------------------------------------------
 
 
-# is_Response
-##### (spirit.node.is_Response)
-
-Returns `true` or `false` depending on if `v` is a instance of [Response](Response.md)
-
-Does not return true for a response map, this is a specific check.
-
-[Source: src/http/response-class.js (is_Response)](../../src/http/response-class.js#L4)
-
-#### Arguments
-* v {*} 
-
-#### Return
-{boolean} 
-
-
--------------------------------------------
-
-
 # is_response
 ##### (spirit.node.is_response)
 

diff --git a/docs/api/spirit.md b/docs/api/spirit.md
@@ -1,3 +1,6 @@
+- [compose](#compose)
+- [callp](#callp)
+
 # compose
 ##### (spirit.compose)
 
@@ -43,19 +46,3 @@ Additionally if `fn` is _not_ a function, it will ignore `args` and return `fn`
 #### Return
 {Promise} The value of `fn(args)` wrapped as a Promise if it's not a Promise already
 
-
---------------------------------------------------
-
-
-# is_promise
-##### (spirit.is_promise)
-
-Returns `true` or `false` depending on if `v` is a Promise
-
-[Source: src/core/promise_utils.js (callp)](../../src/core/promise_utils.js#L20)
-
-#### Arguments
-* v {*} 
-
-#### Return
-{boolean}
diff --git a/index.js b/index.js
@@ -1,36 +1,37 @@
 var core = require("./lib/core/core")
 var p_utils = require("./lib/core/promise_utils")
 
+//-- spirit.node
 var node_adapter = require("./lib/http/node_adapter")
 var response = require("./lib/http/response")
 var response_map = require("./lib/http/response-class")
-
-
 var node = response
 node.adapter = node_adapter.adapter
 node.Response = response_map.Response
-// is_Response has no camelCase alias as it'll overwrite
-// isResponse which is camelCase for is_response
-node.is_Response = response_map.is_Response
-
-node.utils = require("./lib/http/utils")
-node.utils.resolve_response = p_utils.resolve_response
-node.utils.resolveResponse = p_utils.resolve_response
+///////// setup node camelCase aliases
+node.isResponse = node.is_response
+node.makeStream = node.make_stream
+node.fileResponse = node.file_response
+node.errResponse = node.err_response
 
-// node http middleware
+//-- spirit.node.middleware
 node.middleware = {
   proxy: require("./lib/http/middleware/proxy"),
 //  head: require("./lib/http/middleware/head"),
   ifmod: require("./lib/http/middleware/if-modified"),
   log: require("./lib/http/middleware/log")
 }
 
+//-- spirit.utils (Internal API but exported)
+// no camelCase aliases!
+node.utils = require("./lib/http/utils")
+node.utils.is_Response = response_map.is_Response
+node.utils.resolve_response = p_utils.resolve_response
+
 module.exports = {
   compose: core.compose,
   callp: p_utils.callp,
-
-  is_promise: p_utils.is_promise,
-  isPromise: p_utils.is_promise,
+  is_promise: p_utils.is_promise, // exported but not documented
 
   node: node
 }
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "spirit",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "extensible web library for building applications & frameworks",
   "main": "index.js",
   "scripts": {

diff --git a/spec/http/response_class-spec.js b/spec/http/response_class-spec.js
@@ -1,4 +1,6 @@
-const {Response, is_Response}= require("../../index").node
+const spirit = require("../../index")
+const Response = spirit.node.Response
+const is_Response = spirit.node.utils.is_Response
 
 describe("response-class", () => {
   describe("is_Response", () => {

diff --git a/spec/http/utils-spec.js b/spec/http/utils-spec.js
@@ -69,9 +69,6 @@ describe("resolve_response", () => {
     })
   })
 
-  it("alias", () => {
-    expect(utils.resolve_response).toBe(utils.resolveResponse)
-  })
 })
 
 describe("size_of", () => {
@@ -96,9 +93,6 @@ describe("size_of", () => {
     expect(size).toBe(undefined)
   })
 
-  it("alias", () => {
-    expect(utils.size_of).toBe(utils.sizeOf)
-  })
 })
 
 describe("type_of", () => {
@@ -131,8 +125,4 @@ describe("type_of", () => {
     expect(utils.type_of(f)).toBe("file-stream")
   })
 
-  it("alias", () => {
-    expect(utils.type_of).toBe(utils.typeOf)
-  })
-
 })
diff --git a/spec/spirit-spec.js b/spec/spirit-spec.js
@@ -110,3 +110,64 @@ describe("spirit spec", () => {
   })
 
 })
+
+describe("spirit exported API", () => {
+  it("core", () => {
+    const api = Object.keys(spirit)
+    expect(api).toEqual([
+      "compose",
+      "callp",
+      "is_promise", // not documented as exported
+      "node"
+    ])
+    expect(api.length).toEqual(4)
+  })
+
+  it("node", () => {
+    const api = Object.keys(spirit.node).sort()
+    const test_api = [
+      "adapter",
+      "response",
+      "redirect",
+      "make_stream",
+      "is_response",
+      "file_response",
+      "err_response",
+      "Response",
+      "middleware",
+      "utils"
+    ]
+
+    // add in camelCase aliases
+    const test_aliases = test_api.reduce((ta, api_name) => {
+      const t = api_name.split("_")
+      if (t.length === 2) {
+        const alias = t[0] + t[1][0].toUpperCase() + t[1].slice(1)
+        ta.push(alias)
+      }
+      return ta
+    }, [])
+
+    expect(api).toEqual(test_api.concat(test_aliases).sort())
+    expect(api.length).toEqual(14)
+  })
+
+  it("node.middleware", () => {
+    const api = Object.keys(spirit.node.middleware).sort()
+    expect(api).toEqual([
+      "ifmod",
+      "log",
+      "proxy"
+    ])
+  })
+
+  it("node.utils", () => {
+    const api = Object.keys(spirit.node.utils).sort()
+    expect(api).toEqual([
+      "is_Response",
+      "resolve_response",
+      "size_of",
+      "type_of"
+    ])
+  })
+})
diff --git a/src/http/response.js b/src/http/response.js
@@ -174,18 +174,9 @@ const err_response = (err) => {
 
 module.exports = {
   is_response,
-  isResponse: is_response, // alias
-
   make_stream,
-  makeStream: make_stream, // alias
-
   response,
-
   file_response,
-  fileResponse: file_response, // alias
-
   redirect,
-
-  err_response,
-  errResponse: err_response // alias
+  err_response
 }
diff --git a/src/http/utils.js b/src/http/utils.js
@@ -48,7 +48,5 @@ const type_of = (v) => {
 
 module.exports = {
   type_of,
-  typeOf: type_of, // alias
-  size_of,
-  sizeOf: size_of // alias
+  size_of
 }