proxy-compare

What is proxy-compare?

The proxy-compare npm package is a utility for creating proxies that can be used to track changes in objects. It is particularly useful in state management scenarios where you need to detect changes in nested objects efficiently.

What are proxy-compare's main functionalities?

Create Proxies

This feature allows you to create a proxy for an object. Any changes made to the proxy will be tracked, which is useful for state management.

const { createProxy } = require('proxy-compare');

const state = { a: 1, b: { c: 2 } };
const proxyState = createProxy(state);

proxyState.a = 2; // This will be tracked
proxyState.b.c = 3; // This will also be tracked

Track Changes

This feature allows you to track changes made to the proxy and retrieve the untracked state. This is useful for comparing the current state with the previous state.

const { createProxy, getUntracked } = require('proxy-compare');

const state = { a: 1, b: { c: 2 } };
const proxyState = createProxy(state);

proxyState.a = 2;
const untrackedState = getUntracked(proxyState);
console.log(untrackedState); // { a: 2, b: { c: 2 } }

Deep Comparison

This feature allows you to perform a deep comparison between the proxy and the original state to check if any changes have been made.

const { isChanged } = require('proxy-compare');

const state = { a: 1, b: { c: 2 } };
const proxyState = createProxy(state);

proxyState.b.c = 3;
const hasChanged = isChanged(proxyState, state);
console.log(hasChanged); // true

Other packages similar to proxy-compare

immer

Immer is a package that allows you to work with immutable state in a more convenient way. It uses proxies to detect changes and produce a new immutable state. Unlike proxy-compare, Immer focuses on immutability and producing new state rather than just tracking changes.

proxy-memoize

Proxy-memoize is a package that uses proxies to memoize functions based on their input objects. It is similar to proxy-compare in that it uses proxies to track changes, but its primary focus is on memoization rather than state management.

reactive-maps

Reactive-maps is a package that provides reactive data structures using proxies. It is similar to proxy-compare in that it uses proxies to track changes, but it provides more specialized data structures like maps and sets.

README

proxy-compare

Compare two objects using accessed properties with Proxy

Introduction

This is an internal library used in state management libraries such as React Tracked and Valtio.

Install

npm install proxy-compare

Usage

$ 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

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 Object that will be wrapped on the proxy.
• affected WeakMap<object, unknown> WeakMap that will hold the tracking of which properties in the proxied object were accessed.
• proxyCache WeakMap<object, unknown>? WeakMap that will help keep referential identity for proxies.
• targetCache WeakMap<object, any>?

Examples

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<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 The previous object to compare.
• nextObj object Object to compare with the previous one.
• affected WeakMap<object, unknown> WeakMap that holds the tracking of which properties in the proxied object were accessed.
• cache WeakMap<object, unknown>? WeakMap that holds a cache of the comparisons for better performance with repetitive comparisons, and to avoid infinite loop with circular structures.
• isEqual function (a: any, b: any): boolean (optional, default Object.is)

Examples

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 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<object> The proxy wrapper of the originial object.

Examples

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 | 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 Object to mark as tracked or not.
• mark Boolean indicating whether you want to track this object or not. (optional, default true)

Examples

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<object, any> A weak map that is used with createProxy.
• onlyWithValues 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
• reactive-react-redux
• svelte3-redux
• proxy-memoize
• valtio

Similar libraries

• proxyequal
• proxy-state-tree
• proxy-watcher

Changelog

[3.0.1] - 2024-11-22

Changed

• refactor: simplify cache usage for object cycles #77