@idealyst/cli 1.0.91 → 1.0.93

package/template/packages/api/README.md

@@ -2,33 +2,45 @@
 
 {{description}}
 
-A simplified tRPC API with automatic CRUD generation for Prisma models.
+A dual-API backend with both **tRPC** (for internal TypeScript clients) and **GraphQL** (for public APIs and mobile apps).
 
-This API project is built with:
-- **tRPC** - End-to-end```typescript
-import { z } from 'zod';
-import { router, publicProcedure } from '../trpc.js';
-import { createCrudRouter } from '../lib/crud.js';
-import { prisma } from '../lib/database.js';
+## Tech Stack
 
-const baseCrudRouter = createCrudRouter('user', createUserSchema);
-
-export const userRouter = router({
-  ...baseCrudRouter,
-  
-  // Add custom procedures
-  getByEmail: publicProcedure
-    .input(z.object({ email: z.string().email() }))
-    .query(async ({ input }) => {
-      return await prisma.user.findUnique({
-        where: { email: input.email }
-      });
-    }),
-});
-```Zod** - TypeScript-first schema validation
+- **tRPC** - End-to-end type-safe APIs for TypeScript clients
+- **GraphQL + Pothos** - Code-first GraphQL schema with Prisma integration
+- **GraphQL Yoga** - Modern, performant GraphQL server
+- **Zod** - TypeScript-first schema validation
 - **Express.js** - Web framework for Node.js
-- **TypeScript** - Type-safe JavaScript
 - **Prisma** - Next-generation ORM for database access
