appex

nodejs web api with typescript

//----------------------------------------------
// app.js
//----------------------------------------------

var appex = require('appex');

var app = appex({ program : './program.ts' });

app.listen(3000);

//----------------------------------------------
// program.ts
//----------------------------------------------

// http://localhost:3000/
export function index(context) {

	context.response.send('home');
}

// http://localhost:3000/about
export function about(context) {

	context.response.send('about');
}

// http://localhost:3000/(.*)
export function wildcard (context, path) {
    
    context.response.send(404, path + "not found");
}

install

npm install appex

overview

appex is a nodejs web api framework built on top of the TypeScript programming language. It enables developers to create RESTful service endpoints by writing TypeScript functions, as well as providing reflection / type meta data derived from the languages type system.

• getting started
  • application
  • options
  • http server
  • express middleware
• creating services with typescript
  • app context
  • routing handlers
  • handler signatures
  • named handlers
  • index handlers
  • wildcard handlers
  • cascades
  • http verbs
  • middleware
  • exporting functions
  • handling 404
  • serving static files
• reflection
  • reflect everything
  • reflect specific types
• developing with appex
  • appex.d.ts declaration
  • structuring projects
• additional resources

## getting started

The following sections outline configuring appex.

### application

Setting up.

var appex   = require('appex');

var app   = appex({ program : './program.ts', 
                    devmode : true,
                    logging : true });

app.listen(3000);

### options

appex accepts the following startup options.

var options = { 
	// (required) location of source file.
	program    : './program.ts', 

	// (optional) recompile on request. (default:false) 
	devmode    : true,          

	// (optional) log to stdout. (default:false) 
	logging    : true,

	// (optional) user defined objects added to the app context.
	context    : {}
};

var app = appex( options );

### http server

Setting up appex on a nodejs http server.

var http = require('http');

var appex = require('appex');

var app = appex({ program : './program.ts' });

var server = http.createServer( app );

server.listen(3000);

### express middleware

Setting up as express middleware.

var express = require('express');

var appex = require('appex');

var app = express();

app.use(appex({ program : './program.ts' })); 

app.get('/', function(req, res) {

  res.send('Hello World');
  
});

app.listen(3000);

## creating services with typescript

The following section describes how to write http accessible functions with appex.

### app context

All appex functions are passed a application context object as their first argument. The app context object encapulates the http request and response objects issued by the underlying http server, as well as additional objects specific to appex. These are listed below:

// the app context
export function method(context) {
	
	// context.request    - the http request object.

	// context.response   - the http response object.

	// context.cascade    - appex cascade.

	// context.next       - the next function (express middleware)
}

### routing handlers

appex creates routes based on module scope and function name. consider the following:

export module services.customers {
	
	// url: http://[host]:[port]/services/customers/insert
	export function insert(context) { /* handle route */ }
	
	// url: http://[host]:[port]/services/customers/update
	export function update(context) { /* handle route */ }
	
	// url: http://[host]:[port]/services/customers/delete
	export function delete(context) { /* handle route */ }
}

// url: http://[host]:[port]/
export function index   (context) { /* handle route */ }

// url: http://[host]:[port]/about
export function about   (context) { /* handle route */ }

// url: http://[host]:[port]/contact
export function contact (context) { /* handle route */ }

// url: http://[host]:[port]/(.*)
export function wildcard (context, path) { /* handle route */ }

### handler signatures

appex supports three function signatures for http routing (named, index and wildcard). Functions that do not apply these signatures will not be routed.

### named handlers

Named handlers resolve urls to their current module scope + the name of the function.

Named handlers require the following signature:

• name - 'anything'
• argument[0] - app context
• returns - void (optional)

// http://[host]:[port]/about
export function about(context) {

	context.response.send('about page');
}

// http://[host]:[port]/users/login
export module users {

	export function login(context) {
		
		context.response.send('handle login');	
	}
}

### index handlers

Index handlers resolve urls to their current module scope.

Index handlers require the following signature:

• name - 'index'
• argument[0] - app context
• returns - void (optional)

// url: http://[host]:[port]/
export function index(context) { 

	context.response.send('home page');
}

export module blogs {
	
	// url: http://[host]:[port]/blogs
	export function index  (context) 
	{	
		context.response.send('blog index');
	}
}

