@htlkg/data 0.0.1 → 0.0.3

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

@@ -0,0 +1,190 @@
+/**
+ * Property-Based Tests for Data Hooks
+ *
+ * Feature: htlkg-modular-architecture, Property 5: Data hooks return reactive state
+ * Validates: Requirements 11.1, 11.2, 11.3
+ *
+ * Tests that data hooks return reactive state with correct structure and behavior.
+ */
+
+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";
+
+// Mock the client module
+vi.mock("../client", () => ({
+	generateClient: vi.fn(() => ({
+		models: {
+			Brand: {
+				list: vi.fn().mockResolvedValue({ data: [], errors: null }),
+			},
+			Account: {
+				list: vi.fn().mockResolvedValue({ data: [], errors: null }),
+			},
+			User: {
+				list: vi.fn().mockResolvedValue({ data: [], errors: null }),
+			},
+			Product: {
+				list: vi.fn().mockResolvedValue({ data: [], errors: null }),
+			},
+		},
+	})),
+}));
+
+describe("Data Hooks - Property 5: Data hooks return reactive state", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	/**
+	 * Property: For any data hook, calling it should return reactive refs
+	 * for data, loading, error, and a refetch function
+	 */
+	it("useBrands returns reactive state structure", () => {
+		fc.assert(
+			fc.property(
+				fc.record({
+					autoFetch: fc.boolean(),
+					limit: fc.option(fc.integer({ min: 1, max: 100 }), { nil: undefined }),
+				}),
+				(options) => {
+					const result = useBrands(options);
+
+					// Check that all required properties exist
+					expect(result).toHaveProperty("brands");
+					expect(result).toHaveProperty("activeBrands");
+					expect(result).toHaveProperty("loading");
+					expect(result).toHaveProperty("error");
+					expect(result).toHaveProperty("refetch");
+
+					// Check that data properties are reactive refs
+					expect(isRef(result.brands)).toBe(true);
+					expect(isRef(result.loading)).toBe(true);
+					expect(isRef(result.error)).toBe(true);
+
+					// Check that activeBrands is a computed ref
+					expect(isRef(result.activeBrands)).toBe(true);
+
+					// Check that refetch is a function
+					expect(typeof result.refetch).toBe("function");
+
+					// Check initial state values
+					expect(Array.isArray(result.brands.value)).toBe(true);
+					expect(typeof result.loading.value).toBe("boolean");
+					expect(result.error.value === null || result.error.value instanceof Error).toBe(true);
+				},
+			),
+			{ numRuns: 100 },
+		);
+	});
+
+	it("useAccounts returns reactive state structure", () => {
+		fc.assert(
+			fc.property(
+				fc.record({
+					autoFetch: fc.boolean(),
+					limit: fc.option(fc.integer({ min: 1, max: 100 }), { nil: undefined }),
+				}),
+				(options) => {
+					const result = useAccounts(options);
+
+					// Check that all required properties exist
+					expect(result).toHaveProperty("accounts");
+					expect(result).toHaveProperty("loading");
+					expect(result).toHaveProperty("error");
+					expect(result).toHaveProperty("refetch");
+
+					// Check that data properties are reactive refs
+					expect(isRef(result.accounts)).toBe(true);
+					expect(isRef(result.loading)).toBe(true);
+					expect(isRef(result.error)).toBe(true);
+
+					// Check that refetch is a function
+					expect(typeof result.refetch).toBe("function");
+
+					// Check initial state values
+					expect(Array.isArray(result.accounts.value)).toBe(true);
+					expect(typeof result.loading.value).toBe("boolean");
+					expect(result.error.value === null || result.error.value instanceof Error).toBe(true);
+				},
+			),
+			{ numRuns: 100 },
+		);
+	});
+
+	it("useUsers returns reactive state structure", () => {
+		fc.assert(
+			fc.property(
+				fc.record({
+					autoFetch: fc.boolean(),
+					limit: fc.option(fc.integer({ min: 1, max: 100 }), { nil: undefined }),
+				}),
+				(options) => {
+					const result = useUsers(options);
+
+					// Check that all required properties exist
+					expect(result).toHaveProperty("users");
+					expect(result).toHaveProperty("loading");
+					expect(result).toHaveProperty("error");
+					expect(result).toHaveProperty("refetch");
+
+					// Check that data properties are reactive refs
+					expect(isRef(result.users)).toBe(true);
+					expect(isRef(result.loading)).toBe(true);
+					expect(isRef(result.error)).toBe(true);
+
+					// Check that refetch is a function
+					expect(typeof result.refetch).toBe("function");
+
+					// Check initial state values
+					expect(Array.isArray(result.users.value)).toBe(true);
+					expect(typeof result.loading.value).toBe("boolean");
+					expect(result.error.value === null || result.error.value instanceof Error).toBe(true);
+				},
+			),
+			{ numRuns: 100 },
+		);
+	});
+
+	it("useProducts returns reactive state structure", () => {
+		fc.assert(
+			fc.property(
+				fc.record({
+					autoFetch: fc.boolean(),
+					limit: fc.option(fc.integer({ min: 1, max: 100 }), { nil: undefined }),
+				}),
+				(options) => {
+					const result = useProducts(options);
+
+					// Check that all required properties exist
+					expect(result).toHaveProperty("products");
+					expect(result).toHaveProperty("activeProducts");
+					expect(result).toHaveProperty("loading");
+					expect(result).toHaveProperty("error");
+					expect(result).toHaveProperty("refetch");
+
+					// Check that data properties are reactive refs
+					expect(isRef(result.products)).toBe(true);
+					expect(isRef(result.loading)).toBe(true);
+					expect(isRef(result.error)).toBe(true);
+
+					// Check that activeProducts is a computed ref
+					expect(isRef(result.activeProducts)).toBe(true);
+
+					// Check that refetch is a function
+					expect(typeof result.refetch).toBe("function");
+
+					// Check initial state values
+					expect(Array.isArray(result.products.value)).toBe(true);
+					expect(typeof result.loading.value).toBe("boolean");
+					expect(result.error.value === null || result.error.value instanceof Error).toBe(true);
+				},
+			),
+			{ numRuns: 100 },
+		);
+	});
+});

