DEV Community: Andrew

vue-typed-emit

Andrew — Sat, 10 Oct 2020 14:27:25 +0000

Introduction

A half a year has already passed since I wrote the Vue.js Typed events article. During all this time I was searching for a solution, which doesn't require from a developer to change the way how one is used to emit events in Vue.js components (this.$emit('event', payload)). Finally I've found one, and that's resulted in vue-typed-emit library creation.

Features

The main feature of the library is that it doesn't require from a developer any typed wrappers over a this.$emit invocation. It only requires a simple type which describes names of events your component is supposed to emit along with corresponding payloads.

Here is a trivial example:

import Vue from 'vue'
import { WithEvents } from 'vue-typed-emit'

interface Events {
  foo: string
  bar: [string, number]
  baz: undefined
}

export default (Vue as WithEvents<Events>).extend({
  name: 'Component',
  methods: {
    method() {
      this.$emit('foo', 'foo')
      this.$emit('bar', 0)
      this.$emit('baz')
    },
  },
})

vue-typed-emit verifies that component emits only declared events with valid payloads.

If a developer tries to emit invalid event or invalid payload, one gets an error from TypeScript.

You can find vue-type-refs on GitHub and NPM. Feel free to contribute.

Vuex + TypeScript

Andrew — Mon, 04 May 2020 10:03:23 +0000

Preface

🚨 The approach, described in this article, is not encouraged to be used in production, till Vuex 4.x and Vue.js 3.x are completely released. Vuex 4.x and Vue.js 3.x API are still unstable. The article just illustrates my attempts to statically type Vuex store, since Vuex@v4.0.0-beta.1 has removed its global types.

⚠️ The project configuration section is intentionally omitted. All the source code is located in this repository.

Introduction

Vuex@v4.0.0-beta.1 is officially released. One of the breaking changes that was introduced is that the library is no more shipped with global typings for this.$store within Vue Component.

Vuex 4 removes its global typings for this.$store within Vue Component

More information about reasons and motivations behind it you can find in this issue.

Since global typings is removed, it's up to a developer to define it by himself. As stated in release notes:

When using TypeScript, you must provide your own augment declaration.

In this article I want to share my experience of augmenting types of a store. I will demonstrate this with an example of simple store. For simplicity, our store is as dumb as possible.

Let's do some coding.

State

A definition of a store starts with a definition of state.

state.ts:



export const state = {
  counter: 0,
}

export type State = typeof state

We need to export type of a state because it will be used in definitions of getters, mutations and actions.

So far so good. Let's go ahead to mutations.

Mutations

As stated in the Vuex docs:

It is a commonly seen pattern to use constants for mutation types in various Flux implementations.

So, all of our possible names of mutations will be stored in the MutationTypes enum.

mutation-types.ts:



export enum MutationTypes {
  SET_COUNTER = 'SET_COUNTER',
}

Now that we have defined the names of mutations, we can declare a contract for each mutation (its actual type). Mutation is just a simple function, which accepts state as the first argument and payload as the second, and eventually mutates the former. State type comes in action, it is used as the type of the first argument. The second argument is specific to a particular mutation. We already know that we have SET_COUNTER mutation, so let's declare types for it.

mutations.ts:



import { MutationTypes } from './mutation-types'
import { State } from './state'

export type Mutations<S = State> = {
  [MutationTypes.SET_COUNTER](state: S, payload: number): void
}

Great! It's time to implement it.



import { MutationTree } from 'vuex'
import { MutationTypes } from './mutation-types'
import { State } from './state'

export type Mutations<S = State> = {
  [MutationTypes.SET_COUNTER](state: S, payload: number): void
}

export const mutations: MutationTree<State> & Mutations = {
  [MutationTypes.SET_COUNTER](state, payload: number) {
    state.counter = payload
  },
}

The mutations variable is responsible for storing all of implemented mutations, and eventually will be used to construct the store.

MutationTree<State> & Mutations intersection of types guarantees that a contract is correctly implemented. If it isn't, TypeScript complains and we get the following error:



