1.4.0: API simplification (less is more)

[Tao-VanJS]

Hi fellow VanJSers,

I'm happy to announce the release of VanJS 1.4.0. 🎉🎉🎉

Since its first public debut last May, VanJS maintains its goal of reducing the entry barrier of UI programming. To pursue this goal, we have been always trying to provide all essential features of modern web frameworks - DOM templating, state, state binding, state derivation, effect, SPA, client-side routing and even hydration, in the simplest possible way. Simplicity is always among the top priorities of VanJS. The pursuit of simplicity helps VanJS maintain the title of world's smallest reactive UI framework.

Now, after evolving VanJS with 23 public releases, we feel that we can do even better. With 1.4.0 release, we're simplifying VanJS's public API by reducing the top-level functions from 9 to 5!

In this release, we took a deeper look at VanJS's entire API. We realized, some of functions are rarely being used. They can either be merged into other functions, completely replaced by other functions, or replaced by client-side solution in just several lines of code but with much greater flexibility. Thus, this release deprecates these functions. Since the overwhelming majority of applications don't use these functions at all, we expect most apps won't be affected. Even for the ones that do break, there will be an effortless migration pathway.

We believe less is more. Simplifying the API of VanJS will further flatten its learning curve, avoid the common confusion about less used functions, and ensures VanJS apps being built in a more consistent way.

✨ What's in the release?

1. van.tags and van.tagsNS are merged into the same API.

Prior to this release, people have to remember 2 different names for declaring tag functions - van.tags for creating HTML elements, and van.tagsNS for creating elements with custom namespace URI (such as SVG or MathML elements). In VanJS 1.4.0, with some adjustment of the implementation, van.tags and van.tagsNS are merged into the same name - van.tags. You can use:

const {div, p, span} = van.tags

to declare tag functions for HTML elements, and use:

const {circle, path, svg} = van.tags("http://www.w3.org/2000/svg")

to declare tag functions for SVG elements.

2. Deprecate van._ as van.derive can be its drop-in replacement

In 1.4.0 release, we deprecate function van._ as van.derive can be its drop-in replacement wherever van._ is being used. van._ was introduced in VanJS 1.0.0 to allow state-derived on... event handlers (an escape mechanism to avoid binding functions being treated as event handlers). At that time, garbage collection for derived states wasn't implemented thus derived states need to be used very carefully to avoid memory leak. This situation was improved in 1.1.0 where garbage collection for derived states was implemented. After 1.1.0 release, derived states can be used freely just as other features in VanJS. Thus we can safety deprecate van._ by replacing all of its usage with van.derive, see https://vanjs.org/tutorial#state-derived-event-handlers for reference.

3. Deprecate van.val and van.oldVal as they can be replaced by a few lines of code on the client side

