API Reference

The package exports one function. This page describes 2.0.0. The function and its four parameters are the ones 1.0.4 had; the members marked 2.0.0 below are new in that release. (1.0.0 to 1.0.3 were not installed for this wiki.)

replaceStringAtPosition(originalString, sourceString, newString, position)

declare function replaceStringAtPosition(originalString: string, sourceString: string, newString: string, position: number): string;

Returns originalString with the part that starts at position and is sourceString.length code units long replaced by newString. In code, it returns text.slice(0, position) + newString + text.slice(position + sourceString.length) after checking the arguments (How text is replaced).

Parameter	Type	What it is
originalString	string	The text to change. A String object is read by its own value.
sourceString	string	The text being replaced. Only its length is used; it is never compared with the text at position.
newString	string	The text to put in its place. May be empty, which deletes.
position	number	Where the replaced part starts, in UTF-16 code units: an integer from 0 to originalString.length. -0 counts as 0.

Returns a new string. The arguments are not changed, this is not read (a detached call works), and arguments after the fourth are ignored.

Throws:

Error	When	Message
TypeError	a text argument is not a string or a String object	Expected `originalString` to be a string, got null (the argument's name and what it got)
TypeError	position is not of type number (a missing position, a numeric string, a Number object, a BigInt)	Expected `position` to be a number, got the string "1"
RangeError	position is a number but not a safe integer from 0 to the text's length (negative, fractional, NaN, Infinity, past the end)	Expected `position` to be an integer from 0 to 3, got 10

The errors are plain TypeError and RangeError objects with no code or other extra properties. Every message, and the order in which the arguments are checked, is on Edge cases and errors. Before 2.0.0 there were no checks at all (Versions and upgrading).

What each build exports

Build	Loaded by	Exports	Since
dist/index.cjs	require('replace-string-at-position')	the function itself (module.exports), carrying .default and .replaceStringAtPosition, both the same function	the function as in 1.0.4; the two properties since 2.0.0
dist/index.mjs	import	default and replaceStringAtPosition, the same function	2.0.0 (1.x had no ES module build)
dist/index.d.cts	TypeScript, for require() and CommonJS files	export = of the callable with its two properties	2.0.0
dist/index.d.mts	TypeScript, for import	the function as a named export and as default	2.0.0

The exports map allows only replace-string-at-position and replace-string-at-position/package.json; deep imports such as replace-string-at-position/index.js fail with ERR_PACKAGE_PATH_NOT_EXPORTED (Versions and upgrading).

In CommonJS:

const replaceStringAtPosition = require('replace-string-at-position');

console.log(typeof replaceStringAtPosition, replaceStringAtPosition.name, replaceStringAtPosition.length);
console.log(Object.keys(replaceStringAtPosition));

prints:

function replaceStringAtPosition 4
[ 'default', 'replaceStringAtPosition' ]

In an ES module, the namespace has the two names, and the function there has no .default of its own:

import * as module from 'replace-string-at-position';

console.log(Object.keys(module));
console.log(module.default === module.replaceStringAtPosition, module.default.default);

prints:

[ 'default', 'replaceStringAtPosition' ]
true undefined

Two builds, two functions

The ES module and CommonJS builds each hold their own copy of the function. A program that loads the package both ways gets two different objects:

import {createRequire} from 'node:module';
import replaceStringAtPosition from 'replace-string-at-position';

const require = createRequire(import.meta.url);
console.log(require('replace-string-at-position') === replaceStringAtPosition);

prints:

false

The function keeps no state, so this only matters to code that compares the function by identity or adds properties to it.

Package facts

Field	Value in 2.0.0
type	module
main	./dist/index.cjs
module	./dist/index.mjs
types	./dist/index.d.cts
sideEffects	false
engines.node	>=20
dependencies	none
bin	none
Files	10, 29,643 bytes unpacked (read from the registry on 2026-09-30)
Provenance	yes, published from GitHub Actions through npm trusted publishing