Forem

Making illegal state unrepresentable

Nicolas Fränkel — Thu, 23 Apr 2026 09:02:00 +0000

A couple of years ago, I wrote that The Builder pattern is a finite state machine!. A state machine consists of states and transitions between them. As a developer, I want to make illegal states unrepresentable, i.e., users of my API can't create non-existent transitions. My hypothesis is that only a static typing system allows this at compile-time. Dynamic typing systems rely on runtime validation.

In this blog post, I will show that it holds true, with a caveat. If your model has many combinations, you also need generics and other niceties to avoid too much boilerplate code. My exploration will use Python, Java, Kotlin, Rust, and Gleam. With that background in mind, let's move on to the model itself.

The model

I will keep the theme of the aforementioned post: a pizza. Here's the full model:

Every pizza starts with dough. Then, you need to choose your base, either regular tomato or cream. At this point, you can't add any ingredients to it. While you can add ham to both, pineapple is only acceptable on the tomato base, while potatoes are only compatible with the cream base.

The model is purposely simplistic, intentionally leaving out some options and complexities to maintain clarity. It primarily showcases how illegal transitions are represented and avoided. For example, you can't transition from CreamBase to CreamBase with withPineapple.

Modeling with Python

I chose to model with Python first to demonstrate how dynamically-typed languages manage illegal transitions.

Here are some types:

class Crust:
    pass

@dataclass(frozen=True)
class ThinCrust(Crust):
    pass

@dataclass(frozen=True)
class ThickCrust(Crust):
    pass

class Base:
    pass

@dataclass(frozen=True)
class CreamBase(Base):
    pass

@dataclass(frozen=True)
class TomatoBase(Base):
    pass

class Topping:
    pass

@dataclass(frozen=True)
class Potatoes(Topping):
    pass

@dataclass(frozen=True)
class Pineapple(Topping):
    pass

The builders look like:

class DoughBuilder:
    def __init__(self, crust: Crust) -> None:
        self._crust = crust

    def with_cream_base(self) -> "CreamBuilder":
        return CreamBuilder(self._crust, CreamBase(), frozenset())

    def with_tomato_base(self) -> "TomatoBuilder":
        return TomatoBuilder(self._crust, TomatoBase(), frozenset())


class CreamBuilder:
    def __init__(self, crust: Crust, base: CreamBase, toppings: frozenset[Topping]) -> None:
        self._crust = crust
        self._base = base
        self._toppings = toppings

    def with_potatoes(self) -> "CreamBuilder":
        return CreamBuilder(self._crust, self._base, self._toppings | {Potatoes()})

    def with_ham(self) -> "CreamBuilder":
        return CreamBuilder(self._crust, self._base, self._toppings | {Ham()})

    def with_olives(self) -> "CreamBuilder":
        return CreamBuilder(self._crust, self._base, self._toppings | {Olives()})

    def build(self) -> Pizza:
        return Pizza(self._crust, self._base, self._toppings)


class TomatoBuilder:
    def __init__(self, crust: Crust, base: TomatoBase, toppings: frozenset[Topping]) -> None:
        self._crust = crust
        self._base = base
        self._toppings = toppings

    def with_pineapple(self) -> "TomatoBuilder":
        return TomatoBuilder(self._crust, self._base, self._toppings | {Pineapple()})

    def with_ham(self) -> "TomatoBuilder":
        return TomatoBuilder(self._crust, self._base, self._toppings | {Ham()})

    def with_olives(self) -> "TomatoBuilder":
        return TomatoBuilder(self._crust, self._base, self._toppings | {Olives()})

    def build(self) -> Pizza:
        return Pizza(self._crust, self._base, self._toppings)

You can happily write:

pizza = dough(ThinCrust()).with_cream_base().with_potatoes().with_ham().build()
pizza = dough(ThinCrust()).with_cream_base().with_pineapple().with_ham().build()   # 1

Pineapple on a creamy base? Yuck!

Astute readers may have noticed that I used types in the Python code. Seasoned Python developers may use a type checker, e.g., mypy, to leverage them.

uv run mypy .

"CreamBuilder" has no attribute "with_pineapple"  [attr-defined]

Without mypy, the call fails at runtime with an AttributeError.

Python's gradual typing proves that static typing helps avoid calling non-existent transitions. However, because of the way Python works, one needs to invoke a dedicated type checker. In statically-typed languages, it's unnecessary.

Modeling with Java

Let's do the same exercise with Java.

Here's the model:

public sealed interface Crust permits ThinCrust, ThickCrust {}
public record ThinCrust() implements Crust {}
public record ThickCrust() implements Crust {}

sealed interface BaseState permits CreamBase, TomatoBase {}
record CreamBase() implements BaseState {}
record TomatoBase() implements BaseState {}

And here are the builders:

public class DoughBuilder {

    private final Crust crust;

    private DoughBuilder(Crust crust) {
        this.crust = crust;
    }

    public static DoughBuilder dough(Crust crust) {
        return new DoughBuilder(crust);
    }

    CreamBaseBuilder withCreamBase() {
        return new CreamBaseBuilder(crust, new CreamBase());
    }

    TomatoBaseBuilder withTomatoBase() {
        return new TomatoBaseBuilder(crust, new TomatoBase());
    }
}

class CreamBaseBuilder {

    private final Crust crust;
    private final CreamBase base;
    private final List<Topping> toppings;

    CreamBaseBuilder(Crust crust, CreamBase base) {
        this(crust, base, List.of());
    }

    private CreamBaseBuilder(Crust crust, CreamBase base, List<Topping> toppings) {
        this.crust = crust;
        this.base = base;
        this.toppings = toppings;
    }

    CreamBaseBuilder withPotatoes() {
        return new CreamBaseBuilder(crust, base, append(new Potatoes()));
    }

    CreamBaseBuilder withHam() {
        return new CreamBaseBuilder(crust, base, append(new Ham()));
    }

    CreamBaseBuilder withOlives() {
        return new CreamBaseBuilder(crust, base, append(new Olives()));
    }

    Pizza build() {
        return new Pizza(crust, base, Set.copyOf(toppings));
    }

    private List<Topping> append(Topping topping) {
        return Stream.concat(toppings.stream(), Stream.of(topping)).toList();
    }
}

class TomatoBaseBuilder {

    private final Crust crust;
    private final TomatoBase base;
    private final List<Topping> toppings;

    TomatoBaseBuilder(Crust crust, TomatoBase base) {
        this(crust, base, List.of());
    }

    private TomatoBaseBuilder(Crust crust, TomatoBase base, List<Topping> toppings) {
        this.crust = crust;
        this.base = base;
        this.toppings = toppings;
    }

    TomatoBaseBuilder withPineapple() {
        return new TomatoBaseBuilder(crust, base, append(new Pineapple()));
    }

    TomatoBaseBuilder withHam() {
        return new TomatoBaseBuilder(crust, base, append(new Ham()));
    }

    TomatoBaseBuilder withOlives() {
        return new TomatoBaseBuilder(crust, base, append(new Olives()));
    }

    Pizza build() {
        return new Pizza(crust, base, Set.copyOf(toppings));
    }

    private List<Topping> append(Topping topping) {
        return Stream.concat(toppings.stream(), Stream.of(topping)).toList();
    }
}

There's no way we can call withPineapple() on a CreamBase: we didn't declare the method, and compilation fails. However, imagine more combinations: an additional sweet base, or ingredients incompatible with others, e.g., no anchovies with pineapple. This would create additional states, represented as classes, and transitions, as methods. Soon, you'll face an explosion of combinations, which would require lots of boilerplate code. For example, with the anchovies/pineapple exclusion, you'd need two more base classes: TomatoBaseWithPineappleBuilder and TomatoBaseWithAnchoviesBuilder.

Java is not a good fit for creating smart builders. Let's see if other languages may improve the situation.

Modeling with Kotlin

The Kotlin model is pretty similar to the Java one:

sealed interface Crust
data object ThinCrust : Crust
data object ThickCrust : Crust

sealed interface BaseState
data object CreamBase : BaseState
data object TomatoBase : BaseState

sealed interface Topping
data object Ham : Topping
data object Olives : Topping
data object Potatoes : Topping
data object Pineapple : Topping

The builder approach is pretty different, though:

class DoughBuilder internal constructor(internal val crust: Crust)

class PizzaBuilder<out S : BaseState> internal constructor( // 1 // 2
    internal val crust: Crust,
    internal val base: BaseState,
    internal val toppings: List<Topping>,
)

fun dough(crust: Crust): DoughBuilder = DoughBuilder(crust)

fun DoughBuilder.withCreamBase() =
    PizzaBuilder<CreamBase>(crust, CreamBase, emptyList())                         // 3
fun DoughBuilder.withTomatoBase() =
    PizzaBuilder<TomatoBase>(crust, TomatoBase, emptyList())                       // 3
fun PizzaBuilder<CreamBase>.withPotatoes() =
    PizzaBuilder<CreamBase>(crust, base, toppings + Potatoes)                      // 3
fun PizzaBuilder<TomatoBase>.withPineapple() =
    PizzaBuilder<TomatoBase>(crust, base, toppings + Pineapple)                    // 3
fun <S : BaseState> PizzaBuilder<S>.withHam() =
    PizzaBuilder<S>(crust, base, toppings + Ham)                                   // 3 // 4
fun <S : BaseState> PizzaBuilder<S>.withOlives() =
    PizzaBuilder<S>(crust, base, toppings + Olives)                                // 3 // 4
fun <S : BaseState> PizzaBuilder<S>.build() = Pizza(crust, base, toppings.toSet())

Generics on the parent class are possible in Java, but it lacks what comes next.
out is Kotlin's syntax for covariance: a PizzaBuilder<CreamBase> can be used where a PizzaBuilder<BaseState> is expected. The upper bound : BaseState separately constrains S to BaseState and its subclasses.
Function extensions are Kotlin-specific. Instead of creating different subclasses as in Java, we keep a single one, but extend each generic type with the relevant function.
For transitions that are common to both bases, generics help us return the same type. This way, we can define the function once on the generic type.

If we were to add pineapple/anchovies exclusion as in Java, we would need a slight change in the existing hierarchy:

sealed interface TomatoBase : BaseState
data object Tomato : TomatoBase

And then, add the states and the transitions:

data object TomatoWithPineapple : TomatoBase
data object TomatoWithAnchovies : TomatoBase

fun PizzaBuilder<TomatoBase>.withPineapple(): PizzaBuilder<TomatoWithPineapple> = TODO()
fun PizzaBuilder<TomatoBase>.withAnchovies(): PizzaBuilder<TomatoWithAnchovies> = TODO()

