DEV Community: hybrids

Three unique features of the hybrids template engine that you must know

Dominik Lubański — Thu, 19 Dec 2019 17:12:06 +0000

For all of you who don't know yet, hybrids is a JavaScript library for creating web components. It uses a unique hybrid approach based on plain objects and pure functions. This article is the fourth in the series about the core features of the library.

So far we covered how to give up on classes and switch to the full power of plain objects. We have learned more about the cache mechanism, and we have discovered how the latest changes made the library even faster and easier to use.

However, let's be honest - the templates are the heart of UI components. Also, they usually take the biggest part of the component definition. In hybrids, you've got the ultimate freedom to choose the tool for this job. It's super easy to adopt any UI library, that produces the DOM and use it with render factory as a template engine (here you have two examples using React and lit-html). However, the built-in template engine can give you important benefits over the other options.

Inspiration

The foremost inspiration for the built-in template engine was the lit-html library, but the implementation is different and it follows its own conventions. The main objective was to use tagged template literals syntax to create the DOM and update dynamic parts leaving static content untouched.

At the time when the engine was created the lit-html was in the very early development stage. After the first major version, the syntax has changed dramatically. I wanted to create a library, which has no external dependencies, so there will be no problem with possible breaking changes. Also, the hybrids library brings some unique patterns, which I knew that the template engine should follow. For these reasons, I decided to try to build it myself. What we can say about the result?

Closest to the roots

One of the main differences is how it tries to predict user needs, so you don't have to learn special DSL or additional syntax for passing properties or attaching event listeners - just use pure HTML and expressions:

html`
  <button onclick="${increaseCount}" disabled="${disabled}">
    Count: ${count}
  </button>
`

The built-in elements follow the pattern, where attributes are reflected with corresponding property values. The <input> element goes even further and its value can be updated only by the property. The template engine uses element definition and chooses if it should pass values to the property, or eventually use the attribute (as a fallback when the property is not found in the prototype chain). Event listeners are attached by the on* attributes, where the second part is used as the type of the event. Even though attributes are not case-sensitive, the template engine uses the exact name defined in the template, so it is possible to set properties like this:

html`
  <div innerHTML="${mySafeHTML}" onMyCustom-event="${myListener}"></div>
`

There are two exceptions for the built-ins - class and style attributes. As they reflect different properties, the engine accepts a variety of values passed to expressions and it passes them to the right DOM APIs.

html`
  <button class="${{ primary: true, active: false }}">...</button>
`

You may think, that it can't work for all complicated use cases, but give it a try - after all the templates are just about elements composition, passing data and receiving feedback by event listeners!

A deeper explanation of the concept can be found in the Properties & Attributes section of the hybrids library documentation.

Let the host be with you

The most unique feature is related to one of the core patterns of the hybrids library. Instead of using this syntax, the descriptors' methods take a host element as a first argument. This simple shift has a great impact on data flow. The definition of the function is decoupled from the execution context, so those methods are pure functions (except obvious template side effects). A similar idea was implemented in the template engine.

The render factory requires that the passed function will return UpdateFunction(host, target), which takes two arguments - the host and target element. The template engine html not only produces an UpdateFunction but also supports it as a nested template used in the expression. It will be clearer if we look at the following example:

// We still have access to DOM `event` in the second argument
function doSomething(host, event) {
  host.name = 'Did it!';
}

const MyElement = {
  name: 'Do it!',
  render: ({ name }) => html`
    <div id="content">
      <button onclick="${doSomething}">${name}</button>
    </div>
  `,
};

Because the result of the template engine has access to the host element, we can use it for event listeners. Instead of passing only the event object, the first argument is the host. Do you see how this makes a huge difference? The user actions usually change the state of the component, not the element, with which the interaction was taken.

If we would not have direct access to the host element, we would have to create a dynamic function inside of the template:

