fractostate 4.8.4 → 4.8.6

package/dist/index.d.ts

@@ -1,11 +1,18 @@
-import { F as FlowDefinition, D as DerivedFlowDefinition, C as ContextGetterOps, a as FlowOptions, A as ActionOpsObject, b as FlowOperations, U as UseFlowOptions } from './types-CrNg0-d5.js';
-export { c as ArrayOps, B as BaseOps, d as BooleanOps, e as BoundActions, f as FlowAction, g as FlowEffect, h as FlowOpsObject, i as FlowPlugin, N as NumberOps, O as ObjectOps, S as StringOps, T as TypeAwareOps } from './types-CrNg0-d5.js';
+import { F as FlowDefinition, D as DerivedFlowDefinition, C as ContextGetterOps, a as FlowOptions, A as ActionOpsObject, b as FlowOperations, U as UseFlowOptions } from './types-DgcrW93l.js';
+export { c as ArrayOps, B as BaseOps, d as BooleanOps, e as BoundActions, f as FlowAction, g as FlowEffect, h as FlowOpsObject, i as FlowPlugin, N as NumberOps, O as ObjectOps, S as StringOps, T as TypeAwareOps } from './types-DgcrW93l.js';
 
 /**
  * Manually initializes a flow to ensure its effects run immediately.
  * This is useful for flows that need to start working before any component subscribes to them.
  */
 declare function initFlow<T, A, C>(flow: FlowDefinition<T, A, C>): void;
+/**
+ * Executes a list of predefined flows immediately and optimally.
+ * Guaranteed to run exactly once per application initialization.
+ * Ideal for authentication checks, data pre-fetching, or setting up
+ * global state at the root of your application (e.g., in main.tsx).
+ */
+declare function runFlows(flows: FlowDefinition<any, any, any>[]): void;
 /**
  * Clears the entire store, all timers, and runs cleanup for all active flow effects.
  */
@@ -20,8 +27,14 @@ declare function defineFlow<T, A extends Record<string, any>, C = A extends {
 } ? R : undefined>(key: string, initial: T, options: FlowOptions<NoInfer<T>, any> & {
     actions: {
         __ctx__?: (c: ContextGetterOps<T, Record<string, any>>) => C;
+        /**
+         * Automatic initialization action.
+         * Executed once when the flow is first initialized (e.g., page refresh or first use).
+         * Useful for fetching initial data or setting up state before components consume it.
+         */
+        __init__?: () => (ops: ActionOpsObject<T, Record<string, any>, C>) => any;
     } & {
-        [K in keyof A as K extends "__ctx__" ? never : K]: (...args: any[]) => (ops: ActionOpsObject<T, Record<string, any>, C>) => any;
+        [K in keyof A as K extends "__ctx__" | "__init__" ? never : K]: (...args: any[]) => (ops: ActionOpsObject<T, Record<string, any>, C>) => any;
     } & A;
 }): FlowDefinition<T, A, C>;
 declare function defineFlow<T>(key: string, initial: T, options?: FlowOptions<NoInfer<T>, {}>): FlowDefinition<T, {}>;
