Feathers Versions
ALPHA VERSION DOCUMENTATION
If you're reading this, feathers-versions is in alpha, and not all of the functionality is fully described or finalized.
Why?
- You're using feathers.js serverside, and you'd like to save versions of service documents.
- You love your family.
QuickStart
The following assumes you're familiar with feathers.js workflow. If you've never heard of feathers.js before, it's great. Learn it: feathers.js
Install
npm install feathers-versions
Set Up Versions Service
//set up a quick app that will allow you to create documents server sideconst app = //calling versions without any arguments gives the default configuration
Set up a Service that will use Versioning
Once the version service has been set up, you need to add a couple
of hooks
to any service
that you want to use versions.
The addVersion
hook can only be placed as after
patch
, create
and update
hooks, and typically you'd want them on all three.
The clearVersions
can only be placed as a after
remove
hook.
const articles = app //for the sake of example, we'll set up an in memory service //configure your add and clear hooksconst add = const clear = //apply the hooks to the articles service.articles
Create a Document
That's it! Now, when you create or edit article documents, they'll have versions saved on the version service.
articles
Service Configuration
The service configuration comes with a couple of options, most importantly the adapter field:
idType
and adapter
If you don't provide a a database adapter, feathers-versions
will use feathers-memory
by default, which probably won't be very useful.
idType is the constructor for the dataType that your id will be in. Number
by default. This is important to set if you are using service adapters that don't user strings or numbers as ids, like mongodb.
To set the versions service to use mongodb:
//once again, create an app that will allow you to create documents server-sideconst app = MongoClient
serviceName
By default, the service name for the versions service will simply be versions. If you'd like it to be something else, set this option:
const app = //ta daaconst historyService = app
userEntityField
and userIdField
These fields are used for getting a authenticated user object. If a user patches
an document that uses versioning, feathers-versions
will save that users id with
the version data.
By default userEntityField
is user and userIdField
is _id
addVersion
Hook Configuration
There are a couple of options when adding version hooks to documents:
limit
A limit to how many versions can be stored. If the limit is reached, the oldest versions will be deleted to make room for new ones. Default is 1000.
saveInterval
If set, saveInteval
should be a number in milliseconds. New versions added in
less than the set number of milliseconds will be collapsed together. This is so that
if multiple changes are made frequently, they'll be considered one version. By default,
a version will be created with every patch or update.
excludeMask
and includeMask
You should set EITHER excludeMask
or includeMask
, not both, and they
should be an array of strings, representing field names.
These fields will mask the data that gets saved to a version, so that redundant fields are ignored.
clearVersions
Hook Configuration
The clearVersions
hook currently receives no configuration.
getVersion
helper method.
feathers-versions
also exports a helper method called getVersion
It simplifies getting the version data for a specific document.
void { const articles = app const doc = await articles let docVersions docVersions = await // OR, getVersion can also be bound to app for readability docVersions = await app:: console /* { id: 0, document: 0, service: 'articles', list: [{ user: null, updated: [Date], data: { body: 'Informed opinion.', author: 'Some Guy' } }] } */}
Further Considerations
- New versions will not be created if none of the masked data has been changed.