---
title: "Text"
description: "Text and date utilities — UUID v4 / v7, encode / decode HTML entities, type conversions, case helpers, Luxon-backed `toDateTime` / `toB24Format`, number formatting, and query-string builder."
canonical_url: "https://bitrix24.github.io/b24jssdk/docs/working-with-the-rest-api/tools-text"
last_updated: "2026-07-01"
---
# Text

> Text and date utilities — UUID v4 / v7, encode / decode HTML entities, type conversions, case helpers, Luxon-backed `toDateTime` / `toB24Format`, number formatting, and query-string builder.

## Overview

`Text`{className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style=""} is a singleton (`new TextManager()`) exported from `@bitrix24/b24jssdk`. It bundles the small text- and date-related helpers the SDK relies on internally and exposes them for application code:

- **Identifiers** — random strings, a locally-generated UUID v4, and a time-ordered UUID v7 (the SDK's default request id).
- **HTML entity encoding** — `encode` / `decode` in the legacy Bitrix Framework style.
- **Type conversion** — coerce arbitrary values to numbers, integers, and booleans.
- **Case helpers** — `camelCase`, `PascalCase`, `kebab-case`, and `capitalize`.
- **Number formatting** — grouped thousands with a fixed number of decimals.
- **Date helpers** — [Luxon](https://moment.github.io/luxon/){rel="[\"nofollow\"]"}-backed parsing and the `yyyy-MM-dd'T'HH:mm:ssZZ` format Bitrix24 expects in REST payloads.
- **Query strings** — build an `application/x-www-form-urlencoded` string from a plain object.

```ts
import { Text } from '@bitrix24/b24jssdk'

console.log(Text.getUuidRfc4122())          // '019323ac-8ace-725b-a3dc-6a7c333da066'
console.log(Text.getDateForLog())           // '2026-05-04 09:53:51'
console.log(Text.numberFormat(1234.567, 2)) // '1,234.57'
```

## Method Signature

### Identifiers

```ts-type
getRandom(length?: number): string          // random [a-z0-9], default length 8
getUniqId(): string                          // UUID v4 (best-effort, local)
getUuidRfc4122(): string                     // UUID v7 (time-ordered) — SDK default request id
```

### Entity encoding

```ts-type
encode(value: string): string                // & < > ' "  → entity codes (no trailing ;)
decode(value: string): string                // inverse of encode, also numeric entities
```

### Type conversion

```ts-type
toNumber(value: any): number                 // 0 on parse failure
toInteger(value: any): number                // toNumber(parseInt(value, 10))
toBoolean(value: any, trueValues?: string[]): boolean // 'true'/'y'/'1'/1/true → true
```

### Case helpers

```ts-type
toCamelCase(str: string): string
toPascalCase(str: string): string            // capitalize(toCamelCase(str))
toKebabCase(str: string): string
capitalize(str: string): string
```

### Number formatting

```ts-type
numberFormat(
  number: number,
  decimals?: number,        // default 0
  decPoint?: string,        // default '.'
  thousandsSep?: string     // default ','
): string
```

### Date helpers (Luxon)

```ts-type
toDateTime(dateString: string, template?: string, opts?: DateTimeOptions): DateTime
toB24Format(date: string | Date | DateTime): string   // yyyy-MM-dd'T'HH:mm:ssZZ
getDateForLog(): string                                // 'yyyy-MM-dd HH:mm:ss'
```

### Query string

```ts-type
buildQueryString(params: any): string        // application/x-www-form-urlencoded, no leading '?'
```

## Key Concepts

> [!NOTE]
> `encode` / `decode` deliberately omit the trailing `;` (e.g. `&amp` instead of `&amp;`). This matches the legacy Bitrix Framework behaviour. `decode` reverses that output and also recognises the numeric entities (`&#38`, `&#60`, …). Because the tokens carry no `;`, a trailing `;` in the input is left in place (`&amp;` → `&;`).

> [!CAUTION]
> `encode` is **not** a general-purpose HTML sanitizer. It only escapes `&`, `<`, `>`, `'`, and `"` and is not context-aware — it will not stop attribute-breakout, `javascript:` URLs, or markup outside those five characters. Do not use it as the sole XSS defence for untrusted input rendered as HTML.

- **`getRandom` / `getUniqId` are not cryptographically secure.** Both are built from `Math.random()` — use them for cache-busting keys and disposable ids, never for tokens or secrets.
- **`toCamelCase` separators.** `-`, `_`, and whitespace are treated as word boundaries; a fully uppercase input is lowercased (`'ABC'` → `'abc'`).
- **`toKebabCase` splits on case boundaries.** `getUserId` → `get-user-id` and `XMLHttpRequest` → `xml-http-request`, so `camelCase` and mixed-case acronyms are handled. One edge: an uppercase run directly followed by a digit is split letter-by-letter (`parseHTML5` → `parse-h-t-m-l-5`).
- **`numberFormat` matches the server.** Non-finite values become `0`, the fractional part is rounded to `decimals` places, and the thousands separator is inserted every three digits left of the decimal point.
- **`toDateTime` returns a `DateTime` even for invalid input.** When `template` is provided it uses `DateTime.fromFormat`, otherwise `DateTime.fromISO`. Check `result.isValid` before use.
- **`toB24Format` passes strings through unchanged** (assumed already formatted); a JS `Date` is normalised through Luxon first.

## Error Handling

The `Text` helpers do not throw for unexpected input — they degrade gracefully: `toNumber` / `toInteger` return `0`, `toBoolean` returns `false`, `buildQueryString(null)` returns `''`, and `encode` / `decode` return non-string values untouched. `toDateTime` never throws either — it returns a `DateTime` whose `isValid` flag is `false` for unparseable input, so check `result.isValid` before using the value.

## Examples

Identifiers and request ids:

```ts
import { Text } from '@bitrix24/b24jssdk'

Text.getRandom()          // 'a7f3k1z9'
Text.getRandom(4)         // 'p2x8'
Text.getUniqId()          // 'd2b8a1f0-3c4e-4a9b-8f7c-1e2d3a4b5c6d'  (UUID v4)
Text.getUuidRfc4122()     // '019323ac-8ace-725b-a3dc-6a7c333da066'  (UUID v7)
```

Encoding and type conversion:

```ts
import { Text } from '@bitrix24/b24jssdk'

Text.encode('<b>Tom & Jerry</b>') // '&ltb&gtTom &amp Jerry&lt/b&gt'
Text.decode('&ltb&gtTom &amp Jerry&lt/b&gt') // '<b>Tom & Jerry</b>'

Text.toNumber('12.5')     // 12.5
Text.toInteger('42.9')    // 42
Text.toBoolean('Y')       // true
Text.toBoolean('on', ['on']) // true
```

Case helpers and number formatting:

```ts
import { Text } from '@bitrix24/b24jssdk'

Text.toCamelCase('get_user_id')  // 'getUserId'
Text.toPascalCase('get_user_id') // 'GetUserId'
Text.toKebabCase('getUserId')    // 'get-user-id'
Text.capitalize('hello')         // 'Hello'

Text.numberFormat(1234.567, 2)           // '1,234.57'
Text.numberFormat(1234.567, 2, ',', ' ') // '1 234,57'
```

Dates and query strings:

```ts
import { Text } from '@bitrix24/b24jssdk'

// Format a date for a REST payload
Text.toB24Format(new Date()) // '2026-05-04T09:53:51+03:00'

// Parse an ISO string or a custom template
const dt = Text.toDateTime('04.05.2026', 'dd.MM.yyyy')
if (dt.isValid) {
  console.log(dt.toISODate()) // '2026-05-04'
}

// Build a query string (leading '?' is not included)
Text.buildQueryString({ id: 7, tag: ['a', 'b'] })
// 'id=7&tag%5B0%5D=a&tag%5B1%5D=b'
```

## Alternatives and Recommendations

- **Prefer `getUuidRfc4122()` over `getUniqId()`.** The v7 identifier is time-ordered and RFC 4122-compliant, which is why the SDK uses it as the default request id. Reach for `getUniqId()` (UUID v4) only when you specifically need a random, non-sortable id, and for neither when you need cryptographic randomness.
- **Use `toB24Format` for every date you send to the REST API.** Passing a raw `Date` or ISO string with the wrong offset is the most common cause of filter mismatches — see [Filtering](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/filtering.md) for date-range filter examples.
- **Runtime type checks live in [`Type`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/tools-type.md).** `Text` focuses on transformation; use `Type`'s guards (`isStringFilled`, `isArrayFilled`, …) when you need to branch on a value's shape first.
- **Locale-aware currency / IBAN formatting lives in [`useFormatter`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/tools-use-formatters.md).** `numberFormat` is a lightweight thousands-and-decimals helper; for currency, percent, or IBAN output use the dedicated formatters.
- **Work with Luxon directly for anything richer than parsing.** `toDateTime` is a thin wrapper over `DateTime.fromISO` / `DateTime.fromFormat`; for arithmetic, zones, and durations import `DateTime` from `luxon` and operate on the returned value.

## Sitemap

See the full [sitemap](/b24jssdk/sitemap.md) for all pages.