amplifyquery 1.0.0

package/README.md

@@ -0,0 +1,203 @@
+# AmplifyQuery
+
+A library that combines AWS Amplify and React Query, making it easier to manage Amplify backend data in React applications.
+
+## Key Features
+
+- 💡 **Simple Type-Based API**: Written in TypeScript for complete type safety and autocompletion support.
+- 🔄 **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.
+- 🛡 **Auth Mode Support**: Supports various AWS Amplify authentication modes (API Key, IAM, Cognito, etc.).
+- ⚡ **Performance Optimized**: Maximize performance with request batching and intelligent caching.
+
+## Installation
+
+```bash
+npm install amplifyquery
+# or
+yarn add amplifyquery
+```
+
+## Basic Usage
+
+### 1. Initialization
+
+```typescript
+import { AmplifyQuery } from "amplifyquery";
+import { generateClient } from "aws-amplify/api";
+
+// Create Amplify client and initialize AmplifyQuery
+const client = generateClient();
+AmplifyQuery.configure({
+  client,
+  // Caching options (optional)
+  isCachingEnabled: true,
+  // Customize Query Client configuration (optional)
+  queryClientConfig: {
+    defaultOptions: {
+      queries: {
+        staleTime: 60000, // 1 minute
+      },
+    },
+  },
+  // Storage configuration (optional)
+  storage: {
+    mmkvId: "my-app.cache", // MMKV store ID
+    cacheKey: "MY_QUERY_CACHE", // Cache key name
+    maxAge: 1000 * 60 * 60 * 24 * 3, // 3 days (in milliseconds)
+  },
+});
+```
+
+### 2. Service Creation
+
+```typescript
+import { AmplifyQuery } from "amplifyquery";
+
+// Define Todo model type (adjust to your backend schema)
+interface TodoModel {
+  id: string;
+  name: string;
+  description?: string;
+  completed: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// Create Todo service
+const TodoService = AmplifyQuery.createAmplifyService<TodoModel>("Todo");
+
+// Create Singleton service (for single-instance models)
+const UserSettingsService =
+  AmplifyQuery.createSingletonService<UserSettingsModel>("UserSettings");
+```
+
+### 3. Data Fetching and Saving
+
+```typescript
+// Fetch all items
+const todos = await TodoService.list();
+
+// Filtering
+const completedTodos = await TodoService.list({
+  filter: { completed: { eq: true } },
+});
+
+// Fetch a single item
+const todo = await TodoService.get("some-id");
+
+// Create
+const newTodo = await TodoService.create({
+  name: "Buy milk",
+  description: "Low-fat milk",
+  completed: false,
+});
+
+// Update
+await TodoService.update({
+  id: "some-id",
+  completed: true,
+});
+
+// Delete
+await TodoService.delete("some-id");
+```
+
+### 4. Using React Hooks
+
+```tsx
+import React from "react";
+import { View, Text, Button } from "react-native";
+
+function TodoScreen() {
+  // Hook for managing a list of items
+  const {
+    items: todos,
+    isLoading,
+    error,
+    refresh,
+    create,
+    update,
+    delete: deleteTodo,
+  } = TodoService.useHook();
+
+  // Hook for managing a single item
+  const { item: settings, update: updateSettings } =
+    UserSettingsService.useItemHook(); // Assuming UserSettingsService is defined
+
+  if (isLoading) return <Text>Loading...</Text>;
+  if (error) return <Text>Error: {error.message}</Text>;
+
+  return (
+    <View>
+      {todos.map((todo) => (
+        <View key={todo.id}>
+          <Text>{todo.name}</Text>
+          <Button
+            title={todo.completed ? "Done" : "Mark as Done"}
+            onPress={() => update({ id: todo.id, completed: !todo.completed })}
+          />
+          <Button title="Delete" onPress={() => deleteTodo(todo.id)} />
+        </View>
+      ))}
+      <Button
+        title="New Todo"
+        onPress={() => create({ name: "New Todo", completed: false })}
+      />
+      <Button title="Refresh" onPress={() => refresh()} />
+    </View>
+  );
+}
+```
+
+## Advanced Features
+
+### Caching
+
+AmplifyQuery uses MMKV to persistently cache query results. This allows the app to display previous data immediately upon restart.
+
+```typescript
+// Enable/disable caching (enabled by default)
+AmplifyQuery.configure({
+  client,
+  isCachingEnabled: true, // or false
+  storage: {
+    maxAge: 1000 * 60 * 60 * 24 * 7, // 7 days (in milliseconds)
+  },
+});
+
+// Reset cache for a specific model
+TodoService.resetCache();
+
+// Force refresh a specific query
+const todos = await TodoService.list({ forceRefresh: true });
+```
+
+### Authentication Modes
+
+Access data with various authentication methods.
+
+```typescript
+// Set global default authentication mode
+AmplifyQuery.configure({ client, defaultAuthMode: "userPool" });
+
+// Set authentication mode for a service
+TodoService.setAuthMode("apiKey");
+
+// Apply authentication mode to a specific request
+await TodoService.list({ authMode: "iam" });
+
+// Get a new service instance with a specific auth mode applied
+const adminTodoService = TodoService.withAuthMode("iam");
+```
+
+## Important Notes
+
+- This library is designed to be used with AWS Amplify v6 or higher.
+- Requires React Query v5 or higher.
+- Test thoroughly before using in a production project.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import { GraphQLClient } from "./types";
+/**
+ * Function to set the client.
+ * @param client GraphQL client to inject.
+ */
+export declare function setClient(client: GraphQLClient): void;
+/**
+ * Returns the currently configured client.
+ * Throws an error if the client has not been set.
+ */
+export declare function getClient(): GraphQLClient;

