hyper-arrow

中文版

super tiny front-end UI library, for educational purposes

• ~4KB minified, ~2KB gzipped
• ZERO dependencies
• 100% test coverage, reliable
• No building steps, easy use via <script module="type"> tag in plain HTML
• Proxy-based reactivity, like reactive in Vue 3 or makeAutoObservable in MobX
• No templates or JSX. Tag functions div, button and etc. work like h in hyperscript or h in Vue 3
• => arrow functions within tag functions provide reactivity, which is how the name comes ;)
• Smart and performant element children inserting, removing, swapping and updating, if all children has unique id attributes

Get started

// @ts-nocheckimport{mount,reactive,tags}from'../../hyper-arrow.js'classModel{input=''list=[]add(){this.list.push(this.input)this.input=''}clear(){this.list=[]}}// create a reactive objectconstmodel=reactive(newModel())// design your view with nested HTML tag functionsconst{ button, div, input, li, ul }=tags.htmlconstview=div(// element properties in the first parameter{id: 'container-id',class: 'container-class',style: 'padding: 4px;',},// children in the rest parametersdiv({style: 'margin: 4px'},'hyper-arrow demo'),input({type: 'text',// arrow functions make properties reactivevalue: ()=>model.input,class: ()=>(model.input ? 'class3' : 'class4'),// your can set inline styles here with prefix '$'$margin: '4px',// again, arrow function for reactive style$color: ()=>(model.input.length>5 ? 'red' : 'black'),// event listeners with prefix 'on'onInput(event){model.input=event.target.value},onKeydown(event){if(event.code==='Enter')model.add()},}),button({type: 'button',style: 'margin: 4px',onClick(){model.add()},},'add',),// can also using 'innerText' to set text as single child// just like `el.innerText = 'xxx'` in DOM APIbutton({type: 'button',innerText: 'clear all',style: ()=>'margin: 4px;',onClick(){model.clear()},}),// the first element properties can be omitted, if none existsul(// children can also be an arrow function, also reactive()=>model.list.map((item)=>li(item)),),)// mount your view to the page and go!mount('#app',view)model.input='aaa'model.add()model.input='bbb'model.add()

It will create the following DOM tree with proper dynamic behaviors:

<divid="container-id" class="container-class" style="padding: 4px;"><divstyle="margin: 4px;">hyper-arrow demo</div><inputtype="text" class="class4" style="margin: 4px; color: black;" /><buttontype="button" style="margin: 4px;">add</button><buttontype="button" style="margin: 4px;">clear all</button><ul><li>aaa</li><li>bbb</li></ul></div>

See src/examples for more.

Basic API

reactive(object)

Create a reactive proxy for any object, and then it can be used in tag functions.

tags

All HTML tag functions are in tags.html. tags.svg contains SVG tag functions, and tags.mathml contains MathML tag functions.

import{mount,reactive,tags}from'../../hyper-arrow.js'const{ div, button }=tags.htmlconst{ svg, circle }=tags.svgconst{ math, mi, mn, mfrac }=tags.mathmlconstmodel=reactive({number: 10})// children can be an array, instead of being the rest parametersconstview=div({id: 'root'},[button({innerText: 'increase',onClick(){model.number++},}),// if you have single-line props, then children as array formats bettersvg({stroke: 'red',fill: 'lightyellow'},[circle({cx: '50',cy: '50',r: ()=>model.number.toString()}),]),// same here, children in arraymath({display: 'block'},[// here children are not in array. writes easier and looks bettermfrac(mi('x'),mn(()=>model.number.toString()),),]),])mount('#app',view)

It generates the DOM tree:

<divid="root"><button>increase</button><svgstroke="red" fill="lightyellow"><circlecx="50" cy="50" r="10"></circle></svg><mathdisplay="block"><mfrac><mi>x</mi><mn>10</mn></mfrac></math></div>

mount(element_selector, view, [options])

Mount the view onto DOM. Examples already shown above. See below for details of optional options

Advanced API

UID_ATTR_NAME

mount can accept an optional third parameter options for extra configuration.

[UID_ATTR_NAME] is a unique symbol key in mount's options. It adds unique HTML attributes to all DOM elements created by mount in order to identify themselves.

import{mount,tags,UID_ATTR_NAME}from'../../hyper-arrow.js'const{ div }=tags.htmlconstview=div(div('a'),div('b'),div(div('c'),div('d')),div('e'))mount('#app',view,{[UID_ATTR_NAME]: 'uid'})

will generate:

<divuid="0"><divuid="1">a</div><divuid="2">b</div><divuid="3"><divuid="4">c</div><divuid="5">d</div></div><divuid="6">e</div></div>

This is useful, for example, when checking if the parent element, when doing smart children updating or caching, is reusing elements correctly instead of recreating new ones (see below).

