@asaidimu/react-store 3.0.0 → 5.0.0

package/index.cjs

@@ -1 +1 @@
-"use strict";var e=require("react"),t=require("@asaidimu/utils-store"),r=class{executions=[];maxHistory=100;listeners=new Set;track(e){this.executions.unshift(e),this.executions.length>this.maxHistory&&this.executions.pop(),this.notify()}getExecutions(){return[...this.executions]}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(){this.listeners.forEach((e=>e()))}};exports.createStore=function(s,{enableMetrics:n,...a}={}){const i=new t.ReactiveDataStore(s.state,a.persistence),c=Object.keys(s.actions).reduce(((e,t)=>(e[t]=!1,e)),{}),o=new t.ReactiveDataStore(c),u=n?new t.StoreObserver(i,a):void 0,d=n?new r:void 0;n&&d&&(i.on("action:start",(({name:e})=>{o.set((()=>({[e]:!0})))})),i.on("action:complete",(e=>{o.set((()=>({[e.name]:!1}))),d.track({id:e.actionId,name:e.name,params:e.params,startTime:e.startTime,endTime:e.endTime,duration:e.duration,status:"success",result:e.result})})),i.on("action:error",(e=>{o.set((()=>({[e.name]:!1}))),d.track({id:e.actionId,name:e.name,params:e.params,startTime:e.startTime,endTime:e.endTime,duration:e.duration,status:"error",error:e.error})}))),s.middleware&&Object.entries(s.middleware).forEach((([e,t])=>i.use({name:e,action:t}))),s.blockingMiddleware&&Object.entries(s.blockingMiddleware).forEach((([e,t])=>i.use({block:!0,name:e,action:t})));const l=e=>(i.isReady()&&e(),i.on("persistence:ready",e)),m=()=>i.isReady(),h=new t.ArtifactContainer(i);s.artifacts&&Object.entries(s.artifacts).forEach((([e,t])=>{h.register({key:e,factory:t.factory,scope:t.scope,lazy:t.lazy})}));const y=Object.entries(s.actions).reduce(((e,[t,r])=>(i.register({name:t,fn:(e,...t)=>{const s={state:e,resolve:h.resolve.bind(h)};return r(s,...t)}}),e[t]=(...e)=>i.dispatch(t,...e),e)),{});return function(){const t=()=>e.useSyncExternalStore((e=>i.watch("",e)),(()=>i.get()),(()=>i.get())),r=e.useSyncExternalStore(l,m,m);return{store:i,observer:u,select:t=>{const r=i.select(t);return e.useSyncExternalStore((e=>r.subscribe(e)),(()=>r.get()),(()=>r.get()))},actions:y,isReady:r,actionTracker:d,watch:t=>e.useSyncExternalStore((e=>o.watch(t,e)),(()=>!!o.get()[t]),(()=>!!o.get()[t])),resolve:t=>{const r=e.useSyncExternalStore((e=>h.subscribeToArtifact(t,e)),(()=>h.get(t)),(()=>h.get(t)));e.useEffect((()=>{void 0!==r||h.isLoading(t)||h.resolve(t).catch(console.error)}),[t,r]);return[r,null!=r]},get state(){return t}}}};
+"use strict";var e=require("react"),t=require("@asaidimu/utils-store"),r=require("@asaidimu/utils-artifacts"),s=class{executions=[];maxHistory=100;listeners=new Set;track(e){this.executions.unshift(e),this.executions.length>this.maxHistory&&this.executions.pop(),this.notify()}getExecutions(){return[...this.executions]}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(){this.listeners.forEach(e=>e())}};exports.createStore=function(a,{enableMetrics:n,...i}={}){const c=new t.ReactiveDataStore(a.state,i.persistence),o=Object.keys(a.actions).reduce((e,t)=>(e[t]=!1,e),{}),u=new t.ReactiveDataStore(o),l=n?new t.StoreObserver(c,i):void 0,d=n?new s:void 0;n&&d&&(c.on("action:start",({name:e})=>{u.set(()=>({[e]:!0}))}),c.on("action:complete",e=>{u.set(()=>({[e.name]:!1})),d.track({id:e.actionId,name:e.name,params:e.params,startTime:e.startTime,endTime:e.endTime,duration:e.duration,status:"success",result:e.result})}),c.on("action:error",e=>{u.set(()=>({[e.name]:!1})),d.track({id:e.actionId,name:e.name,params:e.params,startTime:e.startTime,endTime:e.endTime,duration:e.duration,status:"error",error:e.error})}));const m=e=>(c.isReady()&&e(),c.on("persistence:ready",e)),h=()=>c.isReady(),y=new r.ArtifactContainer(c),f=y.resolve.bind(y);a.artifacts&&Object.entries(a.artifacts).forEach(([e,t])=>{y.register({key:e,factory:t.factory,scope:t.scope,lazy:t.lazy})}),a.transform&&Object.entries(a.transform).forEach(([e,t])=>{c.use({name:e,action:(e,r)=>t({state:e,resolve:f},r)})}),a.validate&&Object.entries(a.validate).forEach(([e,t])=>{c.use({block:!0,name:e,action:(e,r)=>t({state:e,resolve:f},r)})});const b=Object.entries(a.actions).reduce((e,[t,r])=>(c.register({name:t,fn:(e,...t)=>r({state:e,resolve:f},...t)}),e[t]=(...e)=>c.dispatch(t,...e),e),{});return function(){const t=()=>e.useSyncExternalStore(e=>c.watch("",e),()=>c.get(),()=>c.get()),r=e.useSyncExternalStore(m,h,h);return{select:t=>{const r=c.select(t);return e.useSyncExternalStore(e=>r.subscribe(e),()=>r.get(),()=>r.get())},watch:t=>e.useSyncExternalStore(e=>u.watch(t,e),()=>!!u.get()[t],()=>!!u.get()[t]),resolve:t=>{const r=y.watch(t);return e.useSyncExternalStore(e=>r.subscribe(()=>e()),()=>r.get(),()=>r.get())},actions:b,isReady:r,store:c,observer:l,actionTracker:d,get state(){return t}}}};