Type '{ SET_COUNTER(state: { counter: number; }, payload: number): void; }' is not assignable to type 'MutationTree<{ counter: number; }> & Mutations<{ counter: number; }>'.
  Property '[MutationTypes.RESET_COUNTER]' is missing in type '{ SET_COUNTER(state: { counter: number; }, payload: number): void; }' but required in type 'Mutations<{ counter: number; }>'

Just a few words about MutationTree type. MutationTree is a generic type, that is shipped with the vuex package. From its name it's clear, that it helps to declare a type of mutation tree.

vuex/types/index.d.ts:



export interface MutationTree<S> {
  [key: string]: Mutation<S>;
}

But it's not specific enough to suit our needs, because it supposes that a name of mutation can be any string, but in our case we know that a name of mutation can be only typeof MutationTypes. We have left this type just for compatibility with Store options.

Actions

There is no need for actions for such a simple store, but to illustrate typing for actions, let's imagine that we can fetch counter from somewhere.

In the same way as we store names of mutations we store names of actions.

action-types.ts:



export enum ActionTypes {
  GET_COUTNER = 'GET_COUTNER',
}

actions.ts:



import { ActionTypes } from './action-types'

export const actions = {
  [ActionTypes.GET_COUTNER]({ commit }) {
    return new Promise((resolve) => {
      setTimeout(() => {
        const data = 256
        commit(MutationTypes.SET_COUNTER, data)
        resolve(data)
      }, 500)
    })
  },
}

We have a simple GET_COUNTER action which returns Promise, which is resolved in 500ms. It commits the previously defined mutation (SET_COUNTER). Everything seems okay, but commit allows committing any mutation, which is inappropriate, because we know the we can commit just defined mutations. Let's fix it.



import { ActionTree, ActionContext } from 'vuex'
import { State } from './state'
import { Mutations } from './mutations'
import { ActionTypes } from './action-types'
import { MutationTypes } from './mutation-types'

type AugmentedActionContext = {
  commit<K extends keyof Mutations>(
    key: K,
    payload: Parameters<Mutations[K]>[1]
  ): ReturnType<Mutations[K]>
} & Omit<ActionContext<State, State>, 'commit'>

export interface Actions {
  [ActionTypes.GET_COUTNER](
    { commit }: AugmentedActionContext,
    payload: number
  ): Promise<number>
}

export const actions: ActionTree<State, State> & Actions = {
  [ActionTypes.GET_COUTNER]({ commit }) {
    return new Promise((resolve) => {
      setTimeout(() => {
        const data = 256
        commit(MutationTypes.SET_COUNTER, data)
        resolve(data)
      }, 500)
    })
  },
}

In the same way as we declare a contract for mutations we declare a contract for actions (Actions). We must also augment the ActionContext type which is shipped with the vuex package, because it supposes we can commit any mutation. AugmentedActionContext do the job, is restricts committing only the declared mutations (it also checks payload type).

Typed commit inside actions:

Improperly implemented action:

Getters

Getters are also amenable to be statically typed. A getter is just like mutation, and is essentially a function which receives state as its first argument. A declaration of getters is not much different from a declaration of mutations.

getters.ts:



import { GetterTree } from 'vuex'
import { State } from './state'

export type Getters = {
  doubledCounter(state: State): number
}

export const getters: GetterTree<State, State> & Getters = {
  doubledCounter: (state) => {
    return state.counter * 2
  },
}

Global `$store` type

Core modules of the store have been defined, and now we can actually construct the store. A processes of store creation in Vuex@v4.0.0-beta.1 is slightly different from Vuex@3.x. More information about it is located in release notes. The Store type should be declared to safely access the defined store in components. Note that default Vuex types: getters, commit and dispatch should be replaced with types which we have defined earlier. The reason of this replacement is that default Vuex store types is too general. Just look at the default getters types:



export declare class Store<S> {
  // ...
  readonly getters: any;
  // ...
}

Without a doubt, these types are not suitable in case you want to safely work with a typed store.

store.ts:



import {
  createStore,
  Store as VuexStore,
  CommitOptions,
  DispatchOptions,
} from 'vuex'
import { State, state } from './state'
import { Getters, getters } from './getters'
import { Mutations, mutations } from './mutations'
import { Actions, actions } from './actions'

