);

const ProductCatalog = () => {
const { select, actions, resolve } = useStore();
const products = select((state) => state.products); // Granular selection
const { instance: currencySymbol, ready: currencyReady } = resolve('currencySymbol'); // Reactive artifact resolution

return (

{products.map((product: Product) => (


{product.name}

{currencyReady ? currencySymbol : ''}{product.price.toFixed(2)}

{product.stock} in stock

actions.addToCart(product)} className="w-full">Add to Cart


))}

);
};

function App() {
const { actions, select } = useStore();
const currentCurrency = select((state) => state.currency);

useEffect(() => {
// Real-time simulations for the dashboard
const stockInterval = setInterval(() => actions.updateStock(), 2000);
const usersInterval = setInterval(() => actions.updateActiveUsers(), 3000);
const ordersInterval = setInterval(() => actions.addRandomOrder(), 5000);

return () => {
clearInterval(stockInterval);
clearInterval(usersInterval);
clearInterval(ordersInterval);
};
}, [actions]);

return (

E-Commerce Dashboard

value={currentCurrency}
onChange={(e) => actions.setCurrency(e.target.value)}
className="p-2 border rounded-md"
>
USD
EUR
GBP

{/ Placeholder for other components /}

{/ Placeholder for other components /}

);
}

export default App;
`

$3

To remove a property from the state, use the Symbol.for("delete") symbol in your action’s return value. The store’s internal merge function will remove the specified key from the state.

#### Example

`typescript
import { createStore } from '@asaidimu/react-store';

const deleteStore = createStore({
state: {
id: 'product-123',
name: 'Fancy Gadget',
details: {
color: 'blue',
weight: '1kg',
dimensions: { width: 10, height: 20 }
},
tags: ['electronics', 'new']
},
actions: {
removeDetails: (ctx) => ({ details: Symbol.for("delete") }),
removeDimensions: (ctx) => ({ details: { dimensions: Symbol.for("delete") } }),
removeTag: ({state}, tagToRemove: string) => ({
tags: state.tags.filter(tag => tag !== tagToRemove)
}),
clearAllExceptId: (ctx) => ({
name: Symbol.for("delete"),
details: Symbol.for("delete"),
tags: Symbol.for("delete")
})
},
});

async function runDeleteExample() {
const { select, actions } = deleteStore();

console.log("Initial state:", select(s => s));
// Initial state: { id: 'product-123', name: 'Fancy Gadget', details: { color: 'blue', weight: '1kg', dimensions: { width: 10, height: 20 } }, tags: ['electronics', 'new'] }

await actions.removeDimensions();
console.log("After removing dimensions:", select(s => s));
// After removing dimensions: { id: 'product-123', name: 'Fancy Gadget', details: { color: 'blue', weight: '1kg' }, tags: ['electronics', 'new'] }

await actions.removeDetails();
console.log("After removing details:", select(s => s));
// After removing details: { id: 'product-123', name: 'Fancy Gadget', tags: ['electronics', 'new'] }

await actions.removeTag('new');
console.log("After removing 'new' tag:", select(s => s));
// After removing 'new' tag: { id: 'product-123', name: 'Fancy Gadget', tags: ['electronics'] }

await actions.clearAllExceptId();
console.log("After clearing all except ID:", select(s => s));
// After clearing all except ID: { id: 'product-123' }
}

// In a real application, you would call runDeleteExample() in a component's useEffect or similar.
// runDeleteExample();
`

$3

Persist your store's state across browser sessions or synchronize it across multiple tabs using persistence adapters from @asaidimu/utils-persistence. You can choose between WebStoragePersistence (for localStorage or sessionStorage) and IndexedDBPersistence for more robust storage.

`tsx
import { createStore } from '@asaidimu/react-store';
import { WebStoragePersistence, IndexedDBPersistence } from '@asaidimu/utils-persistence';
import React, { useEffect } from 'react';

interface LocalState { sessionCount: number; lastVisited: string; }
interface SessionState { tabSpecificData: string; }
interface UserProfileState { userId: string; preferences: { language: string; darkMode: boolean; }; }

// 1. Using WebStoragePersistence (localStorage by default)
// Data persists even if the browser tab is closed and reopened.
const localStorePersistence = new WebStoragePersistence('my-app-state-key');
const useLocalStore = createStore(
{
state: { sessionCount: 0, lastVisited: new Date().toISOString() },
actions: {
incrementSessionCount: ({state}) => ({ sessionCount: state.sessionCount + 1 }),
updateLastVisited: () => ({ lastVisited: new Date().toISOString() }),
},
},
{ persistence: localStorePersistence },
);

