VanX 0.4.0: Smart diff, global app state, server-driven UI, serialization and more

[Tao-VanJS]

Hi fellow VanJSers,

I'm happy to announce the release of VanX 0.4.0. 🎉🎉🎉

VanX 0.4.0 is a significant update to VanJS's ultra-lightweight extension. In this release, many new features and improvements are being delivered, which opens up a new spectrum of modern programming paradigms with VanJS. We believe the release will further improve developer experience of VanJS and simplify the workload of building robust, performant and easy-to-maintain UI apps.

✨ What's in the release?

1. vanX.replace is revamped to allow smart diff / update

We revamped vanX.replace to make substantial improvements. First, it can take plain objects (including arrays), in addition to replacement functions, as its second argument. This allows more straightforward code instead of the workaround like:

vanX.replace(items, _ => newData)  // Can be written as `vanX.replace(items, newData)` after 0.4.0

More importantly, we enabled smart diff / update feature for vanX.replace. This allows efficient replacement for a complex object with multiple hierarchies. Specifically, vanX.replace will traverse the entire object tree, do a diff between replacement and obj, and only update leaf-level fields with different values. For instance, if you have a global reactive object appState for a TODO app like that:

{
  "input": "New Item",
  "items": [
    {"text": "Item 1", "done": true},
    {"text": "Item 2", "done": false}
  ]
}

Calling

vanX.replace(appState, {
  input: "New Item",
  items: [
    {text: "Item 1", done: true},
    {text: "Item 2", done: true},
  ]
})

will only get the done field of the 2nd element in items updated, which is equivalent to

appState.items[1].done = true

With the revamp on vanX.replace, you can consolidate the entire app state into a single reactive object, and freely replace the entire app state in one single line without worrying about the performance implication.

We believe this will greatly ease the development of your apps. Not only you can easily serialize / deserialize your global app state, it also enables you with convenient programming paradigms such as server-driven UI (SDUI), where the client completely relies on server events to update the UI. As an example of this technique, you can build a Chat app that updates the online / offline status of your friend list based on server-side events.

2. Calculated fields (vanX.calc(() => ...)) are allowed in vanX.list

With VanX 0.4.0, you can now use calculated fields in vanX.list to build reactive lists. This makes it easier for use cases such as building a filtered list. Before 0.4.0, to build a filtered list, you need to have some ad-hoc solution with vanX.replace like this:

const countries = [...]

const filter = van.state("")
const filteredCountries = vanX.reactive([])
van.derive(() => vanX.replace(filteredCountries, () => countries.filter(
  c => c.toLowerCase().includes(filter.val.toLowerCase()))))

...
vanX.list(ul, filteredCountries, v => li(v))

With this feature in VanX 0.4.0, building the filtered list becomes much more intuitive:

const countries = [...]

const data = vanX.reactive({filter: ""})
const derived = vanX.reactive({
  filteredCountries: vanX.calc(
    () => countries.filter(c => c.toLowerCase().includes(data.filter.toLowerCase()))),
})

...
vanX.list(ul, derived.filteredCountries, v => li(v))

You can refer to this section for the complete example.

Under the hood, whenever the derived value of the calculated field changes, VanX will call vanX.replace to perform the smart diff / update, which is essentially the same as the ad-hoc implementation with vanX.replace shown earlier.

3. vanX.compact to eliminate "holes" in reactive objects

Because of the deletion of items in reactive lists, "holes" might exist in arrays inside the reactive objects, which are undesirable when the reactive objects are serialized (e.g.: they are converted to null in JSON.stringify). Before VanX 0.4.0, users are advised to use items.filter(_ => 1) to eliminate holes, which is hacky and hard-to-understand. In VanX 0.4.0, we provide the official support for hole-elimination - vanX.compact. vanX.compact eliminates holes recursively. i.e.: it traverses the entire object tree of the input reactive object and returns a new object with holes in all encountered arrays eliminated. It's recommended to call vanX.compact before serializing your reactive object in all circumstances. You can refer to this section for more details.

