For development lightweight server apps.
- Boilerplate project https://github.com/AsterAInpm/katrine-hello-world/
- Github project https://github.com/AsterAInpm/katrine
- npmjs.org https://www.npmjs.com/package/katrine
Add following dependencies, in your project
"dependencies": {
"@types/node": "9.6.7",
"katrine": "^1.4.4",
"typescript": "^3.3.3"
}
To start app you need just 2 necessary actions:
- Load atleast one valid Katrine controller with valid action
- Run the app
import { KatrineApp } from 'katrine';
/**
* Katrine requires directories by absolute path or relative path
* if dir path start with '.' (dot) Katrine will require relatively
* Else Katrine will require dirs by absolute path
*
* Any controllers must be annotated by @controller decorator
*/
KatrineApp.loadControllers([
'./controller/IndexController',
'./controller/UserController',
'./controller/AdminController',
]);
// public folder optionally
KatrineApp.setPublicFolder('public'); // express.js compatible public folder
// run with default settings
KatrineApp.run({});
To define controller use a @controller
decorator. Framework will require the file. When you call
typescript KatrineApp.loadControllers
and if class has @controller
decorator Katrine will recognize class
as actions holder.
KatrineController
is userfull class that contains few methods of rendering. And you will be able to render content by
different methods. KatrineController
is unnecessary, but strongly recommended for using.
Also without KatrineController
you could't use internal pug rendering system (View component)
import { KatrineController, controller } from 'katrine';
@controller
export default class IndexController extends KatrineController {
}
@action
annotation receives 2 params
- route:
string
, express.js compatible route - requestType:
HTTPRequestType
, POST or GET type
Actions can return Promise
or string
as result.
import { KatrineController, controller, action, HTTPRequestType } from 'katrine';
@controller
export default class SomeController extends KatrineController {
@action('/api/v1/*/delete', HTTPRequestType.POST)
delete(req): string {
const id = req.body.id;
return JSON.stringify({
status: 'success',
data: id
});
}
// example of async action
@action('/user/random')
async getRandomUserAction(req): Promise<any> {
const userData = await User.findRandomUser();
return JSON.stringify({
status: 'success',
userId: userData.id
});
}
}
Framework uses pug as template engine. All render methods gathered in
KatrineController
// Pug file. Which you prefer to use when method render is called
protected getLayout(): string;
// renders pug file with layout `getLayout()`
protected render(viewPath: any, params?: {}): any;
// renders plain string. Method usefull when you don't need to use separete pug template for action
protected renderString(content: string, params?: {}): any;
// renders particular pug template in particular layout
protected renderLyout(viewPath: string, layoutPath: string, params: any): any;
Example of real controller.
import { action, KatrineController, controller } from 'katrine';
@controller
export default class IndexController extends KatrineController {
/**
* Method used by KatrineController to define layout for any render* methods.
*/
getLayout() : string {
return './view/layout/main.pug';
}
@action('/') // express compatible route
homePageIndexAction(req): string {
return this.render('./view/actions/index.pug', {});
}
@action('404') // Will call this action when route doesn't match on any valid actions
pageNotFound(req): string {
return this.render('./view/system/404.pug',{});
}
@action('403') // Will call this action when RBAC system rejects request by access rules.
accessDenied(req): string {
return this.render('./view/system/403.pug',{});
}
}
There are 2 methods to login and logout user.
KatrineApp.auth(requestSession);
KatrineApp.authLogoutUser(requestSession);
Full example of posible UserController within your app.
@controller
export default class UserController extends KatrineController {
private createUser(userData) : UserInterface {
const user = new UserObject(userData.id, userData.role, userData);
user.setSigned();
return user;
}
@accessByAuth(AuthStatus.NOT_LOGGED_IN)
@action('/user/login', HTTPRequestType.POST)
async loginUserAction(req) {
const email = req.body.email;
const password = req.body.password;
try {
const userData = await User.findByEmailAndPassword(email, password);
if (userData) {
const userObject = this.createUser(userData);
KatrineApp.auth(req.session, userObject);
} else {
throw 'User Email or password incorrect';
}
return JSON.stringify({
status: 'success',
messsage: '',
data: {
role: userData.role,
id: userData.id
}
});
} catch (e) {
console.error(e);
return JSON.stringify({
status: 'error',
message: typeof e === 'string' ? e : 'User Email or password incorrect'
})
}
}
@accessByAuth(AuthStatus.LOGGED_IN)
@action('/user/logout')
logOutAction(req): string {
KatrineApp.authLogoutUser(req.session);
return JSON.stringify({
status : 'success'
});
}
}
To restrict access to actions there are two decorators. Decorators works by OR logic
e.g: if (!rule_1 || !rule_n) reject ...
, so you can combine them to make more complex logic of access control flow
// allows user to call action if his role equals `roles` param
@accessByRole(roles: string | string[])
// allows user to call action according to his Auth state `signed in / not signed in`
@accessByAuth(auth: AuthStatus)
Fill free to make issue reports, or request a features
My email asterai.com@gmail.com
Alex.