Utilities | ArcBlock

The @blocklet/payment-react library exports a suite of utility functions and classes designed to simplify common tasks such as making API requests, managing cache, handling dates, formatting prices, and setting up internationalization. These tools are built to work seamlessly with the library's components and providers.

API Client

The library provides a pre-configured Axios instance for making API requests to your payment backend. It automatically handles base URLs and other necessary configurations.

API Client Usage

import { api } from '@blocklet/payment-react';

// Basic GET request
const getPayments = async () => {
  const response = await api.get('/api/payments');
  return response.data;
};

// POST request with a payload
const createCheckout = async (amount) => {
  const data = await api.post('/api/checkout', { amount });
  return data;
};

// GET request with query parameters
const getPaidInvoices = async () => {
  const results = await api.get('/api/invoices', {
    params: { status: 'paid' }
  });
  return results.data;
};

// PUT request with additional configuration
const updateSubscription = async (data) => {
  const config = {
    headers: { 'Custom-Header': 'value' }
  };
  const response = await api.put('/api/subscription', data, config);
  return response.data;
};

CachedRequest

To optimize performance and reduce redundant network requests, you can use the CachedRequest class. It provides a simple way to cache data with configurable strategies and time-to-live (TTL).

Configuration Options

When creating a CachedRequest instance, you can provide the following options:

Option	Type	Description	Default
`strategy`	`'session' \| 'local' \| 'memory'`	The storage mechanism for the cache.	`'session'`
`ttl`	`number`	The cache's time-to-live in milliseconds. A value of `0` means no expiration.	`0`

Usage Example

Here’s how to create and use a cached request to fetch product prices.

CachedRequest Example

import { CachedRequest, api } from '@blocklet/payment-react';

// 1. Create a cached request instance
const priceRequest = new CachedRequest(
  'product-prices',
  () => api.get('/api/prices'),
  {
    strategy: 'session',  // Cache data in sessionStorage
    ttl: 5 * 60 * 1000   // Cache for 5 minutes
  }
);

// 2. Use the cached request in your component
async function fetchPrices() {
  // This will use the cache if it's available and not expired
  const prices = await priceRequest.fetch();

  // To bypass the cache and force a fresh data fetch
  const freshPrices = await priceRequest.fetch(true);

  return prices;
}

// 3. Clear the cache when data changes
async function updatePrices() {
  await api.post('/api/prices', newPriceData);
  priceRequest.clearCache(); // Or await priceRequest.fetch(true);
}

Date Handling

The library re-exports a pre-configured dayjs instance with useful plugins like relativeTime, utc, and timezone already included. You can use this for any date and time manipulation needs.

Date Handling with dayjs

import { dayjs } from '@blocklet/payment-react';

// Format the current date
const formattedDate = dayjs().format('YYYY-MM-DD HH:mm');

// Parse a timestamp
const dateFromTimestamp = dayjs(1672531200000);
const unixTimestamp = dateFromTimestamp.unix();

// Calculate relative time
const fiveMinutesAgo = dayjs().subtract(5, 'minute');
const relativeTime = dayjs().from(fiveMinutesAgo); // "5 minutes ago"

Internationalization (i18n)

@blocklet/payment-react includes built-in support for i18n. You can create your own translator or merge your translations with the library's defaults.

Creating a Translator

Use the createTranslator function to set up your own translation instance.

Custom Translator Setup

import { createTranslator } from '@blocklet/payment-react';

const myTranslations = {
  en: {
    checkout: { title: 'Complete Payment' }
  },
  zh: {
    checkout: { title: '完成支付' }
  }
};

const translator = createTranslator({ fallbackLocale: 'en' }, myTranslations);

translator('checkout.title', 'zh'); // '完成支付'

Merging with Library Translations

To leverage the library's built-in translations for components while adding your own, you can merge them together.

Merging Translations

import { translations as paymentTranslations } from '@blocklet/payment-react';
import merge from 'lodash/merge';

// Your application's translations
import en from './locales/en';
import zh from './locales/zh';

export const translations = merge(
  {
    en,
    zh,
  },
  paymentTranslations
);

Formatting Utilities

Several helper functions are available to format data for display.

Function	Description
`formatPrice`	Formats a price object into a human-readable string, considering recurring intervals.
`formatRecurring`	Formats a recurring object into strings like "monthly" or "every 3 months".
`formatBNStr`	Formats a BigNumber string from a base unit into a token value with specified precision.
`formatNumber`	Formats a number or string with thousand separators and precision.
`formatError`	Parses various error formats (GraphQL, Joi, Axios) into a readable string.

Formatting Example

import { formatNumber, formatRecurring } from '@blocklet/payment-react';

// Format a number
const formatted = formatNumber('1234567.89123', 2); // "1,234,567.89"

// Format a recurring interval
const monthly = formatRecurring({ interval: 'month', interval_count: 1 }); // "per month"
const quarterly = formatRecurring({ interval: 'month', interval_count: 3 }); // "Quarterly"

Validation Utilities

The library also includes helpers for form validation.

validatePostalCode

Checks if a given postal code is valid for a specific country.

Postal Code Validation

import { validatePostalCode } from '@blocklet/payment-react';

// Returns true
const isValidUS = validatePostalCode('90210', 'US');

// Returns false
const isInvalidUS = validatePostalCode('ABC-123', 'US');

// Returns true for a UK postal code
const isValidGB = validatePostalCode('SW1A 0AA', 'GB');