feat: warn on Effect 3 syntax in @customType; docs + cleanup

The cascade of "GeneratedSchema not assignable to Schema.Top" errors a
consumer hit was NOT a helper-type defect — it was a version-resolution
trap ('prisma-effect-kysely': '*' resolves to the stable 5.x line, not the
6.0.0-next prerelease, because npm/pnpm exclude prereleases from ranges) plus
v3-syntax @customType annotations passed through verbatim. The helper types
were correct as published in 6.0.0-next.1.

Generator-side response (warn-only, never rewrite — transforming arbitrary
user TS is unsafe):
- detectLegacyEffectV3Syntax() in src/utils/annotations.ts: matches known
  v3 @customType patterns (filters now under .check(Schema.is*); variadic
  Union/Tuple/multi-Literal now take arrays; removed Schema.UUID/DateFromSelf;
  optionalWith). The orchestrator scans every field's @customType at generate
  time and prints field-level v4 upgrade hints to stderr.
- README: v3->v4 @customType table + the '*'-resolves-to-stable gotcha (pin
  exact 6.0.0-next.x or use overrides/resolutions).

Docs accuracy: DB interface is Schema.Schema.Type<typeof Model> (not
Selectable<Model>); Json maps to recursive JsonValue (not Schema.Unknown);
Type-safety note scopes the load-bearing helper casts vs cast-free output.

Cleanup: remove dead internal type aliases (MutableInsert/MutableUpdate ==
CustomInsertable/CustomUpdateable; ExtractInsertBaseType == ExtractInsertType).
Bump dev/test effect pin to 4.0.0-beta.70.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: samuelho-dev

.changeset/legacy-customtype-detector.md

@@ -0,0 +1,20 @@
+---
+'prisma-effect-kysely': patch
+---
+
+Warn on Effect 3 syntax in `@customType` annotations.
+
+`@customType(...)` expressions are emitted verbatim, so an Effect 3 expression
+(e.g. `Schema.Number.pipe(Schema.int(), Schema.between(1, 5))` or the variadic
+`Schema.Union(A, B)`) compiles against Effect 3 but breaks against Effect 4. The
+generator now scans `@customType` strings at `prisma generate` time and prints a
+warning that names the field and the v4 replacement — for filters
+(`Schema.int()` → `Schema.check(Schema.isInt())`, `Schema.between(a, b)` →
+`Schema.check(Schema.isBetween({ minimum, maximum }))`, etc.), variadic
+combinators (`Schema.Union(a, b)` → `Schema.Union([a, b])`), and removed schemas
+(`Schema.UUID`, `Schema.DateFromSelf`). It only warns; it never rewrites the
+expression (regex-transforming arbitrary user TypeScript is unsafe).
+
+Also bumps the dev/test Effect pin to `4.0.0-beta.70` and documents that
+consumers must pin the exact `6.0.0-next.x` version — a `"*"` range resolves to
+the stable `5.x` line because npm/pnpm exclude prereleases from version ranges.

CLAUDE.md

@@ -50,7 +50,7 @@ Three files in the configured output directory:
 - **types.ts** — direct exports (no underscore prefix, no wrapper functions):
   - Branded ID schema + type per model
   - Model `Schema.Struct` + type alias
-  - `DB` interface using `Selectable<Model>` per table (respects `@@map`)
+  - `DB` interface using `Schema.Schema.Type<typeof Model>` per table (preserves the `__select__/__insert__/__update__` brands Kysely needs; respects `@@map`)
 - **index.ts** — re-exports
 
 ## Generated shape
