Minoklu

Typescript's noImplicitOverride

Mon, 03 Jul 2023 23:50:26 +0200

TSConfig has a ton of options one can choose to utilize. So many that i always refrained from even starting to look into to them.

Recently i stumbled over noImplicitOverride and was wondering why anyone would want to turn it off. There is basically no benefit in doing so. The only thing one has to do when it is set to true is to add the keyword override in front of any class member that is part of the class one is extending.

The help it can offer is tremendous though. Imagine the following example (which will never happen of course).

Let’s take Lit as an example. It exposes a class LitELement which you can extend from to implement WebComponents and have a more convenient life-cycle management for writing them. LitElement exposes a render method which is supposed to be implemented by each class extending it. It’s purpose is to return something renderable.

customElement("my-component")
export class MyComponent extends LitElement {
	override render() {
		return html`<h1>Hello, World!</h1>`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		"my-component": MyComponent;
	}

If one has noImplicitOverride configured to be true, the above code causes the TypeScript compiler to complain if the override keyword is missing:

customElement("my-component");
export class MyComponent extends LitElement {
	/* This member must have an 'override' modifier because it overrides a
	 * member in the base class 'LitElement'. ts(4114)
	 */
	render() {
		return html`
			<h1>Hello, World!</h1>
		`;
	}
}

Likewise, let’s assume the maintainers of Lit decided to rename the render function to renderFn for some reason. Unlikely but not impossible.

Assuming we added override in the code above, now the TypesScript compiler would complain that we override a method that is not present in LitElement. What a win, we know we’re doing something wrong because something underlying has changed:

customElement("my-component");
export class MyComponent extends LitElement {
	/* This member cannot have an 'override' modifier because it is not declared
	 * in the base class 'LitElement'. Did you mean 'renderFn'? ts(4117)
	 */
	override render() {
		return html`
			<h1>Hello, World!</h1>
		`;
	}
}

I suggest always setting noImplicitOverride to true.

Upgrade esbuild V0.15 to V0.18

Mon, 03 Jul 2023 22:40:27 +0200

Esbuild is moving quickly. When i installed it for my build process last year i took a chance with it. Having quick builds was tempting. I never updated it until a few days ago.

This led me to update from v0.15 to v0.18, That’s 3 minor versions with potential breaking changes. In fact, each single minor release deliberately introduced breaking changes:

Luckily my setup was not too complex and the switch just took an hour of reading the API docs and trying out new features. :)

My setup until that point

/* eslint-disable no-console */
import esbuild from "esbuild";

esbuild
	.build({
		bundle: true,
		entryPoints: ["src/index.ts"],
		minify: true,
		outfile: "dist/bundle.js",
		sourcemap: true,
		watch: {
			onRebuild(error) {
				if (error) {
					console.log("Build failed:", error);
				} else {
					console.log("Build succeeded!\nWaiting for changes...");
				}
			},
		},
	})
	.then(() => {
		console.log("esbuild is in watch mode!");
	});

The configuration itself, i guess, is self-explanatory, we bundle, minify and sourcemap the code.

The only special thing about this setup is the watch. This makes the esbuild process watch the source code directory for file changes and rebuild when they occur. One had to add quite a bit of code to have such log output.

I served the application via the ubiquitous http-server package. Nothing special.

The new setup

import esbuild from "esbuild";
import "dotenv/config";
import fs from "node:fs";

const esbuildContext = await esbuild.context({
	bundle: true,
	entryPoints: ["src/index.ts"],
	define: {
		"process.env.ENV_DEV": process.env.ENV_DEV,
	},
	logLevel: "info",
	metafile: true,
	minify: true,
	outfile: "dist/bundle.js",
	sourcemap: true,
	treeShaking: true,
});

await esbuildContext.watch();

await esbuildContext.serve({
	certfile: process.env.CERTFILE,
	keyfile: process.env.KEYFILE,
	onRequest: ({ method, status, path }) =>
		console.log(`${method} ${status} ${path}`),
	port: 8080,
	servedir: "./",
});

There’s quite a few changes. By far the most convenient one is the missing setup code for the watch. In order to watch, one sets up a build context, which has the watch() method. It does everything i setup myself before but much nicer and more coherent.

