@demokit-ai/trpc 0.0.2 → 0.2.0

package/README.md

@@ -0,0 +1,203 @@
+# @demokit-ai/trpc
+
+![Tests](https://img.shields.io/badge/tests-115%20passing-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-17%25-red)
+
+tRPC v11 type-safe adapter for DemoKit - mock procedures with full type inference.
+
+## Installation
+
+```bash
+npm install @demokit-ai/trpc @demokit-ai/core @trpc/client @trpc/server
+```
+
+## Features
+
+- Type-safe fixture definitions matching your tRPC router
+- Demo link for intercepting tRPC calls client-side
+- React hooks for managing tRPC demo state
+- Procedure-level fixture matching
+- Support for queries, mutations, and subscriptions
+- Full TypeScript support with inference
+
+## Usage
+
+### Define Fixtures
+
+Create type-safe fixtures for your tRPC procedures:
+
+```ts
+import { defineTRPCFixtures } from '@demokit-ai/trpc'
+import type { AppRouter } from './router'
+
+export const fixtures = defineTRPCFixtures<AppRouter>({
+  user: {
+    getById: (input) => ({
+      id: input.id,
+      name: 'Demo User',
+      email: 'demo@example.com',
+    }),
+    list: [
+      { id: '1', name: 'User One' },
+      { id: '2', name: 'User Two' },
+    ],
+  },
+  post: {
+    create: (input) => ({
+      id: 'new-post',
+      title: input.title,
+      content: input.content,
+      createdAt: new Date(),
+    }),
+  },
+})
+```
+
+### Client Setup with Demo Link
+
+Add the demo link to your tRPC client:
+
+```ts
+import { createTRPCClient, httpBatchLink } from '@trpc/client'
+import { createDemoLink } from '@demokit-ai/trpc'
+import { fixtures } from './fixtures'
+
+const demoLink = createDemoLink({
+  fixtures,
+  isEnabled: () => localStorage.getItem('demoMode') === 'true',
+})
+
+const client = createTRPCClient<AppRouter>({
+  links: [
+    demoLink,
+    httpBatchLink({
+      url: '/api/trpc',
+    }),
+  ],
+})
+```
+
+### React Integration
+
+Use the React hooks for component-level control:
+
+```tsx
+import { DemoTRPCProvider, useDemoTRPC } from '@demokit-ai/trpc/react'
+import { fixtures } from './fixtures'
+
+function App() {
+  return (
+    <DemoTRPCProvider fixtures={fixtures}>
+      <YourApp />
+      <DemoControls />
+    </DemoTRPCProvider>
+  )
+}
+
+function DemoControls() {
+  const { enabled, toggle, setFixture } = useDemoTRPC()
+
+  return (
+    <div>
+      <button onClick={toggle}>
+        Demo: {enabled ? 'ON' : 'OFF'}
+      </button>
+      <button
+        onClick={() =>
+          setFixture('user.getById', () => ({
+            id: 'custom',
+            name: 'Custom User',
+          }))
+        }
+      >
+        Override User Fixture
+      </button>
+    </div>
+  )
+}
+```
+
+### Dynamic Fixtures
+
+Use functions for dynamic fixture responses:
+
+```ts
+const fixtures = defineTRPCFixtures<AppRouter>({
+  user: {
+    search: (input) => {
+      const users = [
+        { id: '1', name: 'Alice' },
+        { id: '2', name: 'Bob' },
+        { id: '3', name: 'Charlie' },
+      ]
+      return users.filter((u) =>
+        u.name.toLowerCase().includes(input.query.toLowerCase())
+      )
+    },
+  },
+  order: {
+    getByStatus: (input) => {
+      const orders = generateDemoOrders(10)
+      return orders.filter((o) => o.status === input.status)
+    },
+  },
+})
+```
+
+### Procedure Path Matching
+
+Fixtures support nested router paths:
+
+```ts
+const fixtures = defineTRPCFixtures<AppRouter>({
+  // Matches trpc.user.profile.get()
+  'user.profile': {
+    get: { name: 'Demo User', avatar: '/demo-avatar.png' },
+  },
+  // Matches trpc.admin.users.list()
+  'admin.users': {
+    list: [{ id: '1', role: 'admin' }],
+  },
+})
+```
+
+## API Reference
+
+### `defineTRPCFixtures<Router>(fixtures)`
+
+Type-safe fixture definition helper.
+
+### `createDemoLink(options)`
+
+Creates a tRPC link that intercepts calls when demo mode is enabled.
+
+Options:
+- `fixtures` - Fixture definitions
+- `isEnabled` - Function to check if demo mode is enabled
+- `delay` - Simulated delay in milliseconds
+- `onIntercept` - Callback when a call is intercepted
+
+### `DemoTRPCProvider`
+
+Props:
+- `fixtures` - Fixture definitions
+- `enabled` - Initial enabled state
+- `children` - React children
+
+### `useDemoTRPC()`
+
+Returns:
+- `enabled` - Demo mode state
+- `toggle()` - Toggle demo mode
+- `fixtures` - Current fixtures
+- `setFixture(path, fixture)` - Override a fixture
+- `removeFixture(path)` - Remove a fixture override
+- `clearFixtures()` - Clear all overrides
+
+### `useIsDemoTRPCMode()`
+
+Returns `true` if tRPC demo mode is enabled.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demokit-ai/trpc",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "tRPC v11 type-safe adapter for DemoKit - mock procedures with full type inference",
   "type": "module",
   "main": "./dist/index.cjs",