{"id":11308,"library":"micromark-util-chunked","title":"Micromark Utility for Chunked Array Operations","description":"micromark-util-chunked is a specialized utility package within the `micromark` ecosystem, designed to perform array manipulations (`push` and `splice`) efficiently when dealing with exceptionally large arrays. Its primary purpose is to circumvent performance bottlenecks and V8 engine limitations, such as stack overflows, that can occur with native `Array.prototype.splice` when a massive number of items are involved. The current stable version is `2.0.1` (though the micromark monorepo has related packages at `4.x.x`). As part of the `micromark` monorepo, its updates typically align with the broader `micromark` project's active release schedule. A key differentiator is its optimized algorithms for chunked operations, ensuring stability and performance for complex parsing tasks often encountered within markdown processing. The package is ESM-only and ships with full TypeScript type definitions.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/micromark/micromark#main","tags":["javascript","micromark","util","utility","chunk","splice","push","typescript"],"install":[{"cmd":"npm install micromark-util-chunked","lang":"bash","label":"npm"},{"cmd":"yarn add micromark-util-chunked","lang":"bash","label":"yarn"},{"cmd":"pnpm add micromark-util-chunked","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only. CommonJS `require` will result in an `ERR_REQUIRE_ESM` error. There is no default export.","wrong":"const { push } = require('micromark-util-chunked')","symbol":"push","correct":"import { push } from 'micromark-util-chunked'"},{"note":"The `splice` function is a named export. Attempting to use a default import will fail.","wrong":"import splice from 'micromark-util-chunked'","symbol":"splice","correct":"import { splice } from 'micromark-util-chunked'"},{"note":"While `import * as` works, directly named imports are generally preferred for clarity and tree-shaking benefits for this module's two primary exports.","wrong":"import * as chunked from 'micromark-util-chunked'; chunked.push(...);","symbol":"push, splice","correct":"import { push, splice } from 'micromark-util-chunked'"}],"quickstart":{"code":"import { push, splice } from 'micromark-util-chunked';\n\n// Simulate a context object often used in micromark tokenizers\nconst context = { document: 'Some markdown string with lots of tokens...' };\n\n// Initialize an array of \"events\" (e.g., tokens or state changes).\n// Start with a moderately large array to demonstrate the utility's purpose.\nlet events: Array<[string, any, typeof context]> = [];\n\n// Populate with some initial data using `push`\nfor (let i = 0; i < 5000; i++) {\n  events = push(events, [['text', { type: 'text', value: `item-${i}` }, context]]);\n}\n\nconsole.log(`Initial events length: ${events.length}`);\n// Expected output: Initial events length: 5000\n\n// Demonstrate `push` with a large chunk of new items, which avoids V8 stack limits\nconst newItemsToAdd: Array<[string, any, typeof context]> = [];\nfor (let i = 0; i < 10000; i++) {\n  newItemsToAdd.push(['token', { type: 'new_token', value: `added-${i}` }, context]);\n}\nevents = push(events, newItemsToAdd);\nconsole.log(`Length after large push: ${events.length}`);\n// Expected output: Length after large push: 15000\n\n// Demonstrate `splice`: removing existing items and inserting new ones.\n// Let's remove 500 items from index 1000 and insert 2000 new ones.\nconst itemsToInsert: Array<[string, any, typeof context]> = [];\nfor (let i = 0; i < 2000; i++) {\n  itemsToInsert.push(['insert', { type: 'inserted', value: `inserted-${i}` }, context]);\n}\n\nconst startIndex = 1000;\nconst itemsToRemove = 500;\nsplice(events, startIndex, itemsToRemove, itemsToInsert);\nconsole.log(`Length after splice: ${events.length}`);\n// Expected output: Length after splice: 16500 (15000 - 500 + 2000)\n\n// Verify a few items around the spliced area\nconsole.log('Item before splice start:', events[startIndex - 1]);\nconsole.log('First inserted item:', events[startIndex]);\nconsole.log('Last inserted item:', events[startIndex + itemsToInsert.length - 1]);\nconsole.log('Item after inserted block:', events[startIndex + itemsToInsert.length]);\n\n// Example of a small final push\nevents = push(events, [['final', { type: 'end' }, context]]);\nconsole.log(`Length after final push: ${events.length}`);\n// Expected output: Length after final push: 16501\n","lang":"typescript","description":"This quickstart demonstrates how to use `push` and `splice` from `micromark-util-chunked` to efficiently manage large arrays of 'events' (e.g., markdown tokens), avoiding V8 limitations."},"warnings":[{"fix":"Migrate your import statements to ES module syntax: `import { push, splice } from 'micromark-util-chunked';`","message":"This package is ESM-only. Attempting to use `require()` for importing will result in an `ERR_REQUIRE_ESM` error. This has been the case since its initial major release.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always use `micromark-util-chunked`'s `splice` function when dealing with potentially giant arrays to avoid V8's argument limits.","message":"Using native `Array.prototype.splice` with an extremely large number of items (e.g., 100,000+) can lead to a 'RangeError: Maximum call stack size exceeded' in V8, which this package is designed to prevent.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure you reassign the result of `push` back to your variable: `myArray = push(myArray, newItems);`","message":"The `push` function can return a *new* array reference if the `list` argument was initially empty, instead of modifying `list` in place. Always reassign the return value of `push`.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { push } = require('micromark-util-chunked');` to `import { push } from 'micromark-util-chunked';`","cause":"Attempting to import `micromark-util-chunked` using CommonJS `require()` syntax.","error":"Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /path/to/node_modules/micromark-util-chunked/index.js"},{"fix":"Ensure you are using named imports: `import { splice } from 'micromark-util-chunked';`","cause":"Incorrect ESM import syntax, often trying to destructure a default export or using `import * as` when the module only provides named exports.","error":"TypeError: (0 , micromark_util_chunked__WEBPACK_IMPORTED_MODULE_0__.splice) is not a function"},{"fix":"Refactor your array manipulation logic to use `micromark-util-chunked`'s `push` and `splice` functions, which are optimized for large arrays.","cause":"Directly using `Array.prototype.splice` or `Array.prototype.push` with a very large number of arguments or an extremely large array, causing a V8 engine stack overflow.","error":"RangeError: Maximum call stack size exceeded"}],"ecosystem":"npm"}