Merge pull request #415 from objectstack-ai/copilot/add-type-safe-queries

Author: hotlong

examples/msw-react-crud/README.md

@@ -159,6 +159,91 @@ pnpm dev
 
 Open `http://localhost:3000`. You can now create, edit, and delete tasks. The data persists in the browser memory as long as you don't refresh (simulate persistence by seeding data in step 2).
 
+## ⚛️ React Hooks (NEW!)
+
+This example now includes **two different approaches** for using ObjectStack in React:
+
+### 1. Traditional Approach (`App.tsx`)
+Direct client usage with manual state management:
+
+```tsx
+const [tasks, setTasks] = useState([]);
+const [loading, setLoading] = useState(true);
+
+useEffect(() => {
+  loadTasks();
+}, []);
+
+async function loadTasks() {
+  setLoading(true);
+  const result = await client.data.find('todo_task');
+  setTasks(result.value);
+  setLoading(false);
+}
+```
+
+### 2. React Hooks Approach (`AppWithHooks.tsx`)
+Declarative data fetching with `@objectstack/client-react`:
+
+```tsx
+import { usePagination, useMutation } from '@objectstack/client-react';
+
+function TaskList() {
+  const {
+    data,
+    isLoading,
+    page,
+    nextPage,
+    previousPage
+  } = usePagination<Task>('todo_task', {
+    pageSize: 10,
+    sort: ['priority', '-created_at']
+  });
+
+  const { mutate: deleteTask } = useMutation('todo_task', 'delete', {
+    onSuccess: () => refetch()
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  
+  return (
+    <div>
+      {data?.value.map(task => <TaskItem task={task} />)}
+      <button onClick={previousPage}>Previous</button>
+      <button onClick={nextPage}>Next</button>
+    </div>
+  );
+}
+```
+
+### Switching Between Approaches
+
+Edit `src/main.tsx` and change the `useHooks` flag:
+
+```typescript
+const useHooks = false; // Set to true to use React hooks
+```
+
+### Available Hooks
+
+From `@objectstack/client-react`:
+
+**Data Hooks:**
+- `useQuery` - Query data with automatic caching and refetching
+- `useMutation` - Create, update, or delete data
+- `usePagination` - Paginated data queries with navigation
+- `useInfiniteQuery` - Infinite scrolling / load more
+
+**Metadata Hooks:**
+- `useObject` - Fetch object schema/metadata
+- `useView` - Fetch view configuration
+- `useFields` - Get fields list
+- `useMetadata` - Generic metadata queries
+
+**Context:**
+- `ObjectStackProvider` - Context provider for ObjectStackClient
+- `useClient` - Access ObjectStackClient from context
+
 ## 📦 Migration to Production
 
 When you are ready to go to production:

examples/msw-react-crud/package.json

@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "@objectstack/client": "workspace:*",
+    "@objectstack/client-react": "workspace:*",
     "@objectstack/driver-memory": "workspace:*",
     "@objectstack/example-todo": "workspace:*",
     "@objectstack/plugin-msw": "workspace:*",

examples/msw-react-crud/src/AppWithHooks.tsx

