Complete 1.5.3 implementation

Author: Tao-VanJS

demo/terminal/van-1.5.2.min.js

@@ -1,6 +1,6 @@
 {
   "name": "vanjs-core",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "VanJS. A minimalist React-like UI library based on vanilla JavaScript and DOM.",
   "files": [
     "src/van.js",

demo/terminal/van-1.5.3.min.js

@@ -0,0 +1,48 @@
+export interface State<T> {
+  val: T
+  readonly oldVal: T
+  readonly rawVal: T
+}
+
+// Defining readonly view of State<T> for covariance.
+// Basically we want StateView<string> to implement StateView<string | number>
+export type StateView<T> = Readonly<State<T>>
+
+export type Val<T> = State<T> | T
+
+export type Primitive = string | number | boolean | bigint
+
+export type PropValue = Primitive | ((e: any) => void) | null
+
+export type PropValueOrDerived = PropValue | StateView<PropValue> | (() => PropValue)
+
+export type Props = Record<string, PropValueOrDerived> & { class?: PropValueOrDerived; is?: string }
+
+export type PropsWithKnownKeys<ElementType> = Partial<{[K in keyof ElementType]: PropValueOrDerived}>
+
+export type ValidChildDomValue = Primitive | Node | null | undefined
+
+export type BindingFunc = ((dom?: Node) => ValidChildDomValue) | ((dom?: Element) => Element)
+
+export type ChildDom = ValidChildDomValue | StateView<Primitive | null | undefined> | BindingFunc | readonly ChildDom[]
+
+export type TagFunc<Result> = (first?: Props & PropsWithKnownKeys<Result> | ChildDom, ...rest: readonly ChildDom[]) => Result
+
+type Tags = Readonly<Record<string, TagFunc<Element>>> & {
+  [K in keyof HTMLElementTagNameMap]: TagFunc<HTMLElementTagNameMap[K]>
+}
+
+declare function state<T>(): State<T>
+declare function state<T>(initVal: T): State<T>
+
+export interface Van {
+  readonly state: typeof state
+  readonly derive: <T>(f: () => T) => State<T>
+  readonly add: (dom: Element, ...children: readonly ChildDom[]) => Element
+  readonly tags: Tags & ((namespaceURI: string) => Readonly<Record<string, TagFunc<Element>>>)
+  readonly hydrate: <T extends Node>(dom: T, f: (dom: T) => T | null | undefined) => T
+}
+
+declare const van: Van
+
+export default van

package.json

@@ -0,0 +1,48 @@
+export interface State<T> {
+  val: T
+  readonly oldVal: T
+  readonly rawVal: T
+}
+
+// Defining readonly view of State<T> for covariance.
+// Basically we want StateView<string> to implement StateView<string | number>
+export type StateView<T> = Readonly<State<T>>
+
+export type Val<T> = State<T> | T
+
+export type Primitive = string | number | boolean | bigint
+
+export type PropValue = Primitive | ((e: any) => void) | null
+
+export type PropValueOrDerived = PropValue | StateView<PropValue> | (() => PropValue)
+
+export type Props = Record<string, PropValueOrDerived> & { class?: PropValueOrDerived; is?: string }
+
+export type PropsWithKnownKeys<ElementType> = Partial<{[K in keyof ElementType]: PropValueOrDerived}>
+
+export type ValidChildDomValue = Primitive | Node | null | undefined
+
+export type BindingFunc = ((dom?: Node) => ValidChildDomValue) | ((dom?: Element) => Element)
+
+export type ChildDom = ValidChildDomValue | StateView<Primitive | null | undefined> | BindingFunc | readonly ChildDom[]
+
+export type TagFunc<Result> = (first?: Props & PropsWithKnownKeys<Result> | ChildDom, ...rest: readonly ChildDom[]) => Result
+
+type Tags = Readonly<Record<string, TagFunc<Element>>> & {
+  [K in keyof HTMLElementTagNameMap]: TagFunc<HTMLElementTagNameMap[K]>
+}
+
+declare function state<T>(): State<T>
+declare function state<T>(initVal: T): State<T>
+
+export interface Van {
+  readonly state: typeof state
+  readonly derive: <T>(f: () => T) => State<T>
+  readonly add: (dom: Element, ...children: readonly ChildDom[]) => Element
+  readonly tags: Tags & ((namespaceURI: string) => Readonly<Record<string, TagFunc<Element>>>)
+  readonly hydrate: <T extends Node>(dom: T, f: (dom: T) => T | null | undefined) => T
+}
+
+declare const van: Van
+
+export default van

public/van-1.5.3.d.ts

@@ -0,0 +1,126 @@
+import van from "./van-1.5.3.js"
+
+// If this variable is set to an Array, we will push the error message into the array instead of
+// throwing an error. This is useful in testing, to capture the error occurred asynchronous to the initiating
+// callstack. e.g.: a state change can trigger a dom update processing when idle (i.e.: dom update
+// processing is set via setTimeout function, which is asynchronous to the initiating callstack).
+let capturedErrors
+
+const startCapturingErrors = () => capturedErrors = []
+
+const stopCapturingErrors = () => capturedErrors = null
+
+const expect = (cond, msg) => {
+  if (!cond) {
+    if (capturedErrors) capturedErrors.push(msg); else throw new Error(msg)
+    return false
+  }
+  return true
+}
+
+const protoOf = Object.getPrototypeOf
+const stateProto = protoOf(van.state())
+const isState = s => protoOf(s ?? 0) === stateProto
+
+const checkStateValValid = v => {
+  expect(!isState(v), "State couldn't have value to other state")
+  expect(!(v instanceof Node), "DOM Node is not valid value for state")
+  return v
+}
+
+const state = initVal => {
+  const proxy = new Proxy(van.state(checkStateValValid(initVal)), {
+    set: (s, prop, val) => {
+      prop === "val" && checkStateValValid(val)
+      return Reflect.set(s, prop, val, proxy)
+    },
+  })
+  return proxy
+}
+
+const derive = f => {
+  expect(typeof(f) === "function", "Must pass-in a function to `van.derive`")
+  return van.derive(f)
+}
+
+const isValidPrimitive = v =>
+  typeof(v) === "string" ||
+  typeof(v) === "number" ||
+  typeof(v) === "boolean" ||
+  typeof(v) === "bigint"
+
+const isDomOrPrimitive = v => v instanceof Node || isValidPrimitive(v)
+
+const validateChild = child => {
+  expect(
+    isDomOrPrimitive(child) || child === null || child === undefined,
+    "Only DOM Node, string, number, boolean, bigint, null, undefined are valid child of a DOM Element",
+  )
+  return child
+}
+
+const withResultValidation = f => dom => {
+  const r = validateChild(f(dom))
+  if (r !== dom && r instanceof Node)
+    expect(!r.isConnected,
+      "If the result of complex binding function is not the same as previous one, it shouldn't be already connected to document")
+  return r
+}
+
+const checkChildren = children => children.flat(Infinity).map(c => {
+  if (isState(c)) return withResultValidation(() => c.val)
+  if (typeof c === "function") return withResultValidation(c)
+  expect(!c?.isConnected, "You can't add a DOM Node that is already connected to document")
+  return validateChild(c)
+})
+
+const add = (dom, ...children) => {
+  expect(dom instanceof Element, "1st argument of `van.add` function must be a DOM Element object")
+  return van.add(dom, ...checkChildren(children))
+}
+
+const debugHandler = {
+  get: (vanTags, name) => {
+    const vanTag = vanTags[name]
+    return (...args) => {
+      const [props, ...children] = protoOf(args[0] ?? 0) === Object.prototype ? args : [{}, ...args]
+      const debugProps =  {}
+      for (const [k, v] of Object.entries(props)) {
+        const validatePropValue = k.startsWith("on") ?
+          (k.toLowerCase() === k ?
+            v => (expect(typeof v === "function" || v === null,
+              `Invalid property value for ${k}: Only functions and null are allowed for ${k} property`), v) :
+            v => (expect(typeof v === "string",
+              `Invalid property value for ${k}: Only strings are allowed for ${k} attribute`), v)
+          ) :
+          v => (expect(isValidPrimitive(v) || v === null,
+            `Invalid property value for ${k}: Only string, number, boolean, bigint and null are valid prop value types`), v)
+
+        if (isState(v))
+          debugProps[k] = van.derive(() => validatePropValue(v.val))
+        else if (typeof v === "function" && (!k.startsWith("on") || v._isBindingFunc))
+          debugProps[k] = van.derive(() => validatePropValue(v()))
+        else
+          debugProps[k] = validatePropValue(v)
+      }
+      return vanTag(debugProps, ...checkChildren(children))
+    }
+  },
+}
+
+const _tagsNS = ns => new Proxy(van.tags(ns), debugHandler)
+const tagsNS = ns => {
+  expect(typeof ns === "string", "Must provide a string for parameter `ns` in `van.tags`")
+  return _tagsNS(ns)
+}
+
+const _tags = _tagsNS("")
+const tags = new Proxy(tagsNS, {get: (_, name) => _tags[name]})
+
+const hydrate = (dom, f) => {
+  expect(dom instanceof Node, "1st argument of `van.hydrate` function must be a DOM Node object")
+  expect(typeof(f) === "function", "2nd argument of `van.hydrate` function must be a function")
+  return van.hydrate(dom, withResultValidation(f))
+}
+
+export default {add, tags, state, derive, hydrate, startCapturingErrors, stopCapturingErrors, get capturedErrors() { return capturedErrors }}

public/van-1.5.3.debug.d.ts

@@ -0,0 +1,140 @@
+// This file consistently uses `let` keyword instead of `const` for reducing the bundle size.
+
+// Global variables - aliasing some builtin symbols to reduce the bundle size.
+let protoOf = Object.getPrototypeOf
+let changedStates, derivedStates, curDeps, curNewDerives, alwaysConnectedDom = {isConnected: 1}
+let gcCycleInMs = 1000, statesToGc, propSetterCache = {}
+let objProto = protoOf(alwaysConnectedDom), funcProto = protoOf(protoOf), _undefined
+
+let addAndScheduleOnFirst = (set, s, f, waitMs) =>
+  (set ?? (setTimeout(f, waitMs), new Set)).add(s)
+
+let runAndCaptureDeps = (f, deps, arg) => {
+  let prevDeps = curDeps
+  curDeps = deps
+  try {
+    return f(arg)
+  } catch (e) {
+    console.error(e)
+    return arg
+  } finally {
+    curDeps = prevDeps
+  }
+}
+
+let keepConnected = l => l.filter(b => b._dom?.isConnected)
+
+let addStatesToGc = d => statesToGc = addAndScheduleOnFirst(statesToGc, d, () => {
+  for (let s of statesToGc)
+    s._bindings = keepConnected(s._bindings),
+    s._listeners = keepConnected(s._listeners)
+  statesToGc = _undefined
+}, gcCycleInMs)
+
+let stateProto = {
+  get val() {
+    curDeps?._getters?.add(this)
+    return this.rawVal
+  },
+
+  get oldVal() {
+    curDeps?._getters?.add(this)
+    return this._oldVal
+  },
+
+  set val(v) {
+    curDeps?._setters?.add(this)
+    if (v !== this.rawVal) {
+      this.rawVal = v
+      this._bindings.length + this._listeners.length ?
+        (derivedStates?.add(this), changedStates = addAndScheduleOnFirst(changedStates, this, updateDoms)) :
+        this._oldVal = v
+    }
+  },
+}
+
+let state = initVal => ({
+  __proto__: stateProto,
+  rawVal: initVal,
+  _oldVal: initVal,
+  _bindings: [],
+  _listeners: [],
+})
+
+let bind = (f, dom) => {
+  let deps = {_getters: new Set, _setters: new Set}, binding = {f}, prevNewDerives = curNewDerives
+  curNewDerives = []
+  let newDom = runAndCaptureDeps(f, deps, dom)
+  newDom = (newDom ?? document).nodeType ? newDom : new Text(newDom)
+  for (let d of deps._getters)
+    deps._setters.has(d) || (addStatesToGc(d), d._bindings.push(binding))
+  for (let l of curNewDerives) l._dom = newDom
+  curNewDerives = prevNewDerives
+  return binding._dom = newDom
+}
+
+let derive = (f, s = state(), dom) => {
+  let deps = {_getters: new Set, _setters: new Set}, listener = {f, s}
+  listener._dom = dom ?? curNewDerives?.push(listener) ?? alwaysConnectedDom
+  s.val = runAndCaptureDeps(f, deps, s.rawVal)
+  for (let d of deps._getters)
+    deps._setters.has(d) || (addStatesToGc(d), d._listeners.push(listener))
+  return s
+}
+
+let add = (dom, ...children) => {
+  for (let c of children.flat(Infinity)) {
+    let protoOfC = protoOf(c ?? 0)
+    let child = protoOfC === stateProto ? bind(() => c.val) :
+      protoOfC === funcProto ? bind(c) : c
+    child != _undefined && dom.append(child)
+  }
+  return dom
+}
+
+let tag = (ns, name, ...args) => {
+  let [{is, ...props}, ...children] = protoOf(args[0] ?? 0) === objProto ? args : [{}, ...args]
+  let dom = ns ? document.createElementNS(ns, name, {is}) : document.createElement(name, {is})
+  for (let [k, v] of Object.entries(props)) {
+    let getPropDescriptor = proto => proto ?
+      Object.getOwnPropertyDescriptor(proto, k) ?? getPropDescriptor(protoOf(proto)) :
+      _undefined
+    let cacheKey = name + "," + k
+    let propSetter = propSetterCache[cacheKey] ??= getPropDescriptor(protoOf(dom))?.set ?? 0
+    let setter = k.startsWith("on") ?
+      (v, oldV) => {
+        let event = k.slice(2)
+        dom.removeEventListener(event, oldV)
+        dom.addEventListener(event, v)
+      } :
+      propSetter ? propSetter.bind(dom) : dom.setAttribute.bind(dom, k)
+    let protoOfV = protoOf(v ?? 0)
+    k.startsWith("on") || protoOfV === funcProto && (v = derive(v), protoOfV = stateProto)
+    protoOfV === stateProto ? bind(() => (setter(v.val, v._oldVal), dom)) : setter(v)
+  }
+  return add(dom, children)
+}
+
+let handler = ns => ({get: (_, name) => tag.bind(_undefined, ns, name)})
+
+let update = (dom, newDom) => newDom ? newDom !== dom && dom.replaceWith(newDom) : dom.remove()
+
+let updateDoms = () => {
+  let iter = 0, derivedStatesArray = [...changedStates].filter(s => s.rawVal !== s._oldVal)
+  do {
+    derivedStates = new Set
+    for (let l of new Set(derivedStatesArray.flatMap(s => s._listeners = keepConnected(s._listeners))))
+      derive(l.f, l.s, l._dom), l._dom = _undefined
+  } while (++iter < 100 && (derivedStatesArray = [...derivedStates]).length)
+  let changedStatesArray = [...changedStates].filter(s => s.rawVal !== s._oldVal)
+  changedStates = _undefined
+  for (let b of new Set(changedStatesArray.flatMap(s => s._bindings = keepConnected(s._bindings))))
+    update(b._dom, bind(b.f, b._dom)), b._dom = _undefined
+  for (let s of changedStatesArray) s._oldVal = s.rawVal
+}
+
+export default {
+  tags: new Proxy(ns => new Proxy(tag, handler(ns)), handler()),
+  hydrate: (dom, f) => update(dom, bind(f, dom)),
+  add, state, derive,
+}