{"id":16817342,"url":"https://github.com/phanan/factoria","last_synced_at":"2025-03-17T03:31:43.039Z","repository":{"id":27912937,"uuid":"115551237","full_name":"phanan/factoria","owner":"phanan","description":"Simplistic model factory for Node/JavaScript","archived":false,"fork":false,"pushed_at":"2022-05-02T17:42:29.000Z","size":72,"stargazers_count":52,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-14T05:09:42.879Z","etag":null,"topics":["dummy","factory","javascript","model"],"latest_commit_sha":null,"homepage":"","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/phanan.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["phanan"]}},"created_at":"2017-12-27T19:29:20.000Z","updated_at":"2023-09-22T18:41:28.000Z","dependencies_parsed_at":"2022-07-24T15:32:04.036Z","dependency_job_id":null,"html_url":"https://github.com/phanan/factoria","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phanan%2Ffactoria","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phanan%2Ffactoria/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phanan%2Ffactoria/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phanan%2Ffactoria/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phanan","download_url":"https://codeload.github.com/phanan/factoria/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243841207,"owners_count":20356443,"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":["dummy","factory","javascript","model"],"created_at":"2024-10-13T10:46:55.471Z","updated_at":"2025-03-17T03:31:42.592Z","avatar_url":"https://github.com/phanan.png","language":"TypeScript","funding_links":["https://github.com/sponsors/phanan"],"categories":[],"sub_categories":[],"readme":"# factoria ![Main](https://github.com/phanan/factoria/workflows/Main/badge.svg) ![npm](https://img.shields.io/npm/v/factoria)\n\nSimplistic model factory for Node/JavaScript, heavily inspired by Laravel's [Model Factories](https://laravel.com/docs/master/database-testing#defining-model-factories).\n\n## Install\n\n```bash\n# install factoria\n$ yarn add factoria -D\n# install Faker as a peer dependency\n$ yarn add @faker-js/faker -D\n```\n\n## Usage\n\n### 1. Define a model\n\nTo define a model, import and use `define` from the module. `define` accepts two arguments:\n\n* `name`: (string) Name of the model, e.g. `'user'`\n* `(faker)` (function) A closure to return the model's attribute definition as an object. This closure will receive a [Faker](https://fakerjs.dev) instance, which allows you to generate various random testing data.\n\nExample:\n\n```ts\nconst define = require('factoria').define\n\ndefine('User', faker =\u003e ({\n  id: faker.random.uuid(),\n  name: faker.name.findName(),\n  email: faker.internet.email(),\n  age: faker.random.number({ min: 13, max: 99 })\n}))\n\n// TypeScript with generics\ndefine\u003cUser\u003e('User', faker =\u003e ({\n  // A good editor/IDE should suggest properties from the User type\n}))\n```\n\n### 2. Generate model objects\n\nTo generate model objects, import the factory and call it with the model's defined name. Following the previous example:\n\n```ts\nimport factory from 'factoria'\n\n// The simplest case, returns a \"User\" object\nconst user = factory('User')\n\n// Generate a \"User\" object with \"email\" preset to \"foo@bar.baz\"\nconst userWithSetEmail = factory('User', { email: 'foo@bar.baz' })\n\n// Generate an array of 5 \"User\" objects\nconst users = factory('User', 5)\n\n// Generate an array of 5 \"User\" objects, each with \"age\" preset to 27\nconst usersWithSetAge = factory('User', 5, { age: 27 })\n\n// Use a function as an overriding value. The function will receive a Faker instance.\nconst user = factory('User', {\n  name: faker =\u003e {\n    return faker.name.findName() + ' Jr.'\n  }\n})\n\n// TypeScript with generics\nconst user = factory\u003cUser\u003e('User') // `user` is of type User\nconst users: User[] = factory\u003cUser\u003e('User', 3) // `users` is of type User[]\n```\n\n## Nested factories\n\nfactoria fully supports nested factories. For example, if you have a `Role` and a `User` model, the setup might look like this:\n\n```ts\nimport factory from 'factoria'\n\nfactory.define('Role', faker =\u003e {\n  name: faker.random.arrayElement(['user', 'manager', 'admin'])\n}).define('User', faker =\u003e ({\n  email: faker.internet.email(),\n  role: factory('Role')\n}))\n```\n\nCalling `factory('User')` will generate an object of the expected shape e.g.,\n\n```js\n{\n  email: 'foo@bar.com',\n  role: {\n    name: 'admin'\n  }\n}\n```\n\n## States\n\nStates allow you to define modifications that can be applied to your model factories. To create states, add an object as the third parameter of `factory.define`, where the key being the state name and its value the state's attributes. For example, you can add an `unverified` state for a User model this way:\n\n```ts\nfactory.define('User', faker =\u003e ({\n  email: faker.internet.email(),\n  verified: true\n}), {\n  unverified: {\n    verified: false\n  }\n})\n```\n\nState attributes can also be a function with Faker as the sole argument:\n\n```ts\nfactory.define('User', faker =\u003e ({\n  email: faker.internet.email(),\n  verified: true\n}), {\n  unverified: faker =\u003e ({\n    verified: faker.random.arrayElement([false]) // for the sake of demonstration\n  })\n})\n```\n\nYou can then apply the state by calling the method `states()` with the state name, which returns the factoria instance itself:\n\n```ts\nconst unverifiedUser = factory.states('unverified')('User')\n```\n\nYou can also apply multiple states:\n\n```ts\nconst fourUnverifiedPoorSouls = factory.states('job:engineer', 'unverified')('User', 4)\n```\n\n## Test setup tips\n\nOften, you want to set up all model definitions before running the tests. One way to do so is to have one entry point for the factories during test setup. For example, you can have this `test` script defined in `package.json`:\n\n```json\n{\n  \"test\": \"mocha-webpack --require test/setup.js tests/**/*.spec.js\"\n}\n```\n\nOr, if [Jest](https://facebook.github.io/jest/) is your cup of tea:\n\n```json\n{\n  \"jest\": {\n    \"setupFilesAfterEnv\": [\n      \"\u003crootDir\u003e/test/setup.js\"\n    ]\n  }\n}\n```\n\nThen in `test/setup.js` you can import `factoria` and add the model definitions there.\n\nAnother approach is to have a wrapper module around factoria, have all models defined inside the module, and finally `export` factoria itself. You can then `import` the wrapper and use the imported object as a factoria instance (because it _is_ a factoria instance), with all model definitions registered:\n\n```js\n// tests/factory.js\nimport factory from 'factoria'\n\n// define the models\nfactory.define('User', faker =\u003e ({}))\n       .define('Group', faker =\u003e ({}))\n\n// now export factoria itself\nexport default factory\n```\n\n```js\n// tests/user.spec.js\nimport factory from './factory'\n\n// `factory` is a factoria function instance\nconst user = factory('User')\n```\n\nfactoria itself uses this approach for its tests.\n\n## License\n\nMIT © [Phan An](https://phanan.net)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphanan%2Ffactoria","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphanan%2Ffactoria","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphanan%2Ffactoria/lists"}