# 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(value, type)` | Checks the `Object.prototype.toString` tag. Ordinary and async functions both match `Function`. |
| `isPromise(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. |
```ts
import { callWithAsyncErrorHandling, uuid } from '@/utils'
export const draftId = () => 'draft-' + uuid(12, 36)
export function loadOrReport(
load: () => Promise,
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. |
```ts
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](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/utils/src/core/index.ts) · [Precision implementation](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/utils/src/precision.ts) · [Date picker helper](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/utils/get-date-by-naive-date-picker.ts)