@andrewdonelson/byte-enum/dist/byteEnum.js

A high-performance, memory-optimized enum implementation for TypeScript

"use strict";
/**
 * ByteEnum - Memory-Efficient Enum Utilities for TypeScript
 *
 * A high-performance, memory-optimized enum implementation with
 * type safety and runtime utility methods.
 *
 * Features:
 * - Minimal memory footprint using byte values or single characters
 * - High-performance lookups using Map-based implementation
 * - Type safety with TypeScript
 * - Runtime utility methods for validation and display
 * - Case-insensitive key handling (all keys normalized to UPPERCASE)
 *
 * @license MIT
 * File: src/byteEnum.ts
 */
Object.defineProperty(exports, "__esModule", { value: true });
exports.createByteEnum = createByteEnum;
exports.createCharEnum = createCharEnum;
exports.createAlphaNumEnum = createAlphaNumEnum;
/**
 * Creates a memory-efficient enum using byte values (0-255)
 *
 * @param keys - Array of enum keys as string literals
 * @returns Enum object with utility methods
 */
function createByteEnum(keys) {
    // Create the enum object with keys mapping to sequential byte values
    // Convert all keys to uppercase
    const enumObject = keys.reduce((acc, key, index) => {
        if (index > 255) {
            throw new Error('Byte enum cannot have more than 256 values');
        }
        // Store the key in uppercase regardless of input format
        const upperKey = key.toUpperCase();
        acc[upperKey] = index;
        return acc;
    }, {});
    // Create lookup maps for faster performance
    const valueToKeyMap = new Map();
    const keysList = [];
    const valuesList = [];
    // Populate the lookup maps and cached arrays
    Object.entries(enumObject).forEach(([key, value]) => {
        valueToKeyMap.set(value, key);
        keysList.push(key);
        valuesList.push(value);
    });
    // Add utility functions
    const utilities = {
        /**
         * Get an array of all possible enum values
         */
        values: () => valuesList,
        /**
         * Get an array of all enum keys
         */
        keys: () => keysList,
        /**
         * Check if a value is a valid enum value
         */
        isValue: (value) => valueToKeyMap.has(value),
        /**
         * Check if a key is a valid enum key
         */
        isKey: (key) => enumObject.hasOwnProperty(key.toUpperCase()),
        /**
         * Get the key for a given value (optimized with Map lookup)
         */
        getKeyByValue: (value) => valueToKeyMap.get(value),
        /**
         * Get the display name for a value
         */
        getDisplayName: (value) => {
            const key = utilities.getKeyByValue(value);
            if (!key)
                return '';
            // Convert SNAKE_CASE to Title Case
            return key.toString().toLowerCase()
                .split('_')
                .map(word => word.charAt(0).toUpperCase() + word.slice(1))
                .join(' ');
        },
        /**
         * Get a formatted display name with custom formatter
         */
        getFormattedName: (value, formatter) => {
            const key = utilities.getKeyByValue(value);
            if (!key)
                return '';
            return formatter(key);
        }
    };
    // Combine the enum with its utilities
    return Object.assign(enumObject, utilities);
}
/**
 * Creates a memory-efficient enum using single byte characters (0-255)
 *
 * @param keys - Array of enum keys as string literals
 * @param customCharSet - Optional custom character set to use (defaults to all 256 byte values)
 * @returns Enum object with utility methods
 */
function createCharEnum(keys, customCharSet) {
    // Define the character set with all 256 possible byte values by default
    let charSet = customCharSet;
    if (!charSet) {
        // Generate all 256 characters (0-255) as the default charset
        charSet = '';
        for (let i = 0; i < 256; i++) {
            charSet += String.fromCharCode(i);
        }
    }
    // Create the enum object with keys mapping to character values
    // Convert all keys to uppercase
    const enumObject = keys.reduce((acc, key, index) => {
        if (index >= charSet.length) {
            throw new Error(`Enum has too many values (max: ${charSet.length})`);
        }
        // Store the key in uppercase for case-insensitive access
        const upperKey = key.toUpperCase();
        acc[upperKey] = charSet[index];
        return acc;
    }, {});
    // Create lookup maps for faster performance
    const valueToKeyMap = new Map();
    const keysList = [];
    const valuesList = [];
    // Populate the lookup maps and cached arrays
    Object.entries(enumObject).forEach(([key, value]) => {
        valueToKeyMap.set(value, key);
        keysList.push(key);
        valuesList.push(value);
    });
    // Add the utility functions
    const utilities = {
        values: () => valuesList,
        keys: () => keysList,
        isValue: (value) => valueToKeyMap.has(value),
        isKey: (key) => enumObject.hasOwnProperty(key.toUpperCase()),
        getKeyByValue: (value) => valueToKeyMap.get(value),
        getDisplayName: (value) => {
            const key = utilities.getKeyByValue(value);
            if (!key)
                return '';
            return key.toString().toLowerCase()
                .split('_')
                .map(word => word.charAt(0).toUpperCase() + word.slice(1))
                .join(' ');
        },
        getFormattedName: (value, formatter) => {
            const key = utilities.getKeyByValue(value);
            if (!key)
                return '';
            return formatter(key);
        }
    };
    return Object.assign(enumObject, utilities);
}
/**
 * Creates a memory-efficient enum using alphanumeric characters (0-9, a-z, A-Z)
 * This is provided for compatibility with systems that require printable characters.
 *
 * @param keys - Array of enum keys as string literals
 * @returns Enum object with utility methods
 */
function createAlphaNumEnum(keys) {
    // Define the character set: 0-9, a-z, A-Z (62 characters)
    const charSet = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
    return createCharEnum(keys, charSet);
}