fractostate 1.0.0

package/LICENSE

@@ -0,0 +1,13 @@
+NEHONIX Open Source License (NOSL) v1.0
+
+Copyright (c) 2025 NEHONIX - www.nehonix.com
+
+This License governs the use, modification, and distribution of software provided by NEHONIX under its open source projects. NEHONIX is committed to fostering collaborative innovation while strictly protecting its intellectual property rights. Violation of any term of this License will result in immediate termination of all granted rights and may subject the violator to legal action.
+
+The full version of this license is available at: https://dll.nehonix.com/licenses/NOSL
+
+> **DISCLAIMER OF WARRANTY**  
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+> **LIMITATION OF LIABILITY**  
+> IN NO EVENT SHALL NEHONIX BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

package/README.md

@@ -0,0 +1,83 @@
+# FractoState: Think Fractal. Code Simple.
+
+<p align="center">
+  <img src="https://dll.nehonix.com/assets/FractoState/logo.png" alt="FractoState Logo" width="600" />
+</p>
+
+FractoState is a high-performance, decentralized state management library for React. It is engineered to provide surgical state updates with zero boilerplate, absolute type safety, and an architecture that exists independently of the React component tree.
+
+## See it in Action
+
+<p align="center">
+  <video
+    src="https://dll.nehonix.com/assets/FractoState/fracto_demo.mp4"
+    width="100%"
+    controls
+    loop
+    muted
+  ></video>
+</p>
+
+> ⚠️ **GitHub Limitation**  
+> Autoplay is disabled on GitHub. Click the link below to view the demo video.
+
+<p align="center">
+  <a href="https://dll.nehonix.com/assets/FractoState/fracto_demo.mp4">
+    ▶️ <strong>Watch the FractoState Demo (MP4)</strong>
+  </a>
+</p>
+
+## The Problem
+
+Traditional state management solutions often suffer from specific architectural bottlenecks:
+
+1.  **Prop-Drilling & Context Overhead**: Managing shared state requires wrapping the application in multiple providers, often leading to unnecessary re-renders of the entire sub-tree when a small value changes.
+2.  **Boilerplate Complexity**: Redux and similar libraries introduce a heavy cognitive load with actions, reducers, and selectors for even the simplest state transitions.
+3.  **Performance Degit**: JavaScript's standard object handling for deep state often forces developers into expensive deep-cloning patterns for every modification.
+4.  **Security Risks**: Application state is often stored in plain objects easily accessible via browser dev tools or memory dumps.
+
+## The Solution
+
+FractoState transforms state management into a "Side-Car" service through three core innovations:
+
+- **Secure Memory Vault**: State is isolated in a private JavaScript instance. Data is stored in an obfuscated format to prevent easy inspection and is protected against unauthorized global access.
+- **Surgical Proxy Mutations**: Instead of manually handling immutability, FractoState uses recursive Proxies. You interact with state as if it were a direct object, while the engine performs atomic, immuable updates under the hood.
+- **Provider-less Decoupling**: Components subscribe directly to the Vault. This eliminates the need for context providers and ensures that state updates only trigger re-renders in the exact components that consume the modified data.
+
+## Quick Example
+
+Setting up a shared ecommerce cart state:
+
+```tsx
+import { defineFlow, useFlow } from "fractostate";
+
+// 1. Define the business logic flow
+const CartFlow = defineFlow("cart", { items: [], total: 0 });
+
+// 2. Consume and modify in any component
+function AddToCartButton({ product }) {
+  const [, { ops }] = useFlow(CartFlow);
+
+  return (
+    <button onClick={() => ops.self.items.push(product)}>Add to Cart</button>
+  );
+}
+
+// 3. React to updates elsewhere
+function CartIcon() {
+  const [cart] = useFlow(CartFlow);
+  return <span>{cart.items.length} items</span>;
+}
+```
+
+## Documentation
+
+For detailed information on the library, please refer to the modular documentation files:
+
+- [Architecture Overview](./docs/architecture.md): Deep dive into the Vault and Proxy engine.
+- [Getting Started](./docs/getting-started.md): Installation and basic setup guide.
+- [API Reference](./docs/api-reference.md): Detailed documentation of hooks and operations.
+
+---
+
+FractoState - Engineered for Performance. Created for Developers.

package/docs/api-reference.md

