fractostate 1.0.2 → 2.0.0

package/dist/cjs/src/index.js

@@ -4,33 +4,93 @@ var react = require('react');
 var store = require('./store.js');
 var proxy = require('./proxy.js');
 
+/***************************************************************************
+ * FractoState - Fast And Secure
+ *
+ * @author Nehonix
+ * @license NOSL
+ *
+ * Copyright (c) 2025 Nehonix. All rights reserved.
+ *
+ * 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 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.
+ * 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.
+ *
+ ***************************************************************************** */
+/**
+ * Defines a derived flow that automatically updates based on a source flow.
+ * No store registration happens here; it's purely a definition for the hook.
+ */
+function defineDerived(source, selector, derivedKey) {
+    return {
+        key: derivedKey || `${source.key}_derived_${Date.now()}`,
+        source,
+        selector,
+    };
+}
 /**
  * Defines a flow in a centralized manner.
  * Allows defining the key, initial state, and options in a single reusable object.
  */
 function defineFlow(key, initial, options) {
+    // If generic T is provided manually but A is not, we want A to be inferred from options
+    // However, explicit generics override inference.
+    // The user should ideally use `defineFlow('key', { ...initial }, { actions: ... })`
+    // without explicit generics to get full inference.
+    // Or provide both. This signature supports both but relies on inference for best DX.
     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, ... }
