Coralite Type Reference

This document serves as a comprehensive reference for the type definitions used within Coralite. It outlines the structure, state, and relationships of core types involved in parsing, rendering, and managing HTML documents, templates, and components. The following sections provide detailed breakdowns of each type, with tables and internal links for easy navigation.

Core Types #

HTMLData #

Represents HTML file data including path and raw content.

Property Type Description
type 'page' | 'component' The type of HTML file. 'page' for main pages, 'component' for reusable components.
state CoraliteStateDefinitions The initial state for the HTML module.
path CoraliteFilePath The file's path information within the project structure.
content string (optional) The raw HTML string contents of the file (optional, may be omitted for templates).

CoraliteFilePath #

Represents a file's path structure within the project.

Property Type Description
pathname string Full relative path from the project root to the file.
dirname string Directory name containing the file.
filename string The base file name (including extension).

CoralitePath #

Defines root directories for pages and components in a Coralite project.

Property Type Description
pages string The path to the root pages directory.
components string The path to the root components directory.

CoralitePageState #

Represents URL and file path state available during component rendering. This is injected into components as the page object.

Property Type Description
url.pathname string The URL pathname (e.g., /docs/guide/index.html).
url.dirname string The directory name of the URL.
file.pathname string The full physical file path name.
file.dirname string The directory name of the physical file.
file.filename string The base filename.
meta Object<string, string> Metadata extracted from the page's <head>, including title and lang.

CoraliteState #

Union type representing state available for token replacement in components.

Type Description
CoralitePageState URL and file path state.
Object<string, any> Key-value pairs for token replacement.

CoraliteToken #

Represents a token with name and value.

Property Type Description
name string Token identifier.
content string Token placeholder content (e.g. {{ name }}).

CoraliteAttributeToken #

Represents an HTML attribute token linked to its parent element.

Property Type Description
name string Attribute name.
element CoraliteElement Corresponding HTML element for the attribute.
tokens CoraliteToken[] Array of associated tokens.

CoraliteRef #

Represents an element reference with name and element.

Property Type Description
name string Ref identifier.
element CoraliteElement Corresponding HTML element for the ref.

CoraliteTextNodeToken #

Represents a text node token with associated metadata.

Property Type Description
textNode CoraliteTextNode Text node that contains the token.
tokens CoraliteToken[] Array of associated tokens.

CoraliteStateDefinitions #

A collection of state definitions associated with a module.

Property Type Description
(Key) CoraliteStateDefinition Key-value pairs representing state data.
__script__ ScriptContent (optional) Script content for the module.

ScriptContent #

Coralite module script content.

Property Type Description
content string The script content string.
state Object<string, any> Initial state associated with the script.

CoraliteStateDefinition #

Represents a single value that a module can store or process.

Type Description
string | number | boolean Primitive state.
Array An array of state.
Object A plain object.
CoraliteDirective[] Array of directives (e.g., DOCTYPE).
CoraliteAnyNode[] Array of content nodes (elements, text, comments).

CoraliteErrorData #

Error or warning data passed to the onError callback.

Property Type Description
level 'WARN' | 'ERR' | 'LOG' The severity level.
message string The message describing the error or warning.
error Error (optional) Optional error object for tracing.

CoraliteOnError #

Callback function for handling errors and warnings.

JavaScript
Code copied!
  /**
  * @callback CoraliteOnError
  * @param {CoraliteErrorData} data - The error or warning data.
  * @returns {void}
  */

Document and Result Types #

CoraliteComponentState #

Holds tokenized metadata extracted from document attributes, element references and text nodes.

Property Type Description
refs CoraliteRef[] List of element references.
attributes CoraliteAttributeToken[] List of attribute tokens from the document.
textNodes CoraliteTextNodeToken[] List of text node tokens from the document.

CoraliteComponentResult #

Result of document processing containing extracted state and temporary elements.

Property Type Description
state CoraliteStateDefinitions The state definitions extracted from the document.
tempElements CoraliteElement[] Temporary elements created during processing.

CoraliteResult #

Represents a rendered output document with metadata and statistics.

Property Type Description
path CoraliteFilePath The page file path.
content string Raw HTML content of the render process as a string.
duration number (optional) Time taken to render the page in milliseconds.

CoraliteComponentRoot #

Represents the root node of a document containing all content nodes.

Property Type Description
type 'root' Node type.
children CoraliteAnyNode[] | CoraliteDirective[] Document list of elements, text nodes, or directives.

CoraliteComponent #

Represents a complete Coralite document with metadata and rendering structure.

Property Type Description
root CoraliteComponentRoot Array of elements and text nodes in the document.
customElements CoraliteElement[] Custom elements defined in the document.
path CoralitePath & CoraliteFilePath Document's file path.
state Object The document state.

CoraliteDirective #

