DEV Community: Stanislav Somov

A Quick Note On Hexagonal Architecture

Stanislav Somov — Tue, 14 Oct 2025 15:06:58 +0000

Intro

Let’s look at one of my favorite architecture patterns and understand it with a
simple example.

Everyday analogy

Imagine you need to connect your game console to a monitor. The console provides
an HDMI output; the monitor has a DVI input. You go to a store and buy an
HDMI-to-DVI cable, so the console doesn’t depend on a specific display device.
Another day you want to connect the console to a TV — just grab an HDMI-to-HDMI
cable and you’re good to go. You don’t need to swap the console or the monitor
because the console depends only on the HDMI port. That’s the main idea of
hexagonal architecture: keep the core independent, and make the “devices”
(adapters) modular and swappable.

From analogy to code

You can think of hexagonal architecture as a conversation between two entities,
mediated by a protocol (port). Your EmailService may need a database for
tracking emails, and it might ask: “I need retrieve and save functions. The
retrieve function should have the signature (emailId) -> Json, and the save
function should have the signature (emailId, fromId, toId, body) -> Status.”
Through that interface, it can speak with any external service (adapter) that
implements the protocol.

The database service will look at the protocol and
think: “Okay, I need to implement a save function that takes emailId, fromId,
toId, and body as parameters, and I need to return the status of the operation.”
Which database you use and how it works internally does not matter — these details
are hidden behind the port(protocol implementation). In TypeScript it may
look like this:

// Domain (core, framework-agnostic)
type UUID = string;

interface Email {
  readonly emailId: UUID;
  readonly fromId: UUID;
  readonly toId: UUID;
  readonly body: string;
}

// Outbound Port (driven port from the domain to the outside)
interface EmailRepository {
  save(fromId: UUID, toId: UUID, body: string): Promise<Email>;
  findById(emailId: UUID): Promise<Email | null>;
}

// In-memory Adapter (driving the port)
class InMemoryEmailRepo implements EmailRepository {
  private storage = new Map<UUID, Email>();

  async save(fromId: UUID, toId: UUID, body: string): Promise<Email> {
    const emailId = globalThis.crypto?.randomUUID?.() as UUID;
    const email: Email = { emailId, fromId, toId, body };
    this.storage.set(emailId, email);
    return email;
  }

  async findById(emailId: UUID): Promise<Email | null> {
    return this.storage.get(emailId) ?? null;
  }

  // test helper (not part of the port)
  getAll() {
    return Array.from(this.storage.values());
  }
}

// SQL Adapter (driving the port)
// NOTE: Replace the client with a real one (pg, mysql2, etc.)
type SQLClient = {
  query: (q: string, vals?: unknown[]) => Promise<{ rows: any[] }>;
};

class SQLEmailRepo implements EmailRepository {
  constructor(private client: SQLClient) { }

  async save(fromId: UUID, toId: UUID, body: string): Promise<Email> {
    const result = await this.client.query(
      `INSERT INTO email (email_id, from_id, to_id, body) VALUES ($1, $2, $3, $4)`,
      [ // generate id on app side for consistency with in-mem
        globalThis.crypto?.randomUUID?.(),
        fromId,
        toId,
        body,
      ],
    );
    const row = result.rows[0];
    return {
      emailId: row.email_id as UUID,
      fromId: row.from_id as UUID,
      toId: row.to_id as UUID,
      body: row.body as string,
    };
  }

  async findById(emailId: UUID): Promise<Email | null> {
    const result = await this.client.query(
      `SELECT email_id, from_id, to_id, body FROM email WHERE email_id = $1`,
      [emailId],
    );
    const row = result.rows[0];
    if (!row) return null;
    return {
      emailId: row.email_id as UUID,
      fromId: row.from_id as UUID,
      toId: row.to_id as UUID,
      body: row.body as string,
    };
  }
}

// Application Service (inbound port implementation)
class EmailService {
  constructor(private repo: EmailRepository) { }

