@demokit-ai/tanstack-query 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,238 @@
+# @demokit-ai/tanstack-query
+
+![Tests](https://img.shields.io/badge/tests-28%20passing-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-6%25-red)
+
+TanStack Query v5 adapter for DemoKit - mock queries and mutations for demo mode.
+
+## Installation
+
+```bash
+npm install @demokit-ai/tanstack-query @demokit-ai/core @demokit-ai/react @tanstack/react-query
+```
+
+## Features
+
+- **Demo Query Client** - Intercept queries and return fixtures
+- **Mutation Mocking** - Mock mutation operations in demo mode
+- **Key Matching** - Pattern-based query key matching
+- **Provider Pattern** - Centralized fixture management
+- **Optimistic Updates** - Demo-aware optimistic update handling
+- Full TypeScript support
+
+## Usage
+
+### Demo Query Client
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { createDemoQueryClient } from '@demokit-ai/tanstack-query'
+
+const queryClient = createDemoQueryClient({
+  isEnabled: () => localStorage.getItem('demoMode') === 'true',
+  fixtures: {
+    users: [
+      { id: '1', name: 'Demo User' },
+      { id: '2', name: 'Another User' },
+    ],
+    'users/:id': ({ params }) => ({
+      id: params.id,
+      name: 'Demo User',
+      email: 'demo@example.com',
+    }),
+  },
+})
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+    </QueryClientProvider>
+  )
+}
+```
+
+### Using with useQuery
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function UserList() {
+  const { data, isLoading } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => fetch('/api/users').then((r) => r.json()),
+  })
+
+  // In demo mode, returns fixtures automatically
+  if (isLoading) return <div>Loading...</div>
+  return <ul>{data?.map((u) => <li key={u.id}>{u.name}</li>)}</ul>
+}
+```
+
+### Provider Pattern
+
+```tsx
+import { DemoQueryProvider, useDemoQuery } from '@demokit-ai/tanstack-query'
+
+const fixtures = {
+  users: [{ id: '1', name: 'Demo User' }],
+  products: [{ id: '1', name: 'Demo Product', price: 99.99 }],
+}
+
+function App() {
+  return (
+    <DemoQueryProvider fixtures={fixtures} enabled>
+      <YourApp />
+      <DemoControls />
+    </DemoQueryProvider>
+  )
+}
+
+function DemoControls() {
+  const { enabled, toggle, setFixture } = useDemoQuery()
+
+  return (
+    <div>
+      <button onClick={toggle}>Demo: {enabled ? 'ON' : 'OFF'}</button>
+      <button onClick={() => setFixture('custom', { custom: true })}>
+        Add Custom Fixture
+      </button>
+    </div>
+  )
+}
+```
+
+### Mutation Mocking
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { createDemoMutation } from '@demokit-ai/tanstack-query'
+
+function CreateUser() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: createDemoMutation({
+      mutationFn: (data) =>
+        fetch('/api/users', {
+          method: 'POST',
+          body: JSON.stringify(data),
+        }).then((r) => r.json()),
+      isEnabled: () => true,
+      fixture: (variables) => ({
+        id: 'new-id',
+        ...variables,
+        created: true,
+      }),
+    }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    },
+  })
+
+  return (
+    <button
+      onClick={() => mutation.mutate({ name: 'New User' })}
+      disabled={mutation.isPending}
+    >
+      Create User
+    </button>
+  )
+}
+```
+
+### Dynamic Fixtures
+
+```tsx
+const fixtures = {
+  // Static fixture
+  config: { version: '1.0', features: ['demo'] },
+
+  // Dynamic fixture based on query key
+  'users/:id': ({ params }) => ({
+    id: params.id,
+    name: `User ${params.id}`,
+    email: `user${params.id}@example.com`,
+  }),
+
+  // Function fixture with full context
+  search: ({ queryKey }) => {
+    const [, { query }] = queryKey
+    return [
+      { id: '1', title: `Result for: ${query}` },
+    ]
+  },
+}
+```
+
+### Query Key Matching
+
+```tsx
+const fixtures = {
+  // Exact match
+  users: [...],
+
+  // Parameter matching
+  'users/:id': ({ params }) => ({ id: params.id }),
+
+  // Nested keys (arrays)
+  'users/:id/orders': ({ params }) => [
+    { id: '1', userId: params.id, total: 99.99 },
+  ],
+
+  // Wildcard matching
+  'users/*': ({ queryKey }) => ({
+    path: queryKey.join('/'),
+  }),
+}
+```
+
+## API Reference
+
+### `createDemoQueryClient(options)`
+
+Create a demo-aware QueryClient.
+
+Options:
+- `isEnabled` - Function to check if demo mode is enabled
+- `fixtures` - Fixture definitions by query key pattern
+- `delay` - Simulated delay in milliseconds
+- `defaultOptions` - Default QueryClient options
+
+### `DemoQueryProvider`
+
+Props:
+- `fixtures` - Fixture definitions
+- `enabled` - Whether demo mode is enabled
+- `delay` - Simulated delay in milliseconds
+- `children` - React children
+
+### `useDemoQuery()`
+
+Returns:
+- `enabled` - Whether demo mode is enabled
+- `toggle()` - Toggle demo mode
+- `fixtures` - Current fixtures
+- `setFixture(key, fixture)` - Set a fixture
+- `removeFixture(key)` - Remove a fixture
+- `clearFixtures()` - Clear all fixtures
+
+### `createDemoMutation(options)`
+
+Create a demo-aware mutation function.
+
+Options:
+- `mutationFn` - The real mutation function
+- `isEnabled` - Function to check if demo mode is enabled
+- `fixture` - Mutation fixture (static or function)
+- `delay` - Simulated delay in milliseconds
+
+### `createQueryKeyMatcher(fixtures)`
+
+Create a matcher function for query keys.
+
+Returns a function that takes a query key and returns the matching fixture.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demokit-ai/tanstack-query",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TanStack Query v5 adapter for DemoKit - mock queries and mutations",
   "type": "module",
   "main": "./dist/index.cjs",