@htlkg/data 0.0.21 → 0.0.23

package/src/hooks/createPaginatedDataHook.ts

@@ -0,0 +1,359 @@
+/**
+ * Paginated Data Hook Factory
+ *
+ * Creates reusable Vue composables for fetching paginated data from GraphQL models.
+ * Supports cursor-based pagination (nextToken) for efficient handling of large datasets.
+ *
+ * Key features:
+ * - Server-side pagination with nextToken
+ * - loadMore() for infinite scroll/pagination
+ * - hasMore indicator
+ * - Independent pagination state per hook instance
+ * - Built-in support for active/deleted filtering
+ */
+
+import { ref, computed, onMounted, type Ref, type ComputedRef } from "vue";
+import { query, hasErrors, getErrorMessage } from "../client/proxy";
+
+/**
+ * Filter for active items (not deleted)
+ * Uses OR condition because deletedAt can be:
+ * - Missing (attributeExists: false)
+ * - Explicitly null (eq: null)
+ */
+export const ACTIVE_FILTER = {
+	or: [{ deletedAt: { attributeExists: false } }, { deletedAt: { eq: null } }],
+};
+
+/**
+ * Filter for deleted items
+ * Uses gt: "" to match only actual timestamp strings (not null or missing)
+ */
+export const DELETED_FILTER = {
+	deletedAt: { gt: "" },
+};
+
+/**
+ * Configuration options for creating a paginated data hook
+ */
+export interface CreatePaginatedDataHookOptions<T, TOptions extends PaginatedHookOptions = PaginatedHookOptions> {
+	/** The GraphQL model name (e.g., 'Account', 'User', 'Brand') */
+	model: string;
+	/** Default page size */
+	defaultPageSize?: 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;
+	/** Plural name for the data property (e.g., 'accounts', 'users') */
+	dataPropertyName?: string;
+	/** Base filter to always apply (e.g., for active/deleted variants) */
+	baseFilter?: any;
+}
+
+/**
+ * Base options available to paginated hooks
+ */
+export interface PaginatedHookOptions {
+	/** Additional filter criteria (merged with baseFilter) */
+	filter?: any;
+	/** Page size (default: 25) */
+	pageSize?: number;
+	/** Auto-fetch on mount (default: true) */
+	autoFetch?: boolean;
+}
+
+/**
+ * Pagination state
+ */
+export interface PaginationState {
+	/** Current nextToken for fetching next page */
+	nextToken: string | null;
+	/** Whether there are more items to load */
+	hasMore: boolean;
+	/** Total items loaded so far */
+	loadedCount: number;
+}
+
+/**
+ * Return type for paginated data hooks
+ */
+export interface PaginatedDataHookReturn<T> {
+	/** Reactive array of data (accumulated across pages) */
+	data: Ref<T[]>;
+	/** Loading state (true during any fetch) */
+	loading: Ref<boolean>;
+	/** Loading state for initial fetch */
+	initialLoading: Ref<boolean>;
+	/** Loading state for loadMore */
+	loadingMore: Ref<boolean>;
+	/** Error state */
+	error: Ref<Error | null>;
+	/** Pagination state */
+	pagination: Ref<PaginationState>;
+	/** Whether there are more items to load */
+	hasMore: ComputedRef<boolean>;
+	/** Load next page of data */
+	loadMore: () => Promise<void>;
+	/** Refetch data (resets to first page) */
+	refetch: () => Promise<void>;
+	/** Reset data and pagination state */
+	reset: () => void;
+	/** Update search filter and refetch from server (searches ALL data) */
+	setSearchFilter: (filter: any) => Promise<void>;
+	/** Current search filter */
+	searchFilter: Ref<any>;
+}
+
+/**
+ * Creates a reusable paginated data hook for a specific model
+ *
+ * @example
+ * ```typescript
+ * // Create a hook for active brands
+ * export const useActiveBrands = createPaginatedDataHook<Brand>({
+ *   model: 'Brand',
+ *   dataPropertyName: 'brands',
+ *   baseFilter: ACTIVE_FILTER,
+ *   selectionSet: ['id', 'name', 'status', 'accountId', 'account.name'],
+ * });
+ *
+ * // Usage in component
+ * const { brands, loading, hasMore, loadMore, refetch } = useActiveBrands({
+ *   pageSize: 25,
+ * });
+ * ```
+ *
+ * @example With custom filter builder
+ * ```typescript
+ * interface UseBrandsOptions extends PaginatedHookOptions {
+ *   accountId?: string;
+ * }
+ *
+ * export const useActiveBrands = createPaginatedDataHook<Brand, UseBrandsOptions>({
+ *   model: 'Brand',
+ *   dataPropertyName: 'brands',
+ *   baseFilter: ACTIVE_FILTER,
+ *   buildFilter: (options) => {
+ *     if (options.accountId) {
+ *       return { accountId: { eq: options.accountId } };
+ *     }
+ *     return undefined;
+ *   },
+ * });
+ * ```
+ */
+export function createPaginatedDataHook<T, TOptions extends PaginatedHookOptions = PaginatedHookOptions>(
+	config: CreatePaginatedDataHookOptions<T, TOptions>,
+) {
+	const {
+		model,
+		defaultPageSize = 25,
+		selectionSet,
+		transform,
+		buildFilter,
+		dataPropertyName = "data",
+		baseFilter,
+	} = config;
+
+	return function usePaginatedData(
+		options: TOptions = {} as TOptions,
+	): PaginatedDataHookReturn<T> & Record<string, any> {
+		const { filter: additionalFilter, pageSize = defaultPageSize, autoFetch = true } = options;
+
+		// State
+		const data = ref<T[]>([]) as Ref<T[]>;
+		const loading = ref(false);
+		const initialLoading = ref(false);
+		const loadingMore = ref(false);
+		const error = ref<Error | null>(null);
+		const pagination = ref<PaginationState>({
+			nextToken: null,
+			hasMore: true,
+			loadedCount: 0,
+		});
+
+		// Dynamic search filter (for server-side filtering)
+		const searchFilter = ref<any>(null);
+
+		// Computed
+		const hasMore = computed(() => pagination.value.hasMore);
+
+		// Build combined filter
+		const getFilter = () => {
+			const filters: any[] = [];
+
+			// Add base filter (e.g., active/deleted)
+			if (baseFilter) {
+				filters.push(baseFilter);
+			}
+
+			// Add custom filter from buildFilter
+			if (buildFilter) {
+				const customFilter = buildFilter(options);
+				if (customFilter) {
+					filters.push(customFilter);
+				}
+			}
+
+			// Add additional filter from options
+			if (additionalFilter && Object.keys(additionalFilter).length > 0) {
+				filters.push(additionalFilter);
+			}
+
+			// Add dynamic search filter (for server-side search)
+			if (searchFilter.value && Object.keys(searchFilter.value).length > 0) {
+				filters.push(searchFilter.value);
+			}
+
+			// Combine filters with AND
+			if (filters.length === 0) {
+				return undefined;
+			}
+			if (filters.length === 1) {
+				return filters[0];
+			}
+			return { and: filters };
+		};
+
+		// Fetch function
+		async function fetchPage(nextToken?: string | null, append: boolean = false) {
+			if (!append) {
+				initialLoading.value = true;
+			} else {
+				loadingMore.value = true;
+			}
+			loading.value = true;
+			error.value = null;
+
+			try {
+				const queryOptions: Record<string, any> = {
+					limit: pageSize,
+				};
+
+				const filter = getFilter();
+				if (filter) {
+					queryOptions.filter = filter;
+				}
+
+				if (nextToken) {
+					queryOptions.nextToken = nextToken;
+				}
+
+				if (selectionSet) {
+					queryOptions.selectionSet = selectionSet;
+				}
+
+				const response = await query(model, "list", queryOptions);
+
+				if (hasErrors(response)) {
+					throw new Error(getErrorMessage(response) || `Failed to fetch ${model}`);
+				}
+
+				const items = response.data || [];
+				const transformedItems = transform ? items.map(transform) : items;
+
+				if (append) {
+					data.value = [...data.value, ...transformedItems];
+				} else {
+					data.value = transformedItems;
+				}
+
+				// Update pagination state
+				// Note: Amplify returns nextToken in the response
+				const responseNextToken = (response as any).nextToken;
+				pagination.value = {
+					nextToken: responseNextToken || null,
+					hasMore: !!responseNextToken,
+					loadedCount: data.value.length,
+				};
+			} catch (e) {
+				error.value = e as Error;
+				console.error(`[use${model}] Error fetching ${model}:`, e);
+			} finally {
+				loading.value = false;
+				initialLoading.value = false;
+				loadingMore.value = false;
+			}
+		}
+
+		// Load more function
+		async function loadMore() {
+			if (loadingMore.value || !pagination.value.hasMore) {
+				return;
+			}
+			await fetchPage(pagination.value.nextToken, true);
+		}
+
+		// Refetch (reset to first page)
+		async function refetch() {
+			pagination.value = {
+				nextToken: null,
+				hasMore: true,
+				loadedCount: 0,
+			};
+			await fetchPage(null, false);
+		}
+
+		// Reset state
+		function reset() {
+			data.value = [];
+			error.value = null;
+			searchFilter.value = null;
+			pagination.value = {
+				nextToken: null,
+				hasMore: true,
+				loadedCount: 0,
+			};
+		}
+
+		// Set search filter and refetch from server (searches ALL data)
+		async function setSearchFilter(filter: any) {
+			searchFilter.value = filter;
+			// Reset pagination and fetch with new filter
+			pagination.value = {
+				nextToken: null,
+				hasMore: true,
+				loadedCount: 0,
+			};
+			await fetchPage(null, false);
+		}
+
+		// Auto-fetch on mount if enabled
+		if (autoFetch) {
+			onMounted(() => {
+				fetchPage(null, false);
+			});
+		}
+
+		// Build return object
+		const result: PaginatedDataHookReturn<T> & Record<string, any> = {
+			data,
+			loading,
+			initialLoading,
+			loadingMore,
+			error,
+			pagination,
+			hasMore,
+			loadMore,
+			refetch,
+			reset,
+			setSearchFilter,
+			searchFilter,
+		};
+
+		// Add data property with custom name for backwards compatibility
+		if (dataPropertyName !== "data") {
+			result[dataPropertyName] = data;
+		}
+
+		return result;
+	};
+}
+
+/**
+ * Type helper to extract the return type of a created paginated hook
+ */
+export type InferPaginatedHookReturn<THook extends (...args: any[]) => any> = ReturnType<THook>;

