0
# Repeat String
1

2
Repeat String is a high-performance string repetition utility that repeats a given string a specified number of times using an optimized algorithm. The library implements efficient caching and bit manipulation techniques to achieve superior performance compared to native JavaScript string repetition methods and other similar libraries.
3

4
## Package Information
5

6
- **Package Name**: repeat-string
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install repeat-string`
10

11
## Core Imports
12

13
```javascript
14
var repeat = require('repeat-string');
15
```
16

17
For ES modules (Node.js with CommonJS interop):
18

19
```javascript
20
import repeat from 'repeat-string';
21
```
22

23
Or with named import syntax:
24

25
```javascript
26
import * as repeatString from 'repeat-string';
27
const repeat = repeatString.default;
28
```
29

30
## Basic Usage
31

32
```javascript
33
var repeat = require('repeat-string');
34

35
// Basic string repetition
36
repeat('A', 5);
37
//=> 'AAAAA'
38

39
// Repeat with spaces
40
repeat('abc ', 3);
41
//=> 'abc abc abc '
42

43
// Edge cases
44
repeat('x', 0);  //=> ''
45
repeat('x', 1);  //=> 'x'
46
repeat('x', 2);  //=> 'xx'
47
```
48

49
## Architecture
50

51
Repeat String uses an optimized bit manipulation algorithm with internal caching for maximum performance:
52

53
- **Caching System**: Stores partial results to avoid recomputation when repeating the same string
54
- **Bit Manipulation**: Uses bitwise operations (`&`, `>>`) for efficient string doubling
55
- **Input Validation**: Validates input types and throws descriptive errors
56
- **Edge Case Optimization**: Special handling for common cases (0, 1, 2 repetitions)
57

58
## Capabilities
59

60
### String Repetition
61

62
Repeats a string n times with optimized performance using caching and bit manipulation.
63

64
```javascript { .api }
65
/**
66
 * Repeat the given string the specified number of times
67
 * @param {string} str - The string to repeat
68
 * @param {number|string} num - The number of times to repeat the string
69
 * @returns {string} The repeated string
70
 * @throws {TypeError} When str is not a string
71
 */
72
function repeat(str, num);
73
```
74

75
**Parameters:**
76
- `str` (string): The string to repeat. Must be a string value, throws TypeError otherwise.
77
- `num` (number|string): The number of times to repeat the string. Accepts both numbers and string representations of numbers. Values of 0, null, or undefined return empty string.
78

79
**Returns:**
80
- `string`: The input string repeated the specified number of times.
81

82
**Throws:**
83
- `TypeError`: When the first parameter is not a string. Error message: "expected a string"
84

85
**Usage Examples:**
86

87
```javascript
88
var repeat = require('repeat-string');
89

90
// Basic repetition
91
repeat('A', 5);     //=> 'AAAAA'
92
repeat('hello', 3); //=> 'hellohellohello'
93

94
// String numbers work too
95
repeat('x', '10');  //=> 'xxxxxxxxxx'
96

97
// Edge cases
98
repeat('test', 0);   //=> ''
99
repeat('test', 1);   //=> 'test'
100
repeat('', 5);       //=> ''
101

102
// Whitespace and special characters
103
repeat(' ', 5);      //=> '     '
104
repeat('\\n', 3);    //=> '\\n\\n\\n'
105
repeat('🚀', 3);     //=> '🚀🚀🚀'
106

107
// Error cases
108
repeat(123, 5);      // Throws TypeError: expected a string
109
repeat(null, 5);     // Throws TypeError: expected a string
110
```
111

112
## Performance Characteristics
113

114
The library uses several optimization techniques:
115

116
1. **Quick Returns**: Immediate returns for common cases (num === 1, num === 2)
117
2. **Result Caching**: Caches results when repeating the same string multiple times
118
3. **Bitwise Algorithm**: Uses bit manipulation for efficient string doubling
119
4. **Cache Reuse**: Reuses cached results when possible to avoid recomputation
120

121
This makes repeat-string significantly faster than native `String.prototype.repeat()` and other string repetition libraries, especially for repeated operations on the same string.