npm package: @nodebrick/nodebrick-core
Description: Core of Nodebrick
Author: Xavier Martin
Latest version: 1.4.19

# nodebrick-core  
_Core of the Nodebrick framework_  

## Description
This is the core of the framework and works as a glue between all the modules and is required 
by all application you will create

Table of Contents:

* [Module Structure](#module-sutructure)
* [Dependency Injection](#dependency-injection)
* [Cls hooked and contexts](#contexts)
    * [Existing contexts](#existing-contexts)
        * [For Sorting](#existing-contexts-sorting)
        * [For Field Selection](#existing-contexts-field-selection)
        * [For Filtering](#existing-contexts-filtering)
        * [For Pagination](#existing-contexts-pagination)
        * [For Counting](#existing-contexts-count)
- Inversify DI
- Configuration (node-config)
- class validation formater
- default logger
- Options (filtering, sorting, couting, field p)


### Module Structure
_non exhaustive list_

Few things to note:  
* `index.ts`  
  The entrypoint, exporting all the classes/interfaces accessible by other modules (think public api)
* `I<ModuleNameModule>.ts`  
  The module 'interface' - note we are using the following notation `export abstract class I<ModuleName>` to define interface so they exists in the JS realm and are accessible by InversifyJS
* `<ModuleNameModule>.ts`
  The module class implementing and extending the 'interface'
* `<ModuleNameBindings>.ts`  
  Defines the Inversify bindings for this module
* `models`
  Folder storing all our models, i.e our business logic data  
  Models can also define and validates DTO (data transfer object) fields using [class-transformer](https://github.com/typestack/class-transformer) and [class-validator](https://github.com/typestack/class-validator) libraries eg
  ```typescript
  @Exclude()
  export abstract class IAPIResponse<TData>
  {
  
      @Expose({name: `request_id`, toClassOnly: true})
      @IsOptional()
      public abstract requestId?: string;
  
      @Expose({name: `client_request_id`, toPlainOnly: true})
      @IsString()
      @IsOptional()
      public abstract clientRequestId?: string;
  
      @Expose({name: `start_time`, toPlainOnly: true})
      @IsDate()
      public abstract startTime?: Date;
  
      @Expose({name: `end_time`, toPlainOnly: true})
      @IsDate()
      public abstract endTime: Date;
  
      @Expose({toPlainOnly: true})
      @IsInt()
      @IsOptional()
      // In milliseconds
      public abstract duration?: number;
  }
  ```  
  For instance a REST API returning the above will automatically create a JSON like    
  ```json
  {
    "client_request_id": "933ca46c-25a5-4166-903e-a437700ae4ef",
    "startTime": "933ca46c-25a5-4166-903e-a437700ae4ef",
    "end_time": "933ca46c-25a5-4166-903e-a437700ae4ef",
    "duration": 50
  }
  ```
  I invite you to read the [class-transformer](https://github.com/typestack/class-transformer) and [class-validator](https://github.com/typestack/class-validator) documentations.  
  Note that table column can also be created and validated with [nodebrick-database](../nodebrick-database/README.md) and the help [TypeORM](https://typeorm.io/#/)  

### Dependency Injection
NodebrickCore provides dependency injection by using internally [InversifyJS](http://inversify.io/)

All the bindings will be defined in the `<ModuleNameBindings>.ts` as for instance  
```typescript
    //  bind the module to its interface using transitive binding, i.e we are reusing the singleton.
    bind(INodebrickApiModule).toService(NodebrickApiModule);

    //  middlewares - transient
    bind(IGlobalApiMiddleware).to(GlobalApiMiddleware).inTransientScope();
    bind(IGlobalOptionsMiddleware).to(GlobalOptionsMiddleware).inTransientScope();
    bind(IGlobalRequestMiddleware).to(GlobalRequestMiddleware).inTransientScope();

    //  services - singletons
    bind(INodebrickApiService).to(NodebrickApiService).inSingletonScope();

``` 
As you can see bindings can have multiples scopes, Transient, Singleton and Request.  
Please see [InversifyJS documentation](https://github.com/inversify/InversifyJS/tree/master/wiki). 

### Contexts

_A context can be defined as all the relevant information that a developer needs to complete a task._  
Nodebrick Core uses [cls-hooked](https://github.com/jeff-lewis/cls-hooked#readme) internally.  
We invite you to read the documentation.  

Here is an excerpt of the documentation explaining the core of this library and how it is helping
> Continuation-local storage works like thread-local storage in threaded programming, but is based on chains of Node-style callbacks instead of threads. The standard Node convention of functions calling functions is very similar to something called "continuation-passing style" in functional programming, and the name comes from the way this module allows you to set and get values that are scoped to the lifetime of these chains of function calls
> 
> When you set values in continuation-local storage, those values are accessible until all functions called from the original function – synchronously or asynchronously – have finished executing. This includes callbacks passed to process.nextTick and the timer functions (setImmediate, setTimeout, and setInterval), as well as callbacks passed to asynchronous functions that call native functions (such as those exported from the fs, dns, zlib and crypto modules).  
>
> A simple rule of thumb is anywhere where you want to have threaded scoped variables should now use continuation-local storage. This API is designed to allow you extend the scope of a variable across a sequence of function calls, but with values specific to each sequence of calls.
> Values are grouped into namespaces, created with createNamespace(). Sets of function calls are grouped together by calling them within the function passed to .run() on the namespace object. Calls to .run() can be nested, and each nested context this creates has its own copy of the set of values from the parent context. When a function is making multiple asynchronous calls, this allows each child call to get, set, and pass along its own context without overwriting the parent's.


This is a diagram explaining the above  

![context diagram](./documentation/assets/contexts_explained.svg)

And this is the cls-hooked documention explaining it with code
>
> A simple, annotated example of how this nesting behaves:
> 
> ```javascript
>    var createNamespace = require('cls-hooked').createNamespace;
>     
>     var writer = createNamespace('writer');
>     writer.run(function () {
>       writer.set('value', 0);
>      
>       requestHandler();
>     });
>      
>     function requestHandler() {
>       writer.run(function(outer) {
>         // writer.get('value') returns 0
>         // outer.value is 0
>         writer.set('value', 1);
>         // writer.get('value') returns 1
>         // outer.value is 1
>         process.nextTick(function() {
>           // writer.get('value') returns 1
>           // outer.value is 1
>           writer.run(function(inner) {
>             // writer.get('value') returns 1
>             // outer.value is 1
>             // inner.value is 1
>             writer.set('value', 2);
>             // writer.get('value') returns 2
>             // outer.value is 1
>             // inner.value is 2
>           });
>         });
>       });
>      
>       setTimeout(function() {
>         // runs with the default context, because nested contexts have ended
>         console.log(writer.get('value')); // prints 0
>       }, 1000);
>     }
> 
> ``` 
This also helps segregating the stream of processes (think for instance multiple call to an API, we will create a context when we get a request isolating any models in the context)
  
  
#### Usage  
Nodebrick Core provides you with tools to:  
 * create a context
 * attach typed value to the context    
 * retrieve specific values from the context
 
##### Creating and using context
Please see the following example  

```typescript
abstract class ISomeClass {}

class IATypedValue {
    public someProperty: string;
}

abstract class IATypedValueContext extends IContext<IATypedValue> {}

class SomeClass extends ISomeClass implements ISomeClass
{
    private readonly _applicationContext: IApplicationContextService;
    private readonly _logger: INodebrickLoggerService;

    //  dependency injection
    public constructor(
        applicationContext: IApplicationContextService
    )
    {
        super();
        this._applicationContext = applicationContext;
    }

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    public async someMethod(): Promise<void>
    {
        //  this creates a new context copying the values from the parent (if any)
        this._applicationContext.session.run(() =>
        {
            //  set a value in the context
            this._applicationContext.set(IATypedValueContext, {someProperty: "it works"});
        });
    }
}

abstract class ISomeOtherClass {}

class SomeOtherClass extends ISomeOtherClass implements ISomeOtherClass
{
    private readonly _applicationContext: IApplicationContextService;

    //  dependency injection
    public constructor(
        applicationContext: IApplicationContextService,
        logger: INodebrickLoggerService,
    )
    {
        super();
        this._applicationContext = applicationContext;
        this._logger = logger;
    }

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    public async someMethod(): Promise<void>
    {
        //  this creates a new context copying the values from the parent (if any)
        const aTypedValue: IATypedValue = this._applicationContext.get(IATypedValueContext);
        //  log "it works"
        console.log(aTypedValue.someProperty)
    }
}
```

#### Existing Contexts 
​
nodebrick-core defines multiple contexts that can be used by other modules.


*   <a name="existing-contexts-sorting"></a>**Sorting** with `IOptionSortContext` using `IOptionSort`  
    _creates an object representing how fields should be sorted  
    used internally by:_  
    * _nodebrick-api - sets it from query parameter_
    * _nodebrick-database - can read it to apply to query parameter_  
    
    object example:
    ```
    {
        fields: [ 
            city: SortEnum.ASC,
            age: SortEnum.DESC
        ];
    }
    ```

*   <a name="existing-contexts-field-selection"></a>**Field selection** with `IOptionFieldsContext` using `IOptionFields` class  
    _creates an object representing what fields will be retreived on the resource  
    used internally by:_  
    * _nodebrick-api - sets it from query parameter_
    * _nodebrick-database - can read it to apply to query parameter_   
    
    object example
    ```
    {
        author: true,
        library: {
            name: {
                common: true
            },
            address: {
                city: true,
                country: {
                    code: true
                }
            }
        },
        price: true
    }
    ```

*   <a name="existing-contexts-filtering"></a>**Filtering** with `IOptionFiltersContext` using `IOptionFilters` class  
    _creates an object representing how to filter requested resource  
    used internally by:_  
    * _nodebrick-api - sets it from query parameter_
    * _nodebrick-database - can read it to apply to query parameter_  
    
    <a name="filter-operator-list"></a>
    The list of available operator is:
    * $in: `FilterOperatorsEnum.IN` 
    * $nin: `FilterOperatorsEnum.NOT_IN` 
    * $between: `FilterOperatorsEnum.BETWEEN` 
    * $nbetween: `FilterOperatorsEnum.NOT_BETWEEN` 
    * $eq: `FilterOperatorsEnum.EQUALS` 
    * $neq: `FilterOperatorsEnum.NOT_EQUALS` 
    * $gt: `FilterOperatorsEnum.GREATER_THAN` 
    * $gte: `FilterOperatorsEnum.GREATER_THAN_OR_EQUALS` 
    * $lt: `FilterOperatorsEnum.LESSER_THAN` 
    * $lte: `FilterOperatorsEnum.LESSER_THAN_OR_EQUALS` 
    * $like: `FilterOperatorsEnum.LIKE` 
    * $nlike: `FilterOperatorsEnum.NOT_LIKE` 
    * $ilike: `FilterOperatorsEnum.ILIKE` 
    * $nilike: `FilterOperatorsEnum.NOT_ILIKE` 
     
    object example
    ```
    {
        author: 
        {
            property: "author",
            value: [
                "stephen king"
            ],
            operator: "$like",
            operatorSQL: [
                "LIKE"
            ]
        }  
    }
    
*   <a name="existing-contexts-pagination"></a>**Pagination** with `IPaginationContext` using `IPagination`
    _creates an object defining the clients requires pagination and its specifics (type, start/end, ...)  
    used internally by:_  
    * _nodebrick-api - sets it from query parameter_
    * _nodebrick-database - can read it to apply to query parameter_
    
    We have implemented two types of paginations, **seek** and **offset**.  
    
    **Offset pagination**  
    _requires the record you want to start from and a limit (number of records to return).    
    This is **VERY** inefficient. It requires the database to also work with on all the previous records.    
    This is somehow the default almost everywhere._
    
    Add the following:
    * **start**: integer  
      returns start at the record counts
    * **limit**: integer  
      return this number of records  
    
    object example:
    ```
    {
        type: "offset",
        limit: 5,
        start: 5,
        prev_url: "/resource?limit=5&start=0",
        self_url: "/resource?limit=5&start=5",
        next_url: "/resource?limit=5&start=10"  
    }
    ​
    ```
    ​  
    **Seek pagination**  
    _(extension of keyset pagination, have a look) pagination where you give the ID to get result after or before.
    This also use the limit (number of item to return).  
    This is efficient as the database will jump exactly to this record and the next <Limit> number and work on those._

    Add the following:
    * **limit**: integer.  
      Return this number of records
    * **before**: UUID  
      Return the records before this UUID
    **OR**
    * **after**: UUID  
      Return the records after this UUID
    
    object example:  
    ```
    {
        type: "seek",
        limit: 5,
        after: null,
        before: "c8dae5da-0b64-4b55-ab56-95f59b9eb8b2",
        self: "/nodebrick-api/options?limit=5&before=c8dae5da-0b64-4b55-ab56-95f59b9eb8b2&options=%7Bfields%3A%7Bauthor,library(name%2Fcommon,address(city,country%2Fcode)),price%7D,filters%3A%7Bauthor%3A%24like_stephen%20king,book%3A%24nilike_it,date%3A%24between_1995-01-01_2018-12-12%7D%7D",
        prev: "/nodebrick-api/options?limit=5&before=undefined&options=%7Bfields%3A%7Bauthor,library(name%2Fcommon,address(city,country%2Fcode)),price%7D,filters%3A%7Bauthor%3A%24like_stephen%20king,book%3A%24nilike_it,date%3A%24between_1995-01-01_2018-12-12%7D%7D"  
    }
    ​
    ```
          
*   <a name="existing-contexts-count"></a>**Counting** with `ICountContext` using `ICount`
    _creates an object defining if the client required counting of resources  
    used internally by:_  
    * _nodebrick-api - sets it from query parameter_
    * _nodebrick-database - can read it to apply to query parameter_

    object example:  
    ```
    {
        "do_count": <boolean>,
        "count": <integer>
    }
    ```