const MyElement = {
  name: 'Do it!',
  render: (host) => {
    const { name } = host;
    return html`
      <div id="content">
        <button onclick="${() => { host.name = 'Did it!'; }}">${name}</button>
      </div>
    `,
};

In the above example, we no longer can use destructuring at the level of the arguments - we need a reference to the host. Also, the side effect became an internal part of the template.

It has two important implications. The function will be generated each time the template updates. Also, unit testing is much harder. Before, with access to the host, it was possible to write simple unit tests for the doSomething() function. It wasn't linked to the template at all nor to DOM elements - it was just a function, which takes an object and updates its name property. It's not possible with the callback defined inside of the template.

What about the nested templates? The expressions support passing UpdateFuncion, which html returns. Because of that, it's possible to create separate functions producing partial templates, even outside of the main component definition. If they use event listeners, the callbacks will still have the correct access to the component host element:

// It can be safely defined in a separate file, like `partials.js`
export default function buttonPartial(fn, name) { 
  return html`
    <button onclick="${fn}">${name}</button>
  `;
};

// And then imported
import buttonPartial from './partials';

// It still works, as the host is what we expect to be
function doSomething(host, event) {
  host.name = 'Yes, you did it!';
}

const MyElement = {
  name: 'Do it!',
  render: ({ name }) => html`
    <div>
      ...
      ${buttonPartial(doSomething, name)}
    </div>
  `,
};

The buttonPartial() function adapts to the place where it is used - so no matter in which component definition you will use it, the passed callback for a click event can run side effects related to the component.

Helper methods

At last but not least, I would like to share with you yet another unique approach. The template engine includes helper methods for setting the unique key of the template, dynamically defining web components and passing text-based styles.

The first one - key(id) - allows efficient re-order elements of the array. The lit-html requires using repeat() directive if we want to notify the library about items identifiers. Here you have an example from its documentation:

const employeeList = (employees) => html`
  <ul>
    ${repeat(employees, (employee) => employee.id, (employee, index) => html`
      <li>${index}: ${employee.familyName}, ${employee.givenName}</li>
    `)}
  </ul>
`;

And this is an explanation of the feature:

In most cases, using loops or Array.map is an efficient way to build repeating templates. However, if you want to reorder a large list, or mutate it by adding and removing individual entries, this approach can involve recreating a large number of DOM nodes.

The repeat directive can help here. Directives are special functions that provide extra control over rendering. lit-html comes with some built-in directives like repeat.

Isn't cooler in hybrids, that if you want to hold generated templates in the DOM, all you have to do is to add .key() at the end of the html call? Let's try to write the above example with the hybrids template engine:

const employeeList = (employees) => html`
  <ul>
    ${items.map(({ id, familyName, givenName }, index) => 
      html`<li>${index}: ${familyName}, ${givenName}</li>`.key(id),
    )}
  </ul>
`

The define() helper allows bootstrapping only the required elements and creating a tree-like dependency structure. With usage of this helper, a complex structure of elements may require only one explicit definition at the root level. In the following example, the UiHeader will be defined once the withHeader flag is turned on for the first time:

import UiHeader from './UiHeader';

const UiCard = {
  withHeader: false,

  render: ({ withHeader }) => html`
    <div>
      ${withHeader && html`
        <ui-header>...</ui-header>
      `.define({ UiHeader })}
      ...
    </div>
  `,
};

If you are going to use external CSS files for your project, the style() helper is what you need:

// `styles` should contain text content of CSS file
import styles from './MyElement.css';

const MyElement = {
  render: () => html`
    <div>...</div>
  `.style(styles),
};

A deeper explanation of how to use template helpers can be found in the Iteration, Dependencies and Styling section of the hybrids library documentation.

Summary

Those three features of the template engine that you get for free with the hybrids library show how little differences can make a huge impact on how we write code. The lit-html was created as a general-purpose rendering library, so some of the ideas presented here don't fit. However, in hybrids, the goal is one - make the best possible experience in building web components.

What's next?

Through the last articles, we have learned the main concepts, which apply to factories provided by the library. Let's take a closer look at them to know how to use their powers. One of those used mainly behind the scenes is the property factory (using translation feature). What happens when you define a property as a simple primitive value or complex object? We will find out with the next article from the series!

In the meantime, you can read more about the library at the project documentation.

🙏 How can you support the project? Give the GitHub repository a ⭐️, comment below ⬇️ and spread the news about hybrids to the world 📢!

Cover photo by Kelly Sikkema on Unsplash

Chasing the best performance of rendering the DOM by hybrids library

Dominik Lubański — Sat, 01 Jun 2019 14:34:40 +0000

This is the third in a series of posts about core concepts of hybrids - a library for creating Web Components from plain objects and pure functions.

It's been a while since the last post of the series. Let's catch up on what we have learned so far. The first post explained how the hybrids made web components definition possible without class and this syntax, but with a truly composable structure with pure functions. The second post described built-in cache and change detection mechanisms, which hide redundant lifecycle methods and keep data in sync in a declarative way. If you haven't read them yet, this is the moment to make up for it:

Finally, we can focus on one of the most critical features of all UI libraries - creating and updating the DOM. I think it is not a surprise that hybrids implements this feature slightly different than most libraries and frameworks:

Render is just yet another factory. The foundation of hybrids is the property descriptor concept. Instead of creating a separate internal structure, the library provides render feature as one of the built-in property factories. It brings important benefits. For example, you are not forced to use it. If a built-in solution does not match your needs, you can create a custom render factory, or define local descriptor, which renders and updates the DOM. Moreover, all specific features built for this purpose are available for other definitions. They are part of the public API.
Render factory is a template engine agnostic. Most of the projects force users to use the template solution chosen by the authors. Sometimes it is even impossible to use another one. It might look right - after all, this is considered to be the main objective of the UI libraries. However, I believe that it is always better to have a choice. Of course, hybrids render factory works out of the box with a built-in template engine, but you can easily replace it with React, lit-html or your favorite UI library (The only constraint is that it has to create and update the DOM).
You will always have the fastest solution. Whether you decide to use render factory or not, and whatever template engine you apply - you will still benefit from the hybrids foundations. The cache will prevent redundant calculations, while the change detection mechanism will schedule updates at the end of the next frame in the browser.

I could list many other advantages, but let's face it - rendering the DOM it's all about performance! How does it apply to hybrids? Even though being the fastest rendering library was never the primary goal, from the very beginning hybrids has provided performant DOM rendering. However, recent updates in the project show that some concepts had to be polished. I would like to share with you how I get to those changes, and how they helped hybrids be able to chase the performance of the fastest libraries.

Trigger for investigation

Last December, Vincent Ogloblinsky wrote to me about Web Components Benchmark project. He has created two suites of tests measuring the performance of the web components UI libraries, as well as some mainstream frameworks. Thank you, Vincent, for adding hybrids to your project!

If you would look at the results of the Todo List test, hybrids was somewhere in the middle. The stress test result was more disturbing (the test is about rendering thousands of elements of the Pascal Triangle, which has one hundred rows). The vanilla implementation was below 3 seconds. What about hybrids? It was more than 10 seconds! I thought that implementation might be wrong, but after a closer look, it became clear that some of my assumptions were wrong.

Recursion

When I run the Pascal Triangle test on my local machine, the first thing I noticed was an error message in the console:

Uncaught RangeError: Maximum call stack size exceeded
    at WeakMap.get (<anonymous>)
    at c (render.js:20)
    at c (render.js:30)
    at c (render.js:30)
    at c (render.js:30)
    ...

Ups... The render factory was using recursion in the update process. As long as a list of elements to render was lower than the call stack limit of the JavaScript engine (for V8 it is about 10k), everything worked. However, for one hundred rows, it blew up. I checked, and the safe number is 95. It was very close to not discover the problem!

By the way, the score of the test was even better than it should, as computation stopped before the end of the queue.

The obvious solution is to replace recursion with iteration, where you hold and replace the current item in the variable instead of calling the same function on the end of the loop. The same computation using iteration is also much faster than with recursion.

DOM Events

The second discovered problem was the change detection mechanism. It was built on top of the DOM events. I thought that using them is the right decision. After all, the library is about HTML elements, and they have built-in support for listening and dispatching events. Why should we create a custom structure if we can use "the platform"?

However, I missed one crucial fact - dispatching events can take half of the time of the rendering process if there are many elements there. Take a look at the fragment of Chrome Dev Tools performance chart:

When Pascal Triangle items are connected for the first time, they dispatch the DOM event to trigger their render process (controlled by change detection mechanism). This event is listened by render property of the element, which eventually triggers an update of the DOM of the item. More or less dispatching events takes the same amount of time as putting them in the document. However, if you look at the chart again, you can see another thing - the update process is split between several animation frames after the initial render.

Multiple calls to `requestAnimationFrame` API

In the time when I was rapidly developing hybrids, the asynchronous rendering of the React Fabric was a hot topic. Creating not blocking user input rendering was a tempting idea. And I deemed it's quite easy to implement. The render factory was already using requestAnimationFrame API to schedule the update. The only thing which I had to add was to split the work if the update lasted too long.

We always dream of 60 FPS, so without thinking twice, I set ~16ms budget. After the threshold, the rest of the work was done in the next animation frame (within the own ~16ms budget). No user input blocking, updates in the middle of rendering... It seems to be the holy grail... but it isn't. After each animation frame, the browser has to do a lot of work - recalculate styles, compose the layout, update layer tree, and eventually paint all of that on the screen. Simple structures of elements rarely hit the threshold. If your structure is massive on another hand - the sum of separated executions between frames will always be higher than done in a single one. But without it we might block user input for a long time, don't we?

To make it faster just do less

The above statement seems to be the obvious truth. But authors of some libraries claimed in the past that JavaScript is fast enough - the only problem is the DOM. However, studying performance charts of the Pascal Triangle test taught me, that every variable, call to function or iteration has a cost. We can't avoid some of the work, but functions can be less, data structures can be more straightforward, and iterations might be reduced or scheduled smarter.

The results

On the 29th of May, hybrids hit a new major version, with significant performance improvements. The change detection mechanism has been redesigned. Scheduler, which was an internal part of the render factory is now available for all descriptors. Also, it does not use recursion in the implementation. Instead of attaching and removing event listeners, you should use observe method. It's called in the property scope and only if the property value has changed (it also tracks all dependencies and notify if they change). The callback is queued with requestAnimationFrame API but without the threshold. In the result render factory is now implemented within 30 lines of code. The rest is now an internal part of the library.

If you wonder how those changes apply to the Pascal Triangle test, I am happy to say that time dropped from 10 to 4.3 seconds. It's now less than half of the previous result! The test takes place in a throttled environment (CPU and network are slowed down), so the differences between scores are more important than absolute time, so check out other results on the project home page.

The hybrids library is not yet the number one in the Pascal Triangle test. However, take into account that this is a synthetic test. I would not recommend creating UI, which at one time renders more than five thousands of elements. What is worth to mention is how hybrids performs when we increase the number of rows. When we change the length property from one hundred to one hundred and one, re-render takes 100ms in the throttled environment, while without throttling, it's less than 35ms!

On another hand, Todo List test is much closer to real usage. Before the changes hybrids was somewhere in the middle, but now results are much better - in some areas it is even close to the best in the competition!

Unleashed the power of cache

Decoupling change detection from the DOM has one unique hidden goal, which is not directly related to performance issues. From now, it is possible to attach a cache mechanism to objects, that are not HTML elements. Why is it important? A few months ago, I started working on a new built-in factory - the store. The main goal is to create state management for asynchronous data using all of the hybrids goodies. Without the ability to apply the cache mechanism on that data, it would not be possible. As usual in hybrids, this factory won't be another clone of an existing solution. The idea is to combine fetching, storing, caching, and serving data to your elements in a seamless way as possible. Stay tuned for more details in the next months!

What's next?

The DOM rendering will be as fast as its the weakest point. The render factory is, for now, free of performance issues, but what about the template engine? In the next post of the series, we will learn more about the features of the built-in template engine. Even though it may look similar to lit-html at first, with a closer look, it shows unique patterns taken from core concepts of the library.

In the meantime, you can read more about the library at the project documentation.

🙏 How can you support the project? Give the GitHub repository a ⭐️, comment below ⬇️ and spread the news about hybrids to the world 📢!

Cover photo by Saffu on Unsplash

Say goodbye to lifecycle methods, and focus on productive code

Dominik Lubański — Tue, 29 Jan 2019 09:28:42 +0000

This is the second in a series of posts about core concepts of hybrids - a library for creating Web Components with simple and functional API.

One of the most rooted features of component-based UI libraries is a complex lifecycle. It is a group of methods, which provide full control over the state of the component that may change over time. Usually, libraries use self-explaining name convention and call did* methods after something happens and will* before the change. While studying the library docs, we often find a whole range of possibilities, which can lead to confusion or even frustration. After all, you need to have an in-depth understanding to create correct and efficient code. For example, the component state may depend on a specific sequence of events in time, which makes the code hard to test and eventually maintain or extend.

Is it so bad?

Let's face it two obscure facts about lifecycle methods. Firstly, they shift the burden of state management from the library to us. As it might look legit, it usually means, that we have to write more redundant code manually:

class MyComponent extends Component {
  componentDidUpdate(prevProps) {
    if (this.props.name !== prevProps.name) {
      // do something...
    }
  }
}

In the above example, the library provides a map of previous properties, but it doesn't inform which of them has a new value. We have to create conditions explicitly to be sure that our code is called only if the name property has changed.

In another hand, if a component requires asynchronous data, lifecycle structure may force to fetch data twice - for the first time in something like componentDidMount() method, and then each time in componentDidUpdate() when the dependencies change:

import { getUser } from './api';

class MyComponent extends Component {
  componentDidMount() {
    this.fetch();
  }

  componentDidUpdate(prevProps) {
    if (this.props.userId !== prevProps.userId) {
      this.fetch();
    }
  }

  fetch() {
    getUser(this.props.userId)
      .then((data) => this.setState({ data }));
  }
}

Even though we have extracted redundant logic into the fetch() method, it has to be called twice in two separate lifecycle methods.

Both code examples might look familiar to you. In fact, they represent what the React.Component class provides. React of course is not a web components library, but LitElement, Omi, Slim.js, Stencil and many others follow the trends, and they implemented very similar concepts (use the links to go to the lifecycle section of libraries documentation).

In the first post of the series, we have learned how we can switch component definition from the class syntax into the map of independent property descriptors. If you haven't read it yet, it's a good moment to do so:

From classes to plain objects and pure functions

Dominik Lubański for hybrids ・ Jan 10 '19

#webdev #webcomponents #javascript #functional

This time we will go deeper into the property descriptor definition and learn more about cache mechanism, change detection and its connect method.

Different approach

Lifecycle methods pushed us to think more about when something happens rather than to define how we can get what we need. What would you say if you could focus on value computations and leave the rest to the library?

The hybrids property descriptors concept introduced much more than only a middleware for holding property value. The library provides a complete cache and change detection mechanism.

A component, which requires data fetched asynchronously can be defined with hybrids just like that:

import { html } from 'hybrids';
import { getUser } from './api';

const AsyncUser = {
  userId: 1,
  data: ({ userId }) => getUser(userId),
  render: ({ data }) => html`
    <div>
      ${html.resolve(
        data.then(user => html`
          <span>${user.firstName}</span>
        `),
      )}
    </div>
  `,
};

Click here to play with a live example on ⚡️StackBlitz

The above definition includes userId, data and render descriptors. The data property depends on userId and returns a promise with user details. Don't bother much about the render property for now. You should need to know now that it uses under the hood the render factory (using property translation), which uses html function to create and update contents of the custom element. In the body of the template, we are using dynamic value, which resolves data promise to an element with the first name of the user.

Cache mechanism

The cache mechanism is attached to the getter and setter of every property defined by the library. For set method it automatically updates the cache if calculation returns a new value. For get method cache ensures that the value is only computed if needed, for example, when one of the property dependency has changed. In our example, it means, that getUser() will be called to set an initial value and only when userId will change. How does it work?

The cache controls the data, as well as userId property. When userId is called inside of the data getter, the cache can save it as a data dependency. Next time, when we call data, cache checks userId from the cache and calls getUser(userId) only if userId has changed. Otherwise, it returns the last cached value and omits getter. The cache is global for all elements defined by the library so we can depend on properties defined in other elements too!

The cache concept uses the fact that properties are never computed if they are not called (even if the dependencies have changed). You could try to get a value of data manually, and you would see, that it returns the same promise all the time. However, if you change userId property, data will return a new promise called next time.

Simplified lifecycle

In the first post, we have learned that the property descriptor may have get and set methods. Actually, you can define two more for property lifecycle control - connect and observe method. connect method can return a function, which is called when an element is disconnected. While the observe method is called asynchronously when the property value changes.

{
  get: (host, lastValue) => {...},
  set: (host, value, lastValue) => {...},
  connect: (host, key, invalidate) => {
    // ...
    return () => {...}; // disconnect
  },
  observe: (host, value, lastValue) => {...},
};

However, in the above AsyncUser example we didn't have to use it explicitly. We even didn't have to create property descriptors at all! If we would take all the concepts together, we may start to see a bigger picture here. The raw descriptor provides all the required features to create stateful properties. Then the library adds on top of that cache mechanism. However, the preferred way to define properties is to use built-in or custom factories (functions, that produce descriptors). As the property definition is independent, you can re-use factories wherever you want. As the result, you don't have to define connect method by yourself, and you can focus on productive coding in a declarative way!

Invalidation

You may have noticed a third argument of the connect method - invalidate callback. If a property has only a getter, but it depends on third-party tools, invalidate is a clever way to notify cache, that value should be computed next time. Because of the functional structure, it is super easy to create properties connected to external state managers like redux:

import store from './store';

function connect(store, mapState) {
  return {
    get: (host) => mapState(store.getState(), host),
    connect: (host, key, invalidate) => store.subscribe(invalidate),
  };
};

Redux subscribe method takes a callback where we can pass invalidate. It returns unsubscribe function so we can call it in the connect method defined as an arrow function. We can use the factory in the component definition, like in the following example:

import store from './store';
import connect from './connectFactory';

const MyElement = {
  userId: 1,
  userDetails: connect(store, ({ users }, { userId }) => users[userId]),
};

Change detection mechanism

In the last part of the post let's go back to render property. If the library does not call getters for us, how is it possible that our component works? Even though render might look special, is it the same property descriptor as the rest. The difference is in how the render factory uses connect and observe methods.

The best way to understand how render works is to built a simplified version:

function render(fn) {
  return {
    get: (host) => fn(host),
    connect: (host, key) => {
      if (!host.shadowRoot) host.attachShadow({ mode: 'open' });
    },
    observe: (host, fn) {
      fn(host, host.shadowRoot);
    },
  };
}

Our render factory returns descriptor with get, connect and observe methods. We took advantage of the cache mechanism, so our getter calls fn and saves its dependencies. The property value will be only recalculated if one of the properties used in the fn changes.

The connect creates shadowRoot if it is not already there. Then we want to call fn whenever dependencies change. It is exactly what observe method provides. It might looks familiar to componentDidUpdate() callbacks from other libraries. Eventually, we want to do something when the change occurs. However, the idea behind the observe method is much deeper. The library calls it only when the value of the property has changed. This method is also called only once during the current event loop, because of the internal queue scheduled with requestAnimationFrame API. We don't have to bother to check what property has a new value or not because we covered it with the cache mechanism.

Summary

It might be a lot of new stuff to process. For sure, hybrids didn't give up on lifecycle methods. They are just redesigned and implemented in the opposite direction to patterns known from other libraries. In the explained component example, the chain of cause and effect goes from render property to data (in other libraries it would go from fetching data to rendering new state). A function, which creates a template, wants user details, and only because of that they are fetched, and they eventually trigger an update of the template. If in some condition the template would not require those data, they would not be fetched at all.

We can call it simplified lifecycle. If we add on top of that smart cache mechanism and all already known property-based concepts, it changes everything. We can shift the most of state-related responsibility to the library and focus on the business logic of our components. Usually, the component requires a list of properties for holding simple or computed values and render method for creating element structure. If we need something not covered by the library, we can easily create reusable factories and still do not use lifecycle methods directly.

What's next?

Today, we have scratched the surface of the render factory. In the next post of the series, we will learn more about render factory provided by the library, as well as the rich template engine built on top of tagged template literals.

In the meantime, you can read more about the hybrids library at the project documentation.

hybridsjs / hybrids

Extraordinary JavaScript UI framework with unique declarative and functional architecture

An extraordinary JavaScript framework for creating client-side web applications, UI components libraries, or single web components with unique mixed declarative and functional architecture

Hybrids provides a complete set of features for building modern web applications:

Component Model based on plain objects and pure functions
Global State Management with external storages, offline caching, relations, and more
App-like Routing based on the graph structure of views
Layout Engine making UI layouts development much faster
Localization with automatic translation of the templates content
Hot Module Replacement support without any additional configuration

Documentation

The project documentation is available at the hybrids.js.org site.

Quick Look

Component Model

It's based on plain objects and pure functions¹, still using the Web Components API under the hood:

import { html, define } from "hybrids";
function increaseCount(host) {
  host.count += 1;
}

export default define({
  tag:

…

View on GitHub

🙏 How can you support the project? Give the GitHub repository a ⭐️, comment below ⬇️ and spread the news about hybrids to the world 📢!

👋 Welcome dev.to community! My name is Dominik, and this is my third blog post ever written - any kind of feedback is welcome ❤️.

Cover photo by Paul Skorupskas on Unsplash

From classes to plain objects and pure functions

Dominik Lubański — Thu, 10 Jan 2019 19:00:37 +0000

This is the first in a series of posts about core concepts of hybrids - a library for creating Web Components with simple and functional API.

ES2015 has introduced classes that are now widely used in UI libraries and frameworks. However, are they the best way for creating component-based logic in JavaScript? In my last post, I've highlighted some of the main classes pitfalls:

Do we really need classes in JavaScript after all?

Dominik Lubański ・ Dec 11 '18

#discuss #javascript #webdev #webcomponents

The hybrids library is the result of research on how we can take a different approach, and create simple and functional tools for building web components. However, the only way to create a custom element is to use a class, which extends HTMLElement, and define it with Custom Elements API. There is just no other way (you can also use function constructor with properly reflected super() call). So, how is it possible that hybrids uses plain objects instead of classes?

The answer is a combination of three property-related concepts used together: property descriptors, property factories, and property translation. Let's break down those concepts into the step by step process with a simple custom element definition.

Step 1: Use Custom Elements API

For a better understanding of the process, we are going to use an example with minimal requirements of the Custom Elements API. The goal here is to show how we can switch from class definition to plain object with pure functions.

class MyElement extends HTMLElement {
  constructor() {
    this.firstName = 'Dominik';
    this.lastName = 'Lubański';
  }

  get fullName() {
    return `${this.firstName} ${this.lastName}`;
  }
}

customElements.define('my-element', MyElement);

Our custom element definition has two simple properties (firstName and lastName) and one computed property, which returns the concatenation of the first two. The example does not contain methods, but they can be easily transformed using the same process (you can define a method as computed property, which returns a function).

Step 2: Desugar class syntax using the prototype

The class syntax is nothing more than syntactical sugar on top of the function and its prototype. Every class definition has prototype property, which holds the class methods (expect constructor). What is important, we can change it after the definition, so the body of the class can be empty. Properties can be defined directly on the MyElement.prototype using Object.defineProperty() method. The prototype delegation may work unexpected with normal values, so we should define only computed properties, which return values related to the context.

class MyElement extends HTMLElement {}

// before: this.firstName in constructor()
Object.defineProperty(MyElement.prototype, 'firstName', {
  get: function get() {
    return this._firstName || 'Dominik';
  },
  set: function set(val) {
    this._firstName = val;
  },
  configurable: true,
});

// before: this.lastName in constructor()
Object.defineProperty(MyElement.prototype, 'lastName', {
  get: function get() {
    return this._lastName || 'Lubański';
  },
  set: function set(val) {
    this._lastName = val;
  },
  configurable: true,
});

// before: fullName computed property in the class body
Object.defineProperty(MyElement.prototype, 'fullName', {
  get: function fullName() {
    return `${this.firstName} ${this.lastName}`;
  },
  configurable: true,
});

customElements.define('my-element', MyElement);

It may seem that we have taken a step back. The code has become more verbose and redundant (A simple structure of the class definition was one of the reasons for the introduction of the class syntax). Also, the current implementation is not consistent with the original one. If we set one of the properties to falsy value, it will still return a default value. We'll take care of that in the fifth step. For now, we have to focus on cleaning out our definition.

Step 3: Hide redundant code into the custom definition

All properties are defined by the Object.defineProperty() method. We can extract passed arguments to a map of property names and descriptors, and put the rest into the custom function, which will replace customElements.define() method.

const MyElement = {
  firstName: {
    get: function get() {
      return 'Dominik' || this._firstName;
    },
    set: function set(val) {
      this._firstName = val;
    },
  },
  lastName: {
    get: function get() {
      return 'ConFrontJS' || this._lastName;
    },
    set: function set(val) {
      this._lastName = val;
    },
  },
  fullName: {
    get: function fullName() {
      return `${this.firstName} ${this.lastName}`;
    },
  },
};

defineElement('my-element', MyElement);

This is how the property descriptors concept works. The MyElement is now a plain object with a map of property descriptors, which we define on the custom element prototype.

Our defineElement() function could be defined like this:

function defineElement(tagName, descriptors) {
  class Wrapper extends HTMLElement {}

  Object.keys(descriptors).forEach(key => {
    Object.defineProperty(Wrapper.prototype, key, {
      ...descriptors[key],
      configurable: true,
    });
  });

  return customElements.define(tagName, Wrapper);
}

Step 4: Get rid of "this"

The custom function opens the way for further optimization. From now, we have all control over the structure of the input. Instead of passing through property descriptors to Object.defineProperty(), a function can create them dynamically. We can finally kill the last standing bastion - this keyword.

The first argument of get and set methods may become a host - an element instance. Because of that, we no longer have to access a custom element instance by this keyword. Moreover, methods are pure - they depend only on arguments and have no side effects. Removing context also allows using some of the useful features of ES2015 like arrow functions and destructuring function parameters.

const MyElement = {
  firstName: {
    get: ({ _firstName }) => _firstName || 'Dominik',
    set: (host, value) => { host._firstName = value; },
  },
  lastName: {
    get: ({ _lastName }) => _lastName || 'Lubański',
    set: (host, value) => { host._lastName = value; },
  },
  fullName: {
    get: ({ firstName, lastName }) => `${firstName} ${lastName}`,
  },
};

Our definition has shrunk significantly. We have replaced ordinary functions with arrow functions, and the host parameter has been destructured for the get calls.

Step 5: Add middleware to save property value

A computed property by design doesn't hold its value. The definition is a pair of functions (not values), which one of them returns the current state of the property taken from external dependencies, and second updates those external dependencies. In our current solution firstName and lastName properties depend on _firstName and _lastName properties from the custom element instance (they are defined when set method is invoked for the first time).

Using the fact from the third step, we can introduce a local variable during the property definition in our custom define function. The value can be passed to get and set methods as a new last argument - lastValue. From now, get and set methods should return the current value of the property.

const MyElement = {
  firstName: {
    get: (host, lastValue = 'Dominik') => value,
    set: (host, value, lastValue) => value,
  },
  lastName: {
    get: (host, lastValue = 'Lubański') => value,
    set: (host, value, lastValue) => value,
  },
  fullName: {
    get: ({ firstName, lastName }) => `${firstName} ${lastName}`,
  },
};

You can notice how default values are handled now. We've started using another ES2015 feature - default parameters. Those arguments are initialized with default values if no value or undefined is passed. It's much better than the solution with || operator. Although, the firstName and lastName sill return Dominik or Lubański if we set them to undefined (In a real-world scenario, it is not a problem, as we can use a built-in factory from the library, which covers that case).

Step 6: Introduce property factory

After all of the optimizations, we can find redundant code again - firstName and lastName property descriptors have become almost the same. Only a default value is different. To make it cleaner and simpler we can create a function - property factory, which returns property descriptor parameterized by the arguments.

export function property(defaultValue) {
  return {
    get: (host, lastValue = defaulValue) => value,
    set: (host, value) => value,
  };
}

We can now replace firstName and lastName descriptors with property() function invocation:

import property from './propertyFactory';

const MyElement = {
  firstName: property('Dominik'),
  lastName: property('Lubański'),
  fullName: {
    get: ({ firstName, lastName }) => `${firstName} ${lastName}`,
  },
}

With the property factories concept, we can define properties with only one line of code! Factories hide implementation details and minimize redundant code.

Step 7: Introduce property translation

We still have the last concept to follow. Our custom define function takes only descriptors, which are objects with pre-defined structure. What could happen if we allowed passing primitives, functions, or even objects, but without defined methods?

The property translation concept provides a set of rules for translating property definition that does not match property descriptor structure. It supports primitives, functions, or even objects (without descriptors keys).

For example, if we set the value of the firstName property to a primitive, the library uses the built-in property factory to define it on the prototype of the custom element. In another case, if you set property value as a function, it is translated to a descriptor object with get method.

In the result, custom element definition can be a simple structure of default values and pure functions without external dependencies:

const MyElement = {
  firstName: 'Dominik',
  lastName: 'Lubański',
  fullName: ({ firstName, lastName }) => `${firstName} ${lastName}`,
}

Summary

Here is the end of today's coding journey. In the last step we have created the simplest possible definition without class and this syntax, but with truly composable structure with pure functions.

The whole process has shown that it is possible to replace imperative and stateful class definition with a simple concept of property descriptors. The other two, property factories and property translation, allow simplifying the definition either further.

What's next?

Usually, custom elements do much more than our simple example. They perform async calls, observe and react to changes in the internal and external state and many more. To cover those features, component-based libraries introduced sophisticated lifecycle methods and mechanisms for managing external and internal state. What would you say if all of that was no longer needed?

In the next post of the series, we will go deeper into the property descriptor definition and know more about the cache mechanism, change detection and independent connect method.

Say goodbye to lifecycle methods, and focus on productive code

Dominik Lubański for hybrids ・ Jan 29 '19

#webdev #javascript #webcomponents #functional

You can read more about the hybrids library at the project documentation.

hybridsjs / hybrids

Extraordinary JavaScript UI framework with unique declarative and functional architecture

An extraordinary JavaScript framework for creating client-side web applications, UI components libraries, or single web components with unique mixed declarative and functional architecture

Hybrids provides a complete set of features for building modern web applications:

Component Model based on plain objects and pure functions
Global State Management with external storages, offline caching, relations, and more
App-like Routing based on the graph structure of views
Layout Engine making UI layouts development much faster
Localization with automatic translation of the templates content
Hot Module Replacement support without any additional configuration

Documentation

The project documentation is available at the hybrids.js.org site.

Quick Look

Component Model

It's based on plain objects and pure functions¹, still using the Web Components API under the hood:

import { html, define } from "hybrids";
function increaseCount(host) {
  host.count += 1;
}

export default define({
  tag:

…

View on GitHub

🙏 How can you support the project? Give the GitHub repository a ⭐️, comment below ⬇️ and spread the news about hybrids to the world 📢!

👋 Welcome dev.to community! My name is Dominik, and this is my second blog post ever written - any kind of feedback is welcome ❤️.

Cover photo by Patrick Robert Doyle on Unsplash

DEV Community: hybrids

Three unique features of the hybrids template engine that you must know

Inspiration

Closest to the roots

Let the host be with you

Helper methods

Summary

What's next?

Chasing the best performance of rendering the DOM by hybrids library

Trigger for investigation

Recursion

DOM Events

Multiple calls to requestAnimationFrame API

To make it faster just do less

The results

Unleashed the power of cache

What's next?

Say goodbye to lifecycle methods, and focus on productive code

Is it so bad?

From classes to plain objects and pure functions

Dominik Lubański for hybrids ・ Jan 10 '19

Different approach

Cache mechanism

Simplified lifecycle

Invalidation

Change detection mechanism

Summary

What's next?

hybridsjs / hybrids

Extraordinary JavaScript UI framework with unique declarative and functional architecture

Documentation

Quick Look

Component Model

From classes to plain objects and pure functions

Do we really need classes in JavaScript after all?

Dominik Lubański ・ Dec 11 '18

Step 1: Use Custom Elements API

Step 2: Desugar class syntax using the prototype

Step 3: Hide redundant code into the custom definition

Step 4: Get rid of "this"

Step 5: Add middleware to save property value

Step 6: Introduce property factory

Step 7: Introduce property translation

Summary

What's next?

Say goodbye to lifecycle methods, and focus on productive code

Dominik Lubański for hybrids ・ Jan 29 '19

hybridsjs / hybrids

Extraordinary JavaScript UI framework with unique declarative and functional architecture

Documentation

Quick Look

Component Model

Multiple calls to `requestAnimationFrame` API