Sandbox

new Sandbox()

A locally sandboxed/isolated environment within a single VM instance

Sandbox.compile([name], [template], [compileOpts], [namers], [operations], [director], [store], [log]) ⇒ function

Compiles a locally sandboxed async template rendering function

Parameters

Name	Type	Description
[name]	String	The name given to the template (omit to generate via Sandbox.guid)
[template]	String	The template content that will be used by the renderer. Omit to load the template from cache.
[compileOpts]	TemplateOpts	The TemplateOpts
[namers]	Object	One or more functions responsible for formatting template names into a full path name that is consumable by read/write. Each function accepts the following arguments: 1. {Object} namers An object that contains a property for each available naming function. 1. {String} partialName The name of the partial that will be converted into a name suitable for a read operation. 1. {(TemplateOpts | Function(name:String)😗)} optional Either the TemplateOpts or a function that takes a single name argument and returns the option value. 1. {URLSearchParams} [params] The URLSearchParams that should be used in the converted name. 1. {Object} storage The storage object that can contain metadata used by naming operations. 1. {Boolean} forContent The flag indicating if the converted name is being used to capture partials. 1. {String} extension The file extension override for the converted name (omit to use the default extension set in the options). 1. {Boolean} forContext The flag indicating if the converted name is being used to capture context.
[namers.namer]	function	The default naming function that will be used.
[namers.namerSuper]	function	The naming function to use when a operations[].read function throws an error. The next reader called in the operations[] list will use the name generated by this reader.
[operations]	Array.<Object>	One or more functions and/or objects that will handle render-time read/write operations.
[operations[].read]	function	The reader is an async function responsible for reading partial template content/modules/etc during render-time when a partial template cannot be found within includes. When options.cacheRawTemplates is truthy an attempt will be made to add any missing/read partials into storage.data in order to prevent unnecessary template partial reads for repeated includes. Read functions should not reference any external scope other than the global object space. The following arguments will be passed: 1. {String} name The name of the partial that will be read. The read function may be invoked without a name parameter when the intent is to capture all partials in a single read opteration that will be included. 1. {String} path The path to the partial that will be read. The read function may be invoked without a path parameter when the intent is to capture all partials in a single read opteration that will be included. 1. {String} ext The path file extension to the partial that will be read. The read function may be invoked without an ext parameter when the intent is to capture all partials in a single read opteration that will be included. 1. {Boolean} forContent The flag indicating that the read is for content. Otherwise, the read is for rendering functions. 1. {(TemplateOpts | Function(name:String)😗)} optional Either the TemplateOpts or a function that takes a single name argument and returns the option value. 1. {URLSearchParams} [params] The URLSearchParams that should be used during the read 1. {Object} storage The storage object that can contain metadata for read operations and should contain a data object that stores each of the read paratial template content/metadata. 1. {Function} [formatter] The function that will format reads/writes during include discovery (if any). The formatting function takes 1 or 2 arguments with the first being the content that will be formatted and the second being options.readFormatOptions for reads and options.writeFormatOptions for writes. The returned result should be a valid string. 1. {Boolean} [close] A flag indicating whether or not any resources used during the read should be closed/cleaned up after the read completes. Closure may be dependent upon the policy set on the options. 1. {Object} [log] A logger that can contain functions for each of the following: error/warn/info/debug. Read functions can return the partial template content and/or it can be set on the storage.data. Returning true will stop any further rendering from processing resulting in the rendering function returning a blank string.
[operations[].write]	function	The write function that will be used for writting newly discovered template sources. Accepts the same arguments as operations[].read and all scoped functions will be available. Can return a rendering function that will prevent further iteration of any subsequent operations[].write invocations.
[operations[].finish]	function	An async function that can perform cleanup tasks for a reader. Arguments passed are storage, optional and log as described for operations[].read. after rendering has completed. Arguments passed are storage, optional and log as described for operations[].read. All functions defined within operations[].scopes will be available by name.
[operations[].scopes]	Array.<function()>	Zero or more functions that will be in scope when the read function is called. Scoped functions can assit with complex read/write that can benefit from separate supporting functions. For example, [myFunc(){}] could be referenced like async function myReader(){ myFunc(); ... }.
[director]	Director	The Director that will be for extracting Director.directives
[store]	Object	The private storage set during compilation that will be passed during naming/reads. Contents should only contain valid JSON properties that can be serialized/deserialized.
[store.data]	Object	The cached partials that can be included in the template with the name of the template as a property of the object
[store.data[].name]	String	The name of the partial template
[store.data[].content]	String	The partial template content
[store.data[].params]	Object	The parameters that will be added to scope when the template is parsed
[log]	Object	The log flags that will determine what output will be sent to the console (if any) during rendering
[log.debug]	Boolean	true to output console.debug level log
[log.info]	Boolean	true to output console.info level log
[log.warn]	Boolean	true to output console.warn level log
[log.error]	Boolean	true to output console.error level log

Returns

• function — The rendering async function that returns a template result string based upon the provided context. The following arguments apply:

1. {Object} context The context JSON that can be used as data during rendering
2. {TemplateOpts} [renderOptions] The rendering options that will superceed any compile-time options
3. {Function} [readFormatter] The function that will format read partials during include discovery (if any). The formatting function takes 1 or 2 arguments with the first being the content that will be formatted and the second being the options.readFormatOptions. The returned result should be a valid string.
4. {Function} [writeFormatter] The function that will format written sources during include discovery (if any). The formatting function takes 1 or 2 arguments with the first being the content that will be formatted and the second being the options.writeFormatOptions. The returned result should be a valid string.
5. {Object} [sharedStore] An object used for in-memory storage space that can be shared between rendering functions. This ensures that updated data within a renderer execution will be retained between rendering calls from the same renderer or different renderers that are passed the same shared store.

Sandbox.deserialzeFunction(functionString) ⇒ function | null

Deserialzes a function string within a locally sandboxed environment (only global variables are accessible)

Parameters

Name	Type	Description
functionString	String	The function string to deserialize

Returns

• function | null — The deserialized function

Sandbox.deserialzeBlock(block, [name], [isAsync]) ⇒ function | undefined

Deserialzes a code block iwthin a locally sandboxed environment (only global variables are accessible)

Parameters

Name	Type	Description
block	String | function	The code block to deserialize
[name]	String	A name that will be given to the function
[isAsync]	Boolean	true when the function is async

Returns

• function | undefined — The deserialized function

Sandbox.serialzeFunction(func) ⇒ String | null

Serialzes a function

Parameters

Name	Type	Description
func	function	The function to serialize

Returns

• String | null — The serialized function

Sandbox.guid([value], [hyphenate=true]) ⇒ String

Generates a GUID or formats an existing value

Parameters

Name	Type	Default	Description
[value]	String		when present, will format the value by add any missing hyphens (if hyphenate=true) instead of generating a new value
[hyphenate=true]	Boolean	true	true to include hyphens in generated result

Returns

• String — the generated GUID

Sandbox.global ⇒ Object

Returns

• Object — The global object. Typically, window when ran within a browser or global when ran on a server