@htlkg/data 0.0.21 → 0.0.22

package/src/hooks/brands/usePaginatedBrands.ts

@@ -0,0 +1,206 @@
+/**
+ * Paginated Brands Hooks
+ *
+ * Vue composables for fetching brands with server-side pagination.
+ * Provides separate hooks for active and deleted brands to enable
+ * efficient tab-based filtering in large datasets.
+ */
+
+import type { Ref, ComputedRef } from "vue";
+import type { Brand } from "@htlkg/core/types";
+import {
+	createPaginatedDataHook,
+	ACTIVE_FILTER,
+	DELETED_FILTER,
+	type PaginatedHookOptions,
+	type PaginationState,
+} from "../createPaginatedDataHook";
+
+/** Extended Brand type with computed fields */
+export type BrandWithCounts = Brand & {
+	accountName?: string;
+	enabledProductCount?: number;
+	totalProductCount?: number;
+	deletedAt?: string;
+	deletedBy?: string;
+};
+
+export interface UsePaginatedBrandsOptions extends PaginatedHookOptions {
+	/** Filter by account ID */
+	accountId?: string;
+}
+
+export interface UsePaginatedBrandsReturn {
+	/** Reactive array of brands */
+	brands: Ref<BrandWithCounts[]>;
+	/** 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>;
+}
+
+/**
+ * Build additional filter from hook options
+ */
+function buildFilter(options: UsePaginatedBrandsOptions): any {
+	const conditions: any[] = [];
+
+	if (options.accountId) {
+		conditions.push({ accountId: { eq: options.accountId } });
+	}
+
+	if (options.filter && Object.keys(options.filter).length > 0) {
+		conditions.push(options.filter);
+	}
+
+	if (conditions.length === 0) {
+		return undefined;
+	}
+	if (conditions.length === 1) {
+		return conditions[0];
+	}
+	return { and: conditions };
+}
+
+/**
+ * Transform brand data
+ */
+function transformBrand(brand: any): BrandWithCounts {
+	return {
+		...brand,
+		accountName: brand.account?.name || "",
+	};
+}
+
+/**
+ * Selection set for brand queries
+ */
+const BRAND_SELECTION_SET = [
+	"id",
+	"name",
+	"accountId",
+	"logo",
+	"timezone",
+	"status",
+	"settings",
+	"deletedAt",
+	"deletedBy",
+	"account.name",
+];
+
+/**
+ * Internal hook for active brands
+ */
+const useActiveBrandsInternal = createPaginatedDataHook<BrandWithCounts, UsePaginatedBrandsOptions>({
+	model: "Brand",
+	dataPropertyName: "brands",
+	defaultPageSize: 25,
+	selectionSet: BRAND_SELECTION_SET,
+	transform: transformBrand,
+	buildFilter,
+	baseFilter: ACTIVE_FILTER,
+});
+
+/**
+ * Internal hook for deleted brands
+ */
+const useDeletedBrandsInternal = createPaginatedDataHook<BrandWithCounts, UsePaginatedBrandsOptions>({
+	model: "Brand",
+	dataPropertyName: "brands",
+	defaultPageSize: 25,
+	selectionSet: BRAND_SELECTION_SET,
+	transform: transformBrand,
+	buildFilter,
+	baseFilter: DELETED_FILTER,
+});
+
+/**
+ * Composable for fetching active (non-deleted) brands with pagination
+ *
+ * @example
+ * ```typescript
+ * import { useActiveBrands } from '@htlkg/data/hooks';
+ *
+ * const { brands, loading, hasMore, loadMore, refetch } = useActiveBrands({
+ *   pageSize: 25,
+ * });
+ *
+ * // Load more when user scrolls or clicks "Load More"
+ * async function onLoadMore() {
+ *   await loadMore();
+ * }
+ * ```
+ *
+ * @example With account filter
+ * ```typescript
+ * const { brands, loading } = useActiveBrands({
+ *   accountId: 'account-123',
+ *   pageSize: 50
+ * });
+ * ```
+ */
+export function useActiveBrands(options: UsePaginatedBrandsOptions = {}): UsePaginatedBrandsReturn {
+	const result = useActiveBrandsInternal(options);
+	return {
+		brands: result.brands as Ref<BrandWithCounts[]>,
+		loading: result.loading,
+		initialLoading: result.initialLoading,
+		loadingMore: result.loadingMore,
+		error: result.error,
+		pagination: result.pagination,
+		hasMore: result.hasMore,
+		loadMore: result.loadMore,
+		refetch: result.refetch,
+		reset: result.reset,
+		setSearchFilter: result.setSearchFilter,
+		searchFilter: result.searchFilter,
+	};
+}
+
+/**
+ * Composable for fetching deleted brands with pagination
+ *
+ * @example
+ * ```typescript
+ * import { useDeletedBrands } from '@htlkg/data/hooks';
+ *
+ * const { brands, loading, hasMore, loadMore, refetch } = useDeletedBrands({
+ *   pageSize: 25,
+ * });
+ * ```
+ */
+export function useDeletedBrands(options: UsePaginatedBrandsOptions = {}): UsePaginatedBrandsReturn {
+	const result = useDeletedBrandsInternal(options);
+	return {
+		brands: result.brands as Ref<BrandWithCounts[]>,
+		loading: result.loading,
+		initialLoading: result.initialLoading,
+		loadingMore: result.loadingMore,
+		error: result.error,
+		pagination: result.pagination,
+		hasMore: result.hasMore,
+		loadMore: result.loadMore,
+		refetch: result.refetch,
+		reset: result.reset,
+		setSearchFilter: result.setSearchFilter,
+		searchFilter: result.searchFilter,
+	};
+}

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", () => ({