@gravity-ui/unipika

中文文档
5.6.5发布于 2026/09/23MITCommonJS零依赖近 30 天下载 9536

Common YT/YQL data formatting library

原始使用文档
文档目录6 节
  1. format(data[, settings[, converter]])
  2. List of supported types:
  3. Formatter settings:
  4. formatFromYSON(data[, settings])
  5. formatFromYQL(data[, settings])
  6. Features of Working with Dates:

unipika

Common YT/YQL/QC data formatting library.

format(data[, settings[, converter]])

Function accepts data in Unipika-YSON format (hereinafter referred to as the - Unipika), or, if converter is presented, in any other format and formats data according to its type. Currently two built-in converters are presented:

  • YSON to Unipikа
  • YQL to Unipika

List of supported types:

Source formatTypes
YSONstring, number, int64, uint64, double, map, list, null
YQLyql.string, yql.int64, yql.uint64, yql.double, yql.struct, yql.dict, yql.list, yql.tuple, yql.null, yql.yson, yql.pg.* - PostgreSQL Data Types in YQL are being formatted as string

Similar in meaning types are displayed similarly. For example, int64 and yql.int64, map and yql.struct, etc.

It is assumed that types can't be mixed in arbitrary way, that is, for example, list can't have elements of type yql.string, nevertheless, library doesn't attempt to fix invalid data in this case. When using built-in converter this situation shouldn't happen. Also, for example, only YSON types can have attributes, for the rest of types special field $attributes is pointless.

Formatter settings:

NameTypeDefault valueDescription
normalizeUrl(url: string) => string(url) => new URL(url).toString()Optional pararmeter that allows to override default behavior of utils.normalizeUrl. Default implementation uses encodeURI(url) and returns empty string if the call throws an exception. The result of call settings.normalizeUrl(url) injects to DOM tree "as is" as value of href-attributes, so you have to sanitize returned value to prevent XSS.
validateSrcUrl(url: string) => boolean() => falseFunction, which accepts source url for TaggedType types and returns whether it is allowed to be downloaded. If settings in not defined, TaggedType types (images, audio, video) will be formatted as StructType
formatString'json'[YSON-specific] Affects displaying YSON types. Serialization to text yson or json is supported. These ways of representation are described in YT documentation.
decodeUTF8Booleantrue[YSON-Converter][YSON-specific] Setting is passed to the converter (YSON to Unipikа). Indicated whether to try decode the data. The data received from YT with the setting { encode_utf8 = false } should not be decoded (also is means that all strings are valid UTF-8 sequences, that is, they are not binary). By default the data from YT is received with the setting { encode_utf8 = true } and should be decoded; strings that cannot be decoded are marked as binary.
showDecodedBooleantrue[NCP][YSON-specific] Indicates whether the decoded data should be displayed or the data in the form in which it is received from YT.
binaryAsHexBooleantrue[NCP][YSON-specific] Indicates whether binary strings should be displayed as a sequence of HEX-digits.
asHTMLBooleantrueReturn serialized data in plain text or html.
breakBooleantruePut hyphens and indents or return everything as a single line.
indentNumber4Indent size.
compactBooleanfalseThe mode in which complex types like map, list, yql.struct and so on, are displayed more compact if contain only one element.
highlightControlCharacterBooleanfalseEnables highlighting of special control characters in html strings.
escapeWhitespaceBooleantrue[NCP]The mode in which hyphens and tab characters are not escaped. With this option it is convenient to view formatted data like stack-traces.
escapeYQLStringsBooleantrue[NCP][YQL-Converter]The mode in which no symbols are escaped at all, so that user can get "raw" data.
nonBreakingIndentBooleantrueThe mode in which indents, spaces in key-value separator, and spaces in string binary representation are nonbreaking (   symbol).
omitStructNullBooleanfalse[YQL-Converter] Indicates whether to skip keys with null value in yql.struct type.
maxListSizeNumberundefined[YQL-Converter] Maximum allowed size of list nodes (yql.list, yql.dict, yql.struct, yql.tuple, yql.stream). If value > 0 is set, node will be truncated to this value.
maxStringSizeNumberundefined[YQL-Converter] Maximum allowed size of strings (yql.string, yql.utf8). If value > 0 is set, string will be truncated to this value.
limitMapLengthNumberundefinedMaximum allowed size of all map nodes. If value > 0 is set, node will be truncated to this (value - 1).
limitListLengthNumberundefinedMaximum allowed size of all list nodes. If value > 0 is set, node will be truncated to this (value - 1).
treatValAsDataBooleanfalseIf val is among data fields, it may be treated two ways: as normal object key (if treatValAsData is not set or is set to false) or it's value will be set as overall $value (if treatValAsData is set to true). In most cases this setting should not be set.

