{"id":15190584,"url":"https://github.com/taylanken/mongoose-version-history","last_synced_at":"2025-10-02T06:31:57.925Z","repository":{"id":65733355,"uuid":"114788911","full_name":"taylanken/mongoose-version-history","owner":"taylanken","description":"Mongoose plugin that tracks version history of documents by storing diffs in JSON Patch format.","archived":true,"fork":false,"pushed_at":"2018-07-23T12:16:36.000Z","size":18,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-25T22:54:49.279Z","etag":null,"topics":["json-patch","jsonpatch","mongodb","mongoose","mongoose-plugin","nodejs","storing-diffs"],"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/taylanken.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}},"created_at":"2017-12-19T16:44:02.000Z","updated_at":"2023-02-07T04:23:31.000Z","dependencies_parsed_at":"2023-02-07T05:43:13.060Z","dependency_job_id":null,"html_url":"https://github.com/taylanken/mongoose-version-history","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylanken%2Fmongoose-version-history","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylanken%2Fmongoose-version-history/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylanken%2Fmongoose-version-history/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taylanken%2Fmongoose-version-history/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taylanken","download_url":"https://codeload.github.com/taylanken/mongoose-version-history/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234951821,"owners_count":18912476,"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":["json-patch","jsonpatch","mongodb","mongoose","mongoose-plugin","nodejs","storing-diffs"],"created_at":"2024-09-27T20:42:39.743Z","updated_at":"2025-10-02T06:31:57.598Z","avatar_url":"https://github.com/taylanken.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mongoose-version-history\n\nMongoose plugin that tracks version history of documents by storing diffs in JSON Patch format.\n\n## Install\n\n```bash\nnpm install mongoose-version-history\n```\n\n## Usage\n\nTo use the plugin, simply ```require``` it and add it to the mongoose-schemas you want versioning activated for:\n\n```javascript\nconst Schema = require('mongoose').Schema;\nconst versionHistory = require('mongoose-version-history');\n\nlet User = new Schema({\n    name: {\n        first: String,\n        last: String\n    },\n    address: {\n        street: String,\n        no: String,\n        zipCode: String,\n        city: String,\n        country: String\n    },\n    birthdate: Date,\n    email: String,\n    phone: String\n});\n\nUser.plugin(versionHistory [, options]);\n```\n\nThe plugin will add a new number-field indicating the current version of the document to your schema.\nIt will store the history as JSON Patch diffs in a separate collection. Each changeset is directly bound to a specific version number, enabling you to track every change made for each version and to reconsruct a specific version of your document.\n\nThe version number gets incremented on each save/update.\n\n## Options\n\n### versionKey\n\nThe name of the version-field that gets added to the schema. Defaults to ```documentVersion```.\n\n### collection\n\nThe name of the collection the history gets stored to. Defaults to the name of the schema's collection with an ```_h``` appended to it.\n\n### connection\n\nThe database connection object. This option is required if the database is being connected via ```mongoose.createConnection``` instead of ```mongoose.connect```.\n\n```javascript\nconst mongoose = require('mongoose');\nconst Schema = mongoose.Schema;\nconst versionHistory = require('mongoose-version-history');\n\nlet db = mongoose.createConnection('mongodb://my-database');\n\nlet User = new Schema({\n    name: {\n        first: String,\n        last: String\n    },\n    address: {\n        street: String,\n        no: String,\n        zipCode: String,\n        city: String,\n        country: String\n    },\n    birthdate: Date,\n    email: String,\n    phone: String\n});\n\nUser.plugin(versionHistory, {\n    connection: db\n});\n```\n\n### trackDate\n\nIf set to ```true```, the date of creation will be tracked for each version, causing the __history-collection__ to have an additional field ```date```. If you want to redundantly store the date of the current version in the document itself aswell, additionally enable the ```addDateToDocument```-option.\n\n### addDateToDocument\n\nIf set to ```true```, and if the ```trackDate```-option is enabled, the date of the current version will be reduntantly stored in the actual document aswell.\n\n### versionDateKey\n\nThe name of the versionDate-field that gets added to the schema if the ```addDateToDocument```-option is enabled. Defaults to ```documentVersionDate```.\n\n## Retrieving specific document version\n\nTo retrieve a specific version of your document, you can use the ```getVersion``` function, passing the version number you want to access.\n\nThe ```getVersion``` returns a promise resolving to the desired document version, but it also supports callbacks:\n\n```javascript\n// Promises\nUser.findOne({...}).then(user =\u003e {\n    return user.getVersion(2);\n}).then(userV2 =\u003e {\n    ...\n});\n\n// Callbacks\nUser.findOne({...}, (err, user) =\u003e {\n    if(err) {\n        ...\n    }\n\n    user.getVersion(2, (err, userV2) =\u003e {\n        ...\n    });\n});\n```\n\n## Accessing the history collection directly\n\nTo access the history collection directy, you can call the ```getHistoryModel`` function on a model.\nIt will return a mongoose-model of the history collection:\n\n```javascript\nlet UserHistory = User.getHistoryModel();\nUserHistory.find({...});\n...\n```\n\nEach entry in the history collection represents a changeset (= one or more JSON Patches) and has the following schema:\n\n```javascript\nvar ChangeSet = new mongoose.Schema({\n    parent: mongoose.SchemaTypes.ObjectId, // The ID of the source-document this changeset is attached to\n    version: Number, // The version this changeset was created for\n    patches: [{ // Array of JSON-Patches representing the change\n        op: String, // Patch-operation\n        path: String, // Patch-patch\n        value: mongoose.SchemaTypes.Mixed // Patch-value\n    }],\n    date: Date // Only if the trackDate-option is enabled\n});\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaylanken%2Fmongoose-version-history","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaylanken%2Fmongoose-version-history","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaylanken%2Fmongoose-version-history/lists"}