0
# Micromark Util Chunked
1

2
Optimized array manipulation utilities specifically designed to handle giant arrays without causing V8 stack overflows. This package provides essential performance optimizations for micromark ecosystem extensions that need to process large amounts of data in parsing and tokenization scenarios.
3

4
## Package Information
5

6
- **Package Name**: micromark-util-chunked
7
- **Package Type**: npm
8
- **Language**: JavaScript (ESM)
9
- **Installation**: `npm install micromark-util-chunked`
10

11
## Core Imports
12

13
```javascript
14
import {push, splice} from 'micromark-util-chunked';
15
```
16

17
For environments with ESM.sh:
18

19
```javascript
20
import {push, splice} from 'https://esm.sh/micromark-util-chunked@2';
21
```
22

23
## Basic Usage
24

25
```javascript
26
import {push, splice} from 'micromark-util-chunked';
27

28
// Efficiently append items to a large array
29
const events = [];
30
const newEvents = [['enter', token, context], ['exit', token, context]];
31
const result = push(events, newEvents);
32

33
// Safely splice large arrays without stack overflow
34
const largeArray = new Array(50000).fill().map((_, i) => i);
35
const itemsToInsert = new Array(20000).fill('new-item');
36
splice(largeArray, 1000, 5000, itemsToInsert);
37
```
38

39
## Capabilities
40

41
### Array Appending
42

43
Efficiently appends items to arrays with performance optimizations for empty lists and batch processing to prevent V8 engine issues.
44

45
```javascript { .api }
46
/**
47
 * Append items (an array) at the end of list (another array).
48
 * When list was empty, returns items instead.
49
 * 
50
 * @param {Array<T>} list - List to operate on
51
 * @param {Array<T>} items - Items to add to list
52
 * @returns {Array<T>} Either list or items
53
 */
54
function push(list, items);
55
```
56

57
**Key Features:**
58
- Returns `items` directly when `list` is empty for performance
59
- Uses chunked insertion to prevent V8 hanging on large datasets
60
- Maintains type safety with generic type parameters
61

62
### Array Splicing
63

64
Safe array splicing for giant arrays that prevents V8 stack overflow by chunking operations when dealing with large datasets.
65

66
```javascript { .api }
67
/**
68
 * Like Array#splice, but smarter for giant arrays.
69
 * Does not return removed items and takes items as array instead of rest parameters.
70
 * 
71
 * @param {Array<T>} list - List to operate on
72
 * @param {number} start - Index to remove/insert at (can be negative)
73
 * @param {number} remove - Number of items to remove
74
 * @param {Array<T>} items - Items to inject into list
75
 * @returns {undefined} Nothing
76
 */
77
function splice(list, start, remove, items);
78
```
79

80
**Key Features:**
81
- Handles negative start indices correctly
82
- Chunks operations for arrays with >10,000 items to prevent stack overflow
83
- More efficient than native `Array#splice` for large operations
84
- Does not return removed items (unlike native splice)
85

86
**Usage Examples:**
87

88
```javascript
89
import {splice} from 'micromark-util-chunked';
90

91
// Insert many items at the beginning
92
const items = new Array(15000).fill('data');
93
const insertItems = new Array(5000).fill('new-data');
94
splice(items, 0, 0, insertItems);
95

96
// Replace items in the middle with negative indexing
97
splice(items, -1000, 500, ['replacement1', 'replacement2']);
98

99
// Remove items without replacement
100
splice(items, 100, 50, []);
101
```
102

103
## Performance Characteristics
104

105
This utility is designed for scenarios where arrays can grow to hundreds of thousands of elements:
106

107
- **Chunking Strategy**: Operations are batched in chunks of 10,000 items (defined by `constants.v8MaxSafeChunkSize` from micromark-util-symbol)
108
- **Memory Efficiency**: Avoids expensive operations on empty arrays
109
- **Stack Safety**: Prevents stack overflow that occurs with native methods on giant arrays
110
- **Cross-Platform**: Works consistently across Node.js, Deno, and browser environments
111

112
## Use Cases
113

114
- **Markdown Parsing**: Processing large markdown documents with many tokens
115
- **Event Systems**: Managing large event arrays in micromark extensions  
116
- **Token Manipulation**: Inserting/removing large numbers of parsing tokens
117
- **Data Processing**: Any scenario requiring manipulation of arrays with >10k elements
118

119
## Compatibility
120

121
- **Node.js**: Version 16+
122
- **Browsers**: Modern browsers with ESM support
123
- **Deno**: Full support
124
- **TypeScript**: Fully typed with JSDoc annotations
125
- **Module Type**: ESM only (`"type": "module"`)