Voby

A high-performance framework with fine-grained observable/signal-based reactivity for building rich applications.

Features

This works similarly to Solid, but without a custom Babel transform and with a different API.

No VDOM: there's no VDOM overhead, the framework deals with raw DOM nodes directly.
No stale closures: functions are always executed afresh, no need to worry about previous potential executions of the current function, ever.
No rules of hooks: hooks are just regular functions, which you can nest indefinitely, call conditionally, use outside components, whatever you want.
No dependencies arrays: the framework is able to detect what depends on what else automatically, no need to specify dependencies manually.
No props diffing: updates are fine grained, there's no props diffing, whenever an attribute/property/class/handler/etc. should be updated it's updated directly and immediately.
No key prop: you can just map over arrays, or use the For component with an array of unique values, no need to specify keys explicitly.
No Babel: there's no need to use Babel with this framework, it works with plain old JS (plus JSX if you are into that). As a consequence we have 0 transform function bugs, because we don't have a transform function.
No magic: what you see is what you get, your code is not transformed to actually do something different than what you write, there are no surprises.
No server support: for the time being this framework is focused on local-first rich applications, most server-related features are not implemented: no hydration, no server components, no streaming etc.
Observable-based: observables, also known as "signals", are at the core of our reactivity system. The way it works is very different from a React-like system, it may be more challenging to learn, but it's well worth the effort.
Work in progress: this is probably beta software, I'm working on it because I need something with great performance for Notable, I'm allergic to third-party dependencies, I'd like something with an API that resonates with me, and I wanted to deeply understand how the more solid Solid, which you should also check out, works.

Demos

You can find some demos and benchmarks below, more demos are contained inside the repository.

Playground (CodeSandbox): https://codesandbox.io/s/voby-playground-7w2pxg
Playground (StackBlitz): https://stackblitz.com/edit/vitejs-vite-azlrzl?file=src%2Fcounter.tsx
Benchmark: https://krausest.github.io/js-framework-benchmark/current.html
Counter: https://codesandbox.io/s/voby-demo-counter-23fv5
Clock: https://codesandbox.io/s/voby-demo-clock-w1e7yb
Emoji Counter: https://codesandbox.io/s/voby-demo-emoji-counter-j91iz2
HyperScript: https://codesandbox.io/s/voby-demo-hyperscript-h4rf38
HTML Template Literal: https://codesandbox.io/s/voby-demo-html-lvfeyo
Single-file HTML: https://codesandbox.io/s/voby-demo-html-dueygt?file=/public/index.html
Spiral: https://codesandbox.io/s/voby-demo-spiral-ux33p6
Store Counter: https://codesandbox.io/s/voby-demo-store-counter-kvoqrw
Triangle: https://codesandbox.io/s/voby-demo-triangle-l837v0
Boxes: https://codesandbox.io/s/voby-demo-boxes-wx6rqb

APIs

Methods	Components	Hooks <sub>core</sub>	Hooks <sub>web</sub>	Types	Extras
`$`	`Dynamic`	`useBoolean`	`useAbortController`	`Context`	`Contributing`
`$$`	`ErrorBoundary`	`useCleanup`	`useAbortSignal`	`Directive`	`Globals`
`batch`	`For`	`useContext`	`useAnimationFrame`	`DirectiveOptions`	`JSX`
`createContext`	`Fragment`	`useDisposed`	`useAnimationLoop`	`EffectOptions`	`Tree Shaking`
`createDirective`	`If`	`useEffect`	`useEventListener`	`FunctionMaybe`	`TypeScript`
`createElement`	`KeepAlive`	`useMemo`	`useFetch`	`MemoOptions`
`h`	`Portal`	`usePromise`	`useIdleCallback`	`Observable`
`hmr`	`Suspense`	`useReadonly`	`useIdleLoop`	`ObservableLike`
`html`	`Switch`	`useResolved`	`useInterval`	`ObservableReadonly`
`isBatching`	`Ternary`	`useResource`	`useMicrotask`	`ObservableReadonlyLike`
`isObservable`		`useRoot`	`useTimeout`	`ObservableMaybe`
`isServer`		`useSelector`		`ObservableOptions`
`isStore`		`useSuspended`		`Resource`
`lazy`		`useUntracked`		`StoreOptions`
`render`
`renderToString`
`resolve`
`store`
`template`
`tick`
`untrack`

Usage

This framework is simply a view layer built on top of the Observable library oby, knowing how that works is necessary to understand how this works.

This framework basically re-exports everything that oby exports, sometimes with a slightly different interface, adjusted for usage as components or hooks, plus some additional functions.

Methods

The following top-level functions are provided.

`$`

This function is just the default export of oby, it can be used to wrap a value in an observable.

No additional methods are attached to this function. Everything that oby attaches to it is instead exported as components and hooks.

Read upstream documentation.

Interface:

function $ <T> (): Observable<T | undefined>;
function $ <T> ( value: undefined, options?: ObservableOptions<T | undefined> ): Observable<T | undefined>;
function $ <T> ( value: T, options?: ObservableOptions<T> ): Observable<T>;

Usage:

import {$} from 'voby';

// Create an observable without an initial value

$<number> ();

// Create an observable with an initial value

$(1);

// Create an observable with an initial value and a custom equality function

const equals = ( value, valuePrev ) => Object.is ( value, valuePrev );

const o = $( 1, { equals } );

// Create an observable with an initial value and a special "false" equality function, which is a shorthand for `() => false`, which causes the observable to always emit when its setter is called

const oFalse = $( 1, { equals: false } );

// Getter

o (); // => 1

// Setter

o ( 2 ); // => 2

// Setter via a function, which gets called with the current value

o ( value => value + 1 ); // => 3

