Chalkit NPM | npm.io

Chalkit

A lightweight utility for managing nested state with command-driven operations. Perform atomic updates and batch operations with ease.

Installation

Install via npm:

npm install chalkit

yarn add chalkit

Getting Started

Import and Initialize

import { Chalkit } from "chalkit";

// Initialize store
const store = {};
const chalkit = new Chalkit(store, { marker: "$", divider: "_" });

Basic Operations

Setting and Merging Values

// Set a value in a deep path using the divider
chalkit.apply("user_profile_name$set", { name: "John" });

// Merge values into a deep path
chalkit.apply("user_profile_details$merge", {
  age: 30,
  email: "john@example.com",
});

Clearing Values

// Clear a value in a deep path
chalkit.apply("user_profile_name$remove");

Array Operations

Append to Array

// Append to an array in a deep path
chalkit.apply("user_profile_tags$arrayAppend", {
  data: ["typescript", "javascript"],
});

Toggle Item in Array

// Toggle an item in an array in a deep path
chalkit.apply("user_profile_favorites$arrayToggle", "item1");

Remove from Array

// Remove an item from an array in a deep path
chalkit.apply("user_profile_tags$arrayRemove", { item: "typescript" });

Collection Operations

Set Item in Collection

// Set an item in a collection at a deep path
chalkit.apply("organization_members$itemSet", {
  id: "user1",
  data: { name: "John", age: 30 },
});

Merge Item in Collection

// Merge an item in a collection at a deep path
chalkit.apply("organization_members$itemMerge", {
  id: "user1",
  data: { email: "john@example.com" },
});

Delete Item from Collection

// Delete an item from a collection at a deep path
chalkit.apply("organization_members$itemDelete", "user1");

Batch Operations

Perform Multiple Updates

chalkit.batch([
  { command: "user_profile_name$set", payload: { name: "John" } },
  { command: "settings_theme$set", payload: { theme: "dark" } },
  {
    command: "user_profile_tags$arrayAppend",
    payload: { data: ["typescript"] },
  },
]);

Handle Batch Errors

try {
  chalkit.batch([
    { command: "user_profile_name$set", payload: { name: "John" } },
    { command: "settings_invalid$set", payload: { theme: "dark" } }, // Invalid operation
  ]);
} catch (error) {
  console.log("Batch failed, all changes rolled back");
}