DEV Community: Marko Jakic

🎨 Smooth UI Transitions in HTML with Grains.js, TailwindCSS and g-class directive

Marko Jakic — Sun, 06 Apr 2025 10:29:17 +0000

Spoiler alert: I'm author of Grains.js. If you missed my previous article on Grains.js, please check it out here.

Now I want to show how to use g-class directive for switching classes dynamically based on state. If you're building interactive UIs with plain HTML and want smooth transitions, animations, or dynamic styling — without using a full JS framework — then you'll love how g-class directive works in Grains.js.

Let’s dive into a real-world example.

Note: It's best to utilize TailwindCSS to use ready-made styles via their classes. g-class directive has nothing to do with TailwindCSS, however. It only switches class names based on state. After that, you can use whatever you want.

✨ Animated Notification Example

We’ll build a notification box with:

Visibility toggle
Error/success state styles
Shake animation for emphasis

You can try the live demo here.

You can see updated list of examples at https://github.com/mk0y/grains.js/tree/main/examples.

✅ Setup

Add Grains.js and TailwindCSS to your page:

<script defer src="https://mk0y.github.io/grains.js/dist/grains.min.js"></script>
<script src="https://cdn.tailwindcss.com"></script>

Remember, using cdn.tailwindcss.com is not for production environments. I'm using it only for presentational purposes - you should build your css file instead.

Next, add a simple @keyframes animation for shake:

<style>
  @keyframes shake {
    0%, 100% { transform: translateX(0); }
    25% { transform: translateX(-5px); }
    75% { transform: translateX(5px); }
  }
  .shake {
    animation: shake 0.5s ease-in-out;
  }
</style>

🧠 The Markup

<div
  g-state="notifications"
  g-init='{"isVisible": false, "isError": false, "isShaking": false}'
>
  <div
    g-class="[
      'transform transition-all duration-300 ease-in-out',
      'p-4 rounded-lg shadow-lg mb-4',
      isVisible && 'translate-y-0 opacity-100',
      !isVisible && 'translate-y-4 opacity-0',
      isError && 'bg-red-100 text-red-700',
      !isError && 'bg-green-100 text-green-700',
      isShaking && 'shake'
    ]"
  >
    <p class="font-medium">Notification Message</p>
  </div>

  <div class="space-x-2">
    <button g-on:click="toggleVisibility">Toggle Visibility</button>
    <button g-on:click="toggleError">Toggle Error State</button>
    <button g-on:click="triggerShake">Shake Animation</button>
  </div>
</div>

⚙️ State Changers

Grains.js uses global pure functions to update state. Here’s how we control the behavior:

<script>
window.toggleVisibility = (ctx) => {
  ctx.set({ isVisible: !ctx.get("isVisible") });
};

window.toggleError = (ctx) => {
  ctx.set({ isError: !ctx.get("isError") });
};

window.triggerShake = (ctx) => {
  ctx.set({ isShaking: true });
  setTimeout(() => ctx.set({ isShaking: false }), 500);
};
</script>

💡 How g-class Works

You pass an array of strings or expressions.
Only truthy values are included in the final class list.
This makes toggling animations, colors, and layout transitions declarative and simple.

In the example above, when isVisible is true, classes like translate-y-0 and opacity-100 are added. When false, it falls back to a faded, translated state — giving a nice slide/fade transition.

🏁 Wrap-Up

The g-class directive in Grains.js makes conditional styling effortless, and when combined with Tailwind and a few keyframes, you can build delightful UI transitions in plain HTML — no frameworks or build steps required.

😊 Please let me know what you'd like to change or add as a next feature in the comments.

Thank you!

State Management in HTML with Grains.js

Marko Jakic — Sun, 06 Apr 2025 10:01:19 +0000

I've built Grains.js. Grains.js is a lightweight framework that brings reactivity and state management to vanilla HTML, similar to Alpine.js and HTMX, but with built-in state tracking. Grains.js uses directives as a declarative approach and pure functions for state changers.

Getting Started

First, you need to include Grains.js into your page:

<script
  src="https://mk0y.github.io/grains.js/dist/grains.min.js"
></script>

To define state in Grains.js, you use the g-state directive. This automatically initializes a reactive state that can be referenced throughout your HTML.

