A TypeORM adapter for moleculer
- 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
iftrue
is added after datasource options. Iftrue
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 tomodel:
are tables in the same database.
- Base entity
- Repository and entityManager surfaced for
this.adapter
and additional entities on same adapter instancethis.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 settingsfields
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.
npm install moleculer-db @tyrsolutions/moleculer-db-typeorm-adapter --save
yarn add moleculer-db @tyrsolutions/moleculer-db-typeorm-adapter
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
}
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")
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);
$ npm test
yarn test
In development with watching
$ npm run ci
Grants access to the connection manager instance which is used to create and manage connections. Called using this.adapter.connectionManager
Property | Type | Default | Description |
---|---|---|---|
No input parameters. |
Grants access to the entity manager of the connection. Called using this.adapter.manager
Property | Type | Default | Description |
---|---|---|---|
No input parameters. |
Grants access to the entity repository of the connection. Called using this.adapter.repository
Property | Type | Default | Description |
---|---|---|---|
No input parameters. |
Initialize adapter.
It will be called in broker.start()
and is used internally.
Property | Type | Default | Description |
---|---|---|---|
broker |
ServiceBroker |
required | |
service |
Service |
required |
Connects to database.
It will be called in broker.start()
and is used internally.
Property | Type | Default | Description |
---|---|---|---|
No input parameters. |
Type: Promise
Disconnects all connections from database and connection manager.
It will be called in broker.stop()
and is used internally.
Property | Type | Default | Description |
---|---|---|---|
No input parameters. |
Type: Promise
Create new record or records.
Property | Type | Default | Description |
---|---|---|---|
entityOrEntities |
Object , Array.<Object> |
required | record(s) to create |
options |
Object |
- | Optional MongoDB insert options |
Type: Promise.<(Object|Array.<Object>)>
Create many new entities.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
Object |
- | Parameters. |
Type: Object
, Array.<Object>
Saved entity(ies).
Update an entity by ID
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 |
Type: Promise
- Updated record
Count number of matching documents in the db to a query.
Property | Type | Default | Description |
---|---|---|---|
options |
Object |
required | count options |
query |
Object |
- | query options |
Type: Promise.<number>
Finds entities that match given find options.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | request context |
findManyOptions |
Object |
required | find many options |
Type: Promise.<(Array.<T>|Array.<number>)>
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
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | request context |
findOptions |
Object |
required | find options |
Type: Promise.<(T|undefined)>
Gets item by id(s). Can use find options, no where clause.
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 |
Type: Promise.<(T|undefined)>
Gets item by id(s). No find options can be provided
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 |
Type: Promise.<(T|undefined)>
Populates entity(ies) by id(s) of another record.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
Object |
- | Parameters. |
Type: Object
, Array.<Object>
Found entity(ies).
List entities from db using filters and pagination results.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
ListParams.<Object> |
- | Optional parameters. |
Type: Object
List of found entities and count.
Transforms user defined idField into expected db id field name.
Property | Type | Default | Description |
---|---|---|---|
entity |
Object |
required | Record to be saved |
idField |
String |
required | user defined service idField |
Type: Object
- Modified entity
Transforms db field name into user defined idField service property
Property | Type | Default | Description |
---|---|---|---|
entity |
Object |
required | = Record retrieved from db |
idField |
String |
required | user defined service idField |
Type: Object
- Modified entity
Encode ID of entity.
Property | Type | Default | Description |
---|---|---|---|
id |
any |
required |
Type: any
Convert id to mongodb ObjectId.
Property | Type | Default | Description |
---|---|---|---|
id |
any |
required |
Type: any
Convert mongodb ObjectId to string.
Property | Type | Default | Description |
---|---|---|---|
id |
any |
required |
Type: any
Transform user defined idField service property into the expected id field of db.
Property | Type | Default | Description |
---|---|---|---|
idField |
any |
required | user defined service idField |
Type: Object
- Record to be saved
Decode ID of entity.
Property | Type | Default | Description |
---|---|---|---|
id |
any |
required |
Type: any
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.
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 |
Type: Array
, Object
- Transformed records
Call before entity lifecycle events
Property | Type | Default | Description |
---|---|---|---|
type |
String |
required | |
entity |
Object |
required | |
ctx |
Context |
required |
Type: Promise
Clear the cache & call entity lifecycle events
Property | Type | Default | Description |
---|---|---|---|
type |
String |
required | |
json |
Object , Array.<Object> , Number |
required | |
ctx |
Context |
required |
Type: Promise
Clear cached entities
Property | Type | Default | Description |
---|---|---|---|
No input parameters. |
Type: Promise
Filter fields in the entity object
Property | Type | Default | Description |
---|---|---|---|
doc |
Object |
required | Record to be filtered. |
fields |
Array.<String> |
required | Filter properties of model. |
Type: Object
- Filtered record
Exclude fields in the entity object
Property | Type | Default | Description |
---|---|---|---|
doc |
Object |
required | Record to be filtered. |
fields |
Array.<String> |
required | Exclude properties of model. |
Type: Object
- Recored without excluded fields
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
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Request context |
docs |
Array , Object |
required | Records to be populated |
populateFields |
Array |
- | Fields to be populated |
Type: Promise
- Record with populated fields of relation
Validate an entity by validator.
Uses the entityValidator
setting. If no validator function is supplied, returns record.
Property | Type | Default | Description |
---|---|---|---|
entity |
Object |
required | Record to be validated |
Type: Promise
- Validated record or unvalitaded record if no validator function is supplied.
Convert DB entity to JSON object
Property | Type | Default | Description |
---|---|---|---|
entity |
any |
required | Record to be converted |
Type: Object
- JSON object of record
Authorize the required field list. Remove fields which does not exist in the this.service.settings.fields
Property | Type | Default | Description |
---|---|---|---|
askedFields |
Array |
required | List of fields to be authorized |
Type: Array
- Authorized list of fields
Sanitize context parameters at find
action.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Request context |
params |
Object |
required | Request parameters |
Type: Object
- Sanitized parameters
Sanitize context parameters at find
action.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Request context |
params |
Object |
required | Request parameters |
Type: Object
- Sanitized parameters
Get entity(ies) by ID(s).
Property | Type | Default | Description |
---|---|---|---|
id |
any , Array.<any> |
required | ID or IDs. |
decoding |
Boolean |
- | Need to decode IDs. |
Type: Object
, Array.<Object>
Found entity(ies).
Call before entity lifecycle events
Property | Type | Default | Description |
---|---|---|---|
type |
String |
required | |
entity |
Object |
required | |
ctx |
Context |
required |
Type: Promise
Clear the cache & call entity lifecycle events
Property | Type | Default | Description |
---|---|---|---|
type |
String |
required | |
json |
Object , Array.<Object> , Number |
required | |
ctx |
Context |
required |
Type: Promise
Clear cached entities
Property | Type | Default | Description |
---|---|---|---|
No input parameters. |
Type: Promise
Transform the fetched documents
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | |
params |
Object |
required | |
docs |
Array , Object |
required |
Type: Array
, Object
Validate an entity by validator.
Property | Type | Default | Description |
---|---|---|---|
entity |
Object |
required |
Type: Promise
Encode ID of entity.
Property | Type | Default | Description |
---|---|---|---|
id |
any |
required |
Type: any
Decode ID of entity.
Property | Type | Default | Description |
---|---|---|---|
id |
any |
required |
Type: any
Find entities by query.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
Object |
- | Parameters. |
Type: Array.<Object>
List of found entities.
Get count of entities by query.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
Object |
- | Parameters. |
Type: Number
Count of found entities.
List entities by filters and pagination results.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
Object |
- | Parameters. |
Type: Object
List of found entities and count.
Create a new entity.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
Object |
- | Parameters. |
Type: Object
Saved entity.
Create many new entities.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
Object |
- | Parameters. |
Type: Object
, Array.<Object>
Saved entity(ies).
Get entity by ID.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
Object |
- | Parameters. |
Type: Object
, Array.<Object>
Found entity(ies).
Update an entity by ID.
After update, clear the cache & call lifecycle events.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
Object |
- | Parameters. |
Type: Object
Updated entity.
Remove an entity by ID.
Property | Type | Default | Description |
---|---|---|---|
ctx |
Context |
required | Context instance. |
params |
Object |
- | Parameters. |
List of connections registered in this connection manager.
Property | Type | Default | Description |
---|---|---|---|
No input parameters. |
Type: Array.<DataSource>
- List of connections
Checks if connection with the given name exist in the manager.
Property | Type | Default | Description |
---|---|---|---|
name |
string |
required | Connection name |
Type: boolean
- True if connection exist, false otherwise
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.
Property | Type | Default | Description |
---|---|---|---|
name |
string |
"default" |
Connection name |
Type: DataSource
- Connection
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.
Property | Type | Default | Description |
---|---|---|---|
name |
string |
"default" |
Connection name |
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.
Property | Type | Default | Description |
---|---|---|---|
name |
string , Array.<string> |
"default" |
Connection name |
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.
Property | Type | Default | Description |
---|---|---|---|
options |
Object |
required | TypeORM data source connection options |
newConnection |
boolean |
false |
Toggle to create a new instance of TypeORMDbAdapter. |
Type: Promise.<connection>
- Connection
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.
The project is available under the MIT license.
Copyright (c) 2023 Tyr Soluitons