Heap.Union

Объявляет поле, которое может принимать значение одного из нескольких алтернативных типов. Полный аналог
Typescript union.

Применение / сигнатура

import { Heap } from '@app/heap'
Heap.Union(optionSchemas, options)

Аргументы

optionSchemas: HeapSchema[] *
Список схем соответствующих каждому из возможных типов.
Это может быть любой поддерживаемый тип поля heap-таблицы - простой или сложный.

Из-за особенностей алгоритма десериализации, существуют ограничения на "сочетаемость" разных типов в рамках
Union-поля. Базовый принцип - для каждого низкоуровневого JSON-типа (таких как number, string, array, object)
в одной Union-схеме может быть только один представитель. Т.е. нельзя создать Union, который содержит
одновременно, например: Heap.Integer и Heap.Number, Heap.Tuple и Heap.Array, Heap.Object и Heap.Record.

Исключение из этого правила - Heap.Literal - благодаря тому, что значение литерала уникально и может быть
легко отличимо от других литералов, несколько литералов одного типа могут сочетаться в одном Union, но не
могут сочетаться с не-литеральной схемой такого же типа.

Ниже перечислены группы типов, которые не могут сочетаться:
- Array - Heap.Array, Heap.Money, Heap.Tuple.
- Boolean - Heap.Boolean, Heap.Literal.
- Number - Heap.Integer, Heap.Number, Heap.Enum, Heap.Literal.
- Object - Heap.Object, Heap.Record, Heap.RefLink, Heap.GenericLink, Heap.Intersect.
- String - Heap.String (Heap.RegEx, Heap.NonEmptyString), Heap.DateTime, Heap.RefLink, Heap.GenericLink,
  Heap.Enum, Heap.KeyOf, Heap.Literal.
Если одна из альтернатив - другая Union-схема, то её вложенные альтернативы "выносятся наверх" (рекурсивно) и
объединяются в один список на верхнем уровне. Правила сочетаемости применяются к этому объединённому списку.

Следующие типы не могут быть использованы в качестве альтернатив Heap.Union:
- "Бесформенные" типы - Heap.Any, Heap.Unknown
- Heap.Enum
Схемы с модификаторами Heap.Optional и Heap.NonRequired не поддерживаются и приведут к рантайм-ошибке, т.к. не
имеют смысла в данном контексте.
options: {default}
Объект с дополнительными необязательными параметрами поля.
- default: union type
  Значение по умолчанию для данного поля. Может быть значением типа любой из альтернатив.
  Подробнее о том, как работают значения по умолчанию, см.
  Руководство / Heap / Значения по умолчанию

Возвращаемое значение

JSON-схема anyOf
с соответствующими альтернативными под-схемами.

Примеры

Моделирования nullable значения с помощью Heap.Union

const customers = Heap.Table('customers', {
  age: Heap.Union(
    [Heap.Integer({ minimum: 0 }), Heap.Null()],
    { default: null },
  ),
})

Это только пример, на практике для этого лучше использовать Heap.Nullable.

Моделирование единицы измерения с помощью Heap.Union

const products = Heap.Table('products', {
  weight: Heap.Number(),
  weightUnit: Heap.Union([
    Heap.Literal('gram'),
    Heap.Literal('kilogram'),
    Heap.Literal('ton'),
  ]),
})
await products.create(ctx, {
  weight: 10,
  weightUnit: 'gram',
})

Предложить изменения