Example: Counter with Reactive State

<div g-state="counter" g-init='{"count": 0}'>
  <p>Count: <span g-text="count"></span></p>
  <button g-on:click="increment">Increment</button>
  <button g-on:click="decrement">Decrement</button>
</div>

How It Works

Define state: The g-state="counter" initializes a state variable called counter. This creates a global variable counter. If you inspect it in console as window.counter you'll see its value as Proxy(Object) {count: 0}. Whereas window.counter.count is equal to zero.
Set initial value: The g-init='{"count": 0}' assigns an initial value. This can also be like g-init="myCount", which is referenced to a global variable window.myCount that you have to create.
Bind state to elements: The <span g-text="count"> updates dynamically when counter changes.
Modify state with events: The g-on:click="increment" updates the state on button click.

Define State Changers

State changes are immutable and to dispatch the change we only create global pure functions. In our case increment is a global pure function, which you can inspect as window.increment.

To dispatch the change we use .set method and send the new state object as an argument:

<script>
  function increment(ctx) {
    ctx.set({ count: ctx.get("count") + 1 });
  }
  function decrement(ctx) {
    ctx.set({ count: ctx.get("count") - 1 });
  }
</script>

Take a look at minimal example to get acquainted: https://mk0y.github.io/grains.js/examples/minimal.html.

All examples can be found in the repo: https://github.com/mk0y/grains.js/tree/main/examples.

Why Use Grains.js?

✅ Lightweight & Fast
✅ Declarative State Management
✅ Zero Build Step
✅ Reactive Without Virtual DOM

With Grains.js, managing state in HTML is intuitive and powerful, making it a great alternative for small, interactive UIs without the overhead of larger frameworks.

🚀 Try it out and bring reactivity to your HTML effortlessly!

How to Render JSON Items in Next.js and Server Components?

Marko Jakic — Thu, 08 Jun 2023 10:27:49 +0000

Since Next.js released version 13.4 we have the option to render React components on the server. These are called React Server Components (RSC).

This tutorial will show you the way to load JSON content over HTTPS and render it in the server components, caching included. For storing JSON data and fetching it, we'll use nodb API.

For data fetching in Next.js we'll be using actions. This means we'll have to enable experimental features - in next.config.js first add serverActions experimental flag:

experimental: {
  serverActions: true,
}

This is major prerequisite before we proceed any further. Without this flag nothing will work, but in the next version of Next.js we'll probably already have stable version for actions to use in production.

In Next.js we can use fetch for all HTTP and HTTPS requests within our app. Next.js will cache any request used by fetch, meaning you don't make new request on each page load. This leads us to another important feature of revalidating cache. I tend to use revalidation of tags, compared to paths. This is because we can have multiple requests on the same page, but we only want SOME requests to be cached. That's why I tag the requests and later revalidate using revalidateTag function. If your case means you want to revalidate everything on the same page, feel free to use revalidatePath then.

