Enum Types

Overview

EnumType registers a closed set of allowed values as a named OPRA type. At encode/decode time the codec performs an exact-match check against those values — any value outside the set is rejected.

Three input forms are accepted:

Form	When to use
TypeScript enum	Native TS enums with string or numeric values
Plain object	Key → value mapping defined inline or imported
String array	Simple list of allowed string values

---

TypeScript Enum

Define a standard TypeScript enum, then pass it to EnumType to register it:

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

export enum Gender {
  MALE = 'M',
  FEMALE = 'F',
  OTHER = 'O',
  UNKNOWN = 'U',
}

EnumType(Gender, {
  name: 'Gender',
  description: 'The gender of a person',
  meanings: {
    MALE: 'Male',
    FEMALE: 'Female',
    OTHER: 'Other',
    UNKNOWN: 'Unknown',
  },
});

The enum's values ('M', 'F', …) become the accepted wire values. The keys (MALE, FEMALE, …) are stored as aliases for schema documentation but are not accepted at runtime.

---

Plain Object & Array

Plain object

Use a key → value object when you want human-readable keys mapped to compact wire values:

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

export const OrderStatusEnum = EnumType({
  PENDING: 'pending',
  CONFIRMED: 'confirmed',
  SHIPPED: 'shipped',
  DELIVERED: 'delivered',
  CANCELLED: 'cancelled',
}, {
  name: 'OrderStatus',
  description: 'Current status of an order',
});

String array

Use an array when keys and wire values are the same string:

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

const ColorEnum = EnumType(['red', 'green', 'blue'], {
  name: 'Color',
});

---

Value Descriptions

Add human-readable descriptions to individual enum values with the meanings option. Each key in meanings maps to one of the enum's keys:

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

export enum Gender {
  MALE = 'M',
  FEMALE = 'F',
  OTHER = 'O',
  UNKNOWN = 'U',
}

EnumType(Gender, {
  name: 'Gender',
  description: 'The gender of a person',
  meanings: {
    MALE: 'Male',
    FEMALE: 'Female',
    OTHER: 'Other',
    UNKNOWN: 'Unknown',
  },
});

Meanings appear in the exported schema and in generated documentation — they have no effect on validation.

---

Using EnumType in Fields

Reference a registered enum in @ApiField by passing the enum class/object directly or by its string name:

import { ComplexType, ApiField } from '@opra/common';
import { Gender } from './enums/gender.js';

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

  // Direct reference
  @ApiField({ type: Gender })
  declare gender?: string;

  // String name (must be registered in the ApiDocument)
  @ApiField({ type: 'OrderStatus' })
  declare orderStatus?: string;
}

An inline enum can be defined and passed directly without registering it as a named type:

const ProductStatusEnum = EnumType(['draft', 'published', 'archived'], {
  name: 'ProductStatus',
});

@ComplexType()
class Product {
  @ApiField({ type: ProductStatusEnum })
  declare status?: string;
}

---

Inheritance

Use the base option to extend an existing EnumType. The new type inherits all values from the base and adds its own:

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

export enum Gender {
  MALE = 'M',
  FEMALE = 'F',
}

EnumType(Gender, { name: 'Gender' });

export enum AdministrativeGender {
  OTHER = 'O',
  UNKNOWN = 'U',
}

EnumType(AdministrativeGender, {
  name: 'AdministrativeGender',
  base: Gender,
  description: 'Extended gender classification for administrative use',
  meanings: {
    OTHER: 'Other / non-binary',
    UNKNOWN: 'Not specified',
  },
});

// AdministrativeGender accepted values: 'M', 'F', 'O', 'U'

The derived type accepts all values from the base plus its own.

---

Encode / Decode Behaviour

The codec performs a strict, case-sensitive exact match against the registered values.

Accepted:  'M'  'F'  'O'  'U'
Rejected:  'm'  'male'  'MALE'  ''  null  undefined

• Key aliases (e.g. MALE) are not accepted as wire values — only the mapped values ('M') are.
• No automatic coercion or case-folding is applied.
• Values outside the set produce a validation error at decode time.

const dt = document.node.getDataType('Gender');
const decode = dt.generateCodec('decode');

decode('M');      // ✓ → 'M'
decode('male');   // ✗ → ValidationError
decode('MALE');   // ✗ → ValidationError

---

Options Reference

EnumType(values, options?)

Option	Type	Description
name	string	Registry name for the resulting type.
description	string	Human-readable description included in the schema export.
base	object | string	Base enum to extend. Inherits all base values.
meanings	Record<string, string>	Human-readable labels for individual enum keys.
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.