@@ -0,0 +1,136 @@
+/**
+ * AppWithHooks Component
+ * 
+ * Demonstrates the new React hooks from @objectstack/client-react
+ * This is an alternative to App.tsx showing the hooks-based approach
+ */
+
+import { useState, useEffect } from 'react';
+import { ObjectStackClient } from '@objectstack/client';
+import type { Task } from './types';
+import { TaskFormWithHooks } from './components/TaskFormWithHooks';
+import { TaskListWithHooks } from './components/TaskListWithHooks';
+import './App.css';
+
+export function AppWithHooks() {
+  const [client, setClient] = useState<ObjectStackClient | null>(null);
+  const [editingTask, setEditingTask] = useState<Task | null>(null);
+  const [refreshTrigger, setRefreshTrigger] = useState(0);
+  const [connected, setConnected] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    initializeClient();
+  }, []);
+
+  async function initializeClient() {
+    try {
+      const stackClient = new ObjectStackClient({
+        baseUrl: ''
+      });
+
+      await stackClient.connect();
+      
+      setClient(stackClient);
+      setConnected(true);
+      console.log('✅ ObjectStack Client connected (via MSW)');
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to initialize client');
+      console.error('Failed to initialize client:', err);
+    }
+  }
+
+  function handleFormSuccess() {
+    setEditingTask(null);
+    setRefreshTrigger(prev => prev + 1);
+  }
+
+  function handleEditTask(task: Task) {
+    setEditingTask(task);
+    if (window.innerWidth < 1024) {
+      window.scrollTo({ top: 0, behavior: 'smooth' });
+    }
+  }
+
+  function handleCancelEdit() {
+    setEditingTask(null);
+  }
+
+  if (error) {
+    return (
+      <div className="min-h-screen flex items-center justify-center p-6">
+        <div className="max-w-md w-full p-8 border border-error-light bg-background rounded-lg shadow-sm text-center">
+          <h1 className="text-xl font-bold text-error mb-2">Connection Error</h1>
+          <p className="text-accents-5 mb-6">{error}</p>
+          <button 
+            onClick={initializeClient}
+            className="px-4 py-2 bg-foreground text-background rounded-md hover:bg-accents-7 transition-colors"
+          >
+            Retry
+          </button>
+        </div>
+      </div>
+    );
+  }
+
+  if (!connected || !client) {
+    return (
+      <div className="min-h-screen flex flex-col items-center justify-center p-6 space-y-4">
+        <div className="w-8 h-8 rounded-full border-4 border-accents-2 border-t-foreground animate-spin"></div>
+        <div className="text-center">
+          <h1 className="text-lg font-semibold mb-1">Connecting to ObjectStack...</h1>
+          <p className="text-accents-5 text-sm">Initializing MSW and ObjectStack Client...</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-6xl mx-auto px-6 py-12 min-h-screen font-sans">
+      <header className="text-center mb-16">
+        <h1 className="text-4xl font-extrabold tracking-tight mb-4 text-foreground">
+          ObjectStack React Hooks
+        </h1>
+        <p className="text-accents-5 text-lg mb-6">
+          Using <code className="text-sm bg-accents-1 px-1.5 py-0.5 rounded font-mono text-accents-6">@objectstack/client-react</code> hooks with Mock Service Worker
+        </p>
+        <div className="inline-flex items-center gap-2 px-3 py-1 rounded-full bg-success-lighter border border-success-lighter text-success-dark text-sm font-medium">
+          <span className="relative flex h-2 w-2">
+            <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-success opacity-75"></span>
+            <span className="relative inline-flex rounded-full h-2 w-2 bg-success"></span>
+          </span>
+          React Hooks - Type-safe & Declarative
+        </div>
+      </header>
+
+      <main className="grid grid-cols-1 lg:grid-cols-12 gap-12 text-sm">
+        <section className="lg:col-span-4 lg:sticky lg:top-6 lg:self-start">
+          <TaskFormWithHooks
+            client={client}
+            editingTask={editingTask}
+            onSuccess={handleFormSuccess}
+            onCancel={handleCancelEdit}
+          />
+        </section>
+
+        <section className="lg:col-span-8">
+          <TaskListWithHooks
+            client={client}
+            onEdit={handleEditTask}
+            key={refreshTrigger}
+          />
+        </section>
+      </main>
+
+      <footer className="mt-16 pt-8 border-t border-accents-2 text-center text-sm text-accents-4 space-y-2">
+        <p>
+          This example demonstrates the new React hooks from @objectstack/client-react.
+          Features: useQuery, useMutation, usePagination with type safety.
+        </p>
+        <p className="font-mono text-xs text-accents-3">
+          React Hooks + TypeScript + Vite + MSW + @objectstack/client-react
+        </p>
+      </footer>
+    </div>
+  );
+}