cry-db MongoDB Wrapper

Common errors

• MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

  cause The MongoDB server is not running or is not accessible at the configured `MONGO_URL` (often the default `mongodb://127.0.0.1:27017`).
  fix Ensure your MongoDB instance is running. Verify that `process.env.MONGO_URL` (or the explicit database name in the constructor) is correctly pointing to your MongoDB server address and port.

• Query returns no documents, but I know they exist.

  cause Documents might be marked as soft-deleted (`_deleted`) or archived (`_archived`), and standard queries automatically filter these out by default.
  fix When calling query methods like `find` or `findOne`, pass `{ returnDeleted: true }` and/or `{ returnArchived: true }` in the options object to include these records in the results. Alternatively, use `findAll` which bypasses these filters.

Warnings

• gotcha When soft-delete (`_deleted`) or archiving (`_archived`) features are enabled, most query methods automatically filter out records marked as deleted or archived by default. This can lead to seemingly missing documents.
  Fix: To retrieve soft-deleted records, pass `{ returnDeleted: true }` in `QueryOpts`. For archived records, use `{ returnArchived: true }`. To bypass all filters, use `findAll`.
• gotcha The `deleteOne()` and `delete()` methods perform a *soft-delete* (setting the `_deleted` flag) if soft-delete is enabled for the `Repo` instance. They do not physically remove the document.
  Fix: To permanently remove a document from the database, use `hardDeleteOne()` or `hardDelete()`.
• gotcha Connection to MongoDB relies on `MONGO_URL` and `MONGO_DB` environment variables by default. If these are not set, the library will attempt to connect to `mongodb://127.0.0.1:27017` and use the default database name 'test'.
  Fix: Ensure `process.env.MONGO_URL` and `process.env.MONGO_DB` are correctly configured in your application environment or explicitly pass the database name to the `Repo` or `Mongo` constructor.
• gotcha When revisions are enabled (`useRevisions(true)`), every write operation (insert, update) automatically increments the `_rev` field and updates the `_ts` (timestamp) field on documents.
  Fix: Be aware of these automatic field additions and updates, especially when performing partial updates or expecting specific document shapes. Integrate `_rev` and `_ts` into your document interfaces (`T`) for type safety if using `Repo<T>`.

Install

• npm install cry-db npm
• yarn add cry-db yarn
• pnpm add cry-db pnpm

Imports

• Repo
  wrong:

  const Repo = require('cry-db').Repo;

  correct:

  import { Repo } from 'cry-db';

  `Repo` is a named export, commonly used as a type-safe convenience class for single-collection operations.
• Mongo
  wrong:

  const Mongo = require('cry-db').Mongo;

  correct:

  import { Mongo } from 'cry-db';

  `Mongo` is a named export, providing lower-level, multi-collection database operations.
• ObjectId
  wrong:

  import { Types } from 'cry-db'; // For ObjectId

  correct:

  import { ObjectId } from 'cry-db';

  `cry-db` re-exports the `ObjectId` class from the underlying MongoDB driver for working with document IDs.

Quickstart

This quickstart demonstrates basic CRUD operations using both the `Repo` and `Mongo` classes, including an example of soft-delete and how to retrieve filtered records, and highlights the reliance on environment variables for MongoDB connection.

import { Repo, Mongo, ObjectId } from 'cry-db';

// Ensure MongoDB is running and accessible via MONGO_URL and MONGO_DB environment variables.
// Example: process.env.MONGO_URL = 'mongodb://127.0.0.1:27017';
// Example: process.env.MONGO_DB = 'mytestdb';

async function runExample() {
    // Repo — single-collection convenience class with type safety
    const users = new Repo<{ _id?: ObjectId, name: string, age: number, active?: boolean }>('users', process.env.MONGO_DB || 'testdb');

    // Mongo — multi-collection class for more granular control
    const mongo = new Mongo(process.env.MONGO_DB || 'testdb');

    console.log('--- Repo operations (users collection) ---');

    // Insert a new user
    let alice = await users.insert({ name: 'Alice', age: 30 });
    console.log('Inserted Alice:', alice);

    // Find Alice by name
    let foundAlice = await users.findOne({ name: 'Alice' });
    console.log('Found Alice:', foundAlice);

    // Update Alice's age
    await users.updateOne({ name: 'Alice' }, { $set: { age: 31 } });
    let updatedAlice = await users.findOne({ name: 'Alice' });
    console.log('Updated Alice:', updatedAlice);

    // Demonstrate soft-delete (opt-in) and retrieval
    await users.useSoftDelete(true); // Enable soft-delete for this Repo instance
    if (updatedAlice?._id) {
        await users.deleteOne({ _id: updatedAlice._id });
        console.log('Soft-deleted Alice. Trying to find (should be null):', await users.findOne({ _id: updatedAlice._id }));
        console.log('Finding deleted Alice (with returnDeleted):', await users.findOne({ _id: updatedAlice._id }, { returnDeleted: true }));

        // Cleanup (hard delete to permanently remove)
        await users.hardDeleteOne(updatedAlice._id);
    }
    console.log('Count after cleanup:', await users.count({}));

    console.log('\n--- Mongo operations (products collection) ---');

    // Mongo can operate on any collection without creating a dedicated Repo instance
    const productsCollection = 'products';
    let product1 = await mongo.insert(productsCollection, { name: 'Laptop', price: 1200 });
    console.log('Inserted Laptop:', product1);

    let foundProduct = await mongo.findOne(productsCollection, { name: 'Laptop' });
    console.log('Found Laptop:', foundProduct);

    // Clean up
    if (product1?._id) {
        await mongo.hardDelete(productsCollection, { _id: product1._id });
    }
    console.log('Hard-deleted Laptop.');
}

runExample().catch(console.error);