One great addition is the serve() function the build context exposes. It replaced running http-server completely and allows for secure HTTP as well. So it’s a integrated replacement and fulfills all my needs. Logging the requests put against the server has to be added via the onRequest event handler.

The define property on line 8 is used to enable reloading the application when esbuild rebuilds the application via its live reload feature:

if (process.env.ENV_DEV) {
	new EventSource("/esbuild").addEventListener("change", () => {
		location.reload();
	});
}

If the “environment variable” ENV_DEV is present and true the application will listen to the event, triggering the page to reload. The esbuild change event will be fired upon each build that is performed.

Note that the aforementioned “environment variable” is not actually an environment variable. It’s a placeholder that will be fully replaced by whatever value the process.env.ENV_DEV contains. In my case this is true when the build watch script is run, so the if-statement will be turned into if(true) { ... }. Refer to the define documentation for more information.

Metafile

One new feature that’s very interesting is the built-in Metafile support. This files enables one to analyze the bundled files. The Analyze functionality enables a human readable summary of the build and it’s composition.

If you like visuals more, esbuild has you covered with its Bundle Size Analyzer (Go try it out, it comes with an example bundle).

const build = await esbuild.build({
	bundle: true,
	entryPoints: ["src/index.ts"],
	define: {
		"process.env.ENV_DEV": process.env.ENV_DEV,
	},
	logLevel: "info",
	metafile: true,
	minify: true,
	outfile: "dist/bundle.js",
	sourcemap: true,
	treeShaking: true,
});

fs.writeFileSync("meta.json", JSON.stringify(build.metafile));
console.log(await esbuild.analyzeMetafile(build.metafile));

Migrate Focalboard Boards to Kanboard

Sun, 18 Jun 2023 17:23:27 +0200

TL/DR

Here is the Github repo for the transform script: zemzelett/focalboard-to-kanboard

Preface: Why?

I started using Focalboard last year around October when i started my time-tracker project.

Here is, in short, what bothered me with it:

Over time the UI got slower the more tasks there where on the board. And we are speaking of around 50 tasks altogether…
The UI is not mobile first nor is it bearable to use it there (not a KO criteria but nonetheless something i tend to do every now and then)
The UI is super slow when transitioning tasks from column to column
The UI is super slow when changing the order of tasks
Focalboard has an overload of features which all seem somewhat incomplete
There is a bug displaying a white page after not visiting a board for some time (which can be solved with a hard-reload, but that’s not what should be necessary)

All of these fed a desire to use something else.

When i first looked for this kind of software i found Kanboard as well and chose Focalboard over it for its nicer and seemingly more mature design.

I can’t say how well Kanboard will perform in the future but it can easily handle a fair amount of tasks on the board and the UI is much more fluid on Desktop and on Mobile! It doesn’t look as nice and fancy but that’s something one can customize if desired.

Preparation

I’ll save you some of the hiccups i’ve had via this short summary: At first i compared the export format for both softwares. At some point i had to realize that the Kanboard import format differs from its export format. This is something to consider when using Kanboard initially too!

Focalboard export files analysis

Focalboard has two types of export formats:

archive Essentially a zip file containing some meta data and a JSONL file containing the complete board config and its content
CSV A simple CSV containing all tasks of the board with all columns currently chosen in the view where the export is triggered from.
It will never export the task description though!

The CSV seems fine if only the task titles are of interest otherwise it will fall short of the archive format.

Analysis of the archive format

The archive, in its essence, is a JSONL. JSONL is, simply put, a file with multiple JSON objects separated by newlines.

This is the first time i heard of this format; but i also don’t quite see the purpose in it to be honest. Why not just use a standard JSON-compliant array of objects to achieve basically the same but have it easily parseable by a JSON parser directly?

But i digress, here are the important observations in regards of this file:

Of major interest are objects with the type: "card" or type: "text" if their parentId’s type is "card"
columns and tags are referenced via id’s
- definitions for these are in the very first JSON object (with type: "board") inside of data.cardProperties

Kanboards import format

As mentioned before, the import format differs from the export format. Kanboard lets you download a template for it in its import dialog. It looks as follows:

