solid-proxies v1.0.3

Solid Proxies

Solid Proxies is a JavaScript library that provides signaled versions of JavaScript's built-in objects. This means that all changes to the properties of these objects will be automatically tracked when using the standard API. For example, operations like array.push, array.slice, or direct index access like person['name'] will only trigger an update of specific values. This granular reactivity ensures that your effects will not rerun unnecessarily.

Table of Contents

• Solid Proxies
  • Table of Contents
  • Installation
  • Compatibility
  • Demo
  • Usage
    • SignaledObject
    • SignaledArray
    • SignaledMap
    • SignaledWeakMap
    • SignaledSet
    • SignaledWeakSet

Installation

npm install solid-proxies

Compatibility

• Solid.js ^1.0

Demo

CodeSandbox demo: Link

Usage

SignaledObject

SignaledObject is a variant of the standard JavaScript Object type that automatically tracks changes to its properties. This means that any operation that modifies the properties of a SignaledObject, such as setting a new value, deleting a property, or checking the keys of the object, will trigger an update and make your code react to the change.

To use SignaledObject, you can import the createObject function from the solid-proxies library:

import { createObject } from 'solid-proxies';

Then, you can create a new SignaledObject by calling createObject and passing in an object literal as an argument (optionally):

const user = createObject({ name: "Maciej" });

You can then use the SignaledObject like a normal JavaScript object, but any changes you make to its properties will be tracked and can be reacted to by your code. For example:

createEffect(() => {
  console.log(user.name);
});

// After some time...
user.name = "Exelord"; // This change will rerun the effect

Important: SignaledObjects are not deep wrapped. This means that an object within a SignaledObject would need to be signaled individually.

Here is an example of how you can use SignaledObject to track changes to a nested object:

const user = createObject({
  name: "Maciej",
  address: createObject({
    city: "New York",
    country: "USA"
  })
});

createEffect(() => {
  console.log(user.address.city);
});

// After some time...
user.address.city = "London"; // This change will rerun the effect

SignaledArray

SignaledArray is a variant of the standard JavaScript Array type that automatically tracks changes to its elements. This means that any operation that modifies the elements of a SignaledArray, such as setting a new value, deleting an element, or adding a new element, will trigger an update and make your code react to the change.

To use SignaledArray, you can import the createArray function from the solid-proxies library:

import { createArray } from 'solid-proxies';

Then, you can create a new SignaledArray by calling createArray and passing in an array literal as an argument:

const users = createArray([{ name: "Maciej" }]);

You can then use the SignaledArray like a normal JavaScript array, but any changes you make to its elements will be tracked and can be reacted to by your code. For example:

createEffect(() => {
  console.log(users[0].name);
});

// After some time...
users[0] = { name: "Exelord" }; // This change will rerun the effect

Important: SignaledArrays are not deep wrapped. This means that an array or object within a SignaledArray would need to be signaled individually.

Here is an example of how you can use SignaledArray to track changes to a nested array:

const users = createArray([
  {
    name: "Maciej",
    favoriteColors: ["red", "blue"]
  }
]);

createEffect(() => {
  console.log(users[0].favoriteColors[0]);
});

// After some time...
users[0].favoriteColors[0] = "green"; // This change will NOT rerun the effect

// To track changes to the favoriteColors array itself, you would need to create a new
// SignaledArray for it:
users[0].favoriteColors = createArray(["yellow", "purple"]);

// And then...
users[0].favoriteColors[0] = "green"; // This change WILL rerun the effect

SignaledMap

SignaledMap is a variant of the standard JavaScript Map type that automatically tracks changes to its key-value pairs. This means that any operation that modifies the key-value pairs of a SignaledMap, such as setting a new value, deleting a key-value pair, or adding a new key-value pair, will trigger an update and make your code react to the change.

To use SignaledMap, you can import the createMap function from the solid-proxies library:

import { createMap } from 'solid-proxies';