  create(fromId: UUID, toId: UUID, body: string) {
    return this.repo.save(fromId, toId, body);
  }

  get(emailId: UUID) {
    return this.repo.findById(emailId);
  }
}

// --- Composition at the edges ---
// Example with in-memory adapter
const inMemService = new EmailService(new InMemoryEmailRepo());
await(async () => {
  const created = await inMemService.create("1", "2", "hi second!");
  const fetched = await inMemService.get(created.emailId);
  console.log({ created, fetched });
})();

// Example with SQL adapter (pseudo client)
const fakeSqlClient: SQLClient = {
  async query(q, vals) {
    // Stub: emulate DB returning a single row
    const [email_id, from_id, to_id, body] = vals as string[];
    return { rows: [{ email_id, from_id, to_id, body }] };
  },
};
const sqlService = new EmailService(new SQLEmailRepo(fakeSqlClient));
await(async () => {
  const created = await sqlService.create("10", "20", "over SQL!");
  const fetched = await sqlService.get(created.emailId);
  console.log({ created, fetched });
})();

As you can see, swapping one implementation for another is simple and
straightforward. This approach can also be used to inject other services. It can
even be used to compose use cases — for example, a user service can request an
external email service via this protocol:

interface EmailPort {
  sendEmail: (from: User, to: User, body: string) => Promise<Email | null>,
  getAllEmails: (user: User) =>  Promise<Email[]>
}

...and our email service will provide this functionality:

interface User {
  readonly id: UUID;
  readonly name: string;
}
class EmailService implements EmailPort {
  // ... previous methods
    async sendEmail(from: User, to: User, body: string): Promise<Email> {
    return this.create(from.id, to.id, body);
  }
  async getAllEmails(user: User): Promise<Email[]> {
    // Just a stub
    return [{ emailId: "1", fromId: user.id, toId: "", body: "..." }]
  }
}
class Person implements User {
  private emailService: EmailService;
  id: UUID;
  name: string;

  constructor(id: UUID, name: string, emailService: EmailService) {
    this.id = id;
    this.name = name;
    this.emailService = emailService;
  }

  async sendEmail(to: User, body: string) {
    await this.emailService.create(this.id, to.id, body);

    return `Email has been succefully sent from ${this.id} to ${to.id}`
  }
}

const p1 = new Person("1", "John", inMemService);

await p1.sendEmail({ id: "2", name: "Mary" }, "Hi! How is going?");

Let's sum it up.

First, think from the use-case perspective: what functions do you need from the
external service? Then, describe the protocol to be implemented by the external
service. Finally, compose the port and the adapter.

I hope this article helps you comprehend hexagonal architecture and build more
modular, robust, and maintainable software.

See you next time!

How to Make Coding Fun in JavaScript (Almost Like in Clojure)

Stanislav Somov — Tue, 23 Sep 2025 14:39:57 +0000

A REPL?! What is it?

REPL stands for Read-Eval-Print Loop, and in Clojure it’s the way to work with
code. It’s interactive, fast, and honestly just fun. You write some code, run it
immediately, and boom - you’ve got the result right there.

The problem with the default NodeJS REPL is that it’s not very practical for
everyday coding. Running it in a terminal isn’t convenient: you don’t see the
full picture, your code isn’t linted/checked beforehand, and you’re constantly
switching between the editor and the terminal, losing focus and context.

So, in this post I’ll show you how to make JavaScript coding way more
interactive and enjoyable - kinda like how people code in Clojure.

For example, in JavaScript you might write:

function add(a, b) { return a + b; }

To test it, you’d usually add some tests, or do something like:

console.log(add(36, 6));

Then run it with:

node index.js

That’s a lot of steps for a single result.

In Clojure, it’s much more direct:

(defn add [a b] (+ a b))
(add 35 7) ;; => 42

