sandbox

Sandbox

A locally sandboxed/isolated environment within a single VM instance

Kind: global class

• Sandbox
  • .global ⇒ Object
  • .compile([name], [template], [compileOpts], [namers], [operations], [director], [store], [log]) ⇒ function
  • .deserialzeFunction(functionString) ⇒ function | null
  • .deserialzeBlock(block, [name], [isAsync]) ⇒ function | undefined
  • .serialzeFunction(func) ⇒ String | null
  • .guid([value], [hyphenate]) ⇒ String

Sandbox.global ⇒ Object

Kind: static property of Sandbox
Returns: Object - The global object. Typically, window when ran within a browser or global when ran on a server

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

Compiles a locally sandboxed async template rendering function

Kind: static method of Sandbox
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.

Param	Type	Description
[name]	String	The name given to the template (omit to generate via 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
[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
[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

Sandbox.deserialzeFunction(functionString) ⇒ function | null

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

Kind: static method of Sandbox
Returns: function | null - The deserialized function

Param	Type	Description
functionString	String	The function string to deserialize

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

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

Kind: static method of Sandbox
Returns: function | undefined - The deserialized function

Param	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

Sandbox.serialzeFunction(func) ⇒ String | null

Serialzes a function

Kind: static method of Sandbox
Returns: String | null - The serialized function

Param	Type	Description
func	function	The function to serialize

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

Generates a GUID or formats an existing value

Kind: static method of Sandbox
Returns: String - the generated GUID

Param	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]	Boolean	true	true to include hyphens in generated result