Sandbox

Sandbox

A locally sandboxed/isolated environment within a single VM instance

Constructor

new Sandbox()

Source:

Members

(static) global

Source:

Methods

(static) compile(nameopt, templateopt, compileOptsopt, namersopt, operationsopt, directoropt, storeopt, logopt) → {function}

Compiles a locally sandboxed async template rendering function

Source:
Parameters:
Name Type Attributes Description
name String <optional>

The name given to the template (omit to generate via Sandbox.guid)
template String <optional>

The template content that will be used by the renderer. Omit to load the template from cache.
compileOpts TemplateOpts <optional>

The TemplateOpts
namers Object <optional>

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.
  2. {String} partialName The name of the partial that will be converted into a name suitable for a read operation.
  3. {(TemplateOpts | Function(name:String):*)} optional Either the TemplateOpts or a function that takes a single name argument and returns the option value.
  4. {URLSearchParams} [params] The URLSearchParams that should be used in the converted name.
  5. {Object} storage The storage object that can contain metadata used by naming operations.
  6. {Boolean} forContent The flag indicating if the converted name is being used to capture partials.
  7. {String} extension The file extension override for the converted name (omit to use the default extension set in the options).
  8. {Boolean} forContext The flag indicating if the converted name is being used to capture context.
Name Type Attributes Description
namer function <optional>

The default naming function that will be used.
namerSuper function <optional>

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> <optional>

One or more functions and/or objects that will handle render-time read/write operations.

Name Type Attributes Description
read function <optional>

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.
  2. {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.
  3. {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.
  4. {Boolean} forContent The flag indicating that the read is for content. Otherwise, the read is for rendering functions.
  5. {(TemplateOpts | Function(name:String):*)} optional Either the TemplateOpts or a function that takes a single name argument and returns the option value.
  6. {URLSearchParams} [params] The URLSearchParams that should be used during the read
  7. {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.
  8. {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.
  9. {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.
  10. {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.
write function <optional>

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.
finish function <optional>

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.
scopes Array.<function()> <optional>

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 <optional>

The Director that will be for extracting Director.directives
store Object <optional>

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.

Name Type Attributes Description
data Object <optional>

The cached partials that can be included in the template with the name of the template as a property of the object

Name Type Attributes Description
name String <optional>

The name of the partial template
content String <optional>

The partial template content
params Object <optional>

The parameters that will be added to scope when the template is parsed
log Object <optional>

The log flags that will determine what output will be sent to the console (if any) during rendering

Name Type Attributes Description
debug Boolean <optional>

true to output console.debug level log
info Boolean <optional>

true to output console.info level log
warn Boolean <optional>

true to output console.warn level log
error Boolean <optional>

true to output console.error level log
Returns:
Type:
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.

(static) deserialzeBlock(block, nameopt, isAsyncopt) → {function|undefined}

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

Source:
Parameters:
Name Type Attributes Description
block String | function

The code block to deserialize
name String <optional>

A name that will be given to the function
isAsync Boolean <optional>

true when the function is async
Returns:
Type:
function | undefined

The deserialized function

(static) deserialzeFunction(functionString) → {function|null}

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

Source:
Parameters:
Name Type Description
functionString String

The function string to deserialize
Returns:
Type:
function | null

The deserialized function

(static) guid(valueopt, hyphenateopt) → {String}

Generates a GUID or formats an existing value

Source:
Parameters:
Name Type Attributes Default Description
value String <optional>

when present, will format the value by add any missing hyphens (if hyphenate=true) instead of generating a new value
hyphenate Boolean <optional>
 true

true to include hyphens in generated result
Returns:
Type:
String

the generated GUID

(static) serialzeFunction(func) → {String|null}

Serialzes a function

Source:
Parameters:
Name Type Description
func function

The function to serialize
Returns:
Type:
String | null

The serialized function


1.0.0 (2019-12-16)

Full Changelog