'use strict';
/**
* A framework for all $wider bundles but also a tracker for different modules of the same name being loaded by different packages of the same
*
* creates
* ```javascript
* global.$wider = {
* // container for other wider globals
* }
* ```
* @module @wider/registry
*/
const $moduleName = "@wider/registry";
const $objectName = $moduleName.split( /\// )[ 1 ];
const root = "<<root>>";
const ROOT = Symbol( root ); //moduleName for the root of the @wider cache
const modulesLoaded = {};
modulesLoaded[ ROOT ] = {
created: Date.now(),
objectName: ROOT,
path: "",
section: undefined,
type: "hierarchy"
};
const dictionary = "DICTIONARY";
const DICTIONARY = Symbol( dictionary );
// makes a normally hidden non-enumerable member of global - we must always be the first to set global.$wider
const widerGlobal = global.$wider || {
CONFIG: {
$register: DICTIONARY,
customPaths: []
},
CONSTANTS: {
$register: DICTIONARY,
/*
ENGINE: "nodeJS", >> where-am-i > engine gives node not nodejs
IS_AT_SERVER: true, >> where-am-i > genre === server
*/
DELIMITER: "\uffff", // a general purpose delimiter
ENVIRONMENT: process.env.NODE_ENV || 'development', // could also be production or test or staging
INVALID: Symbol( "invalid" ), // a symbol to mark that a value is invalid
MACHINE: process.env.COMPUTERNAME,
MACHINE_USER: process.env.USERDOMAIN + "\\" + process.env.USERNAME,
MISSING: Symbol( "missing" ), // a symbol to mark something required to be an object but is not being provided and that can be detected by `.isMissing()`
missing: () => {}, // a function with no return value to provide where a function is required but no action is required and that can be detected by `.isMissing()`
NOTHING: "\u2913\u2913", // pretty string for output to user when a field is blank - two enDashes - hyphen
RECOMPUTE: "++", // what a user types into a field to make the system see if there is a default value
SERVER_STARTED_ENGINE: Date.now(), // the dateSerial of the time the current cluster/thread started
UNDER_CONSTRUCTION:Symbol("UNDER_CONSTRUCTION")
}
};
if ( !global.$wider )
Object.defineProperties( global, {
"$wider": {
get: () => {
return widerGlobal;
}
},
} );
/**
* Extends `Error - with its additional properties and also logs the error to the console
* @property {String} message - the error message
* @property {NCName} code a code word for optional programmatic use by code that traps the error
* @property {id|Object} moduleName the name of the module affected. If provided as an object, then the object should have a `.moduleName` property
*/
class loggedError extends Error {
constructor( message, code, moduleName ) {
super( `${$moduleName || 'anonymousModule'} - ${message}` );
this.code = ( code || "UNSPECIFIED" );
this.moduleName = moduleName.$moduleName || moduleName;
console.error( this );
}
}
loggedError.$moduleName = `${$moduleName}[throw loggedError]`;
/* if a section is used, make sure it is created if it does not yet exist */
function validateSection( section ) {
if ( section && !widerGlobal[ section ] ) {
widerGlobal[ section ] = {};
modulesLoaded[ section ] = {
created: Date.now(),
objectName: section,
path: "",
section: undefined,
type: "section"
};
}
}
/**
* Registers an object typically as it is being constructed via require or import. The purpose being to ensure that multiple packages within your runtime
* on a given cluster do not load the same module more than once - as can happen when a package is a dependency of several other packages. This function should *only*
* only be called from within the module level code of the module that is registering itself
*
* @param {String} [moduleName] - the name of the item to be registered. The string should be the same as used as might be used as id in `require`
* or `import`, or as used in `npm install`
*
* If moduleName is an object it is treated as a dictionary of registrations where the keyName is the **moduleName** and the associated value
* is an object with the properties ***value*** and ***objectName***. It may also contain ***section^^^ which if present will override the section parameter of the call to `.register()`
*
* If *moduleName* is absent then nothing is registered and the only action is to return the output Dictionary bundle
*
* @param {*} [value] - if present then the ***moduleName*** must be supplied and this ***value*** is added to the bundle.
*
* If absent, then the ***moduleName***, if provided, is registered in the dictionary and nothing is added to the bundle.
*
* If this is an object (class, function, json, plain object) then it should have a `$moduleName` static property which is the same as the parameter `moduleName`. It may also have a property **$objectName**
* - if this is a string then it must be the same as the **objectName** in this request
* - if this is the value of `registry.MERGE` then **moduleName** must already have been registered and the value shall be a dictionary of entries according to **section**, none of which may pre-exist
* @param {NCName} [objectName] if objectName is present, then ***value*** must be supplied and the value is stored in the response of this `@wider/registry`
* response under this name available for direct use by any other module without use of `require` or `import`. If ***objectName*** is not provided then it will
* be assumed to be the same as ***moduleName***
* @param {NCName} [section] if absent then the value is saved under ***objectName*** at the top level of the output Dictionary, otherwise this defines the section
* name in the dictionary under which the value is filed
*
* @returns {Dictionary} containing all registered items under their objectname and section.
* @throws {loggedError} an extension of the javascript `Error`` object. It is thrown when a registration is rejected
*/
function register( moduleName, value, objectName, section ) {
switch ( typeof moduleName ) {
case "string":
if ( !/^[\w_\-\d\@\/\.]+$/.test( moduleName ) )
throw new loggedError( `module name '${moduleName}' is not a valid simple module id`, "INVALID_MODULE_NAME", $moduleName );
else if ( objectName && !/^\w[\w\d_]*$/ )
throw new loggedError( `${moduleName} - Invalid format for name of objectName ${objectName}`, "BAD_OBJECTNAME", $moduleName );
else if ( section && !/^\w[\w\d_]*$/ )
throw new loggedError( `${moduleName} - Invalid format for name of objectName ${section}`, "BAD_SECTION", $moduleName );
else if ( modulesLoaded[ moduleName ] )
throw new loggedError( `${moduleName} - You have multiple packages attempting to load versions of the same moduleName`, "DUPLICATE_CALL", $moduleName );
else {
validateSection( section );
const target = section ? widerGlobal[ section ] : widerGlobal;
// always add to modulesLoaded
modulesLoaded[ moduleName ] = {
created: Date.now(),
objectName: objectName || ( value && value.$objectName ) || moduleName
};
if ( value !== undefined ) {
objectName = objectName;
if ( !objectName )
throw new loggedError( `${moduleName} - objectName must be provided when value is provided`, "MISSING_OBJECTNAME", $moduleName );
else if ( target[ objectName ] )
throw new loggedError( `Duplicate attempt to save member ${objectName} into $wider`, "DUPLICATE_GLOBAL_MEMBER", $moduleName );
else if ( value.$moduleName != moduleName && value.$objectName != moduleName )
throw new loggedError( `The submitted object does not possess a $moduleName which is the same as the name of the registry name or a matching alias defined by $objectName `, "$MODULENAME_MISSING", $moduleName );
else {
Object.defineProperty( target, objectName, {
get() {
return value;
},
enumerable: true
} );
Object.assign( modulesLoaded[ moduleName ], {
section: section,
path: ( section ? section + "." : "" ) + objectName,
} );
}
}
}
break;
//"undefined" :
default:
if ( moduleName )
throw new loggedError( `Permitted types for the value of moduleName in CAll to register '${moduleName}]' must be a string or an array`, "MODULENAME_MISSING", register.$moduleName );
}
return widerGlobal;
}
register.$moduleName = `${$moduleName[register]}`;
/**
* Merge one or more objects that do not register themselves, for example because they are a third party package
*
* Care needs to be taken when you act as proxy to register other packages in case different parts of your solution try to register the same third party package. If the risks remain despite your care, check in `global.$wider` before calling register.
* @param {Array|Object} entries If this is an array, then it is a collection of objects, each to be registered individually. Each object must contain the property `$moduleName`, and optionally may contain `$objectName`, both as defined in `registry.register()`. If you are registering as proxy, you will need to add these properties to each object before registering them.
* @param {NCName} [section] if provided then
*/
function bundle( entries, section ) {
if ( !Array.isArray( entries ) )
entries = [ entries ];
if ( section ) {
if ( section && typeof section != "string" )
throw new loggedError( "Section name missing or not a string", "SECTION_MISSING", register.$moduleName );
// create the section if it does not yet exist
if ( false && !modulesLoaded[ section ] )
register( section, {
$moduleName: section
}, section );
}
// submit each entry of the dictionary
entries.forEach( ( element, index ) => {
const objectName = element.$objectName || element.$moduleName;
if ( !objectName )
throw new loggedError( `Entry submitted for '${section||root}[${index}]' does not have property $moduleName`, "MODULENAME_MISSING", register.$moduleName );
register( element.$moduleName, element, element.$objectName || element.$moduleName, element.$registrySection || section );
} );
}
/**
* Merges designated properties in a pre-existing registered object. Often used to add CONSTANTS or CONFIG values
* @param {String} [moduleName] as per `registry.register()` - if the name is null, then the entries are added at the root of `$wider` oir the section if provided
* @param {Dictionary} entries
* @param {NCName} [mergeId] optional name of the merge for documentary purposes
* @throws {loggedError} if either the existing module does not exist or if you try to revise an entry that already exists
*/
function merge( moduleName, entries, mergeId ) {
const loaded = modulesLoaded[ moduleName ];
const section = loaded.section;
if ( !loaded )
throw new loggedError( `${$moduleName} not found to merge into`, "INVALID_PARAMS", `${register.$moduleName}[merge]` );
else {
let target = ( section ? widerGlobal[ section ] : widerGlobal );
if ( loaded.objectName !== ROOT )
target = target[ loaded.objectName ];
// register the merge
if ( !loaded.extensions )
loaded.extensions = [];
loaded.extensions.push( {
name: mergeId || "Unnamed " + ( loaded.extensions.length + 1 ),
created: Date.now()
} );
//register the bundle entries
for ( const key in entries ) {
if ( Object.hasOwnProperty.call( entries, key ) ) {
if ( target[ key ] )
throw new loggedError( "Attempting to modify existing entry not allowed during merge", "MERGE_DUPLICATE", `${register.$moduleName}[merge]` );
Object.defineProperty( target, key, {
/* jshint -W083 */
get() {
return entries[ key ];
},
/* jshint +W083 */
enumerable: true
} );
}
}
}
}
/**
*
* @param {String} moduleName the module name to be found
* @returns {*} the result of the search being undefined if the moduleName is unknown, or the
*/
function find( moduleName ) {
try {
let result = widerGlobal;
modulesLoaded[moduleName].path.split(/\./).forEach(element => {
result = result[element];
});
return result;
} catch ( e ) {}
}
/**
* Generate a report of the items that have been loaded and how long into the run session it was
* when they are loaded. NB not all loaded items are published.
* @returns {String} a tabular report of items loaded
*/
function loaded() {
const result = [ "\n## Modules loaded in chronological order of loading\n" ];
const paddingName = 40;
const paddingWait = 10;
const paddingPath = 30;
const started = ( modulesLoaded.CONFIG || modulesLoaded[ $moduleName ] ).created;
for ( const key in modulesLoaded ) {
if ( Object.hasOwnProperty.call( modulesLoaded, key ) ) {
const element = modulesLoaded[ key ];
const extensions = [];
( loaded.extensions || [] ).forEach( element => {
extensions.push( element );
} );
if ( extensions.length )
extensions.unshift( "" );
result.push( key.padEnd( paddingName, " " ) + " " +
( ( element.created - started ) / 1000 ).toFixed( 3 ).padStart( paddingWait, " " ) + " " +
( element.path || "" ).padEnd( paddingPath ) + " " +
( element.type ? `<<${element.type}>>` : "" ) +
extensions.join( "\n extension : " )
);
}
}
return result.join( "\n" );
}
/**
* A report of the structure in the object that is published via the common object
* @returns {String} a tabular report of items published
*/
function published() {
const result = [ "\n## Modules published in global.$wider alphabetical order\n" ];
const paddingName = 40;
const pusher = ( key, element2 ) => {
const elementStr = ( /^(string|number)$/.test( typeof element2 ) || Object.hasOwnProperty.call( element2 || {}, "toString" ) ) ? element2 + "" : "";
result.push(
key.padEnd( paddingName, " " ) + " " +
( typeof element2 ) +
( elementStr ?
` : ${elementStr.substr(0, 40)} ${ (elementStr.length > 40) ? "\u2026" : " "}` :
"" )
);
};
const driller = ( object ) => {
for ( const key in object ) {
if ( Object.hasOwnProperty.call( object, key ) ) {
const target = widerGlobal[ key ];
const element = modulesLoaded[ target.$moduleName ];
if ( !element ) {
result.push( `${key.padEnd( paddingName, " " )} <<${typeof target}>>` );
if ( target.$register && ( target.$register === DICTIONARY || target.$register === "DICTIONARY" ) )
for ( const key2 in target ) {
if ( Object.hasOwnProperty.call( target, key2 ) )
pusher( ( key + "." + key2 ), target[ key2 ] );
}
} else {
result.push( key.padEnd( paddingName, " " ) + " " +
( element.path || "" ) );
if ( target.$moduleName )
for ( const key2 in target ) {
if ( Object.hasOwnProperty.call( target, key2 ) )
pusher( ( key + "." + key2 ), target[ key2 ] );
}
}
}
}
};
driller( widerGlobal );
return result.sort().join( "\n" );
}
// register myself
bundle(
[ {
$moduleName: $moduleName,
$objectName: $objectName,
describe_loaded: loaded,
describe_published: published,
register: register,
loggedError: loggedError,
bundle: bundle,
merge: merge,
find: find,
DICTIONARY: DICTIONARY,
ROOT: ROOT
} ]
);
// there is a risk that this module itself is being multiple loaded so we have to use the version in global even if we didn't create it
//register($moduleName); // to stop ourselves being loaded multiple times
module.exports = global.$wider;