[YQL-Converter] - Options affects only data conversion from YQL format. [YSON-Converter] - Options affects only data conversion from YSON format. [YSON-Specific] - Options affects only YSON types representation and should not affect other types representation. [NCP] - (Non copy-pastable) this representation is used to improve readability, but is not valid; copying and using such data may cause an error.

formatFromYSON(data[, settings])

Format function wrapper, data is passed in YSON format, YSON to Unipika converter is used.

formatFromYQL(data[, settings])

Format function wrapper, data is passed in YQL format (in the list [data, dataType]), YQL to Unipika converter is used.

Features of Working with Dates:

  1. All dates are converted to the Gregorian calendar.
  2. According to the Gregorian calendar, the first year AD is denoted as: 01-01-01T00:00:00.000000Z. If you subtract 1 microsecond from this date, you get the date -01-12-31T23:59:59.999999Z (the first year BC).
  3. To determine if a negative year is a leap year in the Gregorian calendar, first add 1 to the year, and then apply the usual leap year rules. Thus, the year -1 is a leap year (since -1 + 1 = 0, and 0 % 4 = 0, so it is a leap year).
  4. Year -1 came after year -2, but at the same time, -1-01-20 was before -01-01-21 (similarly, -1-01-01 was before -1-02-01). Thus, the minus sign applies only to the value of the year.
  5. There is no year zero in the Gregorian calendar, but this does not prevent us from considering year -1 as a leap year.
  6. It is important to understand that as input, the plugins yql-date, yql-datetime, and yql-timestamp receive time relative to the Unix epoch (1970-01-01T00:00:00.000000Z). Thus, the date 1-01-02 was 719161 days ago relative to the Unix epoch, but one day ahead of the beginning of the era (1-01-01).

版本与发布记录

@gravity-ui/unipika 共发布 27 个版本,首次发布于 2023/02/22;过去 12 个月发布了 4 个版本。

版本发布日期距今
5.6.5latest2026/09/231 个月前
5.6.42026/09/102 个月前
5.6.32026/06/304 个月前
5.6.22025/12/2310 个月前
5.6.12025/11/061 年前
5.6.02025/07/301.3 年前

关于 @gravity-ui/unipika 的常见问题

@gravity-ui/unipika 是什么?

Common YT/YQL data formatting library

如何安装 @gravity-ui/unipika?

在项目目录运行 npm install @gravity-ui/unipika,或使用 pnpm add / yarn add / bun add。

@gravity-ui/unipika 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gravity-ui__unipika 是否存在。

@gravity-ui/unipika 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@gravity-ui/unipika 可以商用吗?

@gravity-ui/unipika 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gravity-ui/unipika 的下载量有多少?

根据 npm 官方下载统计,@gravity-ui/unipika 在 2026/10/17 – 2026/11/15 这 30 天内被下载 9,536 次,日均约 318 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gravity-ui/unipika 还在维护吗?

最新版本 5.6.5 发布于 2026/09/23(1 个月前);至今共发布 27 个版本,其中过去 12 个月发布了 4 个;首次发布于 2023/02/22。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。