ivx v0.3.0

ivx ·

ivx is an extremely fast functional HTML string renderer.

packages	NPM version
ivx
ivx-html
ivx-svg

Features

• Immutable Virtual DOM Nodes
• Implicit data propagation with contexts
• Connectors for sideways data loading
• Diff/Patch renderer

Basic Example

import { render } from "ivx";
import { div } from "ivx-html";

render(div("message").c("Hello World!"));
// => <div class="message">Hello World</div>

API

Virtual DOM

HTML/SVG Elements

HTML and SVG elements are created with predefined factory functions.

• ivx-html package provides factories for HTML elements.
• ivx-svg package proived factories for SVG elements.

interface VNode {
  a(attrs: { [key: string]: any } | null): this;
  s(style: { [key: string]: any } | null): this;
  c(children: VNodeChildren): this;
}

type VNodeChildren = VNodeChildrenArray | VNode<any> | string | number | null;
interface VNodeChildrenArray extends Array<VNodeChildren> { }

HTML and SVG elements have three methods:

a() method is used to assign attributes.

s() method is used to assign styles.

c() method is used to assign children nodes.

Raw Text

Raw text is used to inject any text into the document without any escaping.

function raw(text: string): VNode<null>;

Custom Elements

interface ElementOptions {
  readonly void?: boolean;
  readonly attrs?: {};
}
function element<T>(tagName: string, options?: ElementOptions): (className?: string) => VNode<T>;

element() function creates a factory function for custom elements.

Components

function component(render: () => VNodeChildren): () => VNode<undefined>;
function component<P>(
  render: undefined extends P ? (props?: P) => VNodeChildren : (props: P) => VNodeChildren,
): undefined extends P ? (props?: P) => VNode<P> : (props: P) => VNode<P>;

component() function creates a factory function for components.

const A = component<{ text: string }>(
  (props) => div().c(props.text),
);

render(
  A({ text: "Hello" }),
);
// => <div>Hello</div>

Should Update hint

function withShouldUpdate<P>(
  shouldUpdate: (prev: P, next: P) => boolean,
  c: (props: P) => VNode<P>,
): (props: P) => VNode<P>;

withShouldUpdate() function creates a factory function for components with should update hint.

const A = withShouldUpdate<{ text: string }>(
  (prev, next) => prev.text !== next.text,
  component(
    (props) => h.div().c(props.text),
  ),
);

Context and Connectors

function context<T>(ctx: T, children: VNodeChildren): VNode<T>;

function connect<T>(
  select: (prev: T | null) => T,
  render: (props: T) => VNodeChildren,
): () => VNode<undefined>;
function connect<T, P>(
  select: undefined extends P ? (prev: T | null, props?: P) => T : (prev: T | null, props: P) => T,
  render: (props: T) => VNodeChildren,
): undefined extends P ? () => VNode<P> : (props: P) => VNode<P>;
function connect<T, P, C>(
  select: (prev: T | null, props: P, context: C) => T,
  render: (props: T) => VNodeChildren,
): undefined extends P ? () => VNode<P> : (props: P) => VNode<P>;

Connector is a specialized VNode that have access to the current context. connect() function creates a factory function for connectors.

context() function creates a VNode that will modify current context for its children.

const Connector = connect<string, undefined, { result: string }>(
  (prev, props, context) => {
    const result = context.result;

    return (prev !== null && prev === result) ? prev :
      result;
  },
  (text) => div().c(text),
);

render(
  context({ result: "Hello World!" },
    Connector(),
  ),
);
// => <div>Hello World!</div>

Render to String

function render(
  node: VNode<any>,
  context: {} = {},
): string;

render() function renders Virtual DOM into a string.

Blueprints

function createBlueprint(
  node: VNode<any>,
  context: {} = {},
): BlueprintNode;

createBlueprint() function creates a blueprint that can be used to optimize rendering.

function renderWithBlueprint(
  node: VNode<any>,
  blueprint: BlueprintNode,
  context: {} = {},
): string;

renderWithBlueprint() function renders Virtual DOM into a string. When blueprint parameter is specified, instead of rendering string from scratch, it will apply diff/patch algorithm on blueprint.

Blueprints linked to Components

function componentWithBlueprint<P>(
  node: VNode<P>,
  context?: {},
): (props: P) => VNodeChildren;

Example:

import { component, componentWithBlueprint } from "ivx";
import { div } from "ivx-html";

const Button = component((title: string) => div("Button").c(title));
const PrerenderedButton = componentWithBlueprint(Button(""));

render(PrerenderedButton("Go"));
// => <div class="Button">Go</div>