NPM Package Setup and Deployment

Relevant source files

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

• package.json
• tsconfig.json
• biome.json
• README.md
• test/sizzle.spec.ts
• tsconfig.eslint.json

cheerio-select is a CSS selector engine supporting jQuery selectors, built as a wrapper around the css-select library. The package is structured to support multiple module systems (CommonJS and ESM) and provides comprehensive TypeScript definitions. Its setup emphasizes strict type checking, automated linting, and a robust testing suite based on the Sizzle test library.

Sources: package.json:3-5, README.md:1-5

Module Structure and Exports

The package uses a dual-build system to ensure compatibility across different environments. It is configured as a commonjs type by default but explicitly exports both CommonJS and ESM entry points.

Export Configuration

The project utilizes the exports field in package.json to map import paths to specific build outputs:

Export Type	Path	Purpose
import	./lib/esm/index.js	ECMAScript Module entry point
require	./lib/index.js	CommonJS entry point
types	lib/index.d.ts	TypeScript declaration files

Sources: package.json:2, 17-21

Build Pipeline

The build process is managed via NPM scripts that invoke the TypeScript compiler (tsc). It generates two distinct sets of output in the lib/ directory.

The ESM build process specifically includes a step to echo {"type":"module"} into the lib/esm/package.json file to ensure proper Node.js resolution.

Sources: package.json:23-26

Development Environment Setup

The development environment is governed by TypeScript configurations and strict linting rules provided by Biome and ESLint.

TypeScript Configuration

The project uses a base tsconfig.json for the source code and an extension for the testing environment.

• Compiler Options: Targets es5 with commonjs modules for the primary output. It enforces strict type checking through flags like strict: true, noUnusedLocals: true, and noImplicitReturns: true.
• Source Mapping: declarationMap and sourceMap are enabled to aid debugging.
• Path Mapping: The build script uses git rev-parse HEAD to dynamically set the sourceRoot for source maps, linking them to the specific commit on GitHub.

Sources: tsconfig.json:3-33, package.json:24

Linting and Formatting

Code quality is maintained using two primary tools: Biome and ESLint.

Biome is configured to include .ts, .md, .json, and .yml files while ignoring node_modules, coverage, and lib. It enforces specific performance and style rules, such as useTopLevelRegex and useConsistentTypeDefinitions.

Sources: biome.json:7-14, 21-65, package.json:28-33

Testing and Quality Assurance

The project employs a rigorous testing strategy using Jest and fixtures derived from the Sizzle selector engine.

Test Configuration

Tests are executed via jest with the ts-jest preset. The environment is set to node, and coverage is provided by the v8 provider.

Tool	Usage
Jest	Test runner and assertion library
ts-jest	Enables Jest to process TypeScript files
htmlparser2	Used to parse DOM fixtures for testing
domutils	Used for DOM manipulation during tests

Sources: package.json:44-55, 60-68, test/sizzle.spec.ts:1-5

Sizzle Test Integration

A significant portion of the testing suite (test/sizzle.spec.ts) replicates the Sizzle test suite to ensure compatibility with jQuery-style selectors. This involves loading HTML fixtures (e.g., sizzle.html) and validating selectors against a simulated DOM.

Dependencies and Maintenance

Core Dependencies

The engine relies on a modular stack of DOM and CSS utilities:

• css-select & css-what: The underlying CSS engine and parser.
• domhandler, domutils, domelementtype: Utilities for managing and traversing the DOM.
• boolbase: A basic utility for boolean functions.

Sources: package.json:37-43

Lifecycle Scripts

The package.json defines a prepare script that triggers a full build before the package is packed or published, ensuring the lib/ directory is always up to date.

Sources: package.json:34

The project uses a BSD-2-Clause license and provides a dedicated security contact via Tidelift.

Sources: package.json:11, README.md:61-66