New Priority Mail

    flagon

    0.0.5 • Public • Published

    flagon

    A tiny utility to make using bitwise operations readable by mere mortals. Drink up!

    Quick start

    npm install flagon --save

    Use either a chaining API flag(A).method(B).method(B).value() or access the raw functions via flag.method(A,B)

    var permission = {
      READ:     0b0001,
      CREATE:   0b0010,
      MODIFY:   0b0100,
      DELETE:   0b1000
    }
     
    //Raw API
    var GUEST = permission.READ
    var USER = flagon.merge(permission.READ, permission.MODIFY)
    var ADMIN = flagon.merge(USER, permission.CREATE)
    var SUPERUSER = flagon.merge(ADMIN, permission.DELETE)
     
    var SUPER_GUEST = flagon.toggle(GUEST, permission.DELETE)
     
    //Chaining API
    var DELETE_BUT_NOT_READ = flagon(USER)
                    .merge(permission.DELETE)
                    .toggle(permission.READ)
     
    DELETE_BUT_NOT_READ.contains(permission.READ) == false
    DELETE_BUT_NOT_READ.contains(permission.DELETE) == true
     

    Why make something so concise so verbose?

    Bitwise operations are very powerful and concise. But exactly because they are so powerful, they are often used in security critical situations. By making the operations more readable it is less likely the developer will unintentionally permit access to restricted data or operations.

    I developed this utility for validating user and organizations permissions in a REST API. For simpler use cases, you may prefer to stick to using the underlying bitwise operations.

    Why is Binary OR named merge? and XOR named toggle?

    This utility is trying to infer the purpose of the operation in the context of your application. It is likely this guess may be incorrect, and if so I'd be happy to alias the function names to anything reasonable.

    Here is an example where you may be using Binary OR to merge permissions

    var permission = {
      READ:     0b0001,
      CREATE:   0b0010,
      MODIFY:   0b0100,
      DELETE:   0b1000
    }
     
    var GUEST = permission.READ,
    var USER = flagon.merge(permission.READ, permission.MODIFY),
    var ADMIN = flagon.merge(USER, permission.CREATE)
    var SUPERUSER = flagon.merge(ADMIN, permission.DELETE)
     

    And you may want to check if a GUEST can MODIFY.

    flagon(GUEST).contains(permission.CREATE) == false

    And you may want to temporarily grant access to MODIFY to a GUEST user.

    var GUEST_THAT_CAN_MODIFY = flagon.toggle(GUEST,permission.MODIFY)
     
    //then revoke it later
    var GUEST = flagon.toggle(GUEST_THAT_CAN_MODIFY,permission.MODIFY)

    All of the examples seek to demonstrate that the operations purpose is more important than the underlying binary flags. The flags themselves are uninteresting, but they facilitate expansion of your permission model without altering other aspects of your application (e.g. your DB Schema)

    Functions

    merge (Binary OR)

    Usage: flagon.merge(A,B) or flagon(A).merge(B).value()

    Equivalent Operation: A | B

    Merges all true flags that share a column in two binary sequences.

    e.g.

    (0b1000 | 0b0100 | 0b0010) == 0b1110
     
    flagon.merge(0b1000).merge(0b0100).merge(0b0010).value() == 0b1110
    contains

    Usage: flagon.contains(A,B) or flagon(A).contains(B)

    Equivalent Operation: B == 0 || ((A & B) == B)

    Does a bit mask contain every true value of another bit mask?

    e.g.

    var A = 0b1000
    var B = 0b1100
     
    ;(A & B) == B == false
     
    flagon.contains(B,A) == flagon(B).contains(A) == false
     
    ;(A & B) == A == true

    Note contains will automatically unwrap a wrapped value.

    toggle

    Usage: flagon.toggle(A,B) or flagon(A).toggle(B).value()

    Equivalent Operation: (A ^ B)

    Flips every bit of the object that has a different true value to the subject.

    e.g.

    var A = 0b1000
    var B = 0b1100
     
    ;(A ^ B) == 0b0100
     
    flagon.toggle(A,B) == 0b0100
     
    //toggling twice reverts the change
     
    flagon(A).toggle(B).toggle(B).value() == A == true
    toString

    Usage: flagon(A).toString() or flagon(A) + ""

    Outputs a binary represenation of a number as a string.

    flagon(2).toString() == flagon(2)+"" == 10

    Note, Javascript has similar functionality by providing a radix to a Number toString

    4..toString(2) == "100"

    You can still access this functionality via flagon by simply calling toString(2) on the outputted value.

    flagon(4).value().toString(2) == 100
    
    //output Hexadecimal too!
    flagon(15).value().toString(16) == 'f'
    
    value

    Usage: flagon(A).value()

    Outputs the number value A that was wrapped by calling flagon(A). Useful for extracting the number value after performing a chained operation.

    flagon

    Usage: flagon(A).<method>(B).<method>(C)....value()

    Wraps a value so you can call a series of operations. Access the raw value by calling value() or access a binary representation by calling toString()

    Example:

    //flagon(A).<method>(B).<method>(C).value()
     
    //toString
    flagon(0b10).merge(0b01).toString() == "11"
    //or
    flagon(0b10).merge(0b01)+"" == "11"
     
    //value
    flagon(0b111).toggle(0b010).value() == 0b101

    Why chaining?

    I don't really like chaining, it doesn't work well with composition. But I added chaining when writing the library to help me get my head around the operations. One benefit of chaining, is it becomes quite clear which argument is the object, and which is the subject. In your actual application code I don't see it being that useful, but I also don't see any need for removing it when the whole script is ~20 lines of code.

    Where is bit shifting?

    I didn't need it for my use case, YAGNI. PR's welcome though.

    Chained Equality

    In this readme there are often chained equalities e.g.

    2 == (1 + 1) == (4 / 2)
    

    In actual javascript this wouldn't actually work. The expression would evaluation to:

    2 == 1 + 1 == 4 / 2
    true == 2
    true
    

    But that is only because 2 evaluates to a truthy value.

    I'll change this in future so it is less confusing.

    Install

    npm i flagon

    DownloadsWeekly Downloads

    2

    Version

    0.0.5

    License

    ISC

    Last publish

    Collaborators

    • jaforbes