es-toolkit/dist/compat/string/padStart.mjs

A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.

import { toString } from "../util/toString.mjs";
import { toInteger } from "../util/toInteger.mjs";
import { createPadding, stringSize } from "../_internal/createPadding.mjs";
//#region src/compat/string/padStart.ts
/**
* Pads the start of a string with a given character until it reaches the specified length.
*
* If the length is less than or equal to the original string's length, or if the padding character is an empty string,
* the original string is returned unchanged.
*
* @param str - The string to pad.
* @param [length] - The length of the resulting string once padded.
* @param [chars] - The character(s) to use for padding.
* @returns The padded string, or the original string if padding is not required.
*
* @example
* const result1 = padStart('abc', 6);          // result will be '   abc'
* const result2 = padStart('abc', 6, '_-');    // result will be '_-_abc'
* const result3 = padStart('abc', 3);          // result will be 'abc'
* const result4 = padStart('abc', 2);          // result will be 'abc'
*/
function padStart(str, length = 0, chars = " ") {
	const value = toString(str);
	const targetLength = toInteger(length);
	const strLength = stringSize(value);
	if (targetLength <= strLength) return value;
	return createPadding(targetLength - strLength, `${chars}`) + value;
}
//#endregion
export { padStart };