2026-11-19 16:05:56 +08:00

7.9 KiB
Raw Blame History

Core, Date, and Number Utilities

Import these utilities from @/utils. Core implementations are available from @/utils/core and precision functions from @/utils/precision.

Core utilities example

Compare PromiseLike values with async functions, try synchronous and asynchronous error callbacks, or inspect paths, date ranges, and object updates.

::: details View core example source <<< @/../admin/src/views/demo/docs-core-utils.tsx :::

Types, identifiers, and error handling

API Input and return value
isValueType<T>(value, type) Checks the Object.prototype.toString tag. Ordinary and async functions both match Function.
isPromise<T>(value) Returns true for a callable then, including custom PromiseLike values.
isAsyncFunction(fn) Tests for an async declaration. Returning a promise from an ordinary function does not match.
uuid(length = 16, radix = 62) Web Crypto random identifier. The character set is digits, uppercase letters, then lowercase letters. Radix is 1–62 and length is a nonnegative safe integer. Invalid input throws RangeError. The identifier uses this custom format.
callWithErrorHandling(fn, onError, args?) Returns the synchronous result. On exception, calls the callback and returns undefined. It does not await promises.
callWithAsyncErrorHandling(fn, onError, args?) Awaits the result and handles both synchronous exceptions and rejections. Errors thrown by the callback reach the caller.
import { callWithAsyncErrorHandling, uuid } from '@/utils'

export const draftId = () => 'draft-' + uuid(12, 36)

export function loadOrReport<T>(
  load: () => Promise<T>,
  report: (error: Error) => void,
) {
  return callWithAsyncErrorHandling(load, report)
}

Objects, paths, and dates

  • updateObjectValue(obj, key, value, callback?) updates only own properties. If both values are plain objects, it shallow-merges them. Otherwise it replaces the old value. Success invokes the callback.
  • removeDuplicateKeys(obj) returns a shallow copy of own enumerable properties. Duplicate keys in a JavaScript literal already use the last value by object creation.
  • equalRouterPath(a, b) ignores query, hash, and trailing slash. Use full paths when filters or tab instances matter.
  • getDateByNaiveDatePicker(value, isRange) converts an empty range from null to [null, null] and preserves other values, including units, time zone, and format.
  • getAppEnvironment() exposes Vite import.meta.env for values such as MODE, DEV, and PROD. Keep secrets out of client-visible configuration.
  • detectOperatingSystem() uses the User-Agent to return an OperatingSystem such as iOS (including iPad with a desktop identifier), Android, Windows, macOS, Linux, or Unknown. Use it for display hints and detect capabilities separately.

Fixed-point arithmetic

CurrencyArguments can be a number, string, or currency.js instance. The template defaults to eight decimal places. Results are currency.js instances with .value and .toString().

Interactive example

Change both numbers and compare add with JavaScript +. This example calls @ray-template/utils/precision directly.

::: details View example source <<< @/examples/PrecisionDemo.vue :::

The admin precision demo also provides subtraction, multiplication, division, and allocation.

::: details View the complete precision demo source <<< @/../admin/src/views/demo/precision/index.tsx :::

API

API Behavior
add(...values) Sum. No arguments return zero.
subtract(first, ...rest) Subtract in order.
multiply(first, ...rest) Multiply in order, parsing string factors first.
divide(first, ...rest) Divide in order. Zero divisors or nonfinite results throw RangeError.
format(value, options?) Convert at the chosen precision. Defaults to a number. type: 'string' returns a string retaining precision.
distribute(value, length, options?) Split evenly and assign rounding remainders to the first shares. 0 and 1 both mean one share. Negative or noninteger counts throw. Supports precision and type.
isCurrency(value) Checks for an instance of the current currency.js class.
import { add, distribute, format } from '@/utils'

export const amount = format(add('0.1', '0.2'), {
  precision: 2,
  type: 'string',
})
export const parts = distribute(10, 3, { precision: 2, type: 'string' })

Define decimal places and rounding rules for allocation and settlement in the business code. currency.js stores scaled integers as JavaScript numbers, so the amount times 10 ** precision must remain within the safe integer range. Transfer strings or integer minor units across APIs to avoid binary floating-point artifacts in display.

Core utilities · Precision implementation · Date picker helper