National Palace Museum


    2.0.0 • Public • Published

    Build Status 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.


    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 <collection>_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.
    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.

    myDocument.historicalDetails(new Date('2010-08-17T12:09:36'), function(e, objs){
       //the list of historical changes for my document

    Document #historicalRestore()

    Returns a document as it was at the given date.

    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) {

    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.

    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

    Document #historicalSnapshot()

    Take a complete and current snapshot of my document and store it in history. Unmodified documents only.

    myDocument.historicalSnapshot(function(e, obj){
       //my document as it was provided

    Document #historicalClear()

    Clear all history for my document and take a snapshot. Unmodified documents only.

    myDocument.historicalClear(function(e, obj){
       //my document as it was provided


    npm i historical

    DownloadsWeekly Downloads






    Unpacked Size

    20.2 kB

    Total Files


    Last publish


    • hyperhedron
    • stennettm