export const store = createStore({
  state,
  getters,
  mutations,
  actions,
})

export type Store = Omit<
  VuexStore<State>,
  'getters' | 'commit' | 'dispatch'
> & {
  commit<K extends keyof Mutations, P extends Parameters<Mutations[K]>[1]>(
    key: K,
    payload: P,
    options?: CommitOptions
  ): ReturnType<Mutations[K]>
} & {
  dispatch<K extends keyof Actions>(
    key: K,
    payload: Parameters<Actions[K]>[1],
    options?: DispatchOptions
  ): ReturnType<Actions[K]>
} & {
  getters: {
    [K in keyof Getters]: ReturnType<Getters[K]>
  }
}

I will not focus on the TypeScript's Utility Types.

We are at the finish line. All is left is the augmentation of the global Vue types.

types/index.d.ts:



import { Store } from '../store'

declare module '@vue/runtime-core' {
  interface ComponentCustomProperties {
    $store: Store
  }
}

Perfect! We are ready to enjoy a fully typed store access.

Usage in components

Now that our store is correctly declared and is statically typed, we can utilize it in our components. We will take a look at a store usage in components defined with Options API and Composition API syntax, since Vue.js 3.0 supports both.

Options API



<template>
  <section>
    <h2>Options API Component</h2>
    <p>Counter: {{ counter }}, doubled counter: {{ counter }}</p>
    <input v-model.number="counter" type="text" />
    <button type="button" @click="resetCounter">Reset counter</button>
  </section>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import { MutationTypes } from '../store/mutation-types'
import { ActionTypes } from '../store/action-types'

export default defineComponent({
  name: 'OptionsAPIComponent',
  computed: {
    counter: {
      get() {
        return this.$store.state.counter
      },
      set(value: number) {
        this.$store.commit(MutationTypes.SET_COUNTER, value)
      },
    },
    doubledCounter() {
      return this.$store.getters.doubledCounter
    }
  },
  methods: {
    resetCounter() {
      this.$store.commit(MutationTypes.SET_COUNTER, 0)
    },
    async getCounter() {
      const result = await this.$store.dispatch(ActionTypes.GET_COUTNER, 256)
    },
  },
})
</script>

Typed state:

Typed getters:

Typed commit:

Typed dispatch:

Composition API

To use store in a component defined using Composition API, we must access it via useStore hook, which just returns our store:



export function useStore() {
  return store as Store
}



<script lang="ts">
import { defineComponent, computed, h } from 'vue'
import { useStore } from '../store'
import { MutationTypes } from '../store/mutation-types'
import { ActionTypes } from '../store/action-types'

export default defineComponent({
  name: 'CompositionAPIComponent',
  setup(props, context) {
    const store = useStore()

    const counter = computed(() => store.state.counter)
    const doubledCounter = computed(() => store.getters.doubledCounter)

    function resetCounter() {
      store.commit(MutationTypes.SET_COUNTER, 0)
    }

    async function getCounter() {
      const result = await store.dispatch(ActionTypes.GET_COUTNER, 256)
    }

    return () =>
      h('section', undefined, [
        h('h2', undefined, 'Composition API Component'),
        h('p', undefined, counter.value.toString()),
        h('button', { type: 'button', onClick: resetCounter }, 'Reset coutner'),
      ])
  },
})
</script>

Typed state:

Typed getters:

Typed commit:

Typed dispatch:

Conclusion

The result of our efforts is fully statically typed store. We are allowed to commit/dispatch only declared mutations/actions with appropriate payloads, otherwise we get an error.

By now Vuex does not provide correct helpers to facilitate process of typing, so we have to do it manually. Hope, that the following versions of Vuex will be shipped with the flexible store typing.

Vue.js Typed events

Andrew — Sun, 23 Feb 2020 17:29:21 +0000

This article is aimed for those who wants to make communication between their components more solid and strictly typed.

❗ Notice. Examples of code, described later in this article, is built using @vue/composition-api, so it's highly encouraged to skim through the RFC of the upcoming Composition API before reading.