Finally, you'd define the exclusive transitions on the new types with extension functions.

In Kotlin, unlike Java, adding a new constraint requires only new type markers and extension functions — the growth is linear, not combinatorial.

Modeling with Rust

Rust isn't an Object-Oriented programming language, contrary to Kotlin. Let's examine what we can learn from it.

The model part is quite straightforward:

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Crust {
    Thin,
    Thick,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum Base {
    Cream,
    Tomato,
}

pub struct HasDough;
pub struct CreamBase;
pub struct TomatoBase;

pub struct Pizza {
    crust: Crust,
    base: Base,
    ham: bool,
    olives: bool,
    potatoes: bool,
    pineapple: bool,
}

Interestingly enough, the design is pretty similar to Java's:

#[derive(Default)]
struct ToppingState {
    ham: bool,
    olives: bool,
    potatoes: bool,
    pineapple: bool,
}

pub struct PizzaBuilder<S> {
    crust: Crust,
    toppings: ToppingState,
    _marker: std::marker::PhantomData<S>,                                          // 1
}

impl PizzaBuilder<HasDough> {
    pub fn dough(crust: Crust) -> PizzaBuilder<HasDough> {
        PizzaBuilder {
            crust,
            toppings: ToppingState::default(),
            _marker: std::marker::PhantomData,                                     // 1
        }
    }

    pub fn with_cream_base(self) -> PizzaBuilder<CreamBase> {
        PizzaBuilder {
            crust: self.crust,
            toppings: self.toppings,
            _marker: std::marker::PhantomData,                                     // 1
        }
    }

    pub fn with_tomato_base(self) -> PizzaBuilder<TomatoBase> {
        PizzaBuilder {
            crust: self.crust,
            toppings: self.toppings,
            _marker: std::marker::PhantomData,                                     // 1
        }
    }
}

impl PizzaBuilder<CreamBase> {
    pub fn with_potatoes(mut self) -> Self {
        self.toppings.potatoes = true;
        self
    }

    pub fn with_ham(mut self) -> Self {
        self.toppings.ham = true;
        self
    }

    pub fn with_olives(mut self) -> Self {
        self.toppings.olives = true;
        self
    }

    pub fn build(self) -> Pizza {
        Pizza::new(
            self.crust,
            Base::Cream,
            self.toppings.ham,
            self.toppings.olives,
            self.toppings.potatoes,
            self.toppings.pineapple,
        )
    }
}

impl PizzaBuilder<TomatoBase> {
    pub fn with_pineapple(mut self) -> Self {
        self.toppings.pineapple = true;
        self
    }

    pub fn with_ham(mut self) -> Self {
        self.toppings.ham = true;
        self
    }

    pub fn with_olives(mut self) -> Self {
        self.toppings.olives = true;
        self
    }

    pub fn build(self) -> Pizza {
        Pizza::new(
            self.crust,
            Base::Tomato,
            self.toppings.ham,
            self.toppings.olives,
            self.toppings.potatoes,
            self.toppings.pineapple,
        )
    }
}

Phantom type. See section Phantom types below.

Java and Rust have fundamental differences in approaches: the former uses a runtime, and the latter compiles to native. Yet, from a pure language syntax point of view, Rust impl maps more or less to a Java subclass in this context.

We would get the same combinatory explosion for anchovies and pineapple.

Modeling with Gleam

Gleam is a recent programming language that runs on the BEAM. As of now, I'd say I'm proficient in Java and Kotlin, thus covering the JVM. Kotlin also allows JavaScript transpilation for the browser. I'm able to write quite a bit in Python, and consider myself a Rust newbie. The BEAM is outside my reach, and I wanted to widen my options. Erlang is dynamically-typed, and Elixir is a bit too esoteric. Gleam's syntax is a bit similar to Rust's.

Note: Given my limited knowledge of Gleam, I used Claude Code a lot in this section. I'll be happy to receive feedback from Gleam programmers as I'm still learning.

Types are declared as:

pub type Crust {
  Thin
  Thick
}

pub type Topping {
  Potatoes
  Pineapple
  Ham
  Olives
}

pub type Base {
  CreamBase
  TomatoBase
}

pub type Cream {
  Cream
}

pub type Tomato {
  Tomato
}

pub opaque type Pizza {                                                            // 1
  Pizza(crust: Crust, base: Base, toppings: List(Topping))
}

opaque is Gleam's way to hide the constructor from outside the module

Then the builder looks like:

pub opaque type DoughBuilder {                                                     // 1
  DoughBuilder(crust: Crust)
}

pub opaque type PizzaBuilder(base) {                                               // 1
  PizzaBuilder(crust: Crust, base: Base, toppings: List(Topping))
}

pub fn dough(crust: Crust) -> DoughBuilder {
  DoughBuilder(crust: crust)
}

pub fn with_cream_base(builder: DoughBuilder) -> PizzaBuilder(Cream) {
  let DoughBuilder(crust: crust) = builder
  PizzaBuilder(crust: crust, base: CreamBase, toppings: [])
}

pub fn with_tomato_base(builder: DoughBuilder) -> PizzaBuilder(Tomato) {
  let DoughBuilder(crust: crust) = builder
  PizzaBuilder(crust: crust, base: TomatoBase, toppings: [])
}

pub fn with_potatoes(builder: PizzaBuilder(Cream)) -> PizzaBuilder(Cream) {        // 2
  let PizzaBuilder(crust: crust, base: base, toppings: toppings) = builder
  PizzaBuilder(crust: crust, base: base, toppings: [Potatoes, ..toppings])
}

pub fn with_pineapple(builder: PizzaBuilder(Tomato)) -> PizzaBuilder(Tomato) {     // 2
  let PizzaBuilder(crust: crust, base: base, toppings: toppings) = builder
  PizzaBuilder(crust: crust, base: base, toppings: [Pineapple, ..toppings])
}

pub fn with_ham(builder: PizzaBuilder(a)) -> PizzaBuilder(a) {                     // 3
  let PizzaBuilder(crust: crust, base: base, toppings: toppings) = builder
  PizzaBuilder(crust: crust, base: base, toppings: [Ham, ..toppings])
}

pub fn with_olives(builder: PizzaBuilder(a)) -> PizzaBuilder(a) {                  // 3
  let PizzaBuilder(crust: crust, base: base, toppings: toppings) = builder
  PizzaBuilder(crust: crust, base: base, toppings: [Olives, ..toppings])
}

pub fn build(builder: PizzaBuilder(a)) -> Pizza {
  let PizzaBuilder(crust: crust, base: base, toppings: toppings) = builder
  Pizza(crust: crust, base: base, toppings: list.reverse(toppings))
}

Hide the constructor from outside the module
Specific transitions
Common transitions

Adding anchovies topping exclusive to pineapple would require: adding the new states as types and the transitions as functions. As in Kotlin, it would be a linear code expansion, thanks to the generic PizzaBuilder(a) parameter and return type for common transitions.

Phantom types

Kotlin, Rust, and Gleam all allow a generic type on PizzaBuilder. While the syntax is different and the naming differs, phantom data in Rust, phantom type in Gleam, the concept stays the same: use generic types to enforce typing at compilation time, while letting go of them at runtime.

Here's the Kotlin code above, simplified:

class PizzaBuilder<out S : BaseState>

fun PizzaBuilder<CreamBase>.withPotatoes() = TODO()
fun PizzaBuilder<TomatoBase>.withPineapple() = TODO()

The magic is the S generic in the PizzaBuilder. It allows grafting extension functions based on this type. withPotatoes() only applies when S is CreamBase, withPineapple() when it's TomatoBase. Without a generic type, you can't constrain extension functions. However, S isn't used in any other place: it's effectively a phantom type, hence the name.

Gleam splits between types and functions. While this design is quite different from Kotlin's, it also enables phantom types to constrain functions depending on the phantom type.

The Rust compiler effectively disallows unused types, so you need to reference it somehow. Hence, you need a _marker: std::marker::PhantomData attribute: it's a zero-cost abstraction, discarded in the compiled code and useful only for the compiler. The leading underscore is a Rust convention that suppresses Rust's dead-code warning.

Note that despite Java having generics, its lack of extension functions or related mechanisms prevents attaching methods to a specific generic type.

Conclusion

Static typing is the solid foundation that prevents illegal state transitions. Yet, you need more to design a model that doesn't degrade quickly. Without phantom types and a way to leverage them to bind specific functions to them, each new state adds combinatorial complexity. The exact mechanism depends on the language: extension functions in Kotlin, impl blocks in Rust, and constrained parameter types in Gleam.

The complete source code for this post can be found on Codeberg.

To go further:

Originally published at A Java Geek on April 19^th, 2026.

Stop memorizing JS — think in execution context

Samaresh Das — Thu, 23 Apr 2026 09:00:55 +0000

Forget remembering JavaScript syntax; it's a crutch.

What if I told you that the key to truly understanding JavaScript isn't memorizing endless functions and methods, but grasping how the code actually runs? This article is about shifting your focus from rote learning to thinking about JavaScript's execution context.

Every time your JavaScript code runs, the engine creates an "execution context." Think of it as a mini-environment where your code gets evaluated. There are two main types: the Global Execution Context (the default one for your entire script) and the Function Execution Context (created each time a function is called).

Within each context, two crucial things happen: the creation phase and the execution phase. During creation, the engine sets up the Variable Environment (where var, let, const, and function declarations are stored) and the this binding. It also creates the scope chain.

Then comes the execution phase, where the actual JavaScript code is run line by line. This is where let and const declarations are put into a "temporal dead zone" until their declaration is reached, while var variables are initialized with undefined.

Let's look at a simple example.

console.log(a); // undefined
var a = 10;
console.log(a); // 10

// sayHello(); // This would throw an error
// let sayHello = () => {
//   console.log("Hello!");
// };

The first console.log(a) outputs undefined because var a is hoisted to the top of its scope and initialized with undefined during the creation phase, before the execution phase reaches var a = 10;. If a were declared with let or const, the first console.log would actually throw a ReferenceError because of the temporal dead zone.

Understanding execution context helps untangle confusing behavior, especially with asynchronous operations and closures. It's the "why" behind what your code is doing.

For me, this mindset shift was a game-changer. It's what allows me to build complex websites and apps as a freelancer. If you're ever looking for someone to build your next web project, you can check out my portfolio here: https://hire-sam.vercel.app/

The real superpower in JavaScript isn't memorization, it's understanding the runtime.

Follow for more dev content

Building a Privacy-First URL Shortener on Blockchain

Wes Parsons — Thu, 23 Apr 2026 09:00:02 +0000

Why Traditional URL Shorteners Are a Privacy Nightmare

When you click a bit.ly link, here's what happens:

Bit.ly logs your IP, timestamp, user agent
They see the destination URL
They track your browsing patterns
They sell this data to advertisers

Even if you trust the shortener, their database can be hacked.

Introducing Cryptly

I built cryptly to solve this problem using blockchain and encryption.

How It Works

Encryption (Client-Side)

   const encrypted = await crypto.subtle.encrypt(
     { name: "AES-GCM", iv: iv },
     key,
     urlBuffer
   );

Blockchain Storage
- Encrypted URL stored on Cronos blockchain
- Immutable, decentralized
- No centralized database to hack
Decryption (Browser)
- Browser fetches from blockchain
- Decrypts locally using Web Crypto API
- Server never sees destination

Architecture

Tech Stack:

Cloudflare Workers (serverless, edge deployment)
Web Crypto API (native browser encryption)
Cronos blockchain (decentralized storage)

Privacy Benefits:

✅ Server never sees destination URLs
✅ No tracking, no analytics
✅ No database to leak
✅ Censorship-resistant (blockchain)

Try It

Live demo: cryptly.workers.dev
GitHub: github.com/your-username/cryptly

Still in early stages but feedback welcome!

privacy #blockchain #webdev #opensource

CQRS in Go — Part 4: PostgreSQL as an event store

Odilon HUGONNOT — Thu, 23 Apr 2026 09:00:02 +0000

CQRS in Go series:

Part 1: the aggregate, Transition() and Clone()
Part 2: command handlers without side effects
Part 3: sagas and event choreography
Part 4: PostgreSQL as an event store

The first three parts laid the groundwork: immutable aggregates, pure command handlers, sagas through choreography. One central question remains — where do we persist the events? This part answers that question using PostgreSQL as an append-only event store, with no additional dependencies.

Why PostgreSQL and not EventStoreDB or Kafka

EventStoreDB is an excellent tool, designed specifically for event sourcing. But it's an additional component to deploy, monitor, back up, and maintain. For a team already running PostgreSQL in production, adding EventStoreDB means doubling the operational footprint for a database.

Kafka is often mentioned in this context. It's a message bus, not an event store. Reading by aggregate ID is not its strong suit — Kafka is optimized for sequential partition consumption, not for "give me all events for order CMD-4521 in order". Default retention is time-limited. Reconstituting an aggregate from Kafka requires non-trivial work.

PostgreSQL, you already have it. Native ACID, JSONB with indexing, backups integrated into your existing infrastructure, monitoring your team knows, pg_dump, replication, point-in-time recovery. For 90% of projects, an append-only table in PostgreSQL is more than enough. Moving to a dedicated tool makes sense when you're processing millions of events per second — a threshold most projects never reach.

The es_events table — the core

Everything rests on a single table:

CREATE TABLE es_events (
    id            BIGSERIAL PRIMARY KEY,
    aggregate_id  UUID NOT NULL,
    aggregate_type VARCHAR(64) NOT NULL,
    event_type    VARCHAR(128) NOT NULL,
    event_data    JSONB NOT NULL,
    metadata      JSONB DEFAULT '{}',
    version       INT NOT NULL,
    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    UNIQUE (aggregate_id, version)
);

CREATE INDEX idx_es_events_aggregate ON es_events (aggregate_id, version);

Each column has a specific role:

id (BIGSERIAL): global position in the stream. This is the cursor used by projectors to track where they are. Monotonically increasing, never reused.
aggregate_id: the identifier of the entity involved — the UUID of the order, payment, or shipment. This is the primary read key for reconstituting an aggregate.
aggregate_type: the type of the aggregate — "order", "payment", "shipping". Allows filtering events by domain and avoids UUID collisions between different types.
event_type: the name of the event — "OrderPlaced", "PaymentConfirmed", "ShipmentDispatched". Used to deserialize event_data into the correct Go type.
event_data (JSONB): the serialized event payload. JSONB enables indexing and field-level queries when needed, without sacrificing flexibility.
metadata (JSONB): traceability information — who triggered the action (user ID), correlation ID, causation ID, client timestamp. Not domain data, but indispensable in production.
version: sequence number per aggregate. The first event of an aggregate is at version 1, the second at version 2, and so on.

The UNIQUE (aggregate_id, version) constraint is the centerpiece of concurrent safety. It makes it impossible to insert two events with the same version on the same aggregate. This is the optimistic locking mechanism — no read lock, a constraint violation on write in case of conflict.

Append — writing an event

type EventStore struct {
    db *sqlx.DB
}

func (s *EventStore) Append(ctx context.Context, aggregateID uuid.UUID, aggregateType string, expectedVersion int, events []StorableEvent) error {
    tx, err := s.db.BeginTxx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin tx: %w", err)
    }
    defer tx.Rollback()

    for i, event := range events {
        version := expectedVersion + i + 1

        data, err := json.Marshal(event.Data)
        if err != nil {
            return fmt.Errorf("marshal event: %w", err)
        }

        _, err = tx.ExecContext(ctx, `
            INSERT INTO es_events (aggregate_id, aggregate_type, event_type, event_data, metadata, version)
            VALUES ($1, $2, $3, $4, $5, $6)
        `, aggregateID, aggregateType, event.Type, data, event.Metadata, version)

        if err != nil {
            // UNIQUE violation = version conflict = optimistic locking
            if isUniqueViolation(err) {
                return ErrConcurrencyConflict
            }
            return fmt.Errorf("insert event: %w", err)
        }
    }

    return tx.Commit()
}

