Mongol

Minimalistic MongoDB helper for Node.js.

FEATURES

Auto-connect support
Enhanced JSON Schema draft-4 support
Database hook/trigger support (This feature is still in its early stage of development. Please use it with caution!)
Useful builtin hooks

INSTALLATION

Requirements

Node.js >= 10
MongoDB >= 3.6

Instructions

With yarn:

$ yarn add @albert-team/mongol

With npm:

$ npm i @albert-team/mongol

GET STARTED

The easy way:

const { Mongol } = require('@albert-team/mongol')

const main = async () => {
  const mongol = new Mongol('mongodb://localhost:27017/myproject', 'myproject')
  const coll = await mongol.promisifiedCollection('mycollection')

  // ...now you can use coll variable as a normal Collection object

  await mongol.disconnect()
}
main()

The hard way:

const { Mongol } = require('@albert-team/mongol')

const main = async () => {
  const mongol = new Mongol('mongodb://localhost:27017/myproject', 'myproject', {
    // you can pass any valid MongoClient options here
    client: { useNewUrlParser: true, useUnifiedTopology: true }
  })
  await mongol.connect()
  const db = mongol.database
  const coll = db.collection('mycollection')

  // ...now you can use coll variable as a normal Collection object

  await mongol.disconnect()
}
main()

USAGE

Auto-connect support

To access Db object, instead of manually calling Mongol.connect():

await mongol.connect()
const db = mongol.database

Just use Mongol.promisifiedDatabase and you are good to go:

const db = await mongol.promisifiedDatabase

To fetch an ExtendedCollection object, instead of manually calling Mongol.collection():

await mongol.connect()
const coll = mongol.collection('mycollection')

Just use Mongol.promisifiedCollection() and you are good to go:

const coll = await mongol.promisifiedCollection('mycollection')

Enhanced JSON Schema draft-4 support

Instead of throwing errors on schemas with omitted keywords ($ref, $schema, default, definitions, format and id), Mongol can help you ignore them quietly:

const usedSchema = await mongol.setSchema('mycollection', originalSchema, {
  ignoreType: true,
  ignoreUnsupportedKeywords: true
})

Database hook/trigger support

You can attach a hook to a collection either by using ExtendedCollection.attachHook():

const coll = await mongol.promisifiedCollection('mycollection')
// or
// const coll = mongol.collection('mycollection')
coll.attachHook({
  before: (context) => console.log(`Before ${context.operation}`),
  after: (context) => console.log(`After ${context.operation}`)
})
await coll.insertOne({ foo: 'bar' })
// Before insertOne
// After insertOne

Or using Mongol.attachDatabaseHook():

const coll = db.collection('mycollection')
mongol.attachDatabaseHook(coll, {
  before: (context) => console.log(`Before ${context.operation}`),
  after: (context) => console.log(`After ${context.operation}`)
})
await coll.insertOne({ foo: 'bar' })
// Before insertOne
// After insertOne

Notice:

Using ExtendedCollection.attachHook() is recommended, because it allows you to chain method calls as in the nested hooks example below.
Mongol.attachDatabaseHook() returns the original collection object but casted to ExtendedCollection anyway.

Nested hooks:

const coll = mongol
  .collection('mycollection')
  .attachHook({
    before: () => console.log('Inner before'),
    after: () => console.log('Inner after')
  })
  .attachHook({
    before: () => console.log('Outer before'),
    after: () => console.log('Outer after')
  })
await coll.insertOne({ foo: 'bar' })
// Outer before
// Inner before
// Inner after
// Outer after

Want "unhooked" version? Just create another collection object:

const another = mongol.collection('mycollection') // this has nothing to do with coll variable above
await another.insertOne({ foo: 'bar' })
//

Useful builtin hooks

Timestamp hook:

const { createTimestampHook } = require('@albert-team/mongol/builtins/hooks')

const coll = mongol
  .collection('mycollection')
  .attachHook(createTimestampHook({ namingConventions: ['unchanged', 'snakecase'] }))

Notice: Replacement document in replace operations (findOneAndReplace and replaceOne) is considered a new one, hence uses createdAt/created_at.

@albert-team/mongol