tiny-pattern-ts/README.md

tiny-pattern-ts

Pattern matching for TypeScript/ESM environments (F#-style, not regex).

Development

• Build: npm run build
• Test: npm run test, npm run test:ci
• Checks: npm run check, npm run fix
• Individual fixes: npm run fix:oxfmt, npm run fix:oxlint

Tooling

• TypeScript 7 — type checker and build (tsc).
• node --test + --experimental-strip-types — test runner (Node 22.6+, flag dropped on Node 24).
• c8 — code coverage for test:ci.
• oxlint — Rust-based linter. Type-aware rules are enabled via options.typeAware: true in .oxlintrc.json (powered by oxlint-tsgolint).
• oxlint-tsgolint — type-aware linting via typescript-go (declarative via .oxlintrc.json, no CLI flag). Catches unsafe type assertions, unnecessary type parameters, and other type-system issues that regular oxlint can't see. Source-level oxlint-disable directives are used to silence known false positives (e.g., expectTypeOf() in test files).
• oxfmt — Rust-based formatter (Prettier-compatible). Formats JS/TS, JSON/JSONC, YAML, Markdown, MDX, and more; built-in package.json key sorting replaces sort-package-json.
• cspell — spell checking.
• knip — finds unused dependencies, exports, and files. Scoped via --include dependencies,exports,files to skip the noisy types category (which produces false positives for libraries whose exported types are part of the public API).
• publint — validates package.json for ESM publishing correctness. Runs on publish only (in CI), not as part of npm run check.
• @arethetypeswrong/cli (attw) — validates .d.ts declarations against multiple module-resolution scenarios. Runs on publish only with --profile esm-only (the package is intentionally ESM-only).
• lefthook — git pre-commit hooks.

Requirements

• Node.js >= 26 (engines field; pinned via .node-version).

VSCode integration

• Recommended extensions: see .vscode/extensions.json (oxc, cspell).
• TypeScript 7 is used via the typescriptteam.native-preview extension.
• oxc extension provides oxlint squiggles and oxfmt format-on-save.

Workflows

• Version updates via npm version.
• Publishing via GitHub Actions on tagged commits (see .github/workflows/ci.yml); the publish job runs publish:publint and publish:attw before npm publish.

Script prefix convention

Script names follow a prefix convention that signals when they run:

• check:* — read-only verification. Aggregated by npm run check. Used in pre-commit hooks and CI's build job.
• fix:* — mutating counterpart of check:*. Aggregated by npm run fix. Use after npm run check to auto-resolve issues.
• test:* — test scripts. npm run test runs the full suite; test:unit / test:ci are scope-specific variants.
• publish:* — runs only at publish time, in the CI publish job (immediately before npm publish). There is no local npm run publish script — publishing is CI-only by policy.

Contribution guidelines

• Commit signing (GPG).
• Set up commit message template: npm run use:git-commit-message.
• See commit-message-template.
• Type-only tests use expect-type's expectTypeOf(...) inside node --test cases.