@@ -0,0 +1,46 @@
+# API Reference
+
+A detailed breakdown of the FractoState interface.
+
+## defineFlow<T>(key, initialValue, options?)
+
+Creates a reusable definition for a state flow.
+
+- **key**: A unique string identifying the flow in the global vault.
+- **initialValue**: The default state structure.
+- **options**: Configuration object (timeTravel, debounce, middleware).
+
+Returns a `FlowDefinition<T>`.
+
+## useFlow<T>(identifier, initialValue?, options?)
+
+The primary hook to interact with the state vault.
+
+- **identifier**: Either a string `key` or a `FlowDefinition`.
+- **initialValue**: Required only if identifier is a string and the flow hasn't been initialized.
+- **options**: Overrides for the flow configuration.
+
+Returns `[state, toolbox]`.
+
+### The Toolbox Object
+
+The second element returned by `useFlow` provides powerful control:
+
+- **ops.self**: A recursive proxy providing type-aware methods:
+  - **Numbers**: `increment()`, `decrement()`, `add()`, `multiply()`, `divide()`, `set()`.
+  - **Strings**: `append()`, `prepend()`, `uppercase()`, `replace()`, `set()`.
+  - **Arrays**: `push()`, `pop()`, `filter()`, `map()`, `insertAt()`, `removeAt()`, `set()`.
+  - **Objects**: `merge()`, `delete()`, `set()`.
+- **set(value | fn)**: Manually sets the entire state or applies a transformation function.
+- **undo()**: Reverts to the previous state.
+- **redo()**: Restores the previously undone state.
+- **history**: The full history buffer of the flow.
+- **canUndo / canRedo**: Boolean flags for UI control.
+- **reset()**: Restores the state to its defined initial value.
+
+## FlowOptions
+
+- **timeTravel**: Enable undo/redo functionality (default: false).
+- **maxHistory**: Maximum number of states maintained in the circular buffer (default: 100).
+- **debounce**: Delay in milliseconds before state updates are applied.
+- **middleware**: Array of functions `(state) => state` to intercept and transform values during updates.

package/docs/architecture.md

@@ -0,0 +1,27 @@
+# Architecture: Secure Memory Vault
+
+FractoState operates on a paradigm shift in state management. Instead of relying on a hierarchical data flow injected through component trees, it utilizes a decentralized, side-car architecture.
+
+## The Memory Vault
+
+At the core of FractoState is the SecureVault. This is a pure JavaScript singleton that exists independently of the React lifecycle. It holds the application state in a protected memory space.
+
+### Security and Isolation
+
+Data within the Vault is stored in an obfuscated format. This prevents simple memory inspection and ensures that user data is not readily available in plain text within the browser's RAM. Access is strictly controlled through the FractoState internal engine, returning copies of the data to components to prevent accidental direct mutations.
+
+## Proxy-Based Mutation Engine
+
+FractoState leverages JavaScript Proxies to provide a surgical update mechanism. When you access `ops.self`, you are interacting with a recursive proxy that maps your state structure to specific atomic operations.
+
+### Type-Aware Operations
+
+The proxy identifies the data type at any given path (Number, String, Array, or Object) and presents relevant, type-safe methods. This allows for complex state updates—like pushing to a nested array or merging into a deep object—without the need for manual immutability boilerplate.
+
+## Decoupled React Integration
+
+The `useFlow` hook acts as a high-performance bridge. It subscribes components to specific segments of the Vault.
+
+- **Selective Re-rendering**: Components are only notified when the specific key they are watching is updated.
+- **Provider-less Execution**: Since the store is external, there is no need for context providers. This eliminates the "Wrapper Hell" and ensures that any component, at any depth, can access state with zero performance penalty.
+- **Microtask Batching**: Multiple state changes within the same execution cycle are batched into a single microtask, ensuring optimal UI performance and preventing unnecessary render cycles.

package/docs/getting-started.md

@@ -0,0 +1,94 @@
+# Getting Started with FractoState
+
+This guide will walk you through the integration of FractoState into a React application.
+
+## Installation
+
+Ensure you have the library within your project's source directory (currently in development).
+
+## Core Concepts
+
+FractoState is built around "Flows". A Flow is a reactive stream of data identified by a unique key.
+
+### 1. Defining a Flow
+
+Centralize your state structure and initial values using `defineFlow`. This promotes reusability and type safety.
+
+```typescript
+// store/flows.ts
+import { defineFlow } from "fractostate";
+
+export const UserFlow = defineFlow("user", {
+  name: "Default User",
+  settings: { theme: "dark" },
+});
+```
+
+### 2. Using a Flow in a Component
+
+Use the `useFlow` hook to connect any component to the state.
+
+```tsx
+import { useFlow } from "fractostate";
+import { UserFlow } from "./store/flows";
+
+export default function Profile() {
+  const [state, { ops }] = useFlow(UserFlow);
+
+  return (
+    <div>
+      <h1>User: {state.name}</h1>
+      <button onClick={() => ops.self.name.set("New Name")}>Update Name</button>
+    </div>
+  );
+}
+```
+
+### 3. Sharing State Across Components
+
+To consume or modify the same state in another component, simply use the same `UserFlow` definition. No providers or context required.
+
+```tsx
+import { useFlow } from "fractostate";
+import { UserFlow } from "./store/flows";
+
+export default function Sidebar() {
+  const [state] = useFlow(UserFlow); // Automatically synchronizes with the Profile component
+  return <aside>Active theme: {state.settings.theme}</aside>;
+}
+```
+
+### 4. Advanced Configuration
+
+You can enable features like Time Travel or Middleware directly in the definition or the hook.
+
+```typescript
+// Enable Undo/Redo and middleware for logging
+export const CartFlow = defineFlow(
+  "cart",
+  { items: [] },
+  {
+    timeTravel: true,
+    middleware: [
+      (state) => {
+        console.log("Cart updated:", state);
+        return state;
+      },
+    ],
+  },
+);
+```
+
+Using Time Travel in a component:
+
+```tsx
+function CartControls() {
+  const [cart, { undo, redo, canUndo }] = useFlow(CartFlow);
+
+  return (
+    <button onClick={undo} disabled={!canUndo}>
+      Undo Last Item
+    </button>
+  );
+}
+```

