Get-set-immutable NPM

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:

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.

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.

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.

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]
);

Setters, Getters and Actions

Similar to mobx, it's possible to define setters and getters on the state. But there is a naming convention to follow.

Getters:

Name must start with underscore "_"
can't change the state directly
Getters are not reactive.

Setters:

Name can't start with underscore "_"
can't be async or return a promise or have timers inside.
Only if setters change the state, then the subscriptions will be called.

Actions:

Name must start with "action_"
can be async or return a promise or have timers inside.
can't change the state directly
they can call setters to change the state, they can also call getters to get the state.

Subscribing to State Changes

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

// unsubscribe from state changes
unsub();

Updating State

Reacting to State Changes with Dependencies

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.

// 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

`create(initialState: object): object`

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.