Project Architecture

Relevant source files

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

• packages/fast-check/package.json
• packages/packaged/package.json
• website/package.json
• website/docusaurus.config.ts
• website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md
• website/blog/2023-05-16-fast-check-loves-docusaurus/index.md
• CONTRIBUTING.md
• packages/fast-check/test/e2e/documentation/Docs.md.spec.ts
• packages/poisoning/package.json
• packages/expect-type/package.json
• website/blog/2024-03-04-whats-new-in-fast-check-3-16-0/index.md

The fast-check project is structured as a monorepo managed with pnpm workspaces. This architecture houses the core fast-check testing library, several specialized utility packages, and a comprehensive documentation website. The project is built using TypeScript and is designed for wide compatibility by publishing dual ECMAScript (ESM) and CommonJS (CJS) modules.

This architecture facilitates code sharing, centralized dependency management, and a streamlined development workflow across the different parts of the project, from the core library logic to its public-facing documentation. The tooling is standardized across packages for building, testing, and linting.

Monorepo Structure

The repository utilizes pnpm workspaces to manage multiple JavaScript/TypeScript packages. This setup is evident from the use of workspace:* protocol for internal dependencies and the directory layout.

The diagram below illustrates the high-level structure of the monorepo, highlighting the main packages.

This diagram shows the main packages directory containing the core library and utilities, alongside the website directory for documentation.

Sources: website/package.json:34, packages/fast-check/package.json, packages/packaged/package.json, packages/poisoning/CHANGELOG.md, packages/expect-type/CHANGELOG.md

Packages Overview

The monorepo contains several key packages, each with a distinct purpose.

Package Name	Description	Source File
fast-check	The core property-based testing framework.	packages/fast-check/package.json
@fast-check/packaged	A utility to remove files that will not be part of the final NPM bundle.	packages/packaged/package.json
@fast-check/poisoning	An experimental utility to check for prototype poisoning vulnerabilities.	packages/poisoning/CHANGELOG.md
@fast-check/expect-type	A utility to assert TypeScript types, similar to tsd.	packages/expect-type/CHANGELOG.md
website	The Docusaurus-based documentation website for fast-check.dev.	website/package.json

Sources: packages/fast-check/package.json:3, packages/packaged/package.json:2, packages/poisoning/CHANGELOG.md:164, packages/expect-type/CHANGELOG.md:100, website/package.json:2

Dual CJS/ESM Module Architecture

A critical architectural decision for the fast-check library is its support for both CommonJS (CJS) and ECMAScript Modules (ESM). This "dual package" approach ensures compatibility with a wide range of Node.js versions and build tools.

Sources: website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md

Implementation Details

The dual-module support is implemented using conditional exports in package.json. This feature allows Node.js and bundlers to select the appropriate file based on how the package is imported (require vs. import).

The fast-check package is declared as "type": "module", meaning .js files are treated as ESM by default. A separate lib/cjs directory is created for the CommonJS build, which contains a package.json with "type": "commonjs".

// packages/fast-check/package.json
{
  "name": "fast-check",
  "type": "module",
  "main": "lib/fast-check.js",
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "require": {
        "types": "./lib/cjs/types/fast-check.d.ts",
        "default": "./lib/cjs/fast-check.js"
      },
      "import": {
        "types": "./lib/types/fast-check.d.ts",
        "default": "./lib/fast-check.js"
      }
    }
  },
  "module": "lib/fast-check.js",
  "types": "lib/types/fast-check.d.ts"
}

Sources: packages/fast-check/package.json:2-20, website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md:73-92

The following diagram illustrates how an import resolves to either the CJS or ESM version of the library.

This diagram shows the exports map in package.json acting as a router, directing import and require statements to their respective ESM and CJS builds.

Sources: packages/fast-check/package.json:5-17, website/blog/2023-09-04-dual-packages-or-supporting-both-cjs-and-esm/index.md:73-92

Documentation Website

The project's documentation is a key component, hosted at fast-check.dev. It is built using Docusaurus, a modern static site generator. The decision to use Docusaurus was driven by its ability to create content from simple Markdown files while also allowing for complex React components, and its rich out-of-the-box features like sitemaps, search, and easy deployment.

Sources: website/blog/2023-05-16-fast-check-loves-docusaurus/index.md:83-101, website/docusaurus.config.ts

Website Configuration

The website's behavior is defined in website/docusaurus.config.ts. Key features configured here include:

Feature	Configuration	Purpose
Search	algolia	Integrates Algolia for powerful search capabilities across the documentation.
PWA Support	@docusaurus/plugin-pwa	Enables Progressive Web App features for offline access and better performance.
SEO/Crawling	docusaurus-plugin-llms	Generates llms.txt to guide AI crawlers, improving discoverability.
Deployment	netlify	The site is deployed and hosted on Netlify for better performance and cache control.
Interactive Code	sandpack-react	Provides live, editable code playgrounds directly within the documentation.

Sources: website/docusaurus.config.ts:111-135, website/docusaurus.config.ts:138-181, website/docusaurus.config.ts:183-196, website/package.json:21, website/blog/2024-03-04-whats-new-in-fast-check-3-16-0/index.md:46-48

The diagram below shows the main architectural components of the Docusaurus website.

This diagram outlines how source files (Markdown, React) are processed by Docusaurus and its plugins to produce a static site, which is then deployed to Netlify.

Sources: website/docusaurus.config.ts:51-64, website/docusaurus.config.ts:111-196, website/blog/2024-03-04-whats-new-in-fast-check-3-16-0/index.md:46-48

Build and Testing

The project maintains a high standard of code quality through a robust build, linting, and testing process.

Contribution and CI Workflow

The contribution guidelines and CI setup ensure that all changes are validated before being merged.

1. Local Development: Developers clone the repository, install dependencies with pnpm install, and build the target package (e.g., pnpm --filter fast-check build).
2. Code Style: Code is formatted with Prettier (pnpm format) and checked with a linter (pnpm lint).
3. Pull Request: A pull request triggers GitHub Actions.
4. CI Checks: The CI pipeline runs tests, linting, and style checks.
5. Merge: Once checks pass and the PR is reviewed, it can be merged.

Sources: CONTRIBUTING.md:27-40

This flowchart depicts the development and CI workflow, from local changes to a validated pull request.

Testing Strategy

The project employs a multi-faceted testing strategy:

• Unit & Integration Tests: Located in test/unit and test/integration, these form the core of the testing suite. The project uses vitest as its test runner.
• E2E Documentation Tests: A unique aspect is the testing of code snippets within the documentation. The file packages/fast-check/test/e2e/documentation/Docs.md.spec.ts contains logic to parse Markdown files, execute the JavaScript code blocks, and verify their correctness. This ensures documentation is always up-to-date and functional.
• Type-Definition Tests: The project uses @fast-check/expect-type and other mechanisms to ensure that the TypeScript types are correct and do not break with new releases of TypeScript.

Sources: CONTRIBUTING.md:96-147, packages/fast-check/test/e2e/documentation/Docs.md.spec.ts, website/package.json:40