Introducing VanX: The official VanJS extension that enables more ergonomic code

[Tao-VanJS]

📣 VanX 0.4.0 brings lots of new features: Smart diff, global app state, server-driven UI, serialization and more →

Hi fellow VanJSers,

I'm thrilled to announce: VanX, the official VanJS extension is finally here! 🎉🎉🎉

VanX is a collection of utility functions that enable you to write more ergonomic code for your apps. In this release, it provides 2 primary functionalities:

vanX.reactive: Grouping many VanJS states into a single reactive object

vanX.reactive helps you define a single reactive object that is ideal for holding many State objects for the status of your application. The fields of the reactive objects can be deeply nested. Let's take a look at an example below:

const base = vanX.reactive({
  a: 1,
  b: 2,
  name: {
    first: "Tao",
    last: "Xin",
  },
  list: [1, 2, 3],
})

Getting and setting the fields in the reactive object is equivalent to getting and setting the values of its underlying states. With the reactive object, it's easy to define DOM nodes on top of its fields:

const aDom = input({type: "number", min: 1, max: 9, value: () => base.a,
  oninput: e => base.a = e.target.value})
  const bDom = input({type: "number", min: 1, max: 9, value: () => base.b,
    oninput: e => base.b = e.target.value})

const firstNameDom = input({type: "text", value: () => base.name.first,
  oninput: e => base.name.first = e.target.value})
const lastNameDom = input({type: "text", value: () => base.name.last,
  oninput: e => base.name.last = e.target.value})

Note that, not only you can set the value of each individual leaf field, you can also set the entire object of a subfield. For instance, the following code:

base.name = {first: "Tao", last: "Xin"}

is equivalent to:

base.name.first = "Tao"
base.name.last = "Xin"

All the bound UI elements are guaranteed to be updated accordingly, no matter which way you set the fields.

You can also specify calculated fields in the reactive object, the value of a calculated field depends on the values of other fields according to a calculation function. For instance, we can have a reactive object with calculated fields like that:

const derived = vanX.reactive({
  // Derived individual fields
  a: {
    double: vanX.calc(() => base.a * 2),
    squared: vanX.calc(() => base.a * base.a),
  },
  // Derived object
  b: vanX.calc(() => ({
    double: base.b * 2,
    squared: base.b * base.b,
  })),
  fullName: vanX.calc(() => `${base.name.first} ${base.name.last}`),
  list: vanX.calc(() => ({
    length: base.list.length,
    sum: base.list.reduce((acc, val) => acc + Number(val), 0),
  })),
})

Calculated fields can be used the same way as other fields.

Preview a sample app via CodeSandbox

You can refer to https://vanjs.org/x#reactive-object for more information about vanX.reactive.

vanX.list: Building a reactive list that minimizes DOM re-rendering when its values are updated

vanX.list is a utility function that helps you build a UI element based on a reactive list of values. It supports both non-keyed data (if the reactive object is an array) or keyed data (if the reactive object is a plain object).

Any change to the reactive list, such as inserting an item, updating an item, or deleting an item will be propagated to the UI elements it's bound to.

With the help of vanX.list, we can re-implement the reactive TODO app with substantial simplification (40+ lines of code => just over 10 lines):

const TodoList = () => {
  const items = vanX.reactive(JSON.parse(localStorage.getItem("appState") ?? "[]"))
  van.derive(() => localStorage.setItem("appState", JSON.stringify(items.filter(v => v))))
  const inputDom = input({type: "text"})
  return div(
    inputDom, button({onclick: () => items.push({text: inputDom.value, done: false})}, "Add"),
    vanX.list(div, items, ({val: v}, deleter) => div(
      input({type: "checkbox", checked: () => v.done, onclick: e => v.done = e.target.checked}),
      () => (v.done ? strike : span)(v.text),
      a({onclick: deleter}, "❌"),
    )),
  )
}

Try on jsfiddle

You might notice how easy it is to serialize/deserialize a complex reactive object into/from external storage. This is indeed one notable benefit of reactive objects provided by vanX.reactive.

Not only you can update the list object one item at a time, we also provide the vanX.replace function that enables you to update, insert, delete and reorder items in batch. Let's take a look at the examples below:

// Assume we have a few TODO items as following:
const todoItems = vanX.reactive([
  {text: "Implement VanX", done: true},
  {text: "Test VanX", done: false},
  {text: "Write a tutorial for VanX", done: false},
])

// To delete items in batch
const clearCompleted = () => vanX.replace(todoItems, l => l.filter(v => !v.done))

// To update items in batch
const appendText = () =>
  vanX.replace(todoItems, l => l.map(v => ({text: v.text + "!", done: v.done})))

// To reorder items in batch
const sortItems = () =>
  vanX.replace(todoItems, l => l.toSorted((a, b) => a.localeCompare(b)))

// To insert items in batch
const duplicateItems = () => vanX.replace(todoItems, l =>
  l.flatMap(v => [v, {text: v.text + " copy", done: v.done}]))

Preview sample apps where vanX.list and vanX.replace are being used: App 1, App 2.

You can refer to https://vanjs.org/x#reactive-list for more information about vanX.list.

---

Since the public release of VanJS, we have received enormous feedback from the community. There are common pain points expressed by its users as well as scenarios where programming with VanJS feels different compared to other UI frameworks. VanX is the effort to bridge the gap and address the most prominent pain points of VanJS. I am hoping it can bring the developer experience of VanJS into the next level!

