@prismakit/cli 2.2.3 → 3.0.0

package/skills/prismakit/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: prismakit
+description: >-
+  PrismaKit data-access contract for Prisma apps: repository-only access via createRepository,
+  cache-aside with setCache/invalidate, auto-compose relations, row locks, telemetry, prismakit CLI,
+  and @prismakit/eslint-plugin. Use when working with @prismakit/core, files under repositories/,
+  CacheAdapter/Redis caching of Prisma reads, or when code injects PrismaClient outside a repository.
+---
+
+# PrismaKit
+
+Framework-agnostic Prisma repository kit. Not a Prisma fork. Only repositories talk to Prisma.
+
+NestJS apps: also load skill `prismakit-nestjs` after this contract.
+
+## Non-negotiables
+
+Violations are bugs. Enforce with `@prismakit/eslint-plugin` + this skill.
+
+| Forbidden | Why |
+|-----------|-----|
+| `PrismaClient` / `PrismaService` in services, helpers, controllers, processors | Bypasses cache, compose, invalidation |
+| `prisma.<model>.*` outside `**/repositories/**` | Same |
+| `$transaction` in Nest feature code | Use `TransactionService.execTx` |
+| `setCache: true` on auth / uniqueness `getFirst` | Stale nulls / race hazards |
+| Caching selects with `password` (or other `sensitiveFields`) | Security |
+| Row `lock` without `tx` | Lock must live inside a transaction |
+| Prisma `include` for relations | Use relation keys in `select` (auto-compose) |
+
+| Required | How |
+|----------|-----|
+| Reads/writes | `*Repository` from `createRepository` / Nest factories |
+| Tx writes | `invalidate: 'none'` then `invalidateCache` after commit |
+| User-facing reads | `setCache: true` when the repo has cache config |
+| Relations in `select` | `model` + `scalarFields` or loaded Prisma meta |
+| ESLint | `prismakit.configs.recommended` |
+
+## Layers
+
+```
+Controller / route handler → Service → Helper → Repository → Prisma / CacheAdapter
+```
+
+Helpers may inject repositories — never the Prisma client.
+
+## Decision table
+
+| Task | Use |
+|------|-----|
+| New repository | `createRepository` (core) or Nest `defineRepo` — see `prismakit-nestjs` |
+| User-facing get by id | `getThrowById` / `getById` + `setCache: true` |
+| Existence / uniqueness / auth | `getFirst` — **no** `setCache` |
+| List | `getMany` + `setCache: true` + optional `cacheTags` |
+| Paginated list | `getManyPaginate` |
+| Create / update / delete | matching mutation; default invalidation is enough outside tx |
+| Multi-step write | one transaction; pass `tx` into every repo call |
+| `SELECT … FOR UPDATE` | `lock: { mode: 'update' }` **inside** `tx` |
+| Load relations | nested objects in `select`, not Prisma `include` |
+
+## Create a repository (core)
+
+```typescript
+import { Prisma, PrismaClient } from '@prisma/client';
+import { createRepository } from '@prismakit/core';
+import { RedisCacheAdapter } from '@prismakit/redis';
+
+const DAY = 86_400;
+
+const UserRepoClass = createRepository({
+  model: 'user',
+  scalarFields: Prisma.UserScalarFieldEnum,
+  cache: { ttl: DAY, nullTtl: 60, sensitiveFields: ['password'] },
+  lock: true, // table + columns from Prisma meta
+});
+
+const prisma = new PrismaClient();
+const cache = new RedisCacheAdapter({ prefix: 'myapp' });
+export const users = new UserRepoClass({ prisma, cache });
+```
+
+`defineRepository` and `createPrismaRepository` are aliases of `createRepository`.
+
+| Option | Description |
+|--------|-------------|
+| `model` | Prisma client key (`prisma.user` → `'user'`). Needed for cache + compose. |
+| `scalarFields` | Usually `Prisma.XScalarFieldEnum`. Enables select-split + compose. Optional if DMMF/schema meta is loaded. |
+| `cache` | `CacheOptions` or `true` → `{ ttl: 86400, sensitiveFields: ['password'] }`. |
+| `lock` | `true` / client key / `@@map` table / `{ tableName, columns }`. |
+| `primaryKey` | `string` or `string[]` (composite). Defaults to meta PK or `id`. |
+| `schemaPath` | Path to `schema.prisma` when meta is not loaded globally. |
+| `getDelegate` | Optional. Defaults to `(c) => c[model]`. |
+
+Put files under `**/repositories/**`. Keep Prisma client construction under `**/infrastructure/prisma/**`.
+
+## Reads
+
+Always pass an explicit `select`. Never rely on “fetch all columns”.
+
+```typescript
+await users.getThrowById({
+  id,
+  select: { id: true, email: true, name: true },
+  setCache: true,
+});
+
+await users.getFirst({
+  where: { email },
+  select: { id: true, password: true },
+  // no setCache — auth / uniqueness
+});
+```
+
+| Method | Returns |
+|--------|---------|
+| `getById` | payload or `null` |
+| `getThrowById` | payload; throws if missing |
+| `getFirst` | first match or `null` |
+| `getMany` | array (`take` / `skip` / `orderBy`) |
+| `getManyPaginate` | `{ data, meta: { page, pageSize, totalItems, totalPages } }` |
+
+`id` is `string` or `Record<string, string>` for composite PKs.
+
+## Writes
+
+| Method | Default `invalidate` |
+|--------|----------------------|
+| `create` / `createMany` | `queries` |
+| `updateById` / `updateMany` / `upsert` / `deleteById` / `deleteMany` | `all` |
+
+```typescript
+await users.updateById({
+  id,
+  data: { name: 'Ada' },
+  select: { id: true, name: true },
+});
+```
+
+## Cache
+
+A read uses the cache **only when all of these are true**:
+
+1. `setCache: true` (or repo `cache.defaultSetCache: true` and caller did not pass `false`)
+2. Repository has `model` + `cache` config
+3. No `tx` (transactions never cache)
+4. Method is not disabled in `cache.methods`
+5. `select` does not include a sensitive field (default includes `password`)
+
+If Redis is down, `RedisCacheAdapter` **fails open** — queries still hit Prisma.
+
+| Scenario | `setCache` |
+|----------|------------|
+| API detail / list | `true` |
+| Auth, uniqueness, JWT lookup | omit / `false` |
+| Inside `tx` | ignored |
+
+Empty `cacheModels` allowlist is **fail-open**. In production, register allowed model keys; a cached repo whose model is missing from the list throws at init.
+
+`setCache` / `cacheTags` / `invalidate` / `invalidateCache` exist on the type **only** when the repo has `cache` config. Do not force them on uncached repos.
+
+## Transactions (plain Node)
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  await users.updateById({ tx, id, data, invalidate: 'none' });
+});
+await users.invalidateCache({ id });
+```
+
+Wrap this in an app helper so call sites stay consistent. Nest: `TransactionService.execTx` (skill `prismakit-nestjs`).
+
+Never invalidate cache inside the transaction. If the tx rolls back, cache must still be valid.
+
+## Auto-compose
+
+Relations in `select` load through other registered repositories — not Prisma `include`.
+
+```typescript
+await posts.getThrowById({
+  id,
+  select: {
+    id: true,
+    title: true,
+    author: { select: { id: true, name: true } },
+  },
+  setCache: true,
+});
+```
+
+Requirements: source repo has `model`; `scalarFields` **or** Prisma meta loaded (`loadPrismaMetaFromDmmf(Prisma.dmmf)` on Prisma 5/6, `loadPrismaMetaFromSchema('prisma/schema.prisma')` on Prisma 7); related model repos are registered.
+
+AutoComposer injects the target primary key into nested selects even if omitted. Relation field names resolve from schema / DMMF meta (`schemaPath` defaults to `prisma/schema.prisma`).
+
+## Row locks
+
+Repo must declare `lock`. Call must pass `tx`. Default mode is `noKeyUpdate`. `skipLocked` cannot combine with `nowait`. Prefer short transactions.
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  const row = await wallets.getById({
+    tx,
+    id,
+    select: { id: true, balance: true },
+    lock: { mode: 'update' },
+  });
+  await wallets.updateById({
+    tx,
+    id,
+    data: { balance: row!.balance - amount },
+    invalidate: 'none',
+  });
+});
+await wallets.invalidateCache({ id });
+```
+
+## CLI and ESLint
+
+```bash
+npx prismakit generate <name> --cache
+npx prismakit generate <name> --cache --full --route <path>
+npx prismakit validate --auto-register
+```
+
+```js
+// eslint.config.mjs
+import prismakit from '@prismakit/eslint-plugin';
+export default [prismakit.configs.recommended];
+```
+
+Allowed Prisma usage: `**/repositories/**`, `**/infrastructure/prisma/**`. Rules: `no-prisma-service-outside-repos`, `no-direct-prisma-delegate`, `require-transaction-service`.
+
+## Clean code
+
+- One repository per Prisma model, file `*.repository.ts` under `repositories/`.
+- Select presets as `satisfies Prisma.XSelect`: `minimal` (no cache), `general` (API, cacheable), `withPassword` (auth only, never cached). Keep presets next to the repo; controllers never build selects.
+- Named TTL constants (`const DAY = 86_400`), not magic numbers scattered in call sites.
+- Pass `tx` into **every** repo call in a unit of work. Do not mix cached reads with half-committed writes.
+- Tests: `@prismakit/memory` `MemoryCacheAdapter`. Production: `@prismakit/redis`.
+
+## Anti-patterns (BAD → GOOD)
+
+```typescript
+// BAD — Prisma in a service
+constructor(private readonly prisma: PrismaClient) {}
+await this.prisma.user.findUnique({ where: { id } });
+await this.prisma.$transaction(async (tx) => { /* ... */ });
+await this.prisma.post.findUnique({ include: { author: true } });
+await users.getFirst({ where: { email }, select: { id: true }, setCache: true });
+await users.getById({ id, select: { password: true }, setCache: true });
+await wallets.getById({ id, select: { id: true }, lock: { mode: 'update' } }); // no tx
+await users.updateById({ tx, id, data }); // auto-invalidate inside tx
+
+// GOOD
+constructor(private readonly users: UserRepository) {}
+await this.users.getById({ id, select: { id: true, email: true }, setCache: true });
+await prisma.$transaction(async (tx) => {
+  await this.users.updateById({ tx, id, data, invalidate: 'none' });
+});
+await this.users.invalidateCache({ id });
+await this.posts.getById({
+  id,
+  select: { id: true, author: { select: { id: true, name: true } } },
+  setCache: true,
+});
+await this.users.getFirst({ where: { email }, select: { id: true } }); // no setCache
+await this.users.getFirst({
+  where: { email },
+  select: { id: true, password: true }, // auth; never setCache
+});
+await prisma.$transaction(async (tx) => {
+  await this.wallets.getById({
+    tx, id, select: { id: true, balance: true }, lock: { mode: 'update' },
+  });
+});
+```
+
+## Before you finish
+
+Copy and complete [review-checklist.md](review-checklist.md).
+
+- Method/options detail: [reference.md](reference.md)
+- End-to-end snippets: [examples.md](examples.md)
+- NestJS wiring: skill `prismakit-nestjs`

