{"id":13683363,"url":"https://github.com/jeanfortheweb/typeorm-fixture-builder","last_synced_at":"2025-06-25T13:07:05.941Z","repository":{"id":40291688,"uuid":"216184749","full_name":"jeanfortheweb/typeorm-fixture-builder","owner":"jeanfortheweb","description":"Painless and type safe data fixtures for typeorm","archived":false,"fork":false,"pushed_at":"2024-11-20T11:40:45.000Z","size":973,"stargazers_count":33,"open_issues_count":6,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-19T16:09:11.836Z","etag":null,"topics":["cli","fixture-organization","typeorm","typeorm-fixtures","typescript"],"latest_commit_sha":null,"homepage":null,"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/jeanfortheweb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-10-19T09:57:41.000Z","updated_at":"2025-02-17T16:49:56.000Z","dependencies_parsed_at":"2024-01-14T15:25:16.465Z","dependency_job_id":"1e8abedc-84e2-45f0-b9e3-9ca96f7749d3","html_url":"https://github.com/jeanfortheweb/typeorm-fixture-builder","commit_stats":{"total_commits":81,"total_committers":6,"mean_commits":13.5,"dds":0.2592592592592593,"last_synced_commit":"26f50f72e6f5567bbd7149718c4b912480d067aa"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/jeanfortheweb/typeorm-fixture-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeanfortheweb%2Ftypeorm-fixture-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeanfortheweb%2Ftypeorm-fixture-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeanfortheweb%2Ftypeorm-fixture-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeanfortheweb%2Ftypeorm-fixture-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeanfortheweb","download_url":"https://codeload.github.com/jeanfortheweb/typeorm-fixture-builder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeanfortheweb%2Ftypeorm-fixture-builder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261879319,"owners_count":23223739,"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":["cli","fixture-organization","typeorm","typeorm-fixtures","typescript"],"created_at":"2024-08-02T13:02:08.497Z","updated_at":"2025-06-25T13:07:05.919Z","avatar_url":"https://github.com/jeanfortheweb.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/jeanfortheweb/typeorm-fixture-builder.svg?branch=master)](https://travis-ci.org/jeanfortheweb/typeorm-fixture-builder) [![Maintainability](https://api.codeclimate.com/v1/badges/e37027e3a284fbf4f7d1/maintainability)](https://codeclimate.com/github/jeanfortheweb/typeorm-fixture-builder/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/e37027e3a284fbf4f7d1/test_coverage)](https://codeclimate.com/github/jeanfortheweb/typeorm-fixture-builder/test_coverage)\n\n# typeorm-fixture-builder \u003c!-- omit in toc --\u003e\n\n**typeorm-fixture-builder** was created when I struggled with the current fixture solutions for typeorm avaible. They simply didn't fit my needs and/or weren't flexible enough. So I decided to create another one.\n\n# Documentation \u003c!-- omit in toc --\u003e\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Fixture Bundle Files](#fixture-bundle-files)\n- [Relations](#relations)\n- [Foreign Bundle Files and Helpers](#foreign-bundle-files-and-helpers)\n- [Soft Fixture Creation / Resolvers](#soft-fixture-creation--resolvers)\n- [Programmatic Usage](#programmatic-usage)\n- [Clearing the persistence cache](#clearing-the-persistence-cache)\n\n# Installation\n\nInstall `typeorm-fixture-builder` and it's peer dependencies. Usually you will install `typescript` as dev dependency:\n\n```sh\nyarn add typeorm typeorm-fixture-builder\nyarn add -D typescript\n```\n\nThis will give you access to the `fixtures` cli utitlity as also to the programmatic api.\n\n# Usage\n\nWe need at least one fixture bundle.\nFixtures are written - as typeorm itself - in typescript.\nTherefore, we are able to create typesafe fixture definitions.\nBy default, the CLI will look for a `fixtures` folder, scanning for all files with a `.bundle.ts` suffix:\n\n```ts\nimport { fixture } from 'typeorm-fixture-builder';\nimport { User } from '../entities/user.entity';\n\nexport const user1 = fixture(User, {\n  firstName: 'John',\n  lastName: 'Doe',\n});\n\nexport const user2 = fixture(User, {\n  firstName: 'Max',\n  lastName: 'Mustermann',\n});\n```\n\nNow you can run these fixtures using the CLI:\n\n```sh\n# yarn\nyarn fixtures install\n\n# npm/npx\nnpx fixtures install\n```\n\nFor more CLI options checkout\n\n```sh\n# yarn\nyarn fixtures --help\nyarn fixtures install --help\n\n# npm/npx\nnpx fixtures --help\nnpx fixtures install --help\n```\n\n# Fixture Bundle Files\n\nThe CLI will collect your fixtures from bundles in a smart but yet simple way.\nEvery fixture you want to get peristed has to be exported by the bundle file. Also,\nit's not allowed to export anything else but fixtures from a bundle file.\n\nHowever, there are exceptions to this which will allow you to organize fixtures the way you\nwish to.\n\nThe following rules apply to exports from bundle files:\n\n1. The export is a fixture itself:\n\n   ```ts\n   import { fixture } from 'typeorm-fixture-builder';\n   import { User } from '../entities/User.entity';\n\n   export const user = fixture(User, { firstName: 'Foo' });\n   ```\n\n2. The export is an array of fixtures:\n\n   ```ts\n   import { fixture } from 'typeorm-fixture-builder';\n   import { User } from '../entities/User.entity';\n\n   export const users = [\n     fixture(User, { firstName: 'Foo' }),\n     fixture(User, { firstName: 'Bar' }),\n     fixture(User, { firstName: 'Baz' }),\n   ];\n   ```\n\n3. The export is an Object where the property values are fixtures:\n\n   ```ts\n   import { fixture } from 'typeorm-fixture-builder';\n   import { User } from '../entities/User.entity';\n\n   export const users = {\n     foo: fixture(User, { firstName: 'Foo' }),\n     bar: fixture(User, { firstName: 'Bar' }),\n     baz: fixture(User, { firstName: 'Baz' }),\n   };\n   ```\n\nThese rules can be combined to allow deeper nested structures:\n\n```ts\nimport { fixture } from 'typeorm-fixture-builder';\nimport { User } from '../entities/User.entity';\nimport { Picture } from '../entities/picture.entity';\n\nexport const users = [\n  {\n    user: fixture(User, { firstName: 'Foo' }),\n    picture: fixture(Picture, { path: 'foo.jpg' }),\n  },\n  {\n    user: fixture(User, { firstName: 'Bar' }),\n    picture: fixture(Picture, { path: 'Bar.jpg' }),\n  },\n];\n```\n\n# Relations\n\nRelations as easy to manage as they can get. Just assign a fixture as a relation and you are done. The CLI will handle your relations.\n\nYou do not have to care about cascade setups since the CLI will walk\nover your relations, no matter on which side of the relation.\n\nAlso, the CLI ensures that every fixture is persisted exactly once.\nWhile you could place related fixtures inside a fixture without exporting\nit from the bundle, it's still a good practice to export all fixtures\nyou define:\n\n```ts\nimport { fixture } from 'typeorm-fixture-builder';\nimport { Group } from '../entities/group.entity';\n\nexport const groups = {\n  administrators: fixture(Group, { name: 'Administrators' }),\n  customers: fixture(Group, { name: 'Customers' }),\n};\n\nexport const users = [\n  fixture(User, {\n    firstName: 'Admin',\n    groups: [groups.administrators],\n  }),\n\n  fixture(User, {\n    firstName: 'Customer',\n    groups: [groups.customers],\n  }),\n];\n```\n\n# Foreign Bundle Files and Helpers\n\nIt's absolutely safe to use fixtures from foreign bundle files:\n\n```ts\n// fixtures/groups.bundle.ts\nimport { fixture } from 'typeorm-fixture-builder';\nimport { Group } from '../entities/group.entity';\n\nexport const administrators: fixture(Group, { name: 'Administrators' });\nexport const customers: fixture(Group, { name: 'Customers' });\n```\n\n```ts\n// fixtures/users.bundle.ts\nimport { fixture } from 'typeorm-fixture-builder';\nimport { User } from '../entities/user.entity';\nimport { administrators, customers } from './groups.bundle';\n\nexport const administrator = fixture(User, {\n  firstName: 'Admin',\n  groups: [administrators],\n});\n\nexport const customer = fixture(User, {\n  firstName: 'Customer',\n  groups: [customers],\n});\n```\n\nYou could even define your fixtures, or functions that will create fixtures\nin non bundle files. It's only important that all your intended fixtures are exported from a bundle file in the end:\n\n```ts\nimport { fixture } from 'typeorm-fixture-builder';\nimport faker from 'faker';\nimport { groups } from './groups.bundle';\n\nexport function createRandomUser(): User {\n  return fixture(User, {\n    firstName: faker.name.firstName(),\n    lastName: faker.name.lastName(),\n    groups: [faker.random.arrayElement(groups)],\n  });\n}\n\nexport function createRandomUsers(count: number): User[] {\n  return [...new Array(count)].map(createRandomUser);\n}\n```\n\n```ts\nimport { builder } from 'typeorm-fixture-builder';\nimport { User } from '../entities/user.entity';\nimport { createRandomUsers } from './helpers.ts';\n\nexport const users = createRandomUsers(10);\n```\n\n# Soft Fixture Creation / Resolvers\n\nSometimes, we do not want to create new database entries but use existing ones to update them or to prevent new data creation when fixtures run more\nthan once.\n\nThis can be achieved by passing a third parameter to the `fixture` function.\n\nIt has to be a callback which will receive the repository for the entity\nand the fixture values and should return a setup query builder. We call\nthis a `resolver function`.\n\nThe CLI will use this query builder to find a single entity by it's criteria. If it finds an entity, it will be merged with the fixture data,\notherwise a new entity will be persisted:\n\n```ts\nimport { fixture } from 'typeorm-fixture-builder';\nimport { User } from '../entities/user.entity';\n\nexport const user = fixture(\n  User,\n  { firstName: 'Foo', lastName: 'Bar' },\n  (repository, { firstName }) =\u003e\n    repository\n      .createQueryBuilder('user')\n      .where('user.firstName = :firstName', { firstName }),\n);\n```\n\nHowever, if you want to do this often on a certain type of entity, or even with a fixed set of conditions, it's useful to create a decorated fixture function which will setup the `resolver function` for you:\n\n```ts\nimport { fixture } from 'typeorm-fixture-builder';\nimport { DeepPartial } from 'typeorm';\nimport { User } from '../entities/user.entity';\n\nfunction createOrUpdateUser(data: DeepPartial\u003cUser\u003e) {\n  return fixture(User, data, (repository, { firstName }) =\u003e\n    repository\n      .createQueryBuilder('user')\n      .where('user.firstName = :firstName', { firstName }),\n  );\n}\n\nexport const user = createOrUpdateUser({\n  firstName: 'Foo',\n  lastName: 'Bar',\n});\n```\n\nSuch functions could also be placed in some kind of non bundle helper files, of course.\n\n# Programmatic Usage\n\nIf you just want to install some fixtures programmatically, you can import and use the `install` function. It takes a TypeORM DataSource and an array of fixtures:\n\n```ts\nimport { fixture, install } from 'typeorm-fixture-builder';\nimport { DataSource } from 'typeorm';\nimport { User } from '../entities/user.entity';\n\nexport const user1 = fixture(User, {\n  firstName: 'John',\n  lastName: 'Doe',\n});\n\nexport const user2 = fixture(User, {\n  firstName: 'Max',\n  lastName: 'Mustermann',\n});\n\nasync function installFixtures() {\n  const source = new DataSource();\n\n  await source.initialize();\n  await install(source, [user1, user2]);\n}\n\ninstallFixtures();\n```\n\nYou can also import and collect fixtures from bundle files. Import and use the `collect` function. Pass the imported bundle module and it will return an array of collected fixtures:\n\n```ts\nimport { collect, install } from 'typeorm-fixture-builder';\nimport { DataSource } from 'typeorm';\nimport UserBundle from '../fixtures/user.bundle';\n\nasync function installFixtures() {\n  const source = new DataSource();\n\n  await source.initialize();\n  await install(source, collect(UserBundle));\n}\n\ninstallFixtures();\n```\n\n# Clearing the Persistence Cache\n\nInternally, the library will cache every fixture it has already persisted.\nThis can become quite cumbersome, for example when you're using fixtures in end to end\ntesting scenarios which wants to redeploy fixtures frequently in one process.\n\nTo overcome this, you can use the `clear` function before calling `install` again, which will clear the internal caching, allowing fixtures to be persisted again:\n\n```ts\nimport { collect, install, clear } from 'typeorm-fixture-builder';\nimport { DataSource } from 'typeorm';\nimport UserBundle from '../fixtures/user.bundle';\n\nbeforeEach(async () =\u003e {\n  const source = new DataSource();\n\n  await source.initialize();\n  await install(source, collect(UserBundle));\n});\n\nafterEach(() =\u003e {\n  clear();\n});\n\n// your tests using fixtures...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeanfortheweb%2Ftypeorm-fixture-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeanfortheweb%2Ftypeorm-fixture-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeanfortheweb%2Ftypeorm-fixture-builder/lists"}