@standardbeagle/data-router 1.1.0

package/README.md

@@ -0,0 +1,134 @@
+# @standardbeagle/data-router
+
+A memory-only, XPath-based router for React that operates with data structures instead of URLs. Perfect for complex React components that need internal routing and data manipulation without interfering with the parent application's routing system.
+
+## Features
+
+- **XPath Navigation**: Navigate through data structures using XPath expressions
+- **Data Manipulation**: Built-in CRUD operations (merge, replace, append, delete)
+- **Form Integration**: Form components that automatically update data at specified XPaths
+- **Memory-only**: No browser URL integration - purely internal routing
+- **TypeScript Support**: Full TypeScript support with strict typing
+- **React Hooks**: Hook-based API for easy integration
+
+## Installation
+
+```bash
+npm install @standardbeagle/data-router
+```
+
+## Basic Usage
+
+```tsx
+import { DataProvider, useXPath, useData, Link, Form, Button } from '@standardbeagle/data-router';
+
+// Initialize with some data
+const initialData = {
+  users: [
+    { id: 1, name: 'John', profile: { email: 'john@example.com' } }
+  ],
+  settings: { theme: 'light' }
+};
+
+function App() {
+  return (
+    <DataProvider initialData={initialData} initialXPath="/users[0]">
+      <UserProfile />
+    </DataProvider>
+  );
+}
+
+function UserProfile() {
+  const xpath = useXPath(); // "/users[0]"
+  const targetData = useTargetData(); // { id: 1, name: 'John', profile: {...} }
+  
+  return (
+    <div>
+      <h1>Current Location: {xpath}</h1>
+      <p>User: {targetData.name}</p>
+      
+      {/* Navigate to user's profile */}
+      <Link to="profile">View Profile</Link>
+      
+      {/* Navigate to settings */}
+      <Link to="/settings">Go to Settings</Link>
+      
+      {/* Form to update user data */}
+      <Form targetXPath="/users[0]" operation="merge">
+        <input name="name" defaultValue={targetData.name} />
+        <Button dataAction="merge">Update User</Button>
+      </Form>
+    </div>
+  );
+}
+```
+
+## Core Concepts
+
+### XPath Navigation
+- **Absolute paths**: `/users[0]/profile/email`
+- **Relative paths**: `profile/settings` (relative to current XPath)
+- **Parent navigation**: `..` (go up one level), `../..` (go up two levels)
+
+### Data Operations
+- **merge**: Combine form data with existing object
+- **replace**: Replace entire object/value at XPath
+- **append**: Add to arrays or create new properties
+- **delete**: Remove properties/array elements
+
+### Components
+
+#### DataProvider
+Provides the data context and routing state.
+
+```tsx
+<DataProvider 
+  initialData={myData} 
+  initialXPath="/users[0]"
+>
+  {children}
+</DataProvider>
+```
+
+#### Link
+Navigate to different XPaths (read-only navigation).
+
+```tsx
+<Link to="/users[1]">Go to User 1</Link>
+<Link to="../settings">Go to Settings</Link>
+```
+
+#### Form
+Wrap form elements for data manipulation.
+
+```tsx
+<Form targetXPath="/users[0]" operation="merge">
+  <input name="email" />
+  <Button dataAction="merge">Save</Button>
+</Form>
+```
+
+#### Button
+Submit button with data manipulation capabilities.
+
+```tsx
+<Button 
+  dataAction="replace" 
+  targetXPath="/settings/theme"
+  navigateTo="/settings"
+>
+  Update Theme
+</Button>
+```
+
+### Hooks
+
+- `useXPath()` - Get current XPath
+- `useData()` - Get entire data object
+- `useTargetData()` - Get data at current XPath
+- `useNavigate()` - Get navigation function
+- `useDataManipulation()` - Get data manipulation functions
+
+## License
+
+ISC

