sleavely / json-bitmask

Easy-to-use bitmask serializer

json-bitmask

Minimal utility for de-/serializing bitmask flags.

Installation

npm i json-bitmask

Usage

First, let's define our flags in a file we'll call permissions.js:

const bitmask = require('json-bitmask')

/**
 * Each flag needs to increment the value by 2x to work as a bitmask
 */
const PERMISSIONS = {
  BILLING: 1,
  CREATE_API_KEYS: 2,
  READ_API_KEYS: 4,
}

const parseMask = bitmask.from(PERMISSIONS)

module.exports = exports = {
  PERMISSIONS,
  parseMask,
}

Parsing and Reading

const { parseMask } = require('./permissions')

// Pretend we got a user from our database
const user = {
  username: 'Sleavely',
  permissions: 5
}

// Lets deserialize the permissions to something readable
user.permissions = parseMask(user.permissions)

// Now our user object looks like:
{
  username: 'Sleavely',
  permissions: {
    BILLING: true,
    CREATE_API_KEYS: false,
    READ_API_KEYS: true,
  }
}

We've converted a fairly small value to something that is a breeze to work with:

if (!user.permissions.BILLING) {
  throw new Error('You are not allowed to manage billing!')
}

Editing and saving

user.permissions.BILLING = false

json-bitmask will automatically return the integer representation when you try to perform math or JSON.stringify() on it:

const serializedUser = JSON.stringify(user)
// Note that because we removed the BILLING permission, the value has changed to 4
// {"username":"Sleavely","permissions":4}

saveToDatabase(serializedUser)

json-bitmask's Issues

Create parser from array?

Instead of placing the responsibility of setting the correct bit flag values (1,2,4,..) on the developer, the .from() method could accept an array that defines the names of the flags. Consider the following:

[ 'ADMIN', 'BILLING', 'MEMBERS', 'CALENDAR' ].reduce((out, name, i) => {
  out[name] = Math.pow(2, i);
  return out;
}, {})
// { ADMIN: 1, BILLING: 2, MEMBERS: 4, CALENDAR: 8 }