// Setter that sets a function, it has to be wrapped in another function because the above form exists

const noop = () => {};

o ( () => noop );

`$$`

This function unwraps a potentially observable value.

Read upstream documentation.

Interface:

function $$ <T> ( value: T ): (T extends ObservableReadonly<infer U> ? U : T);

Usage:

import {$$} from 'voby';

// Getting the value out of an observable

const o = $(123);

$$ ( o ); // => 123

// Getting the value out of a function

$$ ( () => 123 ); // => 123

// Getting the value out of an observable but not out of a function

$$ ( o, false ); // => 123
$$ ( () => 123, false ); // => () => 123

// Getting the value out of a non-observable and non-function

$$ ( 123 ); // => 123

`batch`

This function prevents effects from firing until the function passed to it resolves. It's largely only useful when the passed function is asynchronous, as otherwise the reactivity system is lazy so effects won't be over-executed anyway.

Read upstream documentation.

Interface:

function batch <T> ( fn: () => Promise<T> | T ): Promise<Awaited<T>>;
function batch <T> ( value: T ): Promise<Awaited<T>>;

Usage:

import {batch} from 'voby';

batch // => Same as require ( 'oby' ).batch

`createContext`

This function creates a context object, optionally with a default value, which can later be used to provide a new value for the context or to read the current value.

A context's Provider will register the value of context with its children.

Interface:

type ContextProvider<T> = ( props: { value: T, children: JSX.Element } ) => JSX.Element;
type Context<T> = { Provider: ContextProvider<T> };

function createContext <T> ( defaultValue?: T ): Context<T>;

Usage:

import {createContext, useContext} from 'voby';

const App = () => {
  const Context = createContext ( 123 );
  return (
    <>
      {() => {
        const value = useContext ( Context );
        return <p>{value}</p>;
      }}
      <Context.Provider value={312}>
        {() => {
          const value = useContext ( Context );
          return <p>{value}</p>;
        }}
      </Context.Provider>
    </>
  );
};

`createDirective`

This function creates a directive provider, which can be used to register a directive with its children.

A directive is a function that always receives an Element as its first argument, which is basically a ref to the target element, and arbitrary user-provided arguments after that.

Each directive has a unique name and it can be called by simply writing use:directivename={[arg1, arg2, ...argN]]} in the JSX.

Directives internally are registered using context providers, so you can also override directives for a particular scope just by registering another directive with the same name closer to where you are reading it.

A directive's Provider will register the directive with its children, which is always what you want, but it can lead to messy code due to nesting.

A directive's register function will register the directive with the current parent observer, which is usually only safe to do at the root level, but it will lead to very readable code.

Interface:

type DirectiveFunction = <T extends unknown[]> ( ref: Element, ...args: T ) => void;
type DirectiveProvider = ( props: { children: JSX.Element } ) => JSX.Element;
type DirectiveRef<T extends unknown[]> = ( ...args: T ) => (( ref: Element ) => void);
type DirectiveRegister = () => void;
type Directive = { Provider: DirectiveProvider, ref: DirectiveRef, register: DirectiveRegister };

function createDirective <T extends unknown[] = []> ( name: string, fn: DirectiveFunction<T>, options?: DirectiveOptions ): Directive;

Usage:

import {createDirective, useEffect} from 'voby';

// First of all if you are using TypeScript you should extend the "JSX.Directives" interface, so that TypeScript will know about your new directive

namespace JSX {
  interface Directives {
    tooltip: [title: string] // Mapping the name of the directive to the array of arguments it accepts
  }
}

// Then you should create a directive provider

const TooltipDirective = createDirective ( 'tooltip', ( ref, title: string ) => {

  useEffect ( () => {

    if ( !ref () ) return; // The element may not be available yet, or it might have been unmounted

    // Code that implements a tooltip for the given element here...

  });

});

// Then you can use the new "tooltip" directive anywhere inside the "TooltipDirective.Provider"

const App = () => {
  return (
    <TooltipDirective.Provider>
      <input value="Placeholder..." use:tooltip={['This is a tooltip!']} />
    </TooltipDirective.Provider>
  );
};

// You can also use directives directly by padding them along as refs

const App = () => {
  return <input ref={TooltipDirective.ref ( 'This is a tooltip!' )} value="Placeholder..." />;
};

`createElement`

This is the internal function that will make DOM nodes and call/instantiate components, it will be called for you automatically via JSX.

Interface:

function createElement <P = {}> ( component: JSX.Component<P>, props: P | null, ...children: JSX.Element[] ): () => JSX.Element);

Usage:

import {createElement} from 'voby';

const element = createElement ( 'div', { class: 'foo' }, 'child' ); // => () => HTMLDivElement

`h`

This function is just an alias for the createElement function, it's more convenient to use if you want to use Voby in hyperscript mode just because it has a much shorter name.

Interface:

function h <P = {}> ( component: JSX.Component<P>, props: P | null, ...children: JSX.Element[] ): () => JSX.Element);

Usage:

import {h} from 'voby';

const element = h ( 'div', { class: 'foo' }, 'child' ); // => () => HTMLDivElement

`hmr`

This function wraps a component and makes it HMR-aware, for implementations of HMR like Vite's, this makes the component refresh itself and its children without requiring a reload of the whole page.

For an automated way to make all your components HMR-aware check out voby-vite instead.

Interface:

function hmr <T extends Function> ( accept: Function, component: T ): T;

Usage:

import {hmr} from 'voby';

// Define a component

const Counter = ({ value }): JSX.Element => {
  // Return something...
};

// Optionally attach components and other values to it

Counter.Button = ({ onClick }): JSX.Element => {
  // Return something...
};

Counter.INITIAL_VALUE = 0;

// Lastly export it as "default", wrapped in "hmr"
//