toEnumValue function

Returns a value typed as an enum member: the value itself when it belongs to the enum, the fallback otherwise. For a stored setting that may be outdated.

import { toEnumValue } from 'utils';

Signature

export function toEnumValue<E extends EnumObject>(enumObject: E, value: unknown, fallback: E[keyof E]): E[keyof E]

Parameters

Name	Description
E	The type of the enum object.
enumObject	The enum, such as Mode.
value	The value to check.
fallback	The member returned when value does not belong to the enum.

Returns

value narrowed to the enum, or fallback.

Example

enum Mode { Day = 'day', Night = 'night' }
toEnumValue(Mode, 'night', Mode.Day); // Mode.Night
toEnumValue(Mode, 'dusk', Mode.Day); // Mode.Day

Tests

Line coverage: 100 %.

• ✅ keeps a member of the enum
• ✅ falls back for "dusk"
• ✅ falls back for undefined
• ✅ falls back for undefined
• ✅ falls back for "Night"
• ✅ falls back for 0
• ✅ does not accept the names of a numeric enum

Source

src/enum/to-enum-value.ts (on GitHub)

Uses

• EnumObject: Any TypeScript enum, or a const object used as one.
• isEnumValue: Checks whether a value is one of the values of an enum, in O(1): the values of each enum are read once.

Files it needs

src/enum/to-enum-value.ts imports, directly or not:

• src/enum/enum-object.ts
• src/enum/get-enum-entries.ts
• src/enum/get-enum-values.ts
• src/enum/is-enum-value.ts

Source code

import type { EnumObject } from './enum-object';
import { isEnumValue } from './is-enum-value';

/**
 * Returns a value typed as an enum member: the value itself when it belongs to the enum, the fallback
 * otherwise. For a stored setting that may be outdated.
 *
 * @template E - The type of the enum object.
 * @param enumObject - The enum, such as `Mode`.
 * @param value - The value to check.
 * @param fallback - The member returned when `value` does not belong to the enum.
 * @returns `value` narrowed to the enum, or `fallback`.
 * @example
 * enum Mode { Day = 'day', Night = 'night' }
 * toEnumValue(Mode, 'night', Mode.Day); // Mode.Night
 * toEnumValue(Mode, 'dusk', Mode.Day); // Mode.Day
 */
export function toEnumValue<E extends EnumObject>(enumObject: E, value: unknown, fallback: E[keyof E]): E[keyof E] {
  return isEnumValue(enumObject, value) ? value : fallback;
}

Test file

import { toEnumValue } from './to-enum-value';

enum Mode {
  Day = 'day',
  Night = 'night',
}

enum Level {
  Low = 0,
  High = 1,
}

describe(toEnumValue, () => {
  it('keeps a member of the enum', () => {
    expect(toEnumValue(Mode, 'night', Mode.Day)).toBe(Mode.Night);
    expect(toEnumValue(Level, 1, Level.Low)).toBe(Level.High);
  });

  it.for(['dusk', undefined, null, 'Night', 0])('falls back for %j', (value) => {
    expect(toEnumValue(Mode, value, Mode.Day)).toBe(Mode.Day);
  });

  it('does not accept the names of a numeric enum', () => {
    expect(toEnumValue(Level, 'High', Level.Low)).toBe(Level.Low);
  });
});

Keywords: to, enum, value, enums, function