feat(padStart): add padStart (#323)

* feat: add padStart function

* docs: add padStart doc

benchmarks/performance/padStart.bench.ts

@@ -0,0 +1,15 @@
+import { bench, describe } from 'vitest';
+import { padStart as padStartToolkit } from 'es-toolkit';
+import { padStart as padStartLodash } from 'lodash';
+
+describe('padStart', () => {
+  bench('es-toolkit/padStart', () => {
+    const str = 'abc';
+    padStartToolkit(str, 6, '_-');
+  });
+
+  bench('lodash/padStart', () => {
+    const str = 'abc';
+    padStartLodash(str, 6, '_-');
+  });
+});

docs/.vitepress/en.mts

@@ -193,6 +193,7 @@ function sidebar(): DefaultTheme.Sidebar {
             { text: 'capitalize', link: '/reference/string/capitalize' },
             { text: 'startsWith (compat)', link: '/reference/compat/string/startsWith' },
             { text: 'endsWith (compat)', link: '/reference/compat/string/endsWith' },
+            { text: 'padStart', link: '/reference/string/padStart' },
           ],
         },
       ],

docs/reference/string/padStart.md

@@ -0,0 +1,29 @@
+# padStart
+
+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.
+
+## Signature
+
+```typescript
+function padStart<T extends string>(str: T, length = 0, chars = ' '): string;
+```
+
+## Parameters
+
+- `str`: the string to pad
+- `length`: the length of the resulting string
+- `char`: the character to pad the string with
+
+## Returns
+
+Returns a new string padded with the specified character until it reaches the specified length.
+
+## Examples
+
+```javascript
+padStart('hello', 10, 'a'); // 'aaaaahello'
+padStart('hello', 3, 'a'); // 'hello'
+padStart('hello', 5, ''); // 'hello'
+```

src/string/index.ts

@@ -4,3 +4,4 @@ export { kebabCase } from './kebabCase.ts';
 export { lowerCase } from './lowerCase.ts';
 export { startCase } from './startCase.ts';
 export { capitalize } from './capitalize.ts';
+export { padStart } from './padStart.ts';

src/string/padStart.spec.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { padStart } from './padStart';
+
+describe('padStart', () => {
+  it('should pad a string on the left side if it is shorter than the length', () => {
+    expect(padStart('abc', 6)).toBe('   abc');
+  });
+
+  it('should pad a string on the left side with custom characters', () => {
+    expect(padStart('abc', 6, '_-')).toBe('_-_abc');
+  });
+
+  it('should not pad a string if it has the same length', () => {
+    expect(padStart('abc', 3)).toBe('abc');
+  });
+
+  it('should not pad a string if the length is less than the string length', () => {
+    expect(padStart('abc', 2)).toBe('abc');
+  });
+
+  it('should not pad a string if the length is not a number', () => {
+    expect(padStart('abc', NaN)).toBe('abc');
+  });
+
+  it('should not pad a string if the length is not an integer', () => {
+    expect(padStart('abc', 3.5)).toBe('abc');
+  });
+
+  it('should not pad a string if the length is negative', () => {
+    expect(padStart('abc', -3)).toBe('abc');
+  });
+
+  it('should not pad a string if the length is Infinity', () => {
+    expect(padStart('abc', Infinity)).toBe('abc');
+  });
+
+  it('should not pad a string if the length is -Infinity', () => {
+    expect(padStart('abc', -Infinity)).toBe('abc');
+  });
+});

src/string/padStart.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ *
+ * @template T - The type of the input string.
+ * @param {T} str - The string to pad.
+ * @param {number} [length=0] - The length of the resulting string once padded. Default is 0.
+ * @param {string} [chars=' '] - The character(s) to use for padding. Default is a single space.
+ * @returns {string} - 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'
+ */
+export const padStart = <T extends string>(str: T, length = 0, chars = ' '): string => {
+  if (Number.isSafeInteger(length) && length > str.length && chars.length > 0) {
+    return str.padStart(length, chars);
+  }
+  return str;
+};