Provide traps for use as Proxy handler, allowing to keep track of changes and choose to commit or rollback changes
npm install @konfirm/trap
Provide traps for use as Proxy handler, allowing to keep track of changes and choose to commit or rollback changes
``
$ npm install --save @konfirm/trap
ts
// include the Trap module
// const { Trap } = require('@konfirm/trap');
import { Trap } from '@konfirm/trap';
// create a trap instance
const trap = new Trap();
// create the affected object
const affect = { foo: 'bar', bar: 'baz' };
// create the proxy
const proxy = new Proxy(affect, trap);proxy.foo = 'hello world';
console.log(proxy.foo); // 'hello world'
console.log(affect.foo); // 'bar'
delete proxy.bar;
console.log('bar' in proxy); // false
console.log('bar' in affect); // true
// commit all trapped changes
trap.commit();
console.log(affect.foo); // 'hello world'
console.log('bar' in affect); // false
`
API
Trap keeps track of changes within proxied objects, and exposes two methods besides the implemented trap functions.$3
| name | description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
| The Trap class itself |
| MutationInterface | _TypeScript_ interface describing Mutations |
| isMutationInterface | Type Guard validating whether the input is a MutationInterface |
| MutationOptions | _TypeScript_ type describing the target, key and optional value members of a MutationInterface |
| isMutationOptions | Type Guard validating whether the input is MutationOptions |
| DeletionMutation | Mutation describing deletion mutations, created by deleteProperty (delete target.key) operations |
| PropertyMutation | Mutation describing property mutations, created by defineProperty (Object.defineProperty(target, key, {...})) operations |
| ValueMutation | Mutation describing value mutations, created by set (target.key = ...) operations |
| AbstractMutation | abstract implementation of a Mutation |$3
| property | type | required | notes |
| -------- | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
|
target | Object\|Function\|Array | yes | this can be narrowed down (e.g. only objects of a specific type), but never widened (e.g. not add booleans) |
| key | string | symbol | yes | this can be narrowed doen (e.g. only strings), but not wideneded (e.g. not add numbers) |
| value | any | no |$3
The Trap constructor accepts the trackOnlyLastMutation argument (default false) indicating whether or not the mutations should be limited to one per property. If trackOnlyLastMutation is set to true value, any previous change to the trapped object is remove before applying the next value. Should the next value effectively restore the original state, no new mutations is created and the number of mutations is decreased.$3
Apply collected mutations (optionally filtered by a search parameter) to the target and reset the mutation list.`ts
trap.commit({ target: myTarget }); // applies all collected mutations with target myTarget
trap.commit({ key: 'sample' }); // applies all collected mutations for key 'sample'
trap.commit(); // applies all collected mutations
`$3
Drop mutations (optionally filtered by a search parameter) so these will never be applied to the target.ts
trap.rollback({ target: myTarget }); // removes all collected mutations with target myTarget
trap.rollback({ key: 'sample' }); // removes all collected mutations for key 'sample'
trap.rollback(); // removes all collected mutations
`$3
As v2.0 of removed the mutations collection from direct access, the count method allows for counting the number of mutations (optionally filtered by a search parameter).`ts
trap.count({ target: myTarget }); // counts all mutations with target myTarget
trap.count({ key: 'sample' }); // counts all mutations for key 'sample'
trap.count(); // counts all mutations
`$3
Trap provides most of the Proxy handler methods which directly change object properties.; traps Object.defineProperty calls
- deleteProperty; traps property deletion
- get; traps property value getting
- getOwnPropertyDescriptor; traps Object.getOwnPropertyDescriptor calls
- has; traps