mongo-http

v0.0.20

Published

a year ago

A thin wrapper on Mongodb Atlas Data API using native fetch API

Downloads

0High
0Medium
0Low

patrick-kw-chiu

mongo mongodb http async serverless cloudflare workers deno typescript

mongo-http.js

About

mongo-http.js flow

A thin wrapper on Mongodb Atlas Data API using native fetch API. This library serves the usecase where

TCP connections over Mongodb Atlas is not possible (e.g. Serverless runtime like Cloudflare Workers), while still wanting to use similar MongoDB driver syntax.
It can also be used in serverless runtimes which the reuse of a MongoDB connection may not always be available or require manual caching
Sadly, it cannot be used in the browser side yet, due to CORS. Here is a thread to request the CORS feature

Setup

1. Setup MongoDB Atlas to get the App ID and API Key (and App Region)

Follow MongoDB Atlas tutorial.

Get the App ID here

Screenshot 2022-11-20 at 2 25 46 PM

🚨 Importart 🚨: If you select "Local (single region)" when you enable Data API

Screenshot 2023-08-27 at 11 13 25 PM

Make sure to pass the App Region as well!

Screenshot 2023-08-27 at 11 14 29 PM

And Get the API Key here

Screenshot 2022-11-20 at 2 27 12 PM

2. Installation

npm install mongo-http --save

3. Initialization

Depending on your needs, you can either initialize a client, database, or collection

You can initialize a client for connecting to multiple databases

import { initClient } from 'mongo-http';

const client = initClient({
    appId: process.env.appId,
    apiKey: process.env.apiKey,
    // Important! Pass `appRegion` if you deploy Data API as "Local (single region)"
    // See above "1. Setup MongoDB Atlas to get the App ID and API Key (and App Region)"
    appRegion: process.env.appRegion,
});

const db = client.database({ databaseName: process.env.databaseName });

const result = await db.collection('articles').find({
    filter: {
        $or: [{ categories: { $in: ['javascript', 'reactjs', 'nodejs', 'mongodb'] } }],
    },
});

... Or, Initialize a database

import { initDatabase } from 'mongo-http';

const db = initDatabase({
    appId: process.env.appId,
    apiKey: process.env.apiKey,
    // Important! Pass `appRegion` if you deploy Data API as "Local (single region)"
    // See above "1. Setup MongoDB Atlas to get the App ID and API Key (and App Region)"
    appRegion: process.env.appRegion,
    databaseName: process.env.databaseName || '',
});

const result = await db.collection('articles').find({});

... Or, Initialize a collection

import { initCollection } from 'mongo-http';

const articlesCollection = initCollection({
    appId: process.env.appId,
    apiKey: process.env.apiKey,
    // Important! Pass `appRegion` if you deploy Data API as "Local (single region)"
    // See above "1. Setup MongoDB Atlas to get the App ID and API Key (and App Region)"
    appRegion: process.env.appRegion,
    databaseName: process.env.databaseName,
    collectionName: 'articles',
});

const result = await articlesCollection.find({});

API

.findOne({ filter, projection })

Example

const { isSuccess, document, error } = await db.collection('articles').findOne({
    filter: {
        $or: [{ creator: 'Patrick Chiu' }, { title: 'Migrating a Node.js App to Cloudflare Workers From Heroku' }],
    },
    projection: { title: 1, creator: 1, guid: 1, categories: 1 },
});

Parameter

| Parameter | Type | Default Value | Description | | ---------- | ------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | filter | object | {} | A MongoDB Query Filter. The findOne action returns the first document in the collection that matches this filter.If you do not specify a filter, the action matches all document in the collection. | | projection | object | {} | A MongoDB Query Projection. Depending on the projection, the returned document will either omit specific fields or include only specified fields or values) |

Return

| Field | Type | Description | | --------- | ------------- | --------------------------------------------------------------------------------------- | | isSuccess | boolean | Whether the database operation successful or not | | document | object / null | If a document is matched, an object is returnedIf not matched, a null is returned | | error | error / null | Error information |

.find({ filter, projection, sort, limit, skip })

Example