- */
+// --- Implementation ---
 function useFlow(keyOrDef, maybeInitialValue, options = {}) {
-    // Argument analysis to unify initialization and consumption
+    // 1. Identify if we are dealing with a Derived Flow
+    const isDerived = typeof keyOrDef === "object" &&
+        "selector" in keyOrDef &&
+        "source" in keyOrDef;
+    // --- Logic for DERIVED Flows (Read-Only Reactive) ---
+    if (isDerived) {
+        const derivedDef = keyOrDef;
+        const sourceKey = derivedDef.source.key;
+        const selector = derivedDef.selector;
+        const getSourceState = () => store.store.get(sourceKey, derivedDef.source.initial);
+        // Initial derived state
+        const [derivedState, setDerivedState] = react.useState(() => selector(getSourceState()));
+        react.useEffect(() => {
+            const unsub = store.store.subscribe(sourceKey, () => {
+                const nextSource = getSourceState();
+                const nextDerived = selector(nextSource);
+                setDerivedState((prev) => {
+                    if (prev === nextDerived)
+                        return prev;
+                    return nextDerived;
+                });
+            });
+            return unsub;
+        }, [sourceKey, selector]);
+        return [derivedState, {}];
+    }
+    // --- Logic for STANDARD Flows (Read-Write) ---
     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 key = isDef
+        ? keyOrDef.key
+        : keyOrDef;
+    const initialValue = isDef
+        ? keyOrDef.initial
+        : maybeInitialValue;
+    const opt = isDef
+        ? { ...keyOrDef.options, ...options }
+        : options;
     const [state, setState] = react.useState(() => store.store.get(key, initialValue));
     react.useEffect(() => {
-        // Subscribe to store changes
         const unsub = store.store.subscribe(key, () => {
             setState(store.store.get(key, initialValue));
         });
@@ -42,12 +102,20 @@ function useFlow(keyOrDef, maybeInitialValue, options = {}) {
         store.store.set(key, next, opt);
     }, [key, initialValue, opt]);
     const toolbox = react.useMemo(() => {
-        return {
-            ops: {
-                get self() {
-                    return proxy.createDeepProxy(key, [], store.store.get(key, initialValue), opt);
-                },
+        const defaultOps = {
+            get self() {
+                return proxy.createDeepProxy(key, [], store.store.get(key, initialValue), opt);
             },
+        };
+        const boundActions = {};
+        if (opt.actions) {
+            for (const [actionName, actionFn] of Object.entries(opt.actions)) {
+                boundActions[actionName] = (...args) => actionFn(defaultOps, ...args);
+            }
+        }
+        return {
+            ops: defaultOps,
+            actions: boundActions,
             set: setManual,
             undo: () => store.store.undo(key),
             redo: () => store.store.redo(key),
@@ -61,6 +129,7 @@ function useFlow(keyOrDef, maybeInitialValue, options = {}) {
     return [state, toolbox];
 }
 
+exports.defineDerived = defineDerived;
 exports.defineFlow = defineFlow;
 exports.useFlow = useFlow;
 //# sourceMappingURL=index.js.map

package/dist/cjs/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":["import { useState, useEffect, useCallback, useMemo } from \"react\";\nimport type { FlowOptions, FlowOperations, FlowDefinition } from \"./types\";\nimport { store } from \"./store\";\nimport { createDeepProxy } from \"./proxy\";\n\nexport * from \"./types\";\n\n/**\n * Defines a flow in a centralized manner.\n * Allows defining the key, initial state, and options in a single reusable object.\n */\nexport function defineFlow<T>(\n  key: string,\n  initial: T,\n  options?: FlowOptions<T>,\n): FlowDefinition<T> {\n  return { key, initial, options };\n}\n\n/**\n * Unique \"All-in-One\" hook to create or consume a FractoState flow.\n * - If called with a FlowDefinition or an initial value: initializes the flow if it doesn't exist.\n * - If called with just a key: connects to the existing flow.\n *\n * Returns a 2-element array: [state, toolbox]\n * where toolbox contains { ops, set, undo, redo, history, ... }\n */\nexport function useFlow<T>(\n  keyOrDef: string | FlowDefinition<T>,\n  maybeInitialValue?: T,\n  options: FlowOptions<T> = {},\n): [T, FlowOperations<T>] {\n  // Argument analysis to unify initialization and consumption\n  const isDef = typeof keyOrDef !== \"string\";\n  const key = isDef ? keyOrDef.key : keyOrDef;\n\n  // Initial data comes either from the definition or the direct argument\n  const initialValue = isDef ? keyOrDef.initial : maybeInitialValue;\n\n  // Merge options\n  const opt = isDef ? { ...keyOrDef.options, ...options } : options;\n\n  // Store access: store.get handles initialization if initialValue is present\n  const [state, setState] = useState(() => store.get(key, initialValue));\n\n  useEffect(() => {\n    // Subscribe to store changes\n    const unsub = store.subscribe(key, () => {\n      setState(store.get(key, initialValue));\n    });\n    return unsub;\n  }, [key, initialValue]);\n\n  const setManual = useCallback(\n    (val: T | ((prev: T) => T)) => {\n      const current = store.get(key, initialValue);\n      const next = typeof val === \"function\" ? (val as any)(current) : val;\n      store.set(key, next, opt);\n    },\n    [key, initialValue, opt],\n  );\n\n  const toolbox = useMemo((): FlowOperations<T> => {\n    return {\n      ops: {\n        get self() {\n          return createDeepProxy<T>(key, [], store.get(key, initialValue), opt);\n        },\n      },\n      set: setManual,\n      undo: () => store.undo(key),\n      redo: () => store.redo(key),\n      history: store.getHistory(key),\n      canUndo: store.getHistory(key).length > 1,\n      canRedo: store.getRedoStack(key).length > 0,\n      reset: () => store.reset(key),\n      cf: opt,\n    };\n  }, [key, opt, state, initialValue, setManual]);\n\n  return [state, toolbox];\n}\n"],"names":["useState","store","useEffect","useCallback","useMemo","createDeepProxy"],"mappings":";;;;;;AAOA;;;AAGG;SACa,UAAU,CACxB,GAAW,EACX,OAAU,EACV,OAAwB,EAAA;AAExB,IAAA,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE;AAClC;AAEA;;;;;;;AAOG;AACG,SAAU,OAAO,CACrB,QAAoC,EACpC,iBAAqB,EACrB,UAA0B,EAAE,EAAA;;AAG5B,IAAA,MAAM,KAAK,GAAG,OAAO,QAAQ,KAAK,QAAQ;AAC1C,IAAA,MAAM,GAAG,GAAG,KAAK,GAAG,QAAQ,CAAC,GAAG,GAAG,QAAQ;;AAG3C,IAAA,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,CAAC,OAAO,GAAG,iBAAiB;;AAGjE,IAAA,MAAM,GAAG,GAAG,KAAK,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,GAAG,OAAO;;IAGjE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAGA,cAAQ,CAAC,MAAMC,WAAK,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAEtEC,eAAS,CAAC,MAAK;;QAEb,MAAM,KAAK,GAAGD,WAAK,CAAC,SAAS,CAAC,GAAG,EAAE,MAAK;YACtC,QAAQ,CAACA,WAAK,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;AACxC,QAAA,CAAC,CAAC;AACF,QAAA,OAAO,KAAK;AACd,IAAA,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;AAEvB,IAAA,MAAM,SAAS,GAAGE,iBAAW,CAC3B,CAAC,GAAyB,KAAI;QAC5B,MAAM,OAAO,GAAGF,WAAK,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC;AAC5C,QAAA,MAAM,IAAI,GAAG,OAAO,GAAG,KAAK,UAAU,GAAI,GAAW,CAAC,OAAO,CAAC,GAAG,GAAG;QACpEA,WAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC;IAC3B,CAAC,EACD,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,CACzB;AAED,IAAA,MAAM,OAAO,GAAGG,aAAO,CAAC,MAAwB;QAC9C,OAAO;AACL,YAAA,GAAG,EAAE;AACH,gBAAA,IAAI,IAAI,GAAA;AACN,oBAAA,OAAOC,qBAAe,CAAI,GAAG,EAAE,EAAE,EAAEJ,WAAK,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,EAAE,GAAG,CAAC;gBACvE,CAAC;AACF,aAAA;AACD,YAAA,GAAG,EAAE,SAAS;YACd,IAAI,EAAE,MAAMA,WAAK,CAAC,IAAI,CAAC,GAAG,CAAC;YAC3B,IAAI,EAAE,MAAMA,WAAK,CAAC,IAAI,CAAC,GAAG,CAAC;AAC3B,YAAA,OAAO,EAAEA,WAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAC9B,OAAO,EAAEA,WAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC;YACzC,OAAO,EAAEA,WAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC;YAC3C,KAAK,EAAE,MAAMA,WAAK,CAAC,KAAK,CAAC,GAAG,CAAC;AAC7B,YAAA,EAAE,EAAE,GAAG;SACR;AACH,IAAA,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;AAE9C,IAAA,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC;AACzB;;;;;"}
+{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":["/***************************************************************************\n * FractoState - Fast And Secure\n *\n * @author Nehonix\n * @license NOSL\n *\n * Copyright (c) 2025 Nehonix. All rights reserved.\n *\n * This License governs the use, modification, and distribution of software\n * provided by NEHONIX under its open source projects.\n * NEHONIX is committed to fostering collaborative innovation while strictly\n * protecting its intellectual property rights.\n * Violation of any term of this License will result in immediate termination of all granted rights\n * and may subject the violator to legal action.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,\n * INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,\n * AND NON-INFRINGEMENT.\n * IN NO EVENT SHALL NEHONIX BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,\n * OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE,\n * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.\n *\n ***************************************************************************** */\n\nimport { useState, useEffect, useCallback, useMemo } from \"react\";\nimport type {\n  FlowOptions,\n  FlowOperations,\n  FlowDefinition,\n  FlowAction,\n} from \"./types\";\nimport { store } from \"./store\";\nimport { createDeepProxy } from \"./proxy\";\n\nexport * from \"./types\";\n\n// --- New feature: Derived Flows ---\n\nexport interface DerivedFlowDefinition<T, R> {\n  key: string;\n  source: FlowDefinition<T, any>; // The source flow\n  selector: (state: T) => R; // The computation logic\n  options?: any;\n}\n\n/**\n * Defines a derived flow that automatically updates based on a source flow.\n * No store registration happens here; it's purely a definition for the hook.\n */\nexport function defineDerived<T, R>(\n  source: FlowDefinition<T, any>,\n  selector: (state: T) => R,\n  derivedKey?: string,\n): DerivedFlowDefinition<T, R> {\n  return {\n    key: derivedKey || `${source.key}_derived_${Date.now()}`,\n    source,\n    selector,\n  };\n}\n\n/**\n * Defines a flow in a centralized manner.\n * Allows defining the key, initial state, and options in a single reusable object.\n */\nexport function defineFlow<T, A extends Record<string, FlowAction<T>> = {}>(\n  key: string,\n  initial: T,\n  options?: FlowOptions<T, A>,\n): FlowDefinition<T, A> {\n  // If generic T is provided manually but A is not, we want A to be inferred from options\n  // However, explicit generics override inference.\n  // The user should ideally use `defineFlow('key', { ...initial }, { actions: ... })`\n  // without explicit generics to get full inference.\n  // Or provide both. This signature supports both but relies on inference for best DX.\n  return { key, initial, options };\n}\n\n// --- 1. Overload for DERIVED Flows (Read-Only) ---\nexport function useFlow<T, R>(derivedDef: DerivedFlowDefinition<T, R>): [R, {}];\n\n// --- 2. Overload for STANDARD Flows (Read-Write) ---\nexport function useFlow<\n  T,\n  A extends Record<string, FlowAction<T>> = Record<string, FlowAction<T>>,\n>(\n  keyOrDef: string | FlowDefinition<T, A>,\n  maybeInitialValue?: T,\n  options?: FlowOptions<T, A>,\n): [T, FlowOperations<T, A>];\n\n// --- Implementation ---\nexport function useFlow<\n  T,\n  A extends Record<string, FlowAction<T>> = Record<string, FlowAction<T>>,\n  R = T,\n>(\n  keyOrDef: string | FlowDefinition<T, A> | DerivedFlowDefinition<any, R>,\n  maybeInitialValue?: T,\n  options: FlowOptions<T, A> = {},\n): [R extends T ? T : R, Partial<FlowOperations<T, A>>] {\n  // 1. Identify if we are dealing with a Derived Flow\n  const isDerived =\n    typeof keyOrDef === \"object\" &&\n    \"selector\" in keyOrDef &&\n    \"source\" in keyOrDef;\n\n  // --- Logic for DERIVED Flows (Read-Only Reactive) ---\n  if (isDerived) {\n    const derivedDef = keyOrDef as DerivedFlowDefinition<any, R>;\n    const sourceKey = derivedDef.source.key;\n    const selector = derivedDef.selector;\n\n    const getSourceState = () =>\n      store.get(sourceKey, derivedDef.source.initial);\n\n    // Initial derived state\n    const [derivedState, setDerivedState] = useState(() =>\n      selector(getSourceState()),\n    );\n\n    useEffect(() => {\n      const unsub = store.subscribe(sourceKey, () => {\n        const nextSource = getSourceState();\n        const nextDerived = selector(nextSource);\n        setDerivedState((prev) => {\n          if (prev === nextDerived) return prev;\n          return nextDerived;\n        });\n      });\n      return unsub;\n    }, [sourceKey, selector]);\n\n    return [derivedState as any, {}];\n  }\n\n  // --- Logic for STANDARD Flows (Read-Write) ---\n  const isDef = typeof keyOrDef !== \"string\";\n  const key = isDef\n    ? (keyOrDef as FlowDefinition<T, A>).key\n    : (keyOrDef as string);\n\n  const initialValue = isDef\n    ? (keyOrDef as FlowDefinition<T, A>).initial\n    : maybeInitialValue;\n\n  const opt: FlowOptions<T, A> = isDef\n    ? { ...(keyOrDef as FlowDefinition<T, A>).options, ...options }\n    : options;\n\n  const [state, setState] = useState(() => store.get(key, initialValue));\n\n  useEffect(() => {\n    const unsub = store.subscribe(key, () => {\n      setState(store.get(key, initialValue));\n    });\n    return unsub;\n  }, [key, initialValue]);\n\n  const setManual = useCallback(\n    (val: T | ((prev: T) => T)) => {\n      const current = store.get(key, initialValue);\n      const next = typeof val === \"function\" ? (val as any)(current) : val;\n      store.set(key, next, opt);\n    },\n    [key, initialValue, opt],\n  );\n\n  const toolbox = useMemo((): FlowOperations<T, A> => {\n    const defaultOps = {\n      get self() {\n        return createDeepProxy<T>(key, [], store.get(key, initialValue), opt);\n      },\n    };\n\n    const boundActions = {} as any;\n    if (opt.actions) {\n      for (const [actionName, actionFn] of Object.entries(opt.actions)) {\n        boundActions[actionName] = (...args: any[]) =>\n          (actionFn as Function)(defaultOps as any, ...args);\n      }\n    }\n\n    return {\n      ops: defaultOps,\n      actions: boundActions,\n      set: setManual,\n      undo: () => store.undo(key),\n      redo: () => store.redo(key),\n      history: store.getHistory(key),\n      canUndo: store.getHistory(key).length > 1,\n      canRedo: store.getRedoStack(key).length > 0,\n      reset: () => store.reset(key),\n      cf: opt,\n    };\n  }, [key, opt, state, initialValue, setManual]);\n\n  return [state as any, toolbox];\n}\n"],"names":["store","useState","useEffect","useCallback","useMemo","createDeepProxy"],"mappings":"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"}

package/dist/esm/src/index.js

@@ -2,33 +2,93 @@ import { useState, useEffect, useCallback, useMemo } from 'react';
 import { store } from './store.js';
 import { createDeepProxy } from './proxy.js';
 
+/***************************************************************************
+ * FractoState - Fast And Secure
+ *
+ * @author Nehonix
+ * @license NOSL
+ *
+ * Copyright (c) 2025 Nehonix. All rights reserved.
+ *
+ * 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 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.
+ * 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.
+ *
+ ***************************************************************************** */
+/**
+ * Defines a derived flow that automatically updates based on a source flow.
+ * No store registration happens here; it's purely a definition for the hook.
+ */
+function defineDerived(source, selector, derivedKey) {
+    return {
+        key: derivedKey || `${source.key}_derived_${Date.now()}`,
+        source,
+        selector,
+    };
+}
 /**
  * Defines a flow in a centralized manner.
  * Allows defining the key, initial state, and options in a single reusable object.
  */
 function defineFlow(key, initial, options) {
+    // If generic T is provided manually but A is not, we want A to be inferred from options
+    // However, explicit generics override inference.
+    // The user should ideally use `defineFlow('key', { ...initial }, { actions: ... })`
+    // without explicit generics to get full inference.
+    // Or provide both. This signature supports both but relies on inference for best DX.
     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, ... }
- */
+// --- Implementation ---
 function useFlow(keyOrDef, maybeInitialValue, options = {}) {
-    // Argument analysis to unify initialization and consumption
+    // 1. Identify if we are dealing with a Derived Flow
+    const isDerived = typeof keyOrDef === "object" &&
+        "selector" in keyOrDef &&
+        "source" in keyOrDef;
+    // --- Logic for DERIVED Flows (Read-Only Reactive) ---
+    if (isDerived) {
+        const derivedDef = keyOrDef;
+        const sourceKey = derivedDef.source.key;
+        const selector = derivedDef.selector;
+        const getSourceState = () => store.get(sourceKey, derivedDef.source.initial);
+        // Initial derived state
+        const [derivedState, setDerivedState] = useState(() => selector(getSourceState()));
+        useEffect(() => {
+            const unsub = store.subscribe(sourceKey, () => {
+                const nextSource = getSourceState();
+                const nextDerived = selector(nextSource);
+                setDerivedState((prev) => {
+                    if (prev === nextDerived)
+                        return prev;
+                    return nextDerived;
+                });
+            });
+            return unsub;
+        }, [sourceKey, selector]);
+        return [derivedState, {}];
+    }
+    // --- Logic for STANDARD Flows (Read-Write) ---
     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 key = isDef
+        ? keyOrDef.key
+        : keyOrDef;
+    const initialValue = isDef
+        ? keyOrDef.initial
+        : maybeInitialValue;
+    const opt = isDef
+        ? { ...keyOrDef.options, ...options }
+        : options;
     const [state, setState] = useState(() => store.get(key, initialValue));
     useEffect(() => {
-        // Subscribe to store changes
         const unsub = store.subscribe(key, () => {
             setState(store.get(key, initialValue));
         });
@@ -40,12 +100,20 @@ function useFlow(keyOrDef, maybeInitialValue, options = {}) {
         store.set(key, next, opt);
     }, [key, initialValue, opt]);
     const toolbox = useMemo(() => {
-        return {
-            ops: {
-                get self() {
-                    return createDeepProxy(key, [], store.get(key, initialValue), opt);
-                },
+        const defaultOps = {
+            get self() {
+                return createDeepProxy(key, [], store.get(key, initialValue), opt);
             },
+        };
+        const boundActions = {};
+        if (opt.actions) {
+            for (const [actionName, actionFn] of Object.entries(opt.actions)) {
+                boundActions[actionName] = (...args) => actionFn(defaultOps, ...args);
+            }
+        }
+        return {
+            ops: defaultOps,
+            actions: boundActions,
             set: setManual,
             undo: () => store.undo(key),
             redo: () => store.redo(key),
@@ -59,5 +127,5 @@ function useFlow(keyOrDef, maybeInitialValue, options = {}) {
     return [state, toolbox];
 }
 
-export { defineFlow, useFlow };
+export { defineDerived, defineFlow, useFlow };
 //# sourceMappingURL=index.js.map

package/dist/esm/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":["import { useState, useEffect, useCallback, useMemo } from \"react\";\nimport type { FlowOptions, FlowOperations, FlowDefinition } from \"./types\";\nimport { store } from \"./store\";\nimport { createDeepProxy } from \"./proxy\";\n\nexport * from \"./types\";\n\n/**\n * Defines a flow in a centralized manner.\n * Allows defining the key, initial state, and options in a single reusable object.\n */\nexport function defineFlow<T>(\n  key: string,\n  initial: T,\n  options?: FlowOptions<T>,\n): FlowDefinition<T> {\n  return { key, initial, options };\n}\n\n/**\n * Unique \"All-in-One\" hook to create or consume a FractoState flow.\n * - If called with a FlowDefinition or an initial value: initializes the flow if it doesn't exist.\n * - If called with just a key: connects to the existing flow.\n *\n * Returns a 2-element array: [state, toolbox]\n * where toolbox contains { ops, set, undo, redo, history, ... }\n */\nexport function useFlow<T>(\n  keyOrDef: string | FlowDefinition<T>,\n  maybeInitialValue?: T,\n  options: FlowOptions<T> = {},\n): [T, FlowOperations<T>] {\n  // Argument analysis to unify initialization and consumption\n  const isDef = typeof keyOrDef !== \"string\";\n  const key = isDef ? keyOrDef.key : keyOrDef;\n\n  // Initial data comes either from the definition or the direct argument\n  const initialValue = isDef ? keyOrDef.initial : maybeInitialValue;\n\n  // Merge options\n  const opt = isDef ? { ...keyOrDef.options, ...options } : options;\n\n  // Store access: store.get handles initialization if initialValue is present\n  const [state, setState] = useState(() => store.get(key, initialValue));\n\n  useEffect(() => {\n    // Subscribe to store changes\n    const unsub = store.subscribe(key, () => {\n      setState(store.get(key, initialValue));\n    });\n    return unsub;\n  }, [key, initialValue]);\n\n  const setManual = useCallback(\n    (val: T | ((prev: T) => T)) => {\n      const current = store.get(key, initialValue);\n      const next = typeof val === \"function\" ? (val as any)(current) : val;\n      store.set(key, next, opt);\n    },\n    [key, initialValue, opt],\n  );\n\n  const toolbox = useMemo((): FlowOperations<T> => {\n    return {\n      ops: {\n        get self() {\n          return createDeepProxy<T>(key, [], store.get(key, initialValue), opt);\n        },\n      },\n      set: setManual,\n      undo: () => store.undo(key),\n      redo: () => store.redo(key),\n      history: store.getHistory(key),\n      canUndo: store.getHistory(key).length > 1,\n      canRedo: store.getRedoStack(key).length > 0,\n      reset: () => store.reset(key),\n      cf: opt,\n    };\n  }, [key, opt, state, initialValue, setManual]);\n\n  return [state, toolbox];\n}\n"],"names":[],"mappings":";;;;AAOA;;;AAGG;SACa,UAAU,CACxB,GAAW,EACX,OAAU,EACV,OAAwB,EAAA;AAExB,IAAA,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE;AAClC;AAEA;;;;;;;AAOG;AACG,SAAU,OAAO,CACrB,QAAoC,EACpC,iBAAqB,EACrB,UAA0B,EAAE,EAAA;;AAG5B,IAAA,MAAM,KAAK,GAAG,OAAO,QAAQ,KAAK,QAAQ;AAC1C,IAAA,MAAM,GAAG,GAAG,KAAK,GAAG,QAAQ,CAAC,GAAG,GAAG,QAAQ;;AAG3C,IAAA,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,CAAC,OAAO,GAAG,iBAAiB;;AAGjE,IAAA,MAAM,GAAG,GAAG,KAAK,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,GAAG,OAAO;;IAGjE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAEtE,SAAS,CAAC,MAAK;;QAEb,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,MAAK;YACtC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;AACxC,QAAA,CAAC,CAAC;AACF,QAAA,OAAO,KAAK;AACd,IAAA,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;AAEvB,IAAA,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,GAAyB,KAAI;QAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC;AAC5C,QAAA,MAAM,IAAI,GAAG,OAAO,GAAG,KAAK,UAAU,GAAI,GAAW,CAAC,OAAO,CAAC,GAAG,GAAG;QACpE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC;IAC3B,CAAC,EACD,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,CACzB;AAED,IAAA,MAAM,OAAO,GAAG,OAAO,CAAC,MAAwB;QAC9C,OAAO;AACL,YAAA,GAAG,EAAE;AACH,gBAAA,IAAI,IAAI,GAAA;AACN,oBAAA,OAAO,eAAe,CAAI,GAAG,EAAE,EAAE,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,EAAE,GAAG,CAAC;gBACvE,CAAC;AACF,aAAA;AACD,YAAA,GAAG,EAAE,SAAS;YACd,IAAI,EAAE,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;YAC3B,IAAI,EAAE,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;AAC3B,YAAA,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAC9B,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC;YACzC,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC;YAC3C,KAAK,EAAE,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC;AAC7B,YAAA,EAAE,EAAE,GAAG;SACR;AACH,IAAA,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;AAE9C,IAAA,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC;AACzB;;;;"}
+{"version":3,"file":"index.js","sources":["../../../src/index.ts"],"sourcesContent":["/***************************************************************************\n * FractoState - Fast And Secure\n *\n * @author Nehonix\n * @license NOSL\n *\n * Copyright (c) 2025 Nehonix. All rights reserved.\n *\n * This License governs the use, modification, and distribution of software\n * provided by NEHONIX under its open source projects.\n * NEHONIX is committed to fostering collaborative innovation while strictly\n * protecting its intellectual property rights.\n * Violation of any term of this License will result in immediate termination of all granted rights\n * and may subject the violator to legal action.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,\n * INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,\n * AND NON-INFRINGEMENT.\n * IN NO EVENT SHALL NEHONIX BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,\n * OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE,\n * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.\n *\n ***************************************************************************** */\n\nimport { useState, useEffect, useCallback, useMemo } from \"react\";\nimport type {\n  FlowOptions,\n  FlowOperations,\n  FlowDefinition,\n  FlowAction,\n} from \"./types\";\nimport { store } from \"./store\";\nimport { createDeepProxy } from \"./proxy\";\n\nexport * from \"./types\";\n\n// --- New feature: Derived Flows ---\n\nexport interface DerivedFlowDefinition<T, R> {\n  key: string;\n  source: FlowDefinition<T, any>; // The source flow\n  selector: (state: T) => R; // The computation logic\n  options?: any;\n}\n\n/**\n * Defines a derived flow that automatically updates based on a source flow.\n * No store registration happens here; it's purely a definition for the hook.\n */\nexport function defineDerived<T, R>(\n  source: FlowDefinition<T, any>,\n  selector: (state: T) => R,\n  derivedKey?: string,\n): DerivedFlowDefinition<T, R> {\n  return {\n    key: derivedKey || `${source.key}_derived_${Date.now()}`,\n    source,\n    selector,\n  };\n}\n\n/**\n * Defines a flow in a centralized manner.\n * Allows defining the key, initial state, and options in a single reusable object.\n */\nexport function defineFlow<T, A extends Record<string, FlowAction<T>> = {}>(\n  key: string,\n  initial: T,\n  options?: FlowOptions<T, A>,\n): FlowDefinition<T, A> {\n  // If generic T is provided manually but A is not, we want A to be inferred from options\n  // However, explicit generics override inference.\n  // The user should ideally use `defineFlow('key', { ...initial }, { actions: ... })`\n  // without explicit generics to get full inference.\n  // Or provide both. This signature supports both but relies on inference for best DX.\n  return { key, initial, options };\n}\n\n// --- 1. Overload for DERIVED Flows (Read-Only) ---\nexport function useFlow<T, R>(derivedDef: DerivedFlowDefinition<T, R>): [R, {}];\n\n// --- 2. Overload for STANDARD Flows (Read-Write) ---\nexport function useFlow<\n  T,\n  A extends Record<string, FlowAction<T>> = Record<string, FlowAction<T>>,\n>(\n  keyOrDef: string | FlowDefinition<T, A>,\n  maybeInitialValue?: T,\n  options?: FlowOptions<T, A>,\n): [T, FlowOperations<T, A>];\n\n// --- Implementation ---\nexport function useFlow<\n  T,\n  A extends Record<string, FlowAction<T>> = Record<string, FlowAction<T>>,\n  R = T,\n>(\n  keyOrDef: string | FlowDefinition<T, A> | DerivedFlowDefinition<any, R>,\n  maybeInitialValue?: T,\n  options: FlowOptions<T, A> = {},\n): [R extends T ? T : R, Partial<FlowOperations<T, A>>] {\n  // 1. Identify if we are dealing with a Derived Flow\n  const isDerived =\n    typeof keyOrDef === \"object\" &&\n    \"selector\" in keyOrDef &&\n    \"source\" in keyOrDef;\n\n  // --- Logic for DERIVED Flows (Read-Only Reactive) ---\n  if (isDerived) {\n    const derivedDef = keyOrDef as DerivedFlowDefinition<any, R>;\n    const sourceKey = derivedDef.source.key;\n    const selector = derivedDef.selector;\n\n    const getSourceState = () =>\n      store.get(sourceKey, derivedDef.source.initial);\n\n    // Initial derived state\n    const [derivedState, setDerivedState] = useState(() =>\n      selector(getSourceState()),\n    );\n\n    useEffect(() => {\n      const unsub = store.subscribe(sourceKey, () => {\n        const nextSource = getSourceState();\n        const nextDerived = selector(nextSource);\n        setDerivedState((prev) => {\n          if (prev === nextDerived) return prev;\n          return nextDerived;\n        });\n      });\n      return unsub;\n    }, [sourceKey, selector]);\n\n    return [derivedState as any, {}];\n  }\n\n  // --- Logic for STANDARD Flows (Read-Write) ---\n  const isDef = typeof keyOrDef !== \"string\";\n  const key = isDef\n    ? (keyOrDef as FlowDefinition<T, A>).key\n    : (keyOrDef as string);\n\n  const initialValue = isDef\n    ? (keyOrDef as FlowDefinition<T, A>).initial\n    : maybeInitialValue;\n\n  const opt: FlowOptions<T, A> = isDef\n    ? { ...(keyOrDef as FlowDefinition<T, A>).options, ...options }\n    : options;\n\n  const [state, setState] = useState(() => store.get(key, initialValue));\n\n  useEffect(() => {\n    const unsub = store.subscribe(key, () => {\n      setState(store.get(key, initialValue));\n    });\n    return unsub;\n  }, [key, initialValue]);\n\n  const setManual = useCallback(\n    (val: T | ((prev: T) => T)) => {\n      const current = store.get(key, initialValue);\n      const next = typeof val === \"function\" ? (val as any)(current) : val;\n      store.set(key, next, opt);\n    },\n    [key, initialValue, opt],\n  );\n\n  const toolbox = useMemo((): FlowOperations<T, A> => {\n    const defaultOps = {\n      get self() {\n        return createDeepProxy<T>(key, [], store.get(key, initialValue), opt);\n      },\n    };\n\n    const boundActions = {} as any;\n    if (opt.actions) {\n      for (const [actionName, actionFn] of Object.entries(opt.actions)) {\n        boundActions[actionName] = (...args: any[]) =>\n          (actionFn as Function)(defaultOps as any, ...args);\n      }\n    }\n\n    return {\n      ops: defaultOps,\n      actions: boundActions,\n      set: setManual,\n      undo: () => store.undo(key),\n      redo: () => store.redo(key),\n      history: store.getHistory(key),\n      canUndo: store.getHistory(key).length > 1,\n      canRedo: store.getRedoStack(key).length > 0,\n      reset: () => store.reset(key),\n      cf: opt,\n    };\n  }, [key, opt, state, initialValue, setManual]);\n\n  return [state as any, toolbox];\n}\n"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,14 @@
-interface FlowOptions<T = any> {
+type FlowAction<T> = (ops: {
+    self: TypeAwareOps<T>;
+}, ...args: any[]) => any;
+/**
+ * Utility type to extract the public signature of actions.
+ * It removes the first argument (ops) from each action function.
+ */
+type BoundActions<A> = {
+    [K in keyof A]: A[K] extends (ops: any, ...args: infer P) => infer R ? (...args: P) => R : never;
+};
+interface FlowOptions<T = any, A extends Record<string, FlowAction<T>> = {}> {
     /** Enable history tracking for undo/redo functionality */
     timeTravel?: boolean;
     /** Maximum number of states to keep in history (default: 100) */
@@ -7,6 +17,8 @@ interface FlowOptions<T = any> {
     debounce?: number;
     /** Array of functions to transform state before it is saved */
     middleware?: Array<(state: T) => T>;
+    /** Custom async actions attached to the flow */
+    actions?: A;
 }
 type BaseOps<T> = {
     /** Replaces the entire value at this path */
@@ -73,20 +85,26 @@ type BooleanOps = BaseOps<boolean> & {
     toggle: () => void;
 };
 type TypeAwareOps<T> = T extends number ? NumberOps : T extends string ? StringOps : T extends boolean ? BooleanOps : T extends Array<infer U> ? ArrayOps<U> : T extends object ? ObjectOps<T> : BaseOps<T>;
-interface FlowDefinition<T> {
+type FlowOpsObject<T> = {
+    /**
+     * Recursive, type-aware proxy that provides surgical atomic operations
+     * tailored to the shape of your state. It allows direct-like manipulation
+     * that is internally processed as immutable updates.
+     */
+    self: TypeAwareOps<T>;
+};
+interface FlowDefinition<T, A extends Record<string, FlowAction<T>> = {}> {
     key: string;
     initial: T;
-    options?: FlowOptions<T>;
+    options?: FlowOptions<T, A>;
 }
-interface FlowOperations<T> {
-    ops: {
-        /**
-         * Recursive, type-aware proxy that provides surgical atomic operations
-         * tailored to the shape of your state. It allows direct-like manipulation
-         * that is internally processed as immutable updates.
-         */
-        self: TypeAwareOps<T>;
-    };
+interface FlowOperations<T, A extends Record<string, FlowAction<T>> = {}> {
+    ops: FlowOpsObject<T>;
+    /**
+     * Custom actions bound to the flow.
+     * The 'ops' argument is automatically injected.
+     */
+    actions: BoundActions<A>;
     /** Reverts to the previous state in history */
     undo: () => void;
     /** Restores the previously undone state */
@@ -102,23 +120,51 @@ interface FlowOperations<T> {
     /** Restores the state to its initial value */
     reset: () => void;
     /** Current flow configuration options */
-    cf: FlowOptions<T>;
+    cf: FlowOptions<T, A>;
 }
 
+/***************************************************************************
+ * FractoState - Fast And Secure
+ *
+ * @author Nehonix
+ * @license NOSL
+ *
+ * Copyright (c) 2025 Nehonix. All rights reserved.
+ *
+ * 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 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.
+ * 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.
+ *
+ ***************************************************************************** */
+
+interface DerivedFlowDefinition<T, R> {
+    key: string;
+    source: FlowDefinition<T, any>;
+    selector: (state: T) => R;
+    options?: any;
+}
 /**
- * Defines a flow in a centralized manner.
- * Allows defining the key, initial state, and options in a single reusable object.
+ * Defines a derived flow that automatically updates based on a source flow.
+ * No store registration happens here; it's purely a definition for the hook.
  */
-declare function defineFlow<T>(key: string, initial: T, options?: FlowOptions<T>): FlowDefinition<T>;
+declare function defineDerived<T, R>(source: FlowDefinition<T, any>, selector: (state: T) => R, derivedKey?: string): DerivedFlowDefinition<T, R>;
 /**
- * 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, ... }
+ * Defines a flow in a centralized manner.
+ * Allows defining the key, initial state, and options in a single reusable object.
  */
-declare function useFlow<T>(keyOrDef: string | FlowDefinition<T>, maybeInitialValue?: T, options?: FlowOptions<T>): [T, FlowOperations<T>];
+declare function defineFlow<T, A extends Record<string, FlowAction<T>> = {}>(key: string, initial: T, options?: FlowOptions<T, A>): FlowDefinition<T, A>;
+declare function useFlow<T, R>(derivedDef: DerivedFlowDefinition<T, R>): [R, {}];
+declare function useFlow<T, A extends Record<string, FlowAction<T>> = Record<string, FlowAction<T>>>(keyOrDef: string | FlowDefinition<T, A>, maybeInitialValue?: T, options?: FlowOptions<T, A>): [T, FlowOperations<T, A>];
 
-export { defineFlow, useFlow };
-export type { ArrayOps, BaseOps, BooleanOps, FlowDefinition, FlowOperations, FlowOptions, NumberOps, ObjectOps, StringOps, TypeAwareOps };
+export { defineDerived, defineFlow, useFlow };
+export type { ArrayOps, BaseOps, BooleanOps, BoundActions, DerivedFlowDefinition, FlowAction, FlowDefinition, FlowOperations, FlowOpsObject, FlowOptions, NumberOps, ObjectOps, StringOps, TypeAwareOps };

package/package.json

@@ -1,4 +1,5 @@
 {
+  "version": "2.0.0",
   "author": {
     "name": "Nehonix",
     "url": "https://nehonix.com",
@@ -43,18 +44,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/esm/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/cjs/index.js"
-      },
-      "node": {
-        "import": "./dist/esm/index.js",
-        "require": "./dist/cjs/index.js"
-      },
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
       "default": "./dist/cjs/index.js"
     },
     "./package.json": "./package.json"
@@ -71,7 +62,7 @@
     "build": "rollup -c",
     "dev": "tsup src/index.ts --watch --dts --format esm,cjs",
     "lint": "eslint src",
-    "test": "vitest"
-  },
-  "version": "1.0.2"
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  }
 }