https://github.com/stennettm/historical
A Mongoose plugin that archives document diffs and manages document history.
https://github.com/stennettm/historical
historical-documents history mongoose mongoose-plugin snapshot
Last synced: 8 months ago
JSON representation
A Mongoose plugin that archives document diffs and manages document history.
- Host: GitHub
- URL: https://github.com/stennettm/historical
- Owner: stennettm
- License: mit
- Created: 2014-05-13T04:35:44.000Z (about 12 years ago)
- Default Branch: master
- Last Pushed: 2023-01-11T00:56:04.000Z (over 3 years ago)
- Last Synced: 2025-02-01T06:11:46.535Z (over 1 year ago)
- Topics: historical-documents, history, mongoose, mongoose-plugin, snapshot
- Language: JavaScript
- Homepage:
- Size: 122 KB
- Stars: 33
- Watchers: 2
- Forks: 6
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](http://travis-ci.org/stennettm/historical)
Historical
==========
A Mongoose plugin that archives document diffs and manages document history.
Historical requires a primary key (typically `_id`) to be present in your schema.
Installation
------------
`npm install historical@^2.0.0`
Getting Started
---------------
Attach the plugin to your schema with any of these optional configuration parameters:
- `name`: Provide a collection name. Defaults to `_historicals`.
- `connection`: Provide a mongoose connection for the historical collection. Defaults to your schema's connection.
- `primaryKeyName`: Provide your schema's primary key name. Defaults to `_id`.
- `primaryKeyType`: Provide your schema's primary key type. Defaults to your schema's primary key field configuration.
- `ignore`: An array of field names to ignore. Fields included in this list will not be stored in history.
```javascript
var mongoose = require('mongoose'),
ExampleSchema = new mongoose.Schema({
myField: String,
ignoredField: String,
anotherIgnoredField: String
});
ExampleSchema.plugin(require('historical'), {
connection: mongoose.createConnection('mongodb://localhost/example'),
name: null,
primaryKeyName: null,
primaryKeyType: null,
ignore: ['ignoredField', 'anotherIgnoredField']
});
```
Document #historicalDetails()
---------------------------------------------------------
List historical documents up to the given date for a document.
```javascript
myDocument.historicalDetails(new Date('2010-08-17T12:09:36'), function(e, objs){
//the list of historical changes for my document
console.log(objs);
});
```
Document #historicalRestore()
---------------------------------------------------------
Returns a document as it was at the given date.
```javascript
myDocument.historicalRestore(new Date('2010-08-17T12:09:36'), function(e, obj){
//my document as it was in 2010
//or null, if it either had not yet been created or was deleted before this time
if(obj) {
obj.save();
}
});
```
Document #historicalTrim()
------------------------------------------------------
Creates a new historical document by flattening history up to the given date, and deletes the touched historical documents.
Useful for pruning or establishing a maximum history retention period.
```javascript
myDocument.historicalTrim(new Date('2010-08-17T12:09:36'), function(e, obj){
//any history before this time has been flattened into one historical document
//my document as it was provided
console.log(obj);
});
```
Document #historicalSnapshot()
-----------------------------------------------
Take a complete and current snapshot of my document and store it in history.
Unmodified documents only.
```javascript
myDocument.historicalSnapshot(function(e, obj){
//my document as it was provided
console.log(obj);
});
```
Document #historicalClear()
--------------------------------------------
Clear all history for my document and take a snapshot.
Unmodified documents only.
```javascript
myDocument.historicalClear(function(e, obj){
//my document as it was provided
console.log(obj);
});
```