@topgunbuild/react 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import React, { ReactNode } from 'react';
 import * as _topgunbuild_client from '@topgunbuild/client';
-import { TopGunClient, QueryResultItem, QueryFilter, TopicCallback } from '@topgunbuild/client';
-import { LWWMap, ORMap } from '@topgunbuild/core';
+import { TopGunClient, ChangeEvent, QueryResultItem, QueryFilter, TopicCallback, RegisterResult, ResolverInfo } from '@topgunbuild/client';
+import { LWWMap, ORMap, EntryProcessorResult, EntryProcessorDef, JournalEventType, JournalEvent, MergeRejection, ConflictResolverDef } from '@topgunbuild/core';
 
 interface TopGunProviderProps {
     client: TopGunClient;
@@ -10,12 +10,97 @@ interface TopGunProviderProps {
 declare const TopGunProvider: React.FC<TopGunProviderProps>;
 declare function useClient(): TopGunClient;
 
+/**
+ * Options for useQuery change callbacks (Phase 5.1)
+ */
+interface UseQueryOptions<T> {
+    /** Called for any change event */
+    onChange?: (change: ChangeEvent<T>) => void;
+    /** Called when an item is added */
+    onAdd?: (key: string, value: T) => void;
+    /** Called when an item is updated */
+    onUpdate?: (key: string, value: T, previous: T) => void;
+    /** Called when an item is removed */
+    onRemove?: (key: string, previous: T) => void;
+    /**
+     * Maximum number of changes to accumulate before auto-rotating.
+     * When exceeded, oldest changes are removed to prevent memory leaks.
+     * Default: 1000
+     */
+    maxChanges?: number;
+}
+/**
+ * Result type for useQuery hook with change tracking (Phase 5.1)
+ */
 interface UseQueryResult<T> {
+    /** Current data array */
     data: QueryResultItem<T>[];
+    /** Loading state */
     loading: boolean;
+    /** Error if query failed */
     error: Error | null;
+    /** Last change event (Phase 5.1) */
+    lastChange: ChangeEvent<T> | null;
+    /** All changes since last clearChanges() call (Phase 5.1) */
+    changes: ChangeEvent<T>[];
+    /** Clear accumulated changes (Phase 5.1) */
+    clearChanges: () => void;
 }
-declare function useQuery<T = any>(mapName: string, query?: QueryFilter): UseQueryResult<T>;
+/**
+ * React hook for querying data with real-time updates and change tracking.
+ *
+ * @example Basic usage with change tracking
+ * ```tsx
+ * function TodoList() {
+ *   const { data, lastChange } = useQuery<Todo>('todos');
+ *
+ *   useEffect(() => {
+ *     if (lastChange?.type === 'add') {
+ *       toast.success(`New todo: ${lastChange.value.title}`);
+ *     }
+ *   }, [lastChange]);
+ *
+ *   return <ul>{data.map(todo => <TodoItem key={todo._key} {...todo} />)}</ul>;
+ * }
+ * ```
+ *
+ * @example With callback-based notifications
+ * ```tsx
+ * function NotifyingTodoList() {
+ *   const { data } = useQuery<Todo>('todos', undefined, {
+ *     onAdd: (key, todo) => showNotification(`New: ${todo.title}`),
+ *     onRemove: (key, todo) => showNotification(`Removed: ${todo.title}`)
+ *   });
+ *
+ *   return <ul>{data.map(todo => <TodoItem key={todo._key} {...todo} />)}</ul>;
+ * }
+ * ```
+ *
+ * @example With framer-motion animations
+ * ```tsx
+ * import { AnimatePresence, motion } from 'framer-motion';
+ *
+ * function AnimatedTodoList() {
+ *   const { data } = useQuery<Todo>('todos');
+ *
+ *   return (
+ *     <AnimatePresence>
+ *       {data.map(todo => (
+ *         <motion.li
+ *           key={todo._key}
+ *           initial={{ opacity: 0, x: -20 }}
+ *           animate={{ opacity: 1, x: 0 }}
+ *           exit={{ opacity: 0, x: 20 }}
+ *         >
+ *           {todo.title}
+ *         </motion.li>
+ *       ))}
+ *     </AnimatePresence>
+ *   );
+ * }
+ * ```
+ */
+declare function useQuery<T = any>(mapName: string, query?: QueryFilter, options?: UseQueryOptions<T>): UseQueryResult<T>;
 
 interface UseMutationResult<T, K = string> {
     create: (key: K, value: T) => void;
@@ -31,4 +116,495 @@ declare function useORMap<K = string, V = any>(mapName: string): ORMap<K, V>;
 
 declare function useTopic(topicName: string, callback?: TopicCallback): _topgunbuild_client.TopicHandle;
 
-export { TopGunProvider, type TopGunProviderProps, type UseMutationResult, type UseQueryResult, useClient, useMap, useMutation, useORMap, useQuery, useTopic };
+/**
+ * Result type for usePNCounter hook.
+ */
+interface UsePNCounterResult {
+    /** Current counter value */
+    value: number;
+    /** Increment the counter by 1 */
+    increment: () => void;
+    /** Decrement the counter by 1 */
+    decrement: () => void;
+    /** Add delta (positive or negative) to the counter */
+    add: (delta: number) => void;
+    /** Loading state (true until first value received) */
+    loading: boolean;
+}
+/**
+ * React hook for using a PN Counter with real-time updates.
+ *
+ * PN Counters support increment and decrement operations that work offline
+ * and sync to server when connected. They guarantee convergence across
+ * distributed nodes without coordination.
+ *
+ * @param name The counter name (e.g., 'likes:post-123')
+ * @returns Counter value and methods
+ *
+ * @example Basic usage
+ * ```tsx
+ * function LikeButton({ postId }: { postId: string }) {
+ *   const { value, increment } = usePNCounter(`likes:${postId}`);
+ *
+ *   return (
+ *     <button onClick={increment}>
+ *       ❤️ {value}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Inventory control
+ * ```tsx
+ * function InventoryControl({ productId }: { productId: string }) {
+ *   const { value, increment, decrement } = usePNCounter(`inventory:${productId}`);
+ *
+ *   return (
+ *     <div>
+ *       <span>Stock: {value}</span>
+ *       <button onClick={decrement} disabled={value <= 0}>-</button>
+ *       <button onClick={increment}>+</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Bulk operations
+ * ```tsx
+ * function BulkAdd({ counterId }: { counterId: string }) {
+ *   const { value, add } = usePNCounter(counterId);
+ *   const [amount, setAmount] = useState(10);
+ *
+ *   return (
+ *     <div>
+ *       <span>Value: {value}</span>
+ *       <input
+ *         type="number"
+ *         value={amount}
+ *         onChange={(e) => setAmount(parseInt(e.target.value))}
+ *       />
+ *       <button onClick={() => add(amount)}>Add {amount}</button>
+ *       <button onClick={() => add(-amount)}>Subtract {amount}</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function usePNCounter(name: string): UsePNCounterResult;
+
+/**
+ * Options for the useEntryProcessor hook.
+ */
+interface UseEntryProcessorOptions {
+    /**
+     * Number of retry attempts on failure.
+     * Default: 0 (no retries)
+     */
+    retries?: number;
+    /**
+     * Delay between retries in milliseconds.
+     * Default: 100ms, doubles with each retry (exponential backoff)
+     */
+    retryDelayMs?: number;
+}
+/**
+ * Result type for useEntryProcessor hook.
+ */
+interface UseEntryProcessorResult<R> {
+    /**
+     * Execute the processor on a key.
+     * @param key The key to process
+     * @param args Optional arguments to pass to the processor
+     */
+    execute: (key: string, args?: unknown) => Promise<EntryProcessorResult<R>>;
+    /**
+     * Execute the processor on multiple keys.
+     * @param keys The keys to process
+     * @param args Optional arguments to pass to the processor
+     */
+    executeMany: (keys: string[], args?: unknown) => Promise<Map<string, EntryProcessorResult<R>>>;
+    /** True while a processor is executing */
+    executing: boolean;
+    /** Last execution result (single key) */
+    lastResult: EntryProcessorResult<R> | null;
+    /** Last error encountered */
+    error: Error | null;
+    /** Reset the hook state (clears lastResult and error) */
+    reset: () => void;
+}
+/**
+ * React hook for executing entry processors with loading and error states.
+ *
+ * Entry processors execute user-defined logic atomically on the server,
+ * solving the read-modify-write race condition.
+ *
+ * @param mapName Name of the map to operate on
+ * @param processorDef Processor definition (without args - args are passed per-execution)
+ * @param options Optional configuration
+ * @returns Execute function and state
+ *
+ * @example Basic increment
+ * ```tsx
+ * function LikeButton({ postId }: { postId: string }) {
+ *   const { execute, executing } = useEntryProcessor<number>('likes', {
+ *     name: 'increment',
+ *     code: `
+ *       const current = value ?? 0;
+ *       return { value: current + 1, result: current + 1 };
+ *     `,
+ *   });
+ *
+ *   const handleLike = async () => {
+ *     const result = await execute(postId);
+ *     if (result.success) {
+ *       console.log('New like count:', result.result);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleLike} disabled={executing}>
+ *       {executing ? '...' : 'Like'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Inventory reservation with args
+ * ```tsx
+ * function ReserveButton({ productId }: { productId: string }) {
+ *   const { execute, executing, error } = useEntryProcessor<
+ *     { stock: number; reserved: string[] },
+ *     { success: boolean; remaining: number }
+ *   >('inventory', {
+ *     name: 'reserve_item',
+ *     code: `
+ *       if (!value || value.stock <= 0) {
+ *         return { value, result: { success: false, remaining: 0 } };
+ *       }
+ *       const newValue = {
+ *         ...value,
+ *         stock: value.stock - 1,
+ *         reserved: [...value.reserved, args.userId],
+ *       };
+ *       return {
+ *         value: newValue,
+ *         result: { success: true, remaining: newValue.stock }
+ *       };
+ *     `,
+ *   });
+ *
+ *   const handleReserve = async () => {
+ *     const result = await execute(productId, { userId: currentUser.id });
+ *     if (result.success && result.result?.success) {
+ *       toast.success(`Reserved! ${result.result.remaining} left`);
+ *     } else {
+ *       toast.error('Out of stock');
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleReserve} disabled={executing}>
+ *       {executing ? 'Reserving...' : 'Reserve'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Using built-in processor
+ * ```tsx
+ * import { BuiltInProcessors } from '@topgunbuild/core';
+ *
+ * function DecrementStock({ productId }: { productId: string }) {
+ *   const processorDef = useMemo(
+ *     () => BuiltInProcessors.DECREMENT_FLOOR(1),
+ *     []
+ *   );
+ *
+ *   const { execute, executing, lastResult } = useEntryProcessor<
+ *     number,
+ *     { newValue: number; wasFloored: boolean }
+ *   >('stock', processorDef);
+ *
+ *   const handleDecrement = async () => {
+ *     const result = await execute(productId);
+ *     if (result.result?.wasFloored) {
+ *       alert('Stock is now at zero!');
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleDecrement} disabled={executing}>
+ *       Decrease Stock
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useEntryProcessor<V = unknown, R = V>(mapName: string, processorDef: Omit<EntryProcessorDef<V, R>, 'args'>, options?: UseEntryProcessorOptions): UseEntryProcessorResult<R>;
+
+/**
+ * Options for useEventJournal hook.
+ */
+interface UseEventJournalOptions {
+    /** Start from specific sequence */
+    fromSequence?: bigint;
+    /** Filter by map name */
+    mapName?: string;
+    /** Filter by event types */
+    types?: JournalEventType[];
+    /** Maximum events to keep in state (default: 100) */
+    maxEvents?: number;
+    /** Called when new event is received */
+    onEvent?: (event: JournalEvent) => void;
+    /** Pause subscription */
+    paused?: boolean;
+}
+/**
+ * Result type for useEventJournal hook.
+ */
+interface UseEventJournalResult {
+    /** Array of recent events (newest last) */
+    events: JournalEvent[];
+    /** Last received event */
+    lastEvent: JournalEvent | null;
+    /** Clear accumulated events */
+    clearEvents: () => void;
+    /** Read historical events from sequence */
+    readFrom: (sequence: bigint, limit?: number) => Promise<JournalEvent[]>;
+    /** Get latest sequence number */
+    getLatestSequence: () => Promise<bigint>;
+    /** Whether subscription is active */
+    isSubscribed: boolean;
+}
+/**
+ * React hook for subscribing to Event Journal changes.
+ *
+ * The Event Journal captures all map changes (PUT, UPDATE, DELETE) as an
+ * append-only log, useful for:
+ * - Real-time activity feeds
+ * - Audit trails
+ * - Change notifications
+ * - Debugging and monitoring
+ *
+ * @example Basic usage - show all changes
+ * ```tsx
+ * function ActivityFeed() {
+ *   const { events, lastEvent } = useEventJournal();
+ *
+ *   return (
+ *     <ul>
+ *       {events.map((e) => (
+ *         <li key={e.sequence.toString()}>
+ *           {e.type} {e.mapName}:{e.key}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example Filter by map name
+ * ```tsx
+ * function UserActivityFeed() {
+ *   const { events } = useEventJournal({ mapName: 'users' });
+ *
+ *   return (
+ *     <ul>
+ *       {events.map((e) => (
+ *         <li key={e.sequence.toString()}>
+ *           User {e.key}: {e.type}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example With event callback
+ * ```tsx
+ * function NotifyingComponent() {
+ *   const { events } = useEventJournal({
+ *     mapName: 'orders',
+ *     types: ['PUT'],
+ *     onEvent: (event) => {
+ *       toast.success(`New order: ${event.key}`);
+ *     },
+ *   });
+ *
+ *   return <OrderList events={events} />;
+ * }
+ * ```
+ */
+declare function useEventJournal(options?: UseEventJournalOptions): UseEventJournalResult;
+
+/**
+ * Options for useMergeRejections hook.
+ */
+interface UseMergeRejectionsOptions {
+    /** Filter rejections by map name (optional) */
+    mapName?: string;
+    /** Maximum number of rejections to keep in history */
+    maxHistory?: number;
+}
+/**
+ * Result type for useMergeRejections hook.
+ */
+interface UseMergeRejectionsResult {
+    /** List of recent merge rejections */
+    rejections: MergeRejection[];
+    /** Last rejection received */
+    lastRejection: MergeRejection | null;
+    /** Clear rejection history */
+    clear: () => void;
+}
+/**
+ * React hook for subscribing to merge rejection events.
+ *
+ * Merge rejections occur when a custom conflict resolver rejects
+ * a client's write operation. This hook allows you to:
+ * - Display rejection notifications to users
+ * - Refresh local state after rejection
+ * - Log conflicts for debugging
+ *
+ * @param options Optional filtering and configuration
+ * @returns Rejection list and utilities
+ *
+ * @example Show rejection notifications
+ * ```tsx
+ * function BookingForm() {
+ *   const { lastRejection, clear } = useMergeRejections({
+ *     mapName: 'bookings'
+ *   });
+ *
+ *   useEffect(() => {
+ *     if (lastRejection) {
+ *       toast.error(`Booking failed: ${lastRejection.reason}`);
+ *       clear(); // Clear after showing notification
+ *     }
+ *   }, [lastRejection]);
+ *
+ *   return <form>...</form>;
+ * }
+ * ```
+ *
+ * @example Track all rejections
+ * ```tsx
+ * function ConflictLog() {
+ *   const { rejections } = useMergeRejections({ maxHistory: 50 });
+ *
+ *   return (
+ *     <ul>
+ *       {rejections.map((r, i) => (
+ *         <li key={i}>
+ *           {r.mapName}/{r.key}: {r.reason}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+declare function useMergeRejections(options?: UseMergeRejectionsOptions): UseMergeRejectionsResult;
+
+/**
+ * Options for useConflictResolver hook.
+ */
+interface UseConflictResolverOptions {
+    /** Auto-unregister resolver on unmount (default: true) */
+    autoUnregister?: boolean;
+}
+/**
+ * Result type for useConflictResolver hook.
+ */
+interface UseConflictResolverResult {
+    /**
+     * Register a conflict resolver on the server.
+     * @param resolver The resolver definition
+     */
+    register: (resolver: Omit<ConflictResolverDef, 'fn'>) => Promise<RegisterResult>;
+    /**
+     * Unregister a resolver by name.
+     * @param resolverName Name of the resolver to unregister
+     */
+    unregister: (resolverName: string) => Promise<RegisterResult>;
+    /**
+     * List all registered resolvers for this map.
+     */
+    list: () => Promise<ResolverInfo[]>;
+    /** True while a registration/unregistration is in progress */
+    loading: boolean;
+    /** Last error encountered */
+    error: Error | null;
+    /** List of resolvers registered by this hook instance */
+    registered: string[];
+}
+/**
+ * React hook for managing conflict resolvers on a specific map.
+ *
+ * Conflict resolvers allow you to customize how merge conflicts are handled
+ * on the server. This hook provides a convenient way to:
+ * - Register custom resolvers
+ * - Auto-unregister on component unmount
+ * - Track registration state
+ *
+ * @param mapName Name of the map to manage resolvers for
+ * @param options Optional configuration
+ * @returns Resolver management functions and state
+ *
+ * @example First-write-wins for bookings
+ * ```tsx
+ * function BookingManager() {
+ *   const { register, registered, loading, error } = useConflictResolver('bookings');
+ *
+ *   useEffect(() => {
+ *     // Register resolver on mount
+ *     register({
+ *       name: 'first-write-wins',
+ *       code: `
+ *         if (context.localValue !== undefined) {
+ *           return { action: 'reject', reason: 'Already booked' };
+ *         }
+ *         return { action: 'accept', value: context.remoteValue };
+ *       `,
+ *       priority: 100,
+ *     });
+ *   }, []);
+ *
+ *   return (
+ *     <div>
+ *       {loading && <span>Registering...</span>}
+ *       {error && <span>Error: {error.message}</span>}
+ *       <ul>
+ *         {registered.map(name => <li key={name}>{name}</li>)}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Numeric constraints
+ * ```tsx
+ * function InventorySettings() {
+ *   const { register } = useConflictResolver('inventory');
+ *
+ *   const enableNonNegative = async () => {
+ *     await register({
+ *       name: 'non-negative',
+ *       code: `
+ *         if (context.remoteValue < 0) {
+ *           return { action: 'reject', reason: 'Stock cannot be negative' };
+ *         }
+ *         return { action: 'accept', value: context.remoteValue };
+ *       `,
+ *       priority: 90,
+ *       keyPattern: 'stock:*',
+ *     });
+ *   };
+ *
+ *   return <button onClick={enableNonNegative}>Enable Stock Protection</button>;
+ * }
+ * ```
+ */
+declare function useConflictResolver(mapName: string, options?: UseConflictResolverOptions): UseConflictResolverResult;
+
+export { TopGunProvider, type TopGunProviderProps, type UseConflictResolverOptions, type UseConflictResolverResult, type UseEntryProcessorOptions, type UseEntryProcessorResult, type UseEventJournalOptions, type UseEventJournalResult, type UseMergeRejectionsOptions, type UseMergeRejectionsResult, type UseMutationResult, type UsePNCounterResult, type UseQueryOptions, type UseQueryResult, useClient, useConflictResolver, useEntryProcessor, useEventJournal, useMap, useMergeRejections, useMutation, useORMap, usePNCounter, useQuery, useTopic };