### wildcard handlers

Wildcard handlers resolve their urls to their current module scope + url.

appex wildcard handlers allow for wildcard routing at a given module scope. Wildcard handlers support 'typed' url argument mapping, as denoted by the arguments annotation.

In addition, wildcard handlers also support optional arguments which can be specified with TypeScript's '?' on argument names.

appex wildcard handlers require the following signature:

• name - 'wildcard'
• argument[0] - app context
• argument[n] - 1 or more arguments to be mapped from the url
• returns - void (optional)

declare var console;

export module blogs {
	
	// url : http://[host]:[port]/blogs/2013/1/11   - matched

	// url : http://[host]:[port]/blogs/2013/01/11  - matched

	// url : http://[host]:[port]/blogs/2013/01/3rd - not matched - (see number annotation)

	// url : http://[host]:[port]/blogs/2013/01     - matched     - (see ? annotation)

	// url : http://[host]:[port]/blogs/2013        - not matched - (month is required)
	
    export function wildcard(context, year:number, month:number, day?:number) {

        context.response.json({ year: year, month: month, day: day})
    }
}

// url : http://[host]:[port]/
export function index(context) {

	context.response.send('home');
}

// url : http://[host]:[port]/(.*) 
export function wildcard(context, path) {

	context.response.send(404, 'not found');
}

note: appex supports boolean, number, string and any annotations on wildcard arguments. if no annotation is specified, appex interprets the argument as a string. the type 'any' is also interpreted as string.

note: wildcard functions should be declared last in any module scope. this ensures other routes will be matched first.

### cascades

appex supports a cascading attribute scheme on modules and functions. With this, developers can apply arbituary meta data for modules and functions that will propagate through scope. appex has two special cascade properties for middleware and http verb matching, which are described below, however consider the following code which illustrates the concept.

declare function cascade (qualifier:string, obj:any);

cascade({a: 10}); // global.

cascade('foo', {b : 20})
export module foo {

    cascade('foo.bar', {c : 30})
    export module bar {
            
        cascade('foo.bar.index', {d : 40})
        export function index(context) {
        
            //context.cascade
            //{
            //    "a": 10,
            //    "b": 20,
            //    "c": 30,
			//    "d": 40
            //}

            context.response.json( context.cascade );       
        }
    }
}

### http verbs

appex handles http verb matching with cascades. appex will recognise the 'verbs' property applied to the cascade to match against http verbs.

cascade('index', { verbs: ['get'] })
export function index (context) { 
        
    // only allow HTTP GET requests
    context.response.send('index')
}

cascade('index', { verbs: ['post', 'put'] })
export function submit (context) { 
    
    // only allow HTTP POST and PUT requests
    context.response.send('submit')
}

### middleware

appex supports middleware with cascades. appex middleware defined with cascades allows developers to scope middleware on single functions, or entire module scopes. appex will recognise the 'use' property applied to the cascade to invoke middleware.

the following demonstrates how one might use middleware to secure a site admin.

note: middleware 'must' call next or handle the request.

declare function cascade (qualifier:string, obj:any);

declare var console;

function authenticate(context) {

    console.log('authenticate')

	// call next() if authenticated, otherwise, handle the response.
    context.next(); 
}

function authorize(context) {

    console.log('authorize')

	// call next() if authorized, otherwise, handle the response.
    context.next(); 
}

// apply security middleware to admin scope.
cascade('admin', {use: [authenticate, authorize]}) 
export module admin {

    export function index(context) {
        
        console.log(context.cascade); // view cascade

        context.response.send('access granted!')
    }
}

// index handler has no middleware applied.
export function index (context) { 
    
    console.log(context.cascade); // view cascade

    context.response.send('home')
}

### exporting functions

appex will only route functions prefix with the TypeScript 'export' declarer. This rule also applied to modules. Developers can use this to infer notions of public and private at the http level.

consider the following example:

// module is not exported, and is therefore private.
module private_module {
	
	// function is exported, yet private as a http endpoint due to the 
	// parent module being private.
	export function public_method () { }
	
	// function is not exported, and is private to this module.
	function private_method() { }
}

// function is not exported, and is therefore private.
function private_function() { }