Then, you can create a new SignaledMap by calling createMap and passing in an array of key-value pairs as an argument:

const people = createMap([[1, "Maciej"]]);

You can then use the SignaledMap like a normal JavaScript Map, but any changes you make to its key-value pairs will be tracked and can be reacted to by your code. For example:

createEffect(() => {
  console.log(people.get(1));
});

// After some time...
people.set(1, 'Exelord'); // This change will rerun the effect

You can also use the various methods of the Map object, such as has, delete, and clear, to modify the key-value pairs of a SignaledMap and trigger updates.

SignaledWeakMap

SignaledWeakMap is a variant of the standard JavaScript WeakMap type that automatically tracks changes to its key-value pairs. This means that any operation that modifies the key-value pairs of a SignaledWeakMap, such as setting a new value, deleting a key-value pair, or adding a new key-value pair, will trigger an update and make your code react to the change.

Unlike a regular Map, a WeakMap only holds weak references to its keys, which means that the keys can be garbage collected if there are no other references to them. This makes WeakMaps useful for storing metadata or other information that you don't want to keep alive longer than necessary.

To use SignaledWeakMap, you can import the createWeakMap function from the solid-proxies library:

import { createWeakMap } from 'solid-proxies';

Then, you can create a new SignaledWeakMap by calling createWeakMap and passing in an array of key-value pairs as an argument:

const person = { name: "Maciej" };
const people = createWeakMap([[person, "my favorite"]]);

You can then use the SignaledWeakMap like a normal JavaScript WeakMap, but any changes you make to its key-value pairs will be tracked and can be reacted to by your code. For example:

createEffect(() => {
  console.log(people.get(person)));
});

// After some time...
people.set(person, "your favorite"); // This change will rerun the effect

You can also use the has and delete methods of the WeakMap object to modify the key-value pairs of a SignaledWeakMap and trigger updates.

SignaledSet

SignaledSet is a variant of the standard JavaScript Set type that automatically tracks changes to its elements. This means that any operation that modifies the elements of a SignaledSet, such as adding a new element, deleting an element, or checking if an element exists, will trigger an update and make your code react to the change.

To use SignaledSet, you can import the createSet function from the solid-proxies library:

import { createSet } from 'solid-proxies';

Then, you can create a new SignaledSet by calling createSet and passing in an array of elements as an argument:

const people = createSet(["Maciej"]);

You can then use the SignaledSet like a normal JavaScript Set, but any changes you make to its elements will be tracked and can be reacted to by your code. For example:

createEffect(() => {
  console.log(people.has("Exelord"));
});

// After some time...
people.add("Exelord"); // This change will rerun the effect

You can also use the various methods of the Set object, such as delete, clear, and size, to modify the elements of a SignaledSet and trigger updates.

SignaledWeakSet

SignaledWeakSet is a variant of the standard JavaScript WeakSet type that automatically tracks changes to its elements. This means that any operation that modifies the elements of a SignaledWeakSet, such as adding a new element, deleting an element, or checking if an element exists, will trigger an update and make your code react to the change.

Unlike a regular Set, a WeakSet only holds weak references to its elements, which means that the elements can be garbage collected if there are no other references to them. This makes WeakSets useful for storing metadata or other information that you don't want to keep alive longer than necessary.

To use SignaledWeakSet, you can import the createWeakSet function from the solid-proxies library:

import { createWeakSet } from 'solid-proxies';

Then, you can create a new SignaledWeakSet by calling createWeakSet:

const person = { name: "Maciej" };
const people = createWeakSet();

You can then use the SignaledWeakSet like a normal JavaScript WeakSet, but any changes you make to its elements will be tracked and can be reacted to by your code. For example:

createEffect(() => {
  console.log(people.has(person));
});

// After some time...
people.add(person); // This change

You can also use other methods of the WeakSet object to modify the elements of a SignaledWeakSet and trigger updates.