@cdmbase/wiki-browser 12.0.18-alpha.10

package/lib/templates/content/docs/adminide-modules/api-builders/graphql.md

@@ -0,0 +1,906 @@
+# GraphQL Builder - Comprehensive Documentation
+
+## Overview
+
+GraphQL Builder is a powerful, directive-based GraphQL API generation tool that automatically generates Prisma schemas, resolvers, queries, mutations, and DataLoaders from a GraphQL Schema Definition Language (SDL). It provides a visual code editor interface for managing GraphQL projects and enables rapid API development with minimal boilerplate code.
+
+## Key Features
+
+### 1. **Directive-Based Code Generation**
+
+- Automatically converts GraphQL SDL to Prisma schema
+- Generates TypeScript resolvers for queries and mutations
+- Creates DataLoaders for efficient data fetching
+- Supports custom directives for extending functionality
+
+### 2. **Visual Code Editor**
+
+- Monaco Editor-based IDE for editing GraphQL schemas
+- File tree management for organizing schema, resolvers, and directives
+- Tab-based editing interface
+- Real-time syntax highlighting and validation
+- Auto-save functionality
+
+### 3. **Auto-Generated Queries & Mutations**
+
+- Automatically generates CRUD operations for all entity types
+- Supports filtering, pagination, and sorting
+- Generates both single-item and list queries
+- Creates create, update, and delete mutations
+
+### 4. **Custom Directives Support**
+
+- Create and manage custom directives via file-based system
+- Directives are stored as TypeScript files in `/directives` folder
+- Automatic directive extraction and compilation
+- Support for directive composition and reuse
+
+### 5. **DataLoader Generation**
+
+- Automatically generates DataLoaders for relationships
+- Prevents N+1 query problems
+- Supports both single and batch loading
+- Generated DataLoaders are type-safe and optimized
+
+### 6. **Project Management**
+
+- Multi-project support with tenant isolation
+- Project deployment to Express.js servers
+- Environment-specific configurations
+- Connection status monitoring
+
+## Resolvers
+
+### Overview
+
+Resolvers are functions that resolve the value for a field in your GraphQL schema. GraphQL Builder automatically generates resolvers for all entity types, handling queries, mutations, and field relationships.
+
+### Types of Resolvers
+
+#### 1. Query Resolvers
+
+Query resolvers handle read operations. For each entity type, two query resolvers are automatically generated:
+
+**Single Item Query (`get{TypeName}`)**
+
+- Fetches a single entity by ID
+- Uses Prisma's `findUnique` method
+- Returns `null` if not found
+
+**List Query (`getAll{TypeName}s`)**
+
+- Fetches multiple entities with filtering and pagination
+- Uses Prisma's `findMany` method
+- Supports `filter`, `limit`, and `offset` arguments
+
+**Generated Code Example:**
+
+```typescript
+const queryResolvers = {
+    Query: {
+        getUser: async (_parent, { id }, _context) => {
+            const { prisma } = _context;
+            return prisma.user.findUnique({
+                where: { id },
+            });
+        },
+        getAllUsers: async (_, args, _context) => {
+            const { prisma } = _context;
+            const { filter, limit, offset } = args;
+            return prisma.user.findMany({
+                where: filter || {},
+                take: limit || 10,
+                skip: offset || 0,
+            });
+        },
+    },
+};
+```
+
+#### 2. Mutation Resolvers
+
+Mutation resolvers handle write operations. For each entity type, three mutation resolvers are automatically generated:
+
+**Create Mutation (`create{TypeName}`)**
+
+- Creates a new entity
+- Uses Prisma's `create` method
+- Accepts `data` argument with entity fields
+
+**Update Mutation (`update{TypeName}`)**
+
+- Updates an existing entity by ID
+- Uses Prisma's `update` method
+- Accepts `id` and `data` arguments
+
+**Delete Mutation (`delete{TypeName}`)**
+
+- Deletes an entity by ID
+- Uses Prisma's `delete` method
+- Accepts `id` argument
+
+**Generated Code Example:**
+
+```typescript
+const mutationResolvers = {
+    Mutation: {
+        createUser: async (_parent, args, _context) => {
+            const { prisma } = _context;
+            return prisma.user.create({
+                data: args.data,
+            });
+        },
+        updateUser: async (_parent, { id, data }, _context) => {
+            const { prisma } = _context;
+            return prisma.user.update({
+                where: { id },
+                data,
+            });
+        },
+        deleteUser: async (_parent, { id }, _context) => {
+            const { prisma } = _context;
+            return prisma.user.delete({
+                where: { id },
+            });
+        },
+    },
+};
+```
+
+#### 3. Field Resolvers (Type Resolvers)
+
+Field resolvers resolve fields on entity types. They are generated for:
+
+- **Non-column fields**: Fields without `@column` directive that need custom resolution
+- **DataLoader fields**: Fields with `@useLoader` directive for efficient relationship loading
+- **Computed fields**: Fields that require custom logic
+
+**DataLoader Field Resolver Example:**
+
+```typescript
+const typeResolvers = {
+    Post: {
+        author: (parent, args, context) => {
+            const { userAuthorDataLoader } = context;
+            return userAuthorDataLoader.load(parent.authorId);
+        },
+    },
+    User: {
+        posts: (parent, args, context) => {
+            const { userPostsDataLoader } = context;
+            const postIds = (parent.postIds || []).filter(Boolean);
+            return userPostsDataLoader.loadMany(postIds);
+        },
+    },
+};
+```
+
+**TODO Field Resolver Example:**
+For fields that need custom implementation but don't have `@useLoader`:
+
+```typescript
+const typeResolvers = {
+    User: {
+        fullName: (parent, args, context) => {
+            // TODO: Implement resolver for fullName
+            return null;
+        },
+    },
+};
+```
+
+### Resolver Structure
+
+All resolvers follow this structure:
+
+```typescript
+export const resolvers = [
+    queryResolvers, // Query resolvers
+    mutationResolvers, // Mutation resolvers
+    typeResolvers, // Field/Type resolvers
+];
+```
+
+### Resolver Parameters
+
+All resolvers receive three parameters:
+
+1. **`parent`** (or `_parent`): The result from the resolver on the parent field
+2. **`args`**: Arguments passed to the field
+3. **`context`** (or `_context`): Context object containing:
+    - `prisma`: PrismaClient instance
+    - `[DataLoaderName]`: Generated DataLoaders for relationships
+    - `user`: Authenticated user (if using `@auth` directive)
+    - Other context properties
+
+### Resolver Context
+
+The resolver context provides access to:
+
+```typescript
+interface ResolverContext {
+    prisma: PrismaClient;
+    // Generated DataLoaders
+    userAuthorDataLoader?: DataLoader<string, User>;
+    postCommentsDataLoader?: DataLoader<string[], Comment[]>;
+    // Authentication
+    user?: User;
+    // Request object
+    req?: Express.Request;
+}
+```
+
+### Customizing Resolvers
+
+#### Editing Generated Resolvers
+
+The generated `resolvers.ts` file can be edited directly in the editor. You can:
+
+1. **Modify existing resolvers**: Update the generated resolver logic
+2. **Add custom resolvers**: Add new query/mutation/field resolvers
+3. **Override defaults**: Replace generated resolvers with custom implementations
+
+**Example: Adding Custom Query Resolver**
+
+```typescript
+const queryResolvers = {
+    Query: {
+        getUser: async (_parent, { id }, _context) => {
+            // Generated resolver
+            const { prisma } = _context;
+            return prisma.user.findUnique({ where: { id } });
+        },
+        // Custom resolver
+        getUserByEmail: async (_parent, { email }, _context) => {
+            const { prisma } = _context;
+            return prisma.user.findUnique({ where: { email } });
+        },
+        searchUsers: async (_parent, { query }, _context) => {
+            const { prisma } = _context;
+            return prisma.user.findMany({
+                where: {
+                    OR: [{ name: { contains: query } }, { email: { contains: query } }],
+                },
+            });
+        },
+    },
+};
+```
+
+**Example: Adding Custom Field Resolver**
+
+```typescript
+const typeResolvers = {
+    User: {
+        // Generated DataLoader resolver
+        posts: (parent, args, context) => {
+            const { userPostsDataLoader } = context;
+            return userPostsDataLoader.loadMany(parent.postIds || []);
+        },
+        // Custom computed field
+        postCount: async (parent, args, context) => {
+            const { prisma } = context;
+            return prisma.post.count({
+                where: { authorId: parent.id },
+            });
+        },
+        // Custom field with business logic
+        isActive: (parent) => {
+            return parent.status === 'active' && parent.emailVerified;
+        },
+    },
+};
+```
+
+#### Resolver Best Practices
+
+1. **Use DataLoaders for Relationships**: Always use `@useLoader` directive for relationships to prevent N+1 queries
+2. **Keep Resolvers Thin**: Move business logic to service layers
+3. **Handle Errors**: Wrap resolver logic in try-catch blocks
+4. **Validate Input**: Validate arguments before database operations
+5. **Use Context**: Access shared resources through context (prisma, user, etc.)
+6. **Async/Await**: Use async/await for database operations
+7. **Type Safety**: Leverage TypeScript types for resolver parameters and return values
+
+### Resolver Generation Rules
+
+#### Entity Types
+
+- All entity types (`@entity` directive) get query and mutation resolvers
+- Field resolvers are generated for non-column fields and DataLoader fields
+- ID field resolvers are skipped (handled by Prisma)
+
+#### Abstract Entities
+
+- Abstract entities (`@abstractEntity` directive) get query and mutation resolvers
+- Implementing types inherit resolvers from abstract entity
+- Polymorphic queries are generated
+
+#### Non-Entity Types
+
+- Non-entity object types get stub resolvers with TODO comments
+- Stub resolvers return `null` by default
+- You must implement these manually
+
+### Resolver File Location
+
+Generated resolvers are saved in:
+
+```
+project-name/resolvers.ts
+```
+
+This file is editable in the GraphQL Builder editor and persists across deployments.
+
+### Resolver Regeneration
+
+Resolvers are regenerated when:
+
+- Schema changes are saved
+- Project is deployed
+- Types are generated manually
+
+**Important**: Custom resolver modifications are preserved during regeneration. Only new resolvers are added; existing ones are not overwritten unless the schema structure changes significantly.
+
+## Supported Directives
+
+### Core Directives
+
+#### `@entity`
+
+Marks a GraphQL type as a database entity. Only types with this directive are included in Prisma schema generation.
+
+```graphql
+type User @entity {
+    id: ID! @id
+    name: String! @column
+}
+```
+
+#### `@column(overrideType: String)`
+
+Marks a field to be stored as a database column. The `overrideType` parameter allows overriding the Prisma type.
+
+```graphql
+type User @entity {
+    id: ID! @id
+    email: String! @column
+    age: Int @column(overrideType: "Int")
+}
+```
+
+#### `@id`
+
+Marks a field as the primary key. Automatically maps to MongoDB ObjectId.
+
+```graphql
+type User @entity {
+    id: ID! @id
+    # or
+    userId: ID! @id
+}
+```
+
+#### `@useLoader(fieldName: String)`
+
+Generates a DataLoader for efficient relationship loading. The `fieldName` specifies which field contains the foreign key.
+
+```graphql
+type Post @entity {
+    id: ID! @id
+    authorId: String! @column
+    author: User @useLoader(fieldName: "authorId")
+}
+```
+
+#### `@abstractEntity(discriminatorField: String!)`
+
+Creates a polymorphic entity pattern. Useful for inheritance-like structures.
+
+```graphql
+interface Content @abstractEntity(discriminatorField: "contentType") {
+    id: ID! @id
+    title: String! @column
+}
+
+type Article implements Content @entity {
+    contentType: ContentType!
+    body: String! @column
+}
+
+type Video implements Content @entity {
+    contentType: ContentType!
+    url: String! @column
+}
+```
+
+#### `@auth`
+
+Adds authentication middleware to queries, mutations, or fields. Requires valid Keycloak JWT token.
+
+```graphql
+type Query {
+    protectedData: String @auth
+}
+
+type Mutation {
+    updateUser(id: ID!): User @auth
+}
+```
+
+### Prisma-Specific Directives
+
+#### `@unique`
+
+Marks a field as unique in the database.
+
+```graphql
+type User @entity {
+    email: String! @column @unique
+}
+```
+
+#### `@relation(field: String)`
+
+Defines relationships between entities.
+
+```graphql
+type User @entity {
+    id: ID! @id
+    posts: [Post!] @relation(field: "authorId")
+}
+
+type Post @entity {
+    id: ID! @id
+    authorId: String! @column
+    author: User @useLoader(fieldName: "authorId")
+}
+```
+
+#### `@default(value: String)`
+
+Sets a default value for a field.
+
+```graphql
+type User @entity {
+    status: String! @column @default(value: "active")
+}
+```
+
+#### `@defaultBoolean(value: Boolean)`
+
+Sets a default boolean value.
+
+```graphql
+type User @entity {
+    isActive: Boolean! @column @defaultBoolean(value: true)
+}
+```
+
+#### `@defaultInt(value: Int)`
+
+Sets a default integer value.
+
+```graphql
+type Post @entity {
+    viewCount: Int! @column @defaultInt(value: 0)
+}
+```
+
+#### `@defaultFloat(value: Float)`
+
+Sets a default float value.
+
+```graphql
+type Product @entity {
+    price: Float! @column @defaultFloat(value: 0.0)
+}
+```
+
+## Auto-Generated Operations
+
+### Query Operations
+
+For each entity type, the following queries are automatically generated:
+
+#### Single Item Query
+
+```graphql
+query {
+    getUser(id: "123") {
+        id
+        name
+        email
+    }
+}
+```
+
+#### List Query with Filtering & Pagination
+
+```graphql
+query {
+    getAllUsers(filter: { name: { contains: "John" } }, limit: 10, offset: 0) {
+        id
+        name
+        email
+    }
+}
+```
+
+### Mutation Operations
+
+For each entity type, the following mutations are automatically generated:
+
+#### Create Mutation
+
+```graphql
+mutation {
+    createUser(data: { name: "John Doe", email: "john@example.com" }) {
+        id
+        name
+        email
+    }
+}
+```
+
+#### Update Mutation
+
+```graphql
+mutation {
+    updateUser(id: "123", data: { name: "Jane Doe" }) {
+        id
+        name
+        email
+    }
+}
+```
+
+#### Delete Mutation
+
+```graphql
+mutation {
+    deleteUser(id: "123") {
+        id
+    }
+}
+```
+
+## Architecture
+
+### Code Generation Flow
+
+1. **Schema Input**: User writes GraphQL SDL in the editor
+2. **Validation**: Schema is validated for syntax and semantic correctness
+3. **Parsing**: GraphQL schema is parsed into AST
+4. **Directive Processing**: Directives are analyzed and processed
+5. **Prisma Schema Generation**: Prisma schema is generated from entity types
+6. **Resolver Generation**: TypeScript resolvers are generated
+7. **DataLoader Generation**: DataLoaders are created for relationships
+8. **Code Compilation**: Generated code is written to project directory
+9. **Prisma Generate**: Prisma Client is generated
+10. **Deployment**: Project is deployed to Express.js server
+
+### File Structure
+
+```
+project-name/
+├── schema.prisma          # Generated Prisma schema
+├── schema.graphql         # Original GraphQL schema
+├── resolvers.ts           # Generated resolvers
+├── server.ts              # Express server setup
+├── client/                # Generated Prisma Client
+│   └── index.js
+└── dataloaders/           # Generated DataLoaders
+    ├── index.ts
+    └── [entity]DataLoader.ts
+```
+
+### Editor File Structure
+
+```
+/
+├── schema.graphql         # Main GraphQL schema
+├── resolver.ts            # Custom resolvers (optional)
+├── model.ts               # Generated model types
+├── directives/            # Custom directive files
+│   ├── directive.ts       # Compiled directives index
+│   └── [custom].ts       # Individual directive files
+└── _generated/            # Auto-generated client files
+    └── ...
+```
+
+## Usage Guide
+
+### Creating a New Project
+
+1. Navigate to the GraphQL Builder interface
+2. Select your organization
+3. Start editing the default schema template
+4. Define your entities using directives
+5. Save the project
+6. Deploy when ready
+
+### Example Schema
+
+```graphql
+type User @entity {
+    id: ID! @id
+    email: String! @column @unique
+    name: String! @column
+    posts: [Post!] @relation(field: "authorId")
+    createdAt: DateTime! @column
+    updatedAt: DateTime! @column
+}
+
+type Post @entity {
+    id: ID! @id
+    title: String! @column
+    content: String! @column
+    authorId: String! @column
+    author: User @useLoader(fieldName: "authorId")
+    published: Boolean! @column @defaultBoolean(value: false)
+    createdAt: DateTime! @column
+    updatedAt: DateTime! @column
+}
+
+type Query {
+    getUser(id: ID!): User
+    getAllUsers(filter: JSON, limit: Int, offset: Int): [User!]!
+    getPost(id: ID!): Post
+    getAllPosts(filter: JSON, limit: Int, offset: Int): [Post!]!
+}
+
+type Mutation {
+    createUser(data: JSON!): User!
+    updateUser(id: ID!, data: JSON!): User!
+    deleteUser(id: ID!): User!
+    createPost(data: JSON!): Post!
+    updatePost(id: ID!, data: JSON!): Post!
+    deletePost(id: ID!): Post!
+}
+```
+
+### Creating Custom Directives
+
+1. Create a new `.ts` file in the `/directives` folder
+2. Export a directive function:
+
+```typescript
+export const myCustomDirective = (next, source, args, context, info) => {
+    // Custom logic here
+    return next();
+};
+```
+
+3. The directive will be automatically extracted and compiled
+4. Use it in your schema:
+
+```graphql
+type Query {
+    myField: String @myCustomDirective
+}
+```
+
+### Deploying a Project
+
+1. Save your project changes
+2. Click the "Deploy" button
+3. The system will:
+    - Generate Prisma schema
+    - Generate resolvers
+    - Generate DataLoaders
+    - Run `prisma generate`
+    - Deploy to Express server
+    - Create Apollo Server endpoint
+
+## API Endpoints
+
+### GraphQL Endpoint
+
+After deployment, each project gets its own GraphQL endpoint:
+
+```
+POST /graphql/{projectName}
+```
+
+### Project Management Endpoints
+
+#### Get Projects
+
+```graphql
+query {
+    prismaProjects(
+        tenantProject: { projectId: "project-id", environmentTag: "env-tag" }
+        criteria: { name: "project-name" }
+    ) {
+        data {
+            id
+            name
+            schema
+            lastDeployedAt
+        }
+        totalCount
+    }
+}
+```
+
+#### Create Project
+
+```graphql
+mutation {
+    createPrismaProject(
+        prismaProject: {
+            name: "my-project"
+            schema: "type User @entity { ... }"
+            resolvers: "..."
+            directives: []
+            projectId: "project-id"
+            environmentTag: "env-tag"
+        }
+    ) {
+        id
+        name
+    }
+}
+```
+
+#### Deploy Project
+
+```graphql
+mutation {
+    deployPrismaProject(id: "project-id")
+}
+```
+
+#### Generate Types
+
+```graphql
+query {
+    generateTypes(schema: "type User @entity { ... }") {
+        types
+        resolvers
+        collections
+    }
+}
+```
+
+## Advanced Features
+
+### Polymorphic Types
+
+Use `@abstractEntity` to create polymorphic relationships:
+
+```graphql
+interface Media @abstractEntity(discriminatorField: "mediaType") {
+    id: ID! @id
+    title: String! @column
+    url: String! @column
+}
+
+type Image implements Media @entity {
+    mediaType: MediaType!
+    width: Int @column
+    height: Int @column
+}
+
+type Video implements Media @entity {
+    mediaType: MediaType!
+    duration: Int @column
+}
+```
+
+### Custom Resolvers
+
+You can add custom resolvers in the `resolver.ts` file:
+
+```typescript
+export const resolvers = [
+    {
+        Query: {
+            // Custom query resolvers
+            customQuery: async (parent, args, context) => {
+                // Your custom logic
+            },
+        },
+        Mutation: {
+            // Custom mutation resolvers
+            customMutation: async (parent, args, context) => {
+                // Your custom logic
+            },
+        },
+        User: {
+            // Custom field resolvers
+            customField: (parent, args, context) => {
+                // Your custom logic
+            },
+        },
+    },
+];
+```
+
+### Authentication
+
+Use `@auth` directive to protect operations:
+
+```graphql
+type Query {
+    publicData: String
+    privateData: String @auth
+}
+
+type Mutation {
+    updateProfile(id: ID!): User @auth
+}
+```
+
+The `@auth` directive validates Keycloak JWT tokens and ensures the user is authenticated before executing the resolver.
+
+## Best Practices
+
+1. **Use Descriptive Entity Names**: Use clear, singular nouns for entity types
+2. **Leverage Directives**: Use appropriate directives to reduce boilerplate
+3. **Organize Directives**: Keep custom directives in separate files
+4. **Validate Early**: Use the editor's validation before deploying
+5. **Version Control**: Keep your GraphQL schemas in version control
+6. **Use DataLoaders**: Always use `@useLoader` for relationships to avoid N+1 queries
+7. **Test Locally**: Test your schema locally before deploying to production
+8. **Customize Resolvers**: Edit generated resolvers to add business logic
+9. **Handle Errors**: Implement proper error handling in custom resolvers
+10. **Use TypeScript**: Leverage TypeScript types for type safety
+
+## Troubleshooting
+
+### Schema Validation Errors
+
+- Check for syntax errors in your GraphQL SDL
+- Ensure all directives are properly formatted
+- Verify entity types have `@entity` directive
+
+### Deployment Failures
+
+- Check database connection string
+- Verify Prisma schema is valid
+- Ensure all required fields have proper types
+
+### DataLoader Issues
+
+- Verify `@useLoader` directive has correct `fieldName`
+- Check that the field specified exists on the entity
+- Ensure foreign key relationships are properly defined
+
+### Resolver Issues
+
+- Check that resolver context includes required DataLoaders
+- Verify Prisma client is properly initialized
+- Ensure resolver return types match schema types
+- Check for async/await usage in async resolvers
+
+## Technical Details
+
+### Prisma Schema Generation
+
+- Converts GraphQL types to Prisma models
+- Maps GraphQL types to Prisma types
+- Generates relationships based on directives
+- Creates indexes for unique fields
+
+### Resolver Generation
+
+- Generates CRUD operations for all entities
+- Creates field resolvers for relationships
+- Implements DataLoader resolvers
+- Adds TODO placeholders for custom resolvers
+- Preserves custom resolver modifications
+
+### DataLoader Generation
+
+- Creates DataLoader classes for each relationship
+- Implements batch loading logic
+- Handles both single and list relationships
+- Optimizes database queries
+
+### Video Tutorial
+
+https://www.loom.com/share/18b5b92fd3bf406da27c58b3496c8be6
+
+https://www.loom.com/share/7264060666124560b549a082b266fcf8