lit-html-promise

lit-html directive to map a promise − Demo

Installation

Via NPM

npm install --save-dev lit-html-promise

Via CDN

As ESM:

import { promise } from '//unpkg.com/lit-html-promise@^1?module'
import { promise } from '//cdn.skypack.dev/lit-html-promise@^1'

// When jsdelivr esm support is stable, you can also use jsdelivr:
import { promise } from '//cdn.jsdelivr.net/npm/lit-html-promise@^1/+esm'

Usage

This directive can be used for any (relevant) template part, like attributes or child.

With mapper object

Signature

promise<T>(
  thePromise: Promise<T> | undefined | null,
  mappers: {
    idle?: () => any, // occurs when thePromise is falsy
    pending?: (previousValue: T | undefined) => any,
    fulfilled?: (value: T) => any,
    rejected?: (error: Error) => any,
  },
)

Example

import { html, render } from 'lit-html'
import { promise } from 'lit-html-promise'

const renderPost = (post?: Promise<Post>) => html`
  <div style="position: relative">
    <div
      class="overlay"
      ?hidden=${promise(post, {
        pending: () => false,
        idle: () => true,
        fulfilled: () => true,
        rejected: () => true,
      })}
    ></div>
    <div>
      ${promise(post, {
        idle: () => html`Idle…`,
        pending: (previousPost) => html`Pending…`,
        fulfilled: (post) => html`Fulfilled! ${post.id} − ${post.title}`,
        rejected: (error) => html`Something went wrong: ${error.message}`,
      })}
    </div>
  </div>
`

With mapper function

Signature

promise<T>(
  thePromise: Promise<T> | undefined | null,
  mapper: (asyncValue: AsyncValue<T>) => any,
)
type AsyncValue<T> =
  | { state: 'idle' } // occurs when thePromise is falsy
  | { state: 'pending', value: T | undefined /* previous value if any */ }
  | { state: 'fulfilled', value: T }
  | { state: 'rejected', error: Error }

Example

import { html, render } from 'lit-html'
import { promise } from 'lit-html-promise'

const renderPost = (post?: Promise<Post>) => html`
  <div style="position: relative">
    <div
      class="overlay"
      ?hidden=${promise(post, (async) => async.state !== 'pending')}
    ></div>
    <div>
      ${promise(post, (async) => {
        switch (async.state) {
          case 'idle': // async = { state: 'idle' }
            return html`Idle…`
          case 'pending': // async = { state: 'pending', value: previousValue | undefined }
            return html`Pending…`
          case 'fulfilled': // async = { state: 'fulfilled', value: post }
            return html`Fulfilled! ${async.value.id} − ${async.value.title}`
          case 'rejected': // async = { state: 'rejected', error }
            return html`Something went wrong: ${async.error.message}`
        }
      })}
    </div>
  </div>
`