The expectedVersion parameter is the number of the last known event at the time the aggregate was loaded. If the handler produces two events, they will be inserted at versions expectedVersion + 1 and expectedVersion + 2.

If another goroutine wrote an event between loading and writing, the UNIQUE constraint kicks in — PostgreSQL rejects the insert with a constraint violation, translated into ErrConcurrencyConflict. The client can retry: it will reload the aggregate with the new event, recalculate the state, and re-execute the handler. This is optimistic locking — no read lock, just a check at write time.

Load — reloading an aggregate

func (s *EventStore) Load(ctx context.Context, aggregateID uuid.UUID) ([]StoredEvent, error) {
    var events []StoredEvent

    err := s.db.SelectContext(ctx, &events, `
        SELECT id, aggregate_id, aggregate_type, event_type, event_data, metadata, version, created_at
        FROM es_events
        WHERE aggregate_id = $1
        ORDER BY version ASC
    `, aggregateID)

    if err != nil {
        return nil, fmt.Errorf("loading events: %w", err)
    }

    return events, nil
}

The aggregate's state is never stored directly. It's always recalculated by replaying events in order, calling Transition() on each one (see Part 1). This is the replay. The result is deterministic — the same events always produce the same state. This is what makes the system testable and auditable.

Subscriptions — feeding projections

Projectors — the components that maintain read views — must be notified of new events. The simplest solution: a positions table.

CREATE TABLE es_subscriptions (
    subscriber_id  VARCHAR(128) PRIMARY KEY,
    last_event_id  BIGINT NOT NULL DEFAULT 0,
    updated_at     TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Each projector records the identifier of the last event it processed. On startup or after a crash, it resumes from this position. The polling pattern:

type Subscriber struct {
    db           *sqlx.DB
    subscriberID string
    handler      EventHandler
}

func (s *Subscriber) Poll(ctx context.Context) error {
    // 1. Read the last processed position
    var lastID int64
    s.db.GetContext(ctx, &lastID,
        "SELECT last_event_id FROM es_subscriptions WHERE subscriber_id = $1",
        s.subscriberID,
    )

    // 2. Load new events
    var events []StoredEvent
    s.db.SelectContext(ctx, &events,
        "SELECT * FROM es_events WHERE id > $1 ORDER BY id ASC LIMIT 100",
        lastID,
    )

    // 3. Process within a transaction
    for _, event := range events {
        tx, _ := s.db.BeginTxx(ctx, nil)

        if err := s.handler.Handle(ctx, tx, event); err != nil {
            tx.Rollback()
            return fmt.Errorf("handling event %d: %w", event.ID, err)
        }

        // 4. Update the position in the same transaction
        tx.ExecContext(ctx,
            "UPDATE es_subscriptions SET last_event_id = $1, updated_at = NOW() WHERE subscriber_id = $2",
            event.ID, s.subscriberID,
        )

        tx.Commit()
    }

    return nil
}

The critical detail is in point 4: the position update and event processing are in the same transaction. If the process crashes between processing and updating the position, the event will be reprocessed on the next poll. This is at-least-once delivery — handlers must be idempotent to absorb duplicates without side effects.

Idempotency in practice: a handler that inserts a row into a read view can use INSERT ... ON CONFLICT DO NOTHING, or check whether the row already exists. The deduplication key is generally the event_id or a combination of unique business fields.

Real-time notifications with LISTEN/NOTIFY

Polling introduces latency — at best a few hundred milliseconds if the poll runs frequently, at worst several seconds. For read views that need to be reactive, PostgreSQL offers a native mechanism: LISTEN/NOTIFY.

// Event store side: notify after each INSERT
func (s *EventStore) Append(ctx context.Context, aggregateID uuid.UUID, aggregateType string, expectedVersion int, events []StorableEvent) error {
    tx, err := s.db.BeginTxx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin tx: %w", err)
    }
    defer tx.Rollback()

    // ... insert events ...

    // Notify subscribers
    if _, err := tx.ExecContext(ctx, "NOTIFY es_events_channel"); err != nil {
        return fmt.Errorf("notify: %w", err)
    }

    return tx.Commit()
}

// Subscriber side: listen instead of polling
func (s *Subscriber) Listen(ctx context.Context) error {
    conn, err := s.db.Conn(ctx)
    if err != nil {
        return fmt.Errorf("acquire conn: %w", err)
    }
    defer conn.Close()

    if _, err := conn.ExecContext(ctx, "LISTEN es_events_channel"); err != nil {
        return fmt.Errorf("listen: %w", err)
    }

    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
        }

        // Wait for notification (blocking with timeout)
        _, err := conn.WaitForNotification(ctx)
        if err != nil {
            return fmt.Errorf("wait notification: %w", err)
        }

        // Poll immediately after the notification
        if err := s.Poll(ctx); err != nil {
            return err
        }
    }
}

The notification is sent inside the Append transaction — it's only delivered to listeners once the transaction commits. No false alarms on rollback.