Reference,Title,Description,"Assignee Username","Creator Username","Color Name","Column Name","Category Name","Swimlane Name",Complexity,"Time Estimated","Time Spent","Start Date","Due Date",Priority,Status,Tags,"External Link"

An import has to have all of these columns present in that specific order or the import won’t work correctly!

Lucky me, it contains the Description column i longed for.

The migration

For the migration i wrote a Python script that takes a board’s archive and transforms its contents into an Kanboard import CSV.

So the migration steps for each board i had where as follows:

Export Focalboard board in its archive format
Run that file through the transform script
Create a Kanboard board with the same columns (Important!)
Import the CSV into a newly created Kanboard board

The script

The script is also available on Github: zemzelett/focalboard-to-kanboard

Parsing arguments

import argparse
import csv
import json
import zipfile

argumentParser = argparse.ArgumentParser(
    prog='focal-to-kan',
    description='Converts Focalboard archive export to Kanboard import CSV'
)
argumentParser.add_argument(
    'inFile',
    help='Focalboard archive to convert',
    nargs=1,
)
argumentParser.add_argument(
    '-o',
    help='output file name',
    nargs=1
)

args = argumentParser.parse_args()
if not args.inFile:
    print('inFile has to be supplied!')
    exit(1)

I’ll brush over these lines of code. These are just for convenience when running the script. It should mostly speak for itself. If not,read Python’s argparse documentation.

Extracting the boards JSONL

root = zipfile.Path(args.inFile[0])

boardDir = None
for part in root.iterdir():
    if part.is_dir():
        boardDir = part
        break
boardDirPath = root.joinpath(boardDir.name)

boardFile = None
for part in boardDirPath.iterdir():
    if part.is_file():
        boardFile = part
        break

focalJsonl = boardFile.open()

This section of code looks for the folder inside the zip archive, jumps into it and grabs hold of the reference to the first file in it. This is our JSONL file containing the board.

For reference look into Python’s zipfile documentation.

Processing the Focalboard’s board content

tags = {}
tagsId = ''
status = {}
statusId = ''
tasks = {}
descriptions = []

while line := focalJsonl.readline():
    o = json.loads(line)
    data = o['data']
    if o['type'] == 'board':
        for o in data['cardProperties']:
            if o['name'] == 'Status':
                statusId = o['id']
                status = {v['id']: v['value'] for v in o['options']}
            elif o['name'] == 'Tags':
                tagsId = o['id']
                tags = {v['id']: v['value'] for v in o['options']}
    elif data['type'] == 'card':
        tasks[data['id']] = data
    elif data['type'] == 'text':
        descriptions.append(data)

Each line (line 48) in the JSONL is a valid JSON object we have to parse (line 49).

We are interested in objects of type board, card and text.

The board’s metadata is contained in the very first lines object with the type board (line 51). In it we look for the cardProperties and extract Status (the board columns) (line 53) and Tags (line 56).

Entries of type card are the actual tasks (lines 59-60).

Entries of type text are potentially descriptions for tasks (lines 61-62). We’ll store all of them for now.

json.loads is able to deserialize a JSON string. Refer to Python’s json documentation for more insight.

Assembling the Kanboard import CSV

rows = [[
    'Reference',
    'Title',
    'Description',
    'Assignee Username',
    'Creator Username',
    'Color Name',
    'Column Name',
    'Category Name',
    'Swimlane Name',
    'Complexity',
    'Time Estimated',
    'Time Spent',
    'Start Date',
    'Due Date',
    'Priority',
    'Status',
    'Tags',
    'External Link'
]]

for d in descriptions:
    if d['parentId'] in tasks:
        tasks[d['parentId']]['description'] = d['title']

for task in tasks.values():
    props = task['fields']['properties']
    rows.append(
        [
            'focalboard import',
            task['title'],
            task.get('description', ''),
            'your_user_here',
            'your_user_here',
            'Grey',
            status[props[statusId]],
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            None,
            ','.join(map(lambda v: tags.get(v, ''), props.get(tagsId, [])))
        ]
    )

outFilename = args.o[0] if args.o else f'{args.inFile[0]}.csv'
csvFile = open(outFilename, 'w', newline='')
csv.writer(csvFile).writerows(rows)

