nodulator/README.md

Nodulator ============

# Nodulator


## Concept

Nodulator is designed to make it more easy to create highly modulable REST APIs, with integrated ORM (database agnostic) in CoffeeScript.


Open [exemple.coffee](https://github.com/Champii/Nodulator/blob/master/exemple.coffee) to see a full working exemple

___
### Compatible modules
- [Nodulator-Assets](https://github.com/Champii/Nodulator-Assets): Automatic assets management and inclusion
- [Nodulator-Angular](https://github.com/Champii/Nodulator-Angular): Angular class set, add inheritance systeme and default behaviour.

___
## Jump To
- [Installation](#installation)
- [Project Generation](#project-generation)
- [Config](#config)
- [Resource](#resources)
  - [Class methods](#class-methods)
  - [Instance methods](#instance-methods)
- [Overriding and Inheritance](#overriding-and-inheritance)
  - [Override default behaviour](#override-default-behaviour)
  - [Complex inheritance system](#complex-inheritance-system)
- [Route](#routes)
  - [Route Object](#route-object)
  - [DefaultRoute](#default-route-object)
  - [Route Inheritance](#route-inheritance)
- [Auth](#auth)
- [Restriction](#restriction)
- [DOC (Deprecated)](#doc)
- [TODO](#todo)

___
### Installation

Just run :
    npm install nodulator

After you can require `Nodulator` as a module :

```coffeescript
    Nodulator = require 'nodulator'
```

___
### Project Generation
(BETA Feature)
USE IT IN AN EMPTY FOLDER

You can get global nodulator : `$> npm install -g nodulator`
And then: `$> Nodulator init`

It creates the following structure :
```
main.coffee
package.json
settings/
server/
├── index.coffee
├── processors/
│   └── index.coffee
└── resources/
    └── index.coffee
```

And then find for every Nodulator submodules installed, and call their respective `init` method.

You can immediately start to write resources in server/resources !

___
### Config

First of all, the config process is absolutly optional.
If you don't give Nodulator a config, it will assume you want to use SqlMem DB system, with no persistance at all. Usefull for heavy tests periods.

If you prefere to use a persistant system, here is the procedure :

```coffeescript
    Nodulator = require 'nodulator'

    Nodulator.Config
      dbType: 'Mongo'       # You can select 'SqlMem' to use inRAM Document (no persistant data, used    to test) or 'Mongo' or 'Mysql'
      dbAuth:
        host: 'localhost'
        database: 'test'
        port: 27017       # Can be ignored, default values taken
        user: 'test'      # For Mongo and SqlMem, these fields are optionals
        pass: 'test'      #
```

The module provide 2 main Objects :

```coffeescript
    Nodulator.Resource
    Nodulator.Route
```

___
### Resources

A `Resource` is a class permitting to retrive and save a model from a DB.

Here is an exemple of creating a `Resource`

```coffeescript
    PlayerResource = Nodulator.Resource 'player'

    PlayerResource.Init()
    # /!\ Never forget to call Init() /!\ #
```

You can pass several params to `Nodulator.Resource` :

```coffeescript
    Nodulator.Resource name [, Route] [, config]
```

#### Class methods

Each `Resource` provides some 'Class methods' to manage the specific model in db :

```coffeescript
    PlayerResource.Fetch(id, done)
    PlayerResource.FetchBy(field, value, done)
    PlayerResource.List(id, done)
    PlayerResource.ListBy(field, value, done)
    PlayerResource.Deserialize(blob, done)
```

The `Fetch` method take an id and return a `PlayerResource` intance to `done` callback :

```coffeescript
    PlayerResource.Fetch 1, (err, player) ->
      return console.error err if err?

      [...] # Do something with player
```

You can also call `FetchBy` method to give a specific field to retrive.
It can be unique, or the first occurence in DB will return.

You can list every models from this `Resource` thanks to `List` :

```coffeescript
    PlayerResource.List (err, players) ->
      return console.error err if err?

      [...] # players is an array of player instance
```

Like `Fetch`, you can `ListBy` a specific field.

The `Deserialize` method allow to get an instance of a given `Resource`.
Never use `new` operator directly on a `Resource`, else you might bypass the relationning system.
`Deserialize` method used to make pre-processing work (like fetching related models) before instantiation.

#### Instance methods

A player instance has some methods :

    player.Save(done)
        Used to save the model in DB. The callback take 2 arguments : (err, instance) ->

    player.Delete(done)
        Used to delete the model from the DB. The callback take 1 argument : (err) ->

    player.Serialize()
        Used to get every object properties, and return it in a new object.
        Generaly used to get what to be saved in DB.

    player.ToJSON()
        By default, it calls Serialize().
        Generaly used to get what to send to client.

____
### Overriding and Inheritance

You can inherit from a `Resource` to override or enhance its default behaviour, or to make a complex class inheritance system built on `Resource`

#### Override default behaviour
In CoffeeScript its pretty easy:

```coffeescript
    class UnitResource extends Nodulator.Resource 'unit'
      # Here we override the constructor to attach a weapon resource
      # Never forget to call super(blob), or the instance will never be populated by DB fields
      constructor: (blob, @weapon) ->
        super blob

      # We create a new instance method
      LevelUp: (done) ->
        @level++
        @Save done

      # Here we override the Deserialize class method, to fetch the attached WeaponResource
      @Deserialize: (blob, done) ->
        if !(blob.id?)        # If the resource isnt deserialized from db, don't fetch attached resource
          return super blob, done

          WeaponResource.FetchByUserId blob.id, (err, weapon) =>
            res = @
            done(null, new res(blob, weapon))

      UnitResource.Init()
```

#### Complex inheritance system

Given the last exemple, here is a class that inherits from `UnitResource`

```coffeescript
    class PlayerResource extends UnitResource.Extend 'player'

      SpecialBehaviour: (args, done) ->
        [...]

    PlayerResource.Init();
```

You can also define abstract class, to avoid corresponding model to be created/initialized :

```coffeescript
    class UnitResource extends Nodulator.Resource 'unit', {abstract: true}

    UnitResource.Init();
```

Of course, abstract class are only designed to be inherited. (Please note that they can't have Route attached)

___
### Routes

#### Route Object

Nodulator provides a `Route` object, to be attached to a `Resource` object in order to describe routing process.

```coffeescript
    class UnitResource extends Nodulator.Resource 'unit', Nodulator.Route
```

There is no need of `Init()` here.
Default `Nodulator.Route` do nothing.
You have to inherit from it to describe routes :

```coffeescript
    class UnitRoute extends Nodulator.Route
      Config: ->
        super()
        @Add 'get', '/:id', (req, res) =>
          # The @resource field points to attached Resource
          @resource.Fetch req.params.id, (err, unit) ->
            return res.status(500).send err if err?

            res.status(200).send unit.ToJSON()

        @Add 'post', (req, res) ->
          res.status(200).end();
```

This `Route`, attached to a `Resource`, add 2 endPoints :

    GET  => /api/1/units/:id
    POST => /api/1/units

Each `Route` have to implement a `Config()` method, calling `super()` and defining routes thanks to `@Add()` call.
Here is the `@Add()` call definition :

```coffeescript
    Nodulator.Route.Add verb, [endPoint = '/'], [middleware, [middleware, ...]], callback
```

#### Default Route Object

Nodulator provides also a standard route system for lazy : `Nodulator.Route.DefaultRoute`.
It setup 5 routes (exemple when attached to a PlayerResource) :

    GET     /api/1/players       => List
    GET     /api/1/players/:id   => Get One
    POST    /api/1/players       => Create
    PUT     /api/1/players/:id   => Update
    DELETE  /api/1/players/:id   => Delete

#### Route Inheritance

You can inherit from any route object :

```coffeescript
    class TestRoute extends Nodulator.Route.DefaultRoute
```
And you can override existing route by providing same association verb + url. Exemple :

```coffeescript
    class TestRoute extends Nodulator.Route.DefaultRoute
      Config: ->
        super()

        # Here we override the default Get from Id
        @Add 'get', '/:id', (req, res) =>
          [...]
```
___
##Auth

Authentication is based on Passport
You can assign a Ressource as AccountResource :

```coffeescript
    config =
      account: true

    class PlayerResource extends Nodulator.Resource 'player', config
```

Defaults fields are 'username' and 'password'

You can change them (optional) :

```coffeescript
    config =
      account:
        fields:
          usernameField: "login"
          passwordField: "pass"

    class PlayerManager extends Nodulator.Resource 'player', config
```


It creates a custom method from usernameField

    *FetchByUsername(username, done)

      or if customized

    *FetchByLogin(login, done)

    * Class methods

It defines 2 routes :

    POST    /api/1/players/login
    POST    /api/1/players/logout

It setup session system, and thanks to Passport,
It fills req.user variable to handle public/authenticated routes

You have to `extend` yourself the `post` default route (for exemple) of your resource to use it as a signup route.

#Restriction#

USER:

You can restrict access to a resource :

```coffeescript
    config =
      account: true
      restricted: 'user' #Can be 'user', 'auth', or an object

    class PlayerResource extends Nodulator.Resource 'player', config
```

This code create a APlayer resource that is an account,
and only player itself can access to its resource (GET, PUT and DELETE on own /api/1/players/:id)

POST and GET-without-id are still accessible for anyone (you can override them)
/!\ 'user' keyword must only be used on account resource

AUTH:

You can restrict access to a resource for authenticated users only :

```coffeescript
    PlayerResource = Nodulator.Resource 'player',
      restricted: 'auth'
```


This code create a ATest resource that can only be accessed by auth users


OBJECT:

You can restrict access to a resource for users that have particular property set :

```coffeescript
    PlayerResource = Nodulator.Resource 'player',
      restricted:
        group: 1
        x: 'test'
```

It will deny access to whole resource for any users that don't have theses properties set

It's not possible anymore to put a certain rule on a certain route. Theses rules apply to the whole resource.

___
## DOC
 (DEPRECATED)

  Nodulator

    Nodulator.Resource(resourceName, [config])

      Create the resource Class to be extended (if necessary)

    Nodulator.Config(config)

      Change config

    Nodulator.app

      The express main app object

  Resource

  (Uppercase for Class, lowercase for instance)

    Resource.Route(type, url, [restricted], done)

      Create a route.

      'type' can be 'all', 'get', 'post', 'put' and 'delete'
      'url' will be concatenated with '/api/{VERSION}/{RESOURCE_NAME}'
      'restricted' is optional and defines if user must be restricted to see
      'done' is the express app callback: (req, res, next) ->

    Resource.Fetch(id, done)

      Take an id and return it from the DB in done callback: (err, resource) ->

    Resource.List(done)

      Return every records in DB for this resource and give them to done: (err, resources) ->

    Resource.Deserialize(blob, done)

      Method that take the blob returned from DB to make a new instance

    resource.Save(done)

      Save the instance in DB

      If the resource doesn't exists, it create and give it an id
      It return to done the current instance

    resource.Delete(done)

      Delete the record in DB, and return affected rows in done

    resource.Serialize()

      Return every properties that aren't functions or objects or are undefined
      This method is used to get what must be saved in DB

    resource.ToJSON()

      This method is used to get what must be send to client
      Call @Serialize() by default, but can be overrided


## ToDo

  By order of priority

    Error management
    Better++ routing system (Auto add on custom method ?)
    General architecture and file generation
    Advanced Auth (Social + custom)
    Basic view system
    Relational models