interstellar-core

interstellar-core
=============

The interstellar-core module is part of the Interstellar Module System.

It provides the lowest level functionality: a core JS wrapper.

> Quick start to developing in the Interstellar eco-system:
>
> * Read Getting started doc.
> * Install interstellar-workspace.
> * Contribute to our open-source modules or develop your own.

Module contents

#### Classes
* Module
* App
* Inject annotation
* Controller annotation
* Provider annotation
* Service annotation
* Widget annotation
* Intent

#### Services
* interstellar-core.IntentBroadcast
* interstellar-core.Config

#### Widgets
None.

#### Others
* solar
* solar-stellarorg

Module class

Module is a wrapper around Angular.js module. Every Interstellar module is a Module object and Angular.js module. Module provides several methods to help configure a module. It also provides autoloading support for controllers, templates, services, directives and other components.

``js
import {Module} from "interstellar-core";

export const mod = new Module('interstellar-example');
mod.use(interstellarSomeModule.name);

mod.controllers = require.context("./controllers", true);
mod.directives = require.context("./directives", true);
mod.services = require.context("./services", true);
mod.templates = require.context("raw!./templates", true)

mod.define();
`

App class

App class extends Module class and provides helper methods for the final Interstellar application that use other modules. It provides additional functionality like ui-router. The second parameter in a constructor is a configuration JSON.

`js
import {App, mod as interstellarCore} from "interstellar-core";
import {mod as interstellarStellarWallet} from "interstellar-stellar-wallet";
import {mod as interstellarNetwork} from "interstellar-network";
import {mod as interstellarSettings} from "interstellar-settings";
import {mod as interstellarStellarApi} from "interstellar-stellar-api";

let config = require('./config.json');
export const app = new App("interstellar-stellar-client", config);

app.use(interstellarCore.name);
app.use(interstellarStellarWallet.name);
app.use(interstellarNetwork.name);
app.use(interstellarSettings.name);
app.use(interstellarStellarApi.name);

app.templates = require.context("raw!./templates", true);
app.controllers = require.context("./controllers", true);

app.routes = ($stateProvider) => {
$stateProvider.state('login', {
url: "/login",
templateUrl: "interstellar-stellar-client/login"
});
$stateProvider.state('dashboard', {
url: "/dashboard",
templateUrl: "interstellar-stellar-client/dashboard",
requireSession: true
});
// ...
};

// Callbacks to execute in config block.
app.config(configureServices);

// Callbacks to execute in run block.
app.run(registerBroadcastReceivers);

app.bootstrap();
`

Inject annotation

Decorator class to inject dependencies to your controllers or services using AngularJS injector subsystem:

`js
import {Inject} from 'interstellar-core';

@Inject("interstellar-sessions.Sessions", "interstellar-network.Server")
class ReceiveWidgetController {
constructor(Sessions, Server) {
this.Server = Server;
this.Sessions = Sessions;
}
}
`

Controller annotation

Decorator class to annotate your controllers.

`js
import {Controller, Inject} from 'interstellar-core';

@Controller("HeaderController")
@Inject("interstellar-sessions.Sessions", "interstellar-network.Server")
export default class HeaderController {
constructor(Sessions, Server) {
this.Server = Server;
this.Sessions = Sessions;
}
// ...
}
`

> Heads up! Annotated class _must_ be exported as default.

Provider annotation

Decorator class to annotate your providers.

`js
import {Provider} from 'interstellar-core';

@Provider("Config")
export default class ConfigProvider {
constructor() {
this.appConfig = {};
this.modulesConfig = {};
}
// ...
}
`

> Heads up! Annotated class _must_ be exported as default.

Service annotation

Decorator class to annotate your services.

`js
import {Service} from 'interstellar-core';

@Service('IntentBroadcast')
export default class IntentBroadcastService {
constructor() {
this.receivers = {};
}
// ...
}
`

> Heads up! Annotated class _must_ be exported as default.

Widget annotation

Decorator class to annotate your widgets' controllers.

This annotation requires 3 arguments:
* directive name,
* controller name,
* template name.

`js
import {Widget, Inject} from 'interstellar-core';

