https://github.com/gravity-ui/unipika
https://github.com/gravity-ui/unipika
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/gravity-ui/unipika
- Owner: gravity-ui
- License: mit
- Created: 2023-02-17T18:32:53.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-08-20T16:05:51.000Z (almost 2 years ago)
- Last Synced: 2025-01-16T04:43:39.693Z (over 1 year ago)
- Language: TypeScript
- Size: 1.22 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# 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 format | Types |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| YSON | `string`, `number`, `int64`, `uint64`, `double`, `map`, `list`, `null` |
| YQL | `yql.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:
| Name | Type | Default value | Description |
| ------------------------- | -------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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` | `() => false` | Function, 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` |
| format | String | `'json'` | `[YSON-specific]` Affects displaying YSON types. Serialization to text `yson` or `json` is supported. These ways of representation are described in YT documentation. |
| decodeUTF8 | Boolean | `true` | `[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. |
| showDecoded | Boolean | `true` | `[NCP][YSON-specific]` Indicates whether the decoded data should be displayed or the data in the form in which it is received from YT. |
| binaryAsHex | Boolean | `true` | `[NCP][YSON-specific]` Indicates whether binary strings should be displayed as a sequence of HEX-digits. |
| asHTML | Boolean | `true` | Return serialized data in `plain text` or `html`. |
| break | Boolean | `true` | Put hyphens and indents or return everything as a single line. |
| indent | Number | `4` | Indent size. |
| compact | Boolean | `false` | The mode in which complex types like `map`, `list`, `yql.struct` and so on, are displayed more compact if contain only one element. |
| highlightControlCharacter | Boolean | `false` | Enables highlighting of special control characters in html strings. |
| escapeWhitespace | Boolean | `true` | `[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. |
| escapeYQLStrings | Boolean | `true` | `[NCP][YQL-Converter]`The mode in which no symbols are escaped at all, so that user can get "raw" data. |
| nonBreakingIndent | Boolean | `true` | The mode in which indents, spaces in key-value separator, and spaces in string binary representation are nonbreaking ( ` ` symbol). |
| omitStructNull | Boolean | `false` | `[YQL-Converter]` Indicates whether to skip keys with `null` value in `yql.struct` type. |
| maxListSize | Number | `undefined` | `[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. |
| maxStringSize | Number | `undefined` | `[YQL-Converter]` Maximum allowed size of strings (`yql.string`, `yql.utf8`). If value > 0 is set, string will be truncated to this value. |
| limitMapLength | Number | `undefined` | Maximum allowed size of all map nodes. If value > 0 is set, node will be truncated to this (value - 1). |
| limitListLength | Number | `undefined` | Maximum allowed size of all list nodes. If value > 0 is set, node will be truncated to this (value - 1). |
| treatValAsData | Boolean | `false` | If `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).