String API
decodeURIComponentRepeatedly Decode
Repeatedly decodes a URI component until stable or the depth limit is reached.
Signature
export function decodeURIComponentRepeatedly(value: string, maxDepth = 10): string;Example
import { decodeURIComponentRepeatedly } from "@fast-china/utils";
const result = decodeURIComponentRepeatedly("Fast 文档", 10);Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Encoded component without URI path semantics. |
maxDepth | unknown | Optional; defaults to 10 | Maximum decoding passes; defaults to 10. |
Returns
| Value | Type | Description |
|---|---|---|
result | string | Component text after stabilization or the limit. |
parseQueryString Parse
Parses an absolute URL containing ://, a ?query, or a bare query string.
Signature
export function parseQueryString(input: string): ParsedQueryParameters;Example
import { parseQueryString } from "@fast-china/utils";
const result = parseQueryString("?page=1&tag=vue&tag=tsx");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
input | string | Required | Full URL or query text with or without a leading question mark. |
Returns
| Value | Type | Description |
|---|---|---|
result | ParsedQueryParameters | Repeated keys become string arrays; empty values remain empty strings. |
Errors and encoding boundaries
parseQueryString converts + to a space before native decodeURIComponent. Malformed percent encoding or invalid UTF-8 throws URIError instead of replacement with U+FFFD. Repeated keys, empty values, and ordinary own __proto__ properties retain their behavior. Raw unescaped lone surrogates are preserved according to native decoding semantics.
isValidJson Validate
Checks for any valid JSON value, including scalars and null.
Signature
export function isValidJson(value: string): boolean;Example
import { isValidJson } from "@fast-china/utils";
const result = isValidJson(`{"name":"Fast"}`);
console.log(result); // trueInput
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Text to parse; whitespace alone is not JSON. |
Returns
| Value | Type | Description |
|---|---|---|
result | boolean | true when JSON.parse can parse the entire input. |
splitWords Words
Splits words at case boundaries, hyphens, underscores, and whitespace.
Signature
export function splitWords(value: string): string[];Example
import { splitWords } from "@fast-china/utils";
const result = splitWords("Fast 文档");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Text to split. |
Returns
| Value | Type | Description |
|---|---|---|
result | string[] | Word array preserving input order with empty entries removed. |
upperFirst Case
Uppercases the first Unicode code point.
Signature
export function upperFirst(value: string, locale?: StringLocale): string;Example
import { upperFirst } from "@fast-china/utils";
const result = upperFirst("Fast 文档", "zh-CN");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Input text; empty strings remain empty. |
locale | StringLocale | Optional | Explicit locale; omitted locales use standard Unicode casing. |
Returns
| Value | Type | Description |
|---|---|---|
result | string | Text after converting the first Unicode code point. |
lowerFirst Case
Lowercases the first Unicode code point.
Signature
export function lowerFirst(value: string, locale?: StringLocale): string;Example
import { lowerFirst } from "@fast-china/utils";
const result = lowerFirst("Fast 文档", "zh-CN");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Input text; empty strings remain empty. |
locale | StringLocale | Optional | Explicit locale; omitted locales use standard Unicode casing. |
Returns
| Value | Type | Description |
|---|---|---|
result | string | Text after converting the first Unicode code point. |
camelCase Camel
Converts text to camelCase.
Signature
export function camelCase(value: string, locale?: StringLocale): string;Example
import { camelCase } from "@fast-china/utils";
const result = camelCase("Fast 文档", "zh-CN");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Text separated by case boundaries, hyphens, underscores, or whitespace. |
locale | StringLocale | Optional | Case-conversion locale; omitted locales use standard Unicode casing. |
Returns
| Value | Type | Description |
|---|---|---|
result | string | camelCase text. |
pascalCase Pascal
Converts text to PascalCase.
Signature
export function pascalCase(value: string, locale?: StringLocale): string;Example
import { pascalCase } from "@fast-china/utils";
const result = pascalCase("Fast 文档", "zh-CN");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Uses the same argument semantics as the related case-conversion function. |
locale | StringLocale | Optional | Explicit locale for case conversion. |
Returns
| Value | Type | Description |
|---|---|---|
result | string | PascalCase text. |
kebabCase Kebab
Converts text to kebab-case.
Signature
export function kebabCase(value: string, locale?: StringLocale): string;Example
import { kebabCase } from "@fast-china/utils";
const result = kebabCase("Fast 文档", "zh-CN");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Uses the same argument semantics as the related case-conversion function. |
locale | StringLocale | Optional | Explicit locale for case conversion. |
Returns
| Value | Type | Description |
|---|---|---|
result | string | kebab-case text. |
truncateGraphemes Truncate
Truncates by Unicode grapheme clusters without splitting emoji, combining marks, or surrogate pairs.
Signature
export function truncateGraphemes(value: string, maxLength: number, suffix = "…", locale?: StringLocale): string;Example
import { truncateGraphemes } from "@fast-china/utils";
const result = truncateGraphemes("Fast 文档", 4, "…", "zh-CN");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Input text. |
maxLength | number | Required | Maximum grapheme clusters to retain. |
suffix | unknown | Optional; defaults to "…" | Suffix appended on truncation; defaults to … and does not count toward the limit. |
locale | StringLocale | Optional | Grapheme segmentation locale; fixed default en-US. |
Returns
| Value | Type | Description |
|---|---|---|
result | string | Original string when within the limit, otherwise truncated content plus suffix. |
copy Copy
Copies text to the system clipboard.
Signature
export async function copy(value: string): Promise<void>;Example
import { copy } from "@fast-china/utils";
const result = await copy("Fast 文档");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Text to copy. |
Returns
| Value | Type | Description |
|---|---|---|
result | Promise<void> | Promise fulfilled after copying completes. |
randomString Random
Generates a random string.
Signature
export function randomString(length: number, alphabet: string = defaultRandomAlphabet): string;Example
import { randomString } from "@fast-china/utils";
const result = randomString(16, "ABCDEFGHJKLMNPQRSTUVWXYZ23456789");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
length | number | Required | Character count; a safe integer from 0 to 1,000,000. |
alphabet | string | Optional; defaults to defaultRandomAlphabet | Must be nonempty, contain no duplicate characters, and have at most 2^32 Unicode code points. |
Returns
| Value | Type | Description |
|---|---|---|
result | string | Random text composed of Unicode code points from alphabet. |
generateUuidV4 UUID
Generates an RFC 4122 version 4 UUID.
Signature
export function generateUuidV4(): string;Example
import { generateUuidV4 } from "@fast-china/utils";
const result = generateUuidV4();Input
This method has no input parameters.
Returns
| Value | Type | Description |
|---|---|---|
result | string | Lowercase hyphenated UUID v4. |
isUuidV4 UUID
Checks for an RFC 4122 version 4 UUID.
Signature
export function isUuidV4(value: string): boolean;Example
import { isUuidV4 } from "@fast-china/utils";
const result = isUuidV4("550e8400-e29b-41d4-a716-446655440000");
console.log(result); // trueInput
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Text to validate; hexadecimal letters are case-insensitive. |
Returns
| Value | Type | Description |
|---|---|---|
result | boolean | true when version and variant bits are correct. |
escapeHtml Escape
Escapes five special characters in HTML text context.
Signature
export function escapeHtml(value: string): string;Example
import { escapeHtml } from "@fast-china/utils";
const result = escapeHtml("Fast 文档");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | String intended as HTML text-node content. |
Returns
| Value | Type | Description |
|---|---|---|
result | string | Text with &, <, >, double quotes, and single quotes escaped. |
normalizeWhitespace Whitespace
Collapses Unicode whitespace runs to one space and trims both ends.
Signature
export function normalizeWhitespace(value: string): string;Example
import { normalizeWhitespace } from "@fast-china/utils";
const result = normalizeWhitespace("Fast 文档");Input
| Input | Type | Required / default | Description |
|---|---|---|---|
value | string | Required | Input text. |
Returns
| Value | Type | Description |
|---|---|---|
result | string | Normalized text; all-whitespace input becomes an empty string. |
