parseEnumValue function

Reads an enum member from a text, such as a query parameter: '1' gives the member of value 1. With isKeyAccepted, a member name ('High') works too.

import { parseEnumValue } from 'utils';

Signature

export function parseEnumValue<E extends EnumObject>(
  enumObject: E,
  input: number | string,
  isKeyAccepted = false,
): E[keyof E]

Parameters

Name	Description
E	The type of the enum object.
enumObject	The enum, such as Level.
input	The value or the name to read.
isKeyAccepted	Whether a member name also identifies the member. Defaults to false.

Returns

The member.

Errors

• Throws TypeError: When no member matches.

Example

enum Level { Low = 0, High = 1 }
parseEnumValue(Level, '1'); // Level.High
parseEnumValue(Level, 'High', true); // Level.High

Tests

Line coverage: 100 %.

• ✅ reads "1" from a numeric enum as 1
• ✅ reads 1 from a numeric enum as 1
• ✅ reads "0" from a numeric enum as 0
• ✅ reads string enums
• ✅ accepts member names on request
• ✅ throws a TypeError for "7"
• ✅ throws a TypeError for "High"

Source

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

Uses

• EnumObject: Any TypeScript enum, or a const object used as one.
• getEnumEntries: Lists the members of an enum as [name, value] pairs, without the reverse mapping of numeric enums.

Files it needs

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

• src/enum/enum-object.ts
• src/enum/get-enum-entries.ts

Source code

import type { EnumObject } from './enum-object';
import { getEnumEntries } from './get-enum-entries';

/**
 * Reads an enum member from a text, such as a query parameter: `'1'` gives the member of value `1`. With
 * `isKeyAccepted`, a member name (`'High'`) works too.
 *
 * @template E - The type of the enum object.
 * @param enumObject - The enum, such as `Level`.
 * @param input - The value or the name to read.
 * @param isKeyAccepted - Whether a member name also identifies the member. Defaults to `false`.
 * @returns The member.
 * @throws {TypeError} When no member matches.
 * @example
 * enum Level { Low = 0, High = 1 }
 * parseEnumValue(Level, '1'); // Level.High
 * parseEnumValue(Level, 'High', true); // Level.High
 */
export function parseEnumValue<E extends EnumObject>(
  enumObject: E,
  input: number | string,
  isKeyAccepted = false,
): E[keyof E] {
  const text = String(input);
  const match = getEnumEntries(enumObject).find(
    ([key, value]) => String(value) === text || (isKeyAccepted && key === text),
  );
  if (!match) {
    throw new TypeError(`No enum member matches '${text}'`);
  }
  return match[1];
}

Test file

import { parseEnumValue } from './parse-enum-value';

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

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

describe(parseEnumValue, () => {
  it.for([
    ['1', Level.High],
    [1, Level.High],
    ['0', Level.Low],
  ] as const)('reads %j from a numeric enum as %s', ([input, expected]) => {
    expect(parseEnumValue(Level, input)).toBe(expected);
  });

  it('reads string enums', () => {
    expect(parseEnumValue(Mode, 'night')).toBe(Mode.Night);
  });

  it('accepts member names on request', () => {
    expect(parseEnumValue(Level, 'High', true)).toBe(Level.High);
    expect(parseEnumValue(Mode, 'Night', true)).toBe(Mode.Night);
  });

  it.for(['7', 'High'])('throws a TypeError for %j', (input) => {
    expect(() => parseEnumValue(Level, input)).toThrow(TypeError);
  });
});

Keywords: parse, enum, value, enums, function