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.

Property	Type	Description
`page_url_pathname`	`string`	The URL pathname.
`page_url_dirname`	`string`	The directory name of the URL.
`page_pathname`	`string`	The file path name.
`page_dirname`	`string`	The directory name of the file.
`page_filename`	`string`	The filename.

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.

  /**
  * @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.
`skipRenderByAttribute`	`IgnoreByAttribute[] \| string[]` (optional)	Attribute name-value pairs to skip rendering.

CoraliteScriptContext #

Context object passed to the component script in the browser.

Property	Type	Description
`instanceId`	`string`	Unique instance identifier (e.g., `my-comp-0`).
`componentId`	`string`	The component's tag name.
`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.
`page`	`Object`	Static page metadata (url, file).

CoraliteModuleScript #

Callback signature for module script execution (internal).

  /**
        * @callback CoraliteModuleScript
        * @param {Object} context - The script context
        */

ClientPlugin #

Configuration for client-side plugins.

Property	Type	Description
`data`	`function(any): any` (optional)	Initial data fetching function, results merged into state.
`context`	`Object<string, function>` (optional)	Curried utilities added to script context.
`config`	`Object` (optional)	Static config passed from server to client.

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.

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

CoraliteCollectionEventDelete #

Callback for deleting an item from a collection.

  /**
        * @callback CoraliteCollectionEventDelete
        * @param {CoraliteCollectionItem} value - The item being deleted
        */

CoraliteCollectionEventUpdate #

Callback for updating an item in a collection.

  /**
        * @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.

  /**
          * @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 name.
`method`	`function` (optional)	Main server-side function.
`client`	`ClientPlugin` (optional)	Client-side script configuration.
`onPageSet`	`function` (optional)	Triggered when a page is created.

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 name.
`components`	`HTMLData[]`	Components registered by the plugin.

CoralitePluginPageSetCallback #

Async callback for onPageSet.

  /**
          * @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.

  /**
          * @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.

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

CoralitePluginComponentCallback #

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

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

CoralitePluginBeforePageRenderCallback #

Async callback for onBeforePageRender.

  /**
          * @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.

  /**
          * @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.

  /**
  * @constructor
  * @param {CoraliteConfig} options
  */

Initialise Method #

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

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

Build Method #

Compiles pages and collects results.

  /**
      * @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.

  /**
      * @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.

  /**
  * @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.

  /**
  * @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.

  /**
  * @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.

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

Evaluate Method #

Internal script evaluator for components.

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

Module Linker #

Internal VM module linker for development mode.

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

Trigger Plugin Hook #

Internal hook dispatcher.

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

Coralite Type Reference

Start Building with Coralite!