====== Libraries ======
JavaScript libraries are ''.js'' files that are typically located in the ''[[dir:exec]]/[[dir:load]]'' directory (for unmodified-stock libraries) or the ''[[dir: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:
<code javascript>
load('somedefs.js');
some_function(some_value);
</code>

==== 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:
<code javascript>
load('someobject.js');
var someObj = new SomeObject();
someObj.property = true;
someObj.do_something();
</code>

==== 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:
<code javascript>
var someLib = load({}, 'somelib.js');
someLib.property = true;
someLib.do_something();
</code>

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

==== Index ====
Articles documenting the usage of specific JavaScript Libraries are listed here:
{{indexmenu>.}}

===== See Also =====
  * [[:custom:javascript:|JavaScript]]
  * [[https://gitlab.synchro.net/main/sbbs/-/tree/master/exec/load|load Directory contents from Synchronet Git Repo]]

{{tag>javascript}}