nest-qldb
v3.1.0
Published
NestJS ODM for Quantum Ledger Database QLDB
Downloads
174
Readme
Features
- Extends the
amazon-qldb-driver-nodejs
work to add ODM functionality for QLDB common in NestJS. - A simple dependency injection model with
NestQldbModule.forRoot()
,NestQldbModule.forRootAsync()
. - Simple auto-generated CRUD repositories for models, injectable by
@InjectRepository(model)
. - Provides a
QldbQueryService
provider for a simple Dapper-inspired query layer.
How To Use
Install
npm install --save nest-qldb
Importing
NestQldbModule.forRoot()
NestQldbModule.forRoot()
is the simplest way to import the QLDB module and autowire @QldbTable
decorators. We re-export the QldbDriver
from amazon-qldb-driver-nodejs
.
Note: It is necessary that the ledger be created before application initialization.
// app.module.ts
import { NestQldbModule, QldbDriver } from 'nest-qldb';
import { User } from './user.model.ts';
@Module({
imports: [
NestQldbModule.forRoot({
qldbDriver: new QldbDriver('fake-ledger')
createTablesAndIndexes: true,
tables: [User],
}),
],
})
class AppRootModule {}
driver
qldbDriver
is the driver to manage connections to Amazon's Quantum Ledger Database.
NestQldbModule.forRootAsync()
NestQldbModule.forRootAsync()
allows for a FactoryProvider
or ValueProvider
dependency declaration to import our module. Note that ExistingProvider
and ClassProvider
are not yet supported.
// app.module.ts
import { NestQldbModule, QldbDriver } from 'nest-qldb';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { User } from './user.model.ts';
@Module({
imports: [
NestQldbModule.forRootAsync({
qldbDriver: {
useFactory: async (configService: ConfigService) => {
return new QldbDriver(configService.qldbLedgerName, {
credentials: fromIni({
profile: config.qldbProfileName,
}),
});
},
inject: [ConfigService],
},
createTablesAndIndexes: true,
tables: [User],
}),
ConfigModule.forRoot(),
],
})
class AppRootModule {}
Registering Models Binds them to QLDB tables
Models
Model classes are the shape of the data in your QLDB tables. The @QldbTable()
decorator is used to register your model as a table in Quantum Ledger Database.
You can also define the tableName and indexes associated with that model. NOTE: You can only create index when tables are empty so in the module config.
There is config on the module to perform this action at startup createTablesAndIndexes, it gracefully handles tables/indexes already created, however, it'll cost you a few seconds on a cold start so it is advised to turn it off in a production serverless scenario. NOTE: Any id properties will be peeled off models before they are saved! id
is reserved for the qldb documentid
With decorator
// user.model.ts
import { QldbTable } from 'nest-qldb';
@QldbTable({
tableName: 'users',
tableIndexes: ['name', 'phoneNumber'],
})
class User {
name: string;
dateOfBirth: Date;
email: string;
phoneNumber: string;
}
tableName
This is the name of the collection stored in QLDB.
tableIndexes
These indexes will be created upon table creation. You cannot create indexes after records are inserted, so be aware.
useMetadataKey
Default: true
This declares whether the key field should be a value in the QLDB metadata object (true
), or a part of the data object (false
).
keyField
Default: id
This declares the field that will be used as the key.
Repository injection
Repositories can be injected using the @InjectRepository()
decorator. The repositories are created by nest-qldb
and are a simple CRUD interface handy for quickly creating REST controllers.
query(query QldbQuery)
- Performs Partiql query against table.create(data: T)
- Adds an object to the QLDB tableretrieve(id: string)
- Fetches a single document by it's QLDB assigned id.replace(id: string, data: T)
- Replaces an entire document based on the id.destroy(id: string)
- Deletes an object from the table but not its change history from the ledger.history(id: string)
- Fetches all versions of a document across historycreateMany(data: T[])
- Will save many records in transactional batches of 40.
@Controller()
class UserController {
constructor(
@InjectRepository(User) readonly usersRepository: Repository<User>,
) {}
@Get(':id')
async getById(id: string) {
return await this.usersRepository.retrieve(id);
}
}
QldbQueryService
The QldbQueryService
provider exposes simple methods that query and map the object to plain JSON objects.
query
- Performs a query returning a list of rows mapped to a plain JSON object.querySingle
- Performs a query returning a single row mapped to a plain JSON object.queryForSubdocument
- Performs a query returning a list of nested documents in rows mapped to a plain JSON object.querySingleForSubdocument
- Performs a query returning a nested documents in single row mapped to a plain JSON object.execute
- Performs a query that returns no results. Ideal for inserts, updates, and deletes.
import { Injectable } from '@nestjs/common';
import { QldbQueryService } from 'nest-qldb';
import { SearchResult } from './search.interfaces';
@Injectable()
class UserService {
constructor(private readonly queryService: QldbQueryService) {}
async searchUsers(searchQuery: string) {
return await this.queryService.query<SearchResult>(
`
SELECT
id as userId,
u.name as userName,
u.email as userEmail
FROM users AS u BY id
WHERE LOWER(u.name) LIKE ?
OR LOWER(u.email) LIKE ?
`,
searchQuery?.toLocaleLowerCase(),
);
}
}
Stay In Touch
- Author - Benjamin Main and BeerMoneyDev
License
nest-qldb is MIT licensed.
Several core NestDependencies moved to peer dependencies to shrink package size.