cachier

Cachier

The default persistence cache manager that uses a simple object mapping for Cachier.read/Cachier.write operations. All caching is maintained in-memory. Template, partial and context Cachier.read operations use either window.fetch (browsers) or the https module (Node.js) to capture partial template content. Compiled template Cachier.read operations are handled via dynamic import/require (if used). Cachier.write operations are typically written to memory, but can also be configured to POST template, partials and/or context over HTTP/S.

Kind: global class

• Cachier
  • new Cachier([opts], [readFormatter], [writeFormatter], [log])
  • instance
    • .options ⇒ TemplateOpts
    • .metadata ⇒ Object
    • .readFormatter ⇒ function
    • .writeFormatter ⇒ function
    • .log ⇒ Object
    • .operations ⇒ Object | Array.<Object> | function | function | function | Array.<function()>
    • .readWriteNames ⇒ Object | Object | Object
    • .registerHelper(func)
    • .unregister(name)
    • .registerPartial(name, contentOrParams, [extension]) ⇒ String
    • .getRegistered(name, [params], [extension]) ⇒ Object
    • .register([data], [read], [write]) ⇒ Object
    • .compile(name, [template], [params], [extension]) ⇒ function
    • .read(name, [forContent], [extension], [params]) ⇒ Object
    • .write(name, data, [forContent], [extension], [params]) ⇒ function | undefined
    • .clear([all])
    • .modules(optional) ⇒ Object
    • .readWriteName(name, optional, [params], store, forContent, [extension], forContext) ⇒ String
  • static
    • .contentURL(name, opts) ⇒ Object
    • .waiter(proms, [errMsg], [capture]) ⇒ Array | undefined

new Cachier([opts], [readFormatter], [writeFormatter], [log])

Constructor

Param	Type	Description
[opts]	TemplateOpts	the TemplateOpts
[readFormatter]	function	The function(string, readFormatOptions) that will return a formatted string for reading data using the options.readFormatOptions from TemplateOpts as the formatting options. Typically reads are for HTML minification and/or beautifying. NOTE: Use with caution as syntax errors may result depending on the formatter used and the complexity of the data being formatted!
[writeFormatter]	function	The function(string, writeFormatOptions) that will return a formatted string for writting data using the options.writeFormatOptions from TemplateOpts as the formatting options. Typically reads are for JS minification and/or beautifying. NOTE: Use with caution as syntax errors may result depending on the formatter used and the complexity of the data being formatted!
[log]	Object	The log for handling logging output
[log.debug]	function	A function that will accept debug level logging messages (i.e. debug('some message to log'))
[log.info]	function	A function that will accept info level logging messages (i.e. info('some message to log'))
[log.warn]	function	A function that will accept warning level logging messages (i.e. warn('some message to log'))
[log.error]	function	A function that will accept error level logging messages (i.e. error('some message to log'))

cachier.options ⇒ TemplateOpts

Kind: instance property of Cachier
Returns: TemplateOpts - The template compile options

cachier.metadata ⇒ Object

Kind: instance property of Cachier
Returns: Object - The compilation metadata that will be passed into Sandbox.compile
Access: protected

cachier.readFormatter ⇒ function

Kind: instance property of Cachier
Returns: function - The read formatting function that takes 1 or 2 arguments with the first being the content that will be formatted and the second being options.readFormatOptions

cachier.writeFormatter ⇒ function

Kind: instance property of Cachier
Returns: function - The write formatting function that takes 1 or 2 arguments with the first being the content that will be formatted and the second being options.writeFormatOptions

cachier.log ⇒ Object

Kind: instance property of Cachier
Returns: Object - The optional log used by the Cachier

cachier.operations ⇒ Object | Array.<Object> | function | function | function | Array.<function()>

Kind: instance property of Cachier
Returns: Object | Array.<Object> - [operations] One or more operation objects that will handle render-time reads/writesfunction - [operations[].read] 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.function - [operations[].write] 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.function - [operations[].finish] An async function that can perform cleanup tasks for a reader. Arguments passed are storage, optional and log as described for operations[].read.Array.<function()> - [operations[].scopes] Zero or more functions that will be in scope when the read function is called. Scoped functions can assit with complex read/write operations that can benefit from separate supporting functions. For example, [myFunc(){}] could be referenced like async function myReader(){ myFunc(); ... }.