package/src/hooks/hooks.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Data Hooks Tests
+ *
+ * Basic smoke tests to verify hooks can be imported and have correct structure.
+ */
+
+import { describe, it, expect } from "vitest";
+import { useBrands, useAccounts, useUsers, useProducts } from "./index";
+
+describe("Data Hooks", () => {
+	describe("useBrands", () => {
+		it("should be a function", () => {
+			expect(typeof useBrands).toBe("function");
+		});
+
+		it("should return expected properties", () => {
+			const result = useBrands({ autoFetch: false });
+
+			expect(result).toHaveProperty("brands");
+			expect(result).toHaveProperty("activeBrands");
+			expect(result).toHaveProperty("loading");
+			expect(result).toHaveProperty("error");
+			expect(result).toHaveProperty("refetch");
+			expect(typeof result.refetch).toBe("function");
+		});
+	});
+
+	describe("useAccounts", () => {
+		it("should be a function", () => {
+			expect(typeof useAccounts).toBe("function");
+		});
+
+		it("should return expected properties", () => {
+			const result = useAccounts({ autoFetch: false });
+
+			expect(result).toHaveProperty("accounts");
+			expect(result).toHaveProperty("loading");
+			expect(result).toHaveProperty("error");
+			expect(result).toHaveProperty("refetch");
+			expect(typeof result.refetch).toBe("function");
+		});
+	});
+
+	describe("useUsers", () => {
+		it("should be a function", () => {
+			expect(typeof useUsers).toBe("function");
+		});
+
+		it("should return expected properties", () => {
+			const result = useUsers({ autoFetch: false });
+
+			expect(result).toHaveProperty("users");
+			expect(result).toHaveProperty("loading");
+			expect(result).toHaveProperty("error");
+			expect(result).toHaveProperty("refetch");
+			expect(typeof result.refetch).toBe("function");
+		});
+	});
+
+	describe("useProducts", () => {
+		it("should be a function", () => {
+			expect(typeof useProducts).toBe("function");
+		});
+
+		it("should return expected properties", () => {
+			const result = useProducts({ autoFetch: false });
+
+			expect(result).toHaveProperty("products");
+			expect(result).toHaveProperty("activeProducts");
+			expect(result).toHaveProperty("loading");
+			expect(result).toHaveProperty("error");
+			expect(result).toHaveProperty("refetch");
+			expect(typeof result.refetch).toBe("function");
+		});
+	});
+});

