COMMUNICATOR — Class: Request

new Request(options) → {Request}

A Request represents a blueprint for a request to the server, it uses a Connection and the properties listed below to do so.

Parameters:

Name	Type	Argument	Default	Description
`options`	Object	<optional>	{}	Object containing the properties specified below

Properties:

Name	Type	Argument	Default	Description
`name`	String			The name, specific, behaves like a path (name: 'user.login' will result in requests.user.login)
`connection`	String			The name of the `Connection` this `Request` should use to execute itself
`route`	String			The route of this `Request`, '/user/:id' for example
`method`	String			The HTTP method of this `Request`, 'get', 'post', 'put' or 'delete'
`prepare`	function	<optional>	Promise.resolve	Function that is called just before a `Request` is executed, allows for transformations to be applied to the request body, it can work asynchronously by returning a Promise that resolves with the transformed value, if it is synchronous the transformed value can just be returned.
`resolve`	function	<optional>	Promise.resolve	Function that is called when the `Request` is executed successfully, allows for data response body transformation, can work asynchronously by returning a Promise, if synchronous can just return the value. Even allows for rejecting a resolved request.
`reject`	function	<optional>	Promise.reject	Function that is called when the `Request` is executed unsuccessfully, allows for data response body transformation, can work asynchronously by returning a Promise, if synchronous can just return the value. Even allows for resolving a rejected request.

Returns:

Type: Request

Example

cons request = Request({
  name: 'user.findById',
  connection: 'local-xhr',
  route: '/user/:id',
  method: 'get',
  // can also return a Promise that resolves with the transformed data, if the transformation is asynchronous
  prepare(data) {
    delete data.someValueOnlyRequiredByTheClient
    return data;
  },
  resolve(data) {
    return new Promise((resolve, reject) => {
       // .. do stuff to transform data or even reject the promise
       resolve(data);
    });
  },
  reject(data) {
    return new Promise((resolve, reject) => {
       // .. do stuff to transform data or even resolve the promise
       reject(data);
    });
  }
});

Methods

execute(args) → {Promise}

Executes the Request using its own Connection

Parameters:

Name	Type	Argument	Description
`args`	String \| Number	<repeatable>	The :splats followed by the request body

Returns:

A Promise that resolves when the Request has executed successfully, and rejects when it failed to do so.

Type: Promise

Example

// route: '/user/:id'
request.execute(56);
// route: '/user/:id/:id2'
request.execute(56, 57);
// route: '/user/:id/:id2', with request body
request.execute(56, 57, {someData: true});

executeWithConnection(connection, args) → {Promise}

Executes this Request using a Connection

Parameters:

Name	Type	Argument	Description
`connection`	Connection \| String		`Connection` or name of a `Connection` to execute this `Request` with
`args`	*	<repeatable>	The rest of the arguments should be the :splats in the right order, the last argument (the one after the :splats) is the request body, so, if there are no :splats this argument is the request body. If there are :splats in the route, all :splats are required to be provided to this function.

Returns:

A Promise that resolves when the Request has executed successfully, and rejects when it failed to do so.

Type: Promise

Example

// find by id request, route: '/user/:id'
request.executeWithConnection('local-xhr', 13);