0
# Split String
1

2
Split String is a JavaScript utility library that provides intelligent string splitting functionality. Unlike the native `String.split()` method, it respects escaped characters, quoted strings, and nested bracket structures, making it ideal for parsing configuration strings, comma-separated values, and other structured text formats.
3

4
## Package Information
5

6
- **Package Name**: split-string
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install split-string`
10

11
## Core Imports
12

13
```javascript
14
const split = require('split-string');
15
```
16

17
ESM import (requires transpilation or Node.js with ESM support):
18

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

23
TypeScript (using CommonJS require with type definitions):
24

25
```typescript
26
import split = require('split-string');
27
import type { Options, State, ASTNode } from 'split-string';
28
```
29

30
## Basic Usage
31

32
```javascript
33
const split = require('split-string');
34

35
// Basic splitting on dots
36
console.log(split('a.b.c'));
37
//=> ['a', 'b', 'c']
38

39
// Respects escaped characters
40
console.log(split('a.b.c\\.d'));
41
//=> ['a', 'b', 'c.d']
42

43
// Respects quoted strings (when quotes option is provided)
44
console.log(split('a."b.c.d".e', { quotes: ['"'] }));
45
//=> ['a', '"b.c.d"', 'e']
46

47
// Without quotes option, splits inside quoted strings
48
console.log(split('a."b.c.d".e'));
49
//=> ['a', '"b', 'c', 'd"', 'e']
50

51
// Respects nested brackets
52
console.log(split('a.{b.c}.d', { brackets: true }));
53
//=> ['a', '{b.c}', 'd']
54
```
55

56
## Capabilities
57

58
### Main Split Function
59

60
The primary function for splitting strings with intelligent parsing that respects quotes, brackets, and escape sequences. Has multiple overloads for different usage patterns.
61

62
```javascript { .api }
63
/**
64
 * Split a string on a given character unless it's quoted or escaped
65
 */
66
function split(input: string): string[];
67
function split(input: string, options: Options): string[];
68
function split(input: string, fn: SplitFunc): string[];
69
function split(input: string, options: Options, fn: SplitFunc): string[];
70
```
71

72
**Usage Examples:**
73

74
```javascript
75
// Custom separator
76
split('a|b|c', { separator: '|' });
77
//=> ['a', 'b', 'c']
78

79
// Multiple quote types
80
split('a."b.c".\'d.e\'.f', { quotes: ['"', "'"] });
81
//=> ['a', '"b.c"', "'d.e'", 'f']
82

83
// Custom bracket pairs
84
split('a.[b.c].<d.e>.f', { brackets: { '[': ']', '<': '>' } });
85
//=> ['a', '[b.c]', '<d.e>', 'f']
86

87
// Conditional splitting with custom function
88
split('a.b.c.d.e', (state) => state.prev() !== 'b');
89
//=> ['a', 'b.c', 'd', 'e']
90
```
91

92
### Configuration Options
93

94
Options for customizing the splitting behavior.
95

96
```javascript { .api }
97
/**
98
 * Configuration options for split function
99
 * @typedef {Object} Options
100
 * @property {Object|boolean} [brackets] - Bracket pair definitions or true for default brackets
101
 * @property {string[]|boolean} [quotes] - Array of quote characters or true for default quotes  
102
 * @property {string} [separator='.'] - Character to split on
103
 * @property {boolean} [strict=false] - Whether to throw on unmatched brackets
104
 * @property {KeepFunc} [keep] - Function to determine which characters to keep
105
 */
106
```
107

108
**Default Values:**
109
- `separator`: `'.'`
110
- `brackets`: `false` (disabled by default)
111
- `quotes`: `[]` (empty array, disabled by default)
112
- `strict`: `false`
113
- `keep`: Function that excludes backslashes
114

115
**Bracket Configuration:**
116
```javascript
117
// Enable all default brackets
118
{ brackets: true }
119
// Equivalent to: { brackets: { '[': ']', '(': ')', '{': '}', '<': '>' } }
120

121
// Custom bracket pairs (keys are opening brackets, values are closing brackets)
122
{ brackets: { '«': '»', '⟨': '⟩' } }
123

124
// Disabled (default behavior)
125
{ brackets: false } // or omit the property
126
```
127

128
**Quote Configuration:**
129
```javascript
130
// Enable all default quotes
131
{ quotes: true }
132
// Equivalent to: { quotes: ['"', "'", '`'] }
133

134
// Custom quote characters (each character serves as both opener and closer)
135
{ quotes: ['"', '~'] }
136

137
// Disabled (default behavior) 
138
{ quotes: [] } // or omit the property
139
```
140

141
### Custom Split Function
142

143
Function type for implementing custom splitting logic.
144

145
```javascript { .api }
146
/**
147
 * Custom function for controlling split behavior
148
 * @callback SplitFunc
149
 * @param {State} state - Current parsing state
150
 * @returns {boolean} Whether to allow splitting at current position (false prevents split)
151
 */
