An organic web framework for organized web servers.

upcoming features - known issues - send suggestion

Organiser is a web framework focused on provinding the best developing and maintenance experience, benefiting from Ecmascript's new definitions, with support from Babel.

Our goal is having an organized and organic server. But what does that mean?

It means that you can bring complex highly scalable systems to life, with easy maintaining, without having to learn hard syntaxes. It is organized because of its well-known syntax, used in Spring Boot, for example, and it is organic because Organise makes sense: it is just like telling the server what it should do, in almost natural-like language.

Organiser works with inversion of control principles, creating one of the most powerful environments for MVC development in Node.js, for example. Just tell what you want through its decorators and let the magic happen.

⚠️

Organiser is in beta stage. It's not recommended for production usage yet.

1. Install
2. Examples
3. Events
4. Modules
5. @Arguments - Inversion of Control
6. Documentation
7. Team
8. License

Install

This is a Node.js module. Therefore, beforehand, you need to download and install Node.js. Node.js 6.0.0 or higher is required.

Assuming that you have already used the npm init command, run:

$ npm install organiser --save

Examples

• organiser-helloworld

A server with only a GET endpoint at localhost:3000 (default) that shows Hello, world! as plain text.

import { Server, GET, Response, MediaType } from 'organiser'

class HelloWorld {
  @GET
  async foo () {
    return Response.ok('Hello, world!', MediaType.TEXT_PLAIN).build()
  }
}

const server = new Server() // creates a new instance of Organise
server.routes(HelloWorld) // register controllers, passing their classes by reference
server.boot() // start server

• organiser-agenda

Virtual personal agenda, with notes and contacts, using NeDB.

import { Server, Modules } from 'organiser'
import { NotesController } from './controllers/notes'
import { ContactsController } from './controllers/contacts'

const server = new Server({
  name: 'Agenda',
  internal: {
    debug: true
  }
})

server.modules(Modules.bodyParser())
server.routes(NotesController, ContactsController)
server.boot()

Events

Work in progress...

Modules

You can use how many modules, before and/or after a request, as you wish. We support context and connect middlewares/modules styles.

Modules defined in server.modules(module1, module2, module3, ...) will be executed before every controller, in a sequence order (module1 → module2 → module3 → ... → controller). When calling server.modules() with parameters, it returns an object containing a function called after(...), that lets you register modules the same way, but they will run after every controler. Calling it without parameters will return an object with before(...) and after(...).

When you register routes through server.routes(ControllerClass1, ControllerClass2, ControllerClass3, ...), it also returns an object with before(...) and after, letting you register modules only for the routes passed as parameters.

Using @ModuleBefore(module1, module2, module3, ...) and @ModuleAfter(module4, module5, module6, ...) above a class or function reproduces the same behavior.

Built-in modules

• ✔️ Body Parser Modules.bodyParser(options)
• ✔️ Raw Body Parser Modules.rawBodyParser(options)

Example

import { Server, GET, Response, Modules, ModulesBefore, ModulesAfter } from 'organiser'

function hello (context) {
  return new Promise((resolve) => {
    console.log('hello executed!')
    console.log('You can add properties to the request context and use their values in other modules!')
    context.bye = 'See you!'
    context.luckNumber = Math.floor(Math.random() * 10) + 1
    resolve()
  })
}

function bye (context) {
  return new Promise((resolve) => {
    console.log('bye executed!')
    context.expectedResponse = Response.ok({ bye: context.bye, luckNumber: context.luckNumber }).build()
    resolve()
  })
}

@ModulesBefore(hello)
class Foo {
  @GET
  @ModulesAfter(bye)
  async bar () {
    return Response.ok({ foobar: true }).build()
  }
}

const server = new Server()
server.modules(Modules.bodyParser())
server.routes(Foo).before(
  () => console.log('First module executed!'),
  () => console.log(`Keep going...`)
).after(
  () => console.log('last module executed!')
)
server.boot()

Work in progress...

@Arguments - Inversion of Control

Through the Arguments decorator, you can inject dependencies anywhere, anytime. Just use the class of the desired instance and Organised will take care of the rest.

When used above classes, the respective class' constructor will be called with the parameters passed through the Arguments decorator.

When used above functions, it only supports one parameters: the data model (object containing properties that Organiser should retrieve). The data model supports inner models (functions returning objects).

Example

import { Arguments, Path, PUT, Types } from 'organiser'
import ContactsService from '../services/ContactsService'
import Contact from '../models/Contact'
import logEntity from '../utils/exampleLog'

@Arguments(ContactsService, logEntity)
@Path('contacts')
export class ContactsController {

  constructor (service, entityLogger) {
    this.service = service
    this.logger = entityLogger
  }

  @POST
  @Path('{userId}') // => "/contacts/123"
  @Arguments({
    userId: Types.INTEGER,
    contact: Contact
  })
  async create ({ userId, contact }) { // userId = 123, contact = { ... }
    contact.ownerId = userId
    return Response
            .status(201) // Created
            .entity(this.logger(await this.service.create(contact)))
            .build()
  }

}

// '../models/Contact'

import { Types } from 'organiser'

export default function Contact () {
  return {
    id: Types.INTEGER,
    name: Types.STRING,
    email: Types.STRING,
    ownerId: Types.INTEGER
  }
}

// '../utils/exampleLog'

export default function (entity) {
  console.log(entity)
  return entity
}

• Contact is a function that returns an object. This is how you define a model in Organise.
• ContactsService is just a regular class, used as a service. You can also use Arguments to inject parameters in its constructor (calling other services instances, for example).

Read more about how the Arguments decorator works with functions here.

Documentation

Available decorators

• ✔️ Arguments (accept parameters)
• ✔️ Path (accept parameters)
• ✔️ ModulesAfter (accept parameters)
• ✔️ ModulesBefore (accept parameters)
• ✔️ GET (functions only)
• ✔️ HEAD (functions only)
• ✔️ POST (functions only)
• ✔️ PUT (functions only)
• ✔️ DELETE (functions only)
• ✔️ OPTIONS (functions only)
• ✔️ TRACE (functions only)
• ✔️ PATCH (functions only)

Model property types

• ️️✔️ Types.UUID: 'uuid'
• ✔️ Types.STRING: 'string'
• ✔️ Types.BOOLEAN: 'boolean'
• ✔️ Types.INTEGER: 'integer'
• 🚧 Types.DOUBLE: 'double'
• 🚧 Types.FLOAT: 'float'
• 🚧 Types.DATE: 'date'
• 🚧 Types.FILE: 'file'
• ✔️ Types.CLIENT_REQUEST: 'clientRequest'
• ✔️ Types.SERVER_RESPONSE: 'serverResponse'

It is encouraged the usage of Types.* instead of their respective string version, for versioning purposes.

Data models

Work in progress...

Team

Created and developed by Arthur Arioli Bergamaschi, supervised by the JavaScript Advanced Core (NAJaS - Núcleo Avançado de JavaScript) at Fatec Taquaritinga.

License

Licensed under MIT.

Disclaimer: Organiser is still a work in progress. Methods and behavior can change along the way.