@tyrsolutions/moleculer-db-typeorm-adapter

A TypeORM adapter for moleculer

Features

All supported TypeORM databases
Active Record methodology for entities or data mapping methodology if entity class doesn't extend TypeORM BaseEntity built in
Connection Manager - manage your existing connections or create new ones to different database systems on the same service. New connections are a new instance of TypeORMDbAdapter if true is added after datasource options. If true is not specified, then the connection will be created with raw TypeORM datasource and not inherit class methods, only TypeORM methods will be available (about the same as using typeorm by itself).
All entities added to TypeORMDbAdapter and model array are added to this.adapter
- Base entity this.adapter
- any additional entity this.adapter.<entity name> when model has more than one entity. Note: additional entities added to model: are tables in the same database.
Repository and entityManager surfaced for this.adapter and additional entities on same adapter instance this.adapter.<entity name> if more advanced TypeORM features are required
Database connections for service start and stop when service does, so closing db connection not necessary.
Setting idField in service schema is used to specify own preference and obfusicate the true db id field in the entire response, includng returned relations. This gets converted to the actual db field name automatically when querying the database, then converted back to idField on response. If you wish to use the actual db id field of the database, change idField to the database id field name.
The service setting fields:[] filters the response, just like in moleculer-db, so if you do change the idField in settings, be sure to change the id field in service settings fields as well.
Enhanced list method that converts moleculer-db list paramaters to typeorm paramaters or use typeorm FindManyOptions paramaters instead FindManyOptions. List can return relations, though this could be process intensive depending on the amount of relations and entities returned.

Install

NPM

npm install moleculer-db @tyrsolutions/moleculer-db-typeorm-adapter --save

Yarn

yarn add moleculer-db @tyrsolutions/moleculer-db-typeorm-adapter

Usage

In service schema:

service: {
    ...
    adapter: new TypeORMDbAdapter({
        name: 'default',
        type: 'better-sqlite3',
        database: 'temp/test.db',
        synchronize: true,
        logging: ['query', 'error'],
        // entities: [TypeProduct], no longer needed entities are pulled from model and added. Providing one here will override model:
    }),

    model: TypeProduct || [TypeProduct, TypeProduct2], // accepts single entity or array of entities.
    ...
}

Create a new db connection in service (preferably in service started lifecycle handler):

async started() {
    this.logger.debug('♻ User service created');
    /**
     * Creates the new connection using conneciton manager of the existing adapter in service,
     * adding true after the data source options tells connctionmanager to create a new instance
     * of TypeORMDbAdapter to the specified database. This in turn allows the new connection to have multiple entities (db tables)
     * applied that are added to the new connection. In this case below this.products would query the ProductEntity
     * table of database and this.products.<additional entity> would query that table in teh same db.
     */
    const productsConnection = await this.adapter.connectionManager?.create(
        {
            name: 'products',
            type: 'better-sqlite3',
            database: `temp/dbname_product.db`,
            synchronize: true,
            logging: [/* 'query', */ 'error'],
            entities: [ProductEntity],
        },
        true,
    )!;
    await productsConnection.init(this.broker, this); // needed to initialize the conection with broker and service
    await productsConnection.connect(); // connects to the database
    this.products = productsConnection; // assigns new connection to service and can be called with this.products
}

Active Record

Entity:

import { BaseEntity, Entity, PrimaryGeneratedColumn, Column } from "typeorm"

@Entity()
export class User extends BaseEntity { // class extending BaseEntity
    @PrimaryGeneratedColumn()
    id: number

    @Column()
    firstName: string

    @Column()
    lastName: string

    @Column()
    isActive: boolean

    static findByName(firstName: string, lastName: string) {
        return this.createQueryBuilder("user")
            .where("user.firstName = :firstName", { firstName })
            .andWhere("user.lastName = :lastName", { lastName })
            .getMany()
    }
}

In service actions, methods, etc. (anywhere this.adapter can be used):

const user = {
    "firstName": "John",
    "lastName": "Doe",
    "active": true
}
// no need to create new object with entity, just pass one
this.adapter.create(user)

// use static method functions from entity, no additional setup needed
this.adapter.findByName("John", "Doe")