@@ -67,7 +67,7 @@ export const User = Schema.Struct({
 export type User = typeof User;
 
 export interface DB {
-  User: Selectable<User>;
+  User: Schema.Schema.Type<typeof User>;
 }
 ```
 
@@ -97,36 +97,37 @@ Prisma stores `A`/`B` columns; we emit semantic snake_case fields on the struct,
 
 ## Type mappings
 
-| Prisma      | Effect               | Notes                                         |
-| ----------- | -------------------- | --------------------------------------------- |
-| String      | `Schema.String`      | UUID → `Schema.String.check(Schema.isUUID())` |
-| Int / Float | `Schema.Number`      |                                               |
-| BigInt      | `Schema.BigInt`      | native bigint encode (no string coercion)     |
-| Decimal     | `Schema.String`      | precision                                     |
-| Boolean     | `Schema.Boolean`     |                                               |
-| DateTime    | `Schema.Date`        | native Date both sides (Effect 4)             |
-| Json        | `Schema.Unknown`     |                                               |
-| Bytes       | `Schema.Uint8Array`  |                                               |
-| Enum        | imported enum schema | `Schema.Enum(...)`                            |
+| Prisma      | Effect                | Notes                                         |
+| ----------- | --------------------- | --------------------------------------------- |
+| String      | `Schema.String`       | UUID → `Schema.String.check(Schema.isUUID())` |
+| Int / Float | `Schema.Number`       |                                               |
+| BigInt      | `Schema.BigInt`       | native bigint encode (no string coercion)     |
+| Decimal     | `Schema.String`       | precision                                     |
+| Boolean     | `Schema.Boolean`      |                                               |
+| DateTime    | `Schema.Date`         | native Date both sides (Effect 4)             |
+| Json        | recursive `JsonValue` | from `prisma-effect-kysely`                   |
+| Bytes       | `Schema.Uint8Array`   |                                               |
+| Enum        | imported enum schema  | `Schema.Enum(...)`                            |
 
 Arrays → `Schema.Array(t)`. Nullable → `Schema.NullOr(t)`.
 
 ## Type safety principles
 
-- Zero coercion — exact DMMF types, no `as` casts
+- Zero coercion in DMMF→type mapping — exact DMMF types, no string parsing of types
+- The runtime `Selectable`/`Insertable`/`Updateable` helpers use `as unknown as` casts (load-bearing: a dynamically-rebuilt `Schema.Struct` has no statically-checkable shape — see the note above the Schema Functions section in `helpers.ts`); generated OUTPUT contains no casts
 - UUID detection from DMMF, not string parsing
 - Field defaults validated via DMMF structure
 - Strict mode (tsconfig)
 
 ## Package exports
 
-| Entry         | Contents                                          |
-| ------------- | ------------------------------------------------- |
-| `.`           | `Selectable`, `Insertable`, `Updateable`, helpers |
-| `./generator` | Prisma generator binary entry                     |
-| `./kysely`    | `getSchemas`, `columnType`, `generated`, types    |
-| `./error`     | `NotFoundError`, `QueryError`, `DatabaseError`    |
-| `./runtime`   | All runtime utilities                             |
+| Entry         | Contents                                                                              |
+| ------------- | ------------------------------------------------------------------------------------- |
+| `.`           | `Selectable`, `Insertable`, `Updateable`, helpers                                     |
+| `./generator` | Prisma generator binary entry                                                         |
+| `./kysely`    | `columnType`, `generated`, `JsonValue`, `Selectable`/`Insertable`/`Updateable`, types |
+| `./error`     | `NotFoundError`, `QueryError`, `DatabaseError`                                        |
+| `./runtime`   | All runtime utilities                                                                 |
 
 ## Testing patterns
 
@@ -150,6 +151,8 @@ can `Effect.catchTag` cleanly.
 - Generator must be rebuilt before `prisma generate` picks up changes
 - Test fixtures: `src/__tests__/fixtures/test.prisma`
 - Generated headers include timestamp + edit warning
-- Direct exports only — never reintroduce underscore prefixes or wrapper functions in generated code (`getSchemas` remains in runtime API, not in output)
+- Direct exports only — generated code exports schemas directly (`export const User = Schema.Struct(...)`); never reintroduce underscore prefixes or wrapper functions in the output
 - Run `bun run test:emit` after touching any generator emit string — it generates against the fixture and type-checks the emitted code against the installed Effect (unit tests only string-match, they don't compile output)
-- `effect` targets **4.x (beta)**, peer dep `^4.0.0-beta`, dev pin `4.0.0-beta.68`. `src/kysely/helpers.ts` uses the public `Schema.Struct.fields` API (not `effect/SchemaAST` internals — those were reworked in v4). Key v4 names: `Schema.Codec` (was `Schema.Schema`), `Schema.Top` (was `Schema.Schema.All`), `Schema.revealCodec` (was `asSchema`), `.annotate()` (was `.annotations()`), `Schema.Date` (was `DateFromSelf`), `Schema.Union([...])` (was variadic), `Schema.encodeKeys` (was `propertySignature(...).pipe(fromKey(...))`).
+- `effect` targets **4.x (beta)**, peer dep `^4.0.0-beta`, dev pin `4.0.0-beta.70`. `src/kysely/helpers.ts` uses the public `Schema.Struct.fields` API (not `effect/SchemaAST` internals — those were reworked in v4). Key v4 names: `Schema.Codec` (was `Schema.Schema`), `Schema.Top` (was `Schema.Schema.All`), `Schema.revealCodec` (was `asSchema`), `.annotate()` (was `.annotations()`), `Schema.Date` (was `DateFromSelf`), `Schema.Union([...])` (was variadic), `Schema.encodeKeys` (was `propertySignature(...).pipe(fromKey(...))`).
+- `@customType(...)` strings are emitted verbatim and must be valid Effect 4 syntax. `detectLegacyEffectV3Syntax()` in `src/utils/annotations.ts` warns (never rewrites) on known v3 patterns at generate time. v3 filters → `.check(Schema.is*)`; variadic `Union`/`Tuple`/multi-`Literal` → array form.
+- Consumers must pin the exact `6.0.0-next.x` version — a `"*"` range resolves to the stable `5.x` line (npm/pnpm exclude prereleases from ranges), which silently pulls the v3 types.

README.md

@@ -22,11 +22,18 @@ bun add prisma-effect-kysely@next effect@beta
 
 > **Effect 4 support is a pre-release.** It requires `effect@^4.0.0-beta` and is
 > published under the `next` dist-tag, not `latest`. It is **tested against
-> `effect@4.0.0-beta.68`**; later betas may introduce breaking Schema changes. A
+> `effect@4.0.0-beta.70`**; later betas may introduce breaking Schema changes. A
 > generator-output compile check (`bun run test:emit`) guards the emitted code
 > against the installed Effect, but pin `effect` if you need stability during the
 > beta. The `next` line will be promoted to `latest` when Effect 4 goes stable.
 >
+> **Pin the exact version — do not use `"*"` or `"latest"`.** A `"prisma-effect-kysely": "*"`
+> (or any range) dependency resolves to the **stable** `5.x` line, NOT the
+> pre-release, because npm/pnpm semver excludes prereleases from ranges. In a
+> workspace, depend on `"6.0.0-next.x"` exactly (or add a `pnpm.overrides` /
+> `resolutions` entry). Symptom of getting this wrong: the v3 `5.x` types resolve
+> and consumers see cascading `Schema.Top` / `unknown` type errors.
+>
 > Effect 4 and Effect 3 are not interchangeable: the generated output uses
 > Effect-4-only Schema APIs (`Schema.Date`, `Schema.String.check(Schema.isUUID())`,
 > `Schema.encodeKeys`, `Schema.Enum`, …). Stay on the `latest` line if you are on
@@ -135,6 +142,22 @@ model User {
 
 Supported on all Prisma scalar types.
 
+`@customType(...)` expressions are emitted **verbatim** — they must be valid
+Effect 4 syntax. The generator does not rewrite them, but it **warns** at
+`prisma generate` time when it detects Effect 3 syntax, pointing at the v4 form.
+Effect 4 moved all filters under `.check(Schema.is*)` and made the variadic
+combinators take an array:
+
+| Effect 3 (`@customType`)              | Effect 4                                                               |
+| ------------------------------------- | ---------------------------------------------------------------------- |
+| `Schema.Number.pipe(Schema.int())`    | `Schema.Number.pipe(Schema.check(Schema.isInt()))`                     |
+| `Schema.positive()`                   | `Schema.check(Schema.isGreaterThan(0))`                                |
+| `Schema.between(1, 5)`                | `Schema.check(Schema.isBetween({ minimum: 1, maximum: 5 }))`           |
+| `Schema.minLength(3)`                 | `Schema.check(Schema.isMinLength(3))`                                  |
+| `Schema.Union(A, B)`                  | `Schema.Union([A, B])`                                                 |
+| `Schema.Literal('a', 'b')`            | `Schema.Literals(['a', 'b'])` (single `Schema.Literal('x')` unchanged) |
+| `Schema.UUID` / `Schema.DateFromSelf` | `Schema.String.check(Schema.isUUID())` / `Schema.Date`                 |
+
 ## Implicit M2M Join Tables
 
 Prisma columns `A`/`B` map to semantic snake_case fields via `Schema.encodeKeys`:
@@ -148,13 +171,13 @@ export const ProductToProductTag = Schema.Struct({
 
 ## Package Exports
 
-| Entry                            | Contents                                            |
-| -------------------------------- | --------------------------------------------------- |
-| `prisma-effect-kysely`           | Type utilities + runtime helpers (default import)   |
-| `prisma-effect-kysely/generator` | Prisma generator binary entry                       |
-| `prisma-effect-kysely/kysely`    | `getSchemas`, `columnType`, `generated`, type utils |
-| `prisma-effect-kysely/error`     | `NotFoundError`, `QueryError`, `DatabaseError`      |
-| `prisma-effect-kysely/runtime`   | All runtime utilities                               |
+| Entry                            | Contents                                           |
+| -------------------------------- | -------------------------------------------------- |
+| `prisma-effect-kysely`           | Type utilities + runtime helpers (default import)  |
+| `prisma-effect-kysely/generator` | Prisma generator binary entry                      |
+| `prisma-effect-kysely/kysely`    | `columnType`, `generated`, `JsonValue`, type utils |
+| `prisma-effect-kysely/error`     | `NotFoundError`, `QueryError`, `DatabaseError`     |
+| `prisma-effect-kysely/runtime`   | All runtime utilities                              |
 
 ## Development
 

bun.lock

@@ -110,7 +110,7 @@
     "@typescript-eslint/parser": "^8.59.1",
     "@vitest/coverage-v8": "^4.1.5",
     "@vitest/eslint-plugin": "^1.6.16",
-    "effect": "4.0.0-beta.68",
+    "effect": "4.0.0-beta.70",
     "eslint": "^10.0.0",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",

package.json

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { detectLegacyEffectV3Syntax } from '../utils/annotations';
+
+describe('detectLegacyEffectV3Syntax', () => {
+  describe('flags Effect 3 filter syntax', () => {
+    it('Schema.int()', () => {
+      const hints = detectLegacyEffectV3Syntax('Schema.Number.pipe(Schema.int())');
+      expect(hints).toHaveLength(1);
+      expect(hints[0]).toContain('Schema.check(Schema.isInt())');
+    });
+
+    it('Schema.between() — and notes the v4 object-arg shape', () => {
+      const hints = detectLegacyEffectV3Syntax('Schema.Number.pipe(Schema.between(1, 5))');
+      expect(hints[0]).toContain('isBetween({ minimum, maximum })');
+    });
+
+    it('Schema.positive() maps to isGreaterThan(0)', () => {
+      const hints = detectLegacyEffectV3Syntax('Schema.Number.pipe(Schema.positive())');
+      expect(hints[0]).toContain('Schema.check(Schema.isGreaterThan(0))');
+    });
+
+    it('the real creativetoolkits case: int + between together → two hints', () => {
+      const hints = detectLegacyEffectV3Syntax(
+        'Schema.Number.pipe(Schema.int(), Schema.between(1, 5))'
+      );
+      expect(hints).toHaveLength(2);
+    });
+
+    it('greaterThan is matched without also matching greaterThanOrEqualTo', () => {
+      const gt = detectLegacyEffectV3Syntax('Schema.Number.pipe(Schema.greaterThan(0))');
+      expect(gt).toHaveLength(1);
+      expect(gt[0]).toContain('isGreaterThan(n)');
+      const gte = detectLegacyEffectV3Syntax('Schema.Number.pipe(Schema.greaterThanOrEqualTo(0))');
+      expect(gte).toHaveLength(1);
+      expect(gte[0]).toContain('isGreaterThanOrEqualTo(n)');
+    });
+  });
+
+  describe('flags variadic combinators (v4 takes an array)', () => {
+    it('Schema.Union(a, b) — the real licensing.prisma case', () => {
+      const hints = detectLegacyEffectV3Syntax('Schema.Union(SellerId, UserId)');
+      expect(hints).toHaveLength(1);
+      expect(hints[0]).toContain('Schema.Union([a, b, …])');
+    });
+
+    it('Schema.Tuple(a, b)', () => {
+      const hints = detectLegacyEffectV3Syntax('Schema.Tuple(Schema.String, Schema.Number)');
+      expect(hints[0]).toContain('Schema.Tuple([a, b, …])');
+    });
+
+    it('multi-arg Schema.Literal → Literals', () => {
+      const hints = detectLegacyEffectV3Syntax("Schema.Literal('a', 'b')");
+      expect(hints[0]).toContain('Schema.Literals([a, b, …])');
+    });
+  });
+
+  describe('flags removed/renamed schemas', () => {
+    it('Schema.DateFromSelf', () => {
+      expect(detectLegacyEffectV3Syntax('Schema.DateFromSelf')[0]).toContain('Schema.Date');
+    });
+    it('Schema.UUID', () => {
+      expect(detectLegacyEffectV3Syntax('Schema.UUID')[0]).toContain(
+        'Schema.String.check(Schema.isUUID())'
+      );
+    });
+    it('Schema.optionalWith', () => {
+      expect(
+        detectLegacyEffectV3Syntax('Schema.optionalWith(Schema.String, { exact: true })')[0]
+      ).toContain('Schema.optionalKey');
+    });
+  });
+
+  describe('does NOT flag valid v4 syntax (no false positives)', () => {
+    it.each([
+      'Schema.String',
+      'Schema.Number.check(Schema.isInt())',
+      'Schema.Number.check(Schema.isBetween({ minimum: 1, maximum: 5 }))',
+      'Schema.String.check(Schema.isUUID()).pipe(Schema.brand("UserId"))',
+      'Schema.Union([SellerId, UserId])',
+      'Schema.Literals(["a", "b"])',
+      "Schema.Literal('single')", // single literal is unchanged in v4
+      'Schema.Array(Schema.Number).check(Schema.isLengthBetween(3, 3))',
+      'Schema.Date',
+    ])('clean: %s', (expr) => {
+      expect(detectLegacyEffectV3Syntax(expr)).toEqual([]);
+    });
+  });
+});

src/__tests__/legacy-annotation-detection.test.ts

@@ -2,6 +2,7 @@ import type { GeneratorOptions } from '@prisma/generator-helper';
 import { EffectGenerator } from '../effect/generator.js';
 import { KyselyGenerator } from '../kysely/generator.js';
 import { PrismaGenerator } from '../prisma/generator.js';
+import { detectLegacyEffectV3Syntax, extractEffectTypeOverride } from '../utils/annotations.js';
 import { FileManager } from '../utils/file-manager.js';
 import {
   type GeneratorConfig,
@@ -47,6 +48,7 @@ export class GeneratorOrchestrator {
    */
   async generate(options: GeneratorOptions) {
     this.logStart(options);
+    this.warnLegacyAnnotations(options);
 
     // Check if multi-domain mode is enabled
     if (isMultiDomainEnabled(this.config)) {
@@ -244,6 +246,32 @@ export class GeneratorOrchestrator {
     }
   }
 
+  /**
+   * Scan every field's `@customType(...)` annotation for Effect 3 syntax and warn
+   * (to stderr, which Prisma surfaces to the user). `@customType` strings are
+   * emitted verbatim, so a v3 expression silently breaks once compiled against
+   * Effect 4. We never rewrite — only point at the v4 replacement.
+   */
+  private warnLegacyAnnotations(options: GeneratorOptions) {
+    const warnings: string[] = [];
+    for (const model of options.dmmf.datamodel.models) {
+      for (const field of model.fields) {
+        const override = extractEffectTypeOverride(field);
+        if (!override) continue;
+        for (const hint of detectLegacyEffectV3Syntax(override)) {
+          warnings.push(`  ${model.name}.${field.name}: ${hint}`);
+        }
+      }
+    }
+
+    if (warnings.length > 0) {
+      console.warn(
+        `[prisma-effect-kysely] @customType annotations use Effect 3 syntax that does not ` +
+          `compile against Effect 4. Update them in your Prisma schema:\n${warnings.join('\n')}`
+      );
+    }
+  }
+
   /**
    * Log generation completion
    */