fractostate 1.0.0

package/src/proxy.ts

@@ -0,0 +1,313 @@
+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),
+  };
+}

package/src/store.ts

@@ -0,0 +1,324 @@
+import type { FlowOptions } from "./types";
+
+/**
+ * Fast & Secure Memory Vault
+ * Ultra-performant in-memory store with deep cloning and batching
+ * NO PERSISTENCE - Pure memory for maximum safety and speed
+ */
+class SecureVault {
+  private vault = new Map<string, any>();
+  private initialValues = new Map<string, any>();
+  private listeners = new Map<string, Set<() => void>>();
+  private histories = new Map<string, CircularBuffer<any>>();
+  private redoStacks = new Map<string, any[]>();
+  private debounceTimers = new Map<string, number>();
+  private batchQueue = new Set<string>();
+  private batchScheduled = false;
+
+  constructor() {
+    this.setupSecureAccess();
+    this.setupAutoCleanup();
+  }
+
+  /**
+   * Protects the vault instance from global window inspection.
+   */
+  private setupSecureAccess() {
+    if (typeof window !== "undefined") {
+      Object.defineProperty(window, "__FRACTO_VAULT__", {
+        get: () => "🔒 Access Denied: Secure Memory Instance",
+        configurable: false,
+      });
+    }
+  }
+
+  /**
+   * Periodically cleans up orphaned listeners.
+   */
+  private setupAutoCleanup() {
+    if (typeof setInterval !== "undefined") {
+      setInterval(() => {
+        this.listeners.forEach((set, key) => {
+          if (set.size === 0 && !this.vault.has(key)) {
+            this.listeners.delete(key);
+          }
+        });
+      }, 300000); // 5 min
+    }
+  }
+
+  /**
+   * Lightweight but ultra-fast obfuscation for memory protection.
+   */
+  private obfuscate(data: any): any {
+    if (data === undefined) return undefined;
+    try {
+      const str = JSON.stringify(data);
+      // Simple scrambling to prevent plain-text memory inspection
+      return { _: btoa(encodeURIComponent(str)), t: Date.now() };
+    } catch {
+      return data;
+    }
+  }
+
+  /**
+   * Reverts obfuscation to retrieve original data structure.
+   */
+  private deobfuscate(vaultItem: any): any {
+    if (!vaultItem || typeof vaultItem !== "object" || !vaultItem._)
+      return vaultItem;
+    try {
+      const decoded = decodeURIComponent(atob(vaultItem._));
+      return JSON.parse(decoded);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Retrieves state from the vault. Initializes if a value is provided and the key is missing.
+   */
+  get(key: string, initialValue?: any) {
+    if (!this.vault.has(key)) {
+      if (initialValue === undefined) return undefined;
+
+      const cloned = deepClone(initialValue);
+      this.vault.set(key, this.obfuscate(cloned));
+      this.initialValues.set(key, deepClone(cloned));
+      this.histories.set(key, new CircularBuffer(100, [cloned]));
+      this.redoStacks.set(key, []);
+    }
+
+    const val = this.deobfuscate(this.vault.get(key));
+    return val === undefined ? initialValue : val;
+  }
+
+  /**
+   * Updates state in the vault with optional debouncing and middleware support.
+   */
+  set(key: string, newValue: any, options: FlowOptions = {}) {
+    const prevState = this.deobfuscate(this.vault.get(key));
+    let stateToSet = deepClone(newValue);
+
+    // Apply synchronous middleware
+    if (options.middleware) {
+      for (const fn of options.middleware) {
+        stateToSet = fn(stateToSet);
+      }
+    }
+
+    // Skip update if state has not changed (Deep equality check)
+    if (deepEqual(prevState, stateToSet)) return;
+
+    if (options.debounce) {
+      this.debouncedSet(key, stateToSet, options);
+      return;
+    }
+
+    this.applySet(key, stateToSet, options);
+  }
+
+  /**
+   * Executes a debounced state update.
+   */
+  private debouncedSet(key: string, value: any, options: FlowOptions) {
+    const existing = this.debounceTimers.get(key);
+    if (existing) clearTimeout(existing);
+
+    const timer = setTimeout(() => {
+      this.applySet(key, value, options);
+      this.debounceTimers.delete(key);
+    }, options.debounce);
+
+    this.debounceTimers.set(key, timer as any);
+  }
+
+  /**
+   * Core logic for applying a state update and managing history.
+   */
+  private applySet(key: string, stateToSet: any, options: FlowOptions) {
+    this.vault.set(key, this.obfuscate(stateToSet));
+
+    if (options.timeTravel) {
+      const history = this.histories.get(key);
+      if (history) history.push(deepClone(stateToSet));
+      const redo = this.redoStacks.get(key);
+      if (redo) redo.length = 0;
+    }
+
+    this.scheduleBatchNotify(key);
+  }
+
+  /**
+   * Schedules a microtask to batch notifications and optimize React renders.
+   */
+  private scheduleBatchNotify(key: string) {
+    this.batchQueue.add(key);
+    if (this.batchScheduled) return;
+    this.batchScheduled = true;
+    queueMicrotask(() => this.flushBatchNotify());
+  }
+
+  /**
+   * Flushes and notifies all queued listeners.
+   */
+  private flushBatchNotify() {
+    const keys = Array.from(this.batchQueue);
+    this.batchQueue.clear();
+    this.batchScheduled = false;
+    keys.forEach((key) => this.notify(key));
+  }
+
+  /**
+   * Connects a listener to a specific flow key.
+   */
+  subscribe(key: string, listener: () => void) {
+    if (!this.listeners.has(key)) this.listeners.set(key, new Set());
+    this.listeners.get(key)!.add(listener);
+    return () => {
+      this.listeners.get(key)?.delete(listener);
+    };
+  }
+
+  /**
+   * Directly notifies all listeners of a specific key.
+   */
+  private notify(key: string) {
+    this.listeners.get(key)?.forEach((l) => l());
+  }
+
+  /**
+   * Reverts the state to the previous version in history.
+   */
+  undo(key: string) {
+    const history = this.histories.get(key);
+    const redo = this.redoStacks.get(key);
+    if (history && history.length() > 1) {
+      const current = history.pop();
+      if (current) redo?.push(current);
+      const prev = history.peek();
+      this.vault.set(key, this.obfuscate(prev));
+      this.notify(key);
+    }
+  }
+
+  /**
+   * Restores the state to the next version in the redo stack.
+   */
+  redo(key: string) {
+    const history = this.histories.get(key);
+    const redo = this.redoStacks.get(key);
+    if (redo && redo.length > 0) {
+      const next = redo.pop();
+      history?.push(next);
+      this.vault.set(key, this.obfuscate(next));
+      this.notify(key);
+    }
+  }
+
+  /**
+   * Resets a flow to its initial value.
+   */
+  reset(key: string) {
+    const initial = this.initialValues.get(key);
+    if (initial !== undefined) this.set(key, initial);
+  }
+
+  getHistory(key: string) {
+    return this.histories.get(key)?.toArray() || [];
+  }
+  getRedoStack(key: string) {
+    return this.redoStacks.get(key) || [];
+  }
+
+  /**
+   * Clears the entire store and all timers.
+   */
+  clearAll() {
+    this.debounceTimers.forEach((t) => clearTimeout(t));
+    this.vault.clear();
+    this.initialValues.clear();
+    this.listeners.clear();
+    this.histories.clear();
+    this.redoStacks.clear();
+  }
+}
+
+/**
+ * Circular Buffer implementation for high-performance memory-efficient history.
+ */
+class CircularBuffer<T> {
+  private buffer: T[];
+  private head = 0;
+  private size = 0;
+  private maxSize: number;
+
+  constructor(maxSize: number, initial: T[] = []) {
+    this.maxSize = maxSize;
+    this.buffer = new Array(maxSize);
+    initial.forEach((i) => this.push(i));
+  }
+  push(item: T) {
+    this.buffer[this.head] = item;
+    this.head = (this.head + 1) % this.maxSize;
+    if (this.size < this.maxSize) this.size++;
+  }
+  pop(): T | undefined {
+    if (this.size <= 0) return undefined;
+    this.head = (this.head - 1 + this.maxSize) % this.maxSize;
+    this.size--;
+    return this.buffer[this.head];
+  }
+  peek(): T | undefined {
+    return this.size > 0
+      ? this.buffer[(this.head - 1 + this.maxSize) % this.maxSize]
+      : undefined;
+  }
+  length() {
+    return this.size;
+  }
+  toArray(): T[] {
+    const res = [];
+    for (let i = 0; i < this.size; i++) {
+      res.push(
+        this.buffer[(this.head - this.size + i + this.maxSize) % this.maxSize],
+      );
+    }
+    return res;
+  }
+}
+
+/**
+ * High-performance deep cloning utility.
+ */
+function deepClone<T>(obj: T): T {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(deepClone) as any;
+  const cloned: any = {};
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key))
+      cloned[key] = deepClone(obj[key]);
+  }
+  return cloned;
+}
+
+/**
+ * High-performance deep equality utility.
+ */
+function deepEqual(a: any, b: any): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null) return false;
+  if (typeof a === "object") {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+    for (const key of keysA) {
+      if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+      if (!deepEqual(a[key], b[key])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+export const store = new SecureVault();