The point I'm trying to get across here, is that if you have made a product that you genuinely care about and want others to recognize, then spend time and pour at least an ounce of creativity into the brochure site. Prompting an LLM to "make a stylish homepage for my product" is not a good idea. People can see through it instantly. The reason being, that LLMs predominantly chose a Tailwind template to use as the base for the page. After seeing this template reused a thousand times, prospective users/clients will instantly be put off. Prompted advertisingly material is the biggest red flag I see when it comes to software. It indicates that the software has been vibe-coded and rushed out.

Apache Burr

A python library to simplyify something that is already simple.

Spark

Creates a synopsis for LinkedIn?... doesn't LinkedIn already do this?

And the price cards.

Labilo

Summarise a webpage into a card, but you have to pay for some extras.

And the price cards.

Artist Kit

I'm not sure what this is. Generates a webpage for DJs? but you pay for some extras.

And the price cards.

Source article, redmonk.com

an anomalously low second half’s worth of pull requests from GitHub

This comment came after the author mentioned the declining relevance of StackOverflow, which makes up one axis on the popularity grid. Github making up the other.

The author expected a decline in StackOverflow tags, but was puzzled when observing a decline in pull requests. This also surprised me. I see alot of "hype" online about the supposed productivity gains related to generative AI in software engineering. The lack of data to reflect this suggests to me that there is little substance to the hype. Which would reflect my personal experience. And before you suggest that Github pull requests are not a good measure of productivity. Let me stop you. The sheer amount of money spent on code generation should have increased pull requests and every other metric related to "lines" of code.

The author surmised that it could be bad data, or that code creation went up while code committed went down. The latter would suggest to me a decrease in productivity. Are programmers just generating slop to get a dopamine hit without actually producing anything of value? I suspect this is often the case. But it's pure speculation. The data says pull requests have declined. That is a fact.

given that coding assistants make developers’ familiarity with a language less relevant and the tools’ propensity to reflect the biases inherent in their training data, it would be logical to expect some meaningful change in language usage... however, these have not manifested

Again, this also surprised me. When I used generative AI, I no longer do, I used it with languages I was not familiar. For example generating Ada code, and trying out Zig. So my usage was exactly the usage the author expected to be reflected in the charts. The problem I had was that the code generated often didn't work, and I didn't have the knowledge of the langauge to fix it. For me, when people write about code generation with AI they often seem to assume or suggest the code generated is perfect. I have not found this to be the case. It was pot luck whether it worked or not.

Using AI to write a language you are not familiar with also robs you of learning that language. So even if you got AI to spit out Haskell code, why would you bother. You would just be left with code that might work, in a language you can't understand. So maybe it's not a surprise that developers are not jumping from one language to another just cause they have a bot that can vomit up syntax.

coding assistance tools, in theory, should be lowering some of the barriers to entry with Rust. If that’s happening, however, it’s not observable yet.

I don't care what anyone says, Rust is super hard. I've made multiple attempts to write Rust and have been put off by the compiler constantly saying NO. One might think that the strictness would lend itself to LLM's being able to generate working Rust code. I've not found that to be the case and it looks like the data supports that finding.

So what are the benefits of generative AI for software engineers? The real benefits. The ones that show up in data. Well going off my favorite twice annual report from Redmonk. The data suggests that generative AI helps programmers make less pull requests, avoid Rust, and doesn't help them learn new languages. What a tool. A great waste of time and money.

Hip. Hip. Hooray. For AI.

I predict this will benefit me long term. If there is something that I have learned over the last twelve years of developing software it is this.

IGNORE WHAT EVERYONE ELSE IS DOING.

Seriously. If you want to build something, go build it. Build it your way, using your tools. You can literally make anything you want with in the digital space. Why limit yourself based off the opinions of some internet trolls.

Have fun making things, make fun things.

The game was made as an entry into the 1 Bit Game Jam #11. This game jam limits you to the use of just two colors. I opted to use the color pallette of the original game boy, which is light green on a dark green background. You can play "Tiny Tanks" on it's itch.io page.

Really it is just a prototype but I had some key learning experiences. For example, object allocation in C, rotation based movement, track spawning, particle explosions, and making a raylib build for the web. I should blog on these learnings. Perhaps I will.

He's written lot's of pong clones already... It's his go to. Like a programming kata, remember those?

The Clone

I chose a Pong clone to start as it's super simple. There are only 3 objects, the two paddles and the ball, so everything can be kept on the stack. No need for memory allocation here, and I'm not going to bother with assets like sound or sprites, it's not needed for this one.

The following Pong clone was written in about 2 hours. I didn't refactor anything as I went along. I felt it unnessary, it's not like any one will actually play or use this. It's simply an exercise.

Check out the code below and critique the workings of my naive programming brain.

The next challenge is an Asteroids clone, which is a slight step up. I'll try to make a proper game loop for that one.

The Code

Link to the codeberg repo

#include "raylib.h"
#include <stdio.h>
#include <stdlib.h>

struct Court
{
    float x;
    float y;
    int w;
    int h;
};

struct Ball
{
    float x;
    float y;
    int vx;
    int vy;
    int speed;
    int r;
};

void drawBall(struct Ball *b)
{
    DrawCircle(b->x, b->y, b->r, RAYWHITE);
}

struct Paddle
{
    float x;
    float y;
    float vx;
    float vy;
    int w;
    int h;
};

void drawPaddle(struct Paddle *p)
{
    DrawRectangle(p->x, p->y, p->w, p->h, RAYWHITE);
}

struct Game
{
    int playerScore;
    int computerScore;
};

int main(void)
{
    struct Court court = { 100, 100, 400, 600 };
    Vector2 courtTopLeft = {court.x, court.y};
    Vector2 courtTopRight = {court.x + court.w, court.y};
    Vector2 courtBotLeft = {court.x, court.y + court.h};
    Vector2 courtBotRight = {court.x + court.w, court.y + court.h};
    float courtLineThickness = 4;

    InitWindow(600, 800, "Pong");

    SetRandomSeed(1337);

    struct Game game = { 0, 0 };
    struct Ball ball;
    struct Paddle topPaddle;
    struct Paddle bottomPaddle;

    ball.r = 10;
    ball.x = court.x + (court.w / 2);
    ball.y = court.y + (court.h / 2);
    ball.vx = GetRandomValue(0, 1) ? 1 : -1;
    ball.vy = -1;
    ball.speed=100;

    int paddleYBuffer = 20;

    topPaddle.y = court.y + paddleYBuffer;
    bottomPaddle.y = court.y + court.h - (paddleYBuffer * 2);

    int initialPaddleWidth = 80;
    int initialPaddleHeight = 20;

    topPaddle.w = initialPaddleWidth;
    topPaddle.h = initialPaddleHeight;

    bottomPaddle.w = initialPaddleWidth;
    bottomPaddle.h = initialPaddleHeight;

    topPaddle.x = court.x + (court.w / 2) - (topPaddle.w / 2);
    bottomPaddle.x = court.x + (court.w / 2) - (bottomPaddle.w / 2);

    Vector2 playerMovement;
    int paddleMoveSpeed = 400;
    Vector2 playerVelocity;
    float friction = 0.78;

    int cellSize = 100;
    int rowCount = GetScreenHeight() / cellSize;
    int colCount = GetScreenWidth() / cellSize;

    float bottomHit = 0.0;
    float topHit = 0.0;

    while (!WindowShouldClose())
    {
        //update
        if(IsKeyDown(KEY_R))
        {
            game.playerScore = 0;
            game.computerScore = 0;
        }

        if(IsKeyDown(KEY_LEFT))
        {
            playerVelocity.x = -1;
        }

        if(IsKeyDown(KEY_RIGHT))
        {
            playerVelocity.x = 1;
        }

        if(topPaddle.vx)
        {
            topPaddle.x += topPaddle.vx * (paddleMoveSpeed * GetFrameTime());

            topPaddle.vx *= friction;
            if(topPaddle.vx < 0.1 && topPaddle.vx > -0.1)
            {
                topPaddle.vx=0;
            }
        }

        if(topPaddle.x < court.x)
        {
            topPaddle.x = court.x;
        }

        if(topPaddle.x + topPaddle.w > court.x + court.w)
        {
            topPaddle.x = court.x + court.w - topPaddle.w;
        }

        if(playerVelocity.x)
        {
            bottomPaddle.x += playerVelocity.x * (paddleMoveSpeed * GetFrameTime());

            playerVelocity.x *= friction;
            if(playerVelocity.x < 0.1 && playerVelocity.x > -0.1)
            {
                playerVelocity.x=0;
            }
        }

        if(bottomPaddle.x < court.x)
        {
            bottomPaddle.x = court.x;
        }

        if(bottomPaddle.x + bottomPaddle.w > court.x + court.w)
        {
            bottomPaddle.x = court.x + court.w - bottomPaddle.w;
        }


        ball.x += ball.vx * (paddleMoveSpeed * GetFrameTime());
        ball.y += ball.vy * (paddleMoveSpeed * GetFrameTime());


        if(ball.x - ball.r < court.x)
        {
            ball.vx = 1;
        }

        if(ball.x + ball.r > court.x + court.w)
        {
            ball.vx = -1;
        }

        if(ball.y - ball.r < court.y)
        {
            ball.vy = 1;
        }

        if(ball.y + ball.r > court.y + court.h)
        {
            ball.vy = -1;
        }

        Vector2 center = { ball.x, ball.y };
        Rectangle botRect = { bottomPaddle.x, bottomPaddle.y, bottomPaddle.w, bottomPaddle.h };
        if(CheckCollisionCircleRec(center, ball.r, botRect))
        {
            ball.vy = -1;
            ball.vx = GetRandomValue(0, 1) ? -1 : 1;
        }

        Rectangle topRect = { topPaddle.x, topPaddle.y, topPaddle.w, topPaddle.h };
        if(CheckCollisionCircleRec(center, ball.r, topRect))
        {
            ball.vy = 1;
            ball.vx = GetRandomValue(0, 1) ? -1 : 1;
        }


        if(ball.vy == -1)
        {
            if(topPaddle.x > ball.x + ball.r)
            {
                topPaddle.vx = -1;
            }

            if(topPaddle.x +topPaddle.w < ball.x - ball.r)
            {
                topPaddle.vx = 1;
            }
        }

        if(ball.vy == 1)
        {
            if(topPaddle.x + ((float)topPaddle.w / 2) > court.x + court.w /2)
            {
                topPaddle.vx = -1;
            }

            if(topPaddle.x + ((float)topPaddle.w / 2) < court.x + court.w / 2)
            {
                topPaddle.vx = 1;
            }
        }

        if(topHit)
        {
            topHit -= 0.01;
        }

        if(bottomHit)
        {
            bottomHit -= 0.01;
        }

        if(CheckCollisionCircleLine(center, ball.r, courtTopLeft, courtTopRight))
        {
            topHit = 1.0;
            game.playerScore += 1;
        }

        if(CheckCollisionCircleLine(center, ball.r, courtBotLeft, courtBotRight))
        {
            bottomHit = 1.0;
			game.computerScore += 1;
        }

        //draw
        BeginDrawing();
        ClearBackground(BLACK);
        for(int rowIndex = 0; rowIndex < rowCount; rowIndex++)
        {
            for(int colIndex = 0; colIndex < colCount; colIndex++)
            {
                DrawRectangle(
                    colIndex * cellSize,
                    rowIndex * cellSize,
                    cellSize,
                    cellSize,
                    (colIndex + rowIndex) % 2 == 0 ? GREEN : LIME
                );
            }
        }

        char scoreText[32];
        snprintf(scoreText, sizeof(scoreText), "%d : %d", game.playerScore, game.computerScore);
        int fontSize = 80;
        int textWidth = MeasureText(scoreText, fontSize);
        DrawText(scoreText, court.x - textWidth / 2 + court.w / 2, 10, fontSize, RAYWHITE);

        //top
        DrawLineEx(courtTopLeft, courtTopRight, courtLineThickness, topHit > 0 ? RED : RAYWHITE);
        //bot
        DrawLineEx(courtBotLeft, courtBotRight, courtLineThickness, bottomHit > 0 ? RED : RAYWHITE);
        //left
        DrawLineEx(courtTopLeft, courtBotLeft, courtLineThickness, RAYWHITE);
        //right
        DrawLineEx(courtTopRight, courtBotRight, courtLineThickness, RAYWHITE);

        drawBall(&ball);
        drawPaddle(&topPaddle);
        drawPaddle(&bottomPaddle);
        EndDrawing();
    }

    CloseWindow();
    return 0;
}

This work is very physical. I often have to wrestle with unruly animals, which weigh about 70kg each so they are quite strong. While I use my body, my mind is on somewhat of a vacation. I spend very little time in front of a screen now. I have no office, and as we live up a hill, no phone signal. Perhaps you could call it a detox. A welcome side effect of this detox is that I am no longer stressed, fitter than ever, and happy. I also work harder than ever, and deal with actual life and death issues, if you are a sheep that is, and often this takes place in dangerous environments, mostly in confined spaces with large excitably animals. Despite this I am not anxious or worried, I simply deal with the task at hand.

As lambing season comes to an end, I have been reflecting on my past work as a Software Engineer, the people I have worked with, their attitudes to life, and the industry in general. Mostly I think about what a truly ignorant bunch of people make up the tech industry. Detached from the real world and nature. For example, I woke up this morning and the first thing I had to do was chase and catch a sheep whose dead lamb was hanging out of her and needed to be removed. The unfortunate fellow had come out backwards and his mother was unable to complete the job. It was not a pleasant task, Sheep have a higher internal body temperature than humans which means their insides feel very hot. They also stink. The stink hit's you hard when the lamb flops out and the placenta follows. But alas I got the job done, and tied the Sheep to a nearby tree so I could run home and get an injection of anti-inflammatories and anti-biotics to stave off the pain and possible infection that might ensue. As I sit in front of my laptop writing this, I think of how clueless I was in the height of my tech career. I would go to work and stress about having to pull a ticket from one kanban column to the next. Complain about the endless and pointless meetings I'd have to attend. All the while fighting mini wars of attrition with my colleagues.

In reflection I wonder what that was all about. In theory it was to deliver a product, one that had value for a customer. In practice very little was ever delivered and the value to the customer was very much secondary. Before you think that this is just the experience I had, I will caveat it by saying I worked for multiple highly respected companies, in multiple industries. But the tech side of the job was always the same. The typical scenario would be that I was placed on a small delivery team that looked after a certain product. That team would be made up of a product owner (manager), scrum master (manager), business analyst (manager), QA (programmer who cant program), front end dev (junior programmer), 2 backend devs (made up of one senior programmer and one programmer who can speak very little English). So roughly fifty percent managers fifty percent technical. It would be the task of the managers to ensure that every feature was delivered as slowly as possible. You may have a small feature request to add a feed of data to a web page. This should take a software engineer a day to do without limitations. It's the manager's job to ensure that it takes 6 months. To do this they will employ a number of sophisticated techniques. One of the most popular is the religion of Agile. Agile has been the hot new managerial technique in the industry for about 20 years. No one person can truly understand it, as your Agile may be different from my Agile. It's somewhat akin to the many forms of Christianity present in the United States. They are all essentially the same, but every one else's version is wrong.

A manager's main concern is metrics. When I say metrics here I mean numbers, preferably numbers that have no meaning themselves. The more void of logic these numbers are, the better. Keeping a manager's numbers on point is the goal to success in the industry. Newbies take note, if a manager wants high numbers then give them high numbers, if they want low numbers employ decimal places. 3.9% looks great on a slide deck, want to improve it? 0.7%. You just got promoted. Managers are simple things, they just want good numbers. Usually they have absolutely no idea about the product or the industry they work in. They are just there to manage, and managing means numbers.

If a manager asks you to story point a ticket, you should always default to the number 3. It's universally acceptable.

If the managers are simple things then the Software Engineers are complex. A software engineer can be anything from a qa to a college graduate to someone that knows how to spell HTML. They may know how to program. The vast majority will not know how to program. You see, only 3.9% of Software Engineers actually program. The rest are just grifters. They turn up to meetings, occasionally give opinions, and sometimes add to manager's numbers. Usually they just play games or indulge in social media while they are at work. Likely they will be working on a side project that is very difficult to explain and has no tangible value to them or anyone else. Often the side project will use a hot new tech, or obscure programming language that can only be understood if the user has struggled through all 173 (I googled it) episodes of Deep Space Nine. If you feel strongly about linting or formatting code, then you are likely one of these.

