nestjs-ottoman
v3.0.0
Published
Downloads
65
Readme
Description
A Couchbase module for Nestjs, built on top of the ODM ottoman 2.x
Supported Couchbase version
- Server version 6.x, 7.x
- Nodejs SDK 4.x (supports Couchbase SDK API 3)
Usage
Installation
Yarn
yarn add nestjs-ottomanNPM
npm install nestjs-ottoman --saveIntegration
- Import
CouchbaseModulein the root App module(or whatever other module that contains other modules), this provides initialized ottoman connection instance that is available to other modules by injection. UseCouchbaseModule.forRootAsync()if the module options depend on asynchronous processing. You can also bootstrap multiple Ottoman connections corresponding to different cluster/buckets in oneCouchbaseModule.
import { Module } from '@nestjs/common';
import { CouchbaseModule } from 'nestjs-ottoman';
import configuration from './src/configuration';
@Module({
imports: [
ConfigModule.forRoot({
load: [configuration],
}),
CouchbaseModule.forRootAsync([{ // or CouchbaseModule.forRoot with a static option
imports: [ConfigModule],
useFactory: async (configService: ConfigService) => {
return configService.get('couchbase');
},
inject: [ConfigService],
}, {
connectionName: 'pet',
ottomanConnectionOptions: {
connectionString: 'couchbase://localhost',
bucketName: 'pet_bucket',
username: 'Administrator',
password: 'password',
},
}
]),
],
})
export class AppModule {}The configuration file looks like,
export default () => ({
couchbase: {
connectionName: 'cat',
ottomanConnectionOptions: {
connectionString: 'couchbase://localhost',
bucketName: 'cat_bucket',
username: 'Administrator',
password: 'password',
},
}
});
- Define an Ottoman Model and schema, user
CouchbaseModule.forFeature()to initialize and inject the Model object to other app modules.
import { Module } from '@nestjs/common';
import { CouchbaseModule } from 'nestjs-ottoman';
import { CatModelDefinition } from './cat.schema';
@Module({
//'cat' has to match the "connectionName" in step 1
imports: [CouchbaseModule.forFeature([CatModelDefinition], 'cat')],
})
export class CatModule {}- Inject initialized Model object to your service class. See the Ottoman documentation for Model API details.
import { Injectable } from '@nestjs/common';
import { Model, Ottoman } from 'ottoman';
import { InjectModel } from 'nestjs-ottoman';
import { CatModelDefinition } from './cat.schema';
@Injectable()
export class CatService {
constructor(
@InjectModel(CatModelDefinition.name) private catsModel: Model<any>
) {}
async findById(name: string): Promise<any> {
return this.catsModel.findById(name);
}
// other codes ...
}- Optionally, you can also inject a global ottoman connection pools in case of you need to use the low level Couchbase SDK directly.
You can get the specific connection by connectionName, then the
bucketproperty on the connection is a reference tobucketclass of Couchabse Nodejs SDK.
import { Injectable } from '@nestjs/common';
import { Model, Ottoman } from 'ottoman';
import { InjectConnections } from 'nestjs-ottoman';
@Injectable()
export class CatService {
constructor(
@InjectConnections() private connections: Map<String, Ottoman>,
) {}
// a function using the map-reduce view query
async findByBreed(breed: string): Promise<any> {
const res = await this.connections
.get('cat') // `connectionName` in step1,
.bucket.viewQuery('_default_default', 'findByBreed', {
key: breed,
});
return res.rows;
}
}Complete example code can be found in test folder.
Couchbase Indexes
According to the Ottoman Document, building the index can cause a significant performance impact, this Nestjs-Ottoman won't take care of index building, you have to have another script or application to handle the index initialization.
The index defined on schema will have index name like ${bucketName}_${scopeName}_${collectionName}_${modelName}_${indexFields} (or ${bucketName}_${scopeName}_${collectionName}_${indexFields} in nestjs-ottoman version v1.*.*).
When create indexes of different models, same index name may cause conflict, in that case, you can specify scopeName and collectionName in model definition to overwrite the default value '_default'.
Design
Modeling
╔══════════════════════════════════════╗
║ ║
║ (scope:collection-1)║
║ ┌───────────┐ ┌──────────┐ ║
┌───╬─▶│ Model1 │ │ Schema1 │ ║
│ ║ └───────────┘ └──────────┘ ║
│ ║ ║
┌────────────────────┐ ┌─────────────────────┐ │ ║ ║
│ bucket │ │ │ │ ╚══════════════════════════════════════╝
│ │ │ Ottoman instance1 │ │ ╔══════════════════════════════════════╗
│ (cluster:bucket) │────▶│ (connection1) │─────┤ ║ ║
│ │ │ │ │ ║ (scope:collection-2)║
└────────────────────┘ └─────────────────────┘ │ ║ ┌──────────┐ ┌───────────┐ ║
└───╬─▶ │ Model2 │ │ Schema2 │ ║
║ └──────────┘ └───────────┘ ║
║ ║
║ ║
╚══════════════════════════════════════╝
╔══════════════════════════════════════╗
║ ║
║ (scope:collection-1)║
║ ┌───────────┐ ┌──────────┐ ║
┌──╬──▶│ Model3 │ │ Schema3 │ ║
┌─────────────────────┐ ┌─────────────────────┐ │ ║ └───────────┘ └──────────┘ ║
│ bucket │ │ │ │ ║ ║
│ │ │ Ottoman instance2 │ │ ║ ║
│ (cluster:bucket) │───▶│ (connection2) │─────┤ ║ ║
│ │ │ │ │ ║ ┌──────────┐ ┌───────────┐ ║
└─────────────────────┘ └─────────────────────┘ └──╬──▶ │ Model4 │ │ Schema4 │ ║
║ └──────────┘ └───────────┘ ║
║ ║
╚══════════════════════════════════════╝
Ottoman Models spawning
┌─────────────────────────────────────────┐
┌────────────────────────────────────┐ │ │
│Connection pool Provider │ │ │
│ │ │ │
│ ┌────────────────┐ │ │ │
│ │ connection1 │ │ │ ForFeature('model def', connName) │
│ └────────────────┘ │◀───use───│ │
│ ┌────────────────┐ │ │ │
│ │ connenction2 │ │ │ │
│ └────────────────┘ │ │ │
└────────────────────────────────────┘ │ │
└─────────────────────────────────────────┘
│
│
┌─────────generate────┴──generate───────┐
│ │
▼ ▼
┌────────────────────┐ ┌────────────────────┐
│ │ │ │
│ Provider-Model2 │ │ Provider-Model1 │
│ │ │ │
│ │ │ │
│ │ │ │
└────────────────────┘ └────────────────────┘Development
Installation
$ yarn installTest
Bootstrap the Couchbase servcie.
$ ./dockers/up.shRun the test code
$ yarn test