README
____ _ __ _
/ ___| _ __ ___ __ _ _ __| |_ / _| __ _ ___ ___ (_) ___
\___ \| '_ ` _ \ / _` | '__| __| |_ / _` |/ __/ _ \ | |/ _ \
___) | | | | | | (_| | | | |_| _| (_| | (_| __/ _ | | (_) |
|____/|_| |_| |_|\__,_|_| \__|_| \__,_|\___\___| (_) |_|\___/
-----------------------------------------------------------------
NW
This library is intended to ease network (rest-http) connections easly. First it is developed for Smartface then it is adopted to work both with node.
Install
npm i smf-nw
Smartface
If you are within a Smartface workspace first switch to scripts folder. Here is a script that does it all:
(cd ~/workspace/scripts && npm i smf-nw)
Examples
Examples are not included within the npm package. It is possible to reach examples from github page: https://github.com/smartface/js-lib-nw/
Usage
nw relies on XMLHttpRequest object to be global. In Smartface environment it is global. Following code in node makes it global:
if (!global.XMLHttpRequest)
global.XMLHttpRequest = require("xmlhttprequest").XMLHttpRequest;
Make sure that xmlhttprequest module is installed
npm i xmlhttprequest
const nw = require("nw"); //access to nw settings object
In order to make a call, first you need to register a service definition.
nw.registerService(serviceDefinitionObject);
Service Definition
Service Definition Object is a simple object. Members of the object are defined below:
- name: String, required. Name of the service. This is the unique accessor to the service.
- method: String, required. HTTP method of the service. Better to be all in capital letters.
- path: String, required; not required if url is used. Path is concatenated to end of the nw.baseURL. Supports string format. Do not define query string values here, so do not use question mark (?)
- url: String, required; not required if path is used. Full URL of the string, is not related with nw.baseURL. Supports string format.
- mock: Object, optional. Mock value of the service. Can have body, header, status.
- header: Object, optional. Key-value pair object. Static header parameters of the request.
- query: Object, optional. Key-value pair object. Static query string parameters of the request.
- body: Object or String, optional. Static body value of the request.
String format
String format basically is a pattern in the given string and replacing those parameters within the string with given arguments. More details can be reached from: https://www.npmjs.com/package/form-urlencoded
Practical way to add services
Place them in a separate JSON files (with json extension) and require them.
Pass the require result into nw.registerService(require("myServiceDefinitionFile.json"));
API
nw settings
nw settings object provides following API
baseURL
String. Works kind a prefix to path. It does not add slashes (/) automatically while concatenating with path to form the URL of the service.
services
Object. All service definitions are placed here. All services are registered with their names and can be accessed through by its name as property. A service definition with same name overwrites the definition.
factory
Function. Creates nw service object from service definition. Service is given as parameter by name of the registered services. Does not expect a service definition as object.
commonHeaders
Object. In key-value format. Adds header values to all requests. Useful to modify after login and logout. Also useful if all sevices content-type and/or accept values are same.
registerService
Function. Takes a service definition object as parameter. After small validation it adds it to services as a property.
proxy
String. Smartface only! All requests are gone through a socks proxy in provided url value of the proxy server.
ignoreSSLErrors
Boolean. Smartface only! Ignores SSL errors on services
requestSuccessValidator
Function. A pre-processor for defining response of the service falls into category of faulty or success based on the http status of the response. Takes status (number) as argument parameter, returns true|false boolean as result. False mean faulty response. By default this is set all status between 200 & 399 are valid, rest not. Can be replaced with assigning this function with another.
onActivityStart
Function|Event. Fired before network operation starts. Useful to block UI during network operation. Can be set by assigning the function. Does not takes any argument or returns.
onActivityEnd
Function|Event. Fired after network operation starts. Useful to remove UI block after network operation completes. Can be set by assigning the function. Does not takes any argument or returns.
nw service object
nw service object is the real object that handles all network operations. As a pattern every function returns itself (chaining), except chain method. Header value content-type is important before making a request if request has a body. Every request is prepared by its content-type. Every response is also parsed by its response header content-type value and provided as object; if parsing fails then the response body is provided as string.
body
Function. Sets values in body of the request. In form it can be given as key-value pair, first argument is key, second argument is value; in other scenarios it can be given as single parameter.
header
Function. Sets the header values for the request in key-value format. First argument is key, second argument is value.
query
Function. Sets the query string values for the request in key-value format. First argument is key, second argument is value.
path
Function. Formats the string in path. Each argument is provided as argument to formatter.
result
Function. Takes a function as an argument. This function is called after network operation for the service completes. This function has two arguments in error-first-pattern err and data. Structure of both argument are same objects. data is null for unsuccessful response or on a network error; err is null on a successful response as defined in nw.requestSuccessValidator.
result arguments
Objects have following properties:
- status: http status
- body: body object|string of the response
- header: header object of the response
- next: Boolean.In chained flow if this is set to false within the function, chain will not continue.
chain
Creates an another nw service object by the given service definition name (string) in a chained flow. In this case it does not returns the original nw service object instead it returns new nw service object
run
Function. Runs the services according to the flow. Making an actual call and retrieving values from server.
mock
Function. Does not run the service! Instead executes them in flow after 300ms fires result with the values given in service definition in mock field.
Flow
run and mock methods of the nw service object executed in flows.
Normal Flow
- nw.onActivityStart event is fired
- Service is executed
- <nw service object>.result is handled
- nw.onActivityEnd event is fired
Chained Flow
- nw.onActivityStart event is fired
- First nw service object is executed
- First <nw service object>.result is handled
- If there are no more nw service object (s) in chain, go to step 9
- If the next value is true (which is by default) continue. If not go to step 9
- Execute next nw service object in chain
- Handle <nw service object>.result in chain
- Continue with next nw service object in chain: Go to step 4
- nw.onActivityEnd event is fired