Data Mapping

Entity:

import { BaseEntity, Entity, PrimaryGeneratedColumn, Column } from "typeorm"

@Entity()
export class User { // class not extending BaseEntity
    @PrimaryGeneratedColumn()
    id: number

    @Column()
    firstName: string

    @Column()
    lastName: string

    @Column()
    isActive: boolean
}

In service actions, methods, etc. (anywhere this.adapter can be used):

const user = new User()
user.firstName = "John";
user.lastName = "Doe";
user.active = true;

// create new object with entity then save
this.adapter.User.repository.save(user);

// or

const user = {
    "firstName": "John",
    "lastName": "Doe",
    "active": true
}

// no need to create new object with entity, just pass one
this.adapter.User.repository.save(user);

Test

NPM

$ npm test

Yarn

yarn test

In development with watching

$ npm run ci

Properties

`connectionManager`

Grants access to the connection manager instance which is used to create and manage connections. Called using this.adapter.connectionManager

Parameters

Property	Type	Default	Description
No input parameters.

`manager`

Grants access to the entity manager of the connection. Called using this.adapter.manager

Parameters

Property	Type	Default	Description
No input parameters.

`repository`

Grants access to the entity repository of the connection. Called using this.adapter.repository

Parameters

Property	Type	Default	Description
No input parameters.

Methods

`init`

Initialize adapter. It will be called in broker.start() and is used internally.

Parameters

Property	Type	Default	Description
`broker`	`ServiceBroker`	required
`service`	`Service`	required

`connect`

Connects to database. It will be called in broker.start() and is used internally.

Parameters

Property	Type	Default	Description
No input parameters.

Results

Type: Promise

`disconnect`

Disconnects all connections from database and connection manager. It will be called in broker.stop() and is used internally.

Parameters

Property	Type	Default	Description
No input parameters.

Results

Type: Promise

`create`

Create new record or records.

Parameters

Property	Type	Default	Description
`entityOrEntities`	`Object`, `Array.<Object>`	required	record(s) to create
`options`	`Object`	-	Optional MongoDB insert options

Results

Type: Promise.<(Object|Array.<Object>)>

`insert`

Create many new entities.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`Object`	-	Parameters.

Results

Type: Object, Array.<Object>

Saved entity(ies).

`updateById`

Update an entity by ID

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	request context
`id`	`any`	required	ID of record to be updated
`update`	`Object`	required	Object with update data

Results

Type: Promise

Updated record

`count`

Count number of matching documents in the db to a query.

Parameters

Property	Type	Default	Description
`options`	`Object`	required	count options
`query`	`Object`	-	query options

Results

Type: Promise.<number>

`find`

Finds entities that match given find options.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	request context
`findManyOptions`	`Object`	required	find many options

Results

Type: Promise.<(Array.<T>|Array.<number>)>

`findOne`

Finds first item by a given find options. If entity was not found in the database - returns null. Available Options props:

comment
select
where
relations
relationLoadStrategy
join
order
cache
lock
withDeleted
loadRelationIds
loadEagerRelations
transaction

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	request context
`findOptions`	`Object`	required	find options

Results

Type: Promise.<(T|undefined)>

`findByIdWO`

Gets item by id(s). Can use find options, no where clause.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	request context
`key`	`Partial.<T>`	required	primary db id column name
`id`	`string`, `number`, `Array.<string>`, `Array.<number>`	required	id(s) of entity
`findOptions`	`Object`	required	find options, like relations, order, etc. No where clause

Results

Type: Promise.<(T|undefined)>

`findById`

Gets item by id(s). No find options can be provided

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	request context
`key`	`Partial.<T>`	required	primary db id column name
`id`	`string`, `number`, `Array.<string>`, `Array.<number>`	required	id(s) of entity

Results

Type: Promise.<(T|undefined)>

`getPopulations`

Populates entity(ies) by id(s) of another record.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`Object`	-	Parameters.

Results

Type: Object, Array.<Object>

Found entity(ies).

`list`

List entities from db using filters and pagination results.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`ListParams.<Object>`	-	Optional parameters.

Results

Type: Object

List of found entities and count.

