{"id":15664788,"url":"https://github.com/linusu/node-albatross","last_synced_at":"2025-05-05T23:54:07.095Z","repository":{"id":20394185,"uuid":"23670022","full_name":"LinusU/node-albatross","owner":"LinusU","description":"Best way to access MongoDB from Node.js","archived":false,"fork":false,"pushed_at":"2024-10-29T15:48:56.000Z","size":159,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-05T23:53:56.832Z","etag":null,"topics":["hacktoberfest","mongodb","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/LinusU.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":"2014-09-04T16:21:28.000Z","updated_at":"2024-10-29T15:49:01.000Z","dependencies_parsed_at":"2024-11-09T06:03:38.999Z","dependency_job_id":"10b87f0b-3697-44c7-93f0-f3e438c35fb5","html_url":"https://github.com/LinusU/node-albatross","commit_stats":{"total_commits":84,"total_committers":2,"mean_commits":42.0,"dds":"0.011904761904761862","last_synced_commit":"270ca671dfe2281a3ca124221f403713d9a61a6f"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LinusU%2Fnode-albatross","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LinusU%2Fnode-albatross/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LinusU%2Fnode-albatross/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LinusU%2Fnode-albatross/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LinusU","download_url":"https://codeload.github.com/LinusU/node-albatross/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252596396,"owners_count":21773844,"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":["hacktoberfest","mongodb","nodejs"],"created_at":"2024-10-03T13:44:09.604Z","updated_at":"2025-05-05T23:54:07.071Z","avatar_url":"https://github.com/LinusU.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![Albatross](/header.png?raw=true \"Albatross\")\n\nAlbatross is a small library that makes accessing MongoDB from Node.js a breeze. It's goal is to be a thin wrapper that enables you to forget about connection state and get right to accessing your data.\n\n## Installation\n\n```sh\nnpm install --save albatross\n```\n\n## Usage\n\n```js\nimport albatross from 'albatross'\nimport fs from 'node:fs'\n\nconst db = albatross('mongodb://localhost/test')\nconst user = db.collection('user')\n\nawait user.insert({ name: 'Linus', born: 1992 })\nawait user.insert({ name: 'Steve', born: 1955 })\n\nconst doc = await user.findOne({ born: 1992 })\nconsole.log('Hello ' + doc.name)\n//=\u003e Hello Linus\n\nconst grid = db.grid()\n\nconst input = fs.createReadStream('readme.md')\nconst opts = { filename: 'readme.md', contentType: 'text/plain' }\n\nconst id = await grid.upload(input, opts)\nconst result = await grid.download(id)\n\nresult.filename // 'readme.md'\nresult.contentType // 'text/plain'\n\nresult.stream.pipe(process.stdout)\n```\n\nYou can start querying the database right away, as soon as a connection is established it will start sending your commands to the server.\n\n## API\n\n### Module\n\nThe module default exports a single function to create a new `Albatross` instance. It also exports the BSON Binary API as named exports.\n\n#### `albatross(uri)`\n\nCreates a new instance of `Albatross` and connect to the specified uri.\n\n**Note:** Albatross creates the MongoDB client with `ignoreUndefined: true`, which means that `undefined` values will not be stored in the database. This is the new default in the BSON library, and is also how the standard `JSON.stringify` works.\n\n#### BSON Binary API\n\nThe following functions are exported from the module:\n\n```text\nBinary\nCode\nDecimal128\nDouble\nInt32\nLong\nMaxKey\nMinKey\nObjectId\nTimestamp\n```\n\n### Albatross\n\n#### `.collection(name)`\n\nReturns a new instance of Collection bound to the collection named `name`.\n\n#### `.grid([name])`\n\nReturns a new instance of Grid, optionally using the supplied `name` as the name of the root collection.\n\n#### `.id(strOrObjectId)`\n\nMakes sure that the given argument is an ObjectId.\n\n#### `.ping([timeout]): Promise\u003cvoid\u003e`\n\nSend the `ping` command to the server, to check that the connection is still intact.\n\nOptionally accepts a timeout in milliseconds.\n\n#### `.transaction(fn): Promise`\n\nRuns a provided function within a transaction, retrying either the commit operation or entire transaction as needed (and when the error permits) to better ensure that the transaction can complete successfully.\n\nExample:\n\n```js\nconst user = db.collection('user')\n\nconst result = await db.transaction(async (session) =\u003e {\n    await user.insert({ name: 'Linus', born: 1992 }, { session })\n    await user.insert({ name: 'Steve', born: 1955 }, { session })\n\n    return await user.findOne({ born: 1992 }, { session })\n})\n\nconsole.log('Hello ' + result.name)\n//=\u003e Hello Linus\n```\n\n#### `.close(): Promise\u003cvoid\u003e`\n\nCloses the connection to the server.\n\n### Collection\n\n#### `.id(strOrObjectId)`\n\nMakes sure that the given argument is an ObjectId.\n\n#### `findOne(query[, opts]): Promise\u003cobject\u003e`\n\nFind the first document that matches `query`.\n\n#### `find(query[, opts]): Promise\u003cobject[]\u003e`\n\nFind all records that matches `query`.\n\n#### `count(query[, opts]): Promise\u003cnumber\u003e`\n\nCount number of documents matching the query.\n\n#### `distinct(key[, query[, opts]]): Promise\u003cany[]\u003e`\n\nFinds a list of distinct values for the given key.\n\n*note: if you specify `opts` you also need to specify `query`*\n\n#### `exists(query): Promise\u003cboolean\u003e`\n\nCheck if at least one document is matching the query.\n\n#### `insert(docs[, opts]): Promise\u003cobject | object[]\u003e`\n\nInserts a single document or a an array of documents.\n\nThe Promise will resolve with the documents that was inserted. When called with an object instead of an array as the first argument, the Promise resolves with an object instead of an array as well.\n\n**Note:** Contrary to the standard MongoDB Node.js driver, this function will *not modify* any objects that are passed in. Instead, the returned documents from this function are what was saved in the database.\n\n### `findOneAndUpdate(filter, update[, opts]): Promise\u003cobject\u003e`\n\nFinds a document and updates it in one atomic operation.\n\nBy default, the document _before_ the update is returned. To return the document _after_ the update, pass `returnDocument: 'after'` in the options.\n\n#### `updateOne(filter, update[, opts]): Promise\u003cUpdateResult\u003e`\n\nUpdates a single document matching `filter`. Resolves with an object with the following properties:\n\n- `matched`: Number of documents that matched the query\n- `modified`: Number of documents that was modified\n\n#### `updateMany(filter, update[, opts]): Promise\u003cUpdateResult\u003e`\n\nUpdates multiple documents matching `filter`. Resolves with an object with the following properties:\n\n- `matched`: Number of documents that matched the query\n- `modified`: Number of documents that was modified\n\n#### `deleteOne(filter[, opts]): Promise\u003cnumber\u003e`\n\nDeletes a single document matching `filter`. Resolves with the number of documents deleted.\n\n#### `deleteMany(filter[, opts]): Promise\u003cnumber\u003e`\n\nDeletes multiple documents matching `filter`. Resolves with the number of documents deleted.\n\n#### `aggregate(pipeline[, opts]): Promise\u003cobject[]\u003e`\n\nExecutes an aggregation framework pipeline against the collection. Resolves with the aggregated objects.\n\n### Grid\n\n#### `id(strOrObjectId)`\n\nMakes sure that the given argument is an ObjectId.\n\n#### `upload(stream[, opts]): Promise\u003cFileInfo\u003e`\n\nStore the `stream` as a file in the grid store, `opts` is a object with the following properties. All options are optionally.\n\n- `filename`: The value of the `filename` key in the files doc\n- `chunkSizeBytes`: Overwrite this bucket's `chunkSizeBytes` for this file\n- `metadata`: Object to store in the file document's `metadata` field\n- `contentType`: String to store in the file document's `contentType` field\n- `aliases`: Array of strings to store in the file document's `aliases` field\n\nThe `FileInfo` object has the following properties:\n\n- `id`: The id of the file\n- `length`: The length of the file\n- `chunkSize`: The size of each chunk in bytes\n- `filename`: The value of the `filename` key in the files doc\n- `metadata`: An object with the metadata associated with the file\n- `contentType`: The value of the `contentType` key in the files doc\n\n#### `download(id): Promise\u003cFileInfo\u003e`\n\nGet the file with the specified `id` from the grid store. The Promise will resolve with an object with the following properties. If no file with the indicated `id` was found, the Promise will resolve to `null`.\n\n- `id`: The id of the file\n- `length`: The length of the file\n- `chunkSize`: The size of each chunk in bytes\n- `filename`: The value of the `filename` key in the files doc\n- `metadata`: An object with the metadata associated with the file\n- `contentType`: The value of the `contentType` key in the files doc\n- `stream`: The stream with the data that was inside the file\n\n#### `delete(id): Promise\u003cvoid\u003e`\n\nDelete the file with the specified `id` from the grid store.\n\n## In depth documentation\n\nFor more in depth documentation please see the [mongodb module](http://mongodb.github.io/node-mongodb-native/) which Albatross wraps, especially the [Collection object](http://mongodb.github.io/node-mongodb-native/api-generated/collection.html).\n\n## Contributing\n\nPull requests are always welcome, please make sure to add tests and run `mocha` before submitting.\n\nThe tests requiers a MongoDB server running at `localhost`.\n\n## License\n\nAlbatross is licensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinusu%2Fnode-albatross","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinusu%2Fnode-albatross","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinusu%2Fnode-albatross/lists"}