Module: services

Services API optimizes communication based on request-response paradigm between clients and server.

The key concept is a "service": a named facade that simplifies server's interface and handles communication. Each service is of certain type. A service type depends on the type of the server or the type of the channel used in communication, or both. Server can be an HTTP server, a Worker, a Capsule, or anything else able to handle clients' requests.

To create (register) service use the register function.

To send request to a service use the send function.

To flush the service use the flush function.

Each module has its own built-in service types: services.js, capsula.js, and html.js service types. If there is no suitable service type within the collection of built-in service types, one can easily create new service type using registerType function.

Since:
  • 0.1.0
Source:

Classes

ErrorMessage
Request

Namespaces

Errors
ServiceType

Methods

(static) flush(serviceName)

Flushes the service with the given name, i.e. packs all client requests (previously sent to this service using the send function) into a single physical request, sends that physical request to its destination, waits for the physical response, unpacks the physical response into individual responses, and resolves or rejects each request's promise. Clears the service's internal buffer of requests which makes sure the service is ready to accept new requests.
Parameters:
Name Type Description
serviceName string the name of the service to flush
Since:
  • 0.1.0
Source:
See:
Throws:
ILLEGAL_ARGUMENT, SERVICE_UNREGISTERED
Type
Error

(static) flushAll()

Flushes all services in the service layer by simply calling flush for each of the existing services.
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT
Type
Error

(static) getServiceStatus(serviceName) → {string}

Returns the last status of the service with the given name.
Parameters:
Name Type Description
serviceName string the name of the service
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT
Type
Error
Returns:
- the last status of the given service
Type
string

(static) isRegistered(serviceName) → {boolean}

Checks whether the service with the given name is registered or not.
Parameters:
Name Type Description
serviceName string the name of the service to check
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT
Type
Error
Returns:
whether the service is registered (true) or not (false)
Type
boolean

(static) register(serviceName, serviceConfig, opt_overwrite)

Creates new service, registers it under the given name, and associates it to the given service configuration object. After that, the newly created service may be used to handle communication with the target server it represents. To send request to this service (i.e. to the target server) use the send function. Note that there is no need (nor is it possible) to keep a reference to a service in a JavaScript variable. Instead, the service is always referenced by its name. This makes services easily accessible from anywhere in the code.
Parameters:
Name Type Description
serviceName string the name under which to register new service
serviceConfig string the service configuration object. This object must have the 'type' property which is a string that matches the name of either a built-in service type (one of the services.js, capsula.js, or html.js service types) or the service type created using registerType function (custom service type). In addition to the 'type' property, the serviceConfig object may have additional service-type-specific properties. To learn service-type-specific properties of built-in service types, consult the documentation.
opt_overwrite Boolean a flag used to specify whether to overwrite the (existing) service with the given name. If opt_overwrite is not provided or set to false, the SERVICE_ALREADY_REGISTERED error would be thrown in case when the given service name matches the service name of an existing service.
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT, SERVICE_ALREADY_REGISTERED
Type
Error

(static) registerType(serviceType, serviceFunction)

Registers a new service type with the given name; service type that operates as specified in the given function. Upon service type registration, services of that type could be registered (using register function) and used to deliver packages of requests to their destinations.

For example, one could create a service type to handle AJAX communication with the server and then for each URL a separate service of that service type would exist.

Parameters:
Name Type Description
serviceType string the name of the service type to create
serviceFunction Funtion the function of the service type to be created:

- function serviceFunction(requests, serviceConfig, serviceName) - The function should perform all necessary actions in order to send requests to their destination and receive and handle responses. More precisely, it needs to pack all client requests into a single physical request, send that physical request to its destination, wait for the physical response, unpack the physical response into individual responses, and handle each individual response. Handling responses means resolving or rejecting each request's promise by simply calling r.resolve(response) or r.reject(error). Here, r represents an individual request. The requests are given in the requests parameter which represents an array of Request objects each of which contains the client's request in its body property and resolve and reject functions in its resolve and reject properties. serviceConfig is the configuration object of the particular service (the second argument of the service registration register function). serviceName is the name of the particular service (the first argument of the service registration register function).
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT
Type
Error

(static) rejectAll(requests, err)

Utility function that rejects promises of all given requests with the given error.
Parameters:
Name Type Description
requests Array.<Object> array of requests to reject
err Array.<Object> an error to use when rejecting requests
Since:
  • 0.1.0
Source:

(static) resolveAll(requests, responses)

Utility function that resolves promises of all given requests with corresponding responses.
Parameters:
Name Type Description
requests Array.<Object> array of requests to resolve
responses Array.<Object> array of responses to return
Since:
  • 0.1.0
Source:

(static) resolveAllSuccessful(requests, responses)

Utility function that resolves promise of each successfully handled request (response.success = true) within the given collection of requests with its corresponding response. Rejects promise of each unsuccessfully handled request within the given collection of requests with the error from the corresponding response (response.error).
Parameters:
Name Type Description
requests Array.<Object> array of requests to resolve
responses Array.<Object> array of responses to return
Since:
  • 0.1.0
Source:
Throws:
ERRONEOUS_RESPONSE
Type
Error

(static) send(serviceName, request) → {Promise}

Sends the given request to the service with the given name. Returns the Promise object to use to add then and catch handlers. The request stays in the 'service' layer until either flush is called for that particular service or all services are flushed by flushAll.
Parameters:
Name Type Description
serviceName string the name of the service to send request to
request Object the client's request object to send to a service (can be any object whatsoever)
Since:
  • 0.1.0
Source:
Throws:
SERVICE_UNREGISTERED, ILLEGAL_ARGUMENT
Type
Error
Returns:
- the promise object
Type
Promise

(static) setServiceStatus(serviceName, currentStatus)

Sets the status of the service with the given name.
Parameters:
Name Type Description
serviceName string the name of the service
currentStatus string the status of the service with the given name
Since:
  • 0.1.0
Source:
Throws:
ILLEGAL_ARGUMENT
Type
Error

(static) unregister(serviceName)

Unregisters the service with the given name. The service is no longer in operation, i.e. can not be used.
Parameters:
Name Type Description
serviceName string the name of the service to unregister
Since:
  • 0.1.0
Source:
Throws:
SERVICE_UNREGISTERED, ILLEGAL_ARGUMENT
Type
Error