@prismakit/cli 3.2.0 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismakit/cli",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "description": "CLI for PrismaKit — generate modules, validate compose, install agent skills",
   "license": "Apache-2.0",
   "engines": {
@@ -28,8 +28,15 @@
     "LICENSE",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
   "dependencies": {
-    "@prismakit/core": "3.2.0"
+    "@prismakit/core": "workspace:*"
   },
   "peerDependencies": {
     "@prismakit/core": ">=3.2.0 <4"
@@ -56,12 +63,5 @@
     "prismakit",
     "cursor",
     "skills"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist"
-  }
-}
+  ]
+}

package/skills/prismakit/SKILL.md

@@ -32,7 +32,7 @@ Violations are bugs. Enforce with `@prismakit/eslint-plugin` + this skill.
 | 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 |
+| Relations in `select` | `model` + Prisma meta loaded (or `scalarFields` when meta unavailable) |
 | ESLint | `prismakit.configs.recommended` |
 
 ## Layers
@@ -64,7 +64,7 @@ Helpers may inject repositories — never the Prisma client.
 ## Create a repository (core)
 
 ```typescript
-import { Prisma, PrismaClient } from '@prisma/client';
+import { PrismaClient } from '@prisma/client';
 import { createRepository } from '@prismakit/core';
 import { RedisCacheAdapter } from '@prismakit/redis';
 
@@ -72,9 +72,8 @@ 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
+  lock: true, // table + columns resolved from Prisma schema meta
 });
 
 const prisma = new PrismaClient();
@@ -82,16 +81,18 @@ const cache = new RedisCacheAdapter({ prefix: 'myapp' });
 export const users = new UserRepoClass({ prisma, cache });
 ```
 
-`defineRepository` and `createPrismaRepository` are aliases of `createRepository`.
+`defineRepository` is an alias of `createRepository` in core. Note: `createPrismaRepository` is also an alias in core, but in `@prismakit/nestjs` it aliases `createInjectableRepository` instead — avoid using it to prevent confusion.
+
+**NestJS apps:** use `createDefineRepo` / `defineAppRepo` with app-wide cache defaults instead — see skill `prismakit-nestjs`.
 
 | 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'] }`. |
+| `scalarFields` | Usually `Prisma.XScalarFieldEnum`. **Optional** when `schemaPath` / DMMF meta is loaded (default since 3.1). |
+| `cache` | `CacheOptions` or `true` (uses app defaults when bound via `createDefineRepo`). |
 | `lock` | `true` / client key / `@@map` table / `{ tableName, columns }`. |
 | `primaryKey` | Override only. Defaults to schema `@id` / `@@id` (composite `string[]`) or `id`. |
-| `schemaPath` | Path to `schema.prisma` when meta is not loaded globally. |
+| `schemaPath` | Path to `schema.prisma` when meta is not loaded globally. Default: `prisma/schema.prisma`. |
 | `getDelegate` | Optional. Defaults to `(c) => c[model]`. |
 
 Put files under `**/repositories/**`. Keep Prisma client construction under `**/infrastructure/prisma/**`.
