{"id":14956803,"url":"https://github.com/cdimascio/uuid-mongodb","last_synced_at":"2025-05-16T06:04:08.575Z","repository":{"id":32763169,"uuid":"141922768","full_name":"cdimascio/uuid-mongodb","owner":"cdimascio","description":"📇 Generates and parses MongoDB BSON UUIDs","archived":false,"fork":false,"pushed_at":"2024-12-03T04:58:55.000Z","size":553,"stargazers_count":101,"open_issues_count":13,"forks_count":17,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-09T13:50:32.188Z","etag":null,"topics":["binary","bson","hacktoberfest","mongo","mongodb","mongoose","nodejs","uuid"],"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/cdimascio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGE_HISTORY.md","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":"2018-07-22T19:00:59.000Z","updated_at":"2024-12-28T03:24:35.000Z","dependencies_parsed_at":"2024-01-27T17:25:17.909Z","dependency_job_id":"6b17e335-ba1e-4e87-9c02-0d6472d3495f","html_url":"https://github.com/cdimascio/uuid-mongodb","commit_stats":{"total_commits":208,"total_committers":15,"mean_commits":"13.866666666666667","dds":0.7692307692307692,"last_synced_commit":"413b449e29c07c37b083f9545ce073bb2fc5055c"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fuuid-mongodb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fuuid-mongodb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fuuid-mongodb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdimascio%2Fuuid-mongodb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cdimascio","download_url":"https://codeload.github.com/cdimascio/uuid-mongodb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254104104,"owners_count":22015413,"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":["binary","bson","hacktoberfest","mongo","mongodb","mongoose","nodejs","uuid"],"created_at":"2024-09-24T13:13:33.669Z","updated_at":"2025-05-16T06:04:08.516Z","avatar_url":"https://github.com/cdimascio.png","language":"JavaScript","funding_links":["https://www.buymeacoffee.com/m97tA5c"],"categories":[],"sub_categories":[],"readme":"# uuid-mongodb\n![](https://travis-ci.org/cdimascio/uuid-mongodb.svg?branch=master) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/a42f61ffc97b4bcbbca184ab838092c8)](https://www.codacy.com/app/cdimascio/uuid-mongodb?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=cdimascio/uuid-mongodb\u0026amp;utm_campaign=Badge_Grade) ![](https://img.shields.io/npm/v/uuid-mongodb.svg) ![](https://img.shields.io/npm/dm/uuid-mongodb.svg) [![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors)\n ![](https://img.shields.io/badge/license-MIT-blue.svg)\n\nGenerates and parses [BSON UUIDs](https://docs.mongodb.com/manual/reference/method/UUID/) for use with MongoDB. BSON UUIDs provide better performance than their string counterparts.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"400\" src=\"https://raw.githubusercontent.com/cdimascio/uuid-mongodb/master/assets/uuid-mongodb-lr-logo.png?raw=truef\"/\u003e\n\u003c/p\u003e\n\nInspired by [@srcagency's](https://github.com/srcagency) [mongo-uuid](https://github.com/srcagency/mongo-uuid)\n\n## Install\n\n```shell\nnpm install uuid-mongodb\n```\n\n## Usage\n\n```javascript\nconst MUUID = require('uuid-mongodb');\n\n// Create a v1 binary UUID\nconst mUUID1 = MUUID.v1();\n\n// Create a v4 binary UUID\nconst mUUID4 = MUUID.v4();\n\n// Print a string representation of a binary UUID\nmUUID1.toString()\n\n// Create a binary UUID from a valid uuid string\nconst mUUID2 = MUUID.from('393967e0-8de1-11e8-9eb6-529269fb1459')\n\n// Create a binary UUID from a MongoDb Binary\n// This is useful to get MUUIDs helpful toString() method\nconst mUUID3 = MUUID.from(/** MongoDb Binary of SUBTYPE_UUID */)\n```\n\n## Formatting\n\nUUIDs may be formatted using the following options:\n\nFormat | Description | Example\n-- | -- | --\nN | 32 digits | `00000000000000000000000000000000`\nD | 32 digits separated by hyphens | `00000000-0000-0000-0000-000000000000`\nB | 32 digits separated by hyphens, enclosed in braces | `{00000000-0000-0000-0000-000000000000}`\nP | 32 digits separated by hyphens, enclosed in parentheses | `(00000000-0000-0000-0000-000000000000)`\n\n**example:**\n```javascript\nconst mUUID4 = MUUID.v4();\nmUUID1.toString(); // equivalent to `D` separated by hyphens\nmUUID1.toString('P'); // enclosed in parens, separated by hypens\nmUUID1.toString('B'); // enclosed in braces, separated by hyphens\nmUUID1.toString('N'); // 32 digits\n```\n\n## Modes\n\nuuid-mongodb offers two modes:\n\n- **canonical** (default) - A string format that emphasizes type preservation at the expense of readability and interoperability.\n- **relaxed** - A string format that emphasizes readability and interoperability at the expense of type preservation.\n\nThe mode is set **globally** as such:\n\n```javascript\nconst mUUID = MUUID.mode('relaxed'); // use relaxed mode\n```\n\nMode _**only**_ impacts how `JSON.stringify(...)` represents a UUID:\n\ne.g. `JSON.stringy(mUUID.v1())` outputs the following:\n\n```javascript\n\"DEol4JenEeqVKusA+dzMMA==\" // when in 'canonical' mode\n\"1ac34980-97a7-11ea-8bab-b5327b548666\" // when in 'relaxed' mode\n```\n\n## Examples\n\n**Query using binary UUIDs**\n\n```javascript\nconst uuid = MUUID.from('393967e0-8de1-11e8-9eb6-529269fb1459');\nreturn collection.then(c =\u003e\n  c.findOne({\n    _id: uuid,\n  })\n);\n```\n\n**Work with binary UUIDs returned in query results**\n\n```javascript\nreturn collection\n  .then(c =\u003e c.findOne({ _id: uuid }))\n  .then(doc =\u003e {\n    const uuid = MUUID.from(doc._id).toString();\n    // do stuff\n  });\n```\n\n## Examples (with source code)\n\n#### Native Node MongoDB Driver example\n\n- [examples/ex1-mongodb.js](examples/ex1-mongodb.js)\n\n\t**snippet:**\n\t\n\t```javascript\n\tconst insertResult = await collection.insertOne({\n\t  _id: MUUID.v1(),\n\t  name: 'carmine',\n\t});\n\t```\n\n#### Mongoose example\n\n- [examples/ex2-mongoose.js](examples/ex2-mongoose.js)\n\n\t**snippet:**\n\t\n\t```javascript\n\tconst kittySchema = new mongoose.Schema({\n\t  _id: {\n\t    type: 'object',\n\t    value: { type: 'Buffer' },\n\t    default: () =\u003e MUUID.v1(),\n\t  },\n\t  title: String,\n\t});\n\t```\n\n- [examples/ex3-mongoose.js](examples/ex3-mongoose.js)\n\n\t**snippet:**\n\t\n\t```javascript\n\t// Define a simple schema\n\tconst kittySchema = new mongoose.Schema({\n\t  _id: {\n\t    type: 'object',\n\t    value: { type: 'Buffer' },\n\t    default: () =\u003e MUUID.v1(),\n\t  },\n\t  title: String,\n\t});\n\t\n\t// no need for auto getter for _id will add a virtual later\n\tkittySchema.set('id', false);\n\t\n\t// virtual getter for custom _id\n\tkittySchema\n\t  .virtual('id')\n\t  .get(function() {\n\t    return MUUID.from(this._id).toString();\n\t  })\n\t  .set(function(val) {\n\t    this._id = MUUID.from(val);\n\t  });\n\t```\n\n- [examples/ex4-mongoose.js](examples/ex4-mongoose.js)\n\n```javascript\n    const uuid = MUUID.v4();\n\n    // save record and wait for it to commit\n    await new Data({ uuid }).save();\n\n    // retrieve the record\n    const result = await Data.findOne({ uuid });\n```\n\n## Notes\n\nCurrently supports [UUID v1 and v4](https://www.ietf.org/rfc/rfc4122.txt)\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore --\u003e\n\u003ctable\u003e\n \u003ctr\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/cdimascio\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/4706618?v=4\" width=\"100px;\" alt=\"Carmine DiMascio\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eCarmine DiMascio\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cdimascio/uuid-mongodb/commits?author=Carmine-DiMascio\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://glassechidna.com.au\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/482276?v=4\" width=\"100px;\" alt=\"Benjamin Dobell\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBenjamin Dobell\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cdimascio/uuid-mongodb/commits?author=Benjamin-Dobell\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/bytenik\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/441347?v=4\" width=\"100px;\" alt=\"David Pfeffer\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDavid Pfeffer\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/cdimascio/uuid-mongodb/commits?author=bytenik\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\t\u003c/tr\u003e\u003c/table\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n## License\n\n[MIT](./LICENSE)\n\n\u003ca href=\"https://www.buymeacoffee.com/m97tA5c\" target=\"_blank\"\u003e\u003cimg src=\"https://bmc-cdn.nyc3.digitaloceanspaces.com/BMC-button-images/custom_images/orange_img.png\" alt=\"Buy Me A Coffee\" style=\"height: auto !important;width: auto !important;\" \u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdimascio%2Fuuid-mongodb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdimascio%2Fuuid-mongodb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdimascio%2Fuuid-mongodb/lists"}