Enumerationjs NPM

enumerationjs : Java-like enum for javascript/coffeescript

Travis build License
Straightforward though very flexible solution addressing the unimplemented enum keyword.

KEY POINTS

functionalities
ⓘ An enum type MyEnum
      → is instanceof the Enumeration constructor
      → is immutable
      → can be inherited (JS | COFFEE)
      → Object.keys(MyEnum) is ["SOME_CONST1","SOME_CONST2"]
ⓘ An enum constant MyEnum.SOME_CONSTANT1
      → is instanceof MyEnum
      → is immutable
      → can inherit a prototype shared across MyEnum constants (JS | COFFEE)
      → can have its own specific properties (JS | COFFEE)
✓ Allow easy refactoring, avoiding the if else mess (JS | COFFEE)
✓ Lightweight deserialization with MyEnum.from(identifier) and serialization with MyEnum.ENUM_CONST.id()
integration
✓ Rock solid jasmine specified tests.
✓ Fully CommonJS and AMD compliant through a Universal Module Definition | since v1.3.0
✓ Available for npm, bower and Meteor, see the packages section
ⓘ Depends on underscore, but you can use lodash, tested. See this section for more infos.
⚠ The package will work with ecmascript3 standards (IE<=8) but immutability is provided through ecmascript5 standard, see this section

EXAMPLES

→ COFFEE.GUIDE.MD for coffescript devs
→ JS.GUIDE.MD for js devs

DOWNLOAD

❗ Shipped with underscore, ready-to-use
→ COMMENTED BUNDLE ~ 62K | MINIFIED BUNDLE ~ 31K
⚠ Assuming you can provide underscore, either through AMD or global variable _
→ UNDERSCORE-READY COMMENTED ~ 9.4K | UNDERSCORE-READY MINIFIED ~ 5.3K
⚠ Assuming you can provide lodash, either through AMD or global variable _. Read this section first
→ LODASH-READY COMMENTED ~ 9.4K | LODASH-READY MINIFIED ~ 5.3K

PACKAGES

npm install enumerationjs
bower install enumerationjs
meteor add sveinburne:enumerationjs

TABLE OF CONTENTS
1. AMD
1.1. UMD Behaviour
1.2. Requirejs + lodash
2. Quick api overview
2.1. Enumeration.constructor
2.2. Enumeration constant
2.3. Enumeration instance aka enum type
2.4. Enumeration object
2.5. More examples
3. Ecmascript compatibility
4. Dependencies
4.1. Underscore
4.2. For lodash users
5. Changelog

1. AMD

dependency name is "enumerationjs"

1.1. UMD Behaviour

If _ is defined global, the enumeration.js will be defined with no dependency.
Otherwise, it will call define with a dependency on underscore

1.2. Requirejs + lodash

you can map underscore to lodash to avoid an extra dependency easily :

require.config({
  map: {
    '*': {
      'underscore': 'lodash'
    }
  }
})

2. Quick api overview

2.1. Enumeration.constructor

You can instantiate an enum type with the provided Enumeration constructor. It will take three arguments :

MyEnum : the name of this enumeration, must be unique amongst other Enumeration instances.
enumConstants : an object containing the set of enum constants. Each key is the enum constant name and each value is a descriptor that can either be ...
- a raw descriptor i.e. a unique identifier of type string or number (JS | COFFEE)
- a structured descriptor i.e. a plain object (JS | COFFEE)
prototype : optional a prototype all the enum constants will inherit (JS | COFFEE)

2.2. Enumeration constant

Each enum constant will have the following methods :

key() : retrieve the key (SOME_ENUM_CONST for example)
id() : retrieve the identifier (1000 for example)
type() : retrieve the enum type,MyEnum Enumeration constructor's argument
describe() : return a string of the form 'key:id', useful for logging/debugging
...plus the properties provided at instantiation time (inherited from prototype and provided by descriptors)

2.3. Enumeration instance aka enum type

from(id,throwOnFailure=false) : retrieve the enum constant that matches given id. optional throwOnFailure, default to false, throws an error when no id match.
pretty() : give a pretty description of this enum type and all its constants, useful for logging/debugging
() : shortcut for pretty()

2.4. Enumeration object

Enumeration.types() : returns an array containing the MyEnum for each enum type.

2.5. More examples

→ COFFEE.GUIDE.MD for coffescript devs
→ JS.GUIDE.MD for js devs

3. Ecmascript compatibility

ECMA-262 5th edition was published on December 3, 2009

Among those specifications, the following methods must be available to have control over immutability:

Object.defineProperty(object,property,propertyDescriptor)
Object.freeze(object)

These methods prevent user from mistakenly modify any property from the enum type and its bound constants :
any attempt to write a read-only property in 'strict mode' will throw an error, ignored otherwise.
any attempt to reconfigure a non-configurable property in 'strict mode' will throw an error, ignored otherwise.
For older browser, those methods have fallbacks so no exception will show up, however the write permissions will be ignored.

4. Dependencies

4.1. Underscore

Relies on underscore >=1.4.
NB : On version 1.2 I switched to lodash for its optimizations and improvements, but on the other hand underscore appeared lighter for the bundled version, plus it's heavily used by meteor.

4.2. For lodash users

Downloaded version
The latest release has mirror branches with lodash required instead of underscore. Here are the travis build for each of these branches :
lodash v2 (last) : buildV2
lodash v3 (last) : buildV3
For either cases, you can download the appropriate versions here (assuming you can provide the lodash dependency of course):

→ LODASH-READY COMMENTED ~ 8.1K | LODASH-READY MINIFIED ~ 4.4K
ⓘ By loading lodash in a non-AMD context, a global _ variable will be defined and it will work seamlessly
ⓘ By loading lodash in an AMD context, enumeratoinjs will require("lodash")

Dependency managers version

ⓘ With bower, it seems possible by overriding underscore dependency, see this so thread
⚠ With npm, you cannot override dependencies. It is however still possible to shim _ globally with browserify.

5. Changelog

NB : minor doc fixes are not listed above

v1.3.11

Official lodash support

v1.3.10

Hot bugfix with function create is not a constructor

v1.3.8

Fixed underscore minimum version to 1.4, their changelog didn't mention _.object method so I tought it to be shipped from the beginning
Partial support for non ECMA5 engines
Replaced __proto__ direct assignments with custom createObject to allow full integration with old browsers
Performed check over Object.defineProperty and Object.create with IE8 and lower check support

v1.3.7