cachier.readWriteNames ⇒ Object | Object | Object

Kind: instance property of Cachier
Returns: Object - namers One or more async functions responsible for formatting template names into a full path name consumable by read/write oprtationsObject - namers.namer The default naming functionObject - namers.namerSuper The naming function to use when a Cachier.operations function throws an error. The next reader called in the Cachier.operations list will use the name generated by this reader.
See: Cachier.readWriteName for parameter details

cachier.registerHelper(func)

Registers a directive function that can be used within template interpolations

Kind: instance method of Cachier

Param	Type	Description
func	function	A named function that has no external scope dependencies/closures other than those exposed via templates during rendering

cachier.unregister(name)

Unregisters a partial template from cache

Kind: instance method of Cachier

Param	Type	Description
name	String	The template name that uniquely identifies the template content

cachier.registerPartial(name, contentOrParams, [extension]) ⇒ String

Registers and stores a partial template in-memory. Use Cachier.register to write partials to cache (Cachier)

Kind: instance method of Cachier
Returns: String - The partial content

Param	Type	Default	Description
name	String		The raw template name (i.e. not from Cachier.readWriteName)
contentOrParams	String | URLSearchParams		Either the partial template content string to register or the URLSearchParams that will be passed during the content read
[extension]	String	options.defaultExtension	Optional override for a file extension designation for the partial

cachier.getRegistered(name, [params], [extension]) ⇒ Object

Retrieves a template, partial or context that resides in-memory.

Kind: instance method of Cachier
Returns: Object - A copy of the generated data from Cachier.registerPartial

Param	Type	Default	Description
name	String		The raw template name (i.e. not from Cachier.readWriteName)
[params]	URLSearchParams		Any parameters designated during Cachier.registerPartial
[extension]	String	options.defaultExtension	Optional override for a file extension designation for the template, partial or context designated during Cachier.registerPartial

cachier.register([data], [read], [write]) ⇒ Object

Registers and caches the template, one or more partial templates and/or context JSON.

Kind: instance method of Cachier
Returns: Object - An object that contains the registration results:

• data The object that contains the template, partial fragments and/or context that have been registered
  • name The name that uniquely identifies the template, partial or context
  • content The raw content of the template, partial or context
  • extension The template file extension designation
  • params The URLSearchParams passed during the initial content read
  • fromRead A flag that indicates that the data was set from a read operation

Param	Type	Description
[data]	Array.<Object>	The template, partials and/or context to register.
data[].name	String	The name that uniquely identifies the template, partial or context
[data[].content]	String	The raw content that will be registered. Omit when read === true to read content from cache.
[data[].params]	URLSearchParams	The URLSearchParams that will be passed during the content read (ignored when content is specified).
[data[].extension]	String	Optional override for a file extension designated for a template, partial or context.
[read]	Boolean	When true, an attempt will be made to also Cachier.read the template, partials and context that do not have a content property set.
[write]	Boolean	When true, an attempt will be made to also Cachier.write the template, partials and context that have a content property set.

cachier.compile(name, [template], [params], [extension]) ⇒ function

Compiles a locally sandboxed async template rendering function and when applicable, stores the function in cache

Kind: instance method of Cachier
Returns: function - The return function from Sandbox.compile

Param	Type	Description
name	String	The template name that uniquely identifies the primary template content
[template]	String | Boolean	The raw template content, true to read from cache before compilation. Omit to load the template content from cache when the returned rendering function is called.
[params]	URLSearchParams	Any URL search parmeters that will be passed when capturing the primary template and/or context when needed
[extension]	String	The file extension designation for the template

cachier.read(name, [forContent], [extension], [params]) ⇒ Object