package/src/hooks/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Data Hooks for @htlkg/data
+ *
+ * Vue composables for fetching and managing data with reactive state.
+ */
+
+// Hook factory for creating custom data hooks
+export {
+	createDataHook,
+	resetClientInstance,
+	type CreateDataHookOptions,
+	type BaseHookOptions,
+	type DataHookReturn,
+	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";

package/src/hooks/useAccounts.ts

@@ -0,0 +1,66 @@
+/**
+ * useAccounts Hook
+ *
+ * Vue composable for fetching and managing account data with reactive state.
+ * Provides loading states, error handling, and refetch capabilities.
+ */
+
+import type { Ref } from "vue";
+import type { Account } from "@htlkg/core/types";
+import { createDataHook, type BaseHookOptions } from "./createDataHook";
+
+export interface UseAccountsOptions extends BaseHookOptions {
+	/** Filter criteria for accounts */
+	filter?: any;
+	/** Limit number of results */
+	limit?: number;
+	/** Auto-fetch on mount (default: true) */
+	autoFetch?: boolean;
+}
+
+export interface UseAccountsReturn {
+	/** Reactive array of accounts */
+	accounts: Ref<Account[]>;
+	/** Loading state */
+	loading: Ref<boolean>;
+	/** Error state */
+	error: Ref<Error | null>;
+	/** Refetch accounts */
+	refetch: () => Promise<void>;
+}
+
+/**
+ * Internal hook created by factory
+ */
+const useAccountsInternal = createDataHook<Account, UseAccountsOptions>({
+	model: "Account",
+	dataPropertyName: "accounts",
+});
+
+/**
+ * Composable for fetching and managing accounts
+ *
+ * @example
+ * ```typescript
+ * import { useAccounts } from '@htlkg/data/hooks';
+ *
+ * const { accounts, loading, error, refetch } = useAccounts();
+ * ```
+ *
+ * @example With filters
+ * ```typescript
+ * const { accounts, loading } = useAccounts({
+ *   filter: { status: { eq: 'active' } },
+ *   limit: 50
+ * });
+ * ```
+ */
+export function useAccounts(options: UseAccountsOptions = {}): UseAccountsReturn {
+	const result = useAccountsInternal(options);
+	return {
+		accounts: result.accounts as Ref<Account[]>,
+		loading: result.loading,
+		error: result.error,
+		refetch: result.refetch,
+	};
+}

package/src/hooks/useBrands.ts

@@ -0,0 +1,95 @@
+/**
+ * useBrands Hook
+ *
+ * Vue composable for fetching and managing brand data with reactive state.
+ * Provides loading states, error handling, and refetch capabilities.
+ */
+
+import type { Ref, ComputedRef } from "vue";
+import type { Brand } from "@htlkg/core/types";
+import { createDataHook, type BaseHookOptions } from "./createDataHook";
+
+export interface UseBrandsOptions extends BaseHookOptions {
+	/** Filter criteria for brands */
+	filter?: any;
+	/** Limit number of results */
+	limit?: number;
+	/** Auto-fetch on mount (default: true) */
+	autoFetch?: boolean;
+	/** Filter by account ID */
+	accountId?: string;
+	/** Only active brands */
+	activeOnly?: boolean;
+}
+
+export interface UseBrandsReturn {
+	/** Reactive array of brands */
+	brands: Ref<Brand[]>;
+	/** Computed array of active brands only */
+	activeBrands: ComputedRef<Brand[]>;
+	/** Loading state */
+	loading: Ref<boolean>;
+	/** Error state */
+	error: Ref<Error | null>;
+	/** Refetch brands */
+	refetch: () => Promise<void>;
+}
+
+/**
+ * Build filter from hook options
+ */
+function buildFilter(options: UseBrandsOptions): any {
+	let filter: any = options.filter || {};
+
+	if (options.accountId) {
+		filter = { ...filter, accountId: { eq: options.accountId } };
+	}
+
+	if (options.activeOnly) {
+		filter = { ...filter, status: { eq: "active" } };
+	}
+
+	return Object.keys(filter).length > 0 ? filter : undefined;
+}
+
+/**
+ * Internal hook created by factory
+ */
+const useBrandsInternal = createDataHook<Brand, UseBrandsOptions, { activeBrands: Brand[] }>({
+	model: "Brand",
+	dataPropertyName: "brands",
+	buildFilter,
+	computedProperties: {
+		activeBrands: (brands) => brands.filter((b) => b.status === "active"),
+	},
+});
+
+/**
+ * Composable for fetching and managing brands
+ *
+ * @example
+ * ```typescript
+ * import { useBrands } from '@htlkg/data/hooks';
+ *
+ * const { brands, loading, error, refetch } = useBrands();
+ * ```
+ *
+ * @example With filters
+ * ```typescript
+ * const { brands, loading } = useBrands({
+ *   accountId: 'account-123',
+ *   activeOnly: true,
+ *   limit: 50
+ * });
+ * ```
+ */
+export function useBrands(options: UseBrandsOptions = {}): UseBrandsReturn {
+	const result = useBrandsInternal(options);
+	return {
+		brands: result.brands as Ref<Brand[]>,
+		activeBrands: result.activeBrands as ComputedRef<Brand[]>,
+		loading: result.loading,
+		error: result.error,
+		refetch: result.refetch,
+	};
+}

package/src/hooks/useProducts.ts

@@ -0,0 +1,88 @@
+/**
+ * useProducts Hook
+ *
+ * Vue composable for fetching and managing product data with reactive state.
+ * Provides loading states, error handling, and refetch capabilities.
+ */
+
+import type { Ref, ComputedRef } from "vue";
+import type { Product } from "@htlkg/core/types";
+import { createDataHook, type BaseHookOptions } from "./createDataHook";
+
+export interface UseProductsOptions extends BaseHookOptions {
+	/** Filter criteria for products */
+	filter?: any;
+	/** Limit number of results */
+	limit?: number;
+	/** Auto-fetch on mount (default: true) */
+	autoFetch?: boolean;
+	/** Only active products */
+	activeOnly?: boolean;
+}
+
+export interface UseProductsReturn {
+	/** Reactive array of products */
+	products: Ref<Product[]>;
+	/** Computed array of active products only */
+	activeProducts: ComputedRef<Product[]>;
+	/** Loading state */
+	loading: Ref<boolean>;
+	/** Error state */
+	error: Ref<Error | null>;
+	/** Refetch products */
+	refetch: () => Promise<void>;
+}
+
+/**
+ * Build filter from hook options
+ */
+function buildFilter(options: UseProductsOptions): any {
+	let filter: any = options.filter || {};
+
+	if (options.activeOnly) {
+		filter = { ...filter, isActive: { eq: true } };
+	}
+
+	return Object.keys(filter).length > 0 ? filter : undefined;
+}
+
+/**
+ * Internal hook created by factory
+ */
+const useProductsInternal = createDataHook<Product, UseProductsOptions, { activeProducts: Product[] }>({
+	model: "Product",
+	dataPropertyName: "products",
+	buildFilter,
+	computedProperties: {
+		activeProducts: (products) => products.filter((p) => p.isActive === true),
+	},
+});
+
+/**
+ * Composable for fetching and managing products
+ *
+ * @example
+ * ```typescript
+ * import { useProducts } from '@htlkg/data/hooks';
+ *
+ * const { products, loading, error, refetch } = useProducts();
+ * ```
+ *
+ * @example With filters
+ * ```typescript
+ * const { products, loading } = useProducts({
+ *   activeOnly: true,
+ *   limit: 50
+ * });
+ * ```
+ */
+export function useProducts(options: UseProductsOptions = {}): UseProductsReturn {
+	const result = useProductsInternal(options);
+	return {
+		products: result.products as Ref<Product[]>,
+		activeProducts: result.activeProducts as ComputedRef<Product[]>,
+		loading: result.loading,
+		error: result.error,
+		refetch: result.refetch,
+	};
+}

package/src/hooks/useUsers.ts

@@ -0,0 +1,89 @@
+/**
+ * useUsers Hook
+ *
+ * Vue composable for fetching and managing user data with reactive state.
+ * Provides loading states, error handling, and refetch capabilities.
+ */
+
+import type { Ref } from "vue";
+import type { User } from "@htlkg/core/types";
+import { createDataHook, type BaseHookOptions } from "./createDataHook";
+
+export interface UseUsersOptions extends BaseHookOptions {
+	/** Filter criteria for users */
+	filter?: any;
+	/** Limit number of results */
+	limit?: number;
+	/** Auto-fetch on mount (default: true) */
+	autoFetch?: boolean;
+	/** Filter by brand ID */
+	brandId?: string;
+	/** Filter by account ID */
+	accountId?: string;
+}
+
+export interface UseUsersReturn {
+	/** Reactive array of users */
+	users: Ref<User[]>;
+	/** Loading state */
+	loading: Ref<boolean>;
+	/** Error state */
+	error: Ref<Error | null>;
+	/** Refetch users */
+	refetch: () => Promise<void>;
+}
+
+/**
+ * Build filter from hook options
+ */
+function buildFilter(options: UseUsersOptions): any {
+	let filter: any = options.filter || {};
+
+	if (options.brandId) {
+		filter = { ...filter, brandIds: { contains: options.brandId } };
+	}
+
+	if (options.accountId) {
+		filter = { ...filter, accountIds: { contains: options.accountId } };
+	}
+
+	return Object.keys(filter).length > 0 ? filter : undefined;
+}
+
+/**
+ * Internal hook created by factory
+ */
+const useUsersInternal = createDataHook<User, UseUsersOptions>({
+	model: "User",
+	dataPropertyName: "users",
+	buildFilter,
+});
+
+/**
+ * Composable for fetching and managing users
+ *
+ * @example
+ * ```typescript
+ * import { useUsers } from '@htlkg/data/hooks';
+ *
+ * const { users, loading, error, refetch } = useUsers();
+ * ```
+ *
+ * @example With filters
+ * ```typescript
+ * const { users, loading } = useUsers({
+ *   brandId: 'brand-123',
+ *   accountId: 'account-456',
+ *   limit: 50
+ * });
+ * ```
+ */
+export function useUsers(options: UseUsersOptions = {}): UseUsersReturn {
+	const result = useUsersInternal(options);
+	return {
+		users: result.users as Ref<User[]>,
+		loading: result.loading,
+		error: result.error,
+		refetch: result.refetch,
+	};
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @htlkg/data - Data Layer Module
+ *
+ * Provides GraphQL operations, Amplify integration, and reactive data hooks
+ * for the Hotelinking multi-tenant SaaS platform.
+ *
+ * @module @htlkg/data
+ */
+
+// Client exports
+export {
+	generateClient,
+	generateServerClient,
+	getSharedClient,
+	resetSharedClient,
+	type AstroAmplifyConfig,
+} from "./client";
+
+// Query exports
+export * from "./queries";
+
+// Mutation exports
+export * from "./mutations";
+
+// Hook exports
+export * from "./hooks";
+
+// Store factory exports
+export * from "./stores";
+
+// Content Collections exports (will be populated in task 3.8)
+// export * from "./content-collections";