@@ -38,4 +51,4 @@ declare function useFlow<K extends string, T = any>(key: K, initial?: T, options
 declare function useFlow<T, A, C>(def: FlowDefinition<T, A, C>, options?: UseFlowOptions<T>): [T, FlowOperations<T, A>];
 declare function useFlow<T, R>(def: DerivedFlowDefinition<T, R>): [R, {}];
 
-export { ActionOpsObject, ContextGetterOps, DerivedFlowDefinition, FlowDefinition, FlowOperations, FlowOptions, UseFlowOptions, clearAll, defineDerived, defineFlow, getFlow, initFlow, useFlow };
+export { ActionOpsObject, ContextGetterOps, DerivedFlowDefinition, FlowDefinition, FlowOperations, FlowOptions, UseFlowOptions, clearAll, defineDerived, defineFlow, getFlow, initFlow, runFlows, useFlow };

package/dist/plugins.d.ts

@@ -1,4 +1,4 @@
-import { i as FlowPlugin, h as FlowOpsObject } from './types-CrNg0-d5.js';
+import { i as FlowPlugin, h as FlowOpsObject } from './types-DgcrW93l.js';
 
 interface LoggerOptions {
     collapsed?: boolean;

package/dist/types-DgcrW93l.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Core types for FractoState
+ */
+type TypeAwareOps<T, A = any> = [T] extends [null | undefined] ? BaseOps<T, A> : [T] extends [any[]] ? ArrayOps<T[number], A> : [T] extends [number] ? NumberOps<A> : [T] extends [string] ? StringOps<A> : [T] extends [boolean] ? BooleanOps<A> : [NonNullable<T>] extends [object] ? ObjectOps<T, A> : BaseOps<T, A>;
+type FlowOpsObject<T, A = any> = {
+    readonly self: TypeAwareOps<T, A>;
+    readonly state: T;
+};
+/**
+ * Enhanced operations for actions that include the context
+ */
+type ActionOpsObject<T, A = any, C = undefined> = FlowOpsObject<T, A> & {
+    readonly ctx: C;
+};
+/**
+ * Action structure: (...args) => (ops) => Result
+ */
+type FlowAction<T, A = any, C = undefined> = (...args: any[]) => (ops: ActionOpsObject<T, A, C>) => any;
+/**
+ * Transform actions for the component toolbox.
+ * Excludes internal __ctx__ property.
+ */
+type BoundActions<A> = {
+    [K in keyof A as K extends "__ctx__" | "__init__" ? never : K]: A[K] extends (...args: infer P) => (...inner: any[]) => infer R ? (...args: P) => R : never;
+};
+interface FlowPlugin<T = any, A = any> {
+    name: string;
+    onInit?: (ctx: {
+        key: string;
+        initial: T;
+        store: any;
+    }) => void;
+    onUpdate?: (ctx: {
+        key: string;
+        prev: T;
+        next: T;
+        store: any;
+    }) => void;
+    onHydrate?: (ctx: {
+        key: string;
+        initial: T;
+        store: any;
+    }) => T | Promise<T> | undefined;
+    /** Return methods that will be exposed under ops.self._[pluginName] */
+    getOps?: (ctx: {
+        key: string;
+        store: any;
+    }) => Record<string, Function>;
+    /** @internal Phantom type for action inference */
+    __plugin_actions__?: A;
+}
+interface FlowEffect<T, A = any> {
+    /** Function to run on init and when deps change. Can return a cleanup function. */
+    run: (ops: FlowOpsObject<T, A>) => void | (() => void) | Promise<void>;
+    /** Optional dependencies selector. If omitted, runs only on init */
+    deps?: (state: T) => any[];
+}
+interface FlowOptions<T = any, A = any> {
+    timeTravel?: boolean;
+    maxHistory?: number;
+    debounce?: number;
+    middleware?: Array<(state: T) => T>;
+    plugins?: FlowPlugin<T, A>[];
+    effects?: FlowEffect<T, A>[];
+    force?: boolean;
+    skipEquality?: boolean;
+    isUndoRedo?: boolean;
+    bypassClone?: boolean;
+    /** The name of the component or module performing the update */
+    actor?: string;
+    /** Raw actions dictionary for internal binding */
+    actions?: A;
+}
+interface ContextGetterOps<T, A> {
+    state: T;
+    initialState: T;
+    actions: BoundActions<A>;
+    ops: FlowOpsObject<T, A>;
+}
+interface UseFlowOptions<T> extends FlowOptions<T> {
+    name?: string;
+}
+interface FlowDefinition<T, A = {}, C = undefined> {
+    key: string;
+    initial: T;
+    options?: FlowOptions<T, A> & {
+        actions?: A;
+    };
+    /** @internal Phantom type for context inference */
+    __ctx__?: C;
+}
+interface DerivedFlowDefinition<T, R> {
+    key: string;
+    source: FlowDefinition<T, any>;
+    selector: (state: T) => R;
+}
+interface FlowOperations<T, A = {}> {
+    /** The operation object for recursive state manipulation via proxies */
+    ops: FlowOpsObject<T, A>;
+    /** The actions defined in defineFlow, bound to this specific state instance */
+    actions: BoundActions<A>;
+    /** Reverts to the previous state in history (if timeTravel is enabled) */
+    _undo: () => void;
+    /** Reapplies a previously undone state (if timeTravel is enabled) */
+    _redo: () => void;
+    /** Returns the full history stack for this flow */
+    history: T[];
+    /** Boolean indicating if an undo operation is currently possible */
+    _canUndo: boolean;
+    /** Boolean indicating if a redo operation is currently possible */
+    _canRedo: boolean;
+    /** Forcefully updates the state and records history even if values are identical. Useful for triggering effects or manual snapshots. */
+    _set: (val: T | ((prev: T) => T)) => void;
+    /** Optimized update: only commits the change if the new value differs from the current one. Saves history space and render cycles. */
+    _patch: (val: T | ((prev: T) => T)) => void;
+    /** Resets the state back to its initial defined configuration */
+    _reset: () => void;
+    /** Returns the current flow configuration options */
+    cf: FlowOptions<T>;
+    /** Boolean indicating if the flow is currently loading data from a hydration plugin (e.g., localStorage) */
+    isHydrating: boolean;
+}
+/**
+ * Common operations available on every state node.
+ * Prefixed with underscores to avoid collisions with your nested data properties.
+ */
+type BaseOps<T, A = any> = {
+    /** Forcefully replace the value at this path, ignoring equality checks. Records history. */
+    _set: (value: T) => void;
+    /** Smart update: only commits the change if the value is different. */
+    _patch: (value: T) => void;
+    /** Unwraps the proxy and returns the raw value at this specific tree path. */
+    _val: T;
+    /** Access all actions defined in this flow */
+    __actions__: BoundActions<A>;
+    /** Persistence control (provided by persist plugin) */
+    _persist?: {
+        clear: () => void;
+        update: () => void;
+        refresh: () => Promise<void>;
+        getData: () => Promise<T | undefined>;
+    };
+    /** Reverts to the previous state in history (if timeTravel is enabled) - Global Effect */
+    _undo: () => void;
+    /** Reapplies a previously undone state (if timeTravel is enabled) - Global Effect */
+    _redo: () => void;
+    /** Boolean indicating if an undo operation is currently possible */
+    _canUndo: boolean;
+    /** Boolean indicating if a redo operation is currently possible */
+    _canRedo: boolean;
+    /** Returns the full history stack for this flow */
+    _history: T[];
+};
+/** Operations specific to numeric values */
+type NumberOps<A = any> = BaseOps<number, A> & {
+    /** Increment by n (default 1) */
+    _increment: (n?: number) => void;
+    /** Decrement by n (default 1) */
+    _decrement: (n?: number) => void;
+    /** Add n to the value */
+    _add: (n: number) => void;
+    /** Subtract n from the value */
+    _subtract: (n: number) => void;
+    /** Multiply the value by n */
+    _multiply: (n: number) => void;
+    /** Divide the value by n */
+    _divide: (n: number) => void;
+    /** Raise to the power of n */
+    _pow: (n: number) => void;
+    /** Calculate square root */
+    _sqrt: () => void;
+    /** Set to absolute value */
+    _abs: () => void;
+    /** Round to the nearest integer */
+    _round: () => void;
+    /** Round down to the nearest integer */
+    _floor: () => void;
+    /** Round up to the nearest integer */
+    _ceil: () => void;
+    /** Modulo operation */
+    _mod: (n: number) => void;
+    /** Clamp value between min and max */
+    _clamp: (min: number, max: number) => void;
+    /** Negate the value */
+    _negate: () => void;
+    /** Format to fixed precision (updates value to parsed float) */
+    _toPrecision: (precision: number) => void;
+};
+/** Operations specific to string values */
+type StringOps<A = any> = BaseOps<string, A> & {
+    /** Append a string at the end */
+    _append: (s: string) => void;
+    /** Prepend a string at the beginning */
+    _prepend: (s: string) => void;
+    /** Convert value to uppercase */
+    _uppercase: () => void;
+    /** Convert value to lowercase */
+    _lowercase: () => void;
+    /** Trim whitespace from both ends */
+    _trim: () => void;
+    /** Replace first occurrence matching pattern */
+    _replace: (pattern: string | RegExp, replacement: string) => void;
+    /** Replace all occurrences matching pattern */
+    _replaceAll: (pattern: string | RegExp, replacement: string) => void;
+    /** Extract substring */
+    _substring: (start: number, end?: number) => void;
+    /** Extract section of string */
+    _slice: (start: number, end?: number) => void;
+    /** Capitalize first letter */
+    _capitalize: () => void;
+    /** Truncate string to length with suffix */
+    _truncate: (length: number, suffix?: string) => void;
+    /** Pad end of string */
+    _padEnd: (length: number, fill?: string) => void;
+    /** Pad start of string */
+    _padStart: (length: number, fill?: string) => void;
+    /** Repeat string count times */
+    _repeat: (count: number) => void;
+};
+/** Operations specific to array values */
+type ArrayOps<T, A = any> = BaseOps<T[], A> & {
+    /** Add an item to the end of the array */
+    _push: (v: T) => void;
+    /** Remove and return the last item */
+    _pop: () => void;
+    /** Remove and return the first item */
+    _shift: () => void;
+    /** Add an item to the beginning of the array */
+    _unshift: (v: T) => void;
+    /** Keep only items matching the condition */
+    _filter: (fn: (v: T, i: number) => boolean) => void;
+    /** Transform every item in the array */
+    _map: (fn: (v: T, i: number) => T) => void;
+    /** Remove item at a specific index */
+    _removeAt: (i: number) => void;
+    /** Insert an item at a specific index */
+    _insertAt: (i: number, v: T) => void;
+    /** Splice the array (items removed/replaced) */
+    _splice: (start: number, deleteCount: number, ...items: T[]) => void;
+    /** Reverse the array */
+    _reverse: () => void;
+    /** Sort the array */
+    _sort: (compareFn?: (a: T, b: T) => number) => void;
+    /** Fill the array with a static value */
+    _fill: (value: T, start?: number, end?: number) => void;
+    /** Concatenate with another array */
+    _concat: (other: T[]) => void;
+    /** Remove duplicates */
+    _uniq: () => void;
+    /** Randomly shuffle the array */
+    _shuffle: () => void;
+    /** Access item at index (supports negative index) */
+    _at: (i: number) => TypeAwareOps<T, A>;
+    /** Access the first item */
+    _first: () => TypeAwareOps<T, A>;
+    /** Access the last item */
+    _last: () => TypeAwareOps<T, A>;
+    /** Find item by predicate and return its proxy */
+    _findBy: (predicate: (item: T, index: number) => boolean) => TypeAwareOps<T, A> | undefined;
+};
+/** Operations specific to object values */
+type ObjectOps<T, A = any> = BaseOps<T, A> & {
+    /** Shallow merge the provided object into the current state */
+    _merge: (p: Partial<NonNullable<T>>) => void;
+    /** Remove a specific key from the object */
+    _delete: (k: keyof NonNullable<T>) => void;
+    /** Pick only specific keys (removes others) */
+    _pick: (keys: (keyof NonNullable<T>)[]) => void;
+    /** Omit specific keys */
+    _omit: (keys: (keyof NonNullable<T>)[]) => void;
+    /** Set default values for undefined keys */
+    _defaults: (defaults: Partial<NonNullable<T>>) => void;
+    /** Clear all keys (empty object) */
+    _clear: () => void;
+    /** Deep clone (re-assigns self) */
+    _clone: () => void;
+    /** Assign properties from source (alias to merge) */
+    _assign: (source: Partial<NonNullable<T>>) => void;
+    /** Map over values and update */
+    _mapValues: (fn: (value: any, key: keyof T) => any) => void;
+} & {
+    [K in keyof NonNullable<T>]-?: TypeAwareOps<NonNullable<T>[K], A>;
+};
+type BooleanOps<A = any> = BaseOps<boolean, A> & {
+    _toggle: () => void;
+};
+
+export type { ActionOpsObject as A, BaseOps as B, ContextGetterOps as C, DerivedFlowDefinition as D, FlowDefinition as F, NumberOps as N, ObjectOps as O, StringOps as S, TypeAwareOps as T, UseFlowOptions as U, FlowOptions as a, FlowOperations as b, ArrayOps as c, BooleanOps as d, BoundActions as e, FlowAction as f, FlowEffect as g, FlowOpsObject as h, FlowPlugin as i };

package/package.json

@@ -46,7 +46,7 @@
       "types": "./dist/devtools.d.ts"
     },
     "./package.json": "./package.json",
-    "./plugins": {
+    "./plugins": { 
       "default": "./dist/cjs/plugins.js",
       "import": "./dist/esm/plugins.js",
       "require": "./dist/cjs/plugins.js",
@@ -112,5 +112,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "4.8.4"
+  "version": "4.8.6"
 }