0
# Indent String
1

2
Indent String is a simple and efficient utility for indenting each line in a string with customizable indentation characters and count. It provides flexible options including custom indent characters, control over empty line indentation, and precise count control.
3

4
## Package Information
5

6
- **Package Name**: indent-string
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules with TypeScript definitions)
9
- **Installation**: `npm install indent-string`
10

11
## Core Imports
12

13
```javascript
14
import indentString from "indent-string";
15
```
16

17
For CommonJS (requires Node.js dynamic import):
18

19
```javascript
20
const { default: indentString } = await import("indent-string");
21
```
22

23
TypeScript with types:
24

25
```typescript
26
import indentString, { Options } from "indent-string";
27
```
28

29
## Basic Usage
30

31
```javascript
32
import indentString from "indent-string";
33

34
// Basic indentation (default: 1 space)
35
indentString('Unicorns\nRainbows');
36
//=> ' Unicorns\n Rainbows'
37

38
// Custom count
39
indentString('Unicorns\nRainbows', 4);
40
//=> '    Unicorns\n    Rainbows'
41

42
// Custom indent character
43
indentString('Unicorns\nRainbows', 4, {indent: '♥'});
44
//=> '♥♥♥♥Unicorns\n♥♥♥♥Rainbows'
45

46
// Include empty lines
47
indentString('foo\n\nbar', 2, {includeEmptyLines: true});
48
//=> '  foo\n  \n  bar'
49
```
50

51
## Capabilities
52

53
### String Indentation
54

55
Indents each line in a string with customizable indentation.
56

57
```javascript { .api }
58
/**
59
 * Indent each line in a string
60
 * @param string - The string to indent
61
 * @param count - How many times to repeat the indent string (default: 1)
62
 * @param options - Configuration options
63
 * @returns The indented string
64
 * @throws {TypeError} If string is not a string (message: "Expected `input` to be a `string`, got `type`")
65
 * @throws {TypeError} If count is not a number
66
 * @throws {RangeError} If count is negative
67
 * @throws {TypeError} If options.indent is not a string
68
 */
69
export default function indentString(string: string, count?: number, options?: Options): string;
70
```
71

72
**Parameters:**
73
- `string` (string, required): The string to indent
74
- `count` (number, optional, default: 1): How many times to repeat the indent string
75
- `options` (object, optional): Configuration options
76

77
**Options:**
78
- `indent` (string, optional, default: ' '): The string to use for indentation
79
- `includeEmptyLines` (boolean, optional, default: false): Whether to indent empty lines
80

81
**Return Value:**
82
Returns the string with each line indented according to the specified parameters.
83

84
**Error Handling:**
85
- Throws `TypeError` if `string` parameter is not a string (message: "Expected `input` to be a `string`, got `type`")
86
- Throws `TypeError` if `count` parameter is not a number (message: "Expected `count` to be a `number`, got `type`")
87
- Throws `RangeError` if `count` parameter is negative (message: "Expected `count` to be at least 0, got `value`")
88
- Throws `TypeError` if `options.indent` is not a string (message: "Expected `options.indent` to be a `string`, got `type`")
89

90
**Usage Examples:**
91

92
```javascript
93
// Zero count returns original string
94
indentString('foo\nbar', 0);
95
//=> 'foo\nbar'
96

97
// Works with various line endings
98
indentString('foo\r\nbar', 2);
99
//=> '  foo\r\n  bar'
100

101
// Preserves existing indentation
102
indentString(' foo\n bar', 1);
103
//=> '  foo\n  bar'
104

105
// Empty lines not indented by default
106
indentString('foo\n\nbar', 2);
107
//=> '  foo\n\n  bar'
108

109
// Including empty lines
110
indentString('foo\n\nbar', 2, {includeEmptyLines: true});
111
//=> '  foo\n  \n  bar'
112

113
// Custom indent characters
114
indentString('line1\nline2', 3, {indent: '->'});
115
//=> '->->->line1\n->->->line2'
116
```
117

118
## Types
119

120
```typescript { .api }
121
interface Options {
122
  /** The string to use for the indent (default: ' ') */
123
  readonly indent?: string;
124
  /** Also indent empty lines (default: false) */
125
  readonly includeEmptyLines?: boolean;
126
}
127
```