package/dist/client.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setClient = setClient;
+exports.getClient = getClient;
+/**
+ * API client to be used throughout the application.
+ * This is injected by the library user.
+ */
+let _client = null;
+/**
+ * Function to set the client.
+ * @param client GraphQL client to inject.
+ */
+function setClient(client) {
+    _client = client;
+}
+/**
+ * Returns the currently configured client.
+ * Throws an error if the client has not been set.
+ */
+function getClient() {
+    if (!_client) {
+        throw new Error("API client has not been configured. Please call AmplifyQuery.configure() first.");
+    }
+    return _client;
+}

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+import { getClient } from "./client";
+import { queryClient, createQueryKeys, invalidateModel, invalidateModelItem, invalidateModelByField, invalidateAll, ensureMutationsFlushed } from "./query";
+import { createAmplifyService } from "./service";
+import { createSingletonService } from "./singleton";
+import { AmplifyQueryConfig } from "./types";
+import { createRelationalHook, setAppUrl, getAppUrl } from "./utils";
+/**
+ * Initialization function for the AmplifyQuery library.
+ *
+ * This function must be called before using the library.
+ *
+ * @example
+ * ```typescript
+ * import { generateClient } from 'aws-amplify/api';
+ * import { AmplifyQuery } from 'amplifyquery';
+ *
+ * // Create Amplify client and initialize AmplifyQuery
+ * const client = generateClient();
+ * AmplifyQuery.configure({
+ *   client,
+ *   // Additional caching options, etc.
+ *   isCachingEnabled: true,
+ *   storage: {
+ *     mmkvId: "custom.cache",
+ *     maxAge: 1000 * 60 * 60 * 24 // 1 day
+ *   }
+ * });
+ * ```
+ */
+export declare function configure(config: AmplifyQueryConfig): void;
+export * from "./types";
+export { queryClient, invalidateModel, invalidateModelItem, invalidateModelByField, invalidateAll, ensureMutationsFlushed, createQueryKeys, };
+export { getClient };
+export declare const Utils: {
+    getUserId: () => Promise<string>;
+    formatTimestamp: (date?: Date) => string;
+    getDateString: (dateStr: string | undefined) => string;
+    removeOwnerField: <T extends Record<string, any>>(data: T, operation: "create" | "update" | "upsert") => Omit<T, "owner">;
+};
+export declare const Storage: {
+    _types: {
+        Item: {
+            url: string;
+            expiresAt: number;
+        };
+        CacheData: {
+            [key: string]: {
+                url: string;
+                expiresAt: number;
+            };
+        };
+    };
+    _urlCache: Map<string, {
+        url: string;
+        expiresAt: number;
+    }>;
+    _CACHE_KEY: string;
+    _initialized: boolean;
+    _initCache: () => void;
+    _saveCache: () => void;
+    uploadImage: (file: Blob | File, key?: string) => Promise<string>;
+    getFileUrl: (key: string, options?: {
+        forceRefresh?: boolean;
+    }) => Promise<string>;
+    deleteFile: (key: string) => Promise<void>;
+    clearUrlCache: () => void;
+    clearUrlCacheForKey: (key: string) => void;
+    clearExpiredUrlCache: () => void;
+    downloadAudioFile: (audioKey: string) => Promise<string>;
+};
+export declare const Auth: {
+    getCurrentUserInfo: () => Promise<{
+        userId: string;
+        username: string;
+    }>;
+};
+export { setAppUrl, getAppUrl };
+/**
+ * Main object for the AmplifyQuery library.
+ */
+export declare const AmplifyQuery: {
+    configure: typeof configure;
+    createQueryKeys: typeof createQueryKeys;
+    createAmplifyService: typeof createAmplifyService;
+    createSingletonService: typeof createSingletonService;
+    createRelationalHook: typeof createRelationalHook;
+    Utils: {
+        getUserId: () => Promise<string>;
+        formatTimestamp: (date?: Date) => string;
+        getDateString: (dateStr: string | undefined) => string;
+        removeOwnerField: <T extends Record<string, any>>(data: T, operation: "create" | "update" | "upsert") => Omit<T, "owner">;
+    };
+    Storage: {
+        _types: {
+            Item: {
+                url: string;
+                expiresAt: number;
+            };
+            CacheData: {
+                [key: string]: {
+                    url: string;
+                    expiresAt: number;
+                };
+            };
+        };
+        _urlCache: Map<string, {
+            url: string;
+            expiresAt: number;
+        }>;
+        _CACHE_KEY: string;
+        _initialized: boolean;
+        _initCache: () => void;
+        _saveCache: () => void;
+        uploadImage: (file: Blob | File, key?: string) => Promise<string>;
+        getFileUrl: (key: string, options?: {
+            forceRefresh?: boolean;
+        }) => Promise<string>;
+        deleteFile: (key: string) => Promise<void>;
+        clearUrlCache: () => void;
+        clearUrlCacheForKey: (key: string) => void;
+        clearExpiredUrlCache: () => void;
+        downloadAudioFile: (audioKey: string) => Promise<string>;
+    };
+    Auth: {
+        getCurrentUserInfo: () => Promise<{
+            userId: string;
+            username: string;
+        }>;
+    };
+    getModelIds: {
+        User: () => Promise<string>;
+    };
+};