In production, combine both approaches: LISTEN for real-time reactivity under normal conditions, periodic polling (every 5 to 30 seconds) as a safety net in case of reconnection or missed notification. The dedicated LISTEN connection must not be taken from the standard connection pool — it occupies a connection permanently.

The command gateway — putting it all together

With the event store in place, the complete flow for a command becomes explicit:

type CommandGateway struct {
    store *EventStore
}

func (gw *CommandGateway) Execute(ctx context.Context, aggregateID uuid.UUID, cmd Command, handler CommandHandler) error {
    // 1. Load events
    storedEvents, err := gw.store.Load(ctx, aggregateID)
    if err != nil {
        return fmt.Errorf("load aggregate: %w", err)
    }

    // 2. Reconstruct state
    state := Replay(storedEvents)
    currentVersion := len(storedEvents)

    // 3. Execute the handler (pure, no side effects)
    newEvents, err := handler.Handle(ctx, state, cmd)
    if err != nil {
        return err
    }

    // 4. Persist the new events
    return gw.store.Append(ctx, aggregateID, cmd.AggregateType(), currentVersion, newEvents)
}

If two commands arrive simultaneously on the same aggregate, the second fails with ErrConcurrencyConflict. The client can retry — it will reload the aggregate including the events from the first command, recalculate the state, and re-execute the handler on the updated state. In practice, real conflicts are rare on well-bounded aggregates; most concurrent operations touch different aggregates.

This is also the pattern that makes command handlers testable without infrastructure (Part 2): the gateway injects the state, the handler produces events, the gateway persists. Each responsibility is isolated.

Performance — when events accumulate

An aggregate with a few dozen events reloads in microseconds. An aggregate with 10,000 events — a long-lived order, a very active user account — starts to weigh on the replay. The solution is snapshots.

CREATE TABLE es_snapshots (
    aggregate_id   UUID PRIMARY KEY,
    aggregate_type VARCHAR(64) NOT NULL,
    version        INT NOT NULL,
    state_data     JSONB NOT NULL,
    created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

A snapshot is a captured, serialized state at a given point in time, associated with its version. Loading with a snapshot proceeds in two steps:

Load the most recent snapshot for the aggregate (if it exists)
Load only the events after the snapshot's version
Replay the partial events on the snapshot's state

The simplest practical rule: create a snapshot every 100 events. Most aggregates never reach this limit — a typical e-commerce aggregate generates 5 to 20 events over its lifetime. Snapshots are only necessary for high-volume aggregates: accounts, wallets, inventories updated hundreds of times per day.

Important: snapshots are an optimization, not a change to the data model. Events remain the source of truth. A corrupted or deleted snapshot is not data loss — the aggregate can be reconstituted from the beginning of its events.

Series summary

Across four parts, we built a complete CQRS implementation in Go:

Part 1 — The aggregate: immutable state, Transition() for applying events, Clone() for dry-runs. The foundation that makes everything else testable.
Part 2 — Command handlers: pure functions that take a state and a command, return events or an error. No database, no HTTP, testable in complete isolation.
Part 3 — Sagas and choreography: coordination between aggregates through published events. Each service reacts to what interests it, without direct coupling. Sagas handle compensation in case of distributed failure.
Part 4 — The event store: PostgreSQL as the persistence infrastructure. Append-only table, optimistic locking through UNIQUE constraint, subscriptions for projectors, LISTEN/NOTIFY for reactivity, snapshots for large-scale performance.

These four patterns combine: the command gateway loads via the event store, calls the pure handler, persists the produced events. Subscribers read the global stream and maintain read views. Sagas listen for certain event types and trigger commands on other aggregates.

The result is a system that is auditable by construction — the complete history is in the events —, testable at every layer, and operable with the PostgreSQL infrastructure you already manage.

📄 Associated CLAUDE.md

View • Download • Catalogue

10 AI Tools Every Developer Should Try in 2026

Vasyl Popovych — Thu, 23 Apr 2026 08:56:09 +0000

The reality of modern development is brutal. You open your laptop at 9 AM with a clear plan: finish that feature by lunch. But first, there's a standup meeting that runs long. Then Slack explodes with questions about yesterday's deployment. Your IDE throws a cryptic error that sends you down a Stack Overflow rabbit hole. By noon, you haven't written a single line of production code.

According to Stack Overflow's 2024 Developer Survey, which polled over 65,000 developers worldwide, the average developer spends just 3.5 hours per day actually writing code. The rest vanishes into meetings, code reviews, documentation, debugging, and what one survey respondent called "context-switching hell." A study from the University of California Irvine found that it takes 23 minutes to fully regain focus after an interruption. With the average developer facing 12+ interruptions daily, that's four hours of productive time lost before you even factor in the work itself.

The problem isn't that developers are inefficient. It's that we're drowning in overhead. Email hasn't fundamentally changed since the 1990s. Project management tools are basically digital sticky notes. We generate more data than we can analyze and create more tasks than we can possibly complete.

But here's the shift: AI tools have finally moved beyond the hype cycle into genuinely useful territory. Not the kind that promises to replace developers (spoiler: that's not happening), but tools that eliminate the friction points eating your day. According to GitHub's research, developers using AI coding assistants complete tasks 55% faster in controlled experiments. Stack Overflow's 2024 survey shows 76% of developers are now using or planning to use AI tools, up from 70% the previous year.

More importantly, 82% of developers currently use AI tools for writing code, while 68% use them for searching for answers. The tools below aren't theoretical. They're battle-tested solutions that developers are using right now to reclaim their time and focus on work that actually matters.

1. GitHub Copilot: The AI Pair Programmer That Actually Delivers

GitHub Copilot has become the most widely adopted AI coding assistant, and the statistics back up the hype. As of early 2025, Copilot reached 20 million users with 4.7 million paid subscribers, according to multiple industry reports. More impressively, 90% of Fortune 100 companies have adopted it.

The real story is in the productivity numbers. GitHub's own controlled research study found that developers using Copilot completed an HTTP server implementation in JavaScript 55% faster than those without it. Task completion time dropped from 2 hours and 41 minutes to just 1 hour and 11 minutes. Success rates improved from 70% to 78%.

What makes Copilot genuinely useful isn't that it writes perfect code (it doesn't). It handles the boilerplate that nobody wants to write. Need to parse a CSV? Write unit tests? Set up API endpoints? Copilot generates the repetitive logic while you focus on architecture and business logic.

According to data compiled from various enterprise deployments, Copilot now writes approximately 46% of code on average, reaching as high as 61% in Java projects. The acceptance rate for suggestions sits around 30%, meaning developers find roughly one in three suggestions valuable enough to use directly. Most importantly, 88% of Copilot-generated code stays in the final version after review.
GitHub's research found that 73% of developers reported that Copilot helped them stay in flow state, and 87% said it preserved mental effort during repetitive tasks. When you're not fighting with boilerplate, you have more energy for the hard problems.

Pricing is $10/month for individuals, $19/month for business users, and $39/month for enterprise. The individual plan is a no-brainer for freelancers. For teams, the business plan includes privacy guarantees that your code isn't used for training.

2. Cursor: The AI-Native Code Editor

Cursor took a different approach than Copilot. Instead of being an extension, it's a complete IDE built around AI from the ground up. The results speak for themselves: Cursor became the fastest-growing SaaS product ever to reach $100 million in annual recurring revenue, hitting that milestone in just 12 months.

By early 2025, Cursor had over 1 million users with 360,000 paying customers, achieved almost entirely through word-of-mouth. The company's valuation hit $2.6 billion in January 2025, with revenue projected to reach $200 million in 2025. More than half of Fortune 500 companies now use Cursor, according to company reports from mid-2025.

What sets Cursor apart is context awareness across your entire codebase. You can ask it "where is user authentication handled?" and it points you to the relevant files. Tell it "add rate limiting to all API endpoints" and it makes consistent changes across multiple files. According to JetBrains' January 2026 AI Pulse survey, 18% of developers use Cursor at work, making it the second most popular AI coding tool after GitHub Copilot (29%).

Enterprise users report remarkable results. Companies using Cursor see PR volume increase by over 25% and average PR size double, meaning they're shipping approximately 50% more code. One engineering manager noted that adoption in their organization grew from 150 to over 500 engineers (60% of the org) in just a few weeks.

Enterprise users report remarkable results. Companies using Cursor see PR volume increase by over 25% and average PR size double, meaning they're shipping approximately 50% more code — a level of efficiency that mirrors how modern home services platforms have streamlined on-demand work across industries. One engineering manager noted that adoption in their organization grew from 150 to over 500 engineers (60% of the org) in just a few weeks

