pkg-types is a small, ESM-only TypeScript library that provides utilities and type definitions for Node.js configuration files. In production it is consumed as a dependency rather than run as a service: callers use functions such as readPackageJSON, readTSConfig, findWorkspaceDir, resolveLockfile, parseGitConfig, and sortPackage to locate, parse, serialize, and manipulate package.json, tsconfig.json, and .git/config files. It supports package.json, package.json5, package.yaml, JSONC, JSON5, YAML, and git INI formats, with lazy parser loading for JSON5/YAML to keep cold-start cost low. The code is organized into four small vertical slices — resolve, packagejson, tsconfig, and gitconfig — all re-exported from src/index.ts. Path resolution uses exsolve for module-style imports and pathe for cross-platform paths; parsing is delegated to confbox. The primary data flow is simple: an input path is resolved to the nearest or farthest matching file, the file is read and parsed into a typed object, and optionally written back after mutation. There are no API endpoints, data stores, or background processes. Notable implementations include a boundary-aware nearest/farthest file finder that stops at node_modules, workspace directory detection from pnpm/lerna/turbo/rush/deno markers or git config/lockfiles, a Proxy-based updatePackage that auto-creates common package.json map fields during mutation, deterministic package.json sorting/normalizing, and conversion of git's subsection INI format ([remote "origin"]) into generic dotted INI keys for parsing and back on stringify. The project has solid Vitest coverage, type-level tests, and modern CI using oxlint, oxfmt, and obuild. One minor limitation is that git config subsection round-tripping is regex-based and not fully robust for unusual subsection names containing slashes or other non-word characters.
This is a mature Node.js library that makes TypeScript's compile-time path aliases (tsconfig/jsconfig 'paths') work at runtime in plain Node. The code confirms the core claim: src/register.ts patches Module._resolveFilename to intercept module requests, resolves them through tsconfig path mappings, and falls back to Node's original resolution when no mapping matches. The architecture is a clean pipeline: config discovery and loading (tsconfig-loader.ts walks directories, parses JSON5 with comments/trailing commas, resolves 'extends' chains including array form and node_modules packages), mapping construction (mapping-entry.ts sorts patterns by longest prefix and resolves paths to absolute form once), candidate generation (try-path.ts builds file/extension/package.json-main/index probe lists), and matching (match-path-sync.ts and match-path-async.ts) over an injectable filesystem abstraction (filesystem.ts). The public API surface includes register(), loadConfig(), createMatchPath/createMatchPathAsync, and matchFromAbsolutePaths/matchFromAbsolutePathsAsync, plus the 'tsconfig-paths/register' require-hook for CLI usage (node -r tsconfig-paths/register). Data flows from tsconfig.json on disk -> parsed config -> absolute mapping entries -> probed physical paths on each module load. All filesystem operations (fileExists, readJson) are injectable, which makes the test suite pure and deterministic. Runtime dependencies are minimal (json5, minimist, strip-bom), with no network calls, daemons, or persistent state. Craftsmanship is high and the modules are small, single-purpose, and individually extractable. Non-obvious details include: pre-sorting mappings once to avoid per-request sorting; matchStar enforcing a one-character minimum star match; careful async recursion that avoids double-calling callbacks (a real bug that surfaced in tsconfig-paths-webpack-plugin); a suffix-regex that converts .js/.mjs/.cjs requests to .ts/.tsx probes; and a table-driven fixture file (src/__tests__/data/match-path-data.ts) whose 20+ vectors drive both the sync and async test suites, forcing behavioral parity. Code is conservative by design (ES5 target, CommonJS) to support old Node, and strict ESLint rules enforce explicit typing and style. The project is actively maintained (recent commits, an [Unreleased] changelog section, CI matrix on Node 14/16/18). However, the dev toolchain shows measurable drift: TypeScript 4.5, Jest 27, @types/node 6, GitHub Actions versions from 2019-2021, and 'engines' still claiming node >=6 (long EOL). The runtime logic itself remains current and sound; risk is low, but modernization of tooling is overdue. With 1906 stars and 114 open issues, this is the de facto standard for tsconfig paths resolution, relied on by ts-node, mocha setups, and the tsconfig-paths-webpack-plugin.