zilmate 1.7.8 → 1.8.1

package/.agents/skills/prisma-client-api/references/query-options.md

@@ -0,0 +1,276 @@
+# Query Options
+
+Options for controlling query behavior.
+
+## select
+
+Choose specific fields to return:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  select: {
+    id: true,
+    name: true,
+    email: true,
+    // password: false (excluded by not including)
+  }
+})
+// Returns: { id: 1, name: 'Alice', email: 'alice@prisma.io' }
+```
+
+### Select relations
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  select: {
+    name: true,
+    posts: {
+      select: {
+        title: true,
+        published: true
+      }
+    }
+  }
+})
+```
+
+### Select with include inside
+
+```typescript
+const user = await prisma.user.findMany({
+  select: {
+    name: true,
+    posts: {
+      include: {
+        comments: true
+      }
+    }
+  }
+})
+```
+
+### Select relation count
+
+```typescript
+const users = await prisma.user.findMany({
+  select: {
+    name: true,
+    _count: {
+      select: { posts: true }
+    }
+  }
+})
+// Returns: { name: 'Alice', _count: { posts: 5 } }
+```
+
+## include
+
+Include related records:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: true,
+    profile: true
+  }
+})
+```
+
+### Filtered include
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: {
+      where: { published: true },
+      orderBy: { createdAt: 'desc' },
+      take: 5
+    }
+  }
+})
+```
+
+### Nested include
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: {
+      include: {
+        comments: {
+          include: {
+            author: true
+          }
+        }
+      }
+    }
+  }
+})
+```
+
+### Include relation count
+
+```typescript
+const users = await prisma.user.findMany({
+  include: {
+    _count: {
+      select: { posts: true, followers: true }
+    }
+  }
+})
+```
+
+## omit
+
+Exclude specific fields:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  omit: {
+    password: true
+  }
+})
+// Returns all fields except password
+```
+
+### Omit in relations
+
+```typescript
+const users = await prisma.user.findMany({
+  omit: { password: true },
+  include: {
+    posts: {
+      omit: { content: true }
+    }
+  }
+})
+```
+
+**Note:** Cannot use `select` and `omit` together.
+
+## where
+
+Filter records:
+
+```typescript
+const users = await prisma.user.findMany({
+  where: {
+    email: { contains: '@prisma.io' },
+    role: 'ADMIN'
+  }
+})
+```
+
+See `filters.md` for detailed filter operators.
+
+## orderBy
+
+Sort results:
+
+```typescript
+// Single field
+const users = await prisma.user.findMany({
+  orderBy: { name: 'asc' }
+})
+
+// Multiple fields
+const users = await prisma.user.findMany({
+  orderBy: [
+    { role: 'desc' },
+    { name: 'asc' }
+  ]
+})
+```
+
+### Order by relation
+
+```typescript
+const users = await prisma.user.findMany({
+  orderBy: {
+    posts: { _count: 'desc' }
+  }
+})
+```
+
+### Null handling
+
+```typescript
+const users = await prisma.user.findMany({
+  orderBy: {
+    name: { sort: 'asc', nulls: 'last' }
+  }
+})
+```
+
+## take & skip
+
+Pagination:
+
+```typescript
+// First page
+const users = await prisma.user.findMany({
+  take: 10,
+  skip: 0
+})
+
+// Second page
+const users = await prisma.user.findMany({
+  take: 10,
+  skip: 10
+})
+```
+
+### Negative take (reverse)
+
+```typescript
+const lastUsers = await prisma.user.findMany({
+  take: -10,
+  orderBy: { id: 'asc' }
+})
+// Returns last 10 users
+```
+
+## cursor
+
+Cursor-based pagination:
+
+```typescript
+// First page
+const firstPage = await prisma.user.findMany({
+  take: 10,
+  orderBy: { id: 'asc' }
+})
+
+// Next page using cursor
+const nextPage = await prisma.user.findMany({
+  take: 10,
+  skip: 1,  // Skip the cursor record
+  cursor: { id: firstPage[firstPage.length - 1].id },
+  orderBy: { id: 'asc' }
+})
+```
+
+## distinct
+
+Return unique values:
+
+```typescript
+const cities = await prisma.user.findMany({
+  distinct: ['city'],
+  select: { city: true }
+})
+```
+
+### Multiple distinct fields
+
+```typescript
+const locations = await prisma.user.findMany({
+  distinct: ['city', 'country']
+})
+```

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

