Carlos Molina

Using images for every resolution

2019-07-08T00:00:00Z

A couple of days ago I needed to add an icon next to a text into a website I've been working on.

<img src="really-big-icon.png" alt="" />

It was really easy and everything looks nice.

But then, a coworker mentioned that I was delivering a really big file for this small icon. Indeed, by the styles the icon size should be 25px height, and the original icon was 150px. So I went ahead, resize the icon an updated the URL

<img src="icon-25.png" alt="" />

but this time, the icon looked plain bad on my screen. —What's wrong? I wonder myself.

High-density screens ¶

After a bit of search, I realized I was using a high-density screen. In particular, I've been using a somewhat recently MacBook Pro that has a Retina display, which provides a really crispy image all the time —but not now.

The solution I found implies using the srcset attribute with a list of higher resolution images separated by commas, and let the browser choose what is best for the current screen. In my case, it looked like this

<img
    src="icon-25.png"
    srcset="icon-25.png 1x, icon-50.png 2x"
    alt=""
    />

But I still didn't understand why should I provide an image with the double of the pixels. Pixels are pixels. Right?

"CSS px" ¶

So I kept reading and I found an interesting article ^[1] where it states, when we talk about pixels in CSS, we refer to a special unit.

When we talk about CSS px, we are not talking about screen pixels.

CSS px are defined to be small but visible, and in contrast to inches or cm, its size depends from where the user should see the screen. So a CSS 1px in a phone will be smaller than a CSS 1px in a TV because the phone is a few centimeters from our face, but the TV can be a couple of meters away. Anyway, we should be able to see them in both places.

CSS provides this unit, CSS px, that allow us to work for all these different devices without having to worry on how many screen pixels per inch my screen has. All that complexity is hidden behind CSS px. And, of course, in the other CSS units that are px based like em and rem.

In my MacBook Pro screen, the relationship between screen pixels and CSS px is 2x. In order for images to look crisp, I need to provide a resource with the double of the size.

But how do I knew the relationship between screen pixels and CSS px? Thankfully the browser exposes a property called devicePixelRatio. I opened DevTools and I typed

window.devicePixelRatio // my result was "2"

This result depends on the screen the browser is being used. If you happen to have another connected screen, this result may vary. Older desktop screens usually return 1. The newest phones are returning 3.

How many images should I provide? ¶

This depends on the users of your website. If you need to support mobile device users with high-end phones, you should provide 3x, 2x and 1x versions of your assets.

Is "srcset" supported by browsers? ¶

This is important. At the time of writing this article, support for srcset attribute is pretty good ^[2] —a good thing to notice is if we keep the src attribute we will deliver an image to older browsers too.

For this case, it makes sense to deliver the 1x URL in src.

In my example, the code for my icon looks like this

<img
    src="icon-25.png"
    srcset="icon-25.png 1x, icon-50px 2x, icon-75.png 3x"
    alt=""
    />

Conclusion ¶

Summarizing,

Know about your users and which devices they are using
Define which resolutions you should provide: 1x, 2x and/or 3x
Provides the assets they need by using srcset attribute
Deliver the experience for unsupported browsers by using src attribute
If it makes sense, remember to add an alternative text using alt attribute

That's all for now. Have a good day!

Bert Boss wrote an article for the W3C explaining the different units available in CSS, a bit of history, and which should we use depending on each situation https://www.w3.org/Style/Examples/007/units.en.html ↩︎
srcset worldwide support is over 90%. Anyway, you should understand who your users are, what devices are using, and provide what makes sense for your case https://caniuse.com/#search=srcset ↩︎

Know your tools: JavaScript Promises

2019-08-07T00:00:00Z

I am sure you have used Promises before, but if you avoid them because of their mystical behavior, this article is for you.

A Promise is an object that allows us to work on (possible) async task, and notify others when the task is done

Initially, a Promise looks just like a glorified callback. If you are familiar with NodeJS callbacks you've seen this pattern before

// callback version
asyncTask((error, result) => {
    if (error) {
        onError(error);
        return;
    }
    onSuccess(result);
});

If asyncTask returns a Promise instead, this would be the equivalent version

// Promise version
asyncTask()
.then(onSuccess)
.catch(onError);

The latest code present some advantages from the former:

It is shorter: 3 vs 7 lines of code
onSuccess and onError functions are going to be called at most once, and only one of them, guaranteed
Promises are microtasks, which means they run before functions from macrotasks like setTimeout or I/O

But one of the biggest benefits is for the Developer Experience: running multiples async tasks without the callback hell.

Avoiding callback hell ¶

What is the callback hell? Let's see an example by calling in series 4 async functions using callbacks

// callback version
getCredentials((error, credentials) => {
    if (error) return console.error('Credentials not found');

    login(credentials, (error, accessToken) => {
        if (error) return console.error('Credentials are invalid');

        getHomeInformation(accessToken, (error, homeInformation) => {
            if (error) return console.error('There was an error getting your info');

            recordAnalytics('home loaded', () => {
                // we can keep adding indentation, forever... 
                // you will probably need a bigger monitor 
                // to avoid all the horizontal scrolling 😂
            })
        })
    })
})

Slowly, we start to increase indentation by each callback call — and we are not even properly handle errors!

Let's take a look of how to handle this case with Promises

// Promises version
getCredentials()
.then(login)
.then(getHomeInformation)
.then(() => recordAnalytics('home loaded'))
.catch((error) =>{
    /* Handles each error properly */
});

The advantages are clear: keeping indentation under control. No need for buying a bigger monitor 😉

Now, if you are used to use callbacks you can have the Promise callback hell as well

// Promises + callback hell version
// 🚫 DO NOT TRY THIS AT HOME! 🚫
getCredentials()
.then((credentials) => {
    login(credentials)
    .then((accessToken) => {
        getHomeInformation(accessToken)
        .then(() => {
            recordAnalytics('home loaded')
            .then(() => {
                // for new async tasks, 
                // they will keep increasing indentation
                // you will need to buy a new monitor, again 😂
            })
        })
        .catch((error) => console.error('There was an error getting your info'));
    })
    .catch((error) => console.error('Credentials are invalid'));
})
.catch((error) => console.error('Credentials not found'))

Just by using Promises you don't avoid the callback hell: it is in your hands to use Promises as designed. Let's follow 3 simple rules that will help us improve our relationship with Promises.

Rule #1: `onSuccess` and `onError` should always return (or throw) ¶

Promise objects have two methods: .then(onSuccess) and .catch(onError), and their received callback will be called when the Promise state changes from its initial value, pending, to a fulfilled or rejected state respectively.

For both onSuccess and onError callbacks it is a good practice to always return (or to throw), to pass a value to the next chained .then/.catch. But what should we return?

a sync value (a number, an object, a string...), or
another Promise object

In case of a Promise, its result will be the value available for the next chained .then/.catch. Let's look at some examples

// always return/throw
fetch('https://api.domain.com/')
.then((response) => {
    return response.json();  // pass its result to the next `.then`
});
.then((json) => {
    if ('id' in json) {
        return json;         // pass the object to the next `.then`
    }

    // skip all following `.then` and pass error to next `.catch`
    throw new Error('id is not present');
})
.then((validatedJson) => {
    // we have an object with an `id`
});

And what happen if we don't return nor throw? Promises will not be chained at things will run in an order not guaranteed. Look at these anti-patterns

// random things you can do inside a `.then`
// 🚫 DO NOT TRY THIS AT HOME! 🚫
fetch('https://api.domain.com/')
.then((response) {
    response.json();    // 🐛 function doesn't return, order isn't guaranteed!
}); 
.then((json) => {
    console.log(json);  // 🐛 received undefined from last `.then`, not what we expected!
})
.then();                // 🐛 no function at all, resolved value will pass to next `then`
.then(aPromiseObject);  // 🐛 expected a function, received an object!

Rule #2: Prepare for errors, always `catch` ¶

This rule is simple. Eventually, things will go wrong and you have to prepare for that case.

Always place a .catch at the end of your Promise chains and make sure you handle unexpected errors. If you don't, modern browsers will print an error in the console: that is really useful for you during development but gives users no clue if they press a button and nothing happens.

Continuing with the previous example,

