Zync NestJS Data Module

Common errors

• Error: Cannot find module 'zync-nest-data-module'

  cause The package was attempted to be installed from the public npm registry instead of the private AsyncTech registry.
  fix Install using `npm install zync-nest-data-module --registry https://registry.asynctechs.com/` or `pnpm add zync-nest-data-module --registry https://registry.asynctechs.com/`.

• Nest can't resolve dependencies of the [Service/Repository]. Please make sure that the argument at index [X] is available in the [Module] context.

  cause A required provider (e.g., a custom repository, `TransactionManager`) or module (e.g., `DatabaseModule`, `MongooseModule`) was not correctly imported or provided in the respective NestJS module.
  fix Ensure that `DatabaseModule` and `BackupModule` are included in the `imports` array of your application's module. If using custom repositories, ensure they are listed in the `providers` array of the consuming module, and that `MongooseModule.forFeature()` is correctly configured for their schemas.

• MongooseError: The 'uri' parameter to 'openUri()' must be a string, got "undefined"

  cause The MongoDB connection URI provided to `MongooseModule.forRoot()` is undefined or null, likely due to a missing environment variable.
  fix Set the `MONGODB_URI` environment variable (e.g., `mongodb://localhost:27017/mydatabase`) or ensure your NestJS configuration correctly passes the database URI to `MongooseModule.forRoot()`.

• MongooseError: Transaction numbers are only allowed on replica sets. Please make sure that your MongoDB instance is running as a replica set.

  cause Attempting to use Mongoose transactions (via `TransactionManager`) with a standalone MongoDB instance, which does not support transactions.
  fix Configure your MongoDB server as a replica set. For local development, you can start a single-node replica set. Refer to MongoDB documentation for replica set setup.

Warnings

• gotcha This module is primarily published to a private registry (`https://registry.asynctechs.com/`). Attempting to install directly from the public npm registry (`npm install zync-nest-data-module`) will result in a 'package not found' error.
  Fix: Always install using the specified registry: `npm install zync-nest-data-module --registry https://registry.asynctechs.com/` or `pnpm add zync-nest-data-module --registry https://registry.asynctechs.com/`.
• gotcha The module relies heavily on `mongoose` and `@nestjs/mongoose` as peer dependencies. Ensure that the versions of these peer dependencies in your project are compatible with the module's requirements, especially when upgrading Mongoose to major versions (e.g., Mongoose 7.x to 8.x).
  Fix: Check the `peerDependencies` in `package.json` for specific version ranges and align your project's Mongoose and NestJS Mongoose versions accordingly to avoid runtime errors.
• gotcha The `BaseSchema` and `AbstractBaseRepository` are designed to support soft deletion (via `isDeleted` property). If not handled correctly in queries or business logic, soft-deleted documents might still appear or be inadvertently processed, leading to data inconsistencies or unexpected behavior.
  Fix: Always use the repository methods (e.g., `find`, `findOne`) which typically filter out soft-deleted documents by default. When explicitly needing soft-deleted items, ensure your queries or repository overrides account for the `isDeleted` flag.
• gotcha Transaction management through `TransactionManager` requires MongoDB to be running as a replica set, even for local development. Transactions will fail with an error if executed against a standalone MongoDB instance.
  Fix: For local development and production, ensure your MongoDB instance is configured as a replica set. For example, to start a single-node replica set locally: `mongod --replSet rs0 --port 27017 --dbpath /data/db` and then `rs.initiate()` in the mongo shell.

Install

• npm install zync-nest-data-module npm
• yarn add zync-nest-data-module yarn
• pnpm add zync-nest-data-module pnpm

Imports

• DatabaseModule
  wrong:

  const { DatabaseModule } = require('zync-nest-data-module');

  correct:

  import { DatabaseModule } from 'zync-nest-data-module';

  Primary module for MongoDB/Mongoose integration. Used in NestJS `imports` array.
• BackupModule
  wrong:

  const BackupModule = require('zync-nest-data-module').BackupModule;

  correct:

  import { BackupModule } from 'zync-nest-data-module';

  Module for automated database backup services. Also used in NestJS `imports`.
• BaseService

  import { BaseService } from 'zync-nest-data-module';

  Generic base class for creating application services with common CRUD and pagination methods.
• BaseSchema

  import { BaseSchema } from 'zync-nest-data-module';

  A Mongoose schema class providing common fields like `_id`, `createdAt`, `updatedAt`, and `isDeleted` for soft deletion.
• AbstractBaseRepository

  import { AbstractBaseRepository, IPageParams } from 'zync-nest-data-module';

  Abstract class for implementing repositories with standard database operations. `IPageParams` is an interface for pagination.
• TransactionManager

  import { TransactionManager } from 'zync-nest-data-module';

  Service for managing Mongoose transactions, ensuring atomicity for complex operations.

Quickstart

Demonstrates the basic setup of the Zync NestJS Data Module in an AppModule, including how to define a Mongoose schema extending `BaseSchema` and how to implement a custom repository using `AbstractBaseRepository`, showcasing common database patterns.

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';
import { Schema, Prop, SchemaFactory } from '@nestjs/mongoose';
import { Injectable } from '@nestjs/common';
import { SoftDeleteModel } from 'mongoose-delete';

import {
  DatabaseModule,
  BackupModule,
  BaseSchema,
  AbstractBaseRepository,
  IPageParams
} from 'zync-nest-data-module';

// 1. Define your Mongoose Schema extending BaseSchema
@Schema({
  timestamps: true,
  collection: 'my_documents'
})
export class MyDocument extends BaseSchema {
  @Prop({ required: true, unique: true })
  name: string;

  @Prop()
  description?: string;
}

export const MyDocumentSchema = SchemaFactory.createForClass(MyDocument);

// 2. Create your custom repository
@Injectable()
export class MyRepository extends AbstractBaseRepository<MyDocument> {
  constructor(@MongooseInjectModel(MyDocument.name) model: SoftDeleteModel<MyDocument>) {
    super(model);
  }

  protected buildQuery(query: Partial<MyDocument>): any {
    return query;
  }

  public async mapData(data: any, isCreate: boolean): Promise<MyDocument> {
    return data;
  }

  async findByName(name: string): Promise<MyDocument[]> {
    return this.find({ name });
  }
}

// 3. Set up your NestJS AppModule
@Module({
  imports: [
    MongooseModule.forRoot(process.env.MONGODB_URI ?? 'mongodb://localhost/test'),
    MongooseModule.forFeature([{ name: MyDocument.name, schema: MyDocumentSchema }]),
    DatabaseModule, // Integrates core database utilities
    BackupModule,   // Integrates database backup service
  ],
  providers: [MyRepository],
  exports: [MyRepository]
})
export class AppModule {}

// Note: MongooseInjectModel is a placeholder. In a real app, use @nestjs/mongoose's @InjectModel.
// The code above uses a common alias 'MongooseInjectModel' to avoid direct import conflict for example clarity.