Migration Guides

Relevant source files

The following files were used as context for generating this wiki page:

• packages/fast-check/MIGRATION_1.X_TO_2.X.md
• packages/fast-check/MIGRATION_2.X_TO_3.X.md
• website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md
• website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md
• packages/poisoning/CHANGELOG.md
• packages/packaged/CHANGELOG.md
• website/blog/2023-11-22-whats-new-in-fast-check-3-14-0/index.md

The fast-check library undergoes periodic major version updates that may introduce breaking changes, new features, and deprecations. These migration guides provide a comprehensive overview of the changes between major versions to facilitate a smooth upgrade process for users. The guides cover API modifications, changes in supported environments, and structural shifts like the adoption of ES Modules.

The goal is to make upgrading straightforward, typically requiring only a dependency version bump. However, for cases involving breaking changes, this document details the necessary code modifications with examples. A simplified migration path is illustrated below.

This diagram shows the major version progression and indicates which transitions involved significant breaking changes.
Sources: packages/fast-check/MIGRATION_1.X_TO_2.X.md, packages/fast-check/MIGRATION_2.X_TO_3.X.md, website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md

Migration from v3.x to v4.x

Version 4.0.0 streamlines and refines APIs, embraces modern standards, and removes deprecated features to enhance performance and maintainability. A detailed migration guide is available in the documentation.

Sources: website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md:10-14

Key Breaking Changes

The update to v4.0.0 introduces several breaking changes focused on smarter defaults and API consolidation.

Change Description	Details
Smarter Defaults	fc.date now includes invalid dates by default. fc.record and fc.dictionary can now generate objects with a null prototype by default.
Unified string Arbitrary	All string-related arbitraries have been consolidated into a single fc.string arbitrary. Many older, specific string arbitraries are now deprecated and removed.
Finer Scheduler	The scheduling capabilities for race condition testing have been made more precise, ensuring tasks are only scheduled if present at the expected time.
Dropped Deprecations	Deprecated methods and arbitraries from v3.x have been removed, including .noBias, .noShrink, uuidV, ascii*, hexa*, base64, stringOf, and others.
Node.js Version	The minimum required Node.js version is now 12.17.0.

Sources: website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md:20-40, 47-70

Deprecated and Removed Arbitraries

The following table summarizes the arbitraries that were deprecated and subsequently removed in v4.0.0.

Removed Arbitrary/Method	Replacement / Notes
.noBias	Use frequency-based arbitraries or other composition techniques.
uuidV	Use the extended uuid arbitrary which can build any known version.

• unicodeJson* | Use fc.json() and related arbitraries. |
  | ascii*, hexa*, base64*, stringOf, char16bits, fullUnicode*, unicode*, char | All consolidated into the unified fc.string arbitrary. |
  | big{U|}int{N|} | Use fc.bigInt() and fc.bigUint(). |
  | run{Before/After}Each on property | These should be enforced on the property level. |

Sources: website/blog/2025-03-10-whats-new-in-fast-check-4-0-0/index.md:57-70, 79

Migration from v2.x to v3.x

The migration from version 2.x to 3.x is expected to be smooth, as there were no major breaking changes that required a dedicated migration guide. The MIGRATION_2.X_TO_3.X.md file is empty, indicating a straightforward upgrade path for most users.

Sources: packages/fast-check/MIGRATION_2.X_TO_3.X.md

Migration from v1.x to v2.x

The transition from version 1.x to 2.x involved several minor breaking changes that required a major version bump. Most projects can be migrated by simply updating the fast-check version in package.json.

Sources: packages/fast-check/MIGRATION_1.X_TO_2.X.md:3-8

API and Typing Changes

Change	Before (v1.x)	After (v2.x)
fc.record option	with_deleted_keys: true	withDeletedKeys: true
fc.constantFrom typing	fc.constantFrom<boolean | null | number>(false, null, 0)	fc.constantFrom(false, null, 0) or fc.constantFrom<(boolean | null | number)[]>(false, null, 0)
Object constraints type	ObjectConstraints.Settings	ObjectConstraints

Sources: packages/fast-check/MIGRATION_1.X_TO_2.X.md:12-35

A code modification example for fc.record:

   fc.record(
     {
       first_name: fc.string(),
       last_name: fc.string(),
       age: fc.nat(),
     }, {
---    with_deleted_keys: true
+++    withDeletedKeys: true
     })

Sources: packages/fast-check/MIGRATION_1.X_TO_2.X.md:15-22

Environment and Build System Changes

Browser Build Removal

Version 2.x removed the pre-built browser bundle (lib/bundle.js). Users who relied on this bundle from a CDN have two primary alternatives:

1. Use an ESM-compatible CDN: Import fast-check as an ES module from a service like Skypack.

   <script type="module">
     import fc from 'https://cdn.skypack.dev/fast-check';
     // code...
   </script>
   

2. Build the bundle locally: Use a tool like browserify to create a local bundle.

   npx -p browserify browserify node_modules/fast-check/lib/fast-check.js --s fastcheck > node_modules/fast-check/lib/bundle.js
   

Sources: packages/fast-check/MIGRATION_1.X_TO_2.X.md:37-61

Dropped Support for Older Environments

• ECMAScript: Support for ES versions below ES2017 has been dropped.
• TypeScript: Support for TypeScript versions below 3.2 has been dropped.

Users on older environments need to either remain on fast-check v1.x or use a transpiler like Babel.

Sources: packages/fast-check/MIGRATION_1.X_TO_2.X.md:63-73

Module System Migration (CJS to ESM)

A significant architectural change across the fast-check monorepo has been the migration towards ECMAScript modules (ESM) while maintaining CommonJS (CJS) compatibility through a dual-package approach. This ensures that users can import the library regardless of their project's module system.

Sources: website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md:6-12, packages/poisoning/CHANGELOG.md:21-25, packages/packaged/CHANGELOG.md:33-37

Dual Package Structure

To support both module systems, fast-check uses a specific directory structure and package.json configuration.

This diagram illustrates the dual package structure. The root package.json declares the package as CJS, while a nested package.json inside the lib/esm directory declares its contents as ESM.
Sources: website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md:64-70

package.json Exports

The exports field in package.json is used to direct Node.js and bundlers to the correct entry point based on how the package is imported (require vs. import).

{
  "type": "commonjs",
  "main": "lib/fast-check.js",
  "module": "lib/esm/fast-check.js",
  "exports": {
    ".": {
      "require": {
        "types": "./lib/fast-check.d.ts",
        "default": "./lib/fast-check.js"
      },
      "import": {
        "types": "./lib/esm/fast-check.d.ts",
        "default": "./lib/esm/fast-check.js"
      }
    }
  },
  "types": "lib/fast-check.d.ts"
}

This configuration ensures that require('fast-check') resolves to the CJS version and import fc from 'fast-check' resolves to the ESM version, each with its corresponding TypeScript type definitions.

Sources: website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md:78-99, website/blog/2023-11-22-whats-new-in-fast-check-3-14-0/index.md:40-41