`beforeSaveTransformID`

Transforms user defined idField into expected db id field name.

Parameters

Property	Type	Default	Description
`entity`	`Object`	required	Record to be saved
`idField`	`String`	required	user defined service idField

Results

Type: Object

Modified entity

`afterRetrieveTransformID`

Transforms db field name into user defined idField service property

Parameters

Property	Type	Default	Description
`entity`	`Object`	required	= Record retrieved from db
`idField`	`String`	required	user defined service idField

Results

Type: Object

Modified entity

`encodeID`

Encode ID of entity.

Parameters

Property	Type	Default	Description
`id`	`any`	required

Results

Type: any

`toMongoObjectId`

Convert id to mongodb ObjectId.

Parameters

Property	Type	Default	Description
`id`	`any`	required

Results

Type: any

`fromMongoObjectId`

Convert mongodb ObjectId to string.

Parameters

Property	Type	Default	Description
`id`	`any`	required

Results

Type: any

`beforeQueryTransformID`

Transform user defined idField service property into the expected id field of db.

Parameters

Property	Type	Default	Description
`idField`	`any`	required	user defined service idField

Results

Type: Object

Record to be saved

`decodeID`

Decode ID of entity.

Parameters

Property	Type	Default	Description
`id`	`any`	required

Results

Type: any

`transformDocuments`

Transform the fetched documents by converting id to user defind idField, filtering the fields according to the fields service property, and populating the document with the relations specified in the populate service property.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context of the request
`params`	`Object`	required	Params of the request
`docs`	`Array`, `Object`	required	Records to be transformed

Results

Type: Array, Object

Transformed records

`beforeEntityChange`

Call before entity lifecycle events

Parameters

Property	Type	Default
`type`	`String`	required
`entity`	`Object`	required
`ctx`	`Context`	required

Results

Type: Promise

`entityChanged`

Clear the cache & call entity lifecycle events

Parameters

Property	Type	Default
`type`	`String`	required
`json`	`Object`, `Array.<Object>`, `Number`	required
`ctx`	`Context`	required

Results

Type: Promise

`clearCache`

Clear cached entities

Parameters

Property	Type	Default	Description
No input parameters.

Results

Type: Promise

`filterFields`

Filter fields in the entity object

Parameters

Property	Type	Default	Description
`doc`	`Object`	required	Record to be filtered.
`fields`	`Array.<String>`	required	Filter properties of model.

Results

Type: Object

Filtered record

`excludeFields`

Exclude fields in the entity object

Parameters

Property	Type	Default	Description
`doc`	`Object`	required	Record to be filtered.
`fields`	`Array.<String>`	required	Exclude properties of model.

Results

Type: Object

Recored without excluded fields

`populateDocs`

Populate documents for relations. Used when relations between records between different databases can't be done. Populates the retreived record by calling service action with the id of the relation. Does not update related document at this time

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Request context
`docs`	`Array`, `Object`	required	Records to be populated
`populateFields`	`Array`	-	Fields to be populated

Results

Type: Promise

Record with populated fields of relation

`validateEntity`

Validate an entity by validator. Uses the entityValidator setting. If no validator function is supplied, returns record.

Parameters

Property	Type	Default	Description
`entity`	`Object`	required	Record to be validated

Results

Type: Promise

Validated record or unvalitaded record if no validator function is supplied.

`entityToObject`

Convert DB entity to JSON object

Parameters

Property	Type	Default	Description
`entity`	`any`	required	Record to be converted

Results

Type: Object

JSON object of record

`authorizeFields`

Authorize the required field list. Remove fields which does not exist in the this.service.settings.fields

Parameters

Property	Type	Default	Description
`askedFields`	`Array`	required	List of fields to be authorized

Results

Type: Array

Authorized list of fields

`sanitizeParams`

Sanitize context parameters at find action.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Request context
`params`	`Object`	required	Request parameters

Results

Type: Object

Sanitized parameters

`sanitizeParams`

Sanitize context parameters at find action.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Request context
`params`	`Object`	required	Request parameters

Results

Type: Object

Sanitized parameters

`getById`

Get entity(ies) by ID(s).

Parameters