// always catch
fetch('https://api.domain.com/')
.then((response) => response.json());
.then((json) => {
    if ('id' in json) {
        return json;
    }
    throw new Error('id is not present');
})
.catch((error) => {
    if (error.message === 'id is not present') {
        // handle the `id` was not present error
    } else {
        // other errors, like fetch failing
    }
})

Remember: think in your users and always add at least one .catch.

Rule #3: Create Promise with the right approach ¶

Until this moment, Promise objects have appeared from existing APIs. But how can we create our own Promises?

Create a Promise from a sync value ¶

This is easy: all you have to do is call Promise.resolve(value) or Promise.reject(message) if you want a fulfilled or rejected Promise.

Create a Promise from a callback ¶

If you want to convert a callback-based function to return a Promise you will have to call the Promise constructor. Let's look an example:

// from NodeJS callback to Promise
const asyncTaskPromise = () => {
    return new Promise((resolve, reject) => {
        asyncTask((error, result) =>
            (error) ? reject(error) : resolve(result)
        );
    });
};

asyncTaskPromise()
.then(...)

Now that you know the basic rules, let's take a look to a bit more advanced patterns you will be writing.

Advanced Promise patterns ¶

You have to be mindful and create Promise only when you need them. Consider this: you have a dynamic list of Promises you want to run in parallel, and other list to be run in series each after other. How would you approach each case?

Running in parallel ¶

Use Promise.all(list) to wait for a list of promises to be ready. If every Promise succeeded you will receive a list with their corresponding values in the next .then; if any of them fails you will get the error in the next .catch.

// running in parallel ✈️️️️️️️️️️ ✈️️️️️️️️️️️️ ✈️️️️️️️️️️️️ ✈️️️️️️️️️️️️
const urls = ['/1', '/2', '/3', '/4'];
// fetch are triggered "in parallel"
const promises = urls.map(url => fetch(url));

