enumerationjs
v1.3.13
Published
Java-like super flexible enums ! Move the logic.
Downloads
12
Readme
enumerationjs : Java-like enum for javascript/coffeescript
Straightforward though very flexible solution addressing the unimplemented enum
keyword.
KEY POINTS
functionalities
ⓘ An enum typeMyEnum
→ isinstanceof
theEnumeration
constructor
→ is immutable
→ can be inherited (JS | COFFEE)
→Object.keys(MyEnum)
is["SOME_CONST1","SOME_CONST2"]
ⓘ An enum constantMyEnum.SOME_CONSTANT1
→ isinstanceof
MyEnum
→ is immutable
→ can inherit a prototype shared acrossMyEnum
constants (JS | COFFEE)
→ can have its own specific properties (JS | COFFEE)
✓ Allow easy refactoring, avoiding theif else
mess (JS | COFFEE)
✓ Lightweight deserialization withMyEnum.from(identifier)
and serialization withMyEnum.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 ...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 argumentdescribe()
: 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 givenid
. [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 forpretty()
2.4. Enumeration object
Enumeration.types()
: returns an array containing theMyEnum
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) :
lodash v3 (last) :
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 customcreateObject
to allow full integration with old browsers - Performed check over
Object.defineProperty
andObject.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