Coherent.js

Coherent.js API Reference

This document provides a comprehensive reference for all public APIs available in Coherent.js.

Pure Object Philosophy: Coherent.js emphasizes factory functions over class instantiation. Throughout this API reference, we recommend using factory functions for a pure JavaScript object approach.

Supported Imports

Use only the package entrypoints:

import { render } from '@coherent.js/core';
import { hydrate, autoHydrate } from '@coherent.js/client';

Core Rendering

render(component, options?)

Renders a Coherent.js component to an HTML string.

Parameters:

  • component (CoherentNode): The component to render
  • options (Object, optional): Rendering options

Returns: String - The rendered HTML

Example:

import { render } from '@coherent.js/core';

const component = {
  div: {
    className: 'greeting',
    children: [
      { h1: { text: 'Hello, World!' } }
    ]
  }
};

const html = render(component);
// Output: <div class="greeting"><h1>Hello, World!</h1></div>

Options:

  • enableCache (boolean): Enable caching (default: true)
  • enableMonitoring (boolean): Enable performance monitoring (default: false)
  • minify (boolean): Minify output HTML
  • maxDepth (number): Maximum tree depth
  • cacheSize (number): Cache size limit
  • cacheTTL (number): Cache TTL in ms
  • scoped (boolean): Enable CSS scoping (alias of encapsulate)
  • encapsulate (boolean): Enable CSS scoping

Returns: string - The rendered HTML

Example:

import { render } from '@coherent.js/core';

const App = () => ({
  html: {
    children: [
      {
        head: {
          children: [
            { title: { text: 'My App' } },
            { meta: { charset: 'utf-8' } }
          ]
        }
      },
      {
        body: {
          className: 'app',
          children: [
            { h1: { text: 'Welcome!' } }
          ]
        }
      }
    ]
  }
});

const html = render(App(), {
  enableCache: true,
  enableMonitoring: false,
  minify: true,
  encapsulate: true
});

Streaming

Streaming rendering is not currently part of the stable public API surface.

Component Utilities

createComponent(renderFunction)

Creates a component from a render function.

Parameters:

  • renderFunction (Function): A function that returns a CoherentNode

Returns: Function - A component function

Example:

import { createComponent } from '@coherent.js/core';

const Greeting = createComponent(({ name }) => ({
  div: {
    children: [
      { h1: { text: `Hello, ${name}!` } }
    ]
  }
}));

withState(initialState, options?)

Adds reactive state management to a component with automatic re-rendering on state changes.

Parameters:

  • initialState (Object): The initial state object
  • options (Object, optional): State management options
    • debug (Boolean): Enable debug logging for state changes
    • middleware (Array): Array of middleware functions to apply to state changes
    • validator (Function): Function to validate state changes

Returns: Function - A higher-order component function that wraps the component with state

Example:

import { withState } from '@coherent.js/core';

// Basic state management
const Counter = withState({ count: 0 })((props) => {
  const { state, stateUtils } = props;
  const { setState } = stateUtils;
  
  return {
    div: {
      'data-coherent-component': 'counter',
      children: [
        { p: { text: `Count: ${state.count}` } },
        { 
          button: { 
            text: 'Increment', 
            onclick: () => setState({ count: state.count + 1 })
          }
        },
        { 
          button: { 
            text: 'Reset', 
            onclick: () => setState({ count: 0 })
          }
        }
      ]
    }
  };
});

// With options and debugging
const TodoApp = withState({
  todos: [],
  filter: 'all',
  newTodo: ''
}, {
  debug: true, // Logs all state changes
  validator: (newState) => {
    if (newState.todos && !Array.isArray(newState.todos)) {
      throw new Error('todos must be an array');
    }
    return true;
  }
})((props) => {
  const { state, stateUtils } = props;
  const { setState } = stateUtils;
  
  const addTodo = () => {
    if (state.newTodo.trim()) {
      setState({
        todos: [...state.todos, {
          id: Date.now(),
          text: state.newTodo.trim(),
          completed: false
        }],
        newTodo: ''
      });
    }
  };
  
  return {
    div: {
      'data-coherent-component': 'todo-app',
      children: [
        {
          input: {
            type: 'text',
            value: state.newTodo,
            placeholder: 'Add new todo...',
            oninput: (e) => setState({ newTodo: e.target.value })
          }
        },
        {
          button: {
            text: 'Add Todo',
            onclick: addTodo
          }
        },
        {
          ul: {
            children: state.todos.map(todo => ({
              li: { 
                text: todo.text,
                className: todo.completed ? 'completed' : ''
              }
            }))
          }
        }
      ]
    }
  };
});