The editor feels like VS Code (it's built on the same foundation) but treats AI as a first-class feature. In head-to-head comparisons, 93% of engineers prefer Cursor over other AI coding tools, according to the company's enterprise data.

Cursor offers a free tier for basic usage, with paid plans starting around $20/month. For teams serious about AI-assisted development, it's become the standard.

3. Stack Overflow for Teams: AI-Enhanced Knowledge Management

Stack Overflow for Teams has evolved beyond Q&A into an AI-powered knowledge platform. With 84% of developers visiting Stack Overflow at least multiple times per month (many multiple times per day), according to their 2024 survey, it remains the most trusted developer resource.

The 2024 survey revealed that 82% of developers learn to code with online resources, with Stack Overflow (80%) as one of the top resources alongside technical documentation (83%). More tellingly, 35% of developers report that some of their Stack Overflow visits result from AI-related issues, usually to verify or fix AI-generated code.

Stack Overflow for Teams now integrates AI features that help organizations capture and surface institutional knowledge. Instead of answers scattered across Slack threads and outdated wikis, teams can build searchable, verified knowledge bases. The AI surfaces relevant internal discussions and documentation based on context, dramatically reducing time spent hunting for information.

The platform serves over 20,000 organizations, from startups to Fortune 500 enterprises. For distributed teams where knowledge transfer is critical, Stack Overflow for Teams has become essential infrastructure.

4. ChatGPT: The Universal Coding Assistant

ChatGPT remains the most-used AI tool among developers. According to Stack Overflow's 2024 survey, 82% of developers using AI search tools choose ChatGPT, making it far and away the market leader. GitHub Copilot comes in second at 41%, followed by Google Gemini at 24%.
What makes ChatGPT valuable for developers isn't code generation (though it does that). It's the ability to quickly understand unfamiliar concepts, debug error messages, and explore different approaches to problems. Need to understand how WebSockets work? Want to compare different authentication strategies? Stuck on a cryptic compiler error? ChatGPT provides context and explanations that would take 30 minutes of reading documentation.

The tool has 75% admiration among developers who use it, according to Stack Overflow's AI tool rankings. That's higher than most specialized coding tools, suggesting developers find genuine value despite the limitations.

ChatGPT Plus ($20/month) unlocks GPT-4 and faster response times. For developers, the paid tier is worth it for complex technical questions where response quality matters.

5. Claude (by Anthropic): The Thoughtful AI Assistant

Claude has carved out a niche as the AI assistant developers trust for complex reasoning and detailed explanations. While it doesn't dominate usage statistics like ChatGPT, Claude excels at tasks requiring nuanced understanding: architecture decisions, code refactoring, technical writing, and debugging subtle logic errors.
Developers often use Claude when they need an AI that "thinks through" problems rather than just pattern-matching. It's particularly strong at explaining tradeoffs, identifying edge cases, and reviewing code with actual insight rather than generic suggestions.

Claude Pro costs $20/month and includes higher usage limits and priority access during peak times. For developers who need detailed technical discussions, it's a strong complement to more code-focused tools.

6. Linear: Project Management That Doesn't Waste Time

Linear has become the project management tool of choice for engineering teams who are tired of bloated alternatives. While not strictly an AI tool, Linear recently added AI features that automatically categorize issues, suggest labels, and identify related work.

What makes Linear special is speed. The interface is keyboard-driven and blazingly fast. Creating issues, updating statuses, and organizing work takes seconds instead of minutes. For developers who context-switch frequently, this speed adds up to hours saved per week.

Linear integrates with GitHub, Figma, and Slack, pulling in context automatically. When a bug is reported, Linear can surface related PRs, similar issues, and affected components without manual digging.
Thousands of engineering teams use Linear, from early-stage startups to public companies. Pricing starts free for small teams, with paid plans from $8/month per user.

7. Notion AI: Documentation That Writes Itself

Notion transformed from a note-taking app into a full knowledge management platform. With AI features added, it now handles one of developers' most hated tasks: documentation.

Notion AI can summarize meeting notes, generate action items, create documentation from code comments and commit messages, and transform rough notes into polished technical specs. That feature you shipped six months ago that nobody documented? Feed Notion AI your Slack discussions and git history, and it generates a first draft.

For teams, Notion AI excels at synthesis. Drop in notes from multiple planning meetings and ask it to create a unified project brief. It identifies overlaps, contradictions, and gaps better than manually rereading everything.

According to their case studies, teams report 40% less time spent searching for information after implementing AI features. For developers, that's time redirected to building instead of hunting through documentation.

Notion AI costs $10/month per user on top of regular Notion plans. For teams already using Notion, it's a natural extension.

8. Perplexity: The Developer-Friendly Search Engine

Perplexity reimagines search for the AI era. Instead of a list of links, you get direct answers with citations. For developers researching new libraries, comparing frameworks, or troubleshooting issues, Perplexity saves the time spent clicking through search results.

The tool excels at technical queries where you need current information. "What's the best way to handle authentication in Next.js 14?" returns a synthesized answer with links to official docs, blog posts, and GitHub discussions. You can follow up with questions to drill deeper without starting a new search.

Perplexity Pro ($20/month) unlocks unlimited searches and access to more powerful AI models. For developers who do heavy research, it's worth the upgrade.

9. Raycast: The Smart Command Bar

Raycast is a Mac-only productivity tool that replaces Spotlight with something far more powerful. It includes AI features that let you write code snippets, draft messages, and automate workflows without leaving your keyboard.

For developers, Raycast shines at eliminating micro-tasks. Need to convert JSON to TypeScript interfaces? Encode a string to base64? Search your GitHub repos? Format a timestamp? All available instantly via keyboard shortcuts.

Raycast integrates with dozens of developer tools: GitHub, Linear, Jira, Figma, VS Code. You can search issues, create PRs, and manage tasks without context-switching to different apps.

Raycast is free with a Pro tier ($8/month) that includes AI features and unlimited cloud sync. For Mac users, it's an instant productivity boost.

10. Sourcegraph Cody: Code Search That Actually Understands Your Codebase

Sourcegraph Cody is an AI coding assistant that specializes in understanding large codebases. Unlike general-purpose AI tools, Cody indexes your entire repository and understands the relationships between files, functions, and dependencies.

Ask Cody "where do we handle user permissions?" and it shows you every relevant file, not just files with "permissions" in the name. Request "add logging to all database queries" and it identifies every query in your codebase and suggests consistent changes.

For teams working on large projects, Cody solves the onboarding problem. New developers can ask questions about the architecture and get accurate answers instead of bothering senior engineers or guessing from incomplete documentation.

Sourcegraph offers a free tier for individual developers, with team plans starting at $9/month per user. For companies with large codebases, the enterprise tier includes custom training on your specific code.

The Trust Problem: Why Developers Are Skeptical

Here's the uncomfortable reality: while AI adoption is skyrocketing, trust is falling. Stack Overflow's 2024 survey revealed that only 43% of developers trust the accuracy of AI tools, and 45% believe AI tools are bad or very bad at handling complex tasks.

The biggest frustration, cited by 66% of developers in Stack Overflow's 2025 survey, is dealing with "AI solutions that are almost right, but not quite." This leads to the second-biggest complaint: debugging AI-generated code takes longer than writing it manually (45% of developers).

This creates a paradox. Developers use AI tools daily (62% of professional developers in 2024), but 46% don't trust the output. The solution? Treat AI suggestions like suggestions from a junior developer: useful starting points that require review. AI handles the boilerplate, you handle the judgment calls.

Making AI Tools Work for You

Don't try to adopt all ten tools at once. Pick one that addresses your biggest pain point. Drowning in boilerplate code? Start with Copilot or Cursor. Spending too much time searching documentation? Try Perplexity. Documentation piling up? Add Notion AI.

Use it consistently for two weeks. AI tools have a learning curve because they work differently than traditional software. They get better as they learn your patterns, and you get better at knowing when to use them.

The developers succeeding in 2026 aren't using more tools. They're using the right tools for friction points in their workflow. The goal isn't to have the most AI assistants. It's to spend less time on overhead and more time solving real problems.

Frequently Asked Questions

Will AI tools replace developers?
No. Stack Overflow's 2024 survey found that 70% of professional developers don't see AI as a threat to their jobs. AI tools excel at generating boilerplate and handling repetitive tasks, but they don't understand business requirements, make architectural decisions, or navigate organizational complexity. Every company adopting these tools is hiring more developers, not fewer, because they can finally tackle their backlogs.

How much do developers actually trust AI-generated code?
Not much, and trust is declining. Only 43% of developers trust AI tool accuracy according to Stack Overflow's 2024 survey, down from previous years. The key is treating AI code like any other code: review it carefully, test it thoroughly, and don't deploy it without human verification.

Do AI tools actually make developers more productive?
Yes, but with caveats. GitHub's research shows developers complete tasks 55% faster with Copilot in controlled experiments. However, some studies show contradictory results, with developers taking 19% longer when using AI tools in certain contexts. Productivity gains depend heavily on how developers integrate the tools and what types of tasks they're working on.

What are the biggest challenges with AI coding tools?
According to Stack Overflow's 2024 survey, the top challenges are: inaccurate code suggestions (66%), longer debugging times (45%), and poor suitability for complex tasks (45%). Developers also cite concerns about misinformation (79%) and lack of source attribution (65%) as ethical issues with AI tools.

How are junior developers affected by AI tools?
This is debated. Some worry that junior developers become too dependent on AI and don't develop fundamental skills. Others argue AI helps juniors learn faster by providing instant feedback and examples. The consensus is that juniors should understand the code AI generates, not just copy-paste it.

Which AI coding tool has the most users?
GitHub Copilot leads with 20 million total users and 4.7 million paid subscribers as of early 2025. It's used by 90% of Fortune 100 companies. Among AI search tools, ChatGPT dominates with 82% of developers using it, followed by GitHub Copilot (41%) and Google Gemini (24%), according to Stack Overflow's 2024 survey.

Do I need to pay for AI tools or are free versions enough?
It depends on usage intensity. Most tools offer free tiers that work fine for occasional use. Heavy users benefit from paid plans: faster responses, higher usage limits, and access to better models. GitHub Copilot Individual ($10/month) and ChatGPT Plus ($20/month) are the most common paid subscriptions among developers.

How do AI tools handle proprietary code and privacy?
Enterprise versions of tools like GitHub Copilot and Cursor include privacy guarantees that your code isn't used for training models. They typically offer SOC 2 compliance, zero data retention agreements with AI providers, and private deployment options. Always check privacy policies and use business/enterprise plans if working with proprietary code.

The Bottom Line

AI tools won't make you a better developer by themselves. They'll make you a faster developer at the things that don't require judgment, creativity, or domain expertise. That's still valuable. Every hour you save on boilerplate, documentation, and debugging is an hour you can spend on architecture, problem-solving, and building features that matter.

The statistics are clear: 76% of developers are using or planning to use AI tools, and that number keeps climbing. Tools like GitHub Copilot and Cursor have achieved mainstream adoption in under three years. The trend isn't reversing.

The developers winning in 2026 aren't the ones writing more code. They're the ones shipping better products by letting AI handle the grunt work. Your competitors are probably already using some of these tools. The question isn't whether to adopt AI. The question is how much of your time you want to keep spending on tasks that could be automated.

Why use an AI gateway at all?

lulu77-mm — Thu, 23 Apr 2026 08:55:01 +0000

Before picking a platform, I think it's worth asking: why even bother with an aggregation layer?

For me, the pain point became obvious once I started juggling more than two model providers. Different API keys, different billing cycles, different request formats, and the constant context-switching between docs. If you're building anything that needs to switch between GPT for reasoning, Claude for coding, or a local model for cost-saving, a unified API is no longer a nice-to-have—it's a productivity multiplier. It abstracts away the boring plumbing so you can focus on what you're actually building.

OpenRouter — the established workhorse
Like many of you, I've used OpenRouter extensively. Its core value is clear: unmatched model breadth (300+ and counting), smart routing with fallbacks, and a massive community. It's the best discovery engine out there—want to test a newly released open-source model the day it drops? OpenRouter probably has it. The trade-off, which is transparently disclosed, is the platform fee baked into usage.

BasicRouter.ai — a newer alternative I'm exploring
Recently I stumbled upon BasicRouter.ai. Model count is smaller (around 50 curated ones), but it covers my daily stack—GPT, Claude, Gemini, DeepSeek, Qwen—and notably includes native image and video generation endpoints (Kling, Jimeng, Qwen-image) that OpenRouter doesn't focus on. Pricing is direct (no markup), and there's a small credit to test the waters. It feels like a pragmatic, "just the models I actually use" alternative.

**Curious what the rest of you are using to wrangle multiple models. **Sticking with direct provider APIs, or leaning on gateways? Let's hear it. 🦞

The Dawn of a New Era: Google's Gemini Enterprise Agent’s Platform

miracle eze — Thu, 23 Apr 2026 08:54:18 +0000

The Agentic Leap: How Black Innovations Africa is Building the Future with Google’s Gemini Enterprise Agent Platform

Africa is no longer just a participant in the global digital economy; it is becoming its architect. As the Google Cloud NEXT ‘26 announcements unfold, it’s clear that we have entered the Agentic Era. This isn’t just a moment of growth—it is a definitive stepping stone that positions Nigerian and African technology as a cornerstone of the global future.

The Agentic Shift: Beyond Chatbots

The breakthrough this year is Agentic AI. Unlike traditional AI that simply processes data, Agentic AI—powered by Google Cloud’s Gemini 1.5 Pro and the new Agent Development Kit (ADK)—acts as a proactive partner. For Nigerian businesses, this means moving from "automation" to "autonomy."
Black Innovations Africa: A Three-Pronged Revolution
As one of the leaders in the Nigerian tech space, Black Innovations Africa is using this week’s announcements to accelerate our three core missions:

High-Velocity B2B Services

We are leveraging the Agentic Data Cloud to transform B2B integrations. By using agentic "function calling," we’ve reduced the time it takes to sync disparate client systems by 60%. We aren't just giving clients a dashboard; we’re giving them a "digital taskforce" that executes multi-step business logic in real-time.

Building Proprietary Solutions with ADK

We don't just use tools; we build them. Black Innovations Africa is currently developing internal platforms using Vertex AI Agent Builder.
• The Goal: To create "Reasoning Agents" that can navigate local Nigerian market complexities—like fluctuating exchange rates or supply chain logistics—autonomously.
• The Impact: This allows us to move from "concept" to "market-ready" in weeks instead of months, creating solutions that are uniquely African and globally competitive.

Training the "Agentic Taskforce"

The most vital part of our mission is training. We are officially integrating the Google Cloud ADK into our curriculum.
• From Coders to Architects: We are teaching our students to move beyond basic syntax. They are learning to orchestrate multi-agent systems, manage Agentic SecOps, and use BigQuery Graph for supply chain traceability.
• A New Baseline: By teaching the youth of Nigeria to build with Gemini today, we are ensuring they aren't just "job seekers"—they are the architects of the next billion-dollar startups.

A Vision Realized: Prosperity Through Intelligence

This evolution aligns with a broader vision: a world where African ingenuity is a primary export. Agentic AI makes our businesses faster, but more importantly, it makes them richer in capability. It encourages upcoming startups to dream bigger, knowing that with Google Cloud, a team in Lagos has the same power as a team in Silicon Valley.

"The digital revolution in Africa is the single greatest opportunity for global advancement. At Black Innovation Africa, we are building the agents that will lead it."

The Road Ahead

As infrastructure improves and agentic workflows become the standard, the "stepping stone" of today will become the "gold standard" of tomorrow. Africa has arrived, the intelligence is agentic, and the world is finally tuning in.

OCI Run Command Advanced Guide: Remote Execution, Object Storage Scripts, and Production Troubleshooting

Bonthu Durga Prasad — Thu, 23 Apr 2026 08:53:24 +0000

Introduction

Managing remote servers usually means logging in through SSH (Linux) or RDP (Windows). While that works, it also means managing ports, credentials, and access controls.

Oracle Cloud Infrastructure (OCI) offers a cleaner option called Run Command.

OCI Run Command allows you to remotely execute commands or scripts on OCI Compute instances directly from the OCI Console, OCI CLI, or API — without logging in to the server manually.

This blog explains what OCI Run Command is, how it works, what is required, common statuses, troubleshooting, and best practices.

What is OCI Run Command?

OCI Run Command is a feature that lets you run commands remotely on an OCI Compute instance using the Oracle Cloud Agent installed on that server.

Examples:

hostname
whoami
systemctl restart nginx
df -h

Instead of connecting to the server manually, OCI sends the command securely through the cloud control plane.

Why Use Run Command?

OCI Run Command is useful when you want to:

Run quick administrative commands
Restart services
Collect logs
Check disk space / memory
Update configuration
Run scripts remotely
Troubleshoot servers without SSH/RDP access

Architecture Overview

Administrator
│
▼
OCI Console / OCI CLI
│
▼
Run Command Service
│
▼
OCI Instance Agent
│
▼
Compute Instance
│
┌───┴──────────────┐
▼ ▼
Object Storage Log Files
(Scripts) (Output)

Inline Commands vs Large Scripts

Use Inline Commands For:
hostname
uptime
df -h
systemctl status httpd
Use Object Storage Scripts For:
Application deployment
Package installation
Multi-step patching
Configuration enforcement
Long shell logic

Main Components Required

1. OCI Compute Instance

Target server where command will run.

2. Oracle Cloud Agent

Installed on OCI instance. This agent communicates with OCI services.

3. Run Command Plugin

Must be enabled inside Oracle Cloud Agent settings.

4. IAM Policies

Permissions are needed for:

User who creates command
Instance that consumes command
5. Dynamic Group

Used to grant permissions to the OCI instance itself.

Step 1: Enable Run Command Plugin

Go to:

OCI Console → Compute Instance → Oracle Cloud Agent

Enable:

Step 2: Create Dynamic Group

Example rule:

ALL {instance.compartment.id = ''}

This means all servers in that compartment join the Dynamic Group.

Step 3: Dynamic Group Policies

Example:

Allow dynamic-group DeployDG to use instance-agent-command-execution-family in compartment id

Allow dynamic-group DeployDG to read instances in compartment id

Allow dynamic-group DeployDG to read buckets in compartment id

Allow dynamic-group DeployDG to read objects in compartment id where target.bucket.name=''

Allow dynamic-group DeployDG to manage objects in compartment id where target.bucket.name=''

This allows the server to receive and execute commands.

Step 4: User IAM Policies

Example:

Allow group Admins to manage instance-agent-command-family in compartment id

Allow group Admins to read instance-agent-command-execution-family in compartment id

Allow group Admins to inspect instances in compartment id

What is ocarun in OCI Run Command?

ocarun is the local execution user/context used by OCI Run Command plugin on the compute instance.

When you send a command through Oracle Cloud Infrastructure Run Command, the instance agent receives it and executes it using the Run Command plugin. On many OCI images/platform setups, that execution is associated with ocarun.

-> If you run commands that required sudo privilages then you should provide ocarun user to the admin privilage.

Example Run Command (OCI CLI)

oci instance-agent command create \
--compartment-id \
--target '{"instanceId":""}' \
--content '{
"source":{
"sourceType":"TEXT",
"text":"hostname"
}
}' \
--timeout-in-seconds 600 \
--display-name test-hostname