// function is exported, and therefore publically accessible.
export function public_function   (context) { 
	
	// this function can invoke private functions.
	private_function(); // ok
	
	// calling exported method in private module
	private_module.public_method(); // ok

	// calling non exported method in private module
	// private_module.private_method(); // bad

	context.response.send('public_function');
}

### handling 404

Use wildcard functions to catch unhandled routes.

// http:[host]:[port]/
export function index (context) { 

	context.response.send('home page');
}

// http:[host]:[port]/(.*)
export function wildcard (context, path) {

	context.response.send(404, path + ' not found');
}

## serving static files

Use wildcard functions with context.response.serve() to serve static content.

export module static {
	
	// http:[host]:[port]/static/(.*)
	export function wildcard(context, path) {

		context.response.serve('./static/', path);
	}
}

// http:[host]:[port]/
export function index (context) {

	context.response.send('home page');
}

// http:[host]:[port]/(.*)
export function wildcard(context, path) {

	context.response.send(404, path + ' not found');
}

## reflection

appex provides a reflection api derived from TypeScript's type system that developers can leverage to reflect type information declared throughout their appex modules.

the following section outlines how to use the reflection api.

### reflect everything

the appex reflection api is passed on the context.module.reflection property and is available to all appex handler methods. The following code will JSON serialize everything declared in your appex project and write it to the http response.

export function index (context:appex.web.Context) {
    
    context.response.json( context.module.reflection );
}

### reflect specific types

In typical scenarios, developers will want to leverage reflection meta data to generate service contacts and client side models. the reflection api lets you access meta data for the following types declared in your project.

• modules
• imports
• classes
• interfaces
• functions
• variables

to access specific type metadata, use the reflection.get([qualifier]) method, as demonstrated below.

export module models {
    
    export class Customer {

        public firstname   : string;

        public lastname    : string;

        public age         : number;
    }
}

export function index (context:appex.web.Context) {
    
    context.response.json( context.module.reflection.get('models.Customer') );
}

and methods..

function some_method(a:string, b:number, c?:boolean) : void { }

export function index (context:appex.web.Context) {
    
    context.response.json( context.module.reflection.get('some_method') );
}

....and variables...

var some_variable:number = 10;

export function index (context:appex.web.Context) {
    
    context.response.json( context.module.reflection.get('some_variable') );
}

## developing with appex

This section outlines development with appex.

### appex.d.ts declaration

If you develop on a TypeScript complicant editor (one that supports TS 0.9), appex comes bundled with a declaration file you can reference in your project. If installing appex via npm, your reference should be as follows.

/// <reference path="node_modules/appex/appex.d.ts" />

export function index (context:appex.web.IContext) { 
    
    context.response.send('hello');
}

export function wildcard(context:appex.web.IContext, path:string) {

    context.response.serve('./', path);
}

By referencing this in your project, you get the benefits of code completion and static type checking against both appex, and the nodejs core.

Additional declaration files may be obtained from here

### structuring projects

appex includes TypeScript's ability to reference source files with the 'reference' element. appex will traverse each source files references and include it as part of the compilation.

Developers can use this functionality to logically split source files into reusable components of functionality, as demonstrated below.

//---------------------------------------------------	
// file: app.js
//---------------------------------------------------

var appex = require('appex');

var app = appex ({ program : './index.ts' });

app.listen(3000);

//---------------------------------------------------	
// file: index.ts
//---------------------------------------------------

/// <reference path="users.ts" />
/// <reference path="pages.ts" />

//---------------------------------------------------	
// file: users.ts
//---------------------------------------------------

export module users {
	
	// http://[host]:[port]/users/login
	export function login  (context) { context.response.send('users.login') }
	
	// http://[host]:[port]/users/logout
	export function logout (context) { context.response.send('users.logout') }
}

//---------------------------------------------------	
// file: pages.ts
//---------------------------------------------------

// http://[host]:[port]/
export function index   (context) { context.response.send('home') }

// http://[host]:[port]/about
export function about   (context) { context.response.send('about') }

// http://[host]:[port]/contact
export function contact (context) { context.response.send('contact') }

export function wildcard (context, path) { context.response.send(404, ' not found') }

## additional resources

• typescript homepage
• typescript language specification
• typescript declarations repository