@sa0001/simple-proxy

[NPM][https://www.npmjs.com/package/@sa0001/simple-proxy]

This module helps you create a powerful ES6 Proxy using simple options, that otherwise would take a surprising amount of effort and knowledge to correctly implement.

Install

npm install @sa0001/simple-proxy

Usage

const SimpleProxy = require('@sa0001/simple-proxy')

// some data you want to protect
const data = {
	goodKey: 'val'
	subObj: {
		goodKey: 'val'
	}
}

// all available proxy options
const options = {
	// give this proxy a name, which is displayed in the error message
	name: 'SimpleProxy',
	
	// prevent accessing non-defined properties (ex. `var v = proxy.wrongKey`)
	preventAccess: false,
	
	// prevent defining/reconfiguring properties using `Object.defineProperty`
	//  (compare to Object.freeze, Object.seal)
	preventDefine: false,
	
	// prevent removing properties using `delete`
	//  (compare to Object.freeze, Object.seal)
	preventDelete: false,
	
	// prevent adding new properties (ex. `proxy.newKey = true`)
	//  (compare to Object.freeze, Object.seal, Object.preventExtensions)
	preventExtend: false,
	
	// prevent changing values (ex. `proxy.key = 'new value'`)
	//  (compare to Object.freeze)
	preventMutate: false,
	
	// prevent setting/getting value undefined
	//  (can only delete the property, or set to null)
	preventUndefined: false,
	
	// when getting/setting an undefined value, instead get/set null
	//  (use this when you don't want the distinction between undefined and null)
	convertUndefinedToNull: false,
	
	// callback for all errors produced when an action was prevented;
	//  if no callback is provided, then the error is thrown
	onError: (err) => {
		if (err.code === "MUTATE") {
			throw err
		} else {
			console.error(err)
		}
	},
	
	// callback on get/set of every property
	onGet: (k) => {},
	onSet: (k, v) => {},
	
	// callback on get/set of any non-defined property
	onGetNonDefined: (k) => {},
	onSetNonDefined: (k, v) => {},
	
	// callback when a value changes
	onChange: (key, newVal, oldVal) => {},
	
	// proxy will also be applied to sub-objects
	deepProxy: false,
	
	// proxy will also be applied to sub-objects, but with different settings
	deepProxyOptions: null,
}

// create the proxy from initial data + options
const proxy = new SimpleProxy(data, options)

/**
 * some short and sweet examples:
**/

// preventAccess
const proxy = new SimpleProxy(data, { preventAccess: true })
var v = proxy.badKey // Error: SimpleProxy: cannot access non-defined key 'badKey'

// preventExtend
const proxy = new SimpleProxy(data, { preventExtend: true })
proxy.badKey = false // Error: SimpleProxy: cannot extend key 'badKey'

// preventMutate
const proxy = new SimpleProxy(data, { preventMutate: true })
proxy.goodKey = true // Error: SimpleProxy: cannot mutate key 'goodKey'

/**
 * static constructors for the three most common use-cases:
**/

// throw error when accessing (getting) non-defined properties
SimpleProxy.access(data)
var v = proxy.badKey // Error: SimpleProxy: cannot access non-defined key 'badKey'

// same, but also applied to sub-objects
SimpleProxy.deepAccess(data)
var v = proxy.subObj.badKey // Error: SimpleProxy: cannot access non-defined key 'subObj.badKey'

// equivalent of Object.freeze, but also works outside of strict mode
SimpleProxy.freeze(data)
proxy.goodKey = true // Error: SimpleProxy: cannot mutate key 'goodKey'

// same, but also applied to sub-objects
SimpleProxy.deepFreeze(data)
proxy.subObj.goodKey = true // Error: SimpleProxy: cannot mutate key 'subObj.goodKey'

// equivalent of Object.seal, but also works outside of strict mode
SimpleProxy.seal(data)
proxy.badKey = true // Error: SimpleProxy: cannot extend key 'badKey'

// same, but also applied to sub-objects
SimpleProxy.deepSeal(data)
proxy.subObj.badKey = true // Error: SimpleProxy: cannot extend key 'subObj.badKey'

License

MIT