Common Status Values Explained

lifecycle-state

Shows execution status.

ACCEPTED
Command created and queued.
IN_PROGRESS
Command is currently running.
SUCCEEDED
Command completed successfully.
FAILED
Command ran but failed.
CANCELED
Execution canceled.

To check the delivery status

oci instance-agent command-execution list --compartment-id ocid1.compartment.oc1..aaaaaaaagz4mern4sk46kbebwqzl6czdowlud7rop7ornezr7axx6ja5jfla --instance-id ocid1.instance.oc1.ap-mumbai-1.anrg6ljr7gqo7aacuco546smbzylzekybcfbvp2vz2ygvwgu52vf62zk7cma --all

delivery-state

Shows whether command reached the server.

ACKED
Server received the command.
EXPIRED
Command was never picked up before timeout window expired.

Usually caused by:

Wrong Dynamic Group
Agent issue
Network issue
Permissions issue

-> If you get delivery status ACKED and exit code =0 then your command / script successfully executed over the remote server.

How to Troubleshoot

Check Agent Status

Linux:

systemctl status oracle-cloud-agent
Restart Agent
systemctl restart oracle-cloud-agent
View Logs
tail -100 /var/log/oracle-cloud-agent/agent.log

Upload Detailed Logs to Object Storage

For long executions, store logs locally:

/tmp/deploy_httpd.log

Then upload logs back to bucket using automation.

This enables:

✔ Retention
✔ Audit trail
✔ Team review
✔ Full debugging

Security Best Practices

✔ Use least privilege IAM policies
✔ Restrict bucket access
✔ Sign scripts / validate source
✔ Avoid plaintext secrets in scripts
✔ Rotate credentials

Run Command vs SSH

Feature	SSH	OCI Run Command
Needs inbound port	Yes	No
Manual session	Yes	No
API driven	Limited	Yes
Auditable	Moderate	Strong
Scalable fleet ops	Medium	Strong

Final Thoughts

OCI Run Command is a powerful feature for remote server administration. Once properly configured, it becomes one of the easiest and safest ways to execute commands on OCI instances without direct login access.

If you manage OCI servers regularly, it is worth enabling and learning.

I've built an Obsidian Vault for Novel Writing & Worldbuilding

Panos Sakalakis — Thu, 23 Apr 2026 08:53:20 +0000

For the past two and a half years, I've been writing a sci-fi novel. One of the reasons it took me so much time and I haven't even published the first book of the series, was finding the right place to store and organize all my thoughts and ideas.

Like most beginner authors, I started with a blank document on Google Docs. But as I kept writing the book and the story progressed, everything from the characters and locations to events and dates grew to a point where I found myself looking at a document with hundreds of comments and notes. Unlike other writers, my mind can't work like that, and looking at my document was enough to make me procrastinate and pause the writing for a few weeks.

