{"id":15662548,"url":"https://github.com/lmammino/indexed-string-variation","last_synced_at":"2025-05-06T00:57:53.324Z","repository":{"id":57273425,"uuid":"67373226","full_name":"lmammino/indexed-string-variation","owner":"lmammino","description":"Experimental JavaScript module to generate all possible variations of strings over an alphabet using an n-ary virtual tree","archived":false,"fork":false,"pushed_at":"2018-01-04T14:41:50.000Z","size":54,"stargazers_count":18,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-06T00:57:46.872Z","etag":null,"topics":["algorithm","alphabet","characters","duplicates","javascript","javascript-library","library","node","nodejs","string","strings","tree","variations","virtual"],"latest_commit_sha":null,"homepage":"http://loige.co","language":"JavaScript","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/lmammino.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":"2016-09-04T23:19:44.000Z","updated_at":"2023-10-22T06:38:13.000Z","dependencies_parsed_at":"2022-09-17T15:11:40.358Z","dependency_job_id":null,"html_url":"https://github.com/lmammino/indexed-string-variation","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmammino%2Findexed-string-variation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmammino%2Findexed-string-variation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmammino%2Findexed-string-variation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmammino%2Findexed-string-variation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lmammino","download_url":"https://codeload.github.com/lmammino/indexed-string-variation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252601694,"owners_count":21774661,"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":["algorithm","alphabet","characters","duplicates","javascript","javascript-library","library","node","nodejs","string","strings","tree","variations","virtual"],"created_at":"2024-10-03T13:33:14.163Z","updated_at":"2025-05-06T00:57:53.301Z","avatar_url":"https://github.com/lmammino.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# indexed-string-variation\n\n[![npm version](https://badge.fury.io/js/indexed-string-variation.svg)](http://badge.fury.io/js/indexed-string-variation)\n[![Build Status](https://travis-ci.org/lmammino/indexed-string-variation.svg?branch=master)](https://travis-ci.org/lmammino/indexed-string-variation)\n[![codecov.io](https://codecov.io/gh/lmammino/indexed-string-variation/coverage.svg?branch=master)](https://codecov.io/gh/lmammino/indexed-string-variation)\n\n\nExperimental JavaScript module to generate all possible variations of strings over an alphabet using an n-ary virtual tree.\n\n\n## Install\n\nWith NPM:\n\n```bash\nnpm install --save indexed-string-variation\n```\n\n\n## Usage\n\nGenerally useful to create distributed brute-force password recovery tools or\nother software that might require distributed generation of all possible\nstrings on a given alphabet.\n\n```javascript\nconst generator = require('indexed-string-variation').generator;\nconst variations = generator('abc1');\n\nfor (let i=0; i \u003c 23; i++) {\n    console.log(i, variations(i)); // generates the i-th string in the alphabet 'abc1'\n}\n```\n\nWill print:\n\n```bash\n0 ''\n1 'a'\n2 'b'\n3 'c'\n4 '1'\n5 'aa'\n6 'ab'\n7 'ac'\n8 'a1'\n9 'ba'\n10 'bb'\n11 'bc'\n12 'b1'\n13 'ca'\n14 'cb'\n15 'cc'\n16 'c1'\n17 '1a'\n18 '1b'\n19 '1c'\n20 '11'\n21 'aaa'\n22 'aab'\n```\n\n\n## API\n\nThe module `indexed-string-variation` exposes the following components:\n \n * `generator` (also aliased as `default` for ES2015 modules): the \n  main generator function\n * `defaultAlphabet`: a constant string that contains the sequence of \n  characters in the defaultAlphabet\n\nAs you can see in the [usage example](#usage), the `generator` function takes as input the \nalphabet string (which is optional and it will default to `defaultAlphabet` if \nnot provided) and returns a new function called `variations` which can be\nused to retrieve the indexed variation on the given alphabet. `variations` takes\na non-negative integer as input which represents the index of the variations\nthat we want to generate:\n\n```javascript\nconst variations = generator('XYZ');\nconsole.log(variations(7123456789)); // \"XYYZYZZZYYYZYZYXYYYYX\"\n```\n\n\n## How the algorithm works\n\nThe way the generation algorithm work is using an n-ary tree where n is the size of the alphabet.\nFor example, if we have an alphabet containing only `a`, `b` and `c` and we want to generate all\nthe strings with a maximum length of 3 the algorithm will use the following tree:\n\n![Sample ternary tree over abc alphabet](doc/sample_diagram.png)\n\nThe tree is to be considered \"virtual\", because it's never generated in its integrity, so the\nused space in memory is minimal.\n\nIn brevity we can describe the algorithm as follows:\n\n\u003e Given an index **i** over an alphabet of length **n** and it's corresponding n-ary tree,\nthe string associated to **i** corresponds to the string obtained by \nconcatenating all the characters found in the path that goes from the root node to the **i**-th node.\n\nFor example, with the alphabet in the image we can generate the following strings:\n\n| i | generated string |\n|---:|---|\n|0||\n|1|a|\n|2|b|\n|3|c|\n|4|aa|\n|5|ab|\n|6|ac|\n|7|ba|\n|8|bb|\n|9|bc|\n|10|ca|\n|11|cb|\n|12|cc|\n\n\nImportant note: The alphabet is always normalized (i.e. duplicates are removed)\n\n\n## Use big-integer to avoid JavaScript big integers approximations\n\nIntegers with more than 18 digits are approximated (e.g. `123456789012345680000 === 123456789012345678901`), so at some \npoint the generator will start to generate a lot of duplicated strings and it will start to miss many cases.\n\nTo workaround this issue you can use indexes generated with the module [big-integer](https://www.npmjs.com/package/big-integer).\nInternally the indexed-string-variation will take care of performing the correct\noperations using the library.\n\nLet's see an example:\n\n```javascript\nconst bigInt = require('big-integer'); // install from https://npmjs.com/package/big-integer\nconst generator = require('indexed-string-variation').generator;\nconst variations = generator('JKWXYZ');\n\n// generation using regular big numbers (same result)\nconsole.log(variations(123456789012345678901)); // XJZJYXXXYYJKYZZJKZKYJWJJYW\nconsole.log(variations(123456789012345680000)); // XJZJYXXXYYJKYZZJKZKYJWJJYW\n\n// generation using big-integer numbers (correct results)\nconsole.log(variations(bigInt('123456789012345678901'))); // XJZJYXXXYYJKYZZJKZKXZKJZZJ\nconsole.log(variations(bigInt('123456789012345680000'))); // XJZJYXXXYYJKYZZJKZKXZWJJWK\n```\n\nAnyway, keep in mind that big-integers might have a relevant performance impact, \nso if you don't plan to use huge integers it's still recommended to use \nplain JavaScript numbers as indexes.\n\n\n## Contributing\n\nEveryone is very welcome to contribute to this project.\nYou can contribute just by submitting bugs or suggesting improvements by\n[opening an issue on GitHub](https://github.com/lmammino/indexed-string-variation/issues).\n\n\n## License\n\nLicensed under [MIT License](LICENSE). © Luciano Mammino.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flmammino%2Findexed-string-variation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flmammino%2Findexed-string-variation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flmammino%2Findexed-string-variation/lists"}