hydro-js

hydro-js

A lightweight (~3.7K compressed) reactive UI library via template literal tags.
Support in all modern Browsers.

Installation

To bootstrap a new app:

$ npx create-hydro-app@latest <project> // or $ npm init hydro-app@latest <project>

or integrate in an existing app:

$ npm install hydro-js
import { render, html } from 'hydro-js';

Alternatively you can use a CDN:

<script type="module">
  import { render, html } from "https://unpkg.com/hydro-js";
</script>

Examples

• Simple Counter
• Two Way Data Binding
• Destructure Attributes
• Ternary
• Promise Handling
• Nested Reactivity
• Nested Reactivity 2

Concept

There are multiple things this library can do. The first thing is generating HTML from strings. This is mostly done by the Range Web API. There are already ways to do that, like Element.insertAdjacentHTML(), but this has some drawbacks, as it does not create Table Elements, like <colgroup>, <tbody>, <tfoot>, <thead> and <tr>. Furthermore, the html function deals with inline events, objects, Handlebars / {{ Mustache }} etc. Using this function will feel like writing JSX without a build step.

The render function is used for mounting and unmounting Elements to/from the DOM and for executing lifecycle hooks. Optionally, it can diff both HTML Trees and reuse Elements (optionally too). This is not using a virtual DOM.

The functions calls for render and DOM Updates are queued and worked on during a browser's idle periods.

In order to make the DOM reactive, ES6 Proxy objects are being used to map data against an array of DOM Elements. Whenever the setter is being called, the Proxy will check the mapping and update the DOM granularly. No re-renders are needed!

Almost all intern maps are using WeakMap with DOM Elements or Proxy objects as keys and thus memory is cleared efficiently.

Documentation

html

args: string
returns: DocumentFragment | Element | Text

Takes a string and transforms it to HTML. Used for internal bookkeeping too.

render

args:

• new Element (ReturnType<typeof html> | reactive Proxy)
• old Element (ReturnType<typeof html> | string)
• ? shouldSchedule: boolean (default: true)

returns: function that unmounts the new Element

Accepts the return value of html and replaces it with old Element. If it is a string, it will be resolved with querySelector.

setGlobalSchedule

args: boolean

Will enable/disable the schedule logic for render and DOM Updates. Intern value defaults to true.

setReuseElements

args: boolean

Will enable/disable the reuse of Elements in the diffing phase of render. Intern value defaults to true.

setInsertDiffing

args: boolean

If enabled, it will insert the new DOM Tree to the DOM before diffing. This will asssure that reused Elements will not lose their state (e.g. <video> in Chrome. Intern value defaults to false.

setReactivity

args: Node

Inserts Proxy values in the template HTML.

onRender

args:

• function
• elem (ReturnType<typeof html>)
• ...args for passed function

Calls the passed in function with ...args, after the Element is being inserted by render;

onCleanup

args:

• function
• elem (ReturnType<typeof html>)
• ...args for passed function

Calls the passed in function with ...args, after the Element is being diffed out by render or removed by unmount;

reactive

args: value: any
returns: unique Proxy

Returns a Proxy object that can be used within html. The Proxy is a wrapping a function that can set the value. If the setter is called with a function then the argument of the passed in function will be provided as the current value for the Proxy. The actual value will be set on the hydro Proxy, but this Proxy will hide the complexity.
Special behaviour for promises: the library will await promises and will set its value to the unwrapped value. If the Promise rejects, the value will be unset.

observe

args:

• ReturnType<typeof reactive>
  
• function

Calls the function whenenver the value of reactive changes. This is only one layer deep but chaining properties on reactive Proxys will return a Proxy too. Observing a prop of an object will look like: observe(person.name, ...)

unobserve

args:

• ReturnType<typeof reactive>

Removes all observer from the reactive Proxy. This will not unobserve observer on properties.

getValue

args: ReturnType<typeof reactive>
returns: currently set value

Returns the value inside the the Proxy. getValue is needed because reactive Proxy does not have access to the value.

asyncUpdate

args:

• ReturnType<typeof reactive>
  
• boolean

Sets the schedule behavior for DOM Updates that are bound to this Proxy.

unset

args: ReturnType

Deletes the Proxy object and removes Observer. This is important for keeping memory low.

ternary

args:

• condition: function | ReturnType<typeof reactive>
• trueVal: any
• falseVal: any
• ? proxy: ReturnType<typeof reactive>

returns: ReturnType<typeof reactive>

In order to track a ternary in a template literal, this function has to be used. The proxy parameter is optional if the first parameter is a reactive Proxy. Otherwise, a function is being executed, whenever the Proxy value changes, which will update the DOM to either the trueVal or the falseVal.

hydro

The actual Proxy in the library. This cannot be used with getValue, observe, ternary or unset but it offers the same functionality in a different manner.

properties:

• isProxy: boolean (default: true)
  
• asyncUpdate: boolean, (default: true, derived from globalSchedule)
  
• observe: function, args: string as key
  
• unobserve: function, args: string | undefined, unobserve key or all
  
• getObservers: function, returns: map with all observer

emit

args:

• event: string
• data: any
• who: EventTarget
• options: object (default: { bubbles: true })

Emits an event from the EventTarget who. This event bubbles by default.

$

Shortcut for querySelector.

$$

Shortcut for querySelectorAll.

internals

An object with internal data / functions for testing or deeper dives for developers. This only includes a compare function for DOM Elements at the moment.

Roadmap

• Refactor some code parts, once WeakRef is supported in Safari

Changelog

1.2.5- 2020-12-22

• Add feat: display empty string instead of undefined for undefined reactive values
• Bump deps