Now let's see how can we send requests to nodb to store and fetch data. It's simple really. To store data in nodb you make a POST request and send array of objects as the payload (even if it's only one object):

await fetch(
  `https://api.nodb.sh/your-app/dev/items`,
  {
    method: 'POST',
    body: JSON.stringify([item]),
    headers: { token: '...your access token' },
    next: { tags: ['items'] },
  }
);

See nodb docs to learn how to use apps and environments.

For body we must send "stringified" version of the payload. For details take a look at Request API examples. It says:

Note: The body can only be a Blob, an ArrayBuffer, a TypedArray, a DataView, a FormData, a URLSearchParams, a ReadableStream, or a String object, as well as a string literal, so for adding a JSON object to the payload you need to stringify that object.

To tag and later revalidate cached data, we add Next.js extended option { next: { tags: ['anystring'] } }.

In page.js files we usually make GET requests. In my example project I've got the data from nodb like this:

const req = await fetch(
  `https://api.nodb.sh/[app-name]/[env]/items?__sort_by=itemName`,
  {
    method: 'GET',
    headers: { token: `[token]`,
    next: { tags: ['items'] }
  }
);
const { items = [] } = await req.json();

This way we just map the items to React components.

Actions

Let's say we want to delete all items. In nodb we can make a DELETE request to either /items path to delete them all, or /items/:itemId to delete a single entity.

For each request made by the user by clicking a button for example, we make actions.

So, if we want to delete all items, we make a file actions.js in /src/app (or /app) dir in our Next.js project, but you can put it anywhere really, e.g. in /src/actions dir. Inside this file we put the following:

'use server'

export const deleteAllItems = async () => {
  await fetch(
    `${nodbUrl}/items`,
    { method: 'DELETE', headers, next: { tags: ['items'] } });
  revalidateTag('items');
}

Notice here two things. Actions must be called by the server. In Next.js we tell the framework to do exactly that by putting 'use server' on top of the file, or inside a function. The other thing is that finally here we use revalidateTag function. After calling this function you'll see on your page.js file how they're all gone. 😊

The frontend part

Server functions, pages or layouts can't call React hooks or DOM events like onClick. For that we need client components, the ones which will be loaded in the browser.

In our page.js let's import a button which will call action to delete all items. First we create a client component:

// /app/components/delete-all-button.js
'use client'

import { deleteAllItems } from '@/app/actions';

export default function DeleteAllItems() {
  return (
    <button onClick={deleteAllItems}>
      Delete all
    </button>
  );
}

In Next.js we can import server functions inside client files. The result of onClick will delete all the items and your page will re-render automatically due to revalidateTag being called in deleteAllItems server function.

Conclusion

This way we can work with Server Components and fetching data using fetch built-in mechanism. To store and fetch JSON data you can use any service, it's up to you really.

I hope you found this post helpful and meaningful.

You can find example project which I made to reflect on this post. You can find it at https://github.com/nodb-sh/next-nodb-example.

Render bare-bones React app as HTML in Tino

Marko Jakic — Wed, 12 Aug 2020 12:47:38 +0000

Recently I've published Tino functional HTTP server for Deno, and you can read a short overview about it here.

This time I would like to show how you can easily render HTML content using middlewares.

Middlewares in Tino are composition of functions which whatever they return is passed through until your controller receives it.

Using Deno's TextDecoder and readFile top level APIs and Tino's withMiddlewares helper for composing middlewares you can write a simple endpoint definition in the following manner: (for example app.js file)

// app.js
const htmlReader = async () => {
  const decoder = new TextDecoder("utf-8");
  const html = await Deno.readFile("./react.html");
  return { html: decoder.decode(html) };
}

const composedReact = withMiddlewares(htmlReader);
const useHTML = composedReact(({ html }) => ({ resp: html, type: "text/html" }));

app.get(() => ({ path: "/react", use: useHTML }));

Now you need to create your React app as a website somewhere. I won't be using JSX here for simplicity but only React's createElement. Let's say you have your boilerplate saved in ./react.html file (same directory as your app.js file). Have a look at sample content below. All it does is handling "Inc" button and logging incremented value to the console:

<html>

<head>
  <script src="https://unpkg.com/react@16/umd/react.development.js" crossorigin></script>
  <script src="https://unpkg.com/react-dom@16/umd/react-dom.development.js" crossorigin></script>
</head>

<body>
  <div id="root"></div>
  <script>
    const e = React.createElement;
    const domContainer = document.querySelector('#root');
    const IncButton = () => {
      const [incrementedValue, inc] = React.useState(0);
      return e(
        'button',
        {
          onClick: () => {
            inc(incrementedValue + 1);
            console.log(incrementedValue);
          }
        },
        'Inc'
      );
    };
    ReactDOM.render(e(IncButton), domContainer);
  </script>
</body>

</html>

Now when you target http://localhost:8000/react you should see your React app running in the browser.

Hope you liked this post and how using middlewares you can process pretty much anything in Tino and write your own.

Cheers! 🍻

Introduction to Tino - tiny and functional HTTP server for Deno

Marko Jakic — Fri, 07 Aug 2020 08:39:26 +0000

Little bit of theory

Since Deno released its version 1.0 earlier this year I was eager to make an HTTP server for it. And, few weeks later I had some basic routing... thing, I called Tino. It's tiny, it's for Deno.

Tino also offers local JSON REST API for rapid prototyping via responders. More on that when you scroll down.

Keep in mind, it is only JavaScript for now, so no TypeScript, but, that doesn't matter really since we can run both in Deno. We're waiting for this issue to become ready and TS 4.0 version bundled into Deno to make Tino fully TS, too. Why? Because variadic tuples are not yet supported and Tino uses function composition heavily.

I didn't want to have it "java-esque" behaviour with decorated routes and classes and what not (think of Spring Boot for example) only because it is now possible to write TypeScript out of the box. Not saying it's a bad thing, on the contrary.

On the other hand Tino uses only functions and (async) function composition. Async composition (for middlewares) is necessary so you can compose both sync and async functions.

Usage and examples

Let's see how it actually works and how much freedom one might have using functions only. (Take a look at examples any time)

First steps

Import Tino from third party modules (for version number look at README.md):

import tino from "https://deno.land/x/tino@vX.Y.Z/tino.js";
const app = tino.create();
// ... you business logic
tino.listen({ app, port: 8000 });
console.log(`Server running at 8000`);

Now we can focus on the rest of your logic, i.e. defining endpoints, controllers and responders.

Defining your first endpoint is as easy as:

const use = () => ({ resp: "pong" });
app.get(() => ({ path: "/ping", use }));

// Even shorter, but only for prototyping:
app.get(() => ({ path: "/ping", resp: "pong" }));

use is your controller. It is flexible and used also for extending Tino's functionality and custom attributes. Read on for more on that.

Both use and resp can be functions, but it makes more sense for use - if resp is a function, it can still receive props but will be called internally and its return will be used as return for use. ;)

Let's see what controller(use) can be and what it can return:

// A function or async function, only returning a string (can be any primitive)
// content-type: text/plain
const returnPong = ({ resp: "pong" })
const use1 = () => returnPong;
const use2 = async () => returnPong;
app.get(() => ({ path: "/ping", use: use1 }));

// Return an object:
// content-type: application/json
const use = () => ({ resp: () => ({}) });

// Set type and status
const use = () => ({ resp: () => "pong", status: 201, type: "text/plain" });

Named params

Tino uses named params for defining your routes, like:

app.get(() => ({ path: "/users/:id", use }));

Props

Any controller can receive props:

const use = (props) => ({ resp: props.params.id });
app.post(() => ({ path: "/users/:id", use }));

Prop type

Prop is an object with following attributes:

body - body sent from POST, PUT and PATCH methods
params - parameters from named params
query - query object from string like ?p=1&q=2
custom params
matchedPath - path regex
pathPattern - path definition
req - as { method, url }
Any other parameters coming from middlewares

Middlewares

Middlewares are provided through async composition of functions. Each function in chain must return properties which are required for next function in chain, or which are required to pass to controller at the end of the chain.

Let's say we have two async functions and one sync, chained together:

// first we need `useMiddlewares` helper for composition
import { withMiddlewares } from "./tino.js";
const withAuth = async (props) => ({ currentUser: {}, userData: props.body });
const isAdmin = ({ currentUser }) => ({ isAdmin: false, currentUser });
const withDB = async (props) => ({ coll: {}, ...props });

// Then we chain(compose) them:
const composed = useMiddlewares(
  withAuth,
  isAdmin,
  withDB,
);

// Then we wrap our controller with it:
const use = composed((props) => ({ resp: props.currentUser }));
app.get(() => ({ path: "/myapi", use }));

Throw exceptions in middlewares (protect routes)

If you want to return early from middleware chain, just throw an exception with same definition as controller's { resp, status?, type? }:

const withAuth = async () => { throw { resp: "Boom", status: 401 } };

So whatever you return from your controller, your endpoint result will be:

HTTP/1.1 401 Unauthorized
content-length: 4
content-type: text/plain

Boom

Responders

Responders are different set of functions which are useful for writing your own namespaced endpoints or let other people use your package with Tino.

To define one just add root: true param to endpoint definition:

app.any(() => ({ path: "/api/v2", use: myAPI.v2, root: true }));

.any stands for any of the HTTP methods so your namespace reacts to all of them.

Your myAPI.v2 function will receive ctx object which contains some Deno stuff like:

{
  req: ServerRequest,
  body,
  query,
  params,
  use, // reference to your function
}

`jsondb` responder

This responder comes built-in with Tino. It opens /api path by default and is responsible for restful CRUD operations against local db.json file. To learn more about it check it out: https://github.com/Vertrical/tino/blob/develop/README.md#using-jsondb-responder.

Thank you for reading this far about tino and I hope you liked it.

Again, to see how tino can be used check out maintained examples. Tino is under heavy development and expect more to come and more articles. ;)

