@fairfx/spend-common v1.5.2

@fairfx/spend-common

Shared library that will be used by the other services.

This library contains:

• Configuration (config)
• Access Control Logic (lib/permissions and lib/features)
• Domain Models containing Business and Persistence logic. (lib/core)

By using a Domain Model approach we can keep inner dependencies coupled together with a simplified public API for external consumers. This method also simplifies inter Domain Models dependencies without requiring deep tree transversal (ex: ../../../core/models/user) making these dependencies easier to read and maintain.

Application Public Interface (API)

This service exposes its API via lib/index.ts file.

lib/index.ts exposes a default service that:

• Initialises database connection using the provided ENV vars credentials
• Returns a models and a db wrapper.

Models wrapper contains the public interface for users, companies and any other Domain Models.

Company is an example of a Domain Model that contains all properties:

$ tree packages/common/lib/core/company
├── adapter.ts
├── builder.ts
├── entity.ts
├── fetcher.ts
├── index.ts
└── model.ts

Inside the company folder you can find:

• adapter.ts where the mapping from Entity to Presentational Model, and Presentational Model to Entity are defined.
• builder.ts where mutation and construction of new objects are defined.
• entity.ts a simple TypeORM DB schema definition.
• fetcher.ts custom data fetchers like getById, or getAll are defined.
• model.ts where the Public Interface of this Domain Model lives. This Public Interface is one that's exposed to external consumers.
• index.ts is the entry point to this Domain Model. Exposes builders and fetchers.

A Domain Model might have all of these files but that's not mandatory.

Database access and management

Evolving database schema

The database schema is not set in stone and is going to evolve during application life.

We embrace idea of DB schema as code: any changes to DB structure are captured under source control. The schema is defined via TypeORM entities (plus migrations - see below).

The changes to the database schema are captured as migration scripts inside migrations/ directory. See TypeORM migrations API.

Selective applications of DB migrations

In addition to TypeORM's API we introduced additional feature: ability to determine which transactions have to be applied upon creation of new database.

The reason for the mechanism is: TypeORM has its limits and it is not possible to define the DB schema exclusively with its means. For instance complex triggers ot stored procedures.

Upon creation of new DB (for non-production environments) by default all migrations are marked as executed - TypeORM's latest entities define the latest schema.

If particular migration has to be executed regardless it has to have special method

• useUponDatabaseCreation that returns true. See example here.