Promise.all(promises)
.then((responses) => responses.map(res => res.json())
.then((jsons) => {
    // we have an array with the json for each call!
})
.catch((error) => {
    // the first rejected error will get here
})

Running in series ¶

What if we need to wait for the result of a previous Promise before calling the next one?

Running a .map will not work as the Promise is created in that moment. You need to create a function that will return a new Promise when needed (also called a factory).

Start the Promise series with an initial Promise.resolve(), just to have something where to chain to (call .then).

// run in series 🚂🚃🚃🚃
const series = Promise.resolve();
urls.forEach(url => {
    series.then((previousText) => fetchFactory(url, previousText));
})

series
.then((finalText) => {
    // we have the last Promise result
})
.catch((error) => {
    // the first rejected error will get here
})

function fetchFactory(url, text) {
    if (text) {
        url = url + '?text=' + text;
    }

    return fetch(url)
    .then(response => response.text());
}

Cancelling a Promise ¶

Let's say you want to poll an API, and you want to have a way to cancel it. There is no .cancel method in the Promise class, but we can achieve something similar by creating our own cancel function by racing between Promises.

Here I used Promise.race(list): it receives a list of Promises and resolves or rejects as soon as one of the Promise from its list resolves or rejects, with the value from that Promise.

In the next example, a wait Promise will race against the user cancelling the Promise. If the user never cancels, the system will keep polling until the response has a status === 'ready' and will fulfilled with the json response. If the user cancel, the Promise will reject with a message 'cancelled by user' instead.

function wait(delay) {
    return new Promise((resolve) => setTimeout(resolve, delay));
}

function cancellablePolling(url, ms) {
    let rejectCallback;
    const cancelPromise = new Promise((resolve, reject) => {
        rejectCallback = reject;
    });

    const poll = () => Promise.race([wait(ms), cancelPromise])
        .then(() => fetch(url))
        .then((response) => response.json())
        .then((json) => json.status === 'ready' ? json : poll());
    
    const cancel = () => rejectCallback('cancelled by user');
    const promise = poll();

    return {
        cancel,
        promise,
    };
}

const { promise, cancel } = cancellablePolling('/status', 5000);
promise.then(...);      // is a regular Promise
cancel();               // that will be rejected if `cancel` is called before

What's next? ¶

Once you feel comfortable with Promises, a nice addition to the JavaScript language is the await operator and the async functions. This allows to call async functions in a more standard syntax, like sync functions with the regular try/catch statements.

By using async function you declare a function to be async, and always returning a Promise. The advantage is now you can "halt" the execution of your function and wait for Promises to fulfill. Let's take a look to the first example of this article and see how it is different:

// callback version
const main = () => {
    asyncTask((error, result) => {
        if (error) {
            onError(error);
            return;
        }
        onSuccess(result);
    });
};

and now, using async function + await, assuming asyncTaskPromise is the Promise version of asyncTask:

// Promise version, async function/await
const main = async () => {
    try {
        const result = await asyncTaskPromise();
        onSuccess(result);
    }
    catch (error) {
        onError(error);
    }
};

Currently, Promises are widely supported across browsers as well as async functions, both over 90%. The recommendation is to understand who are your users and polyfill and/or transpile if it makes sense.

Hope you have learn something today. Do you have your own rules or advances uses cases for Promises? Comment them below. Have a nice week!

Small Things Matter: Returning early

2020-01-16T00:00:00Z

At the begging of my career as software developer I remember writing really long functions, full of nested conditionals.

I asked a teacher what could you do about this, and this was the first time I was introduced to the "return early" pattern, which improved the readability of my code by a great extent.

The rule ¶

Every time when you are faced with a conditional in a function:

function() {
    if (condition) {
        doA();
    } else {
        doB();
    }
}

it is possible to rewrite it in a way you return after the condition, making the else block redundant.

function() {
    if (condition) {
        doA();
        return;
    }
    // look mam, no else!
    doB();
}

This effectively allows you to:

write code with less indentation (i.e. less horizontal scrolling)
reduce cognitive load, as when you return you don't need to keep in mind what happen in the other branch of the condition

The example ¶

So this seems like a small change that may not have a lot of sense. However, when small improvements are put in place together, the change is noticeable.

Let's take a look of a function in charge of handling an HTTP request for getting scheduled classes of a gym's customer:

function getScheduledClasses(req, res) {
    if (req.user) {
        if (req.user.hasPaidMembership) {
            const classes = getScheduledClassesForUser(user);
            if (classes.length > 0) {
                res(200, { classes });
            } else {
                res(204); // No content
            }
        } else {
            res(403, { reason: 'not_paid_membership' });
        }
    } else {
        res(401); // Unauthorized
    }
}

By swapping the conditional to always return early the logic with less processing, we can rewrite this as follow:

function getScheduledClasses(req, res) {
    if (!req.user) {
        return res(401);
    }

    if (!req.user.hasPaidMembership) {
        return res(403, { reason: 'not_paid_membership' });
    }

    const classes = getScheduledClassesForUser(user);
    if (classes.length === 0) {
        return res(204); // No content
    }

    res(200, { classes });
}

This code presents less indentation, which improves readability. In the first snippet, indentation is correlated to conditionals; in the latest, conditions are presented in a procedural way.

Notice that both snippets have the same amount of lines, however the second one has way more new lines to separate the intention of each block.

What do you think of the technique? Have you used before? Do you think it may make sense applied to your codebase?

Retrying functions in JavaScript

2020-02-20T00:00:00Z

The problem statement is: you want to execute a function that may fail, and you want to retry it N times. How could you solve this?

An initial approach can be to program it for a specific number of times. Let's run functionThatMayFail and retry it 3 times

try {
    functionThatMayFail();
} catch (e0) {
    try {
        // 1st retry
        functionThatMayFail();
    } catch (e1) {
        try {
            // 2nd retry
            functionThatMayFail();
        } catch (e2) {
            try {
                // 3rd retry
                functionThatMayFail();
            } catch (e3) {
                // give up
                handleException(e3);
            }
        }
    }
}

The previous snippet has some problems:

it involves duplication, and
the number of retries can't be modified at runtime

By using recursion we could write a second approach that may address those disadvantages —however I would advocate to avoid it if possible, as this is not a recursive problem per se and the code will be harder to read and debug.

A third approach I'm more willing to follow is to make a utility function that takes care of both calling a function and its retries,

function callAndRetry(fn, maxAmountOfRetries) {
    let error;
    for (let retries = 0; retries < maxAmountOfRetries; retries++) {
        try {
            return fn();
        } catch (err) {
            error = err;
        }
    }
    throw error;
}

In our example, this should be used as

try {
    callAndRetry(functionThatMayFail, 3);
} catch (error) {
    handleException(error);
}

The presented approach solves the original statement and doesn't have the disadvantages of the previous methods. Another good thing about this pattern is that can be repurposed for asynchronous functions as well. How so?

Let's say functionThatMayFail now returns a Promise. Instead of hard-coding retries or going recursive, we can slightly modify callAndRetry to wait for the function to fulfill, as

async function callAndRetry(fn, maxAmountOfRetries) {
    let error;
    for (let retries = 0; retries < maxAmountOfRetries; retries++) {
        try {
            return await fn();
        } catch (err) {
            error = err;
        }
    }
    throw error;
}

Did you notice how we now use an async function and await for the fn function to fulfill? All the rest remains unchanged.

This new version can be used with the typical Promise chaining,

callAndRetry(functionThatMayFail, 3)
.catch(handleException);

But I believe there is even more value when it is used like a sync call:

// in the context of an async function, so we can `await`
(async () => {

    try {
        await callAndRetry(functionThatMayFail, 3);
    } catch (error) {
        handleException(error);
    }

})();

And the reasons are:

we use regular try/catch for error exception, and
this code can be used for both synchronous and asynchronous functions! Yes, functionThatMayFail may return a Promise or anything else and this would still works.

Another advantage of using a snippet to encapsulate the retry logic, instead of mixing it with the business logic, is that we can write it once and reused in your whole project as needed. You may even install one its versions available at NPM which include different retry strategies, if you need them.

I read your feedback in the comments below. Happy retrying!

Logging functions in JavaScript

2020-05-18T00:00:00Z

Logs can be very useful to debug issues in production environments.

By logging when functions are called, with which parameters, it is possible to reproduce issues and find root causes.

I will explore the logging of functions and methods within classes.

Functions ¶

Let's say we have a function we'd like to know when it is being called, its parameters, and its result.

In this example, the function is called range() that when given two numbers it returns a list with the digits between them, excluding the last:

function range(start, end) {
    return Array(end - start)
        .fill(start)
        .map((start, index) => start + index);
}

range(0, 5);    // returns [0, 1, 2, 3, 4]

An initial approach would be to edit the original function and add the logs needed:

function range(start, end) {
    console.log(`Calling range(${start}, ${end})`);

    const result = Array(end - start)
        .fill(start)
        .map((start, index) => start + index);

    console.log(`range(${start}, ${end}) returns ${result}`);

    return result;
}

range(0, 5);    // returns [0, 1, 2, 3, 4]
// logs these two lines
//    Calling range(0, 5)
//    range(0, 5) returns 0,1,2,3,4

This works, however it makes the function harder to read by mixing the proper logic of the function and the boilerplate to make the logs. This may be okay for a 3 line function, however longer ones will become even longer and harder, making them harder to read and to make changes.

An alternative solution would be to move all the logging logic outside to its function:

// let's keep the original version of `range()` without logging statements

// `logFunction()` creates a new function that handles the logging for us
function logFunction(fn, thisArg) {
    return function() {
        const concatenatedArguments = Array.from(arguments).join(', ');
        console.log(`Calling ${fn.name}(${concatenatedArguments})`);

        const result = fn.apply(thisArg, arguments);

        console.log(`${fn.name}(${concatenatedArguments}) returns ${result}`);
        return result;
    }
}

// create a version of `range()` with logs
const loggedRange = logFunction(range);

loggedRange(0, 5);    // returns [0, 1, 2, 3, 4]
// logs these two lines
//    Calling range(0, 5)
//    range(0, 5) returns 0,1,2,3,4

There are advantages to this approach:

now the business logic doesn't need to be mixed with logging, keeping our functions shorter,
you can reuse this function into other functions that need logging as well
if you don't need the logs anymore, stop calling logFunction

Sweet. What about methods?

Methods within classes ¶

Let's take the example of a LoginEmailService class, that needs logging for its 2 methods:

class LoginEmailService {
    lostPasswordFor(emailAddress, usersDB) { ... }
    verifyEmailAddressFor(user, emailAddress) { ... }
}

Following the idea of keeping logic apart from the logs, we can create a new class that extends the original one and makes the logging for us. A first attempt would be:

class LoggedLoginEmailService extends LoginEmailService {
    // option 1: placing the logs directly
    lostPasswordFor(emailAddress, usersDB) {
        console.log(`Calling lostPasswordFor(${emailAddress}, ${usersDB})`);
        const result = super.lostPasswordFor(emailAddress, usersDB);
        console.log(`lostPasswordFor(${emailAddress}, ${usersDB}) returns ${result}`);
        return result;
    }
    // option 2: using `logFunction()`
    verifyEmailAddressFor() {
        const loggedVerifyEmailAddressFor = logFunction(super.verifyEmailAddressFor);
        return loggedVerifyEmailAddressFor.apply(this, arguments);
    }
}

In the example, it works fine to place the logs directly or reusing the logFunction() utility. However, neither of those options will scale well when adding more methods to the original class as it will require manual updates within LoggedLoginEmailService class.

Wouldn't it be nice if logs are added to all methods of a class, including future modifications? This is possible using the Proxy class, used to define custom behavior for operations like reading a property and function invocation. If you want to know more about Proxy read this excellent article. Go on and read it, I'll wait here.

For the next example we will write 2 functions using Proxies:

an external one, loggingMethodsFor(), will listen for reading the properties of an object, and will invoke...
the internal logMethod() to log when a method is executed

const loggedLoginEmailService = loggingMethodsFor(new LoginEmailService());
loggedLoginEmailService.lostPasswordFor('a@b.c', 'db');
// log these two lines:
//    Calling LoginEmailService.lostPasswordFor(a@b.c,dbObject)
//    LoginEmailService.lostPasswordFor(a@b.c, db) returns <...>

function loggingMethodsFor(instance) {
    return new Proxy(instance, {
        get(target, propertyName) {
            const property = target[propertyName];

            if (isMethod(property)) {
                return logMethod(property, target.constructor.name);
            }

            return property;
        }
    })
}

function isMethod(property) {
    return typeof property === "function";
}

// equivalent of `logFunction()` but for methods
function logMethod(method, className) {
    return new Proxy(method, {
        apply(fn, thisArg, argumentsList) {
            const concatenatedArguments = Array.from(argumentsList).join(', ');
            console.log(`Calling ${className}.${fn.name}(${concatenatedArguments})`);

            const result = fn.apply(thisArg, argumentsList);

            console.log(`${className}.${fn.name}(${concatenatedArguments}) returns ${result}`);
            return result;
        }
    })
}

Do you realize how similar both logFunction() and logMethod() are? By using the fact that there are no technical differences between methods and functions, we can modify logFunction() for logging both methods and functions.

function logFunction(methodOrFn, className) {
    const isMethod = className !== undefined;

    return new Proxy(methodOrFn, {
        apply(fn, thisArg, argumentsList) {
            const concatenatedArguments = Array.from(argumentsList).join(', ');
            const fnPrefix = isMethod ? className + '.' : '';
            console.log(`Calling ${fnPrefix}${fn.name}(${concatenatedArguments})`);

            const result = fn.apply(thisArg, argumentsList);

            console.log(`${fnPrefix}${fn.name}(${concatenatedArguments}) returns ${result}`);
            return result;
        }
    })
}

What about Promises? ¶

You may be wondering what if the function or method returns a Promise. Currently, this function is printing "[object Promise]" which is not helpful at all. Let's modify the latest lines of logFunction() to change the way the output is logged.

// inside `logFunction()`
// …
const result = fn.apply(thisArg, argumentsList);

const returnsPromise = result && result.then && typeof result.then === "function";
if (returnsPromise) {
    result.then(output => console.log(`${fnToString} returns ${output}`));
} else {
    console.log(`${fnPrefix}${fn.name}(${concatenatedArguments}) returns ${result}`);
}

return result;
// …

Conclusion ¶

We explored how functions and methods can log their arguments and output without mixing log statements with the business logic.

We reach to a single function that can be used for both functions and methods, handling Promises and non-Promises outputs.

Even if our logFunction() and loggingMethodsFor() functions work they may not be ready for production. For example, depending on how complex are the arguments received by your functions you may want to deep dive into how the concatenatedArguments variable is being built, by leveraging JSON.stringify or any other technique to convert variables to a string. You may also need to avoid logging every method within an object, by having a blocked or allowed list of methods.

I will write here the latest version of the two functions in case you want to play with them. Also split some logic into smaller functions to make it easier to read.

Do you have other ideas for logging?

function loggingMethodsFor(instance) {
    return new Proxy(instance, {
        get(target, propertyName) {
            const property = target[propertyName];

            if (typeof property === "function") {
                return logFunction(property, target.constructor.name);
            }

            return property;
        }
    })
}

function logFunction(methodOrFn, className) {
    return new Proxy(methodOrFn, {
        apply(fn, thisArg, argumentsList) {
            const fnToString = functionAndArgumentsToString(argumentsList, className, fn.name);
            logFunctionStarts(fnToString);
            const result = fn.apply(thisArg, argumentsList);
            logFunctionEnds(fnToString, result);
            return result;
        }
    })
}

function functionAndArgumentsToString(argumentsList, className, functionName) {
    const concatenatedArguments = Array.from(argumentsList).join(', ');
    const functionPrefix = className ? className + '.' : '';
    return `${functionPrefix}${functionName}(${concatenatedArguments})`;
}

function logFunctionStarts(fnToString) {
    console.log(`Calling ${fnToString}`);
}

function logFunctionEnds(fnToString, result) {
    const isPromise = result && result.then && typeof result.then === "function";
    if (isPromise) {
        result.then(output => console.log(`${fnToString} returns ${output}`));
    } else {
        console.log(`${fnToString} returns ${result}`);
    }
}

Time-out functions in JavaScript

2020-06-14T00:00:00Z

I've been thinking about the problem of time-out a function, this is, try to run a function until a maximum amount of time, so it can either complete in time or be interrupted.

So I rolled up my sleeves and wrote this

function runWithTimeout(fn, timeoutInMs) {
    let timeoutId;
    const timeout = new Promise((resolve, reject) => {
        timeoutId = setTimeout(() => reject('timeout'), timeoutInMs);
    });

    const fnResult = Promise.resolve(fn());

    return Promise.race([fnResult, timeout])
        .finally(() => clearTimeout(timeoutId));
}

It is meant to be used by passing a function with no parameters, plus how many milliseconds should be allowed to run. And by wrapping it in a Promise it can support both synchronous and asynchronous values.

However, runWithTimeout() doesn't work as expected.

The rest of the article I'll explain why this function doesn't work and why it is impossible to solve this problem in JavaScript.

Consider these examples,

function uninterruptibleFaultySync() {
    while (true) {  }
}

function uninterruptibleFaultyAsync() {
    if (true) { queueMicrotask(uninterruptibleFaultyAsync); }
}

both will never be interrupted by the runWithTimeout() function. How so?

JavaScript is a single-threaded language ¶

If JavaScript is a single-threaded language, this means a single function is being executed at any given point in time. But then how do we have asynchronous functions? The answer is in the event loop.

The event loop is a list of functions that the JavaScript engine will be running, in order. If there are no functions in the event loop, the engine will be doing nothing until a new function is placed on the list.

The functions in the event loop are called tasks or macrotasks. How are tasks created? Functions run when a file is loaded, and functions placed with setTimeout(), setInterval() are the most common examples.

The interesting thing about macrotasks is, once a task starts running it will run until completion with no interruptions. That's the reason why uninterruptibleFaultySync(), which never ends, will run forever. But for other functions that do complete, they allow the event loop to execute the next function in its queue.

This is not the whole story. There are other types of functions that are considered by the event loop which have more priority than the macrotasks: they are called microtasks. Microtasks are run when the current macrotask completes, and the next macrotask will not be taken until the list of microtasks is empty. How are microtasks created? With Promises and calls to queueMicrotask().

And because microtasks functions will be run until completion with no interruptions, calling uninterruptibleFaultyAsync() will keep putting elements in the microtask list, never allowing pending macrotasks to be started. But for other microtasks that do complete, without creating infinite microtasks, they allow the event loop to keep running the macrotasks in its queue.

Is there a way to timeout a function? ¶

I am afraid it is not possible, at least for the general case. You can see this related question in Stack Overflow to read other people answers.

Now, if the function you want to timeout is not a buggy one, like the uninterruptible ones presented here, runWithTimeout() will indeed help you trigger a timeout error if necessary.

How can you avoid writing uninterruptible functions? Here I bring some ideas:

always return a Promise
ensure your Promises are catching errors
ensure, for loops and recursion, that the function will stop

Publish a TypeScript package in npm

2020-07-11T00:00:00Z

Would you like to reuse that fancy function from a previous project? I do. All the time. And what I always do is to copy and paste it, and call it a day. But… wouldn't it be nice to import the function?

The advantages are:

Don't Repeat Yourself (DRY)
Fixes fixed in one place get propagated everywhere
New features are just an npm update away

So, I'll proceed with 3 steps:

Create a TypeScript package
Write some code
Publish the module in NPM

Let's see exactly how to do this. FYI, I am following these instructions on the current NodeJS LTS, version 16.

1. Create a TypeScript package ¶

I will be creating a new directory, to then set it up as an npm package and TypeScript project. All these changes will be tracked with git.

1.1 Initialize an npm package ¶

Create a directory for your package and start a npm package in it

mkdir <your-package-name> && cd <your-package-name>
npm init -y

Ensure your new package.json file contains at least this configuration (remember to update name, description, author and license):

package.json

{
    "name": "your-package-name",
    "version": "0.1.0",
    "description": "What does this package do?",
    "files": ["dist"],
    "main": "dist/index.js",
    "types": "dist/index.d.ts",
    "scripts": {
        "prepublishOnly": "tsc",
        "test": "mocha test/**/*.spec.ts"
    },
    "author": "You <you@email.com> (https://you.com/)",
    "license": "MIT"
}

If you are curious on the meaning of these properties, checkout the excellent documentation for package.json from npm.

This is also a good time to install your dependencies. There are 2 types:

devDependencies, i.e. packages needed during development to build and test your library, and
dependencies, i.e. packages that need to be deployed alongside your library.

For this example, I will require the following devDependencies for:

transpiling TypeScript files for production and testing, typescript and ts-node;
my favorite test framework and assertion library, mocha and chai;
their types annotations (@types), for a better TypeScript experience.

npm i -D \
    typescript ts-node \
    mocha chai \
    @types/chai @types/mocha

1.2 Initialize a TypeScript project ¶

Let's initialize a TypeScript project by creating a new file, named tsconfig.json, that contains at least this configuration:

tsconfig.json

{
    "include": ["src/**/*"],
    "ts-node": {
        "transpileOnly": true   /* Skips type checking for faster unit testing */
    },
    "compilerOptions": {
        "declaration": true,    /* Generates corresponding '.d.ts' file. */
        "outDir": "./dist/",    /* Redirect output structure to the directory. */
    }
}

1.3 Configure mocha ¶

Before running the tests, let's configure mocha so it understands TypeScript files. Create a new .mocharc.jsonc file with this configuration:

.mocharc.jsonc

{
    "require": "ts-node/register",
    "extension": "ts"
}

Without this file, trying to run the unit tests will fail with the following message:

SyntaxError: Cannot use import statement outside a module

1.4 Track changes with git ¶

First, initialize a git repository in the root of the package:

git init

Then, create a new file named .gitignore to instruct git to ignore two directories, node_modules and dist for the dependencies and compiled files, respectively.

.gitignore

node_modules
dist

Make sure to keep track of these changes with git: git add . && git commit -m "New npm package".

2. Write some code ¶

At this point, we can start writing code and its tests. About time!

Create a new file, src/index.ts, and write some code. For example, export a function that sums two numbers:

src/index.ts

export function sum(a: number, b: number): number {
    return a + b;
}

For the tests, you can create a spec under the test directory, one .spec.ts file for each source code file.

test/index.spec.ts

import { expect } from 'chai';
import { sum } from '../src/index';

describe('sum', () => {
    it('should return the sum of 2 positive numbers', () => {
        expect(sum(1, 2)).to.equal(3);
    });
});

Now you are ready to run npm test and see your test passing. If everything went well make a new commit: git add . && git commit -m "Initial code, unit test passing".

3. Publish a module in NPM ¶

You will need to log in with your npm account (and create one if you don't have it yet), ensure everything looks good, and finally publishing your package.

If you do not already have an npm account, go to https://www.npmjs.com/signup and fill the form.

In a terminal run npm login and fill with your username and password when requested.

3.2 Update your package name (optional, recommended) ¶

Every time a package is published in npm it goes directly into the global scope. And because every package needs to have a unique name, it can be challenging to find an available name for your new package.

To avoid this problem I recommend publishing your package under your username scope (or an org scope if you belong to one). To do this, go back to your package.json and change the name property,

package.json

{
-    "name": "<your-package-name>",
+    "name": "@<your-username>/<your-package-name>",
    // ...
}

3.3 Ensure you have correctly emitted types ¶

Now that you have your code written and tested, it is time to publish it. To see if everything is in order,

run npm link to make your unpublished package available locally
in another directory, run npm link @<your-username>/<your-package-name>
create an index.ts file, and try to import the functions from your package

If everything went well, you will see the editor consuming the types you had specified 😁

3.4 Add a tag ¶

People usually add tags to their git commits associated with a new version of a package so it can be easily referenced later: git tag v0.1.0

3.5 Publish it! ¶

Run npm publish --access public. This access parameter indicates you will publish your package for everyone with access to npm.

If no errors were published in the terminal, you should be able to see your package listed under https://www.npmjs.com/package/@<your-username>/<your-package-name>.

For example, I followed the instructions from this post to publish a logging library mentioned in a previous post and this is the URL of the package: https://www.npmjs.com/package/@cmolina/log

3.6 Publish an update ¶

After publishing the first version of the package you may be wondering how to send an update. Well, you have to commit your changes, ensure every test is passing, compiling, bumping the version, adding a tag… it is pretty easy to forget a step.

Good news we have np, an npm package for publishing to npm.

After committing your changes, run npx np and answer the questions. The first time I run it I had to update npm and made me have a remote repository as well (I chose GitHub).

Conclusion ¶

You learned how to create a TypeScript library from scratch, how to manually publishing a new npm package, and to keep it up to date.

Happy publishing!

Create a dark theme

2020-09-30T00:00:00Z

I've been interested in implementing a dark theme for my blog. I like websites that respect the user preference of using dark themes and was feeling sorry that my blog was always so bright.

Even when I use the DarkReader extension for those pages that don't include a dark mode, which makes a marvelous job by the way— some edge cases made my blog look odd and hard to read. That's why I decided to document the steps to share my learning.

I implemented a dark mode in 3 steps,

Define my colors in a single place
Redefine my colors for the dark theme
Test for accessibility

1. Define my colors in a single place ¶

In the beginning, the colors were defined and redefined all over my CSS. Before implementing my dark theme, I collected the colors used in my light theme, defined new CSS variables for the :root element, and used these variables instead of hardcoded values.

The reason for doing this change is that is going to make it easier later to identify which colors belong to the default/light theme, and which overrides are necessary for the dark theme.

At the beginning of your stylesheet, you can write something like this

/* default colors are defined here */
:root {
    --background: #fff;
    --color: #000;
}

/* and then can be referenced using `var(--custom-color)` */
body {
    background: var(--background);
    color: var(--color);
}

2. Redefine my colors for the dark theme ¶

Now that all the colors are defined in a single place, add a media query for prefers-color-scheme: dark where you redefine the variables as needed.

/* default colors are defined here */
:root {
    --background: #fff;
    --color: #000;
}

/* dark theme overrides */
@media (prefers-color-scheme: dark) {
    :root {
        --background: #333;
        --color: #fff;
    }
}

To see the changes in your browser you need to enable dark mode for the device you are working on.

As I don't have formal studies in design it was hard for me to choose all the colors from scratch; I ended up using the suggested colors given by DarkReader and then manually tweak them until I was happy with the results.

There are excellent guides on how to choose the colors for a dark theme. I recommend reading the Material Design guide and Apple's Dark mode guide. I learned from them that it was wise to set the background with gray instead of black, as very high contrast colors can negatively affect the readability; and that you can use increasingly lighter colors for the background to reflect elevated layers. Check them out.

3. Test for accessibility ¶

Once you are happy with the light and dark colors you have chosen, now it is time to ensure they have enough contrast so all users can read your website.

The main suggestion here is to ensure the contrast between background and foreground color is visible enough, for both the light and the dark theme. The WCAG 2.0 level AA recommends a contrast of 4.5 : 1. I personally like to check the contrast by using the WebAIM's contrast checker tool for individual colors or to scan the whole website with the Accessibility Inspector included in Firefox DevTools.

Focus indicator ¶

On my first dark theme implementation, I totally forgot about ensuring the focus indicators were actually visible. The one that is provided by browsers is not always visible enough (I am talking about you, Firefox), and it could be hard to detect depending on the theme of your website. You can define your custom focus indicator like this:

:focus {
    outline: thick solid var(--primary-color);  /* ensure the color works for both themes */
    outline-offset: .3rem;
}

Conclusion ¶

In this article I presented a technique to keep your website theme to respect the customer preference of either light or dark theme, being careful of choosing colors that all people can read. Did you notice the new dark theme from the blog? Are there any other things you should be thinking of?

Migrating away from hey.com

2021-05-04T00:00:00Z

I really like the Hey email client. I am a customer since July 2020 and after onboarding, I've experienced less time managing my emails and more time doing things I love.

I will not expand in this post why I can't trust Basecamp anymore (the company that builds Hey) as it has already been said multiple times by so many people.

What I will do is to explain how I stopped using Hey, and what is my new email configuration (which is mimicking Hey to a certain extent). Let's get started.

High level overview ¶

I chose Protonmail as my new email provider, together with a custom domain, a single rule filter for replicating the screening, 3 custom folders, and the built-in contacts and mark as spam features.

The new Inbox looks like this:

Did you notice the "Paper trail", "Screening" and "The Feed" folders?

Still interested? Let's jump to the details.

I was looking for an email provider which:

I could mimic Hey screening
I could believe in their mission and I wouldn't have to run away from
I could keep my email in the case of the provider becoming evil

Protonmail is an open source product, with a focus on privacy and to protect civil liberties online. It is free to use, but this guide assumes you buy the Plus plan, starting at €48.00 a year, as I will be using paid features.

First I had to create a protonmail.com account. The process is super straightforward, and you can create a free account and upgrade later when needed.

After I had my new account created, I proceeded to get a cool email alias with a custom domain.

2. Get an email with a custom domain (optional) ¶

One of the nice things of Hey was the possibility of choosing a short email address.

Since Protonmail supports custom domains for paid accounts —and I already have a domain for my blog— I decided to replicate this feature; I replaced my legacy email cmolina@hey.com with the new hi@cmolina.dev. One less character to write!

The instructions to configure a custom domain are here. You will need to set some DNS settings, which sounds hard but the ProtonMail documentation has instructions for the most common domain registrars.

Notice that the changes in DNS may take hours or even days to complete; meanwhile I recommend you to keep going with this guide.

2. Replicating the Screening ¶

Let's configure Protonmail to emulate the Screening feature by following 3 steps.

Go to Folder/Labels link and create 3 folders: "Screening", "Paper trail", and "The Feed".

I decided to on purpose not to create an "Imbox" folder and use the existing "Inbox" (finally I am not reading that typo anymore!).
Go to Contacts and create 3 contact groups: "InboxGroup", "TheFeedGroup", and "PaperTrailGroup".

The idea here is every time you get an email from an unknown sender, you can accept new messages by adding the sender to one of those contact groups; and to screen off you use the "Mark as spam" feature.

Go to Settings > Filters and click "Add Sieve filter".

Create a new Sieve filter named "Mimic the Screening" with the following script:

require ["include", "environment", "variables", "relational", "comparator-i;ascii-numeric", "spamtest", "extlists", "fileinto", "imap4flags"];

# Generated: Do not run this script on spam messages
if allof (environment :matches "vnd.proton.spam-threshold" "*", spamtest :value "ge" :comparator "i;ascii-numeric" "${1}") {
    return;
}

# Ignore messages sent by myself: they will be stored in `Sent`
if header :list "from" ":addrbook:myself" {
    return;
}

# Mimicking the Screening
if header :list "from" ":addrbook:personal?label=InboxGroup" {
    fileinto "Inbox";
}
elsif header :list "from" ":addrbook:personal?label=TheFeedGroup" {
    addflag "\\Seen";
    fileinto "The feed";
}
elsif header :list "from" ":addrbook:personal?label=PaperTrailGroup" {
    fileinto "Paper trail";
}
else {
    fileinto "Screening";
}

The code is pretty much self-explanatory: known senders will be moved to the corresponding folder, otherwise it will go to Screening. I also decided to mark every email under "The Feed" as seen. To learn more about the syntax you can read the Sieve filter guide.

After this, the only pending step is to instruct Hey to forward the emails to the new email.

3. Enabling email forwarding in Hey ¶

Eventually, I will have to change every account linked to my previous @hey.com account. But for now, I need to instruct Hey to forward every new message to my new address.

In app.hey.com, go to "Me" > "Account Setup" > "Forwarding & SMTP Setup" > "Forward email out of HEY".

Write your new email address. You will receive an email in Protonmail to confirm the operation.

4. Importing the emails from Hey ¶

You probably want to be able to access all your emails from an unique account. The good news is that you can bring all your emails from Hey —and the search engine is way better!

To export your emails, in app.hey.com, go to "Me" > "Account Setup" > "Export your data" > "Export my emails". In a few minutes you will receive an email with a MBOX file.

To import the MBOX file to Protonmail, install their Import Export app. You can read the detailed instructions here.

5. Canceling your Hey subscription ¶

Canceling a Hey account allows you to stop paying the service, but you still can read emails, export emails and contacts, and update the forwarding configuration (at least until Basecamp discontinues the service).

In app.hey.com, go to "Me" > "Account Setup" > "Billing & Invoices" in order to cancel your subscription.

Wrapping up ¶

I've been using this configuration for a month now and I can truly say I am having a great time with my emails.

An unexpected benefit of going to Protonmail is the ability to archive emails: I don't need to keep my Inbox full of already read emails, but only of unread and reply later messages.

The good ¶

Is it possible to enjoy your email without supporting Basecamp? Yes. The most valuable feature of Hey, the Screening, works as expected
Is it possible to keep your new email address across providers? Yes, I still receive emails from my legacy Hey account, and my new email address won't change if I ever decide to migrate from Protonmail
Will be less expensive? Yes, as of today it will be at least $41 cheaper, a hefty 40% discount

The bad ¶

As of today, classifying new emails into Inbox/The Feed/Paper trail is somewhat cumbersome. It involves 4 manual steps:
1. create a contact,
2. add the contact to one of the contact groups,
3. go back to the email, and
4. manually move the message to its corresponding folder.

The ugly ¶

Apparently there is a limit of 100 contacts that a single contact group can handle

I imagine a workaround where I can keep creating contact groups while I update the Sieve filter, but I'd prefer not to. Anyway, I am not close to reach the limit yet.

I commented on an existing issue to understand what are my options but the developers haven't answered yet. I will keep this post up-to-date.

Configuring git for the first time

2021-06-14T00:00:00Z

Hey, do you have a new development laptop and do you need to configure git? I always need to run the same commands, but I do it so rarely that I always forget how to do it properly.

This article is a guide for my Future Me. You are welcome, Future Carlos!

Set my name and email ¶

This is the minimum you need to get started with git. Go ahead and execute it with your information:

git config --global user.name "My Name"
git config --global user.email "me@example.com"

Enable autocorrect typos ¶

Did you know git can automatically correct your misspelled commands for you? By enabling this feature with:

git config --global help.autocorrect 10 # time to delay, unit is 1/10th of a second

you will receive a suggestion with a correction that will automatically execute after 1 second, unless you hit Ctrl + C —for example running git sttus will print:

WARNING: You called a Git command named 'sttus', which does not exist.
Continuing in 1.0 seconds, assuming that you meant 'status'.

Use nano as the default editor ¶

Someday I will learn how to use vim (without rebooting my laptop because I didn't know how to close it). In the meantime I will use nano instead:

git config --global core.editor "nano"

Use Visual Studio Code for squashing ¶

So there is one disadvantage of using nano as the default editor: when running git rebase -i it can be pretty time-consuming to squash several commits, as I don't know how to replace multiple words yet.

I prefer to use vscode with the GitLens extension; it can be setup with:

git config --global sequence.editor "code --wait"

which will open a convenient rebase interactive tab when needed, like the one of the next screenshot:

Change your default branch name ¶

The current version of git shows a warning when initializing a new repository with git init, as they are moving away from master. Since I prefer to use main, I made the message disappear by running the following command:

git config --global init.defaultBranch main

Choose a default strategy for `git pull` ¶

I am lazy, and when I want to ensure I have the latest changes from a remote repo I just type git pull —instead of git pull --ff-only command which will bring any commits from origin with a fast-forward. However, this is what git outputs by default:

Pulling without specifying how to reconcile divergent branches is
discouraged. You can squelch this message by running one of the following
commands sometime before your next pull:

git config pull.rebase false  # merge (the default strategy)
git config pull.rebase true   # rebase
git config pull.ff only       # fast-forward only

I use the third option, but feel free to pick your poison.

git config --global pull.ff only

Use a global .gitignore file (optional) ¶

I only had to use this feature once: when I was using a particular tool that generates files to be ignored, but because I was the only coworker using the tool I was not supposed to modify the committed .gitignore file 😒🤷🏽‍♂️🤨.

I am sure this technique may be useful in other situations as well; to use it, run:

git config --global core.excludesfile "~/.gitignore"

And create ~/.gitignore with your favorite editor.

Conclusion ¶

Hopefully you learned or rediscovered some cool things you can do with git 😄

My terminal configuration

2021-11-25T00:00:00Z

Software developers can spend long periods of time in the terminal: installing dependencies, reading logs, exploring the file system and running build commands to name a few examples. For this reason, I wrote a compilation of programs that have made my life easier, by either

making easier to install the packages for my development needs,
providing a custom experience (like custom fonts and syntax highlight), or
typing less (with autocomplete and informative prompt).

Most of these programs are one of the first things I install when using a new laptop, like the terminal emulator and package manager; others, like the ruby version manager, stay pending installation a bit longer until I actually require them.

Currently, I am using a MacBook Air 2020 (M1 chip); however, most of these programs are either cross-platform, or they have an alternative in different OSs. Without further ado, here is my terminal configuration!

Terminal emulator: iTerm2 ¶

I love its minimal UI, but at the same time it has lots of features and is very customizable. Particularly, I like to

split the screen (Cmd + D),
open new tabs (Cmd + T), and
set a profile for "Hotkey Window" (or always-available Guake-style terminal).

Get it from https://iterm2.com/.

Package manager: Homebrew ¶

Package managers are so handy for code development. While I enjoyed them while using Linux, for some reason Mac and Windows don't come with one by default. And Homebrew is not perfect —it breaks from time to time, but it has a big community, and you can probably find a fix for your problem in Stack Overflow.

I've been curious on trying pkgsrc in the past, but I keep deprioritizing it, as it is not as popular as Homebrew and I don't feel like living in the edge so much these days.

I list Homebrew at the top of my list since it is the tool I use for installing the majority of the rest of the programs presented in this blog post.

Get it from https://brew.sh/.

Prompt: Starship ¶

While Starship is supposed to be fully customizable and cross-OS compatible, what I really love about this prompt is that it just works out of the box, particularly git and nodejs integrations. And it is fast —nobody likes to wait for the new terminal to be ready.

I use it with FiraCode Nerd Font, which provide icons for different languages, and it looks awesome. I use the bracketed segment preset as well.

Get it from Homebrew, and read the docs at https://starship.rs/.

Replacements ¶

Some tools within a UNIX-like system are ancient, and for compatibility or codebase reasons they can't improve and keep themselves modern. However, new programs do not have these limitations. Here I list a couple of alternatives to classic terminal programs.

bat: a `cat` alternative ¶

What if you could read files with syntax highlight directly from your terminal? I've always used cat to read files, however it is hard to read code with no colors and no scroll. (Maybe vim users can already do this, but I still have no idea how to exit that program 🥲).

This is why I like bat so much. However, since I am already used to type cat, I made an alias to use bat instead:

~/.zshrc

alias cat="bat"

Get it from Homebrew, and read the docs at https://github.com/sharkdp/bat.

exa: a `ls` alternative ¶

exa is way easier to read for me than ls. Period. I also added an alias to replace ls.

Get it from Homebrew, and read the docs at https://github.com/ogham/exa.

Other utilities ¶

I just I don't know how to classify these, so I will just put them together until a better order comes up.

Fuzzy finder: fzf ¶

This utility is kind of hard to explain until you actually use it; in essence, it allows me to stop hitting the "up" key for navigating my command history. I use it for autocompleting based on

my previous commands, by pressing Ctrl + R
existing files and directories, by typing the/path/I/remember/ + ** + TAB

Get it from Homebrew, and read the docs at https://github.com/junegunn/fzf.

hyperfine: running benchmarks ¶

In my spare time (i.e. when I am waiting for npm install && npm run build to complete) I'd like to understand if I can make scripts to run faster: hyperfine helps me measure how fast a proposed change compares to the initial state.

(Fun fact: I once reduced the build time of a big NodeJS library in 30%, thanks hyperfine!).

Get it from Homebrew, and read the docs at https://github.com/sharkdp/hyperfine.

Version managers ¶

If you work with multiple projects, and they all use the same dependency but with different versions, version manager can become quite handy. The ones that I've used in the past are:

rvm: ruby version manager https://rvm.io/rvm/install#installation
nvm: node version manager https://github.com/nvm-sh/nvm#installing-and-updating

Wrapping up ¶

These are the tools that I keep installing over and over in my Mac laptops. Do you have your favorites ones as well?

Optimizing GitHub Actions: 7 Strategies for Faster and Cost-Effective CI pipelines

2023-12-16T00:00:00Z

From time to time, I need to change my focus from working on new features to ensure build times (and build costs) are reasonable.

In this guide I will share some ideas on how I've reduced the time and money spent in GitHub Actions, a CI managed service; these ideas may translate to other continuous integration services as well.

Measure before and after each change ¶

This step is crucial when trying to optimize a process, we need to determine whether a change was beneficial, had no discernable impact, or had a performance hit compared to the status quo.

Since GitHub Action runners are virtual machines over shared hosts, their performance change based on how busy the real machines are. For example I've seen identical jobs to have different complete times that vary up to 10%, depending on the time and day of the week when these jobs are run.

To rule out differences in performance due to these external factors:

I compare the times between a recently published PR, with the times against a job without these changes that run immediately after
I aim to keep only those PRs that make the build to run at least 10% faster

Now, let's explore the ideas that'd worked for my team in the past.

1. Drop unnecessary work ¶

This may seem obvious but sometimes it is easy to forget: the faster way to complete a job is to remove all its unnecessary steps.

Take a look at a runner logs and see if there is any step that shouldn't be there. Things to look for:

deprecated services you are not using anymore
duplicated commands. Sometimes a first CLI command will call a second CLI command, so you can drop one of those calls from the *.yml definition
unnecessary commands. I recently found out that in one of our apps I was building the app before running its unit tests, an unnecessary step which was only making the build step slower.

2. Enable concurrency's cancel-in-progress ¶

What is the point of running a job once a new commit is in the HEAD of a branch, and a new job has just started? We are going to be spending money in a job that will be ignored, as it was superseded by the latest job.

You can use the concurrency property so every time anyone in your team pushes a new commit to a branch, any existing running jobs related to that branch will be cancelled. For example:

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: ${{ github.ref_name != 'main' }}

The only exception here is for new commits added to the main branch, as I'd like to detect whether merging a PR breaks the build as soon as it happens.

3. Cache dependencies ¶

Your program will probably use dependencies, and installing them each time from an empty cache can be time-consuming. And when you use CI, you will be installing the same dependencies over and over again; so there is an opportunity to keep a copy of your dependencies across jobs to reduce build times.

For this reason popular languages actions provide some caching feature, to save and reuse these dependencies across runs.

Here there are a couple of examples of actions with caching enabled, for both ruby gems and npm packages:

- uses: ruby/setup-ruby@v1
  with:
    bundler-cache: true

- uses: actions/setup-node@v3
  with:
    node-version-file: package.json
    cache: yarn

Sometimes there are dependencies which are not automatically stored by these actions. For that case you can leverage the actions/cache action, and manually cache and restore these dependencies yourself.

Here there is an example for caching Playwright's dependencies and browsers:

# caching Playwright's dependencies and browsers; notice it has 3 steps
- name: Save the installed Playwright version
  run: echo "PLAYWRIGHT_VERSION=$(yarn list --pattern="@playwright/test" --json | jq '.data.trees[0].name' -r | sed 's/.*@//')" >> $GITHUB_ENV

- name: Restore Playwright dependencies and browsers from the cache
  uses: actions/cache@v3
  id: playwright-cache
  with:
    path: ~/.cache/ms-playwright
    key: ${{ runner.os }}-playwright-${{ env.PLAYWRIGHT_VERSION }}
    restore-keys: ${{ runner.os }}-playwright-

- name: Download Playwright dependencies and browsers
  if: steps.playwright-cache.outputs.cache-hit != 'true'
  run: yarn playwright install --with-deps chromium

4. Enable parallelism in your framework ¶

The runners provided by GitHub Actions can run multiple threads; however there are times the frameworks may fail to detect how much parallelization can be done. The larger your project, the more tests you will have, and the more your project can take advantage of splitting the work across all the threads your runner supports, reducing your build times.

In the following example, I am setting the PARALLEL_WORKERS env var so minitest knows how many workers it can actually use:

- name: Set parallel workers env variable
  run: echo "PARALLEL_WORKERS=$(nproc)" >> $GITHUB_ENV

- name: Run Ruby and Rails tests
  env:
    RAILS_ENV: test
  run: bundle exec rails test

5. Optimize Dependabot ¶

Here I've found 2 tricks that have saved me money:

Enable groups, to reduce the number of open PRs for each day

For example, we can have a single PR that bumps the versions of all bundler-related dependencies at the same time, except the rubocop ones, which will be updated in a separate PR:

.github/dependabot.yml

- package-ecosystem: "bundler"
  groups:
    development-dependencies:
      dependency-type: "development"
      exclude-patterns:
        - "rubocop*"
    rubocop:
      patterns:
        - "rubocop*"

Beware: the grouping will have a bigger impact when dependencies are updated once a week; for daily updates groups doesn't make a lot of sense.

Use commit-message for customizing the commit message and its PR title, so I can skip other services

I configured my dependabot PRs to be automatically merged once all jobs are passing. And since there is no human involved in these PRs, I want to avoid triggering deployments for manually testing the changes.

For example, I can avoid running Render.com's preview environments, which can become particularly expensive, by adding a particular prefix to the PR title:

.github/dependabot.yml

- package-ecosystem: "bundler"
  commit-message:
    prefix: "[skip render]"

And with less preview enviroments, the smaller the Render.com's bill 😁

6. Use larger runners ¶

The default runners provided by GitHub are potatoes connected to the internet. If you want to use a modern browser to run system tests you may run out of memory, the tests may run very slowly, or probably both.

The easiest solution is to have faster builds is to opt-in to better runners. You can use the larger runners provided by GitHub, which you first need to enable for your org, and then set the run-on property, for example:

jobs:
  system-tests:
    runs-on: ubuntu-latest-16-cores

However, using these hosts can become pretty expensive, very quickly. I saw my GitHub bill to grow up to 3 times after a few months using larger runners, so be careful when using this setting and keep track of your monthly charges.

Instead, I would recommend to use larger runners from a third party provider. There are services like Warp Build and GitRunners that allows you to enjoy faster machines at a fraction of the cost when compared to GitHub.

Using larger runners will make your jobs be faster and more expensive. In this case I think it is cheaper than having developers waiting for their changes to go live.

7. Split the work with multiple runners ¶

Let's say you have a N system tests. If you run them all in a single runner, and the last test fails, you will still need to wait for all N tests to complete.

What if we split the load, let's say between 5 hosts?

So now, if the last test fails, we will know it in about 1/5 of the original time, making it 80% faster!

We can leverage the strategy and matrix properties, for example we can split the following Playwright tests by setting the shard option:

system-tests:
  name: System tests
  strategy:
    fail-fast: false
    matrix:
      shard: [1, 2, 3, 4, 5]
  env:
    SHARD: ${{ matrix.shard }}/${{ strategy.job-total }} # for example: 1/5, 2/2, ..., 5/5
  steps:
    # other setup steps...

    - name: Run Playwright system tests
      run: yarn playwright test --project=chromium --shard=$SHARD

Unfortunately, as of today, rails doesn't support sharding in their tests. I wrote a small rake task that is equivalent to running rails' system tests in shards, like Playwright.

If you want some extra savings, you can toggle fail-fast: true so you cancel other jobs from the matrix at the first error; however I prefer to keep it off so I know all the system tests that needs to be fixed.

Conclusion ¶

Well, here are 7 ideas on how to have faster and cheaper CI with GitHub Actions. I will probably find some new ideas in the future, but for now I am enjoying the faster integrations.

Rock Your Code with AC/DC: Acceptance Criteria Designed Coding

2024-05-22T00:00:00Z

Welcome to the world of AC/DC, where coding meets rock 'n' roll! No, we’re not talking about shredding guitars or belting out high notes. This AC/DC stands for Acceptance Criteria Designed Coding, a new technique I’ve been crafting for the past few years. It’s a nod to the legendary band, and a cheeky jab at TDD fans. Buckle up and get ready to rock your coding workflow!

The Power Chords of AC/DC ¶

Let’s break down the process and get you rocking.

Grab an Acceptance Criteria (AC) from a Story
List all its cases. Create a playlist of scenarios. Make sure you keep this list up-to-date as you learn and discover new edge cases
Pick a case, and write it in code following these rules:
- Design the ideal signature. Make sure to use the same language of the AC
- Asserting behavior, never implementation: We’re here to rock the stage, not worry about the backstage setup
- Use Arrange, Act, Assert: Your three-step dance routine.
Make sure the new AC’s case is failing: If it’s not failing, it’s not rocking hard enough.
Write the minimum amount of code to make the AC’s case pass: Think minimalistic, like a raw guitar riff.
Optional refactor: Clean up your code and make it smooth.
Confirm all AC's cases are passing: Like hitting are the right notes!
If there are still cases unimplement, go back to step 3. There is more rocking to do
Next AC, Please: Once you’re done, grab the next AC from the story and start over. It is time for a new hit

Why Use AC/DC? ¶

Following AC/DC ensures you address all the ACs from a story. If they ever break, you’ll be notified immediately – no more surprise bugs halfway through your concert. This technique has allowed me to move fast in projects while maintaining high code quality.

Let's Rock an Example ¶

Let’s say we’re grabbing a story for calculating the total price of items in a cart, including tax, in a JavaScript app. Here’s how we’d rock this with AC/DC.

Step-by-Step ¶

Grab an AC from a story: Calculate the total price of items in a cart, including a fixed tax rate of 10%.
List all its cases:
- An empty cart should return 0
- A cart with one item of price 100 should return 110 (including tax)
- A cart with multiple items should sum up all prices and add tax
Pick a case: Let’s start with an empty cart.

calculateTotalPrice.test.js

import { describe, it, expect } from 'vitest';
import { calculateTotalPrice } from './calculateTotalPrice';

it('should return 0 for an empty cart', () => {
  // Arrange
  const cart = [];

  // Act
  const result = calculateTotalPrice(cart);

  // Assert
  expect(result).toBe(0);
});

Make sure the new AC’s case is failing: Run the test to see it fail.

vitest run

Write the minimum amount of code to make the AC’s case pass:

calculateTotalPrice.test.js

export function calculateTotalPrice(cart) {
  return 0; // minimum code to pass the test
}

Optionally refactor: No need yet.
Confirm all AC’s cases are passing: Run the test again.

vitest run

If there are still cases unimplemented, go back to step 3: Next case!

calculateTotalPrice.test.js

it('should return 110 for a cart with one item priced at 100', () => {
  const cart = [{ price: 100 }];

  const result = calculateTotalPrice(cart);

  expect(result).toBe(110);
});

Run the test to see it fail, then write the minimal code:

calculateTotalPrice.js

export function calculateTotalPrice(cart) {
  if (cart.length === 0) return 0;
  return cart[0].price * 1.1; // minimal code to pass the second test
}

Once you write the last case, you may end up with a function like this:

calculateTotalPrice.js

export function calculateTotalPrice(cart) {
  if (cart.length === 0) return 0;
  const total = cart.reduce((sum, item) => sum + item.price, 0);
  return total * 1.1;
}

Optional refactor. We can replace the 1.1 magic number into a well-named constant:

calculateTotalPrice.js

const TAX_RATE = 1.1;

export function calculateTotalPrice(cart) {
  if (cart.length === 0) return 0;
  const total = cart.reduce((sum, item) => sum + item.price, 0);
  return total * TAX_RATE;
}

Confirm all tests are passing, and move on to the next AC with step 9.

Why AC/DC Rocks ¶

Following AC/DC ensures you cover all the acceptance criteria in a user story, providing a safety net that alerts you if any criteria ever break. This technique lets you move fast in projects while maintaining stellar code quality. It’s like having your own coding concert where every function hits the perfect note.

So, turn up the volume on your coding skills and give AC/DC a spin. You might just find yourself rocking out more efficient, reliable, and downright awesome code. Rock on! 🎸

Carlos Molina

Using images for every resolution

High-density screens ¶

"CSS px" ¶

How many images should I provide? ¶

Is "srcset" supported by browsers? ¶

Conclusion ¶

Know your tools: JavaScript Promises

Avoiding callback hell ¶

Rule #1: onSuccess and onError should always return (or throw) ¶

Rule #2: Prepare for errors, always catch ¶

Rule #3: Create Promise with the right approach ¶

Create a Promise from a sync value ¶

Create a Promise from a callback ¶

Advanced Promise patterns ¶

Running in parallel ¶

Running in series ¶

Cancelling a Promise ¶

What's next? ¶

Small Things Matter: Returning early

The rule ¶

The example ¶

Retrying functions in JavaScript

Logging functions in JavaScript

Functions ¶

Methods within classes ¶

What about Promises? ¶

Conclusion ¶

Time-out functions in JavaScript

JavaScript is a single-threaded language ¶

Is there a way to timeout a function? ¶

Publish a TypeScript package in npm

1. Create a TypeScript package ¶

1.1 Initialize an npm package ¶

1.2 Initialize a TypeScript project ¶

1.3 Configure mocha ¶

1.4 Track changes with git ¶

2. Write some code ¶

3. Publish a module in NPM ¶

3.1 Login to npm CLI ¶

3.2 Update your package name (optional, recommended) ¶

3.3 Ensure you have correctly emitted types ¶

3.4 Add a tag ¶

3.5 Publish it! ¶

3.6 Publish an update ¶

Conclusion ¶

Create a dark theme

1. Define my colors in a single place ¶

2. Redefine my colors for the dark theme ¶

3. Test for accessibility ¶

Focus indicator ¶

Conclusion ¶

Migrating away from hey.com

High level overview ¶

1. Sign up for a Protonmail account ¶

2. Get an email with a custom domain (optional) ¶

2. Replicating the Screening ¶

3. Enabling email forwarding in Hey ¶

4. Importing the emails from Hey ¶

5. Canceling your Hey subscription ¶

Wrapping up ¶

The good ¶

The bad ¶

The ugly ¶

Configuring git for the first time

Set my name and email ¶

Enable autocorrect typos ¶

Use nano as the default editor ¶

Use Visual Studio Code for squashing ¶

Change your default branch name ¶

Choose a default strategy for git pull ¶

Use a global .gitignore file (optional) ¶

Conclusion ¶

My terminal configuration

Terminal emulator: iTerm2 ¶

Package manager: Homebrew ¶

Prompt: Starship ¶

Replacements ¶

bat: a cat alternative ¶

exa: a ls alternative ¶

Rule #1: `onSuccess` and `onError` should always return (or throw) ¶

Rule #2: Prepare for errors, always `catch` ¶

Choose a default strategy for `git pull` ¶

bat: a `cat` alternative ¶

exa: a `ls` alternative ¶