@@ -122,7 +123,8 @@ await users.getFirst({
 | `getMany` | array (`take` / `skip` / `orderBy`) |
 | `getManyPaginate` | `{ data, meta: { page, pageSize, totalItems, totalPages } }` |
 | `getManyCursor` | `{ data, nextCursor, hasMore }` |
-| `count` / `exists` | `{ count }` / `{ exists }` |
+| `getThrowFirst` | first match; throws if missing |
+| `count` / `exists` | `number` / `boolean` |
 | `aggregate` / `groupBy` | Prisma delegate results |
 
 `id` is `string` or `Record<string, string>` for composite PKs (object form for `@@id([a,b])`).
@@ -133,8 +135,11 @@ await users.getFirst({
 
 | Method | Default `invalidate` |
 |--------|----------------------|
-| `create` / `createMany` | `queries` |
-| `updateById` / `updateMany` / `upsert` / `deleteById` / `deleteMany` | `all` |
+| `create` / `createMany` / `createManyAndReturn` | `queries` |
+| `updateById` / `update` / `updateMany` / `updateManyAndReturn` | `all` |
+| `upsert` / `upsertMany` | `all` |
+| `deleteById` / `delete` / `deleteMany` | `all` |
+| `queryRaw` / `executeRaw` | none (raw SQL — no cache) |
 
 ```typescript
 await users.updateById({
@@ -239,8 +244,9 @@ Allowed Prisma usage: `**/repositories/**`, `**/infrastructure/prisma/**`. Rules
 
 ## Observability
 
-- Core: `setTelemetry({ enabled, onEvent })` or Nest `telemetry` / `queryLog.slowThreshold`.
+- Core: `setTelemetry({ enabled, onEvent, slowThreshold })` or Nest `telemetry` / `queryLog.slowThreshold`.
 - Optional: `@prismakit/opentelemetry` → `createPrismaKitTelemetry({ slowThreshold })`.
+- Events: `cache.hit` / `cache.miss` / `cache.bypass` / `cache.invalidate` / `cache.error`, `compose.*`, `lock.*`, `stampede.*`, `query.complete` / `query.slow`.
 
 ## Clean code
 

package/skills/prismakit/examples.md

@@ -6,7 +6,7 @@ Copy-paste patterns for `@prismakit/core`. Contract: [SKILL.md](SKILL.md).
 
 ```typescript
 // src/modules/users/repositories/user.repository.ts
-import { Prisma } from '@prisma/client';
+import { Prisma } from '@prisma/client'; // or generated client path for Prisma 7
 import { createRepository } from '@prismakit/core';
 
 const DAY = 86_400;
@@ -23,7 +23,7 @@ export const userSelectPresets = {
 
 export const UserRepoClass = createRepository({
   model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum,
+  // scalarFields: optional when schemaPath/DMMF meta is loaded (default since 3.1)
   cache: {
     ttl: DAY,
     nullTtl: 60,
@@ -40,7 +40,7 @@ export type UserRepository = InstanceType<typeof UserRepoClass>;
 
 ```typescript
 // src/infrastructure/prisma/repos.ts
-import { PrismaClient } from '@prisma/client';
+import { PrismaClient } from '@prisma/client'; // or generated client for Prisma 7
 import { RedisCacheAdapter } from '@prismakit/redis';
 import { UserRepoClass } from '../../modules/users/repositories/user.repository';
 

package/skills/prismakit/reference.md

@@ -29,7 +29,7 @@ pnpm add -D @prismakit/eslint-plugin @prismakit/cli
 createRepository(options) → new RepoClass(deps: RepositoryDeps)
 ```
 
-Aliases: `defineRepository`, `createPrismaRepository`.
+Alias: `defineRepository`. (`createPrismaRepository` is also an alias in core but maps to `createInjectableRepository` in `@prismakit/nestjs` — avoid it to prevent confusion.)
 
 `RepositoryDeps`: `{ prisma, cache?, registry?, autoCompose? }`.
 
@@ -58,12 +58,13 @@ All methods accept optional `tx`. Cached repos also accept cache fields (see bel
 |--------|------------|---------|
 | `getById` | `id`, `select?`, `lock?`, `setCache?` | `T \| null` |
 | `getThrowById` | same | `T` (throws if missing) |
-| `getFirst` | `where?`, `select?`, `lock?`, `setCache?`, `cacheTags?` | `T \| null` |
+| `getFirst` | `where?`, `select?`, `lock?`, `setCache?`, `cacheTags?`, `orderBy?` | `T \| null` |
+| `getThrowFirst` | same as `getFirst` | `T` (throws if missing) |
 | `getMany` | `where?`, `select?`, `orderBy?`, `take?`, `skip?`, `lock?`, `setCache?`, `cacheTags?` | `T[]` |
 | `getManyPaginate` | `where?`, `select?`, `orderBy?`, `page?`, `pageSize?`, `setCache?`, `cacheTags?` | `PaginatedResult<T>` |
 | `getManyCursor` | `where?`, `select?`, `orderBy?`, `cursor?`, `take?`, `skip?`, `setCache?`, `cacheTags?` | `CursorPage<T>`; with `cursor`, default `skip: 1` |
-| `count` | `where?`, `select?`, `setCache?`, `cacheTags?` | `{ count: number }` |
-| `exists` | `where?`, `setCache?`, `cacheTags?` | `{ exists: boolean }` |
+| `count` | `where?`, `setCache?`, `cacheTags?` | `number` |
+| `exists` | `where?`, `setCache?`, `cacheTags?` | `boolean` |
 | `aggregate` | Prisma aggregate args + `setCache?`, `cacheTags?` | delegate result |
 | `groupBy` | Prisma groupBy args + `setCache?`, `cacheTags?` | delegate result |
 
@@ -86,6 +87,13 @@ All methods accept optional `tx`. Cached repos also accept cache fields (see bel
 | `upsert` | `where`, `create`, `update`, `select?`, `invalidate?`, `tags?` | `all` | `T` |
 | `deleteById` | `id`, `select?`, `invalidate?`, `tags?` | `all` | `T` |
 | `deleteMany` | `where`, `invalidate?`, `tags?` | `all` | `{ count }` |
+| `update` | `where`, `data`, `select?`, `invalidate?`, `tags?` | `all` | `T` |
+| `delete` | `where`, `select?`, `invalidate?`, `tags?` | `all` | `T` |
+| `createManyAndReturn` | `data[]`, `select?`, `skipDuplicates?`, `invalidate?`, `tags?` | `queries` | `T[]` |
+| `updateManyAndReturn` | `where`, `data`, `select?`, `invalidate?`, `tags?` | `all` | `T[]` |
+| `upsertMany` | `data[]`, `skipDuplicates?`, `invalidate?`, `tags?` | `all` | `{ count }` |
+| `queryRaw` | `sql`, `...params` | — | raw result |
+| `executeRaw` | `sql`, `...params` | — | `number` (affected rows) |
 
 Mutation `tags`: `string[] | null | undefined | ((result) => string[] | null | undefined)`.
 
@@ -112,7 +120,7 @@ await repo.invalidateCache({ id?: string; tags?: string[] });
 | `ttl` | `86400` | Entity TTL (seconds). |
 | `nullTtl` | — | Negative cache for null results. |
 | `sensitiveFields` | `['password']` | Selects containing these never cache. |
-| `methods` | — | Per-method `{ enabled?, ttl? }` for `getById`, `getThrowById`, `getFirst`, `getMany`, `getManyPaginate`. |
+| `methods` | — | Per-method `{ enabled?, ttl? }` for `getById`, `getThrowById`, `getFirst`, `getThrowFirst`, `getMany`, `getManyPaginate`, `getManyCursor`, `count`, `exists`, `aggregate`, `groupBy`. |
 | `defaultSetCache` | `false` | Reads cache unless caller passes `setCache: false`. |
 | `stampede` | see below | Per-repo stampede overrides. |
 | `compression` | — | Hint for adapters (`'none' \| 'zstd' \| 'lz4'`). Redis adapter uses `'none' \| 'gzip'`. |
@@ -237,12 +245,13 @@ import { setTelemetry } from '@prismakit/core';
 setTelemetry({
   enabled: true,
   onEvent: (event) => { /* metrics */ },
+  slowThreshold: 500, // emits query.slow for queries ≥ this ms
 });
 ```
 
 | Type | When |
 |------|------|
-| `cache.hit` / `cache.miss` / `cache.bypass` / `cache.invalidate` | Cache-aside path |
+| `cache.hit` / `cache.miss` / `cache.bypass` / `cache.invalidate` / `cache.error` | Cache-aside path |
 | `compose.start` / `compose.complete` | Auto-compose (`queryCount`, `durationMs`) |
 | `lock.acquired` / `lock.waited` / `lock.timeout` | Row locks |
 | `stampede.locked` / `stampede.waited` / `stampede.fallthrough` | Stampede protection |
@@ -312,7 +321,6 @@ const autoCompose = new AutoComposer(registry);
 
 const UserRepo = createRepository({
   model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum,
   cache: { ttl: 86_400 },
 });
 const users = new UserRepo({ prisma, cache, registry, autoCompose });

package/skills/prismakit-nestjs/SKILL.md

@@ -23,7 +23,6 @@ pnpm add -D @prismakit/eslint-plugin @prismakit/cli
 import { Module } from '@nestjs/common';
 import { PrismaKitModule } from '@prismakit/nestjs';
 import { RedisCacheAdapter } from '@prismakit/redis';
-import { Prisma } from '@prisma/client';
 
 @Module({
   imports: [
@@ -45,37 +44,65 @@ export class AppModule {}
 
 ## Factory (one default)
 
-Bind `Prisma.TypeMap` once, then define repos with runtime options only.
+Bind `Prisma.TypeMap` once with app-wide cache defaults, then define repos with per-model overrides only.
 
 ```typescript
-// src/infrastructure/prisma/define-repo.ts
+// src/infrastructure/prisma/define-app-repo.ts
 import { createDefineRepo } from '@prismakit/nestjs';
-import type { Prisma } from '@prisma/client';
+import type { Prisma } from '@prisma/client'; // or generated client path
 
-export const defineRepo = createDefineRepo<Prisma.TypeMap>();
+const DAY = 86_400;
+
+export const defineAppRepo = createDefineRepo<Prisma.TypeMap>({
+  cache: {
+    ttl: DAY,
+    nullTtl: 60,
+    defaultSetCache: true,
+  },
+});
 ```
 
 ```typescript
 // src/modules/users/repositories/user.repository.ts
-import { Prisma } from '@prisma/client';
-import { defineRepo } from '../../../infrastructure/prisma/define-repo';
-
-const DAY = 86_400;
+import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
 
-export class UserRepository extends defineRepo({
+export class UserRepository extends defineAppRepo({
   model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum,
-  cache: { ttl: DAY, nullTtl: 60, sensitiveFields: ['password'] },
-  lock: true,
+  cache: {
+    defaultSetCache: false,       // auth lookups pass setCache explicitly
+    sensitiveFields: ['password'],
+    methods: { getFirst: { enabled: false } },
+  },
 }) {}
 ```
 
+```typescript
+// src/modules/category/repositories/category.repository.ts
+import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
+
+export class CategoryRepository extends defineAppRepo({
+  model: 'category',
+  cache: true, // inherits app-wide defaults (ttl, nullTtl, defaultSetCache)
+}) {}
+```
+
+```typescript
+// Uncached repo — TypeScript omits setCache / invalidateCache
+import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
+
+export class AuditLogRepository extends defineAppRepo({
+  model: 'auditLog',
+}) {}
+```
+
+`scalarFields` is **optional** when `schemaPath` or DMMF meta is loaded (default since 3.1). Omit it in new repos.
+
 Escape hatches (do not use as the app default):
 
 - `defineInjectableRepository` from `@prismakit/nestjs` (package alias `defineRepository`) — phantoms + payload HKT when TypeMap is unavailable.
 - `createInjectableRepository` without a types bag — thin, results are `unknown`. Alias: `createPrismaRepository`.
 
-Do not import `defineRepo` from `@prismakit/nestjs` in apps that already bind `createDefineRepo` as `defineRepo`.
+Do not import `defineRepo` from `@prismakit/nestjs` in apps that already bind `createDefineRepo` as `defineAppRepo`.
 
 ## Register and inject
 
@@ -216,7 +243,7 @@ Reference app: [starter-prismakit-nestjs](https://github.com/fikiap23/starter-pr
 
 ## Clean code (Nest)
 
-- One `defineRepo` binder under `src/infrastructure/prisma/`. Do not call `createDefineRepo` per feature.
+- One `defineAppRepo` binder under `src/infrastructure/prisma/`. Do not call `createDefineRepo` per feature.
 - Feature modules own their repository providers; do not make every repo global.
 - Controllers stay HTTP-only: map DTO → service method. No repository calls in controllers.
 - Select presets live next to the repository (`minimal` / `general` / `withPassword`).

package/skills/prismakit-nestjs/examples.md

@@ -47,24 +47,30 @@ export class AppModule {}
 
 Prisma 5/6: pass `dmmf: Prisma.dmmf` instead of (or in addition to skipping) `schemaPath`. Prisma 7: `schemaPath` only.
 
-## 2. TypeMap binder
+## 2. TypeMap binder with app-wide cache defaults
 
 ```typescript
-// src/infrastructure/prisma/define-repo.ts
+// src/infrastructure/prisma/define-app-repo.ts
 import { createDefineRepo } from '@prismakit/nestjs';
-import type { Prisma } from '@prisma/client';
+import type { Prisma } from 'src/infrastructure/prisma/prisma-client';
 
-export const defineRepo = createDefineRepo<Prisma.TypeMap>();
+const DAY = 86_400;
+
+export const defineAppRepo = createDefineRepo<Prisma.TypeMap>({
+  cache: {
+    ttl: DAY,
+    nullTtl: 60,
+    defaultSetCache: true,
+  },
+});
 ```
 
 ## 3. Feature repository + select presets
 
 ```typescript
 // src/modules/users/repositories/user.repository.ts
-import { Prisma } from '@prisma/client';
-import { defineRepo } from '../../../infrastructure/prisma/define-repo';
-
-const DAY = 86_400;
+import { Prisma } from 'src/infrastructure/prisma/prisma-client';
+import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
 
 export const userSelectPresets = {
   minimal: { id: true } satisfies Prisma.UserSelect,
@@ -80,18 +86,24 @@ export const userSelectPresets = {
   } satisfies Prisma.UserSelect,
 };
 
-export const UserRepository = defineRepo({
+export class UserRepository extends defineAppRepo({
   model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum,
   cache: {
-    ttl: DAY,
-    nullTtl: 60,
+    defaultSetCache: false,       // auth lookups pass setCache explicitly
     sensitiveFields: ['password'],
     methods: { getFirst: { enabled: false } },
   },
-  lock: true,
-});
-export interface UserRepository extends InstanceType<typeof UserRepository> {}
+}) {}
+```
+
+```typescript
+// Simple cached repo — inherits app-wide defaults
+import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
+
+export class CategoryRepository extends defineAppRepo({
+  model: 'category',
+  cache: true,
+}) {}
 ```
 
 ## 4. Feature module + thin controller + service

package/skills/prismakit-nestjs/reference.md

@@ -84,11 +84,11 @@ await this.tx.execTx<User, Prisma.TransactionClient>(async (tx) => { /* ... */ }
 | `defineInjectableRepository({ model, select, create, update, where, orderBy, payload, ... })` | TypeMap unavailable. Package aliases: `defineRepository`. |
 | `createInjectableRepository({ model, ... })` | Thin / untyped. Results `unknown` unless `toPayload` is supplied. Alias: `createPrismaRepository`. |
 
-`createDefineRepo` runtime options: `model`, `scalarFields?`, `primaryKey?`, `cache?`, `lock?`, `schemaPath?`.
+`createDefineRepo` accepts app-wide defaults (`cache`, `schemaPath`) and per-repo options: `model`, `scalarFields?` (optional since 3.1), `primaryKey?`, `cache?` (`true` inherits app defaults), `lock?`, `schemaPath?`.
 
 When `cache` is set, the returned API includes `setCache` / `cacheTags` / `invalidate` / `tags` / `invalidateCache`. Otherwise those fields are omitted from the type (`HasCacheFromOptions`).
 
-`createDefineRepo` / `RepositoryApiFromTypeMap` includes the full runtime surface: `createMany`, `updateMany`, `upsert`, `deleteMany`, `lock` + `orderBy` on `getFirst`, `lock` on `getMany`, and composite-PK `id` on `*ById`. `primaryKey` is optional — composite `@@id` is read from schema meta.
+`createDefineRepo` / `RepositoryApiFromTypeMap` includes the full runtime surface: `create`, `createMany`, `createManyAndReturn`, `update`, `updateById`, `updateMany`, `updateManyAndReturn`, `upsert`, `upsertMany`, `delete`, `deleteById`, `deleteMany`, `getThrowFirst`, `count`, `exists`, `aggregate`, `groupBy`, `getManyCursor`, `queryRaw`, `executeRaw`, `lock` + `orderBy` on `getFirst`, `lock` on `getMany`, and composite-PK `id` on `*ById`. `primaryKey` is optional — composite `@@id` is read from schema meta.
 
 Export the instance type with interface merging so `cache` on options gates `setCache` (a same-name `type` alias collapses to `any`):
 
@@ -108,7 +108,7 @@ type Of<S> = S extends Prisma.UserSelect
 
 export const UserRepository = defineInjectableRepository({
   model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum,
+  scalarFields: Prisma.UserScalarFieldEnum, // required for this escape hatch (meta not typed)
   select: null! as Prisma.UserSelect,
   create: null! as Prisma.UserCreateInput,
   update: null! as Prisma.UserUpdateInput,
@@ -135,7 +135,7 @@ Prefer importing Nest-only APIs from `@prismakit/nestjs` and core-only helpers f
 src/
   app.module.ts                          # PrismaKitModule.forRootAsync
   infrastructure/prisma/
-    define-repo.ts                       # createDefineRepo<Prisma.TypeMap>()
+    define-app-repo.ts                   # createDefineRepo<Prisma.TypeMap>({ cache defaults })
     prisma.service.ts                    # client construction only
   modules/<feature>/
     <feature>.module.ts                  # providers: [Service, XRepository]