amplifyquery 1.0.18 → 1.0.19

package/README.md

@@ -8,9 +8,11 @@ A library that combines AWS Amplify and React Query, making it easier to manage
 - 🔄 **React Query Integration**: Leverage all React Query features like caching, retries, background updates, etc.
 - 📱 **Offline Support**: Persistent query caching via MMKV for fast data loading even offline.
 - 🪝 **Convenient Hooks API**: Abstract complex data synchronization into simple Hooks.
+- 🔴 **Realtime Subscriptions**: Built-in support for AWS Amplify realtime updates with automatic cache synchronization.
 - 🛡 **Auth Mode Support**: Supports various AWS Amplify authentication modes (API Key, IAM, Cognito, etc.).
 - ⚙️ **Global Configuration**: Set model mappings and auth modes once - no more repetitive configuration.
 - ⚡ **Performance Optimized**: Maximize performance with request batching and intelligent caching.
+- 🔄 **Automatic Cache Sync**: Mutations automatically update the cache for consistent UI state.
 
 ## Installation
 
@@ -192,6 +194,8 @@ await TodoService.delete("some-id");
 
 ### 5. Using React Hooks
 
+#### Basic Usage
+
 ```tsx
 import React from "react";
 import { View, Text, Button } from "react-native";
@@ -206,11 +210,16 @@ function TodoScreen() {
     create,
     update,
     delete: deleteTodo,
+    getItem,
   } = TodoService.useHook();
 
   // Hook for managing a single item
-  const { item: settings, update: updateSettings } =
-    UserSettingsService.useItemHook(); // Assuming UserSettingsService is defined
+  const {
+    item: settings,
+    isLoading: isSettingsLoading,
+    update: updateSettings,
+    refresh: refreshSettings,
+  } = UserSettingsService.useItemHook("settings-id");
 
   if (isLoading) return <Text>Loading...</Text>;
   if (error) return <Text>Error: {error.message}</Text>;
@@ -237,8 +246,118 @@ function TodoScreen() {
 }
 ```
 
+#### Realtime Subscriptions
+
+Enable real-time updates using AWS Amplify's `observeQuery` feature:
+
+```tsx
+function TodoScreen() {
+  // Enable realtime for list updates
+  const {
+    items: todos,
+    isLoading,
+    isSynced, // true when realtime subscription is active
+    create,
+    update,
+    delete: deleteTodo,
+  } = TodoService.useHook({
+    realtime: {
+      enabled: true,
+      // Optional: filter events to subscribe to
+      events: ["create", "update", "delete"],
+    },
+  });
+
+  // Enable realtime for single item updates
+  const {
+    item: todo,
+    isSynced: isItemSynced,
+    update: updateTodo,
+  } = TodoService.useItemHook(todoId, {
+    realtime: {
+      enabled: true,
+    },
+  });
+
+  return (
+    <View>
+      {isSynced && <Text>🟢 Live updates active</Text>}
+      {todos.map((todo) => (
+        <Text key={todo.id}>{todo.name}</Text>
+      ))}
+    </View>
+  );
+}
+```
+
+**Realtime Features:**
+- ✅ Automatic cache synchronization when data changes
+- ✅ Works across multiple devices/sessions
+- ✅ `isSynced` flag indicates subscription status
+- ✅ Optimistic updates are immediately reflected
+- ✅ No manual refresh needed for real-time changes
+
+**Note:** When `realtime.enabled` is `true`, the initial fetch is skipped to avoid duplicate data. The subscription provides the initial data set.
+
 ## Advanced Features
 
+### Realtime Subscriptions
+
+AmplifyQuery supports real-time data synchronization using AWS Amplify's `observeQuery` API. When enabled, your UI automatically updates when data changes on the server or other devices.
+
+#### useHook Realtime Options
+
+```typescript
+const {
+  items,
+  isSynced, // true when subscription is active
+  create,
+  update,
+  delete: deleteItem,
+} = TodoService.useHook({
+  realtime: {
+    enabled: true, // Enable realtime subscription
+    events: ["create", "update", "delete"], // Optional: filter events
+    observeOptions: {
+      // Optional: additional observeQuery options
+      filter: { completed: { eq: false } },
+    },
+  },
+});
+```
+
+#### useItemHook Realtime Options
+
+```typescript
+const {
+  item,
+  isSynced, // true when subscription is active
+  update,
+  delete: deleteItem,
+} = TodoService.useItemHook(todoId, {
+  realtime: {
+    enabled: true,
+    observeOptions: {
+      // Optional: additional observeQuery options
+    },
+  },
+});
+```
+
+#### How It Works
+
+1. **Initial Load**: When `realtime.enabled` is `true`, the hook subscribes to `observeQuery` instead of making a one-time fetch
+2. **Cache Updates**: All changes (create/update/delete) are automatically synchronized to the React Query cache
+3. **Cross-Device**: Changes made on other devices or sessions are immediately reflected
+4. **Optimistic Updates**: Local mutations are immediately reflected, then confirmed via realtime events
+
+#### Best Practices
+
+- Use realtime for collaborative features or when data changes frequently
+- Monitor `isSynced` to show connection status to users
+- Combine with optimistic updates for the best user experience
+- Consider using `events` filter to reduce unnecessary updates
+
 ### Global Configuration
 
 AmplifyQuery supports global configuration to reduce code duplication and simplify service creation.
