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',
})