ts-enum-util

An EnumWrapper is a class that wraps an "enum-like" object (any object where property values are string or number) to provide utility methods.

While you can reference the class directly, you should almost always use the $enum() function to obtain an instance. The EnumWrapper is generically typed, meaning methods like getKeys() return specific string literal unions of the actual keys in your enum, providing high type safety.

Key Characteristics:

• Map-like: Implements size, keys(), values(), entries(), forEach(), and is iterable. Note that has() and get() are replaced by isKey() and getValueOrDefault() for naming consistency.
• Array-like: Implements the ArrayLike interface, allowing it to be used with libraries like lodash that expect array-like collections of EnumWrapper.Entry objects.
• Order Preserving: It attempts to retain the original definition order of the enum entries.

// Use $enum() to get an EnumWrapper instance
const wrapper = $enum(MyEnum);

If your input type includes null or undefined, you must explicitly handle these cases in your visitor or mapper implementation using unique symbols provided by $enum to avoid naming collisions.

• Use [$enum.handleNull] to handle null values.
• Use [$enum.handleUndefined] to handle undefined values.

If the input type does not include these, you do not need to provide these properties.

import { $enum } from "ts-enum-util";

type RGB = "r" | "g" | "b";

// Handling null in a Visitor
function getRgbLabel(rgb: RGB | null): string {
    return $enum.visitValue(rgb).with({
        r: () => "Red",
        g: () => "Green",
        b: () => "Blue",
        [$enum.handleNull]: () => "null"
    });
}

// Handling null in a Mapper
function getRgbLabelMap(rgb: RGB | null): string {
    return $enum.mapValue(rgb).with({
        r: "Red",
        g: "Green",
        b: "Blue",
        [$enum.handleNull]: "null"
    });
}

An EnumWrapper implements several iteration interfaces, allowing you to treat it like a Map or an Array.

Map-like Iteration

You can use standard Map-like methods to iterate over keys, values, or both:

• keys(): Returns an IterableIterator<KeyType>.
• values(): Returns an IterableIterator<EnumType>.
• entries(): Returns an IterableIterator<EnumWrapper.Entry>.
• forEach(iteratee, context): Executes a callback for every entry.
• @@iterator: Allows direct use in for...of loops (iterates over [key, value] tuples).

Array-like Access

EnumWrapper supports indexed access. You can access [key, value] tuples by their numeric index (e.g., wrapper[0]). The length property returns the total number of entries.

Iteratee Signature

When using forEach or map, the callback (iteratee) receives: (value, key, enumWrapper, index) => R

// Example of for...of iteration
for (const [key, value] of wrapper.entries()) {
  console.log(key, value);
}

// Example of map
const keysArray = wrapper.map((val, key) => key);

An EnumWrapper behaves like a read-only Map where keys are the enum names and values are the enum values. It implements the standard Map interface for iteration.

• size: The number of entries.
• keys(): Returns an iterator for the keys.
• values(): Returns an iterator for the values.
• entries(): Returns an iterator for [key, value] pairs.
• forEach(callback): Iterates over entries. Note that the callback signature (value, key, wrappedEnum, index) includes an extra index parameter compared to standard Map.forEach.

Note: The EnumWrapper does not implement .get() or .has() methods directly; use the lookup methods (e.g., getValueOrThrow) instead.

const wrappedRgb = $enum(RGB);

// type: number
const size = wrappedRgb.size;

// Directly iterable like a Map
for (const [key, value] of wrappedRgb) {
    // type of key: ("R" | "G" | "B")
    // type of value: RGB
}

for (const key of wrappedRgb.keys()) {
    // type of key: ("R" | "G" | "B")
}

for (const value of wrappedRgb.values()) {
    // type of value: RGB
}

When processing data from external sources (like APIs), values might not match your TypeScript types at runtime. By default, $enum.visitValue and $enum.mapValue will throw an error if an unexpected value is encountered.

To override this behavior and provide a custom fallback, use the [$enum.handleUnexpected] property.

• In a Visitor, [$enum.handleUnexpected] is a function.
• In a Mapper, [$enum.handleUnexpected] is a value.

import { $enum } from "ts-enum-util";

type RGB = "r" | "g" | "b";

// Visitor with custom unexpected handler
function getRgbLabel(rgb: RGB): string {
    return $enum.visitValue(rgb).with({
        r: () => "Red",
        g: () => "Green",
        b: () => "Blue",
        [$enum.handleUnexpected]: () => "Unexpected!"
    });
}

// Mapper with custom unexpected handler
function getRgbLabelMap(rgb: RGB): string {
    return $enum.mapValue(rgb).with({
        r: "Red",
        g: "Green",
        b: "Blue",
        [$enum.handleUnexpected]: "Unexpected!"
    });
}

To avoid code duplication, you can define shared handler functions. How you type these functions depends on whether they need to access the value being visited:

1. Without value access: If the handler doesn't use the parameter, it can be a simple function with no arguments.
2. With value access: If the handler uses the parameter, the parameter type must be broad enough to encompass all enum values (and potentially null or undefined) that the handler will be applied to.

type RGB = "r" | "g" | "b";

function isSupportedColor(rgb: RGB | null | undefined): boolean {
    // Shared handler that uses the value
    // Must include the union type to be safe across multiple keys
    const handleSupported = (value: RGB): boolean => {
        console.log(`handling: ${value.toUpperCase()}`);
        return true;
    };

    // Shared handler for null/undefined
    const handleUnsupported = (value: RGB | null | undefined): boolean => {
        console.warn(`unsupported: ${value}`);
        return false;
    };

    return $enum.visitValue(rgb).with<boolean>({
        r: handleSupported,
        g: handleUnsupported,
        b: handleSupported,
        [$enum.handleNull]: handleUnsupported,
        [$enum.handleUndefined]: handleUnsupported
    });
}