set-this v1.0.0

set immutable state easily

A TypeScript utility library for immutable state management, providing a collection of functions to manipulate objects and arrays while maintaining immutability.

Installation

npm install set-this

Usage

Import the utilities you need:

import { set, push, incr, toggle.... } from 'set-this';

Core Concept

All functions take an initial state object and return a new state object, never mutating the original state.

API Reference

Basic Operations

set<T>(obj: T, path: string, value: any): T

Sets a value at the specified path.

const state = { user: { name: "John", age: 25 } };

// Using direct value
const newState1 = set(state, "user", { name: "Jane", age: 25 });
// Result: { user: { name: "Jane", age: 25 } }

// Using callback function
const newState2 = set(state, "user.age", (age) => age + 5);
// Result: { user: { name: "John", age: 30 } }

incr<T>(obj: T, path: string): T

Increments a number value at the specified path.

const state = { counter: 5, stats: { views: 100 } };

const newState1 = incr(state, "counter");
// Result: { counter: 6, stats: { views: 100 } }

const newState2 = incr(state, "stats.views");
// Result: { counter: 5, stats: { views: 101 } }

decr<T>(obj: T, path: string): T

Decrements a number value at the specified path.

const state = { counter: 5, stats: { views: 100 } };

const newState1 = decr(state, "counter");
// Result: { counter: 4, stats: { views: 100 } }

const newState2 = decr(state, "stats.views");
// Result: { counter: 5, stats: { views: 99 } }

Array Operations

push<T>(obj: T, path: string, value: any): T

Adds an item to the end of an array.

const state = { todos: ["Buy milk", ["apple", "banana"]]};

const newState1 = push(state, "todos.1", "orange");
// Result: { todos: ["Buy milk", ["apple", "banana", "orange"]] }

const newState2 = push(state, "todos", "Walk dog");
// result: { todos: ["Buy milk", ["apple", "banana"], "Walk dog"] }

pop<T>(obj: T, path: string): T

Removes the last item from an array.

const state = { todos: ["Buy milk", "Buy eggs", "Walk dog"] };

const newState1 = pop(state, "todos");
// Result: { todos: ["Buy milk", "Buy eggs"] }

const newState2 = pop(newState1, "todos");
// Result: { todos: ["Buy milk"] }

unshift<T>(obj: T, path: string, value: any): T

Adds an item to the beginning of an array.

const state = { queue: ["User2", "User3"] };

const newState1 = unshift(state, "queue", "User1");
// Result: { queue: ["User1", "User2", "User3"] }

const newState2 = unshift(state, "queue", "User0");
// Result: { queue: ["User0", "User2", "User3"] }

shift<T>(obj: T, path: string): T

Removes the first item from an array.

const state = { queue: ["User1", "User2", "User3"] };

const newState1 = shift(state, "queue");
// Result: { queue: ["User2", "User3"] }

const newState2 = shift(newState1, "queue");
// Result: { queue: ["User3"] }

splice<T>(obj: T, path: string, start: number, deleteCount: number, items: any[]): T

Modifies an array by removing or replacing existing elements and/or adding new elements.

const state = { letters: ["a", "b", "c", "d"] };

const newState1 = splice(state, "letters", 1, 2, ["x", "y"]);
// Result: { letters: ["a", "x", "y", "d"] }

const newState2 = splice(state, "letters", 0, 1, ["z"]);
// Result: { letters: ["z", "b", "c", "d"] }

deleteFromIndex<T>(obj: T, path: string, index: number): T

Removes an item at the specified index.

const state = { items: ["first", "second", "third"] };

const newState1 = deleteFromIndex(state, "items", 1);
// Result: { items: ["first", "third"] }

const newState2 = deleteFromIndex(state, "items", 0);
// Result: { items: ["second", "third"] }

addAtIndex<T>(obj: T, path: string, index: number, item: any): T

Adds an item at the specified index.

const state = { items: ["first", "third"] };

const newState1 = addAtIndex(state, "items", 1, "second");
// Result: { items: ["first", "second", "third"] }

const newState2 = addAtIndex(state, "items", 0, "zero");
// Result: { items: ["zero", "first", "third"] }

replaceAtIndex<T>(obj: T, path: string, index: number, item: any): T

Replaces an item at the specified index.

const state = { items: ["old", "keep", "replace"] };

const newState1 = replaceAtIndex(state, "items", 2, "new");
// Result: { items: ["old", "keep", "new"] }

const newState2 = replaceAtIndex(state, "items", 0, "start");
// Result: { items: ["start", "keep", "replace"] }

Array Transformations

map<T>(obj: T, path: string, fn: (item: any) => any): T

Maps over an array using the provided function.

const state = { numbers: [1, 2, 3] };

const newState1 = map(state, "numbers", (n) => n * 2);
// Result: { numbers: [2, 4, 6] }

const newState2 = map(state, "numbers", (n) => `Item \${n}`);
// Result: { numbers: ["Item 1", "Item 2", "Item 3"] }

filter<T>(obj: T, path: string, fn: (item: any) => boolean): T

Filters an array using the provided function.

const state = { numbers: [1, 2, 3, 4, 5] };

const newState1 = filter(state, "numbers", (n) => n % 2 === 0);
// Result: { numbers: [2, 4] }

const newState2 = filter(state, "numbers", (n) => n > 3);
// Result: { numbers: [4, 5] }

Boolean Operations

toTrue<T>(obj: T, path: string): T

Sets a boolean value to true.

const state = { settings: { darkMode: false, notifications: false } };

const newState1 = toTrue(state, "settings.darkMode");
// Result: { settings: { darkMode: true, notifications: false } }

const newState2 = toTrue(state, "settings.notifications");
// Result: { settings: { darkMode: false, notifications: true } }

toFalse<T>(obj: T, path: string): T

Sets a boolean value to false.

const state = { settings: { darkMode: true, notifications: true } };

const newState1 = toFalse(state, "settings.darkMode");
// Result: { settings: { darkMode: false, notifications: true } }

const newState2 = toFalse(state, "settings.notifications");
// Result: { settings: { darkMode: true, notifications: false } }

toggle<T>(obj: T, path: string): T

Toggles a boolean value.

const state = { settings: { darkMode: true, notifications: false } };

const newState1 = toggle(state, "settings.darkMode");
// Result: { settings: { darkMode: false, notifications: false } }

const newState2 = toggle(state, "settings.notifications");
// Result: { settings: { darkMode: true, notifications: true } }

Utility Functions

deepClone<T>(obj: T): T

Creates a deep clone of an object.

const state = { 
  user: { name: "John", settings: { theme: "dark" } },
  posts: [{ id: 1, title: "Hello" }]
};

const clonedState1 = deepClone(state);
// Creates a completely new copy of the state

const clonedState2 = deepClone(state.user);
// Creates a copy of just the user object

License

MIT (or your preferred license)