Heap.Union

Declares a field that can take on the value of one of several alternative types. It is a complete analog to the Typescript union.

Usage / Signature

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

Arguments

• <b id="optionSchemas">optionSchemas</b>: HeapSchema[] <b style="color:red">*</b>
  A list of schemas corresponding to each of the possible types. This can be any supported type of heap table field - simple or complex.

  Due to the peculiarities of the deserialization algorithm, there are restrictions on the "compatibility" of different types within a Union field. The basic principle is that for each low-level JSON type (such as number, string, array, object), there can only be one representative in a single Union schema. That is, you cannot create a Union that contains both, for example: Heap.Integer and Heap.Number, Heap.Tuple and Heap.Array, Heap.Object and Heap.Record.

  An exception to this rule is Heap.Literal - because the literal value is unique and can be easily distinguished from other literals, multiple literals of the same type can be combined in one Union, but they cannot be combined with a non-literal schema of the same type.

  Below are the groups of types that cannot be combined:

  • Array - Heap.Array, Heap.Money, Heap.Tuple.
  • Boolean - Heap.Boolean, Heap.Literal<boolean>.
  • Number - Heap.Integer, Heap.Number, Heap.Enum<number>, Heap.Literal<number>.
  • 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<string>, Heap.KeyOf, Heap.Literal<string>.

  If one of the alternatives is another Union schema, its nested alternatives are "lifted up" (recursively) and combined into a single list at the top level. Compatibility rules apply to this combined list.

  The following types cannot be used as alternatives in Heap.Union:

  • "Formless" types - Heap.Any, Heap.Unknown
  • Heap.Enum

  Schemas with modifiers Heap.Optional and Heap.NonRequired are not supported and will lead to a runtime error, as they do not make sense in this context.

• <b id="options">options</b>: {default}
  An object with additional optional parameters for the field.

  • <b id="default">default</b>: union type
    The default value for this field. It can be a value of any of the alternative types. For more information on how default values work, see Guide / Heap / Default Values

Return Value

A JSON schema anyOf with the corresponding alternative sub-schemas.

Examples

Modeling a nullable value using Heap.Union

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

This is just an example; in practice, it is better to use Heap.Nullable for this purpose.

Modeling a unit of measurement using 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',
})