I started looking for apps that I could use for worldbuilding and novel outlining, and I found quite a few options. First, the king: Scrivener. This is what most professional career authors recommend for every beginner, and after a good week of using it (that's how long their free trial gives you), I knew that Scrivener wasn't it. Don't get me wrong, it's pretty good and powerful and all, but not as customizable as I wanted it to be. I wanted something simpler, yet as powerful as Scrivener, but minimal enough to reduce the chaos I felt I was living with my novel.

First, I tried creating my own software, a native app that fully supported Markdown, and it could have everything I wanted, exactly how I wanted it to be. But as many programmers/developers know, creating, maintaining, and making sure such a program actually works is far from easy. But it wasn't the coding part that I was afraid of, but how much time I'd have to invest in building it.

Time was in essence, because I had just switched my career and focused on becoming what I had always dreamed of: a full-time author. But the only thing that was stopping me was me, unable to find a way to store my thoughts and ideas that my mind would appreciate. Because, you know, if it doesn't, I don't get those beautiful creativity boosts that it gives me every day.

That's when I found Obsidian, and let me tell you, it was love at first sight. Sure, it came with a learning curve, especially for me, who kept looking at their developer docs, but I knew it was the perfect app for what I needed.

So I built my own Vault and put everything there. As time went by, I kept improving it and adding whatever I needed. I kept things simple, used a minimal theme, and made sure that everything was well-linked. And after a while, I thought of sharing it on my Medium.com blog for authors who may find it interesting.

And my oh my, do they found it interesting.

Currently, it has over 180+ downloads on Gumroad alone, and a 5-star rating from a total of 6 reviews. People sent me a lot of feedback, and I've already released two versions of it. I'll continue updating, and the next version is gonna be even better after all the emails I've gotten from people who downloaded it.

It's also closing on making $100 in donations, which is something I never believed I'd see - and for which I'm so grateful, as it supports me to continue focusing on my dream.

With that in mind, say hello to 'The Novelist', a free and open-source Vault for Obsidian that's designed for novel writing and worldbuilding. Although it wasn't designed for non-fiction writers, you can easily adjust it to your needs.

Here's everything you need to know about this Vault.

1. Worldbuilding with Canvas

There's nothing special about this one if you've already been using it. Canvas is a built-in plugin that every Obsidian user can enable or disable, but few know how powerful it is for worldbuilding.

This Canvas includes everything my book and story do, including the book's title and description, characters and locations overviews, ideas, notes, to-do lists, and everything else I feel like putting there. You can probably improve it and make it even better, as I did on my novel's vault, but for demo purposes, I kept it simple.

2. Colorful File Explorer

Obsidian's 'File Explorer' is located on the left side, and it's the place where all your folders, files, and documents are located. I didn't want to have to scroll through hundreds of those, so I organized everything as simply as I could.

The structure:

Chapters

Includes a document called "All Chapters" and, just below it, you can find all the chapters separated individually (e.g, Chapter 1, Chapter 2, Chapter 3, and so on). I keep the 'All Chapters' document as my backup and move each chapter I fully complete there. At the end, it's a process of exporting/copying the whole document and importing it into Atticus, Vellum, etc.

Characters

This is where your characters are located. If you have just a few characters, you can have them all inside this folder, or organize them into folders if you have lots of them. Each character has a few details that you can fill in, such as name, nickname, gender, role, age, family members, friendships, occupation, and so on, but you can remove/rename every property or add more. I've also written about their backgrounds, what kind of people they are, their biggest secrets and fears, and so much more.

Locations

The same as for characters, you can organize them in folders, and each location has its own properties, such as location name and type, how many citizens live there, and everything else that's needed for your story. I've also given a full background for each location, like when (and how) it was built, important events through its history, who's been running it, and everything I feel my story needs.

Tab splitting

What I love about Obsidian is that it lets you split your tabs side by side, or even by placing them above or below your current tabs. This is perfect because while I'm writing for, let's say, a specific location or characters, I want another tab just beside it to see their backgrounds and all the details I've added for them. It's easy to forget some details when you're dealing with lots of different locations and characters.

The 'Graph View' that shows your connections

In the beginning, the 'Graph View' feature doesn't show a lot of information, and it's not as useful and powerful as it will become as your story progresses and you link everything together.

Make sure to link your characters, locations, and everything else you want to be included in the 'Graph View', and after a while, you'll be able to see if you have any missing questions.

Like any feature and tool, you can disable the 'Graph View' if you don't need it.

Installing Obsidian & The Novelist

Download and install the latest version of Obsidian.
Download the latest version of The Novelist (Gumroad | GitHub).
Extract the the-novelist.zip file (double-click on macOS or right-click and "Extract here" on Windows and Linux).
Launch Obsidian and click on your Vault’s name in the bottom left corner, and click on “Manage vaults…".
In the “Open folder as vault” section, click on the “Open” button and select the ‘The Novelist’ folder.
Obsidian will ask you to "Enable community plugins and trust the author". Make sure to click on the "Trust" button to load everything the vault has to offer.

Documentation

If you don't know how to use Obsidian and The Novelist, please refer to the Documentation page, where I share all its features and options with images included (and soon, videos).

As always, I love getting feedback from people who use 'The Novelist', so don't hesitate to leave your comment or contact me with your ideas, bug reports, etc.

Beyond the README: The Evolution of Markdown in the Age of Generative AI

Jimit — Thu, 23 Apr 2026 08:48:31 +0000

Markdown has been the undisputed king of developer communication for two decades. It’s the language of our READMEs, our static site generators (like Astro), and our technical blogs.

But in 2026, Markdown is undergoing its most significant shift yet. It is no longer just a "formatting tool" for humans; it has become the fundamental interface between humans and Large Language Models (LLMs).

1. Why Markdown Won the "Markup Wars"

Before we look forward, we have to understand why Markdown beat out HTML, BBCode, and WikiText.

Portability: A .md file looks the same in VS Code, Obsidian, and GitHub.
Readability: Unlike HTML, Markdown is human-readable even in its raw state.
Standardization: With the rise of CommonMark and GitHub Flavored Markdown (GFM), the "fragmentation" of the early 2000s has largely stabilized.

2. The AI Pivot: Markdown as the "LLM Wire Format"

If you’ve used ChatGPT, Claude, or Gemini, you’ve noticed they almost exclusively respond in Markdown. There is a technical reason for this.

Tokens and Structure: LLMs are trained on massive amounts of web data. Markdown provides a low-token-cost way to define structure. While HTML tags like <div> and <span> consume many tokens, Markdown's # and * are incredibly efficient.

Code-to-UI Mapping:
Markdown serves as the bridge for "UI-less" interfaces. When an AI generates a table in Markdown, it’s not just text; it’s a data structure that modern front-ends can instantly render into interactive components.

3. The Future: "Smart" Markdown and MDX 2.0

We are moving toward a future where Markdown is executable.

From Static to Dynamic (MDX)

For those of us using frameworks like Astro or Next.js, MDX is already the standard. It allows us to import React/Preact components directly into our Markdown files.

The AI Future: Imagine a Markdown file where an AI dynamically injects a live data chart based on the reader's local data—all defined within a standard .md syntax.

Markdown as a Data Source (Content Collections)

In 2026, we are seeing "Markdown-as-a-Database." Instead of complex SQL queries for blogs, we are using type-safe Content Collections to treat folders of Markdown files as structured APIs. This makes it easier for AI agents to crawl, index, and update our documentation autonomously.

4. Best Practices for Markdown in 2026

To ensure your Markdown is "Future-Proof" and "AI-Friendly," follow these standards:

Feature	Best Practice	Why?
Frontmatter	Use YAML headers for metadata.	Essential for SEO and Astro-style routing.
Headers	Stick to a strict hierarchy (H1 -> H2 -> H3).	Helps LLMs understand document "chunks."
Code Blocks	Always specify the language (e.g., ``typescript`).	Enables syntax highlighting and AI code-parsing.
Alt Text	Never skip `![Alt text](url)`.	Critical for accessibility and AI image-recognition.

5. Is Markdown Being Replaced?

Short answer: No. Markdown is becoming the "JSON of Content." While we might see new extensions (like Markdoc from Stripe), the core syntax is too deeply embedded in our ecosystem to disappear.

As we move toward "Vibe Coding" and AI-generated apps, Markdown will be the "source code" that humans review to ensure the AI stayed on track. It is the human-readable anchor in a world of machine-generated complexity.

Conclusion

If you want to stay ahead as a developer, don't just "write" Markdown. Master MDX, understand YAML frontmatter, and learn how to structure your docs so they are easily digestible by both your peers and your AI collaborators.

What’s your favorite Markdown extension? Are you Team Obsidian, or do you still do everything in a simple VS Code window? Let's discuss below!

Compact Is Not TypeScript. That's the Whole Point.

Tushar Pamnani — Thu, 23 Apr 2026 08:44:50 +0000

Most developers approach Compact with the wrong frame.

They see the syntax - functions, types, imports, curly braces, and conclude: this is basically TypeScript with some ZK stuff sprinkled in. Then they start writing. And things break in ways that don't make sense. Loops that should work don't compile. Logic that feels correct fails silently. Private data bleeds into places it shouldn't.

The syntax didn't lie to them. Their mental model did.

The Illusion Is the Lesson

Here's a Compact circuit:

export circuit get(): Uint<64> {
  assert(state == State.SET, "Value not set");
  return value;
}

Your brain reads this and fires the usual pattern: function, assertion, return value. It looks like a getter. Call it, get a thing back.

But that's not what's happening.

This circuit doesn't "run." It declares a set of constraints. When you call it from your dApp, the proof system generates a zero-knowledge proof that those constraints were satisfied, without revealing the inputs. What goes on-chain isn't the output. It's the proof.

The frame shift: You're not writing code that executes. You're writing a description of a valid state, and the system proves you were in it.

Two Mental Models. One Will Break You.

Traditional code:

Input → Code executes → Output

You write instructions. The machine follows them. You get a result.

Compact circuits:

Input → Constraints are declared → Proof is generated → Proof is verified

There are no "instructions" in the traditional sense. The circuit defines relationships. The prover proves the relationships held. The chain verifies the proof without seeing the inputs.

Nothing is executed. Correctness is proved.

This is why assert is your only runtime guard. It's not just input validation, it's the mechanism by which you define what a valid state even is. Every assert is a constraint. Every constraint becomes part of the circuit. The circuit is the proof.

The Constraints Are the Feature

The first reaction most developers have to Compact's restrictions:

No recursion
Bounded loops only (bounds must be compile-time constants)
Fixed type sizes
No any
Unsigned types only

"These seem arbitrary. Why can't I just-"

They're not arbitrary. They're causal.

ZK proofs require finite circuits. A circuit is a fixed structure; gates, wires, constraints, determined entirely at compile time. If you could write unbounded loops or recursion, the compiler couldn't produce a circuit. The circuit literally couldn't exist. The proof couldn't be generated.

The constraints don't limit what Compact can do. They're what make the magic possible at all.

Accept this, and the language makes complete sense. Fight it, and you'll spend weeks trying to port TypeScript patterns into a tool designed around a completely different model.

What "Privacy" Actually Means Here

Compact is not just "TypeScript with encryption." The privacy model is structural.

Midnight has two worlds:

World	Where	Who can see it
Public	On-chain	Everyone
Private	Local	Only you

Your sensitive data; balances, credentials, secrets, never leaves your machine. What goes on-chain is a proof that you ran the computation correctly on that private data. Validators verify the proof. They never see the inputs.

This has a concrete implication: you have to know the boundary.

export ledger is public. witness data is private. disclose() is the explicit line you cross when you intentionally move private data into public state.

The compiler enforces this. If private data tries to flow into public state without going through disclose(), it fails. But knowing why this boundary exists — not just that it does — is what lets you design contracts correctly from the start instead of debugging your way there.

The Use Cases This Unlocks

This matters because entire categories of blockchain applications were previously impossible:

Healthcare: Prove you meet age or eligibility requirements without revealing your date of birth or medical history.
Finance: Prove your balance exceeds a threshold for a loan without revealing the balance.
Identity: Prove citizenship or credential validity without revealing the underlying document.
Competitive markets: Submit bids or inventory levels that can be verified as legitimate without being revealed to competitors.

These aren't niche edge cases. They're the reason regulated industries haven't fully adopted public blockchains. With Compact, the privacy model that makes these use cases viable is built into the language, not bolted on after the fact.

Why the Comparison Breaks Down

Concept	TypeScript	Solidity	Compact
Private data	Convention only	On-chain (visible)	Stays local, always
Functions	Execute instructions	Execute instructions	Declare constraints
Loops	Unbounded	Unbounded (gas-limited)	Bounded at compile time
Recursion	Allowed	Allowed	Not allowed
Privacy enforcement	None	None	Type system + compiler

The closest thing Compact resembles isn't TypeScript. It's a constraint satisfaction system with TypeScript syntax. The syntax is a DX choice, not a design philosophy.

The One Thing to Take Away

Every concept in Compact, witnesses, circuits, disclose(), the boundedness rules, becomes clear once you have the right frame:

You're not writing programs. You're describing valid states and proving you were in them.

With that frame:

Witnesses make sense: they're the private inputs the prover uses to generate the proof.
disclose() makes sense: it's the intentional act of moving a constraint into public view.
Bounded loops make sense: the circuit is fixed at compile time, so everything has to be fixed at compile time.
assert makes sense: it's not validation, it's constraint declaration.

Without that frame, everything in Compact feels like TypeScript with arbitrary restrictions. With it, everything is exactly as it should be.

What I Built for This

Most documentation explains the what. Compact's own docs are good. But the gap isn't information, it's the conceptual layer underneath.

I've been building a structured guide that goes through each concept with the execution model shift front and center: Compact Book

If you're trying to actually understand Compact rather than just cargo-cult your way through examples, start there.

The syntax is the easy part. The mental model is the work. Get that right, and the rest follows.

SVG to PNG: Complete Guide for Developers [2026]

Luca Sammarco — Thu, 23 Apr 2026 08:44:40 +0000

When you actually need PNG instead of SVG

SVG is the best format for most web content. A vector icon at 2 kilobytes renders pixel-perfect at any zoom level, theme-able with CSS, manipulable with JavaScript, and indexable by search engines if you add title and desc. For buttons, logos, illustrations, and data visualizations, SVG beats PNG on every axis.

But there are five places where SVG does not work and you need PNG. First: app icons. iOS and Google Play require fixed-size PNGs — 1024 by 1024 masters with many derivative sizes. Submit SVG and get rejected.

Second: favicon fallback. Modern browsers accept SVG favicons but Safari on older iOS versions and many email clients that preview favicons do not. Multi-size ICO is the safe fallback.

Third: email templates. Gmail, Outlook, Apple Mail strip SVG from HTML. The only reliable inline image format in email is PNG or JPG.

Fourth: social uploads. Instagram, WhatsApp, Facebook, and most ad platforms reject SVG uploads. They want raster.

Fifth: print and embedded documents. Word, PowerPoint, many PDF pipelines, and print-on-demand services need raster. SVG may render unpredictably in Word specifically.

viewBox math and intrinsic size

The first thing a rasterizer needs to know is what size is this SVG naturally. There are three places it can find the answer, in priority order.

One: the width and height attributes on the root SVG. Two: if only one is present, derive the other from the viewBox ratio. Three: if both are missing, fall back to the viewBox extent. Four: if nothing is declared, rasterizers pick a default — browsers use 300 by 150, SammaPix uses 512 by 512.

Always declare both width and height on the root element. Skipping them leads to unpredictable output across rasterizers. This is the single most common reason that my SVG converted fine in tool A but broke in tool B — the two tools used different fallback rules.

Scaling strategy: 1x, 2x, 3x, custom

The output size is a function of intrinsic SVG size times scale factor. For a 100 by 100 SVG: 1x produces 100 by 100 PNG. 2x produces 200 by 200 PNG — standard for Retina and HiDPI. 3x produces 300 by 300 PNG — iPhone Plus and Pro models. 4x produces 400 by 400 PNG — Android XXXHDPI and 4K monitors. Custom allows any width up to 8192 pixels with height scaling to preserve aspect ratio.

SammaPix SVG to PNG parses the intrinsic size from width, height, or viewBox automatically and lets you pick the scale preset or custom width. The maximum 8192 pixels is a deliberate guard — larger canvases can crash the tab on low-memory devices.

Building a favicon pack from one SVG

A modern favicon setup serves three files from one SVG master. First: favicon.svg — the original, served to modern browsers. Second: favicon.ico — multi-size container with 16, 32, 48 (and optionally 64, 128, 256) for legacy clients. Third: apple-touch-icon.png — 180 by 180 for iOS home screen shortcuts.

The HTML is three link tags in the document head. Build the favicon.ico from your SVG using the SammaPix Favicon Generator — upload the SVG, pick sizes, download the ICO file. For the Apple touch icon, run the SVG through SVG to PNG at 180 pixels wide.

App icons for iOS and Android

Both iOS and Google Play require a 1024 by 1024 master PNG — no transparency for iOS App Store, transparency optional for Play. Historical derivative sizes have shrunk because both platforms now generate them from the master automatically, but some CI pipelines still expect the full matrix.

iOS App Store: 1024 by 1024, no alpha, square. Google Play: 1024 by 1024, 32-bit PNG with alpha allowed. iOS home screen: 180 by 180 apple-touch-icon. Android adaptive: 512 by 512 foreground layer with safe-zone padding. PWA manifest: 192 and 512 declared in manifest.json.

If you export a single 1024 PNG from SVG you can downscale inside Xcode or Android Studio. If you need all sizes pre-baked, SammaPix SVG to PNG custom width field accepts any value from 16 to 8192.

Open Graph and social previews

Social platforms require a raster image with a specific aspect ratio. 1200 by 630 for Facebook Open Graph standard. 1200 by 628 for Twitter summary_large_image. 1200 by 627 for LinkedIn recommendation.

You cannot generate this directly from a square SVG — the aspect ratio mismatch means you either design a dedicated 1200 by 630 SVG or composite your logo inside a larger background. Do the layout in SVG first, then rasterize to PNG at custom width 1200.

Transparency: keep it or flatten it

PNG supports 8-bit alpha, same as SVG. By default the conversion preserves any transparent region. Two reasons to flatten to a solid background.

First: iOS App Store. Submitted app icons must not have alpha channel. A 1024 PNG with transparency will be rejected.

Second: email clients. Some legacy clients render transparent PNGs on a dark background, making light icons invisible. A solid white or theme-matched background avoids the issue.

Print output: the DPI conversion

Print pipelines do not think in pixels — they think in inches or millimetres at a specific DPI. The math is pixels width equals inches width times DPI.

Common targets at 300 DPI offset printing standard. Business card 3.5 by 2 inches equals 1050 by 600 pixels. Postcard 6 by 4 inches equals 1800 by 1200 pixels. Letter 8.5 by 11 inches equals 2550 by 3300 pixels. A4 equals 2480 by 3508 pixels. Poster 24 by 36 inches equals 7200 by 10800 — exceeds the 8192 tool limit, split into quarters.

Common pitfalls

External fonts — if your SVG references a Google Font via import, the rasterizer cannot load it. Convert all text to paths before rasterizing, or embed the font with base64.

External images — image xlink href to an external file will not load cross-origin. Inline via base64 or host same-origin.

Script tags — rasterizers disable script inside SVG for security. Any JS-driven animation is gone in the PNG.

Filters — complex SVG filters render differently across rasterizers. Test the output visually.

Huge viewBox — an SVG with viewBox 0 0 10000 10000 scaled 4x produces a 40000 by 40000 PNG. Crash territory. Check intrinsic size before picking scale.

Size benchmarks: SVG vs PNG at scale

We took a 2.1 kilobyte logo SVG and rasterized at five target sizes. 256 by 256: PNG 14 kilobytes, 6.7 times the SVG. 512 by 512: PNG 38 kilobytes, 18 times. 1024 by 1024: PNG 112 kilobytes, 53 times. 2048 by 2048: PNG 320 kilobytes, 152 times. 4096 by 4096: PNG 920 kilobytes, 438 times.

The SVG stays 2.1 kilobytes regardless of display size. The PNG grows quadratically because every additional pixel needs encoding. This is why you ship SVG to browsers and rasterize only when the target rejects SVG.

Free browser-based SVG tools

SammaPix ships three tools covering the full SVG workflow, all running locally in your browser. SVG to PNG for any size conversion. Favicon Generator for multi-size favicon ICO. Compress Images for post-conversion reduction.

FAQ

When do I actually need to convert SVG to PNG? When the destination does not accept SVG: iOS and Android app icons, favicon fallback for legacy browsers, email templates, social media uploads, print pipelines, Word and PDF embedding.

What size PNG should I export from my SVG? Depends on the target. Favicons 16, 32, 48 minimum plus 64, 128, 256. App icons 1024 by 1024. Open Graph 1200 by 630. Retina web 2x the display size.

How does the SVG viewBox affect the PNG output? The viewBox defines the SVG coordinate system. If your SVG has width and height attributes, that is the intrinsic size. A 4x scale produces 4x the pixels.

Will transparency be preserved when I convert SVG to PNG? Yes by default. PNG supports 8-bit alpha, same as SVG.

Why is my PNG file much larger than the SVG source? Because SVG encodes shapes as math and PNG stores every pixel. A 2 kilobyte SVG can render at any resolution.

Can I batch convert SVG to PNG in the browser? Yes. SammaPix SVG to PNG runs 100 percent in your browser using the Canvas API. Drop up to 20 SVGs on the free plan, 200 on Pro.

Originally published at sammapix.com

Try it free: SammaPix — 35 browser-based image tools. Compress, resize, convert, remove background, and more. Everything runs in your browser, nothing uploaded.