+- **TypeScript** - Type-safe JavaScript
+
+## API Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│              Single Express Server              │
+│                 (port 3000)                     │
+├─────────────────────────────────────────────────┤
+│                                                 │
+│   GET  /health        → Health check            │
+│   POST /trpc/*        → tRPC procedures         │
+│   POST /graphql       → GraphQL queries         │
+│   GET  /graphql       → GraphiQL Playground     │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+### When to Use Each
+
+| Use Case | Recommended API |
+|----------|----------------|
+| Internal web app (TypeScript) | tRPC |
+| Mobile apps (React Native, iOS, Android) | GraphQL |
+| Third-party integrations | GraphQL |
+| Admin dashboards | tRPC |
+| Auth flows (login, register) | tRPC |
+| Public data queries | GraphQL |
+| File uploads | tRPC |
 
 ## Quick Start
 
@@ -44,14 +56,14 @@ export const userRouter = router({
 
 3. **Setup database:**
    ```bash
-   # Generate Prisma client
-   yarn prisma:generate
-   
+   # Generate Prisma client and Pothos types
+   yarn generate
+
    # Run migrations
-   yarn prisma:migrate
-   
+   cd ../database && yarn db:migrate
+
    # Seed database with sample data
-   yarn prisma:seed
+   yarn db:seed
    ```
 
 4. **Start development server:**
@@ -59,216 +71,440 @@ export const userRouter = router({
    yarn dev
    ```
 
-The API will be available at `http://localhost:3000`
+The API will be available at:
+- **tRPC**: `http://localhost:3000/trpc`
+- **GraphQL**: `http://localhost:3000/graphql`
+- **GraphiQL Playground**: `http://localhost:3000/graphql` (in development)
+
+## Test API - tRPC vs GraphQL Comparison
+
+The template includes a `Test` model with equivalent implementations in both tRPC and GraphQL, demonstrating how the same functionality can be exposed through both APIs.
+
+### API Equivalence Table
+
+| Operation | tRPC | GraphQL |
+|-----------|------|---------|
+| Get all | `trpc.test.getAll({ skip, take })` | `query { tests(skip, take) { ... } }` |
+| Get by ID | `trpc.test.getById({ id })` | `query { test(id) { ... } }` |
+| Create | `trpc.test.create({ name, message })` | `mutation { createTest(input) { ... } }` |
+| Update | `trpc.test.update({ id, data })` | `mutation { updateTest(id, input) { ... } }` |
+| Delete | `trpc.test.delete({ id })` | `mutation { deleteTest(id) { ... } }` |
+| Count | `trpc.test.count({})` | `query { testCount }` |
+
+### tRPC Usage (TypeScript Client)
+
+```typescript
+import { trpc } from './utils/trpc';
+
+// Get all tests
+const { data: tests } = trpc.test.getAll.useQuery({ take: 10 });
+
+// Get test by ID
+const { data: test } = trpc.test.getById.useQuery({ id: 'test-id' });
+
+// Create a new test
+const createTest = trpc.test.create.useMutation();
+await createTest.mutateAsync({
+  name: 'My Test',
+  message: 'Hello World',
+  status: 'active',
+});
+
+// Update a test
+const updateTest = trpc.test.update.useMutation();
+await updateTest.mutateAsync({
+  id: 'test-id',
+  data: { name: 'Updated Name' },
+});
+
+// Delete a test
+const deleteTest = trpc.test.delete.useMutation();
+await deleteTest.mutateAsync({ id: 'test-id' });
+
+// Get count
+const { data: count } = trpc.test.count.useQuery({});
+```
+
+### GraphQL Usage
+
+Visit `http://localhost:3000/graphql` to access the GraphiQL playground.
+
+```graphql
+# Get all tests (equivalent to trpc.test.getAll)
+query GetTests {
+  tests(take: 10) {
+    id
+    name
+    message
+    status
+    createdAt
+  }
+}
 
-## Creating CRUD APIs
+# Get test by ID (equivalent to trpc.test.getById)
+query GetTest($id: String!) {
+  test(id: $id) {
+    id
+    name
+    message
+    status
+  }
+}
 
-This template provides a simple way to create type-safe APIs with automatic CRUD operations for your Prisma models.
+# Create a new test (equivalent to trpc.test.create)
+mutation CreateTest {
+  createTest(input: {
+    name: "My Test"
+    message: "Hello World"
+    status: "active"
+  }) {
+    id
+    name
+    message
+  }
+}
 
-### 1. Define Your Prisma Model
+# Update a test (equivalent to trpc.test.update)
+mutation UpdateTest($id: String!) {
+  updateTest(id: $id, input: { name: "Updated Name" }) {
+    id
+    name
+  }
+}
 
-Add models to `packages/database/schema.prisma`:
+# Delete a test (equivalent to trpc.test.delete)
+mutation DeleteTest($id: String!) {
+  deleteTest(id: $id) {
+    id
+  }
+}
+
+# Get count (equivalent to trpc.test.count)
+query GetTestCount {
+  testCount
+}
+```
+
+### GraphQL with React/Apollo Client
+
+```typescript
+import { useQuery, useMutation, gql } from '@apollo/client';
+
+const GET_TESTS = gql`
+  query GetTests($take: Int) {
+    tests(take: $take) {
+      id
+      name
+      message
+      status
+    }
+  }
+`;
+
+const CREATE_TEST = gql`
+  mutation CreateTest($input: CreateTestInput!) {
+    createTest(input: $input) {
+      id
+      name
+    }
+  }
+`;
+
+// In your component
+function TestList() {
+  const { data, loading } = useQuery(GET_TESTS, { variables: { take: 10 } });
+  const [createTest] = useMutation(CREATE_TEST);
+
+  const handleCreate = async () => {
+    await createTest({
+      variables: {
+        input: { name: 'New Test', message: 'Hello!' },
+      },
+    });
+  };
+
+  return (/* ... */);
+}
+```
+
+## Adding New Models
+
+### Step 1: Define Prisma Model
+
+Add to `packages/database/prisma/schema.prisma`:
 
 ```prisma
