linked-grid

linked-grid represents a double linked List in 2D space along an x and y axis with every node having up to four links to their neighboring cells:

    A (0, 0) -- B (1, 0) -- C (2, 0)
       |           |           |
    D (0, 1) -- E (1, 1) -- F (2, 1)
       |           |           |
    G (0, 2) -- H (1, 2) -- I (2, 2)

It can act like a sparse matrix, only linking nodes of existing coordinates. And since traversal through a grid can be ambiguous, it utilizes a cursor vector to track the current node to expand or read from. This cursor moves automatically unless states otherwise (grid.autoMove = false).

Usage

import LinkedGrid from 'linked-grid'

const grid = new LinkedGrid<string>('Origin')

grid.appendRight('New Node') // Append a node to (1, 0) with a value of 'New Node'. The cursor automatically moves to (1,0)

console.log(grid.cursorValue) // 'New Node'
console.log(grid.cursor) // '{ x: 1, y: 0 }'

grid.moveLeft() // Move back to (0, 0)
grid.moveUp(25) // Moves to (0, -25), which will be undefined

LinkedGrid also allows to set nodes on distant, not-connected nodes:

grid.set(100, 100, 'A') // Lone, isolated node
grid.moveTo(100, 100) // Set cursor to the isolated node

console.log(grid.cursorNode) // Logs out the current node. The links are empty.

grid.linkCoords(100, 100, 0, 0) // Links together both nodes

// It automatically prefers y connection as x distance < y distance
console.log(grid.cursorNode?.yPrev?.value) // 'Origin'

// Move cursor to the current nodes x prev location
grid.moveYPrev()
console.log(grid.cursorValue) // 'Origin'

@ 2026 Torathion