Thanks for taking an interest. This is a small library and the bar for a contribution is low, but there are a few environment-specific traps that cost real time if you hit them cold.
npm ci # NOT npm install -- see the note about --omit=optional below
npm run build # clean + compile + testnpm ci reads package-lock.json. It should complete with no lifecycle-script
output; if you see scripts running, something is wrong with .npmrc.
TypeScript 7 ships its actual compiler as a platform-specific
optionalDependency. npm ci --omit=optional (or --no-optional) deletes the
compiler and you get a build that fails in a way that looks like a TypeScript bug.
This repo has been bitten by it before.
The same applies to NODE_ENV=production installs.
This repo ships an .npmrc with:
ignore-scripts=true— dependency lifecycle scripts never run on install.min-release-age=7— refuses package versions published less than 7 days ago.
Both are deliberate supply-chain controls. If a dependency legitimately needs an install script, do not remove the setting globally; raise it as a question first.
If you change min-release-age, change cooldown.default-days in
.github/dependabot.yml to match. npm enforces the gate with
ETARGET: No matching version found for <pkg>@<ver> with a date before <date>,
which reads like "this version does not exist" rather than "this version is too
new". If the two drift apart, dependabot opens PRs that fail CI pointing at an
apparently broken dependency instead of at the quarantine.
.github/dependabot.yml validates cleanly against
json.schemastore.org/dependabot-2.0 and can still be rejected by GitHub,
because the published schema is generic across ecosystems and the
ecosystem-specific rules live only in GitHub's own validator. Concretely:
cooldown.semver-major-days/-minor-/-patch-are accepted for npm only. Ongithub-actionsGitHub rejects the file withThe property '#/updates/N/cooldown/semver-major-days' is not supported for the package ecosystem 'github-actions'.- While the config is invalid, Dependabot stops running version updates for the whole file — the damage is not confined to the offending entry.
So "the schema says it's fine" is not evidence. npm run check:dependabot
(which runs as part of npm test) enforces the ecosystem rule and also checks
that cooldown.default-days is not shorter than min-release-age in .npmrc.
Write BigInt(1), not 1n. A literal is a syntax error against some of the
compilation targets this project has historically supported, and the check that
enforces it is a lint rule that is easy to bypass locally.
In the Scalar abstraction, unbounded bounds are explicit values the scalar
owns. There is no "absent means unbounded" convention, and null and
undefined are never conflated. Checks are directional — isPlusInfinity() /
isMinusInfinity() — and there is deliberately no single isInfinity() that
could merge the two signs.
number keeps its native ±Infinity and is not given the synthetic sentinel
treatment; replacing a native capability changes behaviour for no gain.
Import from "range-ts". require("range-ts/dist/cjs/index.js") fails with
ERR_PACKAGE_PATH_NOT_EXPORTED. Everything public is reachable from the package
root; if you find yourself wanting a deep import, that is a signal something is
missing from the index and worth an issue.
| Command | What it does |
|---|---|
npm test |
Runs all three environments (node, jsdom, chrome) |
npm run test:node |
Specs in Node only |
npm run test:jsdom |
Specs in jsdom |
npm run test:chrome |
Specs in real Chrome. Compiles its own target and refuses to report success over a zero-spec run |
npm run test:mutation |
Stryker. Run npm run compile:spec-node first if you have not built |
npm run build |
build:clean + compile + test |
test:chrome needs a Chromium binary on PATH. It is resolved by PATH lookup, so
it works on any machine with Chrome/Chromium installed; it does not assume nix.
- New behaviour needs a test that fails without it. Mutation score is tracked; a change that lowers it will be asked about.
- Tests run in three environments for a reason. If you add something DOM-related, it belongs in the jsdom/chrome path, not the node path.
toThrowError(...)is required for regex matching under Jasmine 5;toThrowdoes not behave as expected there.
- Formatting is Prettier, configured in
.prettierrc.json(100 columns, double quotes, ES5 trailing commas) with.prettierignorefor build output. Runnpm run formatbefore pushing; CI runsnpm run format:checkand fails on drift. - There is deliberately no pre-commit hook. The repo sets
ignore-scripts=truein.npmrc, and the usual way to install a hook (husky) needs apostinstallscript to do it — so the hook would either require weakening the install hardening or a manualgit configstep per clone. A previous.lintstagedrc.jsonhere advertised commit-time formatting that never ran, because no hook was ever installed and nothing checked. CI gating is the control; a local hook is a convenience, not a guarantee. - Match the existing structure:
src/core(scalar abstraction),src/range,src/range-map. - Prefer fixing things in the build over fixing them in the source. The sources
should stay plain, modern TypeScript; target-specific quirks (like adding
.jsextensions to ESM relative imports) belong inscripts/finalize-dist.mjs.
- Open an issue before anything that changes the public API surface.
- Breaking changes are fine for a major version but must be listed in
CHANGELOG.mdunder a### Breakingheading with the reason, not just the what. CHANGELOG.mdfollows Keep a Changelog conventions.
See RELEASE.md. Note that releasing is a maintainer action and that CI deliberately stops at "staged" — promotion requires a human with 2FA.