amplifyquery 1.0.17 → 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/dist/config.d.ts

@@ -11,6 +11,10 @@ export declare function setModelOwnerQueryMap(queryMap: Record<string, string>):
  * @returns The global model owner query mapping or undefined if not set
  */
 export declare function getModelOwnerQueryMap(): Record<string, string> | undefined;
+/**
+ * Set the global selection set mapping
+ * @param selectionSetMap Mapping of model names to selection sets
+ */
 /**
  * Get owner query name for a specific model
  * @param modelName The model name

package/dist/config.js

@@ -26,6 +26,10 @@ function setModelOwnerQueryMap(queryMap) {
 function getModelOwnerQueryMap() {
     return globalConfig.modelOwnerQueryMap;
 }
+/**
+ * Set the global selection set mapping
+ * @param selectionSetMap Mapping of model names to selection sets
+ */
 /**
  * Get owner query name for a specific model
  * @param modelName The model name

package/dist/service.js

@@ -1122,7 +1122,7 @@ function createAmplifyService(modelName, defaultAuthMode) {
         },
         // React Hook returning method - Reimplemented based on TanStack Query
         useHook: (options) => {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
             const hookQueryClient = (0, react_query_1.useQueryClient)();
             // Determine query key
             const queryKey = (0, react_1.useMemo)(() => {
@@ -1171,10 +1171,11 @@ function createAmplifyService(modelName, defaultAuthMode) {
                 service,
             ]);
             const realtimeEnabled = ((_h = options === null || options === void 0 ? void 0 : options.realtime) === null || _h === void 0 ? void 0 : _h.enabled) === true;
+            const realtimeEvents = (_k = (_j = options === null || options === void 0 ? void 0 : options.realtime) === null || _j === void 0 ? void 0 : _j.events) !== null && _k !== void 0 ? _k : ["create", "update", "delete"];
             const queryOptions = {
                 queryKey,
                 queryFn,
-                enabled: ((_j = options === null || options === void 0 ? void 0 : options.initialFetchOptions) === null || _j === void 0 ? void 0 : _j.fetch) !== false && !realtimeEnabled,
+                enabled: ((_l = options === null || options === void 0 ? void 0 : options.initialFetchOptions) === null || _l === void 0 ? void 0 : _l.fetch) !== false && !realtimeEnabled,
                 staleTime: 1000 * 30, // Keep fresh for 30 seconds (refresh more frequently)
                 refetchOnMount: true, // Refetch on component mount
                 refetchOnWindowFocus: false, // Don't auto-refetch on window focus
@@ -1183,22 +1184,63 @@ function createAmplifyService(modelName, defaultAuthMode) {
             const [isSynced, setIsSynced] = (0, react_1.useState)(undefined);
             const { data: items = [], isLoading, error, refetch, } = (0, react_query_1.useQuery)(queryOptions);
             (0, react_1.useEffect)(() => {
-                var _a, _b, _c;
+                var _a, _b, _c, _d, _e, _f;
                 if (!realtimeEnabled)
                     return;
                 if (options === null || options === void 0 ? void 0 : options.customList) {
-                    console.warn(`🍬 ${modelName} useHook realtime: customList is not supported.`);
-                    return;
+                    const client = (0, client_1.getClient)();
+                    const model = (_a = client.models) === null || _a === void 0 ? void 0 : _a[modelName];
+                    if (!model) {
+                        console.warn(`🍬 ${modelName} useHook realtime: model not available.`);
+                        return;
+                    }
+                    const observeOptions = Object.assign({}, (((_b = options === null || options === void 0 ? void 0 : options.realtime) === null || _b === void 0 ? void 0 : _b.observeOptions) || {}));
+                    if (observeOptions.filter === undefined &&
+                        ((_c = options === null || options === void 0 ? void 0 : options.initialFetchOptions) === null || _c === void 0 ? void 0 : _c.filter)) {
+                        observeOptions.filter = options.initialFetchOptions.filter;
+                    }
+                    const subscriptions = [
+                        realtimeEvents.includes("create") && model.onCreate
+                            ? model.onCreate(observeOptions).subscribe({
+                                next: () => hookQueryClient.invalidateQueries({
+                                    queryKey,
+                                    refetchType: "active",
+                                }),
+                                error: (err) => console.error(`🍬 ${modelName} useHook realtime onCreate error:`, err),
+                            })
+                            : null,
+                        realtimeEvents.includes("update") && model.onUpdate
+                            ? model.onUpdate(observeOptions).subscribe({
+                                next: () => hookQueryClient.invalidateQueries({
+                                    queryKey,
+                                    refetchType: "active",
+                                }),
+                                error: (err) => console.error(`🍬 ${modelName} useHook realtime onUpdate error:`, err),
+                            })
+                            : null,
+                        realtimeEvents.includes("delete") && model.onDelete
+                            ? model.onDelete(observeOptions).subscribe({
+                                next: () => hookQueryClient.invalidateQueries({
+                                    queryKey,
+                                    refetchType: "active",
+                                }),
+                                error: (err) => console.error(`🍬 ${modelName} useHook realtime onDelete error:`, err),
+                            })
+                            : null,
+                    ].filter(Boolean);
+                    return () => {
+                        subscriptions.forEach((sub) => { var _a; return (_a = sub === null || sub === void 0 ? void 0 : sub.unsubscribe) === null || _a === void 0 ? void 0 : _a.call(sub); });
+                    };
                 }
                 const client = (0, client_1.getClient)();
-                const model = (_a = client.models) === null || _a === void 0 ? void 0 : _a[modelName];
+                const model = (_d = client.models) === null || _d === void 0 ? void 0 : _d[modelName];
                 if (!(model === null || model === void 0 ? void 0 : model.observeQuery)) {
                     console.warn(`🍬 ${modelName} useHook realtime: observeQuery not available.`);
                     return;
                 }
-                const observeOptions = Object.assign({}, (((_b = options === null || options === void 0 ? void 0 : options.realtime) === null || _b === void 0 ? void 0 : _b.observeOptions) || {}));
+                const observeOptions = Object.assign({}, (((_e = options === null || options === void 0 ? void 0 : options.realtime) === null || _e === void 0 ? void 0 : _e.observeOptions) || {}));
                 if (observeOptions.filter === undefined &&
-                    ((_c = options === null || options === void 0 ? void 0 : options.initialFetchOptions) === null || _c === void 0 ? void 0 : _c.filter)) {
+                    ((_f = options === null || options === void 0 ? void 0 : options.initialFetchOptions) === null || _f === void 0 ? void 0 : _f.filter)) {
                     observeOptions.filter = options.initialFetchOptions.filter;
                 }
                 let isMounted = true;
@@ -1243,8 +1285,8 @@ function createAmplifyService(modelName, defaultAuthMode) {
                 queryKey,
                 hookQueryClient,
                 options === null || options === void 0 ? void 0 : options.customList,
-                (_k = options === null || options === void 0 ? void 0 : options.initialFetchOptions) === null || _k === void 0 ? void 0 : _k.filter,
-                (_l = options === null || options === void 0 ? void 0 : options.realtime) === null || _l === void 0 ? void 0 : _l.observeOptions,
+                (_m = options === null || options === void 0 ? void 0 : options.initialFetchOptions) === null || _m === void 0 ? void 0 : _m.filter,
+                (_o = options === null || options === void 0 ? void 0 : options.realtime) === null || _o === void 0 ? void 0 : _o.observeOptions,
             ]);
             // Interface functions implementation
             const getItem = (0, react_1.useCallback)((id) => {
@@ -1358,9 +1400,11 @@ function createAmplifyService(modelName, defaultAuthMode) {
             };
         },
         // Hook for managing single item - Reimplemented based on TanStack Query
-        useItemHook: (id) => {
+        useItemHook: (id, options) => {
+            var _a, _b;
             const hookQueryClient = (0, react_query_1.useQueryClient)();
             const singleItemQueryKey = itemKey(modelName, id);
+            const realtimeEnabled = ((_a = options === null || options === void 0 ? void 0 : options.realtime) === null || _a === void 0 ? void 0 : _a.enabled) === true;
             // First check data from cache
             const rawCachedData = hookQueryClient.getQueryData(singleItemQueryKey);
             // 🔧 버그 수정: 배열이 캐시되어 있는 경우 처리
@@ -1392,8 +1436,83 @@ function createAmplifyService(modelName, defaultAuthMode) {
                 staleTime: 1000 * 60, // Keep data "fresh" for 1 minute
                 refetchOnMount: cachedData ? false : true, // Only refetch if no cached data
                 refetchOnWindowFocus: false, // Disable window focus refetch to prevent loops
-                enabled: !!id, // Only enable query when id exists
+                enabled: !!id && !realtimeEnabled, // Only enable query when id exists
             });
+            const [isSynced, setIsSynced] = (0, react_1.useState)(undefined);
+            (0, react_1.useEffect)(() => {
+                var _a, _b;
+                if (!realtimeEnabled || !id)
+                    return;
+                const client = (0, client_1.getClient)();
+                const model = (_a = client.models) === null || _a === void 0 ? void 0 : _a[modelName];
+                if (!(model === null || model === void 0 ? void 0 : model.observeQuery)) {
+                    console.warn(`🍬 ${modelName} useItemHook realtime: observeQuery not available.`);
+                    return;
+                }
+                const observeOptions = Object.assign({}, (((_b = options === null || options === void 0 ? void 0 : options.realtime) === null || _b === void 0 ? void 0 : _b.observeOptions) || {}));
+                if (!observeOptions.filter) {
+                    observeOptions.filter = { id: { eq: id } };
+                }
+                let isMounted = true;
+                const subscription = model.observeQuery(observeOptions).subscribe({
+                    next: ({ items: nextItems, isSynced: synced }) => {
+                        if (!isMounted)
+                            return;
+                        const safeItems = Array.isArray(nextItems)
+                            ? nextItems.filter(Boolean)
+                            : [];
+                        const nextItem = safeItems.find((entry) => (entry === null || entry === void 0 ? void 0 : entry.id) === id) || null;
+                        const relatedQueryKeys = findRelatedQueryKeys(modelName, hookQueryClient);
+                        if (nextItem) {
+                            hookQueryClient.setQueryData(singleItemQueryKey, nextItem);
+                            relatedQueryKeys.forEach((queryKey) => {
+                                if (isItemKeyForModel(modelName, queryKey)) {
+                                    return;
+                                }
+                                hookQueryClient.setQueryData(queryKey, (oldData) => {
+                                    const oldItems = Array.isArray(oldData) ? oldData : [];
+                                    const hasItem = oldItems.some((entry) => (entry === null || entry === void 0 ? void 0 : entry.id) === id);
+                                    if (hasItem) {
+                                        return oldItems.map((entry) => (entry === null || entry === void 0 ? void 0 : entry.id) === id ? nextItem : entry);
+                                    }
+                                    if (queryKey.length === 1) {
+                                        return [...oldItems, nextItem];
+                                    }
+                                    return oldItems;
+                                });
+                            });
+                        }
+                        else {
+                            hookQueryClient.setQueryData(singleItemQueryKey, null);
+                            relatedQueryKeys.forEach((queryKey) => {
+                                if (isItemKeyForModel(modelName, queryKey)) {
+                                    return;
+                                }
+                                hookQueryClient.setQueryData(queryKey, (oldData) => {
+                                    const oldItems = Array.isArray(oldData) ? oldData : [];
+                                    return oldItems.filter((entry) => (entry === null || entry === void 0 ? void 0 : entry.id) !== id);
+                                });
+                            });
+                        }
+                        setIsSynced(Boolean(synced));
+                    },
+                    error: (err) => {
+                        console.error(`🍬 ${modelName} useItemHook realtime subscribe error:`, err);
+                    },
+                });
+                return () => {
+                    var _a;
+                    isMounted = false;
+                    (_a = subscription === null || subscription === void 0 ? void 0 : subscription.unsubscribe) === null || _a === void 0 ? void 0 : _a.call(subscription);
+                };
+            }, [
+                realtimeEnabled,
+                id,
+                modelName,
+                hookQueryClient,
+                singleItemQueryKey,
+                (_b = options === null || options === void 0 ? void 0 : options.realtime) === null || _b === void 0 ? void 0 : _b.observeOptions,
+            ]);
             // useMutation hooks call service methods,
             // Service methods handle optimistic updates and cache updates/rollbacks internally.
             // Mutations inside useHook only serve to call service methods.
@@ -1463,6 +1582,7 @@ function createAmplifyService(modelName, defaultAuthMode) {
                 item: item || null,
                 isLoading: effectiveLoading, // Not loading if cached data exists
                 error: error, // Explicitly specify error type
+                isSynced,
                 refresh: refreshItem,
                 update: updateItem,
                 delete: deleteItem,

package/dist/types.d.ts

@@ -41,6 +41,7 @@ export type ModelHook<T> = {
 export type ItemHook<T> = {
     item: T | null;
     isLoading: boolean;
+    isSynced?: boolean;
     error: Error | null;
     refresh: () => Promise<T | null>;
     update: (data: Partial<T>) => Promise<T | null>;
@@ -96,9 +97,15 @@ export interface AmplifyDataService<T> {
         realtime?: {
             enabled?: boolean;
             observeOptions?: Record<string, any>;
+            events?: Array<"create" | "update" | "delete">;
         };
     }) => ModelHook<T>;
-    useItemHook: (id: string) => ItemHook<T>;
+    useItemHook: (id: string, options?: {
+        realtime?: {
+            enabled?: boolean;
+            observeOptions?: Record<string, any>;
+        };
+    }) => ItemHook<T>;
     modelName: string;
     withExtensions: <E>(extensions: E) => AmplifyDataService<T> & E;
     setAuthMode: (authMode: AuthMode) => void;

package/package.json

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