CACHE_REMOVED_CHILDREN

A unique symbol key that indicates how many removed children elements a parent DOM element can cache, so instead of creating new children, it can reuse the cached ones when needed, as long as the children's id attributes match.

import{CACHE_REMOVED_CHILDREN,mount,reactive,tags,UID_ATTR_NAME,}from'../../hyper-arrow.js'const{ div, button, ul, li }=tags.htmlconstmodel=reactive({list: ['0','1']})constview=div(button({innerText: 'change',onClick(){constlength=Math.floor(Math.random()*10)model.list=Array.from({ length },(_,i)=>i.toString())},}),// allows cache, with 100 as max cache sizeul({id: 'list',[CACHE_REMOVED_CHILDREN]: 100},()=>model.list.map((item)=>li({id: ()=>item},item.toString())),),)mount('#app',view,{[UID_ATTR_NAME]: 'uid'})

In the dev tool you can see that, when the list changes, the uid attributes of li elements remain the same. That shows ul is reusing old removed lis.

ON_CREATE

A unique symbol key to create a special "onCreate" event handler on a DOM element.

import{mount,ON_CREATE,tags}from'../../hyper-arrow.js'const{ input }=tags.htmlmount('#app',input({value: 'hello world',[ON_CREATE](el){requestAnimationFrame(()=>{el.focus()setTimeout(()=>{el.select()},1000)})},}),)

The created DOM element, el, is passed into the event handler function.

isReactive(object)

Check if an object is a reactive proxy.

watch(fn, [effectFn])

Run fn() once, and whenever fn's dependencies (see below) change, automatically rerun fn(), or, if effectFn provided, run effectFn(fn()).

fac2opas

Map<FunctionAndContext, WeakMap<Object, Set<Property>>>. For each function-and-context (FAC), fac2opas stores all the object-property-accesses (OPAs) appearing within the function call. When any OPA changes, the corresponding function of the FAC reruns, and with the help of its contextual info, updates the correct position of the DOM as its new returned value. fns of watchs also go into fac2opas.

Keep in mind that your FACs' returned value must rely only on reactive OPAs (like o.p or o[p]) within the FAC, not on any other things like non-reactive object, free variable bindings (like let x = 1 inside the function), or global/closure variables.

Reactive Implementation Details

The reactive system is one of hyper-arrow's core features. Let's dive into how it works.

Basic Concepts

In hyper-arrow, there are three ways to define reactive properties:

constmodel=reactive({count: 0,text: 'hello',})constview=div(// 1. Arrow function (recommended){textContent: ()=>model.text},// 2. Regular function{textContent: function(){returnmodel.text},},// 3. Method shorthand{textContent(){returnmodel.text},},)

Why Functions?

The reactive system works through following steps:

1. Dependency Collection

Simplified implementation:

functionreactive(obj){returnnewProxy(obj,{get(target,key){// When executing a function, record which OPA it depends onif(currentFac){trackDependency(currentFac,target,key)}returntarget[key]},})}

2. Function Execution

functionrunFac(fac){constfn=fac[2]// Get functioncurrentFac=fac// Mark currently executing functionconstresult=fn()// Execute function, trigger proxy.get, collect dependenciescurrentFac=nullreturnresult}

3. Update Triggering

When reactive object property changes:

• System finds all functions depending on this property
• Reruns these functions
• Updates DOM with new return values

Dependency Tracking Mechanism

hyper-arrow uses the following data structure to track dependencies:

// Store each function's dependenciesexportconstfac2opas=newMap<Fac,WeakMap<object,Set<property>>>()

Dependency Collection Process

1. Set currentFac when executing reactive function
2. Accessing reactive property during function execution triggers Proxy's get interceptor
3. Get interceptor records dependency between current function and accessed property

Update Process

1. Modifying reactive object property triggers Proxy's set interceptor
2. Look up all functions depending on this property
3. Rerun these functions
4. Update corresponding DOM elements

Why Arrow Functions Recommended?

1. Conciseness: More concise syntax, easier to read
2. this binding: Avoids this binding issues
3. Design intent: Clearly expresses this is a reactive property

Practical Example

import{reactive,div,mount}from'hyper-arrow'// Create reactive dataconstmodel=reactive({count: 0,message: 'Hello',})// Create viewconstview=div({class: ()=>(model.count>0 ? 'active' : ''),textContent: ()=>`${model.message} (${model.count})`,})// Mount to DOMmount('#app',view)// Data changes automatically trigger view updatesmodel.count++model.message='Hi'

Summary

1. Any form of function can be used for reactive properties
2. Arrow functions are recommended but not required
3. Core of reactive system is dependency collection and automatic updates
4. Functions are used to track property access and rerun when needed