Archive

• Who maintains the package – Jam

[[toc]]

What is this package?

Archive is an easy way to add an archive mechanism to your Meteor app. When a document is archived, it's removed from its original collection and placed in an archive collection so that it can be restored if needed. Its key features are:

• Zero config needed (though you can customize)
• Isomorphic so that it works with Optimistic UI
• Automatically overrides removeAsync to perform an archive (can be turned off)
• Explicitly archive with archiveAsync collection method (optional)
• Restore archived docs with restoreAsync collection method
• Optionally exclude specific collections
• Compatible with Meteor 3.0.2+

Note: Alternative to archive is soft deletion. You can use jam:soft-delete package for that. Be sure to compare those two approaches to pick the solution best suited for your application.

How to download it?

Add the package to your app

meteor add jam:archive

Sources

• GitHub repository

How to use it?

Create your Archives collection

Create an Archives collection in your app just as you would any other collection.

const Archives = new Mongo.Collection('archives');

Documents in the Archives collection will have this shape:

{
  _id, // auto-generated by Meteor as with other collection _ids
  _collection, // the name of the collection, e.g. 'todos', that the doc belonged to originally
  archivedAt, // the timestamp when the document was removed from its original collection and inserted into the archive
  id, // the original doc _id renamed to prevent conflict with the auto-generated one above. when restored, it will be renamed back to _id automatically by this package
  /*
  ...rest of original doc
  */
}

Deleting permanently

By default, this package overrides the removeAsync collection method so that it archives the document(s) rather that removing them from the database. To delete permanently, pass in the option forever: true, e.g.:

Collection.removeAsync(/* your filter */, { forever: true })

If you prefer, you can prevent overriding the removeAsync by setting overrideRemove: false. See Configuring for more details.

Explicitly archiving

If you prefer, you can explicity use archiveAsync, e.g.:

Collection.archiveAsync(/* your filter */)

Restoring a document

To restore an archived document, use restoreAsync, e.g.:

Collection.restoreAsync(/* your filter */)

Configuring (optional)

If you like the defaults, then you won't need to configure anything. But there is some flexibility in how you use this package.

Here are the global defaults:

const config = {
  name: 'archives', // if your Archives collection uses a different name, you'll want to change this
  overrideRemove: true, // overrides the Collection.removeAsync method to make it an archive instead
  exclude: ['roles', 'role-assignment'] // exclude specific collections from using archive so that when they are removed, the are permanently removed from the db. defaults to excluding the collections created by the meteor roles package
};

To change the global defaults, use:

// put this in a file that's imported on both the client and server
import { Archive } from 'meteor/jam:archive';

Archive.configure({
  // ... change the defaults here ... //
});