npm package: @ksgl/adonis4-audit
Description: Audit AdonisJS models without pain.
Author: KS Labs
Latest version: 2.1.15

# Adonis-Audit

[![Run All Tests](https://github.com/ks-labs/adonis-audit/actions/workflows/ci.tests.yml/badge.svg)](https://github.com/ks-labs/adonis-audit/actions/workflows/ci.tests.yml)

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.

```js
const providers = ['@ksgl/adonis-audit/providers/AuditProvider']
```

## Using the module

Add the following to your model's `boot` method:

```js
class MyModel extends Model {
  static boot() {
    super.boot()
    this.addTrait('@provider:Auditable')
  }
}
```

This you can start using as follows:

```js
// 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' }` |

```js
// 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' }` |

```js
// 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 |
| ------- | :---- | :------- | :------- |

```js
// 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' }` |

```js
// 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

```js
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:

```js
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](http://legacy.adonisjs.com) - The web framework used.

## Versioning

[SemVer](http://semver.org/) is used for versioning. For the versions available, see the [tags on this repository](https://github.com/ks-labs/adonis-audit/tags).

## Authors

- **KS Labs** - _Fork Owner_ - [kslabs](https://github.com/ks-labs)
- **Vinny** - _Currently Mantainer_ - [vinicioslc](https://github.com/vinicioslc)
- **Simon Tong** - _Creator_ - [simontong](https://github.com/simontong)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.