@overlook/util-make-symbols NPM

Overlook framework utility to create global symbols

Usage

Create symbols for use in Overlook plugins etc.

Returns an object containing the specified Symbols. Symbols are created with descriptions matching symbol names, to help with debugging.

const makeSymbols = require('@overlook/util-make-symbols');

const symbols = makeSymbols( [ 'FOO', 'BAR' ] );

symbols.FOO // => Symbol(FOO)
symbols.BAR // => Symbol(BAR)

Published modules

When publishing your code as an NPM module, any Symbols you define should be created with makeSymbols() and module name provided as namespace.

The namespace is included in Symbol descriptions to aid debugging.

const symbols = makeSymbols(
  'my-module',
  [ 'FOO', 'BAR' ]
);

symbols.FOO // => Symbol(my-module.FOO)
symbols.BAR // => Symbol(my-module.BAR)

When a namespace is provided, Symbols are cached in a global store, so creating a Symbol with same name and namespace anywhere in an app will return the same symbol.

const symbols1 = makeSymbols( 'my-module', [ 'FOO' ] );
const symbols2 = makeSymbols( 'my-module', [ 'FOO' ] );
symbols1.FOO === symbols2.FOO // => true

Usage in plugins

// Published to npm as `overlook-plugin-wango`
const makeSymbols = require('@overlook/util-make-symbols');

const symbols = makeSymbols(
  require('./package.json').name,
  [ 'FOO', 'BAR' ]
);

const wangoPlugin = /* ... define plugin ... */;
wangoPlugin.FOO = symbols.FOO;
wangoPlugin.BAR = symbols.BAR;

module.exports = wangoPlugin;

Now regardless of whether someone imports version 1.0.0 or 2.3.5 of your plugin, require('overlook-plugin-wango').FOO will be the same Symbol.

Versioning

This module follows semver. Breaking changes will only be made in major version updates.

All active NodeJS release lines are supported (v10+ at time of writing). After a release line of NodeJS reaches end of life according to Node's LTS schedule, support for that version of Node may be dropped at any time, and this will not be considered a breaking change. Dropping support for a Node version will be made in a minor version update (e.g. 1.2.0 to 1.3.0). If you are using a Node version which is approaching end of life, pin your dependency of this module to patch updates only using tilde (~) e.g. ~1.2.3 to avoid breakages.