: start ↔ end\n\nElement example:\n\n parentNode? (as shortcut for a linked list of previous nodes)\n ↑\n ├────────────────────────────────────────────┐\n │ ↓\n node? ← start → attr* → text* → comment* → element* → end → node?\n ↑ │\n └────────────────────────────────────────────┘\n\n\nFragment example:\n\n ┌────────────────────────────────────────────┐\n │ ↓\n start → attr* → text* → comment* → element* → end\n ↑ │\n └────────────────────────────────────────────┘\n```\n\nIf this is not clear, feel free to **[read more in the deep dive page](./deep-dive.md)**.\n\n\n### Why is this better?\n\nMoving *N* nodes from a container, being it either an *Element* or a *Fragment*, requires the following steps:\n\n * update the first *left* link of the moved segment\n * update the last *right* link of the moved segment\n * connect the *left* side, if any, of the moved node at the beginning of the segment, with the *right* side, if any, of the node at the end of such segment\n * update the *parentNode* of the segment to either *null*, or the new *parentNode*\n\nAs result, there are no array operations, and no memory operations, and everything is kept in sync by updating a few properties, so that removing `3714` sparse `` elements in a *12M* document, as example, takes as little as *3ms*, while appending a whole fragment takes close to *0ms*.\n\nTry `npm run benchmark:html` to see it yourself.\n\nThis structure also allows programs to avoid issues such as \"*Maximum call stack size exceeded*\" (basicHTML), or \"*JavaScript heap out of memory*\" crashes (JSDOM), thanks to its reduced usage of memory and zero stacks involved, hence scaling better from small to very big documents.\n\n### Are *childNodes* and *children* always computed?\n\nAs everything is a `while(...)` loop away, by default this module does not cache anything, specially because caching requires state invalidation for each container, returned queries, and so on. However, you can import `linkedom/cached` instead, as long as you [understand its constraints](https://github.com/WebReflection/linkedom#cached-vs-not-cached).\n\n\n## Parsing VS Node Types\n\nThis module parses, and works, only with the following `nodeType`:\n\n * `ELEMENT_NODE`\n * `ATTRIBUTE_NODE`\n * `TEXT_NODE`\n * `COMMENT_NODE`\n * `DOCUMENT_NODE`\n * `DOCUMENT_FRAGMENT_NODE`\n * `DOCUMENT_TYPE_NODE`\n\nEverything else, at least for the time being, is considered *YAGNI*, and it won't likely ever land in this project, as there's no goal to replicate deprecated features of this aged Web.\n\n\n\n## Cached VS Not Cached\n\nThis module exports both `linkedom` and `linkedom/cached`, which are basically the exact same thing, except the cached version outperforms `linkedom` in these scenarios:\n\n * the document, or any of its elements, are rarely changed, as opposite of frequently mutated or manipulated\n * the use-case needs many repeated *CSS* selectors, over a sporadically mutated \"*tree*\"\n * the generic DOM mutation time is *not* a concern (each, removal or change requires a whole document cache invalidation)\n * the *RAM* is *not* a concern (all cached results are held into *NodeList* arrays until changes happen)\n\nOn the other hand, the basic, *non-cached*, module, grants the following:\n\n * minimal amount of *RAM* needed, given any task to perform, as nothing is ever retained on *RAM*\n * linear fast performance for any *every-time-new* structure, such as those created via `importNode` or `cloneNode` (i.e. template literals based libraries)\n * much faster DOM manipulation, without side effect caused by cache invalidation\n\n\n\n## Benchmarks\n\nTo run the benchmark locally, please follow these commands:\n\n```sh\ngit clone https://github.com/WebReflection/linkedom.git\n\ncd linkedom/test\nnpm i\n\ncd ..\nnpm i\n\nnpm run benchmark\n```\n","readmeFilename":"README.md"}