{"id":22796293,"url":"https://github.com/makerxstudio/ts-dossier","last_synced_at":"2025-04-19T13:13:32.897Z","repository":{"id":36970500,"uuid":"503965787","full_name":"MakerXStudio/ts-dossier","owner":"MakerXStudio","description":"A support library to facilitate the easy creation of test data builders for use with an Object-Mother test pattern in TypeScript","archived":false,"fork":false,"pushed_at":"2025-03-10T00:45:17.000Z","size":2680,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-10T03:39:32.846Z","etag":null,"topics":["data-builder","data-builder-pattern","npm","object-mother","object-mother-pattern","oss","package","testing","typescript"],"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/MakerXStudio.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2022-06-16T00:54:40.000Z","updated_at":"2025-03-10T00:41:33.000Z","dependencies_parsed_at":"2024-10-31T02:31:39.392Z","dependency_job_id":"01f5371c-845e-4a8b-929d-a9bb7490dc6d","html_url":"https://github.com/MakerXStudio/ts-dossier","commit_stats":{"total_commits":96,"total_committers":4,"mean_commits":24.0,"dds":"0.17708333333333337","last_synced_commit":"44cc82550f1cd820835022588ca0c63d36cde977"},"previous_names":["makerxstudio/ts-object-mother"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MakerXStudio%2Fts-dossier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MakerXStudio%2Fts-dossier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MakerXStudio%2Fts-dossier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MakerXStudio%2Fts-dossier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MakerXStudio","download_url":"https://codeload.github.com/MakerXStudio/ts-dossier/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249701707,"owners_count":21312758,"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":["data-builder","data-builder-pattern","npm","object-mother","object-mother-pattern","oss","package","testing","typescript"],"created_at":"2024-12-12T05:11:50.013Z","updated_at":"2025-04-19T13:13:32.890Z","avatar_url":"https://github.com/MakerXStudio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TypeScript Dossier (ts-dossier)\n\n\u003e A support library to facilitate the easy creation of test data [builders](https://en.wikipedia.org/wiki/Builder_pattern) for use with an [Object-Mother](https://www.martinfowler.com/bliki/ObjectMother.html) pattern in TypeScript\n\n[![npm package][npm-img]][npm-url]\n[![Build Status][build-img]][build-url]\n[![Downloads][downloads-img]][downloads-url]\n[![Issues][issues-img]][issues-url]\n[![Semantic Release][semantic-release-img]][semantic-release-url]\n\n## Install\n\n```bash\nnpm install @makerx/ts-dossier --save-dev\n```\n\n## Usage\n\nThe first step is to define a model\n\n```ts\ntype Colour = 'Blue' | 'Red' | 'Yellow' | 'Green'\n\nexport type Shape = {\n  name: string\n  sides: number\n  sideLengths: number[]\n  colour: Colour\n}\n```\n\nThen define a Builder for that model\n\n```ts\nimport { randomElement, randomNumberBetween, randomString } from '@makerx/ts-dossier'\nimport { DataBuilder, dossierProxy } from '@makerx/ts-dossier'\nimport { Shape } from './shape'\n\nfunction generateSideLengths(sides: number) {\n  return [...Array(sides).keys()].map((_) =\u003e randomNumberBetween(1, 999))\n}\n\nclass ShapeBuilder extends DataBuilder\u003cShape\u003e {\n  constructor() {\n    const sides = randomNumberBetween(1, 4)\n    super({\n      name: randomString(10, 20),\n      sides,\n      sideLengths: generateSideLengths(sides),\n      colour: randomElement(['Blue', 'Red', 'Yellow', 'Green']),\n    })\n  }\n\n  public withSides(sides: number) {\n    this.with('sides', sides)\n    if (this.thing.sideLengths.length != sides) {\n      this.with('sideLengths', generateSideLengths(sides))\n    }\n    return this\n  }\n\n  public asSquare(length: number) {\n    this.thing = {\n      ...this.thing,\n      name: 'Square',\n      sides: 4,\n      sideLengths: [length, length, length, length],\n    }\n    return this\n  }\n\n  public asIsoscelesTriangle(length: number, perimeter: number) {\n    this.thing = {\n      ...this.thing,\n      name: 'Isosceles triangle',\n      sides: 3,\n      sideLengths: [length, length, perimeter - length * 2],\n    }\n    return this\n  }\n}\n\nexport const shapeBuilder = dossierProxy\u003cShapeBuilder, Shape\u003e(ShapeBuilder)\n```\n\nWith the builder defined, and using the dossier proxy, you now have access to the builder methods supplied by the builder itself and the ones defined for you by the Dossier proxy.\n\n![Intellisense Example](./public/IntellisenseExample.png)\n\nThen define a mother to build known models for testing\n\n```ts\nimport { shapeBuilder } from './shape-builder'\n\nexport const shapeMother = {\n  blueSquare: () =\u003e {\n    return shapeBuilder().asSquare(20).withColour('Blue')\n  },\n  greenTriangle: () =\u003e {\n    return shapeBuilder().withName('Triangle').withSides(3).withColour('Green')\n  },\n  redIsoscelesTriangle: () =\u003e {\n    return shapeBuilder().asIsoscelesTriangle(20, 45).withColour('Red')\n  },\n}\n```\n\nAnd write some tests\n\n```ts\nimport { describe, expect, it } from '@jest/globals'\nimport { shapeMother } from './shape-mother'\n\ndescribe('The square', () =\u003e {\n  it('has four sides', () =\u003e {\n    const shape = shapeMother.blueSquare().build()\n    expect(shape.sides).toBe(4)\n  })\n  it('has four sides of equal length', () =\u003e {\n    const shape = shapeMother.blueSquare().build()\n    expect(shape.sideLengths).toEqual(expect.arrayContaining([...Array(4)].map((_) =\u003e shape.sideLengths[0])))\n  })\n  it('is named correctly', () =\u003e {\n    const shape = shapeMother.blueSquare().build()\n    expect(shape.name).toBe('Square')\n  })\n  it('is coloured blue', () =\u003e {\n    const shape = shapeMother.blueSquare().build()\n    expect(shape.colour).toBe('Blue')\n  })\n})\ndescribe('The isosceles triangle', () =\u003e {\n  it('has three sides', () =\u003e {\n    const shape = shapeMother.redIsoscelesTriangle().build()\n    expect(shape.sides).toBe(3)\n  })\n  it('has two sides of equal length', () =\u003e {\n    const shape = shapeMother.redIsoscelesTriangle().build()\n    expect(shape.sideLengths.reduce\u003cnumber[]\u003e((a, c) =\u003e (a.includes(c) ? a : [...a, c]), [])).toHaveLength(2)\n  })\n  it('is named correctly', () =\u003e {\n    const shape = shapeMother.redIsoscelesTriangle().build()\n    expect(shape.name).toBe('Isosceles triangle')\n  })\n  it('is coloured red', () =\u003e {\n    const shape = shapeMother.redIsoscelesTriangle().build()\n    expect(shape.colour).toBe('Red')\n  })\n})\n```\n\nTry it out on [StackBlitz](https://stackblitz.com/edit/node-au9p8x?file=shape.spec.ts)\n\n## Random Data Builders\n\nDossier comes with a variety of random data builders - View detailed function descriptions includes arguments in the [code docs](./docs/README.md).\n\n| Name                      | Function            | Other                                                                        |\n|---------------------------|---------------------|------------------------------------------------------------------------------|\n| Number                    | randomNumber        |                                                                              |\n| Number between            | randomNumberBetween |                                                                              |\n| Float between             | randomFloatBetween  |                                                                              |\n| String                    | randomString        |                                                                              |\n| ID                        | randomId            |                                                                              |\n| Date                      | randomDate          |                                                                              |\n| Date between              | randomDateBetween   |                                                                              |\n| Boolean                   | randomBoolean       |                                                                              |\n| Incremented number        | incrementedNumber   | Returns a unique incremented number. Call `resetIncrementedNumbers` to reset |\n| Element from a collection | randomElement       |                                                                              |\n| Name of a thing           | randomThingName     |                                                                              |\n| Name of a person          | randomPersonName    |                                                                              |\n| Email                     | randomEmail         |                                                                              |\n| Phone number              | randomPhoneNumber   |                                                                              |\n| URL                       | randomUrl           |                                                                              |\n\n\n[build-img]:https://github.com/MakerXStudio/ts-dossier/actions/workflows/release.yml/badge.svg\n[build-url]:https://github.com/MakerXStudio/ts-dossier/actions/workflows/release.yml\n[downloads-img]:https://img.shields.io/npm/dm/%40makerx%2Fts-dossier\n[downloads-url]:https://www.npmtrends.com/@makerx/ts-dossier\n[npm-img]:https://img.shields.io/npm/v/@makerx/ts-dossier\n[npm-url]:https://www.npmjs.com/package/@makerx/ts-dossier\n[issues-img]:https://img.shields.io/github/issues/MakerXStudio/ts-dossier\n[issues-url]:https://github.com/MakerXStudio/ts-dossier/issues\n[semantic-release-img]:https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg\n[semantic-release-url]:https://github.com/semantic-release/semantic-release\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakerxstudio%2Fts-dossier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmakerxstudio%2Fts-dossier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakerxstudio%2Fts-dossier/lists"}