@tresdoce-nestjs-toolkit/dynamoose NPM

Este módulo está pensado para ser utilizado en NestJS Starter, o cualquier proyecto que utilice una configuración centralizada, siguiendo la misma arquitectura del starter.

Glosario

📝 Requerimientos básicos

NestJS Starter
Node.js v20.18.0 or higher (Download)
YARN v1.22.19 or higher
NPM v10.9.0 or higher
NestJS v10.4.7 or higher (Documentación)
Cliente Local AWS DynamoDB (Download)

🛠️ Instalar dependencia

npm install -S @tresdoce-nestjs-toolkit/dynamoose

yarn add @tresdoce-nestjs-toolkit/dynamoose

⚙️ Configuración

Agregar los datos de conexión a DynamoDB en configuration.ts utilizando el key dynamodb y que contenga el objeto con los datos conexión desde las variables de entorno.

//./src/config/configuration.ts
import { Typings } from '@tresdoce-nestjs-toolkit/core';
import { registerAs } from '@nestjs/config';
import * as PACKAGE_JSON from '../../package.json';

export default registerAs('config', (): Typings.AppConfig => {
  return {
    //...
    dynamodb: {
      local: process.env.NODE_ENV !== 'production' || false,
      logger: process.env.NODE_ENV !== 'production' || false,
      aws: {
        accessKeyId: `${process.env.AWS_ACCESS_KEY_ID}`,
        secretAccessKey: `${process.env.AWS_SECRET_ACCESS_KEY}`,
        region: `${process.env.AWS_REGION}`,
      },
      table: {
        create: process.env.NODE_ENV !== 'production' || false,
        prefix: `${PACKAGE_JSON.name}-`,
        suffix: '-table',
      },
    },
    //...
  };
});

local: Habilita el uso de DynamoDB de manera local.

Type: Boolean | String
Default: false
Values: true | false | http://docker:8000 | http://localhost:8000

logger: Habilita los logs utilizando como provider a dynamoose-logger.

Type: Boolean
Default: false

AWS

Para los datos de AWS es sumamente importante utilizar los siguientes nombres de variables de entorno: AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_REGION

accessKeyId: Es el Access Key ID de aws.

Type: String
Default: local

secretAccessKey: Es el Secret Access Key de aws.

Type: String
Default: local

region: Es la region de la cuenta de aws.

Type: String
Default: us-east-1

Table

Esta propiedad solo está pensada para el desarrollo local, ya que para los entornos de AWS se recomienda no utilizarlo.

create: Activa la creación de la tabla en DynamoDB en caso de que no exista.

Type: Boolean
Default: true

prefix: Es una cadena de texto que se antepone al nombre de la tabla.

Type: String

suffix: Es una cadena de texto que se agrega al final del nombre de la tabla.

Type: String

💬 Para más información sobre la configuración de este módulo puedes revisar la Documentación de Dynamoose.

👨‍💻 Uso

Importar el DynamooseModule en el archivo app.module.ts, y el módulo se encargará de obtener la configuración e instanciar la conexión.

//./src/app.module.ts
import { DynamooseModule } from '@tresdoce-nestjs-toolkit/dynamoose';

@Module({
  //...
  imports: [
    //...
    DynamooseModule,
    //...
  ],
  //...
})
export class AppModule {}

Crear el Schema

//./src/users/models/user.schema.ts
import { Schema } from 'dynamoose';

export const UserSchema = new Schema({
  id: {
    type: String,
    hashKey: true,
  },
  firstName: {
    type: String,
  },
  lastName: {
    type: String,
  },
  email: {
    type: String,
  },
});

Crear el interface del Model

//./src/users/interfaces/user.interface.ts
export interface UserKey {
  id: string;
}

export interface User extends UserKey {
  firstName: string;
  lastName: string;
  email: string;
}

UserKey contiene la hashKey/partitionKey y (opcionalmente) la rangeKey/sortKey. User contiene todos los atributos del document/item. Al crear estas dos interfaces y usarlas al inyectar tu modelo tendrás typechecking al usar operaciones como Model.update().

Inyectar los Schemas al módulo

Se puede inyectar a nivel global en el app.module.ts, o bien, en los módulos que requieran utilizar dicho modelo.

//./src/users/users.module.ts
import { Module } from '@nestjs/common';
import { DynamooseModule } from '@tresdoce-nestjs-toolkit/dynamoose';

import { UsersController } from './controllers/users.controller';
import { UsersService } from './services/users.service';
import { UserSchema } from './models/user.schema';

@Module({
  imports: [
    DynamooseModule.forFeature([
      {
        name: 'User',
        schema: UserSchema,
        options: {
          tableName: 'user',
        },
      },
    ]),
  ],
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

Inyectar y usar los Models el módulo

//./src/users/users.service.ts
import { Injectable } from '@nestjs/common';
import { InjectModel, Model } from '@tresdoce-nestjs-toolkit/dynamoose';

import { UserKey, User as IUser } from '../interfaces/user.interface';

@Injectable()
export class UsersService {
  constructor(@InjectModel('User') private userModel: Model<IUser, UserKey>) {}

  async create(user: User): Promise<any> {
    return await this.userModel.create(user);
  }

  async update(key: UserKey, user: Partial<User>): Promise<any> {
    return await this.userModel.update(key, user);
  }

  async findOne(key: UserKey): Promise<any> {
    return await this.userModel.get(key);
  }

  async findAll(): Promise<any> {
    return await this.userModel.scan().exec();
  }
}

Transaction

//./src/users/users.service.ts
import { Injectable } from '@nestjs/common';
import { InjectModel, Model, TransactionSupport } from '@tresdoce-nestjs-toolkit/dynamoose';

import { UserKey, User as IUser } from '../interfaces/user.interface';

@Injectable()
export class UsersService {
  constructor(@InjectModel('User') private userModel: Model<IUser, UserKey>) {
    super();
  }

  async create(user: User): Promise<any> {
    await this.transaction([
      this.userModel.transaction.create(user);
    ]);
  }
}