@objectstack/client-react 0.6.1

package/dist/data-hooks.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Data Query Hooks
+ *
+ * React hooks for querying and mutating ObjectStack data
+ */
+import { QueryAST, FilterCondition } from '@objectstack/spec/data';
+import { PaginatedResult } from '@objectstack/client';
+/**
+ * Query options for useQuery hook
+ */
+export interface UseQueryOptions<T = any> {
+    /** Query AST or simplified query options */
+    query?: Partial<QueryAST>;
+    /** Simple field selection */
+    select?: string[];
+    /** Simple filters */
+    filters?: FilterCondition;
+    /** Sort configuration */
+    sort?: string | string[];
+    /** Limit results */
+    top?: number;
+    /** Skip results (for pagination) */
+    skip?: number;
+    /** Enable/disable automatic query execution */
+    enabled?: boolean;
+    /** Refetch interval in milliseconds */
+    refetchInterval?: number;
+    /** Callback on successful query */
+    onSuccess?: (data: PaginatedResult<T>) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+/**
+ * Query result for useQuery hook
+ */
+export interface UseQueryResult<T = any> {
+    /** Query result data */
+    data: PaginatedResult<T> | null;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Refetch the query */
+    refetch: () => Promise<void>;
+    /** Is currently refetching */
+    isRefetching: boolean;
+}
+/**
+ * Hook for querying ObjectStack data with automatic caching and refetching
+ *
+ * @example
+ * ```tsx
+ * function TaskList() {
+ *   const { data, isLoading, error, refetch } = useQuery('todo_task', {
+ *     select: ['id', 'subject', 'priority'],
+ *     sort: ['-created_at'],
+ *     top: 20
+ *   });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {data?.value.map(task => (
+ *         <div key={task.id}>{task.subject}</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useQuery<T = any>(object: string, options?: UseQueryOptions<T>): UseQueryResult<T>;
+/**
+ * Mutation options for useMutation hook
+ */
+export interface UseMutationOptions<TData = any, TVariables = any> {
+    /** Callback on successful mutation */
+    onSuccess?: (data: TData, variables: TVariables) => void;
+    /** Callback on error */
+    onError?: (error: Error, variables: TVariables) => void;
+    /** Callback when mutation is settled (success or error) */
+    onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables) => void;
+}
+/**
+ * Mutation result for useMutation hook
+ */
+export interface UseMutationResult<TData = any, TVariables = any> {
+    /** Execute the mutation */
+    mutate: (variables: TVariables) => Promise<TData>;
+    /** Async version of mutate that throws errors */
+    mutateAsync: (variables: TVariables) => Promise<TData>;
+    /** Mutation result data */
+    data: TData | null;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Reset mutation state */
+    reset: () => void;
+}
+/**
+ * Hook for creating, updating, or deleting ObjectStack data
+ *
+ * @example
+ * ```tsx
+ * function CreateTaskForm() {
+ *   const { mutate, isLoading, error } = useMutation('todo_task', 'create', {
+ *     onSuccess: (data) => {
+ *       console.log('Task created:', data);
+ *     }
+ *   });
+ *
+ *   const handleSubmit = (formData) => {
+ *     mutate(formData);
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ */
+export declare function useMutation<TData = any, TVariables = any>(object: string, operation: 'create' | 'update' | 'delete' | 'createMany' | 'updateMany' | 'deleteMany', options?: UseMutationOptions<TData, TVariables>): UseMutationResult<TData, TVariables>;
+/**
+ * Pagination options for usePagination hook
+ */
+export interface UsePaginationOptions<T = any> extends Omit<UseQueryOptions<T>, 'top' | 'skip'> {
+    /** Page size */
+    pageSize?: number;
+    /** Initial page (1-based) */
+    initialPage?: number;
+}
+/**
+ * Pagination result for usePagination hook
+ */
+export interface UsePaginationResult<T = any> extends UseQueryResult<T> {
+    /** Current page (1-based) */
+    page: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Total number of records */
+    totalCount: number;
+    /** Go to next page */
+    nextPage: () => void;
+    /** Go to previous page */
+    previousPage: () => void;
+    /** Go to specific page */
+    goToPage: (page: number) => void;
+    /** Whether there is a next page */
+    hasNextPage: boolean;
+    /** Whether there is a previous page */
+    hasPreviousPage: boolean;
+}
+/**
+ * Hook for paginated data queries
+ *
+ * @example
+ * ```tsx
+ * function PaginatedTaskList() {
+ *   const {
+ *     data,
+ *     isLoading,
+ *     page,
+ *     totalPages,
+ *     nextPage,
+ *     previousPage,
+ *     hasNextPage,
+ *     hasPreviousPage
+ *   } = usePagination('todo_task', {
+ *     pageSize: 10,
+ *     sort: ['-created_at']
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {data?.value.map(task => <div key={task.id}>{task.subject}</div>)}
+ *       <button onClick={previousPage} disabled={!hasPreviousPage}>Previous</button>
+ *       <span>Page {page} of {totalPages}</span>
+ *       <button onClick={nextPage} disabled={!hasNextPage}>Next</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePagination<T = any>(object: string, options?: UsePaginationOptions<T>): UsePaginationResult<T>;
+/**
+ * Infinite query options for useInfiniteQuery hook
+ */
+export interface UseInfiniteQueryOptions<T = any> extends Omit<UseQueryOptions<T>, 'skip'> {
+    /** Page size for each fetch */
+    pageSize?: number;
+    /** Get next page parameter */
+    getNextPageParam?: (lastPage: PaginatedResult<T>, allPages: PaginatedResult<T>[]) => number | undefined;
+}
+/**
+ * Infinite query result for useInfiniteQuery hook
+ */
+export interface UseInfiniteQueryResult<T = any> {
+    /** All pages of data */
+    data: PaginatedResult<T>[];
+    /** Flattened data from all pages */
+    flatData: T[];
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Load the next page */
+    fetchNextPage: () => Promise<void>;
+    /** Whether there are more pages */
+    hasNextPage: boolean;
+    /** Is currently fetching next page */
+    isFetchingNextPage: boolean;
+    /** Refetch all pages */
+    refetch: () => Promise<void>;
+}
+/**
+ * Hook for infinite scrolling / load more functionality
+ *
+ * @example
+ * ```tsx
+ * function InfiniteTaskList() {
+ *   const {
+ *     flatData,
+ *     isLoading,
+ *     fetchNextPage,
+ *     hasNextPage,
+ *     isFetchingNextPage
+ *   } = useInfiniteQuery('todo_task', {
+ *     pageSize: 20,
+ *     sort: ['-created_at']
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {flatData.map(task => <div key={task.id}>{task.subject}</div>)}
+ *       {hasNextPage && (
+ *         <button onClick={fetchNextPage} disabled={isFetchingNextPage}>
+ *           {isFetchingNextPage ? 'Loading...' : 'Load More'}
+ *         </button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useInfiniteQuery<T = any>(object: string, options?: UseInfiniteQueryOptions<T>): UseInfiniteQueryResult<T>;
+//# sourceMappingURL=data-hooks.d.ts.map

package/dist/data-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-hooks.d.ts","sourceRoot":"","sources":["../src/data-hooks.tsx"],"names":[],"mappings":"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"}

package/dist/data-hooks.js

@@ -0,0 +1,398 @@
+"use strict";
+/**
+ * Data Query Hooks
+ *
+ * React hooks for querying and mutating ObjectStack data
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useQuery = useQuery;
+exports.useMutation = useMutation;
+exports.usePagination = usePagination;
+exports.useInfiniteQuery = useInfiniteQuery;
+const react_1 = require("react");
+const context_1 = require("./context");
+/**
+ * Hook for querying ObjectStack data with automatic caching and refetching
+ *
+ * @example
+ * ```tsx
+ * function TaskList() {
+ *   const { data, isLoading, error, refetch } = useQuery('todo_task', {
+ *     select: ['id', 'subject', 'priority'],
+ *     sort: ['-created_at'],
+ *     top: 20
+ *   });
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {data?.value.map(task => (
+ *         <div key={task.id}>{task.subject}</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function useQuery(object, options = {}) {
+    const client = (0, context_1.useClient)();
+    const [data, setData] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
+    const [isRefetching, setIsRefetching] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const intervalRef = (0, react_1.useRef)();
+    const { query, select, filters, sort, top, skip, enabled = true, refetchInterval, onSuccess, onError } = options;
+    const fetchData = (0, react_1.useCallback)(async (isRefetch = false) => {
+        if (!enabled)
+            return;
+        try {
+            if (isRefetch) {
+                setIsRefetching(true);
+            }
+            else {
+                setIsLoading(true);
+            }
+            setError(null);
+            let result;
+            if (query) {
+                // Use advanced query API
+                result = await client.data.query(object, query);
+            }
+            else {
+                // Use simplified find API
+                result = await client.data.find(object, {
+                    select,
+                    filters: filters,
+                    sort,
+                    top,
+                    skip
+                });
+            }
+            setData(result);
+            onSuccess?.(result);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error('Query failed');
+            setError(error);
+            onError?.(error);
+        }
+        finally {
+            setIsLoading(false);
+            setIsRefetching(false);
+        }
+    }, [client, object, query, select, filters, sort, top, skip, enabled, onSuccess, onError]);
+    // Initial fetch and dependency-based refetch
+    (0, react_1.useEffect)(() => {
+        fetchData();
+    }, [fetchData]);
+    // Setup refetch interval
+    (0, react_1.useEffect)(() => {
+        if (refetchInterval && enabled) {
+            intervalRef.current = setInterval(() => {
+                fetchData(true);
+            }, refetchInterval);
+            return () => {
+                if (intervalRef.current) {
+                    clearInterval(intervalRef.current);
+                }
+            };
+        }
+        return undefined;
+    }, [refetchInterval, enabled, fetchData]);
+    const refetch = (0, react_1.useCallback)(async () => {
+        await fetchData(true);
+    }, [fetchData]);
+    return {
+        data,
+        isLoading,
+        error,
+        refetch,
+        isRefetching
+    };
+}
+/**
+ * Hook for creating, updating, or deleting ObjectStack data
+ *
+ * @example
+ * ```tsx
+ * function CreateTaskForm() {
+ *   const { mutate, isLoading, error } = useMutation('todo_task', 'create', {
+ *     onSuccess: (data) => {
+ *       console.log('Task created:', data);
+ *     }
+ *   });
+ *
+ *   const handleSubmit = (formData) => {
+ *     mutate(formData);
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ */
+function useMutation(object, operation, options = {}) {
+    const client = (0, context_1.useClient)();
+    const [data, setData] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const { onSuccess, onError, onSettled } = options;
+    const mutateAsync = (0, react_1.useCallback)(async (variables) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            let result;
+            switch (operation) {
+                case 'create':
+                    result = await client.data.create(object, variables);
+                    break;
+                case 'update':
+                    // Expect variables to be { id: string, data: Partial<T> }
+                    const updateVars = variables;
+                    result = await client.data.update(object, updateVars.id, updateVars.data);
+                    break;
+                case 'delete':
+                    // Expect variables to be { id: string }
+                    const deleteVars = variables;
+                    result = await client.data.delete(object, deleteVars.id);
+                    break;
+                case 'createMany':
+                    // createMany returns an array, which may not match TData type
+                    result = await client.data.createMany(object, variables);
+                    break;
+                case 'updateMany':
+                    // Expect variables to be { records: Array<{ id: string, data: Partial<T> }> }
+                    const updateManyVars = variables;
+                    result = await client.data.updateMany(object, updateManyVars.records, updateManyVars.options);
+                    break;
+                case 'deleteMany':
+                    // Expect variables to be { ids: string[] }
+                    const deleteManyVars = variables;
+                    result = await client.data.deleteMany(object, deleteManyVars.ids, deleteManyVars.options);
+                    break;
+                default:
+                    throw new Error(`Unknown operation: ${operation}`);
+            }
+            setData(result);
+            onSuccess?.(result, variables);
+            onSettled?.(result, null, variables);
+            return result;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error('Mutation failed');
+            setError(error);
+            onError?.(error, variables);
+            onSettled?.(undefined, error, variables);
+            throw error;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, object, operation, onSuccess, onError, onSettled]);
+    const mutate = (0, react_1.useCallback)((variables) => {
+        return mutateAsync(variables).catch(() => {
+            // Swallow error for non-async version
+            // Error is still available in the error state
+            return null;
+        });
+    }, [mutateAsync]);
+    const reset = (0, react_1.useCallback)(() => {
+        setData(null);
+        setError(null);
+        setIsLoading(false);
+    }, []);
+    return {
+        mutate,
+        mutateAsync,
+        data,
+        isLoading,
+        error,
+        reset
+    };
+}
+/**
+ * Hook for paginated data queries
+ *
+ * @example
+ * ```tsx
+ * function PaginatedTaskList() {
+ *   const {
+ *     data,
+ *     isLoading,
+ *     page,
+ *     totalPages,
+ *     nextPage,
+ *     previousPage,
+ *     hasNextPage,
+ *     hasPreviousPage
+ *   } = usePagination('todo_task', {
+ *     pageSize: 10,
+ *     sort: ['-created_at']
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {data?.value.map(task => <div key={task.id}>{task.subject}</div>)}
+ *       <button onClick={previousPage} disabled={!hasPreviousPage}>Previous</button>
+ *       <span>Page {page} of {totalPages}</span>
+ *       <button onClick={nextPage} disabled={!hasNextPage}>Next</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function usePagination(object, options = {}) {
+    const { pageSize = 20, initialPage = 1, ...queryOptions } = options;
+    const [page, setPage] = (0, react_1.useState)(initialPage);
+    const queryResult = useQuery(object, {
+        ...queryOptions,
+        top: pageSize,
+        skip: (page - 1) * pageSize
+    });
+    const totalCount = queryResult.data?.count || 0;
+    const totalPages = Math.ceil(totalCount / pageSize);
+    const hasNextPage = page < totalPages;
+    const hasPreviousPage = page > 1;
+    const nextPage = (0, react_1.useCallback)(() => {
+        if (hasNextPage) {
+            setPage(p => p + 1);
+        }
+    }, [hasNextPage]);
+    const previousPage = (0, react_1.useCallback)(() => {
+        if (hasPreviousPage) {
+            setPage(p => p - 1);
+        }
+    }, [hasPreviousPage]);
+    const goToPage = (0, react_1.useCallback)((newPage) => {
+        const clampedPage = Math.max(1, Math.min(newPage, totalPages));
+        setPage(clampedPage);
+    }, [totalPages]);
+    return {
+        ...queryResult,
+        page,
+        totalPages,
+        totalCount,
+        nextPage,
+        previousPage,
+        goToPage,
+        hasNextPage,
+        hasPreviousPage
+    };
+}
+/**
+ * Hook for infinite scrolling / load more functionality
+ *
+ * @example
+ * ```tsx
+ * function InfiniteTaskList() {
+ *   const {
+ *     flatData,
+ *     isLoading,
+ *     fetchNextPage,
+ *     hasNextPage,
+ *     isFetchingNextPage
+ *   } = useInfiniteQuery('todo_task', {
+ *     pageSize: 20,
+ *     sort: ['-created_at']
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {flatData.map(task => <div key={task.id}>{task.subject}</div>)}
+ *       {hasNextPage && (
+ *         <button onClick={fetchNextPage} disabled={isFetchingNextPage}>
+ *           {isFetchingNextPage ? 'Loading...' : 'Load More'}
+ *         </button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+function useInfiniteQuery(object, options = {}) {
+    const client = (0, context_1.useClient)();
+    const { pageSize = 20, 
+    // getNextPageParam is reserved for future use
+    query, select, filters, sort, enabled = true, onSuccess, onError } = options;
+    const [pages, setPages] = (0, react_1.useState)([]);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
+    const [isFetchingNextPage, setIsFetchingNextPage] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [hasNextPage, setHasNextPage] = (0, react_1.useState)(true);
+    const fetchPage = (0, react_1.useCallback)(async (skip, isNextPage = false) => {
+        try {
+            if (isNextPage) {
+                setIsFetchingNextPage(true);
+            }
+            else {
+                setIsLoading(true);
+            }
+            setError(null);
+            let result;
+            if (query) {
+                result = await client.data.query(object, {
+                    ...query,
+                    limit: pageSize,
+                    offset: skip
+                });
+            }
+            else {
+                result = await client.data.find(object, {
+                    select,
+                    filters: filters,
+                    sort,
+                    top: pageSize,
+                    skip
+                });
+            }
+            if (isNextPage) {
+                setPages(prev => [...prev, result]);
+            }
+            else {
+                setPages([result]);
+            }
+            // Determine if there's a next page
+            const fetchedCount = result.value.length;
+            const hasMore = fetchedCount === pageSize;
+            setHasNextPage(hasMore);
+            onSuccess?.(result);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error('Query failed');
+            setError(error);
+            onError?.(error);
+        }
+        finally {
+            setIsLoading(false);
+            setIsFetchingNextPage(false);
+        }
+    }, [client, object, query, select, filters, sort, pageSize, onSuccess, onError]);
+    // Initial fetch
+    (0, react_1.useEffect)(() => {
+        if (enabled) {
+            fetchPage(0);
+        }
+    }, [enabled, fetchPage]);
+    const fetchNextPage = (0, react_1.useCallback)(async () => {
+        if (!hasNextPage || isFetchingNextPage)
+            return;
+        const nextSkip = pages.length * pageSize;
+        await fetchPage(nextSkip, true);
+    }, [hasNextPage, isFetchingNextPage, pages.length, pageSize, fetchPage]);
+    const refetch = (0, react_1.useCallback)(async () => {
+        setPages([]);
+        await fetchPage(0);
+    }, [fetchPage]);
+    const flatData = pages.flatMap(page => page.value);
+    return {
+        data: pages,
+        flatData,
+        isLoading,
+        error,
+        fetchNextPage,
+        hasNextPage,
+        isFetchingNextPage,
+        refetch
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @objectstack/client-react
+ *
+ * React hooks for ObjectStack Client SDK
+ *
+ * Provides type-safe React hooks for:
+ * - Data queries (useQuery, useMutation, usePagination, useInfiniteQuery)
+ * - Metadata access (useObject, useView, useFields, useMetadata)
+ * - Client context (ObjectStackProvider, useClient)
+ */
+export { ObjectStackProvider, ObjectStackContext, useClient, type ObjectStackProviderProps } from './context';
+export { useQuery, useMutation, usePagination, useInfiniteQuery, type UseQueryOptions, type UseQueryResult, type UseMutationOptions, type UseMutationResult, type UsePaginationOptions, type UsePaginationResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult } from './data-hooks';
+export { useObject, useView, useFields, useMetadata, type UseMetadataOptions, type UseMetadataResult } from './metadata-hooks';
+export { ObjectStackClient, type ClientConfig } from '@objectstack/client';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,SAAS,EACT,KAAK,wBAAwB,EAC9B,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC5B,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,SAAS,EACT,OAAO,EACP,SAAS,EACT,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC"}