spur-common

#Topics - [API](#api) - [Core](#core) - [BaseDelegate](#basedelegate) - [Timer](#timer) - [UncaughtHandler](#uncaughthandler) - [Fixtures](#fixtures) - [FixtureUtil](#fixtureutil) - [HTTP](#http) - [HTTPService](#httpservice) - [HTTPPlugin](#httpplugin) - [HTTPTiming](#httptiming) - [HTTPLogging](#httplogging) - [Logging](#logging) - [Logger](#logger) # API All of these examples can be involved, so in order to make them a little simpler to read, they are implemented with [coffee-script (documentation)](http://coffeescript.org/). ## Core ### BaseDelegate This class can only be used as a base class in order to extend a simple logger. ```coffeescript module.exports = (BaseDelegate)-> new class ConsoleLogger extends BaseDelegate constructor: ()-> @supportsMethods [ "fatal" "error" "warn" "info" "log" "debug" "verbose" ] ``` #### `Properties` | Name | Type | Description | | :---- | ---- | :---- | | **.delegates** | array | List of delegates associated to the class. | | **.recorded** | object | Object of recorded calls to the delegate when the recorder delegate is used. A propert per method called is created. | #### `Methods` | Name | Description | | :---- | :---- | | **.supportsMethods(array)** | Creates a list of methods the delegates will be called upon to support. | | **.use(delegateFn)** | Use to define your own delegate. It must support the list of all supported methods. | | **.useNoop()** | Adds a delegate that doesn't do anything when a method it's supposed to support is called. Mainly used for testing. | | **.useConsole()** | Uses the console.log to support the delegate. | | **.useRecorder()** | Sets the use of a recorder for the supported method. Mainly used for testing to verify calls to the method were executed with specific data. | --- ### Timer A helper class to measure the duration between the call of `.start()` and `.stop()`. ```coffeescript module.exports = (Timer, Logger)-> timer = new Timer() timer.start() # Do something to measure timer.stop() Logger.log(timer.duration) ``` #### `Properties` | Name | Type | Description | | :---- | ---- | :---- | | **.duration** | number | Duration between the `.start()` and `.end()` calls in milliseconds. | #### `Methods` | Name | Description | | :---- | :---- | | **.start()** | Starts the timer | | **.stop()** | Stops the timer | #### `Statics` | Name | Description | | :---- | :---- | | **Timer.mockDuration(mockDurationMs)** | Changes the timer `.stop()` prototype to always return a specific duration. Mainly for testing. | --- ### UncaughtHandler Simple module that catches uncaught errors when initialized. This should be initialized at the start of any Node application. ```coffeescript injector = require "./src/injector" injector().inject (UncaughtHandler)-> UncaughtHandler.listen() # Set up the rest of the application ``` ## Fixtures ### FixtureUtil #### `sample folder structure/contents` ``` +-- fixtures | +-- restaurant-123.js | +-- restaurant-124.js | +-- restaurant-125.js | +-- restaurant-126.js ``` #### `start.coffee` ```coffeescript module.exports = (FixtureUtil, path)-> fixturesPath = path.resolve(__dirname, "./fixtures/") FixtureUtil.setFixturesPath(fixturesPath) ``` #### `loader.coffee` ```coffeescript module.exports = (FixtureUtil, Logger, JSON)-> restaurantsData = [] restaurantsData.push FixtureUtil.get("restaurant-123") restaurantsData.push FixtureUtil.get("restaurant-124") restaurantsData.push FixtureUtil.get("restaurant-125") restaurantsData.push FixtureUtil.get("restaurant-126") Logger.log(JSON.stringify(restaurantsData, null, 2)) # Would echo the objects that were stored in the .json files ``` ## HTTP ### HTTPService HTTPService is based of the popular HTTP request module named [superagent](http://visionmedia.github.io/superagent/). This documentation only covers the custom functionality that we've added in order to add the following features: * Support of promises * Addition of plugin support * Support of logging of every requests * Auto parsing of JSON responses For the full superagent documentation, please visit their [documentation page](http://visionmedia.github.io/superagent/). #### API ##### `Methods` | Name | Description | | :---- | :---- | | **HTTPService**.get/post/put/options/head/del | Any of these methods are used to initialize the creation of a request object. No request is triggered as soon as these menthods are called. An http request is only triggered when `.end()`, or one of its wrapper methods is called. | | **Request**.named(name) | Tags the request with a name for logging | | **Request**.tagged(tagsObject) | Tags the request with a collection of data for logging | | **Request**.promise() | Executes the `.end()` call and wraps the error and response handling with a promise. | | **Request**.promiseBody() | Wraps the `.promise()` call and extracts the `.body` property. | | **Request**.promiseText() | Wraps the `.promise()` call and extracts the `.text` property. | ##### `Statics` | Name | Type | Description | | :---- | :---- | :---- | | **HTTPService**.globalPlugins | array | A list of all the plugins registered | | **HTTPService**.setGlobalPlugins(plugins) | method | Adds either a sinble plugin or an array of plugins | #### Examples ##### `Full respose` ```coffeescript module.exports = (Logger, JSON)-> @HTTPService .get("http://testserver.com/reservations/123") .named("ReservationsService") .tagged({endpoint: "Get"}) .plugin(HTTPLogging) .promise().then (res)=> Logger.log("Status Code:", res.statusCode) Logger.log(JSON.stringify(res, null, 2)) ``` ##### `Unwrap JSON payload` ```coffeescript module.exports = (Logger, JSON)-> @HTTPService .get("http://testserver.com/reservations/123") .named("ReservationsService") .tagged({endpoint: "Get"}) .plugin(HTTPLogging) .promiseBody().then (payload)=> Logger.log(JSON.stringify(payload, null, 2)) ``` ##### `Unwrap text payload` ```coffeescript module.exports = (Logger)-> @HTTPService .get("http://testserver.com/reservations/123") .named("ReservationsService") .tagged({endpoint: "Get"}) .plugin(HTTPLogging) .promiseText().then (text)=> Logger.log("Text:", text) ``` --- ### HTTPPlugin A base class used to specify the interface of an HTTP plugin. The interface is simply two calls: 1) start of the request, 2) end of the request. This allows for one or many plugins to execute at those two points in the request process. ##### Example implementation ```coffeescript module.exports = (Timer, HTTPPlugin)-> class HTTPTiming extends HTTPPlugin start:()-> @timer = new Timer().start() end:()=> # Add the duration to the request to be used later @request.duration = @timer.stop() ``` ### HTTPTiming When set as a global plugin, it will add a duration of the request to all of the http requests made with the HTTPService. ##### Global start script `Register:` ```coffeescript module.exports = (HTTPService, HTTPTiming)-> # Register a single global plugin HTTPService.setGlobalPlugins(HTTPTiming) # Registers an array of global plugins HTTPService.setGlobalPlugins([HTTPTiming]) ``` `Use from request:` ```coffeescript module.exports = (HTTPService)-> @HTTPService .get("http://testserver.com/reservations/123") .plugin(HTTPLogging) .promise().then (response)=> request = response.request Logger.log("Duration:", request.duration) ``` ### HTTPLogging When set as a global plugin, it will log all of the http requests made with the HTTPService. ##### Global start script ```coffeescript module.exports = (HTTPService, HTTPLogging)-> # Register a single global plugin HTTPService.setGlobalPlugins(HTTPLogging) # Registers an array of global plugins HTTPService.setGlobalPlugins([HTTPLogging]) ``` ## Logging ### Logger A simple logging delegate the defaults to the use of the `console.log`. Through the use of delegates you can add additional functionality. At OpenTable we've created delegates to log to Logstash, but only in production environments and only for some of the supported methods. ##### Global set of delegate ```coffeescript module.exports = (Logger)-> new class CustomLogger log: (args...)-> # do something info: (args...)-> # do something error: (args...)-> # do something Logger.use(CustomLogger) ``` ##### Usage of the custom logger ```coffeescript module.exports = (Logger)-> Logger.log("Hi, I am log") Logger.info("Hi, I am info") Logger.error("Hi, I am error", error) ```