van.val and van.oldVal were introduced in VanJS 1.0.0 as rarely used helper functions, primarily for component library authors, to deal with state and non-state input properties in a polymorphic way. i.e.: van.val(v) returns the value of v regardless of whether v is a State object or not. However, we realized that this implementation is rather incomplete (e.g.: it doesn't evaluate the value if v is a binding function), and users likely want to control over its resolution strategy (e.g.: whether to treat functions as binding functions or event handlers). Given it's rare for van.val and val.oldVal to support the real-world needs and it's easy to implement the solution on the user side, we decide to just deprecate these 2 functions. Users can usually replace them with a few lines of code on their side. For instance, the lines of code below implement a function that can resolve a static value, a State object and a binding function:

const stateProto = Object.getPrototypeOf(van.state())
const val = v => {
  const protoOfV = Object.getPrototypeOf(v ?? 0)
  if (protoOfV === stateProto) return v.val
  if (protoOfV === Function.prototype) return v()
  return v
}

You can refer to this section for more information.

4. Support van.state() in TypeScript to create dummy or uninitialized State objects

This release also adjusts van.d.ts to allow van.state() (calling van.state without any argument) for creating a dummy State object (e.g.: for getting states' prototype object as shown in the code above) or creating a State object whose value will be initialized later. van.state() is already a valid usage prior to this release and in 1.4.0 we're making it pass the type checking.

🛫 Migration guide

Most of the apps are expected to be unaffected by this release. But if your app uses one of the functions that are deprecated, you can follow the simple steps below to upgrade:

• If you're using van.tagsNS, simply replace van.tagsNS with van.tags.
• If you're using van._, simply replace van._ with van.derive.
• If you're using van.val or van.oldVal, you can replace it with a few lines of customized implementation illustrated in https://vanjs.org/tutorial#polymorphic-binding.

---

The bundle size decreases thanks to the API simplification. Gzipped bundle decreases to 1012 bytes (1.9kB) from 1049 bytes (37 bytes decrease), while minified bundle decreases to 1896 bytes (1.0kB) from 1923 bytes (27 bytes decrease) - maintaining to be the smallest reactive UI framework in the world.

❤️ Hope you can enjoy!

---

Appendix

Why releasing the API simplification as 1.4.0 instead of 2.0.0?

Technically, the API simplification brings some potential incompatibility and should be released as 2.0.0 instead of 1.4.0. However, after thinking through all the implications, I feel releasing it to 1.4.0 will bring us an easier way to proceed. If we release it as VanJS 2.0.0, it will make the co-existence of 2 major VanJS versions: VanJS v1 and VanJS v2, which will bring significant amount of confusion and complexity.

Specifically, when the users build an app on top of VanJS, they have to explicitly choose whether to use VanJS v1 or VanJS v2. To make things worse, since all the 3rd-party add-ons of VanJS at the moment are based on VanJS v1 (i.e.: having ^1.x.x in the dependency specifier), if a user decides to build an app based on VanJS v2 but also depends on one of the 3rd-party add-on, that will result 2 VanJS versions being imported to the app simultaneously, which will be sure to be problematic (State objects and bindings in one version can't recognize the ones in the other version). A likely mitigation is to requires all VanJS-based libraries to support both versions and change the dependency specifier to something like >=1.x.x, but the requirement of being compatible with both VanJS versions will inevitably bring lots of complexity to the library implementation, which completely defeats the purpose of API simplification.

On the flip side, since the functions that are deprecated in this release are truly the rarely used ones, we expect the number of apps that are broken by this release to be extremely small. And for the ones that do break, the migration will be simple and straightforward. Thus with the careful consideration of pros and cons of each choice, it's more beneficial to the VanJS ecosystem to release this version as 1.4.0 instead of 2.0.0.

[Tao-VanJS]

1.4.1 was just released.

1.4.1 was a minor release. In this release, we fixed a minor type issue of van.state in van.d.ts.

There is no change in the implementation of van.js.

[mdluo]

@Tao-VanJS appreciate the work, but releasing breaking changes with minor version can be problematic. If that's the practice for vanjs moving forward, I suggest mentioning it in the Getting Started section of the documentation to suggest installing with npm install vanjs-core@~1.5.0. npm's default specifier is vanjs-core@^1.5.0 and future minor versions with breaking changes could be installed by accident, in case that people not checking in their lock file or lock file being corrupted/ignored durning build.

[Tao-VanJS]

Thanks @mdluo for the feedback!

I definitely don't want it to be the practice moving forward. Breaking changes are being treated very seriously in VanJS and I only expect them to happen in extremely exceptional circumstances, if they do happen in the future at all.

In the Appendix of this release notes, I laid out the tradeoffs behind which version to release. In short:

• Realistically speaking, these are really rarely used APIs and impacted use cases should be small.
• There is very simple, clear and straightforward migration guide.
• Comparatively, the divergence of VanJS v1 and VanJS v2 will do more harm in the long run.

It's a difficult decision to make and there is no perfect solution. I was weighing in the pros and cons in a pragmatic way, so I really appreciate your understanding about the rationale.

[creatormir]

van.val was rarely used? Seriously?
I don’t understand the desire to make the minimum weight, do you want to place it in the microcontroller memory of 1MB? What's the point of huddling for hundreds of bytes?

UPD:
I read the instructions, but still didn’t understand how to replace van.val. Now I need to spend several hours finding a solution and replacing all occurrences. Perhaps I'll roll back to the old version.

[creatormir]

The same .val replacement is needed in vanX.list(

[Tao-VanJS]

The same .val replacement is needed in vanX.list(

What do you mean?

[creatormir]

selectel = vanX.list(()=>div({class:"selectel"}), in_.obj , (el, deleter, index) =>{
            return selectelCreate(el.val, deleter, index); // el.val to el
        });

[Tao-VanJS]

I don't quite understand. el.val works just fine in the new version. There is nothing to replace in the code snippet above.

[creatormir]

Yes indeed. I pass my proxy to van string values. It worked before the update, but now it returns an error.
toString method called on incompatible Proxy

I added methods to my object before creating the proxy and everything worked.

langbox[Symbol("Symbol.toPrimitive")] = hint => {
    return langbox[langbox.lang];
}
langbox.toString = () => langbox[langbox.lang];
return new Proxy(langbox, {...

Sorry