Before we can build all rows of the import CSV we have to connect the descriptions to their respective tasks. This happens in lines 84-86. We simply iterate over all “descriptions”. If the parentId is one of our tasks, we assign its title value to the task’s (now new) description property.

The loop at line 88 fills the rows with each task’s relevant properties.

Only line 108 might be of special interest here. It concatenates all of a task’s tags together separated by a comma.

For lines 112-114 refer to Python’s csv documentation.

Why I Use Prettier

Wed, 26 Apr 2023 10:25:40 +0900

Recently i thought about dropping Prettier from my dev-dependencies in order to reduce a tool in my chain. I thought of using ESLint instead.

Before just jumping into doing so i did some research and finally decided to leave things as they are.

Motivation

I hate to have to many tools floating around in my projects. I mean in general. So i’m always looking into minimizing dependencies as much as i can without loosing anything valuable.

Seeing that ESLint is practically capable of reformatting the code it analyzes; and it having an explicit ruleset geared towards code style i started thinking of why i use Prettier at all.

Swapping out Prettier?

After the initial thought i started doing some research as i tend to mistrust my desires when it comes to things like this.

I looked into the ESLint ruleset realizing it actually seems to have all the rules one might need to replicate Prettier’s ruleset. That ruleset has a dedicated section in the Rules Reference.

Then i started laying out a strategy in my head of how to approach phasing out Prettier in my time tracker project. Then it hit me:

Just trying to replicate Prettier’s output is hard. Not that i’d want to replicate it 100%, but finding all edge cases and configuring them properly even with a solid style guide is hard and takes a lot of time.
On top of that this would only cover TypeScript/JavaScript and nothing else. This is highly undesirable as i don’t want to start that process with any other language i use or might use in the future each time too…

This also made me understand the common notion around separating concerns in the form of having linters and formatters. Technically linters (taking the word lint literally) could also format and it’s fine to use them for that purpose; linters are nowadays generally understood and primarily designed to find potential bugs or bad practices in your code. Having that in mind it’s odd to think, a linter also format the code as well.

So, no, i do not swap out Prettier, i keep it and i learned to appreciate its existence even more than i did before!

Bare in mind, this is a convenience decision, favoring simplifying the overhead of properly configuring the formatting and properly separating the concerns.

An analogy (and etymology)

Think of knitting a sweater. The formatting would basically be the pattern you knit your sweater in. Is it just one color (think minified code which is just one big blob if characters) or does it have a nice checkered pattern of blue and yellow (think prettified code)?

Now, wearing your sweater after having finished knitting it will result in lint on it to appear over time. If you care about your sweater and its appearance you might start removing those with a lint brush.

The terms linter and linting are derived from that original term and the associated process of removing it.

Interesting side-note

While researching i found out Stylelint deprecated all format related rules with version 15. They themselves state, that this is in light of tools like Prettier existing and that is a consequent move.

The reasons they give are a good read to understand the common sense around formatters and linter.

Further thoughts on formatters vs. linters

There is one specific set of rules i fancy a lot: The rules that are responsible for sorting definitions like variables, object properties, class properties, css properties, import and export etc. Preferably i like to simply have them sorted by alphabet as this is most deterministic and simple to reason about.

Within what reasoning do these fall? There’s no severe potential risk regarding bugs when things are not sorted; rather it might introduce bugs when dependencies are potentially depending on one another. It’s not really a formatting related issue either, is it? This confuses me a bit, honestly.

LitElement spread directive

Wed, 02 Nov 2022 21:25:05 +0100

Disclaimer: Do not use my code without considering its quite obvious short-comings! If you’d like to use a more robust implementation of a spread directive, read the last paragraph.

Context

When i was working on my time-tracker app i was confronted with repeatedly writing out attributes for a custom web component i have written. I was contemplating about how to approach this daunting repetition of code.

I couldn’t come up with an opinion quickly but i a simple intermediate workaround inspired by React sparked up in my mind.

In React one is able to just spread out attributes, or more generally props, to components by utilizing the ES6 spread operator:

function App() {
    return (
        <MyCustomComponent ...someProps />
    )
}

I wondered if something like this is possible with LitElement too. I remembered that directives where potentially capable of doing this. So i started writing my very first directive in Lit. And quite a useful one as it turned out.

Directives

Lit has, as it feels, a very selected set of built-in directives. A lot of these will solve one or many problems one might run into while writing WebComponents with Lit.

The Lit documentation has a whole page designated towards custom directives. It’s advisable to read that closely.

Types of directives

There’s only two types of directives:

Simple functions
Class-based directives

Simple functions are, as it feels, very simple and limited as they have to return a renderable string (or more broadly speaking: anything that turns out to be renderable).

Class-based directives in contrast are very flexible as to how one is able to manipulate the output of the directive, which still has to be a string/renderable nonetheless. As one can hook into the lifecycle of a components with them, one can virtually do anything with them.

Writing the spread directive

Looking at the API Documentation for custom directives it’s easy to figure out, that implementing a class-based directive should not be too big of a feat.

There’s only two method one can implement (apart from the constructor):

render
render feels a bit like the simple function directive, it’s supposed to return something that is renderable One important fact about the render method is, that it serves as the signature of the directive function (even if it is not being utilized otherwise)
update
update enables you to imperatively access the DOM - this is what we need for our spread directive as we will be directly accessing properties of the component we want to spread properties on.

The following is the full code i wrote for my spread directive:

import { Directive, directive } from "lit/directive.js";
import { ElementPart, noChange, nothing } from "lit";

class SpreadDirective extends Directive {
	render(obj: Record<string, unknown> | object) {
		return nothing;
	}

	update(part: ElementPart, [obj]: Record<string, unknown>[]) {
		for (const k in obj) {
			part.element[k] = obj[k];
		}
		return noChange;
	}
}

export const spread = directive(SpreadDirective);

Ok, let’s make this a bit more digestible. The core to create your custom directive is the following:

import { Directive, directive } from "lit/directive.js";

class SpreadDirective extends Directive {
	render() {
		return "something";
	}
}

export const spread = directive(SpreadDirective);

That’s the bare minimum. When creating a class-based custom directive, the last line becomes obligatory to add. Calling the directive function with our custom directive class creates the actual custom directive that can then be exported.

Adding the call signature for our directive

Remember that the render method is used to derive the signature for our directive. This forced me to add the render function just for that purpose.

In order to signal Lit that render actually returns nothing to render, we add the nothing sentinel value.

import { Directive, directive } from "lit/directive.js";
import { nothing } from "lit";

class SpreadDirective extends Directive {
	render(obj: Record<string, unknown> | object) {
		return nothing;
	}
}

export const spread = directive(SpreadDirective);

`update` is where the magic happens

The update method is the key to the spread directive. It takes two parameters:

A Part object exposing an API specific to the part
An array containing all arguments passed to the render method.

The Part type is crucial for our implementation. We want to use the ElementPart which is the one that can be used within element tags.

We extract the obj we are expecting out of the render argument’s array. That obj will be iterated over and all properties on it will override the same property on the target element.

The return value is the noChange sentinel value in order to indicate that we do not want to re-render anything. If a re-render of the component the directive is acting on is necessary, it will derive this on its own by the changes on its properties.

import { Directive, directive } from "lit/directive.js";
import { ElementPart, noChange, nothing } from "lit";

class SpreadDirective extends Directive {
	render(obj: Record<string, unknown> | object) {
		return nothing;
	}

	update(part: ElementPart, [obj]: Record<string, unknown>[]) {
		for (const k in obj) {
			part.element[k] = obj[k];
		}
		return noChange;
	}
}

export const spread = directive(SpreadDirective);

Look further

After implementing the spread directive, i searched the web for an existing directive. Turns out, Google wrote one themselves but did not include with the built-in ones.

The spread directive is part of the lit-helpers module which doesn’t consist of too many helpers at the time of writing this.

The spread directive in that module is much more feature rich than the simple one i wrote. It is capable of attaching properties, attributes, boolean attributes and event listeners by spreading them. The sigils are necessary for those though.

Mon, 01 Jan 0001 00:00:00 +0000

Hi, i am me.