Promise Component for Vue 3

[shixianqin]

Hello everyone,

This is a Promise-based component encapsulation method. Designed to simplify the handling of asynchronous input and output of components. Its design goal is to implement the software engineering concept of High-cohesion and Low-coupling.

This component rendering mode has actually appeared in many UI frameworks (such as MessageBox, Modal and other components), but it has never been extracted and used separately (or I haven't found it yet), so as to support any component to call in the form of Promise.

Next, please see the introduction and examples. I look forward to getting more suggestions from everyone.

Features

🔥 Promise-based invocation

Promise-based invocation allows us to flexibly control the asynchronous input and output flow of components. The
component will be invoked internally at the appropriate time resolve or reject callback. This invocation follows a normalized pattern of asynchronous operation, making the use and management of components more reliable and consistent.

📦 Independence of calls

Each call to the component spawns a new, independent instance. They don't share call state, and they don't have issues like state caching. Whether the same component is called multiple times in a single page, or multiple instances of the same component are used in different pages, they are guaranteed to be independent of each other.

🙋 Render on demand

Components are rendered only when they are needed. This rendering method can be triggered according to specific events or external conditions, making the rendering logic more flexible and controllable. For example, we call a component when a user clicks a button or when a condition is met. This on-demand rendering method can effectively improve page load speed and performance, while also reducing unnecessary rendering and resource consumption.

♻️ Destroy after use

The result of a component's rendering is temporary and will be destroyed as soon as it is finished, similar to the effect of burning. This feature is ideal for temporary and one-off scenarios, while also improving program performance.

Installation

npm i @promise-components/vue

Example

Let's implement a user list and include the ability to interactively add and edit user information using a dialog box.

Initialization

You need to use the shared rendering slot of the Promise component in the root component, which will provide a default rendering location for the Promise components of the entire application and inheritance of the application context (such as: store, theme, i18n...).

<!-- App.vue -->

<script setup lang="ts">
  import { SharedSlot } from '@promise-components/vue'
</script>

<template>
  <div>
    ...

    <SharedSlot/>
  </div>
</template>

Defining a Promise Component

<!-- add-user.vue -->

<script setup lang="ts">
  import { PromiseResolvers } from '@promise-components/vue'
  import { reactive } from 'vue'

  interface UserItem {
    name: string
    age: number
    id: number
  }

  /**
   * 🔴 The Props parameter must inherit from PromiseResolvers
   */
  interface Props extends PromiseResolvers<UserItem> {
    user?: UserItem
  }

  const props = defineProps<Props>()

  const formData = reactive<UserItem>({
    name: '',
    age: 0,
    id: Math.random(),
    ...props.user, // If editing, fill in the default value
  })

  function handleSubmit () {
    if (!formData.name) return alert('Please enter `Name`')
    if (!formData.age) return alert('Please enter `Age`')

    // 🔴 Call resolve callback
    props.resolve(formData)
  }

  function handleCancel () {
    // 🔴 Call reject callback
    props.reject()
  }
</script>

<template>
  <dialog open>
    <form>
      <p>
        <span>Name: </span>
        <input v-model="formData.name" type="text"/>
      </p>

      <p>
        <span>Age: </span>
        <input v-model="formData.age" type="number"/>
      </p>
    </form>

    <p>
      <button @click="handleCancel">Cancel</button>
      <button @click="handleSubmit">Submit</button>
    </p>
  </dialog>
</template>

Since the Promise component instance cannot be exported directly in the .vue file, an additional .ts file is required to create the instance.

// add-user.promise.ts

import { PromiseComponent } from '@promise-components/vue'
import Component from './add-user.vue'

export const AddUser = new PromiseComponent(Component)

File name suggestions:

• Main: index.ts
• Named: [name].promise.ts

Using the Promise component

<!-- user-list.vue -->

<script setup lang="ts">
  import { ref } from 'vue'
  import { AddUser } from './add-user.promise.ts'

  interface UserItem {
    name: string
    age: number
    id: number
  }

  const userList = ref<UserItem[]>([])

  async function handleAdd () {
    /**
     * 🔴 Using component
     */
    const newUser = await AddUser.render()

    userList.value.push(newUser)
  }

  async function handleEdit (editIndex: number) {
    const target = userList.value[editIndex]

    /**
     * 🔴 Using component and providing parameters (Edit mode)
     */
    const modifiedUser = await AddUser.render({
      user: target,
    })

    Object.assign(target, modifiedUser)
  }
</script>

<template>
  <div>
    <ul>
      <li v-for="(item, index) in userList" :key="item.id">
        <span>Name: {{item.name}}, Age: {{item.age}}</span>
        <button @click="handleEdit(index)">Edit</button>
      </li>
    </ul>

    <button @click="handleAdd">Add</button>
  </div>
</template>

Well, we have happily completed the development of the user list function based on the Promise component.

Custom Render Slots

Component slot

If you want to render a Promise component in a specific location, you can use the custom slot of the Promise component.

<!-- user-list.vue -->

<script setup lang="ts">
  import { AddUser } from './add-user.promise.ts'
</script>

<template>
  <div>
    ...

    <AddUser.Slot/>
  </div>
</template>

Interface

import { ComponentOptions, Component } from 'vue'

/**
 * The basic props of the PromiseComponent
 * @property resolve Promise Operation Success Callback (Resolved)
 * @property reject Promise Operation Failure Callback (Rejected)
 */
interface PromiseResolvers<T> {
  resolve: (value: T) => void;
  reject: (reason?: any) => void;
}

/**
 * Public slot of Promise components
 */
declare const SharedSlot: ComponentOptions

/**
 * Promise component constructor
 */
declare class PromiseComponent<T extends PromiseResolvers<any>, P = Omit<T, keyof PromiseResolvers<any>>, R = Parameters<T['resolve']>[0]> {

  constructor (public Component: Component<T>);

  /**
   * promise rendering
   * @param props component props
   */
  render (props?: P): Promise<R>;

  /**
   * Custom slot for Promise component
   */
  Slot: ComponentOptions
}

export {
  PromiseComponent,
  type PromiseResolvers,
  SharedSlot,
}

Github repository

• Promise Components
• @promise-components/vue