// 2. Using WebStoragePersistence (sessionStorage)
// Data only persists for the duration of the browser tab. Clears on tab close.
const sessionStoragePersistence = new WebStoragePersistence('my-session-state-key', true);
const useSessionStore = createStore(
{
state: { tabSpecificData: 'initial' },
actions: {
updateTabSpecificData: (_, newData: string) => ({ tabSpecificData: newData }),
},
},
{ persistence: sessionStoragePersistence },
);

// 3. Using IndexedDBPersistence
// Ideal for larger amounts of data, offers robust cross-tab synchronization.
const indexedDBPersistence = new IndexedDBPersistence('user-profile-data');
const useUserProfileStore = createStore(
{
state: { userId: '', preferences: { language: 'en', darkMode: false } },
actions: {
setUserId: (_, id: string) => ({ userId: id }),
toggleDarkMode: ({state}) => ({ preferences: { darkMode: !state.preferences.darkMode } }),
},
},
{ persistence: indexedDBPersistence },
);

function AppWithPersistence() {
const { select: selectLocal, actions: actionsLocal, isReady: localReady } = useLocalStore();
const { select: selectProfile, actions: actionsProfile, isReady: profileReady } = useUserProfileStore();
const { select: selectSession, actions: actionsSession } = useSessionStore();


const sessionCount = selectLocal(s => s.sessionCount);
const darkMode = selectProfile(s => s.preferences.darkMode);
const tabData = selectSession(s => s.tabSpecificData);


useEffect(() => {
if (localReady) {
actionsLocal.incrementSessionCount();
actionsLocal.updateLastVisited();
}
if (profileReady && !selectProfile(s => s.userId)) {
actionsProfile.setUserId('user-' + Math.random().toString(36).substring(2, 9));
}
}, [localReady, profileReady, actionsLocal, actionsProfile, selectProfile]);

if (!localReady || !profileReady) {
return

Middleware functions can intercept and modify or block state updates. The CHANGELOG.md indicates a breaking change, moving from generic middleware and blockingMiddleware to transform and validate properties in the StoreDefinition. These now receive an ActionContext with state and resolve capabilities.

transform: Functions that run after an action's core logic but before* the state update is committed. They can modify the DeepPartial that will be merged into the state.
validate: Functions that run before* the state update is committed. If a validator returns false (or a Promise), the state update is entirely cancelled.

`typescript
import { createStore } from '@asaidimu/react-store';
import React from 'react';

interface CartState {
items: Array<{ id: string; name: string; quantity: number; price: number }>;
total: number;
}

const useCartStore = createStore({ // TArtifactsMap and TActions are inferred
state: { items: [], total: 0 },
actions: {
addItem: ({state}, item: { id: string; name: string; price: number }) => {
const existingItem = state.items.find(i => i.id === item.id);
if (existingItem) {
return {
items: state.items.map(i =>
i.id === item.id ? { ...i, quantity: i.quantity + 1 } : i
),
};
}
return {
items: [...state.items, { ...item, quantity: 1 }],
};
},
updateQuantity: ({state}, id: string, quantity: number) => ({
items: state.items.map(item => (item.id === id ? { ...item, quantity } : item)),
}),
},
transform: {
// Calculates total based on updated items before state merge
calculateTotal: async ({ state, resolve }, update) => {
if (update.items) {
const newItems = update.items as CartState['items'];
const newTotal = newItems.reduce((sum, item) => sum + (item.quantity * item.price), 0);
return { ...update, total: newTotal };
}
return update;
},
},
validate: {
// Blocks update if any item quantity is negative
validateItemQuantity: async ({ state, resolve }, update) => {
if (update.items) {
for (const item of update.items as CartState['items']) {
if (item.quantity < 0) {
console.warn('Blocked by validator: Item quantity cannot be negative.');
return false; // Blocks the update
}
}
}
return true; // Allows the update
},
},
});

function CartComponent() {
const { select, actions } = useCartStore();
const items = select(s => s.items);
const total = select(s => s.total);

return (


The store supports defining and reactively resolving "artifacts," which can be any asynchronous resource, service, or derived value. Artifacts are defined in the artifacts property of the StoreDefinition and resolved using ctx.resolve() within actions or the resolve() hook in components. They can depend on other artifacts or on the store's reactive state.

`tsx
import { createStore } from '@asaidimu/react-store';
import { ArtifactScopes } from '@asaidimu/utils-artifacts';
import React, { useEffect } from 'react';

interface AppState {
userId: string | null;
settingsLoaded: boolean;
theme: string;
}

// Assume this is an API service or similar
const mockApiService = {
fetchUserSettings: async (userId: string) => {
await new Promise(r => setTimeout(r, 200)); // Simulate API delay
if (userId === 'user-123') {
return { theme: 'dark', notifications: true };
}
return { theme: 'light', notifications: false };
},
};

const useArtifactStore = createStore({
state: { userId: null, settingsLoaded: false, theme: 'light' },
actions: {
setUserId: (_, id: string) => ({ userId: id, settingsLoaded: false }),
loadUserSettings: async ({ state, resolve }) => {
if (!state.userId) return;

const { instance: userSettings } = await resolve('userSettings');
if (userSettings) {
return {
settingsLoaded: true,
theme: userSettings.theme,
};
}
return {};
},
toggleTheme: ({state}) => ({ theme: state.theme === 'light' ? 'dark' : 'light' }),
},
artifacts: {
// A singleton artifact that fetches user settings based on the current userId in state
userSettings: {
scope: ArtifactScopes.Singleton, // Ensure only one instance is created globally
factory: async ({ use }) => {
const userId = await use(({ select }) => select((s: AppState) => s.userId));
if (userId) {
console.log(Fetching settings for user: ${userId});
return mockApiService.fetchUserSettings(userId);
}
return null;
},
lazy: true, // Only create/resolve when first requested
},
// An artifact that provides a simple logger instance
logger: {
factory: async () => console,
scope: ArtifactScopes.Singleton,
},
},
});

function ArtifactConsumer() {
const { actions, select, resolve, isReady } = useArtifactStore();
const userId = select(s => s.userId);
const theme = select(s => s.theme);
const settingsLoaded = select(s => s.settingsLoaded);

// Reactively resolve the userSettings artifact in the component
const { instance: userSettingsArtifact, ready: userSettingsReady } = resolve('userSettings');
const { instance: logger } = resolve('logger');

useEffect(() => {
// Simulate setting a user ID after initial load
if (isReady && !userId) {
actions.setUserId('user-123');
}
}, [isReady, userId, actions]);

useEffect(() => {
// Automatically load settings when userId is available and settings not loaded
if (userId && !settingsLoaded) {
actions.loadUserSettings();
}
}, [userId, settingsLoaded, actions]);

useEffect(() => {
if (logger && userSettingsArtifact) {
logger.log("User settings artifact updated:", userSettingsArtifact);
}
}, [logger, userSettingsArtifact]);

if (!isReady) {
return

Enable metrics and debugging via the observer and actionTracker objects. The enableMetrics option in createStore is crucial for activating these features.

`tsx
import { createStore } from '@asaidimu/react-store';
import React from 'react';

const useObservedStore = createStore(
{
state: { task: '', completed: false, count: 0 },
actions: {
addTask: (_, taskName: string) => ({ task: taskName, completed: false }),
completeTask: (_) => ({ completed: true }),
increment: ({state}) => ({ count: state.count + 1 }),
longRunningAction: async () => {
await new Promise(resolve => setTimeout(resolve, 500)); // Simulate async work
return { count: 100 };
},
},
},
{
enableMetrics: true, // Crucial for enabling the 'observer' and 'actionTracker' objects
enableConsoleLogging: true, // Log events directly to browser console
logEvents: { updates: true, middleware: true, transactions: true }, // Which event types to log
performanceThresholds: {
updateTime: 50, // Warn if updates take longer than 50ms
middlewareTime: 20 // Warn if middleware takes longer than 20ms
},
maxEvents: 500, // Max number of events to keep in history
maxStateHistory: 50, // Max number of state snapshots for time travel
debounceTime: 0, // Actions execute immediately by default
},
);

function DebugPanel() {
const { actions, observer, actionTracker, select, state: getStateSnapshot } = useObservedStore();
const count = select(s => s.count);

// Access performance metrics
const metrics = observer?.getPerformanceMetrics();

// Access state history for time travel (if maxStateHistory > 0)
const timeTravel = observer?.createTimeTravel();

// Access action execution history
const actionHistory = actionTracker?.getExecutions() || []; // actionTracker is only available if enableMetrics is true

return (


Send collected metrics and traces to external systems like OpenTelemetry, Prometheus, or Grafana Cloud for centralized monitoring. This functionality typically resides in the @asaidimu/utils-store ecosystem.

`tsx
import { createStore } from '@asaidimu/react-store';
// Assuming useRemoteObservability is provided by @asaidimu/utils-store or a wrapper
// import { useRemoteObservability } from '@asaidimu/utils-store';
import React, { useEffect } from 'react';

const useRemoteStore = createStore(
{
state: { apiCallsMade: 0, lastApiError: null },
actions: {
simulateApiCall: async ({state}) => {
if (Math.random() < 0.1) {
throw new Error('API request failed');
}
return { apiCallsMade: state.apiCallsMade + 1, lastApiError: null };
},
handleApiError: (_, error: string) => ({ lastApiError: error })
},
},
{
enableMetrics: true, // Required for RemoteObservability
enableConsoleLogging: false,
}
);

function MonitoringIntegration() {
const { store, observer } = useRemoteStore();

// Placeholder for actual useRemoteObservability hook
// const { remote, addOpenTelemetryDestination, addPrometheusDestination, addGrafanaCloudDestination } = useRemoteObservability(store, {
// serviceName: 'my-react-app',
// environment: 'development',
// instanceId: web-client-${Math.random().toString(36).substring(2, 9)},
// collectCategories: {
// performance: true,
// errors: true,
// stateChanges: true,
// middleware: true,
// },
// reportingInterval: 10000, // Send metrics every 10 seconds
// batchSize: 10, // Send after 10 metrics or interval, whichever comes first
// immediateReporting: false, // Don't send immediately after each metric
// });

useEffect(() => {
// In a real implementation, you would use the remote object
// to add destinations and configure reporting.
// Example:
// addOpenTelemetryDestination({ endpoint: 'http://localhost:4318', apiKey: 'your-otel-api-key' });
// addPrometheusDestination({ pushgatewayUrl: 'http://localhost:9091', jobName: 'react-store-metrics' });
// addGrafanaCloudDestination({ url: 'https://loki-prod-us-central1.grafana.net', apiKey: 'your-grafana-cloud-api-key' });

const interval = setInterval(() => {
observer?.reportCurrentMetrics(); // Manually trigger a report if needed
}, 5000); // Report every 5 seconds

return () => clearInterval(interval);
}, [observer]); // Removed placeholder dependencies for actual usage

return null; // This component doesn't render anything visually
}

// In your App component, you would use it like:
// function MyApp() {
// return (
// <>
//
// useRemoteStore().actions.simulateApiCall().catch(e => useRemoteStore().actions.handleApiError(e.message))}>
// Simulate API Call
//
//
// );
// }
`

$3

The store emits various events during its lifecycle, which you can subscribe to for logging, analytics, or custom side effects. This is done via store.onStoreEvent().

`typescript
import { createStore } from '@asaidimu/react-store';
import React, { useEffect } from 'react';

const useEventStore = createStore(
{
state: { data: 'initial', processedCount: 0 },
actions: {
processData: ({state}, newData: string) => ({ data: newData, processedCount: state.processedCount + 1 }),
triggerError: () => { throw new Error("Action failed intentionally"); }
},
transform: { // Using the new middleware API
myLoggingMiddleware: async ({state}, update) => {
console.log('Middleware processing:', update);
return update;
}
}
}
);

function EventMonitor() {
const { store, actions } = useEventStore();
const [eventLogs, setEventLogs] = React.useState([]);

useEffect(() => {
const addLog = (message: string) => {
setEventLogs(prev => [${new Date().toLocaleTimeString()}: ${message}, ...prev].slice(0, 10));
};

// Subscribe to specific store events
const unsubscribeUpdateStart = store.onStoreEvent('update:start', (data) => {
addLog(Update Started (timestamp: ${data.timestamp}));
});

const unsubscribeUpdateComplete = store.onStoreEvent('update:complete', (data) => {
if (data.blocked) {
addLog(Update BLOCKED by middleware or error. Error: ${data.error?.message || 'unknown'});
} else {
addLog(Update Completed in ${data.duration?.toFixed(2)}ms. Paths changed: ${data.changedPaths?.join(', ')});
}
});

const unsubscribeMiddlewareStart = store.onStoreEvent('middleware:start', (data) => {
addLog(Middleware '${data.name}' started (${data.type}));
});

const unsubscribeMiddlewareError = store.onStoreEvent('middleware:error', (data) => {
addLog(Middleware '${data.name}' encountered an error: ${data.error.message});
});

const unsubscribeTransactionStart = store.onStoreEvent('transaction:start', () => {
addLog(Transaction Started);
});

const unsubscribeTransactionError = store.onStoreEvent('transaction:error', (data) => {
addLog(Transaction Failed: ${data.error.message});
});

const unsubscribePersistenceReady = store.onStoreEvent('persistence:ready', () => {
addLog(Persistence is READY.);
});

// Cleanup subscriptions on component unmount
return () => {
unsubscribeUpdateStart();
unsubscribeUpdateComplete();
unsubscribeMiddlewareStart();
unsubscribeMiddlewareError();
unsubscribeTransactionStart();
unsubscribeTransactionError();
unsubscribePersistenceReady();
};
}, [store]); // Re-subscribe if store instance changes (unlikely)

return (


The watch function returned by the useStore hook allows you to subscribe to the loading status of individual actions. This is particularly useful for displaying loading indicators for asynchronous operations.

`tsx
import React from 'react';
import { createStore } from '@asaidimu/react-store';

interface DataState {
items: string[];
}

const useDataStore = createStore({
state: { items: [] },
actions: {
fetchItems: async ({state}) => {
// Simulate an API call
await new Promise(resolve => setTimeout(resolve, 2000));
return { items: ['Item A', 'Item B', 'Item C'] };
},
addItem: async ({state}, item: string) => {
// Simulate a quick add operation
await new Promise(resolve => setTimeout(resolve, 500));
return { items: [...state.items, item] };
},
},
});

function DataLoader() {
const { actions, select, watch } = useDataStore();
const items = select(s => s.items);

// Watch the loading state of specific actions
const isFetchingItems = watch('fetchItems');
const isAddingItem = watch('addItem');

return (


The hook returned by createStore provides several properties for advanced usage and debugging, beyond the commonly used select, actions, and isReady:

`tsx
import { useStore as useMyStore } from './store'; // Assuming this is your store definition

function MyAdvancedComponent() {
const {
select, // Function to select state parts (memoized, reactive)
actions, // Object containing your defined actions (debounced, promise-returning)
isReady, // Boolean indicating if persistence is ready
store, // Direct access to the ReactiveDataStore instance (from @asaidimu/utils-store)
observer, // StoreObserver instance (from @asaidimu/utils-store, if enableMetrics was true)
actionTracker, // Instance of ActionTracker for monitoring action executions (if enableMetrics was true)
state, // A getter function () => TState to get the entire current state object (reactive)
watch, // Function to watch the loading status of actions
resolve, // Function to reactively resolve an artifact (if artifacts are defined)
} = useMyStore(); // Assuming useMyStore is defined from createStore

// Example: Accessing the full state (use with caution for performance; select is preferred)
const fullCurrentState = state();
console.log("Full reactive state:", fullCurrentState);

// Example: Accessing observer methods (if enabled)
if (observer) {
console.log("Performance metrics:", observer.getPerformanceMetrics());
console.log("Recent state changes:", observer.getRecentChanges(3));
}

// Example: Accessing action history
if (actionTracker) { // actionTracker is only available if enableMetrics is true
console.log("Action executions:", actionTracker.getExecutions());
}

// Example: Watching a specific action's loading state
const isLoadingSomeAction = watch('checkout'); // Assuming 'checkout' is an action from the example store
console.log("Is 'checkout' action loading?", isLoadingSomeAction);

// Example: Resolving an artifact (from the example store)
const { instance: currencySymbol, ready: isCurrencySymbolReady } = resolve('currencySymbol');
if (isCurrencySymbolReady) {
console.log("Currency Symbol artifact is ready:", currencySymbol);
}

return (


@asaidimu/react-store is structured to provide a modular yet integrated state management solution. It separates core state logic into reusable utilities while offering a streamlined React-specific API.

$3

The core logic of this package integrates and extends external utility packages, with src/store.ts serving as the main entry point for the React hook.

* src/execution.ts: Defines ActionExecution and ActionTracker classes for monitoring and maintaining a history of action dispatches, including their status and performance metrics.
* src/store.ts: Contains the main createStore factory function. This module orchestrates the initialization of the core ReactiveDataStore, StoreObserver, ActionTracker, and ArtifactContainer. It also binds actions, applies middleware (transform, validate), and sets up the React hook using useSyncExternalStore for efficient component updates.
* src/types.ts: Defines all core TypeScript interfaces and types for the store's public API, including ActionContext, StoreDefinition, StoreHook, middleware signatures (Transformer, Validator), and artifact-related types.

$3

This library leverages the following @asaidimu packages for its core functionalities:

* @asaidimu/utils-store: Provides the foundational ReactiveDataStore for immutable state management, transactions, core event emission, and the StoreObserver instance for deep insights into state changes.
* @asaidimu/utils-persistence: Offers various persistence adapters like WebStoragePersistence and IndexedDBPersistence for saving and loading state, including cross-tab synchronization.
* @asaidimu/utils-artifacts: Provides the ArtifactContainer and related types for defining and resolving asynchronous, reactive dependencies (artifacts) within the store.

$3

* ReactiveDataStore (from @asaidimu/utils-store): The heart of the state management. It handles immutable state updates, middleware processing, transaction management, and emits detailed internal events about state changes.
* StoreObserver (from @asaidimu/utils-store): Built on top of ReactiveDataStore's event system, this component provides comprehensive debugging and monitoring features. This includes event history, state snapshots for time-travel, performance metrics, and utilities for logging or validation middleware.
* ActionTracker (src/execution.ts): A dedicated class for tracking the lifecycle and performance of individual action executions, capturing details like start/end times, duration, parameters, and outcomes (success/error).
* ArtifactContainer (from @asaidimu/utils-artifacts): Manages the registration and resolution of artifacts. It handles dependencies between artifacts and reacts to state changes for artifacts that depend on store state.
* createStore Hook (src/store.ts): The primary React-facing API. It instantiates ReactiveDataStore, StoreObserver, ActionTracker, and ArtifactContainer. It wraps user-defined actions with debouncing and tracking, and provides the select function (powered by useSyncExternalStore for efficient component updates), the watch function for action loading states, and the resolve function for artifacts.
* Persistence Adapters (from @asaidimu/utils-persistence): Implement the SimplePersistence interface. WebStoragePersistence (for localStorage/sessionStorage) and IndexedDBPersistence provide concrete, ready-to-use storage solutions with cross-tab synchronization capabilities.

$3

1. Action Dispatch: A React component calls a bound action (e.g., actions.addItem()).
2. Action Debouncing: Actions are debounced by default (configurable via debounceTime in StoreOptions), preventing rapid successive calls.
3. Action Loading State Update: The store immediately updates the loading state for the dispatched action to true via an internal ReactiveDataStore.
4. Action Execution Tracking: The ActionTracker records the action's details (name, parameters, start time) if enableMetrics is true.
5. State Update Request: The action's implementation (receiving ActionContext with state and resolve) returns a partial state update or a promise resolving to one.
6. Transaction Context: If the action is wrapped within store.transaction(), the current state is snapshotted to enable potential rollback.
7. Validator Middleware: The update first passes through any registered validate middleware. If any validator returns false or throws an error, the update is halted, and the state remains unchanged (and rolled back if in a transaction).
8. Transformer Middleware: If not blocked, the update then passes through transform middleware. These functions can modify the partial update payload.
9. State Merging: The final, possibly transformed, update is immutably merged into the current state using ReactiveDataStore's internal utility.
10. Change Detection: ReactiveDataStore performs a deep diff to identify precisely which paths in the state have changed.
11. Persistence: If changes occurred, the new state is saved via the configured SimplePersistence adapter (e.g., localStorage, IndexedDB). The system also subscribes to external changes from persistence for cross-tab synchronization.
12. Artifact Re-evaluation: If state changes affect an artifact that depends on that part of the state, ArtifactContainer may re-evaluate and re-resolve that artifact.
13. Listener Notification: React.useSyncExternalStore subscribers (used by select and resolve) whose selected paths or resolved artifacts have changed are notified, triggering efficient re-renders of only the relevant components.
14. Action Loading State Reset: Once the action completes (either successfully or with an error), the loading state for that action is reset to false.
15. Observability Events: Throughout this entire flow, ReactiveDataStore emits fine-grained events (update:start, middleware:complete, transaction:error, etc.) which StoreObserver captures for debugging, metrics collection, and remote reporting.

$3

* Custom Middleware: Easily add your own Transformer or Validator functions for custom logic (e.g., advanced logging, analytics, data transformation, or complex validation logic).
* Custom Persistence Adapters: Implement the SimplePersistence interface (from @asaidimu/utils-persistence) to integrate with any storage solution (e.g., a backend API, WebSockets, or a custom in-memory store).
* Custom Artifact Factories: Define factories for any external service, resource, or complex derived state, allowing for clear separation of concerns and reactive dependency injection.
* Remote Observability Destinations: Create new RemoteDestination implementations (part of @asaidimu/utils-store) to send metrics and traces to any external observability platform not already supported by default.

Development & Contributing

We welcome contributions! Please follow the guidelines below.

$3

1. Clone the repository:
`bash
git clone https://github.com/asaidimu/node-react.git
cd react-store
`
2. Install dependencies:
This project uses bun as the package manager.
`bash
bun install
`

$3

* bun ci: Installs dependencies, typically used in CI/CD environments to ensure a clean install.
* bun test:ci: Runs all unit tests once, suitable for CI/CD pipelines.
* bun test:watch: Runs all unit tests using Vitest in interactive watch mode.
* bun test: Runs all unit tests once using Vitest.
* bun clean: Removes the dist directory, cleaning up previous build artifacts.
* bun prebuild: Pre-build step that cleans the dist directory and runs an internal package synchronization script (.sync-package.ts).
* bun build: Compiles the TypeScript source into dist/ for CJS and ESM formats, generates type definitions, and minifies the code using Terser.
* bun dev: Starts the e-commerce dashboard demonstration application using Vite.
* bun postbuild: Post-build step that copies README.md, LICENSE.md, and the specialized dist.package.json into the dist folder, preparing the package for publishing.

$3

Tests are written using Vitest and React Testing Library for component and hook testing.

To run tests:

`bash
bun test


or to run in watch mode

1. Fork the repository and create your branch from main.
2. Code Standards: Ensure your code adheres to existing coding styles (TypeScript, ESLint, Prettier are configured).
3. Tests: Add unit and integration tests for new features or bug fixes. Ensure all tests pass (bun test).
4. Commits: Follow Conventional Commits for commit messages. This project uses semantic-release for automated versioning and changelog generation.
5. Pull Requests: Submit a pull request to the main branch. Provide a clear description of your changes, referencing any relevant issues.

$3

For bugs, feature requests, or questions, please open an issue on the GitHub Issues page.

Additional Information

$3

1. Granular Selectors: Always use select((state) => state.path.to.value) instead of select((state) => state) to prevent unnecessary re-renders of components. The more specific your selector, the more optimized your component updates will be.
2. Action Design: Keep actions focused on a single responsibility. Use async actions for asynchronous operations (e.g., API calls) and return partial updates or promises resolving to partial updates upon completion. Actions should describe what happened, not how.
3. Persistence:
* Use unique storeId or storageKey for each distinct store to avoid data conflicts.
* Always check the isReady flag for UI elements that depend on the initial state loaded from persistence, to prevent rendering incomplete data.
4. Middleware: Leverage transform and validate for cross-cutting concerns like logging, analytics, data transformation, or complex validation logic that applies to multiple actions. They now receive ActionContext, allowing for advanced logic including artifact resolution.
5. Symbol.for("delete"): Use this explicit symbol for property removal to maintain clarity and avoid accidental data mutations or unexpected behavior when merging partial updates.
6. Debounce Time: Adjust the debounceTime in createStore options for actions that might be called rapidly (e.g., search input, scroll events) to optimize performance. A debounceTime of 0 means actions execute immediately.
7. Artifacts: Use artifacts to manage external dependencies, services, or complex derived values that might change over time or have their own lifecycle. This promotes better separation of concerns and testability.

$3

#### createStore(definition, options)

The main entry point for creating a store hook.

`typescript
// From src/types.ts
export interface StoreDefinition<
TState extends object,
TArtifactsMap extends ArtifactsMap,
TActions extends ActionMap,
> {
state: TState;
actions: TActions;
artifacts?: TArtifactsMap; // Optional artifact definitions
transform?: Record>; // Optional transforming middleware
validate?: Record>; // Optional blocking middleware
}

interface StoreOptions extends ObserverOptions { // ObserverOptions from @asaidimu/utils-store
enableMetrics?: boolean; // Enable StoreObserver and ActionTracker features (default: false)
persistence?: SimplePersistence; // Optional persistence adapter instance (from @asaidimu/utils-persistence)
debounceTime?: number; // Time in milliseconds to debounce actions (default: 0ms)
// Other ObserverOptions for logging, performanceThresholds, maxEvents, maxStateHistory are inherited
}

const useStoreHook = createStore(definition, options);
`

Returns: A React hook (useStoreHook) which, when called in a component, returns an object with the following properties:

* store: Direct access to the underlying ReactiveDataStore instance (from @asaidimu/utils-store). This provides low-level control and event subscription.
* observer: The StoreObserver instance (from @asaidimu/utils-store). Available only if enableMetrics is true. Provides debug, time-travel, and monitoring utilities.
* select: A memoized selector function ((selector: (state: TState) => S) => S). Extracts specific state slices. Re-renders components only when selected data changes.
* actions: An object containing your defined actions, fully typed and bound to the store. These actions are debounced (if debounceTime > 0) and their loading states are tracked. Each action returns a Promise resolving to the new state after the action completes.
* actionTracker: An instance of ActionTracker (from src/execution.ts). Available only if enableMetrics is true. Provides methods for monitoring the execution history of your actions.
state: A getter function (() => TState) that returns the entire current state object. Use sparingly, as components relying on this will re-render on any* state change. select is generally preferred for performance.
* isReady: A boolean indicating whether the store's persistence layer (if configured) has finished loading its initial state.
* watch: A function ((action: K) => boolean) to watch the loading status of individual actions. Returns true if the action is currently executing.
* resolve: A reactive artifact resolver ((key: K) => ResolvedArtifact>). If artifacts are defined in the store, this hook returns ResolvedArtifact (containing instance and ready status) for a specific artifact, reactively updating if the artifact instance changes or becomes ready.

#### ReactiveDataStore (accessed via useStoreHook().store from @asaidimu/utils-store)

* get(clone?: boolean): TState: Retrieves the current state. Pass true to get a deep clone (recommended for mutations outside of actions).
* set(update: StateUpdater): Promise: Updates the state with a partial object or a function returning a partial object.
* watch(path: string | string[], callback: (state: TState) => void): () => void: Subscribes a listener to changes at a specific path or array of paths. Returns an unsubscribe function.
* transaction(operation: () => R | Promise): Promise: Executes a function as an atomic transaction. Rolls back all changes if an error occurs if the operation throws.
* use(middleware: StoreMiddleware): string: Adds a transforming middleware. Returns its ID. (Note: The createStore API uses transform and validate which internally map to ReactiveDataStore.use).
* removeMiddleware(id: string): boolean: Removes a middleware by its ID.
* isReady(): boolean: Checks if the persistence layer has loaded its initial state.
* onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void: Subscribes to internal store events (e.g., 'update:complete', 'middleware:error', 'transaction:start').

#### StoreObserver (accessed via useStoreHook().observer from @asaidimu/utils-store)

Available only if enableMetrics is true in createStore options.

* getEventHistory(): DebugEvent[]: Retrieves a history of all captured store events.
* getStateHistory(): TState[]: Returns a history of state snapshots, enabling time-travel debugging (if maxStateHistory > 0).
* getRecentChanges(limit?: number): Array<{ timestamp: number; changedPaths: string[]; from: DeepPartial; to: DeepPartial; }>: Provides a simplified view of recent state changes.
* getPerformanceMetrics(): StoreMetrics: Returns an object containing performance statistics (e.g., updateCount, averageUpdateTime).
* createTimeTravel(): { canUndo: () => boolean; canRedo: () => boolean; undo: () => Promise; redo: () => Promise; getHistoryLength: () => number; clear: () => void; }: Returns controls for time-travel debugging.
* clearHistory(): void: Clears the event and state history.
* disconnect(): void: Cleans up all listeners and resources.

#### Persistence Adapters (from @asaidimu/utils-persistence)

All adapters implement SimplePersistence:

* set(id:string, state: T): boolean | Promise: Persists data.
* get(id:string): T | null | Promise: Retrieves data.
* subscribe(id:string, callback: (state:T) => void): () => void: Subscribes to external changes (e.g., from other tabs).
* clear(id:string): boolean | Promise: Clears persisted data.

##### IndexedDBPersistence(storeId: string)

* storeId: A unique identifier for the IndexedDB object store (e.g., 'user-data').

##### WebStoragePersistence(storageKey: string, session?: boolean)

* storageKey: The key under which data is stored (e.g., 'app-config').
* session: Optional. If true, uses sessionStorage; otherwise, uses localStorage (default: false).

$3

@asaidimu/react-store aims to be a comprehensive, all-in-one solution for React state management, integrating features that often require multiple libraries in other ecosystems. Here's a comparison to popular alternatives:

| Feature | @asaidimu/react-store | Redux | Zustand | MobX | Recoil |
| :--------------------- | :------------------------ | :----------------- | :----------------- | :----------------- | :----------------- |
| Dev Experience | Intuitive hook-based API with rich tooling. | Verbose setup with reducers and middleware. | Minimalist, hook-friendly API. | Reactive, class-based approach. | Atom-based, React-native feel. |
| Learning Curve | Moderate (artifacts, middleware, observability add complexity). | Steep (boilerplate-heavy). | Low (simple API). | Moderate (reactive concepts). | Low to moderate (atom model). |
| API Complexity | Medium (rich feature set balanced with simplicity). | High (many concepts: actions, reducers, etc.). | Low (straightforward). | Medium (proxies, decorators). | Medium (atom/selectors). |
| Scalability | High (transactions, persistence, remote metrics, artifacts). | High (structured but verbose). | High (small but flexible). | High (reactive scaling). | High (granular atoms). |
| Extensibility | Excellent (middleware, custom persistence, observability, artifacts). | Good (middleware, enhancers). | Good (middleware-like). | Moderate (custom reactions). | Moderate (custom selectors). |
| Performance | Optimized (selectors, reactive updates via useSyncExternalStore). | Good (predictable but manual optimization). | Excellent (minimal overhead). | Good (reactive overhead). | Good (granular updates). |
| Bundle Size | Moderate (includes observability, persistence, remote observability framework). | Large (core + toolkit). | Tiny (~1KB). | Moderate (~20KB). | Moderate (~10KB). |
| Persistence | Built-in (IndexedDB, WebStorage, cross-tab). | Manual (via middleware). | Manual (via middleware). | Manual (custom). | Manual (custom). |
| Observability | Excellent (metrics, time-travel, event logging, remote). | Good (dev tools). | Basic (via plugins). | Good (reactive logs). | Basic (via plugins). |
| React Integration | Native (hooks, useSyncExternalStore`). | Manual (React-Redux).