const { isSuccess, documents, error } = await db.collection('articles').find({
    filter: {
        $or: [{ categories: { $in: ['javascript', 'nodejs'] } }],
    },
    projection: { title: 1, creator: 1, guid: 1, categories: 1 },
    sort: { createdAt: -1 },
    limit: 50,
    skip: 100,
});

Parameter

| Parameter | Type | Default value | Description | | ---------- | ------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filter | object | {} | A MongoDB Query Filter. The find action returns documents in the collection that match this filter.If you do not specify a filter, the action matches all document in the collection.If the filter matches more documents than the specified limit, the action only returns a subset of them. You can use skip in subsequent queries to return later documents in the result set. | | projection | object | {} | A MongoDB Query Projection. Depending on the projection, the returned document will either omit specific fields or include only specified fields or values) | | sort | object | {} | A MongoDB Sort Expression. Matched documents are returned in ascending or descending order of the fields specified in the expression. | | limit | number | 1000 | The maximum number of matched documents to include in the returned result set. Each request may return up to 50,000 documents. | | skip | number | 0 | The number of matched documents to skip before adding matched documents to the result set. |

Return

| Field | Type | Description | | --------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------ | | isSuccess | boolean | Whether the database operation successful or not | | documents | array of object(s) / empty array | If document(s) are matched, an array of object(s) is returnedIf no matches, an empty array is returned | | error | error / null | Error information |

.insertOne(document)

Example

const { isSuccess, insertedId, error } = await db.collection('tags').insertOne({
    cachedAt: '2022-11-25T17:44:59.981+00:00',
    tags: ['startup', 'programming', 'digital-nomad', 'passive-income', 'python'],
});

Parameter

Return

| Field | Type | Description | | ---------- | ------------ | ------------------------------------------------ | | isSuccess | boolean | Whether the database operation successful or not | | insertedId | string | ID of the newly inserted document | | error | error / null | Error information |

.insertMany(documents)

Example

const { isSuccess, insertedIds, error } = await db.collection('tags').insertMany([
    {
        date: '2022-11-01T00:00:00.000+00:00',
        tags: ['startup', 'programming', 'digital-nomad', 'passive-income', 'python'],
    },
    {
        date: '2022-12-01T00:00:00.000+00:00',
        tags: ['goblin-mode', 'new-year', 'economic-crisis'],
    },
]);

Parameter

| Parameter | Type | Default value | Description | | --------- | ------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | documents | array of object(s) | [] | An array of one or more EJSON documents to insert into the collection. |

Return

| Field | Type | Description | | ----------- | ------------------ | ------------------------------------------------------------- | | isSuccess | boolean | Whether the database operation successful or not | | insertedIds | array of string(s) | _id values of all inserted documents as an array of strings | | error | error / null | Error information |

.updateOne({ filter, update, upsert })

Example

const { isSuccess, matchedCount, modifiedCount, upsertedId, error } = await db.collection('tags').updateOne({
    filter: {
        _id: { $oid: '638199c045955b5e9701be1f' },
    },
    update: {
        date: '2022-11-25T00:00:00.000+00:00',
        tags: ['startup', 'programming', 'digital-nomad', 'passive-income', 'python', 'something-else'],
    },
    upsert: true,
});

Parameter

| Parameter | Type | Default value | Description | | --------- | ------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filter | object | {} | A MongoDB Query Filter. The updateOne action modifies the first document in the collection that matches this filter. | | update | object | {} | A MongoDB Update Expression that specifies how to modify the matched document | | upsert | boolean | false | The upsert flag only applies if no documents match the specified filter. If true, the updateOne action inserts a new document that matches the filter with the specified update applied to it. |

Return

| Field | Type | Description | | ------------- | ------------ | -------------------------------------------------- | | isSuccess | boolean | Whether the database operation successful or not | | matchedCount | number | The number of documents that the filter matched | | modifiedCount | number | The number of matching documents that were updated | | upsertedId | string | ID of the newly inserted document | | error | error / null | Error information |

.updateMany({ filter, update, upsert })

Example