package/skills/prismakit/examples.md

@@ -0,0 +1,238 @@
+# PrismaKit core examples
+
+Copy-paste patterns for `@prismakit/core`. Contract: [SKILL.md](SKILL.md).
+
+## 1. New repository from scratch
+
+```typescript
+// src/modules/users/repositories/user.repository.ts
+import { Prisma } from '@prisma/client';
+import { createRepository } from '@prismakit/core';
+
+const DAY = 86_400;
+
+export const userSelectPresets = {
+  minimal: { id: true } satisfies Prisma.UserSelect,
+  general: { id: true, email: true, name: true } satisfies Prisma.UserSelect,
+  withPassword: {
+    id: true,
+    email: true,
+    password: true,
+  } satisfies Prisma.UserSelect,
+};
+
+export const UserRepoClass = createRepository({
+  model: 'user',
+  scalarFields: Prisma.UserScalarFieldEnum,
+  cache: {
+    ttl: DAY,
+    nullTtl: 60,
+    sensitiveFields: ['password'],
+    methods: {
+      getFirst: { enabled: false },
+    },
+  },
+  lock: true,
+});
+
+export type UserRepository = InstanceType<typeof UserRepoClass>;
+```
+
+```typescript
+// src/infrastructure/prisma/repos.ts
+import { PrismaClient } from '@prisma/client';
+import { RedisCacheAdapter } from '@prismakit/redis';
+import { UserRepoClass } from '../../modules/users/repositories/user.repository';
+
+const prisma = new PrismaClient();
+const cache = new RedisCacheAdapter({
+  url: process.env.REDIS_URL,
+  prefix: process.env.CACHE_PREFIX ?? 'myapp',
+});
+
+export const users = new UserRepoClass({ prisma, cache });
+export { prisma };
+```
+
+## 2. User-facing read vs uniqueness check
+
+```typescript
+import { users } from '../../infrastructure/prisma/repos';
+import { userSelectPresets } from './repositories/user.repository';
+
+export async function getProfile(id: string) {
+  return users.getThrowById({
+    id,
+    select: userSelectPresets.general,
+    setCache: true,
+  });
+}
+
+export async function assertEmailFree(email: string) {
+  const existing = await users.getFirst({
+    where: { email },
+    select: userSelectPresets.minimal,
+    // never setCache on uniqueness
+  });
+  if (existing) throw new Error('email taken');
+}
+
+export async function verifyLogin(email: string) {
+  return users.getFirst({
+    where: { email },
+    select: userSelectPresets.withPassword,
+    // never cache password selects
+  });
+}
+```
+
+## 3. Paginated list with cache tags
+
+```typescript
+const page = await products.getManyPaginate({
+  where: { categoryId, status: 'ACTIVE' },
+  select: { id: true, name: true, price: true },
+  orderBy: { createdAt: 'desc' },
+  page: 1,
+  pageSize: 20,
+  setCache: true,
+  cacheTags: [`category:${categoryId}`],
+});
+// page.data, page.meta.totalItems, page.meta.totalPages
+
+await products.updateById({
+  id,
+  data: { price: 1999 },
+  select: { id: true },
+  tags: [`category:${categoryId}`],
+});
+```
+
+## 4. Transaction + invalidate after commit
+
+```typescript
+import { prisma, users } from '../../infrastructure/prisma/repos';
+
+export async function renameUser(id: string, name: string) {
+  const result = await prisma.$transaction(async (tx) => {
+    return users.updateById({
+      tx,
+      id,
+      data: { name },
+      select: { id: true, name: true },
+      invalidate: 'none',
+    });
+  });
+  await users.invalidateCache({ id });
+  return result;
+}
+```
+
+Prefer wrapping `$transaction` + `afterCommit` in one app helper so every call site stays consistent.
+
+## 5. Transfer with row lock
+
+```typescript
+export async function transfer(fromId: string, toId: string, amount: number) {
+  const moved = await prisma.$transaction(async (tx) => {
+    const from = await wallets.getById({
+      tx,
+      id: fromId,
+      select: { id: true, balance: true },
+      lock: { mode: 'update' },
+    });
+    const to = await wallets.getById({
+      tx,
+      id: toId,
+      select: { id: true, balance: true },
+      lock: { mode: 'update' },
+    });
+    if (!from || !to) throw new Error('wallet missing');
+    if (from.balance < amount) throw new Error('insufficient funds');
+
+    await wallets.updateById({
+      tx,
+      id: fromId,
+      data: { balance: from.balance - amount },
+      invalidate: 'none',
+    });
+    await wallets.updateById({
+      tx,
+      id: toId,
+      data: { balance: to.balance + amount },
+      invalidate: 'none',
+    });
+    return { fromId, toId, amount };
+  });
+
+  await wallets.invalidateCache({ id: fromId });
+  await wallets.invalidateCache({ id: toId });
+  return moved;
+}
+```
+
+## 6. Nested select (auto-compose)
+
+Related repositories must be constructed and registered before the read.
+
+```typescript
+const post = await posts.getThrowById({
+  id,
+  select: {
+    id: true,
+    title: true,
+    author: { select: { name: true } }, // PK injected; no Prisma include
+    comments: {
+      select: {
+        id: true,
+        body: true,
+        author: { select: { name: true } },
+      },
+    },
+  },
+  setCache: true,
+});
+```
+
+## 7. Unit test with MemoryCacheAdapter
+
+```typescript
+import { createRepository } from '@prismakit/core';
+import { MemoryCacheAdapter } from '@prismakit/memory';
+
+const UserRepo = createRepository({
+  model: 'user',
+  scalarFields: { id: 'id', email: 'email', name: 'name' },
+  cache: { ttl: 60 },
+});
+
+const prisma = {
+  user: {
+    findUnique: async ({ where }: { where: { id: string } }) =>
+      where.id === 'u1' ? { id: 'u1', email: 'a@b.c', name: 'Ada' } : null,
+    findUniqueOrThrow: async ({ where }: { where: { id: string } }) => {
+      if (where.id !== 'u1') throw new Error('missing');
+      return { id: 'u1', email: 'a@b.c', name: 'Ada' };
+    },
+  },
+};
+
+const cache = new MemoryCacheAdapter({ prefix: 'test' });
+const users = new UserRepo({ prisma, cache });
+
+const select = { id: true, email: true, name: true };
+
+const a = await users.getThrowById({ id: 'u1', select, setCache: true });
+const b = await users.getThrowById({ id: 'u1', select, setCache: true }); // cache hit
+```
+
+## 8. Scaffold with CLI
+
+```bash
+npx prismakit generate product --cache
+npx prismakit generate product --cache --full --route products
+npx prismakit generate product --prisma-import src/infrastructure/prisma/client --dry-run
+npx prismakit validate --auto-register
+```
+
+After repo-only generate: register the class (Nest `providers`, or `new RepoClass({ prisma, cache })` in plain Node). After `--full`: import the feature module in `app.module.ts`.