State Management API:

The component receives the following props:

  • state (Object): Current state object
  • stateUtils (Object): State management utilities
    • setState(newState): Update state (triggers re-render)
    • getState(): Get current state
    • resetState(): Reset to initial state
    • subscribe(callback): Subscribe to state changes

memo(component, keyFunction?)

Memoizes a component to prevent unnecessary re-renders.

Parameters:

  • component (Function): The component to memoize
  • keyFunction (Function, optional): A function that returns a cache key based on props

Returns: Function - A memoized component function

Example:

import { memo } from '@coherent.js/core';

const ExpensiveComponent = memo(
  (context) => {
    // Expensive computation here
    return { div: { text: computeResult(context.data) } };
  },
  (context) => context.data.id // Custom key function
);

compose(...components)

Composes multiple components into a single component.

Parameters:

  • ...components (Function[]): Components to compose

Returns: Function - A composed component function

Example:

import { compose } from '@coherent.js/core';

const Header = () => ({ header: { /* ... */ } });
const Main = () => ({ main: { /* ... */ } });
const Footer = () => ({ footer: { /* ... */ } });

const Layout = compose(Header, Main, Footer);

Conditional Rendering

when(condition, trueComponent, falseComponent?)

Renders one of two components based on a condition.

Parameters:

  • condition (any): The condition to evaluate
  • trueComponent (CoherentNode): Component to render if condition is truthy
  • falseComponent (CoherentNode, optional): Component to render if condition is falsy

Returns: CoherentNode - The appropriate component

Example:

import { when } from '@coherent.js/core';

const UserProfile = (context) => ({
  div: {
    children: [
      when(context.user,
        { p: { text: `Welcome, ${context.user.name}!` } },
        { p: { text: 'Please log in' } }
      )
    ]
  }
});

forEach(array, renderFunction)

Renders an array of items using a render function.

Parameters:

  • array (Array): The array of items to render
  • renderFunction (Function): A function that returns a CoherentNode for each item

Returns: Array - An array of rendered components

Example:

import { forEach } from '@coherent.js/core';

const TodoList = (context) => ({
  ul: {
    children: forEach(context.todos, (todo) => ({
      li: { 
        text: todo.text,
        className: todo.completed ? 'completed' : 'pending'
      }
    }))
  }
});

Performance Monitoring

performanceMonitor.start()

Starts performance monitoring.

Returns: String - A unique render ID

performanceMonitor.end(renderId)

Ends performance monitoring for a specific render.

Parameters:

  • renderId (String): The render ID returned by start()

performanceMonitor.getStats()

Gets current performance statistics.

Returns: Object - Performance metrics

performanceMonitor.reset()

Resets performance statistics.

performanceMonitor.getRecommendations()

Gets performance optimization recommendations.

Returns: Array - Array of recommendation objects

Database Layer

createDatabaseManager(config)

✅ Recommended: Creates a database manager instance using factory function.

Parameters:

  • config (Object): Database configuration

Returns: DatabaseManager - A database manager instance

Example:

import { createDatabaseManager } from '@coherent.js/core';

// Recommended approach
const db = createDatabaseManager({
  type: 'sqlite',
  database: ':memory:'
});

createQuery(config)

✅ Recommended: Creates a query builder instance using factory function.

Parameters:

  • config (Object): Query configuration

Returns: QueryBuilder - A query builder instance

Example:

import { createQuery } from '@coherent.js/core';

// Pure object approach
const query = createQuery({
  table: 'users',
  select: ['id', 'name'],
  where: { active: true }
});

executeQuery(query, database?)

✅ Recommended: Executes a query created with factory functions.

Parameters:

  • query (Object): Query object from createQuery
  • database (DatabaseManager, optional): Database instance

Returns: Promise - Query results

Example:

import { createQuery, executeQuery, createDatabaseManager } from '@coherent.js/core';

const db = createDatabaseManager({ type: 'sqlite', database: ':memory:' });
const query = createQuery({ table: 'users', select: ['*'] });
const results = await executeQuery(query, db);

Direct Class Access (Advanced Usage)

Note: While direct class access is available for advanced use cases, we recommend using factory functions for consistency with the pure object philosophy.

new DatabaseManager(config)

Alternative: Direct class instantiation for advanced usage.

new QueryBuilder(options)

Alternative: Direct class instantiation for advanced usage.

Client-side Hydration

hydrate(element, component, props?, options?)

Hydrates a DOM element with a Coherent component to enable client-side interactivity.

Parameters:

  • element (HTMLElement): The DOM element to hydrate
  • component (Function): The Coherent component function
  • props (Object, optional): Component props
  • options (Object, optional): Hydration options
    • initialState (Object): Initial state for stateful components
    • enableCache (Boolean): Enable component caching (default: true)
    • validateInput (Boolean): Enable input validation (default: false)

Returns: HydratedComponentInstance - Hydrated component instance with methods

Example:

import { hydrate } from '@coherent.js/client';
import { Counter } from './components/Counter.js';

// Basic hydration
const element = document.getElementById('counter');
const instance = hydrate(element, Counter, { initialCount: 5 });

// With state initialization
const instance = hydrate(element, Counter, {}, {
  initialState: { count: 10, step: 2 }
});

hydrateAll(elements, components, propsArray?)

Hydrates multiple elements with their corresponding components.

Parameters:

  • elements (Array): Array of DOM elements to hydrate
  • components (Array): Array of Coherent component functions
  • propsArray (Array, optional): Array of component props

Returns: Array - Array of hydrated component instances

Example:

import { hydrateAll } from '@coherent.js/client';
import { Header, Footer } from './components/Layout.js';

const elements = [
  document.getElementById('header'),
  document.getElementById('footer')
];
const components = [Header, Footer];
const instances = hydrateAll(elements, components);

hydrateBySelector(selector, component, props?)

Finds and hydrates all elements matching a CSS selector.

Parameters:

  • selector (String): CSS selector to find elements
  • component (Function): The Coherent component function
  • props (Object, optional): Component props

Returns: Array - Array of hydrated component instances

Example:

import { hydrateBySelector } from '@coherent.js/client';
import { TodoItem } from './components/TodoItem.js';

// Hydrate all todo items
const instances = hydrateBySelector('[data-coherent-component="todoitem"]', TodoItem);

makeHydratable(component, options?)

Creates a hydratable version of a component with metadata for auto-hydration.

Parameters:

  • component (Function): The component function to make hydratable
  • options (Object, optional): Hydration metadata
    • componentName (String): Name for component registry
    • initialState (Object): Default initial state

Returns: Function - A hydratable component function with additional metadata

Example:

import { makeHydratable } from '@coherent.js/client';
import { Counter } from './components/Counter.js';

const HydratableCounter = makeHydratable(Counter, {
  componentName: 'counter',
  initialState: { count: 0 }
});

// Can be used in auto-hydration
export { HydratableCounter };

autoHydrate(componentRegistry)

Automatically hydrates all components on a page based on data-coherent-component attributes.

Parameters:

  • componentRegistry (Object): Registry mapping component names to hydratable components

Example:

import { autoHydrate, makeHydratable } from '@coherent.js/client';
import { Counter } from './components/Counter.js';
import { TodoList } from './components/TodoList.js';

const componentRegistry = {
  counter: makeHydratable(Counter),
  todolist: makeHydratable(TodoList)
};

// Auto-hydrate when DOM is ready
document.addEventListener('DOMContentLoaded', () => {
  autoHydrate(componentRegistry);
});

enableClientEvents(rootElement?)

Enables client-side interactivity for elements with data-action attributes.

Parameters:

  • rootElement (HTMLElement, optional): Root element to enable events on (default: document)

Example:

import { enableClientEvents } from '@coherent.js/client';

// Enable events for entire document
enableClientEvents();

// Enable events for specific container
const container = document.getElementById('interactive-section');
enableClientEvents(container);

