🌱 @exposition/core

Create an @exposition and use integrations or build custom ones by listening to various events.

Install dependencies

Here are three commands for the most used package managers. I'll be biased and promote my favorite one first.

pnpm add -D @exposition/core

yarn add -D @exposition/core

npm install -D @exposition/core

Motivation

The goal of this project is to provide perfect developer experience, when it comes to API mocking. The reason is that API mocking with a large subset of different variations / results is really hard, and I saw a lot of project skipping tests because even thinking about the amount of work and the debugging later on is insane. Okay! Okay! I will stop. Here is a candy to calm down. 🍬

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.

Create an exposition 📙

const exposition = new Exposition({
  stage: {
    options: ['🐛 Small', '🦋 Big']
  }
} as const)

You can also cluster scenarios into groups by defining further objects inside the config as stated in the below example. The last option MUST have an options key for internal type inference.

const exposition = new Exposition({
  user: {
    age: {
      options: ['under 18 🐣', '18 🐓', 'over 18 🦖']
    },
    avatar: {
      options: ['no avatar 💬', 'image 🤳']
    },
    auth: {
      options: ['valid ✅', 'deny ❌']
    },
    rights: {
      users: {
        create: {
          options: ['yes ✅', 'no ❌']
        },
        read: {
          options: ['yes ✅', 'no ❌']
        },
        update: {
          options: ['yes ✅', 'no ❌']
        },
        delete: {
          options: ['yes ✅', 'no ❌']
        }
      }
    }
  }
} as const)

Config

The first parameter is a simple record that will define the Schema of your Exposition instance. Feel free to name your keys that describe your Scenario in the best possible way. Also, the first index of the options array will be set as the initialValue of the Scenario.

Options

You can overwrite the default settings of Exposition with the second parameter.

| setting | description | example | | -------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | active | Signal all integrations that they should stop their actions | @exposition/integrations/msw will reset all handler if this option is set to false | | restoreState | Signal all integrations that they should prevent all state restoration handler | @exposition/integrations/vue-devtools will not interact with the localStorage if this option is set to false |

const exposition = new Exposition(
  {
    // ... your config
  },
  {
    settings: {
      active: false,
      restoreState: false,
    }
  }
)

Interact with the state

You can use the following commands to interact with your defined Scenario elements:

| command | type | action | |-----------------| -------- |------------------------------------------------------------------------| | values | getter | return the current Scenario values | | initialValues | getter | similar to values but will return the initialValue of the Scenario | | update | method | update one or multiple of your Scenario values | | reset | method | reset one or multiple Scenario elements to their initialValue | | init | method | signal all integrations that you are finished with your setup | | getState | method | get current enriched exposition config state |

There are also commands to read and change the state of the overall Exposition settings:

| command | type | action | | ---------------- | -------- | -------------------------------------------- | | settings | getter | get the currently set settings | | updateSettings | method | update one or multiple Exposition settings |

Listen on events

You can write handler to react to the following events:

| event | timing | extras | | ---------------- | ------------------------------------------ | ------------------------ | | reset | when the reset method is called | | | update | when the update method is called | | | initialized | when the init method is called | will only be called once | | updateSettings | when the updateSettings method is called | |

The event handler will also contain the current Exposition.values and Exposition.settings.

const exposition = new Exposition({
  stage: {
    options: ['🐛 Small', '🦋 Big']
  }
} as const)

exposition.on('update', (values, settings) => {
  console.log(values)
})

exposition.update({ stage: '🦋 Big' })

// will trigger the console.log
// console.log(values) -> { "stage": "🦋 Big" }

Add an integration

Mock Service Worker is the primary integration and even the reason for this library. Therefore, I highly recommend to start with the msw setup guide first.

You can also create your own integration that levels on the above on events.

A guide how to write a custom integration will follow.

For now, you can check out the implementation of msw