Represents a directive found in HTML content, like a DOCTYPE declaration.

Property Type Description
type 'directive' Node type.
data string Raw HTML Doctype.
name string Doctype name.
remove boolean (optional) Mark element to be removed from stack.

ParseHTMLResult #

Result of parsing HTML content.

Property Type Description
root CoraliteComponentRoot The root element of the parsed HTML document.
customElements CoraliteElement[] An array of custom elements identified during parsing.
tempElements CoraliteElement[] An array of temporary elements created during the parsing process.
skipRenderElements CoraliteElement[] An array of elements to skip during rendering.

Module and Plugin Types #

CoraliteModule #

A module within Coralite, containing metadata and template structure.

Property Type Description
id string Unique module identifier (the component tag name).
path CoraliteFilePath (optional) File path information for the module.
lineOffset number (optional) Offset for script line numbering.
template CoraliteComponentRoot The module's template AST.
script string (optional) The module's raw JavaScript code.
state CoraliteComponentState Token information extracted from the template.
customElements CoraliteElement[] Custom elements used within the template.
slotElements Object<string, Object<string, CoraliteModuleSlotElement>> Configurations for slots within the component.
isTemplate boolean Indicates if the module has a valid template.

CoraliteModuleSlotElement #

Defines a slot element and its configuration within a module.

Property Type Description
name string Slot name.
element CoraliteElement Corresponding HTML element for the slot.

CoraliteConfig #

Configuration object for a Coralite instance.

Property Type Description
output string (optional) The path to the output directory.
components string The path to the components directory.
pages string The path to the pages directory.
plugins CoralitePluginInstance[] (optional) Optional array of plugin instances.
mode 'production' | 'development' | 'testing' The framework execution mode. Use 'testing' for zero-config test environments.
testing CoraliteTestingConfig (optional) Configuration for testing mode.
skipRenderByAttribute IgnoreByAttribute[] | string[] (optional) Attribute name-value pairs to skip rendering.

CoraliteTestingConfig #

Configuration block for the first-class testing mode.

Property Type Description
mocks Object<string, CoraliteTestingMock> Map of component IDs to their mock definitions.

CoraliteTestingMock #

Defines mock behaviors for a specific component in testing mode.

Property Type Description
server Function Mock implementation of the component's server() block.

CoraliteScriptContext #

Context object passed to the component client function in the browser.

Property Type Description
id string Unique instance identifier (e.g., my-comp-0).
instanceId string Unique instance identifier.
state Proxy The Read/Write unified reactive state.
root HTMLElement The physical DOM element instance of the component.
signal AbortSignal Used for cleaning up event listeners and aborting fetches on unmount.
refs (id: string) => HTMLElement | null A helper function to query elements in the component by their ref name.
observe (key: string, callback: (newVal: any, oldVal: any) => void) => void Registers a callback to execute explicit side-effects on state changes. Automatically cleaned up when the component is disconnected.

CoraliteModuleScript #

Callback signature for module script execution (internal).

JavaScript
Code copied!
  /**
        * @callback CoraliteModuleScript
        * @param {Object} context - The script context
        */

ClientPlugin #

Configuration for client-side plugins (referred to as ScriptPlugin in type definitions).

Property Type Description
name string (optional) Unique identifier/name of the client plugin.
config Object (optional) Static configuration passed from server to client. Available in pluginContext.config.
context (pluginContext: any) => (instanceContext: any) => Object (optional) Two-Phase Resolver function returning helper methods exposed under the plugin namespace.
onBeforeComponentRender function (optional) Hook triggered before a component proxy is created and rendered.
onAfterComponentRender function (optional) Hook triggered after a component DOM is updated in the browser.
onDisconnected function (optional) Hook triggered when a component is unmounted and removed from the DOM.

InstanceContext #

Context for building component instances (internal).

Property Type Description
instanceId string Unique instance identifier.
componentId string Component identifier.
state Object Initial instance state.
page Object Page metadata.

Content Nodes #

CoraliteElement #

Represents a standard HTML element in the content tree.

Property Type Description
type 'tag' Node type.
name string Tag name.
attribs Object<string, string> Element attributes.
children CoraliteAnyNode[] Child nodes.
parent CoraliteContentNode Parent node.

CoraliteTextNode #

Represents a text node within the content tree.

Property Type Description
type 'text' Node type.
data string The text content.
parent CoraliteContentNode Parent element.

CoraliteComment #

Represents an HTML comment.

Property Type Description
type 'comment' Node type.
data string The comment text.
parent CoraliteContentNode Parent element.

CoraliteAnyNode #

Union type representing any content node.

Type Description
CoraliteElement A standard HTML element.
CoraliteTextNode A text node.
CoraliteComment An HTML comment.

CoraliteContentNode #

Union type representing nodes that can have children.

