Build Toolchain

Relevant source files

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

• package.json
• tsconfig.json
• tsconfig.build.json
• AGENTS.md
• vitest.config.ts
• README.md

The @b2m9/keyfold project utilizes a modern, ESM-only TypeScript toolchain designed for Node.js environments (version 22 and above). The toolchain emphasizes strict type safety, high-performance linting, and automated validation of the published package structure. It is architected to produce a zero-dependency, tree-shakeable library that maintains deterministic behavior across different environments.

Sources: AGENTS.md:12-14, package.json:69-71, README.md:38-40

Core Development Environment

The project is built using TypeScript and distributed as a pure ESM package. The environment is managed through npm and requires Node.js >= 22.

TypeScript Configuration

The project uses two primary TypeScript configurations to separate development/testing from production builds:

• Base Configuration (tsconfig.json): Sets the target to ES2022 and enables strict type checking, including exactOptionalPropertyTypes and noUncheckedIndexedAccess.
• Build Configuration (tsconfig.build.json): Extends the base config to target the src directory and output the compiled code to the dist folder for distribution.

Sources: tsconfig.json:3-19, tsconfig.build.json:3-8

Build & Package Flow

The following diagram illustrates the flow from source TypeScript files to a published ESM package.

The diagram shows how source files are compiled into JavaScript and declaration files, which are then validated by specific tools before publishing.
Sources: package.json:39-51, tsconfig.build.json:3-8

Tooling and Automation

The toolchain integrates several specialized utilities to ensure code quality and package integrity.

Linting and Formatting

The project favors high-performance Rust-based tools for code quality:

• Oxlint: Used for static analysis and linting.
• Oxfmt: Used for code formatting and checking.

Sources: AGENTS.md:14-16, package.json:57-59

Validation Tools

To ensure the published package is compatible with the ESM ecosystem, the toolchain includes:

• publint: Validates package.json exports and structure for compatibility issues.
• attw (Are The Types Wrong): Specifically checks if the published types are correctly resolved in ESM environments.

Sources: package.json:60-61, AGENTS.md:15-16

Test Infrastructure

Testing is handled by Vitest, configured for a Node.js environment. The toolchain supports both single runs and watch mode for iterative development.

Sources: vitest.config.ts:3-8, package.json:55-56

Build Scripts Summary

The package.json defines a comprehensive suite of scripts for the development lifecycle:

Script	Command	Description
build	tsc -p tsconfig.build.json	Compiles source to dist directory.
typecheck	tsc --noEmit -p tsconfig.json	Runs full type validation without emitting files.
test	vitest run	Executes the test suite once.
lint	oxlint .	Lints the codebase using Oxlint.
format	oxfmt --check .	Verifies code formatting.
check	npm run typecheck && npm run test && ...	Full validation suite (types, tests, lint, format, build, publint, attw).
prepack	npm run build	Ensures a fresh build exists before package creation.

Sources: package.json:53-63

Project Constraints

The toolchain is designed to enforce specific architectural constraints recorded in the project's agent guide:

• ESM-only: No CommonJS support is provided or intended.
• Zero runtime dependencies: The published package must only contain its own code; all tools are listed as devDependencies.
• Immutability: The build ensures that the logic for immutable folding is preserved through rigorous testing (Vitest and fast-check).

Sources: AGENTS.md:12-21, package.json:65-74

The @b2m9/keyfold build toolchain provides a high-confidence environment for developing and shipping a specialized state-folding library. By combining strict TypeScript configurations with ecosystem-aware validation tools like publint and attw, it ensures the library remains reliable, deterministic, and correctly typed for all consumers.