Cheers! 🍻

How I refactor large functions using composition

Marko Jakic — Sat, 18 Apr 2020 17:12:52 +0000

Before I go into the How, let's start with WHY.

So why would I refactor, and in this case decompose a large function? Each time I stumble upon such a function I have to read through it again and understand it. Then new such function appears, and so on. Not to mention writing tests for such functions - it is you who has to calculate what all needs to be covered by tests, it is you who has to carefully read through and put a modification if needed. And then tests may be ruined, mostly. In my opinion there are following reasons better to do so:

Testability - smaller (and pure, if possible) functions are easy to test. They depend only on input and output, unless there are some side effects like reading from database, or branching like if-else and try-catch. But even with branching smaller functions are easy to read and understand.
Readability - when you look at the name of each function (you should be descriptive with names and not use comments everywhere), you can easily follow what's going on, and inject extra steps in between or remove unnecessary ones. Or reuse them.
Reusability - these functions don't understand the context under which they are being put into and executed. They only care about their inputs.

Let's say we have following, significantly simplified for purposes of this article, function:

const notesRoute = async (ctx, next) => {
  const timeBegin = getTime()
  const { notesCollection } = ctx.dbInstance
  const id = ctx.params.id
  const { updatedAt } = ctx.query
  const messages = ctx.request.body
  const { user } = ctx.auth

  trace('Updating messages /api/notes/:id/messages')

  if (isNil(user)) {
    error('PUT notes: user is not set', ctx.auth)
    throw unauthorized('Not Authorized')
  }

  if (!Array.isArray(messages)) {
    error('PUT notes: empty or malformed body sent', messages)
    throw badRequest(
      'PUT notes: empty or malformed body sent. Expects an array, received: ' +
        JSON.stringify(messages)
    )
  }

  try {
    const note = await notesCollection.findOne({ id })
    if (isEmpty(note) || isNil(note)) {
      error(`Note with id ${id} not found`)
      throw notFound(`Note with id ${id} not found`)
    }

    const isOldVersion = note.meta && note.meta.updatedAt !== updatedAt
    if (isOldVersion) {
      warn('PUT notes: updating old version')
      throw conflict('Updating old version', note)
    }

    const meta = {
      updatedAt: getUpdatedAt(),
      createdBy: getCreatedBy(),
    }
    note.messages = messages.map(item => ({ ...item, meta }))

    const processedMessages = await messagesHandler.processMessages(note)
    ctx.response.status = 200
    ctx.response.type = 'application/json'
    ctx.body = JSON.stringify(processedMessages)
  } catch (e) {
    error(e.message)
    throw boomify(e)
  } finally {
    const endTime = getTimeDuration(startTime)
    log.trace(`Duration: ${endTime}, id:  ${id}`)
    await next()
  }
}

