flachmann - Resource oriented API development

⚠️ ATTENTION! ⚠️

This is very much work in progress. I started this to learn a bit more about TypeScript's Decorator support. More coming soon

Requirements

This package currently only works with TypeScript and is an extension to Express.

Installation

You can install this package via npm or yarn.

Using npm:

npm install flachman --save

Using yarn:

yarn add flachmann

Usage

1. Import the library in your file:

import Flachmann from 'flachmann';

2. Initialize App:

a) The first time you use it in your app:

const App = Flachmann(yourExpressApp);

b) Subsequent files don't have to pass in an express app.

const App = Flachmann(yourExpressApp);

3. Use the different decorators on classes and methods

📚 API

@App.Base(config?: BaseConfig)

Type: Class Decorator

Info: Registers the class as the main router for the application. Meaning it does not generate any base route.

Config Parameters:

Example:

@App.Base()
class Api {
  @App.get('/')
  someMethod() {
    return 'Ahoy!'
  }
}
// Creates the following endpoints:
// GET / => 'Ahoy!'

@App.Resource(resourceNameOrConfig?: string | ResourceConfig)

Type: Class Decorator

Info: Registers the class as a route while taking the class name and turning it into a base route. For this it will modify the name using kebab case and pluralize to determine the the base route.

Config Parameters:

Example:

@App.Resource()
class Person {
  @App.get('/')
  someMethod() {
    return 'Ahoy!'
  }
}
// Creates the following endpoints:
// GET /people => 'Ahoy!'

@App.get(routeOrConfig: string | RouteConfig)
@App.post(routeOrConfig: string | RouteConfig)
@App.delete(routeOrConfig: string | RouteConfig)
@App.patch(routeOrConfig: string | RouteConfig)
@App.put(routeOrConfig: string | RouteConfig)

Type: Method Decorator

Info: Registers the method as a route handler using the respective HTTP request type: GET, POST, DELETE, PATCH, PUT. If you don't specify a name it will kebab case the function name.

⚠️ Behavior: Unless you set the useResponse config to true the system will check the return value of the method you tagged and send that as a response. Alternatively your method can return a Promise for async operations.

Config Parameters:

Example:

@App.Resource()
class Greeting {
  @App.get()
  hello(req: Request) {
    return 'Hello';
  }
 
  @App.get({ useResponse: true })
  ahoy(req: Request, res: Response) {
    res.status(418).type('text/xml').send('<Say>Ahoy!</Say>');
  }
 
  @App.post({
    route: '/moin',
    middleware: [bodyParser.urlencoded({ extended: false })]
  })
  someMethodName() {
    return 'Moin moin!';
  }
 
  @App.delete('/bye')
  someOtherMethod() {
    return 'Bye :(';
  }
}
// Creates the following endpoints:
// GET /greetings/hello => 'Hello'
// GET /greetings/ahoy => <Say>Ahoy!</Say>
// POST /greetings/moin => 'Moin moin!'
// DELETE /greetings/bye => 'Bye :('

@App.all(routeOrConfig: string | RouteConfig)

Type: Method Decorator

Info: Behaves the same way as the other method decorators and has the same options. It will respond to all HTTP types though.

Examples

Check out the test/test.ts and test/test-resource.ts for example code.

Contribute

1. Fork the repository
2. git clone your forked repository
3. Install the dependencies using npm install or yarn inside the document
4. Create a new branch
5. Do the respective changes, update the README.md file and test files if necessary.
6. Test your changes by running npm test
7. Push your changes and open a new Pull Request.
8. 🎉 Get merged 🎉

License

MIT

Contributors

Dominik Kundel dominik.kundel@gmail.com