Adonis-Audit
Audit models in AdonisJS
How to use
- Install npm module:
adonis install @ksgl/adonis-audit
Register provider
Once you have installed adonis-audit, make sure to register the provider inside start/app.js in order to make use of it.
const providers = ['@ksgl/adonis-audit/providers/AuditProvider']Using the module
Add the following to your model's boot method:
class MyModel extends Model {
static boot() {
super.boot()
this.addTrait('@provider:Auditable')
}
}This you can start using as follows:
// create
const createdModel = await MyModel.audit().create({ name: 'John' })this will generate a new entry on audits table with only the name field :
| auditable | auditable_id | event | ...cols | old_data | new_data |
|---|---|---|---|---|---|
user |
1 |
create |
... | null |
{ name: 'John' } |
// simple update event
const myModel = await MyModel.find(1)
await myModel.audit().update({ name: 'Simon' })
const myModel = await MyModel.find(1)this will generate a new update event on audit table with the fields changed :
| ...cols | event | old_data | new_data |
|---|---|---|---|
| ... | update |
{ name :'John' } |
{ name: 'Simon' } |
// ignore audit event when only specified fields in `ignoreDiff` has changed (default to ['updated_at'])
await myModel.audit({ ignoreDiff: ['name', 'updated_at'] }).update({ name: 'Simon' })
// this audit will not write to the `audits` table because only the `name` field changed and its present in `ignoreDiff`this will not create an entry on audits table due the ignored changes on name field:
| ...cols | event | old_data | new_data |
|---|
// save only the specified fields in `onlySave` (default to [])
await myModel
.audit({
onlySave: ['name'],
})
.update({ name: 'newName', password: '32123' })this will generate a new entry on audits table with only the name field :
| ...cols | event | old_data | new_data |
|---|---|---|---|
| ... | update |
{ name :'Simon' } |
{ name: 'newName' } |
// delete
const myModel = await MyModel.find(1)
await myModel.audit().delete()This will generate an entry with delete event on audits table :
| ...cols | event | old_data | new_data |
|---|---|---|---|
| ... | delete |
{ name: 'newName' } |
null |
Transaction Support
const { request } = ctx
const trx = await Database.beginTransaction()
const myModel = await MyModel.find(1)
await myModel.audit({ ctx }).update({ name: 'Simon' }, trx)
await myModel.audit({ ctx }).delete(trx)
// revert changes and remove audit entries created
await trx.rollback()
const foundMyModel = await MyModel.find(1)Relationship Support
You can save relationship information as follows:
await myModel
.audit(
{
ctx,
syncRelated: ['jobs'] /* Tell us which relationships you want to audit */,
},
async (entity) => {
/* In case of an update or create with relationships it is necessary to inform the callback by executing the relationship methods. On deletion this callback is not necessary (or usually not, it depends on your case) */
await entity.jobs().sync(jobs)
}
)
.update(/* *** */)
//or
.create(/* *** */)
//or
.delete()Built For
- Legacy AdonisJS 4.1 - The web framework used.
Versioning
SemVer is used for versioning. For the versions available, see the tags on this repository.
Authors
- KS Labs - Fork Owner - kslabs
- Vinny - Currently Mantainer - vinicioslc
- Simon Tong - Creator - simontong
License
This project is licensed under the MIT License - see the LICENSE file for details.