amplifyquery 1.0.18 → 1.0.20

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

@@ -35,3 +35,15 @@ export declare function getDefaultAuthMode(): "apiKey" | "iam" | "identityPool"
  * Reset global configuration (mainly for testing)
  */
 export declare function resetConfig(): void;
+/**
+ * Enable/disable singleton auto-create behavior for useCurrentHook().
+ */
+export declare function setSingletonAutoCreate(config: {
+    enabled?: boolean;
+    models?: string[];
+}): void;
+export declare function getSingletonAutoCreate(): {
+    enabled?: boolean;
+    models?: string[];
+} | undefined;
+export declare function isSingletonAutoCreateEnabledForModel(modelName: string): boolean;

package/dist/config.js

@@ -9,6 +9,9 @@ exports.getOwnerQueryName = getOwnerQueryName;
 exports.setDefaultAuthMode = setDefaultAuthMode;
 exports.getDefaultAuthMode = getDefaultAuthMode;
 exports.resetConfig = resetConfig;
+exports.setSingletonAutoCreate = setSingletonAutoCreate;
+exports.getSingletonAutoCreate = getSingletonAutoCreate;
+exports.isSingletonAutoCreateEnabledForModel = isSingletonAutoCreateEnabledForModel;
 // Global configuration state
 let globalConfig = {};
 /**
@@ -61,3 +64,24 @@ function resetConfig() {
     globalConfig = {};
     console.log("🔧 AmplifyQuery: Global configuration reset");
 }
+/**
+ * Enable/disable singleton auto-create behavior for useCurrentHook().
+ */
+function setSingletonAutoCreate(config) {
+    globalConfig.singletonAutoCreate = {
+        enabled: config.enabled === true,
+        models: Array.isArray(config.models) ? config.models : undefined,
+    };
+    console.log("🔧 AmplifyQuery: Singleton auto-create configured", globalConfig.singletonAutoCreate);
+}
+function getSingletonAutoCreate() {
+    return globalConfig.singletonAutoCreate;
+}
+function isSingletonAutoCreateEnabledForModel(modelName) {
+    const cfg = getSingletonAutoCreate();
+    if (!(cfg === null || cfg === void 0 ? void 0 : cfg.enabled))
+        return false;
+    if (!cfg.models || cfg.models.length === 0)
+        return true;
+    return cfg.models.includes(modelName);
+}

package/dist/index.js

