Text

Overview

Text 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-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.

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

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

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

Type conversion

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

toCamelCase(str: string): string
toPascalCase(str: string): string            // capitalize(toCamelCase(str))
toKebabCase(str: string): string
capitalize(str: string): string

Number formatting

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

Date helpers (Luxon)

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

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

Key Concepts

• 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:

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:

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:

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:

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 for date-range filter examples.
• Runtime type checks live in Type. 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. 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.