The best way to control Claude Code, Codex and more from any computer or phone

main
md 1,436 lines 47.9 KB
Rendered Raw
1 # Schema: Migration from v3
2
3 This document maps v3 Schema APIs to their v4 equivalents. Simple renames and argument changes are covered in the summary table below. More complex migrations have dedicated sections with code examples.
4
5 ## Migration types
6
7 - **auto** — mechanical find-and-replace, safe to auto-apply
8 - **semi-auto** — follows a clear pattern but needs structural changes
9 - **manual** — requires case-by-case decisions, flag for human review
10 - **removed** — no v4 equivalent
11
12 ## Summary table
13
14 | v3 API | v4 API | Migration type |
15 | ----------------------------------------------- | ----------------------------------------------------------------------------- | ----------------- |
16 | `asSchema(schema)` | `revealCodec(schema)` | rename |
17 | `encodedSchema(schema)` | `toEncoded(schema)` | rename |
18 | `typeSchema(schema)` | `toType(schema)` | rename |
19 | `compose(schemaB)` | `decodeTo(schemaB)` | rename |
20 | `annotations(ann)` | `annotate(ann)` | rename |
21 | `decodingFallback` annotation | `catchDecoding(...)` | rename |
22 | `parseJson()` | `fromJsonString(Unknown)` | rename |
23 | `parseJson(schema)` | `fromJsonString(schema)` | rename |
24 | `pattern(regex)` | `check(isPattern(regex))` | rename |
25 | `nonEmptyString` | `isNonEmpty` | rename |
26 | `BigIntFromSelf` | `BigInt` | rename |
27 | `SymbolFromSelf` | `Symbol` | rename |
28 | `URLFromSelf` | `URL` | rename |
29 | `RedactedFromSelf` | `Redacted` | rename |
30 | `Redacted` | `RedactedFromValue` | rename |
31 | `EitherFromSelf` | `Result` | rename |
32 | `DateFromNumber` | `DateFromMillis` | rename |
33 | `Date` | `DateFromString` | restructure |
34 | `decodeUnknown` | `decodeUnknownEffect` | rename |
35 | `decode` | `decodeEffect` | rename |
36 | `decodeUnknownEither` | `decodeUnknownExit` | rename |
37 | `decodeEither` | `decodeExit` | rename |
38 | `encodeUnknown` | `encodeUnknownEffect` | rename |
39 | `encode` | `encodeEffect` | rename |
40 | `encodeUnknownEither` | `encodeUnknownExit` | rename |
41 | `encodeEither` | `encodeExit` | rename |
42 | `asserts(schema)(input)` | `asserts(schema, input)` | semi-auto |
43 | `Literal(null)` | `Null` | restructure |
44 | `Literal("a", "b")` | `Literals(["a", "b"])` | variadic-to-array |
45 | `pickLiteral("a", "b")` | `Literals(...).pick(["a", "b"])` | restructure |
46 | `Union(A, B)` | `Union([A, B])` | variadic-to-array |
47 | `Tuple(A, B)` | `Tuple([A, B])` | variadic-to-array |
48 | `TemplateLiteral(A, B)` | `TemplateLiteral([A, B])` | variadic-to-array |
49 | `TemplateLiteralParser(A, B)` | `TemplateLiteralParser(schema.parts)` | restructure |
50 | `Record({ key, value })` | `Record(key, value)` | restructure |
51 | `filter(predicate)` | `check(makeFilter(predicate))` | restructure |
52 | `filter(refinement)` | `refine(refinement)` | restructure |
53 | `UUID` | `String.check(isUUID())` | restructure |
54 | `ULID` | `String.check(isULID())` | restructure |
55 | `pick("a")` | `mapFields(Struct.pick(["a"]))` | restructure |
56 | `omit("a")` | `mapFields(Struct.omit(["a"]))` | restructure |
57 | `partial` | `mapFields(Struct.map(Schema.optional))` | restructure |
58 | `partialWith({ exact: true })` | `mapFields(Struct.map(Schema.optionalKey))` | restructure |
59 | `required(schema)` | `schema.mapFields(Struct.map(Schema.requiredKey))` | restructure |
60 | `extend(structB)` | `mapFields(Struct.assign(fieldsB))` or `fieldsAssign(fieldsB)` | restructure |
61 | `transform(from, to, { decode, encode })` | `from.pipe(decodeTo(to, SchemaTransformation.transform({ decode, encode })))` | restructure |
62 | `transformOrFail(from, to, { decode, encode })` | `from.pipe(decodeTo(to, { decode: SchemaGetter.transformEffect(...), ... }))` | restructure |
63 | `transformLiteral(from, to)` | `Literal(from).transform(to)` | restructure |
64 | `transformLiterals([0,"a"], [1,"b"])` | `Literals([0, 1]).transform(["a", "b"])` | restructure |
65 | `attachPropertySignature("k", "v")` | `mapFields(f => ({...f, k: tagDefaultOmit("v")}))` | restructure |
66 | `validate*` | removed (use `decode*` + `toType`) | removed |
67 | `keyof` | — | removed |
68 | `NonEmptyArrayEnsure` | — | removed |
69 | `withDefaults` | — | removed |
70 | `Data(schema)` | — | removed |
71 | `optionalWith(schema, opts)` | varies by options (see [optionalWith](#optionalwith)) | manual |
72 | `optionalToOptional` | see [optional field transformations](#optional-field-transformations) | manual |
73 | `optionalToRequired` | see [optional field transformations](#optional-field-transformations) | manual |
74 | `requiredToOptional` | see [optional field transformations](#optional-field-transformations) | manual |
75 | `filterEffect` | see [filterEffect](#filtereffect) | manual |
76 | `fromKey` | see [rename](#rename) | manual |
77 | `rename({ a: "c" })` | see [rename](#rename) | manual |
78 | `format(schema)` | see [format](#format) | manual |
79 | `ParseResult.ArrayFormatter.formatError(error)` | see [ParseResult formatters](#parseresult-formatters) | manual |
80 | `declare` | see [declare](#declare) | manual |
81
82 ## Additional rename notes
83
84 ### `*FromSelf` renames
85
86 The following `*FromSelf` schemas have been renamed to drop the suffix:
87
88 `DateFromSelf` → `Date`, `DurationFromSelf` → `Duration`, `ChunkFromSelf` → `Chunk`, `ReadonlyMapFromSelf` → `ReadonlyMap`, `ReadonlySetFromSelf` → `ReadonlySet`, `HashMapFromSelf` → `HashMap`, `HashSetFromSelf` → `HashSet`, `BigDecimalFromSelf` → `BigDecimal`, `CauseFromSelf` → `Cause`, `ExitFromSelf` → `Exit`, `OptionFromSelf` → `Option`, `RegExpFromSelf` → `RegExp`
89
90 ### `Date` encoded contract
91
92 **Migration: restructure**
93
94 In v3, `Schema.Date` decoded an ISO date string to a `Date` and rejected invalid dates. In v4, `Schema.Date` is the renamed `Schema.DateFromSelf`, so it expects a valid `Date` as its encoded value. Existing code can still type-check after upgrading while no longer accepting the same input.
95
96 v3
97
98 ```ts
99 import { Schema } from "effect"
100
101 const DateFromIsoString = Schema.Date
102 ```
103
104 v4
105
106 ```ts
107 import { Schema } from "effect"
108
109 const DateFromIsoString = Schema.DateFromString
110 ```
111
112 `Schema.DateFromString` preserves the string-to-`Date` transformation and rejects strings that produce invalid dates.
113
114 ### Filter renames
115
116 All filters have been renamed with an `is` prefix and now use `check(...)` or `pipe(Schema.check(...))`:
117
118 `greaterThan` → `isGreaterThan`, `greaterThanOrEqualTo` → `isGreaterThanOrEqualTo`, `lessThan` → `isLessThan`, `lessThanOrEqualTo` → `isLessThanOrEqualTo`, `between` → `isBetween`, `int` → `isInt`, `multipleOf` → `isMultipleOf`, `finite` → `isFinite`, `minLength` → `isMinLength`, `maxLength` → `isMaxLength`, `length` → `isBetweenLength`
119
120 Note: `positive`, `negative`, `nonNegative`, `nonPositive` have been removed in v4.
121
122 ### Utility renames
123
124 `equivalence` → `toEquivalence`, `arbitrary` → [`Arbitrary.schema`](#migrating-from-the-fast-check-bridge-to-native-arbitrary) from `effect/Arbitrary`, `pretty` → `toFormatter`, `standardSchemaV1` → `toStandardSchemaV1`
125
126 ## Detailed migrations
127
128 ### Redacted
129
130 **Migration: rename with behavior distinction**
131
132 In v3, `Schema.Redacted(value)` decoded the raw encoded value and wrapped the decoded value in `Redacted`.
133
134 In v4, that behavior is named `Schema.RedactedFromValue(value)`.
135
136 v3
137
138 ```ts
139 import { Schema } from "effect"
140
141 const schema = Schema.Redacted(Schema.String)
142 const decode = Schema.decodeSync(schema)
143
144 decode("secret")
145 ```
146
147 v4
148
149 ```ts
150 import { Redacted, Schema } from "effect"
151
152 const schema = Schema.RedactedFromValue(Schema.String)
153 const decode = Schema.decodeSync(schema)
154
155 const redacted = decode("secret")
156 console.log(Redacted.value(redacted))
157 // secret
158 ```
159
160 `Schema.Redacted(value)` in v4 is the replacement for v3 `Schema.RedactedFromSelf(value)`: it expects the input to already be a `Redacted` value, so both `Type` and `Encoded` are `Redacted<...>`.
161
162 ### asserts signature
163
164 **Migration: semi-auto**
165
166 `Schema.asserts` now asserts an input directly instead of returning an assertion function.
167
168 v3
169
170 ```ts
171 import { Schema } from "effect"
172
173 const assertString = Schema.asserts(Schema.String)
174 assertString(input)
175 ```
176
177 v4
178
179 ```ts
180 import { Schema } from "effect"
181
182 Schema.asserts(Schema.String, input)
183 ```
184
185 ### validate* removal
186
187 **Migration: removed**
188
189 The `validate`, `validateEither`, `validatePromise`, `validateSync`, and `validateOption` APIs have been removed. Use `Schema.decode*` + `Schema.toType` instead.
190
191 ```ts
192 import { Schema } from "effect"
193
194 // v3: Schema.validateSync(Schema.String)(input)
195 // v4:
196 const validateSync = Schema.decodeSync(Schema.toType(Schema.String))
197 ```
198
199 ### Data removal
200
201 **Migration: removed**
202
203 `Schema.Data` has no v4 equivalent. Remove it. `Equal.equals` performs deep structural comparison on objects by default in v4, so `Schema.Data` is unnecessary.
204
205 ### pickLiterals
206
207 **Migration: auto**
208
209 v3
210
211 ```ts
212 import { Schema } from "effect"
213
214 const schema = Schema.Literal("a", "b", "c").pipe(Schema.pickLiteral("a", "b"))
215 ```
216
217 v4
218
219 ```ts
220 import { Schema } from "effect"
221
222 const schema = Schema.Literals(["a", "b", "c"]).pick(["a", "b"])
223 ```
224
225 ### TemplateLiteralParser
226
227 **Migration: semi-auto**
228
229 v3
230
231 ```ts
232 import { Schema } from "effect"
233
234 const schema = Schema.TemplateLiteral(Schema.String, ".", Schema.String)
235 const parser = Schema.TemplateLiteralParser(Schema.String, ".", Schema.String)
236 ```
237
238 v4
239
240 ```ts
241 import { Schema } from "effect"
242
243 const schema = Schema.TemplateLiteral([Schema.String, ".", Schema.String])
244 // use the `parts` property instead of repeating the template parts
245 const parser = Schema.TemplateLiteralParser(schema.parts)
246 ```
247
248 Behavior note: `TemplateLiteral` and `TemplateLiteralParser` match parts semantically. Checks on string, number, and bigint schema parts are applied while matching each segment, so refined parts can reject strings that would match the broader primitive shape.
249
250 ### format
251
252 **Migration: manual**
253
254 **New imports:** `SchemaRepresentation`
255
256 v3
257
258 ```ts
259 import { Schema } from "effect"
260
261 console.log(Schema.format(Schema.String))
262 // string
263 ```
264
265 v4
266
267 ```ts
268 import { Schema, SchemaRepresentation } from "effect"
269
270 const doc = SchemaRepresentation.toRepresentation(Schema.String.ast)
271 const multi = SchemaRepresentation.toMultiDocument(doc)
272 const codeDoc = SchemaRepresentation.toCodeDocument(multi)
273 console.log(codeDoc.codes[0].Type)
274 // string
275 ```
276
277 ### ParseResult formatters
278
279 **Migration: manual**
280
281 **New imports:** `SchemaIssue`
282
283 In v4, schema parsing fails with `Schema.SchemaError`, which contains a nested `SchemaIssue` in its `issue` field.
284
285 Use `SchemaIssue.makeFormatterStandardSchemaV1()(error.issue).issues` for the v3 `ParseResult.ArrayFormatter.formatError(error)` equivalent.
286
287 v3
288
289 ```ts
290 import { Either, ParseResult, Schema } from "effect"
291
292 const Person = Schema.Struct({
293 name: Schema.String,
294 age: Schema.Number
295 })
296
297 const decode = Schema.decodeUnknownEither(Person)
298
299 const result = decode({})
300 if (Either.isLeft(result)) {
301 console.error("Decoding failed:")
302 console.error(ParseResult.ArrayFormatter.formatErrorSync(result.left))
303 }
304 /*
305 Decoding failed:
306 [ { _tag: 'Missing', path: [ 'name' ], message: 'is missing' } ]
307 */
308 ```
309
310 v4
311
312 ```ts
313 import { Schema, SchemaIssue } from "effect"
314
315 const Person = Schema.Struct({
316 name: Schema.String,
317 age: Schema.Number
318 })
319
320 const decode = Schema.decodeUnknownSync(Person)
321
322 try {
323 decode({})
324 } catch (error) {
325 if (error instanceof Error) {
326 console.error("Decoding failed:")
327 if (SchemaIssue.isIssue(error.cause)) {
328 console.error(SchemaIssue.makeFormatterStandardSchemaV1()(error.cause).issues)
329 }
330 }
331 }
332 /*
333 Decoding failed:
334 [ { path: [ 'name' ], message: 'Missing key' } ]
335 */
336 ```
337
338 ### Record
339
340 **Migration: auto**
341
342 v3
343
344 ```ts
345 import { Schema } from "effect"
346
347 const schema = Schema.Record({ key: Schema.String, value: Schema.Number })
348 ```
349
350 v4
351
352 ```ts
353 import { Schema } from "effect"
354
355 const schema = Schema.Record(Schema.String, Schema.Number)
356 ```
357
358 Behavior note: dynamic record key schemas select matching own properties before the value schema is applied. Refined key schemas such as `Schema.String.check(...)`, `Schema.Int`, or checked template literals ignore properties that do not match the key schema; they do not validate the value at those ignored keys. For transformed key schemas, selection is based on encoded property names before selected keys are decoded.
359
360 ### pick / omit
361
362 **Migration: semi-auto**
363
364 **New imports:** `Struct`
365
366 v3
367
368 ```ts
369 import { Schema } from "effect"
370
371 const picked = Schema.Struct({ a: Schema.String, b: Schema.Number }).pipe(Schema.pick("a"))
372 const omitted = Schema.Struct({ a: Schema.String, b: Schema.Number }).pipe(Schema.omit("b"))
373 ```
374
375 v4
376
377 ```ts
378 import { Schema, Struct } from "effect"
379
380 const picked = Schema.Struct({ a: Schema.String, b: Schema.Number }).mapFields(Struct.pick(["a"]))
381 const omitted = Schema.Struct({ a: Schema.String, b: Schema.Number }).mapFields(Struct.omit(["b"]))
382 ```
383
384 ### partial / partialWith
385
386 **Migration: semi-auto**
387
388 **New imports:** `Struct`
389
390 - `Schema.partial` → `mapFields(Struct.map(Schema.optional))` (allows `undefined`)
391 - `Schema.partialWith({ exact: true })` → `mapFields(Struct.map(Schema.optionalKey))` (exact)
392
393 ```ts
394 import { Schema, Struct } from "effect"
395
396 const struct = Schema.Struct({ a: Schema.String, b: Schema.Number })
397
398 // v3: struct.pipe(Schema.partial)
399 const withUndefined = struct.mapFields(Struct.map(Schema.optional))
400
401 // v3: struct.pipe(Schema.partialWith({ exact: true }))
402 const exact = struct.mapFields(Struct.map(Schema.optionalKey))
403 ```
404
405 You can also make a subset of fields partial:
406
407 ```ts
408 import { Schema, Struct } from "effect"
409
410 const schema = Schema.Struct({ a: Schema.String, b: Schema.Number })
411 .mapFields(Struct.mapPick(["a"], Schema.optional))
412 ```
413
414 ### required
415
416 **Migration: semi-auto**
417
418 **New imports:** `Struct`
419
420 - `Schema.requiredKey`: makes `optionalKey` fields required; makes `optional` fields required as `T | undefined`
421 - `Schema.required`: makes `optional` fields required (removes `undefined`)
422
423 ```ts
424 import { Schema, Struct } from "effect"
425
426 const original = Schema.Struct({
427 a: Schema.optionalKey(Schema.String),
428 b: Schema.optionalKey(Schema.Number)
429 })
430
431 // v3: Schema.required(original)
432 const schema = original.mapFields(Struct.map(Schema.requiredKey))
433 // { readonly a: string; readonly b: number; }
434 ```
435
436 ### optional field transformations
437
438 **Migration: manual**
439
440 **New imports:** `SchemaGetter`
441
442 `optionalToOptional`, `optionalToRequired`, and `requiredToOptional` are all replaced by `Schema.decodeTo` + `SchemaGetter.transformOptional`.
443
444 The pattern: start with the encoded optionality (`optionalKey` or required), pipe to `decodeTo` with the decoded optionality, and provide `transformOptional` functions for decode/encode.
445
446 **Example** (v3 `optionalToRequired`: setting `null` as default for missing field)
447
448 v3
449
450 ```ts
451 import { Option, Schema } from "effect"
452
453 const schema = Schema.Struct({
454 a: Schema.optionalToRequired(Schema.String, Schema.NullOr(Schema.String), {
455 decode: Option.getOrElse(() => null),
456 encode: Option.liftPredicate((value) => value !== null)
457 })
458 })
459 ```
460
461 v4
462
463 ```ts
464 import { Option, Schema, SchemaGetter } from "effect"
465
466 const schema = Schema.Struct({
467 a: Schema.optionalKey(Schema.String).pipe(
468 Schema.decodeTo(Schema.NullOr(Schema.String), {
469 decode: SchemaGetter.transformOptional(Option.orElseSome(() => null)),
470 encode: SchemaGetter.transformOptional(Option.filter((value) => value !== null))
471 })
472 )
473 })
474 ```
475
476 **Example** (v3 `requiredToOptional`: empty string as missing value)
477
478 v3
479
480 ```ts
481 import { Option, Schema } from "effect"
482
483 const schema = Schema.Struct({
484 a: Schema.requiredToOptional(Schema.String, Schema.String, {
485 decode: Option.liftPredicate((s) => s !== ""),
486 encode: Option.getOrElse(() => "")
487 })
488 })
489 ```
490
491 v4
492
493 ```ts
494 import { Option, Schema, SchemaGetter } from "effect"
495
496 const schema = Schema.Struct({
497 a: Schema.String.pipe(
498 Schema.decodeTo(Schema.optionalKey(Schema.String), {
499 decode: SchemaGetter.transformOptional(Option.filter((value) => value !== "")),
500 encode: SchemaGetter.transformOptional(Option.orElseSome(() => ""))
501 })
502 )
503 })
504 ```
505
506 ### optionalWith
507
508 **Migration: manual**
509
510 **New imports:** `SchemaGetter`, `Predicate` (for nullable variants)
511
512 #### Decision tree
513
514 | v3 options | v4 pattern |
515 | ------------------------------------------ | ----------------------------------------------------------------------- |
516 | `{ exact: true }` | `optionalKey(schema)` |
517 | `{ default }` | `schema.pipe(withDecodingDefaultType(...))` |
518 | `{ exact: true, default }` | `schema.pipe(withDecodingDefaultTypeKey(...))` |
519 | `{ nullable: true }` | `optional(NullOr(schema))` + `decodeTo` + filter null |
520 | `{ nullable: true, exact: true }` | `optionalKey(NullOr(schema))` + `decodeTo` + filter null |
521 | `{ nullable: true, default }` | `optional(NullOr(schema))` + `decodeTo` + filter null + `orElseSome` |
522 | `{ nullable: true, exact: true, default }` | `optionalKey(NullOr(schema))` + `decodeTo` + filter null + `orElseSome` |
523
524 Key rules:
525
526 - `exact: true` → use `optionalKey` instead of `optional`
527 - `nullable: true` → wrap inner schema in `NullOr` and filter nulls via `Option.filter(Predicate.isNotNull)`
528 - `default` → use `withDecodingDefaultType` (or `withDecodingDefaultTypeKey` with `exact: true`)
529
530 #### Example: `{ exact: true }` (simplest case)
531
532 v3
533
534 ```ts
535 import { Schema } from "effect"
536
537 const schema = Schema.Struct({
538 a: Schema.optionalWith(Schema.NumberFromString, { exact: true })
539 })
540 ```
541
542 v4
543
544 ```ts
545 import { Schema } from "effect"
546
547 const schema = Schema.Struct({
548 a: Schema.optionalKey(Schema.NumberFromString)
549 })
550 ```
551
552 #### Example: `{ default }`
553
554 v3
555
556 ```ts
557 import { Schema } from "effect"
558
559 const schema = Schema.Struct({
560 a: Schema.optionalWith(Schema.String, { default: () => "" })
561 })
562 ```
563
564 v4
565
566 ```ts
567 import { Effect, Schema } from "effect"
568
569 const schema = Schema.Struct({
570 a: Schema.String.pipe(Schema.withDecodingDefaultType(Effect.succeed("")))
571 })
572 ```
573
574 #### Example: `{ exact: true, default }`
575
576 v3
577
578 ```ts
579 import { Schema } from "effect"
580
581 const schema = Schema.Struct({
582 a: Schema.optionalWith(Schema.String, { exact: true, default: () => "" })
583 })
584 ```
585
586 v4
587
588 ```ts
589 import { Effect, Schema } from "effect"
590
591 const schema = Schema.Struct({
592 a: Schema.String.pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed("")))
593 })
594 ```
595
596 #### Example: `{ nullable: true, exact: true, default }` (most complex case)
597
598 v3
599
600 ```ts
601 import { Schema } from "effect"
602
603 const schema = Schema.Struct({
604 a: Schema.optionalWith(Schema.NumberFromString, { nullable: true, default: () => -1, exact: true })
605 })
606 ```
607
608 v4
609
610 ```ts
611 import { Option, Predicate, Schema, SchemaGetter } from "effect"
612
613 const schema = Schema.Struct({
614 a: Schema.optionalKey(Schema.NullOr(Schema.NumberFromString)).pipe(
615 Schema.decodeTo(Schema.Number, {
616 decode: SchemaGetter.transformOptional((o) =>
617 o.pipe(Option.filter(Predicate.isNotNull), Option.orElseSome(() => -1))
618 ),
619 encode: SchemaGetter.required()
620 })
621 )
622 })
623 ```
624
625 ### pluck
626
627 **Migration: manual**
628
629 **New imports:** `SchemaGetter`, `Struct`
630
631 v3
632
633 ```ts
634 import { Schema } from "effect"
635
636 const schema = Schema.Struct({ a: Schema.String, b: Schema.Number }).pipe(Schema.pluck("a"))
637 ```
638
639 v4
640
641 ```ts
642 import { Schema, SchemaGetter, Struct } from "effect"
643
644 function pluck<P extends PropertyKey>(key: P) {
645 return <S extends Schema.Top>(
646 schema: Schema.Struct<{ [K in P]: S }>
647 ): Schema.decodeTo<Schema.toType<S>, Schema.Struct<{ [K in P]: S }>> => {
648 return schema.mapFields(Struct.pick([key])).pipe(
649 Schema.decodeTo(Schema.toType(schema.fields[key]), {
650 decode: SchemaGetter.transform((whole: any) => whole[key]),
651 encode: SchemaGetter.transform((value) => ({ [key]: value } as any))
652 })
653 )
654 }
655 }
656
657 const schema = Schema.Struct({ a: Schema.String, b: Schema.Number }).pipe(pluck("a"))
658 ```
659
660 ### extend
661
662 **Migration: semi-auto**
663
664 **New imports:** `Struct` (Struct case), `Tuple` (Union case)
665
666 #### Struct extends Struct
667
668 v3
669
670 ```ts
671 import { Schema } from "effect"
672
673 const schema = Schema.Struct({
674 a: Schema.String,
675 b: Schema.Number
676 }).pipe(Schema.extend(Schema.Struct({ c: Schema.Number })))
677 ```
678
679 v4
680
681 ```ts
682 import { Schema, Struct } from "effect"
683
684 const schema = Schema.Struct({
685 a: Schema.String,
686 b: Schema.Number
687 }).mapFields(Struct.assign({ c: Schema.Number }))
688
689 // or more succinctly
690 const schema2 = Schema.Struct({
691 a: Schema.String,
692 b: Schema.Number
693 }).pipe(Schema.fieldsAssign({ c: Schema.Number }))
694 ```
695
696 #### Union extends Struct
697
698 v3
699
700 ```ts
701 import { Schema } from "effect"
702
703 const schema = Schema.Union(
704 Schema.Struct({ a: Schema.String }),
705 Schema.Struct({ b: Schema.Number })
706 ).pipe(Schema.extend(Schema.Struct({ c: Schema.Boolean })))
707 ```
708
709 v4
710
711 ```ts
712 import { Schema, Tuple } from "effect"
713
714 const schema = Schema.Union([
715 Schema.Struct({ a: Schema.String }),
716 Schema.Struct({ b: Schema.Number })
717 ]).mapMembers(Tuple.map(Schema.fieldsAssign({ c: Schema.Number })))
718 ```
719
720 ### filter
721
722 **Migration: semi-auto**
723
724 v3
725
726 ```ts
727 import { Schema } from "effect"
728
729 // inline filter
730 const a = Schema.String.pipe(Schema.filter((s) => s.length > 0))
731
732 // refinement
733 const b = Schema.Option(Schema.String).pipe(Schema.filter(Option.isSome))
734 ```
735
736 v4
737
738 ```ts
739 import { Option, Schema } from "effect"
740
741 // inline filter
742 const a = Schema.String.check(Schema.makeFilter((s) => s.length > 0))
743
744 // refinement
745 const b = Schema.Option(Schema.String).pipe(Schema.refine(Option.isSome))
746 ```
747
748 In v4, a `makeFilter` predicate can return any of the shapes described by `Schema.FilterOutput`:
749
750 - `undefined` / `true` — success
751 - `false` — generic failure
752 - `string` — failure with that message
753 - `SchemaIssue.Issue` — a fully-formed issue
754 - `{ path, issue }` — failure at a nested path (`issue` is a `string` or `SchemaIssue.Issue`)
755 - `ReadonlyArray<Schema.FilterIssue>` — several failures reported together (empty array = success, single element is unwrapped, otherwise grouped into an `Issue.Composite`)
756
757 **Example** (Failure at a nested path)
758
759 ```ts
760 import { Schema } from "effect"
761
762 const schema = Schema.Struct({ password: Schema.String, confirmPassword: Schema.String }).check(
763 Schema.makeFilter((o) =>
764 o.password === o.confirmPassword
765 ? undefined
766 : { path: ["password"], issue: "password and confirmPassword must match" }
767 )
768 )
769
770 console.log(String(Schema.decodeUnknownExit(schema)({ password: "123456", confirmPassword: "1234567" })))
771 // Failure(Cause([Fail(SchemaError(password and confirmPassword must match
772 // at ["password"]))]))
773 ```
774
775 **Example** (Reporting multiple failures at once)
776
777 ```ts
778 import { Schema } from "effect"
779
780 const schema = Schema.Struct({ a: Schema.Finite, b: Schema.Finite, c: Schema.Finite }).check(
781 Schema.makeFilter((o) => {
782 const issues: Array<Schema.FilterIssue> = []
783 if (o.a > 0) {
784 if (o.b <= 0) issues.push({ path: ["b"], issue: "b must be greater than 0" })
785 if (o.c <= 0) issues.push({ path: ["c"], issue: "c must be greater than 0" })
786 }
787 return issues
788 })
789 )
790
791 console.log(String(Schema.decodeUnknownExit(schema)({ a: 1, b: 0, c: 0 })))
792 // Failure(Cause([Fail(SchemaError(b must be greater than 0
793 // at ["b"]
794 // c must be greater than 0
795 // at ["c"]))]))
796 ```
797
798 ### filterEffect
799
800 **Migration: manual**
801
802 **New imports:** `SchemaGetter`, `Result`
803
804 v3
805
806 ```ts
807 import { Effect, Schema } from "effect"
808
809 async function validateUsername(username: string) {
810 return Promise.resolve(username === "gcanti")
811 }
812
813 const ValidUsername = Schema.String.pipe(
814 Schema.filterEffect((username) =>
815 Effect.promise(() => validateUsername(username).then((valid) => valid || "Invalid username"))
816 )
817 )
818 ```
819
820 v4
821
822 ```ts
823 import { Effect, Result, Schema, SchemaGetter } from "effect"
824
825 async function validateUsername(username: string) {
826 return Promise.resolve(username === "gcanti")
827 }
828
829 const ValidUsername = Schema.String.pipe(
830 Schema.decode({
831 decode: SchemaGetter.checkEffect((username) =>
832 Effect.promise(() => validateUsername(username).then((valid) => valid || "Invalid username"))
833 ),
834 encode: SchemaGetter.passthrough()
835 })
836 )
837 ```
838
839 ### transform
840
841 **Migration: semi-auto**
842
843 **New imports:** `SchemaTransformation`
844
845 v3
846
847 ```ts
848 import { Schema } from "effect"
849
850 const BooleanFromString = Schema.transform(Schema.Literal("on", "off"), Schema.Boolean, {
851 strict: true,
852 decode: (literal) => literal === "on",
853 encode: (bool) => (bool ? "on" : "off")
854 })
855 ```
856
857 v4
858
859 ```ts
860 import { Schema, SchemaTransformation } from "effect"
861
862 const BooleanFromString = Schema.Literals(["on", "off"]).pipe(
863 Schema.decodeTo(
864 Schema.Boolean,
865 SchemaTransformation.transform({
866 decode: (literal) => literal === "on",
867 encode: (bool) => (bool ? "on" : "off")
868 })
869 )
870 )
871 ```
872
873 ### transformOrFail
874
875 **Migration: semi-auto**
876
877 **New imports:** `SchemaGetter`, `SchemaIssue`
878
879 v3
880
881 ```ts
882 import { ParseResult, Schema } from "effect"
883
884 const NumberFromString = Schema.transformOrFail(Schema.String, Schema.Number, {
885 strict: true,
886 decode: (input, _, ast) => {
887 const parsed = parseFloat(input)
888 if (isNaN(parsed)) {
889 return ParseResult.fail(new ParseResult.Type(ast, input, "Failed to convert string to number"))
890 }
891 return ParseResult.succeed(parsed)
892 },
893 encode: (input) => ParseResult.succeed(input.toString())
894 })
895 ```
896
897 v4
898
899 ```ts
900 import { Effect, Number, Option, Schema, SchemaGetter, SchemaIssue } from "effect"
901
902 const NumberFromString = Schema.String.pipe(
903 Schema.decodeTo(Schema.Number, {
904 decode: SchemaGetter.transformEffect((s) =>
905 Option.match(Number.parse(s), {
906 onNone: () => Effect.fail(new SchemaIssue.InvalidValue()),
907 onSome: Effect.succeed
908 })
909 ),
910 encode: SchemaGetter.String()
911 })
912 )
913 ```
914
915 ### transformLiteral / transformLiterals
916
917 **Migration: auto**
918
919 v3
920
921 ```ts
922 import { Schema } from "effect"
923
924 const a = Schema.transformLiteral(0, "a")
925 const b = Schema.transformLiterals([0, "a"], [1, "b"], [2, "c"])
926 ```
927
928 v4
929
930 ```ts
931 import { Schema } from "effect"
932
933 const a = Schema.Literal(0).transform("a")
934 const b = Schema.Literals([0, 1, 2]).transform(["a", "b", "c"])
935 ```
936
937 ### attachPropertySignature
938
939 **Migration: semi-auto**
940
941 v3
942
943 ```ts
944 import { Schema } from "effect"
945
946 const Circle = Schema.Struct({ radius: Schema.Number })
947 const Square = Schema.Struct({ sideLength: Schema.Number })
948
949 const DiscriminatedShape = Schema.Union(
950 Circle.pipe(Schema.attachPropertySignature("kind", "circle")),
951 Square.pipe(Schema.attachPropertySignature("kind", "square"))
952 )
953 ```
954
955 v4
956
957 ```ts
958 import { Schema } from "effect"
959
960 const Circle = Schema.Struct({ radius: Schema.Number })
961 const Square = Schema.Struct({ sideLength: Schema.Number })
962
963 const DiscriminatedShape = Schema.Union([
964 Circle.mapFields((fields) => ({ ...fields, kind: Schema.tagDefaultOmit("circle") })),
965 Square.mapFields((fields) => ({ ...fields, kind: Schema.tagDefaultOmit("square") }))
966 ])
967 ```
968
969 ### decodingFallback
970
971 **Migration: auto**
972
973 v3
974
975 ```ts
976 import { Effect, Schema } from "effect"
977
978 const schema = Schema.String.annotations({
979 decodingFallback: () => Effect.succeed("a")
980 })
981 ```
982
983 v4
984
985 ```ts
986 import { Effect, Schema } from "effect"
987
988 const schema = Schema.String.pipe(Schema.catchDecoding(() => Effect.succeedSome("a")))
989 ```
990
991 ### rename
992
993 **Migration: manual**
994
995 **New imports:** `SchemaTransformation`
996
997 v3
998
999 ```ts
1000 import { Schema } from "effect"
1001
1002 const schema = Schema.Struct({
1003 a: Schema.String,
1004 b: Schema.Number
1005 }).pipe(Schema.rename({ a: "c" }))
1006 ```
1007
1008 v4
1009
1010 ```ts
1011 import { Schema } from "effect"
1012
1013 // experimental API
1014 const schema = Schema.Struct({
1015 a: Schema.String,
1016 b: Schema.Number
1017 }).pipe(Schema.encodeKeys({ a: "c" }))
1018 ```
1019
1020 ### Capitalize / Lowercase / Uppercase / Uncapitalize
1021
1022 **Migration: semi-auto**
1023
1024 **New imports:** `SchemaTransformation`
1025
1026 v3
1027
1028 ```ts
1029 import { Schema } from "effect"
1030
1031 const schema = Schema.Capitalize
1032 ```
1033
1034 v4
1035
1036 ```ts
1037 import { Schema, SchemaTransformation } from "effect"
1038
1039 const schema = Schema.String.pipe(
1040 Schema.decodeTo(Schema.String.check(Schema.isCapitalized()), SchemaTransformation.capitalize())
1041 )
1042 ```
1043
1044 ### NonEmptyTrimmedString
1045
1046 **Migration: semi-auto**
1047
1048 v3
1049
1050 ```ts
1051 import { Schema } from "effect"
1052
1053 const schema = Schema.NonEmptyTrimmedString
1054 ```
1055
1056 v4
1057
1058 ```ts
1059 import { Schema } from "effect"
1060
1061 const schema = Schema.Trimmed.check(Schema.isNonEmpty())
1062 ```
1063
1064 ### split
1065
1066 **Migration: manual**
1067
1068 **New imports:** `SchemaTransformation`
1069
1070 v3
1071
1072 ```ts
1073 import { Schema } from "effect"
1074
1075 const schema = Schema.split(",")
1076 ```
1077
1078 v4
1079
1080 ```ts
1081 import { Schema, SchemaTransformation } from "effect"
1082
1083 function split(separator: string) {
1084 return Schema.String.pipe(
1085 Schema.decodeTo(
1086 Schema.Array(Schema.String),
1087 SchemaTransformation.transform({
1088 decode: (s) => s.split(separator) as ReadonlyArray<string>,
1089 encode: (as) => as.join(separator)
1090 })
1091 )
1092 )
1093 }
1094 ```
1095
1096 ## Migrating from the fast-check bridge to native Arbitrary
1097
1098 This section covers migration from the fast-check bridge published in `effect@4.0.0-rc.109` to the native,
1099 Schema-first module at `effect/Arbitrary`.
1100
1101 The new module removes fast-check from the `effect` package. Applications may still install and use fast-check
1102 directly, but Effect Schema generation and `@effect/vitest` property tests no longer depend on it.
1103
1104 For the new API and its semantics, see [Arbitrary in Effect](../packages/effect/ARBITRARY.md).
1105
1106 ### Import changes
1107
1108 The following APIs have been removed:
1109
1110 - `effect/testing/FastCheck`;
1111 - `Schema.toArbitrary`;
1112 - `Schema.Arbitrary`;
1113 - the legacy `Schema.Annotations.ToArbitrary` contract and declaration-level `toArbitrary` annotation;
1114 - the legacy `arbitrary` filter annotation;
1115 - raw fast-check arbitrary inputs and `fastCheck` options in `@effect/vitest`.
1116
1117 Import the native module explicitly:
1118
1119 ```ts
1120 import * as Arbitrary from "effect/Arbitrary"
1121 ```
1122
1123 If other tests still use fast-check-specific APIs, add fast-check as a direct development dependency and import it
1124 from `"fast-check"`. Do not import it through Effect.
1125
1126 ### Generating samples
1127
1128 Previously, `Schema.toArbitrary` returned a factory that needed the fast-check module:
1129
1130 ```ts
1131 import { Schema } from "effect"
1132 import { FastCheck } from "effect/testing"
1133
1134 const Person = Schema.Struct({
1135 name: Schema.String,
1136 age: Schema.Int
1137 })
1138
1139 const personArbitrary = Schema.toArbitrary(Person)(FastCheck)
1140 const samples = FastCheck.sample(personArbitrary, { numRuns: 20, seed: 42 })
1141 ```
1142
1143 Now derive and sample through the Effect-native module:
1144
1145 ```ts
1146 import { Effect, Schema } from "effect"
1147 import * as Arbitrary from "effect/Arbitrary"
1148
1149 const Person = Schema.Struct({
1150 name: Schema.String,
1151 age: Schema.Int
1152 })
1153
1154 const personArbitrary = Arbitrary.schema(Person)
1155 const samples = await Effect.runPromise(
1156 Arbitrary.sampleEffect(personArbitrary, { count: 20, seed: 42 })
1157 )
1158 ```
1159
1160 `Arbitrary.sampleEffect` returns an `Effect` because sampling is interruptible, uses Effect `Random` when no seed is
1161 provided, and reports bounded generation exhaustion as a typed `SampleError`.
1162
1163 The generated values still use the decoded Schema `Type`. The sequence and distribution are not compatible with
1164 fast-check, even when the same numeric seed is used.
1165
1166 ### Checking properties
1167
1168 Previously, fast-check owned both the property and the runner:
1169
1170 ```ts
1171 import { Schema } from "effect"
1172 import { FastCheck } from "effect/testing"
1173
1174 const integer = Schema.toArbitrary(Schema.Int)(FastCheck)
1175
1176 FastCheck.assert(
1177 FastCheck.property(integer, (value) => Number.isInteger(value)),
1178 { numRuns: 100, seed: 42 }
1179 )
1180 ```
1181
1182 Now `Arbitrary.checkEffect` runs a pure or Effectful property and returns a structured result:
1183
1184 ```ts
1185 import { Effect, Schema } from "effect"
1186 import * as Arbitrary from "effect/Arbitrary"
1187
1188 const result = await Effect.runPromise(
1189 Arbitrary.checkEffect(
1190 Arbitrary.schema(Schema.Int),
1191 (value) => Number.isInteger(value),
1192 { runs: 100, seed: 42 }
1193 )
1194 )
1195 ```
1196
1197 Unlike `FastCheck.assert`, `Arbitrary.checkEffect` does not throw for an ordinary falsification. Handle `Passed`,
1198 `Falsified`, `Exhausted`, and `ReplayMismatch` explicitly, or use `@effect/vitest`, which converts non-passing results
1199 into test failures.
1200
1201 Typed failures from Effectful properties are preserved in `Falsified.failure`. Defects and interruption continue
1202 through the returned Effect.
1203
1204 ### Option mapping
1205
1206 The most common options map as follows:
1207
1208 | Previous fast-check option | Native option | Migration note |
1209 | -------------------------- | -------------------- | ------------------------------------------------------------------ |
1210 | `numRuns` | `count` or `runs` | Use `count` for `sampleEffect` and `runs` for `checkEffect`. |
1211 | `seed` | `seed` | The type is compatible, but generated sequences are not. |
1212 | `path` | `replay` | Existing fast-check paths cannot be converted. |
1213 | `maxSkipsPerRun` | `maxDiscards` | Native uses one absolute discard budget, not a multiplier per run. |
1214 | `examples` | No direct equivalent | Keep explicit regression cases as ordinary tests. |
1215 | `endOnFailure` | `maxShrinks` | Use `maxShrinks: 0` to stop at the initial failure. |
1216 | `interruptAfterTimeLimit` | Effect interruption | Apply an Effect or test timeout around the check. |
1217 | `skipAllAfterTimeLimit` | No direct equivalent | Prefer explicit run and discard bounds. |
1218 | `verbose` | No direct equivalent | Inspect `CheckResult` or use `@effect/vitest` failure output. |
1219
1220 Review any less common fast-check runner option manually. The native API deliberately does not reproduce the complete
1221 `fc.Parameters` surface.
1222
1223 ### Replay migration
1224
1225 Fast-check replay used a seed plus a shrink `path`. Native replay uses one opaque token returned by a `Falsified`
1226 result:
1227
1228 ```ts
1229 const replayed = Arbitrary.checkEffect(arbitrary, property, {
1230 replay: previousFailure.replay
1231 })
1232 ```
1233
1234 There is no conversion from a fast-check seed and path to a native replay token. Re-run the property with the native
1235 engine, then record the new token from its `Falsified` result.
1236
1237 Replay tokens are intended for reproducing and diagnosing a current failure. Because the module is unstable, they are
1238 not guaranteed to survive upgrades. Preserve important failing inputs as explicit regression tests.
1239
1240 Array shrinking now tries deleting prefixes and interior blocks as well as suffixes. Products and objects retain child
1241 shrink candidates when exploring other branches. Shrunk outputs and replay paths can therefore differ from earlier
1242 native releases, including RC.115. Re-run affected properties to record new tokens.
1243 For arrays of composed Arbitraries, use `Arbitrary.array(item, { maxLength: 50 })` instead of shrinking a generated
1244 length through `flatMap` and `all`; deletions then preserve the remaining generated elements.
1245
1246 ### Migrating declaration annotations
1247
1248 The old `toArbitrary` annotation directly constructed a fast-check arbitrary and exposed fast-check recursion and
1249 constraint details:
1250
1251 ```ts
1252 import { Schema } from "effect"
1253
1254 class UserId {
1255 readonly value: number
1256 constructor(value: number) {
1257 this.value = value
1258 }
1259 }
1260
1261 const UserIdSchema = Schema.instanceOf(UserId, {
1262 toArbitrary: () => (fc) => fc.integer({ min: 1, max: 1_000_000 }).map((value) => new UserId(value))
1263 })
1264 ```
1265
1266 The native `toCodecArbitrary` annotation describes a generatable representation as a Schema `Link`:
1267
1268 ```ts
1269 import { Schema, SchemaTransformation } from "effect"
1270
1271 class UserId {
1272 readonly value: number
1273 constructor(value: number) {
1274 this.value = value
1275 }
1276 }
1277
1278 const UserIdSchema = Schema.instanceOf(UserId, {
1279 toCodecArbitrary: () =>
1280 Schema.link<UserId>()(
1281 Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 1_000_000 })),
1282 SchemaTransformation.transform({
1283 decode: (value) => new UserId(value),
1284 encode: (id) => id.value
1285 })
1286 )
1287 })
1288 ```
1289
1290 Before adding `toCodecArbitrary`, check whether the declaration already has a useful `toCodecJson` or `toCodec`.
1291 Native derivation falls back to those canonical codecs automatically. Add an arbitrary-specific Link only when the
1292 canonical representation is opaque or generates valid values too rarely.
1293
1294 The migration changes where generation logic lives:
1295
1296 | Legacy contract | Native contract |
1297 | ---------------------------------------------- | -------------------------------------------------------------- |
1298 | Returns a `fast-check.Arbitrary` | Returns a `SchemaAST.Link` through `Schema.link`. |
1299 | Receives generated arbitrary type parameters | Receives decoded Schema type parameters. |
1300 | Receives fast-check constraints and recursion | Receives normalized constraints. |
1301 | Manages terminal recursive branches explicitly | Leaves recursion analysis and budgets to the native compiler. |
1302 | Uses arbitrary combinators | Uses Schema constructors, checks, and a Schema transformation. |
1303
1304 The original declaration remains authoritative. Values decoded by the Link are checked against it. Failed decodes and
1305 rejected values become bounded discards.
1306
1307 #### Custom filter metadata
1308
1309 The old `arbitrary` filter annotation has been replaced by `arbitraryConstraint`. Ordinary custom filters continue to
1310 work as residual filters without generation metadata:
1311
1312 ```ts
1313 import { Schema } from "effect"
1314
1315 const Even = Schema.Int.check(
1316 Schema.makeFilter((value) => value % 2 === 0)
1317 )
1318 ```
1319
1320 Residual filtering is bounded, so a very selective or impossible predicate may produce `SampleError` or `Exhausted`.
1321
1322 If the previous annotation supplied a recognized constructive constraint, move it to `arbitraryConstraint` and adapt
1323 its shape. The predicate remains authoritative:
1324
1325 ```ts
1326 import { Order, Schema } from "effect"
1327
1328 const Positive = Schema.Number.check(
1329 Schema.makeFilter(
1330 (value) => value > 0,
1331 {
1332 arbitraryConstraint: {
1333 order: Order.Number,
1334 minimum: 0,
1335 exclusiveMinimum: true
1336 }
1337 }
1338 )
1339 )
1340 ```
1341
1342 The main constraint-shape changes are:
1343
1344 | Previous field | Native field |
1345 | ------------------------------------ | ------------------------------------------------------------------- |
1346 | `ordered.order` | `order` |
1347 | `ordered.minimum` / `maximum` | `minimum` / `maximum` |
1348 | `ordered.exclusiveMinimum` / maximum | `exclusiveMinimum: true` / `exclusiveMaximum: true` |
1349 | `integer: true` | `number: "integer"` |
1350 | `noNaN` and `noInfinity` | `number: "finite"` when both restrictions apply |
1351 | collection `minLength` / `maxLength` | `minLength`, `minSize`, or `minProperties` and its matching maximum |
1352 | string pattern | `{ source, flags }` in `patterns` |
1353 | `unique: true` | `uniqueBy: identity` |
1354 | `candidate` | No direct equivalent |
1355
1356 Choose the cardinality field that matches the Schema domain: `minLength` and `maxLength` for strings and arrays,
1357 `minSize` and `maxSize` for sized collections, and `minProperties` and `maxProperties` for object properties.
1358
1359 For an opaque declaration that needs a reusable statistically better source domain, express that source as a Schema
1360 Link with `toCodecArbitrary`.
1361
1362 ### Migrating `@effect/vitest`
1363
1364 Property inputs may be Schemas, native Arbitraries, or mixtures of both.
1365
1366 Schema-only properties need only an option rename:
1367
1368 ```ts
1369 // Before
1370 it.prop(
1371 "commutative",
1372 [Schema.Int, Schema.Int],
1373 ([a, b]) => a + b === b + a,
1374 { fastCheck: { numRuns: 200, seed: 42 } }
1375 )
1376
1377 // After
1378 it.prop(
1379 "commutative",
1380 [Schema.Int, Schema.Int],
1381 ([a, b]) => a + b === b + a,
1382 { arbitrary: { runs: 200, seed: 42 } }
1383 )
1384 ```
1385
1386 Raw or mixed fast-check inputs are no longer accepted:
1387
1388 ```ts
1389 // No longer supported
1390 it.prop("raw arbitrary", [fc.integer()], ([value]) => Number.isInteger(value))
1391 it.prop("mixed", [Schema.String, fc.integer()], ([text, value]) => true)
1392 ```
1393
1394 Replace those inputs with Schemas when they describe a domain supported by Schema, or compose a native Arbitrary:
1395
1396 ```ts
1397 import * as Arbitrary from "effect/Arbitrary"
1398
1399 const integer = Arbitrary.schema(Schema.Int)
1400
1401 it.prop("native arbitrary", [integer], ([value]) => Number.isInteger(value))
1402 it.prop("mixed", [Schema.String, integer], ([text, value]) => typeof text === "string" && Number.isInteger(value))
1403 ```
1404
1405 If a test genuinely needs a fast-check-specific arbitrary or runner feature, use fast-check directly with Vitest
1406 rather than passing it through `@effect/vitest`.
1407
1408 `it.prop`, `it.effect.prop`, and `it.live.prop` all accept native check options under `arbitrary`.
1409
1410 ### Behavioral differences to review
1411
1412 Migration is not only an import rename. Review the following differences:
1413
1414 - native generation and shrinking have different distributions and may find different shrunk inputs;
1415 - native checking returns structured results instead of using fast-check's assertion exceptions;
1416 - generation that cannot find enough valid samples is bounded and reports `SampleError` or `Exhausted`;
1417 - pure and Effectful properties share one interruptible runner;
1418 - recursive and mutually recursive Schemas are analyzed as a graph and must have a finite generation path;
1419 - replay tokens, seeds, and shrink paths are not compatible with fast-check;
1420 - generated values are the decoded Schema `Type`;
1421 - properties must not mutate generated values.
1422
1423 ### Migration checklist
1424
1425 1. Replace `effect/testing/FastCheck` imports. Use the native Arbitrary module for Schema generation and import
1426 `"fast-check"` directly only where it is still independently required.
1427 2. Replace `Schema.toArbitrary(schema)(FastCheck)` with `Arbitrary.schema(schema)`.
1428 3. Replace `FastCheck.sample` with `Arbitrary.sampleEffect` and run the returned Effect.
1429 4. Replace `FastCheck.check` or `FastCheck.assert` for Schema-derived inputs with `Arbitrary.checkEffect`, then handle its
1430 structured result.
1431 5. Rename `@effect/vitest` options from `fastCheck` to `arbitrary` and convert `numRuns` to `runs`.
1432 6. Replace raw fast-check inputs in `@effect/vitest` with Schemas or native Arbitraries.
1433 7. Migrate declaration-level `toArbitrary` callbacks to the `toCodecArbitrary` Link-returning contract and replace old
1434 filter-level `arbitrary` annotations with `arbitraryConstraint`.
1435 8. Re-run properties with the native engine and record new replay tokens or explicit regression examples.
1436 9. Review discard limits for selective custom filters.