Reads either template content or template code from internal cache. When options.partialsURL is set to an HTTPS URL and the read is for partial content, A GET call to window.fetch is made when running within browsers or to the https module when running on the server. The partial name will be appended to options.partialsURL (e.g. https://example.com/some/id.html where some/id.html is the the partial's Cachier.readWriteName and options.partialsURL is set to https://example.com). When options.partialsURL is omitted reading of template partial content will be limited to reading from memory. Compiled template source code is alwaysread from memory only.

Kind: instance method of Cachier
Returns: Object - An object read from cache that contains either the template content or module.

Returned template content properties:

• name The template name that uniquely identifies the template content
• content The template content
• extension The template file extension designation

Returned module properties:

• name The template name that uniquely identifies the template content
• func The module function generated from the code

Param	Type	Description
name	String	The template name that uniquely identifies the template content
[forContent]	Boolean	true to read a template content, false to read the template source code
[extension]	String	The file extension designation (only used when forContent is truthy)
[params]	URLSearchParams	The URLSearchParams to pass for the read (only used when forContent is truthy)

cachier.write(name, data, [forContent], [extension], [params]) ⇒ function | undefined

Writes either template content or template code from internal cache. When options.partialsURL is set to an HTTPS URL and the read is for partial content, A POST call to window.fetch is made when running within browsers or to the https module when running on the server. The partial name will be appended to options.partialsURL (e.g. https://example.com/some/id.html where some/id.html is the the partial's Cachier.readWriteName and options.partialsURL is set to https://example.com). When options.partialsURL is omitted writting of template partial content will be limited to writes to memory. Compiled template source code is alwayswritten to memory only.

Kind: instance method of Cachier
Returns: function | undefined - Optionally return the compiled/written module function

Param	Type	Description
name	String	The template name that uniquely identifies the template content
data	String | function	The data to write. For content, data should be a string. Otherwise data should be a function or a function string.
[forContent]	Boolean	true to read a template content, false to read the template source code
[extension]	String	The file extension designation (only used when forContent is truthy)
[params]	URLSearchParams	The URLSearchParams to pass for the write (only used when forContent is truthy)

cachier.clear([all])

Clears the cache

Kind: instance method of Cachier

Param	Type	Default	Description
[all]	Boolean	false	true to clear all unassociated cache instances when possible

cachier.modules(optional) ⇒ Object

Kind: instance method of Cachier
Returns: Object - The object that contains the modules used by the Cachier implementation

Param	Type	Description
optional	TemplateOpts | function	Either the TemplateOpts or a function that takes a single name argument and returns the option value

cachier.readWriteName(name, optional, [params], store, forContent, [extension], forContext) ⇒ String

Converts template names into a full path name consumable by read/write oprtations. Each function from Cachier.readWriteNames will be executed in order using the same arguments as Cachier.readWriteName as well as an additional last agument being the return value from the previous function invocation.

Kind: instance method of Cachier
Returns: String - The full template name

Param	Type	Description
name	String	The name of the template, partial or context that will be converted into a name suitable for a read operation
optional	TemplateOpts | function	Either the TemplateOpts or a function that takes a single name argument and returns the option value
[params]	URLSearchParams	The parameters that should be used in the converted name
store	Object	The storage object that can contain metadata used by naming operations
forContent	Boolean	The flag indicating if the converted name is being used to capture partials
[extension]	String	The file extension override for the converted name (omit to use the default extension set in the options)
forContext	Boolean	The flag indicating if the converted name is being used to capture context

Cachier.contentURL(name, opts) ⇒ Object

Extracts the proper URL and option name used for a particular template, partial or context

Kind: static method of Cachier
Returns: Object - The extracted content that contains a url property and a optionName that describes the option used for the URL

Param	Type	Description
name	String	The template, partial or context name
opts	TemplateOpts	The template options

Cachier.waiter(proms, [errMsg], [capture]) ⇒ Array | undefined

Waits for promises to finish and throws commulative errors into a single meaningful stack while continuing to process subsequent promises in the array. When an error is thrown and capture === true, it will also contain a results property that contains either each result from an awaited promise or an error thrown when waiting for the promise to complete.

Kind: static method of Cachier
Returns: Array | undefined - When capture === true, the awaited promise results are retuend. When an error occurs, the value at the given index will contain the error instead. When capture !== true nothing is captured/returned.

Param	Type	Default	Description
proms	Array.<Promise>		The promises to wait for.
[errMsg]	String	'One or more pomises failed'	The message to use when any errors occur.
[capture]	Boolean	true	When true each promise results/errors will be captured and returned. Otherwise, nothing will be captured