DEV Community: Lukas Bach

Headless Tree is now available in Beta!

Lukas Bach — Tue, 15 Apr 2025 19:53:26 +0000

Lukas Bach

Apr 15 '25

Headless-Tree, and the Future of React-Complex-Tree

#webdev #react #a11y

Comments

9 min read

Headless-Tree, and the Future of React-Complex-Tree

Lukas Bach — Tue, 15 Apr 2025 19:50:52 +0000

Hey everyone! I'm Lukas, I have created react-complex-tree and maintained it over the last couple of years. Quite some time ago, I started the development of a successor library, Headless Tree, which is now available in a Beta phase and will soon become available as stable release. In this blog post, I want to give some insights into this library, what it's plans and future goals are, and how it relates to the future of react-complex-tree.

TLDR: Headless-Tree is a reimplementation of react-complex-tree, with the goal of providing the same features while improving on many of the disadvantages or compromises I had to take based on the architecture of react-complex-tree. At the moment, I have no plans of deprecating react-complex-tree. New features include virtualization support, better performance and smaller bundle size, easier interfaces, better customizability and more drag-related capabilities. Feel free to join the community on Discord to contribute with ideas, thoughts or PRs, or follow BlueSky for updates!

In the following, I will use the abbreviation RCT for react-complex-tree, and HT for Headless Tree.

Some history on react-complex-tree

I started working on RCT more than four years ago, with the goal of building a library for accessible tree views for the web. The motivation was a lack of libraries which are able to deliver on all important aspects of the expectations that users have from tree views, and since most of us are software developers who use powerful IDEs everyday, our expectations go pretty far. At the same time, the ecosystem didn't really provide anything that is fully accessible, provides powerful drag-and-drop capabilities, supports hotkeys and multi select and so on. So my goal with RCT was to fill that gap. At the same time, the library should be unopinionated and well suited for as many projects as possible.

As such, the library only focused on bridging the gap between your structured tree data, and rendering the data. It was still your task to manage the data model below, which makes sense since that will differ a lot between use cases and a library design that is too specific in that aspect makes the library unsuited for many users. Also, rendering the data is up you, which is also important since we don't want to force specific UI libraries on you.

While RCT gives you quite a bit of flexibility, the interface still feels inflexible in some ways. RCT provides a big React component which renders the entirety of the tree, and allows you to customize individual parts of the tree with custom render methods.

<UncontrolledTreeEnvironment
  renderItem={(title, arrow, children) => (
    <li {...context.itemContainerWithChildrenProps}>
      <button
        {...context.itemContainerWithoutChildrenProps}
        {...context.interactiveElementProps}
      >
        {arrow}
        {title}
      </button>
      {children}
    </li>
  )}
>
  // ...
</UncontrolledTreeEnvironment>

The reason for not letting you render everything yourself, is that W3's accessibility requirements for trees with computed properties rather strictly dictate how a tree should be rendered, and the recursive tree structure makes it hard to provide an easy-to-use interface for that, which is why RCT still manages the complicated accessibility-compliant tree render-structure for you.

<ul>
  <li><a>1. level</a></li>
  <li>
    <a>1. Level</a>
    <ul>
      <li><a>2. Level</a></li>
    </ul>
  </li>
</ul>

The fact that RCT manages this aspect of rendering also means that certain performance aspects are out of your hand, and RCT-internal rerendering mechanics degrade performance quite a bit for certain tree structures. Also, virtualization is hard to achieve as library consumer since you have barely any control of how the overall structure is rendered. It would have been possible to implement virtualization as core part of the library, but I also didn't want that since virtualization can be janky in many cases, and forcing it onto every user is also something that I don't think would have made a lot of sense.

Why a new library?