package/src/hooks/data-hook-errors.property.test.ts

@@ -9,10 +9,10 @@
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import * as fc from "fast-check";
-import { useBrands } from "./useBrands";
-import { useAccounts } from "./useAccounts";
-import { useUsers } from "./useUsers";
-import { useProducts } from "./useProducts";
+import { useBrands } from "./brands/useBrands";
+import { useAccounts } from "./accounts/useAccounts";
+import { useUsers } from "./users/useUsers";
+import { useProducts } from "./products/useProducts";
 
 // Create separate mock functions for each model
 const mockBrandList = vi.fn();

package/src/hooks/data-hook-filters.property.test.ts

@@ -9,10 +9,10 @@
 
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import * as fc from "fast-check";
-import { useBrands } from "./useBrands";
-import { useAccounts } from "./useAccounts";
-import { useUsers } from "./useUsers";
-import { useProducts } from "./useProducts";
+import { useBrands } from "./brands/useBrands";
+import { useAccounts } from "./accounts/useAccounts";
+import { useUsers } from "./users/useUsers";
+import { useProducts } from "./products/useProducts";
 import type { Brand, Account, Product } from "@htlkg/core/types";
 
 // Create separate mock functions for each model

package/src/hooks/data-hooks.property.test.ts

@@ -10,10 +10,10 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import * as fc from "fast-check";
 import { ref, isRef, isReactive, computed } from "vue";
