dancing-links

About

This is an implementation of Knuth's DLX to solve the exact cover problem.
It is a port of Knuth's literate dancing links implementation and supports primary and secondary constraints, and returning custom data in addition to row indices.

There are no external dependencies and there is full TypeScript support.

It is currently the fastest Dancing Links implementation in JavaScript.

Usage

$3

``ts
import { DancingLinks } from 'dancing-links'

const dlx = new DancingLinks()
const solver = dlx.createSolver({ columns: 3 })

solver.addSparseConstraint('row1', [0, 2]) // Constraint active in columns 0 and 2
solver.addSparseConstraint('row2', [1]) // Constraint active in column 1
solver.addSparseConstraint('row3', [0, 1]) // Constraint active in columns 0 and 1

const solutions = solver.findAll()
// Returns: [[{ data: 'row1', index: 0 }, { data: 'row2', index: 1 }]]
`

$3

#### Sparse Constraints (Recommended)

Sparse constraints are the most efficient format - specify only the active column indices instead of full binary arrays. This reduces parsing overhead and memory usage, especially for problems with many columns.

`ts
const solver = dlx.createSolver({ columns: 100 })

// ⚡ EFFICIENT: Only specify active columns
solver.addSparseConstraint('constraint1', [0, 15, 42, 87])
solver.addSparseConstraint('constraint2', [1, 16, 43, 99])

// Batch operations for better performance
const constraints = [
{ data: 'batch1', columnIndices: [0, 10, 20] },
{ data: 'batch2', columnIndices: [5, 15, 25] },
{ data: 'batch3', columnIndices: [2, 12, 22] }
]
solver.addSparseConstraints(constraints)
`

#### Binary Constraints

Use binary constraints when it's more convenient for your encoding logic or when you already have constraint data in binary format:

`ts
const solver = dlx.createSolver({ columns: 4 })

// Convenient when encoding naturally produces binary arrays
solver.addBinaryConstraint('row1', [1, 0, 1, 0])
solver.addBinaryConstraint('row2', [0, 1, 0, 1])
solver.addBinaryConstraint('row3', [1, 1, 0, 0])

// Batch operations
const binaryConstraints = [
{ data: 'batch1', columnValues: [1, 0, 1, 0] },
{ data: 'batch2', columnValues: [0, 1, 0, 1] }
]
solver.addBinaryConstraints(binaryConstraints)
`

$3

For problems with reusable constraint patterns, templates provide significant performance benefits by pre-processing base constraints. Templates are especially beneficial when using binary constraints, as the binary-to-sparse conversion happens once during template creation rather than every time you create a solver:

`ts
// Create template with base constraints
const template = dlx.createSolverTemplate({ columns: 20 })
template.addSparseConstraint('base1', [0, 5, 10])
template.addSparseConstraint('base2', [1, 6, 11])

// Create multiple solvers from the same template
const solver1 = template.createSolver()
solver1.addSparseConstraint('extra1', [2, 7, 12])
const solutions1 = solver1.findAll()

const solver2 = template.createSolver()
solver2.addSparseConstraint('extra2', [3, 8, 13])
const solutions2 = solver2.findAll()
`

$3

For problems requiring both primary constraints (must be covered exactly once) and secondary constraints (optional - may be left uncovered, but if covered, allow no collisions):

`ts
const solver = dlx.createSolver({
primaryColumns: 2, // First 2 columns are primary
secondaryColumns: 2 // Next 2 columns are secondary
})

// Method 1: Add constraints separately
solver.addSparseConstraint('constraint1', {
primary: [0], // Must cover primary column 0
secondary: [1] // May cover secondary column 1 (optional, but no conflicts if used)
})

// Method 2: Add as binary constraint
solver.addBinaryConstraint('constraint2', {
primaryRow: [0, 1], // Binary values for primary columns
secondaryRow: [1, 0] // Binary values for secondary columns
})
`

Key difference between primary and secondary constraints:

- Primary: All primary columns MUST be covered exactly once in any valid solution
- Secondary: Secondary columns are optional - they can be left uncovered, but if a secondary column IS covered, only one constraint can cover it (no collisions allowed)

$3

`ts
// Find one solution
const oneSolution = solver.findOne()

// Find all solutions
const allSolutions = solver.findAll()

// Find up to N solutions
const limitedSolutions = solver.find(10)
`

$3

For large solution spaces or when you need early termination, use the generator interface:

`ts
// Stream solutions one at a time
const generator = solver.createGenerator()

let solutionCount = 0
for (const solution of generator) {
console.log('Found solution:', solution)

solutionCount++
if (solutionCount >= 5) {
// Stop after finding 5 solutions
break
}
}

// Manual iteration for full control
const generator2 = solver.createGenerator()
let result = generator2.next()
while (!result.done) {
processSolution(result.value)
result = generator2.next()
}
``

The generator maintains search state between solutions, enabling memory-efficient streaming and early termination without computing all solutions upfront.

Examples

The benchmark directory contains complete implementations for:

- N-Queens Problem: Classical constraint satisfaction problem
- Pentomino Tiling: 2D shape placement with rotation constraints
- Sudoku Solver: Number placement with row/column/box constraints

These examples demonstrate encoding techniques for different problem types and show performance optimization strategies.

Benchmarks

This section contains performance comparisons against other JavaScript Dancing Links libraries, updated automatically during releases.

All benchmarks run on the same machine with identical test cases. Results show operations per second (higher is better).

$3

| Library | Ops/Sec | Relative Performance | Margin of Error |
| ----------------------- | -------- | -------------------- | --------------- |
| dancing-links (sparse) | 12776.77 | 1.00x (fastest) | ±0.16% |
| dancing-links (binary) | 5084.72 | 0.40x | ±0.23% |
| dance | 2022.24 | 0.16x | ±0.41% |
| dancing-links-algorithm | 1397.72 | 0.11x | ±0.38% |
| dlxlib | 1274.87 | 0.10x | ±0.71% |

$3

| Library | Ops/Sec | Relative Performance | Margin of Error |
| ---------------------- | ------- | -------------------- | --------------- |
| dancing-links (sparse) | 442.34 | 1.00x (fastest) | ±0.56% |
| dancing-links (binary) | 430.33 | 0.97x | ±0.46% |
| dlxlib | 348.68 | 0.79x | ±0.68% |
| dance | 84.99 | 0.19x | ±0.79% |

$3

| Library | Ops/Sec | Relative Performance | Margin of Error |
| ---------------------- | ------- | -------------------- | --------------- |
| dancing-links (sparse) | 68.74 | 1.00x (fastest) | ±1.12% |
| dlxlib | 68.32 | 0.99x | ±1.11% |
| dancing-links (binary) | 67.45 | 0.98x | ±1.14% |
| dance | 17.36 | 0.25x | ±0.85% |

$3

| Library | Ops/Sec | Relative Performance | Margin of Error |
| ---------------------- | ------- | -------------------- | --------------- |
| dancing-links (sparse) | 9.11 | 1.00x (fastest) | ±2.07% |
| dancing-links (binary) | 8.99 | 0.99x | ±1.67% |
| dlxlib | 8.61 | 0.95x | ±2.00% |
| dance | 2.37 | 0.26x | ±1.85% |

Testing Environment:

- Node.js v25.3.0
- Test cases: Sudoku solving, pentomino tiling (1, 10, 100 solutions)

_Last updated: 2026-01-15_

Contributing

For development information, performance benchmarking, profiling, and contribution guidelines, see DEVELOPMENT.md.