All those short-comings of the library - Poor performance in certain use cases, no compatibility with virtualization, no full control over render-logic - are all things I realized over time are important, and I also realized that the current interface of RCT is mostly incompatible with solving those issues. At the same time, maintaining React Complex Tree for four years, fixing many bugs and working together with many contributors and users has taught me many things about what is important in production use cases, and what a tree library needs to have to succeed as battle-tested product. This is why I have decided to build a new library, Headless Tree, which aims to solve those shortcomings with a new API that is easier to work with.

I have solved the underlying accessibility way a different way: By using declared properties instead of computed properties, it is possible to achieve a W3C compliant tree implementation, that can use a flattened rendered list of tree items, making customization by users significantly easier and providing a trivial interface to virtualize the rendering with. With declared properties, the tree instead injects information about the tree structure into aria attributes, that are interpreted by accessibility tools the same way how DOM structure is interpreted for computed properties otherwise. This allows the library to actually give the rendering responsibility entirely into your hands. At the same time, the flat structure also makes the concept easily compatible with virtualization, so easy that you can just plop the data you get from HT directly into a virtualization library of your choice and just render its output instead.

<button aria-setsize="2" aria-posinset="0" aria-level="0">1. Level</button>
<button aria-setsize="2" aria-posinset="1" aria-level="0">1. Level</button>
<button aria-setsize="1" aria-posinset="0" aria-level="1">2. Level</button>

Headless Tree will still take the responsibility of computing all necessary props for each element including all those ARIA attributes. HT will then provide the its interface through a single hook instead of an overly-complicated component:

  const tree = useTree<string>({
    rootItemId: "folder",
    getItemName: (item) => item.getItemData().name,
    isItemFolder: (item) => !item.getItemData().isFolder,
    dataLoader: {
      getItem: (itemId) => myData[itemId],
      getChildren: (itemId) => myData[itemId].childrenIds,
    },
    features: [ syncDataLoaderFeature, selectionFeature, hotkeysCoreFeature ],
  });

  return (
    <div ref={tree.registerElement}>
      {tree.getItems().map((item) => (
        <div
          key={item.getId()}
          style={{ marginLeft: `${item.getItemMeta().level * 20}px` }}
        >
          <button
            {...item.getProps()}
            ref={item.registerElement}
          >
            {item.getItemName()}
          </button>
        </div>
      ))}
    </div>
  );

This new interface and the fact that rendering is now completely separated from the library itself, also has another benefit, which you might have guessed from its new name compared to react-complex-tree: There is no direct relation to React anymore, and support for other UI frameworks is totally viable! At the moment, the majority of HL lives in a framework-agnostic package @headless-tree/core , and the React hook is a very thin 50 LOC binding in a separate @headless-tree/react package. I haven't started to port the react bindings to other frameworks, but plan to do so in the future.

Also, I want to mention another thing at this point: If you have used Tanstack Table in the past, then both the public interface and the internal implementation of the library might be similar to what you've seen in the past. HT's implementation and interface is largely motivated by Tanstack Table, with its modularity in terms of features, and the way how its hook-based interface works. Big thanks to Tanstack providing a motivation for how interfaces for modern framework-agnostic UI libraries should look like!

What does that mean for react-complex-tree?

Over the past years, I have continuously tried to use the time I had available to maintain react-complex-tree as good as I could. There definitely were areas that needed more attention, but honestly, I reached a point where I was pretty happy with the state of react-complex-tree quite some time ago. This meant that I haven't really implemented new features for a long time now, but instead focused on maintenance and fixing bugs. I think that the issues reported in the past reflect that well, since most are bug reports that I do my best to fix once they come up. There are some open discussions about features like virtualization, but I provided some details above why those features are so hard to implement with RCT.

The goal of Headless Tree is to build a new library that provides the basis for delivering those features that I was unable to do with react-complex-tree. However, I do not plan to deprecate react-complex-tree at this time, nor will I stop working on bug fixes for issue reports that come in. If you are currently using react-complex-tree and find that it fulfills your requirements, there is no reason to switch away. I'll continue maintenance for it, and plan to do so even after HT reached a mature state. New bigger features are not planned for RCT, but they have not been for a longer time now, instead I will focus on HT to provide those features, where it is more viable to do so.