You should also definitely check out vue-typed-emit.

Preface

Recently, I have been working on a large-scale project which has approximately 200+ components. The project contains a lot of dumb components, which has no state and accept only props, but also a bunch of stateful components, which tie up these dumb components and contain business logic.

Project's code tends to grow. Business wants new features, and wants them being implemented as fast as possible. When you are set off to release a new feature, there is a big chance that you are going to change the logic of already defined component. Another components might still utilize this component (pass props to it, or listen to its events). So how can you be confident that your changes do not break another components and ultimately the entire system?

Further, I will describe my attempts to make communication between components more reliable and typed.

Typed contracts

The idea is to create typed contracts between components. Every component has it's own "API": props it receives and events it emits. As you might know, events can contain payload (additional data that is attached to event). Thus every component should provide its own API: "I claim that I receive such props with such types and I emit such events with such payload".

JavaScript is dynamically typed, so TypeScript in rescue.

Let's create our first contract. We will use TypeScript interfaces to express that contract.

types.d.ts:

export interface Props {
  messages: {
    id: string
    text: string
    sender: {
      username: string
      avatar?: string
    }
  }[]
}

export interface Events {
  message: MessageEvent
}

export interface MessageEvent {
  text: string
}

Our component declares that it receives array of messages through messages prop, and each message should contain id, text, sender (which should contain username, and also may contain avatar). Also it states that event message with payload of type { text: string } can be emitted.

Remember yourself skimming through component's code trying figure out what events with what payloads it emits? The inner logic of component probably do not bother you at that moment, but you have to skim through it. Dedicated file which contains types(contracts) of our component solves that problem.

Implementation

To properly implement our contracts we must write our components using TypeScript. Unfortunately Vue.js 2.0 is built without proper TypeScript support, while upcoming 3.0 is fully built upon TypeScript. So we are going to use 2.0 @vue/composition-api plugin which adds some new features from 3.0 and also provides us with better TypeScript support.

Let's define our dummy component.

import { createComponent } from '@vue/composition-api'

import { Props } from './types'

export default createComponent({
  name: 'AppChat',
  props: {
    messages: {
      type: Array,
      required: true
    }
  },
  setup(props: Props) {}
})

Vue Composition API provides us with convenient method to define prop types in setup method (props: Props). That's all, we have fully typed props 🎉.

The next part is to emit typed events. As stated here the second argument of setup is context. But typings does not suit our purpose:

interface SetupContext {
  // ...
  emit: (event: string, ...args: unknown[]) => void
  // ...
}

So we need to create some sort of wrapper, which knows typings of our events, and will shout out at us if we emit something wrong (something we do not state in our contract).
Let's use feats @vue/composition-api provides to us, namely create custom hook to use it across the components. There is a handy self-speaking method exposed by @vue/composition-api — getCurrentInstance. Below is the code snippet of our code:

emitter.ts:

import { getCurrentInstance } from '@vue/composition-api'

export function useEmitter<T extends Record<string, any>>() {
  const instance = getCurrentInstance()

  return function emit<K extends keyof T>(name: K, payload: T[K]) {
    if (instance !== null) {
      instance.$emit(name, payload)
    }
  }
}

Now it's time to test our hook to see the real benefit.

// ...

import { useEmitter } from '../../composable/emitter'

import { Props, Events } from './types'

export default createComponent({
  // ...
  setup(props: Props) {
    const emitter = useEmitter<Events>()

    function messageHandler(text: string) {
      emitter('message', { text })
    }
  }
})

emitter knows about our events and suggests us message as possible event name.

Moreover, it warns us, if we pass incorrect payload (incorrect in that case means payload, that does not match with our contract).

Another benefit is that it's possible to directly import type of certain event and to use it in parent's handler:

import { createComponent, createElement as h } from '@vue/composition-api'

import AppChat from '../AppChat'
import { MessageEvent } from '../AppChat/types'

export default createComponent({
  name: 'AppParent',
  components: {
    AppChat
  },
  setup() {
    function messageHandler(message: MessageEvent) {
      console.log(message.text)
    }

    return () => h(AppChat, { on: { message: messageHandler } })
  }
})

