Rattail
A Vite+ oriented, AI Agent friendly front-end toolchain from rattail. All utilities, integrations, and CLI are published under one rattail package.
IMPORTANT: For each API, open the corresponding references/<name>.md (see tables below). Those files mirror the VitePress docs (usage, arguments, return), link to the official English and Chinese pages on rattail.varletjs.org, and include the corresponding src/**/*.ts excerpt as type declarations.
CLI (rt)
Binary name: rt (registered via package.json → dist/cli/bin.mjs). Built with Commander. Unifies release, changelog, commit-lint, API generation, hook management, cleanup, and lockfile checking into a single CLI.
Configuration: All CLI commands read from the rattail key inside vite.config.ts (loaded via unconfig). See references/cli/configuration.md.
Commands
| Command |
Description |
Reference |
rt clean [patterns...] |
Remove files and directories using glob patterns |
references/cli/clean.md |
rt api |
Generate API modules from OpenAPI/Swagger schema |
references/cli/api.md |
rt hook |
Install git hooks from config |
references/cli/hook.md |
rt release |
Release packages, generate changelogs, tag, optionally publish |
references/cli/release.md |
rt changelog |
Generate changelog |
references/cli/changelog.md |
rt commit-lint <path> |
Lint a commit message file |
references/cli/commit-lint.md |
rt lockfile-check |
Check lockfile updates and auto-install dependencies |
references/cli/lockfile-check.md |
Quick start
// vite.config.ts
import { defineConfig } from 'rattail/vite-plus'
export default defineConfig({
rattail: {
clean: ['dist', 'coverage'],
hook: {
'commit-msg': ['rt commit-lint $1'],
},
api: {
input: './schema.yaml',
output: './src/apis/generated',
preset: 'axle',
},
release: {
// @varlet/release options
},
changelog: {
// @varlet/release changelog options
},
},
})
Programmatic usage
All CLI commands are also available as functions:
import { clean, api, hook, release, changelog, commitLint, lockfileCheck } from 'rattail/cli'
Core functions
Import from rattail:
import { isString, debounce, cloneDeep /* ... */ } from 'rattail'
General
| Function |
Description |
isString |
Determine whether the input value is a string. |
isNumber |
Determine whether the input value is a number. |
isNumeric |
Determine whether the input value is a number or a numeric string. |
isBoolean |
Determine whether the input value is a boolean. |
isTruthy |
Determine whether the input value is truthy. |
isPrimitive |
Determine whether the input value is a primitive. |
isPlainObject |
Determine whether the input value is a plain object. |
isObject |
Determine whether the input value is an object (excluding null). |
isArray |
Determine whether the input value is an array. |
isNullish |
Determine whether the input value is null or undefined. |
isPromise |
Determine whether the input value is a Promise. |
isRegExp |
Determine whether the input value is a RegExp. |
isFunction |
Determine whether the input value is a function. |
isDate |
Determine whether the input value is a Date. |
isSet |
Determine whether the input value is a Set. |
isMap |
Determine whether the input value is a Map. |
isSymbol |
Determine whether the input value is a symbol. |
isWeakMap |
Determine whether the input value is a WeakMap. |
isWeakSet |
Determine whether the input value is a WeakSet. |
isBlob |
Determine whether the input value is a Blob. |
isFile |
Determine whether the input value is a File. |
isArrayBuffer |
Determine whether the input value is a ArrayBuffer. |
isTypedArray |
Determine whether the input value is a TypedArray. |
isDataView |
Determine whether the input value is a DataView. |
isError |
Determine whether the input value is an Error object. |
isDOMException |
Determine whether the input value is a DOMException object. |
isWindow |
Determine whether the input value is the global window object. |
isEmpty |
Determine whether the input value is empty (undefined, null, an empty string, or an empty array). |
isEmptyPlainObject |
Determine whether the input value is a empty (no own enumerable keys and no symbols) plain object. |
isNonEmptyArray |
Determine whether the input value is a non-empty array. |
isEqual |
Deeply compare two values. |
isEqualWith |
Deeply compare two values. Supports passing a comparison method, and returns true if the two values are equal. |
inBrowser |
Determine whether the code is running in a browser environment. |
inMobile |
Determine whether the code is running in a mobile browser environment. |
hasOwn |
Determine whether an object has a specific property as its own (not inherited). |
hasDuplicates |
Checks if an array contains duplicate values. |
hasDuplicatesBy |
Checks if an array contains duplicate values based on a custom comparison function. |
supportTouch |
Determine whether the current environment supports touch events. |
toTypeString |
Return the type string of the input value. |
toRawType |
Return the raw type of the input value. |
getGlobalThis |
Retrieve the global object based on the current environment. |
assert |
Throws an error when the input value is not true, the second argument is the error message. |
Number
| Function |
Description |
toNumber |
Convert the input value to a number. If the value is null or undefined, it returns 0. |
genNumberKey |
Generate a unique numeric key, incrementing with each call. |
randomNumber |
Generate a random integer between min and max, inclusive. |
clamp |
Clamp a number within the inclusive min and max bounds. |
clampArrayRange |
Clamp an index within the bounds of an array's length. |
times |
Execute a function a specified number of times and return an array of results. |
delay |
Create a promise that resolves after a specified time in milliseconds. |
String
| Function |
Description |
randomString |
Generate a random alphanumeric string of a specified length. |
randomColor |
Generate a random hexadecimal color string. |
genStringKey |
Generate a unique string key by incrementing a numeric value and converting it to a string. |
camelize |
Convert a string to camelCase. |
kebabCase |
Convert a string to kebab-case. |
pascalCase |
Convert a string to PascalCase. |
upperFirst |
Capitalize the first letter of a string, leaving the rest unchanged. |
lowerFirst |
Lowercase the first letter of the string and keep the rest unchanged. |
slash |
Convert all backslashes (\) in a path to forward slashes (/). |
ensurePrefix |
Ensure that a prefix exists in the string, and add it if it does not exist. |
ensureSuffix |
Ensure that a suffix exists in the string, and add it if it does not exist. |
maskString |
Mask part of a string with a specified character, keeping prefix and suffix visible. |
Math
| Function |
Description |
sum |
Calculates the sum of values in an array of numbers. |
sumBy |
Calculates the sum of values in an array based on a provided function. |
sumHash |
Calculate a hash sum for a given value. |
minBy |
Find the minimum value in an array based on a function applied to each element. |
maxBy |
Find the maximum value in an array based on a function applied to each element. |
mean |
Calculate the mean (average) of an array of numbers. |
meanBy |
Calculate the mean (average) of an array by applying a function to each element. |
sample |
Return a random element from an array. |
round |
Return number rounded to precision. |
floor |
Return number rounded down to precision. |
ceil |
Return number rounded up to precision. |
Object
| Function |
Description |
set |
Set a value at a given path in an object, creating nested objects or arrays as needed. |
pick |
Pick object properties and construct a new object. |
pickBy |
Extract object properties by a predicate function and construct a new object. |
omit |
Excludes object properties and constructs a new object. |
omitBy |
Excludes object properties by a predicate function and constructs a new object. |
deriveKey |
Derive new object keys by a mapping while keeping the original keys. |
mapObject |
Maps an object into a new object. |
rekey |
Rename object keys by a mapping and construct a new object. |
objectKeys |
Get an array of keys from an object, with full TypeScript type support. |
objectEntries |
Get an array of key-value pairs from an object, with full TypeScript type support. |
promiseWithResolvers |
Returns an object containing a new Promise and two functions to resolve or reject it. |
Array
| Function |
Description |
at |
Retrieves the element at a specified index in an array, supporting negative indices. |
chunk |
Chunking an array. The passed size indicates the length of the chunk. |
uniq |
Creates a duplicate-free version of an array, using the values equality. |
uniqBy |
Creates a duplicate-free version of an array, using a custom comparison function. |
difference |
Creates an array of values not contained in other given arrays. |
differenceWith |
Creates an array of values not contained in other given arrays, with custom comparison. |
intersection |
Creates an array of unique values contained in all given arrays. |
intersectionWith |
Creates an array of unique values contained in all given arrays, with custom comparison. |
xor |
XOR (Exclusive OR) the passed array and return a new array. |
xorWith |
XOR (Exclusive OR) the passed array with custom comparison. |
groupBy |
Group the elements in a given array by a function's return value as the key. |
find |
Finds the first or last element in an array that meets a condition, returning the element and its index. |
shuffle |
Randomly shuffles elements within an array. |
removeItem |
Removes the first occurrence of a specific item from an array. |
removeItemBy |
Removes the first item matching a predicate, mutating the original array. |
removeItemsBy |
Removes all items matching a predicate, mutating the original array. |
toggleItem |
Adds or removes an item from an array, based on its existence. |
removeArrayBlank |
Removes null or undefined values from an array. |
removeArrayEmpty |
Removes null, undefined, or empty string ('') values from an array. |
normalizeToArray |
Converts a value to an array if it is not already an array. |
Collection
| Function |
Description |
cloneDeep |
Create a deep clone of a value. |
cloneDeepWith |
Create a deep clone of a value, applying a custom function for cloning. |
merge |
Merge two objects recursively. |
mergeWith |
Merge two objects recursively, with custom merge logic. |
Function
| Function |
Description |
NOOP |
This method returns undefined. |
call |
Call a single function or multiple functions and pass arguments to them. |
callOrReturn |
Calls a function with args if input is a function, otherwise returns the input directly. |
once |
Creates a function that will only execute once. |
debounce |
Create a debounce function that delays execution by delay ms after the last call. |
throttle |
Create a throttle function that calls fn at most once every delay ms. |
tryCall |
Safely call a function and return an [error, result] tuple. |
tryAsyncCall |
Safely call an async function and return a Promise<[error, result]> tuple. |
File
| Function |
Description |
toText |
Converts a File object to a text string. |
toDataURL |
Converts a File object to a Data URL string. |
toArrayBuffer |
Converts a File object to an ArrayBuffer. |
Util
| Function |
Description |
motion |
Used to implement basic transition animation based on requestAnimationFrame. |
copyText |
Copies text to the clipboard. |
download |
Trigger browser download, supporting downloading via file url, Blob, File. |
duration |
Creates a fluent duration builder that allows chaining time units to calculate total milliseconds or seconds. |
enumOf |
Enum utility with TS-friendly types. Built-in fields: value, label, description. |
storage |
Enhance localStorage and sessionStorage, support automatic JSON stringify and parse. |
classes |
Generates a list of class names based on a given condition. |
createNamespaceFn |
Creates a namespace function for BEM-style naming. |
createCacheManager |
Creates a simple in-memory cache manager with optional TTL support. |
raf |
Creates a Promise-based requestAnimationFrame that resolves on the next frame. |
doubleRaf |
Creates a Promise-based double requestAnimationFrame that resolves after two frames. |
requestAnimationFrame |
Provides a cross-browser compatible requestAnimationFrame function. |
cancelAnimationFrame |
Cancels a requestAnimationFrame request, with a fallback to clearTimeout. |
inViewport |
Determines if an element is visible within the viewport. |
preventDefault |
Prevents the default action of an event if it is cancelable. |
getStyle |
Retrieves computed CSS styles for a given DOM element. |
getRect |
Gets the dimensions and position of an element or window as a DOMRect object. |
getScrollTop |
Gets the vertical scroll position of an element or window. |
getScrollLeft |
Gets the horizontal scroll position of an element or window. |
getParentScroller |
Finds the closest scrollable ancestor of an element. |
getAllParentScroller |
Retrieves all scrollable ancestor elements of an element. |
prettyJSONObject |
Formats a JSON object with indentation for easy readability. |
tryParseJSON |
Attempts to parse a JSON string. If parsing fails, returns undefined. |
navigation |
Browser-level navigation API for real page jumps. |
Integrated
| Function |
Description |
mitt |
Event emitter / pubsub. Integrated with mitt. |
uuid |
UUID generation helpers integrated with uuid. |
First-party integration: Axle (rattail/axle)
Progressive HTTP request layer on top of axios for Vue 3 (and plain JS for the core client), re-exported as a first-party integration. Three entry points:
| Entry |
Import |
Purpose |
| Core |
rattail/axle |
createAxle, types, createMatcher, helpers, interceptors |
| Vue |
rattail/axle/use |
createUseAxle, useValues, useHasLoading, useAverageProgress |
| API builder |
rattail/axle/api |
createApi — URL-bound load / use helpers |
Upstream: @varlet/axle · README · Chinese README
IMPORTANT: Open references/axle/<topic>.md for detailed API docs, type declarations, and usage examples.
Quick start
import { createAxle } from 'rattail/axle'
const axle = createAxle(/* axios create config */)
axle.get('/url', { current: 1, pageSize: 10 }, { headers: {} })
Topic references
| Topic |
Reference |
createAxle, AxleInstance, shared axios, headers, runner overview |
references/axle/core-client.md |
GET/POST/… runners (getBlob, postUrlEncode, …) |
references/axle/request-runners.md |
createUseAxle and composables |
references/axle/vue-composition.md |
createApi (load, use, path params) |
references/axle/api-factory.md |
matchPattern, createMatcher, interceptors |
references/axle/interceptors-and-matcher.md |
withResponse, download |
references/axle/helpers.md |
Peer dependency: vue ^3.2 when using rattail/axle/use or rattail/axle/api.
First-party integration: Ruler Factory (rattail/ruler-factory)
Flexible chainable validation rule factory for TypeScript/JavaScript, re-exported as a first-party integration. Supports UI form integration with Varlet, Vant, Naive UI, Element Plus.
import { rulerFactory } from 'rattail/ruler-factory'
Upstream: ruler-factory · README · Chinese README
IMPORTANT: Before chaining rules, read the reference for rulerFactory and your UI's generator pattern, then open the specific references/ruler-factory/<name>.md for the method or type you use.
Quick start
import { rulerFactory } from 'rattail/ruler-factory'
const r = rulerFactory((validator) => {
return (value) => {
const e = validator(value)
return e ? e.message : true
}
})
r().string('Not a string').required('Required').min(2, 'Too short').done()
API index
Package
| Symbol |
Description |
rulerFactory |
Factory that builds a chainable ruler for your UI rule format. |
Exported types
| Symbol |
Description |
RulerFactoryMessage |
String or lazy string for error messages. |
RulerFactoryValidator |
Validator fn: value in, Error or undefined out. |
RulerFactoryGenerator |
Maps validator + params to rule type R. |
RulerContext |
Chainable context type (methods + extend). |
Type guards
| Symbol |
Description |
string |
Assert string type (optional message). |
number |
Assert number type. |
array |
Assert array type. |
boolean |
Assert boolean type. |
object |
Assert plain object type. |
symbol |
Assert symbol type. |
bigint |
Assert bigint type. |
null |
Assert value is null. |
undefined |
Assert value is undefined. |
true |
Assert value is true. |
false |
Assert value is false. |
Validators
| Symbol |
Description |
required |
Reject empty values (rattail isEmpty). |
min |
Min length / numeric min depending on type. |
max |
Max length / numeric max depending on type. |
length |
Exact length for string or array. |
regex |
String matches RegExp. |
startsWith |
String starts with prefix. |
endsWith |
String ends with suffix. |
includes |
Substring or array includes value. |
uppercase |
String is all uppercase. |
lowercase |
String is all lowercase. |
email |
String looks like an email. |
gt |
Number/bigint greater than. |
gte |
Number/bigint greater or equal. |
lt |
Number/bigint less than. |
lte |
Number/bigint less or equal. |
positive |
Number/bigint > 0. |
negative |
Number/bigint < 0. |
uniq |
Array has no duplicates. |
uniqBy |
Array unique by comparator. |
Predicates
| Symbol |
Description |
is |
Custom predicate must pass. |
not |
Custom predicate must fail. |
Finish
| Symbol |
Description |
done |
Return built rules array. |
Custom
| Symbol |
Description |
addRule |
Append custom validator. |
getMessage |
Resolve message string/lazy fn. |
Transform
| Symbol |
Description |
trim |
Trim strings before validation. |
toLowerCase |
Lowercase strings before validation. |
toUpperCase |
Uppercase strings before validation. |
transform |
Replace transformer with custom fn. |
transformer |
Current transform pipeline (internal hook). |
…(truncated)
1---2name: varletjs-rattail-rattail3description: Rattail4---56# Rattail78A Vite+ oriented, AI Agent friendly front-end toolchain from [rattail](https://github.com/varletjs/rattail). All utilities, integrations, and CLI are published under one `rattail` package.910**IMPORTANT:** For each API, open the corresponding `references/<name>.md` (see tables below). Those files mirror the VitePress docs (usage, arguments, return), link to the official English and Chinese pages on [rattail.varletjs.org](https://rattail.varletjs.org), and include the corresponding `src/**/*.ts` excerpt as type declarations.1112---1314## CLI (`rt`)1516Binary name: **`rt`** (registered via `package.json` → `dist/cli/bin.mjs`). Built with Commander. Unifies release, changelog, commit-lint, API generation, hook management, cleanup, and lockfile checking into a single CLI.1718**Configuration:** All CLI commands read from the `rattail` key inside `vite.config.ts` (loaded via `unconfig`). See [references/cli/configuration.md](references/cli/configuration.md).1920### Commands2122| Command | Description | Reference |23| ------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------- |24| `rt clean [patterns...]` | Remove files and directories using glob patterns | [references/cli/clean.md](references/cli/clean.md) |25| `rt api` | Generate API modules from OpenAPI/Swagger schema | [references/cli/api.md](references/cli/api.md) |26| `rt hook` | Install git hooks from config | [references/cli/hook.md](references/cli/hook.md) |27| `rt release` | Release packages, generate changelogs, tag, optionally publish | [references/cli/release.md](references/cli/release.md) |28| `rt changelog` | Generate changelog | [references/cli/changelog.md](references/cli/changelog.md) |29| `rt commit-lint <path>` | Lint a commit message file | [references/cli/commit-lint.md](references/cli/commit-lint.md) |30| `rt lockfile-check` | Check lockfile updates and auto-install dependencies | [references/cli/lockfile-check.md](references/cli/lockfile-check.md) |3132### Quick start3334```ts35// vite.config.ts36import { defineConfig } from 'rattail/vite-plus'3738export default defineConfig({39 rattail: {40 clean: ['dist', 'coverage'],4142 hook: {43 'commit-msg': ['rt commit-lint $1'],44 },4546 api: {47 input: './schema.yaml',48 output: './src/apis/generated',49 preset: 'axle',50 },5152 release: {53 // @varlet/release options54 },5556 changelog: {57 // @varlet/release changelog options58 },59 },60})61```6263### Programmatic usage6465All CLI commands are also available as functions:6667```ts68import { clean, api, hook, release, changelog, commitLint, lockfileCheck } from 'rattail/cli'69```7071---7273## Core functions7475Import from `rattail`:7677```ts78import { isString, debounce, cloneDeep /* ... */ } from 'rattail'79```8081### General8283| Function | Description |84| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |85| [`isString`](references/isString.md) | Determine whether the input value is a `string`. |86| [`isNumber`](references/isNumber.md) | Determine whether the input value is a `number`. |87| [`isNumeric`](references/isNumeric.md) | Determine whether the input value is a `number` or a `numeric string`. |88| [`isBoolean`](references/isBoolean.md) | Determine whether the input value is a `boolean`. |89| [`isTruthy`](references/isTruthy.md) | Determine whether the input value is `truthy`. |90| [`isPrimitive`](references/isPrimitive.md) | Determine whether the input value is a `primitive`. |91| [`isPlainObject`](references/isPlainObject.md) | Determine whether the input value is a `plain object`. |92| [`isObject`](references/isObject.md) | Determine whether the input value is an `object` (excluding `null`). |93| [`isArray`](references/isArray.md) | Determine whether the input value is an `array`. |94| [`isNullish`](references/isNullish.md) | Determine whether the input value is `null` or `undefined`. |95| [`isPromise`](references/isPromise.md) | Determine whether the input value is a `Promise`. |96| [`isRegExp`](references/isRegExp.md) | Determine whether the input value is a `RegExp`. |97| [`isFunction`](references/isFunction.md) | Determine whether the input value is a `function`. |98| [`isDate`](references/isDate.md) | Determine whether the input value is a `Date`. |99| [`isSet`](references/isSet.md) | Determine whether the input value is a `Set`. |100| [`isMap`](references/isMap.md) | Determine whether the input value is a `Map`. |101| [`isSymbol`](references/isSymbol.md) | Determine whether the input value is a `symbol`. |102| [`isWeakMap`](references/isWeakMap.md) | Determine whether the input value is a `WeakMap`. |103| [`isWeakSet`](references/isWeakSet.md) | Determine whether the input value is a `WeakSet`. |104| [`isBlob`](references/isBlob.md) | Determine whether the input value is a `Blob`. |105| [`isFile`](references/isFile.md) | Determine whether the input value is a `File`. |106| [`isArrayBuffer`](references/isArrayBuffer.md) | Determine whether the input value is a `ArrayBuffer`. |107| [`isTypedArray`](references/isTypedArray.md) | Determine whether the input value is a `TypedArray`. |108| [`isDataView`](references/isDataView.md) | Determine whether the input value is a `DataView`. |109| [`isError`](references/isError.md) | Determine whether the input value is an `Error` object. |110| [`isDOMException`](references/isDOMException.md) | Determine whether the input value is a `DOMException` object. |111| [`isWindow`](references/isWindow.md) | Determine whether the input value is the global `window` object. |112| [`isEmpty`](references/isEmpty.md) | Determine whether the input value is empty (`undefined`, `null`, an `empty string`, or an `empty array`). |113| [`isEmptyPlainObject`](references/isEmptyPlainObject.md) | Determine whether the input value is a empty (no own enumerable keys and no symbols) plain object. |114| [`isNonEmptyArray`](references/isNonEmptyArray.md) | Determine whether the input value is a `non-empty array`. |115| [`isEqual`](references/isEqual.md) | Deeply compare two values. |116| [`isEqualWith`](references/isEqualWith.md) | Deeply compare two values. Supports passing a comparison method, and returns `true` if the two values are equal. |117| [`inBrowser`](references/inBrowser.md) | Determine whether the code is running in a `browser` environment. |118| [`inMobile`](references/inMobile.md) | Determine whether the code is running in a `mobile` browser environment. |119| [`hasOwn`](references/hasOwn.md) | Determine whether an `object` has a specific property as its own (not inherited). |120| [`hasDuplicates`](references/hasDuplicates.md) | Checks if an array contains duplicate values. |121| [`hasDuplicatesBy`](references/hasDuplicatesBy.md) | Checks if an array contains duplicate values based on a custom comparison function. |122| [`supportTouch`](references/supportTouch.md) | Determine whether the current environment supports `touch events`. |123| [`toTypeString`](references/toTypeString.md) | Return the `type string` of the input value. |124| [`toRawType`](references/toRawType.md) | Return the `raw type` of the input value. |125| [`getGlobalThis`](references/getGlobalThis.md) | Retrieve the global object based on the current environment. |126| [`assert`](references/assert.md) | Throws an error when the input value is not `true`, the second argument is the error message. |127128### Number129130| Function | Description |131| -------------------------------------------------- | --------------------------------------------------------------------------------------------- |132| [`toNumber`](references/toNumber.md) | Convert the input value to a `number`. If the value is `null` or `undefined`, it returns `0`. |133| [`genNumberKey`](references/genNumberKey.md) | Generate a unique numeric key, `incrementing` with each call. |134| [`randomNumber`](references/randomNumber.md) | Generate a random integer between `min` and `max`, inclusive. |135| [`clamp`](references/clamp.md) | Clamp a number within the inclusive `min` and `max` bounds. |136| [`clampArrayRange`](references/clampArrayRange.md) | Clamp an index within the bounds of an array's length. |137| [`times`](references/times.md) | Execute a function a specified number of times and return an array of results. |138| [`delay`](references/delay.md) | Create a promise that resolves after a specified time in milliseconds. |139140### String141142| Function | Description |143| -------------------------------------------- | --------------------------------------------------------------------------------------------- |144| [`randomString`](references/randomString.md) | Generate a random alphanumeric string of a specified length. |145| [`randomColor`](references/randomColor.md) | Generate a random hexadecimal color string. |146| [`genStringKey`](references/genStringKey.md) | Generate a unique `string` key by incrementing a numeric value and converting it to a string. |147| [`camelize`](references/camelize.md) | Convert a string to `camelCase`. |148| [`kebabCase`](references/kebabCase.md) | Convert a string to `kebab-case`. |149| [`pascalCase`](references/pascalCase.md) | Convert a string to `PascalCase`. |150| [`upperFirst`](references/upperFirst.md) | Capitalize the `first letter` of a `string`, leaving the rest unchanged. |151| [`lowerFirst`](references/lowerFirst.md) | Lowercase the `first letter` of the `string` and keep the rest unchanged. |152| [`slash`](references/slash.md) | Convert all backslashes (`\`) in a path to forward slashes (`/`). |153| [`ensurePrefix`](references/ensurePrefix.md) | Ensure that a prefix exists in the `string`, and add it if it does not exist. |154| [`ensureSuffix`](references/ensureSuffix.md) | Ensure that a suffix exists in the `string`, and add it if it does not exist. |155| [`maskString`](references/maskString.md) | Mask part of a string with a specified character, keeping prefix and suffix visible. |156157### Math158159| Function | Description |160| ---------------------------------- | ----------------------------------------------------------------------------------- |161| [`sum`](references/sum.md) | Calculates the sum of values in an `array` of numbers. |162| [`sumBy`](references/sumBy.md) | Calculates the sum of values in an `array` based on a provided function. |163| [`sumHash`](references/sumHash.md) | Calculate a hash sum for a given value. |164| [`minBy`](references/minBy.md) | Find the `minimum` value in an `array` based on a function applied to each element. |165| [`maxBy`](references/maxBy.md) | Find the maximum value in an array based on a function applied to each element. |166| [`mean`](references/mean.md) | Calculate the `mean` (average) of an `array` of `numbers`. |167| [`meanBy`](references/meanBy.md) | Calculate the mean (average) of an `array` by applying a function to each element. |168| [`sample`](references/sample.md) | Return a random element from an `array`. |169| [`round`](references/round.md) | Return number rounded to precision. |170| [`floor`](references/floor.md) | Return number rounded down to precision. |171| [`ceil`](references/ceil.md) | Return number rounded up to precision. |172173### Object174175| Function | Description |176| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |177| [`set`](references/set.md) | Set a value at a given path in an object, creating nested objects or arrays as needed. |178| [`pick`](references/pick.md) | Pick object properties and construct a new object. |179| [`pickBy`](references/pickBy.md) | Extract object properties by a predicate function and construct a new object. |180| [`omit`](references/omit.md) | Excludes object properties and constructs a new object. |181| [`omitBy`](references/omitBy.md) | Excludes object properties by a predicate function and constructs a new object. |182| [`deriveKey`](references/deriveKey.md) | Derive new object keys by a mapping while keeping the original keys. |183| [`mapObject`](references/mapObject.md) | Maps an object into a new object. |184| [`rekey`](references/rekey.md) | Rename object keys by a mapping and construct a new object. |185| [`objectKeys`](references/objectKeys.md) | Get an array of keys from an object, with full TypeScript type support. |186| [`objectEntries`](references/objectEntries.md) | Get an array of key-value pairs from an object, with full TypeScript type support. |187| [`promiseWithResolvers`](references/promiseWithResolvers.md) | Returns an object containing a new Promise and two functions to `resolve` or `reject` it. |188189### Array190191| Function | Description |192| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |193| [`at`](references/at.md) | Retrieves the element at a specified index in an `array`, supporting negative indices. |194| [`chunk`](references/chunk.md) | Chunking an `array`. The passed `size` indicates the length of the chunk. |195| [`uniq`](references/uniq.md) | Creates a duplicate-free version of an `array`, using the values equality. |196| [`uniqBy`](references/uniqBy.md) | Creates a duplicate-free version of an `array`, using a custom comparison function. |197| [`difference`](references/difference.md) | Creates an `array` of values not contained in other given arrays. |198| [`differenceWith`](references/differenceWith.md) | Creates an `array` of values not contained in other given arrays, with custom comparison. |199| [`intersection`](references/intersection.md) | Creates an `array` of unique values contained in all given arrays. |200| [`intersectionWith`](references/intersectionWith.md) | Creates an `array` of unique values contained in all given arrays, with custom comparison. |201| [`xor`](references/xor.md) | XOR (Exclusive OR) the passed array and return a new `array`. |202| [`xorWith`](references/xorWith.md) | XOR (Exclusive OR) the passed array with custom comparison. |203| [`groupBy`](references/groupBy.md) | Group the elements in a given `array` by a function's return value as the key. |204| [`find`](references/find.md) | Finds the `first` or `last` element in an array that meets a condition, returning the element and its index. |205| [`shuffle`](references/shuffle.md) | Randomly shuffles elements within an `array`. |206| [`removeItem`](references/removeItem.md) | Removes the first occurrence of a specific item from an `array`. |207| [`removeItemBy`](references/removeItemBy.md) | Removes the first item matching a predicate, mutating the original array. |208| [`removeItemsBy`](references/removeItemsBy.md) | Removes all items matching a predicate, mutating the original array. |209| [`toggleItem`](references/toggleItem.md) | Adds or removes an item from an `array`, based on its existence. |210| [`removeArrayBlank`](references/removeArrayBlank.md) | Removes `null` or `undefined` values from an `array`. |211| [`removeArrayEmpty`](references/removeArrayEmpty.md) | Removes `null`, `undefined`, or empty string (`''`) values from an `array`. |212| [`normalizeToArray`](references/normalizeToArray.md) | Converts a value to an `array` if it is not already an array. |213214### Collection215216| Function | Description |217| ---------------------------------------------- | ----------------------------------------------------------------------- |218| [`cloneDeep`](references/cloneDeep.md) | Create a deep clone of a value. |219| [`cloneDeepWith`](references/cloneDeepWith.md) | Create a deep clone of a value, applying a custom function for cloning. |220| [`merge`](references/merge.md) | Merge two objects recursively. |221| [`mergeWith`](references/mergeWith.md) | Merge two objects recursively, with custom merge logic. |222223### Function224225| Function | Description |226| -------------------------------------------- | ---------------------------------------------------------------------------------------- |227| [`NOOP`](references/NOOP.md) | This method returns `undefined`. |228| [`call`](references/call.md) | Call a single function or multiple functions and pass arguments to them. |229| [`callOrReturn`](references/callOrReturn.md) | Calls a function with args if input is a function, otherwise returns the input directly. |230| [`once`](references/once.md) | Creates a function that will only execute once. |231| [`debounce`](references/debounce.md) | Create a `debounce` function that delays execution by `delay` ms after the last call. |232| [`throttle`](references/throttle.md) | Create a throttle function that calls `fn` at most once every `delay` ms. |233| [`tryCall`](references/tryCall.md) | Safely call a function and return an `[error, result]` tuple. |234| [`tryAsyncCall`](references/tryAsyncCall.md) | Safely call an async function and return a `Promise<[error, result]>` tuple. |235236### File237238| Function | Description |239| ---------------------------------------------- | ---------------------------------------------- |240| [`toText`](references/toText.md) | Converts a `File` object to a text string. |241| [`toDataURL`](references/toDataURL.md) | Converts a `File` object to a Data URL string. |242| [`toArrayBuffer`](references/toArrayBuffer.md) | Converts a `File` object to an `ArrayBuffer`. |243244### Util245246| Function | Description |247| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |248| [`motion`](references/motion.md) | Used to implement basic transition animation based on `requestAnimationFrame`. |249| [`copyText`](references/copyText.md) | Copies text to the clipboard. |250| [`download`](references/download.md) | Trigger browser download, supporting downloading via file `url`, `Blob`, `File`. |251| [`duration`](references/duration.md) | Creates a fluent duration builder that allows chaining time units to calculate total milliseconds or seconds. |252| [`enumOf`](references/enumOf.md) | Enum utility with TS-friendly types. Built-in fields: `value`, `label`, `description`. |253| [`storage`](references/storage.md) | Enhance `localStorage` and `sessionStorage`, support automatic JSON `stringify` and `parse`. |254| [`classes`](references/classes.md) | Generates a list of class names based on a given condition. |255| [`createNamespaceFn`](references/createNamespaceFn.md) | Creates a namespace function for BEM-style naming. |256| [`createCacheManager`](references/createCacheManager.md) | Creates a simple in-memory cache manager with optional TTL support. |257| [`raf`](references/raf.md) | Creates a Promise-based `requestAnimationFrame` that resolves on the next frame. |258| [`doubleRaf`](references/doubleRaf.md) | Creates a Promise-based double `requestAnimationFrame` that resolves after two frames. |259| [`requestAnimationFrame`](references/requestAnimationFrame.md) | Provides a cross-browser compatible `requestAnimationFrame` function. |260| [`cancelAnimationFrame`](references/cancelAnimationFrame.md) | Cancels a `requestAnimationFrame` request, with a fallback to `clearTimeout`. |261| [`inViewport`](references/inViewport.md) | Determines if an element is visible within the viewport. |262| [`preventDefault`](references/preventDefault.md) | Prevents the default action of an event if it is cancelable. |263| [`getStyle`](references/getStyle.md) | Retrieves computed CSS styles for a given DOM element. |264| [`getRect`](references/getRect.md) | Gets the dimensions and position of an element or window as a `DOMRect` object. |265| [`getScrollTop`](references/getScrollTop.md) | Gets the vertical scroll position of an element or window. |266| [`getScrollLeft`](references/getScrollLeft.md) | Gets the horizontal scroll position of an element or window. |267| [`getParentScroller`](references/getParentScroller.md) | Finds the closest scrollable ancestor of an element. |268| [`getAllParentScroller`](references/getAllParentScroller.md) | Retrieves all scrollable ancestor elements of an element. |269| [`prettyJSONObject`](references/prettyJSONObject.md) | Formats a `JSON` object with indentation for easy readability. |270| [`tryParseJSON`](references/tryParseJSON.md) | Attempts to parse a `JSON` string. If parsing fails, returns `undefined`. |271| [`navigation`](references/navigation.md) | Browser-level navigation API for real page jumps. |272273### Integrated274275| Function | Description |276| ---------------------------- | ---------------------------------------------------------------------------------- |277| [`mitt`](references/mitt.md) | Event emitter / pubsub. Integrated with [mitt](https://github.com/developit/mitt). |278| [`uuid`](references/uuid.md) | UUID generation helpers integrated with [uuid](https://github.com/uuidjs/uuid). |279280---281282## First-party integration: Axle (`rattail/axle`)283284Progressive HTTP request layer on top of **axios** for **Vue 3** (and plain JS for the core client), re-exported as a first-party integration. Three entry points:285286| Entry | Import | Purpose |287| ----------- | ------------------ | ------------------------------------------------------------------- |288| Core | `rattail/axle` | `createAxle`, types, `createMatcher`, helpers, interceptors |289| Vue | `rattail/axle/use` | `createUseAxle`, `useValues`, `useHasLoading`, `useAverageProgress` |290| API builder | `rattail/axle/api` | `createApi` — URL-bound `load` / `use` helpers |291292**Upstream:** [`@varlet/axle`](https://github.com/varletjs/axle) · [README](https://github.com/varletjs/axle/blob/main/packages/axle/README.md) · [Chinese README](https://github.com/varletjs/axle/blob/main/packages/axle/README.zh-CN.md)293294**IMPORTANT:** Open [`references/axle/<topic>.md`](references/axle/core-client.md) for detailed API docs, type declarations, and usage examples.295296### Quick start297298```ts299import { createAxle } from 'rattail/axle'300301const axle = createAxle(/* axios create config */)302axle.get('/url', { current: 1, pageSize: 10 }, { headers: {} })303```304305### Topic references306307| Topic | Reference |308| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |309| `createAxle`, `AxleInstance`, shared `axios`, headers, runner overview | [references/axle/core-client.md](references/axle/core-client.md) |310| GET/POST/… runners (`getBlob`, `postUrlEncode`, …) | [references/axle/request-runners.md](references/axle/request-runners.md) |311| `createUseAxle` and composables | [references/axle/vue-composition.md](references/axle/vue-composition.md) |312| `createApi` (`load`, `use`, path params) | [references/axle/api-factory.md](references/axle/api-factory.md) |313| `matchPattern`, `createMatcher`, interceptors | [references/axle/interceptors-and-matcher.md](references/axle/interceptors-and-matcher.md) |314| `withResponse`, `download` | [references/axle/helpers.md](references/axle/helpers.md) |315316Peer dependency: **`vue` ^3.2** when using `rattail/axle/use` or `rattail/axle/api`.317318---319320## First-party integration: Ruler Factory (`rattail/ruler-factory`)321322Flexible chainable validation rule factory for TypeScript/JavaScript, re-exported as a first-party integration. Supports UI form integration with Varlet, Vant, Naive UI, Element Plus.323324```ts325import { rulerFactory } from 'rattail/ruler-factory'326```327328**Upstream:** [`ruler-factory`](https://github.com/varletjs/ruler-factory) · [README](https://github.com/varletjs/ruler-factory/blob/main/README.md) · [Chinese README](https://github.com/varletjs/ruler-factory/blob/main/README.zh-CN.md)329330**IMPORTANT:** Before chaining rules, read the reference for `rulerFactory` and your UI's `generator` pattern, then open the specific [`references/ruler-factory/<name>.md`](references/ruler-factory/rulerFactory.md) for the method or type you use.331332### Quick start333334```ts335import { rulerFactory } from 'rattail/ruler-factory'336337const r = rulerFactory((validator) => {338 return (value) => {339 const e = validator(value)340 return e ? e.message : true341 }342})343344r().string('Not a string').required('Required').min(2, 'Too short').done()345```346347### API index348349#### Package350351| Symbol | Description |352| ---------------------------------------------------------- | -------------------------------------------------------------- |353| [`rulerFactory`](references/ruler-factory/rulerFactory.md) | Factory that builds a chainable ruler for your UI rule format. |354355#### Exported types356357| Symbol | Description |358| ---------------------------------------------------------------------------- | ----------------------------------------------- |359| [`RulerFactoryMessage`](references/ruler-factory/RulerFactoryMessage.md) | String or lazy string for error messages. |360| [`RulerFactoryValidator`](references/ruler-factory/RulerFactoryValidator.md) | Validator fn: value in, Error or undefined out. |361| [`RulerFactoryGenerator`](references/ruler-factory/RulerFactoryGenerator.md) | Maps validator + params to rule type R. |362| [`RulerContext`](references/ruler-factory/RulerContext.md) | Chainable context type (methods + extend). |363364#### Type guards365366| Symbol | Description |367| ---------------------------------------------------- | -------------------------------------- |368| [`string`](references/ruler-factory/string.md) | Assert string type (optional message). |369| [`number`](references/ruler-factory/number.md) | Assert number type. |370| [`array`](references/ruler-factory/array.md) | Assert array type. |371| [`boolean`](references/ruler-factory/boolean.md) | Assert boolean type. |372| [`object`](references/ruler-factory/object.md) | Assert plain object type. |373| [`symbol`](references/ruler-factory/symbol.md) | Assert symbol type. |374| [`bigint`](references/ruler-factory/bigint.md) | Assert bigint type. |375| [`null`](references/ruler-factory/null.md) | Assert value is null. |376| [`undefined`](references/ruler-factory/undefined.md) | Assert value is undefined. |377| [`true`](references/ruler-factory/true.md) | Assert value is true. |378| [`false`](references/ruler-factory/false.md) | Assert value is false. |379380#### Validators381382| Symbol | Description |383| ------------------------------------------------------ | ------------------------------------------- |384| [`required`](references/ruler-factory/required.md) | Reject empty values (rattail isEmpty). |385| [`min`](references/ruler-factory/min.md) | Min length / numeric min depending on type. |386| [`max`](references/ruler-factory/max.md) | Max length / numeric max depending on type. |387| [`length`](references/ruler-factory/length.md) | Exact length for string or array. |388| [`regex`](references/ruler-factory/regex.md) | String matches RegExp. |389| [`startsWith`](references/ruler-factory/startsWith.md) | String starts with prefix. |390| [`endsWith`](references/ruler-factory/endsWith.md) | String ends with suffix. |391| [`includes`](references/ruler-factory/includes.md) | Substring or array includes value. |392| [`uppercase`](references/ruler-factory/uppercase.md) | String is all uppercase. |393| [`lowercase`](references/ruler-factory/lowercase.md) | String is all lowercase. |394| [`email`](references/ruler-factory/email.md) | String looks like an email. |395| [`gt`](references/ruler-factory/gt.md) | Number/bigint greater than. |396| [`gte`](references/ruler-factory/gte.md) | Number/bigint greater or equal. |397| [`lt`](references/ruler-factory/lt.md) | Number/bigint less than. |398| [`lte`](references/ruler-factory/lte.md) | Number/bigint less or equal. |399| [`positive`](references/ruler-factory/positive.md) | Number/bigint > 0. |400| [`negative`](references/ruler-factory/negative.md) | Number/bigint < 0. |401| [`uniq`](references/ruler-factory/uniq.md) | Array has no duplicates. |402| [`uniqBy`](references/ruler-factory/uniqBy.md) | Array unique by comparator. |403404#### Predicates405406| Symbol | Description |407| ---------------------------------------- | --------------------------- |408| [`is`](references/ruler-factory/is.md) | Custom predicate must pass. |409| [`not`](references/ruler-factory/not.md) | Custom predicate must fail. |410411#### Finish412413| Symbol | Description |414| ------------------------------------------ | ------------------------- |415| [`done`](references/ruler-factory/done.md) | Return built rules array. |416417#### Custom418419| Symbol | Description |420| ------------------------------------------------------ | ------------------------------- |421| [`addRule`](references/ruler-factory/addRule.md) | Append custom validator. |422| [`getMessage`](references/ruler-factory/getMessage.md) | Resolve message string/lazy fn. |423424#### Transform425426| Symbol | Description |427| -------------------------------------------------------- | ------------------------------------------- |428| [`trim`](references/ruler-factory/trim.md) | Trim strings before validation. |429| [`toLowerCase`](references/ruler-factory/toLowerCase.md) | Lowercase strings before validation. |430| [`toUpperCase`](references/ruler-factory/toUpperCase.md) | Uppercase strings before validation. |431| [`transform`](references/ruler-factory/transform.md) | Replace transformer with custom fn. |432| [`transformer`](references/ruler-factory/transformer.md) | Current transform pipeline (internal hook). |433434---435436437438…(truncated)