const { isSuccess, matchedCount, modifiedCount, upsertedId, error } = await db.collection('users').updateMany({
    filter: {
        lastLoginAt: { $lt: '2023-01-01' },
    },
    update: {
        isActive: false,
    },
    upsert: true,
});

Parameter

| Parameter | Type | Default value | Description | | --------- | ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filter | object | {} | A MongoDB Query Filter. The updateMany action modifies all documents in the collection that match this filter. | | update | object | {} | A MongoDB Update Expression that specifies how to modify matched documents. | | upsert | boolean | false | The upsert flag only applies if no documents match the specified filter. If true, the updateMany action inserts a new document that matches the filter with the specified update applied to it. |

Return

.replaceOne({ filter, replacement, upsert })

Example

const { isSuccess, matchedCount, modifiedCount, upsertedId, error } = await db.collection('tags').replaceOne({
    filter: {
        _id: { $oid: '638199c045955b5e9701be1f' },
    },
    replacement: {
        date: '2022-11-25T00:00:00.000+00:00',
        tags: ['startup', 'programming', 'digital-nomad', 'passive-income', 'python', 'something-else'],
    },
    upsert: true,
});

Parameter

| Parameter | Type | Default value | Description | | ----------- | ------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | filter | object | {} | A MongoDB Query Filter. The replaceOne action overwrites the first document in the collection that matches this filter. | | replacement | object | {} | An EJSON document that overwrites the matched document. | | upsert | boolean | false | The upsert flag only applies if no documents match the specified filter. If true, the replaceOne action inserts the replacement document. |

Return

.deleteOne({ filter })

Example

const { isSuccess, deletedCount, error } = await db.collection('tags').deleteOne({
    filter: {
        date: '2022-12-01T00:00:00.000+00:00',
    },
});

Parameter

| Parameter | Type | Default value | Description | | --------- | ------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filter | object | {} | A MongoDB Query Filter. The deleteOne action deletes the first document in the collection that matches this filter. |

Return

| Field | Type | Description | | ------------ | ------------ | ------------------------------------------------ | | isSuccess | boolean | Whether the database operation successful or not | | deletedCount | number | The number of deleted documents | | error | error / null | Error information |

.deleteMany({ filter })

Example

const { isSuccess, deletedCount, error } = await db.collection('tags').deleteMany({
    filter: {
        date: { $gte: '2022-12-01' },
    },
});

Parameter

| Parameter | Type | Default value | Description | | --------- | ------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filter | object | {} | A MongoDB Query Filter. The deleteMany action deletes all documents in the collection that match this filter. |

Return

.aggregate({ pipeline })

Example

const { isSuccess, documents, error } = await db.collection('users').aggregate({
    pipeline: [
        { $match: { userId: 'f95cfc82f512' } },
        {
            $lookup: {
                from: 'notifications',
                localField: 'userId',
                foreignField: 'userId2',
                as: 'notification',
            },
        },
        { $unwind: '$notification' },
    ],
});

Parameter

| Parameter | Type | Default value | Description | | --------- | ---------------- | ------------- | ------------------------------------------------------------------------------------------------- | | pipeline | array of objects | [] | A MongoDB Aggregation Pipeline. |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

mongo-http.js

About

Table of Contents

Setup

1. Setup MongoDB Atlas to get the App ID and API Key (and App Region)

Get the App ID here

🚨 Importart 🚨: If you select "Local (single region)" when you enable Data API

And Get the API Key here

2. Installation

3. Initialization

You can initialize a client for connecting to multiple databases

... Or, Initialize a database

... Or, Initialize a collection

API

.findOne({ filter, projection })

Example

Parameter

Return

.find({ filter, projection, sort, limit, skip })

Example

Parameter

Return

.insertOne(document)

Example

Parameter

Return

.insertMany(documents)

Example

Parameter

Return

.updateOne({ filter, update, upsert })

Example

Parameter

Return

.updateMany({ filter, update, upsert })

Example

Parameter

Return

.replaceOne({ filter, replacement, upsert })

Example

Parameter

Return

.deleteOne({ filter })

Example

Parameter

Return

.deleteMany({ filter })

Example

Parameter

Return

.aggregate({ pipeline })

Example

Parameter

Return