local-lite 0.0.3 → 0.0.5

package/dist/react/index.d.ts

@@ -1,6 +1,10 @@
-import { LocalFirstClient } from '../core/client.js';
-import { QueryOptions, SyncMetrics } from '../core/types.js';
+import { LocalFirstClient, TransactionalClient } from '../core/client.js';
+import { BatchMutation, MutateOptions, QueryOptions } from '../core/types.js';
 export type LiveQueryFn<T> = (client: LocalFirstClient) => Promise<T[]> | T[];
+/**
+ * Clears the in-memory live query cache.
+ */
+export declare function clearLiveQueryCache(): void;
 /**
  * Hook to execute a live reactive table query that automatically re-runs
  * whenever the table is mutated locally or via incoming remote delta.
@@ -24,25 +28,92 @@ export declare function useLiveQuery<T = any>(client: LocalFirstClient | null |
     refetch: () => Promise<void>;
     loading: boolean;
 };
-export interface UseSyncStatusResult {
-    isOnline: boolean;
-    isPushing: boolean;
-    isPulling: boolean;
-    isSyncing: boolean;
-    pendingCount: number;
-    pendingRecords: any[];
-    lastSyncedAt: number | null;
-    refresh: () => Promise<void>;
+export type MultiQuerySpec<T = any> = string | (QueryOptions & {
+    table?: string;
+}) | LiveQueryFn<T>;
+export type MultiQueryInput = Array<string | (QueryOptions & {
+    table: string;
+})> | Record<string, MultiQuerySpec>;
+export interface UseLiveQueriesResult<T extends Record<string, any[]>> {
+    data: T;
+    loading: boolean;
+    refetch: () => Promise<void>;
 }
 /**
- * Consolidated hook that tracks real-time sync connectivity, sync worker activity
- * (pushing/pulling/syncing), and pending items in the local SQLite outbox queue.
+ * Reactive multi-table live query hook that loads data from multiple tables concurrently.
+ *
+ * Benefits:
+ * - Parallel fetching: queries SQLite tables concurrently via Promise.all.
+ * - Single atomic React commit: coalesces multiple table results into a single state update,
+ *   preventing cascading re-renders and UI freezing.
+ * - Multi-table event coordination: listens to mutations across all requested tables,
+ *   coalescing updates so downstream calculations only run once.
+ * - Zero-latency cache read-through: returns instant cached rows on mount.
+ *
+ * Usage with dictionary:
+ * ```ts
+ * const { data, loading } = useLiveQueries(client, {
+ *   projects: 'projects',
+ *   tasks: { where: { project_id: '123' }, orderBy: 'created_at' },
+ *   tags: { table: 'labels' }
+ * });
+ * // data.projects, data.tasks, data.tags
+ * ```
+ *
+ * Usage with array:
+ * ```ts
+ * const { data, loading } = useLiveQueries(client, ['projects', 'tasks', 'tags']);
+ * // data.projects, data.tasks, data.tags
+ * ```
  */
-export declare function useSyncStatus(client: LocalFirstClient | null | undefined): UseSyncStatusResult;
+export declare function useLiveQueries<T extends Record<string, any[]> = Record<string, any[]>>(client: LocalFirstClient | null | undefined, queries: MultiQueryInput): UseLiveQueriesResult<T>;
 /**
- * Hook that provides real-time sync telemetry and engine performance metrics.
+ * Reactive hook to query a single record by primary key with 0ms cache read-through.
+ * Automatically re-renders only when this specific row or table changes.
  */
-export declare function useSyncMetrics(client: LocalFirstClient | null | undefined, pollIntervalMs?: number): {
-    metrics: SyncMetrics | null;
-    refresh: () => Promise<void>;
+export declare function useLiveRow<T = any>(client: LocalFirstClient | null | undefined, tableName: string, rowId: string | null | undefined, options?: {
+    includeDeleted?: boolean;
+}): {
+    data: T | null;
+    refetch: () => Promise<void>;
+    loading: boolean;
 };
+export interface InfiniteQueryOptions extends QueryOptions {
+    pageSize?: number;
+}
+export interface UseLiveInfiniteQueryResult<T> {
+    data: T[];
+    loading: boolean;
+    isFetchingNextPage: boolean;
+    hasNextPage: boolean;
+    fetchNextPage: () => Promise<void>;
+    refetch: () => Promise<void>;
+}
+/**
+ * Reactive infinite query hook that progressively loads pages of records
+ * with live updates when underlying table rows are inserted, updated, or synced.
+ */
+export declare function useLiveInfiniteQuery<T = any>(client: LocalFirstClient | null | undefined, tableName: string, options?: InfiniteQueryOptions): UseLiveInfiniteQueryResult<T>;
+export interface UseMutationsResult<TTable extends string = string> {
+    client: LocalFirstClient | null | undefined;
+    insert: <T extends Record<string, any> = Record<string, any>>(tableName: TTable | (string & {}), payload: T, options?: MutateOptions) => Promise<string | undefined>;
+    insertMany: <T extends Record<string, any> = Record<string, any>>(tableName: TTable | (string & {}), records: T[], options?: MutateOptions) => Promise<string[] | undefined>;
+    update: <T extends Record<string, any> = Record<string, any>>(tableName: TTable | (string & {}), rowId: string, payload: Partial<T>, options?: MutateOptions) => Promise<void>;
+    updateMany: <T extends Record<string, any> = Record<string, any>>(tableName: TTable | (string & {}), updates: Array<{
+        id: string;
+        payload: Partial<T>;
+    }>, options?: MutateOptions) => Promise<void>;
+    delete: (tableName: TTable | (string & {}), rowId: string, options?: MutateOptions) => Promise<void>;
+    batch: (mutations: BatchMutation[]) => Promise<string[] | undefined>;
+    transaction: <T>(action: (txClient: TransactionalClient) => Promise<T>) => Promise<T | undefined>;
+}
+/**
+ * Universal mutations hook providing memoized, null-safe helpers for database operations.
+ */
+export declare function useMutations<TTable extends string = string>(client: LocalFirstClient | null | undefined): UseMutationsResult<TTable>;
+export * from './runner.js';
+export * from './status.js';
+export * from './theme.js';
+export * from './BenchmarkModal.js';
+export { SyncInspector, SyncIndicator } from './SyncInspector.js';
+export type { SyncInspectorProps, SyncIndicatorProps } from './SyncInspector.js';