Conclusion

Every approach has its advantages and disadvantages. I will try to outline pros and cons of that approach. Let's begin with pros 😊:

strictly typed emits ✅
strictly typed event handlers ✅
types(contracts) is located in dedicated files ✅

It's turn for cons:

you have to use wrapper useEmitter over emit (not emit itself), that adds some overhead to your component's code, and component is highly coupled with that hook, so cannot be easily reused in project which does not contain that hook ❌

Vue.js 3.0 is written from the scratch upon TypeScript, so we can hope that typed emit's will be shipped from out of the box. But for now the only way is to construct our own wrappers to make Vue.js more strictly typed.

Stay tuned, because in the next article I will outline how I managed to patch types of createComponent to substitute type of emit method.

You can play around with the demo here.

Vue.js Composition API: usage with MediaDevices API

Andrew — Mon, 30 Dec 2019 22:18:02 +0000

Introduction

In this article I would like to share my experience about how Vue Composition API helped me to organise and structure work with browser's navigator.mediaDevices API.

It's highly encouraged to skim through the RFC of the upcoming Composition API before reading.

Task

The task I received was not trivial:

application should display all the connected cameras, microphones and speakers that user have;
user should have the ability to switch between them (e.g. if user have two cameras he/she can choose which one is active);
application should appropriately react when user connects or disconnects devices;
the solution should be easily reusable, so developers can use it on any page.

Solution

For now, the only one way to reuse logic across components was mixins. But they have their own nasty drawbacks, so I decided to give a chance to a new Composition API.

Vue Composition API allows easily share stateful logic across components.

Let's start with separation of concerns – create three appropriate hooks useCamera, useMicrophone, useSpeaker. Each hook encapsulates the logic related to the specific device kind.

Let's look at one of them — useCamera:

useCamera.ts:

import { ref, onMounted, onUnmounted } from '@vue/composition-api'

export function useCamera() {
  const camera = ref('')
  const cameras = ref<MediaDeviceInfo[]>([])

  function handler() {
    navigator.mediaDevices.enumerateDevices().then(devices => {
      const value = devices.filter(device => device.kind === 'videoinput')
      cameras.value = value

      if (cameras.value.length > 0) {
        camera.value = cameras.value[0].deviceId
      }
    })
  }

  onMounted(() => {
    if (navigator && navigator.mediaDevices) {
      navigator.mediaDevices.addEventListener('devicechange', handler)
      handler()
    }
  })

  onUnmounted(() => {
    if (navigator && navigator.mediaDevices) {
      navigator.mediaDevices.removeEventListener('devicechange', handler)
    }
  })

  return {
    camera,
    cameras,
  }
}

Here is some explanations:

First off create two variables:

camera, which will store the deviceId of the active camera (remember that user can choose active device);
cameras, which will contain the list of all connected cameras.

These variables is supposed to be consumed by the component, so we return them.

There is handler function which enumerates all the connected devices and pushes only those with kind === 'videoinput' to the cameras array. The type of cameras variable is MediaDeviceInfo[], here is the snippet from lib.dom.d.ts which declares that interface:

type MediaDeviceKind = "audioinput" | "audiooutput" | "videoinput";

/** The MediaDevicesInfo interface contains information that describes a single media input or output device. */
interface MediaDeviceInfo {
    readonly deviceId: string;
    readonly groupId: string;
    readonly kind: MediaDeviceKind;
    readonly label: string;
    toJSON(): any;
}

Composition API provides us with onMounted and onUnmounted hooks, which is the analog to the current Options API mounted and destroyed hooks. As you can see, we invoke our handler function in onMounted hook to get the list of cameras, when component mounts.

Since devices can be connected or disconnected during the runtime of the application, we have to synchronize our data model with actually connected devices. To accomplish that task we need to subscribe to devicechange event which fires either when new device connects or already connected device disconnects. Since we did subscription, we need to not forget to unsubscribe from this event when component is completely destroyed to not catch any nasty bugs.

We have all set up, now let's use our custom hook in a component.

component.vue:

