{"id":15608655,"url":"https://github.com/hypercubed/randomator","last_synced_at":"2025-04-28T11:46:49.606Z","repository":{"id":38315330,"uuid":"350525515","full_name":"Hypercubed/Randomator","owner":"Hypercubed","description":"Think of Randomator as rxjs for random values.  Build your own DSF (Domain Specific Faker) BYOD (Bring Your Own Data).","archived":false,"fork":false,"pushed_at":"2023-08-11T18:06:43.000Z","size":882,"stargazers_count":5,"open_issues_count":12,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-19T12:45:31.219Z","etag":null,"topics":["fake","faker","generator","mocking","random"],"latest_commit_sha":null,"homepage":"https://hypercubed.github.io/Randomator/","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/Hypercubed.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-23T00:02:50.000Z","updated_at":"2022-02-28T18:46:51.000Z","dependencies_parsed_at":"2023-01-22T09:01:03.983Z","dependency_job_id":null,"html_url":"https://github.com/Hypercubed/Randomator","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hypercubed%2FRandomator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hypercubed%2FRandomator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hypercubed%2FRandomator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hypercubed%2FRandomator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hypercubed","download_url":"https://codeload.github.com/Hypercubed/Randomator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251309458,"owners_count":21568823,"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":["fake","faker","generator","mocking","random"],"created_at":"2024-10-03T05:21:47.692Z","updated_at":"2025-04-28T11:46:49.589Z","avatar_url":"https://github.com/Hypercubed.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Randomator\n\nComposable, Iterable, and transformable random value generators.\n\n## Intro\n\nA `Randomator` is a random value generator.  A `Randomator` may be constructed using the `new Randomator` constructor but more often they are constructed using the supplied generators and operators described below.  Every `Randomator` is a function and an iterable that returns a new value each time.  Some interesting things about  `Randomator`s are:\n\n* A `Randomator` is a function that returns a new random value each time it is called.\n* A `Randomator` is an iterable and can be used in a for-of loop.\n* A `Randomator` can be transformed using the `.map` and `.filter` operators.\n\nAs an base example we will create a `Randomator` that returns a random integer between 0 and 1:\n\n```js\nconst number$ = new Randomator(() =\u003e Math.random());\n```\n\n\u003e Note: in this readme I'll use [Finnish Notation](https://medium.com/@benlesh/observables-and-finnish-notation-df8356ed1c9b) to signify a `Randomator` instance.  This is simply for clarity.\n\nThe `Randomator` constructor takes a function that returns a new value each time it is called.  Since a `Randomator` is a function it can be called to return a value:\n\n```js\nconsole.log(number$());  // prints a random number between 0 and 1 (same as Math.random())\n```\n\nA `Randomator` is also an iterable and can be used in a for-of loop:\n\n```js\nlet count = 0;\nfor (const number of number$) {\n  if (count++ \u003e 10) break;\n  console.log(number);\n}\n```\n\n\u003e Warning: Use caution when using a `Randomator` in a for-of loop... it is an infinite stream of values!\n\nA `Randomator` can be transformed using the `.map` and `.filter` operators:\n\n```js\nconst numbers$ = new Randomator(() =\u003e Math.random());\nconst integers$ = numbers$.map(number =\u003e Math.floor(number * 100));\nconst evenIntegers$ = integers$.filter(number =\u003e number % 2 === 0);\n```\n\n\u003e Warning: Use caution when using `filter`, a strict predicate may cause an infinite loop.\n\nThese derived `Randomator`s are lazy; meaning that no generation takes place until the `Randomator` is called.\n\nWhile `Randomator`s can be created using the `new Randomator` constructor, they are more often created using the built-in operators:\n\n```js\nconst number$ = numbers();\nconsole.log(number$());  // Prints an random number (same as Math.random())\n```\n\nA more involved example is the `string` function which take several options and returns a `Randomator` of strings:\n\n```js\nconst chars$ = chars({ pool: 'abc' });\nconst length$ = integers({ min: 3, max: 13 });\nconst string$ = strings({ chars: chars$, length: length$ }); // A randomator that generates string between three (3) and 13 characters (inclusive) of 'a', 'b' or 'c'.\n```\n\nAnd operators:\n\n```js\nconst number$ = numbers();\nconst evenNumber$ = number$.filter(number =\u003e number % 2 === 0);\nconst oddNumber$ = number$.filter(number =\u003e number % 2 !== 0);\nconst oddEven$ = tuple(oddNumber$, evenNumber$);  // A randomator that generates odd/even pairs\n```\n\n## Built-in Generators\n\n### Numbers\n\n#### `numbers`\n\nGenerates a number between 0 and 1 (inclusive of 0, but excluding 1).  This `Randomator` is basically a wrapper around `Math.random`.\n\n```js\nconst number$ = numbers();\nnumber$();  // [0, 1) same as `Math.Random`\n```\n\n#### `floats`\n\nGenerates a number between `min` and `max` rounded to `fixed` decimal places (default: `{ min: 0, max: 1, fixed: 4 }`) inclusive of `min`, but not `max`.\n\n```js\nconst float$ = floats();\nfloat$();  // [0, 1)\n\nconst otherFloat$ = floats({ min: -1e10, max: 1e10, fixed: 0 });\notherFloat$();  // [-1e10, 1e10)\n```\n\n#### `integers`\n\nGenerates a integer between min and max (default: `{ min: 0, max: 9 }`) inclusive of `min` and `max`.\n\n```js\nintegers()();  // [0, 9] (aka a single digit)\nintegers({ min: 5, max: 12 })();  // [5,12]\n```\n\n### Strings\n\n#### `chars`\n\n```js\nchars()();  // returns a random character (one of `abcdefghijklmnopqrstuvwxyABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^\u0026*()`).\nchars({ pool: '!@#$' })();  // returns a random character from the set '!@#$'\n```\n\n#### `strings`\n\n```js\nstrings()();  // returns a random string with between 5 and 20 lowercase characters.\nstrings({ length: 5 })();  // returns a string of five lowercase characters.\n\nconst chars$ = chars({ pool: 'abc' });\nconst length$ = integers({ min: 3, max: 13 });\nconst string$ = strings({ chars: chars$, length: length$ });\nconsole.log(string$());  // Prints a string between three (3) and 13 characters (inclusive) of 'a', 'b' or 'c'.\n```\n\n### Dates\n\n#### `dates`\n\n```js\ndates()();  // returns a date between Sep 14 1752 and Apr 18 2187\ndates({ min: new Date('1/1/1970'), max: new Date('1/1/2020') })();  // returns a string between 1 Jan 1970 and 1 Jan 2020\n```\n\n#### `past`\n\n```js\npast()();  // returns a date between Sep 14 1752 and now\npast({ min: new Date('1/1/1970') })();  // returns a string between 1 Jan 1970 and now\n```\n\n#### `future`\n\n```js\nfuture()();  // returns a date between now invoked and Apr 18 2187\nfuture({ max: new Date('1/1/2020') })();  // returns a string between now and 1 Jan 2020\n```\n\n## Operators\n\nOperators are functions which can be called to create a new `Randomator`s.\n\n### `oneOf`\n\n```js\nconst yesNoMaybe$ = oneOf(['yes', 'no', 'maybe']);\nyesNoMaybe$(); // returns one random value from the input array\n```\n\n### `tuple`\n\n```js\nconst integer$ = integers();\nconst string$ = strings();\nconst tuple$ = tuple([integer$, string$]);\ntuple$();  // returns an array (equivalent to [integer$(), string$()])\n```\n\n### `array`\n\n```js\nconst string$ = strings();\narray(string$, 3)();  // returns an array of three (3) random strings\ninteger({ min: 0, max: 6 }).map(length =\u003e array(string$, length)();  // returns an array of between three (3) and six (6) random strings\n```\n\n### `seq`\n\n```js\nconst name$ = string().map(capitalize);\nconst age$ = integer({ min: 0, max: 12 });\nconst phrase$ = seq([name$, ' is ', age$]);\nphrase$();  // returns a random string like `{string} is {integer}`\n```\n\n## `randomator` Tag Function\n\nA `randomator` tagged template function which is essentially a wrapper around the `seq` operator:\n\n```js\nconst name$ = strings().map(capitalize);\nconst age$ = integers({ min: 0, max: 12 });\nconst phrase$ = randomator`${name$} is ${age$}`;\nphrase$();  // same as seq([name$, ' is ', age$])();\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypercubed%2Frandomator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypercubed%2Frandomator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypercubed%2Frandomator/lists"}