-import { useBrands } from "./useBrands";
-import { useAccounts } from "./useAccounts";
-import { useUsers } from "./useUsers";
-import { useProducts } from "./useProducts";
+import { useBrands } from "./brands/useBrands";
+import { useAccounts } from "./accounts/useAccounts";
+import { useUsers } from "./users/useUsers";
+import { useProducts } from "./products/useProducts";
 
 // Mock the client module
 vi.mock("../client", () => ({

package/src/hooks/index.ts

@@ -2,6 +2,7 @@
  * Data Hooks for @htlkg/data
  *
  * Vue composables for fetching and managing data with reactive state.
+ * Organized by entity type in subfolders for better maintainability.
  */
 
 // Hook factory for creating custom data hooks
@@ -14,11 +15,103 @@ export {
 	type InferHookReturn,
 } from "./createDataHook";
 
-// Pre-built hooks for common models
-export { useBrands, type UseBrandsOptions, type UseBrandsReturn } from "./useBrands";
-export { useAccounts, type UseAccountsOptions, type UseAccountsReturn } from "./useAccounts";
-export { useUsers, type UseUsersOptions, type UseUsersReturn } from "./useUsers";
-export { useProducts, type UseProductsOptions, type UseProductsReturn } from "./useProducts";
-export { useProductInstances, type UseProductInstancesOptions, type UseProductInstancesReturn } from "./useProductInstances";
-export { useReservations, type UseReservationsOptions, type UseReservationsReturn } from "./useReservations";
-export { useContacts, type UseContactsOptions, type UseContactsReturn } from "./useContacts";
+// Paginated hook factory for large datasets
+export {
+	createPaginatedDataHook,
+	ACTIVE_FILTER,
+	DELETED_FILTER,
+	type CreatePaginatedDataHookOptions,
+	type PaginatedHookOptions,
+	type PaginationState,
+	type PaginatedDataHookReturn,
+	type InferPaginatedHookReturn,
+} from "./createPaginatedDataHook";
+
+// ============================================
+// BRAND HOOKS
+// ============================================
+export {
+	useBrands,
+	useActiveBrands,
+	useDeletedBrands,
+	type UseBrandsOptions,
+	type UseBrandsReturn,
+	type BrandWithCounts,
+	type UsePaginatedBrandsOptions,
+	type UsePaginatedBrandsReturn,
+} from "./brands";
+
+// ============================================
+// USER HOOKS
+// ============================================
+export {
+	useUsers,
+	useActiveUsers,
+	useDeletedUsers,
+	type UseUsersOptions,
+	type UseUsersReturn,
+	type UserWithRelations,
+	type UsePaginatedUsersOptions,
+	type UsePaginatedUsersReturn,
+} from "./users";
+
+// ============================================
+// ACCOUNT HOOKS
+// ============================================
+export {
+	useAccounts,
+	useActiveAccounts,
+	useDeletedAccounts,
+	type UseAccountsOptions,
+	type UseAccountsReturn,
+	type AccountWithBrands,
+	type AccountWithBrands as PaginatedAccountWithBrands,
+	type UsePaginatedAccountsOptions,
+	type UsePaginatedAccountsReturn,
+} from "./accounts";
+
+// ============================================
+// RESERVATION HOOKS
+// ============================================
+export {
+	useReservations,
+	useActiveReservations,
+	useDeletedReservations,
+	type UseReservationsOptions,
+	type UseReservationsReturn,
+	type ReservationWithRelations,
+	type UsePaginatedReservationsOptions,
+	type UsePaginatedReservationsReturn,
+} from "./reservations";
+
+// ============================================
+// PRODUCT HOOKS
+// ============================================
+export {
+	useProducts,
+	type UseProductsOptions,
+	type UseProductsReturn,
+} from "./products";
+
+// ============================================
+// PRODUCT INSTANCE HOOKS
+// ============================================
+export {
+	useProductInstances,
+	type UseProductInstancesOptions,
+	type UseProductInstancesReturn,
+} from "./productInstances";
+
+// ============================================
+// CONTACT HOOKS
+// ============================================
+export {
+	useContacts,
+	useActiveContacts,
+	useDeletedContacts,
+	type UseContactsOptions,
+	type UseContactsReturn,
+	type ContactWithRelations,
+	type UsePaginatedContactsOptions,
+	type UsePaginatedContactsReturn,
+} from "./contacts";

package/src/hooks/productInstances/index.ts

@@ -0,0 +1 @@
+export * from "./useProductInstances";

package/src/hooks/{useProductInstances.ts → productInstances/useProductInstances.ts}

@@ -1,14 +1,14 @@
 /**
- * useProductInstances Hook
+ * ProductInstance Hooks
  *
- * Vue composable for fetching and managing product instance data with reactive state.
+ * Vue composables for fetching and managing product instance data with reactive state.
  * Provides loading states, error handling, refetch capabilities, and CRUD operations.
  */
 
 import type { Ref, ComputedRef } from "vue";
 import type { ProductInstance } from "@htlkg/core/types";
-import { createDataHook, type BaseHookOptions } from "./createDataHook";
-import { getSharedClient } from "../client";
+import { createDataHook, type BaseHookOptions } from "../createDataHook";
+import { getSharedClient } from "../../client";
 import {
 	createProductInstance,
 	updateProductInstance,
@@ -16,7 +16,7 @@ import {
 	toggleProductInstanceEnabled,
 	type CreateProductInstanceInput,
 	type UpdateProductInstanceInput,
-} from "../mutations/productInstances";
+} from "../../mutations/productInstances";
 
 export interface UseProductInstancesOptions extends BaseHookOptions {
 	/** Filter criteria for product instances */
@@ -102,7 +102,7 @@ const useProductInstancesInternal = createDataHook<
  *
  * @example
  * ```typescript
- * import { useProductInstances } from '@htlkg/data/hooks';
+ * import { useProductInstances } from '@htlkg/data/hooks/productInstances';
  *
  * const { instances, loading, error, refetch } = useProductInstances();
  * ```
@@ -172,3 +172,6 @@ export function useProductInstances(options: UseProductInstancesOptions = {}): U
 		toggleEnabled,
 	};
 }
+
+// Re-export types for convenience
+export type { CreateProductInstanceInput, UpdateProductInstanceInput };

package/src/hooks/products/index.ts

@@ -0,0 +1 @@
+export * from "./useProducts";

package/src/hooks/{useProducts.ts → products/useProducts.ts}

@@ -1,13 +1,12 @@
 /**
- * useProducts Hook
+ * Product Hooks
  *
- * Vue composable for fetching and managing product data with reactive state.
- * Provides loading states, error handling, and refetch capabilities.
+ * Vue composables for fetching and managing product data with reactive state.
  */
 
 import type { Ref, ComputedRef } from "vue";
 import type { Product } from "@htlkg/core/types";
-import { createDataHook, type BaseHookOptions } from "./createDataHook";
+import { createDataHook, type BaseHookOptions } from "../createDataHook";
 
 export interface UseProductsOptions extends BaseHookOptions {
 	/** Filter criteria for products */
@@ -63,7 +62,7 @@ const useProductsInternal = createDataHook<Product, UseProductsOptions, { active
  *
  * @example
  * ```typescript
- * import { useProducts } from '@htlkg/data/hooks';
+ * import { useProducts } from '@htlkg/data/hooks/products';
  *
  * const { products, loading, error, refetch } = useProducts();
  * ```

package/src/hooks/reservations/index.ts

@@ -0,0 +1,2 @@
+export * from "./useReservations";
+export * from "./usePaginatedReservations";