Type Description
CoraliteElement An element tag.
CoraliteComponentRoot The document root.

Plugins, Collections and Events #

IgnoreByAttribute #

Rule for excluding elements from processing based on attributes.

Property Type Description
name string Name of attribute.
value string Value of attribute.

CoraliteCollectionCallbackResult #

Internal result from collection event handlers.

Property Type Description
type 'page' | 'component' Item type.
result any The processed item value.

CoraliteCollectionItem #

An item within a Coralite collection (page or component).

Type Description
HTMLData & { result: any } Combines raw file data with processed results.

CoraliteCollectionEventResult #

Final processed value from a collection event.

Property Type Description
value any The processed value.
type 'page' | 'component' Item type.
id string (optional) Item identifier.

CoraliteCollectionEventSet #

Callback for setting an item in a collection.

JavaScript
Code copied!
  /**
        * @callback CoraliteCollectionEventSet
        * @param {HTMLData} data - The raw file data
        * @returns {Promise<coralitecollectioneventresult>}
          */</coralitecollectioneventresult>

CoraliteCollectionEventDelete #

Callback for deleting an item from a collection.

JavaScript
Code copied!
  /**
        * @callback CoraliteCollectionEventDelete
        * @param {CoraliteCollectionItem} value - The item being deleted
        */

CoraliteCollectionEventUpdate #

Callback for updating an item in a collection.

JavaScript
Code copied!
  /**
        * @callback CoraliteCollectionEventUpdate
        * @param {CoraliteCollectionItem} newValue - The new item
        * @param {CoraliteCollectionItem} oldValue - The old item
        */

CoralitePluginContext #

Context object passed to plugin hooks.

Property Type Description
state Object Current state available to the hook.
page Object Current page metadata.
elements ParseHTMLResult Parsed HTML document (for page hooks).
app Coralite The Coralite instance.
config any The plugin's configuration object.

CoralitePluginGlobalContext #

Shared context across all plugins, mutable during Phase 1.

Property Type Description
app Coralite The Coralite instance.
(Others) any Any properties added by previous plugins in the sequence.

CoralitePluginModule #

The main execution function for a plugin.

JavaScript
Code copied!
  /**
          * @callback CoralitePluginModule
          * @param {any} options - Plugin configuration options
          * @param {Object} context - Rendering context
          */

CoralitePlugin #

Configuration definition for a plugin.

Property Type Description
name string Unique identifier/name of the plugin.
server CoralitePluginServer (optional) Server-side configuration and lifecycle hooks.
client ClientPlugin (optional) Client-side runtime configuration and hooks.

CoralitePluginServer #

Server-side plugin configuration.

Property Type Description
name string (optional) Unique name for server scope. Defaults to plugin name.
config Object (optional) Plugin-specific configuration options.
context (pluginContext: any) => Object (optional) Function evaluated once per build session to return helper methods for component server() blocks.
components string[] (optional) Array of paths to component files registered globally.
(Lifecycle Hooks) function (optional) Server-side hooks: onBeforeBuild, onAfterBuild, onPageSet, onPageUpdate, onPageDelete, onComponentSet, onComponentUpdate, onComponentDelete, onBeforePageRender, onAfterPageRender, onBeforeComponentRender, onAfterComponentRender.

CoralitePluginResult #

Internal result from executing a plugin hook.

Property Type Description
state Object (optional) Partial state to merge.
page Object (optional) Partial page metadata to merge.

CoralitePluginInstance #

A configured and registered plugin instance.

Property Type Description
name string Unique identifier/name of the plugin.
server CoralitePluginServer (optional) Server-side plugin configuration.
client ClientPlugin (optional) Client-side plugin configuration.

CoralitePluginPageSetCallback #

Async callback for onPageSet.

JavaScript
Code copied!
  /**
          * @callback CoralitePluginPageSetCallback
          * @param {Object} context
          * @param {ParseHTMLResult} context.elements - The page AST
          * @param {Object} context.state - The page state
          * @param {Object} context.page - Page metadata
          * @param {CoraliteCollectionItem} context.data - The page data
          * @param {CoraliteInstance} context.app - The Coralite instance
          */

CoralitePluginPageUpdateCallback #

Async callback for onPageUpdate.

JavaScript
Code copied!
  /**
          * @callback CoralitePluginPageUpdateCallback
          * @param {Object} context
          * @param {ParseHTMLResult} context.elements - The updated AST
          * @param {CoraliteCollectionItem} context.newValue - The new page data
          * @param {CoraliteCollectionItem} context.oldValue - The old page data
          * @param {CoraliteInstance} context.app - The Coralite instance
          */

CoralitePluginPageDeleteCallback #

Async callback for onPageDelete.

JavaScript
Code copied!
  /**
          * @callback CoralitePluginPageDeleteCallback
          * @param {CoraliteCollectionItem & { app: Coralite }} context - The deleted page context
          */

