πŸ’ Promises as components
Branch: master
Clone or download
bodograumann and posva docs(readme): improve grammar
I think this is the intended behaviour of `context.isPending`.

Please squash.
Latest commit 4e212dc Feb 20, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci πŸ’š use yarn.lock as checksum Aug 8, 2018
.github 🚸 Adding github files Jan 27, 2018
docs docs(demo): use new syntax to mix things Feb 11, 2019
src feat: remove assertions in production mode Oct 28, 2018
tests test: add resolved promised test Feb 9, 2019
.eslintrc πŸ”§ Add eslint config Jan 28, 2018
.gitignore πŸ“ add example Mar 9, 2018
.release-it.json chore: release without emojis Oct 28, 2018
LICENSE πŸŽ‰ Init Jan 24, 2018
README.md docs(readme): improve grammar Feb 20, 2019
babel.config.js chore(deps): update Feb 9, 2019
jest.config.js refactor: update package versions and move files Dec 9, 2018
package.json
yarn.lock chore(deps): update Feb 9, 2019

README.md

vue-promised Build Status npm package coverage thanks

Transform your Promises into components !

Help me keep working on Open Source in a sustainable way πŸš€

Become a Patreon

Silver Sponsors

Vue Mastery logo

Bronze Sponsors

Gridsome logo


Installation

npm install vue-promised
# or
yarn add vue-promised

Why?

When dealing with asynchronous requests like fetching content through API calls, you may want to display the loading state with a spinner, handle the error and even hide everything until at least 200ms have been elapsed so the user doesn't see a loading spinner flashing when the request takes very little time. This is quite some boilerplate, and you need to repeat this for every request you want:

<template>
  <div>
    <p v-if="error">Error: {{ error.message }}</p>
    <p v-else-if="isLoading && isDelayElapsed">Loading...</p>
    <ul v-else-if="!isLoading">
      <li v-for="user in data">{{ user.name }}</li>
    </ul>
  </div>
</template>

<script>
export default {
  data: () => ({
    isLoading: false,
    error: null,
    data: null,
    isDelayElapsed: false,
  }),

  methods: {
    fetchUsers() {
      this.error = null
      this.isLoading = true
      this.isDelayElapsed = false
      getUsers()
        .then(users => {
          this.data = users
        })
        .catch(error => {
          this.error = error
        })
        .finally(() => {
          this.isLoading = false
        })
      setTimeout(() => {
        this.isDelayElapsed = true
      }, 200)
    },
  },

  created() {
    this.fetchUsers()
  },
}
</script>

πŸ‘‰ Compare this to the version using Vue Promised that handles new promises.

That is quite a lot of boilerplate and it's not handling cancelling on going requests when fetchUsers is called again. Vue Promised encapsulates all of that to reduce the boilerplate.

Migrating from v0.2.x

Migrating to v1 should be doable in a small amount of time as the only breaking changes are some slots name and the way Promised component is imported. Check releases notes to see the list of breaking changes

Usage

Import the component to use it

import { Promised } from 'vue-promised'

Vue.component('Promised', Promised)

In the following examples, promise is a Promise but can initially be null. data contains the result of the promise. You can of course name it the way you want:

Using pending, default and rejected slots

<template>
  <Promised :promise="usersPromise">
    <!-- Use the "pending" slot to display a loading message -->
    <template v-bind:pending>
      <p>Loading...</p>
    </template>
    <!-- The default scoped slot will be used as the result -->
    <template v-bind="data">
      <ul>
        <li v-for="user in data">{{ user.name }}</li>
      </ul>
    </template>
    <!-- The "rejected" scoped slot will be used if there is an error -->
    <template v-bind:rejected="error">
      <p>Error: {{ error.message }}</p>
    </template>
  </Promised>
</template>

<script>
export default {
  data: () => ({ usersPromise: null }),

  created() {
    this.usersPromise = this.getUsers()
  },
}
</script>

Using one single combined slot

You can also provide a single combined slot that will receive a context with all relevant information. That way you can customise the props of a component, toggle content with your own v-if but still benefit from a declarative approach:

<Promised
  :promise="promise"
  v-slot:combined="{ isPending, isDelayOver, data, error }"
>
  <pre>
    pending: {{ isPending }}
    is delay over: {{ isDelayOver }}
    data: {{ data }}
    error: {{ error && error.message }}
  </pre>
</Promised>

This allows to create more advanced async templates like this one featuring a Search component that must be displayed while the searchResults are being fetched:

<Promised
  :promise="searchResults"
  :pending-delay="200"
  v-slot:combined="{ isPending, isDelayOver, data, error }"
>
  <div>
    <!-- data contains previous data or null when starting -->
    <Search :disabled-pagination="isPending || error" :items="data || []">
      <!-- The Search handles filtering logic with pagination -->
      <template slot-scope="{ results, query }">
        <ProfileCard v-for="user in results" :user="user" />
      </template>
      <!--
        If there is an error, data is null, therefore there are no results and we can display
        the error
      -->
      <MySpinner v-if="isPending && isDelayOver" slot="loading" />
      <template slot="noResults">
        <p v-if="error" class="error">Error: {{ error.message }}</p>
        <p v-else class="info">No results for "{{ query }}"</p>
      </template>
    </Search>
  </div>
</Promised>

context object

  • isPending: is true while the promise is in a pending status. Becomes false once the promise is resolved or rejected. It is reset to true when the promise prop changes.
  • isDelayOver: is true once the pendingDelay is over or if pendingDelay is 0. Becomes false after the specified delay (200 by default). It is reset when the promise prop changes.
  • data: contains the last resolved value from promise. This means it will contain the previous succesfully (non cancelled) result.
  • error: contains last rejection or null if the promise was fullfiled.

Setting the promise

There are different ways to provide a promise to Promised. The first one, is setting it in the created hook:

export default {
  data: () => ({ promise: null }),
  created() {
    this.promise = fetchData()
  },
}

But most of the time, you can use a computed property. This makes even more sense if you are passing a prop or a data property to the function returning a promise (fetchData in the example):

export default {
  props: ['id'],
  computed: {
    promise() {
      return fetchData(this.id)
    },
  },
}

API Reference

Promised component

Promised will watch its prop promise and change its state accordingly.

props

Name Description Type
promise Promise to be resolved Promise
tag Wrapper tag used if multiple elements are passed to a slot. Defaults to span String
pendingDelay Delay in ms to wait before displaying the pending slot. Defaults to 200 Number

slots

Name Description Scope
pending Content to display while the promise is pending and before pendingDelay is over β€”
default Content to display once the promise has been successfully resolved data: resolved value
rejected Content to display if the promise is rejected error: rejection reason
combined Combines all slots to provide a granular control over what should be displayed context See details

License

MIT