@@ -69,6 +69,10 @@ function configure(config) {
     if (config.defaultAuthMode) {
         (0, config_1.setDefaultAuthMode)(config.defaultAuthMode);
     }
+    // Set singleton auto-create
+    if (config.singletonAutoCreate) {
+        (0, config_1.setSingletonAutoCreate)(config.singletonAutoCreate);
+    }
     // Apply React Query settings
     (0, query_1.configure)({
         isCachingEnabled: config.isCachingEnabled,

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, _m, _o;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
             const hookQueryClient = (0, react_query_1.useQueryClient)();
             // Determine query key
             const queryKey = (0, react_1.useMemo)(() => {
@@ -1372,10 +1372,32 @@ function createAmplifyService(modelName, defaultAuthMode) {
             }), [service, refetch] // refetch dependency added
             );
             const refresh = (0, react_1.useCallback)((refreshOptions) => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
                 console.log(`🍬 ${modelName} useHook refresh called`, queryKey);
-                const { data } = yield refetch({ throwOnError: true }); // Throw on error
-                return data || [];
-            }), [refetch, queryKey]);
+                // IMPORTANT:
+                // TanStack Query's refetch() re-runs queryFn, but our service.list/customList can short-circuit
+                // and return cached data unless forceRefresh is true.
+                // refresh() must guarantee a network fetch to reflect server-side updates.
+                try {
+                    if (options === null || options === void 0 ? void 0 : options.customList) {
+                        return yield service.customList(options.customList.queryName, options.customList.args, { forceRefresh: true });
+                    }
+                    const mergedFilter = (_a = refreshOptions === null || refreshOptions === void 0 ? void 0 : refreshOptions.filter) !== null && _a !== void 0 ? _a : (_b = options === null || options === void 0 ? void 0 : options.initialFetchOptions) === null || _b === void 0 ? void 0 : _b.filter;
+                    if (mergedFilter) {
+                        return yield service.list({
+                            filter: mergedFilter,
+                            forceRefresh: true,
+                        });
+                    }
+                    return yield service.list({ forceRefresh: true });
+                }
+                catch (e) {
+                    // Keep previous behavior of surfacing errors via refetch when desired
+                    // while still logging consistently.
+                    console.error(`🍬 ${modelName} useHook refresh error:`, e);
+                    throw e;
+                }
+            }), [modelName, options === null || options === void 0 ? void 0 : options.customList, (_p = options === null || options === void 0 ? void 0 : options.initialFetchOptions) === null || _p === void 0 ? void 0 : _p.filter, queryKey, service]);
             const customListFn = (0, react_1.useCallback)((queryName, args, options) => __awaiter(this, void 0, void 0, function* () {
                 try {
                     const result = yield service.customList(queryName, args, options);
@@ -1527,9 +1549,13 @@ function createAmplifyService(modelName, defaultAuthMode) {
             // Interface function implementations
             const refreshItem = (0, react_1.useCallback)(() => __awaiter(this, void 0, void 0, function* () {
                 console.log(`🍬 ${modelName} useItemHook refresh called`, singleItemQueryKey);
-                const { data } = yield refetch({ throwOnError: true }); // Throw on error
-                return data || null;
-            }), [refetch, singleItemQueryKey]); // Added queryKey dependency
+                // IMPORTANT:
+                // refetch() re-runs queryFn which calls service.get(id) (default forceRefresh=false).
+                // If cache exists, service.get will return cached data and never hit the network.
+                // refresh() must guarantee a network fetch to reflect server-side updates.
+                const latest = yield service.get(id, { forceRefresh: true });
+                return latest || null;
+            }), [id, modelName, service, singleItemQueryKey]); // Added id/modelName for correctness
             const updateItem = (0, react_1.useCallback)((data) => __awaiter(this, void 0, void 0, function* () {
                 // No additional work needed here as cache is already updated in service.update
                 try {

package/dist/singleton.js

@@ -14,6 +14,8 @@ exports.createSingletonService = createSingletonService;
 const client_1 = require("./client");
 const auth_1 = require("aws-amplify/auth");
 const react_query_1 = require("@tanstack/react-query");
+const config_1 = require("./config");
+const react_1 = require("react");
 /**
  * Function to create an extension service for singleton models
  * @param baseService Base service
@@ -125,7 +127,7 @@ function createSingletonService(baseService, getModelId) {
             }
         }), 
         // React hook to manage the current singleton item
-        useCurrentHook: () => {
+        useCurrentHook: (options) => {
             const { data: currentId, isLoading: isIdLoading, error: idError, refetch: refetchId, } = (0, react_query_1.useQuery)({
                 queryKey: [modelName, "currentId"],
                 queryFn: () => __awaiter(this, void 0, void 0, function* () {
@@ -147,7 +149,8 @@ function createSingletonService(baseService, getModelId) {
                 refetchOnWindowFocus: false,
             });
             const idForItemHook = currentId !== null && currentId !== void 0 ? currentId : "";
-            const core = baseService.useItemHook(idForItemHook);
+            const core = baseService.useItemHook(idForItemHook, options);
+            const didAutoCreateRef = (0, react_1.useRef)(false);
             const item = (() => {
                 var _a;
                 if (!currentId)
@@ -161,6 +164,29 @@ function createSingletonService(baseService, getModelId) {
             })();
             const isLoading = isIdLoading || core.isLoading;
             const error = idError || core.error || null;
+            (0, react_1.useEffect)(() => {
+                if (!currentId)
+                    return;
+                if (isLoading)
+                    return;
+                if (!(0, config_1.isSingletonAutoCreateEnabledForModel)(modelName))
+                    return;
+                if (didAutoCreateRef.current)
+                    return;
+                if (item)
+                    return;
+                didAutoCreateRef.current = true;
+                // Best-effort: create { id } if missing.
+                void (() => __awaiter(this, void 0, void 0, function* () {
+                    try {
+                        yield singletonService.upsertCurrent({});
+                        yield core.refresh();
+                    }
+                    catch (e) {
+                        console.warn(`🍬 ${modelName} useCurrentHook auto-create failed:`, e);
+                    }
+                }))();
+            }, [currentId, isLoading, item, modelName]);
             const refresh = () => __awaiter(this, void 0, void 0, function* () {
                 if (!currentId) {
                     const { data } = yield refetchId({ throwOnError: false });

package/dist/types.d.ts

@@ -118,7 +118,12 @@ export interface SingletonAmplifyService<T> extends AmplifyDataService<T> {
     }) => Promise<T | null>;
     updateCurrent: (data: Partial<T>) => Promise<T | null>;
     upsertCurrent: (data: Partial<T>) => Promise<T | null>;
-    useCurrentHook: () => ItemHook<T>;
+    useCurrentHook: (options?: {
+        realtime?: {
+            enabled?: boolean;
+            observeOptions?: Record<string, any>;
+        };
+    }) => ItemHook<T>;
 }
 export interface BaseModel {
     id: string;
@@ -142,6 +147,10 @@ export interface AmplifyQueryConfig {
     client: GraphQLClient;
     defaultAuthMode?: AuthMode;
     modelOwnerQueryMap?: Record<string, string>;
+    singletonAutoCreate?: {
+        enabled?: boolean;
+        models?: string[];
+    };
     isCachingEnabled?: boolean;
     queryClientConfig?: QueryClientConfig;
     storage?: {

package/package.json

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