<script lang="ts">
import { createComponent, computed, watch } from '@vue/composition-api'
import { useCamera } from '@/use/camera'

export default createComponent({
  name: 'MyComponent',
  setup() {
    const { camera, cameras } = useCamera()

    const camerasLabels = computed(() =>
      cameras.value.map(camera => camera.label || camera.deviceId)
    )

    watch(cameras, value => {
      console.log(value)
    })

    return {
      camerasLabels,
    }
  },
})
</script>

<template>
  <section>Connected cameras: {{ camerasLabels }}</section>
</template>

Our hook can only be used during the invocation of a setup hook. When hook is invoked it returns our two variables: camera and cameras.

From that moment we can do whatever we want – we have fully reactive variables, as we would have with data using Options API.

For example, let's create a computed property camerasLabels which will list labels of cameras.

Note that when new camera connects or already connected camera disconnects our hook will handle it and update cameras value, which itself is reactive, so our template will be updated too. We can even watch for cameras and perform our custom logic.

The code of useMicrophone and useSpeaker code is the same, but the only difference is device.kind in the handler function. Thus, the solution can be reduced into the one hook – useDevice, which can accept the device kind as it's first argument:

export function useDevice(kind: MediaDeviceKind) {
  // ... the same logic
  function handler() {
    navigator.mediaDevices.enumerateDevices().then(devices => {
      const value = devices.filter(device => device.kind === kind) // <- filter by device kind
      // ... the same logic
    })
  }
  // ... the same logic
}

But I would prefer to split it up using three different hooks, because there might be logic specific to the device kind.

So our final solution looks something like this:

<script lang="ts">
import { createComponent, computed, watch } from '@vue/composition-api'

import { useCamera } from '../use/camera'
import { useMicrophone } from '../use/microphone'
import { useSpeaker } from '../use/speaker'

export default createComponent({
  name: 'App',
  setup() {
    const { camera, cameras } = useCamera()
    const { microphone, microphones } = useMicrophone()
    const { speaker, speakers } = useSpeaker()

    // computed
    const camerasLabels = computed(() =>
      cameras.value.map(camera => camera.label)
    )

    // or method
    function getDevicesLabels(devices: MediaDeviceInfo[]) {
      return devices.map(device => device.label)
    }

    watch(cameras, value => {
      console.log(value)
    })

    return {
      camerasLabels,
      microphones,
      speakers,
      getDevicesLabels,
    }
  },
})
</script>

<template>
  <ul>
    <li>Connected cameras: {{ camerasLabels }}</li>
    <li>Connected microphones: {{ getDevicesLabels(microphones) }}</li>
    <li>Connected speakers: {{ getDevicesLabels(speakers) }}</li>
  </ul>
</template>

Demo

Live demo is located here. You can experiment with it a little – connect a new microphone or camera and you will see how the application reacts.

I have cheated a little. As you can see there are some lines:

await navigator.mediaDevices.getUserMedia({ video: true }) // <- in useCamera
await navigator.mediaDevices.getUserMedia({ audio: true }) // <- in useMicrophone and useSpeaker

It ensures that user have granted access to camera and microphone. If user have denied access to devices hooks won't work. So they implies that user have granted access to devices.

Conclusion

We have created a bunch of useful hooks, that can be easily shared across projects to facilitate work with navigator.mediaDevices. Our hooks react to the actual devices state and synchronize it with data model. The API is simple enough – just execute hook in the setup method, all the logic is encapsulated in hook itself.

P.S. If you like the article, please, click "heart" or "unicorn" — it will give me some motivation to write the next article, where I plan to showcase how to combine these hooks in the useMediaStream hook, which contains stream with our active camera and microphone. Article also will describe how to change input and output sources of the stream.

DEV Community: Andrew

vue-typed-emit

Introduction

Features

Vuex + TypeScript

Preface

Introduction

State

Mutations

Actions

Getters

Global $store type

Usage in components

Options API

Composition API

Conclusion

Vue.js Typed events

Preface

Typed contracts

Implementation

Conclusion

Vue.js Composition API: usage with MediaDevices API

Introduction

Task

Solution

Demo

Conclusion

Global `$store` type