zilmate 1.7.8 → 1.8.1

package/.agents/skills/prisma-client-api/references/constructor.md

@@ -0,0 +1,208 @@
+# PrismaClient Constructor
+
+Configure Prisma Client when instantiating.
+
+## Basic Instantiation
+
+```typescript
+import { PrismaClient } from '../generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const adapter = new PrismaPg({
+  connectionString: process.env.DATABASE_URL
+})
+
+const prisma = new PrismaClient({ adapter })
+```
+
+## Constructor Options
+
+### adapter (Required for the SQL provider workflow)
+
+Driver adapter instance:
+
+```typescript
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const adapter = new PrismaPg({
+  connectionString: process.env.DATABASE_URL
+})
+
+const prisma = new PrismaClient({ adapter })
+```
+
+### accelerateUrl (For Accelerate users)
+
+```typescript
+import { withAccelerate } from '@prisma/extension-accelerate'
+
+const prisma = new PrismaClient({
+  accelerateUrl: process.env.DATABASE_URL,  // prisma:// URL
+}).$extends(withAccelerate())
+```
+
+### log
+
+Configure logging:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: ['query', 'info', 'warn', 'error'],
+})
+```
+
+#### Log levels
+
+| Level | Description |
+|-------|-------------|
+| `query` | All SQL queries |
+| `info` | Informational messages |
+| `warn` | Warnings |
+| `error` | Errors |
+
+#### Log to events
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: [
+    { level: 'query', emit: 'event' },
+    { level: 'error', emit: 'stdout' },
+  ],
+})
+
+prisma.$on('query', (e) => {
+  console.log('Query:', e.query)
+  console.log('Duration:', e.duration, 'ms')
+})
+```
+
+### errorFormat
+
+Control error formatting:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  errorFormat: 'pretty',  // 'pretty' | 'colorless' | 'minimal'
+})
+```
+
+### comments
+
+Attach SQL commenter plugins for observability, tracing, or query insights:
+
+```typescript
+import { PrismaClient } from '../generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+import { prismaQueryInsights } from '@prisma/sqlcommenter-query-insights'
+import { queryTags, withQueryTags } from '@prisma/sqlcommenter-query-tags'
+import { traceContext } from '@prisma/sqlcommenter-trace-context'
+
+const prisma = new PrismaClient({
+  adapter: new PrismaPg(process.env.DATABASE_URL!),
+  comments: [prismaQueryInsights(), traceContext(), queryTags()],
+})
+
+await withQueryTags({ route: '/api/users', requestId: 'req-123' }, () =>
+  prisma.user.findMany(),
+)
+```
+
+Use `comments` only for SQL providers. This is the clean way to add trace or query-shape metadata without changing your query calls.
+
+### transactionOptions
+
+Default transaction settings:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  transactionOptions: {
+    maxWait: 5000,      // Max wait to acquire transaction (ms)
+    timeout: 10000,     // Max transaction duration (ms)
+    isolationLevel: 'Serializable',
+  },
+})
+```
+
+## Singleton Pattern
+
+Prevent multiple client instances in development:
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from '../generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined
+}
+
+function createPrismaClient() {
+  const adapter = new PrismaPg({
+    connectionString: process.env.DATABASE_URL!
+  })
+  return new PrismaClient({ adapter })
+}
+
+export const prisma = globalForPrisma.prisma ?? createPrismaClient()
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma
+}
+```
+
+## Next.js Pattern
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from '@/generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const createAdapter = () => new PrismaPg({
+  connectionString: process.env.DATABASE_URL!
+})
+
+const prismaClientSingleton = () => {
+  return new PrismaClient({ adapter: createAdapter() })
+}
+
+declare const globalThis: {
+  prismaGlobal: ReturnType<typeof prismaClientSingleton>
+} & typeof global
+
+const prisma = globalThis.prismaGlobal ?? prismaClientSingleton()
+
+export default prisma
+
+if (process.env.NODE_ENV !== 'production') {
+  globalThis.prismaGlobal = prisma
+}
+```
+
+## Query Events
+
+Listen to query events:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: [{ level: 'query', emit: 'event' }],
+})
+
+prisma.$on('query', (e) => {
+  console.log('Query:', e.query)
+  console.log('Params:', e.params)
+  console.log('Duration:', e.duration)
+})
+```
+
+## Log Events
+
+```typescript
+prisma.$on('info', (e) => console.log(e.message))
+prisma.$on('warn', (e) => console.warn(e.message))
+prisma.$on('error', (e) => console.error(e.message))
+```

package/.agents/skills/prisma-client-api/references/filters.md

@@ -0,0 +1,256 @@
+# Filter Conditions and Operators
+
+Filter operators for the `where` clause.
+
+## Equality
+
+```typescript
+// Exact match (implicit)
+where: { email: 'alice@prisma.io' }
+
+// Explicit equals
+where: { email: { equals: 'alice@prisma.io' } }
+
+// Not equal
+where: { email: { not: 'alice@prisma.io' } }
+```
+
+## Comparison
+
+```typescript
+// Greater than
+where: { age: { gt: 18 } }
+
+// Greater than or equal
+where: { age: { gte: 18 } }
+
+// Less than
+where: { age: { lt: 65 } }
+
+// Less than or equal
+where: { age: { lte: 65 } }
+
+// Combined
+where: { age: { gte: 18, lte: 65 } }
+```
+
+## Lists
+
+```typescript
+// In array
+where: { role: { in: ['ADMIN', 'MODERATOR'] } }
+
+// Not in array
+where: { role: { notIn: ['GUEST', 'BANNED'] } }
+```
+
+## String Filters
+
+```typescript
+// Contains
+where: { email: { contains: 'prisma' } }
+
+// Starts with
+where: { email: { startsWith: 'alice' } }
+
+// Ends with
+where: { email: { endsWith: '@prisma.io' } }
+
+// Case-insensitive (default for some databases)
+where: { 
+  email: { 
+    contains: 'PRISMA',
+    mode: 'insensitive' 
+  } 
+}
+```
+
+## Null Checks
+
+```typescript
+// Is null
+where: { deletedAt: null }
+
+// Is not null
+where: { deletedAt: { not: null } }
+
+// Using isSet (for optional fields)
+where: { middleName: { isSet: true } }
+```
+
+## Logical Operators
+
+### AND (implicit)
+
+```typescript
+// Multiple conditions = AND
+where: {
+  email: { contains: '@prisma.io' },
+  role: 'ADMIN'
+}
+```
+
+### AND (explicit)
+
+```typescript
+where: {
+  AND: [
+    { email: { contains: '@prisma.io' } },
+    { role: 'ADMIN' }
+  ]
+}
+```
+
+### OR
+
+```typescript
+where: {
+  OR: [
+    { email: { contains: '@gmail.com' } },
+    { email: { contains: '@prisma.io' } }
+  ]
+}
+```
+
+### NOT
+
+```typescript
+where: {
+  NOT: {
+    role: 'GUEST'
+  }
+}
+
+// Multiple NOT conditions
+where: {
+  NOT: [
+    { role: 'GUEST' },
+    { verified: false }
+  ]
+}
+```
+
+### Combined
+
+```typescript
+where: {
+  AND: [
+    { verified: true },
+    {
+      OR: [
+        { role: 'ADMIN' },
+        { role: 'MODERATOR' }
+      ]
+    }
+  ],
+  NOT: { deletedAt: { not: null } }
+}
+```
+
+## Relation Filters
+
+### some
+
+At least one related record matches:
+
+```typescript
+// Users with at least one published post
+where: {
+  posts: {
+    some: { published: true }
+  }
+}
+```
+
+### every
+
+All related records match:
+
+```typescript
+// Users where all posts are published
+where: {
+  posts: {
+    every: { published: true }
+  }
+}
+```
+
+### none
+
+No related records match:
+
+```typescript
+// Users with no published posts
+where: {
+  posts: {
+    none: { published: true }
+  }
+}
+```
+
+### is / isNot (1-to-1)
+
+```typescript
+// Users with profile in specific country
+where: {
+  profile: {
+    is: { country: 'USA' }
+  }
+}
+
+// Users without profile
+where: {
+  profile: {
+    isNot: null
+  }
+}
+```
+
+## Array Field Filters
+
+For fields like `String[]`:
+
+```typescript
+// Has element
+where: { tags: { has: 'typescript' } }
+
+// Has some elements
+where: { tags: { hasSome: ['typescript', 'javascript'] } }
+
+// Has every element
+where: { tags: { hasEvery: ['typescript', 'prisma'] } }
+
+// Is empty
+where: { tags: { isEmpty: true } }
+```
+
+## JSON Filters
+
+```typescript
+// Path-based filter
+where: {
+  metadata: {
+    path: ['settings', 'theme'],
+    equals: 'dark'
+  }
+}
+
+// String contains in JSON
+where: {
+  metadata: {
+    path: ['bio'],
+    string_contains: 'developer'
+  }
+}
+```
+
+## Full-Text Search
+
+```typescript
+// Requires @@fulltext index
+where: {
+  content: {
+    search: 'prisma database'
+  }
+}
+```

package/.agents/skills/prisma-client-api/references/model-queries.md

@@ -0,0 +1,281 @@
+# Model Queries
+
+CRUD operations for your Prisma models.
+
+## Read Operations
+
+### findUnique
+
+Find a single record by unique field:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 }
+})
+
+const user = await prisma.user.findUnique({
+  where: { email: 'alice@prisma.io' }
+})
+```
+
+#### With composite unique key
+
+```typescript
+// Model with @@unique([firstName, lastName])
+const user = await prisma.user.findUnique({
+  where: {
+    firstName_lastName: {
+      firstName: 'Alice',
+      lastName: 'Smith'
+    }
+  }
+})
+```
+
+### findUniqueOrThrow
+
+Same as findUnique but throws if not found:
+
+```typescript
+const user = await prisma.user.findUniqueOrThrow({
+  where: { id: 1 }
+})
+// Throws PrismaClientKnownRequestError if not found
+```
+
+### findFirst
+
+Find first matching record:
+
+```typescript
+const user = await prisma.user.findFirst({
+  where: { role: 'ADMIN' },
+  orderBy: { createdAt: 'desc' }
+})
+```
+
+### findFirstOrThrow
+
+```typescript
+const user = await prisma.user.findFirstOrThrow({
+  where: { role: 'ADMIN' }
+})
+```
+
+### findMany
+
+Find multiple records:
+
+```typescript
+const users = await prisma.user.findMany({
+  where: { role: 'USER' },
+  orderBy: { name: 'asc' },
+  take: 10,
+  skip: 0
+})
+```
+
+## Create Operations
+
+### create
+
+Create a single record:
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'alice@prisma.io',
+    name: 'Alice'
+  }
+})
+```
+
+#### With relations
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'alice@prisma.io',
+    posts: {
+      create: [
+        { title: 'First Post' },
+        { title: 'Second Post' }
+      ]
+    }
+  },
+  include: { posts: true }
+})
+```
+
+### createMany
+
+Create multiple records:
+
+```typescript
+const result = await prisma.user.createMany({
+  data: [
+    { email: 'alice@prisma.io', name: 'Alice' },
+    { email: 'bob@prisma.io', name: 'Bob' }
+  ],
+  skipDuplicates: true  // Skip records with duplicate unique fields
+})
+// Returns { count: 2 }
+```
+
+### createManyAndReturn
+
+Create multiple and return them:
+
+```typescript
+const users = await prisma.user.createManyAndReturn({
+  data: [
+    { email: 'alice@prisma.io', name: 'Alice' },
+    { email: 'bob@prisma.io', name: 'Bob' }
+  ]
+})
+// Returns array of created users
+```
+
+## Update Operations
+
+### update
+
+Update a single record:
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: { name: 'Alice Smith' }
+})
+```
+
+#### Atomic operations
+
+```typescript
+const post = await prisma.post.update({
+  where: { id: 1 },
+  data: {
+    views: { increment: 1 },
+    likes: { decrement: 1 },
+    score: { multiply: 2 },
+    rating: { divide: 2 },
+    version: { set: 5 }
+  }
+})
+```
+
+### updateMany
+
+Update multiple records:
+
+```typescript
+const result = await prisma.user.updateMany({
+  where: { role: 'USER' },
+  data: { verified: true }
+})
+// Returns { count: 42 }
+```
+
+### updateManyAndReturn
+
+```typescript
+const users = await prisma.user.updateManyAndReturn({
+  where: { role: 'USER' },
+  data: { verified: true }
+})
+// Returns array of updated users
+```
+
+### upsert
+
+Update or create:
+
+```typescript
+const user = await prisma.user.upsert({
+  where: { email: 'alice@prisma.io' },
+  update: { name: 'Alice Smith' },
+  create: { email: 'alice@prisma.io', name: 'Alice' }
+})
+```
+
+## Delete Operations
+
+### delete
+
+Delete a single record:
+
+```typescript
+const user = await prisma.user.delete({
+  where: { id: 1 }
+})
+// Returns deleted record
+```
+
+### deleteMany
+
+Delete multiple records:
+
+```typescript
+const result = await prisma.user.deleteMany({
+  where: { role: 'GUEST' }
+})
+// Returns { count: 5 }
+
+// Delete all
+const result = await prisma.user.deleteMany({})
+```
+
+## Aggregation Operations
+
+### count
+
+```typescript
+const count = await prisma.user.count({
+  where: { role: 'ADMIN' }
+})
+```
+
+### aggregate
+
+```typescript
+const result = await prisma.post.aggregate({
+  _avg: { views: true },
+  _sum: { views: true },
+  _min: { views: true },
+  _max: { views: true },
+  _count: { _all: true }
+})
+```
+
+### groupBy
+
+```typescript
+const groups = await prisma.user.groupBy({
+  by: ['country'],
+  _count: { _all: true },
+  _avg: { age: true },
+  having: {
+    age: { _avg: { gt: 30 } }
+  }
+})
+```
+
+## Return Types
+
+| Method | Returns |
+|--------|---------|
+| `findUnique` | Record \| null |
+| `findUniqueOrThrow` | Record (throws if not found) |
+| `findFirst` | Record \| null |
+| `findFirstOrThrow` | Record (throws if not found) |
+| `findMany` | Record[] |
+| `create` | Record |
+| `createMany` | { count: number } |
+| `createManyAndReturn` | Record[] |
+| `update` | Record |
+| `updateMany` | { count: number } |
+| `delete` | Record |
+| `deleteMany` | { count: number } |
+| `count` | number |
+| `aggregate` | Aggregate result |
+| `groupBy` | Group result[] |