Suppliers

Learn about sharing and reusing values across multiple scripts and views.

Suppliers are scripts which export one or more named values, for the sole purpose of having those values imported by another script -- either by another supplier, a JS endpoint, or a Mustache endpoint. Suppliers allow for reusing values and functions. All values exported by suppliers exist in the module '📤'.

A general best practice is to keep supplier scripts very small and purpose specific. If you're exporting more than a few values out of a single supplier script, then it's likely worth breaking it out into multiple supplier scripts. Keeping supplier scripts small and purpose specific will enhance readability, performance, and maintainability.

Supplier Types

Choosing a supplier type depends on its purpose and allowed values. Supplier .js files are placed into a sub-directory named '📤', and any directory may have a supplier sub-directory. Suppliers are only visible to the current directory where the supplier directory is located, as well as descendant directories. This allows scoping exported supplier values to only those endpoints which need the values/functions.

Request Supplier

📤/AnyName.js Allowed exports: Primitives (String, Number, Boolean), Map/Object of Primitives, a single instance of a Model, or a Query.

Only model read/query operations are allowed within the supplier. However the endpoint finally using the supplied value may itself perform write operations if allowed by the endpoint.

Function Supplier

📤/{}AnyName.js. Allowed exports: "Utility" functions only. Function Suppliers have very limited functionality. They may not import anything (not even other suppliers). Their primary purpose is to provide functions that perform calculations or transformations on parameters.

Importing Values

Regardless of where the supplier exists in the path hierarchy, and regardless of the supplier's file name, all supplier values are located in the module named '📤'. This creates a simple flat namespace for importing named values.


// Importing specific values:
import {Something, Other, That} from '📤';
        

Endpoint Specific and Pinned Suppliers

Endpoint Specific Supplier

Because suppliers follow the hierarchical REST structure, they have varying levels of specificity for an endpoint. The most specific supplier is one with the same name as the endpoint itself. For example, an endpoint named index.html may also have a supplier named 📤/index.js. As the most specific supplier, only index.html may access values exported by 📤index.js (however index.html may also access other in-scope suppliers).

Pinned Supplier

An extension to an endpoint specific supplier is a "pinned" supplier. Indicate a pinned supplier with the pin emoji, e.g. 📤/📌index.js. Pinned suppliers may be used to hide or re-expose broader/earlier supplied values.

This is especially useful where more strict separation of concerns are desired, for example in the case of Mustache endpoints. The JavaScript developer may want to ensure that regardless of any suppliers along the REST path, only very explicit / strictly supplied values are visible to the Mustache file.