Property	Type	Default	Description
`id`	`any`, `Array.<any>`	required	ID or IDs.
`decoding`	`Boolean`	-	Need to decode IDs.

Results

Type: Object, Array.<Object>

Found entity(ies).

`beforeEntityChange`

Call before entity lifecycle events

Parameters

Property	Type	Default
`type`	`String`	required
`entity`	`Object`	required
`ctx`	`Context`	required

Results

Type: Promise

`entityChanged`

Clear the cache & call entity lifecycle events

Parameters

Property	Type	Default
`type`	`String`	required
`json`	`Object`, `Array.<Object>`, `Number`	required
`ctx`	`Context`	required

Results

Type: Promise

`clearCache`

Clear cached entities

Parameters

Property	Type	Default	Description
No input parameters.

Results

Type: Promise

`transformDocuments`

Transform the fetched documents

Parameters

Property	Type	Default
`ctx`	`Context`	required
`params`	`Object`	required
`docs`	`Array`, `Object`	required

Results

Type: Array, Object

`validateEntity`

Validate an entity by validator.

Parameters

Property	Type	Default	Description
`entity`	`Object`	required

Results

Type: Promise

`encodeID`

Encode ID of entity.

Parameters

Property	Type	Default	Description
`id`	`any`	required

Results

Type: any

`decodeID`

Decode ID of entity.

Parameters

Property	Type	Default	Description
`id`	`any`	required

Results

Type: any

`_find`

Find entities by query.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`Object`	-	Parameters.

Results

Type: Array.<Object>

List of found entities.

`_count`

Get count of entities by query.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`Object`	-	Parameters.

Results

Type: Number

Count of found entities.

`_list`

List entities by filters and pagination results.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`Object`	-	Parameters.

Results

Type: Object

List of found entities and count.

`_create`

Create a new entity.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`Object`	-	Parameters.

Results

Type: Object

Saved entity.

`_insert`

Create many new entities.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`Object`	-	Parameters.

Results

Type: Object, Array.<Object>

Saved entity(ies).

`_get`

Get entity by ID.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`Object`	-	Parameters.

Results

Type: Object, Array.<Object>

Found entity(ies).

`_update`

Update an entity by ID.

After update, clear the cache & call lifecycle events.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`Object`	-	Parameters.

Results

Type: Object

Updated entity.

`_remove`

Remove an entity by ID.

Parameters

Property	Type	Default	Description
`ctx`	`Context`	required	Context instance.
`params`	`Object`	-	Parameters.

Connection Manager

`connections`

List of connections registered in this connection manager.

Parameters

Property	Type	Default	Description
No input parameters.

Results

Type: Array.<DataSource>

List of connections

`has`

Checks if connection with the given name exist in the manager.

Parameters

Property	Type	Default	Description
`name`	`string`	required	Connection name

Results

Type: boolean

True if connection exist, false otherwise

`get`

Gets registered connection with the given name. If connection name is not given then it will get a default connection. Throws error if connection with the given name was not found.

Parameters

Property	Type	Default	Description
`name`	`string`	`"default"`	Connection name

Results

Type: DataSource

Connection

`remove`

Removes registered connection with the given name. If connection name is not given then it will get a default connection. Throws error if connection with the given name was not found.

Parameters

Property	Type	Default	Description
`name`	`string`	`"default"`	Connection name

`close`

closes registered connection with the given name and removes it from ConnectionManager. If connection name is not given then it will get a default connection. Throws error if connection with the given name was not found.

Parameters

Property	Type	Default	Description
`name`	`string`, `Array.<string>`	`"default"`	Connection name

`create`

Creates a new connection based on the given connection options and registers it in the manager. Connection won't be established, you'll need to manually call connect method to establish connection.

Parameters

Property	Type	Default	Description
`options`	`Object`	required	TypeORM data source connection options
`newConnection`	`boolean`	`false`	Toggle to create a new instance of TypeORMDbAdapter.

Results

Type: Promise.<connection>

Connection

Contribution

Please send pull requests improving the usage and fixing bugs, improving documentation and providing better examples, or providing some testing, because these things are important.

License

The project is available under the MIT license.