carabao-mongo

library1.1.3jsnpmunverified

Carabao-Mongo is a lightweight, TypeScript-first abstraction over the official MongoDB driver (v1.1.3). It provides strong typing, explicit CRUD operations, aggregation-based queries with joins via $lookup, UUID abstraction, multi-database support, and transaction support. Unlike ORMs, it avoids decorators and schema reflection, staying close to MongoDB concepts while reducing boilerplate. Release cadence is irregular; active development continues. Key differentiator: type-safe, explicit query API without magic, enabling easy fallback to native driver.

database

npm install carabao-mongo

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CARABAO-MONGO

carabao-mongo

databasejavascriptv1.1.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

connectDatabase

✓ import { connectDatabase } from 'carabao-mongo'

✗ const { connectDatabase } = require('carabao-mongo')

ESM-only; TypeScript types included.

getCollection

✓ import { getCollection } from 'carabao-mongo'

✗ import { getCollection } from 'carabao-mongo/lib/collection'

Always import from the main package; subpath exports are not public.

closeDatabase

✓ import { closeDatabase } from 'carabao-mongo'

✗ import { closeDatabase } from 'carabao-mongo/client'

closeDatabase is a top-level export.

Collection

✓ import type { Collection } from 'carabao-mongo'

✗ import { Collection } from 'carabao-mongo'

Collection is a type, use type import to avoid runtime import.

QueryOptions

✓ import type { QueryOptions } from 'carabao-mongo'

✗ import { QueryOptions } from 'carabao-mongo'

QueryOptions is a type parameter.

Shows connecting, inserting with unique constraint, querying with pagination metadata, and closing the connection.

import { connectDatabase, getCollection, closeDatabase } from 'carabao-mongo'; interface User { uuid?: string; name: string; email: string; createdAt: Date; status: 'active' | 'inactive'; } const run = async () => { await connectDatabase(process.env.MONGO_URI ?? 'mongodb://localhost:27017/test'); const userCollection = await getCollection<User>('users'); // Insert const id = await userCollection.insertData({ data: { name: 'Jane', email: 'jane@example.com', createdAt: new Date(), status: 'active' }, uniqueFields: ['email'] }); console.log('Inserted:', id); // Query const users = await userCollection.findMultipleData({ where: { status: 'active' } }); console.log('Total:', users.totalCount, 'Users:', users.datas); await closeDatabase(); }; run().catch(console.error);

Debug

Known issues

gotchaThe `uuid` field is automatically generated if omitted; it is the string representation of the MongoDB `_id` ObjectId. Do not set `uuid` manually unless you intend to control the `_id` value.

fix

Let the library generate `uuid` automatically, or pass a valid UUID string.

affects: >=1.0

gotcha`findMultipleData` always returns pagination metadata (`{ datas, totalCount }`) even if no pagination is specified. totalCount counts all matching documents (not affected by limit).

fix

If you only need the documents, use `findSingleData` or destructure `datas` from `findMultipleData`.

affects: >=1.0

gotchaThe `uniqueFields` option in `insertData` uses a unique index on those fields. If the index doesn't exist, the insert may succeed but the uniqueness guarantee is not enforced by the library.

fix

Create a unique index in MongoDB before using `uniqueFields`, or handle potential duplicates manually.

affects: >=1.0

gotcha`getCollection` returns a `Collection` instance, but `insertData` returns only the `uuid` string (not the full document). The return type differs from native MongoDB driver's `InsertOneResult`.

fix

Expect a string, not an object with `acknowledged` etc.

affects: >=1.0

deprecatedEarly versions (before 1.0) used a different API with `getCollection` returning directly without await. Now `getCollection` is async and must be awaited.

fix

Use `await getCollection<T>('collectionName')` instead of `getCollection<T>('collectionName')`.

affects: <1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'carabao-mongo'

Package not installed.

fix

Run `npm install carabao-mongo mongodb` to install both packages.

TypeError: userCollection.insertData is not a function

Using an older version where the method was named differently or not available.

fix

Update to version >=1.0.0. The method is `insertData` (not `insert` or `insertOne`).

TypeError: (intermediate value).findMultipleData is not a function

Missing `await` on `getCollection`.

fix

Use `const collection = await getCollection<T>('name')`.

Argument of type '{ where: ... }' is not assignable to parameter of type 'QueryOptions<T>'

Incorrect query options structure; `where` should be a MongoDB filter object.

fix

Check the type definition: `QueryOptions` has `where`, `select`, `sort`, `limit`, `skip`, etc.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

mongodbrequiredPeer dependency for MongoDB driver; version >=6.0

Agent activity

40 hits · last 30 days

node

Bingbot

OpenAI (training)

Resources

githubhttps://github.com/TinyRabarioelina/carabao-mongo ↗

packagecarabao-mongo ↗

homepagehttps://github.com/TinyRabarioelina/carabao-mongo#readme ↗