@saibotsivad/mongodb

Simple wrapper for the MongoDB Data API.

> v1 Update! MongoDB's "Data API" is out of beta, so this library is now v1! 🎉

Install

The usual ways:

``shell
npm install @saibotsivad/mongodb
`

Example

Instantiate and issue a request:

`js
import { mongodb } from '@saibotsivad/mongodb'

const db = mongodb({
apiKey: 'AKAIDEXAMPLEKEY',
apiUrl: 'https://data.mongodb-api.com/app/data-abc123/endpoint/data/v1',
dataSource: 'myCluster3',
database: 'myDatabase',
collection: 'vehicles',
})

const car = await db.findOne({ filter: { type: 'car' } })
// => { _id: "61df...", type: "car", ...etc }
`

Instantiate

Import the { mongodb } function and instantiate with the following properties:

#### apiKey: string (always required)

The programmatic API key, generated using the MongoDB Atlas interface.

#### apiUrl: string (always required)

The fully qualified URL, e.g. something like this:

`
https://data.mongodb-api.com/app/data-abc123/endpoint/data/v1
`

#### interpose: function

Called immediately prior to making the fetch request, with the name of the request (e.g. findOne) and the body of the request. Useful for things like logging and debugging, but you can also mutate the object if needed.

`ts
type interpose = (input: { name: string, body: Object }) => { body: Object }
`

Request Requirements

These are properties that are required for every request.

You can set them when you create a mongodb instance, or override or provide them on the individual request:

`js
const db = mongodb({
apiKey: 'AKAIDEXAMPLEKEY',
apiUrl: 'https://data.mongodb-api.com/app/data-abc123/endpoint/data/v1',
dataSource: 'myCluster1',
database: 'myDatabase',
collection: 'vehicles',
})

// override collection for this one request
const car = await db.findOne({ filter: { type: 'hobbit' } }, { collection: 'people' })
// => { _id: "42fd...", type: "hobbit", ...etc }
`

#### dataSource: string

The name of the MongoDB cluster.

#### database: string

The name of the MongoDB database.

#### collection: string

The name of the collection.

Environment Specific

#### fetch: function

This library was written to use the fetch Web API using globalThis.fetch to make requests to the MongoDB Data API.

To make requests in an environment without fetch, e.g. NodeJS, you will need to provide your own fetch-like implementation.

Check the response type definition for interface requirements, but for example you could use something like the very lightweight httpie library, like in the demo.

Methods

The available methods follow the Data API Resources exactly, so go read those for more details.

Each one can be overridden with a second property, which is an object containing the earlier "Request Requirements" properties, e.g.:

`js
await db.findOne(
{ filter: { type: 'car' } },
{
dataSource: 'AlternateCluster',
database: 'AlternateDatabase',
collection: 'AlternateTable',
},
)
`

$3

Runs an aggregation pipeline and returns the result set of the final stage of the pipeline as an array of documents.

`ts
(
parameters: { pipeline: MongoPipeline },
overrides?: { dataSource?: string, database?: string, collection?: string },
) =>
Promise<{ documents: Array