CoralitePluginComponentCallback #

Async callback for component lifecycle hooks (set, update).

JavaScript
Code copied!
  /**
          * @callback CoralitePluginComponentCallback
          * @param {CoraliteModule & { app: Coralite }} context - The component context
          */

CoralitePluginBeforePageRenderCallback #

Async callback for onBeforePageRender.

JavaScript
Code copied!
  /**
          * @callback CoralitePluginBeforePageRenderCallback
          * @param {Object} context
          * @param {CoraliteComponent} context.component - The component being rendered
          * @param {Object} context.state - The rendering state
          * @param {Object} context.page - Page metadata
          * @param {CoraliteSession} context.session - The page build session
          * @param {CoraliteInstance} context.app - The Coralite instance
          */

CoralitePluginAfterPageRenderCallback #

Async callback for onAfterPageRender.

JavaScript
Code copied!
  /**
          * @callback CoralitePluginAfterPageRenderCallback
          * @param {Object} context
          * @param {CoraliteResult} context.result - The rendered page result
          * @param {CoraliteSession} context.session - The page build session
          * @param {CoraliteInstance} context.app - The Coralite instance
          * @returns {CoraliteResult | CoraliteResult[] | void}
          */

Constructor and Methods #

Constructor #

Initializes a new Coralite instance using the await createCoralite factory.

JavaScript
Code copied!
  /**
  * @constructor
  * @param {CoraliteConfig} options
  */

Initialise Method #

Initialises the instance by loading components and discovery-only pages.

JavaScript
Code copied!
  /**
      * @returns {Promise<void>}
      */
      Coralite.prototype.initialise = async function () { }
  </void>

Build Method #

Compiles pages and collects results.

JavaScript
Code copied!
  /**
      * @param {string | string[]} [path] - Target paths
      * @param {Object} [options] - Build options
      * @param {function} [callback] - Result transformer
      * @return {Promise<any[]>}
      */
      Coralite.prototype.build = async function (path, options, callback) { }
  </any[]>

Save Method #

Compiles and saves pages to disk.

JavaScript
Code copied!
  /**
      * @param {string | string[]} [path] - Target paths
      * @param {Object} [options] - Save options
      * @returns {Promise<any[]>}
      */
      Coralite.prototype.save = async function (path, options) { }
  </any[]>

Render Method #

Renders a node tree to a raw HTML string.

JavaScript
Code copied!
  /**
  * @param {Object} root - The node tree
  * @returns {string}
  */
  Coralite.prototype.transform = function (root) { }

Get Page Paths Using Custom Element #

Retrieves page paths containing a specific component.

JavaScript
Code copied!
  /**
  * @param {string} path - The component path
  * @returns {string[]}
  */
  Coralite.prototype.getPagePathsUsingCustomElement = function (path) { }

Add Render Queue #

Dynamically adds a page to the current build process.

JavaScript
Code copied!
  /**
  * @param {any} value - Page path or item
  * @param {string} buildId - Current build ID
  */
  Coralite.prototype.addRenderQueue = async function (value, buildId) { }

Create Component #

Internal factory for processing components during rendering.

JavaScript
Code copied!
  /**
     * @param {Object} options
     * @returns {Promise<any>}
     */
    Coralite.prototype.createComponentElement = async function (options, head = true) { }
  </any>

Write File #

Writes a file to the output directory and registers it for protection during build cleanup.

JavaScript
Code copied!
  /**
      * @param {string} dest - Destination path relative to output dir
      * @param {string | Buffer} content - File content
      * @param {Object} [options] - Node.js writeFile options
      * @returns {Promise<string>} Absolute path to the file
      */
      Coralite.prototype.writeFile = async function (dest, content, options) { }
  </string>

Track Output File #

Manually adds an absolute file path to the build cleanup whitelist.

JavaScript
Code copied!
  /**
  * @param {string} path - Absolute file path
  */
  Coralite.prototype.trackOutputFile = function (path) { }

Evaluate Method #

Internal script evaluator for components.

JavaScript
Code copied!
  /**
      * @param {Object} data
      * @returns {Promise<object>}
      */
      Coralite.prototype._evaluate = async function (data) { }
  </object>

Module Linker #

Internal VM module linker for development mode.

JavaScript
Code copied!
  /**
  * @param {Object} path
  * @param {Object} context
  */
  Coralite.prototype._moduleLinker = function (path, context) { }

Trigger Plugin Hook #

Internal hook dispatcher.

JavaScript
Code copied!
  /**
      * @param {string} name
      * @param {any} initialData
      * @return {Promise<any>}
      */
      Coralite.prototype._triggerPluginHook = async function (name, initialData) { }
  </any>

Start Building with Coralite!

Use the scaffolding script to get jump started into your next project with Coralite

Copied commandline!