Utils

packages/utils provides shared utility functions for all H5 apps, aggregating the cache and utility modules from @vh5-core/shared.

Installation

Already included as a workspace dependency:

{
  "dependencies": {
    "@vh5/utils": "workspace:*"
  }
}

Async Error Handling

to()

Eliminate try/catch nesting by converting a Promise into a [error, data] tuple.

import { to } from '@vh5/utils';

const [err, data] = await to(getProductList());
if (err) {
  console.error('Request failed', err);
  return;
}
console.log(data);

Progress Bar

startProgress() / stopProgress()

Dynamically loads NProgress to show a top progress bar during route navigation.

import { startProgress, stopProgress } from '@vh5/utils';

router.beforeEach(() => startProgress());
router.afterEach(() => stopProgress());

Global Loading

unmountGlobalLoading()

Removes the injected skeleton screen loading with a fade-out transition. Call after app mount:

import { unmountGlobalLoading } from '@vh5/utils';
unmountGlobalLoading();

Date Formatting

import { formatDate, formatDateTime } from '@vh5/utils';

formatDate(new Date()); // '2024-01-01'
formatDate(new Date(), 'YYYY-MM-DD HH:mm'); // '2024-01-01 12:00'
formatDateTime(new Date()); // '2024-01-01 12:00:00'

Cache Manager

StorageManager

LocalStorage/sessionStorage wrapper with prefix and expiry support:

import { StorageManager } from '@vh5/utils';

const storage = new StorageManager({ prefix: 'my-app-' });

// Set with expiry (ms)
storage.setItem('token', 'xxx', 7 * 24 * 60 * 60 * 1000);

// Get (returns null if expired)
const token = storage.getItem('token');

// Clear all prefixed keys
storage.clear();

// Clear all expired items
storage.clearExpiredItems();

File Download

import {
  downloadFileFromUrl,
  downloadFileFromBase64,
  downloadFileFromBlob,
} from '@vh5/utils';

await downloadFileFromUrl({
  source: 'https://example.com/file.pdf',
  fileName: 'report.pdf',
});
downloadFileFromBlob({ source: blob, fileName: 'export.xlsx' });

// Download via Base64
downloadFileFromBase64({ source: base64String, fileName: 'image.png' });

Other Utilities

Function	Description
cloneDeep()	Deep clone (lodash.clonedeep)
get() / set()	Object path read/write (es-toolkit)
isEqual()	Deep comparison (es-toolkit)
cn()	Merge CSS class names (clsx + tw)
openWindow()	Safely open a new window
diffObj()	Object diff comparison
generateTree()	Convert array to tree structure
flatTree()	Flatten tree structure
isUrl()	URL format validation
unmountGlobalLoading()	Remove global skeleton screen