@piyawasin/byte-flags/dist/cjs/ByteFlags.js

A lightweight, type-safe utility library for efficiently storing and managing boolean flags in compact numeric values (8, 16, or 32 bits). Perfect for permission systems, feature flags, status tracking, and any scenario requiring compact boolean storage w

"use strict";
var __extends = (this && this.__extends) || (function () {
    var extendStatics = function (d, b) {
        extendStatics = Object.setPrototypeOf ||
            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
        return extendStatics(d, b);
    };
    return function (d, b) {
        if (typeof b !== "function" && b !== null)
            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
        extendStatics(d, b);
        function __() { this.constructor = d; }
        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
    };
})();
var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
        if (ar || !(i in from)) {
            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
            ar[i] = from[i];
        }
    }
    return to.concat(ar || Array.prototype.slice.call(from));
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.ByteFlags = void 0;
exports.createByteFlags = createByteFlags;
var BaseFlags_1 = require("./BaseFlags");
/**
 * Efficiently stores and manages up to 8 boolean flags in a single byte (8-bit value).
 *
 * Ideal for permission systems, feature flags, or status tracking where compact
 * serialization is needed. Flag names are fixed at creation for type safety.
 *
 * @example
 * // Recommended usage with type safety:
 * const flags = createByteFlags('read', 'write', 'execute', 'admin', 'guest');
 * flags.admin = true; // TypeScript knows this is a boolean
 *
 * @see {@link createByteFlags} for better TypeScript support
 */
var ByteFlags = /** @class */ (function (_super) {
    __extends(ByteFlags, _super);
    /**
     * Create a new ByteFlags instance with the specified flag names
     * @param flagNames Names of flags to initialize (1-8 flags)
     * @throws Error if more than 8 flags are provided or if flag names are invalid
     */
    function ByteFlags() {
        var flagNames = [];
        for (var _i = 0; _i < arguments.length; _i++) {
            flagNames[_i] = arguments[_i];
        }
        var _this = this;
        if (flagNames.length > ByteFlags._MAX_FLAGS) {
            throw new Error("Cannot have more than ".concat(ByteFlags._MAX_FLAGS, " flags"));
        }
        _this = _super.apply(this, flagNames) || this;
        // Maximum number of flags that can be stored in a single byte
        _this.MAX_FLAGS = ByteFlags._MAX_FLAGS;
        // Maximum byte value (2^8 - 1)
        _this.MAX_VALUE = ByteFlags._MAX_VALUE;
        return _this;
    }
    /**
     * Convert the flags to a byte value (0-255)
     * @returns Byte representation of all flags
     */
    ByteFlags.prototype.toByte = function () {
        return this.toValue();
    };
    /**
     * Load flags from a byte value
     * @param b Byte value to load (0-255)
     * @returns This instance for chaining
     * @throws Error if the byte value is invalid
     */
    ByteFlags.prototype.fromByte = function (b) {
        return this.fromValue(b);
    };
    /**
     * Create a ByteFlags instance from a JSON string
     * @param json JSON string or object from toJSON()
     * @returns New ByteFlags instance
     * @throws Error if JSON is invalid or flags don't match
     */
    ByteFlags.fromJSON = function (json) {
        var obj = typeof json === "string" ? JSON.parse(json) : json;
        var instance = new (ByteFlags.bind.apply(ByteFlags, __spreadArray([void 0], Object.keys(obj), false)))();
        return instance.setFlags(obj);
    };
    // For use in constructor
    ByteFlags._MAX_FLAGS = 8;
    ByteFlags._MAX_VALUE = 0xff;
    return ByteFlags;
}(BaseFlags_1.BaseFlags));
exports.ByteFlags = ByteFlags;
/**
 * Creates a type-safe ByteFlags instance with the specified flag names
 * @example
 * // Basic usage
 * const flags = createByteFlags('read', 'write', 'admin', 'guest');
 * flags.admin = true; // TypeScript knows this is a boolean
 *
 * // With explicit type
 * type AppFlags = 'darkMode' | 'notifications' | 'analytics';
 * const features = createByteFlags<AppFlags>('darkMode', 'notifications', 'analytics');
 * features.darkMode = true; // OK
 */
function createByteFlags() {
    var flagNames = [];
    for (var _i = 0; _i < arguments.length; _i++) {
        flagNames[_i] = arguments[_i];
    }
    return new (ByteFlags.bind.apply(ByteFlags, __spreadArray([void 0], flagNames, false)))();
}