@albert-team/mongol

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.

API DOCUMENTATION

Read more here.

CHANGELOG

Read more here.