🧩 Enum.js

A lightweight, versatile utility class for creating and managing enumerable values in JavaScript. Great for maintaining clean, ordered value sets like directions, states, roles, and more.

✨ Features

• Create immutable, ordered enumerations
• Access values by index, label, or relative position
• Supports iteration, mapping, filtering, and other functional utilities
• Easily retrieve first, last, random, and adjacent values
• Enhanced validation for enum values
• Works in both Node.js and browser environments
• Fully documented and tested

📦 Installation

npm install @herb-ert/enumjs

If you're using ES Modules:

import Enum from '@herb-ert/enumjs';

Or with CommonJS:

const Enum = require('@herb-ert/enumjs');

🚀 Usage

const Directions = new Enum('NORTH', 'EAST', 'SOUTH', 'WEST');

console.log(Directions.NORTH);        // "NORTH"
console.log(Directions.values);       // ["NORTH", "EAST", "SOUTH", "WEST"]
console.log(Directions.next('EAST')); // "SOUTH"
console.log(Directions.random());     // Randomly picks one of the directions
console.log([...Directions]);         // ["NORTH", "EAST", "SOUTH", "WEST"]

🧰 API

Constructor

new Enum(...values)

Properties

| Name | Description | |----------|------------------------------| | values | Array of all enum values | | length | Number of values in the enum | | first | First value | | last | Last value |

Methods

| Method | Description | |------------------------------------|-------------------------------------------------------------------------------------------------------------| | Enum.of(...args) | Creates a new instance of the Enum class with the provided arguments. | | next(currentValue) | Retrieves the next value in the sequence from the values array. | | previous(currentValue) | Retrieves the previous value in the values array relative to the given current value. | | compare(firstValue, secondValue) | Compares the positions of two values within the values array and determines their relative difference. | | getByIndex(index) | Retrieves the value at the specified index from the values array. | | has(value) | Checks if a specified value exists in the collection. | | indexOf(value) | Returns index of value or -1 | | toString(value) | Converts the current instance into its string representation. | | isFirst(value) | Checks if the provided value is the first element in the values array. | | isLast(value) | Checks if the provided value is the last element in the array values array. | | random() | Retrieves a random element from the values array. | | filter(predicate) | Filters the values of the current instance based on a provided predicate function. | | some(predicate) | Checks if at least one element in the array satisfies the provided testing function. | | every(predicate) | Evaluates whether all elements in the values array satisfy the provided predicate function. | | map(callback) | Applies a callback function to each element in the values array and returns a new array with the results. | | reduce(callback, initialValue) | Reduces the array to a single value using a provided callback function. | | forEach(callback) | Iterates over each element in the collection and executes the provided callback function. | | [Symbol.iterator]() | Returns the default iterator for the object. |

📦 More Examples

Creating Enums

You can instantiate an enum in two equivalent ways:

const Roles1 = new Enum('USER', 'MODERATOR', 'ADMIN');  // Using the constructor
const Roles2 = Enum.of('USER', 'MODERATOR', 'ADMIN');   // Via the static helper

Accessing Basic Properties

console.log(Roles2.values)            // ['USER', 'MODERATOR', 'ADMIN']
console.log(Roles2.first);            // "USER"       — the first value in the enum
console.log(Roles2.last);             // "ADMIN"      — the last value in the enum
console.log(Roles2.length)            // 3

Functional Utilities

Enum supports most of the array utility methods. Here's how you can use them.

const Status = Enum.of('IDLE', 'RUNNING', 'DONE');

console.log(Status.some(s => s.startsWith('R')));           // true  (because "RUNNING" starts with "R")
console.log(Status.every(s => typeof s === 'string'));      // true  (all values are strings)
console.log(Status.map(s => s.toLowerCase()));              // ["idle", "running", "done"]
console.log(Status.reduce((acc, val) => acc + val[0], '')); // "IRD"  (concatenates first letters of each status)
const Short = Status.filter(s => s.length <= 4);            // ["IDLE", "DONE"]
console.log(Status.random());                               // e.g. "RUNNING"

Iteration

Enums are iterable, so you can spread or loop over them.

for (const s of Status) {
  console.log(s);
}

console.log([...Status]); // ["IDLE", "RUNNING", "DONE"]

🧪 Validation

The constructor will throw an error if: Any value is not a string There are duplicate values

new Enum('A', 'B', 42);       // ❌ TypeError: Enum values must be strings. Invalid entries: 42
new Enum('A', 'B', 'A');      // ❌ Error: Enum values must be unique. Duplicates found: RED

🔧 License

MIT © herb-ert