flachmann
v1.0.0-alpha1flachmann - 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
- Fork the repository
git clone
your forked repository- Install the dependencies using
npm install
oryarn
inside the document - Create a new branch
- Do the respective changes, update the
README.md
file and test files if necessary. - Test your changes by running
npm test
- Push your changes and open a new Pull Request.
- :tada: Get merged :tada:
License
MIT
Contributors
Dominik Kundel [email protected]