@ksgl/adonis4-audit

Adonis-Audit

Audit models in AdonisJS

How to use

1. 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.