-model User {
+model Product {
   id        String   @id @default(cuid())
-  email     String   @unique
   name      String
+  price     Float
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 }
 ```
 
-### 2. Create a Router
+### Step 2: Create tRPC Router
 
-Create `src/routers/user.ts`:
+Create `src/routers/product.ts`:
 
 ```typescript
 import { z } from 'zod';
 import { createCrudRouter } from '../lib/crud.js';
 
-const createUserSchema = z.object({
-  email: z.string().email(),
+const createProductSchema = z.object({
   name: z.string().min(1),
+  price: z.number().positive(),
 });
 
-const updateUserSchema = z.object({
-  email: z.string().email().optional(),
-  name: z.string().min(1).optional(),
-});
-
-export const userRouter = createCrudRouter(
-  'user',
-  createUserSchema,
-  updateUserSchema
-);
+export const productRouter = createCrudRouter('Product', createProductSchema);
 ```
 
-### 3. Add to Main Router
-
-Update `src/router/index.ts`:
+Add to `src/router/index.ts`:
 
 ```typescript
-import { userRouter } from '../routers/user.js';
+import { productRouter } from '../routers/product.js';
 
 export const appRouter = router({
-  // ... existing routes
-  users: userRouter,
+  test: testRouter,
+  product: productRouter,  // Add here
 });
 ```
 
-### 4. Use in Frontend
+### Step 3: Create GraphQL Type
+
+Create `src/graphql/types/product.ts`:
 
 ```typescript
-// Get all users
-const { data: users } = trpc.users.getAll.useQuery();
-
-// Create user
-const createUser = trpc.users.create.useMutation();
-await createUser.mutateAsync({ 
-  email: 'user@example.com', 
-  name: 'John Doe' 
+import { builder } from '../builder.js';
+import { prisma } from '../../lib/database.js';
+
+builder.prismaObject('Product', {
+  fields: (t) => ({
+    id: t.exposeID('id'),
+    name: t.exposeString('name'),
+    price: t.exposeFloat('price'),
+    createdAt: t.expose('createdAt', { type: 'DateTime' }),
+  }),
 });
 
-// Update user
-const updateUser = trpc.users.update.useMutation();
-await updateUser.mutateAsync({ 
-  id: 'user-id', 
-  data: { name: 'Jane Doe' } 
+builder.queryFields((t) => ({
+  products: t.prismaField({
+    type: ['Product'],
+    args: {
+      skip: t.arg.int(),
+      take: t.arg.int(),
+    },
+    resolve: async (query, _root, args) => {
+      return prisma.product.findMany({
+        ...query,
+        skip: args.skip ?? undefined,
+        take: args.take ?? 10,
+      });
+    },
+  }),
+}));
+
+const CreateProductInput = builder.inputType('CreateProductInput', {
+  fields: (t) => ({
+    name: t.string({ required: true }),
+    price: t.float({ required: true }),
+  }),
 });
 
-// Delete user
-const deleteUser = trpc.users.delete.useMutation();
-await deleteUser.mutateAsync({ id: 'user-id' });
+builder.mutationFields((t) => ({
+  createProduct: t.prismaField({
+    type: 'Product',
+    args: {
+      input: t.arg({ type: CreateProductInput, required: true }),
+    },
+    resolve: async (query, _root, args) => {
+      return prisma.product.create({
+        ...query,
+        data: args.input,
+      });
+    },
+  }),
+}));
 ```
 
-## Generated CRUD Operations
+Register in `src/graphql/types/index.ts`:
 
-Each `createCrudRouter` call generates:
-
-- `getAll({ skip?, take?, orderBy? })` - List with pagination
-- `getById({ id })` - Get single record
-- `create(data)` - Create new record
-- `update({ id, data })` - Update existing record  
-- `delete({ id })` - Delete record
-- `count({ where? })` - Count records
+```typescript
+import './product.js';
+```
 
-## Available Scripts
+### Step 4: Regenerate Types
 
-- `yarn dev` - Start development server with hot reload
-- `yarn build` - Build production bundle
-- `yarn start` - Start production server
-- `yarn test` - Run tests
-- `yarn lint` - Lint code
-- `yarn type-check` - Check TypeScript types
+```bash
+yarn generate
+```
 
 ## Project Structure
 
 ```
 src/
+├── graphql/
+│   ├── builder.ts        # Pothos schema builder setup
+│   ├── generated.ts      # Auto-generated Prisma types
+│   ├── index.ts          # GraphQL Yoga server
+│   └── types/
+│       ├── index.ts      # Type registration
+│       ├── test.ts       # Test model (active)
+│       ├── user.ts       # User model (example)
+│       ├── post.ts       # Post model (example)
+│       └── comment.ts    # Comment model (example)
 ├── router/
-│   └── index.ts          # Main router definition
+│   └── index.ts          # Main tRPC router
 ├── routers/
-│   ├── test.ts          # Example CRUD router for Test model
-│   └── user.example.ts  # Example CRUD router for User model
+│   ├── test.ts           # Test tRPC CRUD router
+│   └── user.example.ts   # User tRPC example
 ├── lib/
-│   ├── crud.ts          # CRUD router generator
-│   └── database.ts      # Database connection
-├── context.ts           # tRPC context
-├── trpc.ts             # tRPC setup
-└── server.ts           # Express server setup
+│   ├── crud.ts           # tRPC CRUD generator
+│   └── database.ts       # Prisma client
+├── context.ts            # Shared context
+├── trpc.ts               # tRPC setup
+├── index.ts              # Exports
+└── server.ts             # Express server
 ```
 
-## Advanced Usage
-
-### Custom Procedures
-
-Extend generated routers with custom procedures:
-
-```typescript
-import { router, publicProcedure } from '../trpc.js';
-import { createCrudRouter } from '../lib/crud.js';
-
-const baseCrudRouter = createCrudRouter('user', createUserSchema);
-
-export const userRouter = router({
-  ...baseCrudRouter,
-  
-  // Add custom procedures
-  getByEmail: publicProcedure
-    .input(z.object({ email: z.string().email() }))
-    .query(async ({ input }) => {
-      return await db.user.findUnique({
-        where: { email: input.email }
-      });
-    }),
-});
-```
-
-### Authentication
-
-For protected routes, you can add authentication middleware to the tRPC setup or create protected procedures:
-
-```typescript
-import { protectedProcedure } from '../trpc.js';
-
-// Use protectedProcedure instead of publicProcedure in your CRUD router
-```
-
-## Development
-
-1. **Add New Model**: 
-   - Add to Prisma schema
-   - Run `yarn db:migrate`
-   - Create router with `createCrudRouter`
-   - Add to main router
-
-2. **Test API**: 
-   - Start development: `yarn dev`
-   - API available at `http://localhost:3000/trpc`
-
-3. **Type Safety**: 
-   - All operations are fully type-safe
-   - Frontend gets autocomplete and validation
-   - Schemas ensure data integrity
+## Available Scripts
 
-This simplified approach removes controller complexity while maintaining full type safety and providing powerful CRUD operations for all your Prisma models.
+| Script | Description |
+|--------|-------------|
+| `yarn dev` | Start development server with hot reload |
+| `yarn build` | Build production bundle |
+| `yarn start` | Start production server |
+| `yarn generate` | Generate Prisma client and Pothos types |
+| `yarn test` | Run tests |
+| `yarn lint` | Lint code |
+| `yarn type-check` | Check TypeScript types |
 
 ## Environment Variables
 
-Create a `.env` file with:
-
 ```env
 # Database
-DATABASE_URL="file:./dev.db"
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
 
 # API
 PORT=3000
 NODE_ENV=development
-
-# Add your environment variables here
+CORS_ORIGIN=http://localhost:5173
 ```
 
 ## Testing
 
-The project includes Jest for testing:
+### Testing tRPC
 
 ```typescript
 import { createContext } from '../src/context.js';
 import { appRouter } from '../src/router/index.js';
 
-describe('API Tests', () => {
-  test('should get test records', async () => {
+describe('tRPC Test API', () => {
+  test('should get all tests', async () => {
     const ctx = createContext({} as any);
     const caller = appRouter.createCaller(ctx);
-    
-    const tests = await caller.test.getAll({});
+
+    const tests = await caller.test.getAll({ take: 10 });
     expect(tests).toBeDefined();
   });
+
+  test('should create a test', async () => {
+    const ctx = createContext({} as any);
+    const caller = appRouter.createCaller(ctx);
+
+    const test = await caller.test.create({
+      name: 'Test Name',
+      message: 'Test Message',
+    });
+    expect(test.id).toBeDefined();
+    expect(test.name).toBe('Test Name');
+  });
 });
 ```
 
-Run tests with:
-```bash
-yarn test
-```
+### Testing GraphQL
+
+```typescript
+import { schema } from '../src/graphql/index.js';
+import { graphql } from 'graphql';
+
+describe('GraphQL Test API', () => {
+  test('should query tests', async () => {
+    const query = `
+      query {
+        tests(take: 5) {
+          id
+          name
+          message
+        }
+      }
+    `;
+
+    const result = await graphql({ schema, source: query });
+    expect(result.errors).toBeUndefined();
+    expect(result.data?.tests).toBeDefined();
+  });
+
+  test('should create a test', async () => {
+    const mutation = `
+      mutation {
+        createTest(input: {
+          name: "Test Name"
+          message: "Test Message"
+        }) {
+          id
+          name
+        }
+      }
+    `;
+
+    const result = await graphql({ schema, source: mutation });
+    expect(result.errors).toBeUndefined();
+    expect(result.data?.createTest.name).toBe('Test Name');
+  });
+});
+```
+
+## Advanced: Shared Service Layer
+
+For complex business logic, use a shared service layer:
+
+```typescript
+// src/services/test.service.ts
+import { prisma } from '../lib/database.js';
+
+export const testService = {
+  async getAll(options: { skip?: number; take?: number }) {
+    return prisma.test.findMany({
+      skip: options.skip,
+      take: options.take ?? 10,
+      orderBy: { createdAt: 'desc' },
+    });
+  },
+
+  async create(data: { name: string; message: string; status?: string }) {
+    // Add business logic, validation, etc.
+    return prisma.test.create({ data });
+  },
+};
+
+// Use in tRPC (src/routers/test.ts)
+import { testService } from '../services/test.service.js';
+
+export const testRouter = router({
+  getAll: publicProcedure
+    .input(z.object({ skip: z.number().optional(), take: z.number().optional() }))
+    .query(({ input }) => testService.getAll(input)),
+});
+
+// Use in GraphQL (src/graphql/types/test.ts)
+builder.queryFields((t) => ({
+  tests: t.field({
+    type: [TestType],
+    args: { skip: t.arg.int(), take: t.arg.int() },
+    resolve: (_, args) => testService.getAll(args),
+  }),
+}));
+```
+
+This ensures consistent business logic across both APIs.

package/template/packages/api/package.json

@@ -20,15 +20,23 @@
     "test:coverage": "jest --coverage",
     "lint": "eslint src --ext .ts,.tsx",
     "lint:fix": "eslint src --ext .ts,.tsx --fix",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "generate": "prisma generate && yarn generate:pothos",
+    "generate:pothos": "tsx scripts/generate-pothos-types.ts"
   },
   "dependencies": {
     "@{{workspaceScope}}/database": "workspace:*",
     "@{{workspaceScope}}/shared": "workspace:*",
+    "@pothos/core": "^4.10.0",
+    "@pothos/plugin-prisma": "^4.12.0",
+    "@pothos/plugin-relay": "^4.6.2",
+    "@pothos/plugin-validation": "^4.2.0",
     "@trpc/server": "^11.5.1",
     "cors": "^2.8.5",
     "dotenv": "^16.3.1",
     "express": "^4.18.2",
+    "graphql": "^16.9.0",
+    "graphql-yoga": "^5.10.6",
     "zod": "^3.22.4"
   },
   "devDependencies": {
@@ -47,6 +55,8 @@
   "keywords": [
     "api",
     "trpc",
+    "graphql",
+    "pothos",
     "zod",
     "typescript",
     "express"