loopback/node_modules/asteroid-module/README.md

# asteroid-module
v0.0.1

## About

Asteroid applications are a combination of regular Node.js modules and Asteroid modules. Asteroid modules may be initialized using JavaScript or by writing config files.

## Using Asteroid Modules

There are two distinct ways to use an Asteroid Module in your application.

### App API

The `app` API allows you to define [data sources](../data-source) and [models](../model) in regular Node JavaScript. [See the docs for more info](../../readme.md#API).

### Config Files

You may also define [data sources](../data-source), [models](../model) and other asteroid modules by writing `config.json` files. See the documentation for a given module to see what config data it requires.

## Extending Asteroid

The core of asteroid is very lightweight and unopionated. All features are added on as `AsteroidModule`s. This means you can add your own functionality, modify existing functionality, or extend existing functionality by creating your own `AsteroidModule` class.

An `AsteroidModule` is an abstract class that provides a base for all asteroid modules. Its constructor takes an `options` argument provided by a `config.json`. It is also supplied with dependencies it lists on its constructor based on information in the `config.json` file.

See [model](../model) for an example.

### AsteroidModule.dependencies

An asteroid module may define dependencies on other modules that can be configured in `config.json`. Eg. the [collection](../collection/lib/collection.js) module defines a [model](../model) dependency.

    Collection.dependencies = {
      model: 'model'
    }
    
A configuration then must define:

    {
      "dependencies": {
        "model": "some-model-module"
      }
    }
    
Where `some-model-module` is an existing `model` instance.

### AsteroidModule.options

Asteroid Modules may also describe the options they accept. This will validate the configuration and make sure users have supplied required information and in a way that the module can use to construct a working instance.

Here is an example options description for the [oracle database connection module](../connections/oracle-connection).

    OracleConnection.options = {
      'hostname': {type: 'string', required: true},
      'port': {type: 'number', min: 10, max: 99999},
      'username': {type: 'string'},
      'password': {type: 'string'}
    };

**key** the option name given in `config.json`.

**type** must be one of:

 - string
 - boolean
 - number
 - array
 
**min/max** depend on the type

    {
      min: 10, // minimum length or value
      max: 100, // max length or value
    }