4. vanX.list allows DOM elements as its 1st argument

Prior to VanX 0.4.0, users are required to provide a function () => Element as the 1st argument for the container element of reactive list. This is convenient when tag functions such as ul, ol or div are directly used there. However, if you want some customized property values of the container element, such as <div class="item-list">, you need to specify something like

vanX.list(() => div({class: "item-list"}), ...)

With VanX 0.4.0, the code can be simplified to

vanX.list(div({class: "item-list"}), ...)

as DOM elements can be directly specified there.

5. vanX.raw allows access to deeply nested fields without registering the dependency

vanX.raw was introduced in VanX 0.3.0 for accessing a field of a reactive object without registering the dependency. In VanX 0.4.0, we extended vanX.raw to allow access to deeply nested fields (without registering the dependency). For instance, before VanX 0.4.0, vanX.raw(data).a.a registers the dependency of data.a.a but not data.a. After VanX 0.4.0 release, vanX.raw(data).a.a will just access the field data.a.a without registering any dependency.

6. van-x.d.ts changes

We made some changes to the type systems of VanX. In VanX 0.4.0 we relaxed the type checking for functions like vanX.list and vanX.replace, which checked whether the 1st argument passed-in is a reactive object. This kind of type checkings brings inconvenience when sub-fields of reactive objects are being passed there.

Specifically, to illustrate the problem, since reactive objects and their non-reactive counterparts don't have any difference in shape, before VanX 0.4.0, we were introducing an artificial "reactivity marker" to indicate whether an object is reactive or not. However, the reactivity marker only applies to the top-level reactive objects, not to their sub-fields. Thus sub-fields of reactivity objects lose the "reactivity marker" and are not considered reactive by the type system, which breaks the type checking when they are passed into functions like vanX.list and vanX.replace, even though the usage is completely legitimate.

As a result, users usually need the workaround like any-casting to soothe the type system, like the code below:

const appState = vanX.reactive({items: [...]})

...
vanX.list(<any>appState.items)

which is cumbersome and defeats the purpose of type-checking.

Thus, essentially, we're facing 2 choices to proceed:

1. Pushing the reactivity marker to all the sub-fields of reactive objects (recursively), but this will make the type system much more complex, especially for the message of type-checking errors.
2. Relaxing the type checking in VanX by skipping checking the reactivity of objects. This will make the type system much simpler but "unsound" when a non-reactive object is passed into a function that expects a reactive object.

We decided to go with 2nd option in VanX 0.4.0. Our current assessment is that people rarely mistakenly pass non-reactive objects into places expecting reactivity (as reactivity is the fundamental concept of reactive programming), and when this does happen, it should be relatively easy to figure it out. After all, TypeScript is duck-typing-based with primary focus on shape-conformance. That being said, I am open to actual feedback from users to see if we need to introduce more complex and strict type system (or other kinds of mechanism) for reactivity checking in future releases.

---

With all the improvement, the bundle size of VanX increases slightly. Gzipped bundle increases to 1106 bytes (1.1kB) from 1047 bytes (1.0kB) (59 bytes increase), while minified bundle increases to 2191 bytes (2.1kB) from 1952 bytes (1.9kB) (239 bytes increase) - still being an ultra-lightweight extension to VanJS.

❤️ Hope you can enjoy!

[strash]

With this feature in VanX 0.4.0, building the filtered list becomes much more intuitive:

const countries = [...]

const data = vanX.reactive({filter: ""})
const derived = vanX.reactive({
  filteredCountries: vanX.calc(
    () => countries.filter(c => c.toLowerCase().includes(data.filter.toLowerCase()))),
})

...
vanX.list(ul, filteredCountries, v => li(v))

Hi, I'm confused with this example. Where did filteredCountries come from?

[strash]

I'm guessing it should be like this?

...
vanX.list(ul, derived.filteredCountries, v => li(v))

[Tao-VanJS]

Thanks for the catch! Yeah, you're right. That was a typo. I have corrected the code now.

[HEAVYPOLY]

Nice improvements to vanX.list!