However, if you are looking for a tree-library and found that RCT lacks certain aspects for your use case, or if you already integrated RCT and still lack certain features, or even if you were happy with RCT in the past and are curious about the future, I suggest having a look at Headless Tree, see what it has to offer and maybe even join its community and see if you are interested in contributing or maybe just engage in discussions.

Other new features with Headless Tree

In addition to the simplified interface and support for virtualization, there are many other things that are newly supported by Headless Tree.

RCT already supported dragging items between several tree instances within a single tree environment. HT breaks apart the boundaries of environments, and allows individual tree instances to define interfaces for how they interact with arbitrary external drag events. This can be used to hook up several similar or not-so-similar trees, but also to support dragging non-tree items into a tree, or accepting drag events in custom components while dragging tree items.

There are more hotkeys to customize, and it's easier to customize them. In addition to that, it's very easy to implement completely new hotkeys that do custom logic within a tree:

  const tree = useTree<string>({
    hotkeys: {
      focusNextItem: {
        hotkey: "ArrowRight",
      },
      focusPreviousItem: {
        hotkey: "ArrowLeft",
      },
      customExpandAll: {
        hotkey: "Ctrl+q",
        handler: (e, tree) => {
          tree.expandAll();
        },
      },
    },
    features: [
      syncDataLoaderFeature,
      selectionFeature,
      hotkeysCoreFeature,
      expandAllFeature,
    ],
  });

RCT wasn't terribly large, but certainly not a tiny library with a 16.8kB gzipped bundlesize, due to the many features it offered and which it exposed via a single symbol. Headless Tree is not just smaller at 9.4kB, but exposes its features as seperate variables that can manually be included or not, depending on what you need. This allows you to stay below 5kB in many cases, if you just use the features you need.

The feature composability also allows you write your own plugins to HT as new features, that add new capability to the tree functionality. It also makes it easier to customize Headless Tree, since you can write small features that just replace parts of what core features contribute, or copy the entire implementation of a feature such as drag-and-drop and change it exactly to how you want it to work.

When will Headless Tree become available as stable release?

Headless Tree is already in a pretty stable state. So far, I've handled HT as "alpha" state, meaning that I considered bugs to be expected and allowed patch version bumps to have breaking changes. As of now with the availability as Beta, I will start proper versioning and make efforts to keep the current API stable in future releases, and maintain semantic versioning for breaking changes. I would be very happy for you to try it out and let me know of any bugs you may encounter, and report them via Github Issues so I can look into them. You can find documentations on how to get started on the Headless Tree Homepage. You can also join the Headless Tree Discord to share your thoughts or interest to contribute. If you want to support the development of Headless Tree, you can also do so via my GitHub Sponsors Page or by sharing the word about it and starring it on GitHub.

Once I got some feedback on the current state of HT and fixed the initial bug reports that will come in, I plan to release it as stable release in the next two months.

A more streamlined development workflow for Obsidian plugins

Lukas Bach — Fri, 28 Apr 2023 15:42:07 +0000

I recently started to play around with Obsidian as note taking app, and am a very big fan of the large availability of community plugins and the open architecture that really allows lots of customizability through plugins. I wanted bridge the gaps of features that I was missing from Obsidian so far, and built two of my own plugins that recently got published in the Obsidian app store: Obsidian Code Files, a plugin for editing text files with Monaco Editor, the editor instance that powers VSCode, and Obsidian File Order, a plugin for reordering files in the file tree.

In this short article, I wanted to share some learnings that I gained from building these two plugins, and the setup I ended up with to automate the majority of the development and releasing process, which is what I find somewhat complicated and unintuitive by itself.

The usual plugin development process

Obsidian provides a GitHub template repo that can be used as starter to build a plugin. It contains a scaffold of what is needed to get started, and some documentation on what needs to be done to develop and release plugin versions, but the entire process feels very manual and has many steps involved.