@@ -0,0 +1,194 @@
+# Raw Queries
+
+Execute raw SQL when Prisma's query API isn't sufficient.
+
+## $queryRaw
+
+Execute SELECT queries and get typed results:
+
+```typescript
+const users = await prisma.$queryRaw`
+  SELECT * FROM "User" WHERE email LIKE ${'%@prisma.io'}
+`
+```
+
+### With type
+
+```typescript
+type User = { id: number; email: string; name: string | null }
+
+const users = await prisma.$queryRaw<User[]>`
+  SELECT id, email, name FROM "User" WHERE role = ${'ADMIN'}
+`
+```
+
+### Dynamic table/column names
+
+Use `Prisma.raw()` for identifiers (not safe for user input):
+
+```typescript
+import { Prisma } from '../generated/client'
+
+const column = 'email'
+const users = await prisma.$queryRaw`
+  SELECT ${Prisma.raw(column)} FROM "User"
+`
+```
+
+### With Prisma.sql
+
+Build queries dynamically:
+
+```typescript
+import { Prisma } from '../generated/client'
+
+const email = 'alice@prisma.io'
+const query = Prisma.sql`SELECT * FROM "User" WHERE email = ${email}`
+const users = await prisma.$queryRaw(query)
+```
+
+### Join multiple SQL fragments
+
+```typescript
+import { Prisma } from '../generated/client'
+
+const conditions = [
+  Prisma.sql`role = ${'ADMIN'}`,
+  Prisma.sql`verified = ${true}`
+]
+
+const users = await prisma.$queryRaw`
+  SELECT * FROM "User" 
+  WHERE ${Prisma.join(conditions, ' AND ')}
+`
+```
+
+## $executeRaw
+
+Execute INSERT, UPDATE, DELETE (returns affected count):
+
+```typescript
+const count = await prisma.$executeRaw`
+  UPDATE "User" SET verified = true WHERE email LIKE ${'%@prisma.io'}
+`
+console.log(`Updated ${count} users`)
+```
+
+### Delete example
+
+```typescript
+const deleted = await prisma.$executeRaw`
+  DELETE FROM "User" WHERE "deletedAt" < ${thirtyDaysAgo}
+`
+```
+
+### Insert example
+
+```typescript
+const inserted = await prisma.$executeRaw`
+  INSERT INTO "Log" (message, level, timestamp)
+  VALUES (${message}, ${level}, ${new Date()})
+`
+```
+
+## $queryRawUnsafe / $executeRawUnsafe
+
+For fully dynamic queries (use with caution!):
+
+```typescript
+// ⚠️ SQL injection risk - only use with trusted input
+const table = 'User'
+const users = await prisma.$queryRawUnsafe(
+  `SELECT * FROM "${table}" WHERE id = $1`,
+  userId
+)
+```
+
+### Parameterized unsafe query
+
+```typescript
+const result = await prisma.$executeRawUnsafe(
+  'UPDATE "User" SET name = $1 WHERE id = $2',
+  'Alice',
+  1
+)
+```
+
+## SQL Injection Prevention
+
+### Safe (parameterized)
+
+```typescript
+// ✅ User input is parameterized
+const email = userInput
+const users = await prisma.$queryRaw`
+  SELECT * FROM "User" WHERE email = ${email}
+`
+```
+
+### Unsafe (concatenation)
+
+```typescript
+// ❌ SQL injection vulnerability!
+const email = userInput
+const users = await prisma.$queryRawUnsafe(
+  `SELECT * FROM "User" WHERE email = '${email}'`
+)
+```
+
+## Database-Specific Features
+
+### PostgreSQL
+
+```typescript
+// Array operations
+const users = await prisma.$queryRaw`
+  SELECT * FROM "User" WHERE 'admin' = ANY(roles)
+`
+
+// JSON operations
+const users = await prisma.$queryRaw`
+  SELECT * FROM "User" WHERE metadata->>'theme' = 'dark'
+`
+```
+
+### MySQL
+
+```typescript
+// Full-text search
+const posts = await prisma.$queryRaw`
+  SELECT * FROM Post WHERE MATCH(title, content) AGAINST(${searchTerm})
+`
+```
+
+## Transactions with Raw Queries
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  await tx.$executeRaw`UPDATE "Account" SET balance = balance - ${amount} WHERE id = ${senderId}`
+  await tx.$executeRaw`UPDATE "Account" SET balance = balance + ${amount} WHERE id = ${recipientId}`
+})
+```
+
+## Handling Results
+
+### BigInt handling
+
+PostgreSQL returns BigInt for COUNT:
+
+```typescript
+const result = await prisma.$queryRaw<[{ count: bigint }]>`
+  SELECT COUNT(*) as count FROM "User"
+`
+const count = Number(result[0].count)
+```
+
+### Date handling
+
+```typescript
+type Result = { createdAt: Date }
+const users = await prisma.$queryRaw<Result[]>`
+  SELECT "createdAt" FROM "User"
+`
+// createdAt is already a Date object
+```