@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 | Description | | -------- | ---- | ------- | ----------- | | type | String | required | | | entity | Object | required | | | ctx | Context | required | |

Results

Type: Promise

entityChanged

Clear the cache & call entity lifecycle events

Parameters

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | 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 | Description | | -------- | ---- | ------- | ----------- | | type | String | required | | | entity | Object | required | | | ctx | Context | required | |

Results

Type: Promise

entityChanged

Clear the cache & call entity lifecycle events

Parameters

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | 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 | Description | | -------- | ---- | ------- | ----------- | | 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.

Contact

Copyright (c) 2023 Tyr Soluitons