# Archive

- `Who maintains the package` – [Jam](https://github.com/jamauro)

[[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`](./soft-delete.md) 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
```bash
meteor add jam:archive
```

### Sources

* [GitHub repository](https://github.com/jamauro/archive)

## How to use it?

### Create your Archives collection
Create an Archives collection in your app just as you would any other collection.
```js
const Archives = new Mongo.Collection('archives');
```

Documents in the Archives collection will have this shape:
```js
{
  _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.:
```js
Collection.removeAsync(/* your filter */, { forever: true })
```

If you prefer, you can prevent overriding the `removeAsync` by setting `overrideRemove: false`. See [Configuring](#configuring-optional) for more details.

### Explicitly archiving
If you prefer, you can explicity use `archiveAsync`, e.g.:
```js
Collection.archiveAsync(/* your filter */)
```

### Restoring a document
To restore an archived document, use `restoreAsync`, e.g.:
```js
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:
```js
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:
```js
// 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 ... //
});
```
