freedom.js structure: Provider Interface

The freedom.js Provider Interface is the complement to the Client Interface, and describes how a module can provide a service and interface to other modules. The interface is based around the concept that you have a class that you want to export, and that the class implements the methods defined in a [freedom.js JSON API specification].

There are two design points associated with this goal. The first is how to specify the implementation of functions being exported. This is taken care of through registering a class constructor with the provider Interface, which will then construct instances of your implementation as consumer modules request them. The second issue has to do with what convention your implementation uses for returning values. Some code may be synchronous, other code uses callbacks to denote that it is finished, and still other code returns promises or other deferred objects that can be used to denote completion.

Defining an API

Some APIs are defined by freedom.js itself, namely Social, Transport, and Storage - common concepts that we have found to provide useful abstractions across many implementations.

Other modules may have an interface that is specific to the logic of your application. For these, you will define a custom API declaratively in your module's manifest file.

Asynchronous Methods

freedom.js currently requires all methods in your implementation to use the same return style, and allows you to choose one of three options:

• Synchronous

  In a synchronous API, your class is able to respond to method requests synchronously, by returning an appropriate value. For example, consider a simple calculator API:

      "calculator": {
        "add": {
          "type": "method",
          "value": ["number", "number"],
          "ret": "number"
        }
      }

  A synchronous Implementation of this API would look look like this:

      var Calculator = function() {
      }
      Calculator.prototype.add = function(a, b) {
        return a + b;
      }
      freedom.calculator().provideSynchronous(Calculator);

• Callback Asynchronous

  In a callback style API, methods will be passed an extra callback, which can be called when processing is complete. In the calculator example above, the callback API would be implemented as follows:

      var Calculator = function() {
      }
      Calculator.prototype.add = function(a, b, callback) {
        // at some point later when result is ready:
        callback(a + b);
      }
      freedom.calculator().provideAsynchronous(Calculator);

• Promise Asynchronous

  Promises provide a newer model for asynchronous semantics in javascript which are rapidly being adopted by many projects. In the promise model, methods return a promise, an object which will later call attached callback functions with the resulting value. The promise-based implementation of the calculator provider looks like this:

      var Calculator = function() {
      }
      Calculator.prototype.add = function(a, b) {
        return new Promise(function(resolve, reject) {
          // At some point later
          resolve(a, b);
        });
      }
      freedom.calculator().providePromises(Calculator);

Registering your API

To export a custom API from your module that others can consume, you add the API definition to your manifest. Your module should then define which javascript factory or class should be used by the freedom.js system to provide the exported functionality. This is done by registering with one of the three styles in the previous section, depending on the convention you use for handling asynchronous calls.