{"id":16357866,"url":"https://github.com/schalkventer/faker-extra","last_synced_at":"2025-03-21T00:31:36.401Z","repository":{"id":41382558,"uuid":"257175858","full_name":"schalkventer/faker-extra","owner":"schalkventer","description":"🎠 Adds additional functionality and configuration options to the base Faker.js library","archived":false,"fork":false,"pushed_at":"2023-09-27T05:50:19.000Z","size":832,"stargazers_count":11,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-15T15:09:51.387Z","etag":null,"topics":["extension","faker","javascript","jest","mocha","mocking","test-driven-development","testing","typescript"],"latest_commit_sha":null,"homepage":"http://npm.im/faker-extra","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/schalkventer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2020-04-20T04:59:38.000Z","updated_at":"2023-09-06T07:09:44.000Z","dependencies_parsed_at":"2024-10-28T09:11:47.802Z","dependency_job_id":"42161dbd-a0d9-442c-8229-95f18f6ef65f","html_url":"https://github.com/schalkventer/faker-extra","commit_stats":{"total_commits":100,"total_committers":3,"mean_commits":"33.333333333333336","dds":"0.020000000000000018","last_synced_commit":"a8b94021941a974647b4ec08d35a1b95b98ad2b7"},"previous_names":["schalkventer/faker-enhanced"],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schalkventer%2Ffaker-extra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schalkventer%2Ffaker-extra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schalkventer%2Ffaker-extra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schalkventer%2Ffaker-extra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schalkventer","download_url":"https://codeload.github.com/schalkventer/faker-extra/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244094267,"owners_count":20397020,"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":["extension","faker","javascript","jest","mocha","mocking","test-driven-development","testing","typescript"],"created_at":"2024-10-11T02:04:20.945Z","updated_at":"2025-03-21T00:31:36.130Z","avatar_url":"https://github.com/schalkventer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- omit in toc --\u003e\n# 🎠 Faker Extra\n\n---\n\n[![deprecated](http://badges.github.io/stability-badges/dist/deprecated.svg)](http://github.com/badges/stability-badges)\n\n⚠ Note that this package is deprecated! It was originally created to add missing functionality to the base Faker.js library. At the time the original maintainer of Faker.js was (to be frank) actively hostile towards outside contributors. This package was created as an add-on to be used alongside Faker.js. In 2022 it saw around 1,500 downloads/week.\n\nHowever, today Faker.js is managed by a completely different team, which have gone above and beyond to extend the library. With the recent addition of `helpers.multiple` to the Faker.js it has all functionality covered by this add-on. I've begun removing Faker Extra from my own projects, and am happy to retire it in favour of the base Faker.js library. Please support the new team at [https://fakerjs.dev/](https://fakerjs.dev/), they are doing amazing work!\n\n---\n\n**Contains original Faker.js functionality and extra methods, similar to [fs-extra](https://www.npmjs.com/package/fs-extra).**\n\n![](https://raw.githubusercontent.com/schalkventer/faker-extra/master/docs/assets/logo.png)\n\n\u003c!-- omit in toc --\u003e\n## Table of Contents\n\n- [Usage](#usage)\n- [Why Faker Extra?](#why-faker-extra)\n- [Installing](#installing)\n- [API](#api)\n  - [`faker.extra.frequency()`](#fakerextrafrequency)\n  - [`faker.extra.array()`](#fakerextraarray)\n  - [`faker.extra.object()`](#fakerextraobject)\n## Usage\n\nDue to the removal of the original Faker.js library from Github in early 2022, this project has the latest working version and types of Faker.js (1.5.3) built directly into it. This means that the import from `faker-extra` functions exactly the same as the original Faker.js package (and can even be used as a drop-in replacement for the original package too).\n\nThe only difference is that `faker-extra` has an optional extra property called `extra`. You can use it as follows:\n\n\n  ```js\n  import faker from 'faker-extra';\n  faker.seed(1);\n\n  const ids = faker.extra.array([10, 3000], faker.datatype.uuid);\n\n  const competitors = faker.extra.object(\n    ids,\n    () =\u003e ({\n      awards: faker.extra.array([0, 2], ['red', 'green', 'blue', 'orange'], true).\n      score: faker.datatype.number({ min: 0, max: 1000 }),\n      league: faker.extra.frequency({ bronze: 65, silver: 30, gold: 5 }),\n      attendance: faker.extra.object([\"2019\", \"2020\", \"2021\", \"2022\", \"2023\"], faker.datatypes.boolean),\n    }),\n  )\n\n  /*\n   * Will return an object with anywhere between 10 to 3000 key/value pairs.\n   *\n   * These will be randomly generated against the same seed (they will\n   * always be the same random values). They might look something like this:\n   *\n   * {\n   *   4aa71604-2d35-4de2-8c86-9b6791bbc90a: {\n   *    badges: ['orange', 'green', 'red']\n   *    score: 667,\n   *    league: 'bronze'\n   *  },\n   *\n   *  e572ca5e-c857-493b-a212-95e3ec812b2c: {\n   *    badges: [],\n   *    score: 446,\n   *    league: 'silver'\n   *  },\n   *\n   *   82b46b13-2e0e-4572-a2cd-ded291cdb3f4: {\n   *    badges: ['red']\n   *    score: 915,\n   *    league: 'bronze'\n   *  },\n   *\n   *   ...\n   * }\n   *\n   */\n  ```\n\n## Why Faker Extra?\n\n- **Returning random values at different frequencies**:\n\n  ```js\n  /* 65% chance to be 'bronze', 30% chance to be 'silver' and 5% chance to be 'gold' */\n\n  const league = faker.extra.frequency({ bronze: 65, silver: 30, gold: 5 });\n  ```\n\n- **Returning an array of random length**:\n\n  ```js\n  /* An array of anywhere between 10 and 3000 unique IDs. */\n\n  const ids = faker.extra.array([10, 3000], faker.datatype.uuid);\n  ```\n\n- **Returning an array of random length with no duplicates**:\n\n  ```js\n  /* An array that contains between 0 and 2 separate values from source. Note, the `true` argument ensures that a value can be added only once (for example you won't get `['red', 'red']`) */\n\n  const awards = faker.extra.array(\n    [0, 2],\n    ['red', 'green', 'blue', 'orange'],\n    true\n  );\n  ```\n\n- **Returning an object with random values**:\n\n  ```js\n  /* An object that has all years and the amount of winners as values. */\n\n  const attendance = faker.extra.object([\"2019\", \"2020\", \"2021\", \"2022\", \"2023\"], faker.datatypes.boolean);\n  ```\n## Installing\n\n1. **Run via terminal/command-line in root of project.**\n\n   _Note: Packages should be installed as a development dependencies since you want to avoid using mock values in your production output._\n\n   `npm install --save-dev faker-extra`\n\n2. **Then import as follows:**\n\n   _Note: that you can also destructure the extra helpers (via named exports) if you want to reduce file size._\n\n   **ES Modules**\n\n   ```js\n   import faker from \"faker-extra\";\n\n   faker.extra.frequency({ a: 10, b: 10, c: 90 });\n   faker.extra.array(10, Math.random);\n   ```\n\n   **TypeScript**\n\n   ```ts\n   import faker from \"faker-extra\";\n\n   faker.extra.frequency\u003cstring\u003e({ a: 10, b: 10, c: 90 });\n   faker.extra.array\u003cnumber\u003e(10, Math.random);\n   ```\n\n   **CommonJS**\n\n   ```js\n   const faker = require(\"faker-extra\");\n\n   faker.extra.frequency({ a: 10, b: 10, c: 90 });\n   faker.extra.array(10, Math.random);\n   ```\n\n## API\n### `faker.extra.frequency()`\n\n**Creates an array/object who's length is equal, or ranging between, predefined amounts.**\n\n```ts\n\u003cT extends any\u003e(\n  ratios:\n    | number\n    | Record\u003cT, number\u003e\n    | { percentage: number; value: T; call?: boolean }[]\n) =\u003e T;\n```\n\n- To return a boolean value:\n\n  ```js\n  faker.extra.frequency(70);\n\n  /*\n   * - Has a 70% chance to return `true`\n   * - Has a 30% chance to return `false`\n   */\n  ```\n\n- To return a value from a pre-defined list.\n\n  ```js\n  faker.extra.frequency({ a: 70, b: 30 });\n\n  /*\n   * - Has a 70% chance to return \"a\".\n   * - Has a 30% chance to return \"c\".\n   */\n  ```\n\n- To return a value from a pre-defined list that has more than 2 items. _(Note that an error will be thrown if all frequencies do not add up to 100.)_\n\n  ```js\n  faker.extra.frequency({ \"A B C\": 10, \"A C B\": 20, \"C A B\": 20, \"C B A\": 50 });\n\n  /*\n   * - Has a 10% chance to return \"A B C\".\n   * - Has a 20% chance to return \"A C B\" or \"C A B\".\n   * - Has a 50% chance to return \"C B A\".\n   */\n  ```\n\n- To return a values other than strings or numbers:\n\n  ```js\n  faker.extra.frequency([\n    {\n      percentage: 10,\n      value: new Error(\"Oops!\"),\n    },\n    {\n      percentage: 20,\n      value: [1, 2, 3, 4, 5],\n    },\n    {\n      percentage: 20,\n      value: faker.commerce.productName(),\n    },\n    {\n      percentage: 50,\n      value: false,\n    },\n  ]);\n\n  /*\n   * - Has a 10% chance to return the result of `new Error('Oops!')`.\n   * - Has a 20% chance to return `[1, 2, 3, 4, 5]` or the result of `faker.commerce.productName()`\n   * - Has a 50% chance to return `false`.\n   */\n  ```\n\n_Note that the above returns the result of `faker.commerce.productName()`. This means that it will not generate a new product name when that relevant value needs to be returned. If you want to dynamically provide a value each time you need to pass the function itself._\n\n- To execute a function everytime a value is aclled.\n\n  ```js\n  faker.extra.frequency([\n    {\n      percentage: 10,\n      value: () =\u003e faker.datatype.number({ min: 10, max: 70 }),\n    },\n    {\n      percentage: 10,\n      value: faker.address.streetName,\n    },\n    {\n      percentage: 20,\n      value: () =\u003e new Date(),\n    },\n    {\n      percentage: 50,\n      value: () =\u003e faker.extra.array([1, 5], true),\n    },\n  ]);\n\n  /*\n   * - Has a 10% chance to that a number between 10 and 70 will be returned.\n   * - Has a 20% chance to that a random street name or the current date will be returned.\n   * - Has a 50% that an array with containing between 1 and 5 instances of `true` .\n   */\n  ```\n\n_Functions are automatically called by default. This means that if you want the result itself to be the provided function you should set `call` to `false`._\n\n- To return a functions as the actual result:\n\n  ```js\n  faker.extra.frequency([\n    {\n      percentage: 10,\n      value: () =\u003e console.log(\"1\"),\n      call: false,\n    },\n    {\n      percentage: 10,\n      value: () =\u003e console.log(\"2\"),\n      call: false,\n    },\n    {\n      percentage: 20,\n      value: () =\u003e console.log(\"3\"),\n      call: false,\n    },\n    {\n      percentage: 50,\n      value: () =\u003e console.log(\"4\"),\n      call: false,\n    },\n  ]);\n\n  /*\n   * - Has a 10% chance to return a function that will log \"1\" to the console when called.\n   * - Has a 20% chance to return a function that will log \"2\" or \"3\" to the console when called.\n   * - Has a 50% chance to return a function that will log \"4\" to the console when called.\n   */\n  ```\n\n---\n\n### `faker.extra.array()`\n\n**Returns an array created from pre-defined values.**\n\n```ts\n\u003cT extends any\u003e(\n  length: number | [number, number],\n  value?: T | (() =\u003e T) | T[],\n  extract?: boolean\n): T[]\n```\n\n- To create an array with a length of 5:\n\n  ```js\n  faker.extra.array(5);\n\n  /*\n   * Will be `[undefined, undefined, undefined, undefined, undefined]`.\n   */\n  ```\n\n- To create an array with a random length between 3 and 6:\n\n  ```js\n  faker.extra.array([3, 6]);\n\n  /*\n   * - Has a 25% chance to be `[undefined, undefined, undefined]`\n   * - Has a 25% chance to be `[undefined, undefined, undefined, undefined]`.\n   * - Has a 25% chance to be `[undefined, undefined, undefined, undefined, undefined]`.\n   * - Has a 25% chance to be `[undefined, undefined, undefined, undefined, undefined, undefined]`.\n   */\n  ```\n\n- To populate it with a value:\n\n  ```js\n  faker.extra.array(5, \"abc\");\n\n  /*\n   * Will be `[\"abc\", \"abc\", \"abc\", \"abc\", \"abc\"]`.\n   */\n  ```\n\n- To populate it with by means of a callback:\n\n  ```js\n  faker.extra.array(3, Math.random);\n\n  /*\n   *  Might something like `[0.3667866123486143, 0.44642296430964445, 0.915051909777594]`\n   */\n  ```\n\n- To extract from an existing array add `true` as the third argument.\n\n  ```js\n  faker.exra.array([2, 4], [\"a\", \"b\", \"c\", \"d\", \"e\"], true);\n\n  /*\n   *  Might something like `['c', 'e']` or [`'d', 'a', 'e', 'b']`\n   */\n  ```\n\n  - To populate an array with objects via a callback:\n\n  ```js\n  faker.extra.array(3, () =\u003e ({\n    score: Math.round(Math.random() * 1000),\n  }));\n\n  /*\n   *  Might look something like:\n   *\n   * [\n   *  { score: 667 },\n   *  { score: 446 },\n   *  { score: 915 },\n   * ]\n   *\n   */\n  ```\n\n---\n\n### `faker.extra.object()`\n\n**Returns an array created from pre-defined values.**\n\n```ts\n\u003cK extends any, T extends any\u003e(\n  length: K[],\n  value?: T | ((key?: K) =\u003e T),\n) =\u003e Record\u003cK, T\u003e\n```\n\n- To create an object from `['a', 'b', 'c', 'd', 'e']` keys:\n\n  ```js\n  faker.extra.object([\"a\", \"b\", \"c\", \"d\", \"e\"]);\n\n  /*\n   * Will be:\n   *\n   * {\n   *    a: undefined,\n   *    b: undefined,\n   *    c: undefined,\n   *    d: undefined,\n   *    e: undefined,\n   * }\n   *\n   */\n  ```\n\n- To create an object from the `[1, 2, 3, 4, 5]` keys and `'abc'` as a value:\n\n  ```js\n  faker.extra.object([1, 2, 3, 4, 5], \"abc\");\n\n  /*\n   * Will be:\n   *\n   * {\n   *    1: 'abc',\n   *    2: 'abc',\n   *    3: 'abc',\n   *    4: 'abc',\n   *    5: 'abc',\n   * }\n   *\n   */\n  ```\n\n- To create an object from `[1, 2, 3, 4, 5]` and use a callback to create a value:\n\n  ```js\n  faker.object([1, 2, 3, 4, 5], () =\u003e faker.random.number(100));\n\n  /*\n   * Might look something like this:\n   *\n   * {\n   *    1: 63,\n   *    2: 9,\n   *    3: 71,\n   *    4: 3,\n   *    5: 51,\n   * }\n   *\n   */\n  ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschalkventer%2Ffaker-extra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschalkventer%2Ffaker-extra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschalkventer%2Ffaker-extra/lists"}