flachmann - Resource oriented API development

:warning: ATTENTION! :warning:

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

:books: 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:

| Property | Type | Required | Description | | --- | --- | --- | --- | | middleware | RequestHandler[] | false | Array of ExpressJS request handlers (middleware) that should be executed on every request to any subroute. |

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:

| Property | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | name | string | false | Overrides the default behavior of using the class name for the base route. Also does not pluralize or use kebab case | 'demo' | | prefix | boolean | false | URL prefix that will be appended before the name | '/api' | | middleware | RequestHandler[] | false | Array of ExpressJS request handlers (middleware) that should be executed on every request to any subroute. | |

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.

:warning: 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:

| Property | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | route | string | false | Overrides the default of using the kebab case version of the function name and let's you specify your own. Supports the same path syntax as ExpressJS | '/hello/:name' | | useResponse | boolean | false | If set to true it will behave like a normal ExpressJS request handler and expect you to use res.send() rather than returning a value or Promise | true | | middleware | RequestHandler[] | false | Array of ExpressJS request handlers (middleware) that should be executed on every request to any subroute. | |

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. :tada: Get merged :tada:

License

MIT

Contributors

Dominik Kundel [email protected]