@@ -338,6 +457,25 @@ TodoService.resetCache();
 const todos = await TodoService.list({ forceRefresh: true });
 ```
 
+#### Automatic Cache Synchronization
+
+AmplifyQuery automatically synchronizes the cache when you use hook methods (`create`, `update`, `delete`):
+
+- **Immediate Updates**: Changes are reflected in the UI immediately after successful operations
+- **Consistent State**: The cache stays in sync across all hook instances
+- **Optimistic Updates**: UI updates before server confirmation for better UX
+- **Realtime Integration**: Works seamlessly with realtime subscriptions
+
+```tsx
+// Create, update, delete automatically update the cache
+const { create, update, delete: deleteItem } = TodoService.useHook();
+
+// These operations immediately update the hook's items array
+await create({ name: "New Todo" });
+await update({ id: todoId, completed: true });
+await deleteItem(todoId);
+```
+
 ### Authentication Modes
 
 Access data with various authentication methods.
@@ -363,10 +501,62 @@ await TodoService.list({ authMode: "iam" });
 const adminTodoService = TodoService.withAuthMode("iam");
 ```
 
+### Hook API Reference
+
+#### useHook(options?)
+
+Returns a hook for managing a list of items.
+
+**Options:**
+- `initialFetchOptions?: { fetch?: boolean, filter?: Record<string, any> }` - Control initial data fetch
+- `customList?: { queryName: string, args: Record<string, any>, forceRefresh?: boolean }` - Use custom query for list
+- `realtime?: { enabled?: boolean, observeOptions?: Record<string, any>, events?: Array<"create" | "update" | "delete"> }` - Enable realtime subscriptions
+
+**Returns:**
+```typescript
+{
+  items: T[];              // Array of items
+  isLoading: boolean;       // Loading state
+  error: Error | null;      // Error state
+  isSynced?: boolean;       // Realtime sync status (if realtime enabled)
+  getItem: (id: string) => T | undefined;  // Get item by ID from cache
+  refresh: (options?: { filter?: Record<string, any> }) => Promise<T[]>;  // Refresh list
+  create: (data: Partial<T>) => Promise<T | null>;  // Create new item
+  update: (data: Partial<T> & { id: string }) => Promise<T | null>;  // Update item
+  delete: (id: string) => Promise<boolean>;  // Delete item
+  customList?: (queryName: string, args: Record<string, any>, options?: { forceRefresh?: boolean }) => Promise<T[]>;  // Custom list query
+}
+```
+
+#### useItemHook(id, options?)
+
+Returns a hook for managing a single item.
+
+**Parameters:**
+- `id: string` - The ID of the item to manage
+
+**Options:**
+- `realtime?: { enabled?: boolean, observeOptions?: Record<string, any> }` - Enable realtime subscription
+
+**Returns:**
+```typescript
+{
+  item: T | null;          // The item (null if not found or not loaded)
+  isLoading: boolean;       // Loading state
+  error: Error | null;      // Error state
+  isSynced?: boolean;       // Realtime sync status (if realtime enabled)
+  refresh: () => Promise<T | null>;  // Refresh item
+  update: (data: Partial<T>) => Promise<T | null>;  // Update item (id not needed)
+  delete: () => Promise<boolean>;  // Delete item (id not needed)
+}
+```
+
 ## Important Notes
 
 - This library is designed to be used with AWS Amplify v6 or higher.
 - Requires React Query v5 or higher.
+- When `realtime.enabled` is `true`, the initial fetch is skipped to avoid duplicate data.
+- All mutations (`create`, `update`, `delete`) automatically synchronize the cache.
 - Test thoroughly before using in a production project.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amplifyquery",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "Amplify+Query",
   "keywords": [
     "Amplify",