get-set-immutable

get-set-immutable makes it easy to update immutable objects similar to Immer but up to 5 times faster. It can be used inside redux or zustand where it's difficult to work with large complex deeply nested objects. You can also use it as a independent store for any type of js application.

Installation

You can install get-set-immutable via npm:

``bash
npm install get-set-immutable
`

Usage

Check out the example along with benchmarks here:

Here is an example on how you can use i to mutate immutable objects.

`javascript
import { i } from "get-set-immutable";

// obj is an immutable object.
const obj = { count: 0, address: { street: "" } };

// update obj as you would a js object. let the library handle immutability for you.
// this creates a new object without changing original obj.
const newObj = i(obj, (s) => {
s.count = 1;
s.address.street = "street name";
}); // { count: 1, address: { street: "" } }

`

Here is an example of using i inside redux reducer to change the state as you change a js object.

`javascript
function countReducer(state = initialState, action: ActionTypes): CountState {
switch (action.type) {
case SET_STREET:
return i(state, (s) => s.address.street = "new street");
case DECR:
return i(state, (s) => s.count--);
case INCR:
return i(state, (s) => s.count++);
default:
return state;
}
}
`

here is how you can use it as a store.

`javascript
import { i } from "get-set-immutable";

// store without actions or setters or getters.
const store = create({
count: 0,
address: { street: "" },
countDoubled: 0,
});

// store with setters.
const storeWithSetters = create({
address: { street: "" },
setStreet(street) {
this.address.street = street;
},
});

// store with setters and getters.
const storeWithSettersAndGetters = create({
address: { street: "" },
_getStreet() {
return this.address.street;
},
setStreet(street) {
this.address.street = street;
},
});

// store with actions
const storeWithActions = create({
count: 0,
data: null,
incr() {
this.count++;
},
decr() {
this.count--;
},
setData(data) {
this.data = data;
},
// this is an action that can be called
async action_loadData(){
const data = await fetch("https://api.example.com/data");
this.setData(data);
}
});

// returns the current state
store.getState();

// set the state using setter.
storeWithSetters.getState().setStreet("new street");

// call an action
await storeWithActions.action_loadData();


// 3 ways to set the state
store.set({ count: 1 });
// or
store.set((currentState) => ({ ...currentState, count: currentState.count + 1 }));
// or
store.update((state) => {
// mutate the state directly. library will take care of immutability.
state.address.street = "new street";
});


// Subscribe to state changes and log the changes
store.subscribe((changes) => {
console.log("State changed:", changes);
// changes is an array of change object where you can see the the key and value that changed.
});
// react to specific changes
store.react(
(state) => {
state.countDoubled = state.count * 2;
},
// pass a function as second param that returns dependency array
(state) => [state.count]
);
`

$3

`javascript
// Subscribe to state changes
const unsub = state.subscribe((changes) => {
console.log("State changed:", changes);
});

// unsubscribe from state changes
unsub();
`

$3

$3

this is useful when you want to react to state changes. you can listen to entire state or you can listen to portion of it. you can also update state in reaction call back which gets the updated state, and if you want to change the state, you can access state instance's set or update methods.

`javascript
// React to state changes with dependencies
state.react(
(s) => {
// if you want to change the state, you can do that like this:
s.countDoubled = s.count * 2;
console.log("Count changed:", s.count);
},
// pass a function as second param that returns dependency array
(s) => [s.count]
);
`

API

$3

Creates a new get-set-immutable instance with the provided initial state.

- initialState: An object representing the initial state.

Returns an object with the following methods:

- getState(): object returns the current state.
- set(newState: object | (currentState: object) => object): object: Updates the whole state with the provided new state object or a function that returns a new state object based on the current state.

- update(newState: object | (currentState: object) => void): object: updates the portion of the state.

- subscribe(callback: (changes: Change[]) => void): unsubFn: Subscribes to state changes. The callback function will be called whenever the state changes, and it receives an object containing the changes. returns unsubcribe function when called, will remove subscription. each change represents an assign operation done inside the callback of update or setter function. subscriptions are called on a debounce.
`typescript
type Change = {
path: string;
type: "add" | "update" | "delete";
value?: any;
functionName?: string;
fileName?: string;
id: string;
from: "react" | "update" | "set";
}
`
- react(effectFn: (state: object) => void, dependencyArrayFn: (state: object) => any[]): void: Similar to React's useEffect. It takes an effect function and a dependency array function. The effect function is called when the dependencies change.

- reset(): void: Resets the state to its initial state.

- saveVersion(versionName: string): void: Saves the current state as a version.

- getSavedVersion(versionName: string): object`: Gets the saved version.

EOD