package/dist/FormHandler.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode, ButtonHTMLAttributes } from 'react';
+import { FormData, DataOperationType } from './types';
+interface FormHandlerProps {
+    xpath?: string;
+    operation?: DataOperationType;
+    onSubmit?: (data: FormData, navigate: (xpath: string) => void) => void;
+    children: ReactNode;
+    className?: string;
+    id?: string;
+}
+export declare function Form({ xpath, operation, onSubmit, children, ...props }: FormHandlerProps): import("react/jsx-runtime").JSX.Element;
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    dataAction?: DataOperationType;
+    targetXPath?: string;
+    navigateTo?: string;
+    children: ReactNode;
+}
+export declare function Button({ dataAction, targetXPath, navigateTo, children, onClick, type, ...props }: ButtonProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/hooks/useAsyncBatch.d.ts

@@ -0,0 +1,46 @@
+export interface BatchOperation<T = any> {
+    xpath: string;
+    fetcher: () => Promise<T>;
+    priority?: 'low' | 'normal' | 'high';
+    onSuccess?: (data: T) => void;
+    onError?: (error: Error) => void;
+}
+export interface BatchConfig {
+    concurrency?: number;
+    failFast?: boolean;
+    retryCount?: number;
+    retryDelay?: number;
+    onBatchComplete?: (results: BatchResult[]) => void;
+    onBatchError?: (error: Error, results: BatchResult[]) => void;
+}
+export interface BatchResult<T = any> {
+    xpath: string;
+    status: 'success' | 'error' | 'pending';
+    data?: T;
+    error?: Error;
+}
+export interface AsyncBatchResult {
+    execute: () => Promise<BatchResult[]>;
+    cancel: () => void;
+    isLoading: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    isIdle: boolean;
+    results: BatchResult[];
+    progress: {
+        total: number;
+        completed: number;
+        failed: number;
+        pending: number;
+        percentage: number;
+    };
+}
+export declare function useAsyncBatch(operations: BatchOperation[], config?: BatchConfig): AsyncBatchResult;
+export declare function useAsyncParallel<T = any>(operations: Array<{
+    xpath: string;
+    fetcher: () => Promise<T>;
+}>, config?: Omit<BatchConfig, 'concurrency'>): AsyncBatchResult;
+export declare function useAsyncSequential<T = any>(operations: Array<{
+    xpath: string;
+    fetcher: () => Promise<T>;
+}>, config?: Omit<BatchConfig, 'concurrency'>): AsyncBatchResult;

package/dist/hooks/useAsyncData.d.ts

@@ -0,0 +1,23 @@
+export interface AsyncDataConfig {
+    enabled?: boolean;
+    staleTime?: number;
+    cacheTime?: number;
+    refetchOnWindowFocus?: boolean;
+    refetchOnReconnect?: boolean;
+    retryCount?: number;
+    retryDelay?: number;
+    onSuccess?: (data: any) => void;
+    onError?: (error: Error) => void;
+}
+export interface AsyncDataResult<T = any> {
+    data: T | undefined;
+    isLoading: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    isIdle: boolean;
+    error: Error | undefined;
+    refetch: () => Promise<T>;
+    cancel: () => void;
+    invalidate: () => void;
+}
+export declare function useAsyncData<T = any>(xpath: string, fetcher: () => Promise<T>, config?: AsyncDataConfig): AsyncDataResult<T>;

package/dist/hooks/useAsyncMutation.d.ts

@@ -0,0 +1,22 @@
+export interface AsyncMutationConfig<TData = any, TVariables = any> {
+    optimisticUpdate?: (currentData: TData, variables: TVariables) => TData;
+    rollbackOnError?: boolean;
+    invalidate?: string[];
+    retryCount?: number;
+    retryDelay?: number;
+    onSuccess?: (data: TData, variables: TVariables) => void;
+    onError?: (error: Error, variables: TVariables) => void;
+    onSettled?: (data: TData | undefined, error: Error | undefined, variables: TVariables) => void;
+}
+export interface AsyncMutationResult<TData = any, TVariables = any> {
+    mutate: (variables: TVariables) => Promise<TData>;
+    mutateAsync: (variables: TVariables) => Promise<TData>;
+    reset: () => void;
+    isLoading: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    isIdle: boolean;
+    data: TData | undefined;
+    error: Error | undefined;
+}
+export declare function useAsyncMutation<TData = any, TVariables = any>(xpath: string, mutationFn: (variables: TVariables) => Promise<TData>, config?: AsyncMutationConfig<TData, TVariables>): AsyncMutationResult<TData, TVariables>;

package/dist/hooks/useAsyncState.d.ts

@@ -0,0 +1,44 @@
+import { AsyncState } from '../types';
+export interface AsyncStateInfo extends AsyncState {
+    xpath: string;
+    hasPendingOperation: boolean;
+    isStale: (staleTime?: number) => boolean;
+}
+export interface AsyncStateResult<T = any> {
+    data: T | undefined;
+    asyncState: AsyncStateInfo | undefined;
+    isLoading: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    isIdle: boolean;
+    error: Error | undefined;
+    isPending: boolean;
+    lastUpdated: number | undefined;
+}
+export declare function useAsyncState<T = any>(xpath: string): AsyncStateResult<T>;
+export declare function useAsyncStates(xpaths: string[]): Record<string, AsyncStateResult>;
+export declare function useGlobalAsyncState(): {
+    summary: {
+        totalStates: number;
+        loadingStates: number;
+        errorStates: number;
+        successStates: number;
+        idleStates: number;
+        pendingOperations: number;
+        executingOperations: number;
+        queuedOperations: number;
+        hasAnyLoading: boolean;
+        hasAnyError: boolean;
+        optimisticUpdateCount: number;
+    };
+    statesByStatus: {
+        loading: [string, AsyncState][];
+        error: [string, AsyncState][];
+        success: [string, AsyncState][];
+        idle: [string, AsyncState][];
+    };
+    asyncStates: Record<string, AsyncState>;
+    pendingOperations: ReadonlySet<string>;
+    commandQueue: import("../types").CommandQueue;
+    optimisticUpdates: Record<string, import("../types").OptimisticUpdate>;
+};

package/dist/hooks/useData.d.ts

@@ -0,0 +1,3 @@
+export declare function useData(): Record<string, any>;
+export declare function useTargetData(): any;
+export declare function useDataAtXPath(xpath: string): any;

package/dist/hooks/useDataManipulation.d.ts

@@ -0,0 +1,2 @@
+import { DataManipulationHook } from '../types';
+export declare function useDataManipulation(): DataManipulationHook;

package/dist/hooks/useInvalidation.d.ts

@@ -0,0 +1,28 @@
+export interface InvalidationConfig {
+    includeChildren?: boolean;
+    includeParents?: boolean;
+    clearData?: boolean;
+    force?: boolean;
+}
+export interface InvalidationResult {
+    invalidate: (xpath: string, config?: InvalidationConfig) => void;
+    invalidateMany: (xpaths: string[], config?: InvalidationConfig) => void;
+    invalidatePattern: (pattern: string, config?: InvalidationConfig) => void;
+    invalidateAll: () => void;
+    revalidate: (xpath: string) => void;
+    revalidateMany: (xpaths: string[]) => void;
+    getInvalidationCount: () => number;
+}
+export declare function useInvalidation(): InvalidationResult;
+export declare function useAutoInvalidation(dependencies: string[], config?: InvalidationConfig & {
+    debounceMs?: number;
+    onInvalidate?: (paths: string[]) => void;
+}): {
+    trigger: () => void;
+    invalidateDependencies: () => void;
+};
+export declare function useQueryInvalidation(): {
+    invalidateQueries: (queryKey: string | string[]) => void;
+    invalidateQueriesMatching: (predicate: (path: string) => boolean) => void;
+    getQueries: (queryKey?: string | string[]) => string[];
+};

package/dist/hooks/useNavigate.d.ts

@@ -0,0 +1,4 @@
+import { NavigationObject } from '../types';
+export declare function useNavigate(): (xpath: string) => void;
+export declare function useNavigation(): NavigationObject;
+export declare function useHistory(): readonly string[];

package/dist/hooks/useOptimisticUpdates.d.ts

@@ -0,0 +1,27 @@
+export interface OptimisticUpdateConfig<T = any> {
+    rollbackOnError?: boolean;
+    onRollback?: (originalData: T) => void;
+    onCommit?: (newData: T) => void;
+}
+export interface OptimisticUpdateResult<T = any> {
+    apply: (newData: T) => string;
+    rollback: (updateId: string) => void;
+    commit: (updateId: string) => void;
+    rollbackAll: () => void;
+    getOriginalData: (updateId: string) => T | undefined;
+    hasOptimisticUpdates: boolean;
+    optimisticUpdateIds: string[];
+}
+export declare function useOptimisticUpdates<T = any>(xpath: string, config?: OptimisticUpdateConfig<T>): OptimisticUpdateResult<T>;
+export declare function useOptimisticList<T = any>(xpath: string, config?: OptimisticUpdateConfig<T[]>): OptimisticUpdateResult<T[]> & {
+    addItem: (item: T, position?: number) => string;
+    updateItem: (index: number, item: T) => string;
+    removeItem: (index: number) => string;
+    moveItem: (fromIndex: number, toIndex: number) => string;
+};
+export declare function useOptimisticObject<T extends Record<string, any>>(xpath: string, config?: OptimisticUpdateConfig<T>): OptimisticUpdateResult<T> & {
+    updateProperty: <K extends keyof T>(key: K, value: T[K]) => string;
+    updateProperties: (updates: Partial<T>) => string;
+    removeProperty: <K extends keyof T>(key: K) => string;
+    mergeObject: (updates: Partial<T>) => string;
+};

package/dist/hooks/useXPath.d.ts

@@ -0,0 +1 @@
+export declare function useXPath(): string;

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { ComponentProps } from 'react';
+import { ReactNode } from 'react';
+export { DataProvider } from './provider';
+export { useXPath } from './hooks/useXPath';
+export { useData, useTargetData, useDataAtXPath } from './hooks/useData';
+export { useNavigate, useNavigation, useHistory } from './hooks/useNavigate';
+export { useDataManipulation } from './hooks/useDataManipulation';
+export { useAsyncData } from './hooks/useAsyncData';
+export { useAsyncMutation } from './hooks/useAsyncMutation';
+export { useAsyncState, useAsyncStates, useGlobalAsyncState } from './hooks/useAsyncState';
+export { useAsyncBatch, useAsyncParallel, useAsyncSequential } from './hooks/useAsyncBatch';
+export { useOptimisticUpdates, useOptimisticList, useOptimisticObject } from './hooks/useOptimisticUpdates';
+export { useInvalidation, useAutoInvalidation, useQueryInvalidation } from './hooks/useInvalidation';
+export { asyncStart, asyncSuccess, asyncError, asyncCancel, commandQueueUpdate, generateRequestId } from './state/actions';
+export { CommandQueueManager } from './state/command-queue';
+export type { AsyncState, AsyncCommand, CommandQueue, OptimisticUpdate } from './types';
+export type { AsyncDataConfig, AsyncDataResult } from './hooks/useAsyncData';
+export type { AsyncMutationConfig, AsyncMutationResult } from './hooks/useAsyncMutation';
+export type { AsyncStateInfo, AsyncStateResult } from './hooks/useAsyncState';
+export type { BatchOperation, BatchConfig, BatchResult, AsyncBatchResult } from './hooks/useAsyncBatch';
+export type { OptimisticUpdateConfig, OptimisticUpdateResult } from './hooks/useOptimisticUpdates';
+export type { InvalidationConfig, InvalidationResult } from './hooks/useInvalidation';
+export { Form, Button } from './FormHandler';
+interface LinkProps extends Omit<ComponentProps<'a'>, 'href' | 'onClick'> {
+    to: string;
+    children: ReactNode;
+}
+export declare const Link: React.ForwardRefExoticComponent<Omit<LinkProps, "ref"> & React.RefAttributes<HTMLAnchorElement>>;

package/dist/index.es.d.ts

@@ -0,0 +1 @@
+export * from './index'