package/index.d.cts

@@ -1,65 +1,191 @@
 import { SimplePersistence } from '@asaidimu/utils-persistence';
-import { DeepPartial, ArtifactFactory, ArtifactScope, ObserverOptions, BlockingMiddleware, Middleware } from '@asaidimu/utils-store';
+import { DeepPartial, ObserverOptions, ReactiveDataStore, StoreObserver } from '@asaidimu/utils-store';
+import { ResolvedArtifact, ArtifactScope as ArtifactScope$1, ArtifactTemplate, InferRegistry, ArtifactValue } from '@asaidimu/utils-artifacts';
 
-interface ActionContext<TState extends object, TResolvedArtifacts extends object> {
+interface ActionExecution {
+    id: string;
+    name: string;
+    params: unknown[];
+    startTime: number;
+    endTime: number;
+    duration: number;
+    status: 'success' | 'error';
+    error?: Error;
+    result?: unknown;
+}
+declare class ActionTracker {
+    private executions;
+    private maxHistory;
+    private listeners;
+    track(execution: ActionExecution): void;
+    getExecutions(): ActionExecution[];
+    subscribe(listener: () => void): () => boolean;
+    private notify;
+}
+
+/**
+ * The context object provided as the first argument to all actions, transforms, and validators.
+ * It provides access to the current state and the artifact resolution system.
+ *
+ * @template TState The shape of the main store state.
+ * @template TRegistry The inferred type of the entire artifact registry.
+ */
+interface ActionContext<TState extends object, TRegistry extends Record<string, any>> {
     /**
-     * Resolve an artifact.
-     * This records a dependency between the caller and the requested artifact.
+     * Resolve an artifact, recording a dependency between the caller and the requested artifact.
+     * This function is asynchronous because artifact factories can be asynchronous.
+     *
+     * @param key The name of the artifact to resolve.
+     * @returns A promise that resolves to the resolved artifact instance and its metadata.
+     */
+    resolve<K extends keyof TRegistry>(key: K): Promise<ResolvedArtifact<TRegistry[K]>>;
+    /**
+     * The current snapshot of the store state.
      */
-    resolve<K extends keyof TResolvedArtifacts>(key: K): Promise<TResolvedArtifacts[K]>;
     state: TState;
 }
-type ActionImplementation<TState extends object, TResolvedArtifacts extends object, TArgs extends any[]> = (ctx: ActionContext<TState, TResolvedArtifacts>, ...args: TArgs) => DeepPartial<TState> | Promise<DeepPartial<TState>>;
-type ArtifactDefinition<TState extends Object, R> = {
-    factory: ArtifactFactory<TState, R>;
-    scope?: ArtifactScope;
-    lazy?: boolean;
-};
-type ArtifactsMap<TState extends object> = Record<string, ArtifactDefinition<TState, any>>;
-type ExtractArtifactInstanceFromConfig<T> = T extends {
-    factory: ArtifactFactory<any, infer I>;
-} ? I : never;
-type ExtractInstanceFromMap<TMap extends ArtifactsMap<any>, TKey extends keyof TMap> = ExtractArtifactInstanceFromConfig<TMap[TKey]>;
-type ResolvedArtifactsMap<TArtifactsMap extends ArtifactsMap<any>> = {
-    [K in keyof TArtifactsMap]: ExtractInstanceFromMap<TArtifactsMap, K>;
-};
-type ActionMap<TState extends object, TArtifactsMap extends ArtifactsMap<TState>> = Record<string, ActionImplementation<TState, ResolvedArtifactsMap<TArtifactsMap>, any[]>>;
 /**
- * Bounds the actions for the resulting store hook, removing the context argument.
+ * Re-exports the ArtifactScope for use in the store's definition.
+ */
+type ArtifactScope = ArtifactScope$1;
+/**
+ * The core function signature for an Action.
+ * It takes the context and any custom arguments, and returns a (potentially partial)
+ * update to the state or a Promise resolving to the update.
+ *
+ * @template TState The shape of the main store state.
+ * @template TRegistry The inferred type of the entire artifact registry.
+ * @template TArgs The custom arguments accepted by the action.
+ */
+type ActionImplementation<TState extends object, TRegistry extends Record<string, any>, TArgs extends any[]> = (ctx: ActionContext<TState, TRegistry>, ...args: TArgs) => DeepPartial<TState> | Promise<DeepPartial<TState>>;
+/**
+ * A map of all artifact definitions keyed by their names.
+ *
+ * @template TState The shape of the main store state.
+ */
+type ArtifactsMap<TState extends object> = Record<string, Omit<ArtifactTemplate<TState, any, any>, "key">>;
+/**
+ * A map of all ActionImplementations keyed by their action names.
+ *
+ * @template TState The shape of the main store state.
+ * @template TArtifactsMap The map of artifact definitions.
+ */
+type ActionMap<TState extends object, TArtifactsMap extends ArtifactsMap<TState>> = Record<string, ActionImplementation<TState, InferRegistry<TArtifactsMap>, any[]>>;
+/**
+ * Utility type to extract the non-context arguments (the "tail" parameters) from an ActionImplementation.
+ */
+type TailParams<F, TState extends object, TRegistry extends Record<string, any>> = F extends (ctx: ActionContext<TState, TRegistry>, ...args: infer R) => any ? R : never;
+/**
+ * Defines the public, bound signature of the store's actions.
+ * This removes the internal `ActionContext` argument and makes the return type a Promise
+ * that resolves when the state update is complete.
+ *
+ * @template TState The shape of the main store state.
+ * @template TArtifactsMap The map of artifact definitions.
+ * @template TActions The map of ActionImplementations.
  */
 type BoundActions<TState extends object, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>> = {
-    [K in keyof TActions]: (...args: Parameters<TActions[K]> extends [ActionContext<any, any>, ...infer R] ? R : never) => Promise<TState>;
+    [K in keyof TActions]: (...args: TailParams<TActions[K], TState, InferRegistry<TArtifactsMap>> extends [] ? [] : TailParams<TActions[K], TState, InferRegistry<TArtifactsMap>>) => Promise<TState>;
 };
+/**
+ * Tracks the loading status of specific actions, used for UI feedback.
+ */
 type LoadingState<TActions> = Partial<Record<keyof TActions, boolean>>;
+/**
+ * Configuration options for the store instance, governing features like metrics and persistence.
+ *
+ * @template T The shape of the store state.
+ */
 type StoreOptions<T> = ObserverOptions & {
     enableMetrics?: boolean;
     persistence?: SimplePersistence<T>;
 };
+/**
+ * A function that transforms a state update before it is committed.
+ * Runs after the action implementation but before state merge.
+ *
+ * @template TState The shape of the main store state.
+ * @template TArtifactsMap The map of artifact definitions.
+ */
+type Transformer<TState extends object, TArtifactsMap extends ArtifactsMap<TState>> = (ctx: ActionContext<TState, InferRegistry<TArtifactsMap>>, update: DeepPartial<TState>) => Promise<DeepPartial<TState>> | Promise<void> | DeepPartial<TState> | void;
+/**
+ * A function that validates a state update. If it returns false (or a Promise resolving to false),
+ * the update is cancelled, maintaining state consistency.
+ *
+ * @template TState The shape of the main store state.
+ * @template TArtifactsMap The map of artifact definitions.
+ */
+type Validator<TState extends object, TArtifactsMap extends ArtifactsMap<TState>> = (ctx: ActionContext<TState, InferRegistry<TArtifactsMap>>, update: DeepPartial<TState>) => Promise<boolean> | boolean;
+/**
+ * The main configuration object used to create a store.
+ *
+ * @template TState The initial shape of the store state.
+ * @template TArtifactsMap The map of service/dependency definitions (Artifacts).
+ * @template TActions The map of state mutation functions (Actions).
+ */
 interface StoreDefinition<TState extends object, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>> {
+    /** The initial state of the store. */
     state: TState;
+    /** A map of functions that mutate the state. */
     actions: TActions;
+    /** An optional map of asynchronous resources or services (Artifacts). */
     artifacts?: TArtifactsMap;
+    /** Optional initial loading state for specific actions. */
     loading?: LoadingState<TActions>;
+    /** Optional function to synchronize state with an external system after changes. */
     sync?: (args: TState) => void;
-    blockingMiddleware?: Record<string, BlockingMiddleware<TState>>;
-    middleware?: Record<string, Middleware<TState>>;
+    /** Optional map of transformers that run after an action but before state merge. */
+    transform?: Record<string, Transformer<TState, TArtifactsMap>>;
+    /** Optional map of validators that run before state merge to check for correctness. */
+    validate?: Record<string, Validator<TState, TArtifactsMap>>;
 }
+/**
+ * The resulting React hook function returned by `createStore`.
+ * When called inside a component, it provides reactive access to the store's capabilities.
+ *
+ * @template TState The shape of the store state.
+ * @template TArtifactsMap The map of artifact definitions.
+ * @template TActions The map of action definitions.
+ */
 type StoreHook<TState extends object, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>> = () => {
-    store: any;
-    observer: any;
+    /** Internal store instance. */
+    store: ReactiveDataStore<TState>;
+    /** Internal observer instance. */
+    observer: StoreObserver<TState>;
+    /**
+     * Selects a value from the state using a memoized selector function.
+     * Only causes a re-render if the selected value changes.
+     *
+     * @param selector A function to derive data from the store state.
+     */
     select: <S>(selector: (state: TState) => S) => S;
+    /** The publicly available, bound actions for mutating state. */
     actions: BoundActions<TState, TArtifactsMap, TActions>;
     /**
      * Reactive Artifact Resolver.
-     * Returns [instance, isReady].
+     * Returns the resolved artifact with instance and metadata (ready status).
+     * Causes a re-render when the artifact's dependencies (e.g., state) change.
+     *
+     * @param key The name of the artifact to resolve.
      */
-    resolve: <K extends keyof TArtifactsMap>(key: K) => readonly [ExtractInstanceFromMap<TArtifactsMap, K>, true] | readonly [ExtractInstanceFromMap<TArtifactsMap, K> | undefined, false];
+    resolve: <K extends keyof TArtifactsMap>(key: K) => ResolvedArtifact<ArtifactValue<TArtifactsMap[K]>>;
+    /** Flag indicating if the store and its essential artifacts are ready for use. */
     isReady: boolean;
-    actionTracker: any;
+    /** Tracker for monitoring in-flight or completed actions. */
+    actionTracker: ActionTracker;
+    /**
+     * Watches a specific action and returns its loading state (true if running).
+     *
+     * @param action The name of the action to watch.
+     */
     watch: (action: keyof TActions) => boolean;
+    /**
+     * Returns the current, non-reactive snapshot of the store state.
+     * Calling this will NOT trigger component re-renders when state changes.
+     */
     state: () => TState;
 };
 
 declare function createStore<TState extends Record<string, unknown>, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>>(definition: StoreDefinition<TState, TArtifactsMap, TActions>, { enableMetrics, ...options }?: StoreOptions<TState>): StoreHook<TState, TArtifactsMap, TActions>;
 
-export { type ActionContext, type ActionImplementation, type ActionMap, type ArtifactDefinition, type ArtifactsMap, type BoundActions, type ExtractArtifactInstanceFromConfig, type ExtractInstanceFromMap, type LoadingState, type ResolvedArtifactsMap, type StoreDefinition, type StoreHook, type StoreOptions, createStore };
+export { type ActionContext, type ActionImplementation, type ActionMap, type ArtifactScope, type ArtifactsMap, type BoundActions, type LoadingState, type StoreDefinition, type StoreHook, type StoreOptions, type Transformer, type Validator, createStore };

package/index.d.ts

@@ -1,65 +1,191 @@
 import { SimplePersistence } from '@asaidimu/utils-persistence';
-import { DeepPartial, ArtifactFactory, ArtifactScope, ObserverOptions, BlockingMiddleware, Middleware } from '@asaidimu/utils-store';
+import { DeepPartial, ObserverOptions, ReactiveDataStore, StoreObserver } from '@asaidimu/utils-store';
+import { ResolvedArtifact, ArtifactScope as ArtifactScope$1, ArtifactTemplate, InferRegistry, ArtifactValue } from '@asaidimu/utils-artifacts';
 
-interface ActionContext<TState extends object, TResolvedArtifacts extends object> {
+interface ActionExecution {
+    id: string;
+    name: string;
+    params: unknown[];
+    startTime: number;
+    endTime: number;
+    duration: number;
+    status: 'success' | 'error';
+    error?: Error;
+    result?: unknown;
+}
+declare class ActionTracker {
+    private executions;
+    private maxHistory;
+    private listeners;
+    track(execution: ActionExecution): void;
+    getExecutions(): ActionExecution[];
+    subscribe(listener: () => void): () => boolean;
+    private notify;
+}
+
+/**
+ * The context object provided as the first argument to all actions, transforms, and validators.
+ * It provides access to the current state and the artifact resolution system.
+ *
+ * @template TState The shape of the main store state.
+ * @template TRegistry The inferred type of the entire artifact registry.
+ */
+interface ActionContext<TState extends object, TRegistry extends Record<string, any>> {
     /**
-     * Resolve an artifact.
-     * This records a dependency between the caller and the requested artifact.
+     * Resolve an artifact, recording a dependency between the caller and the requested artifact.
+     * This function is asynchronous because artifact factories can be asynchronous.
+     *
+     * @param key The name of the artifact to resolve.
+     * @returns A promise that resolves to the resolved artifact instance and its metadata.
+     */
+    resolve<K extends keyof TRegistry>(key: K): Promise<ResolvedArtifact<TRegistry[K]>>;
+    /**
+     * The current snapshot of the store state.
      */
-    resolve<K extends keyof TResolvedArtifacts>(key: K): Promise<TResolvedArtifacts[K]>;
     state: TState;
 }
-type ActionImplementation<TState extends object, TResolvedArtifacts extends object, TArgs extends any[]> = (ctx: ActionContext<TState, TResolvedArtifacts>, ...args: TArgs) => DeepPartial<TState> | Promise<DeepPartial<TState>>;
-type ArtifactDefinition<TState extends Object, R> = {
-    factory: ArtifactFactory<TState, R>;
-    scope?: ArtifactScope;
-    lazy?: boolean;
-};
-type ArtifactsMap<TState extends object> = Record<string, ArtifactDefinition<TState, any>>;
-type ExtractArtifactInstanceFromConfig<T> = T extends {
-    factory: ArtifactFactory<any, infer I>;
-} ? I : never;
-type ExtractInstanceFromMap<TMap extends ArtifactsMap<any>, TKey extends keyof TMap> = ExtractArtifactInstanceFromConfig<TMap[TKey]>;
-type ResolvedArtifactsMap<TArtifactsMap extends ArtifactsMap<any>> = {
-    [K in keyof TArtifactsMap]: ExtractInstanceFromMap<TArtifactsMap, K>;
-};
-type ActionMap<TState extends object, TArtifactsMap extends ArtifactsMap<TState>> = Record<string, ActionImplementation<TState, ResolvedArtifactsMap<TArtifactsMap>, any[]>>;
 /**
- * Bounds the actions for the resulting store hook, removing the context argument.
+ * Re-exports the ArtifactScope for use in the store's definition.
+ */
+type ArtifactScope = ArtifactScope$1;
+/**
+ * The core function signature for an Action.
+ * It takes the context and any custom arguments, and returns a (potentially partial)
+ * update to the state or a Promise resolving to the update.
+ *
+ * @template TState The shape of the main store state.
+ * @template TRegistry The inferred type of the entire artifact registry.
+ * @template TArgs The custom arguments accepted by the action.
+ */
+type ActionImplementation<TState extends object, TRegistry extends Record<string, any>, TArgs extends any[]> = (ctx: ActionContext<TState, TRegistry>, ...args: TArgs) => DeepPartial<TState> | Promise<DeepPartial<TState>>;
+/**
+ * A map of all artifact definitions keyed by their names.
+ *
+ * @template TState The shape of the main store state.
+ */
+type ArtifactsMap<TState extends object> = Record<string, Omit<ArtifactTemplate<TState, any, any>, "key">>;
+/**
+ * A map of all ActionImplementations keyed by their action names.
+ *
+ * @template TState The shape of the main store state.
+ * @template TArtifactsMap The map of artifact definitions.
+ */
+type ActionMap<TState extends object, TArtifactsMap extends ArtifactsMap<TState>> = Record<string, ActionImplementation<TState, InferRegistry<TArtifactsMap>, any[]>>;
+/**
+ * Utility type to extract the non-context arguments (the "tail" parameters) from an ActionImplementation.
+ */
+type TailParams<F, TState extends object, TRegistry extends Record<string, any>> = F extends (ctx: ActionContext<TState, TRegistry>, ...args: infer R) => any ? R : never;
+/**
+ * Defines the public, bound signature of the store's actions.
+ * This removes the internal `ActionContext` argument and makes the return type a Promise
+ * that resolves when the state update is complete.
+ *
+ * @template TState The shape of the main store state.
+ * @template TArtifactsMap The map of artifact definitions.
+ * @template TActions The map of ActionImplementations.
  */
 type BoundActions<TState extends object, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>> = {
-    [K in keyof TActions]: (...args: Parameters<TActions[K]> extends [ActionContext<any, any>, ...infer R] ? R : never) => Promise<TState>;
+    [K in keyof TActions]: (...args: TailParams<TActions[K], TState, InferRegistry<TArtifactsMap>> extends [] ? [] : TailParams<TActions[K], TState, InferRegistry<TArtifactsMap>>) => Promise<TState>;
 };
+/**
+ * Tracks the loading status of specific actions, used for UI feedback.
+ */
 type LoadingState<TActions> = Partial<Record<keyof TActions, boolean>>;
+/**
+ * Configuration options for the store instance, governing features like metrics and persistence.
+ *
+ * @template T The shape of the store state.
+ */
 type StoreOptions<T> = ObserverOptions & {
     enableMetrics?: boolean;
     persistence?: SimplePersistence<T>;
 };
+/**
+ * A function that transforms a state update before it is committed.
+ * Runs after the action implementation but before state merge.
+ *
+ * @template TState The shape of the main store state.
+ * @template TArtifactsMap The map of artifact definitions.
+ */
+type Transformer<TState extends object, TArtifactsMap extends ArtifactsMap<TState>> = (ctx: ActionContext<TState, InferRegistry<TArtifactsMap>>, update: DeepPartial<TState>) => Promise<DeepPartial<TState>> | Promise<void> | DeepPartial<TState> | void;
+/**
+ * A function that validates a state update. If it returns false (or a Promise resolving to false),
+ * the update is cancelled, maintaining state consistency.
+ *
+ * @template TState The shape of the main store state.
+ * @template TArtifactsMap The map of artifact definitions.
+ */
+type Validator<TState extends object, TArtifactsMap extends ArtifactsMap<TState>> = (ctx: ActionContext<TState, InferRegistry<TArtifactsMap>>, update: DeepPartial<TState>) => Promise<boolean> | boolean;
+/**
+ * The main configuration object used to create a store.
+ *
+ * @template TState The initial shape of the store state.
+ * @template TArtifactsMap The map of service/dependency definitions (Artifacts).
+ * @template TActions The map of state mutation functions (Actions).
+ */
 interface StoreDefinition<TState extends object, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>> {
+    /** The initial state of the store. */
     state: TState;
+    /** A map of functions that mutate the state. */
     actions: TActions;
+    /** An optional map of asynchronous resources or services (Artifacts). */
     artifacts?: TArtifactsMap;
+    /** Optional initial loading state for specific actions. */
     loading?: LoadingState<TActions>;
+    /** Optional function to synchronize state with an external system after changes. */
     sync?: (args: TState) => void;
-    blockingMiddleware?: Record<string, BlockingMiddleware<TState>>;
-    middleware?: Record<string, Middleware<TState>>;
+    /** Optional map of transformers that run after an action but before state merge. */
+    transform?: Record<string, Transformer<TState, TArtifactsMap>>;
+    /** Optional map of validators that run before state merge to check for correctness. */
+    validate?: Record<string, Validator<TState, TArtifactsMap>>;
 }
+/**
+ * The resulting React hook function returned by `createStore`.
+ * When called inside a component, it provides reactive access to the store's capabilities.
+ *
+ * @template TState The shape of the store state.
+ * @template TArtifactsMap The map of artifact definitions.
+ * @template TActions The map of action definitions.
+ */
 type StoreHook<TState extends object, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>> = () => {
-    store: any;
-    observer: any;
+    /** Internal store instance. */
+    store: ReactiveDataStore<TState>;
+    /** Internal observer instance. */
+    observer: StoreObserver<TState>;
+    /**
+     * Selects a value from the state using a memoized selector function.
+     * Only causes a re-render if the selected value changes.
+     *
+     * @param selector A function to derive data from the store state.
+     */
     select: <S>(selector: (state: TState) => S) => S;
+    /** The publicly available, bound actions for mutating state. */
     actions: BoundActions<TState, TArtifactsMap, TActions>;
     /**
      * Reactive Artifact Resolver.
-     * Returns [instance, isReady].
+     * Returns the resolved artifact with instance and metadata (ready status).
+     * Causes a re-render when the artifact's dependencies (e.g., state) change.
+     *
+     * @param key The name of the artifact to resolve.
      */
-    resolve: <K extends keyof TArtifactsMap>(key: K) => readonly [ExtractInstanceFromMap<TArtifactsMap, K>, true] | readonly [ExtractInstanceFromMap<TArtifactsMap, K> | undefined, false];
+    resolve: <K extends keyof TArtifactsMap>(key: K) => ResolvedArtifact<ArtifactValue<TArtifactsMap[K]>>;
+    /** Flag indicating if the store and its essential artifacts are ready for use. */
     isReady: boolean;
-    actionTracker: any;
+    /** Tracker for monitoring in-flight or completed actions. */
+    actionTracker: ActionTracker;
+    /**
+     * Watches a specific action and returns its loading state (true if running).
+     *
+     * @param action The name of the action to watch.
+     */
     watch: (action: keyof TActions) => boolean;
+    /**
+     * Returns the current, non-reactive snapshot of the store state.
+     * Calling this will NOT trigger component re-renders when state changes.
+     */
     state: () => TState;
 };
 
 declare function createStore<TState extends Record<string, unknown>, TArtifactsMap extends ArtifactsMap<TState>, TActions extends ActionMap<TState, TArtifactsMap>>(definition: StoreDefinition<TState, TArtifactsMap, TActions>, { enableMetrics, ...options }?: StoreOptions<TState>): StoreHook<TState, TArtifactsMap, TActions>;
 
-export { type ActionContext, type ActionImplementation, type ActionMap, type ArtifactDefinition, type ArtifactsMap, type BoundActions, type ExtractArtifactInstanceFromConfig, type ExtractInstanceFromMap, type LoadingState, type ResolvedArtifactsMap, type StoreDefinition, type StoreHook, type StoreOptions, createStore };
+export { type ActionContext, type ActionImplementation, type ActionMap, type ArtifactScope, type ArtifactsMap, type BoundActions, type LoadingState, type StoreDefinition, type StoreHook, type StoreOptions, type Transformer, type Validator, createStore };

package/index.js

@@ -1 +1 @@
-import{useSyncExternalStore as e,useEffect as t}from"react";import{ReactiveDataStore as s,StoreObserver as r,ArtifactContainer as i}from"@asaidimu/utils-store";var n=class{executions=[];maxHistory=100;listeners=new Set;track(e){this.executions.unshift(e),this.executions.length>this.maxHistory&&this.executions.pop(),this.notify()}getExecutions(){return[...this.executions]}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(){this.listeners.forEach((e=>e()))}};function a(a,{enableMetrics:o,...c}={}){const d=new s(a.state,c.persistence),u=Object.keys(a.actions).reduce(((e,t)=>(e[t]=!1,e)),{}),m=new s(u),l=o?new r(d,c):void 0,h=o?new n:void 0;o&&h&&(d.on("action:start",(({name:e})=>{m.set((()=>({[e]:!0})))})),d.on("action:complete",(e=>{m.set((()=>({[e.name]:!1}))),h.track({id:e.actionId,name:e.name,params:e.params,startTime:e.startTime,endTime:e.endTime,duration:e.duration,status:"success",result:e.result})})),d.on("action:error",(e=>{m.set((()=>({[e.name]:!1}))),h.track({id:e.actionId,name:e.name,params:e.params,startTime:e.startTime,endTime:e.endTime,duration:e.duration,status:"error",error:e.error})}))),a.middleware&&Object.entries(a.middleware).forEach((([e,t])=>d.use({name:e,action:t}))),a.blockingMiddleware&&Object.entries(a.blockingMiddleware).forEach((([e,t])=>d.use({block:!0,name:e,action:t})));const b=e=>(d.isReady()&&e(),d.on("persistence:ready",e)),f=()=>d.isReady(),g=new i(d);a.artifacts&&Object.entries(a.artifacts).forEach((([e,t])=>{g.register({key:e,factory:t.factory,scope:t.scope,lazy:t.lazy})}));const p=Object.entries(a.actions).reduce(((e,[t,s])=>(d.register({name:t,fn:(e,...t)=>{const r={state:e,resolve:g.resolve.bind(g)};return s(r,...t)}}),e[t]=(...e)=>d.dispatch(t,...e),e)),{});return function(){const s=()=>e((e=>d.watch("",e)),(()=>d.get()),(()=>d.get())),r=e(b,f,f);return{store:d,observer:l,select:t=>{const s=d.select(t);return e((e=>s.subscribe(e)),(()=>s.get()),(()=>s.get()))},actions:p,isReady:r,actionTracker:h,watch:t=>e((e=>m.watch(t,e)),(()=>!!m.get()[t]),(()=>!!m.get()[t])),resolve:s=>{const r=e((e=>g.subscribeToArtifact(s,e)),(()=>g.get(s)),(()=>g.get(s)));t((()=>{void 0!==r||g.isLoading(s)||g.resolve(s).catch(console.error)}),[s,r]);return[r,null!=r]},get state(){return s}}}}export{a as createStore};
+import{useSyncExternalStore as e}from"react";import{ReactiveDataStore as t,StoreObserver as s}from"@asaidimu/utils-store";import{ArtifactContainer as r}from"@asaidimu/utils-artifacts";var a=class{executions=[];maxHistory=100;listeners=new Set;track(e){this.executions.unshift(e),this.executions.length>this.maxHistory&&this.executions.pop(),this.notify()}getExecutions(){return[...this.executions]}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(){this.listeners.forEach(e=>e())}};function i(i,{enableMetrics:n,...o}={}){const c=new t(i.state,o.persistence),u=Object.keys(i.actions).reduce((e,t)=>(e[t]=!1,e),{}),m=new t(u),d=n?new s(c,o):void 0,l=n?new a:void 0;n&&l&&(c.on("action:start",({name:e})=>{m.set(()=>({[e]:!0}))}),c.on("action:complete",e=>{m.set(()=>({[e.name]:!1})),l.track({id:e.actionId,name:e.name,params:e.params,startTime:e.startTime,endTime:e.endTime,duration:e.duration,status:"success",result:e.result})}),c.on("action:error",e=>{m.set(()=>({[e.name]:!1})),l.track({id:e.actionId,name:e.name,params:e.params,startTime:e.startTime,endTime:e.endTime,duration:e.duration,status:"error",error:e.error})}));const f=e=>(c.isReady()&&e(),c.on("persistence:ready",e)),h=()=>c.isReady(),p=new r(c),b=p.resolve.bind(p);i.artifacts&&Object.entries(i.artifacts).forEach(([e,t])=>{p.register({key:e,factory:t.factory,scope:t.scope,lazy:t.lazy})}),i.transform&&Object.entries(i.transform).forEach(([e,t])=>{c.use({name:e,action:(e,s)=>t({state:e,resolve:b},s)})}),i.validate&&Object.entries(i.validate).forEach(([e,t])=>{c.use({block:!0,name:e,action:(e,s)=>t({state:e,resolve:b},s)})});const y=Object.entries(i.actions).reduce((e,[t,s])=>(c.register({name:t,fn:(e,...t)=>s({state:e,resolve:b},...t)}),e[t]=(...e)=>c.dispatch(t,...e),e),{});return function(){const t=()=>e(e=>c.watch("",e),()=>c.get(),()=>c.get()),s=e(f,h,h);return{select:t=>{const s=c.select(t);return e(e=>s.subscribe(e),()=>s.get(),()=>s.get())},watch:t=>e(e=>m.watch(t,e),()=>!!m.get()[t],()=>!!m.get()[t]),resolve:t=>{const s=p.watch(t);return e(e=>s.subscribe(()=>e()),()=>s.get(),()=>s.get())},actions:y,isReady:s,store:c,observer:d,actionTracker:l,get state(){return t}}}}export{i as createStore};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/react-store",
-  "version": "3.0.0",
+  "version": "5.0.0",
   "description": "Efficient react state manager.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -26,10 +26,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@asaidimu/utils-persistence": "^2.1.0",
-    "@asaidimu/utils-store": "^4.0.0",
+    "@asaidimu/utils-artifacts": "^3.1.0",
+    "@asaidimu/utils-persistence": "^2.2.2",
+    "@asaidimu/utils-store": "^7.0.0",
     "hash-wasm": "^4.12.0",
-    "react": "^19.0.0",
+    "react": "^19.2.0",
     "uuid": "^11.1.0"
   }
 }