@denis_bruns/nosql-mongodb-service NPM

@denis_bruns/nosql-mongodb-service

A MongoDB service for clean architecture projects, featuring filter expressions, pagination, and safe validations.

Overview

@denis_bruns/nosql-mongodb-service provides a MongoDB-specific data service based on clean architecture principles. It extends @denis_bruns/base-database-service to offer:

Filter expression construction (MongoExpressionBuilder), converting filters to MongoDB queries
Offset-based pagination and in-memory transformations
Type-safe mapping of _id to id for convenience
Validation utilities to mitigate NoSQL injection attempts
Seamless integration with MongoDB’s native Collection API

This library aims to simplify the boilerplate involved in typical CRUD or query operations on MongoDB while keeping your business logic clean and testable.

Key Features

MongoDB-Specific Expression Builder
- Converts common filter queries (IFilterQuery) into a structured MongoDB conditions object.
- Supports operators like <, <=, >, >=, =, !=, in, not in, like, and not like.
Pagination & Sorting
- Applies limit, skip (offset), and sort automatically based on your query.
- Offers page-based and offset-based pagination in one approach.
Type-Safe Results
- Converts Mongo’s _id to a string id, enabling a more consistent domain model.
- Allows further overrides of processResults for custom transformations if desired.
Built-in Validation
- Ensures safe field names and values (validateValue) to help guard against potential injection patterns.
- Checks pagination parameters (validatePagination) to confirm integer inputs.
Extensible Architecture
- Extends the BaseDatabaseService so you can override or customize query building, error handling, or result processing.

Installation

With npm:

npm install @denis_bruns/nosql-mongodb-service

Or with yarn:

yarn add @denis_bruns/nosql-mongodb-service

You’ll also need MongoDB types and driver:

npm install mongodb

Basic Usage

Below is a simple usage example. In a real-world application, you might integrate this into a domain-specific repository or service layer.

import { MongoClient } from "mongodb";
import { fetchWithFiltersAndPaginationMongoDb, MongoDBService } from "@denis_bruns/nosql-mongodb-service";
import { IGenericFilterQuery } from "@denis_bruns/web-core-ts";

interface User {
  id: string;
  name: string;
  email: string;
}

async function example() {
  // 1) Connect to MongoDB
  const client = new MongoClient("mongodb://localhost:27017");
  await client.connect();
  const collection = client.db("my-database").collection("users");

  // 2) Build a filter query
  const query: IGenericFilterQuery = {
    filters: [
      { field: "email", operator: "=", value: "test@example.com" }
    ],
    pagination: { page: 1, limit: 5, sortBy: "name" }
  };

  // 3) Option A: Direct Helper Function
  const directResult = await fetchWithFiltersAndPaginationMongoDb<User>(
    "users", // tableName
    query,
    collection
  );
  console.log("Direct Helper:", directResult.data);

  // 4) Option B: MongoDBService instance
  const service = new MongoDBService("users");
  const serviceResult = await service.fetchWithFiltersAndPagination<User>(query, collection);
  console.log("Service Class:", serviceResult.data);

  client.close();
}

example().catch((err) => console.error("Mongo Example Error:", err));

In this snippet:

fetchWithFiltersAndPaginationMongoDb is a quick helper if you just need a one-off query.
MongoDBService allows for deeper customization or extension in your codebase.

Core Concepts

Filter Expressions
Each filter has field, operator, and value. Operators like "in", "not in", "like", and "not like" are mapped to Mongo’s $in, $nin, $regex, and $not respectively.
```
filters: [
  { field: "status", operator: "=", value: "active" },
  { field: "name", operator: "like", value: "john" }
];
```
Pagination
- page, limit, offset are all supported.
- sortBy and sortDirection let you sort on a specific field in ascending or descending order.
Validation
- validateValue checks for suspicious patterns in strings or objects (to reduce injection attacks).
- validatePagination ensures page, limit, and offset are valid integers.
ID Mapping
- If your filters or results use "id", it’s automatically mapped to or from _id so you can keep a consistent domain model.

Related Packages

@denis_bruns/web-core-ts

Contains the fundamental interfaces and types used in this library (e.g., IFilterQuery, IGenericFilterQuery, etc.).
@denis_bruns/base-database-service

The abstract service this library extends to handle common database logic, such as error handling and pagination utilities.