@embedvr/mongodb-data-api

MongoDB Atlas Data API SDK for Node.js and V8 Isolate environments like Cloudflare Workers.

Fixes a bug with aggregation.

Installation

npm i @embedvr/mongodb-data-api

or

yarn add @embedvr/mongodb-data-api

Usage

Init

import { createMongoDBDataAPI, Region } from '@embedvr/mongodb-data-api'

// init by URL Endpoint
const api = createMongoDBDataAPI({
  apiKey: '<your_mongodb_api_key>',
  urlEndpoint: 'https://data.mongodb-api.com/app/<your_mongodb_app_id>/endpoint/data/beta'
})

// or init by app ID
const api = createMongoDBDataAPI({
  apiKey: '<your_mongodb_api_key>',
  appId: '<your_mongodb_app_id>'
})

// specific region of app
const api = createMongoDBDataAPI({
  apiKey: '<your_mongodb_api_key>',
  appId: '<your_mongodb_app_id>',
  region: Region.Virginia
})

Actions

See MongoDB Data API Resources.

• api.findOne
• api.find
• api.insertOne
• api.insertMany
• api.updateOne
• api.updateMany
• api.replaceOne
• api.deleteOne
• api.deleteMany
• api.aggregate

Action examples

1. find a single document

api
  .findOne({
    dataSource: '<target_cluster_name>',
    database: '<target_database_name>',
    collection: '<target_collection_name>',
    filter: { name: 'Surmon' }
  })
  .then((result) => {
    console.log(result.document)
  })

2. insert a single document

api
  .insertOne({
    dataSource: '<target_cluster_name>',
    database: '<target_database_name>',
    collection: '<target_collection_name>',
    document: {
      name: 'Surmon',
      age: 19
    }
  })
  .then((result) => {
    console.log(result.insertedId)
  })

3. run an aggregation pipeline

api
  .aggregate({
    dataSource: '<target_cluster_name>',
    database: '<target_database_name>',
    collection: '<target_collection_name>',
    pipeline: [
      { $match: { status: 'urgent' } },
      { $group: { _id: '$productName', sumQuantity: { $sum: '$quantity' } } }
    ]
  })
  .then((result) => {
    console.log(result.documents)
  })

Method chaining

// select cluster
const clusterA = api.$cluster('a')
// select database
const databaseB = clusterA.$database('b')
// select collection
const collectionC = databaseB.$collection<C>('c')
// data actions
const data = await collectionC.findOne({
  filter: {
    /*...*/
  }
})
const result = await collectionC.insertOne({
  document: {
    /*...*/
  }
})

// -------------

// chaining is equivalent to the api call
api.$cluster('a').$database('b').$collection<C>('c').findOne({ filter: {} })
// the same as
api.findOne<C>({
  dataSource: 'a',
  database: 'b',
  collection: 'c',
  filter: {}
})

Specific Action

You can specific the action request to prevent this package from lagging relative to the official one.

api.$$action('findOne', {
  dataSource: '...',
  database: '...',
  collection: '...',
  filter: {}
})

Original Class

You can use the original Class to implement some special requirements.

import { MongoDBDataAPI } from 'mongodb-data-api'

const customerCollection = new MongoDBDataAPI<CustomerDocument>(
  {
    apiKey: '<your_mongodb_api_key>',
    appId: '<your_mongodb_app_id>'
  },
  {
    dataSource: '<target_cluster_name>',
    database: '<target_database_name>',
    collection: '<target_collection_name>'
  }
)

const customer = await customerCollection.findOne({ ... })

Development

# install dependencies
yarn

# lint
yarn lint

# test
yarn test

# build
yarn build

Changelog

Detailed changes for each release are documented in the release notes.

License

MIT