feat: Introduction of kurama state management

[dilane3]

🔗 Related Issue

RAS

🚀 Type of Change

• 📖 Documentation (Updates to README, API docs, or comments)
• 🐞 Bug Fix (Non-breaking fix for an issue)
• ⚡ Performance (Optimizations for faster execution)
• ✨ Feature (New functionality without breaking changes)
• 🔧 Refactor (Code improvements without changing behavior)
• 🧹 Chore (Build process, tooling, dependencies)
• ⚠️ Breaking Change (Modifications that impact existing usage)

📜 Description

Kurama is a state manager similar to zustand with the same mechanism. It will reinforce the Rasengan.js ecosystem by handling, storing and managing data into a Rasengan.js application.

⚡️ Features

• 🌀 Minimal API – Simple store creation, no boilerplate.
• 💫 Reactive Selectors – Subscribe to specific slices for performance.
• 🧠 Type-safe by Design – Written in TypeScript, fully inferred.
• 🔁 Persistent Stores – Save state to localStorage or custom drivers.
• 🔒 SSR + Hydration – Works seamlessly with Rasengan.js server rendering.
• ⚙️ Middleware System – Extend store behavior (logger, persist, devtools, etc.).
• 🧩 Framework Agnostic – Works in Rasengan.js, Next.js, Remix, React Router & more.

🦾 Quick Start

import { createStore } from '@rasenganjs/kurama';

type CounterState = {
  count: number;
  increment: () => void;
  decrement: () => void;
};

export const useCounter = createStore<CounterState>((set) => ({
  count: 0,
  increment: () => set((s) => ({ count: s.count + 1 })),
  decrement: () => set((s) => ({ count: s.count - 1 })),
}));

// Use it anywhere
function Counter() {
  const { count, increment, decrement } = useCounter();
  return (
    <>
      <button onClick={increment}>+</button>
      <button onClick={decrement}>-</button>
      Chakra Power: {count}
    </>
  );
}

There is also a middleware system supported with two middlewares already included into this PR

• Logger: To log state changes after any updates. Perfect for debugging purpose

import { createStore, middleware } from '@rasenganjs/kurama';

export const useStore = createStore(
  middleware.logger((set) => ({
    chakra: 100,
    decrease: () => set((s) => ({ chakra: s.chakra - 10 })),
  }))
);

• Persist: To save the state permanently into either a localstorage or a session storage.

import { middleware, createStore } from '@rasenganjs/kurama';

export type ThemeState = {
  mode: 'light' | 'dark';
  toggle: () => void;
};

export const useTheme = createStore<ThemeState>(
  middleware.persist({ name: 'theme', storage: 'session' })((set) => ({
    mode: 'light',
    toggle: () => set((s) => ({ mode: s.mode === 'light' ? 'dark' : 'light' })),
  }))
);

✅ Checklist

• I have linked a related issue or discussion.
• I have updated documentation if needed.
• I have tested the changes in a real project.
• I have added tests or confirmed that existing tests pass.