Road_roller/.claude/skills/uni-helper/references/lib-uni-promises.md

name, description

name	description
uni-promises	Promise wrappers for uni-app APIs - convert callback-based APIs to Promise-based

uni-promises

Promise wrappers for uni-app's callback-based APIs. Convert uni-app APIs to return Promises for better async/await support.

Installation

npm i @uni-helper/uni-promises

Usage

Instead of using callbacks:

// Original callback style
uni.request({
  url: 'https://api.example.com',
  success: (res) => {
    console.log(res.data)
  },
  fail: (err) => {
    console.error(err)
  },
})

Use Promises:

import { request } from '@uni-helper/uni-promises'

// Promise style
const res = await request({
  url: 'https://api.example.com',
})
console.log(res.data)

Available APIs

Most uni-app APIs are wrapped:

Network

• request - HTTP request
• uploadFile - File upload
• downloadFile - File download
• connectSocket - WebSocket

Storage

• setStorage - Set storage
• getStorage - Get storage
• removeStorage - Remove storage
• clearStorage - Clear all storage
• getStorageInfo - Storage info

Media

• chooseImage - Select images
• chooseVideo - Select video
• chooseMedia - Select media
• previewImage - Preview images
• saveImageToPhotosAlbum - Save image
• compressImage - Compress image

File

• saveFile - Save file
• getFileInfo - File info
• getSavedFileList - Saved files list
• removeSavedFile - Remove saved file
• openDocument - Open document

Location

• getLocation - Get location
• chooseLocation - Choose location
• openLocation - Open location

Device

• getSystemInfo - System info
• getNetworkType - Network type
• scanCode - QR/barcode scan
• setClipboardData - Copy to clipboard
• getClipboardData - Get clipboard

UI

• showToast - Show toast
• showModal - Show modal
• showActionSheet - Show action sheet
• showLoading - Show loading
• hideLoading - Hide loading
• showNavigationBarLoading - Nav loading
• hideNavigationBarLoading - Hide nav loading
• setNavigationBarTitle - Set nav title
• setNavigationBarColor - Set nav color
• pageScrollTo - Scroll to position

Navigation

• navigateTo - Navigate to page
• redirectTo - Redirect to page
• reLaunch - Re-launch app
• switchTab - Switch tab
• navigateBack - Go back

Login

• login - User login
• checkSession - Check session
• getUserProfile - Get user profile
• getUserInfo - Get user info

Payment

• requestPayment - Request payment

Example Usage

import {
  showModal,
  showToast,
  getStorage,
  navigateTo,
  getSystemInfo,
  chooseImage,
  uploadFile,
} from '@uni-helper/uni-promises'

async function handleUserAction() {
  // Show confirmation
  const { confirm } = await showModal({
    title: 'Confirm',
    content: 'Are you sure?',
  })

  if (!confirm) return

  try {
    // Get cached data
    const { data: token } = await getStorage({ key: 'token' })

    // Get system info
    const systemInfo = await getSystemInfo()
    console.log('Platform:', systemInfo.platform)

    // Select image
    const { tempFilePaths } = await chooseImage({
      count: 1,
      sizeType: ['compressed'],
    })

    // Upload file
    const uploadRes = await uploadFile({
      url: 'https://api.example.com/upload',
      filePath: tempFilePaths[0],
      name: 'file',
    })

    await showToast({
      title: 'Success!',
      icon: 'success',
    })

    // Navigate
    await navigateTo({
      url: '/pages/success/index',
    })
  } catch (error) {
    await showToast({
      title: error.message || 'Failed',
      icon: 'error',
    })
  }
}

Error Handling

All wrapped APIs reject with standard Error objects:

import { request } from '@uni-helper/uni-promises'

try {
  const res = await request({ url: 'https://api.example.com' })
} catch (error) {
  // error.message contains the fail callback message
  console.error('Request failed:', error.message)
}