❤️ Hope you can enjoy!

[metaleap]

Digging this a lot! Just in time as I get back to some frontending after weeks of backending.

Being more of a fair-weather [Ecma|Type]scripter, I find this challenging to grok:

Note that we are calling items.filter(_ => 1) before serializing to the JSON string via JSON.stringify. This is because after some deletions of items, there will be holes in the items array, which can result null values in the result JSON string and cause problems when the JSON string is deserialized. items.filter(_ => 1) eliminates the holes.

I understand the "standard" filter semantics as returning a bool depending on the input, _ here. Has vanX.list.filter different semantics from standard Array.filter? Or how does returning 1 for all values filter out nulls? (A link will also suffice to sate my curiosity here =)

[Tao-VanJS]

_ => 1 is not the as item => (item !== null && item !== void0). The reason why a.filter(_ => 1) is compacting the array is that: when Array.prototype.filter is called, it iterates all the entries of the array. The entries of regular arrays are easy to understand. For instance, for [1, 2, 3], its entries are ["0", 1], ["1", 2] and ["2", 3] (remember, the second argument of callbackFn in Array.prototype.filter is index, see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter#parameters). For arrays with holes, let's the array like:

{
  "0": 1,
  "2": 3,
}

it's entries are ["0", 1] and ["2", 3]. Note that the entry ["1", undefined] doesn't really exist and won't be iterated. The workflow of a.filter(_ => 1) is roughly like that:

1. Find all entries of a, which is ["0", 1] and ["2", 3].
2. Call the callbackFn for each entry, and collect all entries when callbackFn returns true-ish values. In our case, _ => 1 will return 1 (which is true-ish) for both entries (["0", 1] and ["2", 3]).
3. Build a new array based on the entries collected in Step 2 and return it to the callers. When the new array is being built, indexes are rewritten with integers starting from 0, 1, .... In our case, the new array will have entries ["0", 1] and ["1", 3].

Let me know if it makes sense to you.

[metaleap]

Ahhh, now I got it — muchos gracias indeed =) didn't run into this holes situation yet because I only ever removed via filter or slice anyway, not delete ^_^

[Tao-VanJS]

That's reasonable. I don't think holes in array have good utilities in most of the scenarios. However, in the particular use case of vanX.list, if we're using filter, there will be lots of value updates in the array (think about for an array, the "keys" are actually the indexes) which will lead to lots of DOM re-rendering.

[WilliCommer]

You can also use [...Object.values(a)]. Try this
(() => {let a = Array.from({length: 1e7}, (, i) => i);let d = new Date();let b=a.filter( => 1); console.log(new Date()-d);d = new Date(); b=[...Object.values(a)]; console.log(new Date()-d)})()
For me it prints 530 154

[WilliCommer]

P.S. The underscores were swallowed in the post. The result is from Node.js in the Firefox console is 230 470, in Chrome 340 560. So it's good as it is

[metaleap]

Btw might inclusion of X in https://vanjs.org/start#download-table be feasible? Being decidedly JS-deps-free apart from VanJS, I rather like manual (non-node_modules or similar) "package" "management" ... 😁

[Tao-VanJS]

I think https://vanjs.org/x#via-a-script-tag has the thing you need.

[metaleap]

I think https://vanjs.org/x#via-a-script-tag has the thing you need.

Not so, because I already import in my *.ts the standard van*.js which do have a downloadable that is importable without requiring <script>.

For now I fetched the X .js & .d.ts from the release tag and modified x's own import line from the npm pkg name to essentially ./van-....js =) — still more bearable than bringing in packers or bundlers that further pile upon the already disappointing tsc compile speeds and chance getting abandoned after a year or incompat'd or bugged after half. 😁

[Tao-VanJS]

Ah, I see what you mean.

You can refer to my reply in a different thread: #129 (comment). Basically the grab-n-go ESM support for VanX is left out because it's tricky to add:

1. In ESM, VanX needs to import a VanJS module to work properly.
2. Your application likely needs to import a VanJS module as well.
3. If your application is importing a different version of VanJS than what VanX imports. At least, we're wasting network bandwidth for importing different versions of the same module. The worse thing is: different versions of VanJS might conflict with each other to cause troubles to your application.

Currently I don't have a good solution to this and that's why the grab-n-go ESM support for VanX is left out.

[metaleap]

Ah that's alright, my hacky 2-step approach there is "manual, but it ain't hard". Releases after all happen only every-n-weeks, not days or hours, and it's just that 1 extra file... any more deps, guess I'll have to bite the npm/yarn/some-such bullet but not until then..

[Tao-VanJS]

I think this is probably the reason why we're not seeing too much adoption of pure ESM, unlike NPM or <script type="text/javascript">, which are quite popular. I really don't know a good solution of deduping the versions of ESM dependencies.

[HEAVYPOLY]

Hi, to use vanX do I also need to import vanJS?

<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/vanjs-org/van/public/van-1.2.7.nomodule.min.js"></script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/[email protected]/dist/van-x.nomodule.min.js"></script>

or only the van-x script?

[Tao-VanJS]

Yes, see https://vanjs.org/x#via-a-script-tag.

[Ashvith10]

@Tao-VanJS would it be right to call this a store library?

[Tao-VanJS]

I wouldn't call it that way. VanX is primarily for complex state management and state binding.