Libraries

JavaScript libraries are .js files that are typically located in the exec/load directory (for unmodified-stock libraries) or the mods/load directory (for modified-stock or 3rd party libraries).

JavaScript libraries are usually referenced from another script via the load() or require() global functions.

Background Load

The load() function may be used to load and execute script in a background thread, by passing an initial argument of true to the function. This usage of load() is very unique and is not typically used to load traditional JavaScript libraries. The require() function cannot be used to execute background scripts.

Require vs. Load

The require() function (added in Synchronet v3.17) is identical in usage to load() with the exception that it will conditionally load and execute the script only if the property name (propname) argument, specified just after the filename argument, is not already defined in the target scope. This prevents redundant loading/compilation/execution of libraries shared among multiple modules. For large libraries or commonly used libraries, consider using require() instead of load() to enhance performance and avoid the possible erroneous redefinition of const variables during subsequent load() operations of the same library.

exit

Libraries should not (normally) call the global exit() method or else the calling script(s) will also terminate, possibly unexpectedly.

Styles

There are 3 main styles of JavaScript libraries included with Synchronet:

Legacy

Leagcy-style JavaScript libraries just define a series of vars, consts or functions which may be referenced, as needed, by a loading script. Legacy-style libraries may be loaded into a distinct scope object or into the caller's global scope, whatever is most convenient for the application.

Example Legacy-style library usage:

load('somedefs.js');
some_function(some_value);

Object

Object-style JavaScript libraries define an object that can by instantiated (like a class, using the new keyword), as needed, by the loading script. You can identify Object-style libraries because they will typically define an object constructor function, some Object.prototype member functions (methods), and perhaps one or more Object.defineProperty() calls to define property getters and setters.

Example Object-style library usage:

load('someobject.js');
var someObj = new SomeObject();
someObj.property = true;
someObj.do_something();

Return

Return-style JavaScript libraries are designed to be loaded with an empty target scope object ({} or new Object) and return the newly constructed library object. You can identify Return-style libraries because they will end with a single this; line.

Example Return-style library usage:

var someLib = load({}, 'somelib.js');
someLib.property = true;
someLib.do_something();

Return-style libraries are the preferred style of digital man, but all styles of JavaScript libraries may found within the Synchronet exec/load directory.