{"id":16387588,"url":"https://github.com/surmon-china/mongodb-data-api","last_synced_at":"2025-03-16T16:31:01.425Z","repository":{"id":43065669,"uuid":"453183736","full_name":"surmon-china/mongodb-data-api","owner":"surmon-china","description":"MongoDB Atlas Data API SDK for @nodejs","archived":false,"fork":false,"pushed_at":"2022-11-23T19:54:12.000Z","size":186,"stargazers_count":40,"open_issues_count":3,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-27T11:35:50.801Z","etag":null,"topics":["mongodb","mongodb-api","mongodb-atlas","mongodb-atlas-api","mongodb-atlas-cloud","mongodb-atlas-data-api","mongodb-cloud-api","mongodb-data-api","mongodb-driver","mongodb-serverless"],"latest_commit_sha":null,"homepage":"https://www.mongodb.com/docs/atlas/api/data-api/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/surmon-china.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-28T18:58:05.000Z","updated_at":"2024-07-06T19:11:03.000Z","dependencies_parsed_at":"2022-08-24T17:10:34.139Z","dependency_job_id":null,"html_url":"https://github.com/surmon-china/mongodb-data-api","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surmon-china%2Fmongodb-data-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surmon-china%2Fmongodb-data-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surmon-china%2Fmongodb-data-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surmon-china%2Fmongodb-data-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/surmon-china","download_url":"https://codeload.github.com/surmon-china/mongodb-data-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243822283,"owners_count":20353499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mongodb","mongodb-api","mongodb-atlas","mongodb-atlas-api","mongodb-atlas-cloud","mongodb-atlas-data-api","mongodb-cloud-api","mongodb-data-api","mongodb-driver","mongodb-serverless"],"created_at":"2024-10-11T04:26:55.699Z","updated_at":"2025-03-16T16:31:01.121Z","avatar_url":"https://github.com/surmon-china.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"/logo.png\" height=\"120px\" /\u003e\n\u003c/p\u003e\n\n# mongodb-data-api\n\n[![GitHub stars](https://img.shields.io/github/stars/surmon-china/mongodb-data-api.svg?style=for-the-badge)](https://github.com/surmon-china/mongodb-data-api/stargazers)\n\u0026nbsp;\n[![npm](https://img.shields.io/npm/v/mongodb-data-api?color=c7343a\u0026label=npm\u0026style=for-the-badge)](https://www.npmjs.com/package/mongodb-data-api)\n\u0026nbsp;\n[![Test Codecov](https://img.shields.io/codecov/c/github/surmon-china/mongodb-data-api?style=for-the-badge)](https://codecov.io/gh/surmon-china/mongodb-data-api)\n\u0026nbsp;\n[![GitHub license](https://img.shields.io/github/license/surmon-china/mongodb-data-api.svg?style=for-the-badge)](/LICENSE)\n\nMongoDB Atlas [Data API](https://www.mongodb.com/docs/atlas/api/data-api/) SDK for Node.js.\n\n---\n\n### Installation\n\n```bash\nnpm install mongodb-data-api --save\n```\n\nor\n\n```bash\nyarn add mongodb-data-api\n```\n\n### Usage\n\n#### Init\n\n```ts\nimport { createMongoDBDataAPI } from 'mongodb-data-api'\n\n// init by URL Endpoint\nconst api = createMongoDBDataAPI({\n  apiKey: '\u003cyour_mongodb_api_key\u003e',\n  urlEndpoint: 'https://data.mongodb-api.com/app/\u003cyour_mongodb_app_id\u003e/endpoint/data/v1'\n})\n\n// or init by app ID\nconst api = createMongoDBDataAPI({\n  apiKey: '\u003cyour_mongodb_api_key\u003e',\n  appId: '\u003cyour_mongodb_app_id\u003e'\n})\n\n// specific region and cloud of app\nconst api = createMongoDBDataAPI({\n  apiKey: '\u003cyour_mongodb_api_key\u003e',\n  appId: '\u003cyour_mongodb_app_id\u003e',\n  region: '\u003cyour_mongodb_app_region\u003e', // e.g. us-east-1\n  cloud: '\u003cyour_mongodb_app_cloud\u003e' // e.g. aws\n})\n```\n\n#### Actions\n\nSee [MongoDB Data API Resources](https://www.mongodb.com/docs/atlas/api/data-api-resources/).\n\n- [`API.findOne`](https://www.mongodb.com/docs/atlas/api/data-api-resources/#find-a-single-document)\n- [`API.find`](https://www.mongodb.com/docs/atlas/api/data-api-resources/#find-multiple-documents)\n- [`API.insertOne`](https://www.mongodb.com/docs/atlas/api/data-api-resources/#insert-a-single-document)\n- [`API.insertMany`](https://www.mongodb.com/docs/atlas/api/data-api-resources/#insert-multiple-documents)\n- [`API.updateOne`](https://www.mongodb.com/docs/atlas/api/data-api-resources/#update-a-single-document)\n- [`API.updateMany`](https://www.mongodb.com/docs/atlas/api/data-api-resources/#update-multiple-documents)\n- [`API.replaceOne`](https://www.mongodb.com/docs/atlas/api/data-api-resources/#replace-a-single-document)\n- [`API.deleteOne`](https://www.mongodb.com/docs/atlas/api/data-api-resources/#delete-a-single-document)\n- [`API.deleteMany`](https://www.mongodb.com/docs/atlas/api/data-api-resources/#delete-multiple-documents)\n- [`API.aggregate`](https://www.mongodb.com/docs/atlas/api/data-api-resources/#run-an-aggregation-pipeline)\n\n#### Action examples\n\n1. find a single document\n\n```ts\napi\n  .findOne({\n    dataSource: '\u003ctarget_cluster_name\u003e',\n    database: '\u003ctarget_database_name\u003e',\n    collection: '\u003ctarget_collection_name\u003e',\n    filter: { name: 'Surmon' }\n  })\n  .then((result) =\u003e {\n    console.log(result.document)\n  })\n```\n\n2. insert a single document\n\n```ts\napi\n  .insertOne({\n    dataSource: '\u003ctarget_cluster_name\u003e',\n    database: '\u003ctarget_database_name\u003e',\n    collection: '\u003ctarget_collection_name\u003e',\n    document: {\n      name: 'Surmon',\n      age: 19\n    }\n  })\n  .then((result) =\u003e {\n    console.log(result.insertedId)\n  })\n```\n\n3. run an aggregation pipeline\n\n```ts\napi\n  .aggregate({\n    dataSource: '\u003ctarget_cluster_name\u003e',\n    database: '\u003ctarget_database_name\u003e',\n    collection: '\u003ctarget_collection_name\u003e',\n    pipeline: [\n      { $match: { status: 'urgent' } },\n      { $group: { _id: '$productName', sumQuantity: { $sum: '$quantity' } } }\n    ]\n  })\n  .then((result) =\u003e {\n    console.log(result.documents)\n  })\n```\n\n#### Method chaining\n\n```ts\n// select cluster\nconst clusterA = api.$cluster('a')\n// select database\nconst databaseB = clusterA.$database('b')\n// select collection\nconst collectionC = databaseB.$collection\u003cC\u003e('c')\n// data actions\nconst data = await collectionC.findOne({\n  filter: {\n    /*...*/\n  }\n})\nconst result = await collectionC.insertOne({\n  document: {\n    /*...*/\n  }\n})\n\n// -------------\n\n// chaining is equivalent to the api call\napi.$cluster('a').$database('b').$collection\u003cC\u003e('c').findOne({ filter: {} })\n// the same as\napi.findOne\u003cC\u003e({\n  dataSource: 'a',\n  database: 'b',\n  collection: 'c',\n  filter: {}\n})\n```\n\n#### Specific Action\n\nYou can specify the action request to prevent this package from lagging relative to the official one.\n\n```ts\napi.$$action('findOne', {\n  dataSource: '...',\n  database: '...',\n  collection: '...',\n  filter: {}\n})\n```\n\n#### Original Class\n\nYou can use the original Class to implement some special requirements.\n\n```ts\nimport { MongoDBDataAPI } from 'mongodb-data-api'\n\nconst customerCollection = new MongoDBDataAPI\u003cCustomerDocument\u003e(\n  {\n    apiKey: '\u003cyour_mongodb_api_key\u003e',\n    appId: '\u003cyour_mongodb_app_id\u003e'\n  },\n  {\n    dataSource: '\u003ctarget_cluster_name\u003e',\n    database: '\u003ctarget_database_name\u003e',\n    collection: '\u003ctarget_collection_name\u003e'\n  }\n)\n\nconst customer = await customerCollection.findOne({ ... })\n```\n\n### Development\n\n```bash\n# install dependencies\nyarn\n\n# lint\nyarn lint\n\n# test\nyarn test\n\n# build\nyarn build\n```\n\n### Changelog\n\nDetailed changes for each release are documented in the [release notes](/CHANGELOG.md).\n\n### License\n\n[MIT](/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurmon-china%2Fmongodb-data-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsurmon-china%2Fmongodb-data-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurmon-china%2Fmongodb-data-api/lists"}