0.0.12 • Published 3 years ago
@sa0001/simple-proxy v0.0.12
@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'