The feedback loop is immediate. (Of course, we still need proper tests for
real-world software, but for exploration and problem-solving, a REPL is very
effective.)

The Recipe

So how do we bring that to JavaScript?

I wrote an extension for the Conjure plugin
in Neovim. Setup is simple - just follow the
docs:

Install Neovim
Install Conjure
Install NodeJS
Install Treesitter and run :TSInstall javascript inside Neovim
Create a new ".js" file and open it in Neovim(for example: nvim repl-test.js in your terminal). Conjure should attach automatically if everything is setup correctly. That’s it - you’re ready to start evaluating JavaScript straight from your editor.

Why bother? Because once you’ve got this REPL loop going, you make fewer bugs,
you can actually feel the flow of your code, and you tweak things way faster.

Example:

const mult = (a, b) => a * b;
mult(3, 4);  // (out) 12
mult(5, 3);  // (out) 15
mult(10, 8); // (out) 80

Want to see the value of an expression quickly? Press <localleader>ee
(Conjure’s default). Need to explore an object? Just evaluate it:

const obj = { a: 1, b: { c: 3 } }; // eval this first
obj.b.c;                           // (out) 3

Debugging on the Fly

Checking intermediate steps becomes simple:

[1, 2, 2, 3].reduce((acc, x) => { 
  console.log("acc", acc);
  console.log("x", x);
  console.log("val", acc[x]);
  return { ...acc, [x]: ++acc[x] || 1 }; 
}, {});

You’ll instantly see each step in Conjure’s log buffer. No rerunning files, no
juggling terminals. Just... flow.

A Quick Clojure Example

Clojure developers often define a function and immediately test it inside a
(comment ...) block:

(defn name-extractor [m] (get m :name))
(comment 
   (name-extractor {:name "Kisha"}) ;; "Kisha"
   (name-extractor {:age 20}))      ;; nil

If we want to return :noname when the field is missing, we just adjust the
function:

(defn name-extractor [m]
   (get m :name :noname))

And if we want to handle empty strings as well:

(defn name-extractor [{:keys [name]}]
  (or (not-empty name) :noname))

Each step is tried and refined in the REPL.

Doing the Same in JavaScript

function nameExtractor({ name }) {
  return name || "noname";
}
nameExtractor({ name: "John" }); // 'John'
nameExtractor({ age: 15 });      // 'noname'
nameExtractor({ name: "" });     // 'noname'

Just like in Clojure, you can write small test cases inline and adapt the
function step by step.

Exploring RXJS

RXJS can feel abstract at first, but with the REPL you can experiment
interactively and see results as you go:

import { BehaviorSubject } from "rxjs"
import { combineLatestWith, map, tap } from "rxjs/operators"

let o1 = new BehaviorSubject({ a: 1 })
let o2 = new BehaviorSubject({ b: 6 })

o1.pipe(combineLatestWith(o2),
  tap(x => console.log("combined:", x)),
  map(([{ a }, { b }]) => a + b),
  tap(x => console.log("sum:", x))
).subscribe()

o1.next({ a: 2 })
o2.next({ b: 8 })

o1.unsubscribe()
o2.unsubscribe()

You can adjust values, rerun them, and instantly observe how the transformations
behave.

Useful Keybindings

<localleader>ef - evaluate the whole file
<localleader>ts - toggle Stray Out Mode (to see delayed evaluations like setTimeout)
<localleader>cr - restart the REPL (clears all previous evaluations)
<localleader>E - evaluate a selected block of text in visual mode (great for JSDoc examples)

NodeJS Quirks (Handled by Conjure)

Arrow functions can’t be redefined in the NodeJS REPL, but Conjure rewrites them as regular functions.
import isn’t supported in the NodeJS REPL, but Conjure translates it into require.

Wrapping Up

These tricks can make your workflow in JavaScript faster, more interactive, and
closer to the Clojure REPL style. A shorter feedback loop not only makes coding
more enjoyable, but also helps you write cleaner, more reliable code.