@alexdicy/mongodb-data-api

MongoDB Atlas Data API SDK for Node.js.

Installation

npm i @alexdicy/mongodb-data-api

or

yarn add @alexdicy/mongodb-data-api

Usage

Init

import { createMongoDBDataAPI } from '@alexdicy/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/v1'
})

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

// specific region and cloud of app
const api = createMongoDBDataAPI({
  apiKey: '<your_mongodb_api_key>',
  appId: '<your_mongodb_app_id>',
  region: '<your_mongodb_app_region>', // e.g. us-east-1
  cloud: '<your_mongodb_app_cloud>' // e.g. aws
})

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 specify 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