152
```
153

154
**Usage Example:**
155
```javascript
156
// Only split when previous character is not 'a'
157
const customSplit = (state) => state.prev() !== 'a';
158
split('a.b.c.a.d.e', customSplit);
159
//=> ['a.b.c.a', 'd.e']
160
```
161

162
### Parsing State
163

164
State information available to custom functions and keep functions.
165

166
```javascript { .api }
167
/**
168
 * Parsing state information passed to custom functions and keep functions
169
 * @typedef {Object} State
170
 * @property {string} input - Original input string
171
 * @property {string} separator - Current separator character
172
 * @property {ASTNode[]} stack - Stack of AST nodes being processed
173
 * @property {string} value - Current character value (set during parsing)
174
 * @property {number} index - Current character index (set during parsing)
175
 * @property {ASTNode} block - Current AST block (set during parsing)
176
 * @property {function(): boolean} bos - Returns true if at beginning of string
177
 * @property {function(): boolean} eos - Returns true if at end of string
178
 * @property {function(): string} prev - Returns previous character
179
 * @property {function(): string} next - Returns next character
180
 */
181
```
182

183
### Custom Keep Function
184

185
Function for filtering characters during parsing.
186

187
```javascript { .api }
188
/**
189
 * Function to determine which characters to keep in the output
190
 * @callback KeepFunc
191
 * @param {string} value - Current character being processed
192
 * @param {State} state - Current parsing state
193
 * @returns {boolean} Whether to keep the character (false excludes it)
194
 */
195
```
196

197
**Usage Example:**
198
```javascript
199
// Keep all characters except backslashes and unescaped quotes
200
const keepFunc = (value, state) => {
201
  return value !== '\\' && (value !== '"' || state.prev() === '\\');
202
};
203

204
split('a.b.\\"c.d."e.f.g".h.i', { quotes: ['"'], keep: keepFunc });
205
//=> ['a', 'b', '"c', 'd', 'e.f.g', 'h', 'i']
206
```
207

208
## Types
209

210
### AST Node Structure
211

212
Internal abstract syntax tree node structure used during parsing.
213

214
```javascript { .api }
215
/**
216
 * Abstract syntax tree node structure used internally during parsing
217
 * @typedef {Object} ASTNode
218
 * @property {'root'|'bracket'} type - Node type ('root' for main document, 'bracket' for bracketed sections)
219
 * @property {ASTNode[]} nodes - Child nodes
220
 * @property {string[]} stash - Accumulated string segments
221
 * @property {ASTNode} [parent] - Parent node reference (undefined for root)
222
 */
223
```
224

225
## Error Handling
226

227
The function handles various error conditions:
228

229
- **TypeError**: Thrown when input is not a string
230
- **SyntaxError**: Thrown in strict mode when brackets are unmatched
231
- **Graceful degradation**: Unmatched brackets are handled gracefully in non-strict mode
232

233
```javascript
234
// Error examples
235
try {
236
  split(123); // TypeError: expected a string
237
} catch (error) {
238
  console.error(error.message);
239
}
240

241
try {
242
  split('a.{b.c', { brackets: true, strict: true }); // SyntaxError: Unmatched
243
} catch (error) {
244
  console.error(error.message);
245
}
246

247
// Non-strict mode handles unmatched brackets gracefully
248
split('a.{b.c', { brackets: true });
249
//=> ['a', '{b', 'c']
250
```
251

252
## Advanced Usage Patterns
253

254
### Parsing Configuration Strings
255

256
```javascript
257
// Parse dotted configuration paths
258
const config = 'database.connection.host';
259
const parts = split(config);
260
//=> ['database', 'connection', 'host']
261

262
// Handle escaped dots in values
263
const configWithEscapes = 'app.name.my\\.app\\.name';
264
const parts2 = split(configWithEscapes);
265
//=> ['app', 'name', 'my.app.name']
266
```
267

268
### Processing CSV-like Data
269

270
```javascript
271
// Parse quoted CSV fields
272
const csvField = 'name,"Smith, John",age';
273
const fields = split(csvField, { separator: ',', quotes: ['"'] });
274
//=> ['name', '"Smith, John"', 'age']
275
```
276

277
### Parsing Nested Structures
278

279
```javascript
280
// Parse object-like strings
281
const objectString = 'a.{b.{c.d}.e}.f';
282
const parsed = split(objectString, { brackets: true });
283
//=> ['a', '{b.{c.d}.e}', 'f']
284

285
// Parse arrays and mixed brackets
286
const mixedString = 'a.[b.{c.d}].e';
287
const mixed = split(mixedString, { brackets: true });
288
//=> ['a', '[b.{c.d}]', 'e']
289
```