Maps SDK for Web

Class Chain

This module has two utilities:

This module create getters and setters for every property of the object passed as first argument and also implement the "go" method which executed an arbitrary function passing all the property values.

To create the getters and setters the first argument of the constructor should be an object with the following accepted properties:

name: String Custom name of the property. If isn't define the name of the property will be used.
validator: Function(value) If the value isn't valid this function should throw an Error, otherwise it should return the value validated
defaultValue: Function() This function have to return the default value
converter: Function(value) The returned value of this function will be used

This is an example of configurations this module could take:

Constructor

Chain(fields, [goFunction], [options])

Parameters

Name	Description	Required	Type/Values	Default
fields		Yes	Object	None
fields.callback	Default callback function to be executed by "goFunction" function	Yes	Function	None
fields.fail	Default fail function callback to be executed by "goFunction" function	Yes	Function	None
goFunction	Should have the signature: function(properties, callback): Promise\|undefined	No	Function	None
options	Object with the initial values for the properties defined in the "fields" argument	No	Object	None
options.fail	Failsafe "fail" function to be executed by "goFunction" callback argument. It will override "fields.fail" (yeah, don't ask me why)	No	Function	None

Example

var properties = {
  city: {
    name: 'bestCity',
    validator: function (name) {
      if (typeof name !== 'string' || name.length === 0) throw new Error('City name is not valid');
      return name;
    },
    converter: function (name) {
      return name.toLowerCase();
    },
    defaultValue: function() {
      return 'Lodz';
    }
  }
}
var config = require('chain')(properties);
config.city(); // prints "lodz"
config.city('Torun'); // prints "torun"
config.city(); // prints "torun"

Take notice the converter function is always executed, even for the default value.

As second argument a function will be expected and this function will be executed using the "go" method returned by this constructor. The additional functions returned by this constructor are: "go", "callback" and "fail".

The "go" function will execute the function passed as second argument of the constructor which should implement the next signature: goFunction(properties, callback) .

Is expected that the "goFunction" will call the callback function available in the second argument which is the same function defined in fields.callback or the first argument passed to the "go" function.

The "go" method can receive two callback arguments: "success" and "fail" which will override the initial callbacks defined during the creation and will be continue to be used in the next execution of the "go" function.

If a callback is not provided nor in the fields.callback or as first argument of the "go" call, then the "go" function will return a Promise, otherwise this function will return undefined.

var properties = {
  city: {},
  country: {}
}
var defaults = {city: 'Lima', country: 'Peru'};
function sendToBackend(properties, callback) {
  // Ajax call sending the properties
  // ...
  callback("OK");
}
function onSuccess() {};
function onfail() {};

var config = require('chain')(properties, sendToBackend, defaults);

// Calling "go" passing callbacks
config.go(onSuccess, onfail);

// Calling go and receive a Promise
config.go()
  .then(onSuccess)
  .catch(onFail);

Do you think this was difficult to read? Believe me, the most difficult was to write it.

Methods

callback([newValue]): Function Chainable

Sets or gets the value of the option callback.

This callback function will be called only after the go method successfully complete its task.

Its first and unique argument passed to the callback will be the result of the request.

Parameters

Name	Description	Required	Type/Values	Default
newValue	The new callback function	No	Function	None

Throws

TypeError If the given argument is not a function

Returns

Function The same service instance or the current callback function if no argument was given

Example

function callbackFn(results) {
  console.log(results);
}
tomtom.fuzzySearch()
  .query("pizza")
  .callback(callbackFn)
  .go();

fail([newValue]): Function Chainable

Sets or gets the value of the option fail.

This function is called when an error occurs (e.g. invalid values or a communication error).

The callback will receive just one argument which is the error description.

This parameter will be ignored if the callback function is not defined and therefore the go method will return a Promise that will be rejected if an error occurs.

If you don't specificy a failure callback, the default behavior in case of encounter a problem is to throw an error.

Parameters

Name	Description	Required	Type/Values	Default
newValue	The new callback function	No	Function	None

Throws

TypeError If the given argument is not a function

Returns

Function The same service instance or the current callback function if no argument was given

Example

function successCallback(results) {
  console.log(results);
}
function failureCallback(error) {
  console.log(error);
}
tomtom.fuzzySearch()
  .query("pizza")
  .callback(successCallback)
  .fail(failureCallback)
  .go();

go([success], [fail]): Promise | Null

Executes a predefined asynchronous task using the current configuration and then execute one of the callback functions based on the success of the result.

It receives two optional arguments. The first one is a callback function that will be used when the task is successfully completed. The second one is another callback function that will be used only in case of failure.

Both arguments are shortcuts for the callback and fail methods respectively.

Parameters

Name	Description	Required	Type/Values	Default
success	The callback function to be called on case of success	No	Function	None
fail	The callback function to be called on case of failure. If a success callback was not given this argument will be ignored. In that case the returned Promise should be used to handle the failures.	No	Function	None

Returns

Promise | Null If the success callback is omitted (and wasn't defined one yet) this function will return a Promise

Example

All the ways of using this method:

// Defining callbacks as function arguments
tomtom.fuzzySearch()
  .query("pizza")
  .go(successCallback, failureCallback);

// Defining callbacks using setters methods
tomtom.fuzzySearch()
  .query("pizza")
  .callback(successCallback)
  .fail(failureCallback)
  .go();

// Using the returned Promise
tomtom.fuzzySearch()
  .query("pizza")
  .go()
  .then(successCallback)
  .catch(failureCallback);

The SDK provides a Promise polyfill for browsers (IE<9) without native ECMAScript 6 support.