There are several if-else/try-catch branches, and a finally, and variables which are used far later in the code after they are defined. Also, there is a side effect, reading from database, which is not synchronous operation.
I like to use ramda library for anything functional and to compose a functionality (or simply a program) I use compose function.
First thing first, with compose function you can only do synchronous composition, but we need to compose together sync and async functions. For such use case we can use this asyncCompose function:

const asyncCompose = (...functions) => input =>
  functions.reduceRight(
    (chain, func) => chain.then(func),
    Promise.resolve(input)
  )

I wouldn't be bothered to understand it, but what it does is simply .then it all the way. This way we force synchronous functions to be async, i.e. wrap them with a Promise. At the end we have result.then().then.then() and THEN, we await it.
In practise we use it like this:

const createHandler = asyncCompose(func1, asyncFunc2, func3, func4)
const result = await createHandler()

What's important here is that any argument passed can be taken further to the next function in chain. You'll see this in action later on.
What I like to do first is to "spread dependencies". This means to initiate first block of variables needed for chain execution. Notice when you compose functions, first one to be executed goes last as an argument to asyncCompose. (f(g(h(x))) here function h executes first. Pipe is what you need if reverse order is important to you.

Function to initiate dependencies may look like:

const spreadDependencies = ({ ctx, messagesHandler }) => {
  const timeBegin = getTime()
  const { notesCollection } = ctx.dbInstance
  const id = ctx.params.id
  const { updatedAt } = ctx.query
  const messages = ctx.request.body
  const { user } = ctx.auth
  const { auth } = ctx
  trace('Updating messages /api/notes/:id/messages')
  return {
    timeBegin,
    notesCollection,
    id,
    updatedAt,
    messages,
    user,
    auth,
    messagesHandler
  }
}

What's good here is also that now you can easily see what exactly is what your program needs. Notice how I just pass here messagesHandler further - so it's available later. Reason behind this is if you import messagesHandler from './someHandler' and use it directly in your function, it will be hard to test it. Sure there are packages out there to proxy your imports but I find that ugly approach. Here you can you sinon for example and stub your arguments easily, which will be covered later on. Also, trace and any kind of logging we can use directly in function, because in many cases you don't want to test that part. If you'd like to though, you can pass it to dependencies as well and stub it, OR write middleware function like tap which only does some side effect and pass on input arguments further.

Next step would be to check if user is not received in request:

const throwIfNoUser = ({ user, auth, ...props }) => {
  if (isNil(user)) {
    error('PUT notes: user is not set', auth)
    throw unauthorized('Not Authorized')
  }
  return { user, ...props }
}

Notice here how auth is just needed for this function and we won't send it further anymore. If you want to go fully functional you can use for example Ramda's when or ifElse, although many teams are not ready for this, but branching isn't bad for small functions (and all should be!) and is often more readable since we got used to this, mostly.

I think by now you're getting it - next step is to check for integrity of our messages:

const throwIfMessagesAreEmptyOrMalformed = ({ messages, ...props }) => {
  if (!Array.isArray(messages)) {
    error('PUT notes: empty or malformed body sent', messages)
    throw badRequest(
      'PUT notes: empty or malformed body sent. Expects an array, received: ' +
        JSON.stringify(messages)
    )
  }
  return { ...props }
}

I write here long names for reading purposes, they don't have to be (but makes writing comments obsolete too!). You can check here for other falsy values too.

So now how about that big try-catch block? Hint: nothing really. You can continue with composing as if it's not there. Since processMessages is the only thing we don't control, the boomify will be applied to the whole chain (we'll see that later on), or the very framework can deal with it, if possible.

Let's get note from database:

const dbGetNote = async ({ id, notesCollection, ...props }) => {
  const note = await notesCollection.findOne({ id })
  if (isEmpty(note) || isNil(note)) {
    error(`Note with id ${id} not found`)
    throw notFound(`Note with id ${id} not found`)
  }
  return { note, ...props }
}

Here we create a new variable note to pass further. Function spreadDependencies was only a way to initialise something to begin with. Also I was wrong, reading from database is again something we don't have control over - it can...break. Remember createHandler? Wrapping it with try-catch is very simple and solves our gigantic blocks, and with our functions we only want to focus on what we have control over.

Let's continue:

const throwOldVersionConflict = ({ note, updatedAt, ...props }) => {
  const isOldVersion = note.meta && note.meta.updatedAt !== updatedAt
    if (isOldVersion) {
      warn('PUT notes: updating old version')
      throw conflict('Updating old version', note)
    }
  }
  return { note, ...props }
}

Variable updatedAt is here since beginning, created in spreadDependencies function, available in ...props all the time. It was only meant to be used here and now we don't need it anymore, so we just return (pass on) note and other props whatever is there.

Let's do last step of our composition:

const asyncProcessMessages = async ({ note, messages, timeBegin, messagesHandler }) => {
  const meta = {
    updatedAt: getUpdatedAt(),
    createdBy: getCreatedBy(),
  }
  note.messages = messages.map(item => ({ ...item, meta }))

  const processedResult = await messagesHandler.processMessages(note)
  return {
    processedResult,
    timeBegin,
  }
}

Here we don't have any try-catch since processMessages is beyond our control and we're gonna wrap the whole thing with single try-catch to handle unknowns. We don't need ...props either - disregard anything except what's needed for last step - readability - now we see only what we actually need. (You can have specific try-catch here, to throw your own self described error)
For the sake of this article and it's simplicity, I iterated over messages with map, but lenses are far more beautiful.

Modern frameworks and environments typically have route definitions like so: route.get('/myroute/here', controller). In such an environment lets discuss how can we make our composed function a handler for the controller.

What we have so far is composed function of:

const createMessageHandler = asyncCompose(
  asyncProcessMessages,
  throwOldVersionConflict,
  dbGetUser,
  throwIfMessagesAreEmptyOrMalformed,
  throwIfNoUser,
  spreadDependencies
)

Suppose we have on top of our file:

import { messageProcessor } from 'some-processor'

Let's say our route is using PUT on /notes/:id.
Additionally, we want to have control of all our side effects, including the messageProcessor, so we want to pass it as an argument (a dependency) instead of calling it directly.

Let's define our main controller handler function. Usually in modern Node.js frameworks controllers are defined as (contextObject, nextFunction) => {} and here I'm placing HOC (higher order function) beforehand so that we can inject our dependencies to the controller's function context:

const messagesRouteHandler = ({ messageHandler, processor }) => async (ctx, next) => {
  const handlerResult = await messageHandler({ ctx, processor })
  const { processedResult, timeBegin } = handlerResult
  const duration = getDuration(timeBegin)
  trace(`Duration: ${duration}`)
}

And here we define our route. Now we have controller's definition (ctx, next) => {} passed to put handler. Our dependencies createMessageHandler and messageProcessor are now available in controller, most importantly they can be replaced as dummy promises in tests.

router.put(
  '/notes/:id',
  messagesRouteHandler({
    messageHandler: createMessageHandler,
    processor: messageProcessor,
  })
)

Now that handler is set, let's write one integration test and one unit test. Let's write integration test for our route handler, i.e. test which mimics behaviour of our main dependencies: our own messages handler and third party messages processor.

test('messagesRouteHandler', async () => {
  const createProcessor = Promise.resolve({
    processedResult: {},
    timeBegin: getTime(),
  })
  const createMessageHandler = Promise.resolve({})
  const ctx = {
    response: {},
    query: {},
    request: { header: {} },
  }
  const next = sinon.stub().resolves()
  await messagesRouteHandler({
    messageHandler: createMessageHandler,
    processor: createProcessor,
  })(ctx, next)
  sinon.assert.calledOnce(next)
})

This test doesn't have greatest value, but it shows you how you can mock/stub/spy dependencies and is rather a demonstration. One idea can be that you can mock methods of a third party dependency, making your tests inform you if its API changed after upgrading it to newer version for example - tests could expect calls on some methods which don't exist anymore! So now you know that you shouldn't upgrade that specific package or change your app to conform it.

Let's unit test asyncProcessMessages. We only want to know that array of items will contain meta data.

test('asyncProcessMessages', async () => {
  const note = { id: 1, messages: [] }
  const messages = [{ text: 'Test 1' }, { text: 'Test 2' }]
  const messagesHandler = { processMessages: () => Promise.resolve({}) }
  const result = await asyncProcessMessages({ note, messages, messagesHandler }) // don't need timeBegin
  expect(result).toEqual({
    id: 1,
    messages: [{ 
      text: 'Test 1',
      meta: {
        updatedAt: '2020-04-18',
        createdBy: 'Jane Doe',
      }
    }, {
      text: 'Test 2',
      meta: {
        updatedAt: '2020-04-18',
        createdBy: 'Art Vandelay',
      }
    }]
  })
})

See how you can now test only a piece of your functionality. This way tests become easier, if trivial is too much to say. (Let's pretend we know what getUpdatedAt and getCreatedBy return, otherwise we would make them as dependencies, too)

I hope with this article I helped other people in need of better application flow and easier testing. I wrote this article also for me to go back to it in dire times when complexity of monolith strikes me. Feel free to throw tomatoes at my face or give better suggestions - overall idea is let's write better software! Other ideas are more than welcome.