fractostate 1.0.1 → 1.0.2

package/docs/architecture.md

@@ -1,27 +0,0 @@
-# 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

@@ -1,94 +0,0 @@
-# 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/src/index.ts

@@ -1,82 +0,0 @@
-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];
-}

package/src/proxy.ts

@@ -1,313 +0,0 @@
-import type { FlowOptions, TypeAwareOps } from "./types";
-import { store } from "./store";
-
-/**
- * Creates a deep proxy that provides type-specific atomic operations for a flow.
- * The proxy tracks its path within the state tree and maps access to specific update logic.
- */
-export function createDeepProxy<T = any>(
-  key: string,
-  path: string[],
-  currentVal: any,
-  options: FlowOptions<any>,
-): TypeAwareOps<T> {
-  return new Proxy(() => {}, {
-    get(_target: any, prop: any) {
-      if (typeof prop === "symbol") return undefined;
-
-      const newPath = [...path, prop];
-
-      // --- Meta-Operations ---
-
-      // Generic property replacement
-      if (prop === "set") {
-        return (val: any) => {
-          try {
-            const currentState = store.get(key, undefined);
-            const newState = setInPath(currentState, path, val);
-            store.set(key, newState, options);
-          } catch (error) {
-            console.error(
-              `[FlowProxy] Error setting value at path ${path.join(".")}:`,
-              error,
-            );
-            throw error;
-          }
-        };
-      }
-
-      // --- Type-Specific Atomic Operations ---
-
-      // Number Operations
-      if (typeof currentVal === "number") {
-        if (prop === "increment")
-          return (amount = 1) => {
-            if (typeof amount !== "number" || !isFinite(amount)) {
-              console.warn(`[FlowProxy] Invalid increment amount: ${amount}`);
-              return;
-            }
-            update(currentVal + amount);
-          };
-        if (prop === "decrement")
-          return (amount = 1) => {
-            if (typeof amount !== "number" || !isFinite(amount)) {
-              console.warn(`[FlowProxy] Invalid decrement amount: ${amount}`);
-              return;
-            }
-            update(currentVal - amount);
-          };
-        if (prop === "add")
-          return (amount: number) => {
-            if (typeof amount !== "number" || !isFinite(amount)) {
-              console.warn(`[FlowProxy] Invalid add amount: ${amount}`);
-              return;
-            }
-            update(currentVal + amount);
-          };
-        if (prop === "subtract")
-          return (amount: number) => {
-            if (typeof amount !== "number" || !isFinite(amount)) {
-              console.warn(`[FlowProxy] Invalid subtract amount: ${amount}`);
-              return;
-            }
-            update(currentVal - amount);
-          };
-        if (prop === "multiply")
-          return (amount: number) => {
-            if (typeof amount !== "number" || !isFinite(amount)) {
-              console.warn(`[FlowProxy] Invalid multiply amount: ${amount}`);
-              return;
-            }
-            update(currentVal * amount);
-          };
-        if (prop === "divide")
-          return (amount: number) => {
-            if (typeof amount !== "number" || !isFinite(amount)) {
-              console.warn(`[FlowProxy] Invalid divide amount: ${amount}`);
-              return;
-            }
-            if (amount === 0) {
-              console.error(`[FlowProxy] Cannot divide by zero`);
-              return;
-            }
-            update(currentVal / amount);
-          };
-      }
-
-      // Array Operations
-      if (Array.isArray(currentVal)) {
-        if (prop === "push")
-          return (item: any) => update([...currentVal, item]);
-        if (prop === "pop")
-          return () => {
-            if (currentVal.length === 0) {
-              console.warn(`[FlowProxy] Cannot pop from empty array`);
-              return;
-            }
-            update(currentVal.slice(0, -1));
-          };
-        if (prop === "shift")
-          return () => {
-            if (currentVal.length === 0) {
-              console.warn(`[FlowProxy] Cannot shift from empty array`);
-              return;
-            }
-            update(currentVal.slice(1));
-          };
-        if (prop === "unshift")
-          return (item: any) => update([item, ...currentVal]);
-        if (prop === "filter")
-          return (fn: any) => {
-            if (typeof fn !== "function") {
-              console.error(`[FlowProxy] Filter requires a function`);
-              return;
-            }
-            try {
-              update(currentVal.filter(fn));
-            } catch (error) {
-              console.error(`[FlowProxy] Filter function threw error:`, error);
-            }
-          };
-        if (prop === "map")
-          return (fn: any) => {
-            if (typeof fn !== "function") {
-              console.error(`[FlowProxy] Map requires a function`);
-              return;
-            }
-            try {
-              update(currentVal.map(fn));
-            } catch (error) {
-              console.error(`[FlowProxy] Map function threw error:`, error);
-            }
-          };
-        if (prop === "splice")
-          return (...args: any[]) => {
-            try {
-              const next = [...currentVal];
-              const start = args[0] ?? 0;
-              const deleteCount = args[1] ?? 0;
-
-              if (
-                typeof start !== "number" ||
-                typeof deleteCount !== "number"
-              ) {
-                console.error(`[FlowProxy] Splice requires numeric arguments`);
-                return;
-              }
-
-              next.splice(start, deleteCount, ...args.slice(2));
-              update(next);
-            } catch (error) {
-              console.error(`[FlowProxy] Splice error:`, error);
-            }
-          };
-        if (prop === "removeAt")
-          return (index: number) => {
-            if (
-              typeof index !== "number" ||
-              index < 0 ||
-              index >= currentVal.length
-            ) {
-              console.warn(`[FlowProxy] Invalid index: ${index}`);
-              return;
-            }
-            update(currentVal.filter((_, i) => i !== index));
-          };
-        if (prop === "insertAt")
-          return (index: number, item: any) => {
-            if (
-              typeof index !== "number" ||
-              index < 0 ||
-              index > currentVal.length
-            ) {
-              console.warn(`[FlowProxy] Invalid index: ${index}`);
-              return;
-            }
-            const next = [...currentVal];
-            next.splice(index, 0, item);
-            update(next);
-          };
-      }
-
-      // String Operations
-      if (typeof currentVal === "string") {
-        if (prop === "append")
-          return (str: string) => {
-            if (typeof str !== "string") {
-              console.warn(`[FlowProxy] Append requires a string`);
-              return;
-            }
-            update(currentVal + str);
-          };
-        if (prop === "prepend")
-          return (str: string) => {
-            if (typeof str !== "string") {
-              console.warn(`[FlowProxy] Prepend requires a string`);
-              return;
-            }
-            update(str + currentVal);
-          };
-        if (prop === "uppercase") return () => update(currentVal.toUpperCase());
-        if (prop === "lowercase") return () => update(currentVal.toLowerCase());
-        if (prop === "trim") return () => update(currentVal.trim());
-        if (prop === "replace")
-          return (search: string | RegExp, replace: string) => {
-            if (typeof replace !== "string") {
-              console.warn(`[FlowProxy] Replace requires a string replacement`);
-              return;
-            }
-            try {
-              update(currentVal.replace(search, replace));
-            } catch (error) {
-              console.error(`[FlowProxy] Replace error:`, error);
-            }
-          };
-      }
-
-      // Object Operations
-      if (
-        currentVal !== null &&
-        typeof currentVal === "object" &&
-        !Array.isArray(currentVal)
-      ) {
-        if (prop === "merge")
-          return (obj: any) => {
-            if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
-              console.warn(`[FlowProxy] Merge requires an object`);
-              return;
-            }
-            update({ ...currentVal, ...obj });
-          };
-        if (prop === "delete")
-          return (keyToDel: string) => {
-            if (typeof keyToDel !== "string") {
-              console.warn(`[FlowProxy] Delete requires a string key`);
-              return;
-            }
-            if (!(keyToDel in currentVal)) {
-              console.warn(`[FlowProxy] Key "${keyToDel}" does not exist`);
-              return;
-            }
-            const next = { ...currentVal };
-            delete next[keyToDel];
-            update(next);
-          };
-      }
-
-      /**
-       * Internal helper to commit a value update to the store.
-       */
-      function update(val: any) {
-        try {
-          const currentState = store.get(key, undefined);
-          const newState = setInPath(currentState, path, val);
-          store.set(key, newState, options);
-        } catch (error) {
-          console.error(
-            `[FlowProxy] Error updating value at path ${path.join(".")}:`,
-            error,
-          );
-          throw error;
-        }
-      }
-
-      // Recursive step: create a new proxy for the child property
-      const nextVal = currentVal ? currentVal[prop] : undefined;
-      return createDeepProxy(key, newPath, nextVal, options);
-    },
-  }) as unknown as TypeAwareOps<T>;
-}
-
-/**
- * Immutable update utility that sets a value at a specific path within an object/array.
- */
-export function setInPath(obj: any, path: string[], value: any): any {
-  if (path.length === 0) return value;
-
-  const [head, ...tail] = path;
-
-  if (Array.isArray(obj)) {
-    const index = parseInt(head, 10);
-
-    if (isNaN(index) || index < 0) {
-      throw new Error(`[FlowProxy] Invalid array index: ${head}`);
-    }
-
-    const newArr = [...obj];
-
-    if (index >= newArr.length) {
-      newArr.length = index + 1;
-    }
-
-    newArr[index] = setInPath(newArr[index], tail, value);
-    return newArr;
-  }
-
-  // Handle nested objects (including null/undefined recovery)
-  const currentObj = obj ?? {};
-
-  return {
-    ...currentObj,
-    [head]: setInPath(currentObj[head], tail, value),
-  };
-}