extractInitialState(element, options?)

Extracts initial state from DOM element data attributes.

Parameters:

  • element (HTMLElement): The DOM element
  • options (Object, optional): Extraction options

Returns: Object|null - The extracted state or null

Example:

import { extractInitialState } from '@coherent.js/client';

const element = document.getElementById('counter');
// <div id="counter" data-coherent-state='{"count": 5}'>
const state = extractInitialState(element);
// Returns: { count: 5 }

registerEventHandler(id, handler)

Registers a global event handler for use with data-action attributes.

Parameters:

  • id (String): Unique identifier for the event handler
  • handler (Function): The event handler function

Example:

import { registerEventHandler } from '@coherent.js/client';

registerEventHandler('my-click-handler', (event, state, setState) => {
  console.log('Button clicked!', { event, state });
});

Framework Integrations

Express.js Integration

express.coherentMiddleware(options?)

Express middleware for Coherent.js.

Parameters:

  • options (Object, optional): Configuration options

express.createCoherentHandler(componentFactory, options?)

Creates an Express route handler for Coherent.js components.

Parameters:

  • componentFactory (Function): Function that returns a Coherent component
  • options (Object, optional): Handler options

express.setupCoherent(app, options?)

Sets up Coherent.js with Express app.

Parameters:

  • app (Express.Application): Express application instance
  • options (Object, optional): Configuration options

Fastify Integration

fastify.coherentFastify(fastify, options, done)

Fastify plugin for Coherent.js.

Parameters:

  • fastify (FastifyInstance): Fastify instance
  • options (Object): Plugin options
  • done (Function): Callback to signal plugin registration completion

fastify.createHandler(componentFactory, options?)

Creates a Fastify route handler for Coherent.js components.

Parameters:

  • componentFactory (Function): Function that returns a Coherent component
  • options (Object, optional): Handler options

fastify.setupCoherent(fastify, options?)

Sets up Coherent.js with Fastify instance.

Parameters:

  • fastify (FastifyInstance): Fastify instance
  • options (Object, optional): Configuration options

Next.js Integration

nextjs.createCoherentNextHandler(componentFactory, options?)

Creates a Next.js API route handler for Coherent.js components.

Parameters:

  • componentFactory (Function): Function that returns a Coherent component
  • options (Object, optional): Handler options

nextjs.createCoherentAppRouterHandler(componentFactory, options?)

Creates a Next.js App Router route handler for Coherent.js components.

Parameters:

  • componentFactory (Function): Function that returns a Coherent component
  • options (Object, optional): Handler options

nextjs.createCoherentServerComponent(componentFactory, options?)

Creates a Next.js Server Component for Coherent.js.

Parameters:

  • componentFactory (Function): Function that returns a Coherent component
  • options (Object, optional): Component options

nextjs.createCoherentClientComponent(componentFactory, options?)

Creates a Next.js Client Component for Coherent.js with hydration support.

Parameters:

  • componentFactory (Function): Function that returns a Coherent component
  • options (Object, optional): Component options

Utilities

escapeHtml(text)

Escapes HTML entities in a string.

Parameters:

  • text (String): The text to escape

Returns: String - The escaped text

validateComponent(component)

Validates a Coherent.js component.

Parameters:

  • component (any): The component to validate

Returns: Boolean - Whether the component is valid

extractProps(element)

Extracts props from a Coherent.js element.

Parameters:

  • element (Object): The element to extract props from

Returns: Object - The extracted props

Types

CoherentNode

Represents a Coherent.js node, which can be:

  • A CoherentElement object
  • A string
  • A number
  • A boolean
  • null
  • undefined

CoherentElement

Represents a Coherent.js element with the structure:

{
  [tagName: string]: {
    text?: string;
    html?: string;
    children?: CoherentNode[];
    className?: string | (() => string);
    [key: string]: any;
  }
}

ComponentFunction

Represents a Coherent.js component function:

(props?: Record<string, any>) => CoherentNode;

HydratedComponentInstance

Represents a hydrated component instance:

{
  element: HTMLElement;
  component: ComponentFunction;
  props: Record<string, any>;
  isHydrated: boolean;
  update(newProps: Record<string, any>): void;
  destroy(): void;
}