Bitmask flags decoder

Provide the stored value and a list that maps each name to a power-of-two bit. The result preserves your declaration order, returns every active name, and reports any value left over from bits you did not define. It is useful when reading database fields, API payloads, protocol values, access-control settings, and legacy configuration without manually converting numbers to binary or relying on language-specific bitwise behavior.

Describe the mask with explicit named bits

Start with the non-negative integer in the value field, then add one flags row for every meaning your system defines. Each row contains a name and a bit. The bit must be a positive power of two: 1, 2, 4, 8, 16, and so on. Those values represent independent binary positions, which makes them safe to combine by addition or bitwise OR. Names are trimmed and must remain unique, and bit values must also be unique, because two labels for the same position would make the decoded answer ambiguous. Definitions may appear in any order; active_flags follows the order you supplied, which lets an application keep a preferred display order instead of receiving an arbitrary numeric sort. The decoder accepts zero as a valid mask and returns an empty active_flags array for it. Inputs use JavaScript-safe non-negative integers, supporting exact values through 9,007,199,254,740,991 and individual declared bits through 4,503,599,627,370,496. Invalid records fail clearly instead of being silently coerced into a plausible but incorrect permission list.

Understand active flags and unknown bits

For every declaration, the decoder tests whether that binary position is present in value. If it is present, the corresponding name is appended to active_flags and its numeric bit contributes to the declared active total. The response also includes unknown_bits, calculated as the original value minus all active bits that were declared. A zero unknown_bits value means the supplied definitions fully explain the mask. A nonzero value is not automatically an error: it often signals a newly introduced server flag, an intentionally omitted internal option, or a schema version mismatch. Keeping that remainder visible is safer than dropping information. For example, if value is 13 and the declared bits are read=1, write=2, execute=4, and admin=8, the active names are read, execute, and admin, while unknown_bits is zero. If bit 8 were omitted from the definitions, the same input would return read and execute with unknown_bits equal to 8. The original value is returned unchanged so logs and downstream checks can retain exact provenance.

Use deterministic decoding in permission and option workflows

Bitmasks are common in database columns, operating-system modes, feature switches, device registers, game state, and third-party API responses because many booleans fit into one integer. This capability makes those fields readable at an integration boundary. Store the flag definitions beside the schema version, call the decoder when a record enters your pipeline, and use active_flags for display, filtering, or policy checks. Monitor unknown_bits as a compatibility signal: a nonzero remainder can route the record for review before software mistakes a new permission for an ordinary old value. The algorithm performs bounded arithmetic over at most 256 definitions and uses no network, clock, locale, random source, or mutable state, so identical JSON always produces identical JSON. It also avoids JavaScript's signed 32-bit bitwise operators and therefore handles exact masks well above 32 bits within the safe-integer range. The browser runner and API share this same library. Interactive decoding is free, while successful automated API tasks use the published base price of $0.002.