regalia v1.0.2

regalia

Helps you make symbol trees

Why?

Because we may like to use symbols as constants.

Or perhaps you have a another use for symbol trees.

Yet, in writing symbol trees yourself, there may be some repetition:

const constants = {
  doNotRepeatYourself: Symbol('doNotRepeatYourself')
}

Unlike function names there is no syntax to infer the symbol description from the key.

This library provides a convenient API for making symbol trees and also some testing utilities.

Also:

• sensible symbol descriptions
• testing utilities (see below)

How?

const regalia = require('regalia')
regalia(['foo'])
// { foo: Symbol(foo) }

Symbols are created using Symbol() (not Symbol.for()).

The input is composed of arrays that contain strings. Each array will be transformed into an object, where the property names are the strings and the values are symbols.

The description of each symbol will be the same as its property name.

regalia([
  'foo',
  'bar'
])
// { foo: Symbol(foo), bar: Symbol(bar) }

Nested hierarchies are possible, using objects:

regalia({
  a: ['foo'],
  b: ['foo']
})
// { a: { foo: Symbol(a.foo) }, b: { foo: Symbol(b.foo) } }

Arrays can’t contain objects.

The dot notation in each symbol description is according to its path in the tree structure. Due to this, periods are not allowed anywhere.

Test utilities

• equals-regalia: deep equality check for regalia trees
• is-regalia: validate regalia trees
• regalia-reverse: reverses regalia trees back to input format

Why not Symbol.for()?

The theoretical benefit of symbols, as opposed to Symbol.fors, is that references to them cannot be obtained anywhere but where they were created. They must be exported or passed on in order for them to reach another module.

Symbol.for symbols can be re-obtained anywhere by calling with the same identifier.