{"id":27644606,"url":"https://github.com/h2xd/exposition","last_synced_at":"2025-04-24T00:27:31.796Z","repository":{"id":38294090,"uuid":"485082571","full_name":"h2xd/exposition","owner":"h2xd","description":"Structure to explain the who, what and where of the API mocking process","archived":false,"fork":false,"pushed_at":"2023-04-25T21:14:37.000Z","size":1899,"stargazers_count":4,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-18T09:01:45.261Z","etag":null,"topics":["dx","mocks","testing","typescript","vuejs"],"latest_commit_sha":null,"homepage":"https://h2xd.github.io/exposition/","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/h2xd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-24T16:40:01.000Z","updated_at":"2023-04-19T20:08:29.000Z","dependencies_parsed_at":"2023-01-21T00:46:50.322Z","dependency_job_id":null,"html_url":"https://github.com/h2xd/exposition","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2xd%2Fexposition","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2xd%2Fexposition/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2xd%2Fexposition/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2xd%2Fexposition/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/h2xd","download_url":"https://codeload.github.com/h2xd/exposition/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249931129,"owners_count":21347273,"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":["dx","mocks","testing","typescript","vuejs"],"created_at":"2025-04-24T00:27:31.181Z","updated_at":"2025-04-24T00:27:31.774Z","avatar_url":"https://github.com/h2xd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cbr /\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/src/public/assets/exposition-logo.svg\" width=\"150\" alt=\"Exposition logo\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eExposition\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eStructure to explain the who, what and where of the API mocking process\u003c/b\u003e\n  \u003cbr /\u003e\n  \u003ci\u003eThe ambition is to enhance the creation, usage and the overall experience of API mocking.\u003c/i\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://h2xd.github.io/exposition/\" target=\"_blank\"\u003eDocumentation\u003c/a\u003e\u0026nbsp;\u0026bull;\n  \u003ca href=\"https://twitter.com/aschujkow\" target=\"_blank\"\u003ePing me on Twitter\u003c/a\u003e\n\u003c/p\u003e\n\n## Motivation\n\nThe goal of this project is to provide perfect developer experience, when it comes to API mocking.\nThe reason is that API mocking with a large subset of different variations / results is really hard,\nand I saw a lot of project skipping tests because even thinking about the amount of work and the debugging\nlater on is insane. _Okay! Okay! I will stop. Here is a candy to calm down._ 🍬\n\n**This library is written with the thought that devs never want to leave their IDE and love to fiddle around with code first. Therefore, you can find a lot of examples and descriptions in TSDoc.**\n\n## Install dependencies\n\nHere are three commands for the most used package managers.\u003cbr\u003e\n_I'll be biased and promote my favorite one first._\n\n```sh\npnpm add -D @exposition/core\n```\n\n```sh\nyarn add -D @exposition/core\n```\n\n```sh\nnpm install -D @exposition/core\n```\n\n## Create an exposition 📙\n\n```ts\nconst exposition = new Exposition({\n  stage: {\n    options: ['🐛 Small', '🦋 Big']\n  }\n} as const)\n```\n\nYou can also cluster scenarios into groups by defining further objects inside the config as stated in the below example.\n_The last option MUST have an `options` key for internal type inference._\n\n```ts\nconst exposition = new Exposition({\n  user: {\n    age: {\n      options: ['under 18 🐣', '18 🐓', 'over 18 🦖']\n    },\n    avatar: {\n      options: ['no avatar 💬', 'image 🤳']\n    },\n    auth: {\n      options: ['valid ✅', 'deny ❌']\n    },\n    rights: {\n      users: {\n        create: {\n          options: ['yes ✅', 'no ❌']\n        },\n        read: {\n          options: ['yes ✅', 'no ❌']\n        },\n        update: {\n          options: ['yes ✅', 'no ❌']\n        },\n        delete: {\n          options: ['yes ✅', 'no ❌']\n        }\n      }\n    }\n  }\n} as const)\n```\n\n\n### Config\n\nThe first parameter is a simple record that will define the Schema of your `Exposition`\ninstance. Feel free to name your keys that describe your `Scenario` in the best possible way.\nAlso, the first index of the `options` array will be set as the `initialValue` of the `Scenario`.\n\n### Options\n\nYou can overwrite the default settings of `Exposition` with the second parameter.\n\n| setting        | description                                                                    | example                                                                                                                                                                                |\n| -------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `active`       | Signal all integrations that they should stop their actions                    | [`@exposition/integrations/msw`](https://h2xd.github.io/exposition/integrations/msw.html) will reset all handler if this option is set to `false`                                      |\n| `restoreState` | Signal all integrations that they should prevent all state restoration handler | [`@exposition/integrations/vue-devtools`](https://h2xd.github.io/exposition/integrations/vue-devtools.html) will not interact with the `localStorage` if this option is set to `false` |\n\n\n```ts\nconst exposition = new Exposition(\n  {\n    // ... your config\n  },\n  {\n    settings: {\n      active: false,\n      restoreState: false,\n    }\n  }\n)\n```\n\n## Interact with the state\n\nYou can use the following commands to interact with your defined `Scenario` elements:\n\n| command         | type     | action                                                                 |\n|-----------------| -------- |------------------------------------------------------------------------|\n| `values`        | `getter` | return the current `Scenario` values                                   |\n| `initialValues` | `getter` | similar to `values` but will return the initialValue of the `Scenario` |\n| `update`        | `method` | update one or multiple of your `Scenario` values                       |\n| `reset`         | `method` | reset one or multiple `Scenario` elements to their `initialValue`      |\n| `init`          | `method` | signal all integrations that you are finished with your setup          |\n| `getState`      | `method` | get current enriched exposition config state                           | \n\nThere are also commands to read and change the state of the overall `Exposition` settings:\n\n| command          | type     | action                                       |\n| ---------------- | -------- | -------------------------------------------- |\n| `settings`       | `getter` | get the currently set settings               |\n| `updateSettings` | `method` | update one or multiple `Exposition` settings |\n\n\n\n## Listen on events\n\nYou can write handler to react to the following events:\n\n| event            | timing                                     | extras                   |\n| ---------------- | ------------------------------------------ | ------------------------ |\n| `reset`          | when the `reset` method is called          |                          |\n| `update`         | when the `update` method is called         |                          |\n| `initialized`    | when the `init` method is called           | will only be called once |\n| `updateSettings` | when the `updateSettings` method is called |                          |\n\nThe event handler will also contain the current `Exposition.values` and `Exposition.settings`.\n\n```ts\nconst exposition = new Exposition({\n  stage: {\n    options: ['🐛 Small', '🦋 Big']\n  }\n} as const)\n\nexposition.on('update', (values, settings) =\u003e {\n  console.log(values)\n})\n\nexposition.update({ stage: '🦋 Big' })\n\n// will trigger the console.log\n// console.log(values) -\u003e { \"stage\": \"🦋 Big\" }\n```\n\n## Add an integration\n\nMock Service Worker is the primary integration and even the reason\nfor this library. Therefore, I highly recommend to start with the [msw setup guide](https://h2xd.github.io/exposition/cookbook/setup-msw.html) first.\n\nYou can also create your own integration that levels on the above `on` events.\n\nA guide how to write a custom integration will follow.\n\nFor now, you can check out the implementation of [`msw`](https://github.com/h2xd/exposition/blob/main/packages/integrations/msw/functions/createMswIntegration.ts)\n\n\u003cbr /\u003e\n\u003chr /\u003e\n\u003cbr /\u003e\n\n## Packages\n\n- [🌱 @exposition/core](https://github.com/h2xd/exposition/tree/main/packages/core) — _main functionality_\n- [🧩 @exposition/integrations](https://github.com/h2xd/exposition/tree/main/packages/integrations) — _extensions for developer experience_\n- [🧰 @exposition/core](https://github.com/h2xd/exposition/tree/main/packages/sdk) — _utils to build custom integrations or other exposition based function_\n- [🌐 @exposition/web](https://github.com/h2xd/exposition/tree/main/packages/web) — (NOT PUBLISHED) _utils to interact with web apis like localStorage or the window object_\n\n## Misc\n\n- [🏗 Board](https://github.com/users/h2xd/projects/2)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh2xd%2Fexposition","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fh2xd%2Fexposition","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh2xd%2Fexposition/lists"}