@konfirm/trap

Trap Module

Provide traps for use as Proxy handler, allowing to keep track of changes and choose to commit or rollback changes

Installation

$ npm install --save @konfirm/trap

Usage

The Trap module is designed to handle and reflect Proxy manipulations to an object Proxy, during its handler assignment you can provide a Trap-instance or parts of it.

Trap all mutations

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

Exports

name	description
Trap	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

type MutationOptions

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
value	any	no

Trap([trackOnlyLastMutation])

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.

commit

Apply collected mutations (optionally filtered by a search parameter) to the target and reset the mutation list.

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

rollback

Drop mutations (optionally filtered by a search parameter) so these will never be applied to the target.

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

count

As v2.0 of Trap removed the mutations collection from direct access, the count method allows for counting the number of mutations (optionally filtered by a search parameter).

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

Implemented Trap functions

Trap provides most of the Proxy handler methods which directly change object properties.

• defineProperty; traps Object.defineProperty calls
• deleteProperty; traps property deletion
• get; traps property value getting
• getOwnPropertyDescriptor; traps Object.getOwnPropertyDescriptor calls
• has; traps <key> in <Object> calls
• ownKeys; traps Object.keys calls
• set; traps property value setting

Trap functions not implemented

The following functions are currently not implemented by the Trap module, if there is a need for them to be added, feel free to submit an issue or create a pull request.

• apply; traps method invocations
• construct; traps new instance creation
• getPrototypeOf; traps Object.getPrototypeOf calls
• isExtensible; traps Object.isExtensible calls
• preventExtensions; traps Object.preventExtensions calls
• setPrototypeOf; traps Object.setPrototypeOf calls

Licence

MIT License

Copyright (c) 2017-2023 Rogier Spieker (Konfirm)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.