{"id":15555038,"url":"https://github.com/craftup/node-mongo-tenant","last_synced_at":"2025-04-09T18:18:01.691Z","repository":{"id":9943481,"uuid":"63863495","full_name":"craftup/node-mongo-tenant","owner":"craftup","description":"A multi-tenancy plugin for mongoose with tenant separation on document level. It's completely customizable, provides a neat interface for model-tenant-binding and can be disabled for running in single-tenant/on premis scenarios.","archived":false,"fork":false,"pushed_at":"2025-01-16T19:56:59.000Z","size":1099,"stargazers_count":72,"open_issues_count":16,"forks_count":25,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2025-04-09T18:17:58.531Z","etag":null,"topics":["mongo-tenant","mongoose","multi-tenancy-plugin","multitenancy","nodejs","tenant"],"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/craftup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2016-07-21T11:23:53.000Z","updated_at":"2024-11-30T11:40:13.000Z","dependencies_parsed_at":"2024-06-18T16:56:52.875Z","dependency_job_id":null,"html_url":"https://github.com/craftup/node-mongo-tenant","commit_stats":{"total_commits":158,"total_committers":11,"mean_commits":"14.363636363636363","dds":"0.25316455696202533","last_synced_commit":"2c0c2618e9c21f8730102eba75ef13706180e4a9"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/craftup%2Fnode-mongo-tenant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/craftup%2Fnode-mongo-tenant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/craftup%2Fnode-mongo-tenant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/craftup%2Fnode-mongo-tenant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/craftup","download_url":"https://codeload.github.com/craftup/node-mongo-tenant/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085328,"owners_count":21045139,"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":["mongo-tenant","mongoose","multi-tenancy-plugin","multitenancy","nodejs","tenant"],"created_at":"2024-10-02T15:06:00.938Z","updated_at":"2025-04-09T18:18:01.667Z","avatar_url":"https://github.com/craftup.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Multi Tenancy Plugin for Mongoose\n\n[![Subscribe to Release Notes](https://release-notes.com/badges/v1.svg)](https://release-notes.com/@craftup/node-mongo-tenant)\n[![Get Help on Gitter](https://img.shields.io/gitter/room/RealMQ/node-mongo-tenant.svg)](https://gitter.im/RealMQ/node-mongo-tenant)\n[![Build Status](https://travis-ci.org/craftup/node-mongo-tenant.png?branch=master)](https://travis-ci.org/craftup/node-mongo-tenant)\n[![Coverage Status](https://coveralls.io/repos/github/craftup/node-mongo-tenant/badge.svg?branch=master)](https://coveralls.io/github/craftup/node-mongo-tenant?branch=master)\n[![npm version](https://badge.fury.io/js/mongo-tenant.svg)](https://badge.fury.io/js/mongo-tenant)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/craftup/node-mongo-tenant/master/LICENSE)\n\n## Prelude\n\nThere are 3 ways of implementing multi-tenancy in mongoDB:\n\n- on document level (cheap and easy to administer but only secured by app logic)\n- on collection level (not recommended, due to breaking mongoDB concepts)\n- on database level (very flexible and secure but expensive)\n\n## About\n\nThe mongo tenant is a highly configurable mongoose plugin solving multi-tenancy problems on\ndocument level (for now...). \nIt creates a tenant-reference field and takes care of unique indexes.\nAlso it provides access to tenant-bound model-classes, that prohibit the\nexploid of the given tenant scope.\nLast but not least the \"MAGIC\" can be disabled so that shipping of the\nsame code in single- and multi-tenancy environment (on premis vs. cloud hosted)\nis a question of a single line of config.\n\n## Requirements\n\nMongo tenant is compatible with mongoose 4 and 5.\n\n## Incompatibilities\n\n* Mongo Tenant does not work with mongoose 4.8.1-4.8.2 see [Automattic/mongoose#4947](https://github.com/Automattic/mongoose/issues/4947).\n\n## Install\n\n```sh\n$ npm i -S mongo-tenant\n// or\n$ yarn add mongo-tenant\n```\n\n## Use\n\nRegister the plugin on the relevant mongoose schema.\n\n```javascript\nconst mongoose = require('mongoose');\nconst mongoTenant = require('mongo-tenant');\n\nconst MySchema = new mongoose.Schema({});\nMySchema.plugin(mongoTenant);\n\nconst MyModel = mongoose.model('MyModel', MySchema);\n```\n\nRetrieve the model in tenant scope with static `byTenant` method. This will return\na new model subclass that has special tenant-scope guards.\nIt has the exactly same interface as any other mongoose model but prevents\nthe access to other tenant scopes.\n\n```javascript\nconst MyTenantBoundModel = MyModel.byTenant('some-tenant-id');\n\n(new MyTenantBoundModel()).getTenantId() === 'some-tenant-id'; // true\n\n// silently ignore other tenant scope\n(new MyTenantBoundModel({\n  tenantId: 'some-other-tenant-id'\n})).getTenantId() === 'some-tenant-id'; // true\n\n```\n\nYou can check for tenant context of a model class or instance by checking\nthe `hasTenantContext` property. If this is truthy you may want to retrieve\nthe bound tenant scope with `getTenantId()` method.\n\n```javascript\n\n// With enabled mongo-tenant on a schema, all tenant bound models\n// and there instances provide the hasTenantContext flag\nif (SomeModelClassOrInstance.hasTenantContext) {\n  const tenantId = SomeModelClassOrInstance.getTenantId();\n  ...\n}\n```\n\n### Indexes\n\nThe mongo-tenant takes care of the tenant-reference field, so that you\nwill be able to use your existing schema definitions and just plugin the\nmongo-tenant without changing a single line of schema definition.\n\nBut under the hood the mongo-tenant creates an indexed field *(tenantId by default)*\nand includes this in all defined unique indexes. So by default, all unique \nfields (and compound indexes) are unique for a single tenant id.\n\nYou may have use-cases where you want to archive global uniqueness.\nTo skip the automatic unique key extension of mongo-tenant for a specific\nindex you can set the `preserveUniqueKey` config option to true.\n\n```javascript\nconst MySchema = new mongoose.Schema({\n  someField: {\n    unique: true,\n    preserveUniqueKey: true\n  },\n  anotherField: String,\n  yetAnotherField: String\n});\n\nMySchema.index({\n  anotherField: 1,\n  yetAnotherField: 1\n}, {\n  unique: true,\n  preserveUniqueKey: true\n});\n```\n\n### Context bound models and populate\n\nOnce a model with tenant context is created it will try to keep the context\nfor other models created via it. Whenever it detects that a subsequent models\ntenant configuration is compatible to its own, it will return that model\nbound to the same tenant context.\n\n```javascript\nconst AuthorSchema = new mongoose.Schema({});\nAuthorSchema.plugin(mongoTenant);\nconst AuthorModel = mongoose.model('author', AuthorSchema);\n\nconst BookSchema = new mongoose.Schema({\n  author: { type: mongoose.Schema.Types.ObjectId, ref: 'author' }\n});\nBookSchema.plugin(mongoTenant);\nconst BookModel = mongoose.model('book', BookSchema);\n\nconst BoundBookModel = BookModel.byTenant('some-tenant-id');\nBoundBookModel.model('author'); // return author model bound to \"some-tenant-id\"\nBoundBookModel.db.model('author'); // return author model bound to \"some-tenant-id\"\n```\n\n### Configuration\n\nThe mongo tenant works out of the box, so all config options are optional.\nBut you have the ability to adjust the behavior and api of the mongo tenant\nto your needs.\n\n```javascript\nconst config = {\n  /**\n   * Whether the mongo tenant plugin MAGIC is enabled. Default: true\n   */\n  enabled: false,\n\n  /**\n   * The name of the tenant id field. Default: tenantId\n   */\n  tenantIdKey: 'customerId',\n\n  /**\n   * The type of the tenant id field. Default: String\n   */\n  tenantIdType: Number,\n\n  /**\n   * The name of the tenant id getter method. Default: getTenantId\n   */\n  tenantIdGetter: 'getCustomerId',\n\n  /**\n   * The name of the tenant bound model getter method. Default: byTenant\n   */\n  accessorMethod: 'byCustomer',\n\n  /**\n   * Enforce tenantId field to be set. Default: false\n   * NOTE: this option will become enabled by default in mongo-tenant@2.0\n   */\n  requireTenantId: true\n};\n\nSomeSchema.plugin(mongoTenant, config);\n```\n\n### Running Tests\n\nSome tests rely on a running mongoDB and by default the tests are performed\nagainst 'mongodb://localhost/mongo-tenant-test'.\nThe tests can also be run against a custom mongoDB by passing the\ncustom connection string to **MONGO_URI** environment variable.\n\n```sh\n# perform jshint on sources and tests\n$ npm run hint\n\n# run the tests and gather coverage report\n$ npm run test-and-cover\n\n# run tests with custom mongoDB uri\n$ MONGO_URI='mongodb://user:password@xyz.mlab.com:23315/mongo-tenant-test' npm run test-and-cover\n```\n\n### LICENSE\n\nThe files in this archive are released under MIT license.\nYou can find a copy of this license in [LICENSE](https://github.com/craftup/node-mongo-tenant/raw/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcraftup%2Fnode-mongo-tenant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcraftup%2Fnode-mongo-tenant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcraftup%2Fnode-mongo-tenant/lists"}