Mavnn's blog · bonfire.mavnn.eu

Mavnn's blog

Articles from the blog (https://blog.mavnn.eu/)

blog.mavnn.eu

48 posts 7 followers 1 following Joined Mar 2026

Mavnn's blog

@blog · last week

⁂ Article

Presenting Games with a Story

Read this post in its full formatted glory at https://blog.mavnn.eu/2026/05/06/presenting_games_with_a_story.html

As a special bonus extra for following the blog, here's a sneak peak of the draft course description for the under 18s online course I'm planning to run next half term (i.e. starting in a few weeks time). If it sounds interesting or you've got any suggestions, let me know.

Separate from the ability to create art (visual or musical) is the ability to use it. This is a course on using the digital tools available freely to create assets (the artwork and sounds) for games and digital presentations. Not how to draw, but how to turn your picture into a game character. Not how to play an instrument, but how to use a crisp packet to make the sound of sneaking footsteps in the woods.

Using some example visual novels as project starters (like the ones you can build in "Coding Games with a Story"), we'll spend some time looking at the process of creating digital art assets, starting from prototyping, deliberately 'wrong' placeholders and story boarding to work out what it is that we even need.

Then we'll move onto the tips and tricks of the trade for using digital art tools. We'll look at how to take existing artwork created on paper and turn it into assets that we can use easily and that look good without spending forever and a year doing so. We'll use layers to create many variants of the same image without having to redraw it every time, and to let you perfect parts of the artwork independently, and then we'll expand their use to have a look at basic animation techniques. And we'll look at how to use art styles to your advantage, such as using pixel art to create a final visual design that looks good but isn't quite so labour intensive.

On the audio side we'll learn how to balance and adjust the volume of our recordings so that they match well together, have a look at Foley work (the creation of sound effects using everyday objects), and play with some effects to do things like voice acting multiple parts with the same person.

We might not end up results like a AAA computer game with a budget of millions, but we will end up with a set of skills to communicate your ideas more quickly and more accurately - and a lot of new ways to cheat on making things look and sound better quickly!

To take part in this course you'll need access to a device that has both Krita (for visual work) and Audacity (for working with sound) installed as we will be using them during the sessions. Both pieces of software are available for free, and the course introduction will contain links to download them safely. Between sessions you'll need access to a way to take pictures and record audio - any smartphone will do. If you have a graphics tablet for drawing it will be a nice bonus extra, but it will not be required.

Finally, to take part in the course, you will need to be know how to download, save, and find the example starter files that we will be using (links will be shared for each session). To fit all of the good stuff into the short five week format, we will be assuming a foundational knowledge of saving and loading files on the device you are using.

Mavnn's blog

@blog · 2 weeks ago

⁂ Article

Crunchier pixels in VisualInk

Read this post in its full formatted glory at https://blog.mavnn.eu/2026/05/01/crunchier_pixels_in_visual_ink.html

Pixel art has a certain charm all of its own, and visual novels in particular often borrow from the older games of yesteryear for their artistic inspiration.

But unfortunately, that means that if you're using a web based visual novel engine like VisualInk your assets can end up looking blurred and smudgy depending on the screen size where they are viewed.

VisualInk now has the pixel_style variable for choosing whether images that need to be resized are scaled using "Smooth" style (the default, good for photos and scanned hand drawn artwork), and "Pixelated" style for low resolution pixel art to be scaled up keeping nice sharp edges between the pixels.

As an example:

Figure 1: Smooth style with photos

Versus (excuse the placeholder images):

Figure 2: Pixelated style with pixel art

Mavnn's blog

@blog · last month

Now with hashtags

Read this post in its full formatted glory at https://blog.mavnn.eu/2026/04/11/now_with_hashtags.html

To follow up on yesterday's announcement of fediverse, the 'federate your RSS feed' project, today I've pushed support for mapping RSS categories to ActivityPub hashtags. This does add a new required config field, as each ActivityPub server can map hashtags to different places.

That's... about it, really. This is mostly a blog post so that there is a blog post with hashtags to point at.

Now with hashtags

Mavnn Forgejo: Code repositories at mavnn.eu

fediverss

Drive an activitypub Actor via an RSS feed

Fediverss

Mavnn's blog boosted

Mavnn's blog

@blog · last month

⁂ Article

Fediverss

Read this post in its full formatted glory at https://blog.mavnn.eu/2026/04/10/fediverss_release.html

You might have noticed that this blog has suddenly acquired a comments section at the end of the articles. I've tried some work arounds in the past - in a previous version of the blog using an external service, or manually linking to fediverse posts made about the blog post - it never sat quite right.

For this version of the blog, I didn't want to force people to create a log in for "my blog" or run a bunch of dedicated comment receiving infrastructure, but I also didn't the comments to be controlled by a third party service with all the archival and privacy concerns that implied.

So I've now built fediverss. This is a program designed to sit on the same server as a static blog automate the process of keep that blog on "the fediverse" via its rss feed. It is very much pre-release quality at the moment, but I'd very much like to polish it up so that it can be deployed easily by non-coders and in environments where running it on the same server as the blog isn't practical. That shouldn't be impossible, especially given that all the dependencies are already managed in Nix, so much this space for future developments.

And, you know, leave a comment via the fediverse if this seems interesting!

Mavnn's blog

@blog · last month

⁂ Article

Fediverss

Read this post in its full formatted glory at https://blog.mavnn.eu/2026/04/10/fediverss_release.html

And, you know, leave a comment via the fediverse if this seems interesting!

Mavnn's blog

@blog · last month

⁂ Article

Coding more games with more stories

Read this post in its full formatted glory at https://blog.mavnn.eu/2026/04/08/coding_games_with_a_story.html

It's that time again! If you know somebody who's 12-18 who likes the idea of writing interactive fiction in the form of visual novels, you can sign up for my five week starter course by browsing over to ThinkersMeetup.

I'm also thinking of expanding the course out for a further five weeks with more advanced techniques and time to actually build the stories, rather than just looking at how to build them so I'll post an update in a few weeks about that as well.

If you have no idea at all what I'm talking about, wonder over to VisualInk and try the example story linked on the home page.

Aaaaaand... on a final note, I'm also looking at two other options. One is an introduction to Godot as an intensive course over the summer to teach real time game development, and the other is interactive fiction courses aimed at adults. If you have any interest in either, let me know. I'm especially if you're an adult interested in expanding creative writing into writing interactive fiction to hear what format works best for you: once a week at lunch time for an hour, weekend courses, several afternoons during a single week as an intensive block with writing time in between? Adult schedules are always interesting to manage.

Michael Newton

@mavnn · last month

Updated as a test

Mavnn's blog

@blog · last month

@mavnn testing more

Mavnn's blog

@blog · last month

Read this post in its full formatted glory at https://blog.mavnn.eu/2021/09/22/NewBeginnings.html

This is just a short test; I'm beginning to publish my blog via Emacs Org mode rather than Jekyll because... well, because I don't enjoy updating Ruby, and blogging is something that I (partially) do for my own relaxation and enjoyment.

So... welcome to the new blog. To those few of you subscribed to my blog as a feed, apologies for the largely content free post.

If this works I'll be updating as I go along with actual posts, as well as the obligatory posts on how the blog works and why I've set it up as I'm planning to.

Remind me why every developer feels the need to do that, again?

Mavnn's blog

@blog · last month

Read this post in its full formatted glory at https://blog.mavnn.eu/2021/10/04/LiterateCSS.html

One of the benefits of writing my blog in Org-Mode in Emacs, is that my blog posts are a functional literate programming environment. Which is pretty handy for keeping track of things like "how does my CSS work", for example.

Well, in general Org-Mode injects a basic set of CSS into web pages as it exports them, but I'm planning to amend that slightly as I go forward. Meaning this blog post will be a bit of a living document, evolving over time. Hi, future me! Hope you like it.

We're going to cheat a bit and use a "classless CSS framework" (water.css is going to be my first attempt). This means we can remove a lot of default styling, and focus only on the more specific classes org adds. The entire unminified water.css file is included at the end of this file so that it gets bundled together with my custom css. I may build a workflow to minimize the results in the future, but honestly it seems a false optimization right now.

Load fonts early to avoid glitches and spacing issues:

@font-face {
  font-family: charter;
  font-style: normal;
  font-weight: normal;
  font-stretch: normal;
  src: url('/fonts/charter_regular.woff2') format('woff2');
}

@font-face {
  font-family: charter;
  font-style: italic;
  font-weight: normal;
  font-stretch: normal;
  src: url('/fonts/charter_italic.woff2') format('woff2');
}

@font-face {
  font-family: charter;
  font-style: normal;
  font-weight: bold;
  font-stretch: normal;
  src: url('/fonts/charter_bold.woff2') format('woff2');
}

@font-face {
  font-family: charter;
  font-style: italic;
  font-weight: bold;
  font-stretch: normal;
  src: url('/fonts/charter_bold_italic.woff2') format('woff2');
}

@font-face {
  font-family: source_code_pro;
  font-style: regular;
  font-weight: normal;
  src: url('/fonts/SourceCodePro-Regular.otf.woff2') format('woff2');
}

Colour variables, so we don't need to keep on repeating them and we have some consistency.

/**
 * These colors are taken from `water.css`, rearranged to
 * my liking and expanded a bit for code highlighting.
 *
 * Automatic version:
 * Uses light theme by default but switches to dark theme
 * if a system-wide theme preference is set on the user's device.
 */

:root {
  /* re-usable names for quickly experimenting */
  --dominant-base: #EC0000;
  --complement-base: #00BD00;
  --secondary-base: #EC6B00;
  --secondary-complement-base: #008E8E;

  --dominant: color-mix(in oklab, var(--dominant-base), var(--mixin-foreground) 10%);
  --complement: color-mix(in oklab, var(--complement-base), var(--mixin-foreground) 25%);
  --secondary: color-mix(in oklab, var(--secondary-base), var(--mixin-foreground) 25%);
  --secondary-complement: color-mix(in oklab, var(--secondary-complement-base), var(--mixin-foreground) 10%);

  --mixin-foreground: black;
  --mixin-background: white;

  --nearly-foreground: 98%;
  --mostly-foreground: 95%;
  --half-foreground: 50%;
  --slightly-foreground: 25%;
  --nearly-background: 99%;
  --mostly-background: 94%;
  --half-background: 50%;
  --slightly-background: 25%;

  --text-main: color-mix(in oklab, var(--dominant), var(--mixin-foreground) var(--nearly-foreground));
  --text-bright: color-mix(in oklab, var(--dominant), var(--mixin-foreground) var(--mostly-foreground));
  --text-muted: color-mix(in oklab, var(--dominant), var(--mixin-background) var(--slightly-background));

  --background-body: color-mix(in oklab, var(--complement-base), var(--mixin-background) var(--nearly-background));
  --background: color-mix(in oklab, var(--complement-base), var(--mixin-background) var(--mostly-background));
  --background-alt: color-mix(in oklab, var(--complement-base), var(--mixin-background) var(--half-background));

  --code-keyword: var(--dominant);
  --code-value: var(--complement);
  --code-type: var(--secondary);
  --code-comment: var(--secondary-complement);
  --code-punctuation: var(--text-main);
  --code-background: var(--background);
  --code: var(--text-main);

  --selection: var(--complement);
  --links: var(--secondary);
  --focus: var(--secondary);
  --border: var(--secondary-complement);
  --animation-duration: 0.1s;
  --button-base: var(--background-alt);
  --button-hover: color-mix(in oklab,var(--background-alt), var(--mixin-foreground) var(--slightly-foreground));
  --form-placeholder: var(--text-muted);
  --form-text: var(--text-main);
  --variable: var(--code);
  --highlight: var(--complement);
  --select-arrow: url("data:image/svg+xml;charset=utf-8,%3C?xml version='1.0' encoding='utf-8'?%3E %3Csvg version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' height='62.5' width='116.9' fill='%23161f27'%3E %3Cpath d='M115.3,1.6 C113.7,0 111.1,0 109.5,1.6 L58.5,52.7 L7.4,1.6 C5.8,0 3.2,0 1.6,1.6 C0,3.2 0,5.8 1.6,7.4 L55.5,61.3 C56.3,62.1 57.3,62.5 58.4,62.5 C59.4,62.5 60.5,62.1 61.3,61.3 L115.2,7.4 C116.9,5.8 116.9,3.2 115.3,1.6Z'/%3E %3C/svg%3E");
}

@media (prefers-color-scheme: dark) {
:root {
  --mixin-foreground: white;
  --mixin-background: #121212;

  --dominant: color-mix(in oklab, var(--dominant-base), var(--mixin-foreground));
  --complement: color-mix(in oklab, var(--complement-base), var(--mixin-foreground));
  --secondary: color-mix(in oklab, var(--secondary-base), var(--mixin-foreground));
  --secondary-complement: color-mix(in oklab, var(--secondary-complement-base), var(--mixin-foreground));

  --nearly-foreground: 98%;
  --mostly-foreground: 95%;
  --half-foreground: 50%;
  --slightly-foreground: 25%;
  --nearly-background: 90%;
  --mostly-background: 75%;
  --half-background: 20%;
  --slightly-background: 10%;

}
}

Responsive text and content sizes from the absolutely amazing Practical Typography from Matthew Butterick.

html {
  font-size: 2.4vw;
  height: 100%;
}
/** Make sure that while font size scales smoothly, it never gets
 * too big or small.
 */
@media all and (min-width:1000px) { html { font-size: 24px; } }
@media all and (max-width:670px) { html{ font-size: 18px; } }

body {
  margin: 20px auto;
  padding: 0 0.5rem;
  max-width: 1000px;
  min-height: 100%;
  position: relative; z-index: -10000; -webkit-font-smoothing: subpixel-antialiased; /* corrects safari rendering */
  font-family: charter, serif;
  font-weight: normal;
  line-height: 1.4;
  word-wrap: break-word;
  color: var(--text-main);
  background: var(--background-body);
  text-rendering: optimizeLegibility;
}

My nice little "go home" header needs some CSS to get it looking as cute as I'd want it.

img.home-logo {
  width: 50px;
  height: 50px;
  padding: 3px;
  background: white;
  border-radius: 10px;
}

#org-div-home-and-up {
  font-size: 70%;
  display: flex;
  flex-direction: row;
  align-items: center;
  justify-content: flex-end;
  gap: 10px;
}

Adding some horizontal rules helps keep sections separate.

header::after {
  content: "";
  display: block;
  height: 1px;
  width: 100%;
  background: var(--border);
}

/* The class given to divs containing a top level org heading */
.outline-2 {
  border-top: 1px solid var(--border);
  padding-top: 10px;
}

Keeping the minimalist footer neat:

/* positioning only, the rest of the header styling is defined in the default water css below */
#my-contacts {
  display: flex;
  flex-flow: row wrap;
  align-items: center;
  gap: 20px;
}

Code colouring. There's a slightly interesting quirk here as each language can define its own custom token types as well as the more general shared set. We get around that by using fairly permissive attribute selectors to categorise classes within source blocks (for example, colouring all spans with a class including the string keyword or primitive the same way rather than rather a separate rule for .org-typescript-primitive).

/* This class is applied to a wrapper div around code blocks */
.org-src-container {
    color: var(--text-main);
    word-wrap: normal;
}
/** Combines with the language specific rules below to add a "tab"
 * showing the language contained in the code block
 */
.org-src-container:before {
  display: block;
  font-style: italic;
  font-size: 0.8em;
  width: fit-content;
  padding: 5px;
  border-bottom: solid 1px var(--code-value);
  color: var(--text-muted);
  margin-bottom: 0px;
  background-color: var(--code-background);
  border-radius: 8px 8px 0px 0px;
}

pre.src {
  font-family: source_code_pro, monospace;
  font-weight: normal;
  font-size: 0.8rem;
  position: relative;
  white-space: pre;
  margin: 0px;
  /* Code can be long; especially on mobile, it might need to scroll */
  overflow-x: auto;
  background-color: var(--code-background);
  padding: 5px;
  border-radius: 0px 0px 8px 8px;
  margin-top: 0px;
  color: var(--code);
}

code {
  font-size: 80%;
}

pre.src {
  /* Rule for keywords etc */
  & > span[class*="keyword"],
  & > span[class*="access-modifier"] {
      color: var(--code-keyword);
  }

  /* Rule for as many literal values as I can think of */
  & > span[class*="string"],
  & > span[class*="constant"],
  & > span[class*="number"] {
      color: var(--code-value);
  }

  /* Rule for punctuation */
  & > span[class*="punctuation"],
  & > span[class*="rainbow"],
  & > span[class*="bracket"] {
      color: var(--code-punctuation);
  }

  /* Rule for comments */
  & > span[class*="comment"] {
      color: var(--code-comment);
  }

  /* Rule for types etc */
  & > span[class*="type"],
  & > span[class*="attribute"],
  & > span[class*="tag"],
  & > span[class*="primitive"],
  & > span[class*="property"],
  & > span[class*="builtin"] {
      color: var(--code-type);
  }
}

Comments! The comment section is something I've written myself, so needs its own styling.

.box {
  border-top: var(--border) solid 1px;
  border-left: var(--border) solid 1px;
  border-radius: 0.2rem;
  margin-left: 0.5rem;
  margin-bottom: 0.5rem;
  padding-bottom: 1rem;
  padding-left: 1rem;
  background: linear-gradient(var(--background), var(--background-body) 3rem);
}


.replies {
  margin-left: 2rem;
}

.author {
  font-weight: bold;
  color: var(--text-bright);
}

Everything below this point is modified from the default org style sheet, that normally gets embedded into every page. I'm going to separate it out here so that I can start hacking on it, and then set the export not to inject it every time.