package/dist/index.js

@@ -0,0 +1,89 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AmplifyQuery = exports.getAppUrl = exports.setAppUrl = exports.Auth = exports.Storage = exports.Utils = exports.getClient = exports.createQueryKeys = exports.ensureMutationsFlushed = exports.invalidateAll = exports.invalidateModelByField = exports.invalidateModelItem = exports.invalidateModel = exports.queryClient = void 0;
+exports.configure = configure;
+const client_1 = require("./client");
+Object.defineProperty(exports, "getClient", { enumerable: true, get: function () { return client_1.getClient; } });
+const query_1 = require("./query");
+Object.defineProperty(exports, "queryClient", { enumerable: true, get: function () { return query_1.queryClient; } });
+Object.defineProperty(exports, "createQueryKeys", { enumerable: true, get: function () { return query_1.createQueryKeys; } });
+Object.defineProperty(exports, "invalidateModel", { enumerable: true, get: function () { return query_1.invalidateModel; } });
+Object.defineProperty(exports, "invalidateModelItem", { enumerable: true, get: function () { return query_1.invalidateModelItem; } });
+Object.defineProperty(exports, "invalidateModelByField", { enumerable: true, get: function () { return query_1.invalidateModelByField; } });
+Object.defineProperty(exports, "invalidateAll", { enumerable: true, get: function () { return query_1.invalidateAll; } });
+Object.defineProperty(exports, "ensureMutationsFlushed", { enumerable: true, get: function () { return query_1.ensureMutationsFlushed; } });
+const service_1 = require("./service");
+const singleton_1 = require("./singleton");
+const utils_1 = require("./utils");
+Object.defineProperty(exports, "setAppUrl", { enumerable: true, get: function () { return utils_1.setAppUrl; } });
+Object.defineProperty(exports, "getAppUrl", { enumerable: true, get: function () { return utils_1.getAppUrl; } });
+/**
+ * Initialization function for the AmplifyQuery library.
+ *
+ * This function must be called before using the library.
+ *
+ * @example
+ * ```typescript
+ * import { generateClient } from 'aws-amplify/api';
+ * import { AmplifyQuery } from 'amplifyquery';
+ *
+ * // Create Amplify client and initialize AmplifyQuery
+ * const client = generateClient();
+ * AmplifyQuery.configure({
+ *   client,
+ *   // Additional caching options, etc.
+ *   isCachingEnabled: true,
+ *   storage: {
+ *     mmkvId: "custom.cache",
+ *     maxAge: 1000 * 60 * 60 * 24 // 1 day
+ *   }
+ * });
+ * ```
+ */
+function configure(config) {
+    // Configure Amplify client
+    if (config.client) {
+        (0, client_1.setClient)(config.client);
+    }
+    // Apply React Query settings
+    (0, query_1.configure)({
+        isCachingEnabled: config.isCachingEnabled,
+        queryClientConfig: config.queryClientConfig,
+        storage: config.storage,
+    });
+    console.log("🔌 AmplifyQuery initialized successfully.");
+}
+// Re-export types
+__exportStar(require("./types"), exports);
+// Re-export utility services
+exports.Utils = utils_1.Utils;
+exports.Storage = utils_1.StorageService;
+exports.Auth = utils_1.AuthService;
+/**
+ * Main object for the AmplifyQuery library.
+ */
+exports.AmplifyQuery = {
+    configure,
+    createQueryKeys: query_1.createQueryKeys,
+    createAmplifyService: service_1.createAmplifyService,
+    createSingletonService: singleton_1.createSingletonService,
+    createRelationalHook: utils_1.createRelationalHook,
+    Utils: utils_1.Utils,
+    Storage: utils_1.StorageService,
+    Auth: utils_1.AuthService,
+    getModelIds: singleton_1.getModelIds,
+};

