{"id":22610221,"url":"https://github.com/strangedev/zufall","last_synced_at":"2025-04-11T07:45:53.941Z","repository":{"id":35107918,"uuid":"207558528","full_name":"strangedev/zufall","owner":"strangedev","description":"JS/TS library for generating random things and sampling data","archived":false,"fork":false,"pushed_at":"2024-06-16T11:01:19.000Z","size":2117,"stargazers_count":4,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-22T19:05:56.254Z","etag":null,"topics":["javascript","random","random-generator","sampling","testing-tools"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/strangedev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-10T12:52:02.000Z","updated_at":"2025-01-11T20:03:21.000Z","dependencies_parsed_at":"2024-05-14T14:08:09.743Z","dependency_job_id":null,"html_url":"https://github.com/strangedev/zufall","commit_stats":{"total_commits":59,"total_committers":8,"mean_commits":7.375,"dds":0.5593220338983051,"last_synced_commit":"d394fdbf18468974391df93e97bc79eabd4dafe3"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangedev%2Fzufall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangedev%2Fzufall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangedev%2Fzufall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strangedev%2Fzufall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strangedev","download_url":"https://codeload.github.com/strangedev/zufall/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248359389,"owners_count":21090521,"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":["javascript","random","random-generator","sampling","testing-tools"],"created_at":"2024-12-08T16:06:16.268Z","updated_at":"2025-04-11T07:45:53.920Z","avatar_url":"https://github.com/strangedev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zufall - [_ˈt͡suːˌfal_]\n\n[![npm version](https://badge.fury.io/js/zufall.svg)](https://badge.fury.io/js/zufall)\n\nA small JS/TS library for generating random numbers and sampling data,\nbecause using `Math.random()` is tiresome.\n\n\"Zufall\" is german for \"chance\" or \"coincidence\". When something happens \"per Zufall\", it happens at random.\n\nThis library is aimed at testing and other _non-security_ applications. It\nis just a wrapper for `Math.random()`, so don't expect any cryptographic\nproperties from it!\n\n## Migrating to v2\n\nZufall has been rewritten in TypeScript! It is now more streamlined, too.\nOnly the basic functions are included now, removing the dependency on mongodb\nthat we had before.\n\nWe reckon that it is more important to provide a few focussed functions that you\ncan build on, instead of providing many small functions for every possible use\ncase.\n\nYou can find the v1 docs here: https://github.com/strangedev/zufall/blob/v1.1.2/README.md\n\nIn v2 we removed:\n- The `TYPES`, `VALUE_TYPES`, and `OBJECT_TYPES` constants. If you want to create random values of certain types, you can easily do so by combining the other functions like `draw`, `randomInteger`, and `randomArrayBy`.\n- The `randomValue`, `randomThing`, `randomThingOf`, `randomThingOfTypes`, `randomArrayOf`, `randomObjectOf`, and `randomObjectOfTypes` functions. These were meant for fuzzing purposes, but we discovered that their behavior was too unpredictable in real world applications, as you couldn't control the random generation enough. If you need to generate random inputs, combine the `randomInteger`, `randomNumber`, `randomString`, `draw` and the `randomArrayBy` and `randomObjectBy`functions.\n- The `randomType`, `randomValueType` and `randomTypeExcept` functions. These were meant as helpers for the aforementioned functions, so they served no purpose anymore.\n- The object generation function `randomObjectWithDepth`. Its behavior can be accomplished using `randomObjectBy`.\n- The `randomObjects` function, as it can be built easily by combining `randomArrayBy` and `randomObjectBy`, and doing it manually gives more control.\n- The `randomDbRef`, `randomDbRefs`, and `randomDocument` functions. These were very specific to one use case, which was the use case we had when writing this library. Since then, we wanted to use the library in different contexts and even the browser, and having the dependency on mongodb proved to be a limitation.\n- The `words` constant. Get your own words ;D\n- The `isPrefixOf` helper. It does not belong in this library.\n\nWe also renamed some things:\n- `randInt` and `randNum` have been renamed to `randomInteger` and `randomNumber`.\n- `chooseN` is now called `sample`, as it models sampling a populace.\n- `chooseNReplace` is now called `draw`, as it models drawing numbers.\n- `randomWord` is now called `randomString` to better match the naming of the other functions.\n\nSome of the function signatures have also changed:\n- `randomInteger` now receives a minimum and a maximum parameter.\n- `randomNumber` now receives a minimum and a maximum parameter.\n- `randomArrayBy` now receives an exact length instead of randomizing the length based on the given parameter.\n- `randomObjectBy` now receives an exact length instead of randomizing the length based on the given parameter.\n- `randomString` now receives an exact length instead of randomizing the length based on the given parameter.\n\nWe also added a `shuffle` function that you can use to immutably shuffle arrays!\n\n## Installation\n\nInstall from npmjs.com:\n\n```sh\nnpm install zufall\nnpm install -D zufall # when used for testing\n```\n\n## Usage\n\nNode:\n\n```javascript\nconst Zufall = require(\"zufall\");\n```\n\nES6:\n\n```javascript\nimport { draw, choose } from \"zufall\";\n```\n\n### Generating random numbers\n\nYou can generate random floats and integers with zufall.\nYou can either get a value between 0 and `Math.MAX_VALUE`, if you don't pass\nany parameters, or you can adjust the allowed interval by passing a minimum\nand a maximum.\n\n_Note:_ The `maximum` is always excluded from the interval! In mathematical\nterms, the value if chosen from the interval `[min; max)`. This has been chosen\nto be compatible with `Math.random()`, which also excludes the 1, and it also\nmakes it easier to work with array indices.\n\n```ts\n// Generate a random float between 0 and Math.MAX_VALUE \nrandomNumber();\n\n// Generate a random float between 2 and 11\nrandomNumber(2, 11);\n\n// The minimum can also be negative!\nrandomNumber(-3, 4);\n```\n\n```ts\n// Generate a random integer between 0 and Math.MAX_VALUE \nrandomInteger();\n\n// Generate a random integer between 2 and 11\nrandomInteger(2, 11);\n\n// The minimum can also be negative!\nrandomInteger(-3, 4);\n```\n\n### Generating random strings\n\nYou can generate random strings with zufall. These are not really random, but\nyou can use them if you need some placeholder text in a pinch.\n\n```ts\n// Get a random string with 12 characters in it.\nrandomString(12);\n```\n\n### Drawing and sampling from arrays\n\nYou can choose a random element from an array using `choose`:\n\n```ts\nchoose([1, 2, 3, 4]);\n```\n\nIf you want to choose multiple elements without replacing the element between\ndraws, you can use `sample`.\n\n```ts\nsample([1, 2, 3, 4], 3);\n\n// The sample size can't be larger than the given array!\nsample([1, 2, 3, 4], 5); // :(\n```\n\nIf you want to choose multiple elements from an array and replace the elements\nbetween each draw (meaning you can have duplicates), you can use `draw`.\n\n```ts\n// Here, the size can be as large as you want!\ndraw(['heads', 'tails'], 20); \n```\n\n### Shuffling arrays\n\nTo shuffle an array, you can use the `shuffle` function. The function does not\nmodify the original array. This also means that this function copies the input\narray, so be careful when trying to shuffle really large arrays.\n\n```ts\nshuffle([1, 2, 3, 4]);\n```\n\n### Generating random arrays\n\nYou can generate random arrays by using `randomArrayBy`. You need to supply a\ngenerator function, which will be called once for every item you want to have\nin your array. If you want to have an array with 5 items, it will be called 5\ntimes.\n\nThe generator function receives the index of the element it should generate and\nthe current array. It should return the element at the given index.\n\n```ts\nrandomArrayBy(() =\u003e randomInteger(10));\n// e.g.: [ 4, 6, 3, 3, 6, 7, 4]\n\nconst generatorFn = (i, currentArray) =\u003e {\n  let nextElement;\n\n  do {\n    nextElement = randomInteger(100);\n  } while (currentArray.includes(nextElement));\n  \n  return nextElement;\n};\n\nrandomArrayBy(generatorFn);\n// e.g.: [ 73, 29, 25, 31, 11, 86, 34,  9]\n```\n\n### Generating random objects\n\nYou can generate random objects by using `randomObjectBy`. You need to supply a\ngenerator function, which will be called once for every key-value pair you want\nto have in your object. If you want to have an object with 5 properties, it will\nbe called 5 times.\n\nThe generator function receives the index of the element it should generate and\nthe current object. It should return a key-value pair for the generated property.\n\n```ts\nrandomObjectBy(() =\u003e [ randomString(), randomInteger(10) ], 3);\n// e.g.: { lampe: 8, zwerg: 8, saft: 6 }\n\n// generate unique numbers by checking\n// if the next number is already contained in\n// the object\nconst generatorFn = (i, currentObject) =\u003e {\n  let nextElement;\n\n  do {\n    nextElement = randomInteger(100);\n  } while (Object.values(currentObject).includes(nextElement));\n\n  return [ randomString(), nextElement ];\n};\n\nrandomObjectBy(generatorFn, 2);\n// e.g.: { fliege: 69, geschwurbel: 3 }\n```\n\n## Running quality assurance\n\n```shell\nnpx roboter\n```\n\n## Support\n\nPlease [open an issue](https://github.com/strangedev/zufall/issues/new) for support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrangedev%2Fzufall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrangedev%2Fzufall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrangedev%2Fzufall/lists"}