230 lines
8.4 KiB
Markdown
230 lines
8.4 KiB
Markdown
|
|
# proxy-compare
|
||
|
|
|
||
|
|
[](https://github.com/dai-shi/proxy-compare/actions?query=workflow%3ACI)
|
||
|
|
[](https://www.npmjs.com/package/proxy-compare)
|
||
|
|
[](https://bundlephobia.com/result?p=proxy-compare)
|
||
|
|
[](https://discord.gg/MrQdmzd)
|
||
|
|
|
||
|
|
Compare two objects using accessed properties with Proxy
|
||
|
|
|
||
|
|
## Introduction
|
||
|
|
|
||
|
|
This is an internal library used in state management libraries such as [React Tracked](https://react-tracked.js.org) and [Valtio](https://github.com/pmndrs/valtio).
|
||
|
|
|
||
|
|
## Install
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm install proxy-compare
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
$ node
|
||
|
|
> const { createProxy, isChanged } = require('proxy-compare')
|
||
|
|
undefined
|
||
|
|
> state = { a: 1, b: 2 }
|
||
|
|
{ a: 1, b: 2 }
|
||
|
|
> affected = new WeakMap()
|
||
|
|
WeakMap { [items unknown] }
|
||
|
|
> proxy = createProxy(state, affected)
|
||
|
|
Proxy [
|
||
|
|
{ a: 1, b: 2 },
|
||
|
|
{
|
||
|
|
get: [Function: get],
|
||
|
|
has: [Function: has],
|
||
|
|
getOwnPropertyDescriptor: [Function: getOwnPropertyDescriptor],
|
||
|
|
ownKeys: [Function: ownKeys]
|
||
|
|
}
|
||
|
|
]
|
||
|
|
> proxy.a
|
||
|
|
1
|
||
|
|
> isChanged(state, { a: 1, b: 22 }, affected)
|
||
|
|
false
|
||
|
|
> isChanged(state, { a: 11, b: 2 }, affected)
|
||
|
|
true
|
||
|
|
```
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
|
||
|
|
|
||
|
|
### createProxy
|
||
|
|
|
||
|
|
Create a proxy.
|
||
|
|
|
||
|
|
This function will create a proxy at top level and proxy nested objects as you access them,
|
||
|
|
in order to keep track of which properties were accessed via get/has proxy handlers:
|
||
|
|
|
||
|
|
NOTE: Printing of WeakMap is hard to inspect and not very readable
|
||
|
|
for this purpose you can use the `affectedToPathList` helper.
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
|
||
|
|
* `obj` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object that will be wrapped on the proxy.
|
||
|
|
* `affected` **[WeakMap](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)<[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object), unknown>** WeakMap that will hold the tracking of which properties in the proxied object were accessed.
|
||
|
|
* `proxyCache` **[WeakMap](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)<[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object), unknown>?** WeakMap that will help keep referential identity for proxies.
|
||
|
|
|
||
|
|
#### Examples
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
import { createProxy } from 'proxy-compare';
|
||
|
|
|
||
|
|
const original = { a: "1", c: "2", d: { e: "3" } };
|
||
|
|
const affected = new WeakMap();
|
||
|
|
const proxy = createProxy(original, affected);
|
||
|
|
|
||
|
|
proxy.a // Will mark as used and track its value.
|
||
|
|
// This will update the affected WeakMap with original as key
|
||
|
|
// and a Set with "a"
|
||
|
|
|
||
|
|
proxy.d // Will mark "d" as accessed to track and proxy itself ({ e: "3" }).
|
||
|
|
// This will update the affected WeakMap with original as key
|
||
|
|
// and a Set with "d"
|
||
|
|
```
|
||
|
|
|
||
|
|
Returns **[Proxy](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy)<[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** Object wrapped in a proxy.
|
||
|
|
|
||
|
|
### isChanged
|
||
|
|
|
||
|
|
Compare changes on objects.
|
||
|
|
|
||
|
|
This will compare the affected properties on tracked objects inside the proxy
|
||
|
|
to check if there were any changes made to it,
|
||
|
|
by default if no property was accessed on the proxy it will attempt to do a
|
||
|
|
reference equality check for the objects provided (Object.is(a, b)). If you access a property
|
||
|
|
on the proxy, then isChanged will only compare the affected properties.
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
|
||
|
|
* `prevObj` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** The previous object to compare.
|
||
|
|
* `nextObj` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object to compare with the previous one.
|
||
|
|
* `affected` **[WeakMap](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)<[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object), unknown>** WeakMap that holds the tracking of which properties in the proxied object were accessed.
|
||
|
|
* `cache` **[WeakMap](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)<[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object), unknown>?** WeakMap that holds a cache of the comparisons for better performance with repetitive comparisons,
|
||
|
|
and to avoid infinite loop with circular structures.
|
||
|
|
|
||
|
|
#### Examples
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
import { createProxy, isChanged } from 'proxy-compare';
|
||
|
|
|
||
|
|
const obj = { a: "1", c: "2", d: { e: "3" } };
|
||
|
|
const affected = new WeakMap();
|
||
|
|
|
||
|
|
const proxy = createProxy(obj, affected);
|
||
|
|
|
||
|
|
proxy.a
|
||
|
|
|
||
|
|
isChanged(obj, { a: "1" }, affected) // false
|
||
|
|
|
||
|
|
proxy.a = "2"
|
||
|
|
|
||
|
|
isChanged(obj, { a: "1" }, affected) // true
|
||
|
|
```
|
||
|
|
|
||
|
|
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Boolean indicating if the affected property on the object has changed.
|
||
|
|
|
||
|
|
### getUntracked
|
||
|
|
|
||
|
|
Unwrap proxy to get the original object.
|
||
|
|
|
||
|
|
Used to retrieve the original object used to create the proxy instance with `createProxy`.
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
|
||
|
|
* `obj` **[Proxy](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy)<[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** The proxy wrapper of the originial object.
|
||
|
|
|
||
|
|
#### Examples
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
import { createProxy, getUntracked } from 'proxy-compare';
|
||
|
|
|
||
|
|
const original = { a: "1", c: "2", d: { e: "3" } };
|
||
|
|
const affected = new WeakMap();
|
||
|
|
|
||
|
|
const proxy = createProxy(original, affected);
|
||
|
|
const originalFromProxy = getUntracked(proxy)
|
||
|
|
|
||
|
|
Object.is(original, originalFromProxy) // true
|
||
|
|
isChanged(original, originalFromProxy, affected) // false
|
||
|
|
```
|
||
|
|
|
||
|
|
Returns **([object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) | null)** Return either the unwrapped object if exists.
|
||
|
|
|
||
|
|
### markToTrack
|
||
|
|
|
||
|
|
Mark object to be tracked.
|
||
|
|
|
||
|
|
This function marks an object that will be passed into `createProxy`
|
||
|
|
as marked to track or not. By default only Array and Object are marked to track,
|
||
|
|
so this is useful for example to mark a class instance to track or to mark a object
|
||
|
|
to be untracked when creating your proxy.
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
|
||
|
|
* `obj` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object to mark as tracked or not.
|
||
|
|
* `mark` Boolean indicating whether you want to track this object or not. (optional, default `true`)
|
||
|
|
|
||
|
|
#### Examples
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
import { createProxy, markToTrack, isChanged } from 'proxy-compare';
|
||
|
|
|
||
|
|
const nested = { e: "3" }
|
||
|
|
|
||
|
|
markToTrack(nested, false)
|
||
|
|
|
||
|
|
const original = { a: "1", c: "2", d: nested };
|
||
|
|
const affected = new WeakMap();
|
||
|
|
|
||
|
|
const proxy = createProxy(original, affected);
|
||
|
|
|
||
|
|
proxy.d.e
|
||
|
|
|
||
|
|
isChanged(original, { d: { e: "3" } }, affected) // true
|
||
|
|
```
|
||
|
|
|
||
|
|
Returns **any** No return.
|
||
|
|
|
||
|
|
### affectedToPathList
|
||
|
|
|
||
|
|
Convert `affected` to path list
|
||
|
|
|
||
|
|
`affected` is a weak map which is not printable.
|
||
|
|
This function is can convert it to printable path list.
|
||
|
|
It's for debugging purpose.
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
|
||
|
|
* `obj` **any** An object that is used with `createProxy`.
|
||
|
|
* `affected` **[WeakMap](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)<[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object), any>** A weak map that is used with `createProxy`.
|
||
|
|
* `onlyWithValues` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** An optional boolean to exclude object getters.
|
||
|
|
|
||
|
|
Returns **any** An array of paths.
|
||
|
|
|
||
|
|
### replaceNewProxy
|
||
|
|
|
||
|
|
replace newProxy function.
|
||
|
|
|
||
|
|
This can be used if you want to use proxy-polyfill.
|
||
|
|
Note that proxy-polyfill can't polyfill everything.
|
||
|
|
Use it at your own risk.
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
|
||
|
|
* `fn` **any** 
|
||
|
|
|
||
|
|
## Projects using this library
|
||
|
|
|
||
|
|
* [react-tracked](https://github.com/dai-shi/react-tracked)
|
||
|
|
* [reactive-react-redux](https://github.com/dai-shi/reactive-react-redux)
|
||
|
|
* [svelte3-redux](https://github.com/dai-shi/svelte3-redux)
|
||
|
|
* [proxy-memoize](https://github.com/dai-shi/proxy-memoize)
|
||
|
|
* [valtio](https://github.com/pmndrs/valtio)
|
||
|
|
|
||
|
|
## Similar libraries
|
||
|
|
|
||
|
|
* [proxyequal](https://www.npmjs.com/package/proxyequal)
|
||
|
|
* [proxy-state-tree](https://www.npmjs.com/package/proxy-state-tree)
|
||
|
|
* [proxy-watcher](https://www.npmjs.com/package/proxy-watcher)
|