{"id":14984935,"url":"https://github.com/masfana/masfana-mongodb-api-sdk","last_synced_at":"2025-04-10T22:54:23.251Z","repository":{"id":255445842,"uuid":"852432739","full_name":"MasFana/masfana-mongodb-api-sdk","owner":"MasFana","description":"A TypeScript SDK for MongoDB Atlas Data API with query operator IntelliSense.","archived":false,"fork":false,"pushed_at":"2024-09-08T13:06:36.000Z","size":11,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T22:54:17.681Z","etag":null,"topics":["bun","cloudflare","cloudflare-workers","deno","hono","mongodb","nodejs","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/masfana-mongodb-api-sdk","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/MasFana.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-04T19:47:14.000Z","updated_at":"2024-11-25T23:21:37.000Z","dependencies_parsed_at":"2024-11-13T16:53:56.420Z","dependency_job_id":"2cb0c04c-48cf-4412-b593-95b937abd2a2","html_url":"https://github.com/MasFana/masfana-mongodb-api-sdk","commit_stats":{"total_commits":7,"total_committers":2,"mean_commits":3.5,"dds":0.1428571428571429,"last_synced_commit":"6c21adeffe6a9eaea2a07a7853855bd45b54a704"},"previous_names":["masfana/masfana-mongodb-api-sdk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasFana%2Fmasfana-mongodb-api-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasFana%2Fmasfana-mongodb-api-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasFana%2Fmasfana-mongodb-api-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasFana%2Fmasfana-mongodb-api-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MasFana","download_url":"https://codeload.github.com/MasFana/masfana-mongodb-api-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248312172,"owners_count":21082638,"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":["bun","cloudflare","cloudflare-workers","deno","hono","mongodb","nodejs","typescript"],"created_at":"2024-09-24T14:09:53.510Z","updated_at":"2025-04-10T22:54:23.226Z","avatar_url":"https://github.com/MasFana.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n  \n\n# MasFana MongoDB Data API SDK\n\n  \n\n  \n\nA TypeScript SDK for interacting with MongoDB Atlas Data API with full IntelliSense support for query operators.\n\n  \n\n  \n\nAlternative for Native MongoDB SDK\n\n  \n\n## Installation\n\n  \n\n  \n\n```bash\n\nnpm  install  masfana-mongodb-api-sdk\n\n```\n\n### Requirements\n\n  \n\n-  **Node.js** version 14 or higher.\n\n- A MongoDB Atlas account with Data API enabled. [Learn how to set up MongoDB Atlas Data API](https://www.mongodb.com/docs/atlas/app-services/data-api/).\n\n- TypeScript project setup (if you're using TypeScript).\n\n  \n### Example\n- [Auth With Hono](https://github.com/MasFana/masfana-mongodb-example-auth)\nSimple authentication using Hono and Cloudflare Worker\n\n## Getting Started\n\n  \n\n### Step 1: Setting Up MongoDB Atlas Data API\n\n  \n\nTo use this SDK, you need to enable the **Data API** in your MongoDB Atlas cluster. Here’s a brief guide:\n\n  \n\n1. Log in to your [MongoDB Atlas account](https://cloud.mongodb.com/).\n\n2. Go to **App Services** and click **Create new application**.\n\n3. Enable the **Data API** for your application.\n\n4. Copy the **App ID** and **API Key** from the Data API section.\n\n  \n\n### Step 2: Environment Configuration\n\n  \n\nTo use the SDK, you'll need to configure the MongoDB environment variables in your project. Create a `.env` file in the root of your project:\n\n```bash\n\ntouch  .env\n\n```\n\n### Step 3: Setting Up Your TypeScript Project\n\n  \n\nIf you're using TypeScript, ensure that you have a basic **tsconfig.json** set up:\n\n  \n\n```json\n\n{\n\n\"compilerOptions\": {\n\n\"target\": \"ES6\",\n\n\"module\": \"CommonJS\",\n\n\"outDir\": \"./dist\",\n\n\"strict\": true,\n\n\"esModuleInterop\": true\n\n},\n\n\"include\": [\"src/**/*.ts\"],\n\n\"exclude\": [\"node_modules\"]\n\n}\n\n```\n\nCreate a `src/index.ts` file where you'll write your code.\n\n  \n\n### Step 4: Using the SDK\n\n  \n\n1. Import the SDK and define the types for your MongoDB documents.\n\n2. Initialize the MongoDB API with environment variables.\n\n3. Use the provided CRUD methods (`findOne`, `find`, `insertOne`, `updateOne`, `deleteOne`, `aggregate`).\n\n  \n\n#### Example\n\n```typescript\n\nimport { MongoDBAPI } from  \"mongodb-data-api-sdk\";\n\nimport  *  as  dotenv  from  \"dotenv\";\n\ndotenv.config();\n\n  \n\n// Define the type of the documents in your MongoDB collection\n\ntype  Task = {\n\ntext: string;\n\nstatus: string;\n\ncompletedAt?: Date;\n\n};\n\n  \n\n// Initialize the MongoDB API SDK with environment variables\n\nconst  env = {\n\nMONGO_API_URL:  process.env.MONGO_API_URL!,\n\nMONGO_API_KEY:  process.env.MONGO_API_KEY!,\n\nDATABASE:  process.env.DATABASE!,\n\nCOLLECTION:  process.env.COLLECTION!,\n\nDATA_SOURCE:  process.env.DATA_SOURCE!\n\n};\n\n  \n\nconst  mongoAPI = new  MongoDBAPI\u003cTask\u003e(env);\n\n  \n\n// Example usage of the SDK\n\nasync  function  run() {\n\ntry {\n\n// Find a single document where the task status is \"complete\"\n\nconst  task = await  mongoAPI.findOne({ status: { $eq:  \"complete\" } });\n\nconsole.log(\"Found task:\", task);\n\n  \n\n// Insert a new task\n\nconst  insertResult = await  mongoAPI.insertOne({ text:  \"Clean the kitchen\", status:  \"open\" });\n\nconsole.log(\"Inserted task with ID:\", insertResult.insertedId);\n\n  \n\n// Find all tasks with status \"open\", sort by `completedAt` field, and return only `text` and `status` fields\n\nconst  tasks = await  mongoAPI.find(\n\n{ status: { $eq:  \"open\" } },\n\n{ text:  1, status:  1 },\n\n{ completedAt: -1 },\n\n10  // Limit to 10 results\n\n);\n\nconsole.log(\"Found tasks:\", tasks);\n\n  \n\n// Update a task to mark it as \"complete\"\n\nconst  updateResult = await  mongoAPI.updateOne({ text:  \"Clean the kitchen\" }, { status:  \"complete\" });\n\nconsole.log(\"Updated task:\", updateResult);\n\n  \n\n// Delete a task\n\nconst  deleteResult = await  mongoAPI.deleteOne({ text:  \"Clean the kitchen\" });\n\nconsole.log(\"Deleted task:\", deleteResult.deletedCount);\n\n  \n\n} catch (error) {\n\nconsole.error(\"Error:\", error);\n\n}\n\n}\n\n  \n\nrun();\n\n```\n\n### Step 5: Running Your Application\n\n  \n\nTo run the example code, ensure you’ve set up your TypeScript project and compiled your code:\n\n  \n\n```bash\n\n# Install dependencies\n\nnpm  install\n\n  \n\n# Compile TypeScript code\n\nnpm  run  build\n\n  \n\n# Run the compiled JavaScript code\n\nnode  dist/index.js\n\n  \n\n### CRUD Operations Overview\n\n```\n\n1.  **Find One Document**\n\n```typescript\n\nconst  task = await  mongoAPI.findOne({ status: { $eq:  \"complete\" } });\n\n```\n\n  \n\n2.  **Find Many Documents**\n\n```typescript\n\nconst  tasks = await  mongoAPI.find(\n\n{ status: { $eq:  \"open\" } }, // Filter\n\n{ text:  1, status:  1 }, // Projection (fields to include)\n\n{ completedAt: -1 }, // Sort by completedAt descending\n\n10  // Limit results to 10\n\n);\n\n```\n\n3.  **Insert One Document**\n\n```typescript\n\nconst  insertResult = await  mongoAPI.insertOne({ text:  \"Buy groceries\", status:  \"open\" });\n\n```\n\n  \n\n4.  **Update One Document**\n\n```typescript\n\nconst  updateResult = await  mongoAPI.updateOne({ text:  \"Buy groceries\" }, { status:  \"complete\" });\n\n```\n\n5.  **Delete One Document**\n\n```typescript\n\nconst  deleteResult = await  mongoAPI.deleteOne({ text:  \"Buy groceries\" });\n\n```\n\n  \n\n### MongoDB Query Operators Supported\n\n  \n\nHere are some common MongoDB query operators supported by this SDK:\n\n  \n\n-  **`$eq`**: Matches values that are equal to a specified value.\n\n-  **`$ne`**: Matches values that are not equal to a specified value.\n\n-  **`$gt`**: Matches values that are greater than a specified value.\n\n-  **`$gte`**: Matches values that are greater than or equal to a specified value.\n\n-  **`$lt`**: Matches values that are less than a specified value.\n\n-  **`$lte`**: Matches values that are less than or equal to a specified value.\n\n-  **`$in`**: Matches any of the values specified in an array.\n\n-  **`$nin`**: Matches none of the values specified in an array.\n\n-  **`$exists`**: Matches documents where the field exists.\n\n  \n\n### TypeScript Support\n\n  \n\nThe SDK is fully type-safe, so your code will have **IntelliSense** support for query operators and MongoDB operations. Here's an example of how IntelliSense helps you with MongoDB operators like `$eq`, `$gt`, and more:\n\n```typescript\n\nconst  filter = {\n\nstatus: { $eq:  \"complete\" },\n\ncompletedAt: { $gt:  new  Date(\"2023-01-01\") }\n\n};\n\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasfana%2Fmasfana-mongodb-api-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmasfana%2Fmasfana-mongodb-api-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasfana%2Fmasfana-mongodb-api-sdk/lists"}