Skip to content

Commit

Permalink
Improved Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@Exelord
Exelord committed Dec 29, 2022
1 parent 9b8c17c commit add35c7
Showing 1 changed file with 164 additions and 42 deletions.
206 changes: 164 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,27 @@

# Solid Proxies

This package provides signaled versions of Javascript's built-in objects. Thanks to it, all theirs properties will be automatically tracked while using standard API. That means all operations like array's `push`, `slice` or direct index access `track['me']` will only trigger an update of specific values. The granular reactivity will make sure your effects will not rerun without a need.

Signaled built-ins:

- Object
- Array
- Map
- WeakMap
- Set
- WeakSet
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](#solid-proxies)
- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Compatibility](#compatibility)
- [Demo](#demo)
- [Usage](#usage)
- [SignaledObject](#signaledobject)
- [SignaledArray](#signaledarray)
- [SignaledMap](#signaledmap)
- [SignaledWeakMap](#signaledweakmap)
- [SignaledSet](#signaledset)
- [SignaledWeakSet](#signaledweakset)

## Installation

```
npm i solid-proxies
npm install solid-proxies
```

## Compatibility
Expand All @@ -33,108 +39,224 @@ CodeSandbox demo: [Link](https://codesandbox.io/s/solid-proxies-pt2slm)

### SignaledObject

`SignaledObject` will track all properties changes automatically. Setting new values, deleting, or checking keys will make your code react to changes.
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:

```js
import { createObject } from 'solid-proxies';
```

const user = createObject({ name: "Maciej" })
Then, you can create a new SignaledObject by calling createObject and passing in an object literal as an argument (optionally):

```js
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:

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

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

**Important** SignaledObjects are not deep wrapped. Means an object in SignaledObject would need to be signaled individually.
**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:

```js
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` will track any changes in the array automatically. Setting new values, deleting, or checking keys will make your code react to changes.
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:

```js
import { createArray } from 'solid-proxies';
```

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

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

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:

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

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

**Important** SignaledArrays are not deep wrapped. Means an array or object in SignaledObject would need to be signaled individually.
**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:

```js
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` will track any changes in the Map automatically. Setting new values, deleting, or checking keys will make your code react to changes.
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:

```js
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:

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

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:

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

// After some time...
props.set(1, 'Exelord') // This change will rerun the effect
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` will track any changes in the WeakMap automatically. Setting new values, deleting, or checking keys will make your code react to changes.
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:

```js
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:

```js
const person = { name: "Maciej" };
const people = createWeakMap([[person, ({ name }) => `Hello ${name}!`]])
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:

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

// After some time...
props.set(person, ({ name}) => `Welcome ${name}!`) // This change will rerun the effect
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` will track any changes in the Set automatically. Setting new values, deleting, or checking keys will make your code react to changes.
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:

```js
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:

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

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:

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

// After some time...
props.add("Exelord") // This change will rerun the effect
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` will track any changes in the WeakSet automatically. Setting new values, deleting, or checking keys will make your code react to changes.
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:

```js
import { createWeakSet } from 'solid-proxies';
```

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

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

const person = { name: "Exelord" }
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:

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

// After some time...
props.add(person) // This change will rerun the effect
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.

0 comments on commit add35c7

Please sign in to comment.