package/package.json

@@ -0,0 +1,37 @@
+{
+  "author": "Nehonix-Team",
+  "dependencies": {
+    "vite": "^7.3.1"
+  },
+  "description": "FractoState is a high-performance, decentralized state management library for React. It is engineered to provide surgical state updates with zero boilerplate, absolute type safety, and an architecture that exists independently of the React component tree.",
+  "devDependencies": {
+    "@types/react": "^19.2.9",
+    "react": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "react",
+    "state",
+    "management",
+    "fractal",
+    "global state",
+    "hooks"
+  ],
+  "license": "N",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "name": "fractostate",
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --dts --format esm,cjs",
+    "dev": "tsup src/index.ts --watch --dts --format esm,cjs",
+    "lint": "eslint src",
+    "test": "vitest"
+  },
+  "types": "dist/index.d.ts",
+  "version": "1.0.0"
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+import { useState, useEffect, useCallback, useMemo } from "react";
+import type { FlowOptions, FlowOperations, FlowDefinition } from "./types";
+import { store } from "./store";
+import { createDeepProxy } from "./proxy";
+
+export * from "./types";
+
+/**
+ * Defines a flow in a centralized manner.
+ * Allows defining the key, initial state, and options in a single reusable object.
+ */
+export function defineFlow<T>(
+  key: string,
+  initial: T,
+  options?: FlowOptions<T>,
+): FlowDefinition<T> {
+  return { key, initial, options };
+}
+
+/**
+ * Unique "All-in-One" hook to create or consume a FractoState flow.
+ * - If called with a FlowDefinition or an initial value: initializes the flow if it doesn't exist.
+ * - If called with just a key: connects to the existing flow.
+ *
+ * Returns a 2-element array: [state, toolbox]
+ * where toolbox contains { ops, set, undo, redo, history, ... }
+ */
+export function useFlow<T>(
+  keyOrDef: string | FlowDefinition<T>,
+  maybeInitialValue?: T,
+  options: FlowOptions<T> = {},
+): [T, FlowOperations<T>] {
+  // Argument analysis to unify initialization and consumption
+  const isDef = typeof keyOrDef !== "string";
+  const key = isDef ? keyOrDef.key : keyOrDef;
+
+  // Initial data comes either from the definition or the direct argument
+  const initialValue = isDef ? keyOrDef.initial : maybeInitialValue;
+
+  // Merge options
+  const opt = isDef ? { ...keyOrDef.options, ...options } : options;
+
+  // Store access: store.get handles initialization if initialValue is present
+  const [state, setState] = useState(() => store.get(key, initialValue));
+
+  useEffect(() => {
+    // Subscribe to store changes
+    const unsub = store.subscribe(key, () => {
+      setState(store.get(key, initialValue));
+    });
+    return unsub;
+  }, [key, initialValue]);
+
+  const setManual = useCallback(
+    (val: T | ((prev: T) => T)) => {
+      const current = store.get(key, initialValue);
+      const next = typeof val === "function" ? (val as any)(current) : val;
+      store.set(key, next, opt);
+    },
+    [key, initialValue, opt],
+  );
+
+  const toolbox = useMemo((): FlowOperations<T> => {
+    return {
+      ops: {
+        get self() {
+          return createDeepProxy<T>(key, [], store.get(key, initialValue), opt);
+        },
+      },
+      set: setManual,
+      undo: () => store.undo(key),
+      redo: () => store.redo(key),
+      history: store.getHistory(key),
+      canUndo: store.getHistory(key).length > 1,
+      canRedo: store.getRedoStack(key).length > 0,
+      reset: () => store.reset(key),
+      cf: opt,
+    };
+  }, [key, opt, state, initialValue, setManual]);
+
+  return [state, toolbox];
+}