{"id":14975642,"url":"https://github.com/vikpe/mongoose-mpath","last_synced_at":"2025-04-09T17:21:31.753Z","repository":{"id":25297984,"uuid":"103674850","full_name":"vikpe/mongoose-mpath","owner":"vikpe","description":"Mongoose plugin for tree hierarchy using the materialized path pattern.","archived":false,"fork":false,"pushed_at":"2024-08-30T11:04:08.000Z","size":2337,"stargazers_count":66,"open_issues_count":5,"forks_count":16,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-02T07:59:28.986Z","etag":null,"topics":["hierarchical-data","materialized-path","mongodb","mongoose","mongoose-plugin","node"],"latest_commit_sha":null,"homepage":"https://docs.mongodb.com/manual/tutorial/model-tree-structures-with-materialized-paths/","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/vikpe.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-15T15:50:11.000Z","updated_at":"2025-02-03T21:58:23.000Z","dependencies_parsed_at":"2023-02-18T23:20:19.611Z","dependency_job_id":"4d64f5bf-8445-4653-8906-e7fb6dbac33a","html_url":"https://github.com/vikpe/mongoose-mpath","commit_stats":{"total_commits":334,"total_committers":6,"mean_commits":"55.666666666666664","dds":0.08083832335329344,"last_synced_commit":"6ecc70397aa8d7e5bf06adcf7d4c239dc3258d8c"},"previous_names":[],"tags_count":75,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikpe%2Fmongoose-mpath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikpe%2Fmongoose-mpath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikpe%2Fmongoose-mpath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vikpe%2Fmongoose-mpath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vikpe","download_url":"https://codeload.github.com/vikpe/mongoose-mpath/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248075009,"owners_count":21043510,"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":["hierarchical-data","materialized-path","mongodb","mongoose","mongoose-plugin","node"],"created_at":"2024-09-24T13:52:19.571Z","updated_at":"2025-04-09T17:21:31.735Z","avatar_url":"https://github.com/vikpe.png","language":"JavaScript","funding_links":[],"categories":["🌳 Tree \u0026 Hierarchical Data"],"sub_categories":[],"readme":"# Mongoose Materialized Path [![npm version](https://badge.fury.io/js/mongoose-mpath.svg)](https://www.npmjs.com/package/mongoose-mpath) [![test](https://github.com/vikpe/mongoose-mpath/workflows/test/badge.svg)](https://github.com/vikpe/mongoose-mpath/actions?query=workflow%3Atest) [![codecov](https://codecov.io/gh/vikpe/mongoose-mpath/branch/master/graph/badge.svg)](https://codecov.io/gh/vikpe/mongoose-mpath)\n\u003e Mongoose plugin for tree hierarchy using the [materialized path pattern](https://docs.mongodb.com/manual/tutorial/model-tree-structures-with-materialized-paths/).\n\n## Requirements\n\n* Node.js \u003e= 14\n* MongoDB \u003e= 4\n* Mongoose \u003e= 6\n\n## Installation\n```shell\nnpm install mongoose-mpath\n```\n\n## Setup\n\u003e **Important note**\n\u003e\n\u003e This plugins adds `parent`, `path` and `children` fields to the schema. You should not define them in the schema which the plugin is enabled on.\n\n**Semantics**\n```javascript\nMySchema.plugin(MpathPlugin, [PLUGIN OPTIONS]);\n```\n\n**Plugin options**\n\n```javascript\nconst options = {\n  modelName:     'MyModel',        // Name of model\n  pathSeparator: '#',              // (optional) String used to separate ids in path\n  onDelete:      'REPARENT',       // (optional) 'REPARENT' or 'DELETE'\n  idType:        Schema.ObjectId   // (optional) Type used for model id\n}\n```\n\n**Example setup**\n```javascript\nimport Mongoose from 'mongoose';\nimport MpathPlugin from 'mongoose-mpath';\n\nconst LocationSchema = new Mongoose.Schema({name: String});\nLocationSchema.plugin(MpathPlugin, {modelName: 'Location'});\n\nconst LocationModel = Mongoose.model('Location', LocationSchema);\n\nconst europe = new LocationModel({name: 'europe'});\nconst sweden = new LocationModel({name: 'sweden', parent: europe});\nconst stockholm = new LocationModel({name: 'stockholm', parent: sweden});\n\nawait europe.save();\nawait sweden.save();\nawait stockholm.save();\n```\n\nAt this point in mongoDB you will have documents similar to\n```\n{\n  \"_id\" : ObjectId(\"50136e40c78c4b9403000001\"),\n  \"name\" : \"europe\",\n  \"path\" : \"50136e40c78c4b9403000001\"\n}\n{\n  \"_id\" : ObjectId(\"50136e40c78c4b9403000002\"),\n  \"name\" : \"sweden\",\n  \"parent\" : ObjectId(\"50136e40c78c4b9403000001\"),\n  \"path\" : \"50136e40c78c4b9403000001#50136e40c78c4b9403000002\"\n}\n{\n  \"_id\" : ObjectId(\"50136e40c78c4b9403000003\"),\n  \"name\" : \"stockholm\",\n  \"parent\" : ObjectId(\"50136e40c78c4b9403000002\"),\n  \"path\" : \"50136e40c78c4b9403000001#50136e40c78c4b9403000002#50136e40c78c4b9403000003\"\n}\n```\n\nThe `path` is used for recursive methods and is kept up to date by the plugin if the `parent` is changed.\n\n## API\n* [`getAncestors()`](#getancestors)\n* [`getAllChildren()`](#getallchildren)\n* [`getImmediateChildren()`](#getimmediatechildren)\n* [`getChildrenTree()`](#getchildrentree)\n* [`getParent()`](#getparent)\n* [`level`](#level)\n\nAll examples below are based on the following document hierarchy:\n```\nafrica\neurope\n - norway\n - sweden\n   -- stockholm\n     --- skansen\n```\n\n### getAncestors()\nReturns ancestors of a document. Returns a promise.\n\n**Signature**\n```\ndocument.getAncestors(conditions, [fields], [options])\n```\n\n**Arguments**\n* See offical docs on [model.find()](http://mongoosejs.com/docs/api.html#model_Model.find) for description of arguments.\n\n**Example**\n```javascript\nconst ancestors = await stockholm.getAncestors({});    // (Array) [europe, sweden]\n```\n\n### getAllChildren()\nReturns all children of a document. Returns a promise.\n\n**Signature**\n```\ndocument.getAllChildren(conditions, [fields], [options])\n```\n\n**Arguments**\n* See offical docs on [model.find()](http://mongoosejs.com/docs/api.html#model_Model.find) for description of arguments.\n\n**Example**\n```javascript\nconst children = await sweden.getAllChildren({});       // (Array) [stockholm, skansen]\nconst children = await stockholm.getAllChildren({});    // (Array) [skansen]\n```\n\n### getChildrenTree()\nReturns all children of a document formatted as a tree hierarchy. Returns a promise.\n\n**Signature**\n```\ndocument.getChildrenTree([args])    // as method\nmodel.getChildrenTree([args])       // as static\n```\n\n**Arguments**\n* (Object) `args`\n    ```\n    {\n        (Object) filters: {},            // mongoose query filters\n        (Object|String) fields: null,    // mongoose query fields (null equals all fields)\n        (Object) options: {},            // mongoose query options\n        (String) populate: '',           // string to passed to populate()\n        (int) minLevel: 1,               // minimum level to include\n        (int) maxLevel: 9999,            // maximum level to include\n        (Mongoose.document) rootDoc      // mongoose document\n    }\n    ```\n\n    Example\n    ```javascript\n    const args = {\n      filters: {author: 'vikpe'},\n      fields: '_id name',\n      options: {sort: 'name'},\n      populate: 'repos',\n      minLevel: 2,\n      maxLevel: 4\n    }\n    ```\n\n**Example**\n```javascript\nconst tree = await sweden.getChildrenTree({});\n// tree is an array similar to\n/*\n[\n  {\n    'name': 'sthlm',\n    'children': [\n      {\n        'name': 'skansen',\n        'children': [],          \n      }\n    ],\n  }\n]\n*/\n```\n\n### getImmediateChildren()\nReturns immediate children of a document. Returns a promise.\n\n**Signature**\n```\ndocument.getImmediateChildren(conditions, [fields], [options])\n```\n\n**Arguments**\n* See offical docs on [model.find()](http://mongoosejs.com/docs/api.html#model_Model.find) for description of arguments.\n\n**Example**\n```javascript\nconst children = await europe.getImmediateChildren({});    // (Array) [norway, sweden]\nconst children = await sweden.getImmediateChildren({});    // (Array) [stockholm]\n```\n\n### getParent()\nReturns parent of a document.\n\n**Signature**\n```\ndocument.getParent([fields], [options])\n```\n\n**Arguments**\n* See offical docs on [model.find()](http://mongoosejs.com/docs/api.html#model_Model.find) for description of arguments.\n\n**Example**\n```javascript\nconst parent = await sweden.getParent();       // (Object) europe\nconst parent = await stockholm.getParent();    // (Object) sweden\n```\n\n### level\nA Virtual field that equals to the level of a document in the hierarchy.\n\n**Signature**\n```\n(Number) document.level\n```\n\n**Example**\n```\nafrica.level    // 1\nsweden.level    // 2\nskansen.level   // 4\n```\n\n### children\nPlaceholder variable populated when calling `.getChildrenTree()`.\n\n\n## More examples\n\nGiven the following document hierarchy:\n```\nafrica\neurope\n - norway\n - sweden\n   -- stockholm\n     --- skansen\n```\n\n\n**getAncestors()**\n```\neurope.getAncestors()       // (Array) []\nstockholm.getAncestors()    // (Array) [europe, sweden]\nskansen.getAncestors()      // (Array) [europe, sweden, stockholm]\n```\n\n**getAllChildren()**\n```\neurope.getAllChildren()       // (Array) [sweden, stockholm, skansen]\nstockholm.getAllChildren()    // (Array) [skansen]\nskansen.getAllChildren()      // (Array) []\n```\n\n**getImmediateChildren()**\n```\neurope.getImmediateChildren()       // (Array) [norway, sweden]\nstockholm.getImmediateChildren()    // (Array) [skansen]\nskansen.getImmediateChildren()      // (Array) []\n```\n\n**getChildrenTree()**\n```\neurope.getChildrenTree()\n\n/*\n[\n  {\n    'name': 'norway',\n    'children': []\n  },\n  {\n    'name': 'sweden',\n    'children': [\n        {\n          'name': 'sthlm',\n          'children': [\n            {\n              'name': 'skansen',\n              'children': []          \n            }\n          ],\n        }\n    ]\n   }  \n]\n*/\n\n\nsweden.getChildrenTree()\n\n/*\n[\n  {\n    'name': 'sthlm',\n    'children': [\n      {\n        'name': 'skansen',\n        'children': [],          \n      }\n    ],\n  }\n]\n*/\n```\n\n**getParent()**\n```\neurope.getParent()       // (null)\nstockholm.getParent()    // (Object) sweden\nskansen.getParent()      // (Object) stockholm\n```\n\n**level**\n```\nafrica.level       // (Number) 1\neurope.level       // (Number) 1\nnorway.level       // (Number) 2\nsweden.level       // (Number) 2\nstockholm.level    // (Number) 3\nskansen.level      // (Number) 4\n```\n\n## Development\nFeedback and pull requests are most welcome!\n\n1. `npm install mongoose-mpath`\n2. [Install MongoDB (Community Server)](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-ubuntu/#install-mongodb-community-edition).\n3. Start MongoDB: `mongod`\n3. Run tests: `npm run test`\n\n## Credits\nThis plugin is inspired by `mongoose-path-tree` by [swayf](https://github.com/swayf).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvikpe%2Fmongoose-mpath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvikpe%2Fmongoose-mpath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvikpe%2Fmongoose-mpath/lists"}