# @jeaks03/overseer

> Just another TypeScript Back-End framework

Latest version **1.2.33** (published 2019-05-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @jeaks03/overseer
pnpm add @jeaks03/overseer
yarn add @jeaks03/overseer
bun add @jeaks03/overseer
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.33 |
| Published | 2019-05-05 |
| First published | 2019-01-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=8.9 |
| Dependencies | 9 |
| Unpacked size | 170 KB |
| Known vulnerabilities | 0 (+27 in 2 direct dependencies) |
| Install scripts | no |
| Maintainers | jeaks03 |
| Keywords | overseer, typescript, aspect-oriented, aspect, aop, framework, backend, server, lightweight |

## Links

- npm: https://www.npmjs.com/package/@jeaks03/overseer
- Repository: https://github.com/paulcosma97/overseer
- Homepage: https://github.com/paulcosma97/overseer#readme
- Issues: https://github.com/paulcosma97/overseer/issues
- npm.io page: https://npm.io/package/@jeaks03/overseer

## Dependencies (9)

- [axios](https://npm.io/package/axios.md) ^0.18.0
- [npmlog](https://npm.io/package/npmlog.md) ^4.1.2
- [deasync](https://npm.io/package/deasync.md) ^0.1.14
- [promisify](https://npm.io/package/promisify.md) 0.0.3
- [jsonwebtoken](https://npm.io/package/jsonwebtoken.md) ^8.4.0
- [@jeaks03/cached](https://npm.io/package/@jeaks03/cached.md) *
- [@jeaks03/logger](https://npm.io/package/@jeaks03/logger.md) *
- [reflect-metadata](https://npm.io/package/reflect-metadata.md) ^0.1.13
- [@types/jsonwebtoken](https://npm.io/package/@types/jsonwebtoken.md) ^8.3.2

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.2.33 (latest) — 2019-05-05
- 1.2.32 — 2019-05-05
- 1.2.31 — 2019-05-05
- 1.2.30 — 2019-05-05
- 1.2.29 — 2019-04-14
- 1.2.28 — 2019-04-14
- 1.2.27 — 2019-04-14
- 1.2.26 — 2019-04-14
- 1.2.25 — 2019-04-14
- 1.2.24 — 2019-04-14
- 1.2.23 — 2019-04-14
- 1.2.22 — 2019-04-13
- 1.2.21 — 2019-04-13
- 1.2.20 — 2019-04-13
- 1.2.19 — 2019-04-13
- … 50 more at https://npm.io/package/@jeaks03/overseer/versions

## README

# Overseer

Overseer is a Typescript Aspect-Oriented framework for backend which takes inspiration from Spring-boot and Angular.

## Installation

Before you begin, make sure your development environment includes Node.js® and an npm package manager.

### Node.js
Overseer requires Node.js version 8.x or 10.x.
 - To check your version, run node -v in a terminal/console window.
 - To get Node.js, go to nodejs.org.

Creating a Overseer project is as simple as:

```bash
npx @jeaks03/typescript-base -o
```

The ```npx @jeaks03/typescript-base``` part creates a base for a typescript project and the ```-o``` flag lets the installer know that it is an Overseer framework and makes the proper adjustments.

## Minimal 'Hello World' example

*index.ts*
```typescript
import { Overseer } from '@jeaks03/overseer-core';
Overseer.serve(module, 8000);
```

*my.controller.ts*
```typescript
import { Requisite, Pathway } from '@jeaks03/overseer-core';

@Requisite
export class MyController {

    @Pathway({ path:'/hello' })
    sayHello() {
        return {
            message: 'hello world!'
        }
    }
}
```
This example opens a ```http server``` that listens on port ```8000``` and registers a ```GET``` endpoint ```/hello``` that returns the "hello world" message.
To start the application run:
```bash
npm run dev
```

#### Explaining the magic
- The ```Overseer.serve(8000)``` line lets the framework know where the **sources root** is located, and what the port desired port is.
 - ```@Requisite``` makes transforms the class into an **injectable** and lets the framework find it. More on injectables and this decorator later.
 - ```@Pathway``` marks the method as a handler for the given path. The method is called when the endpoint is reached. More on this later.

## Documentation
Section in which I explain how the framework functions.
### Project Structure
For the framework to work correctly it must have it's directory structure as follows:
 - index.ts -- doesn't matter where it is. Preferably in ```/src```
 - resources -- ( directory ) it must be one level above *index.ts* file. So if your main file is ```/src/index.ts``` then the resources directory must be ```/resources/```.
 - public -- ( directory ) it must be inside the resources directory. ```/resources/public```

In the **resources** directory can be stored any kind of project files you need and access them freely. Inside it is the **public** directory where all the files are visible to the http server. 

Let's say that you have a file named *index.html* inside and the server open on port *8000*. If you make a request on ```localhost:8000/index.html``` the file will be sent. 
**Note:** If the file is named ```index.html``` then the file will be available on both ```localhost:8000/index.html``` and ```localhost:8000/```

### Decorators
Documentation details regarding the decorators.
#### @Requisite -- and dependency injection
 This decorator is used to mark the class as an injectable. Yes, Overseer also handles dependency injection in a manner similar to Angular's. In order to inject a requisite it must be a parameter for the constructor.

 In order to let the framework find the requisites, all files that contain such classes **must** have their name ending in
  - ```.controller.ts```
  - ```.service.ts```
  - ```.component.ts```
 
 Example of dependency injection:

 *my.service.ts*
 ```typescript
 import { Requisite } from '@jeaks03/overseer-core';
 
 @Requisite
 export class MyService {
     public log(message: string): void {
         console.log(message);
     }
  }
 ```
  *my-other.service.ts*
 ```typescript
 import { Requisite } from '@jeaks03/overseer-core';
 import MyService from './my.service';
 
 @Requisite
 export class MyOtherService {
    constructor(private myService: MyService) {}
 
     private onInit(): void {
         this.myService.log('I got initialized!');
     }
  }
 ```
 
#### @Pathway
 This decorator marks a method as the handler of the given path. It requires an argument of type ```WayDetails``` which has the following attributes:
  - path -- *string*: the path for the endpoint to map. Default: ```/```
  - method -- *string*: http method. Default: ```GET```
  - statusCode -- *number*: http status code. Default: ```200```
  - produces -- *string[]*: list of content types that can be produced by this handler. Default: ```['application/json']```
  - consumes -- *string[]*: list of content types that can be consumed by this handler. Default: ```['application/json', 'multipart/form-data', 'application/x-www-form-urlencoded']``` 
  - guards -- *Guard[]*: list of ```Guard``` implementations. This works just like Angular's guard security. Default: ```[]```

#### @LifecycleEvent
 This decorator is used on requisites to mark a method as a lifecycle event. These events are triggered at a certain time during their life.
 
 It accepts a string as a sort of *event type* to let it know when to trigger the method. These arguments are:
 - "onInit" -- method is triggered shortly after the instantiation
 - "afterInit" -- method is triggered after all requisites have been instantiated

#### @OnInit
 Shorthand version of ```@LifecycleEvent('onInit')```

#### @AfterInit
 Shorthand version of ```@LifecycleEvent('afterInit')```

### Base classes 101

#### RequisiteManager
This class handles and contains all the requisites.

An instance of this class can be imported under the name of ```Requisites``` as a ```RestrictedRequisiteManager``` interface.


RestrictedRequisiteManager:
```typescript
interface RestrictedRequisiteManager {
    addInstance: (instance, isController?: boolean) => void;
    find: <T>(clazz: Class<T>) => T;
    findByName: <T>(className: string) => T;
    findAll: <T>(clazz: Class<T>) => T[];
}
```

#### Authentication
In order to secure your application, you must provide an implementation of this class as a requisite. The default authentication 
implementation provided is ```NoAuthentication``` which basically behaves as if there is no security.

In order to create an instance for any ```Authentication``` implementation you have to pass a ```UserProvider``` to the constructor.
`UserProvider` interface is a function that looks like this: `(username: string) => UserDetails | Promise<UserDetails>`

Overseer ships with the following implementations:
- NoAuthentication
- BasicAuthentication
- JWTAuthentication

Here is an example of how to secure your application using basic auth:
```ts
export class SecurityComponent {
    constructor(private database: DatabasePlaceHolder) { }

    @OnInit()
    secureApp() {
        const auth = new BasicAuthentication((username: string) => this.database.findUser(username));
        Requisites.addInstance(auth);
    }
}
```

#### Converter
This class can be extended to create converters that understand other content types, and it looks like this:
```ts
export class Converter {
    public getContentType(): string;

    public canRead(target: string, contentType: string): boolean;
    public canWrite(target: any, contentType: string): boolean;
    
    public doWrite(target: any): string;
    public doRead(target: string): any;
}
```

### This documentation is a work in progress. More will be added later.

## License
[MIT License](https://github.com/paulcosma97/overseer/blob/master/LICENSE)

---
_Source: https://npm.io/package/@jeaks03/overseer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._