Array Types

Overview

ArrayType wraps any OPRA type to produce a typed array. The element type can be a SimpleType, ComplexType, EnumType, MappedType, MixinType, UnionType, or another ArrayType (for nested arrays).

import { ArrayType } from '@opra/common';

ArrayType(ElementType, options?)

The result is used wherever a type is accepted — as the type option of @ApiField(), as the element type of another ArrayType, or directly in a UnionType.

---

Basic Usage

Pass the element type to ArrayType and assign it to @ApiField({ type: ... }):

Array of a SimpleType

import { ComplexType, ApiField, ArrayType } from '@opra/common';

@ComplexType()
class Article {
  @ApiField({ type: ArrayType(String) })
  declare tags?: string[];

  @ApiField({ type: ArrayType('email') })
  declare notifyEmails?: string[];

  @ApiField({ type: ArrayType(Number) })
  declare scores?: number[];
}

Array of a ComplexType

import { ComplexType, ApiField, ArrayType } from '@opra/common';

@ComplexType()
class Address {
  @ApiField({ required: true }) declare city: string;
  @ApiField() declare street?: string;
}

@ComplexType()
class Customer {
  @ApiField({ required: true }) declare givenName: string;

  @ApiField({ type: ArrayType(Address) })
  declare addresses?: Address[];
}

Array of an EnumType

import { ComplexType, ApiField, ArrayType, EnumType } from '@opra/common';

enum Permission {
  Read = 'read',
  Write = 'write',
  Delete = 'delete',
}

@ComplexType()
class Role {
  @ApiField({ required: true }) declare name: string;

  @ApiField({ type: ArrayType(EnumType(Permission)) })
  declare permissions?: Permission[];
}

---

Constraints

Use minOccurs and maxOccurs to restrict the number of elements in the array.

Option	Type	Description
minOccurs	number	Minimum number of elements (inclusive)
maxOccurs	number	Maximum number of elements (inclusive)

import { ComplexType, ApiField, ArrayType } from '@opra/common';

@ComplexType()
class Survey {
  // At least 1, at most 5 answers
  @ApiField({ type: ArrayType(String, { minOccurs: 1, maxOccurs: 5 }) })
  declare answers?: string[];

  // Must have exactly 3 coordinates
  @ApiField({ type: ArrayType(Number, { minOccurs: 3, maxOccurs: 3 }) })
  declare coordinates?: number[];
}

Constraints are validated at encode/decode time. Violations produce a validation error.

---

Nested Arrays

Pass an ArrayType as the element type of another ArrayType to create multi-dimensional arrays:

import { ComplexType, ApiField, ArrayType } from '@opra/common';

@ComplexType()
class Matrix {
  // Two-dimensional number array: number[][]
  @ApiField({ type: ArrayType(ArrayType(Number)) })
  declare rows?: number[][];

  // Three-dimensional: string[][][]
  @ApiField({ type: ArrayType(ArrayType(ArrayType(String))) })
  declare cube?: string[][][];
}

Constraints can be applied at each level independently:

@ComplexType()
class Grid {
  // Outer array: 1–10 rows; each inner array: exactly 3 columns
  @ApiField({
    type: ArrayType(
      ArrayType(Number, { minOccurs: 3, maxOccurs: 3 }),
      { minOccurs: 1, maxOccurs: 10 },
    ),
  })
  declare cells?: number[][];
}

---

Arrays of Union Types

Use UnionType as the element type to create arrays that accept multiple types per element:

import { ComplexType, ApiField, ArrayType, UnionType } from '@opra/common';

@ComplexType({ discriminatorField: 'kind', discriminatorValue: 'dog' })
class Dog {
  @ApiField({ required: true }) declare kind: string;
  @ApiField() declare breed?: string;
}

@ComplexType({ discriminatorField: 'kind', discriminatorValue: 'cat' })
class Cat {
  @ApiField({ required: true }) declare kind: string;
  @ApiField() declare indoor?: boolean;
}

@ComplexType()
class Shelter {
  // Each element is decoded as Dog or Cat based on the discriminator
  @ApiField({ type: ArrayType(UnionType([Dog, Cat])) })
  declare animals?: (Dog | Cat)[];
}

See Union Types for discriminator-based decoding and other union patterns.

---

Options Reference

ArrayType(elementType, options?)

Option	Type	Description
minOccurs	number	Minimum number of array elements.
maxOccurs	number	Maximum number of array elements.
name	string	Registry name for the resulting array type.
description	string	Human-readable description included in the schema export.
abstract	boolean	Cannot be used directly in fields — only extended.
scopePattern	string | RegExp | (string | RegExp)[]	Restricts which scopes can use this type.
embedded	boolean	Not exposed as a standalone named type in the schema.
examples	DataTypeExample[]	Example values for schema documentation.

// Named, reusable array type
const TagList = ArrayType(String, {
  name: 'TagList',
  description: 'A list of string tags',
  minOccurs: 1,
  maxOccurs: 20,
});

@ComplexType()
class Article {
  @ApiField({ type: TagList })
  declare tags?: string[];
}