{"id":17296104,"url":"https://github.com/timbeyer/node-dlx","last_synced_at":"2025-06-20T19:40:23.619Z","repository":{"id":32623311,"uuid":"36209066","full_name":"TimBeyer/node-dlx","owner":"TimBeyer","description":"Dancing Links","archived":false,"fork":false,"pushed_at":"2022-06-23T19:26:41.000Z","size":203,"stargazers_count":8,"open_issues_count":7,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-16T15:12:36.146Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimBeyer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-25T04:07:57.000Z","updated_at":"2022-01-21T08:50:18.000Z","dependencies_parsed_at":"2022-06-26T23:33:46.491Z","dependency_job_id":null,"html_url":"https://github.com/TimBeyer/node-dlx","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TimBeyer/node-dlx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimBeyer%2Fnode-dlx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimBeyer%2Fnode-dlx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimBeyer%2Fnode-dlx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimBeyer%2Fnode-dlx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimBeyer","download_url":"https://codeload.github.com/TimBeyer/node-dlx/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimBeyer%2Fnode-dlx/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261006436,"owners_count":23096058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-15T11:12:00.231Z","updated_at":"2025-06-20T19:40:18.578Z","avatar_url":"https://github.com/TimBeyer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dancing-links [![codecov](https://codecov.io/gh/TimBeyer/node-dlx/branch/master/graph/badge.svg)](https://codecov.io/gh/TimBeyer/node-dlx)\n\n## About\n\nThis is an implementation of Knuth's DLX to solve the exact cover problem.\nIt is a port of [Knuth's literate dancing links implementation](https://cs.stanford.edu/~knuth/programs/dance.w) and supports primary and secondary constraints, and returning custom data in addition to row indices.\n\nThere are no external dependencies and there is full typescript support.\n\nIt is currently [the fastest](#benchmarks) Dancing Links implementation in JS.\n\n## Usage\n\n```javascript\n\nconst dlx = require('dancing-links')\n\n// Simple case\nconst constraints = [\n    {\n        data: 'first one',\n        row: [1,0]\n    },\n    {\n        data: 'second one',\n        row: [0,1]\n    },\n    {\n        data: 'third one',\n        row: [0,1]\n    }\n]\n\nconst oneSolution = dlx.findOne(constraints)\n/**\n * [{\n *      data: 'first one',\n *      index: 0\n *  },\n *  {\n *      data: 'second one',\n *      index: 1\n *  }]\n */\n\nconst allSolutions = dlx.findAll(constraints)\n/**\n * [[{\n *      data: 'first one',\n *      index: 0\n *  },\n *  {\n *      data: 'second one',\n *      index: 1\n *  }],\n *  [{\n *      data: 'first one',\n *      index: 0\n *  },\n *  {\n *      data: 'third one',\n *      index: 2\n *  }]]\n */\n\n// Secondary constraints\n\nconst constraints = [\n    {\n        data: 'first one',\n        primaryRow: [1,0],\n        secondaryRow: [1]\n    },\n    {\n        data: 'second one',\n        primaryRow: [0,1],\n        secondaryRow: [0]\n    },\n    {\n        data: 'third one',\n        primaryRow: [0,1],\n        secondaryRow: [1]\n    }\n]\n\nconst oneSolution = dlx.findOne(constraints)\n/**\n * [{\n *      data: 'first one',\n *      index: 0\n *  },\n *  {\n *      data: 'second one',\n *      index: 1,\n *  }]\n */\n\nconst allSolutions = dlx.findAll(constraints)\n/**\n * \n * Not the best example, but for brevity's sake believe me that it works as intended.\n *\n * [{\n *      data: 'first one',\n *      index: 0\n *  },\n *  {\n *      data: 'second one',\n *      index: 1,\n *  }]\n */\n```\n\n## Implementation\n\nPreviously, this library was directly based on the [original DLX paper](https://arxiv.org/pdf/cs/0011047.pdf) and implemented using recursion.  \nHowever, in order to improve performance and align with [Knuth's reference implementation](https://cs.stanford.edu/~knuth/programs/dance.w), the algorithm needed to be converted to an iteration.\n\nSince JS does not support the `goto` statement, and since it's considered harmful anyway, the implementation uses a very simple state machine to execute the algorithm.\n\n\n## Benchmarks\n\nThe benchmarks were done against [dlxlib](https://github.com/taylorjg/dlxlibjs) and [dance](https://github.com/wbyoung/dance) using constraints for a 6x10 [pentomino](https://en.wikipedia.org/wiki/Pentomino) tiling.\n\nYou can run them with `npm run benchmark`\n\n```\nBenchmark: A solution to the sodoku\n\n.|.|.|.|.|.|.|.|.\n.|.|.|.|.|3|.|8|5\n.|.|1|.|2|.|.|.|.\n.|.|.|5|.|7|.|.|.\n.|.|4|.|.|.|1|.|.\n.|9|.|.|.|.|.|.|.\n5|.|.|.|.|.|.|7|3\n.|.|2|.|1|.|.|.|.\n.|.|.|.|4|.|.|.|9\n\ndancing-links find x 2,247 ops/sec ±2.19% (89 runs sampled)\ndancing-links findRaw x 4,975 ops/sec ±1.59% (93 runs sampled)\ndlxlib x 390 ops/sec ±1.04% (88 runs sampled)\ndance x 400 ops/sec ±0.75% (87 runs sampled)\ndancing-links-algorithm x 447 ops/sec ±1.50% (86 runs sampled)\nFastest is dancing-links findRaw\n\n\nBenchmark: Finding one pentomino tiling on a 6x10 field\n\ndancing-links find x 231 ops/sec ±2.60% (85 runs sampled)\ndancing-links findRaw x 249 ops/sec ±0.83% (84 runs sampled)\ndlxlib x 66.70 ops/sec ±1.90% (70 runs sampled)\ndance x 37.58 ops/sec ±1.05% (65 runs sampled)\nFastest is dancing-links findRaw\n\n\nBenchmark: Finding ten pentomino tilings on a 6x10 field\n\ndancing-links find x 38.64 ops/sec ±1.49% (52 runs sampled)\ndancing-links findRaw x 37.77 ops/sec ±3.22% (50 runs sampled)\ndlxlib x 10.54 ops/sec ±1.98% (30 runs sampled)\ndance x 7.75 ops/sec ±2.41% (24 runs sampled)\n\nFastest is dancing-links findRaw\n\n\nBenchmark: Finding one hundred pentomino tilings on a 6x10 field\n\ndancing-links find x 5.18 ops/sec ±11.43% (17 runs sampled)\ndancing-links findRaw x 5.42 ops/sec ±1.20% (18 runs sampled)\ndlxlib x 1.50 ops/sec ±0.69% (8 runs sampled)\ndance x 1.15 ops/sec ±2.04% (7 runs sampled)\n\nFastest is dancing-links findRaw\n```\n\n## Profiling\n\nYou can generate a CPU profile of the algorithm using `npm run profile`.\nIt will create a file called `profile.cpuprofile` which you can then load into the Chrome inspector.\nTo do this, you will need to install the optional dependency `v8-profiler` manually using `npm install --no-save v8-profiler`.  \nThis is because there isn't currently a way to specify optional dev dependencies, and as a dev dependency compiling of the dependency fails in CI.\n\n## Examples\n\nThe [benchmark directory](https://github.com/TimBeyer/node-dlx/tree/master/benchmark) implements encoders for the n-queens and pentomino tiling problems.  \nThey aren't very optimized (the pentomino tiling does not consider symmetries) but you can use them as examples for how to encode your constraints for the library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimbeyer%2Fnode-dlx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimbeyer%2Fnode-dlx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimbeyer%2Fnode-dlx/lists"}