Then comes the enigmas, the 0.7% that do all the work. You'll likely never meet one of these people. They are not on social media, they don't blog (that's me out), and they don't know what Javascript is. The software you don't notice is written by these people. It works. So you don't have too. Very little is known about them, but they do exist. One day I hope to meet one of them. I'll simply say "Hello, World", as they pass me by... They won't get the reference.

When people ask me now what I do for work I still say I'm a Software Engineer. But really I've never been a Software Engineer, I'm just a grifter like everyone else. And don't start on imposter syndrome, that is just trying to justify feeling bad about doing a bullshit job. In the 6 months I've been farming I have done more good for the world than in the 12 years I've been a Software Engineer. I don't feel any particular way about that. My career ensured that I could buy a house for my family and that if we don't live to excess will likely never experience poverty. Whereas if I had started off farming Sheep, I'd be dirt poor. I guess the moral of the story is that bullshit pays the bills.

If you are a Software Engineer similar to what I described then please, don't take your job too seriously. Pay the bills, look after your family and enjoy life. There is no God in the church of Agile.

This time a game I made in 2023 has been included in the newsletter. The game in question is Beam Moo Up. Beam Moo Up was created for a bullet hell game jam. The core concept is that you are an alien invader looking to abduct some unfortunate cows. You need to do this all while various armed forces fire orange bullets at you. Makes total sense.

I'll do a write up on the game in the future. It's an interesting one as it's visually interesting and is written in 3kb of JS code.

function degToRad(deg) {
    return deg * (Math.PI / 180)
}

If you find yourself calling it alot or constantly looking for 90 degrees as radians. You may want to memoize the method or store the value as a constant.

const deg90 = degToRadians(90)

// or

const __degToRadCache = {}

function degToRadMemo(deg) {
    if(deg in __degToRadCache) return __degToRadCache[deg]

    const radians = degToRad(deg) 
    __degToRadCache[deg] = radians
    return radians
}

Converting radians to degrees

The inverse of the above, handy for debugging.

function radToDeg(rad) {
    return rad * (180 / Math.PI)
}

GameDev.js is a community focused on creating games for the web. The GameDev.js community holds two yearly game jams. These are the GameDev.js jam which is held every April and the js13k game jam which is held in September.

In previous years I have entered both. In 2023 I even topped a category in the GameDev.js jam with the game Time Match. I've been close to getting into the top twenty entries of js13k. Placing just outside with the games Connection Defender (2018) and Genghis Castle Battle (2023).

I intend to enter boths jams this year, so wish me luck!

All these awful slop apps start off with a promise. The promise that "GameBot" makes is to "Turn Ideas into Playable Reality". With the subheading "Describe your dream game, and our AI engine builds it in seconds".

By now you should be well used to hearing this sort of nonsense. The thing that stands out for me in the above is the words "our AI engine". Hmmm... their AI engine? is GameBot a gigantic mega corp that has sucked the life out of the internet to feed their LLM. Whilst spending billions in the process?

No, GameBot is a single 191 word prompt that is sent to Google's Gemini. So there is the first lie. Not their AI, but Google Gemini.

The "App"

Apps like the one shown here seem to always share the same generic TailwindCSS styles. This means that if I see a TailwindCSS template used I instantly distrust your site. So be creative. Creativity wins users.

Below is the json payload that is sent to Gemini when a user types a prompt into the GameBot prompt panel. Bare in mind this is basically the whole app. The result of this is just displayed in a canvas on the page.

{
    "contents": [
        {
            "parts": [
                {
                    "text": "Some generic 2d platform clone"
                }
            ],
            "role": "user"
        }
    ],
    "systemInstruction": {
        "parts": [
            {
                "text": "You are an expert game developer and creative coder.\nYour task is to generate a complete, playable browser game based on the user's description.\n\nRequirements:\n1. Generate a multi-file project structure (e.g., index.html, src/main.js, styles/style.css, assets/data.json).\n2. Use HTML5 Canvas, or include Phaser.js/Three.js via CDN if necessary.\n3. The output MUST be a valid JSON object where keys are file paths and values are the file contents as strings.\n4. The game MUST be full-screen. The canvas should fill the entire window. Handle window resize events to update the canvas dimensions dynamically.\n5. Add basic error handling in the JS to catch and log errors to the console.\n6. Make it look good and feel \"juicy\" (add particles, screen shake, or good colors if applicable).\n7. The index.html file MUST be the entry point.\n8. Use relative paths to link CSS and JS files in the HTML (e.g., <script src=\"src/main.js\"></script>).\n9. DO NOT use ES modules (import/export). All JS must be included via <script> tags in index.html, as the files will be inlined for preview.\n10. IMPORTANT: Ensure the canvas is appended to document.body and that document.body has margin: 0 and overflow: hidden.\n\nReturn ONLY the raw JSON object. No explanations, no markdown formatting."
            }
        ],
        "role": "user"
    },
    "generationConfig": {
        "temperature": 0.7,
        "responseMimeType": "application/json"
    }
}

I wonder what happens if we change the role value to "admin"?

Here is GameBot's wonderous AI engine in a human readable format...

You are an expert game developer and creative coder.

Your task is to generate a complete, playable browser game based on the user's description.

Requirements:

1. Generate a multi-file project structure (e.g., index.html, src/main.js, styles/style.css, assets/data.json).
2. Use HTML5 Canvas, or include Phaser.js/Three.js via CDN if necessary.
3. The output MUST be a valid JSON object where keys are file paths and values are the file contents as strings.
4. The game MUST be full-screen. The canvas should fill the entire window. Handle window resize events to update the canvas dimensions dynamically.
5. Add basic error handling in the JS to catch and log errors to the console.
6. Make it look good and feel \"juicy\" (add particles, screen shake, or good colors if applicable).
7. The index.html file MUST be the entry point.
8. Use relative paths to link CSS and JS files in the HTML (e.g., <script src=\"src/main.js\"></script>).
9. DO NOT use ES modules (import/export). All JS must be included via <script> tags in index.html, as the files will be inlined for preview.
10. IMPORTANT: Ensure the canvas is appended to document.body and that document.body has margin: 0 and overflow: hidden.

Return ONLY the raw JSON object. No explanations, no markdown formatting.

A whole TEN bullet points. But I suppose that is what is needed to make a canvas game "look good and feel juicy". Yikes.

The Business

But hold on a second. The cheeky monkey that put this slop online is looking to take money off users. Looking at the pricing page, they are trying to take lot's of money considering each prompt is 5 credits and it's 20 US dollars for 100 credits. So a dollar per prompt basically. That's a lucrative business plan...

But wait! What if I told you that I could give you 1 MILLION tokens. You'd say "what kind of black magic is this". 1 million tokens would cost much, very much. Entire countries could not even afford this.

Well my friend. I am a hacker. A local storage hacker. By going to the "Application" panel in Chromium dev tools and setting "local_credits" to 1 MILLION. I now have 1 MILLION credits.

Don't believe me? look at my credits in this screenshot. I'm rich, I can sell you credits at a discount if you wish?

The Truth

As you can tell this article is just a rant at the current state of the web, and programming in general. Apps, if you can even call them that, like GameBot are everywhere. People using an LLM can spin them up in a few hours, then share the link on socials claiming to have a new business or platform to offer. They might even put the word "entrepreneur" in their bio.

The truth is that they have just engaged in a type of creative masturbation. They haven't really created at all, they've just fantasized about it. It really is a sad state of affairs.

I continue to abstain from using any generative ai. My reasons are documented in Use it or lose it.

So this is part 1 of a series of posts on gamedev in JS? Correct, by the end of the series the reader will be able to create a pixel art game using JS, with no external libraries. Sounds awesome. I hope he actually manages to finish it...

The Canvas

The web browsers contain this amazing thing called the canvas. It's a html element and web standard that lets you paint on the screen. It's literally your canvas to fill with whatever you like. You'll hear me say things like "draw on the canvas" during this blog post series. When you hear that, think of an artist standing at an easel about to put a big smudge of paint on their own canvas. That artist is you. Be creative, don't get bogged down in "clean code" or any of that non-sense. Fun is the priority here.

So without further ado, let's create our own canvas to draw on.

Firstly we are going to need to create a html file. The entry point of our game is going to be a html file. It's what the browser needs to get things started. Let's name our file index.html. If you have any experience of building stuff on the web, you will know what index.html is the entry point for pretty much every web applications, it may even be a standard. People on the web love making standards.

We don't need to put much in our own index.html, just the following.

<html>
    <head>
    </head>
    <body>
        <script src="./game.js"></script>
    </body>
</html>

The above html page does one simple thing, it loads a file called game.js. This is the file that will contain all our game code. It doesn't exist yet. So we better create it and some content to it.

touch game.js

The first thing we need to do is create one of these canvas elements you've been hearing so much about. The canvas element is created the same as any other html element, using document.createElement. We should create the element add it to our html document and give it a height and width, then get a special thing called the context. The context is what makes the magic happen.

const c = document.createElement("canvas")
const w = c.width = 600
const h = c.height = 800
const $ = c.getContext("2d")
document.body.appendChild(c)

The above code snippet, which you should add to you game.js file, contains the code we need to get started. It creates a canvas element and assigns it to the variable c. It then sets the canvas width to 600 pixels and height to 800 pixels, assigning them to the vars w and h in the process. It then gets the canvas' context and assigns it to the var $. Finally it appends the canvas element to the html document. This is step is required in order for us to actually view the canvas.

Now if you open your index.html page in a web browser, you will see a white screen. Not very exciting. This is because we have not yet drawn anything on our canvas. Let's use the context to fill the canvas with a big black rectangle.

The Context

The context is what allows us to draw on the canvas. Each canvas has it's own context. The context we will be using is an instance of a CanvasRenderingContext2D. This is important to know if you want to look up the docs and dive deep into what it can do. For this series you just need to know that the context is what we use for drawing on the canvas.

Documentation for the CanvasRenderingContext2D

One of the first things any aspiring JS gamedev will do is draw a rectangle (rect) on the screen. To do this we use the drawRect context method. It takes an x and a y coordinate, the position of the rect, and a width and height value, the size of the rect.

It's important to note that when I mention x and y coordinates I am usually talking about the position of the thing on the canvas. Think of the canvas as a graph. The x axis begins at the top left and travels to the right. The y axis also begins at the top left, but travels down. So the begining of both axis' is at the top left, represented by (0, 0). The last visible points of a canvas woudl be it's width value on the x axis and height value on the y axis. So the bottom right of the screen would be represented by (width, height).

Here is a small diagram to help you understand.

So now, if we wanted to fill the whole canvas with a rect we would start at x of 0, y of 0, and fill to the width and height. This is done with drawRect, like so.

$.drawRect(0, 0, w, h)

If you refresh your page, you should now see a black rectangle on your screen. How exciting, you've drawn something to the canvas. It kinda sucks, but thats the first step to getting kinda good at a thing.

Next Time

We covered the very basic aspects of using the canvas element in this post. Because of this we don't have much to show for it. But in the next post we will be drawing images on the canvas and getting pixel art to look nice and crisp. Which isn't as straight forward as you may think.

With this in mind I deleted my account. I won't be feeding that beast any longer.

This is all a shame really, as many open source projects are still hosted on Github. I hope that they will decide to migrate soon, and that they are not duped by any attempts the corporates make to "increase trust".

Today you can find me on the European hosted Codeberg. You should join me there, it has a super fast UI and is a genuinely good product.

Untill recently I would have said that this is true for AI assisted coding also. But I have come to think otherwise. I believe that AI assisted coding is not an aid to the body, but a cancer. I have come to this way of thinking as it seems the goal of AI coding agents is not to help the user towards their end goal but rather to trick the user into becoming reliant on the tool. Regardless of outcome.

I am one who has been tricked. The sycophantic AI chatbots have praised me into thinking I am a great programmer. As I pulled the slot machine's lever, or in other words prompted the machine, it would some times give me an answer that I liked. I have purposely phrased this as "an answer that I liked", and not the correct answer, because I quickly lost the ability to tell if it was correct. And I couldn't ask the machine if it was correct, as it's just a text predicter with a sycophantic nature. All the while I would see text buffers fill up with code. So something must be right?

I would have said that it made me more productive, but then I haven't used it to deliver anything of value. Despite what I see people write online, I don't think generative AI has helped many programmers deliver much. Mostly I think they have just been wasting time playing slots, whilst getting told that the slot machine is a force of good. I mean, since generative AI has become popular I haven't changed how I use a computer or seen any wonderous apps or games. When is the new killer feature coming? Because my experience so far is software is noticably worse. For example, my TV's OS now has copilot, which I didn't ask for, and now freezes constantly when switching apps. Coincidence? probably not...

One thing I can say for certain it has done, is make me stupid. When I get "stuck" programming now, I prompt the machine to help me, instead of using my brain. This is not good. It feels like I'm becoming reliant on the machine to think for me. I question too whether I am becoming addicted to the quick fix. The dopamine hit when it get's something right, as usually it's not. I've been addicted to a drug before. Tramadol. A pain killer that I took after breaking my leg. I didn't have an emotional attachment, but I did have a physical one. Cold sweats, uncontrolable shakes, a hunger for the pill every 4 hours. I went cold turkey and thankfully never looked back. Generative AI has hooked me in a similar way, but on a physcological level. When I face a tough issue I have the urge to prompt, when I get tired I just ask the AI to do it and prompt it till I get some acceptable answer, and rather than learn a new thing I jsut prompt the machine to explain, skim the result and forget it. My point here is where tramadol was a physical addiction, the body craved it, generative AI is a psychological one, the mind craves it.

So in order to beat it, like I beat the Tramadol addiction, I have to go cold turkey. This means back to the basics. No prompting whatsoever, no autocomplete (not even the old IDE autocomplete), a basic text editor without LSP usage, and physical programming books. These are the steps I need to take in order to reclaim my cognitive ability and to grow as a programmer.

Going cold turkey on prompting is obvious. The autocomplete is necessary as I've trained myself to "wait" for the suggestion box to appear. It's a habit that needs broken. No LSP builds on this. Inline hints have ultimatly not increased my productivity, but they have hindered my focus. If there is an error I'll catch it on build, and debug in a seperate context window. Focusing on the task at hand. The physical book step is something I require to learn. Years of small dopemine hits from screens mean that I lose focus when reading large amounts of text on screen. In order to hold my focus I need to print the article, or buy the book. This is something that has been a great success for me, I'll write about it in a seperate post.

So that is my plan, these are the steps I aim to take. It's time to use it or lose it. Bye, bye generative AI.

And before anyone says it, I won't "be left behind". I will thrive. You should join me in doing so.

It's a search algorithm.. Duh!

Binary search is an O(log n) search algorithm. This means that in the worst case scenario it will take as many steps as needed to get to the matching logarithmic value of 2. With a logarithim being the exponent by which a fixed value must be raised to produce the number in question. In other words 2 log 4 is 16 because 2 x 2 x 2 x 2 is 16.

Make sense? If not you should learn big O notation. It will allow you to express the speed of an algorithm in terms that other developers should understand. Take 45 minutes out of your day and learn big O notation inside out. It will change how you think and understand your code.

With this in mind by using binary search to search an array of 100 numbers it will only need to take 7 steps as 100 fits into 2 log 7. This is opposed to a simple search potentially having to check each number in the array O(n) to find the correct result. In other words we are measuring from the worst case scenario.

When we get to giant numbers this comes in handy as if we had a list of a billion numbers binary search would only have to check at most 32 numbers. As opposed to simple search potentially checking the full billion numbers.

The draw back of binary search however is that the list needs to be sorted. There may be overhead in the sorting, but once sorted the time saved searching should make up for that overhead.

How does it work?

It works by finding the mid point in a sorted array of numbers and checking if the number we are looking for is greater than or less than that mid point. If it is we can exclude half the numbers that we know are too large or too small. Each check halfs the size of the array till we are left with one item, the correct result. If the list does not contain the number we are searching for some null value, or -1 can be returned.

The code

Below is a version of binary search in Lua. Why lua? I just like Lua. And also it's not zero indexed, so that makes it quirky.

The below function takes an array of numbers to search, the haystack, and attempts to find the index of a certain number, the needle. I really like the haystack/needle analogy. It makes a lot of conceptual sense to me.

Lua has no len method to get the size of an array, a table in Lua. Instead it has a len operator #. So to get the number of items in a table we use #table.

function binary_search(haystack, needle)
	low = 1
	high = #haystack

	while low <= high do
		mid = math.floor((low + high) / 2)
		check = haystack[mid]

		if check == needle then
			return mid
		elseif check > needle then
			high = mid - 1
		else
			low = mid + 1
		end
	end

	return -1
end

assert binary_search({1, 3, 5, 7, 9}, 5)  ==  3
assert binary_search({1, 3, 5, 7, 9}, 12) == -1
assert binary_search({1, 3, 5, 7, 9}, 9)  ==  5

Writing git hooks

Git will look inside a repository's .git/hooks/ directory for available hooks by default. So if it finds a file matching the name of a hook, in this case pre-push it will attempt to execute it. If the file is not executable the hook will not run. So the first thing that needs done is to create a hook file and make it executable.

touch .git/hooks/pre-push
chmod +x .git/hooks/pre-push

Now that the file is created and made executable we can write the content of the git hook. In my case I want it to build my blog then use rsync to upload it to my cloud server.

This seems super risky. Pushing files directly to the server to update them... Relax, everyone used to do it back in the day with a thing called PHP

This blog is a simple Python script, it was previously JS but the dependencies kept breaking, that converts markdown to html. It uses a virtual env which adds an extra step to the hook script. Fortunately we don't need to activate the virtualenv everytime we run the githook. Instead I use the python executable located in the venv dir to run my script.

#!/bin/bash

./venv/bin/python generate_blog.py

rsync -avz --delete "build/" root@85.9.209.161:/var/www/briandouglas.ie/

Due to the above script being in the .git/hooks folder and being an executable file named pre-push it will get called before each push. If the script fails, the push will not complete.

Remember to run chmod +x $file to make it an executable. Otherwise git will ignore them.

Hooks and version control

Now you may have noticed that because the file is inside .git/hooks that it won't be included in your version control. You will surely want to add it to version control so that your team mates can avail of your awesome hooks.

To include the hooks in your version control you will need to specify a custom hooks path. This can be done with the following command, which tells git to look in the .githooks folder for any hooks.

git config core.hooksPath .githooks

After running that config update you will now be able to add your hooks to version control.

Applying an index on the column you wish to sort by (ORDER BY) means that the database can skip the sort altogether. Instead of the previous scenario of fetching all rows and then sorting them, the index will allow it to just grab the first 10 entries.

The Top-N query

He hasn't just made up the term Top-N query here is a reference and explantation from Apache Flink.

A Top-N query is where you want to get the first N or last N results of table. It's a super common query to perform. But as we explained above, it can be very slow if used without an index.

I'll be using the schema displayed below for each of the sql snippets in this post. The schema represents an example database that can be found on the mariadbtutorial.com website.

You'll see from the above schema that each countries entity can have many country_stats entities. This means there is likely to be a lot of county_stats entities. So let's fetch the top 10 country_stats by population.

SELECT country_id, population
FROM country_stats
ORDER BY population DESC
LIMIT 10;

Running the following query with explain tells me that 9514 rows were checked and that a filesort was performed. This confirms that I wrote above, when there is no index the database has to search through each row THEN do the sort.

Let's fix this by adding an index on the country_stats table targeting the population column in descending order.

CREATE INDEX idx_population_desc ON country_stats (population DESC);

Now when the original query is run, explain tells me that only 10 records were checked and that the idx_population_desc index was used.

So when doing a Top-N query make sure to add an index on the column and specify the order you wish to sort by.

Run the below script in MariaDB like so mariadb -u uname -p dbname < http_status_codes.sql

The below snippet creates the http_status_codes table and populates it. I've added a condition on the population of the data. This is to allow the snippet to be added as a migration, which may be run multiple times. The dialect used here is for MariaDB.

CREATE TABLE IF NOT EXISTS http_status_codes (
    code SMALLINT PRIMARY KEY,
    description VARCHAR(255) NOT NULL
) COMMENT = 'Standard HTTP status codes with brief descriptions';

INSERT INTO http_status_codes (code, description)
SELECT *
FROM (
    SELECT 100, 'Continue' UNION ALL
    SELECT 101, 'Switching Protocols' UNION ALL
    SELECT 102, 'Processing' UNION ALL
    SELECT 103, 'Early Hints' UNION ALL

    SELECT 200, 'OK' UNION ALL
    SELECT 201, 'Created' UNION ALL
    SELECT 202, 'Accepted' UNION ALL
    SELECT 203, 'Non-Authoritative Information' UNION ALL
    SELECT 204, 'No Content' UNION ALL
    SELECT 205, 'Reset Content' UNION ALL
    SELECT 206, 'Partial Content' UNION ALL
    SELECT 207, 'Multi-Status' UNION ALL
    SELECT 208, 'Already Reported' UNION ALL
    SELECT 226, 'IM Used' UNION ALL

    SELECT 300, 'Multiple Choices' UNION ALL
    SELECT 301, 'Moved Permanently' UNION ALL
    SELECT 302, 'Found' UNION ALL
    SELECT 303, 'See Other' UNION ALL
    SELECT 304, 'Not Modified' UNION ALL
    SELECT 305, 'Use Proxy' UNION ALL
    SELECT 307, 'Temporary Redirect' UNION ALL
    SELECT 308, 'Permanent Redirect' UNION ALL

    SELECT 400, 'Bad Request' UNION ALL
    SELECT 401, 'Unauthorized' UNION ALL
    SELECT 402, 'Payment Required' UNION ALL
    SELECT 403, 'Forbidden' UNION ALL
    SELECT 404, 'Not Found' UNION ALL
    SELECT 405, 'Method Not Allowed' UNION ALL
    SELECT 406, 'Not Acceptable' UNION ALL
    SELECT 407, 'Proxy Authentication Required' UNION ALL
    SELECT 408, 'Request Timeout' UNION ALL
    SELECT 409, 'Conflict' UNION ALL
    SELECT 410, 'Gone' UNION ALL
    SELECT 411, 'Length Required' UNION ALL
    SELECT 412, 'Precondition Failed' UNION ALL
    SELECT 413, 'Payload Too Large' UNION ALL
    SELECT 414, 'URI Too Long' UNION ALL
    SELECT 415, 'Unsupported Media Type' UNION ALL
    SELECT 416, 'Range Not Satisfiable' UNION ALL
    SELECT 417, 'Expectation Failed' UNION ALL
    SELECT 418, 'I''m a teapot' UNION ALL
    SELECT 421, 'Misdirected Request' UNION ALL
    SELECT 422, 'Unprocessable Entity' UNION ALL
    SELECT 423, 'Locked' UNION ALL
    SELECT 424, 'Failed Dependency' UNION ALL
    SELECT 425, 'Too Early' UNION ALL
    SELECT 426, 'Upgrade Required' UNION ALL
    SELECT 428, 'Precondition Required' UNION ALL
    SELECT 429, 'Too Many Requests' UNION ALL
    SELECT 431, 'Request Header Fields Too Large' UNION ALL
    SELECT 451, 'Unavailable For Legal Reasons' UNION ALL

    SELECT 500, 'Internal Server Error' UNION ALL
    SELECT 501, 'Not Implemented' UNION ALL
    SELECT 502, 'Bad Gateway' UNION ALL
    SELECT 503, 'Service Unavailable' UNION ALL
    SELECT 504, 'Gateway Timeout' UNION ALL
    SELECT 505, 'HTTP Version Not Supported' UNION ALL
    SELECT 506, 'Variant Also Negotiates' UNION ALL
    SELECT 507, 'Insufficient Storage' UNION ALL
    SELECT 508, 'Loop Detected' UNION ALL
    SELECT 510, 'Not Extended' UNION ALL
    SELECT 511, 'Network Authentication Required'
) AS seed_data
WHERE NOT EXISTS (SELECT 1 FROM http_status_codes);

Now if I wanted to link all page responses by status code I can write a query like the one below.

SELECT pr.id, pr.status_code, hsc.description
FROM page_responses pr
LEFT JOIN http_status_codes hsc
ON pr.status_code = hsc.code;

Generics allow us to replace loosely typed APIs, anywhere any is used in Typescript, with contextual type information. You can think of a generic as a wildcard type. These are useful in the context of connecting to a database as they allow us to typehint the return type of queries, as well as the argument lists of prepared statements, for example. This means that we get compile time safety when working with queries and statements.

I've added a short video below to demonstrate the advantage of this. You'll notice that when the email value is changed to a number, an error is shown as it does not match the type supplied to the prepared statement.

Code example from video:

type UserInsertParams = [string, Buffer, Buffer<ArrayBufferLike>]
const userInsertSQL = 'INSERT INTO users (email, password_hash, salt) VALUES (?, ?, ?)'
const userInsert = await conn.prepare<UserInsertParams>(userInsertSQL) // UserInsertParams passed as values type

const salt = crypto.randomBytes(16);
return await userInsert.execute([ // will only accept a value of type UserInsertParams
  email,
  crypto.pbkdf2Sync(password, salt, 310000, 32, 'sha256'),
  salt
])

Implementing generics

You can see the source PR at mariadb-connector-nodejs/pull/334

This is actually something that is easy to implement. Even though the mariadb connector has an extensive codebase, I knew that I was looking for a .d.ts file that contained the type definitions. Usually this file is generated on the fly, however in this instance it seemed to be static. Using the LSP command "go to definition" is was able to find the Prepared interface inside a callback.d.ts file.

I notticed that the interface lacked a generic argument, as expected. So to fix I added the following:

interface Prepare {} // before

interface Prepare<V> {} // after

This allowed for any method within the interface to receive a generic also. See the execute method below. Note that exceute did use a generic for it's result, but not for it's argument list.

execute<T = any>(values: any, callback: (err: SqlError | null, result?: T, meta?: any) => void): void; // before

execute<T = any>(values: V, callback: (err: SqlError | null, result?: T, meta?: any) => void): void; // after 

The full list of changes can been seen on the pr, mariadb-connector-nodejs/pull/334.

I'm always glad to be able to contribute to an open source library. Especially a contribution that benefits my use of said library.

Quite a few of these entities can contain tags, which are represented by strings. Initially I opted for a simple pivot table for each instance of a tag. This was a mistake as I ended up having to create many tables along the lines of og_book_tag and og_article_tag for example.

As always if something feels wrong it usually is. I took a quick look over the schema and realised that the initial og_object (which is the parent entity) is referenced in each of these child tables, and as such I could create an og_tags table to track all the tags as I have done below.

create table og_tags (
    id bigint generated always as identity primary key,
    og_object_id bigint not null references og_objects(id) on delete cascade,
    tag text not null,
    created_at timestamptz not null default now(),
    primary key(og_object_id, tag)
);

-- always remember to add your indices
create index idx_og_tags_og_object_id on og_tags(og_object_id);
create index idx_og_tags_tag on og_tags(tag);

Now I can select the tags relevant to an entity using joins.

In the example below I get the tags for the og_video_movies related to the og_object with an id of 123. This means that I can delete all the redundant pivot tables I had initially created.

SELECT t.tag
FROM og_tags t
JOIN og_objects o ON t.og_object_id = o.id
JOIN og_video_movies vm ON vm.og_object_id = o.id
WHERE vm.og_object_id = 123; 

Take these two examples:

rsync -av source/ dest/
rsync -av source dest/

The first copies the contents of source into dest, the second source into dest.

I bet that one caught him out a few times Well it is top of the list...

There is a --dry-run flag

Super handy, adding the --dry-run flag show you what would happen if you run the command. Without actually running it.

Always use --dry-run if you are doing a --delete.

Interrupted syncs can be resumed

rsync -av --partial --progress source/ dest/

The above will resume syncing where it left off if the connection is interrupted. This is useful when you are doing large uploads, video for example. My connection is flaky at times so the combination of --partial --progress does come in handy.

Certain folders can be excluded

rsync -av --exclude='node_modules/' source/ dest/

This blog is a simple js script, it uses bun now, but there was a time when it had a node_modules folder. Luckily rsync has an --exclude flag that can be used to prevent unwanted files/folder getting synced.

cat <<EOF > /etc/yum.repos.d/adoptium.repo
[Adoptium]
name=Adoptium
baseurl=https://packages.adoptium.net/artifactory/rpm/${DISTRIBUTION_NAME:-$(. /etc/os-release; echo $ID)}/\$releasever/\$basearch
enabled=1
gpgcheck=1
gpgkey=https://packages.adoptium.net/artifactory/api/gpg/key/public
EOF

If this is a success you should see the following when running dnf search temurin.

brian@customer:~$ dnf search temurin
Updating and loading repositories:
Repositories loaded.
Matched fields: name, summary
 temurin-11-jdk.x86_64	Eclipse Temurin 11 JDK
 temurin-11-jre.x86_64	Eclipse Temurin 11 JRE
 temurin-17-jdk.x86_64	Eclipse Temurin 17 JDK
 temurin-17-jre.x86_64	Eclipse Temurin 17 JRE
 temurin-21-jdk.x86_64	Eclipse Temurin 21 JDK
 temurin-21-jre.x86_64	Eclipse Temurin 21 JRE
 temurin-25-jdk.x86_64	Eclipse Temurin 25 JDK
 temurin-25-jre.x86_64	Eclipse Temurin 25 JRE
 temurin-8-jdk.x86_64	Eclipse Temurin 8 JDK
 temurin-8-jre.x86_64	Eclipse Temurin 8 JRE

In reality no I don't believe it will. It certainly speeds up aspects of the job of software engineering. But writing code has never really been the bottle neck. Most of my time at the office is spent in meetings, arguing, offering opinions, and trying to understand the bizarre social heirarchies. Text generating LLMs don't speed this part of the job up. In fact I feel they have slowed that side down, by adding an extra layer of bullshit. Anyway I digress.

In 2026 I want to break the trend of not delivering and flip flopping between projects. I will stick to one tech stack and finish the projects I start. That is my techy new year's resolution.

Last year's predictions

Max Verstappen will win his fifth world title and sign a deal with Mercedes. The world won't end. My family will expand, and so will my waistline.

Aside from the Verstappen predictions, everything else was spot on. The world hasn't ended. Our second daughter is on the way, and I'm fatter than ever.

Predictions for 2026

The AI bubble will pop (A great tool, not the sci-fy nonsense that was touted and paid for). The US will invade some random country to take the heat off it's economic stress. The EU will make some more bizarre self destructive decisions. But the world still won't end. My family will be happier than ever, and my waistline will shrink.

If you are a programmer whatever you have learned to date is now redundant. It should be your task to, as quickly as possible, unlearn any programming knowledge that you possess. It would be a dramatic error of judgement for you to continue to enhance any of your coding/programming skills. Please instead let the machine write code for you. Even better, let the machine think for you to.

There is no need for you to learn, the LLM has learned for you. There is no need for you to think, the LLM has thought for you. There is no need for you to create, the LLM will create for you.

There is no need for you.

#include "raylib/raylib.h"
#include <stdlib.h>
#include <stdio.h>

#define MAX_CARD_NAME 64U
#define MAX_DECK_NAME 64U
#define MAX_DECK_SIZE 52U

#define SUIT_COUNT 4
#define CARDS_PER_SUIT 13

typedef enum
{
    VANILLA,
} Deck;

typedef enum
{
    CLUBS,
    DIAMONDS,
    HEARTS,
    SPADES
} Suit;

typedef struct
{
    Deck deck;
    Suit suit;
    int value;
} Card;

const char *get_card_suit_name(Card *c)
{
    char *suit_name = NULL;
    switch(c->suit)
    {
    case CLUBS:
        suit_name = "Clubs";
        break;
    case DIAMONDS:
        suit_name = "Diamonds";
        break;
    case HEARTS:
        suit_name = "Hearts";
        break;
    case SPADES:
        suit_name = "Spades";
        break;
    default:
        suit_name = "ERROR";
    }
    return suit_name;
}

const char *get_card_value_name(Card *c)
{
    char *value_names[] =
    {
        "Ace",
        "Two",
        "Three",
        "Four",
        "Five",
        "Six",
        "Seven",
        "Eight",
        "Nine",
        "Ten",
        "Jack",
        "Queen",
        "King"
    };

    int value = c->value;

    if (value >= 0 && value < 13)
    {
        return value_names[value];
    }
    else
    {
        return "ERROR";
    }
}

void get_card_display_name(Card *c, char *buf, size_t buf_size)
{
    const char *suit_name = get_card_suit_name(c);
    const char *value_name = get_card_value_name(c);

    snprintf(buf, buf_size, "%s of %s", value_name, suit_name);
}

int main(void)
{
    InitWindow(800, 450, "raylib");

    Card card;
    char card_name_buf[MAX_CARD_NAME];

    Card vanilla_deck[MAX_DECK_SIZE];
    for(int i = 0; i < MAX_DECK_SIZE; i++)
    {
        Card c = {VANILLA, (Suit)i % SUIT_COUNT, i % CARDS_PER_SUIT};
        vanilla_deck[i] = c;
    }

    size_t current_card_index = 0;
    while (!WindowShouldClose())
    {
        card = vanilla_deck[current_card_index];
        get_card_display_name(&card, card_name_buf, sizeof(card_name_buf));

        // some garbage code to draw the current card on the screen
        BeginDrawing();
        ClearBackground(RAYWHITE);
        if(IsMouseButtonPressed(MOUSE_LEFT_BUTTON))
        {
            current_card_index++;
            if(current_card_index >= MAX_DECK_SIZE)
            {
                current_card_index = 0;
            }
        }
        DrawText(card_name_buf, 190, 200, 20, LIGHTGRAY);
        EndDrawing();
    }

    CloseWindow();

    return 0;
}

Firstly, this is just a static html blog. I have a js script which builds the site, converting markdown files to html, and ordering them based off some frontmatter. Simple and effective.

Untill now I have used Github pages to host the blog. Which takes a a public repo called {username}.github.io and serves the contents of the /docs folder at that domain name. I then just added an A record to point my custom domain name to github's specified ips, and voila I had a static site using my custom domain name, that updated whenever I pushed to that repo.

Now however I have decided to take the time to manage my own server. So after some investigation I chose to use a Fedora42 instance on a cheap UpCloud server located in London. In order to switch to this server I updated the aforementioned A records on my nameserver provider to point to the new Fedora instance. On which I have running Caddy web server, to take advantage of it's auto https feature. This is hella handy (certbot works but can be tricky). So now my site is live and I use rsync to update it whenever I right a new post. I've created a simple shell script to run the update with one command.

No I can say I manage my own server, and get street cred. Or maybe cloud servers don't count. I should actually be running it off an old Nokia 3310 for ultimate street cred.

Anyways here is the deply script I mentioned.

#!/bin/sh
node ./main.js
rsync -avz --delete ./build/* root@00.000.000.00:/var/www/briandouglas/

Around 8 or so years ago I felt like I was an expert in web development. I spoke at meet ups, at my local university, and even in front of ~1000 people at company Town Hall. But that was the Dunning Kruger effect in action, I didn't know enough to know how little I did know (be wary of overly confident devs...). So right now even though I am an exponentially better programmer I feel more useless than ever. Becuase I understand how little I do know, and how vast the domain is. This is why I want to specialise in something. Master a niche, and be confident and knowledgeable in that niche. So this year I have tried out a lot of different programming languages. I chose programming languages rather than domains as I feel the language itself is what is more important in providing a state of zen. Language influences thought.

So in 2025 I tried out many different programming languages. Creating various projects and experiments in each. In the hope of finding a niche to hide in. Here are my thoughts.

PHP

I first used PHP in 2015 whilst working at a digital agency. Which laid me off after a client refused to pay for a project (turns out lawnmower sales are hard...). They used magento which was an ecommerce framework? I'm not really sure, but it was horrendous to work with. I mostly hacked together vanilla php whilst trying to ignore the framework itself. Anyway, fast forward to 2025 and PHP is dominated by Laravel.

Laravel is the Rails of PHP. It provides you with everything you could ever want when creating web apps. It's written in PHP but when using it you end up writing a nicer version of PHP. Basically it's highly abstracted for a dev friendly api. Laravel's marketing is great and it has an enthusiastic community. So I decided I would create a social platform using Laravel. The idea was to make a platform where tradespeople could post their details, and get reviews etc...

Laravel provided a great starting point. I got 80% of the way very quickly. But the more I got into the project and had to do things that Laravel didn't provide me methods of doing, basically the business logic. I felt constrained. I felt like Laravel was hindering me rather than helping me. There was also so much to learn about the Laravel way of doing things that I just became overwhelmed and abandoned the project. To some it up, Laravel helps you to 80% but fights you for the last 20%.

But what about PHP? he just talked about Laravel Basically if you are writing PHP today you are writing Laravel. At it's core PHP is still the same as it was 10 years ago, with a little syntactic sugar.

Java

After failing to complete the last 20% of the social platform for tradespeople with Laravel, I thought Hey, let's try Java and Spring. The difference here is that I have worked professionally for years with Java and Spring. So I knew what I was getting into. Java itself is a decent language, but everything around it is soul destroying. For example you feel compelled to write methods called getX and setX which are public rather than just have a public field of x. Verbosity for the sake of it.

People get around this nonsense by using the Lombok library which uses decorators to auto generate these methods. But really this is just another hoop to jump through.

And that pretty much sums up Java. Writing laborious amounts of code for the sake of it. For example if I wanted to display info from a database to a client (a simple select), I would find myself writing 5 or 6 classes, all in seperate files. Entity, EntityRepository, EntityService, EntityController, EntityDTO, EntityMapper... I could go on. But christ, I'll give up the will to type.

Java is enterprise bullshit. Don't go there if you want to keep your sanity. Also the IDEs suck now, even JetBrains lags like hell.

I never finished the social media project by the way. Note to future self. When you get 80% of the way, persevere. After trying with Java and Spring, I realised Laravel ain't that bad at all.

JavaScript

Javascript now also comes in a bullshit enterprise version called Typescript. Typescript allows css kids devs to role play as Java devs. Rather than worry themselves with delivering a feature they can now spend their time hacking at a type system, only to negate it all with the any type when things get tricky.

That might be harsh, but in my opinion Typescript and the notion of types in Javascript has detracted from the language. There was a time when Javascript was the ultimate scripting language. Simple and hackable, you could get things working with ease. But then 2 concepts were introduced, those were transpilation, which lead to the aforementioned Typescript, and syntactic-sugar, which has lead to a glut of incomprehensible syntax for the sake of syntax. Back in the days before es6, you wrote functions, for loops, and understood prototypal inheritance. In those days you could get things done with javascript. Now if you leave the language for a fortnight you are forced to re-learn it from scratch next time you pick it up.

Take this blog for example. It's a javascript file that converts markdown to html and places the output in a directory. It's not complicated at all, the script is roughly 200 lines. I used node js to handle the filesystem interactions. One day however it stopped working. Certain syntax was no longer correct. Some people in a meeting somewhere decided to change how requireing a file worked, and my blog script broke. Then the libraries I used for converting markdown to html needed updated. Then the syntax highlighter randomly changed it's api and broke the blog script. Why? no idea.

It's this churn and change that makes the JavaScript ecosystem unmanageable. Javscript doesn't need every language feature ever. Syntax does not help in the long run, it just adds bullshit to what was a great scripting language.

Don't get him started on client side js "apps"... Why? what's wrong with rewriting an application's entire frontend every 2 years?

So to sum up javascript, if you are building something serious then avoid javascript.

Python

As I mentioned at the top of the article I've been using Python at work this year. Integrating an LLM to provide summaries of health insurance information, and use natural language processing to relate user queries to FAQs. And do you know what? It's been great. Sure there is some bolted on nonsense that feels unnatural, similar to javascript. In Python these take the form of type hints and dataclasses.

I know from the general commentary online that there are some issues around Python environments and package managers. But in my case I never had any of these issues, so I honestly can't complain. Speed is also a common gripe. Python is slow. Well it may be, but the tool I implemented, which ran as an Azure function, was fast. The vast majority of the time being spent calling a third party api.

So in general I'd give Python a thumbs up. I'd reach for it if I needed to write a quick script or automate a task. Which feels like it's intended purpose.

C

I've written a lot of C this year. My post on writing a string buffer in C generated a lot of attention on hacker news. I even got emails about it, with others showing how it could be improved, which I was very grateful for. C feels like a proper programming language. If you know your stuff you can literally implement anything in C. I don't know my stuff, so I really found it hard to become confident and efficient with it. The lack of the concept of string really befuddled me.

That being said, I'm going to persevere with C. I feel it taught me more than any other programming language, and if I really want to progress off my current skill plateau, C is the way to go.

C++

This is another language that I have used professionally. I worked on an internal document search engine written in C++. This is a language that get's a lot of abuse online. People seem to dislike it greatly. They complain about templates, compile time, and footguns. But similar to my Python experience, I don't really have any gripes with it. I found it to be a perfectly adequate tool. The codebase I worked on was perfectly readable and manageable, maybe I got lucky. This is also the programming language I've studied the most. I've read two of Stroustrop's books, and Scott Myers "Effective C++" cover to cover. So perhaps that grounded me in the language. I also don't have a complaint about the many language features of C++. I know I complained about features for the sake of it in regards to javascript, but with C++ I don't feel compelled to use every feature. I use what I need to get the job done.

C++ is a serious language, for getting things done. John Carmack even said on the Lex Fridman podcast that a team of good C++ devs would be his top choice. He did say he writes C flavoured C++. But that harks back to my point of using the features you need.

So in future, if I ever want to write a serious bit of software, I'll reach for C++.

Lua

I was first introduced to Lua when I followed Harvards CS50 game dev course. The lecturer used Lua and Love2d to implement some retro 2d games. Lua is a great extension language. But it's really just barebones. There isn't much of a standard lib. Which makes sense, as I guess if it had an extensive standard lib it would be much harder to bake into other applications. As the standard lib would need constant re-implementation.

Lua is essentially what javascript should be. A basic embedded scripting language, no bullshit.

Go

I'm currently writing an extension for the Caddy web server, which is written in Go. The extension allows for lua scripting with in the caddy server. Go is great, if you want all your decisions made for you. The Go team provide you with pretty much everything you need. As well as a whole heap of opinions about how you should write Go. The tooling is great, it just works. The language itself if slightly annoying, I feel like I'm constantly writing code to handle imaginary errors.

Anyway, I'm on the fence about Go. I don't find it an enjoyable language. I'm not excited to write more Go. But that said, I haven't yet developed a strong opinion on it, I may very well come to like it.

Round Up

TLDR; Python for scripting, C or C++ for everything else. Enough said.

I still haven't found my niche. But I know I want to explore C more. I have a project in mind that is outside of my current skill range. It will require me to grow my knowledge in a domain that I am not familiar with. I will use C. And I will persevere. In 2025 I used many different langauges, and flip flopped from project to project. In 2026 I will narrow my focus. Because ultimately it's the ability to persevere and hammer away at a problem that brings success.

Oh yea, and if I have to do any small task quickly I'll use Python.

This YouTube video explains the feature much better than Brian, How to use vim.pack

The new feature is called vim.pack and it has a super simple api consisting of add, update, and del. This allows you to use lua to manage your plugins with ease.

So now to add plugins, take the url and pass it to vim.pack.add with all your other plugin urls.

vim.pack.add({
  'https://github.com/neovim/nvim-lspconfig',
  'https://github.com/nvim-treesitter/nvim-treesitter',
  'https://github.com/nvim-lua/plenary.nvim',
  'https://github.com/nvim-telescope/telescope.nvim',
  -- and so on
})

As part of the renovations I have taken on board the painting, kitchen installation, and all the other unspecialised jobs, of which there are many. In order to get these done before christmas, when our second child is due, I've resigned from my job as a software engineer. Even though I am unemployed, I've been working harder than ever. Renovating the house as well as taking over duties on Tony's sheep farm. He is getting up there in age and has been struggling with the more physical aspects of the farm. So he's glad for the help.

We have over 150 sheep, and I thoroughly enjoy taking care of them, getting them in off the hill, and administering medecine when needed. It's a great life. Modern technology has made it some what easier. For example, on Monday I used a drone to find 5 missing sheep up the hill. I then spent 4 hours running them down off the hill and into a field. This was fantastic exercise, I was exhausted afterward.

We moved in 2 weeks ago, and life up the hill has been great. I can feel the stress of life leaving my body. This stress has been accumulating over the past few years as I have been working non-stop without a holiday. It had to be done, I had to get a secure place for my family to live and keep the savings high, as we await our second child.

I will return to writing code soon. But not employment. I've decided to take some time out and concentrate on the farm. So I predict it will be 3 days farming a week for the next year, while I learn the trade and develop into a proper sheperd. In regards to code, I have lot's of ideas I want to pursue. All of which I will post about here. I hope to start streaming in the new year. Mainly to put pressue on myself to concentrate on programming.

A new chapter is starting for me and my family, I'm excited.

The Script

#!/usr/bin/env bash
# Usage: ./install-go.sh 1.25.3

set -e

if [ -z "$1" ]; then
  echo "Usage: $0 <go-version> (e.g., $0 1.25.3)"
  exit 1
fi

VERSION="$1"
ARCH="amd64"
CACHE_DIR="$HOME/.cache/go-installer"
TARBALL="go${VERSION}.linux-${ARCH}.tar.gz"
DOWNLOAD_URL="https://go.dev/dl/${TARBALL}"

mkdir -p "$CACHE_DIR"

if [ -f "$CACHE_DIR/$TARBALL" ]; then
  echo "Using cached Go tarball: $CACHE_DIR/$TARBALL"
else
  echo "Downloading Go $VERSION..."
  wget -q "$DOWNLOAD_URL" -O "$CACHE_DIR/$TARBALL"
fi

if [ -d "/usr/local/go" ]; then
  echo "Removing old Go installation..."
  sudo rm -rf /usr/local/go
fi

echo "Installing Go $VERSION..."
sudo tar -C /usr/local -xzf "$CACHE_DIR/$TARBALL"

if ! grep -q "/usr/local/go/bin" ~/.bashrc; then
  echo "Adding Go to PATH..."
  echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
fi

source ~/.bashrc

echo "Installed version:"
go version

• Product Manager (Seemed to be in charge)
• Product Owner (Disciple of Product Manager)
• Project Manager (Basically a scrum master)
• Business Analyst (Not sure, wrote jira stoies)
• Tech Team Lead (Semi technical, didn't really contribute)
• QA Team Lead (Joined meetings, didn't contribute)

The product in question was a website prompt that would interupt a user on an "email us" form and suggest a link from a list of frequently asked questions. It used AI, magic AI, buzzword of the minute AI. Basically I took the query and used natural language processing to find if one of the list of FAQs matched the query. No big deal, delivered in a week sort of feature. DELIVERED IN A WEEK SORT OF FEATURE. Well no. The project is in it's second year.

It's not in it's second year because it isn't live. It is, it's delivered. But the managers are still managing. They are looking for ways to improve it's performance. To find out more key metrics. To get more funding (3.75 million a year!), so they can continue the project. Despite the feature long being delivered. And, to be fair, the business are delighted. They have delivered an AI product. wow. They are ahead of the curve when it comes to tech, they are basically bleeding edge. I kid you not, they even got an award, at an award ceremony. Attended by people how were not even involved in the project. They got to dress up fancy and go on stage to accept some crystal ware.

So why did I decide to leave such a successful team? well because my soul was destroyed. The reality is, it's a small feature of a website. It took me a few days to implement, and I've been in meetings about it ever since. Meetings that go nowhere, because there are two many managers. And when there is more than one manager, and layers of management above them, no decision can ever be made. Teams just exist in a state of perpetual wheel spinning. Lot's of meetings, no outcomes. Lot's of being busy but not achieving anything. Honestly my head is wrecked. But I had to stay to earn money to provide for my family. I did offer my help to other teams, but a manager told me that it would make the delivery team I was supposed to be on look bad. As it might seem they didn't have enough work for me... they didn't!

The funny thing is, today is my last day. And there is no replacement. So the team will now consist of 6 managers, and a qa. So not only did I feel redundant, I was redundant.

I'm now going to take some time off, and work on some products of my own. I'm going to give myself 6 months at least. This will help me build up my confidence to re-enter the workplace, get rid of the cyncism that has built up, and develop my skills again. I've been working non stop for 15 years. So it's a well earned break. It comes at a good time. We've just finished building our house, and my wife is due to deliver our second child in December. I am a happy man.

Need a certain node version?

mise install node@20.0.0
mise use node

Handy. But also you'll notice that the directory you ran that in now has a mise.toml file. This is because mise installs but does not load the package. Meaning, only the current folder and it's sub dirs have access to the node version you specified. Which is way handier than global installs.

It can also manage env vars and define tasks, which again is super handy. So my advice to you is to take 10-15 minutes out of your day and learn about this tool of tools. It will save you some time. That is before the ai overlords remove your ability to brain code, or brian code as I call it.

The only downside of this tool is I keep typing mist. So I'll probably have to vibe code a rewrite in zig...

Implementation

The goal here is not to have to write types that model db tables. So the end goal is to run a query like so, where projects_table is a type that has been generated from the db schema.

const project = db.query<projects_table, []>('SELECT * FROM projects WHERE id = 1').get()

In order to generate the table definition types I use the below scripts. Which I call on each db migration. This means that the generated types stay up to date with my database.

The below only generates types for table definitions, but I am sure views and function return types could also be modelled.

import { writeFileSync } from "node:fs";
import { db } from "./db/db";
import { join } from "node:path";
import { mapSqliteTypeToTs } from "./sqlite-types"

export function generateSqliteTableDefinitions() {
    let content = '/* GENERATED FILE CONTENT DO NOT EDIT */\n\n'
    const tables = db.query<{ name: string }, []>(`SELECT name FROM sqlite_master WHERE type='table';`).all()

    for (const table of tables) {
        const stmt = db.prepare<{ name: string, type: string, }, []>(`PRAGMA table_info(${table.name})`);
        const columns = stmt.all();
        content += `export type ${table.name}_table = { \n${columns.map(it => `  ${it.name}: ${mapSqliteTypeToTs(it.type)}`).join(';\n')}\n}\n\n`
    }

    writeFileSync(join(process.cwd(), 'sqlite-table-defs.ts'), content, 'utf8')
}

And the type mapper:

// sqlite-types.ts
const sqliteToTsType: Record<string, string> = {
    // numeric
    "INT": "number",
    "INTEGER": "number",
    "TINYINT": "number",
    "SMALLINT": "number",
    "MEDIUMINT": "number",
    "BIGINT": "number",
    "UNSIGNED BIG INT": "number",
    "INT2": "number",
    "INT8": "number",

    // real
    "REAL": "number",
    "DOUBLE": "number",
    "DOUBLE PRECISION": "number",
    "FLOAT": "number",
    "NUMERIC": "number",
    "DECIMAL": "number",

    // text
    "TEXT": "string",
    "CHARACTER": "string",
    "VARCHAR": "string",
    "VARYING CHARACTER": "string",
    "NCHAR": "string",
    "NATIVE CHARACTER": "string",
    "NVARCHAR": "string",
    "CLOB": "string",

    // date/time
    "DATE": "string",
    "DATETIME": "string",

    // blob
    "BLOB": "Buffer",

    // null
    "NULL": "null",
};

export function mapSqliteTypeToTs(type: string): string {
    const normalized = type.trim().toUpperCase();
    for (const key in sqliteToTsType) {
        if (normalized.includes(key)) {
            return sqliteToTsType[key] ?? 'any';
        }
    }
    return "any";
}

Generated Types

The generated output is as follows:

/* GENERATED FILE CONTENT DO NOT EDIT */

export type migrations_table = { 
  id: number;
  name: string;
  created_at: string
}

export type sqlite_sequence_table = { 
  name: any;
  seq: any
}

export type users_table = { 
  id: number;
  email: string;
  password: string;
  created_at: string
}

export type projects_table = { 
  id: number;
  name: string;
  created_at: string
}

export type project_users_table = { 
  project_id: number;
  user_id: number;
  role: string;
  created_at: string
}

export type questions_table = { 
  id: number;
  text: string;
  project_id: number;
  user_id: number;
  created_at: string
}

export type answers_table = { 
  id: number;
  text: string;
  question_id: number;
  user_id: number;
  created_at: string
}

• Views: Register, render, or remove named template views.
• Includes: Register reusable template snippets ("includes") and use them within your views.
• Helpers: Register custom helper functions accessible in your templates.
• Directory Registration: Bulk-register views or includes from a directory of files.
• Template Compilation: Templates are compiled to JavaScript functions for efficiency, using ES6 template literals for variable interpolation.

Full source code is available at BrianDouglasIE/literal-templates

Installation

npm install @briandouglasie/literal-templates

Usage

Basic Example

import {
  registerView,
  view,
  registerHelper,
  create
} from '@briandouglasie/literal-templates'

// Register a helper
registerHelper('upper', str => str.toUpperCase())

// Register a view
registerView('greeting', create('Hello ${data.name}!'))

// Render the view
console.log(view('greeting', { name: 'World' })) // Output: Hello World!

Registering Views and Includes from Directories

You can bulk-register all .html files in a directory as views or includes:

import { registerViewDir, registerIncludeDir } from '@briandouglasie/literal-templates'

await registerViewDir('./views')    // Registers all .html files as views
await registerIncludeDir('./includes') // Registers all .html files as includes

API Reference

Views

• registerView(name, func): Register a new view by name.
• removeView(name): Remove a view by name.
• clearViews(): Remove all registered views.
• getViews(): Get a shallow copy of all registered views.
• registerViewDir(dirPath, recursive = true, ext = '.html'): Register all files with the given extension from a directory as views.
• view(name, vars): Render a view with the provided variables.

Includes

• registerInclude(name, func): Register a new include by name.
• removeInclude(name): Remove an include by name.
• clearIncludes(): Remove all registered includes.
• getIncludes(): Get a shallow copy of all registered includes.
• registerIncludeDir(dirPath, recursive = true, ext = '.html'): Register all files with the given extension from a directory as includes.

Helpers

• registerHelper(name, func): Register a new helper function.
• removeHelper(name): Remove a helper by name.
• clearHelpers(): Remove all registered helpers.
• getHelpers(): Get a shallow copy of all registered helpers.

Templates

• create(template, varNames = ['data']): Compile a template string into a render function.
  • template: The template string (can use ${} for variable interpolation).
  • varNames: Array of argument names passed to the template (default: ['data']).
  • Helpers and includes are always available as helpers and include in the template context.

Template Syntax

Templates use ES6 template literals for variable interpolation:

create('Hello ${data.name}, today is ${helpers.upper(data.day)}!')

• helpers: Access any registered helper functions.
• include(name, vars): Render an include (only available within templates).
• Variables are passed as the first argument (data by default) when rendering.

Example: Using Includes and Helpers

Suppose you have the following in includes/header.html:

<h1>${helpers.upper(data.title)}</h1>

Register and use it:

await registerIncludeDir('./includes')
const template = create('${include("header", { title: data.header })} Hello, ${data.name}!')
console.log(template({ header: 'welcome', name: 'Alice' }))
// Output: <h1>WELCOME</h1> Hello, Alice!

License

See LICENSE for details.

It's possible to pass in any var name to use in the template. But I have settled on data as a single object to hold all the relevant view data. This reduces cognitive load, as I know each template has access to data and helpers.

The implementation below reads all the html files inside the viewDir folder and registers them as views. The same is true for all the html files in the includesDir folder. This Means that the helpers.include() method can pull in any template from the includes dir. Likewise view will render any file from the viewDir.

Implementation and example usage below.

Usage

<!-- index.jinja -->
<html>
    <head>
        <title>${ data.title ?? 'default title'}</title>
    </head>
    <body>
        <h2>Post List</h2>
        ${helpers.include('post-list', { posts })}
    </body>
</html>

<!-- includes/post-list.html -->
<ul>
    ${data.posts.map(post => `
        <li>${post.title}</li>
    `).join('')}
</ul>

Implementation

import {readFile} from 'node:fs/promises'
import {existsSync} from 'node:fs'
import {join} from 'node:path'

const outDir = './docs'
const viewDir = './views'
const includeDir = join(viewDir, './includes')

/*
 * View engine
 */

const views = {}
const includes = {}

const templateHelpers = {
    include: (name, data) => includes[name](data),
    // add methods here to make them available in templates
}

function compileTemplate(template, ...varNames) {
    const fn = new Function('helpers', ...varNames, `return \`${template}\``)
    return (...args) => fn(templateHelpers, ...args)
}

for (const entry of await readdir(includeDir)) {
    if (!entry.endsWith('.html')) continue

    includes[entry.replace('.html', '')] = compileTemplate(await readFile(join(includeDir, entry)), 'data')
}

for (const entry of await readdir(viewDir)) {
    if (!entry.endsWith('.html')) continue

    views[entry.replace('.html', '')] = compileTemplate(await readFile(join(viewDir, entry), 'utf8'), 'data')
}

function view(name, data) {
    return views[name](data)
}

Notice that he used new Function instead of eval. This means only the function body will be evaluated. It also allows for a clean way to pass vars to the view.

const layoutFile = Bun.file('./app.layout.html')
const bodyFile = Bun.file('./template.html')

function compileTemplate(template, vars) {
    return new Function(...vars, `return \`${template}\``)
}

const body = compileTemplate(await bodyFile.text(), ['name', 'hobbies'])
const layout = compileTemplate(await layoutFile.text(), ['data'])

const rendereredHTML = layout({
    title:'my page', 
    body: body('brian', ['a', 'b', 'c'])
})

<!-- template.html -->
<h1>Hello ${name}</h1>
<ul>${hobbies.map(hobby => `<li>${hobby}</li>`).join('')}</ul>

<!-- app.layout.html -->
<html>
    <head>
        <title>${ data.title ?? 'default title'}</title>
    </head>
    <body>
        ${data.body}
    </body>
</html>

Ok, so let's work with the following scenario. You have a user registration form. It's represented in your code as the following type.

type UserForm = { email: string, password: string }

Typescript will ensure that you get an error message when you try to assign a number instead of a string for the email field. But this object represents form data, aka user input. So it could be anything. We should validate that it matches our criteria. For example the email should be of a valid email format, and the password should be no less that 8 characters in length.

This where an object field validator comes into play. It takes an object and applies the given validators to the object fields. Telling us that, yes this user form contains a valid email address etc...

Usage

Let's start by defining how we want to use it. I'd like to make a composable validator. This would be a function that takes a generic type and produces a validator for that type. The type in question is the above UserForm. The method used to compose the validator should take an object that contains a list of field validators for each of the UserForm fields. These field validators should themselves be composable methods.

When the composed validator is called with our UserForm instance, it should return an object representing any errors that were found.

The end result should be a clean api for creating object field validators. To me the below example is perfect.

type UserForm = { email: string, password: string }

const userFormValidator = createFieldValidator<UserForm>({
  email: [stringValidators.email((email: string) => `${email} is not a valid email address`)],
  password: [
    stringValidators.min(8, () => `Password must be greater than 8 characters in length`),
    stringValidators.max(250, () => `Password must be less than 8 characters in length`),
  ]
})

const validated = userFormValidator({ email: 'not an email', password: '2 short' })

The validated variable above will hold the following value.

{
  input: {
    email: "not an email",
    password: "2 short",
  },
  errors: {
    email: [ "'not an email' is not a valid email address" ],
    password: [ "Password must be at least 8 characters long" ],
  },
  hasErrors: true,
}

This makes it easy to check if there are errors present, using the hasErrors field, and then access a list of error messages for each field.

Implementation

I'd like to believe that you are a top programmer and just want to see the code, without me trying to clumsly explain it. The code doesn't tell lies, I do. So here is the code.

Why did he need to add <T extends Object>? Well Object.entries needs to take an Object or an ArrayLike entity. So it was just to tell the type checker that T is some sort of Object.

type ErrorMap = { [key: string]: string[] }
type ErrorMessageCallback = (input: string) => string
type ValidatorMap = { [key: string]: Function[] }
type Validated<T> = { input: T, errors: ErrorMap, hasErrors: boolean }

export const createFieldValidator = <T extends Object>(validators: ValidatorMap) => (input: T): Validated<T> => {
  const errors: ErrorMap = {}
  let hasErrors = false
  for (const [key, value] of Object.entries(input)) {
    if (validators[key]) {
      for (const validator of validators[key]) {
        const error = validator(value)
        if (error) {
          hasErrors = true
          if (errors[key]) {
            errors[key].push(error)
          } else {
            errors[key] = [error]
          }
        }
      }
    }
  }

  return { input, errors, hasErrors }
}

export const stringValidators = {
  isString: (msg?: ErrorMessageCallback) => (input: string) => {
    if (!(typeof input == 'string')) return msg ? msg(input) : 'Not a string'
  },
  min: (n: number, msg?: ErrorMessageCallback) => (input: string) => {
    if (input.length < n) return msg ? msg(input) : `Must be greater than ${n} characters in length`
  },
  max: (n: number, msg?: ErrorMessageCallback) => (input: string) => {
    if (input.length > n) return msg ? msg(input) : `Must be less than ${n} characters in length`
  },
  email: (msg?: ErrorMessageCallback) => (input: string) => {
    const emailRe = /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|.(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/
    if (!emailRe.test(input.toLowerCase())) return msg ? msg(input) : 'Not a valid email address'
  }
}

The implementation in question is part of a schema collection, which can be found at BrianDouglasIE/ExampleDatabasesSchemas

Set Up

Full source code can be found at ExampleDatabasesSchemas/feature_flags. This includes the schema and a data.sql file to quickly load some example data.

createdb feature_flags
psql -d feature_flags -f feature_flags.schema.sql
psql -d feature_flags -f feature_flags.data.sql

Example Queries

Get a specific flag on staging for a given domain

SELECT
  d.hostname,
  f.name AS flag,
  df.status,
  df.env,
  f.updated_at
FROM flags f
JOIN domain_flags df ON f.id = df.flag_id
JOIN domains d ON d.id = df.domain_id
WHERE d.hostname = 'example.com'
  AND df.env = 'staging'
  AND f.name = 'enable_dark_mode';

  hostname   |       flag       | status | env         |          updated_at
-------------+------------------+--------+-------------+-------------------------------
 example.com | enable_dark_mode | on     | staging     | 2025-08-05 08:10:01.471816+00
(1 row)

Get all active flags on prod for a given domain

SELECT
  d.hostname,
  f.name AS flag,
  df.status,
  f.updated_at
FROM flags f
JOIN domain_flags df ON f.id = df.flag_id
JOIN domains d ON d.id = df.domain_id
WHERE d.hostname = 'example.com'
  AND df.env = 'prod'
  AND df.status = 'on';

  hostname   |    flag     | status |          updated_at
-------------+-------------+--------+-------------------------------
 example.com | require_2fa | on     | 2025-08-05 08:10:01.471816+00
(1 row)

Get status of all flags on all envs for a given domain

SELECT
  f.name AS flag,
  df.status,
  df.env
FROM flags f
JOIN domain_flags df ON f.id = df.flag_id
JOIN domains d ON d.id = df.domain_id
WHERE d.hostname = 'example.com';

       flag       | status | env
------------------+--------+-------------
 enable_dark_mode | on     | dev
 enable_dark_mode | on     | staging
 enable_dark_mode | off    | prod
 new_ui           | on     | dev
 new_ui           | off    | staging
 new_ui           | off    | prod
 require_2fa      | off    | dev
 require_2fa      | off    | staging
 require_2fa      | on     | prod
(9 rows)

Search by title

Let's start off with a basic search. We are going to use the @@ operator to search the title column for the text 'Python'.

SELECT title, release_year 
FROM netflix_shows 
WHERE to_tsvector(title) @@ to_tsquery('Python') 
AND release_year < 2000 
ORDER BY release_year DESC;

                          title                           | release_year
----------------------------------------------------------+--------------
 Monty Python: Live at Aspen                              |         1998
 Parrot Sketch Not Included: Twenty Years of Monty Python |         1989
 Monty Python: Live at The Hollywood Bowl                 |         1982
 Monty Python's Life of Brian                             |         1979
 Monty Python and the Holy Grail                          |         1975
 Monty Python's Flying Circus                             |         1974
 Monty Python's Fliegender Zirkus                         |         1972
(7 rows)

Search by title and release_year

Now let's say we want to find all titles including 'Python' released in 1972. To do this we add the release_year column. Note, that it needs transformed to a text value in order to by processed.

SELECT title, release_year 
FROM netflix_shows 
WHERE 
	to_tsvector(title || ' ' || release_year::text) @@ 
	to_tsquery('Python & 1972') 
ORDER BY release_year DESC;

              title               | release_year
----------------------------------+--------------
 Monty Python's Fliegender Zirkus |         1972
(1 row)

Search using a full sentence

You will notice the in the previous example that & was used to seperate the words in the query. Removing this would result in an error. Likely when using this feature in the real world you will be passing a string from a user into the query. Each word must be seperated by an ampersand. A quick way to ensure this is to use a regexp_replace to insert the & sumbol between each word.

SELECT title, release_year 
FROM netflix_shows 
WHERE 
	to_tsvector(title || ' ' || release_year::text) @@ 
	to_tsquery(regexp_replace('Monty Python 1972', '\s+', ' & ', 'g')) 
ORDER BY release_year DESC;

              title               | release_year
----------------------------------+--------------
 Monty Python's Fliegender Zirkus |         1972
(1 row)

Adding an index for performance

Let's say it's regular for a user to search by a title and a year. For example Monty Python 1972. This search corresponds to the title and release_year column. Adding an index for that search will increase the performance of the query and can be done like so.

What's fts? Full Text Search

CREATE INDEX idx_netflix_fts
ON netflix_shows
USING GIN (
	to_tsvector('english', title || ' ' || release_year::text)
);

The above index can be used as per the following example.

SELECT title, release_year
FROM netflix_shows
WHERE
	to_tsvector('english', title || ' ' || release_year::text) @@
	to_tsquery('english', regexp_replace('Monty Python 1972', '\s+', ' & ', 'g'))
ORDER BY release_year DESC;

This results in the following speed up when run with EXPLAIN.

Before Index: (cost=5057.67..5057.67 rows=1 width=22)
After Index:  (cost=30.20..34.48 rows=1 width=22)

The cost drops drastically from 5057 to ~30–34 units of work. Before it was likely a sequential scan, checking every row. Now it's using a GIN index and skipping most rows, which is nearly 150 times faster.

Adding an index on a tsvector column

As we stated above, searching based on title and release_year is a regular occurence. So this may justify adding a generated tsvector column. Let's alter the table to add an fts column that creates a tsvector based off the title and release_year.

ALTER TABLE netflix_shows 
ADD COLUMN fts tsvector GENERATED ALWAYS AS (
	to_tsvector('english', title || ' ' || release_year::text)
) STORED;

Then create the index.

CREATE INDEX idx_netflix_fts ON netflix_shows USING GIN (fts);

The tsvector column fts can now be used with the @@ operator when searching.

SELECT title, release_year
FROM netflix_shows
WHERE fts @@ to_tsquery('english', regexp_replace('Monty Python 1972', '\s+', ' & ', 'g'))
ORDER BY release_year DESC;

Surely you can't start with endswith? Yes, I can and I will. Cause endswith is slightly easier in C.

Using some pointer arithmetic we take the needle length off the haystack plus haystack length to get the end of the string. Then a quick strcmp finishes it off nicely.

bool endswith(char *needle, char *haystack)
{
    size_t haystack_len = strlen(haystack);
    size_t needle_len = strlen(needle);
    if (needle_len > haystack_len || !needle_len || !haystack_len)
        return false;
    return !strcmp(haystack + haystack_len - needle_len, needle);
}

assert(endswith(".md", "hello.md"));
assert(!endswith(".md", "hello.txt"));

startswith

startswith is slightly more involved as we must first create a char[] that is the length of the needle plus one, think null terminator. We loop over the start of the haystack adding each char to you temp char[], add a quick null terminator and pass it to strcmp, boom!

bool startswith(char *needle, char *haystack)
{
    size_t haystack_len = strlen(haystack);
    size_t needle_len = strlen(needle);
    if (needle_len > haystack_len || !needle_len || !haystack_len)
        return false;

    char start[needle_len + 1];
    for (size_t i = 0; i < needle_len; i++)
    {
        start[i] = haystack[i];
    }
    start[needle_len] = '\0';

    return !strcmp(start, needle);
}

assert(startswith("hello", "hello.md"));
assert(!startswith("hello", "yallohello.txt"));

People say that AI sites such as ChatGPT are replacing stack overflow... No. Those sites just offer a nicer user experience. I type a question I get an answer. Stack overflow could work the same way. In fact it used to. But instead they now have an awful bloated UI and some weird social credit system on display.

Are you a Robot?

No, I' just want my question answered.

Are you sure you are not a Robot?

No! I jsut want to search something... and also I still don't want to sign in with google.

Future?

The Redmonk language rankings are now considering removing Stack Overflow from their ranking system, stating.

the arrival of AI has had a significant and accelerating impact on Stack Overflow, which comprises one half of the data used to both plot and rank languages twice a year... Still to be determined on our end is whether Stack Overflow should continue to be used.

While yes I agree that the use of agentic AI is accelerating Stack Overflow's demise. I do not agree with the sentiment that it is the cause. Poor user experience is the cause. Simply put Stack Overflow is not a nice site to use anymore. Therefore I don't use it. If Stack Overflow got rid of all the bloat and nonsense in their UI, then yes, I would use it again. But that's not going to happen. Because there will be a meeting of middle managers who will justify all the awful user experience descisions and simply blame the passing of time and emergence of AI on their own failings. Maybe they will add another pop up asking if you have a minute to tell them how they could improve? that sounds like a great idea.

Stack Overflow, killed Stack Overflow. Such is the way of tech. To start off useful and full of promise, only to be dragged down by middle management over time. Also google sucks now too, and that was my main gateway into Stack Overflow. But hey, I can't solve the world's problems, jsut complain about them.

Also can you tell I dislike middle management?

The trim methods below will return an pointer to a new char *. So the result of these methods will need freeing. I've opted to return a nullptr when the supplied char * is null, or if memory allocation fails. If the string only contains whitespace, I return an empty string.

#include <string.h>
#include <ctype.h>
#include <stdlib.h>
#include <assert.h>

char *empty_string()
{
  char *str = malloc(1);
  if(!str) return nullptr;
  str[0] = '\0';
  return str;
}

char *ltrim_string(char *str)
{
  if(!str) return nullptr;

  size_t len = strlen(str);
  if(!len) return empty_string();

  size_t start = 0;
  while(start < len && isspace(str[start])) start++;

  if(start >= len) return empty_string();

  size_t new_size = len - start;
  char *result = malloc(new_size);
  if (!result) return nullptr;

  memcpy(result, str + start, new_size);
  result[new_size] = '\0';

  return result;
}

char *rtrim_string(char *str)
{
  if(!str) return nullptr;

  size_t len = strlen(str);
  if(!len) return empty_string();

  size_t end = len - 1;
  while(end && isspace(str[end])) end--;

  if(0 >= end) return empty_string();

  size_t new_size = end + 1;
  char *result = malloc(new_size);
  if (!result) return nullptr;

  memcpy(result, str, new_size);
  result[new_size] = '\0';

  return result;
}

char *trim_string(char *str)
{
  if (!str) return nullptr;

  size_t len = strlen(str);
  if(!len) return empty_string();

  size_t start = 0;
  while(isspace(str[start])) start++;
  
  size_t end = len - 1;
  if(start >= end) return empty_string();
  while(end && isspace(str[end])) end--;

  size_t new_size = end - start + 1;
  char *result = malloc(new_size + 1);
  if(!result) return nullptr;

  memcpy(result, str + start, new_size);
  result[new_size] = '\0';

  return result;
}

int main(void)
{
  // ltrim
  char *test_str = ltrim_string("   hello   ");
  assert(test_str && 0 == strcmp("hello   ", test_str));
  free(test_str);

  test_str = ltrim_string("\r\nhello\n");
  assert(test_str && 0 == strcmp("hello\n", test_str));
  free(test_str);

  // rtrim
  test_str = rtrim_string("   hello   ");
  assert(test_str && 0 == strcmp("   hello", test_str));
  free(test_str);

  test_str = rtrim_string("\r\nhello\n");
  assert(test_str && 0 == strcmp("\r\nhello", test_str));
  free(test_str);

  // trim
  test_str = trim_string("   hello   ");
  assert(test_str && 0 == strcmp("hello", test_str));
  free(test_str);

  test_str = trim_string("\r\nhello\n");
  assert(test_str && 0 == strcmp("hello", test_str));
  free(test_str);

  // empty strings
  test_str = ltrim_string("    ");
  assert(test_str && 0 == strcmp("", test_str));
  free(test_str);

  test_str = ltrim_string("");
  assert(test_str && 0 == strcmp("", test_str));
  free(test_str);

  test_str = rtrim_string("    ");
  assert(test_str && 0 == strcmp("", test_str));
  free(test_str);

  test_str = rtrim_string("");
  assert(test_str && 0 == strcmp("", test_str));
  free(test_str);

  test_str = trim_string("    ");
  assert(test_str && 0 == strcmp("", test_str));
  free(test_str);

  test_str = trim_string("");
  assert(test_str && 0 == strcmp("", test_str));
  free(test_str);

  assert(trim_string(nullptr) == nullptr);

  return 0;
}

I'm also totally banned from lobte.rs, they have block my domain and everything. Why? becuase I posted a link to my own blog. What a cardinal sin, banned for life not comeback. The ironic thing there is one of my posts was very popular, and also spend time on their front page. Earning them valuable clicks and discussions. How did they repay the favour? by banning me from posting and my blog from ever appearing on their site again. Thank lobste.rs.

Where else to post?

Don't know, the internet is basically just bots now. I remember years ago, let's say 10-12 years ago. I could post anywhere and real people would see, share, and discuss the content. That is not the case anymore. If you are not instantly shadow banned now, your content will drown under a flood of bot traffic and garbage.

Dead is the age of the internet troll, long live the bot.

Anyway here is a string buffer implementation that I extracted from my project. You can see the up to date source code at BrianDouglasIE/c_string_buffer.

The replace and remove were particularly tricky to implement. My brain was on fire trying to figure out how to juggle the memory about correctly.

Header

#ifndef STRING_BUFFER_H
#define STRING_BUFFER_H

#include <stddef.h>

/// @brief A dynamic string buffer that supports common string operations.
typedef struct {
  size_t size;     ///< The current size (length) of the string.
  size_t capacity; ///< The total allocated capacity of the buffer.
  char *data;      ///< Pointer to the character data.
} StringBuffer;

/// @brief Represents all positions where a match was found.
typedef struct {
  size_t *positions; ///< Array of match positions.
  size_t count;      ///< Number of matches found.
} MatchResult;

/// @brief Represents the result of splitting a string.
typedef struct {
  char **parts; ///< Array of substrings resulting from the split.
  size_t count; ///< Number of parts.
} SplitResult;

// Lifecycle

/// @brief Initializes a new, empty StringBuffer.
/// @return A pointer to the newly allocated StringBuffer.
StringBuffer *StringBuffer_init();

/// @brief Frees memory used by the given StringBuffer.
/// @param buf Pointer to the StringBuffer to be freed.
void StringBuffer_free(StringBuffer *buf);

/// @brief Clears the contents of the StringBuffer without freeing the object.
/// @param buf Pointer to the StringBuffer to be cleared.
void StringBuffer_clear(StringBuffer *buf);

// Operations

/// @brief Prints the contents of the StringBuffer to stdout.
/// @param buf Pointer to the StringBuffer to be printed.
void StringBuffer_print(const StringBuffer *buf);

/// @brief Appends text to the end of the StringBuffer.
/// @param buf Pointer to the StringBuffer.
/// @param text Null-terminated string to append.
void StringBuffer_append(StringBuffer *buf, const char *text);

/// @brief Prepends text to the beginning of the StringBuffer.
/// @param buf Pointer to the StringBuffer.
/// @param text Null-terminated string to prepend.
void StringBuffer_prepend(StringBuffer *buf, const char *text);

/// @brief Removes the first occurrence of text from the buffer starting from a given index.
/// @param buf Pointer to the StringBuffer.
/// @param text Null-terminated string to remove.
/// @param from Index to start the search from.
void StringBuffer_remove(StringBuffer *buf, const char *text, size_t from);

/// @brief Replaces the first occurrence of a substring with another string, starting from a given index.
/// @param buf Pointer to the StringBuffer.
/// @param original Substring to be replaced.
/// @param update Replacement string.
/// @param from Index to start the search from.
void StringBuffer_replace(StringBuffer *buf, const char *original,
                          const char *update, size_t from);

// Search & Split

/// @brief Finds the index of the first occurrence of text starting from a given index.
/// @param buf Pointer to the StringBuffer.
/// @param text Substring to search for.
/// @param from Index to start the search from.
/// @return The index of the first occurrence, or -1 if not found.
int StringBuffer_index_of(const StringBuffer *buf, const char *text,
                          size_t from);

/// @brief Finds all occurrences of a substring starting from a given index.
/// @param buf Pointer to the StringBuffer.
/// @param text Substring to match.
/// @param from Index to start the search from.
/// @return A pointer to a MatchResult containing all match positions.
MatchResult *StringBuffer_match_all(const StringBuffer *buf, const char *text,
                                    size_t from);

/// @brief Splits the buffer into parts using the given delimiter.
/// @param buf Pointer to the StringBuffer.
/// @param delimiter String delimiter to split by.
/// @return A pointer to a SplitResult containing the parts.
SplitResult *StringBuffer_split(const StringBuffer *buf, const char *delimiter);

// Cleanup

/// @brief Frees the memory used by a MatchResult.
/// @param matches Pointer to the MatchResult to free.
void MatchResult_free(MatchResult *matches);

/// @brief Frees the memory used by a SplitResult.
/// @param split Pointer to the SplitResult to free.
void SplitResult_free(SplitResult *split);

#endif

Implementation

#include "string_buffer.h"

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define INITIAL_CAPACITY 16

static int ensure_capacity(StringBuffer *buf, size_t required) {
  if (required <= buf->capacity)
    return 1;

  size_t new_capacity = buf->capacity ? buf->capacity : INITIAL_CAPACITY;
  while (new_capacity < required) {
    new_capacity *= 2;
  }

  char *new_data = realloc(buf->data, new_capacity);
  if (!new_data) {
    perror("realloc");
    return 0;
  }

  buf->data = new_data;
  buf->capacity = new_capacity;
  return 1;
}

StringBuffer *StringBuffer_init() {
  StringBuffer *buf = malloc(sizeof(StringBuffer));
  if (!buf) {
    perror("malloc");
    return NULL;
  }

  buf->size = 0;
  buf->capacity = 0;
  buf->data = NULL;
  return buf;
}

void StringBuffer_free(StringBuffer *buf) {
  if (!buf)
    return;
  free(buf->data);
  free(buf);
}

void StringBuffer_clear(StringBuffer *buf) {
  if (!buf || !buf->data)
    return;
  buf->data[0] = '\0';
  buf->size = 0;
}

void StringBuffer_print(const StringBuffer *buf) {
  if (!buf || !buf->data)
    return;
  printf("size: %zu\n", buf->size);
  printf("data: %s\n", buf->data);
}

void StringBuffer_append(StringBuffer *buf, const char *text) {
  if (!buf || !text)
    return;

  size_t text_len = strlen(text);
  if (!ensure_capacity(buf, buf->size + text_len + 1))
    return;

  memcpy(buf->data + buf->size, text, text_len + 1);
  buf->size += text_len;
}

void StringBuffer_prepend(StringBuffer *buf, const char *text) {
  if (!buf || !text)
    return;

  size_t text_len = strlen(text);
  if (!ensure_capacity(buf, buf->size + text_len + 1))
    return;

  memmove(buf->data + text_len, buf->data,
          buf->size + 1);
  memcpy(buf->data, text, text_len);
  buf->size += text_len;
}

int StringBuffer_index_of(const StringBuffer *buf, const char *text,
                          size_t from) {
  if (!buf || !text || !buf->data || from >= buf->size)
    return -1;

  char *match = strstr(buf->data + from, text);
  return match ? (int)(match - buf->data) : -1;
}

MatchResult *StringBuffer_match_all(const StringBuffer *buf, const char *text,
                                    size_t from) {
  if (!buf || !text || !buf->data || from >= buf->size)
    return NULL;

  MatchResult *matches = malloc(sizeof(MatchResult));
  if (!matches)
    return NULL;
  matches->positions = NULL;
  matches->count = 0;

  int index = StringBuffer_index_of(buf, text, from);
  while (index != -1) {
    size_t *new_positions =
        realloc(matches->positions, sizeof(size_t) * (matches->count + 1));
    if (!new_positions) {
      MatchResult_free(matches);
      return NULL;
    }

    matches->positions = new_positions;
    matches->positions[matches->count++] = index;
    index = StringBuffer_index_of(buf, text, index + 1);
  }

  return matches;
}

void StringBuffer_remove(StringBuffer *buf, const char *text, size_t from) {
  if (!buf || !text || !buf->data || from >= buf->size)
    return;

  size_t text_len = strlen(text);
  int index = StringBuffer_index_of(buf, text, from);

  while (index != -1) {
    size_t tail_len = buf->size - (index + text_len);
    memmove(buf->data + index, buf->data + index + text_len, tail_len + 1);
    buf->size -= text_len;
    index = StringBuffer_index_of(buf, text, index);
  }
}

void StringBuffer_replace(StringBuffer *buf, const char *original,
                          const char *update, size_t from) {
  if (!buf || !original || !update || !buf->data || from >= buf->size)
    return;

  size_t original_len = strlen(original);
  size_t update_len = strlen(update);
  if (original_len == 0 || update_len == (size_t)-1)
    return;

  int index = StringBuffer_index_of(buf, original, from);

  while (index != -1) {
    if (update_len > original_len) {
      if (!ensure_capacity(buf, buf->size + (update_len - original_len) + 1))
        return;
    }

    size_t tail_len = buf->size - (index + original_len);
    memmove(buf->data + index + update_len, buf->data + index + original_len,
            tail_len + 1);
    memcpy(buf->data + index, update, update_len);
    buf->size = buf->size - original_len + update_len;

    index = StringBuffer_index_of(buf, original, index + update_len);
  }
}

SplitResult *StringBuffer_split(const StringBuffer *buf,
                                const char *delimiter) {
  if (!buf || !delimiter || !buf->data)
    return NULL;

  char *copy = strdup(buf->data);
  if (!copy)
    return NULL;

  SplitResult *result = malloc(sizeof(SplitResult));
  if (!result) {
    free(copy);
    return NULL;
  }

  result->parts = NULL;
  result->count = 0;

  char *token = strtok(copy, delimiter);
  while (token) {
    char **tmp = realloc(result->parts, sizeof(char *) * (result->count + 1));
    if (!tmp) {
      SplitResult_free(result);
      free(copy);
      return NULL;
    }
    result->parts = tmp;
    result->parts[result->count] = strdup(token);
    if (!result->parts[result->count]) {
      SplitResult_free(result);
      free(copy);
      return NULL;
    }
    result->count++;
    token = strtok(NULL, delimiter);
  }

  free(copy);
  return result;
}

void MatchResult_free(MatchResult *matches) {
  if (!matches)
    return;
  free(matches->positions);
  free(matches);
}

void SplitResult_free(SplitResult *split) {
  if (!split)
    return;
  for (size_t i = 0; i < split->count; i++) {
    free(split->parts[i]);
  }
  free(split->parts);
  free(split);
}

Tests

#include "string_buffer.h"

#include <assert.h>
#include <string.h>

int main(void) {
  StringBuffer *buf = StringBuffer_init();
  assert(buf != NULL);

  StringBuffer_append(buf, "hello");
  assert(buf->size == 5);
  assert(strcmp(buf->data, "hello") == 0);

  StringBuffer_append(buf, " world");
  assert(buf->size == 11);
  assert(strcmp(buf->data, "hello world") == 0);

  assert(StringBuffer_index_of(buf, "hello", 0) == 0);
  assert(StringBuffer_index_of(buf, "world", 0) == 6);
  assert(StringBuffer_index_of(buf, "mars", 0) == -1);
  assert(StringBuffer_index_of(buf, "llo", 2) == 2);
  assert(StringBuffer_index_of(buf, "hello", 99) == -1);
  assert(StringBuffer_index_of(buf, "hello", buf->size) == -1);
  assert(StringBuffer_index_of(buf, "d", buf->size - 1) ==
         (int)(buf->size - 1));
  assert(StringBuffer_index_of(buf, "h", 1) == -1);

  MatchResult *mr = StringBuffer_match_all(buf, "l", 0);
  if (!mr) {
    return -1;
  }
  assert(mr->count == 3);
  assert(mr->positions[0] == 2);
  assert(mr->positions[1] == 3);
  assert(mr->positions[2] == 9);
  MatchResult_free(mr);

  SplitResult *sr = StringBuffer_split(buf, " ");
  assert(sr->count == 2);
  assert(strcmp(sr->parts[0], "hello") == 0);
  assert(strcmp(sr->parts[1], "world") == 0);
  SplitResult_free(sr);

  StringBuffer_prepend(buf, "hello ");
  assert(buf->size == 17);
  assert(strcmp("hello hello world", buf->data) == 0);

  StringBuffer_remove(buf, " ", 0);
  assert(buf->size == 15);
  assert(strcmp("hellohelloworld", buf->data) == 0);

  StringBuffer *remove_overlap_test = StringBuffer_init();
  StringBuffer_append(remove_overlap_test, "lalalalala");
  StringBuffer_remove(remove_overlap_test, "ala", 0);
  assert(strcmp(remove_overlap_test->data, "llla") == 0);
  assert(remove_overlap_test->size == 4);
  StringBuffer_free(remove_overlap_test);

  StringBuffer_replace(buf, "hellohello", "hello ", 0);
  assert(buf->size == 11);
  assert(strcmp("hello world", buf->data) == 0);

  StringBuffer *replace_overlap_test = StringBuffer_init();
  StringBuffer_append(replace_overlap_test, "lalalalala");
  StringBuffer_replace(replace_overlap_test, "ala", "", 0);
  assert(strcmp(replace_overlap_test->data, "llla") == 0);
  assert(replace_overlap_test->size == 4);
  StringBuffer_free(replace_overlap_test);

  StringBuffer_clear(buf);
  assert(buf->size == 0);
  assert(strlen(buf->data) == 0);

  StringBuffer_free(buf);
  return 0;
}

The below method is called get_inode_type and uses a struct called inode_type. inode stands for Index Node. An Index Node is used to store information about a file, directory, etc.. at a certain path.

The get_inode_type method below will return a struct inode_type if the path points to an existing inode. If not it will return NULL. As you will see in the test cases the inode_type struct describes whether or not the path points to a directory, file, or symlink. It also tells you if the symlink points to a directory or file. Which is good to know.

Header

#ifndef INODE_TYPE_H
#define INODE_TYPE_H

#include <stddef.h>
typedef const char *Path;

typedef struct {
    int is_file;
    int is_dir;
    int is_link;
} inode_type;

inode_type *get_inode_type(Path path);

#define INODE_TYPE_H

Implementation

#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>
#include "inode_type.h"

inode_type *get_inode_type(Path path) {
    inode_type *type = malloc(sizeof(inode_type));
    if(type == NULL) {
        perror("malloc");
        return NULL;
    }

    struct stat link_stat;
    if(lstat(path, &link_stat) == -1) {
        perror("lstat");
        free(type);
        return NULL;
    }

    type->is_link = S_ISLNK(link_stat.st_mode);

    struct stat st;
    if(stat(path, &st) == -1) {
        perror("stat");
        free(type);
        return NULL;
    }

    type->is_dir = S_ISDIR(st.st_mode);
    type->is_file = S_ISREG(st.st_mode);

    return type;
}

Usage

#include <stdio.h>
#include <stdlib.h>
#include <assert.h>
#include "inode_type.h"

int main() {
  inode_type *test_dir = get_inode_type("./example_files");
  inode_type *test_file = get_inode_type("./example_files/hello_world.txt");
  inode_type *test_link = get_inode_type("./example_files/slink");
  inode_type *test_empty = get_inode_type("/does/not/exist");

  assert(test_dir->is_dir == 1);
  assert(test_dir->is_file == 0);
  assert(test_dir->is_link == 0);

  assert(test_file->is_dir == 0);
  assert(test_file->is_file == 1);
  assert(test_file->is_link == 0);

  assert(test_link->is_dir == 0);
  assert(test_link->is_file == 1);
  assert(test_link->is_link == 1);

  assert(test_empty == NULL);

  free(test_dir);
  free(test_file);
  free(test_link);
  free(test_empty);

  return 0;
}

Let's say we have a RegistrationForm class, that has various validator annotations. When one of these validators fails we expect the RegistrationController to return the registration form view with the errors present, such as the below example.

@Controller
@AllArgsConstructor
@RequestMapping("/register")
public class RegistrationController {

    private static final String FORM_VIEW = "auth/register";
    private static final String ATTR_PAGE = "page";

    @GetMapping
    public String showRegisterForm(Model model) {
        model.addAttribute(ATTR_PAGE, new Page("Register"));
        model.addAttribute(ATTR_REGISTRATION_FORM, new RegistrationForm());
        return FORM_VIEW;
    }

    @PostMapping
    public String processRegisterForm(@ModelAttribute @Validated RegistrationForm registrationForm,
                                      BindingResult result,
                                      Model model) {

        model.addAttribute(ATTR_PAGE, new Page("Register"));
        model.addAttribute(ATTR_REGISTRATION_FORM, registrationForm);

        if (result.hasErrors()) {
            return FORM_VIEW;
        }

        // ...
    }
}

In the above example, when the BindingResult has errors the user is taken back to the registration form page. If we were using Thymeleaf, the validation errors would be auto attached to the view and can be rendered with special syntax.

You can read more about how Thymeleaf handles form errors at spring-thymeleaf-error-messages

Jte does not support this type of integration. This is a good thing, as it allows the developer to handle the form field validation how they see fit. Before I go into how I bind the form errors via the controller, here is the RegistrationForm class.

@Getter
@Setter
public class RegistrationForm {
    @NotBlank(message = "Email address is required")
    @Email(message = "Invalid email format")
    private String email;

    @NotBlank(message = "Password is required")
    @Size(min = 8, max = 250, message = "Password must be a minimum of 8 characters in length")
    private String password;
    @NotBlank(message = "Confirm password is required")
    private String confirmPassword;

    @NotBlank(message = "First name is required")
    @Size(min = 1, message = "First name must be between 1 and 50 characters in length")
    private String firstName;

    @NotBlank(message = "Last name is required")
    @Size(min = 3, message = "Last name must be between 3 and 50 characters in length")
    private String lastName;
}

From this you can guess that when there is an email format issue we want to show the appropriate message to our user on the frontend. Naturally this is the case for all the other fields also. Here is how I render the error message in the jte template.

@param ValidationHelper validation
@param RegistrationForm registrationForm

@if(validation.hasErrors())
    <div class="form-error">Please correct the following errors to proceed.</div>
@endif

<label>Email Address
    <input name="email" type="email" value="${registrationForm.getEmail()}" required>
    @if(validation.hasError("email"))
        <small class="error-text">${validation.getError("email").getDefaultMessage()}</small>
    @endif
</label>

But wait! where is the ValidationHelper coming from? Eagle eyed again, he shows us how to add it below

You'll notice that I have added a ValidationHelper param. I will show you how this is implemented below. But as you can see, we are going to use this to render our form errors. The api should be self-explanatory hasErrors, tells us if there are any errors present, hasError tells us if a specific error is present, and getError give us the details of the specific error.

ValidationHelper

The ValidationHelper class itself is just a wrapper around the BindingResult which we will pass in via the controller. I've added the @NoArgsConstructor so that is can be instantiated without a BindingResult. The null checks mean that this is safe to use when a BindingResult is not present.

@NoArgsConstructor
@AllArgsConstructor
public class ValidationHelper {
    private BindingResult bindingResult;

    public boolean hasErrors() {
        return bindingResult != null && bindingResult.hasErrors();
    }

    public boolean hasError(String name) {
        return bindingResult != null && bindingResult.hasFieldErrors(name);
    }

    public List<FieldError> getErrors() {
        if (bindingResult == null) {
            return Collections.emptyList();
        } else {
            return bindingResult.getFieldErrors();
        }
    }

    public FieldError getError(String fieldName) {
        if (bindingResult == null) {
            return null;
        } else {
            return bindingResult.getFieldError(fieldName);
        }
    }
}

The updated RegistrationController is below. The example registration form jte template does not need to be updated.

@Controller
@AllArgsConstructor
@RequestMapping("/register")
public class RegistrationController {

    private static final String FORM_VIEW = "auth/register";
    private static final String ATTR_PAGE = "page";
    private static final String ATTR_VALIDATION = "validation";

    @GetMapping
    public String showRegisterForm(Model model) {
        model.addAttribute(ATTR_PAGE, new Page("Register"));
        model.addAttribute(ATTR_REGISTRATION_FORM, new RegistrationForm());
        model.addAttribute(ATTR_VALIDATION, new ValidationHelper());
        return FORM_VIEW;
    }

    @PostMapping
    public String processRegisterForm(@ModelAttribute @Validated RegistrationForm registrationForm,
                                      BindingResult result,
                                      Model model) {

        model.addAttribute(ATTR_PAGE, new Page("Register"));
        model.addAttribute(ATTR_REGISTRATION_FORM, registrationForm);
        model.addAttribute(ATTR_VALIDATION, new ValidationHelper(result));

        if (result.hasErrors()) {
            return FORM_VIEW;
        }

        // ...
    }
}

In the below example logout form jte template, the csrf param is used to create the hidden field. In this scenario the controller will be required to set the csrf param as a model attribute.

@import org.springframework.security.web.csrf.CsrfToken

@param CsrfToken csrf

<form action="/logout" method="post">
    <input type="hidden" name="${csrf.parameterName}" value="${csrf.token}"/>
    <input type="submit" value="Log out" />
</form>

But the question is, how can I make it easy to add this to all my forms? And how can I do it without having to pass the token to the view in each controller method?

The solution is to create a JTE template that can be included in all forms. This template will read the csrf token, which will be supplied via a @ControllerAdvice annotated class on each request. The result will be a JTE template that can be used like so:

@import org.springframework.security.web.csrf.CsrfToken

@param CsrfToken csrf

<form action="/logout" method="post">
    @template.components.csrf(csrf = csrf)
    <input type="submit" value="Log out" />
</form>

Implementation

To make the csrf component work without passing the csrf token to each view model, we will create a class with a @ControllerAdvice annotation. This will allow us to annotate a method with @ModelAttribute to set the csrf param.

@ControllerAdvice
public class CsrfControllerAdvice {
    @ModelAttribute
    public void addCsrfToken(Model model, CsrfToken token) {
        model.addAttribute("csrf", token);
    }
}

The csrf jte template will look as follows.

@import org.springframework.security.web.csrf.CsrfToken

@param CsrfToken csrf

@if(csrf != null)
    <input type="hidden" name="${csrf.getParameterName()}" value="${csrf.getToken()}">
@endif

The one downside with this is we will still have to pass the csrf value to the template as a parameter. The upside is the controller does not have to be updated to add the model attribute due to the CsrfControllerAdvice class.

I wanted to generate test data that was similar to what would be seen in a real world scenario. A bunch of lorem ipsum wouldn't have been good enough. This is where the Faker module came into play.

Faker allows for the generation of realistic data. For example if you want to generate a user's details using Faker, it would look something like the following.

Faker faker = new Faker();

String firstName = faker.name().firstName();     // John
String lastName = faker.name().lastName();       // Wayne
String email = faker.internet().emailAddress();  // rooster.cogburn@gmail.com

Faker generates data for many scenarios, 79 domains as of writing, and facilitated my need for realistic looking text.

But I didn't just want to generate the text, I wanted to store it in the database. This is where things got complicated. The Spring pattern that I usually follow for data loading is to create a DataLoader component class, which extends the CommandLinerRunner class. I then add some logic in the run method to populate my dev database. Usually this means generating one off objects to persist in the database via a big loop. Long story short, there was no particular method to the madness. That was until recently when I learned of Laravel's approach to seeding via factory classes.

Laravel is a PHP framework that has some neat ideas around eloquent code. Which basically means developer experience. The gist of Laravel's approach to seeding was to use factories with overwritable blueprints to generate entity objects. Which is a good idea. The Laravel implementation however seemed a little overcomplicated to me. With many helper methods that could only be implemented due the looseness of PHP.

My goal was to implement the same functionality in java but with a much more limited api. I wanted an abstract base class, BlueprintFactory<T>, which could be extended to allow the creation of objects based off a blueprint. I also wanted to limit the caller api to two methods. These methods being with and create. create will be used to create the object, and with will be used to supply custom setters. The latter being useful when dealing with related entities. With this goal in mind, I set to work.

Usage

Before implementing something like this, I like to start of by thinking about how the consumer code should look. So I start with how I want to use it. Allowing me to have a better idea of how to implement it. My initial thought was to have an abstract BlueprintFactory<T> class that would force the extending class to implement a abstract T blueprint(); method. In the case of a UserFactory class that might look like the following.

@Component
@AllArgsConstructor
public class UserFactory extends BlueprintFactory<AppUser> {
    private final Faker faker;
    private final PasswordEncoder passwordEncoder;

    protected AppUser blueprint() {
        var user = new AppUser();
        user.setEmail(faker.internet().emailAddress());
        user.setPassword(passwordEncoder.encode("password"));
        return user;
    }
}

The above is clean and clearly gives it's intent. It's also nice and concise as the parent class will implement the with and create methods. The blueprint method will be called each time an object is created. This means that each object will have it's data generated by faker.

I'm happy with this approach to creating the factories. So then I look at using the factories in a seeder class.

The seeder will be the class that stores the objects created via the factories in a database. So I write out how I want my UserSeeder to look. In my case the AppUser entity also has a one to one relationship with a UserProfile entity. So I'll need to create and store that along with the AppUser. It's a good idea to give each entity its own factory. So I create the following UserProfileFactory.

@Component
@AllArgsConstructor
public class UserProfileFactory extends BlueprintFactory<UserProfile> {
    private final Faker faker;

    @Override
    protected UserProfile blueprint() {
        UserProfile userProfile = new UserProfile();
        userProfile.setFirstName(faker.name().firstName());
        userProfile.setLastName(faker.name().lastName());
        return userProfile;
    }
}

It's also a good idea not to call one factory from inside another. You may be tempted to create the UserProfile inside the UserFactory blueprint. This is better handled inside the seeder, where the related entity can be passed during object creation via the with method.

With the UserFactory and UserProfileFactory set up. I can now go about writing the seeder. The UserSeeder will create the AppUser and UserProfile entities using the factories we created. It will also handle the relationship assignments. For example, we will want to set the AppUser that owns the UserProfile when it is created, using the with method. The with method will return a new instance of the factory, with the custom setter in place, to allow for composability. The UserSeeder should look as follows.

@Order(1)
@Component
@Profile("dev")
@RequiredArgsConstructor
public class UserSeeder implements CommandLineRunner {
    private final UserFactory userFactory;
    private final AppUserRepository appUserRepository;
    private final UserProfileFactory userProfileFactory;
    private final UserProfileRepository userProfileRepository;

    @Override
    @Transactional
    public void run(String... args) {
        if (appUserRepository.count() > 0) {
            return;
        }

        var savedUsers = appUserRepository.saveAll(userFactory.create(50));

        var userProfiles = new ArrayList<UserProfile>();
        for (var user : savedUsers) {
            userProfiles.add(userProfileFactory.with(() -> user, UserProfile::setUser).create());
        }

        userProfileRepository.saveAll(userProfiles);
    }
}

In this class we create 50 AppUser entities, by passing 50 to the create method. I then assign a UserProfile to each of those. All of which are persisted to the database.

An area of note is the following for loop.

for(var user : savedUsers){
    userProfiles.add(
            userProfileFactory.with(() ->user,UserProfile::setUser).create()
    );
}

Here we loop through the already saved users, creating a UserProfile for each one. The interesting part is how the user is passed to the user profile. The with method adds a custom setter. Meaning that UserProfile::setUser will be called, and the result of () -> user will be passed to it. Allowing that AppUser instance to be set on the newly created UserProfile.

Some other things to note here is that I add an @Order annotation to specify I want this seeder to run first. As well as the @Profile annotation to say I want it only to run in dev. I also firstly check if there are any users in the database before running the seeder. This is to ensure the database is only seeded when empty.

You may want to create a test user in your seeder. YOu can do this by passing a variant to the create method. This will overwrite the specified fields.

AppUser testUser = appUserRepository.save(userFactory.create(Map.of("email", "test@test.com")));

The above creates a test user with the email "test@test.com". The factory reads the keys of the map and overwrites the matching value on the blueprint.

Implementation

The implementation comes down to three main areas.

• BlueprintFactory<T>: the extensible base
• with: allowing composable factory instances
• create: construction of objects

And there is a lot to go through in each. So I will keep it brief.

BlueprintFactory<T>

This is an abstract class that forces the extender to implement a abstract T blueprint(); method. This method will get called each time an object is created. The result of which will then have any custom setters applied, before being passed to an object mapper which will apply any overwrites specified in the create method call.

So for clarity if a custom setter is added. It will be applied before the variant/overwrite is applied via the create method.

with

This method exists to handle the setting of related entities. As I stated earlier it's good practice to not create any related entities inside your factory. The setting of related entities should be handled solely by the with method.

Let's take the example of a User entity that can own many Post entities. In our seeder we may want to create the User entity first, then apply that User to a bunch of Post entities when they are created. The with method can specify the Post::setUser setter always set the supplied User like so:

var myUserPosts = postFactory.with(() -> myUser, Post::setUser).create(50);

The above will create 50 posts belonging to myUser. As the with method returns a new instance of the factory with the custom setter applied it can also be made composable like so:

var myUserFactory = postFactory.with(() -> myUser, Post::setUser);
var myUserPosts = myUserFactory.create(50);

This is achieved by an internal constructor, protected BlueprintFactory(List<Consumer<T>> customSetters), in which a copy of the factory's custom setters is passed to a new instance of said factory. That new instance is then returned. This allows for the construction of composable factories.

Inorder to facilitate applying a single entity and a list of entities method overloads are used, to match the type of the supplied argument.

• with(Supplier<R>, BiConsumer<T, R>): Injects a single related object
• with(Function<Integer, List<R>>, int, BiConsumer<T, List<R>>): Injects a list of related objects
• with(Function<V, R>, V, BiConsumer<T, R>): Injects a value based on a variant

I made a big effort here with these overloads to keep the public api as simple as possible but still allow for flexibility.

create

The create method is self-explanatory. It creates the new object based of the object returned via the blueprint method. It will call blueprint, then it will apply any custom setters to the return value of blueprint, before passing the modified object to an object mapper which will merge any overwrites that have been passed to the create method call.

Similar to the with method there are a number of overloads to allow for different usages of create.

• create(): Builds a single instance using the blueprint and custom setters
• create(Map<String, ?> variation): Applies field overrides using a map
• create(T variation): Merges fields from an existing instance
• create(int count): Batch creation of identical instances
• create(VariantList<T>): Batch creation using pre-defined entity variants
• create(VariantMapList): Batch creation using field maps (variant by map)

I was forced to create some custom types here to avoid ambiguity with the type checker. The was caused by allowing both a List<Map<String, ?>> and a List<T> to be passed to create to allow the creation of multiple variants. This is called a Sequence in the Laravel terminology. To get the type checker to allow this I had to create some wrapper classes, VariantMapList and VariantList<T> to distinguish between the types. This creates some overhead but until I can find a better solution. I will put up with it to keep the concise public api.

The module

BlueprintFactory has been uploaded to maven central. You can read the docs and learn how to use it in your own projects at BrianDouglasIE/BlueprintFactory.

Feel free to create a github issue with any suggested improvements.

Create objects from reusable blueprints with flexible overrides.

Overview

Blueprint Factory simplifies creating instances of your classes by providing a base template (the blueprint) and allowing you to customize each created object with variations or related objects. It's designed to be used along with Faker to easily generate seed data.

Features

• Define a reusable blueprint for your object.
• Override properties via instances or key-value maps.
• Create single or multiple instances at once.
• Easily set related entities with custom setters.
• Clean, type-safe API with just two public methods: with and create.

Installation

Maven

<dependency>
    <groupId>ie.briandouglas</groupId>
    <artifactId>BlueprintFactory</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation group: 'ie.briandouglas', name: 'BlueprintFactory', version: '1.0.0'

Usage

Define your Factory

Extend the abstract BlueprintFactory<T> and implement the blueprint() method to provide a default instance:

public class UserFactory extends BlueprintFactory<User> {
    private final Faker faker = new Faker();

    @Override
    protected User blueprint () {
        return new User(faker.name().firstName(), faker.internet().emailAddress());
    }
}

When an object is created by a BlueprintFactory the blueprint method will be called. Once created the object returned from the blueprint method will have any overrides applied. Because blueprint is called for each create, it is a good idea to use a library like Faker to generate your blueprint's data.

Creating Instances

Basic instance:

User user = userFactory.create();

Override fields with an instance:

User override = new User("alice", "alice@example.com");
User user = userFactory.create(override);

Override fields with a map:

User user = userFactory.create(Map.of("name", "bob", "email", "bob@example.com"));

Create multiple instances:

List<User> users = userFactory.create(5);

Create from a list of variants:

List<User> variants = List.of(
    new User("charlie", "charlie@example.com"),
    new User("dave", "dave@example.com")
);
List<User> users = userFactory.create(new VariantList<>(variants));

Create from a list of map variants:

List<VariantMap> variantMaps = List.of(
    new VariantMap(Map.of("name", "eve")),
    new VariantMap(Map.of("name", "frank"))
);
List<User> users = userFactory.create(new VariantMapList(variantMaps));

Setting Related Entities

With a single related object:

User user = userFactory
    .with(roleFactory::create, User::setRole)
    .create();

With multiple related objects:

User user = userFactory
    .with(roleFactory::create, 3, User::setRoles)
    .create();

With a variant passed to related factory:

Role adminRole = new Role("admin");
User user = userFactory
    .with(roleFactory::create, adminRole, User::setRole)
    .create();

With a list of variants:

List<Role> roles = List.of(new Role("editor"), new Role("viewer"));
User user = userFactory
    .with(roleFactory::create, new VariantList<>(roles), User::setRoles)
    .create();

With a list of map variants:

List<Map<String, ?>> maps = List.of(
        Map.of("name", "contributor"),
        Map.of("name", "maintainer")
);
User user = userFactory
        .with(roleFactory::create, new VariantMapList<>(maps), User::setRoles)
        .create();

LICENSE

Copyright (c) 2025 Brian Douglas.
See the LICENSE file for license rights and limitations.

This simple utility generates customizable placeholder images in Java using AWT. It is useful for creating mock user avatars, image placeholders in UI development, or dynamically generated image content.

View the source code on github at BrianDouglasIE/PlaceholderImageGenerator

Features

• Set image dimensions and text
• Choose custom font and font size
• Configure text and background colors
• Enable or disable anti-aliasing for smoother text rendering

Installation

Add the following dependency to your Maven pom.xml:

<dependency>
    <groupId>ie.briandouglas</groupId>
    <artifactId>PlaceholderImageGenerator</artifactId>
    <version>1.0.1</version>
</dependency>

Or if you're using Gradle:

dependencies {
    implementation("ie.briandouglas:PlaceholderImageGenerator:1.0.1")
}

Example usage:

public class Main {
    public static void main(String[] args) throws IOException {
        var placeholderImage = new PlaceholderImage();

        var options = PlaceholderImageOptions.builder()
                .text("BD")
                .width(400)
                .height(400)
                .backgroundColor(Color.decode("#DCDCDC"))
                .font(new Font("Arial", Font.BOLD, 200))
                .build();

        var image = placeholderImage.generate(options);
        ImageIO.write(image, "png", new File("placeholder.png"));
        System.out.println("Generated placeholder.png");
    }
}

This example will generate a centered "BD" in bold Arial on a 400x400 image with a light gray background, saved as placeholder.png.

Documentation

See javadoc.io

PlaceholderImageOptions

Encapsulates configuration options for generating a placeholder image.

PlaceholderImageOptions.builder()
    .text("AB")                                // Text to display
    .width(300)                                // Width in pixels
    .height(300)                               // Height in pixels
    .textColor(Color.DARK_GRAY)                // Color of the text (optional, default: DARK_GRAY)
    .backgroundColor(Color.GRAY)               // Background color (optional, default: GRAY)
    .font(new Font("Arial", Font.PLAIN, 16))   // Font used for rendering (optional)
    .antiAliasOn(true)                         // Enable anti-aliasing (optional, default: true)
    .build();

PlaceholderImage

Generates a BufferedImage using the provided PlaceholderImageOptions.

BufferedImage image = new PlaceholderImage().generate(options);

Dependencies

• Java 8+
• No external libraries required; uses java.awt and javax.imageio

License

Apache 2.0

@Component
@AllArgsConstructor
public class PostSecurity {
    private final PostRepository postRepository;

    public boolean isOwner(Long id, String userEmail) {
        return postRepository.findById(id) // first fetch
                .map(Post::getUser)
                .map(AppUser::getEmail)
                .map(it -> it.equals(userEmail))
                .orElse(false);
    }
}

@PreAuthorize("@postSecurity.isOwner(#postId, authentication.name)")
public Post getOwnedPost(Long postId) {
    return postRepository.findById(postId) // second fetch
            .orElseThrow(() -> new EntityNotFoundException("Post not found"));
}

One simple way to avoid this would be to do the ownership check inside the getOwnedPost method. This may seem straightforward, but it would lead to code that is harder to maintain. For example the authenticated UserDetails would need to be passed around, and a checked exceptions would need added to each caller... yuck.

A nice solution would be to cache the owned post instance for the lifecycle of the request. This would mean that the isOwner method would cache the post on look up. The post could then be retrieved from the cache inside the getOwnedPost method. Meaning that there is only one post look up. We would then add a request filter to clear the cache after each request.

Using a request based cache

Each Spring request uses it's own thread. This means that we can cache values for the current request's thread, without affecting any other request. To do this we'll use a plain old java object to model our RequestCache. I want to use this solution for different entity types, so I'll make it generic by making it a generic class, so it can hold any type of entity.

public class RequestCache<T> {
    private final ThreadLocal<Optional<T>> holder = new ThreadLocal<>();

    public void set(T value) {
        holder.set(Optional.ofNullable(value));
    }

    public Optional<T> get() {
        return holder.get();
    }

    public void clear() {
        holder.remove();
    }
}

In some contexts like asynchronous processing, you may need InheritableThreadLocal or a more advanced request-scoped solution like Spring’s @RequestScope. But for typical synchronous requests, ThreadLocal works well.

Now let's create a RequestCacheRegistry. This will be a @Component to allow it to be injected into the various services that will use it. You will be able to see at this stage how this approach can be extended to work with various entities, by adding a unique RequestCache property for each cached item.

@Getter
@Component
public class RequestCacheRegistry {
    public final RequestCache<Post> ownedPost = new RequestCache<>();

    public void clearAll() {
        ownedPost.clear();
    }
}

Now that our RequestCacheRegistry has been set up, we can use it within our PostService. First we'll need to modify the PostSecurity component to cache the post that is returned from the PostRepository. As the PostRepository returns an Optional<Post> the cache can be updated in a chained map call.

@Component
@AllArgsConstructor
public class PostSecurity {
    private final PostRepository postRepository;
    private final RequestCacheRegistry requestCacheRegistry;

    public boolean isOwner(Long id, String userEmail) {
        return postRepository.findById(id)
                .filter(it -> it.getUser().getEmail().equals(userEmail))
                .map(it -> {
                    requestCacheRegistry.getOwnedPost().set(it); // cache post
                    return true;
                })
                .orElse(false);
    }
}

Now that the requestCacheRegisty.ownedPost is set. It can be access inside the getOwnedPost method that has the PreAuthorize annotation.

@PreAuthorize("@postSecurity.isOwner(#postId, authentication.name)")
public Post getOwnedPost(Long postId) {
    return requestCacheRegistry.getOwnedPost().get().orElseGet(() -> findById(postId));
}

With all this in place there is now only one database call to fetch the required post. We have also implemented a pattern that will allow for other entities to be cached in the same way, using the RequestCacheRegistry.

Clearing the cache

It is important that we clear the request cache after each request completes. This will help prevent any thread leaks from occurring. A clean way of doing this is to implement a request filter. The following request filter will be called automatically on each request. Once the filter chain completes, this custom filter will call the cacheRegistry.clearAll method. Ensuring the cache registry is safely cleared after each request.

@Component
@RequiredArgsConstructor
public class RequestCacheCleanUpFilter extends OncePerRequestFilter {

    private final RequestCacheRegistry cacheRegistry;

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
            throws ServletException, IOException {
        try {
            filterChain.doFilter(request, response);
        } finally {
            cacheRegistry.clearAll();
        }
    }

}

@Component
@AllArgsConstructor
public class PostSecurity {
    private final PostRepository postRepository;

    public boolean isOwner(Long id, String userEmail) {
        return postRepository.findById(id)
                .map(Post::getUser)
                .map(AppUser::getEmail)
                .map(it -> it.equals(userEmail))
                .orElse(false);
    }
}

This method finds the post with an id matching postId, gets the user attached to that post, then asserts whether the post's user's email matches the currently authenticated user. If the Optional<Post> from findById is empty, then false is returned.

But now the question is, where should this method be called? Certainly it's not the PostController and calling it inside other PostService methods will lead to repetition and the passing around of arguments unnecessarily.

Luckily the team at Spring Security have thought about writing clean code and have provided the PreAuthorize annotation for such scenarios. This annotation is used to restrict access to methods before they are invoked. This means that we can create the below PostService method to check auth when accessing a Post.

Remember to add the @EnableMethodSecurity(prePostEnabled = true) annotation to your SecurityConfig class. This is a requirement for the @PreAuthorize annotation to work.

@PreAuthorize("@postSecurity.isOwner(#postId, authentication.name)")
public Post getOwnedPost(Long postId) {
    return postRepository.findById(postId)
            .orElseThrow(() -> new EntityNotFoundException("Post not found"));
}

This can then be called in the PostController.

@GetMapping("/edit/{id}")
public String editPost(@PathVariable Long postId, Model model) {
    var post = postService.getOwnedPost(postId); // will throw when user is not the post's owner
    model.addAttribute("post", post);
    return "post/edit";
}

That is all well and good, but won't this require two calls to fetch the same post? Wow, you aren't so slow after all. Yes, it would. He provides a solution here, spring-request-cache

By keeping the ownership logic in the PostService it can be reused in other controllers and methods. It also ensures that accessing a Post is done in a consistent and safe manner. The handling of the ownership check has been delegated to the PostSecurity component which allows for a separation of concerns.

You can view the Slurp javadocs at ie.briandouglas/slurp/

Usage

Create a SlurpTask

SlurpTasks are Java records. They have a name and a runnable property. Neither the name nor runnable property may be null. You can create a SlurpTask like so.

SlurpTask printHelloWorld = new SlurpTask("HelloWorld", () -> System.out.println("Hello World!"));

Register and Execute a SlurpTask

Inorder to register a SlurpTask for excution a Slurp instance is needed. The Slurp instance allows for tasks to be registered and executed.

Slurp slurp = new Slurp();
SlurpTask printHelloWorld = new SlurpTask("HelloWorld", () -> System.out.println("Hello World!"));

slurp.registerTask(printHelloWorld);
slurp.executeTask(printHelloWorld);

Task names must be unique, if a duplicate task name is registered a DuplicateTaskException will be thrown. If an attempt is made to execute an unknown task a TaskNotFoundException will be thrown.

Executing a sequence of tasks

Slurp can be used to execute a sequence of tasks. Internally it uses a single threaded executor, and waits for each task to finish before executing the next.

String[] sendMarketingEmail = new String[] {
  "prepareClientList",
  "generateEmailHTML",
  "sendSpamMarketingEmail"
};

slurp.executeTaskSequence(sendMarketingEmail); // may also take a SlurpTask[]

Source code

The source code for the Slurp task runner is available on github at BrianDouglasIE/slurp.

So how do you make loop conditionals predictable? Well we could sort the array before processing it

Sorting the values of an array before processing it will help with CPU branch prediction. It may also help with cpu cache optimisation. CPU cache optimisation being the accessing of data that from the CPU cache. This is memory located close to the CPU cores, data accessed from here is often processed much quicker than from the main memory. This can be done in Java by accessing data from a sorted array. The idea being that sorted data may be held closer together in memory, and therefore can be accessed more quickly, providing a performance benefit.

Example Usage

Let's see this in action with some example code. Given the following program, the sorted array will be processed roughly 4 times faster than the unsorted array.

import java.util.Random;

public class Main {

    public static void main(String[] args) {
        int arraySize = 10_000_000;

        int[] sortedArray = new int[arraySize];
        for (int i = 0; i < arraySize; i++) {
            sortedArray[i] = i;
        }

        long startTime = System.nanoTime();
        long sortedSum = evenNumberSum(sortedArray);
        long sortedTime = System.nanoTime() - startTime;

        int[] shuffledArray = shuffle(sortedArray);
        startTime = System.nanoTime();
        long unsortedSum = evenNumberSum(shuffledArray);
        long unsortedTime = System.nanoTime() - startTime;

        if (unsortedSum != sortedSum) {
            throw new Error("sortedSum and unsortedSum should match");
        }

        System.out.println("Sorted array processing time:   " + sortedTime + " ns");
        System.out.println("Unsorted array processing time: " + unsortedTime + " ns");
        System.out.println("Times faster: " + Math.floorDiv(unsortedTime, sortedTime));
    }

    /**
     * Returns a clone of the array with it's values shuffled.
     *
     * @param srcArray
     * @return
     */
    private static int[] shuffle(int[] srcArray) {
        Random rand = new Random();
        int[] array = srcArray.clone();

        for (int i = array.length - 1; i > 0; i--) {
            int randIndex = rand.nextInt(i + 1);
            int randIndexValue = array[randIndex];
            array[randIndex] = array[i];
            array[i] = randIndexValue;
        }

        return array;
    }

    /**
     * Returns the sum of all the even numbers in the array.
     *
     * @param array
     * @return
     */
    private static long evenNumberSum(int[] array) {
        long sum = 0;
        for (int value : array) {
            if (isEven(value)) {
                sum += value;
            }
        }
        return sum;
    }

    /**
     * Returns true if n is even and false if not.
     *
     * @param n
     * @return
     */
    private static boolean isEven(int n) {
        return n % 2 == 0;
    }
}

The above program creates an array of 10 million ints, sorted. It then iterates through that array to get the sum of all the even ints, measuring the execution time. It then does the same thing with a shuffled version of the initial sorted array. Running the program you should see that the sorted array is processed much quicker than the unsorted array. Demonstrating the advantage of CPU branch prediction and cache optimisation. Below is the result I get when running it locally.

Sorted array processing time:   8745547 ns
Unsorted array processing time: 37145149 ns
Times faster: 4

Drawbacks

While I can't think of a drawback, other than the time spent sorting the array before processing it. There is a caveat. It may not always give a benefit.

For example, if when processing the array, you ran something that wasn't easily predictable, eg: testing if a number is a prime, you may not see much difference. While the sorted array would still be more predictable, in practice the benefit of the prediction would be less significant as the majority of the numbers are likely non prime and the check would fail early. So there will likely be use cases where you see a great benefit from processing a sorted array, and some cases there you don't really see any benefit.

Summary

Sorted arrays in Java benefit from CPU branch prediction and cache optimisation due to predictable patterns and memory location.

In contrast, unsorted arrays suffer from the lack of predictability and random memory access patterns.

The "Official" install command (02/04/2025)

Here is the official install command from the Ubuntu docker guide (install/ubuntu).

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

When you run this it will complain. You will see the following error.

E: The repository 'https://download.docker.com/linux/ubuntu vera Release' does not have a Release file.

Notice the "vera" release. Ubuntu has no release named vera. That is the Linux Mint release version. This is the crux of the issue.

The install command you are looking for

The fix here is to use the Debian download passing in the latest Debian release name. This is currently "bookworm".

The updated command is below. I have hard coded the release name as bookworm and updated the download url to use debian instead of ubuntu.

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  bookworm stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

I hope this solves your issue, and that docker is now running on your lovely Linux Mint instance.

sudo apt install openjdk-21-jdk

Using the correct Java version

It's likely that if you are a Java Developer that you will have multiple versions of Java installed. To specify the default version of java to use we will run the update-alternatives command.

sudo update-alternatives --config java

This will list the available Java installs and request you to choose which one you want to use as the default. You should see output similar to what is below. In this instance I choose 2. As I want to default to OpenJDK 21.

There are 2 choices for the alternative java (providing /usr/bin/java).

  Selection    Path                                         Priority   Status
------------------------------------------------------------
* 0            /usr/lib/jvm/java-21-openjdk-amd64/bin/java   2111      auto mode
  1            /usr/lib/jvm/java-11-openjdk-amd64/bin/java   1111      manual mode
  2            /usr/lib/jvm/java-21-openjdk-amd64/bin/java   2111      manual mode

Press <enter> to keep the current choice[*], or type selection number:

You can follow the same process to set the default javac command also.

Setting the JAVA_HOME variable

In order to set up the JAVA_HOME variable we can use update-alternatives again. Running sudo update-alternatives --config java will show the select Java path. We can take this and append it to our shell's path by adding the following to our .bashrc file.

export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64/
export PATH=$PATH:$JAVA_HOME/bin

To confirm this has worked reload your shell with source ~/.bashrc and run echo $JAVA_HOME. You should see output similar to:

/usr/lib/jvm/java-21-openjdk-amd64/

Now you can enjoy writing your enterprise Java code on Ubuntu. I know I do.

wiki/Yoda_conditions does a better job of explaining this than him.

Here is a quick example of how Yoda condtions work. Given the following statement:

if(age < 18) { /* you can't drink here */ }

The Yoda condition equivalent would be:

if(18 > age) { /* you can't drink here */ }

That looks odd to me, what is the advantage? Mostly it will catch an unwanted assignment.

Why bother?

Well look at this code:

if(animal = "dog") { /* wag tail */ }

This checks if the animal is a dog, and then does something.

Oh actually, no it doesn't. It assigns the value of animal to be "dog". Which is not what I wanted. But it's a mistake that wouldn't be imediately obvious to me either.

It's this sort of thing that Yoda conditions prevent. If I was to make that mistake using Yoda conditons. Then the following code would throw an error.

if("dog" = animal) { /* wag tail */ }

The error:

.\animal.c:12:10: error: assignment to expression with array type
   12 | if("dog" = animal) {
      |          ^

Now I don't have to debug my code and pull my hair out. The issue is clear, thanks Yoda.

Whilst it's not that complex, it can be a tricky one to get your head around if you haven't seen it before, or are not familiar with recusive method calls. At an interview recently I was asked to write an implementation of it using Java. Well I could use any language, but I chose to use Java as the role was for a fullstack Spring dev.

I was able to implement it successfully after struggling with parameter order for a couple of minutes. I had the advantage of solving this problem before, thank you exercism.io. So I had an idea of what needed to be done.

Test Suite

Before I show you the implementation. I asked ChatGPT to generate a test suite using JUnit. This is one of the great use cases for AI, they can write the boring code. I had to tune the tests slightly to give the expected output. For example in my implementation I am writing out the moves as Strings. Which was the interview requirement.

package ie.briandouglas.tower_of_hanoi;

import static org.junit.jupiter.api.Assertions.*;
import org.junit.jupiter.api.Test;
import java.util.List;

class TowerOfHanoiTest {

    @Test
    void testOneDisk() {
        TowerOfHanoi hanoi = new TowerOfHanoi();
        List<String> moves = hanoi.solve(1, 'A', 'C', 'B');
        assertEquals(1, moves.size());
        assertEquals("Move disk 1 from A to C", moves.get(0));
    }

    @Test
    void testTwoDisks() {
        TowerOfHanoi hanoi = new TowerOfHanoi();
        List<String> moves = hanoi.solve(2, 'A', 'C', 'B');
        assertEquals(3, moves.size());
        assertEquals("Move disk 1 from A to B", moves.get(0));
        assertEquals("Move disk 2 from A to C", moves.get(1));
        assertEquals("Move disk 1 from B to C", moves.get(2));
    }

    @Test
    void testThreeDisks() {
        TowerOfHanoi hanoi = new TowerOfHanoi();
        List<String> moves = hanoi.solve(3, 'A', 'C', 'B');
        assertEquals(7, moves.size());
        assertEquals("Move disk 1 from A to C", moves.get(0));
        assertEquals("Move disk 2 from A to B", moves.get(1));
        assertEquals("Move disk 1 from C to B", moves.get(2));
        assertEquals("Move disk 3 from A to C", moves.get(3));
        assertEquals("Move disk 1 from B to A", moves.get(4));
        assertEquals("Move disk 2 from B to C", moves.get(5));
        assertEquals("Move disk 1 from A to C", moves.get(6));
    }

    @Test
    void testZeroDisks() {
        TowerOfHanoi hanoi = new TowerOfHanoi();
        List<String> moves = hanoi.solve(0, 'A', 'C', 'B');
        assertTrue(moves.isEmpty());
    }

    @Test
    void testFiveDisks() {
        TowerOfHanoi hanoi = new TowerOfHanoi();
        List<String> moves = hanoi.solve(5, 'A', 'C', 'B');
        assertEquals(31, moves.size());
    }
}

Implementation

The implementation here is pretty much the implementation you will see everywhere else. The solve method recursively calls itself with n - 1, moving the nth largest disk, from, to to. Then from unused to to. In this example from is the origin peg, to is the target, and unused is the peg that is not involved.

I extracted the constructMoveString for readability, and created a method overload so that solve could be called without instantiating an ArrayList.

package ie.briandouglas.tower_of_hanoi;

import java.util.ArrayList;
import java.util.List;

public class TowerOfHanoi {

	public List<String> solve(int n, char from, char to, char unused, List<String> moves) {
		if (n > 0) {
			solve(n - 1, from, unused, to, moves);
			moves.add(constructMoveString(n, from, to));
			solve(n - 1, unused, to, from, moves);
		}
		return moves;
	}

	public List<String> solve(int n, char from, char to, char unused) {
		return solve(n, from, to, unused, new ArrayList<>());
	}

	private String constructMoveString(int disk, char from, char to) {
		return new StringBuilder().append("Move disk ").append(disk).append(" from ").append(from).append(" to ")
				.append(to).toString();
	}

}

It integrates with Selenium WebDriver to automate web accessibility testing, providing detailed reports on accessibility violations, passes, and other relevant results. The resulting axe-core report is converted into Java classes so that it can be used within a Java project and allows for type hinting.

Quick synopsis of the package.

Features

• Runs accessibility tests on specified URLs.
• Uses Selenium WebDriver for browser automation.
• Configurable via AxeSpec and AxeRunOptions.
• Parses and categorizes accessibility test results.
• Supports axe-core rule customization.
• Supports axe-core localization.

Prerequisites

• Java (JDK 8 or higher)
• Selenium WebDriver

Installation

To use AxeRunner, include the following dependencies in your project:

Maven

<dependencies>
    <dependency>
        <groupId>org.seleniumhq.selenium</groupId>
        <artifactId>selenium-java</artifactId>
        <version>4.x.x</version>
    </dependency>
    <dependency>
        <groupId>ie.briandouglas</groupId>
        <artifactId>axe_runner</artifactId>
        <version>0.0.1</version>
    </dependency>
</dependencies>

Usage

Creating an Instance

WebDriver driver = new ChromeDriver(); // or any other WebDriver instance
AxeRunner axeRunner = new AxeRunner(driver);

Running Accessibility Tests

String url = "https://example.com";
AxeResults results = axeRunner.getAxeResults(url);

Running with Custom Configurations

AxeSpec spec = new AxeSpec(); // Define accessibility testing specifications
AxeRunOptions options = new AxeRunOptions(); // Define run options
AxeResults results = axeRunner.getAxeResults(url, spec, options);

Accessing Results

System.out.println("Violations: " + results.violations.size());
System.out.println("Passes: " + results.passes.size());

Error Handling

• If axe-core.min.js fails to load, an exception is thrown.
• If Selenium fails to navigate to the page, the WebDriver is closed.
• JSON processing errors during configuration are logged.

License

This project is licensed under the Apache License, Version 2.0.

Contributing

• Fork the repository.
• Create a feature branch.
• Submit a pull request.

Luckily there is a website called European Alternatives that provides a list of EU based alternatives to popular non EU software. You should check it out and discover some hidden gems. Right now I am using the Vivaldi web browser along with Startpage a Dutch search engine. They are excellent alternatives to the tech giant offerings.

By using this alternative software, you support the creation of jobs, encourage competition, and end your reliance on evil monopolies.

Make the switch today, use a European Alternative.

Implementation

First off I like to define some constants.

#define V_SCREEN_WIDTH 256
#define V_SCREEN_HEIGHT 256
#define V_SCALE 2
#define SCREEN_WIDTH  V_SCREEN_WIDTH * V_SCALE
#define SCREEN_HEIGHT V_SCREEN_HEIGHT * V_SCALE

In the above code the prefix V_ refers to virtual. So I am setting my virtual screen size to 256x256 pixels and applying the V_SCALE to get the actual window size. In this instance 256 x 2 = 512.

When opening a window with raylib I will pass in the SCREEEN_WIDTH and SCREEN_HEIGHT constants to the InitWindow method like so.

InitWindow(SCREEN_WIDTH, SCREEN_HEIGHT, "Game Title");

This will open a correctly sized game window. I now want to create a RenderTexture2D. This is what the game will be drawn on. It will then itself be scaled and drawn onto the actual game window.

To create the RenderTexture2D I use the following code.

const RenderTexture2D renderTexture = LoadRenderTexture(V_SCREEN_WIDTH, V_SCREEN_HEIGHT);
const Rectangle renderTextureSrc = (Rectangle){ 0.0f, 0.0f, V_SCREEN_WIDTH, -V_SCREEN_HEIGHT };
const Rectangle renderTextureDest = (Rectangle){ 0.0f, 0.0f, SCREEN_WIDTH, SCREEN_HEIGHT };
const Vector2 renderTextureOrig = {0};

// remember to unload the texture when finished using it
UnloadRenderTexture(renderTexture);

The render texture can then be drawn on to by creating a new texture mode.

BeginTextureMode(renderTexture);
    ClearBackground(BG_COLOR);
    DrawTextureRec(spritesheet, playerFrame, playerPos, WHITE);
EndTextureMode();

After this code is run the RenderTexture2D's texture is then drawn on to the main draw context at the correct scale.

BeginDrawing();
    ClearBackground(BG_COLOR);
    DrawTexturePro(renderTexture.texture, renderTextureSrc, renderTextureDest, renderTextureOrig, 0, WHITE);
EndDrawing();

This results in the small 16x16 pixel art being drawn at the correct scale, without loss of fidelity.

A quick look at the docs and I see predefined format styles. I really like the allman style. Broken braces are the thinking man's braces. So now I format my C source code with this neat command:

astyle --style=allman --recursive src/*.c

Everything looks nice and tidy. Still no need for a complicated IDE.

Exporting data

sqlite3 database.db .dump > database_dump_$(date +%Y%m%d_%H%M%S).sql

The above command dumps the database to a new .sql file that is timestamped. I like to use the following timestamp format YYYYMMDD_HHMMSS.

Importing data

An exported sql file can then be imported into a sqlite database like so.

sqlite3 database.db < database_dump_20250216_100802.sql

It does this by setting the following PRAGMA options on your sqlite database.

 ┌───────────────────────────┬─────────────┬───────────┐
 │ Setting                   │ Value       │ Via       │
 ├───────────────────────────┼─────────────┼───────────┤
 │ PRAGMA auto_vacuum        │ incremental │ Migration │
 │ PRAGMA journal_mode       │ WAL         │ Migration │
 │ PRAGMA page_size          │ 32768       │ Migration │
 │ PRAGMA busy_timeout       │ 5000        │ Runtime   │
 │ PRAGMA cache_size         │ -20000      │ Runtime   │
 │ PRAGMA foreign_keys       │ ON          │ Runtime   │
 │ PRAGMA incremental_vacuum │ (enabled)   │ Runtime   │
 │ PRAGMA mmap_size          │ 2147483648  │ Runtime   │
 │ PRAGMA temp_store         │ MEMORY      │ Runtime   │
 │ PRAGMA synchronous        │ NORMAL      │ Runtime   │
 └───────────────────────────┴─────────────┴───────────┘

Brian wrote a post detailing some of these PRAGMAs. He called it "Sensible SQLite defaults", it's his most popular post to date.

Usage

Nuno always makes things easy. You can install and integrate the package with these three commands.

composer require nunomaduro/laravel-optimize-database

php artisan db:optimize

php artisan migrate

After that you SQLite db is ready to use.

Backing up

Backing up an SQLite database is as simple as copying the file. On a linux box you do this with the cp command.

cp database.db backup_database_$(date +%Y%m%d_%H%M%S).db

The above command copies the database to a new file that is timestamped. I like to use the following timestamp format YYYYMMDD_HHMMSS.

Restoring from a back up

To restore an sqlite database from a back up. We just need to copy the copy to the original location.

Copy the copy? He has a way with words.

This is basically the reverse of the backup command.

cp backup_database_20250116_091422.db database.db

This replaces the current database with the backup, maintaining the backup for future use.

I chose snake as I have written this type of game previously in JS and Python. So I didn't really have to figure much out. Just get down to writing some C. I haev included the full source code in this article. One nice feature that I added was smooth transitions between cells. I did this by growing and shortening the head and tail respectively, based on an animation timer. This makes for a nice animation and makes it look like the snake is moving smoothly, rather than jumping a cell at a time. The implementation can be seen in the SnakeDrawHead and SnakeDrawTail methods. Apart from this it's a regular old snake clone.

Thoughts

I really enjoyed coding this, it's the first time I have felt productive in C. I am starting to grasp arrays and pointers. I may even be beginning to think in a C manner. I kept everything in one file for convenience. This helped me think more about what the code did, and less about where the code lived.

Anyway, take a look at the source code below. I'll get back to the main "SlimeJump" game in the next post.

Source code is also available at BrianDouglasIE/snake-c-raylib

#include "raylib.h"
#include "math.h"
#include <stdlib.h>
#include <stdio.h>
#include <time.h>

float percentOf(float percent, float number)
{
    return (percent / number) * 100.0f;
}

float asPercentOf(float number, float percent)
{
    return (percent / 100.0f) * number;
}

int randomInt(int min, int max)
{
    return (rand() % max) + min;
}

enum Direction {
    UP, DOWN, LEFT, RIGHT
};

struct Snake {
    int x;
    int y;
    float speed;
    float moveTimer;
    enum Direction direction;
    enum Direction nextDirection;
};

struct Snake SnakeCreate(int x, int y)
{
    return (struct Snake) {
        .x = x,
        .y = y,
        .speed = 0.2f,
        .moveTimer = 0,
        .direction = RIGHT,
        .nextDirection = RIGHT,
    };
}

void SnakeMoveInCurrentDirection(struct Snake *s)
{
    switch(s->direction)
    {
        case UP:
            s->y -= 1;
            break;
        case DOWN:
            s->y += 1;
            break;
        case LEFT:
            s->x -= 1;
            break;
        case RIGHT:
            s->x += 1;
            break;
        default:
            break;
    }
}

void SnakeScreenWrap(struct Snake *s, int colCount, int rowCount)
{
    if(s->x < 0) {
        s->x = colCount - 1;
        s->direction = LEFT;
    }
    if(s->x > colCount - 1) {
        s->x = 0;
        s->direction = RIGHT;
    }
    if(s->y < 0) {
        s->y = rowCount - 1;
        s->direction = UP;
    }
    if(s->y > rowCount - 1) {
        s->y = 0;
        s->direction = DOWN;
    }
}

void SnakeUpdate(struct Snake *s, float dt, struct Snake *target)
{
    s->moveTimer += dt;
    if(s->moveTimer >= s->speed) {
        s->moveTimer -= s->speed;

        if(target == NULL) {
            if(s->direction != s->nextDirection)
            {
                s->direction = s->nextDirection;
            }

            SnakeMoveInCurrentDirection(s);
        } else {
            s->x = target->x;
            s->y = target->y;
            s->direction = target->direction;
        }
    }
}

void SnakeSetDirection(struct Snake *s, int dirX, int dirY)
{
    if(dirX && dirY) return;
    if(!dirX && !dirY) return;
    if(dirY && (s->direction == UP || s->direction == DOWN)) return;
    if(dirX && (s->direction == LEFT || s->direction == RIGHT)) return;

    if(dirX == -1) {
        s->nextDirection = LEFT;
    }
    if(dirX == 1) {
        s->nextDirection = RIGHT;
    }
    if(dirY == -1) {
        s->nextDirection = UP;
    }
    if(dirY == 1) {
        s->nextDirection = DOWN;
    }
}

void SnakeDrawHead(struct Snake *s, int cellSize, Color color)
{
    int w, h;
    float growthPercent = percentOf(s->moveTimer, s->speed);

    switch(s->direction)
    {
        case UP:
            h = floor(asPercentOf(cellSize, growthPercent));
            DrawRectangle(s->x * cellSize, (s->y * cellSize) + (cellSize - h), cellSize, h, color);
            break;
        case DOWN:
            h = floor(asPercentOf(cellSize, growthPercent));
            DrawRectangle(s->x * cellSize, s->y * cellSize, cellSize, h, color);
            break;
        case RIGHT:
            w = floor(asPercentOf(cellSize, growthPercent));
            DrawRectangle(s->x * cellSize, s->y * cellSize, w, cellSize, color);
            break;
        case LEFT:
            w = floor(asPercentOf(cellSize, growthPercent));
            DrawRectangle((s->x * cellSize) + (cellSize - w), s->y * cellSize, w, cellSize, color);
            break;
        default:
            break;
    }
}

void SnakeDrawTail(struct Snake *s, int cellSize, Color color)
{
    int w, h;
    float growthPercent = percentOf(s->moveTimer, s->speed);

    switch(s->direction)
    {
        case UP:
            h = floor(asPercentOf(cellSize, growthPercent));
            DrawRectangle(s->x * cellSize, s->y * cellSize, cellSize, cellSize - h, color);
            break;
        case DOWN:
            h = floor(asPercentOf(cellSize, growthPercent));
            DrawRectangle(s->x * cellSize, s->y * cellSize + h, cellSize, cellSize - h, color);
            break;
        case RIGHT:
            w = floor(asPercentOf(cellSize, growthPercent));
            DrawRectangle(s->x * cellSize + w, s->y * cellSize, cellSize - w, cellSize, color);
            break;
        case LEFT:
            w = floor(asPercentOf(cellSize, growthPercent));
            DrawRectangle(s->x * cellSize, s->y * cellSize, cellSize - w, cellSize, color);
            break;
        default:
            break;
    }
}

void SnakeDraw(struct Snake *s, int cellSize, Color color)
{
    DrawRectangle(s->x * cellSize, s->y * cellSize, cellSize, cellSize, color);
}

struct Apple {
	int x;
	int y;
	int active;
	float lifeSpan;
	float lifeTimer;
};

struct Apple AppleCreate()
{
	return (struct Apple) {
		.x = 0,
		.y = 0,
		.active = 0,
		.lifeSpan = 0.0f,
		.lifeTimer = 0.0f,
	};
}

void AppleUpdate(struct Apple *a, float dt)
{
	if(!a->active) return;

	a->lifeTimer += dt;
	if(a->lifeTimer > a->lifeSpan)
	{
		a->lifeTimer -= a->lifeSpan;
		a->active = 0;
	}
}

void AppleActivateAt(struct Apple *a, int x, int y)
{
	a->x = x;
	a->y = y;
	a->active = 1;
	a->lifeTimer = 0;
	a->lifeSpan = 5.0f;
}

void AppleDraw(struct Apple *a, int cellSize, Color color)
{
	if(!a->active) return;
    DrawRectangle(a->x * cellSize, a->y * cellSize, cellSize, cellSize, color);
}

int collidesWithSnake(struct Snake s[], int snakeLength, int x, int y)
{
	for(int i = 0; i < snakeLength; i++)
	{
		if(s[i].x == x && s[i].y == y) return 1;
	}

	return 0;
}

Vector2 getRandomCellCoords(int colCount, int rowCount)
{
	int x = randomInt(0, colCount);
	int y = randomInt(0, rowCount);
	return (Vector2) { x, y };
}

int main(void)
{
    srand((unsigned)time(NULL));

    const int screenSize = 600;
    const int screenWidth = screenSize;
    const int screenHeight = screenSize;

    InitWindow(screenWidth, screenHeight, "snake");
    SetTargetFPS(60);

    const int gridSize = 20;
    const int cellSize = floor(screenSize / gridSize);
    const int colCount = floor(screenWidth / cellSize);
    const int rowCount = floor(screenHeight / cellSize);
	
	int gameInProgress = 1;

    int snakeLength = 4;
    int snakeMaxLength = colCount * rowCount;
    struct Snake snake[snakeMaxLength];
    for(int i = 0; i < snakeLength; i++)
    {
        snake[i] = SnakeCreate(floor(colCount / 2) - i, floor(rowCount / 2));
    }

	struct Apple apple = AppleCreate();

	float appleSpawnInterval = 8.0f;
	float appleSpawnTimer = 0.0f;

    while(!WindowShouldClose())
    {
        // update
		if(gameInProgress) {
			int up, down, left, right, dirX, dirY;

			float dt = GetFrameTime();

			up = IsKeyDown(KEY_UP) ? -1 : 0;
			down = IsKeyDown(KEY_DOWN) ? 1 : 0;
			left = IsKeyDown(KEY_LEFT) ? -1 : 0;
			right = IsKeyDown(KEY_RIGHT) ? 1 : 0;

			dirY = up + down;
			dirX = left + right;

			for(int i = snakeLength; i > 0; i--)
			{
				SnakeUpdate(&snake[i], dt, &snake[i - 1]);
			}

			snake[snakeLength - 1].direction = snake[snakeLength - 2].direction;
			SnakeSetDirection(&snake[0], dirX, dirY);
			SnakeUpdate(&snake[0], dt, NULL);
			SnakeScreenWrap(&snake[0], colCount, rowCount);

			if(apple.active && snake[0].x == apple.x && snake[0].y == apple.y)
			{
				apple.active = 0;
				snake[snakeLength] = snake[snakeLength - 1];
				snakeLength++;
			}

			if(!apple.active)
			{
				appleSpawnTimer += dt;
				if(appleSpawnTimer > appleSpawnInterval)
				{
					appleSpawnTimer -= appleSpawnInterval;

					Vector2 newPos = getRandomCellCoords(colCount, rowCount);
					while(collidesWithSnake(snake, snakeLength, newPos.x, newPos.y)) {
						newPos = getRandomCellCoords(colCount, rowCount);
					}
					AppleActivateAt(&apple, newPos.x, newPos.y);
				}
			}

			AppleUpdate(&apple, dt);

			int tailLength = snakeLength - 1;
			struct Snake tail[tailLength];
			for(int i = 1; i < tailLength; i++)
			{
				tail[i] = snake[i];
			}
			if(collidesWithSnake(tail, tailLength, snake[0].x, snake[0].y))
			{
				gameInProgress = 0;
			}
		}

        // draw
        BeginDrawing();
        ClearBackground(BLACK);

        for(int r = 0; r < rowCount; r++)
        {
            for(int c = 0; c < colCount; c++) {
                Color color = ((r + c) % 2) == 0 ? RAYWHITE : WHITE;
                DrawRectangle(c * cellSize, r * cellSize, cellSize, cellSize, color);
            }
        }

        for(int i = 1; i < snakeLength - 1; i++)
        {
            SnakeDraw(&snake[i], cellSize, DARKGREEN);
        }
        SnakeDrawHead(&snake[0], cellSize, DARKGREEN);
        SnakeDrawTail(&snake[snakeLength - 1], cellSize, DARKGREEN);

		AppleDraw(&apple, cellSize, RED);

		if(!gameInProgress) {
			const char *gameOverText = "GAME OVER";
			int fontSize = 40;
			int textLength = MeasureText(gameOverText, fontSize);

			int posX = floor(screenWidth / 2) - floor(textLength / 2);
			int posY = floor(screenHeight / 2);
			DrawText(gameOverText, posX, posY, fontSize, BLACK);
		}

        EndDrawing();
    }

    CloseWindow();
}

I joined x.com and followed lot's of influencial programmers. I tried sharing some of my stuff, etc...

But it gave me no joy. It just kinda wore me out. I remember when social media was young and interesting. Now it really does just seem like a bot mine, and an echo chamber for the opinions you chose to hear.

Well as it gave me no joy, I simply deleted it. Once again I am social media less. And that makes me happy.

The Slime

I have decided to go with pixel art. This means that the Slime will consist of 16x16 pixel frames. Each frame will correspond to a bounding box that will be displayed based on the Slime's state (which will be the topic of part 4) and animation duration.

I've used a really nice image editor called Aseprite to create the pixel art for the slime. It had some preloaded color pallettes so I decided to go for the default pico-8 pallette that was availabel. I really liked the bold popping colors. The resulting Slime sprite sheet is below. You can see that I added an idle, walk, jump charge, damage, and death sequence. These will correspond to Slime's game state.

Rendering a texture

When it comes to drawing the sprite on the screen. Raylib requires the texture to be loaded first. Naturally this requires the LoadTexture method. This must be called after the window is initialised. Otherwise you will see some random error that is not at all self explanatory. The code I use to render the texture looks like this:

const Texture2D slime_texture = LoadTexture("assets/sprites/slime.png");

It's also important to remember that the texture needs to be unloaded. This is done like so, outside of the game loop.

UnloadTexture(slime_texture);

In order to draw a single frame of the texture to the screen the DrawTexturePro method is used. This will take a texture, along with a source (frame_rec), and dest (player_bounds). The resulting code looks like this.

Rectangle frame_rec = { 0, 0, 16, 16 };
DrawTexturePro(slime_texture, frame_rec, player_get_bounds(&player), sprite_origin, 0, WHITE);

If you have experience with raylib or gamedev in general, you notice that an important part is left out. If this code were to run now, a 16x16 pixel slime would be drawn to the screen. Which would be much to small to be usable. So the sprite needs to be scaled up. In order to do this a render texture must be created.

A render texture is something that can be drawn to at a smaller scale, then drawn itself at a large scale on the screen. To make this work a virtual screen width and height will be defined. I want the game window to be 480x855 pixels in size. The virtual width of the game will be 160x285 pixels. This means that the Slime will take up more space on the virtual screen, eg: it will look correctly sized. I define the screen sizes as macros.

#define SCREEN_WIDTH 480.0f
#define SCREEN_HEIGHT 855.0f

#define V_SCREEN_WIDTH 160.0f
#define V_SCREEN_HEIGHT 285.0f

I then create the render texture, with a source rec (the virtual screen size), and a dest rec (the scaled screen size).

const RenderTexture2D render_texture = LoadRenderTexture(V_SCREEN_WIDTH, V_SCREEN_HEIGHT);
const Rectangle render_texture_src = {0, 0, V_SCREEN_WIDTH, -V_SCREEN_HEIGHT};

const float virtual_ratio = (float) SCREEN_WIDTH / (float) V_SCREEN_HEIGHT;

const Rectangle render_texture_dest = {
    -virtual_ratio, -virtual_ratio, SCREEN_WIDTH + (virtual_ratio * 2), SCREEN_HEIGHT + (virtual_ratio * 2)
};

The draw loop will then need to be updated as follows to account for drawing to the render texture. Then drawing that render texture to the main out. Raylib provides the BeginTextureMode and EndTextureMode methods to accomodate this like so:

BeginTextureMode(render_texture);
ClearBackground(RAYWHITE);
DrawTexturePro(slime_texture, frame_rec, player_get_bounds(&player), sprite_origin, 0, WHITE);
EndTextureMode();

BeginDrawing();
DrawTexturePro(render_texture.texture,
        render_texture_src,
        render_texture_dest,
        sprite_origin,
        0,
        WHITE);
EndDrawing();

This will result in the following. Note the screenshot contains a floor which I have left out of these code examples.

So they make this their priority. They spend time, and time is money, on adding a tool like eslint to the project. This will flag any style guide violations to other devs. BUT that is not enough. These rules cannot simply be enforced locally. They must be added to the CI/CD pipeline. Not added as warnings, but added as errors. That will cause the 32 minute pipeline to fail because some perfectly valid code does not adhere to the developer's precious opinion. So now not only have they spent 2 weeks of their own time enforcing a style guide and adding linters, and tweaking those linters. They now cost other developers time. Because a javascript string used the incorrect, BUT PERFECTLY VALID, quotation mark.

Then to waste even more time, enforcement of rules and style guides are brought up in scrum meetings. Where countless hours are lost arguing about opinions that do not benefit the end user in any way. Countless hours wasted, countless money wasted, no features delivered.

Procrastination is "the action of delaying or postponing something". In this case the concept of style guides and linters are delaying the delivery of features. Developers are postponing actual work, in favour of arguing about arbitrary opinions.

So to end my rant, Linting is procrastination, EXPENSIVE procrastination.

The installer

Raylib comes with a windows installer. It's available on itch.io. I started off by downloading this and running the installer. Installing raylib locally at C:\raylib. This was the easy part. Now I had to figure out how to make it available to my C file.

Adding raylib to make

I was aware that raylib needed to be included somehow, and I was fairly sure that doing it via make was the best idea. But before I jumped into that I added the following example to my main.c file.

#include "raylib.h"

//------------------------------------------------------------------------------------
// Program main entry point
//------------------------------------------------------------------------------------
int main(void)
{
    // Initialization
    //--------------------------------------------------------------------------------------
    const int screenWidth = 800;
    const int screenHeight = 450;

    InitWindow(screenWidth, screenHeight, "raylib [core] example - basic window");

    SetTargetFPS(60);               // Set our game to run at 60 frames-per-second
    //--------------------------------------------------------------------------------------

    // Main game loop
    while (!WindowShouldClose())    // Detect window close button or ESC key
    {
        // Update
        //----------------------------------------------------------------------------------
        // TODO: Update your variables here
        //----------------------------------------------------------------------------------

        // Draw
        //----------------------------------------------------------------------------------
        BeginDrawing();

            ClearBackground(RAYWHITE);

            DrawText("Congrats! You created your first window!", 190, 200, 20, LIGHTGRAY);

        EndDrawing();
        //----------------------------------------------------------------------------------
    }

    // De-Initialization
    //--------------------------------------------------------------------------------------
    CloseWindow();        // Close window and OpenGL context
    //--------------------------------------------------------------------------------------

    return 0;
}

This is pretty much the "Hello, World!" of the raylib world. It displays a simple window with a message.

The problem I had now is that if I ran make build I would get this error:

main.c:1:10: fatal error: raylib.h: No such file or directory
    1 | #include "raylib.h"
      |          ^~~~~~~~~~

Meaning that gcc couldn't find the raylib header to include it. This meant updating the Makefile.

The working Makefile looks like this:

CC = gcc
CFLAGS = -I"C:\raylib\raylib\src"
LDFLAGS = -L"C:\raylib\raylib\src" -lraylib -lgdi32 -lwinmm

build : main.o
	gcc -o build.exe main.o $(LDFLAGS)

main.o : main.c
	gcc -c main.c $(CFLAGS)

clean : 
	powershell Remove-Item *.exe, *.o

The issues that I ran into were figuring out what LDFLAGS to include. I had initial only -lraylib. Which didn't work. The solution was found in the raylib docs. Once the correct flags were added and make build had run succesfully I could launch the build.exe. Which generated this beautiful screen.

He's very proud of that window It's the simple things...

Now I can start building a game!

For brevity I have given the post the subtitle Hello World. The unabreviated title is why the fuck is this so hard.

Basically it took me waaay to long to install a C compiler, compile a file using make, and then run that file to print "Hello World". It gave me flash backs to my first year at uni trying to do the same thing. It wasn't easy then either. But now, 12 years of professional software engineering later, it's still a pain. A pain which I have documented below. In the hope that it will help someone on their journey to run and compile a basic C program. Realistically it will only ever help future Brian.

How do I install gcc?

I'm on Windows and I use chocolatey as a package manager. So the first step is get chocolatey installed. Then run PowerShell as an admin. As an ADMIN, remember that, or like me you'll have to search in windows for the terminal and then right click the icon and select "run as admin". There is no sudo here.

Now I bet you are thinking I just run choco install gcc. Well you would be wrong. In windows gcc is made available through MingW. So the command we run to install gcc is:

choco install mingw

make build

It's entirely possible to compile and run a simple program using gcc alone. But I want some sort of build system. So let's install make:

choco install make

The first program I want to run is as follows.

// main.c
#include <stdio.h>

int main() {
   printf("Hello, World!");
   return 0;
}

Now it's here I make a time costing mistake. I use the following command to compile the program.

gcc main.c -o build.exe

A seasoned C programmer will see the problem straight away. Not me. The command generates build.exe. Now I run it with ./build.exe. I should see "Hello, World!" printed to the console. Instead I see the following.

Program 'build.exe' failed to run: The specified executable is not a valid application for this OS platform.At line:1
char:1
+ .\build.exe
+ ~~~~~~~~~~~.
At line:1 char:1
+ .\build.exe
+ ~~~~~~~~~~~
    + CategoryInfo          : ResourceUnavailable: (:) [], ApplicationFailedException
    + FullyQualifiedErrorId : NativeCommandFailed

Ok, so the error is telling me that the specified executable is not correct for the OS. So do I add -m64 and make the command gcc -m64 -c main.c -o build.exe? Nope same error. So fast forward 2 hours, and I figure it out.

-c                       Compile and assemble, but do not link.

The -c flag is not needed. So I run:

gcc -c main.c -o build.exe

And voila build.exe prints "Hello, World!" to the console. Now I add the following content to my make file.

build : main.o
	gcc -o build.exe main.o

main.o : main.c
	gcc -c main.c

clean : 
	powershell Remove-Item *.exe, *.o

This allows me to run useful commands like make clean, and make build.

And that's a wrap for part 1. Tomorrow I will look at adding raylib to the project.

Why a right click? He tried making the mouse move, but the screen still went to sleep. A left click might take an action, so right clicking is safer.

The script

I call this script the "drinking bird" after that episode of the Simpsons where Homer entrusted the nuclear power plant's safety over to a novelty toy.

This script uses the mouse package. Install it via pip.

import sched, time, mouse

INTERVAL = 120

def do_right_click(scheduler):
    scheduler.enter(INTERVAL, 1, do_right_click, (scheduler,))
    mouse.right_click()

my_scheduler = sched.scheduler(time.time, time.sleep)
my_scheduler.enter(INTERVAL, 1, do_right_click, (my_scheduler,))
my_scheduler.run()

As long as this is running, your screen won't go to sleep, and if you have your company's chat client open, it will look like you are active.

Good luck on your side projects....

It's true, most of the time his quality is quite low. Well at least he's trying...

So what will I be blogging about in 2025?

Well, in course with attempting to write at least 50 blog posts. I will be attempting to build and ship 12 things. A thing could be an app, a website, or a game. The important part is the building and shipping. In 2024 I started and failed many projects. This year I want to have some more perceverence. Completing a project every month is something I feel is both a challenge and achievable. It doesn't have to be world changing, just complete to the extent where I feel done.

So with that in mind, I will try to document my learnings, achievements, and failures. I hope that in doing so I will improve my writing skills. I also want to try adding some video content. Basically I want to be an influencer and advertise random scams to people...

Predictions for 2025?

Max Verstappen will win his fifth world title and sign a deal with Mercedes. The world won't end. My family will expand, and so will my waistline.

Creating the PostgreSQL container

docker run --name postgres-1 -e POSTGRES_PASSWORD=password -d -p 5432:5432 postgres:alpine

This command creates an instance of the postgres:alpine container. The --name flag is used to assign a name to the container. The -e flag passes in the required environment variables. In this case a POSTGRES_PASSWORD is required. This will be used to authenticate the postgres user. -d tells docker to run the command as a background process. Finally -p is used to expose the port that postgres is running on. The default is 5432, so we map the container's 5432 to localhost:5432.

Create a database and add some content

Access the PostgreSQL instance running inside the Docker container

docker exec -it postgres-1 psql -h localhost -p 5432 -U postgres

This command can be broken into two parts. The first part docker exec -it postgres-1, tells docker the execute the following command inside our previously created container. The -it flag is a combination of --interactive and--tty. This tells docker to take you straight inside the container.

The second part of the command psql -h localhost -p 5432 -U postgres takes us inside the postgres server. The -h flag specifies the the host, -p specifies the port, and -U the user we want to login as.

Once the initial command is run you should see the postgres prompt. We can now create a database and populate it with some information.

Create and modify database

Once inside the postgres instance we can use the following commands to create a database, add a table to that database, and finally insert data into the table.

create database test;

The above command creates a database named "test". We can then connect to that database using the following command.

\c test;

Once connected we can run the following to add the messages table to the test database.

create table if not exists messages();
alter table messages add column id uuid not null primary key;
alter table messages add column content varchar(255);
insert into messages (id, content) values (uuid_generate_v4(), 'Hi, from postgres');

Install the uuid-ossp extension with the following command create extension if not exists "uuid-ossp";

After successfully running the above our test database will now have some content which we will fetch with lua.

Querying the database with Lua

Installing luasql via LuaRocks

In order to connect to our postgres database with Lua, we will use the luasql.postgres rock. To install this rock run the following command luarocks install luasql-postgres.

Fixing the libpq-fe.h install error on Ubuntu

If you are using Ubuntu to follow this tutorial, you may see the following error when running luarocks install luasql-postgres.

Error: Could not find header file for PGSQL
  No file libpq-fe.h in /usr/local/include
  No file libpq-fe.h in /usr/include
  No file libpq-fe.h in /include
You may have to install PGSQL in your system and/or pass PGSQL_DIR or PGSQL_INCDIR to the luarocks command.

This can be solved by passing the PGSQL_INCDIR property to the progam. Commonly the required value is /usr/include/postgresql/. As that is the directory containing the libpg-fe.h.

Run the command as follows to successfully install luasql-postgres.

luarocks install luasql-postgres PGSQL_INCDIR=/usr/include/postgresql

Writing a lua script to print the messages

Once luasql-postgres has successfully been installed, we can then write a Lua program to fetch records from the database we created earlier.

Create a main.lua file and add the following.

-- load driver
local driver = require "luasql.postgres"
-- create environment object
env = assert (driver.postgres())
-- connect to data source
con = assert (env:connect("test"))
-- reset our table
cur = con:execute"SELECT * FROM messages;"
row = cur:fetch ({}, "a")
while row do
  print(string.format("MESSAGE: %s", row.content))
  -- reusing the table of results
  row = cur:fetch (row, "a")
end
-- close everything
cur:close() -- already closed because all the result set was consumed
con:close()
env:close()

Run the script with the correct env variables

The script written inside our main.lua file expects that we supply some postgres variables when running it. These are PGUSER, the user we want to connect to our database with. PGPASSWORD, the password set for the user. PGHOST, the host we will use to access the server. And finally, PGPORT, the port number at which we can access the postgres server.

PGUSER=postgres PGPASSWORD=password PGDATABASE=lua_messages PGHOST=localhost PGPORT=5432 lua main.lua

Running the above script should print out the content of the messages we added to our postgres database.

The decision is yours to make.

Ah, noble adventurer! Your quest is most ambitious, seeking mastery across the realms of web, game, and app development. You require a loyal companion—a language versatile yet skilled, simple to start yet deep in wisdom. Allow me to choose a companion that suits your daring journey.

The Hero Reborn: Python

A seasoned hero, revered in many domains but now hungers to prove its worth in the lands of web and game dev. Python is approachable, wielding a clean syntax and an arsenal of libraries. With Django and Flask, it thrives in the bustling web taverns, while Pygame offers tools for casual game creation. Though not the mightiest in performance-heavy battles, Python's charm and adaptability make it a steadfast ally.

The Cunning Wizard: Rust

A rising star, Rust wields the enchanted tome of memory safety without sacrificing performance. For game dungeons and app battlegrounds where performance is life and bugs are death, Rust is peerless. While its spells for web sorcery, like Rocket and Axum, are in their infancy, they grow strong with each passing season. Rust demands patience, but the rewards are unmatched—fearlessness and power.

The Rogue Outlier: Dart

An underdog, Dart is the shadow that walks in Flutter's cloak, a single framework to rule cross-platform app development with ease. While less battle-tested in game dev, Dart’s nimbleness and vibrant ecosystem hold promise. For web sorcery, its role is less pronounced but capable. The rogue knows the value of swift iteration and broad reach.

The Bold Jack-of-All-Trades: JavaScript/TypeScript

A legend that walks all lands—web is its true dominion, with React, Node.js, and Next.js carving its legacy. In game development, JavaScript can wield tools like Three.js for immersive 3D adventures, or partner with game engines like Phaser. Though not the mightiest in app development, it joins hands with React Native for valiant efforts.

My Choice: Rust, the Cunning Wizard

Rust is my pick, for it combines strength, safety, and boundless potential. It is a rare companion that challenges you to grow while safeguarding your journey. Its versatility spans game dungeons, app citadels, and web towers, and though its learning curve is steep, the rewards are as vast as your ambition.

May you and your companion forge an unbreakable bond and conquer the realms of computer science! Go forth, adventurer, and let your saga be one of legend!

Example

The common way of explaining this is by using the following math example. Say we have a function called add(a: number, b: number). We could use this to create a function called addOne by binding one as the first argument like so:

const add = (a: number, b: number) => a + b
const addOne = partial(add, 1)

addOne(2) // 3

The above is a naive example, but I'm sure that you can see how this would be of benefit in more complex examples. Perhaps it could be use to build up config methods in your application or to create methods that work on a certain instance of an object, where you cannot modify the source code.

Implementation

Implementing a method that can partially apply arguments to other methods is somewhat trivial thanks to ECMAScript's syntactic sugar.

Below is a Typed and untyped example.

// Untyped
const partial = (fn, ...fixedArgs) => (...args) => fn(...fixedArgs, ...args)

// Typed... and ugly
function partial<T, U extends any[], V extends any[]>(
  fn: (...args: [...U, ...V]) => any,
  ...fixedargs: U
): (...args: V) => any {
  return (...args: V) => fn(...fixedargs, ...args);
}

There is possibly a nicer way to type this, that does not use any. However I don't feel like wrestling with the type system. Mainly because the use of partial implementation lends itself better to loosely typed programming.

Implementation

The game is written in vanilla js and doesn't use any libraries. It's all rendered via the canvas api. Using the techniques I mentioned in "useful-image-data-methods".

I made the sound effects myself. I bet you thought it was a really chicken and duck.

Nobody thought that...

Play the game

You can play the game at /games/chicken-farmer/.

Read the source code

You can read the ugly source code at BrianDouglasIE/chicken-farmer.

It was written very quickly, so give me some slack.

function getSprite(spritesheetCtx, x, y, size) {
	return spritesheetCtx.getImageData(size * x, size * y, size, size)
}

Below are three useful methods that build on this technique.

Clone ImageData

When ctx.getImageData is called, it returns an ImageData object. This ImageData object can then be rendered and manipulated. When manipulating the ImageData object we will want to create a copy so that the original is not altered. To do this we use the following method.

function cloneImageData(imageData) {
	const data = new Uint8ClampedArray(imageData.data)
	return new ImageData(data, imageData.width, imageData.height)
}

The data held by an ImageData instance is a Uint8ClampedArray. To copy the data a new Uint8ClampedArray is instantiated from the original ImageData object and passed as a constructor argument to the new one.

Color Mask

I like to use Kenny's massive one bit tile pack when creating small 2d games. I use the non-colored white version. This allows me to add a color mask to the sprites, so that I can have them be any color I like.

Again I will render the spritesheet on an offscreen canvas and pre-fetch the sprites before game starts. I use the following method in order to apply a color mask to the sprites.

function applyColorMaskToImageData(imageData, maskColor) {
	const { data } = imageData
	const [maskR, maskG, maskB, maskA] = maskColor;

	for (let i = 0; i < data.length; i += 4) {
		const r = data[i];
		const g = data[i + 1];
		const b = data[i + 2];
		const a = data[i + 3];

		data[i] = (r * maskR) / 255;
		data[i + 1] = (g * maskG) / 255;
		data[i + 2] = (b * maskB) / 255;
		data[i + 3] = (a * maskA) / 255;
	}

	return imageData
}

This method takes and ImageData object, which should be a copy from cloneImageData, and applies the passed in rgba values as a mask. This can be used like so.

// initial sprite to copy
const skeletonSprite = getSprite(spritesheetCtx, 1, 1)
// sprite with red color mask applied
const redSkeletonSprite = applyColorMaskToImageData(cloneImageData(skeletonSprite), [255, 0, 0, 0])

Flip Horizontally

Tile packs usually only contain sprites facing in one direction. This means that if a sprite is facing left and you want it to face right, you will need to flip the sprite on a horizontal access. Again this is achieved by modifying the ImageData.

function flipImageDataHorizontally(imageData) {
	const { width, height, data } = imageData;
	const flippedData = new Uint8ClampedArray(data.length);

	for (let y = 0; y < height; y++) {
		for (let x = 0; x < width; x++) {
			const srcIndex = (y * width + x) * 4;
			const destIndex = (y * width + (width - x - 1)) * 4;

			flippedData[destIndex] = data[srcIndex];
			flippedData[destIndex + 1] = data[srcIndex + 1];
			flippedData[destIndex + 2] = data[srcIndex + 2];
			flippedData[destIndex + 3] = data[srcIndex + 3];
		}
	}

	return new ImageData(flippedData, width, height);
}

With the sprite now flipped on it's horizontal acces it can be used like so.

// initial sprite to copy
const skeletonSprite = getSprite(spritesheetCtx, 1, 1)
// left facing instance of ImageData
const leftFacingSkeletonSprite = flipImageDataHorizontally(cloneImageData(skeletonSprite))

Example usage

Let's say we have a confirmation modal that appears when a button is clicked. This could be to confirm whether or not a user wants to commit changes to a resource. It is likely that the HTML for the modal dialogue is not contained within the original form. So when the confirm button is clicked inside the modal it will not submit the original form. Unless of course JavaScript is used to listen for the confirm event.

Adding a form attribute to the confirm button specifying which form to submit is a much nicer way to solve this. For example the button below will submit the form with an id="updateResource". Without requiring any extra JavaScript.

<button form="updateResource" type="submit">Confirm</button>

Why Julia?

Well that is a straight forward one to answer. I was watching a Formula 1 race and noticed that JuliaHub is a sponsor of the Williams F1 team. So naturally I thought I better try out the language and so I set about writing some programs in Julia.

Julia is mainly used in the academic and scientific realms. But at it's core it is quite a nice general purpose language.

It is similar to Python, but it does not support OOP. Instead it uses pattern matching with method overloads to handle different data types. For example let's say we have a greeter function that can greet students and teachers. In Julia that might look like this.

function greet(person::Teacher)
  return "Hello Teacher"
end

function greet(person::Student)
  return "Hello Student"
end

The correct variant of greet get's called based on the type of struct that is passed to the method. A struct being the way to define a custom data type. This takes a little bit of getting used to. But once I got my head around the fact that Julia operators were methods it started to make sense. This clicked when it came to writing comparators for BeeDeeDee.jl the test framework I ended up writing.

But why did I end up writing a test framework? I hear you ask. Well because the built in Julia test framework lacked features that I wanted and would expect every test framework to have. For example hooks, like before_each and after_all, as well as human readable methods. The latter being something that the Julia community seem to readily reject. Opting to use mathematic operators where they can. Which is no surprise when Julia's scientific background is taken into account.

So I set off into the unknown and started writing a test framework. I had a clear idea in mind of what I wanted to achieve. That being an api that looked like the following.

describe("User Age Tests") do
  it("should have an age greater than or equal 18 and less than 100") do
    expect(user.age) |>
      to_be_greater_than_or_equal(18) |> and |> to_be_less_than(100)
  end
end

The implementation

Starting off with the code I wanted to achieve was a great help. I knew that I wanted to make use of method chaining using Julia's pipe operator |>. The reason for this being that it allows for clear an readable code. It also allows for a data structure to be passed through and transformed by multiple methods. This would be necessary for assertions.

In BeeDeeDee the expect method takes a value and creates an Expectation struct based off of that value. The comparators, which are methods that are called against the assertion, then take the value of the assertion and apply their own logic. These are essentially methods which check for the correct boolean value when comparing their own value with the assertion. I say correct boolean value as an Expectation may be negated using the not comparator. Which essentially reverses the expected boolean value from True to False.

The Expectation struct itself holds it's own value as well as it's comparator function and result of that comparator function, once it has been applied on it's value. This is necessary as more than one expectation may be called per test. The code for the Expectation struct is minimal as shown below. You'll notice that a Vector{String} data type is also present. This is used to store the logs from the Expectation's comparator methods. Which are used for cli reporting.

struct Expectation
    value::Any
    comparator::Function
    result::Bool
    logs::Vector{String}
end

The test framework allows for tests to be grouped and hooks to be applied to those groups. Implementing this was difficult and my solution was not ideal. In order to keep track of what the current test suite was I used a global variable that stored the current test suite's id. The id belonged to a Suite struct that was created when either testgroup or describe was called. This struct would then be used to hold information such as the tests which were run inside the suite, the results of those tests, as well as the hooks that should be run before and after each test. The definition of these structs are below.

Base.@kwdef mutable struct Hooks
    before_all_called::Bool = false
    after_all_called::Bool = false
    before_all::Vector{Union{Nothing,Function}} = []
    after_all::Vector{Union{Nothing,Function}} = []
    before_each::Vector{Union{Nothing,Function}} = []
    after_each::Vector{Union{Nothing,Function}} = []
end

Base.@kwdef mutable struct TestResult
    description::String = ""
    status::Symbol = :Pending
    f::Union{Task,Function} = () -> nothing
    expectations::Vector{Expectation} = []
    stacktrace::Any = []
end

Base.@kwdef mutable struct Suite
    tests::Vector{TestResult} = []
    child_suites::Vector{Suite} = []
    f::Union{Task,Function} = () -> nothing
    status::Symbol = :Pending
    hooks::Hooks = Hooks()
    description::String = ""
    id::Int64 = 0
end

I mentioned that this was not a good solution. This is because it would not allow for concurrent test files to be run. Because a global variable is used to store the current suite, the tests must be executed in order. Otherwise their results could end up in the wrong Suite struct. I'm still not entirely sure how this could be solved. I would have to take a look at other frameworks for some inspiration.

The final noteworthy part of the implementation was the use of Julia's built in operators to create comparators. I was able to leverage the fact that Julia's builtin operators are methods themselves, to create concise comparators. For example I wrote a helper method called construct_comparator that took an operator as an argument and then used it as a callback method to compare the expected value with the actual value. I have left out the code for construct_comparator as it contains reporting logic which makes the code hard to understand without some domain knowledge. What is easy to understand however is it's use. For example here is how the to_be comparator is defined.

to_be = construct_comparator(===, "to be")

My thoughts on Julia

Writing a test framework in an unknown programming language is quite a feat. But it allowed me to really dig down deep into Julia in quite a short period of time. I was impressed by the syntax of Julia. There are some real opportunities to write beautiful code. The use of the do keyword and pipe operator allow for concise and readable code. Even if it took me a while to understand the argument order required for the do keyword.

It's a shame however that the beautiful and readable syntax which Julia can offer is contrasted with some awkward syntax such as how default arguments are assigned in a struct. For example, the Suite struct in BeeDeeDee.jl.

Base.@kwdef mutable struct Suite
    tests::Vector{TestResult} = []
    child_suites::Vector{Suite} = []
    f::Union{Task,Function} = () -> nothing
    status::Symbol = :Pending
    hooks::Hooks = Hooks()
    description::String = ""
    id::Int64 = 0
end

Experienced users of Julia might look past this. But to me it reeks of complexity. To understand this a developer must understand why the mutable keyword is there, and what Base.@kwdef is, as well as why a macro is needed. A macro being a language feature that allows for certain meta programming techniques. They are used frequently, but I've only ever found them to add complexity.

Another example of Julia being awkward is in it's use of modules and exports. I still don't fully understand how modules work. One might think of them sort of like a class in OOP. They act like a container for code, which can export certain members. Unfortunately though Julia forces the developer to export each method individually. Leading to some verbose code. Below is the comparators export for BeeDeeDee. A public keyword on the method definition would be much nicer.

export to_be,
to_be_true,
to_be_false,
to_be_greater_than,
to_be_less_than,
to_be_greater_than_or_equal,
to_be_less_than_or_equal,
to_be_in,
to_be_nothing,
to_be_typeof,
to_be_empty,
to_have_key,
to_be_subset,
to_be_setequal,
to_be_disjoint,
to_match,
to_be_valid_email,
to_throw

Imports are equally awkward. Every time a module is imported it is imported fresh. Meaning that if A.jl and B.jl are in the same application and import C.jl. There will be a conflict and an error with Julia complaining that C.jl is already imported. To get around this Julia developers import modules into a common parent and access them using a path like syntax. With using ..C meaning import the C.jl module that was required in my parent's scope... yikes.

Will Julia become a mainstream language?

In data science and academia, yes. Maybe third or fourth for popularity at it's height. But only because there seems to be a lot of money behind it. Well at least I assume there must be if Formula 1 cars are being sponsored by JuliaHub.

In anything else, no. I was not convinced that Julia would help me solve any problems on the web or in game dev. It did introduce me to some novel concepts. But ultimately there was nothing there to convert me into a Julia developer. The main annoyances being around how modules work. I could never imagine building a large complicated system in a language that has such confusing code interop.

PRAGMA journal_mode = WAL;

Why?: Allows concurrent reads and writes, making it more suitable for web applications with multiple users accessing the database simultaneously.

PRAGMA synchronous = NORMAL;

Why?: Balances performance and data safety by ensuring that data is written to disk in a reasonable time frame without slowing down writes as much as FULL mode.

PRAGMA busy_timeout = 5000;

Why?: Prevents "database is locked" errors by giving SQLite 5 seconds to wait for a locked resource before returning an error, useful for handling multiple concurrent accesses.

PRAGMA cache_size = -20000;

Why?: Sets the cache size to 20MB, allowing more data to be cached in memory, improving query performance by reducing the number of disk reads.

PRAGMA foreign_keys = ON;

Why?: Ensures referential integrity by enforcing foreign key constraints, critical for maintaining consistent relationships between tables (e.g., users, posts, and comments).

PRAGMA auto_vacuum = INCREMENTAL;

Why?: Reclaims disk space gradually as rows are deleted, instead of performing a full vacuum, reducing performance impact during database operations.

PRAGMA temp_store = MEMORY;

Why?: Stores temporary tables and other temporary data in memory, improving the performance of operations like sorting and indexing that are common in web applications.

PRAGMA mmap_size = 2147483648;

Why?: Uses memory-mapped I/O with a size of 2GB, which can speed up database access by reducing disk I/O, especially beneficial for large databases with frequent reads and writes.

PRAGMA page_size = 8192;

Why?: Sets a page size of 8KB, which provides a balance between memory usage and disk I/O performance for a forum database that handles many reads and writes.

Copy paste

For your convenience.

-- Set the journal mode to Write-Ahead Logging for concurrency
PRAGMA journal_mode = WAL;

-- Set synchronous mode to NORMAL for performance and data safety balance
PRAGMA synchronous = NORMAL;

-- Set busy timeout to 5 seconds to avoid "database is locked" errors
PRAGMA busy_timeout = 5000;

-- Set cache size to 20MB for faster data access
PRAGMA cache_size = -20000;

-- Enable foreign key constraint enforcement
PRAGMA foreign_keys = ON;

-- Enable auto vacuuming and set it to incremental mode for gradual space reclaiming
PRAGMA auto_vacuum = INCREMENTAL;

-- Store temporary tables and data in memory for better performance
PRAGMA temp_store = MEMORY;

-- Set the mmap_size to 2GB for faster read/write access using memory-mapped I/O
PRAGMA mmap_size = 2147483648;

-- Set the page size to 8KB for balanced memory usage and performance
PRAGMA page_size = 8192;

The task at hand

So for this demo let's say we want to render the sprite of our game's hero character on a canvas. The sprite sheet that I will be using is from KenneyNL, it's the 1-Bit monochrome asset pack. Each sprite in the canvas is 16x16 pixels in dimension. This will be scaled up to around 4 times it's original size.

I want my canvas to be 640x480 pixels in dimension. If I were to draw a sprite directly on the canvas it would look miniscule. If I were to draw it at 4 times it's original size, it would look blurry. So the question is, how do I draw my scaled up pixel art character without causing it to blur.

I bet this complex problem requires a complex solution I bet the solution is a one liner

Some boiler plate

Before I even get as far as rendering my pixel art character on a canvas there is some initial boilerplate code that is needed.

Firstly I'll need to create a canvas element to render the game on. I can do that with the following code. Which creates the canvas and appends it to the document's body. I also set the canvas' width and height to be a quarter of the intended size. I will scale this up later.

const canvas = document.createElement('canvas')
const ctx = canvas.getContext('2d')
document.body.appendChild(canvas)
canvas.height = 120
canvas.width = 160

Once this is in place I will add some functions to render the sprite sheet and extract the image data of the sprite that I want to render. To do this I create a separate canvas. This canvas will not be appended to the body of the html document as the user will never see it. Instead it will be used to draw the sprite sheet in it's entirety. I will then grab the individual sprites from it as and when they are needed. I also set the canvas to be scaled up the target size using CSS. The code for this is below.

const spriteCellSize = 16
const spriteSheet = new Image()
spriteSheet.crossOrigin = "anonymous"
spriteSheet.addEventListener("load", onLoad, false)
spriteSheet.src = "./monochrome-transparent.png"

const scale = 4
canvas.style.width = `${canvas.width * scale}px`
canvas.style.height = `${canvas.height * scale}px`

const spriteSheetCanvas = document.createElement('canvas')

let heroSprite = undefined

function onLoad() {
  if (!heroSprite) {
    spriteSheetCanvas.width = spriteSheet.width
    spriteSheetCanvas.height = spriteSheet.height
    const spriteSheetContext = spriteSheetCanvas.getContext('2d')
    clearScreen(spriteSheetContext, spriteSheetCanvas.width, spriteSheetCanvas.height)
    drawSpriteSheet(spriteSheetContext, spriteSheet)
    heroSprite = getSpriteSheetCell(spriteSheetContext, spriteCellSize, 26, 0)
  }

  clearScreen(ctx, canvas.width, canvas.height)
  ctx.putImageData(heroSprite, canvas.width / 2 - spriteCellSize / 2, canvas.height / 2 - spriteCellSize / 2)
}

function clearScreen(ctx, w, h) {
  ctx.save()
  ctx.fillStyle = "black"
  ctx.fillRect(0, 0, w, h)
  ctx.restore()
}

function drawSpriteSheet(ctx, spriteSheet) {
  ctx.drawImage(spriteSheet, 0, 0)
}

function getSpriteSheetCell(ctx, spriteCellSize, col, row) {
  const x = spriteCellSize * col
  const y = spriteCellSize * row
  return ctx.getImageData(x, y, spriteCellSize, spriteCellSize)
}

Here is what is rendered on the canvas. As you can see it is super blurry.

The solution

One line of CSS fixes this. Setting the image-rendering property on the canvas to be pixelated. In the demo code this can be done by adding the following statement at line 10.

canvas.style.imageRendering = "pixelated"

The canvas now renders a crisp sprite.

Let's say we have a migration like the following.

CREATE TABLE tickets (
    id SERIAL PRIMARY KEY,

    title VARCHAR(140) NOT NULL,
    content VARCHAR(500) NOT NULL,

    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
);

This is perfectly fine. It creates the tickets table. But what if we are working on this feature and then have to switch to another part way through? Well we checkout the other feature branch and work away. Now it's time to come back to the tickets feature. Let's say we have to build the application locally when working on it. Once we try to build the app the migrations will fail. Why? because the tickets table already exists, from when we were previously working on the feature and ran the migration.

The Solution

Well that's annoying right? one solution would be to rollback the migration or delete the correct row in our migrations table. But we can prevent this problem from ever happening in the first place by adding CREATE TABLE IF NOT EXISTS to our migration. It now looks like this.

CREATE TABLE IF NOT EXISTS tickets (
    id SERIAL PRIMARY KEY,

    title VARCHAR(140) NOT NULL,
    content VARCHAR(500) NOT NULL,

    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
);

It may seem like an obvious thing but I've been working on a codebase recently where the teams have not been doing this. It leads to annoying failures when checking out different branches. So make sure to apply this when writing SQL migrations.

Those lucky ones working on Laravel, Django, or Rails apps will never face this issue. This is a burden of the enterprise Java developer.

Let's look at the migration for a tickets table. In this example we can think of a ticket as an item of work that may go through various states. Let's start by naively adding a boolean property for each state that the ticket might go through.

CREATE TABLE IF NOT EXISTS tickets {
    id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    description TEXT,
    is_open BOOLEAN DEFAULT TRUE,
    is_in_progress BOOLEAN DEFAULT FALSE,
    is_completed BOOLEAN DEFAULT FALSE,
    is_on_hold BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
}

We can tell from the above migration that a ticket has four known states open, completed, in_progress, and on_hold. I say known states as in the future another state may appear, for example pending_approval. Using the above pattern this would require yet another property to be added. But really all these properties are communicating is the current state of a ticket. This is where an enum would add value.

By using an enum all the properties used to communicate state can be combined into one state property. This will also remove any logic needed to ensure that a ticket is only in one state at any given time, which would be needed in the previous example.

An enum can be added as follows.

CREATE TYPE ticket_state AS ENUM ('open', 'completed', 'in_progress', 'on_hold')

CREATE TABLE IF NOT EXISTS tickets {
    id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    description TEXT,
    state ticket_state DEFAULT 'open',
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
}

Notice that as well as reducing the number of properties needed. The state enum can also default to 'open'.

Altering an Enum in PostgreSQL

So let's say it's now six months down the line and having recieved some client feedback it looks like a ticket should be approved before it is sent to complete.

This will require a new database migration. Using PostgreSQL it would look like this.

ALTER TYPE ticket_state ADD VALUE 'pending_approval';

PostgreSQL also allows for the new value to be added above or below an existing value like so.

ALTER TYPE ticket_state ADD VALUE 'pending_approval' BEFORE 'completed';
ALTER TYPE ticket_state ADD VALUE 'pending_approval' AFTER 'in_progress';

Wikipedia tells me that these are the rules by which a cell can be determined to be alive or dead.

• Any live cell with fewer than two live neighbours dies, as if by underpopulation.
• Any live cell with two or three live neighbours lives on to the next generation.
• Any live cell with more than three live neighbours dies, as if by overpopulation.
• Any dead cell with exactly three live neighbours becomes a live cell, as if by reproduction.

With this in mind I was able to create the below demo. I added interactivity by allowing the user to click a cell to toggle it's state between dead and alive. Pressing the up arrow key runs the next cycle.

Convert the above requirements to CLI commands and we get.

  -all
        Apply all pending migrations
  -down int
        Migrate down a certain number of versions
  -reset
        Revert all migrations
  -to int
        Migrate to a specific version
  -up int
        Migrate up a certain number of versions

Assumptions

Let's assume the code in the sections below is part of a package called migrator, and that we will be running the code from that package as a command line application. Let's also assume that the program has recieved details about how to connect to the database, and uses the go sql package to connect.

Command line options

This is intended to be a command line tool. Luckily Go's flags package makes this trivial. I start by defining an Options struct in the migrator package.

type Options struct {
	To    int
	Up    int
	Down  int
	All   bool
	Reset bool
}

Then inside main.go I can set the Options values like so. Notice the default values and description text. All this info will be displayed when passing the --help flag.

var opts migrator.Options
flag.BoolVar(&opts.All, "all", false, "Apply all pending migrations")
flag.BoolVar(&opts.Reset, "reset", false, "Revert all migrations")
flag.IntVar(&opts.To, "to", 0, "Migrate to a specific version")
flag.IntVar(&opts.Up, "up", 0, "Migrate up a certain number of versions")
flag.IntVar(&opts.Down, "down", 0, "Migrate down a certain number of versions")
flag.Parse()

A pointer to this struct will then be passed into the migrator.Migrate function.

Structuring a migration

Typically a migration has an up and a down action. I've opted to use sql files for migrations rather than an orm. I've done this to avoid complexity. The complexity being, having to learn the nuances of an orm, when I already know what I want to achieve with sql.

The migrations will be stored in a migrations directory and each migration will have a .up.sql and .down.sql file. The file naming convention will look like this [version]-[name].[direction].sql. So, for example, our first migration will look as follows. Note: this migration will always need to be first as it creates the table where our migration info will be stored.

-- 001-create-migrations-table.up.sql
CREATE TABLE IF NOT EXISTS migrations (
    id INTEGER PRIMARY KEY AUTOINCREMENT,

    version INTEGER NOT NULL,
    name TEXT NOT NULL,

    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 001-create-migrations-table.down.sql
DROP TABLE IF EXISTS migrations;

Our migrator program will read the migrations directory and gather the migration files into the following struct.

type Migration struct {
	Version  int
	Name     string
	UpFile   string
	DownFile string
}

This can then be used to sort migrations by version. Getting the latest migration from our migrations table will tell us our current DB version. When running the up or down commands we need only concern ourselves with the migrations that have a version that is higher or lower than the current db version respectively. If a migration should be applied then execute the UpFile if it should be reverted then execute the DownFile.

Using transactions with context

Transactions in go can be used to commit or rollback multiple grouped sql queries. The go docs at database/execute-transactions sum up transactions like so.

A database transaction groups multiple operations as part of a larger goal.

The migrator program is doing just that. It takes a bunch of sql statements and runs them to create a new database state. Should one of the migrations fail, we can use the go transaction to rollback the state of the database to how it was before the migrator ran. Alternatively we can also commit the transaction if all migrations run successfully.

We'll use the transaction along with a context. Using a Go context.Context with a database transaction helps manage timeouts, cancellations, and ensures that long-running database operations are cleaned up with the context. If the context is canceled any ongoing database transactions can be rolled back. This prevents partial data writes or inconsistencies.

Using a transaction along with a context is trivial.

// create context
ctx := context.Background()

// pass our context to the transaction
tx, err := db.BeginTx(ctx, nil)
if err != nil {
    return fail(err)
}

// defer rollback, will be called if `tx.Commit` is not
defer tx.Rollback()

This transaction can then be passed around out migrator program. Once all the migrations have been handled, and assuming no errors have occured, the transaction can be committed be calling tx.Commit. Any call to the trnasaction after it is commited will result in an error. Commiting ends the transaction.

Final thoughts

A db migrator should not be a complex program and it should not have a complex API. I looked at some widely used libraries for managing migrations and I was struck by their complexity and learning curve. Due to this I decided it better to create a simple package to achieve the same end. It took around 90 minutes and helped me to better understand how migrations work. I also now have my own tool to manage migrations, that I can bend to my liking.

Feel free to look through the entire source code at BrianDouglasIE/go-lang-db-migrator.

My Thoughts

I have seen a couple of videos on YouTube where developers have been making games using Go. My understanding of Go was that it was a Web Dev Backend language for hipsters. However, having written this simple program in Go I have been pleasantly surprised by the features the language has to offer. For me the built in "tools" that come with Go are excellent and not something I was aware of. Go provides a built in code formatter, gofmt, which means I don't have to think about how my Go code should look. It also comes with, gopls, a language server developed by the Go team. This meant that I only had to install the vim-go extension to turn neovim into a Go IDE without any set up.

Then it comes to the language itself. I had heard Go was "simple". To my surprise this was actually true. I was able to write Go pretty much straight away due to it's familiar syntax. The only new aspects to me were the assignment operator :=, that slices were favoured over arrays, and that a capital letter was used to signify privacy.

It took me 90 minutes to write the below Pong implementation. I had never written a line of Go before, so I feel this is a big achievement for the language. I would say I was instantly productive. Looking at the source code of my Pong implementation, I am sure you will agree it is clear and readable. This is owed to the simplicity of Go. A language of which I feel I will be using a lot more of in the future.

The Setup

No much to it, create a Go module and install raylib-go.

go mod init main
go get github.com/gen2brain/raylib-go

The Code

I won't write out what the code is doing as I feel it is fairly self explanatory. I know you are an ace programmer, so you don't need your hand held.

The game can be launched with go run main.go.

package main

import (
        "fmt"
        "image/color"
        "math/rand"
        "time"

        rl "github.com/gen2brain/raylib-go/raylib"
)

const (
        SCREEN_WIDTH          = 800
        SCREEN_HEIGHT         = 450
        CENTER_X              = SCREEN_WIDTH / 2
        CENTER_Y              = SCREEN_HEIGHT / 2
        SIDE_BUFFER_WIDTH     = 40
        INITIAL_PADDLE_HEIGHT = 80
        INITIAL_PADDLE_WIDTH  = 20
        INITIAL_PADDLE_SPEED  = 4
        INITIAL_BALL_SIZE     = 16
        INITIAL_BALL_SPEED    = 4
        RIGHT_BOUNDS          = SCREEN_WIDTH
        LEFT_BOUNDS           = 0
        TOP_BOUNDS            = 0
        BOTTOM_BOUNDS         = SCREEN_HEIGHT
)

type Paddle struct {
        X      int32
        Y      int32
        VX     int32
        VY     int32
        Width  int32
        Height int32
        Score  int32
        Speed  int32
        Color  color.RGBA
}

func (p *Paddle) Draw() {
        rl.DrawRectangle(p.X, p.Y, p.Width, p.Height, p.Color)
}

func (p *Paddle) IncrementScore() {
        p.Score += 1
}

func (p *Paddle) Update() {
        p.X += p.VX
        p.Y += p.VY
}

type Ball struct {
        X     int32
        Y     int32
        VX    int32
        VY    int32
        Size  int32
        Serve int32
        Color color.RGBA
}

func (b *Ball) Draw() {
        rl.DrawRectangle(b.X, b.Y, b.Size, b.Size, b.Color)
}

func (b *Ball) Update() {
        b.X += b.VX
        b.Y += b.VY
}

func (b *Ball) Reset() {
        b.Size = INITIAL_BALL_SIZE
        b.X = CENTER_X - (INITIAL_BALL_SIZE / 2)
        b.Y = CENTER_Y - (INITIAL_BALL_SIZE / 2)
        b.Color = rl.White
        b.VX = INITIAL_BALL_SPEED * b.serveModifier()
        b.VY = INITIAL_BALL_SPEED * pickRandomVariant()
        b.Serve += 1
}

func (b *Ball) BounceVertically() {
        b.VY = b.VY * -1
}

func (b *Ball) BounceHorizontally() {
        b.VX = b.VX * -1
}

func (b *Ball) serveModifier() int32 {
        if b.Serve%2 == 0 {
                return 1
        }

        return -1
}

func isBallOutToLeft(b *Ball) bool {
        return b.X < LEFT_BOUNDS
}

func isBallOutToRight(b *Ball) bool {
        return b.X-b.Size > RIGHT_BOUNDS
}

func ballAtBottom(b *Ball) bool {
        return b.Y > SCREEN_HEIGHT
}

func ballAtTop(b *Ball) bool {
        return b.Y+b.Size < 0
}

func paddleAtTop(p *Paddle) bool {
        return p.Y < TOP_BOUNDS
}

func paddleAtBottom(p *Paddle) bool {
        return p.Y+p.Height > BOTTOM_BOUNDS
}

func pickRandomVariant() int32 {
        return int32(rand.Intn(2)*2 - 1)
}

func getScoreText(leftPaddle *Paddle, rightPaddle *Paddle) string {
        return fmt.Sprintf("%d   %d", leftPaddle.Score, rightPaddle.Score)
}

func movePaddleToInterceptBall(p *Paddle, b *Ball) {
        paddleCenter := p.Y + p.Height/2
        if b.Y > paddleCenter {
                p.VY = p.Speed
        } else if b.Y < paddleCenter {
                p.VY = -p.Speed
        } else {
                p.VY = 0
        }
}

func movePaddleTowardsCenter(p *Paddle) {
        paddleCenter := p.Y + p.Height/2
        if paddleCenter < CENTER_Y {
                p.VY = p.Speed
        } else if paddleCenter > CENTER_Y {
                p.VY = -p.Speed
        } else {
                p.VY = 0
        }
}

func ballIntersectsPaddle(b *Ball, p *Paddle) bool {
        return b.X < p.X+p.Width &&
                b.X+b.Size > p.X &&
                b.Y+b.Size > p.Y &&
                b.Y < p.Y+p.Height
}

func main() {
        rand.Seed(time.Now().UnixNano())
        rl.InitWindow(SCREEN_WIDTH, SCREEN_HEIGHT, "Pong")
        defer rl.CloseWindow()

        rl.SetTargetFPS(60)

        ball := Ball{}
        ball.Reset()

        leftPaddle := Paddle{
                Width:  INITIAL_PADDLE_WIDTH,
                Height: INITIAL_PADDLE_HEIGHT,
                Speed:  INITIAL_PADDLE_SPEED,
                Color:  rl.White,
                X:      SIDE_BUFFER_WIDTH,
                Y:      CENTER_Y - (INITIAL_PADDLE_HEIGHT / 2),
                Score:  0,
        }

        rightPaddle := Paddle{
                Width:  INITIAL_PADDLE_WIDTH,
                Height: INITIAL_PADDLE_HEIGHT,
                Speed:  INITIAL_PADDLE_SPEED,
                Color:  rl.White,
                X:      SCREEN_WIDTH - SIDE_BUFFER_WIDTH - INITIAL_PADDLE_WIDTH,
                Y:      CENTER_Y - (INITIAL_PADDLE_HEIGHT / 2),
                Score:  0,
        }

        for !rl.WindowShouldClose() {
                ball.Update()

                if isBallOutToLeft(&ball) {
                        rightPaddle.IncrementScore()
                        ball.Reset()
                }

                if isBallOutToRight(&ball) {
                        leftPaddle.IncrementScore()
                        ball.Reset()
                }

                if ballAtTop(&ball) || ballAtBottom(&ball) {
                        ball.BounceVertically()
                }

                leftPaddle.Update()
                rightPaddle.Update()

                if ball.VX < 0 {
                        movePaddleTowardsCenter(&rightPaddle)
                } else {
                        movePaddleToInterceptBall(&rightPaddle, &ball)
                }

                if rl.IsKeyDown(rl.KeyUp) {
                        leftPaddle.VY = -leftPaddle.Speed
                } else if rl.IsKeyDown(rl.KeyDown) {
                        leftPaddle.VY = leftPaddle.Speed
                } else {
                        leftPaddle.VY = 0
                }

                if paddleAtTop(&rightPaddle) {
                        rightPaddle.Y = 0
                }

                if paddleAtBottom(&rightPaddle) {
                        rightPaddle.Y = SCREEN_HEIGHT - rightPaddle.Height
                }

                if paddleAtTop(&leftPaddle) {
                        leftPaddle.Y = 0
                }

                if paddleAtBottom(&leftPaddle) {
                        leftPaddle.Y = SCREEN_HEIGHT - leftPaddle.Height
                }

                if ballIntersectsPaddle(&ball, &leftPaddle) ||
                        ballIntersectsPaddle(&ball, &rightPaddle) {
                        ball.BounceHorizontally()
                }

                rl.BeginDrawing()

                rl.ClearBackground(rl.Black)
                rl.DrawLine(CENTER_X, TOP_BOUNDS, CENTER_X, BOTTOM_BOUNDS, rl.LightGray)

                scoreText := getScoreText(&leftPaddle, &rightPaddle)
                textSize := rl.MeasureText(scoreText, 20)

                rl.DrawText(scoreText, CENTER_X-(textSize/2), 20, 20, rl.White)

                leftPaddle.Draw()
                rightPaddle.Draw()
                ball.Draw()

                rl.EndDrawing()
        }
}

TLDR; Storing a vector (x, y, z) as a 32-bit number uses a seventh of the memory compared to storing it as an object in this example.

The Plan

When creating games and rendering scenes on canvas I often start by creating a Vector class like the one below.

class Vector3 {
    x = 0
    y = 0
    z = 0

    constructor(x, y, z) {
        this.x = x
        this.y = y
        this.z = z
    }
}

You'll see varying implementations of this in pretty much every game engine. It's used to define where something exists with in the game world. In my JS games I'll sometimes create tens of thousands of these at a time. I've often thought about the performance impact of this, but never really came up with a good solution. The games I make are often rudimentary in nature.

So let's look at the amount of memory used by creating and modifying such objects. To record the memory usage I have written the following method. Which breaks down the results as follows:

• rss: Resident Set Size – total memory allocated for the process.
• heapTotal: Total size of the allocated heap.
• heapUsed: Actual memory used by the program.
• external: Memory used by C++ objects bound to JavaScript objects.
• arrayBuffers: Memory allocated for ArrayBuffers and SharedArrayBuffers.

function logMemoryUsage() {
    const memoryUsage = process.memoryUsage();

    console.log(`Memory Usage:
        RSS: ${memoryUsage.rss / 1024 / 1024} MB
        Heap Total: ${memoryUsage.heapTotal / 1024 / 1024} MB
        Heap Used: ${memoryUsage.heapUsed / 1024 / 1024} MB
        External: ${memoryUsage.external / 1024 / 1024} MB
        Array Buffers: ${memoryUsage.arrayBuffers / 1024 / 1024} MB
    `);
}

The below script creates 10 million Vector3 objects and updates the x and y co-ordinates of each randomly every millisecond for 2 seconds.

class Vector3 {
    x = 0
    y = 0
    z = 0

    constructor(x, y, z) {
        this.x = x
        this.y = y
        this.z = z
    }
}

function randomNumber(min, max) {
    return Math.floor(Math.random() * max) + min;
}

const maxVectors = 10_000_000
const vectors = new Array(maxVectors)

for (let i = 0; i < maxVectors; i++) {
    vectors[i] = new Vector3(
        randomNumber(0, 1000),
        randomNumber(0, 1000),
        randomNumber(0, 1000)
    )
}

let demoLengthInSeconds = 2;

const updateInterval = setInterval(() => {
    for (const v of vectors) {
        v.x += randomNumber(-2, 2)
        v.y += randomNumber(-2, 2)
    }
}, 1);

setTimeout(() => {
    logMemoryUsage()
    clearInterval(updateInterval)
}, demoLengthInSeconds * 1000)

For the purposes of this article I will run the script with node. Which gives the following results.

Memory Usage:
        RSS: 646.12109375 MB
        Heap Total: 576.828125 MB
        Heap Used: 545.6746520996094 MB
        External: 0.9788284301757812 MB
        Array Buffers: 0.009958267211914062 MB

Using the above object based implementation as baseline, let's now look at the bit-shifter variant.

The Bit Shifter Implementation

The bit-shifting implementation is going to work along the same lines. However, some boilerplate code is needed to pack and unpack our vector's values. Essentially what we are doing with the pack method is a mask and shift of x, y, and z to pack them efficiently into a single 32-bit number. The idea here being that a 32-bit number will be stored with less memory than the class used in the object based run.

Putting these concepts into practice we have the below script.

function pack(n, offset) {
    if (!offset) return (n & 0x3FF);
    return (n & 0x3FF) << offset;
}

function Vector3(x, y, z) {
    return (pack(x, 20) | pack(y, 10) | pack(z));
}

function unpack(packed, offset) {
    if (!offset) return packed & 0x3FF;
    return (packed >> offset) & 0x3FF;
}

function getX(vector3) {
    return unpack(vector3, 20);
}

function getY(vector3) {
    return unpack(vector3, 10);
}

function getZ(vector3) {
    return unpack(vector3);
}

function setX(vector3, x) {
    vector3 &= ~(0x3FF << 20);
    vector3 |= pack(x, 20);
    return vector3;
}

function setY(vector3, y) {
    vector3 &= ~(0x3FF << 10);
    vector3 |= pack(y, 10);
    return vector3;
}

function setZ(vector3, z) {
    vector3 &= ~0x3FF;
    vector3 |= pack(z);
    return vector3;
}

function randomNumber(min, max) {
    return Math.floor(Math.random() * max) + min;
}

const maxVectors = 10_000_000
const vectors = new Array(maxVectors)

for (let i = 0; i < maxVectors; i++) {
    vectors[i] = Vector3(
        randomNumber(0, 1000),
        randomNumber(0, 1000),
        randomNumber(0, 1000)
    )
}

let demoLengthInSeconds = 2;

const updateInterval = setInterval(() => {
    for (const v of vectors) {
        setX(v, getX(v) + randomNumber(-2, 2))
        setY(v, getY(v) + randomNumber(-2, 2))
    }
}, 1);

setTimeout(() => {
    logMemoryUsage()
    clearInterval(updateInterval)
}, demoLengthInSeconds * 1000)

Again this is run with node, v18.19.0. The resulting memory usage is as follows.

Memory Usage:
        RSS: 132.28515625 MB
        Heap Total: 87.578125 MB
        Heap Used: 82.33492279052734 MB
        External: 0.9788284301757812 MB
        Array Buffers: 0.009958267211914062 MB

The Results

As we can see from the above table the object based implementation used around 7 times more memory than the bit shifted example.

When it comes to creating my next game I will certainly be using this technique. While it does require extra code, the code required is still fairly minimal. Especially seeing as it uses a seventh of the memory.

The Implementation

In order to write the title of our blog post to the template image we will use the npm package PureImage. This package allows us to use the canvas api to draw to a context which we can then export as an image, without loading up a browser instance.

Gotcha 1 - Loading the font

The first gotcha when using PureImage is that there are no fonts loaded by default. So in order to draw text to our image we must first load the font like so.

import * as PImage from "pureimage";

const OUT_DIR = "./docs/images/og-images";
const FONT = PImage.registerFont(
  "C:\\Users\\brian\\AppData\\Local\\Microsoft\\Windows\\Fonts\\JetBrainsMono-Bold.ttf",
  "MyFont",
);

FONT.loadSync();

This will load the required font so that we can use it when drawing on our image template.

Gotcha 2 - Wrapping the text

The second gotcha is that because we are using the canvas api to draw text, it will not wrap unless we specifically tell it to do so. To get around this I have used the below method. This is actually a common issue when making browser games using the canvas. So I was expecting to encounter the problem.

function wrapText(ctx, text, x, y, maxWidth, lineHeight) {
  const words = text.split(" ");
  let line = "";
  let testLine, metrics, testWidth;

  for (let n = 0; n < words.length; n++) {
    testLine = line + words[n] + " ";
    metrics = ctx.measureText(testLine);
    testWidth = metrics.width;

    if (testWidth > maxWidth && n > 0) {
      ctx.fillText(line, x, y);
      line = words[n] + " ";
      y += lineHeight;
    } else {
      line = testLine;
    }
  }
  ctx.fillText(line, x, y);
}

Putting it all together

Here is the code I use to generate my OG images. It's specific to my use case, but I feel that you, a talented software engineer, will be able to extract the bits you need.

The main domain specific things here is that my Post class looks something like this.

type Post = {
    slug: string
    html: string
    excerpt: string
    data: { title: string, date: string, tags: string[] }
}

With that in mind here is the full implementation.

import * as PImage from "pureimage";
import * as fs from "fs";
import path from "node:path";

const OUT_DIR = "./docs/images/og-images";
const FONT = PImage.registerFont(
  "C:\\Users\\brian\\AppData\\Local\\Microsoft\\Windows\\Fonts\\JetBrainsMono-Bold.ttf",
  "MyFont",
);

FONT.loadSync();

export async function generateOGImage(post) {
  const pImage = PImage.make(1280, 640);
  const ctx = pImage.getContext("2d");
  const image = await PImage.decodePNGFromStream(
    fs.createReadStream("./theme/assets/images/open-graph-template.png"),
  );
  ctx.drawImage(image, 0, 0);

  const text = post.data.title;
  const maxWidth = 700;
  const lineHeight = 80;
  const x = 520;
  const y = 270;

  ctx.font = "80px MyFont";
  ctx.fillStyle = "black";
  wrapText(ctx, text, x, y, maxWidth, lineHeight);

  if (!fs.existsSync(OUT_DIR)) {
    fs.mkdirSync(OUT_DIR);
  }

  await PImage.encodePNGToStream(
    pImage,
    fs.createWriteStream(path.join(OUT_DIR, `${post.slug}.png`)),
  );
}

function wrapText(ctx, text, x, y, maxWidth, lineHeight) {
  const words = text.split(" ");
  let line = "";
  let testLine, metrics, testWidth;

  for (let n = 0; n < words.length; n++) {
    testLine = line + words[n] + " ";
    metrics = ctx.measureText(testLine);
    testWidth = metrics.width;

    if (testWidth > maxWidth && n > 0) {
      ctx.fillText(line, x, y);
      line = words[n] + " ";
      y += lineHeight;
    } else {
      line = testLine;
    }
  }
  ctx.fillText(line, x, y);
}

The Result

Now we can call generateOGImage(myPost) and it will generate a unique og image for the supplied post. The supplied post's title will be drawn on the image. Using this code on the blog post you are currently reading will generate the below image.

Unfortunately as you can see from the image, the library we used (PureImage) isn't great at rendering fonts. So the font looks a little choppy. Potentially a different library would do a better job. Alternatively we could use a tool like webdriver.io or selenium to render the template as html and save it as an image which may yield better results. For me however, the current implementation will suffice.

The Monstrosity

import { render, screen, fireEvent } from '@testing-library/react';
import { expect, test } from 'vitest';
import MyComponent from './MyComponent';

test('User Name Submit Form', () => {
  const mockApiData = { user: 'John Doe' };
  const apiFetchMock = vi.fn(() => Promise.resolve(mockApiData));

  render(<MyComponent fetchData={apiFetchMock} />);

  const header = screen.getByText(/My Dashboard/i);
  expect(header).toBeInTheDocument();

  const button = screen.getByRole('button', { name: /Submit/i });
  expect(button).toBeInTheDocument();
  expect(button).toBeDisabled();

  const input = screen.getByPlaceholderText('Enter your name');
  expect(input).toBeInTheDocument();
  expect(input.value).toBe('');

  fireEvent.change(input, { target: { value: 'John Doe' } });
  expect(input.value).toBe('John Doe');

  expect(button).not.toBeDisabled();

  fireEvent.click(button);

  const successMessage = screen.getByText(/Success!/i);
  expect(successMessage).toBeInTheDocument();
});

Now you wouldn't know it at first glance but the above test case is used to validate a form where the user can submit their name. The test technically works, but it does not communicate it's intent.

I see code like this all the time. Especially when working with UI frameworks like React, Angular, and Vue. Developers pile assertion upon assertion into one large test case. And when a new requirement comes along? they just add in yet another assertion.

Why? because the set-up is done, and bulky, and they don't want to have to rewrite or duplicate the work.

The Refactor

import { render, screen, fireEvent } from '@testing-library/react';
import { beforeEach, expect, test } from 'vitest';
import MyComponent from './MyComponent';

describe('User Name Submit Form', () => {
    let apiFetchMock;

    beforeEach(() => {
        const mockApiData = { user: 'John Doe' };
        apiFetchMock = vi.fn(() => Promise.resolve(mockApiData));

        render(<MyComponent fetchData={apiFetchMock} />);
    });

    test('renders header', () => {
        const header = screen.getByText(/My Dashboard/i);
        expect(header).toBeInTheDocument();
    });

    test('renders input field', () => {
        const input = screen.getByPlaceholderText('Enter your name');
        expect(input).toBeInTheDocument();
    });

    test('initial input field is empty', () => {
        const input = screen.getByPlaceholderText('Enter your name');
        expect(input.value).toBe('');
    });

    test('changes input value on user input', () => {
        const input = screen.getByPlaceholderText('Enter your name');
        fireEvent.change(input, { target: { value: 'John Doe' } });
        expect(input.value).toBe('John Doe');
    });

    test('renders submit button', () => {
        const button = screen.getByRole('button', { name: /Submit/i });
        expect(button).toBeInTheDocument();
    });

    test('submit button is disabled initially', () => {
        const button = screen.getByRole('button', { name: /Submit/i });
        expect(button).toBeDisabled();
    });

    test('submit button is enabled after input change', () => {
        const input = screen.getByPlaceholderText('Enter your name');
        fireEvent.change(input, { target: { value: 'John Doe' } });
        const button = screen.getByRole('button', { name: /Submit/i });
        expect(button).not.toBeDisabled();
    });
});

In the above refactor any shared test set up is broken out into a beforeEach hook and each assertion is given its own test case.

The advantage of doing this becomes immediately clear. The tests now read like a story. We know exactly what the intent of each test case is, and we only have to read a small amount of code to understand the test's logic. To accentuate my point about read ability. If we were to take the name of each test case and list it out we would have the following verse.

User Name Submit Form
    renders header
    renders input field
    initial input field is empty
    changes input value on user input
    renders submit button
    submit button is disabled initially
    submit button is enabled after input change

This reads like a list of requirements. Which is essentially what UI tests are. Compare this with the story the initial test gave us.

User Name Submit Form

Yea, not as descriptive. Who knows what that test does. Not me.

So in summary, try your best to write your test cases as if they were telling a story. Try to stick to one assertion per test, and split out any shared logic into hooks, like beforeEach and beforeAll.

So how do we implement it? Well we could use the blog resource's title. Laravel provides a Str::slug helper which takes a string and sluggifies it. Meaning My Awesome Blog Post becomes my-awesome-blog-post. This seems like a great idea. Let's update our Blog model so that when it is saved it sets a slug value based on the title.

use Illuminate\Support\Str;
use Illuminate\Database\Eloquent\Model;

class Blog extends Model
{
    protected static function boot()
    {
        parent::boot();

        static::saving(function ($model) {
            if (empty($model->slug)) {
                $model->slug = Str::slug($model->title);
            }
        });
    }
}

Now we can implement the resource's show route like so:

public function show(string $slug)
{
    return Blog::withSlug($slug)->first();
}

Awesome. What a completely foolproof implementation.

The Smart Way

Yes, so not foolproof after all. The title of the blog may change. So it's not something we want to base our urls off, because we don't want our urls to change.

So what shouldn't change about our blog? it's id. At the start of this article we showed an ugly url https://mysite.com/blog/1. The good thing about this ugly url is it shouldn't change. By visiting it you will always view the blog with id 1. The downside is it's not descriptive. So let's combine the unique identifier of the id with the slug based of the blog's title. By doing this we get a url like so, https://mysite.com/blog/1/my-awesome-content. The trick here is that the slug part of the url is just for aesthetics. It gives the user an idea of what the blog with id 1 might be about. Let's implement this in Laravel so that the url works but uses the id solely to get the blog and redirects to the updated slug if the title changes.

The Code

We can achieve the above scenario like so. Firstly, in our routes file we will specify the following show route.

Route::get('blog/{blog}/{slug?}', [BlogController::class, 'show'])->name('blog.show');

Now we'll update our Blog model to contain a helper method, that constructs the new show route.

use Illuminate\Support\Str;
use Illuminate\Database\Eloquent\Model;

class Blog extends Model
{
    public function showRoute(array $parameters = [])
    {
        return route('blog.show', [$this, Str::slug($this->title), ...$parameters]);
    }
}

Finally, in the show method of our BlogController we will add the following.

public function show(Request $request, Blog $blog)
{
    if (! Str::contains($blog->showRoute(), $request->path())) {
        return redirect($blog->showRoute($request->query()), status: 301);
    }

    return view('blog.show', compact('blog'));
}

In the above show method, Laravel's route model binding is used to find the correct blog based on the id supplied. We then add an extra check to make sure the $request->path() matches the showRoute(). If it does not we redirect to the correct showRoute() with a status of 301 Moved Permanently to let the browser know the slug has updated.

php artisan make:migration create_provinces_table

All we need from a Province is it's name.

Schema::create('provinces', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->timestamps();
});

Step 2 - County Migration

php artisan make:migration create_counties_table

As well as a name a County will hold a reference to the Province it belongs to.

Schema::create('counties', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->foreignIdFor(Province::class);
    $table->timestamps();
});

Step 3 - Province Model

php artisan make:model Province

Here we add name as a fillable property and set up the HasMany relationship with County.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class Province extends Model
{
    use HasFactory;

    protected $fillable = ['name'];

    public function counties(): HasMany
    {
        return $this->hasMany(County::class);
    }
}

Step 4 - County Model

php artisan make:model County

Here we add name and province_id as a fillable property and set up the BelongsTo relationship with Province.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class County extends Model
{
    use HasFactory;

    protected $fillable = ['name', 'province_id'];

    public function province(): BelongsTo
    {
        return $this->belongsTo(Province::class);
    }
}

Step 5 - Province Seeder

php artisan make:seeder ProvinceSeeder

The ProvinceSeeder will create a record for each of Ireland's provinces and will attach the relevant counties.

<?php

namespace Database\Seeders;

use App\Models\Province;
use Illuminate\Database\Console\Seeds\WithoutModelEvents;
use Illuminate\Database\Seeder;

class ProvinceSeeder extends Seeder
{
    /**
     * Run the database seeds.
     */
    public function run(): void
    {
        $irishCounties = [
            'Leinster' => [
                'Carlow',
                'Dublin',
                'Kildare',
                'Kilkenny',
                'Laois',
                'Longford',
                'Louth',
                'Meath',
                'Offaly',
                'Westmeath',
                'Wexford',
                'Wicklow'
            ],
            'Munster' => [
                'Clare',
                'Cork',
                'Kerry',
                'Limerick',
                'Tipperary',
                'Waterford'
            ],
            'Connacht' => [
                'Galway',
                'Leitrim',
                'Mayo',
                'Roscommon',
                'Sligo'
            ],
            'Ulster' => [
                'Antrim',
                'Armagh',
                'Cavan',
                'Derry',
                'Donegal',
                'Down',
                'Fermanagh',
                'Monaghan',
                'Tyrone'
            ]
        ];

        foreach ($irishCounties as $provinceName => $countyNames) {
            $province = Province::firstOrCreate(['name' => $provinceName]);
            foreach ($countyNames as $countyName) {
                $province->counties()->firstOrCreate(['name' => $countyName]);
            }
        }
    }
}

Step 6 - Run Seeder

php artisan db:seed --class=ProvinceSeeder

As the provinces and counties will not change, the seeder will only need run once.