als-mongo-list

als-mongo-list is a flexible and intuitive library for managing MongoDB queries in Node.js applications. It provides a simplified way to handle filtering, pagination, sorting, and field selection using a main List class and related modules.

Installation

npm install als-mongo-list

Main Module: List

The List class is the primary interface for creating MongoDB queries. It abstracts common database query operations and provides a seamless way to filter, paginate, sort, and select fields.

Constructor

const list = new List(Model, options);

• Model: MongoDB model (required).
• options (optional): Object with the following properties:
  • select (default '-__v'): Fields to select.
  • populate (default []): Array of fields to populate.
  • order (default ''): Default sorting field.
  • searchKeys (default []): Array of fields allowed for search and filtering.

Example

const List = require('als-mongo-list');
const myModel = require('./models/myModel');

const list = new List(myModel, {
   select: 'name age',
   populate: ['comments'],
   order: 'age',
   searchKeys: ['name', 'age', 'isActive']
});

Methods

query(req, search)

This method initiates a query with the given request. It returns a Query instance that manages the filtering, pagination, sorting, and field selection.

• req: HTTP request object containing query parameters.
• search (optional): Search conditions.

Usage:

const result = await list.query(req).read();

Example with Pagination and Filtering

const req = { query: { pageNumber: '1', pageSize: '10', age_gte: '20', age_lte: '40', isActive: 'true' } };
const result = await list.query(req).read();

console.log(result);

Options

options.select - Fields to select from the database.

options.populate - Fields to populate.

options.order - Default field for ordering.

options.searchKeys - Array of fields to filter by.

Example: Complete Usage

const req = { query: { pageNumber: '1', pageSize: '10', name_regex: 'Al', age_gte: '20', age_lte: '30' } };

const result = await list.query(req).read();
console.log(result.items); // Paginated, filtered, and sorted results.

Helper Modules

prepareSearch(query, searchKeys)

Generates a search object from a query and set of searchable keys. This function handles various conditions including exact match, range, and regex search.

• query: Object with search criteria.
• searchKeys: Array of [key, validator] pairs, where validator is a function from typeFns.

type-fns.js

Utility functions that convert query values to specified types.

• String: Converts to a string.
• Boolean: Converts to boolean.
• Number: Converts to a number.
• ObjectId: Validates and converts to MongoDB ObjectId.

query.js

Handles filtering, pagination, sorting, and population for MongoDB queries.

Methods:

• populate(ref): Adds a population reference.
• select(fields): Limits the fields returned.
• order(field): Orders results by a specified field.

read.js

Executes the MongoDB query and returns paginated, sorted results.

• Returns an object with items, pagination, orderBy, and error.

Example API Usage

Basic Setup

const List = require('als-mongo-list');
const model = require('./models/myModel');

const list = new List(model, {
  select: 'name age',
  populate: ['author'],
  order: 'createdAt',
  searchKeys: ['name', 'age', 'isActive']
});

// Set up your request
const req = { query: { pageNumber: '1', pageSize: '10', name_regex: 'Test' } };
const result = await list.query(req).read();
console.log(result);

This documentation provides an overview of the functionality and API for als-mongo-list. For detailed examples, refer to the test cases which illustrate typical usage scenarios.