enumerationjs : Java-like enum for javascript/coffeescript

!Travis build
!jasmine
!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

$3

> 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'
}
}
})

$3

#### 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

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

Among those specifications, the following methods must be available to have control over immutability:
``javascript
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.

$3

#### 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.

$3

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

- Added changelog

v1.3.6

- Fixed bug with describe() method when descriptors are structured

v1.3.4

- Meteor support
- Added Enumeration.types() as an alias to Enumeration.list() to be semantically consistent

v1.3.2

- Enhanced semantic consistency

v1.3.0

- UML loader, AMD compliant
- replaced lodash with underscore

v1.2.2

- Fixed MyEnum() function bug

v1.2.0

- Replaced underscore with lodash

v1.0

- First release

↑ Back to TABLE OF CONTENTS