@htlkg/data 0.0.1 → 0.0.3

package/src/hooks/README.md

@@ -0,0 +1,293 @@
+# Data Hooks
+
+Vue composables for fetching and managing data with reactive state management.
+
+## Overview
+
+Data hooks provide a consistent, type-safe way to interact with Amplify Data models using Vue's Composition API. Each hook provides:
+
+- **Reactive state**: Automatic reactivity for data, loading, and error states
+- **Auto-fetch**: Optional automatic data fetching on component mount
+- **Error handling**: Built-in error state management and logging
+- **Refetch**: Manual refetch capability for refreshing data
+- **Filtering**: Support for GraphQL filters and options
+
+## Available Hooks
+
+### useBrands
+
+Fetch and manage brand data.
+
+```typescript
+import { useBrands } from '@htlkg/data/hooks';
+
+const { brands, activeBrands, loading, error, refetch } = useBrands({
+  accountId: 'account-123',
+  activeOnly: true,
+  limit: 50
+});
+```
+
+**Options:**
+- `filter` - GraphQL filter criteria
+- `limit` - Maximum number of results
+- `autoFetch` - Auto-fetch on mount (default: true)
+- `accountId` - Filter by account ID
+- `activeOnly` - Only return active brands
+
+**Returns:**
+- `brands` - Reactive array of all brands
+- `activeBrands` - Computed array of active brands only
+- `loading` - Loading state
+- `error` - Error state
+- `refetch` - Function to refetch data
+
+### useAccounts
+
+Fetch and manage account data.
+
+```typescript
+import { useAccounts } from '@htlkg/data/hooks';
+
+const { accounts, loading, error, refetch } = useAccounts({
+  filter: { status: { eq: 'active' } },
+  limit: 50
+});
+```
+
+**Options:**
+- `filter` - GraphQL filter criteria
+- `limit` - Maximum number of results
+- `autoFetch` - Auto-fetch on mount (default: true)
+
+**Returns:**
+- `accounts` - Reactive array of accounts
+- `loading` - Loading state
+- `error` - Error state
+- `refetch` - Function to refetch data
+
+### useUsers
+
+Fetch and manage user data.
+
+```typescript
+import { useUsers } from '@htlkg/data/hooks';
+
+const { users, loading, error, refetch } = useUsers({
+  brandId: 'brand-123',
+  accountId: 'account-456',
+  limit: 50
+});
+```
+
+**Options:**
+- `filter` - GraphQL filter criteria
+- `limit` - Maximum number of results
+- `autoFetch` - Auto-fetch on mount (default: true)
+- `brandId` - Filter by brand ID
+- `accountId` - Filter by account ID
+
+**Returns:**
+- `users` - Reactive array of users
+- `loading` - Loading state
+- `error` - Error state
+- `refetch` - Function to refetch data
+
+### useProducts
+
+Fetch and manage product data.
+
+```typescript
+import { useProducts } from '@htlkg/data/hooks';
+
+const { products, activeProducts, loading, error, refetch } = useProducts({
+  activeOnly: true,
+  limit: 50
+});
+```
+
+**Options:**
+- `filter` - GraphQL filter criteria
+- `limit` - Maximum number of results
+- `autoFetch` - Auto-fetch on mount (default: true)
+- `activeOnly` - Only return active products
+
+**Returns:**
+- `products` - Reactive array of all products
+- `activeProducts` - Computed array of active products only
+- `loading` - Loading state
+- `error` - Error state
+- `refetch` - Function to refetch data
+
+## Usage Examples
+
+### Basic Usage
+
+```vue
+<script setup lang="ts">
+import { useBrands } from '@htlkg/data/hooks';
+
+// Auto-fetches on mount
+const { brands, loading, error } = useBrands();
+</script>
+
+<template>
+  <div v-if="loading">Loading...</div>
+  <div v-else-if="error">Error: {{ error.message }}</div>
+  <div v-else>
+    <div v-for="brand in brands" :key="brand.id">
+      {{ brand.name }}
+    </div>
+  </div>
+</template>
+```
+
+### With Filters
+
+```vue
+<script setup lang="ts">
+import { useBrands } from '@htlkg/data/hooks';
+
+const { brands, loading } = useBrands({
+  accountId: 'account-123',
+  activeOnly: true,
+  limit: 50
+});
+</script>
+```
+
+### Manual Fetch
+
+```vue
+<script setup lang="ts">
+import { useBrands } from '@htlkg/data/hooks';
+import { onMounted } from 'vue';
+
+const { brands, loading, refetch } = useBrands({
+  autoFetch: false
+});
+
+onMounted(async () => {
+  await refetch();
+});
+</script>
+```
+
+### Computed Filters
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { useBrands } from '@htlkg/data/hooks';
+
+const searchQuery = ref('');
+const { brands } = useBrands();
+
+const filteredBrands = computed(() =>
+  brands.value.filter(b => 
+    b.name.toLowerCase().includes(searchQuery.value.toLowerCase())
+  )
+);
+</script>
+```
+
+## Implementation Details
+
+### State Management
+
+Each hook uses Vue's `ref` and `computed` for reactive state:
+
+```typescript
+const brands = ref<Brand[]>([]);
+const loading = ref(false);
+const error = ref<Error | null>(null);
+
+const activeBrands = computed(() =>
+  brands.value.filter(b => b.status === 'active')
+);
+```
+
+### Auto-fetch
+
+Hooks automatically fetch data on mount when `autoFetch` is true (default):
+
+```typescript
+if (autoFetch) {
+  onMounted(() => {
+    fetch();
+  });
+}
+```
+
+### Error Handling
+
+Errors are caught, logged, and stored in the error state:
+
+```typescript
+try {
+  const { data, errors } = await client.models.Brand.list({ filter, limit });
+  
+  if (errors) {
+    throw new Error(errors[0]?.message || "Failed to fetch brands");
+  }
+  
+  brands.value = data || [];
+} catch (e) {
+  error.value = e as Error;
+  console.error("[useBrands] Error fetching brands:", e);
+}
+```
+
+### Filter Building
+
+Hooks build GraphQL filters from options:
+
+```typescript
+let filter: any = baseFilter || {};
+
+if (accountId) {
+  filter = { ...filter, accountId: { eq: accountId } };
+}
+
+if (activeOnly) {
+  filter = { ...filter, status: { eq: "active" } };
+}
+```
+
+## Testing
+
+Basic smoke tests verify hook structure:
+
+```typescript
+import { useBrands } from '@htlkg/data/hooks';
+
+const result = useBrands({ autoFetch: false });
+
+expect(result).toHaveProperty("brands");
+expect(result).toHaveProperty("loading");
+expect(result).toHaveProperty("error");
+expect(result).toHaveProperty("refetch");
+```
+
+Run tests:
+
+```bash
+npm run test
+```
+
+## Requirements
+
+Implements requirements:
+- **3.4**: Data hooks provide Vue composables for brands, accounts, users, and products
+- **11.1**: useBrands returns brands, loading, error, and refetch
+- **11.2**: useAccounts returns accounts, loading, error, and refetch
+- **11.3**: useUsers returns users, loading, error, and refetch
+
+## Next Steps
+
+Future enhancements may include:
+- Caching with localStorage
+- Real-time subscriptions
+- Pagination support
+- Optimistic updates
+- Request deduplication

package/src/hooks/createDataHook.ts

@@ -0,0 +1,208 @@
+/**
+ * Data Hook Factory
+ *
+ * Creates reusable Vue composables for fetching data from GraphQL models.
+ * Provides a DRY approach to data fetching with consistent patterns.
+ */
+
+import { ref, computed, onMounted, type Ref, type ComputedRef } from "vue";
+import { getSharedClient, resetSharedClient } from "../client";
+
+/**
+ * Configuration options for creating a data hook
+ */
+export interface CreateDataHookOptions<T, TOptions extends BaseHookOptions = BaseHookOptions> {
+	/** The GraphQL model name (e.g., 'Account', 'User', 'Brand') */
+	model: string;
+	/** Default limit for queries */
+	defaultLimit?: number;
+	/** Selection set for the query (fields to fetch) */
+	selectionSet?: string[];
+	/** Transform function to apply to fetched data */
+	transform?: (item: any) => T;
+	/** Build filter from hook options */
+	buildFilter?: (options: TOptions) => any;
+	/** Define computed properties based on the data */
+	computedProperties?: Record<string, (data: T[]) => any>;
+	/** Plural name for the data property (e.g., 'accounts', 'users') */
+	dataPropertyName?: string;
+}
+
+/**
+ * Base options available to all hooks
+ */
+export interface BaseHookOptions {
+	/** Filter criteria */
+	filter?: any;
+	/** Limit number of results */
+	limit?: number;
+	/** Auto-fetch on mount (default: true) */
+	autoFetch?: boolean;
+}
+
+/**
+ * Return type for data hooks
+ */
+export interface DataHookReturn<T, TComputed extends Record<string, any> = Record<string, never>> {
+	/** Reactive array of data */
+	data: Ref<T[]>;
+	/** Loading state */
+	loading: Ref<boolean>;
+	/** Error state */
+	error: Ref<Error | null>;
+	/** Refetch data */
+	refetch: () => Promise<void>;
+	/** Computed properties */
+	computed: { [K in keyof TComputed]: ComputedRef<TComputed[K]> };
+}
+
+// Re-export resetSharedClient for testing convenience
+export { resetSharedClient as resetClientInstance };
+
+/**
+ * Creates a reusable data hook for a specific model
+ *
+ * @example
+ * ```typescript
+ * // Create a simple hook
+ * export const useAccounts = createDataHook<Account>({
+ *   model: 'Account',
+ *   dataPropertyName: 'accounts',
+ * });
+ *
+ * // Usage
+ * const { data: accounts, loading, error, refetch } = useAccounts();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create a hook with custom filters and computed properties
+ * interface UseBrandsOptions extends BaseHookOptions {
+ *   accountId?: string;
+ *   activeOnly?: boolean;
+ * }
+ *
+ * export const useBrands = createDataHook<Brand, UseBrandsOptions>({
+ *   model: 'Brand',
+ *   dataPropertyName: 'brands',
+ *   buildFilter: (options) => {
+ *     const filter: any = options.filter || {};
+ *     if (options.accountId) filter.accountId = { eq: options.accountId };
+ *     if (options.activeOnly) filter.status = { eq: 'active' };
+ *     return Object.keys(filter).length > 0 ? filter : undefined;
+ *   },
+ *   computedProperties: {
+ *     activeBrands: (brands) => brands.filter(b => b.status === 'active'),
+ *   },
+ * });
+ * ```
+ */
+export function createDataHook<
+	T,
+	TOptions extends BaseHookOptions = BaseHookOptions,
+	TComputed extends Record<string, any> = Record<string, never>,
+>(
+	config: CreateDataHookOptions<T, TOptions> & {
+		computedProperties?: { [K in keyof TComputed]: (data: T[]) => TComputed[K] };
+	},
+) {
+	const {
+		model,
+		defaultLimit,
+		selectionSet,
+		transform,
+		buildFilter,
+		computedProperties,
+		dataPropertyName = "data",
+	} = config;
+
+	return function useData(options: TOptions = {} as TOptions): DataHookReturn<T, TComputed> & Record<string, any> {
+		const { filter: baseFilter, limit = defaultLimit, autoFetch = true } = options;
+
+		// State
+		const data = ref<T[]>([]) as Ref<T[]>;
+		const loading = ref(false);
+		const error = ref<Error | null>(null);
+
+		// Build filter using custom builder or default
+		const getFilter = () => {
+			if (buildFilter) {
+				return buildFilter(options);
+			}
+			return baseFilter && Object.keys(baseFilter).length > 0 ? baseFilter : undefined;
+		};
+
+		// Fetch function
+		async function fetch() {
+			loading.value = true;
+			error.value = null;
+
+			try {
+				const client = getSharedClient();
+				const queryOptions: any = {
+					filter: getFilter(),
+					limit,
+				};
+
+				if (selectionSet) {
+					queryOptions.selectionSet = selectionSet;
+				}
+
+				const { data: responseData, errors } = await (client as any).models[model].list(queryOptions);
+
+				if (errors) {
+					throw new Error(errors[0]?.message || `Failed to fetch ${model}`);
+				}
+
+				const items = responseData || [];
+				data.value = transform ? items.map(transform) : items;
+			} catch (e) {
+				error.value = e as Error;
+				console.error(`[use${model}] Error fetching ${model}:`, e);
+			} finally {
+				loading.value = false;
+			}
+		}
+
+		// Create computed properties
+		const computedRefs: Record<string, ComputedRef<any>> = {};
+		if (computedProperties) {
+			for (const [key, fn] of Object.entries(computedProperties)) {
+				computedRefs[key] = computed(() => fn(data.value));
+			}
+		}
+
+		// Auto-fetch on mount if enabled
+		if (autoFetch) {
+			onMounted(() => {
+				fetch();
+			});
+		}
+
+		// Build return object
+		const result: DataHookReturn<T, TComputed> & Record<string, any> = {
+			data,
+			loading,
+			error,
+			refetch: fetch,
+			computed: computedRefs as { [K in keyof TComputed]: ComputedRef<TComputed[K]> },
+		};
+
+		// Add data property with custom name for backwards compatibility
+		if (dataPropertyName !== "data") {
+			result[dataPropertyName] = data;
+		}
+
+		// Add computed properties at top level for backwards compatibility
+		for (const [key, computedRef] of Object.entries(computedRefs)) {
+			result[key] = computedRef;
+		}
+
+		return result;
+	};
+}
+
+/**
+ * Type helper to extract the return type of a created hook
+ */
+export type InferHookReturn<THook extends (...args: any[]) => any> = ReturnType<THook>;