Development

The source is TypeScript in src/, built by tsdown into dist/. The rules for anyone working in the repository, people or agents, are in AGENTS.md; the modernization plan, decisions and session notes are under ai-docs/.

Build and test

git clone https://github.com/m4bwav/replace-string-at-position.git
npm ci
npm test

Command	What it does
npm run build	tsdown writes dist/index.mjs, dist/index.cjs, their declarations and source maps
npm test	builds, then runs the golden, unit, property and package-shape suites against both builds
npm run test:dist	the same suites against the dist/ already built
npm run test:consumers	builds, packs, installs the tarball into a temporary project and runs the consumer fixtures
npm run coverage	c8 over the suites, mapped back to src/; fails under 95% of lines or 90% of branches
npm run lint	xo
npm run typecheck	tsc --noEmit
npm run check	publint, attw --pack . and npm pack --dry-run

tsdown needs Node 22.18 or later, or 24, to build; the built files and the tests run on Node 20 and later. test:consumers takes CONSUMER_PACKAGE=replace-string-at-position@<version> to install from npm instead of packing, and CONSUMER_RUNTIMES=bun,deno to add Bun and Deno, which must then be on PATH.

For this wiki, on 2026-09-30, a fresh clone of commit 33b97b5 on Windows with Node 24.18.0 gave:

• npm ci: 493 packages.
• npm test: 177 tests, 177 passed.
• npm run test:consumers: 10 tests, 7 passed and 3 skipped (the Bun and Deno fixtures, not asked for).
• npm run test:consumers with CONSUMER_PACKAGE=replace-string-at-position@2.0.0 and CONSUMER_RUNTIMES=bun,deno (Bun 1.4.2, Deno 2.9.6): 10 tests, 10 passed.

The test suites

• test/golden/: 71 calls recorded from the published 1.0.4. The 26 well-formed ones must give the same answer from both builds; the other 45 are named exceptions that must throw the documented class. The recording is never regenerated from this repository.
• test/unit/: the export shapes, every error message, the boundaries, and a property test of 400 seeded random texts at every position against 1.0.4's formula.
• test/package/: the exact file list of the tarball and its size budget, package.json entry points, and that the builds use no Node or browser globals.
• test/consumers/: eight setups run against the installed package: an ES module, a CommonJS module, the type assertions under TypeScript nodenext (ESM and CommonJS), bundler and node10, and TypeScript 5.9.3 with esModuleInterop off. They use the repository's TypeScript (6.0.3 in the lock file), not TypeScript 7; see Getting started for what 7.0.2 does with the node10 setups.

CI

.github/workflows/ci.yml runs lint and typecheck, the package checks with coverage, the tests on Node 20, 22, 24 and 26 on Ubuntu and on Node 24 on Windows and macOS, and the consumer fixtures under Bun and Deno. Every job installs and builds on Node 24 first, then switches to its own Node line. The master branch ruleset requires the final ci job, which passes only when all the others did.

Releases

1. Update CHANGELOG.md; a release heading carries its date.
2. npm version <major|minor|patch>, then git push --follow-tags.
3. release.yml builds, tests, stages the publish through npm trusted publishing (with provenance) and creates the GitHub Release.
4. The maintainer approves the staged version on npmjs.com with two-factor authentication.
5. Run the verify-published workflow with the version; it installs the release from npm and runs the consumer fixtures on every platform.

Nothing is published from a developer's machine, and no npm token is stored anywhere.

This wiki

The pages live in the wiki's own repository, replace-string-at-position.wiki.git. How they were written and checked, the program that produced every output and how to update them for the next release are in the repository's ai-docs/notes/2026-09-30-github-wiki.md.