@Widget("balance", "BalanceWidgetController", "interstellar-network-widgets/balance-widget")
@Inject("$scope", "interstellar-sessions.Sessions", "interstellar-network.AccountObservable", "interstellar-network.Server")
export default class BalanceWidgetController {
constructor($scope, Sessions, AccountObservable, Server) {
if (!Sessions.hasDefault()) {
console.error('No session. This widget should be used with active session.');
return;
}
// ...
}
// ...
}
`

> Heads up! Annotated class _must_ be exported as default.

Intent class

Modules in Interstellar communicate by broadcasting Intent objects using Android-inspired intent system. Modules can:
* Broadcast Intents to trigger some events in other modules,
* Register Broadcast Receivers to listen to Intents sent by other modules.

Every Intent has a type which must be one of standard intent types:
* SEND_TRANSACTION - User wants to send a transaction.
* SHOW_DASHBOARD - User wants to see a dashboard.
* LOGOUT - User wants to logout.

Intent can also contain additional data helpful for a Broadcast Receiver. For example, SEND_TRANSACTION Intent can contain destination address.

`js
// Sending Broadcast
IntentBroadcast.sendBroadcast(
new Intent(
Intent.TYPES.SEND_TRANSACTION,
{destination: this.destination}
)
);
// Receiving Broadcast
IntentBroadcast.registerReceiver(Intent.TYPES.SEND_TRANSACTION, intent => {
widget.set('destinationAddress', intent.data.destination);
});
`

interstellar-core.IntentBroadcast service

interstellar-core.IntentBroadcast service is responsible for delivering Intents to correct Broadcast Receivers. It has two methods:
* sendBroadcast(intent) - to broadcast an Intent,
* registerReceiver(type, broadcastReceiver) - to register Broadcast Receiver of specific type.

interstellar-core.Config service

The Config service provides the system through which the client can retrieve configuration flags. It provides a get(configName) to which clients can retrieve values.

Conceptually, an application's configuration presents itself as a simple nested json object.

$3

interstellar-core.Config provider has 2 methods that App and Modules can use to define configuration values:
* addAppConfig(config) - used by App
* addModuleConfig(moduleName, config) - used by Modules

All config values added by modules are treated as default values that can be overwritten by the App config. For example, let's say interstellar-network module adds following config JSON using addModuleConfig:
`json
{
"horizon": {
"secure": true,
"hostname": "horizon-testnet.stellar.org",
"port": 443
}
}
`
To overwrite this module's configuration, an app needs to add following config JSON using addAppConfig:
`json
{
"modules": {
"interstellar-network": {
"horizon": {
"secure": false,
"hostname": "horizon.example.com",
"port": 80
}
}
}
}
`

$3

Once you have an instance of the config service (using normal angular DI mechanisms), you may access any previously loaded configuration using a "dot separated" accessor string. For example, say the App configuration data is the json object below:

`json
{
"horizon": {
"secure": true,
"hostname": "horizon-testnet.stellar.org",
"port": 443
}
}
`

You can retrieve the address for the horizon with:
`js
let hostname = Config.get("horizon.hostname");
`

Getting configuration values in Module is a little different. During configuration phase all modules' configurations are appended to modules object in the main config JSON. For example, let's say interstellar-network module adds following configuration:
`json
{
"horizon": {
"secure": true,
"hostname": "horizon-testnet.stellar.org",
"port": 443
}
}
`

Now, you can retrieve the address for the horizon with:
`js
let hostname = Config.get("modules.interstellar-network.horizon.hostname");
`

$3

In the spirit of failing fast, consumers of the config service can apply type restrictions to config variables, such that an exception will be thrown at the point of retrieval if the result is of the wrong type. For example, given a config object of {"foo": "bar"}, executing the statement Config.getNumber("foo")` will throw an exception because the result ("bar") is a string.