Let's start by looking into how plugins are distributed and installed: A plugin consists of a main.js and a manifest.json file, and optionally also a styles.css file. When installed, they are stored in the .obsidian/plugins/pluginname folder within your vault. To release a new version, a new GitHub release needs to be published, and the plugin files need to be attached to the release. The version in the release needs to be bumped and match the version in the manifest.json file. A comprehensive documentation is available in the readme of the template repo.

The template repo contains a custom version script which automatically syncs the version in the package.json file with the version in the manifest.json file, so bumping the version through npm version will also bump the manifest file. It also contains an esbuild setup to build and bundle the TypeScript source code into a main.js bundle file. However, drafting the GitHub release, making sure it has the right name (since the plugin registry of Obsidian is actually sensitive against the release name), and uploading the files is still a manual process. This is tedious, but can also lead to human failure, for example if you forget to build the plugin beforehand and thus publish an old version, or use an incorrect version.

Also development is inconvenient because there is no perfect way to get the plugin into Obsidian while you develop it. The intended way is to place your entire repo into the plugins folder of your Obsidian vault, so that Obsidian sees the built JS file and directly loads the plugin from there. However, being restricted in where to place the repo is inconvenient for some setups (for example, I have my vault placed in a OneDrive folder, but I don't want to place a repository with a gigantic node_modules folder somewhere where it will be synced with a cloud), and also you need to reload the Obsidian UI everytime you make a change.

Improving the development process

To make development easier, I've opted into using the package obsidian-plugin-cli. It is an unofficial utility tool not maintained by Obsidian, and is still marked as Alpha software with the note that it will bring breaking changes in the future. However, I found that it improved the development process greatly, was really easy to use and didn't really have any issues that I encountered.

It replaces the esbuild setup in your plugin project, which previously just build your TypeScript source into a JS bundle, with a more elaborate setup that does many things for you. It wraps an esbuild setup so you don't have to define your own, but more importantly, provides a "watching" dev script that automatically installs your devloped plugin into a local vault of your choosing, and automatically rebuilds it when changes are detected. That means you can place the source code of your plugin anywhere on your machine, and just install your plugin into any arbitrary vault.

That means, that the scripts

{
  "scripts": {
    "dev": "node esbuild.config.mjs",
    "build": "tsc -noEmit -skipLibCheck && node esbuild.config.mjs production"
  }
}

becomes

{
  "scripts": {
    "dev": "obsidian-plugin dev --with-stylesheet src/styles.css src/main.ts",
    "build": "obsidian-plugin build --with-stylesheet src/styles.css src/main.ts"
  }
}

The library does the rest for you. It also offers to install a hot-reload plugin into Obsidian, which will automatically to a light reload in Obsidian when you change something locally in your plugin, which is much faster than the full reload you would normally have to do, and also more convenient since you don't need to manually trigger a reload in Obsidian.

Improving the releasing process

This still left the release process of Obsidian an unconvenient labor that I wanted to improve for my setup. For that, I modified a publishing CLI tool that I worked on at an earlier point to be compatible with the release requirements of Obsidian: publish-fast. It is a simple npm release wrapper, that supports configuration to automatically run scripts like building or linting beforehands, which can bump the package version, manage changelogs and also create a github release and upload asset files.

publish-fast can be configured through a dedicated file, or a publish object in the package.json file. The necessary setup was installing it through npm i publish-fast --save-dev and adding the following to the package.json file:

{
  "scripts": {
    "release": "publish-fast",
    "postversion": "node version-bump.mjs"
  },
  "publish": {
    "preScripts": "lint,build",
    "skipPublish": true,
    "releaseAssets": "dist/*",
    "noVersionPrefix": true
  }
}

This make the publish process run the lint- and build-script prior to release, skips publishing the package to the NPM registry and uploads the files in the dist folder to the created github release. The remaining defaults for the tool do the rest, i.e. the tool automatically creates a GitHub release and bumps the version by default.

I still needed the custom script that syncs the version from package.json to manifest.json, but moved the execution of that script to a postversion script, so it would be automatically called by NPM after the version bump. For completeness, here is the version bump script that is provided by the Obsidian template repo:

import { readFileSync, writeFileSync } from "fs";

const targetVersion = process.env.npm_package_version;

// read minAppVersion from manifest.json and bump version to target version
let manifest = JSON.parse(readFileSync("manifest.json", "utf8"));
const { minAppVersion } = manifest;
manifest.version = targetVersion;
writeFileSync("manifest.json", JSON.stringify(manifest, null, "\t"));

// update versions.json with target version and minAppVersion from manifest.json
let versions = JSON.parse(readFileSync("versions.json", "utf8"));
versions[targetVersion] = minAppVersion;
writeFileSync("versions.json", JSON.stringify(versions, null, "\t"));

This is pretty much it, running npm run release now automatically bumps the version, builds your assets, and creates a new release on GitHub to which it uploads your assets. If you want to release a new version, you just need to run that script. You could even set it up as a CI pipeline in GitHub actions to run completely automated.

Summary

Obsidian is a pretty cool tool for note-taking and working with markdown notes, and the big community and easy ways to improve the Obsidian experience through custom plugins is really nice. I tried to improve some aspects of plugin development and automate some of the more tedious aspects of it. I found obsidian-plugin-cli, which made development much more convenient, and adopted my own tool publish-fast to implement an automated release process that makes it easier to move fast in developing Obsidian plugins.

TypeScript: The many types of nothing

Lukas Bach — Thu, 30 Mar 2023 12:15:01 +0000

Almost all programming languages have a special value that can be used to denote that a variable is uninitialized, not yet defined or was set in the context of a corner case. Perl calls it undef, Python calls it None, but most languages refer to it as null. If you've worked with JavaScript before, you know its apparent ambiguity of having two different kinds of this value: null and undefined. TypeScript doesn't necessarily help in clearing up confusion here by introducing three more special types related to type corner cases: never, void, and unknown. Let's explore those types to understand how they work and what they can be used for.

null and undefined during runtime

Null and undefined are the only items of the aforementioned that actually are values that can exist during runtime, the others are only types that exist during compile time and are thrown away by the TypeScript compiler.

We get some interesting insights into those two values by looking at how they interact in terms of equality, notably that both are strictly equal to itself, but only equal to itself with a type conversion, which is what the double-equal operator does:

undefined === undefined; // true
null === null; // true
undefined === null; // false
undefined == null; // true

Using the typeof operator also provides some insights:

typeof undefined; // "undefined"
typeof abc; // "undefined"
typeof null; // "object"

Here, we see that the value undefined is internally used by JS in some cases, in this instance variables that are not defined ("abc") will be equivalent to the value undefined, and a typeof check returns the string "undefined" accordingly. Checking the type of null is not as intuitive by returning "object", a quirk that the book "Professional JS for Web Developers" by Wrox provides some more details on:

You may wonder why the typeof operator returns 'object' for a value that is null. This was actually an error in the original JavaScript implementation that was then copied in ECMAScript. Today, it is rationalized that null is considered a placeholder for an object, even though, technically, it is a primitive value.

In practice, likely the most important difference is that the JS runtime commonly uses undefined in many places to denote that something does not exist; null on the other hand is never used automatically. This gives developers a way of distinguishing between something that does not exist due to never being defined, or something that was intentionally set to null because it denotes an "empty" case. However, this is up to the developer since undefined can very much be assigned manually as well.

There is another oddity of undefined, which allows developers to assign a variable with the name "undefined" and use it sucessfully, something that is not possible with "null", however this is something that should not affect realistic code unless one would actively try to break things.

(() => {
  // Need to use scope, since `undefined` already is defined in the global scope. 
  // Don't think about it too hard...
  const undefined = "hello";
  // const null = "hello"; // would through a ReferenceError
  console.log(undefined); // logs "hello"
})();

undefined and null during compile time

We just looked at how undefined and null behave during runtime. Now let us look at how they are interpreted during compile time by the typescript compiler. This will be a rather short investigation, since typescript defines the respective types "undefined" and "null" and has them behave the same way:

const nullValue = null; // type: null
const undefinedValue = undefined; // type: undefined

function maybeUndefined() {
    return Math.random() > .5 ? null : "hello";
}

const nullOrString = maybeUndefined(); // type: null | "hello"

The type "never"

never is, in my opinion, one of the more interesting types in this list. It is mostly used internally by TypeScripts evaluation rules, but can be very powerful in complex type rules. The TypeScript handbook defines it as the following:

The never type is a subtype of, and assignable to, every type; however, no type is a subtype of, or assignable to, never (except never itself). Even any isn't assignable to never.

TypeScript uses it as an inferred return value of a function which does not return. A function does not return if it either always throws an error:

const neverReturns = () => {
    throw Error("goodbye")
}
// inferred type is "const neverReturns: () => never" even without explicit types

This is also the case if it calls a method that never returns. Note that, in the following example, the return value of neverReturns is not directly used or returned, yet the TypeScript compiler knows that some never-returning function is called during the execution of alsoNeverReturns, and thus alsoNeverReturns is inferred to also never return either.

const neverReturns = () => {
    throw Error("goodbye")
}
const alsoNeverReturns = () => {
    neverReturns()
    return "something"
}
// inferred type is "const alsoNeverReturns: () => void"

Note that, if there is a chance of returning something, a function will not have the return value of never, so just because a function does not have that return type, it is not a guarantee that the function cannot throw.

const maybeReturns = () => {
    if (Math.random() > .5) {
        throw Error("goodbye")
    } 
    return "something"
}
// inferred type is "const maybeReturns: () => string"

Functions that run an endless loop also never return, which the TypeScript compiler correctly infers based on static code analysis, but again a function not returning never is not a guarantee that no endless loop happens.

const neverReturns = () => {
    while(true) {}
}
// inferred type is "const neverReturns : () => never"

const maybe = Math.random() > .5 // type boolean
const maybeReturns = () => {
    while(maybe) {}
}
// inferred type is "const maybeReturns : () => void"

Leveraging `never` for complex types

I mentioned before that I find never to be one of the more useful types when it comes to writing complex types. What is beneficial here is that never is pulled through nested type evaluations in a transitive way just as it is in transitive function invocations.

Let's say we have a type MailHostOf<T> which infers the host of a particular email address in a string value, so we want MailHostOf<"john@outlook.com"> to evalaute to "outlook". This is very easy to do with the infer-keyword in TypeScript. However, we also need to handle the case where types are passed that are no valid emails. Let's say we just map the mail host to null in those cases:

type MailHostOf<T> = T extends `${string}@${infer H}.com` ? H : null

type Domain = MailHostOf<"contact@lukasbach.com"> // type is "lukasbach"
type InvalidMail = MailHostOf<"this is no valid email"> // type is null

type AlternativeMail = `noreply@${Domain}.com` // type is "noreply@lukasbach.com"
type InvalidAlternative = `noreply@${InvalidMail}.com` // type is "noreply@null.com"

This generally works fine, but as you can see, the type InvalidAlternative evaluates to "noreply@null.com" which is not what we want in this case. Type evaluation works different if we choose never as the returned type in those cases where a non-valid email is passed:

type MailHostOf<T> = T extends `${string}@${infer H}.com` ? H : never

type Domain = MailHostOf<"contact@lukasbach.com"> // type is "lukasbach"
type InvalidMail = MailHostOf<"this is no valid email"> // type is never

type AlternativeMail = `noreply@${Domain}.com` // type is "noreply@lukasbach.com"
type InvalidAlternative = `noreply@${InvalidMail}.com` // type is never

This is more appropriate to what we expect.

Let's recall what the TypeScript handbook said about never: never is assignable to every type, but no other type is assignable to never. This is important here:

never being assignable to every type means that we can continue to refer to a type that potentially evaluates to never even further down the road of our complex type definitions.
no type being assignable to never means that, once we narrow down the type by providing values for generics and thus producing a certain never-type, the compiler will correctly alert us that a type was produced that cannot be used.

So even though for now our code is valid and no errors were produced, we will encounter errors once the types are used:

const validMail: AlternativeMail = "noreply@lukasbach.com"
// works

const invalidMail: InvalidAlternative = "" as any
// Compiler error: "Type 'any' is not assignable to type 'never'."
// nothing can be assigned here, not even any

The type `void`

Whereas never is a type that is really useful for custom types, void is a type that is rather unlikely to be useful in many instances. It is the inferred return type of a function which returns nothing. This sounds very much like the definition of never, but recall that never is the return type of a function that literally never returns, i.e. an exception is thrown or the function is stuck in a loop, whereas void is the return type of a function which very much returns, it just does not return any value. You probably know the term from other programming languages like Java, where you are required to type a function to void in that case.

const neverFunc = () => {
    // type: () => never
    throw Error()
}
const voidFunc = () => {
    // type: () => void
}

In JavaScript, the return value of a function that doesn't return anything is evaluated as undefined. As such, undefined is the only valid value that can be assigned to the type void (although, with strictNullChecks enabled, null can also be assigned):

const a: void = undefined // works
const b: void = true // type error

However, void is special in one aspect: A function of type () => void can also return other things than undefined, even functions that never return are valid assignments.

type voidFunc = () => void
const returnsUndefined: voidFunc = () => undefined
const returnsTrue: voidFunc = () => true
const returnsString: voidFunc = () => "hello"
const neverReturns: voidFunc = () => {
    throw Error("sorry")
}
// All work, no type errors here

If a function is typed as () => void, it is just that its return type is evaluated to void and thus cannot be used:

type voidFunc = () => void
const returnsString: voidFunc = () => "hello"
const returnValue = returnsString() // evaluates to "void"

This very much looks counter intuitive at first glance - Why have that type in the first place it does not enforce the return type to be undefined? In practice, the useful implication of this is the ability to type a function such that its return type does not matter, and, more importantly, use a function with a specific return type in a situation where its return type is unimportant.

Common use cases are the ability to provide callbacks that do return a value to library functions that want a function without a return value.

const array = []
typeof array.push // (...items: any[]) => number
typeof array.forEach // (callbackfn: (value: any, ...) => void, thisArg?: any) => void
[1, 2, 3].forEach(num => array.push(num))

In the final line, we have an inline forEach loop that calls the array.push function for every item in the [1, 2, 3] array. However, forEach requires callbacks with void as return value, whereas array.push returns a number (the length of the new array). So intuitively we would have a type clash here, but the final line is valid in JavaScript and works expected, so the void type is defined with this workaround in mind so that those cases are still valid.

The type `unknown`

Finally, we have the type unknown. It behaves similar to any as in it being assignable to every other type, except that the compiler forbids you to do anything with something that is unknown before (safely) casting it to something more specific. It serves as a safer alternative to any, which is okay to use in production (which is something not generally the case with any), even though some additional checks are necessary in this case.

const value: unknown = { user: "Lukas" }
// let's assume this comes from a REST call where we
// don't know the value at compile time

console.log(value.user) // error

if (typeof value === "object" && value !== null && "user" in value) {
    // the if-clause made an implicit cast
    console.log(value.user) // safe, no error
}

Explicit casts can also be used with user-defined type guards:

type T = { user: string }
const isT = (val: any): val is T 
    => typeof value === "object" && value !== null && "user" in value

const value: unknown = { user: "Lukas" }

if (isT(value)) {
    console.log(value.user) // safe, no error
}

Note that unknown and any are also the only legal explicit types for exceptions in catch-clauses, and again unknown is the safer way to use here:

// unsafe catch
try {
    maybeThrows()
} catch (e: any) {
    console.log(e.message)
}

// safe catch
try {
    maybeThrows()
} catch(e: unknown) {
    console.log(e.message)
    // error, e could be anything

    if (e instanceof Error) {
        console.log(e.message)
        // valid
    }
}

TypeScript: Properly filtering arrays for non-null values

Lukas Bach — Fri, 13 Jan 2023 20:03:45 +0000

If you have used JavaScript and array operations for a while, there is a good chance you wanted to filter an array for non-null values. And if you are using TypeScript, there is a chance you ended up with something along the lines of that:

const array = ["Michael", "Dwight", undefined, "Pam", "Jim", undefined]
typeof array // (string | undefined)[]

console.log(array.map(value => value.includes("Mich")))
// error, value could be undefined
// I should filter for only defined values...

const filteredAttempt = array.filter(value => !!value)
typeof filteredAttempt // (string | undefined)[]
// Argh dang, TypeScript doesn't infer the filter logic, that didn't do anything...

// screw it
const filteredAttempt2 = array.filter(value => !!value) as any
typeof filteredAttempt2 // any, good enough..
console.log(filteredAttempt2.map(value => value.includes("Mich")))

You will quickly find that TypeScript doesn't actually check what the filter function does, so the returned array will be the same, and you will have to straighten the type manually to make it work, often relying on any which is always a bad idea.

However, this is really easy to do properly with type guards. A type guard function in TypeScript that takes a parameter x and returns a type of the form x is T with T being any type. Now, if code is called in a scope in which this type guard function was called and returned true, the type of x will be automatically narrowed down to T within that scope:

const isString = (v: any): v is string =>
    typeof v === "string"

const stringOrNumber = Math.random() > .5 ? "hello" : 42

if (isString(stringOrNumber)) {
    console.log(stringOrNumber.endsWith("lo")) // works
} else {
    console.log(stringOrNumber.toPrecision()) // works
}

Note that this technically is a type conversion, and you very much can do non sensical stuff with this:

const surelyAString = (v: any): v is string => true

const stringOrNumber = Math.random() > .9999 ? "hello" : 42

if (surelyAString(stringOrNumber)) {
    console.log(stringOrNumber.endsWith("lo")) 
    // works, but probably not during runtime
}

However, it allows you to encapsulate casting logic, which makes the code easier to read and understand which conversions are being made and how they work, thus reducing the likelihood of errors in that logic.

Returning to the original question: How can we leverage type guards to properly filter an array for non-undefined values?

const array = ["Michael", "Dwight", undefined, "Pam", "Jim", undefined]
typeof array // (string | undefined)[]

const isNotUndefined = <T>(value: T | undefined): value is T => 
    value !== undefined

const filteredArray = array.filter(isNotUndefined)
typeof filteredArray // string[]

console.log(filteredArray.map(value => value.includes("Mich"))) // works!

We define a type guard function isNotUndefined with generic type T, which takes a parameter of type T | undefined. If we now supply a value of type string | undefined, T is inferred to be string, and the type guard will narrow the type of the parameter down to string if it returns true. This can also be done for filtering out other types such as null.

const isNotNullish = <T>(value: T | null | undefined): value is T => 
    value !== undefined && value !== null

DEV Community: Lukas Bach

Headless Tree is now available in Beta!

Headless-Tree, and the Future of React-Complex-Tree

Headless-Tree, and the Future of React-Complex-Tree

Some history on react-complex-tree

Why a new library?

What does that mean for react-complex-tree?

Other new features with Headless Tree

When will Headless Tree become available as stable release?

A more streamlined development workflow for Obsidian plugins

The usual plugin development process

Improving the development process

Improving the releasing process

Summary

TypeScript: The many types of nothing

null and undefined during runtime

undefined and null during compile time

The type "never"

Leveraging never for complex types

The type void

The type unknown

TypeScript: Properly filtering arrays for non-null values

Leveraging `never` for complex types

The type `void`

The type `unknown`