.todo   { font-family: monospace; color: red; }
.done   { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag > span   {
  background-color: var(--background-alt);
  color: var(--secondary);
  border-radius: 0.2rem;
  padding: 0.1rem;
  font-size: 75%;
  font-weight: normal;
}
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right  { margin-left: auto; margin-right: 0px;  text-align: right; }
.org-left   { margin-left: 0px;  margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
footer p, #preamble p { font-size: 90%; margin: .2em; min-height: 100px; }
p.verse { margin-left: 3%; }
/* Languages per Org manual */
.org-src-container:has(pre.src-asymptote):before { content: 'Asymptote'; }
.org-src-container:has(pre.src-awk):before { content: 'Awk'; }
.org-src-container:has(pre.src-C):before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
.org-src-container:has(pre.src-clojure):before { content: 'Clojure'; }
.org-src-container:has(pre.src-css):before { content: 'CSS'; }
.org-src-container:has(pre.src-D):before { content: 'D'; }
.org-src-container:has(pre.src-ditaa):before { content: 'ditaa'; }
.org-src-container:has(pre.src-dot):before { content: 'Graphviz'; }
.org-src-container:has(pre.src-calc):before { content: 'Emacs Calc'; }
.org-src-container:has(pre.src-emacs-lisp):before { content: 'Emacs Lisp'; }
.org-src-container:has(pre.src-fortran):before { content: 'Fortran'; }
.org-src-container:has(pre.src-gnuplot):before { content: 'gnuplot'; }
.org-src-container:has(pre.src-haskell):before { content: 'Haskell'; }
.org-src-container:has(pre.src-hledger):before { content: 'hledger'; }
.org-src-container:has(pre.src-java):before { content: 'Java'; }
.org-src-container:has(pre.src-js):before { content: 'Javascript'; }
.org-src-container:has(pre.src-latex):before { content: 'LaTeX'; }
.org-src-container:has(pre.src-ledger):before { content: 'Ledger'; }
.org-src-container:has(pre.src-lisp):before { content: 'Lisp'; }
.org-src-container:has(pre.src-lilypond):before { content: 'Lilypond'; }
.org-src-container:has(pre.src-lua):before { content: 'Lua'; }
.org-src-container:has(pre.src-matlab):before { content: 'MATLAB'; }
.org-src-container:has(pre.src-mscgen):before { content: 'Mscgen'; }
.org-src-container:has(pre.src-ocaml):before { content: 'Objective Caml'; }
.org-src-container:has(pre.src-octave):before { content: 'Octave'; }
.org-src-container:has(pre.src-org):before { content: 'Org mode'; }
.org-src-container:has(pre.src-oz):before { content: 'OZ'; }
.org-src-container:has(pre.src-plantuml):before { content: 'Plantuml'; }
.org-src-container:has(pre.src-processing):before { content: 'Processing.js'; }
.org-src-container:has(pre.src-python):before { content: 'Python'; }
.org-src-container:has(pre.src-R):before { content: 'R'; }
.org-src-container:has(pre.src-ruby):before { content: 'Ruby'; }
.org-src-container:has(pre.src-sass):before { content: 'Sass'; }
.org-src-container:has(pre.src-scheme):before { content: 'Scheme'; }
.org-src-container:has(pre.src-screen):before { content: 'Gnu Screen'; }
.org-src-container:has(pre.src-sed):before { content: 'Sed'; }
.org-src-container:has(pre.src-sh):before { content: 'shell'; }
.org-src-container:has(pre.src-sql):before { content: 'SQL'; }
.org-src-container:has(pre.src-sqlite):before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
.org-src-container:has(pre.src-forth):before { content: 'Forth'; }
.org-src-container:has(pre.src-io):before { content: 'IO'; }
.org-src-container:has(pre.src-J):before { content: 'J'; }
.org-src-container:has(pre.src-makefile):before { content: 'Makefile'; }
.org-src-container:has(pre.src-maxima):before { content: 'Maxima'; }
.org-src-container:has(pre.src-perl):before { content: 'Perl'; }
.org-src-container:has(pre.src-picolisp):before { content: 'Pico Lisp'; }
.org-src-container:has(pre.src-scala):before { content: 'Scala'; }
.org-src-container:has(pre.src-shell):before { content: 'Shell Script'; }
.org-src-container:has(pre.src-ebnf2ps):before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
     in ob-*.el */
.org-src-container:has(pre.src-cpp):before  { content: 'C++'; }
.org-src-container:has(pre.src-abc):before  { content: 'ABC'; }
.org-src-container:has(pre.src-coq):before  { content: 'Coq'; }
.org-src-container:has(pre.src-groovy):before  { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
   ob-shell.el: ob-shell is the only babel language using a lambda to put
   the execution function name together. */
.org-src-container:has(pre.src-bash):before  { content: 'bash'; }
.org-src-container:has(pre.src-csh):before  { content: 'csh'; }
.org-src-container:has(pre.src-ash):before  { content: 'ash'; }
.org-src-container:has(pre.src-dash):before  { content: 'dash'; }
.org-src-container:has(pre.src-ksh):before  { content: 'ksh'; }
.org-src-container:has(pre.src-mksh):before  { content: 'mksh'; }
.org-src-container:has(pre.src-posh):before  { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
.org-src-container:has(pre.src-ada):before { content: 'Ada'; }
.org-src-container:has(pre.src-asm):before { content: 'Assembler'; }
.org-src-container:has(pre.src-caml):before { content: 'Caml'; }
.org-src-container:has(pre.src-delphi):before { content: 'Delphi'; }
.org-src-container:has(pre.src-html):before { content: 'HTML'; }
.org-src-container:has(pre.src-idl):before { content: 'IDL'; }
.org-src-container:has(pre.src-mercury):before { content: 'Mercury'; }
.org-src-container:has(pre.src-metapost):before { content: 'MetaPost'; }
.org-src-container:has(pre.src-modula-2):before { content: 'Modula-2'; }
.org-src-container:has(pre.src-pascal):before { content: 'Pascal'; }
.org-src-container:has(pre.src-ps):before { content: 'PostScript'; }
.org-src-container:has(pre.src-prolog):before { content: 'Prolog'; }
.org-src-container:has(pre.src-simula):before { content: 'Simula'; }
.org-src-container:has(pre.src-tcl):before { content: 'tcl'; }
.org-src-container:has(pre.src-tex):before { content: 'TeX'; }
.org-src-container:has(pre.src-plain-tex):before { content: 'Plain TeX'; }
.org-src-container:has(pre.src-verilog):before { content: 'Verilog'; }
.org-src-container:has(pre.src-vhdl):before { content: 'VHDL'; }
.org-src-container:has(pre.src-xml):before { content: 'XML'; }
.org-src-container:has(pre.src-nxml):before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
   (add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
.org-src-container:has(pre.src-conf):before { content: 'Configuration File'; }

/* added manually after generation */
.org-src-container:has(pre.src-typescript):before { content: 'TypeScript'; }
.org-src-container:has(pre.src-fsharp):before { content: 'F#'; }
.org-src-container:has(pre.src-nix):before { content: 'nix'; }
.org-src-container:has(pre.src-procfile):before { content: 'procfile'; }
.org-src-container:has(pre.src-yaml):before { content: 'yaml'; }
.org-src-container:has(pre.src-ink):before { content: 'ink'; }
.org-src-container:has(pre.src-gdscript):before { content: 'GDScript'; }

caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
th.org-right  { text-align: center;  }
th.org-left   { text-align: center;   }
th.org-center { text-align: center; }
td.org-right  { text-align: right;  }
td.org-left   { text-align: left;   }
td.org-center { text-align: center; }
.footpara { display: inline; }
.footdef  { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.equation-container {
  display: table;
  text-align: center;
  width: 100%;
}
.equation {
  vertical-align: middle;
}
.equation-label {
  display: table-cell;
  text-align: right;
  vertical-align: middle;
}
.inlinetask {
  padding: 10px;
  border: 2px solid gray;
  margin: 10px;
  background: #ffffcc;
}
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
  { font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
  { background-color: #ffff00; color: #000000; font-weight: bold; }
.org-svg { width: 90%; }

This is the contents of the MIT licensed `water.css` file that we're choosing to use, and which aren't already included above!

button {
  transition:
    background-color 0.1s linear,
    border-color 0.1s linear,
    color 0.1s linear,
    box-shadow 0.1s linear,
    transform 0.1s ease;
  transition:
    background-color var(--animation-duration) linear,
    border-color var(--animation-duration) linear,
    color var(--animation-duration) linear,
    box-shadow var(--animation-duration) linear,
    transform var(--animation-duration) ease;
}

@media (prefers-color-scheme: dark) {

  button {
  transition:
    background-color 0.1s linear,
    border-color 0.1s linear,
    color 0.1s linear,
    box-shadow 0.1s linear,
    transform 0.1s ease;
  transition:
    background-color var(--animation-duration) linear,
    border-color var(--animation-duration) linear,
    color var(--animation-duration) linear,
    box-shadow var(--animation-duration) linear,
    transform var(--animation-duration) ease;
  }
}

input {
  transition:
    background-color 0.1s linear,
    border-color 0.1s linear,
    color 0.1s linear,
    box-shadow 0.1s linear,
    transform 0.1s ease;
  transition:
    background-color var(--animation-duration) linear,
    border-color var(--animation-duration) linear,
    color var(--animation-duration) linear,
    box-shadow var(--animation-duration) linear,
    transform var(--animation-duration) ease;
}

@media (prefers-color-scheme: dark) {

  input {
  transition:
    background-color 0.1s linear,
    border-color 0.1s linear,
    color 0.1s linear,
    box-shadow 0.1s linear,
    transform 0.1s ease;
  transition:
    background-color var(--animation-duration) linear,
    border-color var(--animation-duration) linear,
    color var(--animation-duration) linear,
    box-shadow var(--animation-duration) linear,
    transform var(--animation-duration) ease;
  }
}

textarea {
  transition:
    background-color 0.1s linear,
    border-color 0.1s linear,
    color 0.1s linear,
    box-shadow 0.1s linear,
    transform 0.1s ease;
  transition:
    background-color var(--animation-duration) linear,
    border-color var(--animation-duration) linear,
    color var(--animation-duration) linear,
    box-shadow var(--animation-duration) linear,
    transform var(--animation-duration) ease;
}

@media (prefers-color-scheme: dark) {

  textarea {
  transition:
    background-color 0.1s linear,
    border-color 0.1s linear,
    color 0.1s linear,
    box-shadow 0.1s linear,
    transform 0.1s ease;
  transition:
    background-color var(--animation-duration) linear,
    border-color var(--animation-duration) linear,
    color var(--animation-duration) linear,
    box-shadow var(--animation-duration) linear,
    transform var(--animation-duration) ease;
  }
}

h1 {
  font-size: 2.2em;
  margin-top: 0;
}

h1,
h2,
h3,
h4,
h5,
h6 {
  margin-bottom: 12px;
  margin-top: 24px;
}

h1 {
  color: #000;
  color: var(--text-bright);
}

@media (prefers-color-scheme: dark) {

  h1 {
  color: #fff;
  color: var(--text-bright);
  }
}

h2 {
  color: #000;
  color: var(--text-bright);
}

@media (prefers-color-scheme: dark) {

  h2 {
  color: #fff;
  color: var(--text-bright);
  }
}

h3 {
  color: #000;
  color: var(--text-bright);
}

@media (prefers-color-scheme: dark) {

  h3 {
  color: #fff;
  color: var(--text-bright);
  }
}

h4 {
  color: #000;
  color: var(--text-bright);
}

@media (prefers-color-scheme: dark) {

  h4 {
  color: #fff;
  color: var(--text-bright);
  }
}

h5 {
  color: #000;
  color: var(--text-bright);
}

@media (prefers-color-scheme: dark) {

  h5 {
  color: #fff;
  color: var(--text-bright);
  }
}

h6 {
  color: #000;
  color: var(--text-bright);
}

@media (prefers-color-scheme: dark) {

  h6 {
  color: #fff;
  color: var(--text-bright);
  }
}

strong {
  color: #000;
  color: var(--text-bright);
}

@media (prefers-color-scheme: dark) {

  strong {
  color: #fff;
  color: var(--text-bright);
  }
}

h1,
h2,
h3,
h4,
h5,
h6,
b,
strong,
th {
  font-weight: 600;
}

q::before {
  content: none;
}

q::after {
  content: none;
}

blockquote {
  border-left: 4px solid #0096bfab;
  border-left: 4px solid var(--focus);
  margin: 1.5em 0;
  padding: 0.5em 1em;
}

@media (prefers-color-scheme: dark) {

  blockquote {
  border-left: 4px solid #0096bfab;
  border-left: 4px solid var(--focus);
  }
}

q {
  border-left: 4px solid #0096bfab;
  border-left: 4px solid var(--focus);
  margin: 1.5em 0;
  padding: 0.5em 1em;
  font-style: italic;
}

@media (prefers-color-scheme: dark) {

  q {
  border-left: 4px solid #0096bfab;
  border-left: 4px solid var(--focus);
  }
}

blockquote > footer {
  font-style: normal;
  border: 0;
}

blockquote cite {
  font-style: normal;
}

address {
  font-style: normal;
}

a[href^='mailto\:']::before {
  content: '📧 ';
}

a[href^='tel\:']::before {
  content: '📞 ';
}

a[href^='sms\:']::before {
  content: '💬 ';
}

mark {
  background-color: #ff0;
  background-color: var(--highlight);
  border-radius: 2px;
  padding: 0 2px 0 2px;
  color: #000;
}

@media (prefers-color-scheme: dark) {

  mark {
  background-color: #efdb43;
  background-color: var(--highlight);
  }
}

a > code,
a > strong {
  color: inherit;
}

button,
select,
input[type='submit'],
input[type='reset'],
input[type='button'],
input[type='checkbox'],
input[type='range'],
input[type='radio'] {
  cursor: pointer;
}

input,
select {
  display: block;
}

[type='checkbox'],
[type='radio'] {
  display: initial;
}

input {
  color: #1d1d1d;
  color: var(--form-text);
  background-color: #efefef;
  background-color: var(--background);
  font-family: inherit;
  font-size: inherit;
  margin-right: 6px;
  margin-bottom: 6px;
  padding: 10px;
  border: none;
  border-radius: 6px;
  outline: none;
}

@media (prefers-color-scheme: dark) {

  input {
  background-color: #161f27;
  background-color: var(--background);
  }
}

@media (prefers-color-scheme: dark) {

  input {
  color: #fff;
  color: var(--form-text);
  }
}

button {
  color: #1d1d1d;
  color: var(--form-text);
  background-color: #efefef;
  background-color: var(--background);
  font-family: inherit;
  font-size: inherit;
  margin-right: 6px;
  margin-bottom: 6px;
  padding: 10px;
  border: none;
  border-radius: 6px;
  outline: none;
}

@media (prefers-color-scheme: dark) {

  button {
  background-color: #161f27;
  background-color: var(--background);
  }
}

@media (prefers-color-scheme: dark) {

  button {
  color: #fff;
  color: var(--form-text);
  }
}

textarea {
  color: #1d1d1d;
  color: var(--form-text);
  background-color: #efefef;
  background-color: var(--background);
  font-family: inherit;
  font-size: inherit;
  margin-right: 6px;
  margin-bottom: 6px;
  padding: 10px;
  border: none;
  border-radius: 6px;
  outline: none;
}

@media (prefers-color-scheme: dark) {

  textarea {
  background-color: #161f27;
  background-color: var(--background);
  }
}

@media (prefers-color-scheme: dark) {

  textarea {
  color: #fff;
  color: var(--form-text);
  }
}

select {
  color: #1d1d1d;
  color: var(--form-text);
  background-color: #efefef;
  background-color: var(--background);
  font-family: inherit;
  font-size: inherit;
  margin-right: 6px;
  margin-bottom: 6px;
  padding: 10px;
  border: none;
  border-radius: 6px;
  outline: none;
}

@media (prefers-color-scheme: dark) {

  select {
  background-color: #161f27;
  background-color: var(--background);
  }
}

@media (prefers-color-scheme: dark) {

  select {
  color: #fff;
  color: var(--form-text);
  }
}

button {
  background-color: #d0cfcf;
  background-color: var(--button-base);
  padding-right: 30px;
  padding-left: 30px;
}

@media (prefers-color-scheme: dark) {

  button {
  background-color: #0c151c;
  background-color: var(--button-base);
  }
}

input[type='submit'] {
  background-color: #d0cfcf;
  background-color: var(--button-base);
  padding-right: 30px;
  padding-left: 30px;
}

@media (prefers-color-scheme: dark) {

  input[type='submit'] {
  background-color: #0c151c;
  background-color: var(--button-base);
  }
}

input[type='reset'] {
  background-color: #d0cfcf;
  background-color: var(--button-base);
  padding-right: 30px;
  padding-left: 30px;
}

@media (prefers-color-scheme: dark) {

  input[type='reset'] {
  background-color: #0c151c;
  background-color: var(--button-base);
  }
}

input[type='button'] {
  background-color: #d0cfcf;
  background-color: var(--button-base);
  padding-right: 30px;
  padding-left: 30px;
}

@media (prefers-color-scheme: dark) {

  input[type='button'] {
  background-color: #0c151c;
  background-color: var(--button-base);
  }
}

button:hover {
  background: #9b9b9b;
  background: var(--button-hover);
}

@media (prefers-color-scheme: dark) {

  button:hover {
  background: #040a0f;
  background: var(--button-hover);
  }
}

input[type='submit']:hover {
  background: #9b9b9b;
  background: var(--button-hover);
}

@media (prefers-color-scheme: dark) {

  input[type='submit']:hover {
  background: #040a0f;
  background: var(--button-hover);
  }
}

input[type='reset']:hover {
  background: #9b9b9b;
  background: var(--button-hover);
}

@media (prefers-color-scheme: dark) {

  input[type='reset']:hover {
  background: #040a0f;
  background: var(--button-hover);
  }
}

input[type='button']:hover {
  background: #9b9b9b;
  background: var(--button-hover);
}

@media (prefers-color-scheme: dark) {

  input[type='button']:hover {
  background: #040a0f;
  background: var(--button-hover);
  }
}

input[type='color'] {
  min-height: 2rem;
  padding: 8px;
  cursor: pointer;
}

input[type='checkbox'],
input[type='radio'] {
  height: 1em;
  width: 1em;
}

input[type='radio'] {
  border-radius: 100%;
}

input {
  vertical-align: top;
}

label {
  vertical-align: middle;
  margin-bottom: 4px;
  display: inline-block;
}

input:not([type='checkbox']):not([type='radio']),
input[type='range'],
select,
button,
textarea {
  -webkit-appearance: none;
}

textarea {
  display: block;
  margin-right: 0;
  box-sizing: border-box;
  resize: vertical;
}

textarea:not([cols]) {
  width: 100%;
}

textarea:not([rows]) {
  min-height: 40px;
  height: 140px;
}

select {
  background: #efefef url("data:image/svg+xml;charset=utf-8,%3C?xml version='1.0' encoding='utf-8'?%3E %3Csvg version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' height='62.5' width='116.9' fill='%23161f27'%3E %3Cpath d='M115.3,1.6 C113.7,0 111.1,0 109.5,1.6 L58.5,52.7 L7.4,1.6 C5.8,0 3.2,0 1.6,1.6 C0,3.2 0,5.8 1.6,7.4 L55.5,61.3 C56.3,62.1 57.3,62.5 58.4,62.5 C59.4,62.5 60.5,62.1 61.3,61.3 L115.2,7.4 C116.9,5.8 116.9,3.2 115.3,1.6Z'/%3E %3C/svg%3E") calc(100% - 12px) 50% / 12px no-repeat;
  background: var(--background) var(--select-arrow) calc(100% - 12px) 50% / 12px no-repeat;
  padding-right: 35px;
}

@media (prefers-color-scheme: dark) {

  select {
  background: #161f27 url("data:image/svg+xml;charset=utf-8,%3C?xml version='1.0' encoding='utf-8'?%3E %3Csvg version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' height='62.5' width='116.9' fill='%23efefef'%3E %3Cpath d='M115.3,1.6 C113.7,0 111.1,0 109.5,1.6 L58.5,52.7 L7.4,1.6 C5.8,0 3.2,0 1.6,1.6 C0,3.2 0,5.8 1.6,7.4 L55.5,61.3 C56.3,62.1 57.3,62.5 58.4,62.5 C59.4,62.5 60.5,62.1 61.3,61.3 L115.2,7.4 C116.9,5.8 116.9,3.2 115.3,1.6Z'/%3E %3C/svg%3E") calc(100% - 12px) 50% / 12px no-repeat;
  background: var(--background) var(--select-arrow) calc(100% - 12px) 50% / 12px no-repeat;
  }
}

@media (prefers-color-scheme: dark) {

  select {
  background: #161f27 url("data:image/svg+xml;charset=utf-8,%3C?xml version='1.0' encoding='utf-8'?%3E %3Csvg version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' height='62.5' width='116.9' fill='%23efefef'%3E %3Cpath d='M115.3,1.6 C113.7,0 111.1,0 109.5,1.6 L58.5,52.7 L7.4,1.6 C5.8,0 3.2,0 1.6,1.6 C0,3.2 0,5.8 1.6,7.4 L55.5,61.3 C56.3,62.1 57.3,62.5 58.4,62.5 C59.4,62.5 60.5,62.1 61.3,61.3 L115.2,7.4 C116.9,5.8 116.9,3.2 115.3,1.6Z'/%3E %3C/svg%3E") calc(100% - 12px) 50% / 12px no-repeat;
  background: var(--background) var(--select-arrow) calc(100% - 12px) 50% / 12px no-repeat;
  }
}

@media (prefers-color-scheme: dark) {

  select {
  background: #161f27 url("data:image/svg+xml;charset=utf-8,%3C?xml version='1.0' encoding='utf-8'?%3E %3Csvg version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' height='62.5' width='116.9' fill='%23efefef'%3E %3Cpath d='M115.3,1.6 C113.7,0 111.1,0 109.5,1.6 L58.5,52.7 L7.4,1.6 C5.8,0 3.2,0 1.6,1.6 C0,3.2 0,5.8 1.6,7.4 L55.5,61.3 C56.3,62.1 57.3,62.5 58.4,62.5 C59.4,62.5 60.5,62.1 61.3,61.3 L115.2,7.4 C116.9,5.8 116.9,3.2 115.3,1.6Z'/%3E %3C/svg%3E") calc(100% - 12px) 50% / 12px no-repeat;
  background: var(--background) var(--select-arrow) calc(100% - 12px) 50% / 12px no-repeat;
  }
}

@media (prefers-color-scheme: dark) {

  select {
  background: #161f27 url("data:image/svg+xml;charset=utf-8,%3C?xml version='1.0' encoding='utf-8'?%3E %3Csvg version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' height='62.5' width='116.9' fill='%23efefef'%3E %3Cpath d='M115.3,1.6 C113.7,0 111.1,0 109.5,1.6 L58.5,52.7 L7.4,1.6 C5.8,0 3.2,0 1.6,1.6 C0,3.2 0,5.8 1.6,7.4 L55.5,61.3 C56.3,62.1 57.3,62.5 58.4,62.5 C59.4,62.5 60.5,62.1 61.3,61.3 L115.2,7.4 C116.9,5.8 116.9,3.2 115.3,1.6Z'/%3E %3C/svg%3E") calc(100% - 12px) 50% / 12px no-repeat;
  background: var(--background) var(--select-arrow) calc(100% - 12px) 50% / 12px no-repeat;
  }
}

select::-ms-expand {
  display: none;
}

select[multiple] {
  padding-right: 10px;
  background-image: none;
  overflow-y: auto;
}

input:focus {
  box-shadow: 0 0 0 2px #0096bfab;
  box-shadow: 0 0 0 2px var(--focus);
}

@media (prefers-color-scheme: dark) {

  input:focus {
  box-shadow: 0 0 0 2px #0096bfab;
  box-shadow: 0 0 0 2px var(--focus);
  }
}

select:focus {
  box-shadow: 0 0 0 2px #0096bfab;
  box-shadow: 0 0 0 2px var(--focus);
}

@media (prefers-color-scheme: dark) {

  select:focus {
  box-shadow: 0 0 0 2px #0096bfab;
  box-shadow: 0 0 0 2px var(--focus);
  }
}

button:focus {
  box-shadow: 0 0 0 2px #0096bfab;
  box-shadow: 0 0 0 2px var(--focus);
}

@media (prefers-color-scheme: dark) {

  button:focus {
  box-shadow: 0 0 0 2px #0096bfab;
  box-shadow: 0 0 0 2px var(--focus);
  }
}

textarea:focus {
  box-shadow: 0 0 0 2px #0096bfab;
  box-shadow: 0 0 0 2px var(--focus);
}

@media (prefers-color-scheme: dark) {

  textarea:focus {
  box-shadow: 0 0 0 2px #0096bfab;
  box-shadow: 0 0 0 2px var(--focus);
  }
}

input[type='checkbox']:active,
input[type='radio']:active,
input[type='submit']:active,
input[type='reset']:active,
input[type='button']:active,
input[type='range']:active,
button:active {
  transform: translateY(2px);
}

input:disabled,
select:disabled,
button:disabled,
textarea:disabled {
  cursor: not-allowed;
  opacity: 0.5;
}

::-moz-placeholder {
  color: #949494;
  color: var(--form-placeholder);
}

:-ms-input-placeholder {
  color: #949494;
  color: var(--form-placeholder);
}

::-ms-input-placeholder {
  color: #949494;
  color: var(--form-placeholder);
}

::placeholder {
  color: #949494;
  color: var(--form-placeholder);
}

@media (prefers-color-scheme: dark) {

  ::-moz-placeholder {
  color: #a9a9a9;
  color: var(--form-placeholder);
  }

  :-ms-input-placeholder {
  color: #a9a9a9;
  color: var(--form-placeholder);
  }

  ::-ms-input-placeholder {
  color: #a9a9a9;
  color: var(--form-placeholder);
  }

  ::placeholder {
  color: #a9a9a9;
  color: var(--form-placeholder);
  }
}

fieldset {
  border: 1px #0096bfab solid;
  border: 1px var(--focus) solid;
  border-radius: 6px;
  margin: 0;
  margin-bottom: 12px;
  padding: 10px;
}

@media (prefers-color-scheme: dark) {

  fieldset {
  border: 1px #0096bfab solid;
  border: 1px var(--focus) solid;
  }
}

legend {
  font-size: 0.9em;
  font-weight: 600;
}

input[type='range'] {
  margin: 10px 0;
  padding: 10px 0;
  background: transparent;
}

input[type='range']:focus {
  outline: none;
}

input[type='range']::-webkit-slider-runnable-track {
  width: 100%;
  height: 9.5px;
  -webkit-transition: 0.2s;
  transition: 0.2s;
  background: #efefef;
  background: var(--background);
  border-radius: 3px;
}

@media (prefers-color-scheme: dark) {

  input[type='range']::-webkit-slider-runnable-track {
  background: #161f27;
  background: var(--background);
  }
}

input[type='range']::-webkit-slider-thumb {
  box-shadow: 0 1px 1px #000, 0 0 1px #0d0d0d;
  height: 20px;
  width: 20px;
  border-radius: 50%;
  background: #dbdbdb;
  background: var(--border);
  -webkit-appearance: none;
  margin-top: -7px;
}

@media (prefers-color-scheme: dark) {

  input[type='range']::-webkit-slider-thumb {
  background: #526980;
  background: var(--border);
  }
}

input[type='range']:focus::-webkit-slider-runnable-track {
  background: #efefef;
  background: var(--background);
}

@media (prefers-color-scheme: dark) {

  input[type='range']:focus::-webkit-slider-runnable-track {
  background: #161f27;
  background: var(--background);
  }
}

input[type='range']::-moz-range-track {
  width: 100%;
  height: 9.5px;
  -moz-transition: 0.2s;
  transition: 0.2s;
  background: #efefef;
  background: var(--background);
  border-radius: 3px;
}

@media (prefers-color-scheme: dark) {

  input[type='range']::-moz-range-track {
  background: #161f27;
  background: var(--background);
  }
}

input[type='range']::-moz-range-thumb {
  box-shadow: 1px 1px 1px #000, 0 0 1px #0d0d0d;
  height: 20px;
  width: 20px;
  border-radius: 50%;
  background: #dbdbdb;
  background: var(--border);
}

@media (prefers-color-scheme: dark) {

  input[type='range']::-moz-range-thumb {
  background: #526980;
  background: var(--border);
  }
}

input[type='range']::-ms-track {
  width: 100%;
  height: 9.5px;
  background: transparent;
  border-color: transparent;
  border-width: 16px 0;
  color: transparent;
}

input[type='range']::-ms-fill-lower {
  background: #efefef;
  background: var(--background);
  border: 0.2px solid #010101;
  border-radius: 3px;
  box-shadow: 1px 1px 1px #000, 0 0 1px #0d0d0d;
}

@media (prefers-color-scheme: dark) {

  input[type='range']::-ms-fill-lower {
  background: #161f27;
  background: var(--background);
  }
}

input[type='range']::-ms-fill-upper {
  background: #efefef;
  background: var(--background);
  border: 0.2px solid #010101;
  border-radius: 3px;
  box-shadow: 1px 1px 1px #000, 0 0 1px #0d0d0d;
}

@media (prefers-color-scheme: dark) {

  input[type='range']::-ms-fill-upper {
  background: #161f27;
  background: var(--background);
  }
}

input[type='range']::-ms-thumb {
  box-shadow: 1px 1px 1px #000, 0 0 1px #0d0d0d;
  border: 1px solid #000;
  height: 20px;
  width: 20px;
  border-radius: 50%;
  background: #dbdbdb;
  background: var(--border);
}

@media (prefers-color-scheme: dark) {

  input[type='range']::-ms-thumb {
  background: #526980;
  background: var(--border);
  }
}

input[type='range']:focus::-ms-fill-lower {
  background: #efefef;
  background: var(--background);
}

@media (prefers-color-scheme: dark) {

  input[type='range']:focus::-ms-fill-lower {
  background: #161f27;
  background: var(--background);
  }
}

input[type='range']:focus::-ms-fill-upper {
  background: #efefef;
  background: var(--background);
}

@media (prefers-color-scheme: dark) {

  input[type='range']:focus::-ms-fill-upper {
  background: #161f27;
  background: var(--background);
  }
}

a {
  text-decoration: none;
  color: #0076d1;
  color: var(--links);
}

@media (prefers-color-scheme: dark) {

  a {
  color: #41adff;
  color: var(--links);
  }
}

a:hover {
  text-decoration: underline;
}

code {
  background: #efefef;
  background: var(--background);
  color: #000;
  color: var(--code);
  padding: 2.5px 5px;
  border-radius: 6px;
}

@media (prefers-color-scheme: dark) {

  code {
  color: #ffbe85;
  color: var(--code);
  }
}

@media (prefers-color-scheme: dark) {

  code {
  background: #161f27;
  background: var(--background);
  }
}

samp {
  background: #efefef;
  background: var(--background);
  color: #000;
  color: var(--code);
  padding: 2.5px 5px;
  border-radius: 6px;
  font-size: 1em;
}

@media (prefers-color-scheme: dark) {

  samp {
  color: #ffbe85;
  color: var(--code);
  }
}

@media (prefers-color-scheme: dark) {

  samp {
  background: #161f27;
  background: var(--background);
  }
}

time {
  background: #efefef;
  background: var(--background);
  color: #000;
  color: var(--code);
  padding: 2.5px 5px;
  border-radius: 6px;
  font-size: 1em;
}

@media (prefers-color-scheme: dark) {

  time {
  color: #ffbe85;
  color: var(--code);
  }
}

@media (prefers-color-scheme: dark) {

  time {
  background: #161f27;
  background: var(--background);
  }
}

pre > code {
  padding: 10px;
  display: block;
  overflow-x: auto;
}

var {
  color: #39a33c;
  color: var(--variable);
  font-style: normal;
  font-family: monospace;
}

@media (prefers-color-scheme: dark) {

  var {
  color: #d941e2;
  color: var(--variable);
  }
}

kbd {
  background: #efefef;
  background: var(--background);
  border: 1px solid #dbdbdb;
  border: 1px solid var(--border);
  border-radius: 2px;
  color: #363636;
  color: var(--text-main);
  padding: 2px 4px 2px 4px;
}

@media (prefers-color-scheme: dark) {

  kbd {
  color: #dbdbdb;
  color: var(--text-main);
  }
}

@media (prefers-color-scheme: dark) {

  kbd {
  border: 1px solid #526980;
  border: 1px solid var(--border);
  }
}

@media (prefers-color-scheme: dark) {

  kbd {
  background: #161f27;
  background: var(--background);
  }
}

img,
video {
  max-width: 100%;
  height: auto;
}

hr {
  border: none;
  border-top: 1px solid #dbdbdb;
  border-top: 1px solid var(--border);
}

@media (prefers-color-scheme: dark) {

  hr {
  border-top: 1px solid #526980;
  border-top: 1px solid var(--border);
  }
}

table {
  border-collapse: collapse;
  margin-bottom: 10px;
  width: 100%;
  table-layout: fixed;
}

table caption {
  text-align: left;
}

td,
th {
  padding: 6px;
  text-align: left;
  vertical-align: top;
  word-wrap: break-word;
}

thead {
  border-bottom: 1px solid #dbdbdb;
  border-bottom: 1px solid var(--border);
}

@media (prefers-color-scheme: dark) {

  thead {
  border-bottom: 1px solid #526980;
  border-bottom: 1px solid var(--border);
  }
}

tfoot {
  border-top: 1px solid #dbdbdb;
  border-top: 1px solid var(--border);
}

@media (prefers-color-scheme: dark) {

  tfoot {
  border-top: 1px solid #526980;
  border-top: 1px solid var(--border);
  }
}

tbody tr:nth-child(even) {
  background-color: #efefef;
  background-color: var(--background);
}

@media (prefers-color-scheme: dark) {

  tbody tr:nth-child(even) {
  background-color: #161f27;
  background-color: var(--background);
  }
}

tbody tr:nth-child(even) button {
  background-color: #f7f7f7;
  background-color: var(--background-alt);
}

@media (prefers-color-scheme: dark) {

  tbody tr:nth-child(even) button {
  background-color: #1a242f;
  background-color: var(--background-alt);
  }
}

tbody tr:nth-child(even) button:hover {
  background-color: #fff;
  background-color: var(--background-body);
}

@media (prefers-color-scheme: dark) {

  tbody tr:nth-child(even) button:hover {
  background-color: #202b38;
  background-color: var(--background-body);
  }
}

::-webkit-scrollbar {
  height: 10px;
  width: 10px;
}

::-webkit-scrollbar-track {
  background: #efefef;
  background: var(--background);
  border-radius: 6px;
}

@media (prefers-color-scheme: dark) {

  ::-webkit-scrollbar-track {
  background: #161f27;
  background: var(--background);
  }
}

::-webkit-scrollbar-thumb {
  background: rgb(170, 170, 170);
  background: var(--scrollbar-thumb);
  border-radius: 6px;
}

@media (prefers-color-scheme: dark) {

  ::-webkit-scrollbar-thumb {
  background: #040a0f;
  background: var(--scrollbar-thumb);
  }
}

@media (prefers-color-scheme: dark) {

  ::-webkit-scrollbar-thumb {
  background: #040a0f;
  background: var(--scrollbar-thumb);
  }
}

::-webkit-scrollbar-thumb:hover {
  background: #9b9b9b;
  background: var(--scrollbar-thumb-hover);
}

@media (prefers-color-scheme: dark) {

  ::-webkit-scrollbar-thumb:hover {
  background: rgb(0, 0, 0);
  background: var(--scrollbar-thumb-hover);
  }
}

@media (prefers-color-scheme: dark) {

  ::-webkit-scrollbar-thumb:hover {
  background: rgb(0, 0, 0);
  background: var(--scrollbar-thumb-hover);
  }
}

::-moz-selection {
  background-color: #9e9e9e;
  background-color: var(--selection);
  color: #000;
  color: var(--text-bright);
}

::selection {
  background-color: #9e9e9e;
  background-color: var(--selection);
  color: #000;
  color: var(--text-bright);
}

@media (prefers-color-scheme: dark) {

  ::-moz-selection {
  color: #fff;
  color: var(--text-bright);
  }

  ::selection {
  color: #fff;
  color: var(--text-bright);
  }
}

@media (prefers-color-scheme: dark) {

  ::-moz-selection {
  background-color: #1c76c5;
  background-color: var(--selection);
  }

  ::selection {
  background-color: #1c76c5;
  background-color: var(--selection);
  }
}

details {
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  background-color: #f7f7f7;
  background-color: var(--background-alt);
  padding: 10px 10px 0;
  margin: 1em 0;
  border-radius: 6px;
  overflow: hidden;
}

@media (prefers-color-scheme: dark) {

  details {
  background-color: #1a242f;
  background-color: var(--background-alt);
  }
}

details[open] {
  padding: 10px;
}

details > :last-child {
  margin-bottom: 0;
}

details[open] summary {
  margin-bottom: 10px;
}

summary {
  display: list-item;
  background-color: #efefef;
  background-color: var(--background);
  padding: 10px;
  margin: -10px -10px 0;
  cursor: pointer;
  outline: none;
}

@media (prefers-color-scheme: dark) {

  summary {
  background-color: #161f27;
  background-color: var(--background);
  }
}

summary:hover,
summary:focus {
  text-decoration: underline;
}

details > :not(summary) {
  margin-top: 0;
}

summary::-webkit-details-marker {
  color: #363636;
  color: var(--text-main);
}

@media (prefers-color-scheme: dark) {

  summary::-webkit-details-marker {
  color: #dbdbdb;
  color: var(--text-main);
  }
}

dialog {
  background-color: #f7f7f7;
  background-color: var(--background-alt);
  color: #363636;
  color: var(--text-main);
  border: none;
  border-radius: 6px;
  border-color: #dbdbdb;
  border-color: var(--border);
  padding: 10px 30px;
}

@media (prefers-color-scheme: dark) {

  dialog {
  border-color: #526980;
  border-color: var(--border);
  }
}

@media (prefers-color-scheme: dark) {

  dialog {
  color: #dbdbdb;
  color: var(--text-main);
  }
}

@media (prefers-color-scheme: dark) {

  dialog {
  background-color: #1a242f;
  background-color: var(--background-alt);
  }
}

dialog > header:first-child {
  background-color: #efefef;
  background-color: var(--background);
  border-radius: 6px 6px 0 0;
  margin: -10px -30px 10px;
  padding: 10px;
  text-align: center;
}

@media (prefers-color-scheme: dark) {

  dialog > header:first-child {
  background-color: #161f27;
  background-color: var(--background);
  }
}

dialog::-webkit-backdrop {
  background: #0000009c;
  -webkit-backdrop-filter: blur(4px);
          backdrop-filter: blur(4px);
}

dialog::backdrop {
  background: #0000009c;
  -webkit-backdrop-filter: blur(4px);
          backdrop-filter: blur(4px);
}

footer {
  border-top: 1px solid #dbdbdb;
  border-top: 1px solid var(--border);
  padding-top: 10px;
  color: #70777f;
  color: var(--text-muted);
}

@media (prefers-color-scheme: dark) {

  footer {
  color: #a9b1ba;
  color: var(--text-muted);
  }
}

@media (prefers-color-scheme: dark) {

  footer {
  border-top: 1px solid #526980;
  border-top: 1px solid var(--border);
  }
}

body > footer {
  margin-top: 40px;
}

@media print {
  body,
  pre,
  code,
  summary,
  details,
  button,
  input,
  textarea {
    background-color: #fff;
  }

  button,
  input,
  textarea {
    border: 1px solid #000;
  }

  body,
  h1,
  h2,
  h3,
  h4,
  h5,
  h6,
  pre,
  code,
  button,
  input,
  textarea,
  footer,
  summary,
  strong {
    color: #000;
  }

  summary::marker {
    color: #000;
  }

  summary::-webkit-details-marker {
    color: #000;
  }

  tbody tr:nth-child(even) {
    background-color: #f2f2f2;
  }

  a {
    color: #00f;
    text-decoration: underline;
  }
}

And I think that's all we need for now.

Mavnn's blog

@blog · last month

Read this post in its full formatted glory at https://blog.mavnn.eu/2022/01/07/types-in-typescript.html

26.0.1. These are not the types you are looking for

TypeScript's compiler will let you write code that looks illegal - but compiles just fine.

This is the story of one such piece of code, and the epiphany it led me to: TypeScript doesn't use your type definitions to decide if a type is compatible, it uses the JavaScript that could represent that type.

Let's walk through what that means.

26.0.2. The code

I'm writing code to make defining GraphQL resolvers a type safe experience (earlier developer feedback for the win). You don't need to know the details of GQL to follow this example though; all you need to know is that I have a type for defining the configuration of a resolver, and once certain information is supplied, I know the config is valid.

Let's have a look at some code:

type ConfigValid = "valid" | "invalid"

class Config<T extends ConfigValid> {
  private myConfig: string | null = null

  private constructor() {}

  public static make(): Config<"invalid"> {
    return new Config<"invalid">()
  }

  // I want this function to only accept valid configurations, and I want to
  // check if they are valid *at compile time*
  public static build(config: Config<"valid">) {
    // do stuff!
    console.log(config.myConfig)
  }
}

Pop quiz: Config.make always returns a Config<"invalid">, and Config.build only takes a Config<"valid">. Will the code Config.build(Config.make()) compile or not?

Given I'm asking, you've probably guessed that it does compile, breaking both my intuition... and my code.

Why?

26.0.3. What actually is TypeScript anyway?

Don't get whiplash, I'm going somewhere with this.

What is TypeScript?

Let's hit the TypeScript website. It starts with "TypeScript is JavaScript with syntax for types", and then continues with "TypeScript is a strongly typed programming language that builds on JavaScript, giving you better tooling at any scale".

To my way of thinking, that first quote looks accurate. The second is a lie.

Okay, okay: "strongly typed" has "no precise technical definition" so you can argue that it's half true; I wouldn't agree, given the code above, but you can argue it. But what I'm really calling a lie is the statement that TypeScript is a programming language.

I would instead argue that TypeScript is an inline theorem prover for JavaScript. Because anything that does something in your code is really JavaScript - after all, TypeScript compiles to JavaScript, and all your lovely types are erased. While all of the TypeScript in your code (anything that isn't valid JavaScript) is just there trying to prove that your code is correct.

TypeScript has been designed to make demonstrating correctness as easy as possible when dealing with existing (untyped) JavaScript. (Hint: as easy as possible doesn't mean easy...)

26.0.4. Erm... what's this got to do with the code above?

We're not there yet. Stage 2 in our journey is structural typing.

Most strongly typed programming languages use "nominal" typing. Roughly, it's the "name" of the type that matters and if you give two types two different names (not aliases, actual different names), the compiler will keep track of which one you use where and treat them as different things - even if they hold exactly the same data.

So in, for example, F#, the following two types are not the same, and a function that accepts one will not accept the other:

type FirstRecord = {
    name: string
}

type SecondRecord = {
    name: string
}

let withFirstRecord (record: FirstRecord) =
  record.name

Trying to send a record of SecondRecord to withFirstRecord would be a compile time error. Now, in F# there's an alternative; the function below will accept any type with a member called name:

let inline withName arg =
  (^a : (member name : string) arg)

Notice a few things here:

That syntax is horrific; turns out this is a deliberate choice to discourage overuse (see the rest of the bullets for why)
I had to add the inline keyword to get it to compile. This literally means that in each place this method is used, the compiler will inline a version that uses the type inferred in that location in the code base. This can be good or bad.
You can probably imagine that the error messages from this type of code become explosively unreadable if you nest several layers of functions using this technique, and the constraints start to grow. F# can no longer tell you "you need to give my a FirstRecord"; instead it has to resort to "here's a list of constraints, find me something that meets them all."

This is structural typing, checking types based on the type of data that they hold. And here we wrap back around to TypeScript, which always uses structural typing.

The question is: what are we comparing to see if things are structurally compatible? And this is where my intuition was broken.

In F#, we're comparing the type definition to the constraints. But in TypeScript, we're comparing the JavaScript representation of the type to the constraints because TypeScript exists to make JavaScript safer, not to be a programming language in its own right.

26.0.5. The mystery resolved

Back to our code:

type ConfigValid = "valid" | "invalid"

class Config<T extends ConfigValid> {
  private myConfig: string | null = null

  private constructor() {}

  public static make(): Config<"invalid"> {
    return new Config<"invalid">()
  }

  // I want this function to only accept valid configurations, and I want to
  // check if they are valid *at compile time*
  public static build(config: Config<"valid">) {
    // do stuff!
    console.log(config.myConfig)
  }
}

What is the difference between the JavaScript representations of Config<"invalid"> and Config<"valid">?

Answer: nothing.

The generic parameter on the type is not used or stored at runtime (i.e. in JavaScript) on Config, and therefore it gets completely erased when we compile to JavaScript. Suddenly, it becomes no surprise that the compiler is perfectly happy to allow the use of Config<"invalid"> anywhere we specify Config<"valid"> - by TypeScript's standards they are structurally equivalent.

26.0.6. But: the safety?!

Okay, so the code above doesn't work. But now we know what the problem actually is, so... let's fix it!

type ConfigValid = "valid" | "invalid"

class Config<T extends ConfigValid> {
  private myConfig: string | null = null
  private _isValid: T

  private constructor(isValid: T) {
    this._isValid = isValid
  }

  public static make(): Config<"invalid"> {
    return new Config<"invalid">("invalid")
  }

  // I want this function to only accept valid configurations, and I want to
  // check if they are valid *at compile time*
  public static build(config: Config<"valid">) {
    // do stuff!
    console.log(config.myConfig)
  }
}

You see that _isValid field? Now we're storing a value in that field, and that value will exist at runtime in the compiled JavaScript. Now TypeScript cares about it, and now we can call Config.build safe in the knowledge it will only take a valid configuration instance.

26.0.7. That's a wrap

I hope you've enjoyed this little journey into making making illegal states unrepresentable, and if you think you could enjoy this kind of thing (or even using the results to just build stuff!) I'm currently working with Blissfully and we're currently hiring (it says backend developers, but we're also hiring for our Elm frontend where making illegal states unrepresentable is even easier...).

If you feel a burning need to comment on this post, or suggest a correction, you can submit suggestions for changes(GitHub account required). Just hit the "edit this file button" and go from there.

With special thanks to Matthew Griffith and Aaron White for reading, pushing for and suggesting a stronger title and introductory paragraph.

Mavnn's blog

@blog · last month

⁂ Article

Teaching (coding) wisdom

Read this post in its full formatted glory at https://blog.mavnn.eu/2022/06/20/teaching-coding-wisdom.html

[talking about the teaching of wisdom]

There are these distillations that we get throughout the story, like in the ten commandments or in the Sermon on the Mount. At points, it’s very clear: “Don’t murder.” “Honor your ma and pa.” “Do to others what you want them to do to you.” But if you really think about it, you don’t want a list. You might want a list for a certain season that will train your moral compass. Then, when you confront really complex situations, like Joshua or Moses, and it’s not clear, and there’s no list, you’ve been shaped to be the kind of person who knows how to figure out the right way forward. Lists will not help you do that. Wisdom will help you do that.

--- https://bibleproject.com/podcast/wisdom-lifes-complexity/

Listening to the podcast above earlier and thinking that it feels very similar to how to teach good coding practices. We use the short hand of rules, and lists of recommendations… sometimes. But that doesn’t teach you how to deal with the complex situations, the edge cases, the actual real problems that need solving.

The flip side being that as soon as you’re guided by wisdom, by the stories of what works, the shaping of thinking, you start getting into interpretation and ambiguity because you’re actually needing to think about the decisions you’re making. It can become hard to explain why you’re doing things, and different experiences will have coloured the “wisdom” that you’ve formed over the years. Which is why it becomes so important to have a variety of backgrounds and a willingness to communicate in a technical team that’s actually going to get things done. Why the lists and rules (microservices rule the world! TDD is the one true way! pure code is the only real code!) only get you so far, and should be starting points - not ending points.

If you'd like to comment on this post, or suggest a correction, you can submit suggestions for changes (GitHub account required). Just hit the "edit this file button" and go from there - or log an issue on the repository.

Mavnn's blog

@blog · last month

⁂ Article

ADHD and me

Read this post in its full formatted glory at https://blog.mavnn.eu/2022/10/14/adhd_and_me.html

This morning, I did the washing up.

Now: your first response might be "Michael: why do I care? Do I look like a washing up blog reader?"

But that would miss the point. This morning I did the washing up, and only the washing up. I didn't procrastinate with some Twitter or YouTube videos first. I didn't need to listen to a podcast at the same time to avoid getting lost staring off into space thinking about something completely different.

Most importantly: no crushing feeling of overwhelm about needing to do this task that both feels insurmountable but is obviously (objectively) trivial. It's embarrassing to admit that I've been repeatedly reduced to tears by the need to do the washing up.

This change, it appears, is the impact of methylphenidate (Ritalin®) on my brain. I was recently diagnosed with ADHD, and yesterday I undertook a series of "challenge tests" to see if I am one of the 75% of adult's with ADHD whose symptoms are helped by the drug.

I did the same series of tests twice: once in the morning, before taking methylphenidate; the other in the afternoon an hour after taking the first trial intake under observation (methylphenidate is a controlled substance here in Italy).

It was a strange, and almost disturbing, experience to feel my brain acting differently. Recall was smoother. Free association on a topic easier because my brain stayed on that topic, without veering away onto side lines that I needed to filter out from what I was saying. My thoughts were still my own, but with... less in the way.

You see: trying to do stuff (and by stuff I mean pretty much anything that you need to choose to do, rather than that you happen to start because it distracted you...) with ADHD is hard. I didn't realize how hard until some of that effort was lifted.

The closest I've come to being able to describe it is that having ADHD is like your brain wearing an ancient near eastern tunic to work a farm.

Ever hear the phrase "gird your loins"? It's the process of tying up your tunic (designed primarily to keep you cool) so that you can run, or fight, or carry out hard physical labour at ground level without the 'skirt' of the tunic getting in the way and tripping you up.

My brain wears a tunic: I need to put effort into preparing to do things before I can even start doing them. So it takes energy and effort just to get ready to start. And if you make a mistake in the girding, or the knot slips? Well, now you're half way through your task with a bunch of cloth swishing around your legs and getting in the way.

Methylphenidate is the equivalent of putting on jeans. You can be casual still, but you can also just... do stuff? Finish your morning coffee, look across the kitchen, and go: "I need to do the washing up."

This morning, I did the washing up.

Mavnn's blog

@blog · last month

⁂ Article

TypeScript Enums and Serialization

Read this post in its full formatted glory at https://blog.mavnn.eu/2022/11/24/typescript_enums_and_serialization.html

In general, TypeScript is not its own language - it's a set of annotations that can be added to JavaScript to help check the "correctness" of you program. The authors have been very reluctant to add features to TypeScript that don't exist in JavaScript, and so normally you can turn your TypeScript into JavaScript purely by deleting the type annotations that you've added.

Enums, though, are a bit different. They actually generate JavaScript code based on the TypeScript you write. Today, we're going to look at a piece of code that allows you to deserialize enums with string values in a type safe manner. And we're going to take advantage of the fact that enums (according to the TypeScript compiler) are both a type, and a value with a different type - at the same time.

For context, we're going to be using SchemaWax to create our decoder, so we can build it into a larger contextual decoder as needed.

First: the code! If you already know SchemaWax, you don't care about types, and you're here because it was a hit for "deserialize any enum" on Google this is the bit to cut and paste.

import * as D from "schemawax"

// This is only type safe if passed a Enum with string values.
// I don't think there's anyway to stop someone passing { "boo": "broken" }
// in TypeScripts type system :(
// At least this stops us from rewriting the same unsafe code every time though.
export const stringEnumDecoder = <Enum extends { [name: string]: string }>(
targetEnum: Enum,
): D.Decoder<Enum[keyof Enum]> => D.literalUnion(...Object.values(targetEnum)) as D.Decoder<Enum[keyof Enum]>

That's it. The whole thing. How do you use it?

Like this:

import * as D from "schemawax"
import { stringEnumDecoder } from "./enum"

enum TestEnum1 {
"why" = "would",
"anyone" = "do",
"this" = "!",
}

type ObjectWithEnumField = {
testEnum: TestEnum1
name: string
age?: number
}

describe("stringEnumDecoder", () => {
it("decodes string enums", () => {
const result = stringEnumDecoder(TestEnum1).forceDecode("!")
expect(result).toEqual(TestEnum1.this)
})
it("rejects invalid enum values", () => {
const result = stringEnumDecoder(TestEnum1).decode("this")
expect(result).toBeNull()
})

it("can be used in larger decoders", () => {
const objectDecoder: D.Decoder<ObjectWithEnumField> = D.object({
required: {
testEnum: stringEnumDecoder(TestEnum1),
name: D.string,
},
optional: {
dateOfBirth: D.string.andThen((str) => new Date(str)),
},
})

const inputFromApi = `{ "testEnum": "!", "name": "bob", "dateOfBirth": "2022-11-24"}`
const result1 = objectDecoder.decode(JSON.parse(inputFromApi))
expect(result1).toEqual({ testEnum: TestEnum1.this, name: "bob", dateOfBirth: new Date("2022-11-24") })
})
})

How does this work? How can we write a function that can take an enum type as an argument, and then generate a decoder? (Feel free to drop out if you were just here to solve your immediate problem!)

If you type an enum into the online TypeScript playground (here's one I prepared earlier), you'll see that the enum (with string values) is, in fact, compiled into a variable that ends up with a simple record with string keys and values attached to it.

Going back to the implementation, you'll see that's exactly the constraint on the argument we pass into stringEnumDecoder.

...
export const stringEnumDecoder = <Enum extends { [name: string]: string }>(... rest of implementation)

Then some slightly weird magic happens: when you pass an enum into the function, the TypeScript compiler infers that the type of the argument is the typeof the enum you passed in. Whatever is happening internally here, it keeps track of the fact that the keys of this type are the types of the valid enum cases, so it turns Enum[keyof Enum] into the union type of each of the possible enum value types which is, if you squint hard enough, actually the enum itself. We then return a decoder that accepts a string, checks that said string is actually one of the values stored in the enum object, and then tells the compiler that this decoder will only ever return valid enum values. Unfortunately with a cast - but the full context we need to check this cast is valid is contained within this one line of code.

So there you have it: a safe way to deserialize strings into enums, and it even composes nicely into more complex decoders.

Until next time!

Want to comment on something you've read here? This mastodon post is the official commenting point!

Mavnn's blog

@blog · last month

⁂ Article

Writing CVs for more senior roles

Read this post in its full formatted glory at https://blog.mavnn.eu/2024/01/26/writing_a_cv.html

A while back (checks notes, gulps) I wrote a fairly successful blog post on the types of CVs I liked receiving as one of the people screening technical applications, and some of the mistakes I was seeing applicants making.

What I didn't speak about at all was the "structure" of the CV; how to arrange it, and what sections to include/not include.

Today somebody asked me for an actual CV for the first time in... quite a while actually. The last couple of jobs both had their own interview process that didn't include one, so that means it's been at least 5 years.

Turns out that having been on the other side of the table a few more times now, and hiring for more senior candidates, my CV creation style has changed radically. The result is four broad categories of ways I've been effective in previous jobs, with a brief description of when I became senior enough to start doing that. So rather than having a big timeline of work history and education, I end up with things like:

Training and mentoring

For over a decade I have provided mentoring and training both to team members and as a service offered. This has ranged from people learning to code for the first time (CodeInstitute), to week long courses teaching professional developers new programming languages or architectural styles (@mavnn ltd), to giving talks at conferences on topics from the obscure to the philosophical (SDDConf, NDC, F# Exchange, Lambda Days, etc).

Apart from formal training I have mentored teams several times during the introduction of new programming languages, libraries, and techniques (15below, NoRedInk, Blissfully/Vendr).

Again - your mileage may vary; it's not like I've had any feed back on the application yet, or even that a single response tells you much about how the CV be received in general. But I can tell you that from the other side of the table that I'm much more interested in what you think are the areas you've made a difference, or that you're proud of, than I am in the job descriptions of your last 5 posts and where you went to secondary school.

One slight caveat: I did include my LinkedIn profile, which has all the gritty dates and things. It just wasn't what I chose to highlight in the part of the process that I can control. Your CV is your chance to control the narrative - take it.

Mavnn's blog

@blog · last month

Read this post in its full formatted glory at https://blog.mavnn.eu/2024/01/29/short_term_help.html

These days I generally work longer term contracts, which means I'm not often available for the more immediate "pay money for a solved problem" services I could offer while I was consulting. Right now though, I'm between long term contracts.

"But Michael," I hear you say, "what problems can I give you money to solve so that I can avoid distracting my own amazing team from actually building the product?"

I'm so glad you asked. Or, you know, you can just skip straight to the logistics section if you already know what you want.

21.1. Consulting

21.1.1. Build, packaging, and continuous integration

I have spent a lot of time getting build, test, and deployment pipelines up and running. Most of the advice out there assumes that you are using one technology and you can just use "the build tool" for that stack. Reality tends to be more complicated than that, with many projects involving multiple languages, code generation, and extensive test set up.

What kind of things could your CI/CD process do for you? It depends on your needs, but things that have really helped in other places include:

Making sure that CI/CD is managed in the code repository so that running the build locally and on the build server does the same thing in the same way, and the build can evolve in a safe, version controlled way just like the rest of your code
Helping trace and encode the real dependencies in your code base to unlock incremental, cachable build steps and reduce overall build times with concurrency
Split your test suite so tests can be run in parallel (yes, even integration tests) and then aggregate the results
Use tools like Nix or multi-step docker/podman builds to create minimal containers that only contain what they really need
- bonus extra: doing this with Nix also gives you development environments as code and reproducible deployment artifacts - same code in, same container out

If this is a new product/project and you just want someone to make all these considerations go away I can also build you a project skeleton with everything set up and ready to go for your preferred CI provider and deployment environment.

21.1.2. Architecture review

Putting together a new project, or have a code base that's moving from "minimum viable" to "oh - I've got customers"? I can review your plans, or, given your constraints and objectives I can put together a suggested system architecture for you.

It's worth noting that I don't have a personal axe to grind here. I won't tell you to use a "clean" architecture because that's my thing, or to use microservices because they are fashionable. Different architectural styles exist for a reason, and each has its own trade offs in terms of constraints you choose to accept in order to gain certain benefits.

I have the advantage of having helped architect and design solutions in a variety of styles in production environments.

This is a bit of a hybrid service that includes aspects of technology evaluation and code audit with a splash of domain driven design by example (so that I understand what you're building) - but zoomed out to look at "how do I put all this together."

21.1.3. Code audit

For ecosystems I've built decent sized projects in (.NET, TypeScript) I can spend some time reviewing your code and pointing out things you may want to improve.

This isn't the kind of code review you'd do on an individual PR: this is the kind of code review where I can (as an outsider) come in with fresh eyes and point out broader patterns in your code base that may be problematic. I can also help you take your conventions and "traditions" and turn them into a coding style guide with (in many cases) automated tooling to help the team put it into practice.

21.1.4. Technology evaluation

Considering buying a new service, picking up a new programming language, or changing to a new database library? I can do the research and evaluation you need based on your requirements. I've been helping drive technology choices in organizations for well over a decade now, and I can help you spot the good, the bad, and the ugly of the options you're considering. I may even be aware of options you haven't considered.

21.2. Workshops and training

Unlike more general consultancy, workshops on topics I know well such as the ones below are a fairly fixed commitment. If you're considering using your training budget, you can assume around 2500 euros/day for up to 6 people online. In person will increase the cost but allows for groups of up to 10 people.

I have also offered bespoke training courses in the past (examples: giving a team of Ruby developers a 5 day crash course in everything they needed to know to take over maintenance of a .NET code base, tailored to the project in question) but that requires significant preparation and a quote.

21.2.1. Domain driven design coaching

At its heart, the promise of domain driven design is simple: a code base that uses the same language as the people using it do, so that developers and domain experts can accurately share understanding of what the code should do and why.

Actually doing domain driven design is not simple at all, because it is a process to help you model reality and it turns out reality has a surprising amount of detail.

I can help with the process of getting started with DDD, help lead the early exploratory meetings between developers and domain experts, and give advice on how to capture what you discover in code while keeping everything maintainable.

21.2.2. Event sourcing

Event sourcing is a technique for capturing all the events that "have happened" and using those to calculate the current state of your system.

For example, if a customer of yours moves you may publish a CustomerHasMoved event when they tell you, and a CustomerAddressHasChanged event when you have finished the business process that manages customers moving.

This has enormous benefits for auditing, for being able to look at how the system has changed over time, and for being able to fix bugs "retroactively" as you don't only have the current state of the system but also all of the steps that got you here.

It also requires a slightly different way of thinking about your code base and some specific tooling to avoid a system that slows down over time. And it affects how you think about business constraints like data retention and the right to erasure.

As the saying goes: been there, done that. I can help you do it too.

21.2.3. Teach property based testing

I'm a huge fan of property based testing, and I'm more than happy to give interactive workshops on getting started with it in .NET, TypeScript, and probably other languages if you ask nicely. Why pay for this when you could download a conference talk about it for free (including ones I've given myself)? Because I'll use a piece of your code to get started with you will walk away with an up and running example in your code base. This will keep us focused on the reality of doing property based testing in practice rather than seeing the nice, easy, examples you tend to be shown in a 45 minute talk.

21.3. Bespoke software creation

21.3.1. Build a tool/library

I do just write good code as well. If you need a self contained library or a small solution built, I can do that for you. Whether it is parsing an obscure data format, efficient immutable directed graph data structures, or just a nice F# wrapper around a dotnet library, I will make sure it fits the style you're asking for and is well tested. Significant discounts apply if the results are going to be released under an open source licence.

21.3.2. Build a project skeleton

If you're starting a green field project, I can create a "skeleton" repository with a managed developer environment, CI/CD and testing story set up and ready to use. You and your team get to start with actually writing your product.

21.4. Logistics

Let's cover the basics. I don't want us to waste time, so I'm going to try and keep this as straight forward as possible:

I will always want to have an extensive conversation(s) and will normally want to provide a quote before starting a short term piece of work. Book a slot to talk on Calendly or just send me an email (michael at mavnn.eu)
I currently live in Italy, about an hour away from Rome. I can offer all of the services above remotely. Asking me to attend in person will add travel costs and at least 2 billable days of my time.
You can hire me by the day, but in general for short term work I quote and then charge you for the work delivered rather than bill by unit time. I will consider discounts for non-profits, student organizations, etc. It it's easier for you, I can give a quote that includes all expenses rather than reclaiming them separately. (Hint: if you're in a large organization and this is the first time you're arranging to get a consultant in - this will be easier for you)
- I am VAT registered in the EU
In the rare occasion where it turns out that I cannot deliver what I promised (I'm just one human - things like illness can happen) I will let you know promptly, and before the work is due to be delivered, so we can renegotiate where to go from the reality of the situation.

That's about everything, I think.

Mavnn's blog

@blog · last month

Read this post in its full formatted glory at https://blog.mavnn.eu/2024/01/31/dev-journal-1.html

This is something a little bit new. A series I'm starting that documents the building of a simple project from the ground up using a set of tools and techniques I've come to either really like, or that I'd like to try out.

On the one hand this is a personal project. On the other, I'd like to take advantage of nice things like CI/CD, testing, etc, even when I'm working on something for myself. So this is also a mini-tour of many of the things I would do setting up a new greenfield project for a team.

As the series progresses, I'll carry on adding the sections here.

The series so far

Foundations: Build and package
Scaffolding: Testing and consistency
Does it run?: Make sure the docker container is valid and stays valid
Log in, log out (and part 2): Adding the database and the ability to log into our web site
Internal quality review: making it easier to make correct changes to our code
With style: Adding style and interactivity with server side HTML

20.0.1. Part 1: Foundations

Our application will eventually be a little web site for redacted in case I change my mind. I'm going to be using mix of tried and new tech (for me personally).

On the things I'd like to try front, we have:

htmx (probably with bulma for initial styling) to provide the UI. This isn't going to be hugely interactive application, it is mostly going to collect information from forms, and display nice looking output tables so htmx's server side rendering model seems a perfect fit. I've used server side rendering in other projects and liked it, and htmx seems a low impact way to take that to the next level.
falco for writing the backend server in F#. Freya, my webserver of choice for F# back in the day, is no longer actively maintained but it looks like Falco has taken some of its nicer features and done its own thing with them.

On the technologies I've used before and found useful front, we have:

nix to give a version controlled build/development environments and reproducible packaging.
direnv for seamless local development environments.
marten from the "Critter Stack" as an event store on top of postgresql to build our datastore.
gitlab for code repository, container registry and CI/CD pipeline.

I'm not sure how far I'm going to take this experiment publicly, but what I'm going to focus on first is just the basics of any online app: people being able to sign up, log in, and manage an account for a paid service. At least that far the whole project will be MIT licensed, so if you like what you see you can just pick it up and use it as a starter template for your own project.

For today, let's start with a minimum deployable product: a "Hello world" Falco server with CI/CD pipeline in place. We'll have a gitlab hosted project anybody with a working nix environment can pull down and:

run nix run and have a webserver running locally that will respond to get requests to / with "Hello world"
run nix build .#dockerImage to build a docker image with the same architecture they're using (i.e. aarch64-darwin if you run it on a Mac)
by pushing a commit to gitlab trigger a CI pipeline building said docker image for x86_64-linux and pushing it to a package registry ready to deploy

Enough bullet points. What did I actually do? (Sneak preview: browse the gitlab repo at the time of the commit that this post describes)

Setup a nix flake to provide our environment

A nix "flake" is a declarative description of a set of packages we'd like to be able to reference. You can read the whole file but the important part for today is that our flake.nix file specifies three outputs in this stanza:

# Tools we want available during development
devShells.default = pkgs.mkShell {
  buildInputs = [ dnc.sdk_8_0 pkgs.nixfmt pkgs.skopeo ];
};

# Default result of running `nix build` with this
# flake; it builds the F# project `CalDance.fsproj`
packages.default = pkgs.buildDotnetModule {
  pname = name;
  version = "0.1";

  src = ./.;
  projectFile = "CalDance.fsproj";
  nugetDeps = nugets;

  # We set nix to create an output that contains
  # everything needed, rather than depending
  # on the dotnet runtime
  selfContainedBuild = true;

  # This is a webserver, and it complains if it
  # has no access to openssl
  runtimeDeps = [ pkgs.openssl pkgs.cacert ];

  dotnet-sdk = dnc.sdk_8_0;
  dotnet-runtime = dnc.runtime_8_0;
  executables = [ "CalDance" ];
};

# A target that builds a fully self-contained docker
# file with the project above
packages.dockerImage = pkgs.dockerTools.buildImage {
  name = name;
  config = {
    # asp.net likes a writable /tmp directory
    Cmd = pkgs.writeShellScript "runServer" ''
      ${pkgs.coreutils}/bin/mkdir -p /tmp
      ${pkgs.coreutils}/bin/mount -t tmpfs tmp /tmp
      ${packages.default}/bin/CalDance.Server
    '';
    Env =
      [ "DOTNET_EnableDiagnostics=0" "ASPNETCORE_URLS=http://+:5001" ];
    ExposedPorts = { "5001/tcp" = { }; };
  };
};

First we say we want a shell environment which includes the dotnet core SDK (version 8), nixfmt (for formatting nix files), and skopeo which we can use for moving docker images around.

Then we define the default output for this flake: it uses the buildDotnetModule to specify that in our case it should build the executable CalDance based on the F# project file CalDance.fsproj. A helper makes sure that Nix is aware of which nuget packages the project has referenced, so that they can be packaged correctly.

Finally, we define the dockerImage which uses the dockerTools.buildImage helper to say we want to be able to build a docker image that contains the executable from the default package above, everything it needs to run and nothing else at all. In our case, this produces a docker image weighing in at around 80MB - similar to what you'd get optimising a two step hand crafted dockerfile, and significantly smaller than using the official Microsoft ASP.NET runtime image.

direnv
Direnv is a tool that can add environment variables to your shell when you enter a directory. It also, conveniently, knows about Nix flakes.

We add a .envrc file to our project with the contents:
```
#!/usr/bin/env bash
# the shebang is ignored, but nice for editors
use flake
```
Next time we move into this directory, direnv will ask us to allow this .envrc file. If we accept, our normal local shell will have everything specified in the devShell above added to its path. This means we can, for example, use the dotnet command and we will use the version specified in flake.nix even if we haven't installed a system wide version of dotnet at all.
The F# project
There's absolutely nothing special about this at all. I just created an F# project with dotnet on the command line, moved Program.fs into a sub directory called src because I prefer it that way, and then added a package dependency on Falco using dotnet add package Falco.

Replace the contents of Program.fs with:
```
module Mavnn.CalDance.Server

open Falco
open Falco.Routing
open Falco.HostBuilder

webHost [||] {
    endpoints [
        get "/" (Response.ofPlainText "Hello World")
    ]
}
```
Set up the CI pipeline
Having used Nix for our development environment, our CI pipeline becomes exceedingly straight forward. All we need is a build container with Nix available and we have all the other information we need for the build already. Nix themselves provide a nixos/nix image (Nix is the package manager, NixOS is the linux distribution that uses Nix as its package manager) so we'll just use that.

There's a little bit of boilerplate to tell nix that we want to allow flakes and to allow connection to the gitlab package registry. Once that is done, we log into the registry for this project using the CI provided environment variables, run nix build .#dockerImage and then push the results up to the registry.
```
build-container:
  image:
    name: "nixos/nix:2.19.3"
  variables:
    IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
  before_script:
    - nix-env --install --attr nixpkgs.skopeo
  script:
    - mkdir -p "$HOME/.config/nix"
    - echo 'experimental-features = nix-command flakes' > "$HOME/.config/nix/nix.conf"
    - mkdir -p "/etc/containers/"
    - echo '{"default":[{"type":"insecureAcceptAnything"}]}' > /etc/containers/policy.json
    - skopeo login --username "$CI_REGISTRY_USER" --password "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
    - 'nix build .#dockerImage'
    - ls -lh ./result
    - 'skopeo inspect docker-archive://$(readlink -f ./result)'
    - 'skopeo copy docker-archive://$(readlink -f ./result) docker://$IMAGE_TAG'
```
It's worth noting here that Nix is a deterministic build system (for example, stripping dates from compiled metadata so building the same source code on a different day doesn't product a different binary). In a "real life" context I would be caching the results of the nix build steps to a service like Cachix so that they could be reused between builds, which becomes increasingly useful as the project grows and starts to be comprised of multiple build steps (Nix will be able to cache each "step" individually, even if you only ask for the final outcome of the process).
Wrapping it all up

Not a bad first days work, I'd say. Our project is already at a stage that we can work on it with standard .NET tooling (for instance, adding a new nuget package with dotnet package add ... will automatically flow through to that package being added to the docker image) and CI will produce on push a lean deployable artifact. Versions of everything we are using from the .NET SDK to the nuget package we're depending on are fixed across all environments, and we have a nice place to add more developer tooling as we move forwards - for example standardizing the version of postgresql that will be used during development and in CI.

As a bonus extra, anybody with nix installed can build and run the project without having to know .NET or have any .NET tooling installed; a very nice feature when you have others depending on your work who might want to run your code locally, but may not have chosen the same tech stack.
Feedback? Comments?

Have questions? Comments? Hate something, love something, know a better way of doing something? Drop an issue on the repository at https://gitlab.com/mavnn/caldance and let me know. I'll be pointing a tag at the commit referenced by each blog post, so I can always branch off and include your ideas in a future revision!
Next

Part 2 adds unit tests and consistent formatting to the project.

Mavnn's blog

@blog · last month

Read this post in its full formatted glory at https://blog.mavnn.eu/2024/02/06/dev-journal-2.html

This post is part of the "Dev Journal" series. Part 1 contains the series index, while the DevJournal2 tag for the CalDance project in GitLab holds the state of the repository as described here.

After the initial set up work that builds our project and packages it for deployment done, it looked might it could be time to write some code. Given we're planning to use htmx, we're going to be spending a lot of time constructing urls to inject into our site that need to match end points on the server so a good starting point seemed to be building a set of helpers for defining "bidirectional routing".

Adding the Routing.fs file to the F# project went exactly as you'd expect. We'll come back to this code when we test it properly, but to give you an idea we then updated the main server to actually start returning some HTML. The new Program.fs file new looks like this:

module Mavnn.CalDance.Server

open Falco.HostBuilder
open Falco.Markup
open Mavnn.CalDance.Routing
open Mavnn.CalDance.Routing.Operators

let greetingRoute =
  literalSection "greetings/" ./+ stringSection "name"

let indexRoute = literalSection "/"

let indexEndpoint =
  htmxGet indexRoute (fun () _ ->
    Elem.html
      []
      [ Elem.body
          []
          [ Elem.h1 [] [ Text.raw "Hi!" ]
            Elem.p
              []
              [ Text.raw "Would you like to "
                htmxLink greetingRoute "Bob" "greet Bob?" ] ] ])

let greetingEndpoint =
  htmxGet greetingRoute (fun name _ ->
    Elem.html
      []
      [ Elem.body
          []
          [ Elem.h1 [] [ Text.rawf "Hi %s!" name ] ] ])

webHost [||] {
  add_antiforgery
  endpoints [ indexEndpoint; greetingEndpoint ]
}

We now have two routes, one which starts with greetings/ and then matches any string, and one which responds at /. You can see in index end point we use our new htmxLink helper to construct a link that will be matched by the greeting end point, and in the greeting end point we supply a handler that knows it is going to receive a string.

This is all type safe, and that's lovely and all... but now we have two problems.

Let's tackle the biggest problem first!

19.0.1. Clarity and style

Writing lists of lists is a succinct and powerful way of representing HTML, but it is also a pain in the backside to format nicely by hand. It's also very easy to bike shed about, leading to a lot of wasted time and churn in commits.

One of the best solutions to this is to automate code formatting following a reasonable style guide. This is especially important at the beginning of a project, or (ahem) when writing code you'd like people to follow as an example as it means all of the changes made to the project are because something meaningful has actually changed and there is a consistent style to follow along with.

Fantomas is the code formatter generally used by the F# community. We always want everyone to be using the same version and config, so let's build it into our nix configuration. The nix files we use to structure the set up of the repository are a programming language in their own right, so we can write a function to provide the correct version of Fantomas taking the version of the dotnet runtime as an input argument (we've put this in a separate file in the nix directory to keep things neat).

{ pkgs, dnc }:
let version = "6.2.3";
in pkgs.stdenv.mkDerivation {
  pname = "fantomas";
  version = version;
  nativeBuildInputs = with pkgs; [ unzip makeWrapper ];
  src = pkgs.fetchurl {
    url = "https://globalcdn.nuget.org/packages/fantomas.${version}.nupkg";
    hash = "sha256-Aol10o5Q7l8s6SdX0smVdi3ec2IgAx+gMksAMjXhIfU=";
  };
  unpackPhase = ''
    ls -al $src
    unzip "$src" -d $out
  '';
  installPhase = ''
    mkdir -p $out/bin
    cp -r * $out/bin
    echo '#! ${pkgs.bash}/bin/bash -e' > $out/bin/fantomas
    echo "FANTOMAS_PATH=$out/tools/net6.0/any/fantomas.dll" >> $out/bin/fantomas
    echo '${dnc.runtime_8_0}/bin/dotnet $FANTOMAS_PATH "$@"' >> $out/bin/fantomas
    chmod +x $out/bin/fantomas
  '';
}

This basically says that we want to download a particular version of Fantomas from nuget (the dotnet package library), unzip it, and then create a shell script that uses our dotnet core runtime to run it. This works because Fantomas is built using an "any CPU" build configuration, allowing us to supply the correct runtime as needed by the system we're currently using but still executing the same compiled dotnet code. For a package that included any CPU specific code the normal nix approach is to download the source and then build it ourselves.

Because we put the shell script in the bin directory of the output of this derivation (how nix refers to the definition of an enclosed package), this will be added to the path of any nix shell definition that depends on it. To make people's lives easier, we can also wrap it for common use cases which we do here to create the format-all and format-stdin commands.

In our top level flake.nix file we can now import these tools and expose them to our developers:

let
  # ... snip ...
  fantomas = (import ./nix/fantomas.nix) { inherit pkgs dnc; };
  format-all = (import ./nix/format-all.nix) { inherit pkgs fantomas; };
  format-stdin =
    (import ./nix/format-stdin.nix) { inherit pkgs fantomas; };
  # ... snip ...
in rec {
  # Tools we want available during development
  devShells.default = pkgs.mkShell {
    buildInputs = [
      dnc.sdk_8_0
      pkgs.nixfmt
      pkgs.skopeo
      fantomas
      format-all
      format-stdin
    ];
  };
  # ... snip ...
}

Now everybody has the same formatting tools available and an easy way to reference them. It even allows us to provide git hooks and/or attribute filters that users can choose to activate that will prevent unformatted code from being pushed or even format it as it is committed to the repository (check out the section on smudge and clean filters here if you're interested).

I'm normally quite keen on leaving the formatter settings on their default, but given the purpose of this particular repository I've also added a .editorconfig file to the repository to adjust the indentation to two spaces rather than the default four, and to reduce the aimed for line length to 60 characters to make it easier to read in the blog posts.

19.0.2. Testing (local)

Nearly as importantly as the code being readable is whether it actually works. Expecto is an F# unit test library that allows you to write executable test programs and defines tests as pieces of data rather than class methods with particular attributes. This can be insanely helpful in writing parameterized tests, which we'll get back to in a later post.

Right now though, we just want the tests to exist and be run in CI.

We'll start off by moving the existing server code into a directory called (... let the suspense build ...) Server. Next to it we'll create an F# console project called Server.Test and use dotnet add package to add Expecto, along with YoloDev.Expecto.TestSdk and Microsoft.NET.Test.Sdk which allow the project to also be run by calling dotnet test so everybody's editors know how to run the Expecto tests.

Finally, we add a project reference to Server from Server.Test and locally at least we're all set for running unit tests!

Let's add one to Program.fs:

module Mavnn.CalDance.Server.Test

open Expecto

[<Tests>]
let tests =
  testList
    "My list"
    [ testCase "hello" (fun () ->
        Expect.equal
          "hello"
          "hello"
          "Is it me you're looking for?") ]

[<EntryPoint>]
let main args =
  // This allows running with different arguments from the command line,
  // as well as via `dotnet test`
  runTestsWithCLIArgs [] args tests

And then we can run it from the root of our project:

CalDance on  main via ❄️  impure (nix-shell)
❯ dotnet run --project  Server.Test
# snipped warning messages about FSharp.Core versions
[15:59:00 INF] EXPECTO? Running tests... <Expecto>
[15:59:00 INF] EXPECTO! 1 tests run in 00:00:00.0262215 for My list.hello – 1 passed, 0 ignored, 0 failed, 0 errored. Success! <Expecto>

CalDance on  main via ❄️  impure (nix-shell)
❯

The current version of Expecto hasn't been updated to the latest FSharp.Core yet but it appears to work fine so we'll just keep an eye on that for now.

19.0.3. Testing (CI)

Now though, we have a problem. The promise of using Nix was that we wouldn't need to configure CI with lots of setup for things likes tests because our build environment is self contained, and that we could incrementally and deterministically build our sub-components. But now we either create a single nix derivation that has both our projects in, or we need to somehow package the tests separately. We don't want to create a joint derivation because we're compiling down our server code into a self contained enclosure including its own copy of the dotnet runtime.

But we can't reference that build output directly from our test project, because it is built as a self contained enclosure but in the test project we want to reference it as a library in a different executable.

This is where we play some slightly interesting tricks to get all the properties we want. Do you remember above, where we put the output of the Fantomas derivation in the bin directory to declare that the file in question was an executable? Turns out that we can also put a file in the share directory to signify that it is available to other derivations but is not directly used by any executables in this one.

It also turns out that the way the F# helpers in nix manage incremental builds is by assuming that F# nix derivations will provide a Nuget package in the share directory. This means that we can build the server code once as a self-contained executable and put it in the bin folder, but we can also build it again without the self-contained flag and package it into the share folder by adding a hook to our derivation:

# ... snip ...
postInstall = ''
  ${dnc.sdk_8_0}/bin/dotnet \
      pack \
      -p:ContinuousIntegrationBuild=true \
      -p:Deterministic=true \
      --output "$out/share" \
      --configuration "Release"
'';
# ... snip ...

We'll move the derivation into its own file while we're at it to stop the main flake.nix file getting too confusing and noisy, and start passing in things like the dotnet core version and project name as variables to make it easier to keeps changes between components in sync.

Aside: there is actually a helpful boolean flag that can be used to pack F# libraries but it fairly reasonably complains if you try and package a self-contained build.

This in turn allows us to define a derivation for the test project which looks very similar to the server derivation, just that it takes to server derivation as an argument so that it can declare a project reference on it along with all the previous arguments.

Quirk alert: this works very, very, well giving us cached incremental builds but it does also require us to add a conditional package dependency on the server to our test project for the build to complete successfully under Nix. This means you end up with a project file that contains something like:

<ItemGroup>
  <ProjectReference Include="..\Server\CalDance.Server.fsproj" />
  <PackageReference Include="CalDance.Server" Version="*" Condition=" '$(ContinuousIntegrationBuild)'=='true' " />
</ItemGroup>

To finish off our test setup, we add a new output to our flake file - a request for a JUnit formatted xml file containing our test results.

packages.test = pkgs.stdenv.mkDerivation {
  name = "${baseName}.TestResults";
  version = version;
  unpackPhase = "true";

  installPhase = ''
    ${testExecutable}/bin/CalDance.Server.Test --junit-summary $out/server.test.junit.xml
  '';
};

Now we can run nix build .#test in our root directory and we will get a result directory containing the test results (which will be cached unless the code of either the server or the test project changes).

Some boiler plate additions to the GitLab CI configuration finishes things off; we tell the build to build both .#dockerImage and .#test (which nix will happily build run in parallel for us) and then copy the test results to a folder in the actual build directory which we tell GitLab contains junit xml results. This is needed because the result-1 directory they are created in is a symlink to the a hash addressable store that nix uses, and it turns out GitLab's build artifact upload mechanism can't follow the symlink.

# Nothing before the build command in the script has changed since the previous post
  - 'nix build .#dockerImage .#test'
  - mkdir testResults
  - 'cp result-1/* testResults'
  - ls -lh ./result
  - 'skopeo inspect docker-archive://$(readlink -f ./result)'
  - 'skopeo copy docker-archive://$(readlink -f ./result) docker://$IMAGE_TAG'
artifacts:
  when: always
  paths:
    - 'testResults/*.xml'
  reports:
    junit: 'testResults/*.xml'

19.0.4. Wrapping it all up

That seems like a nice breaking off point for now. In this next stage we have:

Provided shared versions of formatting tools to help keep the code base consistent
Added a test project to allow us to unit test our code
Updated CI to run and report on those tests
Created a standard pattern for being able to add more F# projects to our repository which will all be built deterministically and for which the build results can be independently cached

As always, if you have questions or comments on what's happened so far then leave an issue on the CalDance GitLab repository. And as a thank you note for reading this far (and to see if anyone actually is!) we now have a bonus "choose your own adventure" poll.

If you'd like to see the next post focusing on testing the code we already have, hit the thumbs up on this issue.

If you'd like to see the next post starting to actually hook up a form and a data store, hit the thumbs up on this issue instead!

19.0.5. Next

Part 3 continues with an end to end test of our docker container.

Mavnn's blog

@blog · last month

Read this post in its full formatted glory at https://blog.mavnn.eu/2024/02/19/do-notation-for-typescript.html

This post is still here as an interesting deep dive into the mechanics of using TypeScript's type system, but if what you're really looking for is a production ready async/result/state monad for TypeScript I'd strongly recommend the Effect TS library rather than rolling your own - now I know it exists.

I've written a brief introduction here: A gentle introduction to Effect TS.

This is rather an aside from recent blog posts, but something I found interesting none the less.

Fair warning to start us off: this post assumes that you are aware of and understand "do notation" (or "computational expressions" or "monad syntax") and like the idea of having it available in TypeScript.

It starts by working through a possible way of implementing a type safe representation of a sequence of monadic operations that has a much nicer user experience than nested continuation functions, and then leads into a lengthy example of both building and showing how to use a monad which I've found very useful when working in TypeScript for handling asynchronous code that needs to meaningfully respond to both successes and failures.

The idea is that we're going to go from code that looks like this:

export const processLaxCallback = ({
  laxOperations,
  commands,
  localFunctions,
}: LaxCallbackDependencies) => async (httpRequest) => {
  try {
    const laxSignatureCheck = await laxOperations.checkSignature(httpRequest)
    if(isFailure(signature)) {
      await reportError(signature)
      return
    }
    const laxContext = laxOperations.parseRequest({ httpRequest, laxSignatureCheck })
    if(isFailure(laxContext)) {
      await reportError(laxContext)
      return
    }
    // ...continued
  } catch (e) {
    // ... etc
  }
}

...to code that looks more like this:

export const processLaxCallback = ({
  laxOperations,
  commands,
  localFunctions,
}: LaxCallbackDependencies) =>
  SolidChain.start<{ httpRequest: HttpRequest }, LaxCallBackState>()
    .chain("laxSignatureCheck", laxOperations.checkSignature)
    .chain("laxContext", laxOperations.parseRequest)
    // ...continued

If you're impatient you can jump straight to appendix 2 where you will find a cut and pastable code block with everything you need to play with the code in the TypeScript editor of your choice.

For the avoidance of any doubt, all the code in this blog post is available for re-use under the MIT license as list in appendix 3.

18.0.1. The idea

TypeScript has one form of monad notation already - the await keyword. Unfortunately, there isn't any way to plug into the mechanism used and define your own alternative bind implementation without doing something dangerously hacky. And, frankly, the last thing your TypeScript code needs is an other sharp edge to cut yourself on.

But... what does binding a value in monad notation really do? It doesn't allow you to write code you couldn't have written anyway long hand. It allows you to give the result of a calculation in your code in name in the current scope.

So: if we consider the fact that a scope is really just a mapping from names to values, and that TypeScript allows function inputs to alter the type of their output... maybe we can do something with that?

18.0.2. Defining a scope

A type that maps names to values is reasonably easy to define in TypeScript. It looks something like this:

export type Scope<Keys extends string> = {
  [K in Keys]: any;
};

We can say that anything we're willing to consider as a scope is a type that extends the type above: it will have some keys, which will all be strings, and they will map to some values, which will all be sub types of any.

Now we need a type safe way to add a value to the scope.

We start with a calculated type which works out what the result of adding a value with a name to a scope should be:

export type ExtendedScope<
  OldScope extends Scope<any>,
  NewField extends string,
  NewValue
> = OldScope extends any
  ? {
      [K in keyof OldScope | NewField]: K extends NewField
        ? NewValue
        : K extends keyof OldScope
        ? OldScope[K]
        : never;
    }
  : never;

...doesn't OldScope always extend any?

Well, yes. But it turns out that wrapping the calculated type in a check (even one which is always true) forces tsc to calculate what the resulting type should be.

This makes no difference to what code tsc considers correct, but a big difference to how it shows it in an editor; instead of:

ExtendedScope<ExtendedScope<{ aDate: DateTime }, "aNumber", number>, "aString", string>

...tool tips and error messages will show:

{
    aDate: DateTime,
    aNumber: number,
    aString: string
}

...which is a heck of a lot easier to work with.

This basically says we want a new type that has all the keys in the old scope and the new key, and the fields in the new context are the same type as the old context except the field that has the name NewField which will be of type NewValue.

Now we can write a wrapper function that actually does the work at runtime:

export const extendScope = <
  OldScope extends Scope<any>,
  NewField extends string,
  NewValue
>(
  oldScope: OldScope,
  newField: NewField,
  newValue: NewValue
) => {
  const addToScope = {
    [newField]: newValue,
  };
  return {
    ...oldScope,
    ...addToScope,
  } as ExtendedScope<OldScope, NewField, NewValue>;
};

You may be wondering why we bothered with the type definition above given that tsc will try and infer the type of a "splat" like the one we return above.

The short answer is: tsc infers it wrong.

The longer answer is: tsc infers it wrong when NewField is the same as an existing field name, but NewValue is different to the type of that field on OldContext.

tsc always infers the result of splatting two generic objects (A and B) as being A & B. But if you think about an example like this one:

type AString = { myField: string };
type ANumber = { myField: number };

const splat = <A, B>(a: A, b: B) => ({ ...a, ...b });

const result = splat<AString, ANumber>(
  { myField: "hello" },
  { myField: 10 },
);

You can see that tsc inferring the type of result as AString & ANumber is obviously incorrect. Interestingly, it works out correctly that it is ANumber if you create the splat function with fixed types known at compile time, but that doesn't help us much here.

This is all starting to look quite hopeful with us now having a representation of a scope, and a type safe way to add values to it.

18.0.3. Building an operation

The next question we need to answer is what is this going to be the scope of. Monad friendly syntax normally binds names in the scope of a function body, so let's generalize that idea slightly (and with a lot of hand waving) to the idea of the scope of an operation.

We want to be able to do two main things with this operation: we want to be able to add steps to it (using the scope accumulated so far), and we want to be able to execute it. The idea of building up an operation like this brings to mind the appropriately named "builder" pattern, where we use a class with some state to "build" up the thing we want. I'm going to call the "add step" method chain (because it feels a fairly intuitive name for what's happening) and the "execute" method execute (no reason needed). To keep the theme, we'll call the builder class a SomethingChain where something is a monad.

If such a builder class were to exist, it would allow us to write code like this:

export const monadTest = new MonadChain((name: string) =>
  Monad.pure({ initialInput: name }),
)
  .chain("punctuation", () => Monad.pure("!"))
  .chain("finalGreeting", (scope) =>
    Monad.pure(
      `Hello ${scope.initialInput}${scope.punctuation}`,
    ),
  ).execute;

The type of monadTest above is a function that takes a string, and returns a monad value of an object with three string fields: "initialInput", "punctuation", and "finalGreeting". As you can see, each step in the chain adds to or overwrites a value in the scope while leaving the rest of the scope available for use later.

The pattern of how we implement the builder for each type of monad is going to be pretty much the same (that's the point), but we can also play some neat tricks based on the specific monad we're implementing. The magic is in the chain method, which wraps a perfectly normal "bind" with a call to extendScope from above. Let's see the pattern first in its purest possible form by creating an identity monad chain, along with some comments in the chain method.

export type Monad<T> = T;

export namespace Monad {
  export const bind = <A, B>(
    prev: Monad<A>,
    func: (prev: A) => Monad<B>,
  ): Monad<B> => {
    return func(prev);
  };
  export const pure = <A,>(value: A): Monad<A> => value;
}

export class MonadChain<Input, OutputScope extends Scope<any>> {
  private readonly operation: (
    input: Input,
  ) => Monad<OutputScope>;
  constructor(
    starter: (input: Input) => Monad<OutputScope>,
  ) {
    this.operation = starter;
  }

  execute(input: Input): Monad<OutputScope> {
    return this.operation(input);
  }

  chain<NextOutput, ResultName extends string>(
    resultName: ResultName,
    next: (previous: OutputScope) => Monad<NextOutput>,
  ): MonadChain<
    Input,
    ExtendedScope<OutputScope, ResultName, NextOutput>
  > {
    // We need to build the operation to pass to
    // the constructor of the chain we're going
    // to return
    const chainedOperation = (
      input: Input,
    ): Monad<
      ExtendedScope<OutputScope, ResultName, NextOutput>
    > => {
      // Get the monadic value of the chain
      // up to this point.
      const previousResult = this.operation(input);
      return Monad.bind(
        previousResult,
        (output: OutputScope) => {
          // Use the output from the chain so far /twice/.
          // The first time to work out the new value that is
          // going to be added to the scope, and the second
          // time to as the starting scope passed to ~extendScope~
          return Monad.bind(next(output), (nextOutput) => {
            return Monad.pure(
              extendScope(output, resultName, nextOutput),
            );
          });
        },
      );
    };
    // Wrap the function back into the builder class
    // so we can carry on calling chain on it
    return new MonadChain(chainedOperation);
  }
}

18.0.4. Some working examples

Maybe

Let's start with the classics. Tried of handling nulls and undefined manually? Redefine our bind method and we're done: apart from changing the name, nothing else changes.

export type Maybe<T> = T | null | undefined;

export namespace Maybe {
  export const bind = <A, B>(
    prev: Maybe<A>,
    func: (prev: A) => Maybe<B>,
  ): Maybe<B> => {
    if(prev === null || prev === undefined) {
        return null;
    } else {
        return func(prev);
    }
  };
  export const pure = <A,>(value: A): Maybe<A> => value;
}

The rest of the code is behind the cut to avoid us being too repetitive.

 export class MaybeChain<Input, OutputScope extends Scope<any>> {
  private readonly operation: (
    input: Input,
  ) => Maybe<OutputScope>;
  constructor(
    starter: (input: Input) => Maybe<OutputScope>,
  ) {
    this.operation = starter;
  }

  execute(input: Input): Maybe<OutputScope> {
    return this.operation(input);
  }

  chain<NextOutput, ResultName extends string>(
    resultName: ResultName,
    next: (previous: OutputScope) => Maybe<NextOutput>,
  ): MaybeChain<
    Input,
    ExtendedScope<OutputScope, ResultName, NextOutput>
  > {
    const chainedOperation = (
      input: Input,
    ): Maybe<
      ExtendedScope<OutputScope, ResultName, NextOutput>
    > => {
      const previousResult = this.operation(input);
      return Maybe.bind(
        previousResult,
        (output: OutputScope) => {
          return Maybe.bind(next(output), (nextOutput) => {
            return Maybe.pure(
              extendScope(output, resultName, nextOutput),
            );
          });
        },
      );
    };
    return new MaybeChain(chainedOperation);
  }
}

export const maybeTest = new MaybeChain((name: string) =>
  Maybe.pure({ initialInput: name }),
)
  .chain("punctuation", () => Maybe.pure("!"))
  .chain("finalGreeting", (scope) =>
    Maybe.pure(
      `Hello ${scope.initialInput}${scope.punctuation}`,
    ),
  ).execute;

AsyncMaybe

Of course, TypeScript has fairly robust tools for handling null and undefined already. But they get pretty painfully verbose if you start needing to handle a lot of asynchronous calls. Chains to the rescue!

Our monad definition now looks like this:

export type AsyncMaybe<T> = Promise<T | null | undefined>;

export namespace AsyncMaybe {
  export const bind = async <A, B>(
    prevAsync: AsyncMaybe<A>,
    func: (prev: A) => AsyncMaybe<B>,
  ): AsyncMaybe<B> => {
    const prev = await prevAsync
    if(prev === null || prev === undefined) {
        return null;
    } else {
        return func(prev);
    }
  };
  export const pure = <A,>(value: A): AsyncMaybe<A> => Promise.resolve(value);
}

After a quick search and replace, we can now use our chain to start writing significantly clearer code (in my opinion, anyway!).

// An interface representing some external services
export interface MaybeData {
  getName: (userId: string) => Promise<string | null>;
  getPunctuation: (
    name: string,
  ) => Promise<string | undefined>;
}

// Without Chain
export const before = async ({
  userId,
  maybeData,
}: {
  userId: string;
  maybeData: MaybeData;
}) => {
  const name = await maybeData.getName(userId);
  if (name === null) {
    return null;
  }
  const punctuation = await maybeData.getPunctuation(name);
  if (punctuation === undefined) {
    return null;
  }
  return `Hello ${name}${punctuation}`;
};

// With Chain
export const after = new AsyncMaybeChain(
  AsyncMaybe.pure<{ userId: string; maybeData: MaybeData }>,
)
  .chain("name", (s) => s.maybeData.getName(s.userId))
  .chain("punctuation", (s) =>
    s.maybeData.getPunctuation(s.name),
  )
  .chain("result", (s) =>
    AsyncMaybe.pure(`${s.name}{s.punctuation}`),
  ).execute;

Nicer, but still not fully nice. The constructor looks a bit weird, it's annoying that we have to call AsyncMaybe.pure in the last step, and we're returning our entire internal scope at the end of every operation.

We can deal with each of these fairly easily though, because one thing the builder pattern is great at is providing an API for building things.

A static method gives us a more intuitive way of starting the chain:

export class AsyncMaybeChain<
  Input,
  OutputScope extends Scope<any>,
> {
  // ...snip rest of code...

  static start<
    InputScope extends Scope<any>,
  >(): AsyncMaybeChain<InputScope, InputScope> {
    return new AsyncMaybeChain(AsyncMaybe.pure<InputScope>);
  }
}

We can expose a map method on the chain to avoid having to manually wrap parts of the chain in pure:

 map<NextOutput, ResultName extends string>(
  resultName: ResultName,
  next: (previous: OutputScope) => NextOutput,
): AsyncMaybeChain<
  Input,
  ExtendedScope<OutputScope, ResultName, NextOutput>
> {
  return this.chain(resultName, (scope) =>
    AsyncMaybe.pure(next(scope)),
  );
}

And finally we can add an executeTarget method as an alternative to execute that returns only a single field from the scope.

executeTarget<ResultName extends keyof OutputScope>(resultName: ResultName) {
  return (input: Input) =>
    AsyncMaybe.bind(this.execute(input), (outputScope) =>
      AsyncMaybe.pure(outputScope[resultName])
    );
}

This allows us to change our code to be just that bit cleaner and clearer:

// With Chain
export const after = AsyncMaybeChain.start<{
  userId: string;
  maybeData: MaybeData;
}>()
  .chain("name", (s) => s.maybeData.getName(s.userId))
  .chain("punctuation", (s) =>
    s.maybeData.getPunctuation(s.name),
  )
  .map("result", (s) => `${s.name}{s.punctuation}`)
  .executeTarget("result");

The full code is here if you want to be able to see it all in context.

export type AsyncMaybe<T> = Promise<T | null | undefined>;

export namespace AsyncMaybe {
  export const bind = async <A, B>(
    prevAsync: AsyncMaybe<A>,
    func: (prev: A) => AsyncMaybe<B>,
  ): AsyncMaybe<B> => {
    const prev = await prevAsync;
    if (prev === null || prev === undefined) {
      return null;
    } else {
      return func(prev);
    }
  };
  export const pure = <A,>(value: A): AsyncMaybe<A> =>
    Promise.resolve(value);
}

export class AsyncMaybeChain<
  Input,
  OutputScope extends Scope<any>,
> {
  private readonly operation: (
    input: Input,
  ) => AsyncMaybe<OutputScope>;
  constructor(
    starter: (input: Input) => AsyncMaybe<OutputScope>,
  ) {
    this.operation = starter;
  }

  execute(input: Input): AsyncMaybe<OutputScope> {
    return this.operation(input);
  }

  chain<NextOutput, ResultName extends string>(
    resultName: ResultName,
    next: (previous: OutputScope) => AsyncMaybe<NextOutput>,
  ): AsyncMaybeChain<
    Input,
    ExtendedScope<OutputScope, ResultName, NextOutput>
  > {
    const chainedOperation = (
      input: Input,
    ): AsyncMaybe<
      ExtendedScope<OutputScope, ResultName, NextOutput>
    > => {
      const previousResult = this.operation(input);
      return AsyncMaybe.bind(
        previousResult,
        (output: OutputScope) => {
          return AsyncMaybe.bind(
            next(output),
            (nextOutput) => {
              return AsyncMaybe.pure(
                extendScope(output, resultName, nextOutput),
              );
            },
          );
        },
      );
    };
    return new AsyncMaybeChain(chainedOperation);
  }

  map<NextOutput, ResultName extends string>(
    resultName: ResultName,
    next: (previous: OutputScope) => NextOutput,
  ): AsyncMaybeChain<
    Input,
    ExtendedScope<OutputScope, ResultName, NextOutput>
  > {
    return this.chain(resultName, (scope) =>
      AsyncMaybe.pure(next(scope)),
    );
  }

  executeTarget<ResultName extends keyof OutputScope>(
    resultName: ResultName,
  ) {
    return (input: Input) =>
      AsyncMaybe.bind(
        this.execute(input),
        (outputScope) => outputScope[resultName],
      );
  }

  static start<
    InputScope extends Scope<any>,
  >(): AsyncMaybeChain<InputScope, InputScope> {
    return new AsyncMaybeChain(AsyncMaybe.pure<InputScope>);
  }
}

18.0.5. Diving deeper: handling errors with style and panache

For our last example we're going to both take things up a notch, and take a bit more advantage of TypeScript's type level programming.

We're going to create what I'm going to call, for brevity, the Solid monad. (Technically it's an asynchronous either state monad - mix and match order to taste - but that's a bit of a mouth full). This allows us to think about how to write our code in a slightly different way, separating out the logic of our "happy path" from error handling in a way that would be either very verbose or completely break type safety without some tooling like this builder.

Let's first look at the kind of use cases where this monad is useful. Imagine we've created an integration with the "Lax" messaging service, and now when a customer clicks a button in one of the messages we send out our code has to handle a call back from Lax. But we don't know anything about the incoming request initially. We don't know whether it actually comes from Lax, whether we can find the customer organization that the message was sent to, which user of Lax in that organization clicked the button, which user in our application that Lax user maps to...

This uncertainty means there's also numerous ways this process could go wrong. Maybe the message isn't actually from Lax (who cryptographically sign their callback payloads). Maybe our database is down. Or maybe Bob clicked the button 30 seconds after Fred did and you can't do that thing anymore. We also need to respond differently and to different people depending on what has failed.

To deal with this, each step in the process can either succeed or fail. What we want to do in the case of failure is often highly dependent on both what type of failure has occurred and what information we already have available. As such, it's common to see code that either returns a union type of Success | SemanticallyMeaningfulErrorType(s) or where each operation in turn is wrapped in try ... catch blocks to respond to exceptions in context.

Normally in TypeScript the resulting code will end up looking something like this:

export const withoutChain =
 ({ laxOperations, commands, localFunctions }: LaxCallbackDependencies) =>
 async (httpRequest: HttpRequest) => {
   const signatureOk = await laxOperations.checkSignature({ httpRequest });
   if (signatureOk.result.kind !== "success") {
     console.log("Error to internal logging service");
     return;
   }

   const laxContext = await laxOperations.parseRequest({
     laxSignatureCheck: signatureOk.result.value,
   });
   if (laxContext.result.kind !== "success") {
     console.log("Error to internal logging service");
     return;
   }

   const command = await commands.parseUntrustedCommand({
     untrustedCommand: laxContext.result.value.actionPayload,
   });
   if (command.result.kind !== "success") {
     console.log("Error to internal logging service");
     // Oh! We know how to contact the user now as well!
     await laxOperations.reply({
       laxContext: laxContext.result.value,
       reply: "A suitable error message" as any,
     });
     return;
   }

   // ... more code here ...
 };

This code isn't ideal. Admittedly, it has one big advantage: anyone who has written any TypeScript can immediately see how it works. But it also has a number of flaws. The most important one is that it is so verbose, and in such a repetitive way, that it is actually hard to follow the flow of what the code "wants" to do - the sequence of operations that will be carried out if everything works as expected. Trying to work out how a particular type of error will be handled, or even which types of errors might occur, is even harder.

What if we could separate out the straight forward intent of our code on the one hand, but also ensure we handle all of the possible failure states? What if we could compose together multiple operations which each, individually, know how they might fail and end up with a larger operation that still knows all the ways it can fail.

Business logic that looks like this:

export const processLaxCallback = ({
  laxOperations,
  commands,
  localFunctions,
}: LaxCallbackDependencies) =>
  SolidChain.start<HttpRequest, LaxCallBackState>()
    .chain("laxSignatureCheck", laxOperations.checkSignature)
    .chain("laxContext", laxOperations.parseRequest)
    .tap(({ laxContext }) => Solid.set("laxContext", laxContext))
    .chain("command", ({ laxContext }) =>
      commands.parseUntrustedCommand({
        untrustedCommand: laxContext.actionPayload,
      })
    )
    .chain("userInfo", laxOperations.findUserAndOrganization)
    .tap(({ userInfo }) => Solid.set("user", userInfo.user))
    .tap(({ userInfo }) => Solid.set("organization", userInfo.organization))
    .chain("eventsCaused", commands.executeCommand)
    .map("reply", localFunctions.createSuccessResponse)
    .tap(laxOperations.reply)
    .executeTarget("eventsCaused");

Once we've called our code, we can then exhaustively handle any errors it may have produced, safe in the knowledge that if any of the operations we're depending on add a new failure mode the compiler will force us to deal with them appropriately. This consolidates all of our error handling into an other clear and easy to read piece of code, generally looking something like the following:

switch (processResult.result.failure.type) {
  case "NotPermitted":
    await reportError("You can't do that");
    break;
  case "ValidationFailed":
    await reportError("You sent the wrong information");
    break;
  case "UnrecognizedCommand":
    await reportError(
      "Something is wrong with the message we sent you, sorry!"
    );
    break;
  case "OrganizationNotFound":
  case "UserNotFound":
    await reportError("You don't seem to be fully set up on Lax yet");
    break;
  case "UnableToParseLaxContext":
  case "InvalidLaxSignature":
    await reportError("Invalid callback");
    break;
  case "CouldNotContactLax":
    await reportError(
      "We tried to send you a message, but something went wrong at Lax's end."
    );
    break;
  case "LaxRefusedReply":
    await reportError(
      "We tried to send you a message but something went wrong on our end."
    );
    break;
  case "UnhandledException":
    await reportError(
      "Something went wrong, our support staff will look into it"
    );
    break;
  default:
    // this is just a function that takes and returns "never"
    // to enforce completeness
    return exhausted(processResult.result.failure);
}

Let's do it! We need to both build out our monad, and then also think about how to write the code that uses it.

The monad itself

First let's build the monad we're going to need. To write the code we want to, we know that we need a few properties. Our operations will frequently be asynchronous, so we need to deal with that. They need to be able to declare how they can fail, so we need them to return a success or failure result type. And they need to be able to capture information during the operation even if the operation then fails so that we can make that information available during error handling.

Standing on the shoulders of giants, this sounds very much like we're talking about a state monad stacked on top of an either (sometimes called result) monad. The type of a state monad is a function that takes the state so far, and returns the state and a result. The either monad says that the result in question can be either a success or a failure.

We're going to place one more restriction on the "state" type, because in our case it will nearly always be true and it simplifies some of the types: all of the fields on the state object being passed through the operations are optional.

Let's try and model that as a type in TypeScript.

export type SolidSuccess<Success> = {
  kind: "success";
  value: Success;
};

export type SolidFailure<Failure> = {
  kind: "failure";
  failure: Failure;
};

export type Solid<Success, Failure, State extends Scope<any>> = (
  state: Partial<State>
) => Promise<{
  state: Partial<State>;
  result: SolidSuccess<Success> | SolidFailure<Failure>;
}>;

Now we need a bind and a pure method.

export const Solid = {
  pure: <Success, State extends Scope<any>>(
    value: Success
  ): Solid<Success, never, State> => {
    return async (state) => ({ state, result: { kind: "success", value } });
  },
  bind: <Success, NextSuccess, Failure, NextFailure, State extends Scope<any>>(
    prev: Solid<Success, Failure, State>,
    func: (success: Success) => Solid<NextSuccess, NextFailure, State>
  ): Solid<NextSuccess, Failure | NextFailure, State> => {
    return async (state: Partial<State>) => {
      const awaitedPrevious = await prev(state);
      const prevResult = awaitedPrevious.result;
      if (prevResult.kind === "success") {
        const next = await func(prevResult.value)(prevResult.state);
        return next;
      } else {
        return { state: prevResult.state, result: prevResult };
      }
    };
  }
};

This, as normal, is where the magic really happens. pure is fairly straight forward; we can lift any concrete value into our monad type by creating a function that takes the current state and returns the same state unchanged along with the concrete value as a "success" result.

bind, on the other hand, might have a type signature that is different from what you would expect. It does not limit the failure type of the continuation function to match the existing monad, but instead declares that the new resulting monad has a failure type of Failure | NextFailure. This means that if we, say, start with a monad that has a failure type of NetworkFailure and we bind a follow up operation with a failure type of FileSystemFailure we get a resulting monad that says it could fail with either a network or a file system failure.

Pretty snazzy, and one of the areas where TypeScript genuinely shines.

Life is much nicer if we also add some helper methods; a short hand for returning a failure, methods to get, set, and update the state being passed through, and finally a helper that captures thrown exceptions and turns them into a typed UnhandledException failure type while also capturing the stack trace.

export type UnhandledExceptionFailure = {
  type: "UnhandledException";
  thrown: any;
};

export const Solid = {
  // pure and bind from above go here
  failure: <Failure, State extends Scope<any>>(
    failure: Failure
  ): Solid<never, Failure, State> => {
    return async (state) => ({ state, result: { kind: "failure", failure } });
  },
  get: <Failure, State extends Scope<any>>(): Solid<
    Partial<State>,
    Failure,
    State
  > => {
    return async (state: Partial<State>) => ({
      state,
      result: { kind: "success", value: state },
    });
  },
  modify: <State extends Scope<any>>(
    func: (prev: Partial<State>) => Partial<State>
  ): Solid<Partial<State>, never, State> => {
    return async (state: Partial<State>) => {
      const newState = func(state);
      return {
        state: newState,
        result: { kind: "success", value: newState },
      };
    };
  },
  set: <State extends Scope<any>, Key extends keyof State>(
    key: Key,
    value: State[Key]
  ): Solid<void, never, State> => {
    return Solid.bind(
      Solid.modify((prev) => ({ ...prev, [key]: value })),
      () => Solid.pure(undefined)
    );
  },
  noThrow: <Success, Failure, State extends Scope<any>>(
    solid: Solid<Success, Failure, State>
  ): Solid<Success, Failure | UnhandledExceptionFailure, State> => {
    return (state: Partial<State>) => {
      try {
        return solid(state);
      } catch (e) {
        return Solid.failure({
          type: "UnhandledException" as const,
          thrown: e,
        })(state);
      }
    };
  },
};

We have a monad now, so our chain should look very familiar; let's put the whole thing here in full so we can admire it in all its abstract beauty. We've added a tap method which puts an operation in the chain that doesn't add anything to the scope, useful for things like updating the state or sending messages, and we've added a call to noThrow in the "execute" methods to make sure that we don't accidentally forget to capture exceptions and so break all our lovely new error handling. Apart from that, it should all look very familiar.

export class SolidChain<
  Input,
  OutputScope extends Scope<any>,
  Failure,
  State extends Scope<any>
> {
  private readonly operation: (
    input: Input
  ) => Solid<OutputScope, Failure, State>;
  constructor(starter: (input: Input) => Solid<OutputScope, Failure, State>) {
    this.operation = starter;
  }

  execute(
    input: Input
  ): Solid<OutputScope, Failure | UnhandledExceptionFailure, State> {
    return Solid.noThrow(this.operation(input));
  }

  chain<NextOutput, NextFailure, ResultName extends string>(
    resultName: ResultName,
    next: (previous: OutputScope) => Solid<NextOutput, NextFailure, State>
  ): SolidChain<
    Input,
    ExtendedScope<OutputScope, ResultName, NextOutput>,
    Failure | NextFailure,
    State
  > {
    const chainedOperation = (
      input: Input
    ): Solid<
      ExtendedScope<OutputScope, ResultName, NextOutput>,
      Failure | NextFailure,
      State
    > => {
      const previousResult = this.operation(input);
      return Solid.bind(previousResult, (output: OutputScope) => {
        return Solid.bind(next(output), (nextOutput) => {
          return Solid.pure(extendScope(output, resultName, nextOutput));
        });
      });
    };
    return new SolidChain(chainedOperation);
  }

  map<NextOutput, ResultName extends string>(
    resultName: ResultName,
    next: (previous: OutputScope) => NextOutput
  ): SolidChain<
    Input,
    ExtendedScope<OutputScope, ResultName, NextOutput>,
    Failure,
    State
  > {
    return this.chain(resultName, (scope) => Solid.pure(next(scope)));
  }

  tap<NextFailure>(
    func: (previous: OutputScope) => Solid<void, NextFailure, State>
  ): SolidChain<Input, OutputScope, Failure | NextFailure, State> {
    return new SolidChain((input: Input) =>
      Solid.bind(this.operation(input), (scope) =>
        Solid.bind(func(scope), () => Solid.pure(scope))
      )
    );
  }

  executeTarget<ResultName extends keyof OutputScope>(
    resultName: ResultName
  ): (
    input: Input
  ) => Solid<
    OutputScope[ResultName],
    Failure | UnhandledExceptionFailure,
    State
  > {
    return (input: Input) =>
      Solid.noThrow(
        Solid.bind(this.execute(input), (outputScope) =>
          Solid.pure(outputScope[resultName])
        )
      );
  }

  static start<
    InputScope extends Scope<any>,
    State extends Partial<Scope<any>>
  >(): SolidChain<InputScope, InputScope, never, State> {
    return new SolidChain(Solid.pure<InputScope, State>);
  }
}

Writing the code
To fully take advantage of our new shiny monad, there's a few simple rules we want to follow.
- It should be easy to distinguish between error types; a discriminator field is great for this
- We should aim to write our "business" functions to take a single object argument, so that a scope object can be built up that can call them
- If at all possible, those arguments should use well known field names for well known pieces of data
This means that we'll end up with external dependencies represented as functions that look something like this (either globally, or wrapped locally for use in the chain if you're not basing your whole code architecture off this blog post: shame on you!):
```
export interface Commands {
  parseUntrustedCommand: <State extends Scope<any>>(scope: {
    untrustedCommand: any;
  }) => Solid<Command, { type: "UnrecognizedCommand"; message: string }, State>;
  executeCommand: <State extends Scope<any>>(args: {
    userInfo: { user: User; organization: Organization };
    command: Command;
  }) => Solid<
    Events,
    { type: "NotPermitted" | "ValidationFailed"; message: string },
    State
  >;
}
```
Following these patterns and combining them with the type safety of the chain builder is enormously powerful, especially for helping out new developers. For example, if you want to call the executeCommand operation you'll find that you can't put it in the chain before the operations that get the command and the user info, and you can't return a chain that doesn't explicitly flag that it may fail with the "NotPermitted" and "ValidationFailed" errors.

18.0.6. Appendix 1: Stealing from the best

The advantage of using a standard abstraction like a monad is that someone has done most of the hard thinking already for you. In TypeScript we don't have a nice way of defining code that works on "anything which is a monad", but in Haskell you can - and that means that there's collections of functions that you can refer to that are implemented on the basis of something being a monad. This means that if you have a working knowledge of Haskell (or Scala, or an other language where someone has done this work for you already) you can easily add features to your XChain class as you discover you need them.

For example, what do you do if you have an array of inputs that you want to map using a Solid returning function?

Well, if you check the link above you'll find the mapM function with the signature mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b). A Traversable is roughly an iterable in TypeScript speak, so we can check how mapM is implemented on a type that would be useful in TypeScript. It turns out it is an alias for the traverse function of whichever t is traversable, so we pick the list implementation as probably being close to what we'd want and it is:

instance Traversable [] where
  {-# INLINE traverse #-} -- so that traverse can fuse
  traverse f = List.foldr cons_f (pure [])
    where cons_f x ys = liftA2 (:) (f x) ys

Hmm. liftA2 is a bit weirdly named but it allows a binary operation to happen in our monadic context. We can in turn look up a default implementation of that in terms of what's available in a monad, and we end up with some new helper functions on monad.

export const Solid = {
  // All the existing monad operations like bind etc...
  map: <Previous, Next, Failure, State extends Scope<any>>(
    func: (previous: Previous) => Next,
    prev: Solid<Previous, Failure, State>
  ) => {
    return Solid.bind(prev, (success) => Solid.pure(func(success)));
  },
  apply: <Success, NextSuccess, Failure, NextFailure, State extends Scope<any>>(
    funcInMonad: Solid<(prev: Success) => NextSuccess, NextFailure, State>,
    prev: Solid<Success, Failure, State>
  ): Solid<NextSuccess, Failure | NextFailure, State> => {
    return Solid.bind(funcInMonad, (func) => Solid.map(func, prev));
  },
  lift2: <
    Left,
    Right,
    Result,
    LeftFailure,
    RightFailure,
    State extends Scope<any>
  >(
    operation: (left: Left, right: Right) => Result,
    left: Solid<Left, LeftFailure, State>,
    right: Solid<Right, RightFailure, State>
  ): Solid<Result, LeftFailure | RightFailure, State> => {
    return Solid.apply(
      Solid.map((left: Left) => (right: Right) => operation(left, right), left),
      right
    );
  },
  traverse: <Input, Success, Failure, State extends Scope<any>>(
    inputs: Input[],
    func: (input: Input) => Solid<Success, Failure, State>
  ): Solid<Success[], Failure, State> => {
    return inputs.reduce<Solid<Success[], Failure, State>>(
      (acc, next) =>
        Solid.lift2(
          (results: Success[], next: Success) => {
            results.push(next);
            return results;
          },
          acc,
          func(next)
        ),
      Solid.pure([])
    );
  },
};

Did translating that make my brain hurt a bit? Yes, but it made my brain hurt a lot less than working out that logic for myself. And now you are just a cut and paste away from being able to reuse this same code on any other monads you want to create, and in your solid chains you can right things like:

export const traverseExample =
  (commandOperations: Commands) => (untrustedInput: any[]) =>
    SolidChain.start<
      {
        untrustedInput: any[];
        userInfo: { user: User; organization: Organization };
      },
      {}
    >()
      .chain("parsedCommands", ({ untrustedInput }) =>
        Solid.traverse(untrustedInput, commandOperations.parseUntrustedCommand)
      )
      .chain("resultingEvents", ({ parsedCommands, userInfo }) =>
        Solid.traverse(parsedCommands, (command) =>
          commandOperations.executeCommand({ command, userInfo })
        )
      )
      .executeTarget("resultingEvents");

Warning: there's an argument for not adding too many of these helpers too quickly or to not make all of the intermediate abstractions publicly available. Developers new to functional programming will quickly see the point of a method like traverse when shown an example, but finding something like lift2 is going to leave a lot of people scratching their heads.

18.0.7. Appendix 2: A slightly excessive example of the Solid monad in action

You can cut and paste this big fat code block into the TS editor of your choice and have a play with the Solid monad. Go on. It's fun!

export type Scope<Keys extends string> = {
  [K in Keys]: any;
};

export type ExtendedScope<
  OldScope extends Scope<any>,
  NewField extends string,
  NewValue
> = OldScope extends any
  ? {
      [K in keyof OldScope | NewField]: K extends NewField
        ? NewValue
        : K extends keyof OldScope
        ? OldScope[K]
        : never;
    }
  : never;

export const extendScope = <
  OldScope extends Scope<any>,
  NewField extends string,
  NewValue
>(
  oldScope: OldScope,
  newField: NewField,
  newValue: NewValue
) => {
  const addToScope = {
    [newField]: newValue,
  };
  return {
    ...oldScope,
    ...addToScope,
  } as ExtendedScope<OldScope, NewField, NewValue>;
};

export type AsyncMaybe<T> = Promise<T | null | undefined>;

export namespace AsyncMaybe {
  export const bind = async <A, B>(
    prevAsync: AsyncMaybe<A>,
    func: (prev: A) => AsyncMaybe<B>
  ): AsyncMaybe<B> => {
    const prev = await prevAsync;
    if (prev === null || prev === undefined) {
      return null;
    } else {
      return func(prev);
    }
  };
  export const pure = <A>(value: A): AsyncMaybe<A> => Promise.resolve(value);
}

export class AsyncMaybeChain<Input, OutputScope extends Scope<any>> {
  private readonly operation: (input: Input) => AsyncMaybe<OutputScope>;
  constructor(starter: (input: Input) => AsyncMaybe<OutputScope>) {
    this.operation = starter;
  }

  execute(input: Input): AsyncMaybe<OutputScope> {
    return this.operation(input);
  }

  chain<NextOutput, ResultName extends string>(
    resultName: ResultName,
    next: (previous: OutputScope) => AsyncMaybe<NextOutput>
  ): AsyncMaybeChain<
    Input,
    ExtendedScope<OutputScope, ResultName, NextOutput>
  > {
    const chainedOperation = (
      input: Input
    ): AsyncMaybe<ExtendedScope<OutputScope, ResultName, NextOutput>> => {
      const previousResult = this.operation(input);
      return AsyncMaybe.bind(previousResult, (output: OutputScope) => {
        return AsyncMaybe.bind(next(output), (nextOutput) => {
          return AsyncMaybe.pure(extendScope(output, resultName, nextOutput));
        });
      });
    };
    return new AsyncMaybeChain(chainedOperation);
  }

  map<NextOutput, ResultName extends string>(
    resultName: ResultName,
    next: (previous: OutputScope) => NextOutput
  ): AsyncMaybeChain<
    Input,
    ExtendedScope<OutputScope, ResultName, NextOutput>
  > {
    return this.chain(resultName, (scope) => AsyncMaybe.pure(next(scope)));
  }

  executeTarget<ResultName extends keyof OutputScope>(resultName: ResultName) {
    return (input: Input) =>
      AsyncMaybe.bind(this.execute(input), (outputScope) =>
        AsyncMaybe.pure(outputScope[resultName])
      );
  }

  static start<InputScope extends Scope<any>>(): AsyncMaybeChain<
    InputScope,
    InputScope
  > {
    return new AsyncMaybeChain(AsyncMaybe.pure<InputScope>);
  }
}

export const maybeTest = AsyncMaybeChain.start<{ initialInput: string }>()
  .chain("punctuation", () => AsyncMaybe.pure("!"))
  .chain("finalGreeting", (scope) =>
    AsyncMaybe.pure(`Hello ${scope.initialInput}${scope.punctuation}`)
  ).execute;

export interface MaybeData {
  getName: (userId: string) => Promise<string | null>;
  getPunctuation: (name: string) => Promise<string | undefined>;
}

// Without Chain
export const before = async ({
  userId,
  maybeData,
}: {
  userId: string;
  maybeData: MaybeData;
}) => {
  const name = await maybeData.getName(userId);
  if (name === null) {
    return null;
  }
  const punctuation = await maybeData.getPunctuation(name);
  if (punctuation === undefined) {
    return null;
  }
  return `Hello ${name}${punctuation}`;
};

// With Chain
export const after = AsyncMaybeChain.start<{
  userId: string;
  maybeData: MaybeData;
}>()
  .chain("name", (s) => s.maybeData.getName(s.userId))
  .chain("punctuation", (s) => s.maybeData.getPunctuation(s.name))
  .map("result", (s) => `${s.name}{s.punctuation}`)
  .executeTarget("result");

export const exhausted = (narrowedType: never) => narrowedType;

export type SolidSuccess<Success> = {
  kind: "success";
  value: Success;
};

export type SolidFailure<Failure> = {
  kind: "failure";
  failure: Failure;
};

export type Solid<Success, Failure, State extends Scope<any>> = (
  state: Partial<State>
) => Promise<{
  state: Partial<State>;
  result: SolidSuccess<Success> | SolidFailure<Failure>;
}>;

export const Solid = {
  pure: <Success, State extends Scope<any>>(
    value: Success
  ): Solid<Success, never, State> => {
    return async (state) => ({ state, result: { kind: "success", value } });
  },
  failure: <Failure, State extends Scope<any>>(
    failure: Failure
  ): Solid<never, Failure, State> => {
    return async (state) => ({ state, result: { kind: "failure", failure } });
  },
  bind: <Success, NextSuccess, Failure, NextFailure, State extends Scope<any>>(
    prev: Solid<Success, Failure, State>,
    func: (success: Success) => Solid<NextSuccess, NextFailure, State>
  ): Solid<NextSuccess, Failure | NextFailure, State> => {
    return async (state: Partial<State>) => {
      const awaitedPrevious = await prev(state);
      const prevResult = awaitedPrevious.result;
      if (prevResult.kind === "success") {
        const next = await func(prevResult.value)(prevResult.state);
        return next;
      } else {
        return { state: prevResult.state, result: prevResult };
      }
    };
  },
  get: <Failure, State extends Scope<any>>(): Solid<
    Partial<State>,
    Failure,
    State
  > => {
    return async (state: Partial<State>) => ({
      state,
      result: { kind: "success", value: state },
    });
  },
  modify: <State extends Scope<any>>(
    func: (prev: Partial<State>) => Partial<State>
  ): Solid<Partial<State>, never, State> => {
    return async (state: Partial<State>) => {
      const newState = func(state);
      return {
        state: newState,
        result: { kind: "success", value: newState },
      };
    };
  },
  set: <State extends Scope<any>, Key extends keyof State>(
    key: Key,
    value: State[Key]
  ): Solid<void, never, State> => {
    return Solid.bind(
      Solid.modify((prev) => ({ ...prev, [key]: value })),
      () => Solid.pure(undefined)
    );
  },
  noThrow: <Success, Failure, State extends Scope<any>>(
    solid: Solid<Success, Failure, State>
  ): Solid<Success, Failure | UnhandledExceptionFailure, State> => {
    return (state: Partial<State>) => {
      try {
        return solid(state);
      } catch (e) {
        return Solid.failure({
          type: "UnhandledException" as const,
          thrown: e,
        })(state);
      }
    };
  },
  map: <Previous, Next, Failure, State extends Scope<any>>(
    func: (previous: Previous) => Next,
    prev: Solid<Previous, Failure, State>
  ) => {
    return Solid.bind(prev, (success) => Solid.pure(func(success)));
  },
  apply: <Success, NextSuccess, Failure, NextFailure, State extends Scope<any>>(
    funcInMonad: Solid<(prev: Success) => NextSuccess, NextFailure, State>,
    prev: Solid<Success, Failure, State>
  ): Solid<NextSuccess, Failure | NextFailure, State> => {
    return Solid.bind(funcInMonad, (func) => Solid.map(func, prev));
  },
  lift2: <
    Left,
    Right,
    Result,
    LeftFailure,
    RightFailure,
    State extends Scope<any>
  >(
    operation: (left: Left, right: Right) => Result,
    left: Solid<Left, LeftFailure, State>,
    right: Solid<Right, RightFailure, State>
  ): Solid<Result, LeftFailure | RightFailure, State> => {
    return Solid.apply(
      Solid.map((left: Left) => (right: Right) => operation(left, right), left),
      right
    );
  },
  traverse: <Input, Success, Failure, State extends Scope<any>>(
    inputs: Input[],
    func: (input: Input) => Solid<Success, Failure, State>
  ): Solid<Success[], Failure, State> => {
    return inputs.reduce<Solid<Success[], Failure, State>>(
      (acc, next) =>
        Solid.lift2(
          (results: Success[], next: Success) => {
            results.push(next);
            return results;
          },
          acc,
          func(next)
        ),
      Solid.pure([])
    );
  },
};

export type UnhandledExceptionFailure = {
  type: "UnhandledException";
  thrown: any;
};

export class SolidChain<
  Input,
  OutputScope extends Scope<any>,
  Failure,
  State extends Scope<any>
> {
  private readonly operation: (
    input: Input
  ) => Solid<OutputScope, Failure, State>;
  constructor(starter: (input: Input) => Solid<OutputScope, Failure, State>) {
    this.operation = starter;
  }

  execute(
    input: Input
  ): Solid<OutputScope, Failure | UnhandledExceptionFailure, State> {
    return Solid.noThrow(this.operation(input));
  }

  chain<NextOutput, NextFailure, ResultName extends string>(
    resultName: ResultName,
    next: (previous: OutputScope) => Solid<NextOutput, NextFailure, State>
  ): SolidChain<
    Input,
    ExtendedScope<OutputScope, ResultName, NextOutput>,
    Failure | NextFailure,
    State
  > {
    const chainedOperation = (
      input: Input
    ): Solid<
      ExtendedScope<OutputScope, ResultName, NextOutput>,
      Failure | NextFailure,
      State
    > => {
      const previousResult = this.operation(input);
      return Solid.bind(previousResult, (output: OutputScope) => {
        return Solid.bind(next(output), (nextOutput) => {
          return Solid.pure(extendScope(output, resultName, nextOutput));
        });
      });
    };
    return new SolidChain(chainedOperation);
  }

  map<NextOutput, ResultName extends string>(
    resultName: ResultName,
    next: (previous: OutputScope) => NextOutput
  ): SolidChain<
    Input,
    ExtendedScope<OutputScope, ResultName, NextOutput>,
    Failure,
    State
  > {
    return this.chain(resultName, (scope) => Solid.pure(next(scope)));
  }

  tap<NextFailure>(
    func: (previous: OutputScope) => Solid<void, NextFailure, State>
  ): SolidChain<Input, OutputScope, Failure | NextFailure, State> {
    return new SolidChain((input: Input) =>
      Solid.bind(this.operation(input), (scope) =>
        Solid.bind(func(scope), () => Solid.pure(scope))
      )
    );
  }

  executeTarget<ResultName extends keyof OutputScope>(
    resultName: ResultName
  ): (
    input: Input
  ) => Solid<
    OutputScope[ResultName],
    Failure | UnhandledExceptionFailure,
    State
  > {
    return (input: Input) =>
      Solid.noThrow(
        Solid.bind(this.execute(input), (outputScope) =>
          Solid.pure(outputScope[resultName])
        )
      );
  }

  static start<
    InputScope extends Scope<any>,
    State extends Partial<Scope<any>>
  >(): SolidChain<InputScope, InputScope, never, State> {
    return new SolidChain(Solid.pure<InputScope, State>);
  }
}

type HttpRequest = {};
type User = {};
type Organization = {};
type Command = {};
type Events = {};
type LaxMessage = {};

type LaxContext = {
  laxUserId: string;
  laxOrganizationId: string;
  laxResponseUrl: URL;
  actionPayload: any;
};

export interface LaxOperations {
  checkSignature: <State extends Scope<any>>(scope: {
    httpRequest: HttpRequest;
  }) => Solid<
    "laxSignatureOk",
    { type: "InvalidLaxSignature"; message: string },
    State
  >;
  parseRequest: <State extends { laxContext: LaxContext }>(scope: {
    laxSignatureCheck: "laxSignatureOk";
  }) => Solid<
    LaxContext,
    { type: "UnableToParseLaxContext"; message: string },
    State
  >;
  reply: <State extends { laxContext: LaxContext }>(scope: {
    laxContext: LaxContext;
    reply: LaxMessage;
  }) => Solid<
    void,
    { type: "CouldNotContactLax" | "LaxRefusedReply"; message: string },
    State
  >;
  findUserAndOrganization: <State extends Scope<any>>(scope: {
    laxContext: LaxContext;
  }) => Solid<
    { user: User; organization: Organization },
    { type: "OrganizationNotFound" | "UserNotFound"; message: string },
    State
  >;
}

export interface Commands {
  parseUntrustedCommand: <State extends Scope<any>>(scope: {
    untrustedCommand: any;
  }) => Solid<Command, { type: "UnrecognizedCommand"; message: string }, State>;
  executeCommand: <State extends Scope<any>>(args: {
    userInfo: { user: User; organization: Organization };
    command: Command;
  }) => Solid<
    Events,
    { type: "NotPermitted" | "ValidationFailed"; message: string },
    State
  >;
}

export interface TheseWouldBeLocalFunctions {
  createSuccessResponse: (scope: {
    command: Command;
    userInfo: { user: User; organization: Organization };
    eventsCaused: Events;
  }) => LaxMessage;
}

export type LaxCallBackState = {
  laxContext: LaxContext;
  user: User;
  organization: Organization;
};

export type LaxCallbackDependencies = {
  laxOperations: LaxOperations;
  commands: Commands;
  localFunctions: TheseWouldBeLocalFunctions;
};

export const processLaxCallback = ({
  laxOperations,
  commands,
  localFunctions,
}: LaxCallbackDependencies) =>
  SolidChain.start<{ httpRequest: HttpRequest }, LaxCallBackState>()
    .chain("laxSignatureCheck", laxOperations.checkSignature)
    .chain("laxContext", laxOperations.parseRequest)
    .tap(({ laxContext }) => Solid.set("laxContext", laxContext))
    .chain("command", ({ laxContext }) =>
      commands.parseUntrustedCommand({
        untrustedCommand: laxContext.actionPayload,
      })
    )
    .chain("userInfo", laxOperations.findUserAndOrganization)
    .tap(({ userInfo }) => Solid.set("user", userInfo.user))
    .tap(({ userInfo }) => Solid.set("organization", userInfo.organization))
    .chain("eventsCaused", commands.executeCommand)
    .map("reply", localFunctions.createSuccessResponse)
    .tap(laxOperations.reply)
    .executeTarget("eventsCaused");

export const laxCallbackHandler =
  (deps: LaxCallbackDependencies) => async (httpRequest: HttpRequest) => {
    const processResult = await processLaxCallback(deps)({ httpRequest })({});

    if (processResult.result.kind === "success") {
      console.log("Woot! Created events: ", processResult.result.value);
    } else {
      // Error handling
      const reportError = async (message: string) => {
        console.log(
          "Always report errors internally with full info including stack trace for unhandled exceptions",
          processResult
        );
        if (processResult.state.laxContext) {
          // We have enough info to tell the user something went wrong.
          // In theory we could check if this operation failed, but
          // we also can't do anything about it so :shrug:
          await deps.laxOperations.reply({
            laxContext: processResult.state.laxContext,
            reply: message as any as LaxMessage, // Let's pretend :)
          })({});
        }
      };
      switch (processResult.result.failure.type) {
        case "NotPermitted":
          await reportError("You can't do that");
          break;
        case "ValidationFailed":
          await reportError("You sent the wrong information");
          break;
        case "UnrecognizedCommand":
          await reportError(
            "Something is wrong with the message we sent you, sorry!"
          );
          break;
        case "OrganizationNotFound":
        case "UserNotFound":
          await reportError("You don't seem to be fully set up on Lax yet");
          break;
        case "UnableToParseLaxContext":
        case "InvalidLaxSignature":
          await reportError("Invalid callback");
          break;
        case "CouldNotContactLax":
          await reportError(
            "We tried to send you a message, but something went wrong at Lax's end."
          );
          break;
        case "LaxRefusedReply":
          await reportError(
            "We tried to send you a message but something went wrong on our end."
          );
          break;
        case "UnhandledException":
          await reportError(
            "Something went wrong, our support staff will look into it"
          );
          break;
        default:
          return exhausted(processResult.result.failure);
      }
    }
  };

export const traverseExample =
  (commandOperations: Commands) => (untrustedInput: any[]) =>
    SolidChain.start<
      {
        untrustedInput: any[];
        userInfo: { user: User; organization: Organization };
      },
      {}
    >()
      .chain("parsedCommands", ({ untrustedInput }) =>
        Solid.traverse(untrustedInput, commandOperations.parseUntrustedCommand)
      )
      .chain("resultingEvents", ({ parsedCommands, userInfo }) =>
        Solid.traverse(parsedCommands, (command) =>
          commandOperations.executeCommand({ command, userInfo })
        )
      )
      .executeTarget("resultingEvents");

const expandingErrors =
  (commandOperations: Commands) =>
  (untrustedInput: any, userInfo: { user: User; organization: Organization }) =>
    Solid.bind(
      commandOperations.parseUntrustedCommand({
        untrustedCommand: untrustedInput,
      }),
      (command) => commandOperations.executeCommand({ command, userInfo })
    );

18.0.8. Appendix 3: license

All the code (and only the code) in this blog post is licensed with the MIT license below:

Copyright 2024 Michael Newton

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

18.0.9. I have opinions

Good stuff! You may have noticed I do as well: the "official" place to comment is on this mastodon post. https://mastodon.sdf.org/@mavnn/111957791763779112

Mavnn's blog

@blog · last month

⁂ Article

Does it run? Dev Journal 3

Read this post in its full formatted glory at https://blog.mavnn.eu/2024/02/20/dev-journal-3.html

This post is part of the "Dev Journal" series. Part 1 contains the series index, while the DevJournal3 tag for the CalDance project in GitLab holds the state of the repository as described here.

A short update this time. Gregg Bremer (hi Gregg!) pointed out that running nix run on his linux machine resulted in an error about not being able to find libssl.

This neatly highlights one of the weak spots of Nix; while an excellent packaging solution, it isn't perfect. Nix sandboxes your packages by altering the path environment variable, but not everything is located via that mechanism.

In this case, nix run ran on my machine because I happened to have the libraries in the "right place" for a self contained dotnet core executable, but Gregg did not.

Neither, it turns out, did the docker container I was building. I built and tested it initially with a dotnet console app (which did work, not needing libssl) and then carried on assuming that running nix run on my local machine would also tell me if the docker image could run correctly.

I've now fixed up the code in the previous posts (we needed to add some runtimeDeps to our server package, and the docker image start up command needs to create a writable /tmp directory for asp.net to run correctly).

Most importantly though, I've also made sure that CI will prevent this from happening again by actually checking that the docker image produced can respond to a request to the index with a 200 response code. This is done by adding "stages" to our CI build; the first does exactly what we were doing already, the second then starts the just finished docker image as a "service" and uses curl to check it can respond to us.

You can check out the revised .gitlab-ci.yml file below:

stages:
- build-container
- end-to-end-tests

build-container:
stage: build-container
image:
name: "nixos/nix:2.19.3"
variables:
IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
before_script:
- nix-env --install --attr nixpkgs.skopeo
script:
- mkdir -p "$HOME/.config/nix"
- echo 'experimental-features = nix-command flakes' > "$HOME/.config/nix/nix.conf"
- mkdir -p "/etc/containers/"
- echo '{"default":[{"type":"insecureAcceptAnything"}]}' > /etc/containers/policy.json
- skopeo login --username "$CI_REGISTRY_USER" --password "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
- 'nix build .#dockerImage .#test'
- mkdir testResults
- 'cp result-1/* testResults'
- ls -lh ./result
- 'skopeo inspect docker-archive://$(readlink -f ./result)'
- 'skopeo copy docker-archive://$(readlink -f ./result) docker://$IMAGE_TAG'
artifacts:
when: always
paths:
- 'testResults/*.xml'
reports:
junit: 'testResults/*.xml'

end-to-end-tests:
stage: end-to-end-tests
image:
name: "nixos/nix:2.19.3"
variables:
IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
GIT_STRATEGY: none
services:
- name: $IMAGE_TAG
alias: caldance
script:
- curl -f "http://caldance:5001/"

Next up: adding in the database

Mavnn's blog

@blog · last month

⁂ Article

ADHD and TDD

Read this post in its full formatted glory at https://blog.mavnn.eu/2024/02/21/adhd_and_tdd.html

This piece of writing started as repost comment on LinkedIn responding to a question from J. B. Rainsberger about how people with an ADHD diagnosis experienced TDD. It's a good question, but it's the kind of topic I "own" enough that I don't want to leave my thoughts on it locked away on a platform like LinkedIn, so now they're here too!

This is an interesting one for me; I have both an ADHD diagnosis and I do feel that I use certain programming practices to compensate for it. Something that interests me enough that I'm talking on the subject at Lambda Days 2024, in fact.

Any practice that starts with building a feed back loop is going to be helpful from the ADHD point of view; for example, I have a strong preference for strongly typed languages because the compiler will remind me to finish bits I've forgotten about or catch the typos of concentration lapses in the wild.

That said, I'm personally not a huge fan of TDD as I've normally met it in the wild (I can see the one true Scotsman replies from here, and some of you are probably even right). And the reason for that dislike is also ADHD related but has nothing to do with the initial writing of the code - but with refactoring.

In the vast majority of cases I've seen, TDD has led to code bases with many, many, tests that are tightly coupled to the current implementation of a piece of code because what's actually happened is that each test has been written to confirm the next piece of the implementation is doing what is expected, not to test the overall inputs/outputs of the "block". Mocks that check they are called in a certain order or with certain inputs. Carefully crafted fake dependencies which return the data needed in the correct order and type to satisfy the internal of the function being tested. (Is this what TDD is meant to be? No, not at all - I'm aware)

This makes refactoring deeply painful with a pain that hits hard at the heart of ADHD - you're faced with the choice of updating all these painful, pointless, implementation internal specific mocks on the one hand or having the argument about why your refactoring PR "reduces test coverage" on the other. If you're particularly unlucky there aren't any tests covering the actual behaviour of the original code at all, and now you're left wondering:

"But is my refactor really a refactor at all?"

(It would be remiss of me not to note that teaching developers how to test behaviour and not implementations is actually a service I offer, partly because I don't want to live with the consequences of them not knowing! See my short term consulting page.)