🧩️ Mongo Blocks

Mongo blocks provide pure business logic functions for MongoDB operations in NodeBlocks applications. These blocks contain the core database logic and are designed to be used with applyPayloadArgs for payload context lifting.

---

🎯 Overview

Mongo blocks are designed to:

• Separate database logic from payload handling
• Provide pure functions that take only required data
• Enable easy testing with isolated logic
• Support composition with payload context lifting
• Return Result types for proper error handling
• Handle MongoDB-specific operations with standardized error handling

---

📋 Mongo Block Types

Database Query Blocks

Pure functions for querying MongoDB collections.

Query Options Blocks

Pure functions for building MongoDB query options.

---

🔧 Available Mongo Blocks

findResources

Retrieves multiple documents from MongoDB collection with error handling.

Purpose: Executes MongoDB find queries with proper error handling and field projection, returning an array of documents or an appropriate error.

Parameters:

• collection: Collection - MongoDB collection instance to query
• options: { filter: Filter<Document>; options?: FindOptions } - Filter criteria and optional find options
• errorClass: BlockErrorConstructor - Error constructor class for custom error handling
• errorMessage: string - Error message to display if operation fails

Returns: Promise<Result<Document[], BlockError>> - Result with array of documents or error

Handler Process:

• Input: MongoDB collection, filter criteria, error class, and error message
• Process: Executes find query with projection to exclude _id field, converts cursor to array
• Output: Array of documents or error
• Errors: Returns custom BlockError if database operation fails

Usage:

import { blocks } from '@nodeblocks/backend-sdk';

const { findResources } = blocks;

// Used in route composition:
const findUsersRoute = withRoute({
  handler: applyPayloadArgs(
    findResources,
    [
      ['context', 'db', 'users'],
      ['params', 'requestQuery'],
      DatabaseError,
      'Failed to retrieve users'
    ]
  )
});

// Find all users with specific criteria:
const result = await findResources(
  usersCollection,
  { filter: { status: 'active' } },
  DatabaseError,
  'Failed to retrieve users'
);

if (result.isOk()) {
  const users = result.value;
  // Process found users
}

---

buildWithoutMongoIdFindOptions

Builds MongoDB find options to exclude the _id field from query results.

Purpose: Creates projection options to exclude MongoDB's default _id field from query results, ensuring clean API responses.

Parameters: None

Returns: Result<{ projection: { _id: 0 } }, never> - Result with MongoDB projection options

Handler Process:

• Input: No parameters required
• Process: Creates projection options to exclude MongoDB's default _id field
• Output: Projection configuration with _id: 0
• Errors: Never fails (always returns ok result)

Usage:

import { blocks } from '@nodeblocks/backend-sdk';

const { buildWithoutMongoIdFindOptions } = blocks;

// Used in route composition:
const findUsersRoute = withRoute({
  handler: compose(
    applyPayloadArgs(
      buildWithoutMongoIdFindOptions,
      [],
      'options'
    ),
    applyPayloadArgs(
      findResources,
      [
        ['context', 'db', 'users'],
        ['params', 'requestQuery'],
        ['context', 'data', 'options']
      ]
    )
  )
});

// Use in MongoDB queries to exclude _id field:
const options = buildWithoutMongoIdFindOptions();
if (options.isOk()) {
  const users = await collection.find({}, options.value);
}

---

🔗 Related Documentation

• Mongo Index - MongoDB blocks overview