@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:

npm install @saibotsivad/mongodb

Example

Instantiate and issue a request:

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.

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:

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.:

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

aggregate

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

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

await db.aggregate({
	pipeline: [
		{
			$group: {
				_id: "$status",
				count: { $sum: 1 },
				text: { $push: "$text" }
			}
		},
		{ $sort: { count: 1 } }
	]
})
// => { documents [{ _id: ... }] }

deleteOne

Delete the first document matching the filter, and return the number of documents deleted.

(
	parameters: { filter: MongoFilter },
	overrides?: { dataSource?: string, database?: string, collection?: string },
) =>
	Promise<{ deletedCount: Number }>

await db.deleteOne({
	filter: { _id: { $oid: '6193ebd53821e5ec5b4f6c3b' } }
})
// => { deletedCount: 1 }

deleteMany

Delete multiple documents and return the number of documents deleted.

(
	parameters: { filter: MongoFilter },
	overrides?: { dataSource?: string, database?: string, collection?: string },
) =>
	Promise<{ deletedCount: Number }>

await db.deleteMany({
	filter: { status: 'complete' }
})
// => { deletedCount: 7 }

find

Find multiple documents and return a list of those documents.

(
	parameters: { filter: MongoFilter, projection: MongoProjection, sort: MongoSort, limit: Integer, skip: Integer },
	overrides?: { dataSource?: string, database?: string, collection?: string },
) =>
	Promise<{ documents: Array<Object> }>

await db.find({
	filter: { status: 'complete' },
	sort: { completedAt: -1 }
})
// => { documents: [{ _id: ... }] }

findOne

Find and return the first document matching the filter.

(
	parameters: { filter: MongoFilter, projection: MongoProjection },
	overrides?: { dataSource?: string, database?: string, collection?: string },
) =>
	Promise<{ document: Object }>

await db.findOne({ filter: { _id: { $oid: '6193ebd53821e5ec5b4f6c3b' } } })
// => { document: { _id: ... } }

insertOne

Insert a single document and return the ID of that document.

(
	parameters: { document: EjsonDocument },
	overrides?: { dataSource?: string, database?: string, collection?: string },
) =>
	Promise<{ insertedId: String }>

await db.insertOne({ document: { type: 'car' } })
// => { insertedId: '61935189ec53247016a623c9' }

insertMany

Insert multiple documents at once and return the generated IDs.

(
	parameters: { documents: Array<EjsonDocument> },
	overrides?: { dataSource?: string, database?: string, collection?: string },
) =>
	Promise<{ insertedIds: Array<String> }>

await db.insertMany({
	documents: [
		{ type: 'car' },
		{ type: 'truck' }
	]
})
// => { insertedIds: [ '61935189ec53247016a623c9', '61935189ec53247016a623ca' ] }

replaceOne

Replace or upsert the first document matching the filter and return the matched and modified count, along with the generated ID if a new document was generated.

(
	parameters: { filter: MongoFilter, replacement: EjsonDocument, upsert: Boolean },
	overrides?: { dataSource?: string, database?: string, collection?: string },
) =>
	Promise<{ matchedCount: Integer, modifiedCount: Integer, upsertedId?: String }>

await db.replaceOne({
	filter: { id: { $oid: '61935189ec53247016a623c9' } },
	replacement: { type: 'van' }
})
// => { matchedCount: 1, modifiedCount: 1, upsertedId: '...' }

updateOne

Update the first document matching the filter and return the matched and modified count, along with the generated ID if a new document was generated.

(
	parameters: { filter: MongoFilter, update: MongoUpdate, upsert: Boolean },
	overrides?: { dataSource?: string, database?: string, collection?: string },
) =>
	Promise<{ matchedCount: Integer, modifiedCount: Integer, upsertedId?: String }>

await db.updateOne({
	filter: { id: { $oid: '61935189ec53247016a623c9' } },
	update: {
		$set: {
			status: 'complete',
			completedAt: { $date: { $numberLong: Date.now().toString() } }
		}
	}
})
// => { matchedCount: 1, modifiedCount: 1, upsertedId: '...' }

updateMany

Update all documents matching the filter and return the matched and modified count, along with the generated ID if a new document was generated.

(
	parameters: { filter: MongoFilter, update: MongoUpdate, upsert: Boolean },
	overrides?: { dataSource?: string, database?: string, collection?: string },
) =>
	Promise<{ matchedCount: Integer, modifiedCount: Integer, upsertedId?: String }>

await db.updateOne({
	filter: { status: 'open' },
	update: {
		$set: {
			status: 'complete',
			completedAt: { $date: { $numberLong: Date.now().toString() } }
		}
	}
})
// => { matchedCount: 7, modifiedCount: 4 }

License

Published and released under the Very Open License.

If you need a commercial license, contact me here.