package/dist/query.d.ts

@@ -0,0 +1,52 @@
+import { QueryClient, QueryClientConfig } from "@tanstack/react-query";
+type ConfigOptions = {
+    isCachingEnabled?: boolean;
+    queryClientConfig?: QueryClientConfig;
+    storage?: {
+        mmkvId?: string;
+        cacheKey?: string;
+        maxAge?: number;
+    };
+};
+/**
+ * TanStack Query client
+ */
+export declare let queryClient: QueryClient;
+/**
+ * AmplifyQuery configuration
+ * @param options Configuration options
+ */
+export declare function configure(options?: ConfigOptions): void;
+/**
+ * Create query keys from model names
+ * @param modelNames Array of model names
+ * @returns Object of query keys per model
+ */
+export declare function createQueryKeys(modelNames: string[]): Record<string, string[]>;
+/**
+ * Invalidate all queries for a model
+ * @param modelName Model name
+ */
+export declare function invalidateModel(modelName: string): void;
+/**
+ * Invalidate a model item with a specific ID
+ * @param modelName Model name
+ * @param id Item ID
+ */
+export declare function invalidateModelItem(modelName: string, id: string): void;
+/**
+ * Invalidate model items with a specific field value
+ * @param modelName Model name
+ * @param field Field name
+ * @param value Field value
+ */
+export declare function invalidateModelByField(modelName: string, field: string, value: any): void;
+/**
+ * Invalidate all query caches (full app reset)
+ */
+export declare function invalidateAll(): void;
+/**
+ * Ensure important changes are synced to server before app closes
+ */
+export declare function ensureMutationsFlushed(): Promise<unknown>;
+export {};