DEV Community: Ivan Alejandro

Loosely coupling with Typescript

Ivan Alejandro — Mon, 16 Oct 2023 16:20:59 +0000

Introduction

On this article we'll go through a simple example that shows how to type the data you pass around on your application in a way that makes it easier to test and maintain.

About "loosely coupling"

In computing and systems design, a loosely coupled system is one in which components are weakly associated with each other, and thus changes in one component least affect existence or performance of another component

-- https://en.wikipedia.org/wiki/Loose_coupling

We'll adjust our types and code to connect our components more loosely.

Example

Let's say we have a chat application, we are dealing with messages, and we have a utility function that calculates the size of a list of messages.

// this usually lives on some other file and is imported here
interface MessageModel {
  id: string;
  author: { id: string; username: string };
  text: string;
  timestamp: number;
}

function getMessagesSize(messages: MessageModel[]): number {
  let size = 0;
  messages.forEach(message => size += message.text.length);
  return size;
}

We have the MessageModel interface defining the shape of our data, and then on the getMessagesSize function we receive a parameter of that type.

Simple enough, and it'll work just as expected. But as you add more features and functions, and your code grows, using this approach makes it harder to maintain over time than it needs to be.

What's the problem?

The function we just wrote only needs to use the text field, but it "knows" (through the parameter type) about all the other fields that a message has. And not only knows, it requires the other fields to be there.

Why is that a problem? You may ask. Let's write a simple test for our function:

test("that the messages size is correct", () => {
  const messages = [
    { text: "hello" },
    { text: "world" },
  ];

  const size = getMessagesSize(messages);
  expect(size).toBe(10);
});

You'll get this error:

error: TS2345 [ERROR]: Argument of type '{ text: string; }[]' is not assignable to parameter of type 'MessageModel[]'.
  Type '{ text: string; }' is missing the following properties from type 'MessageModel': id, author, timestamp

It basically says that you're passing the wrong type to the getMessagesSize function.

In order to make it right, you need to write the test like so:

test("that the messages size is correct", () => {
  const messages = [
    {
      id: "test-message-id-01",
      author: { id: "test-uid-01", username: "username-01" },
      text: "hello",
      timestamp: 1234,
    },
    {
      id: "test-message-id-02",
      author: { id: "test-uid-02", username: "username-02" },
      text: "world",
      timestamp: 2345,
    },
  ];

  const size = getMessagesSize(messages);
  expect(size).toBe(10);
});

We have to write some "test data" just to construct a type that works with what getMessagesSize needs, when we only care about the text field.

Also, if the type changes in the future, we'll have to update our test, even if the change is irrelevant for what we want to test and for the implementation of the function we want to test. For example either adding or removing fields, that are not the text field that we use on this function.

Different valid data shapes

Another problem we may face is that you may not be able to use the getMessagesSize function on different places of the app freely. A common use case is to use GraphQL APIs to get the data we need for the parts of the app we're working on. So most likely the Message will look different on other parts of the app.

For example, on a message list you may care about the user avatars, but on a notifications icon you may only care about the number of messages.

How can we make this better?

Let's change how we declare the type of data we expect to receive on our function.

interface Message {
  text: string;
}
function getMessagesSize(messages: Message[]): number {
  let size = 0;
  messages.forEach(message => size += message.text.length);
  return size;
}

Note that we don't need to change the actual data that we send to this function, we are just saying that the data we expect needs to have a text field.

This new function signature will accept any message that has a text field. The message could have any number of fields or just text.

Because of how types work¹ any "extra" fields will be accepted with no complaints.

Now we can write our test like so:

test("that the messages size is correct", () => {
  const messages = [
    { text: 'hello' },
    { text: 'world' },
  ]
  const size = getMessagesSize(messages);
  expect(size).toBe(10);
});

Not only this is simpler, but if the type changes in the future, we won't have to update our test since we typed the getMessagesSize function with only what's relevant.

Considerations

Note that since we are now using a parameter that only has what's needed for the implementation, if eventually we need to update the function to use other fields that we may be passing, we'll need to update the type/interface as well, even if the data we need is there, the shape we defined says otherwise, which in my opinion is a good trade-off since we are working with what we need.

Playground

Here's the two code examples we discussed on the article, loaded on a Typescript playground for you to experiment:

The full MessageModel and the function requiring it: playground
And the function requiring only the text field: playground

If you're interested on how typescript matches types and data even if they are not exactly the same read about "structural typing" on the Typescript Handbook: https://www.typescriptlang.org/docs/handbook/type-compatibility.html. ↩

Use a custom data folder on Flatpak apps

Ivan Alejandro — Sat, 01 Jul 2023 02:27:31 +0000

The problem

You want to use different data/configuration folders for a Flatpak application, or maybe run multiple instances independent from each other.

I read through Flatpak's man pages, cli help and documentation but I didn't find a solution to my problem.

The solution

Run the flatpak app with a different HOME env variable.

env HOME=/path/to/your/custom/flatpak/home flatpak run your-app

And that's pretty much it, everything related to running this specific app will be contained on that path you just used. And subsequent runs will work just as it would if you'd use the default home.

Example

For example, let's say we want a separate instance of Zoom (Zoom on Flathub) to run along the default one.

And also, let's use Flatseal to manage the flatpak app permissions.

I also created a couple of scripts to simplify the task of starting them up:

$ cat zoom.sh
#!/bin/sh
env HOME=$(pwd)/custom-flatpak-home flatpak run us.zoom.Zoom

$ cat flatseal.sh
#!/bin/sh
env HOME=$(pwd)/custom-flatpak-home flatpak run com.github.tchx84.Flatseal

Here's how the data folder looks like:

~/apps/zoom.1$ tree -L 4 -a
.
├── custom-flatpak-home
│   ├── .cache
│   │   └── flatpak
│   │       └── system-cache
│   ├── Documents
│   │   └── Zoom
│   ├── .local
│   │   └── share
│   │       └── flatpak
│   ├── .var
│   │   └── app
│   │       ├── com.github.tchx84.Flatseal
│   │       └── us.zoom.Zoom
│   └── .zoom
│       ├── data
│       │   ├── com.zoom.ipc.assistantapp__req
│       │   ├── com.zoom.ipc.assistantapp__res
│       │   └── zoomus.enc.v2.db
│       ├── im
│       ├── logs
│       │   └── zoom_stdout_stderr.log
│       ├── reports
│       └── screenCapture
├── flatseal.sh
└── zoom.sh

19 directories, 6 files

Use cases

How can you take advantage of this? or what could this be useful for?

logging in into multiple accounts on some app at the same time, maybe Teams or Zoom.
- this can be useful to isolate them from each other, or
- to use multiple accounts when it's not supported natively by the app
playing around with an app and its configurations without worrying about breaking your main working app
use this isolation to contain the data for a "disposable" instance you want to run, for tests/experiments/etc

Handle Javascript errors like in Go

Ivan Alejandro — Thu, 11 Aug 2022 15:00:02 +0000

Introduction?

I feel like some patterns or shapes of error handling are more convenient than others. Depending on the context and what I needed to do when an exception occurred, I found myself handling errors differently.

And then I thought that it could be useful to write down the different ways of handling errors that I've been using and maybe experiment a bit with something new.

On this article I'll show you common ways of using data and errors, and then how I approached exception handling as is common in the Go programming language (disclaimer: I'm not a Go developer).

I'm going to be focusing on async/Promises based code.

Error handling, alt 1

try {
  const data = await somethingThatCanFail()
  // do something with the `data`
} catch(error) {
  // handle the `error`
}

Most likely the most common way of handling error nowadays.

Error handling, alt 2

somethingThatCanFail()
  .then((data) => { /* do something with the `data` */ })
  .catch((error) => { /* do something with the `error` */ })

Nothing new here, on the contrary, the most common way of handling errors before async/await became mainstream.

Error handling, alt 3

try {
  await somethingThatCanFail()
    .then((data) => { /* do something with the `data` */ })
} catch(error) {
  // handle the `error`
}

This could be used on a way where you don't have to do much with the data, but you have to do more than a simple action to handle the error.

Note that even though we used .then we need await, otherwise if there's a problem catch won't get it.

Error handling, alt 4

const data = await somethingThatCanFail()
  .catch((error) => { /* do something with the `error` */ })
// do something with the `data`

This could be used on cases where you don't need to do much with the error, or where the error itself doesn't need to be accessed outside of the catch callback. It "saves" you from the extra nesting from the try/catch block, so it could help you handle problems more concisely.

Error handling, idea

I don't think I've seen this approach anywhere, so I wanted to experiment on whether this "shape" made sense to me.

My idea is to borrow Go's approach of handling the error as a value, which is basically:

f, err := os.Open("filename.ext")
if err != nil {
    log.Fatal(err)
}
// do something with the open *File f

You can read more about error handling in Go here: https://go.dev/blog/error-handling-and-go

I was picturing that the end result would be something like:

const [data, error] = await somethingThatCanFail()
if (error) {
  // handle the `error`
}

Basically, we want our Promise to be turned into an array, we can do that like so:

function promiseToArray(promise) {
   return promise
    .then(data => [data])
    .catch(error => [undefined, error]);
}

const [data, error] = await promiseToArray(somethingThatCanFail());
if (error) {
  // handle the `error`
}

So, we are kind of there, but I still don't like the syntax, let's try to improve this a bit...

Promise.prototype.toGo = function() {
  return this
    .then(data => [data])
    .catch(error => [undefined, error]);
};

const [data, error] = await somethingThatCanFail().toGo();
if (error) {
  // handle the `error`
}
// or conversely
if (!error) {
  // do something with the `data`
}

Now I like it much better. We are modifying the Promise prototype, which may not be the best idea, but for an experiment looks great.

Final thoughts

Should you use this? I don't know, probably not a good idea. Personally I'd rather stick to more commonly used patterns.

This approach could be useful for some specific use case, or maybe this idea will spark some other idea that will actually be useful.

Disclaimer

While writing this, I found that someone already thought about this much earlier than me, check out this article:
https://blog.grossman.io/how-to-write-async-await-without-try-catch-blocks-in-javascript/

Running unverified apps on Mac

Ivan Alejandro — Tue, 22 Mar 2022 19:05:22 +0000

The problem

You download a binary or application, go to run it and Mac won't let you. There are (arguably) good reasons for this, but that's out of the scope of this article, but you'll find more information about Mac's Gatekeeper on the internet :).

You'll see something like this:

Error message while trying to run binary:
“your-binary” cannot be opened because the developer cannot be verified.
macOS cannot verify that this app is free from malware.
Chrome downloaded this file today at 9:00 from example.com

Explanation

So, how does Mac knows that a binary is not to be checked/trusted?

When you download a file, the browser sets the extended attributes that Mac will check before allowing you to run the binary/app.

Show extended attributes

$ xattr your-binary
com.apple.metadata:kMDItemWhereFroms
com.apple.quarantine

Show extended attributes' data

Here's an example

# if you downloaded it using Chrome
$ xattr -l your-binary
com.apple.metadata:kMDItemWhereFroms: ...
com.apple.quarantine: 0181;62324d50;Chrome;37400A13-128E-4ABA-97ED-D61093874F54

# if you downloaded it using Firefox
$ xattr -l your-binary
com.apple.metadata:kMDItemWhereFroms: ...
com.apple.quarantine: 0181;62324b24;Firefox;99E8F9C8-78F9-4CD4-8E08-9D1D6791B22B

You can see that there's also a com.apple.metadata:kMDItemWhereFroms attrbiute, it has binary data (mostly text, though). It contains the url where you downloaded the binary from. This information is used to show the error message to the user.

Remove quarentine attribute

Removing the quarentine flag should be enough to allow you to run your binary.

$ xattr -d com.apple.quarantine your-binary

Remove all extended attributes

If you want to get rid of all the data, you can use:

$ xattr -c your-binary

An app instead of a binary?

If you have an app, which is really a directory (e.g. YourApp.app) you may want to apply these changes to every file on that folder. You can do that using the -r argument for xattr. For example:

$ xattr -dr com.apple.quarantine YourApp.app

Alternative

Depending on your use case it may be easier to just use curl or wget (on the command line) to download the file.
At the time of writing this, those tools are not "compliant" with Mac and don't set any extended attribute, so you can just download and run without Mac's Gatekeeper complaining.

I'm not sure if "compliant" is proper word for apps setting these extended attributes, though.

Safer types on TypeScript

Ivan Alejandro — Fri, 11 Mar 2022 00:00:00 +0000

Nominal typing on TypeScript

You can use "nominal typing" for a clearer and safer code, as well as to potentially reduce the need of data validation on multiple places.

TypeScript has type compatibility based on "structural typing" but we can get some kind of "nominal typing" with not much effort.

You can read more about TypeScript's type compatibility on their handbook.

Please read the references section on the bottom for information about "structural typing", "nominal typing" and the different approaches that can be used.

Example

Consider this person renaming function:

function renamePerson(id: string, newName: string): boolean {

The id and newName arguments can be any string, they don't have to be valid id/name respectively (for whatever definition of valid we use on our app).

Because of that, the safest thing to do is to actually validate them as soon as we enter the function.

We would also have validation for the person name somewhere on the UI so we can give feedback to the user if there's a wrong name being used.

In order to make sure that the renamePerson function actually receives valid data we can do something like this:

function renamePerson(id: PersonId, newName: PersonName): boolean {

Note that id and newName now have their own type.

How should we define those types?

We can't use something like type PersonName = string because, due to TypeScript type compatibility being based on structural typing, you could send strings for those parameters and that'll just work without complaints from the compiler.

There are several ways of doing this, I'll just pick the simplest one to explain the concept, once you're familiar with the idea you can choose from other variations.

We create a custom type with something specific to it to simulate "nominal typing". Here's an example:

// intersect string with something specific to prevent a structural typing match
type PersonName = string & { __brand: "valid person name" };

Let's use it:

function sayHello(name: PersonName) { /* ... */ }
sayHello("Alice");

// Argument of type 'string' is not assignable to parameter of type 'PersonName'.
//   Type 'string' is not assignable to type '{ __brand: "valid person name"; }'.(2345)

Now, our PersonName typed data is not "structurally compatible" with a string. We have to use our own type.

// any variable of type PersonName must be created here
// that way we guarantee that validation happens
function getPersonName(personName: string): PersonName | undefined {
  if (isValidPersonName(personName)) return;
  return personName as PersonName;
}

function sayHello(name: PersonName) { /* ... */ }
const name = getPersonName("Alice");
if (name !== undefined) sayHello(name);

If we only create a PersonName using this "constructor", and the validation is done properly, we can be certain that everywhere we see a PersonName is going to be valid.

We could validate a string as soon as we receive it from a user or from an API, and then create a PersonName, from that point on we can be certain that we are dealing with valid data.

Playground

Here's a TypeScript playground with some example code: typescript playground

References

Here are some articles where You can read more about nominal typing:

There's also TypeScript's handbook:

https://www.typescriptlang.org/docs/handbook/type-compatibility.html

An example of this on TypeScript's playground:

https://www.typescriptlang.org/play#example/nominal-typing

Some relevant Stack Overflow answers:

P.S. about people names

I used people names for my example because it's easy to grasp for an example, but remember that defining what a valid name is is not straigforward. See the "Falsehoods Programmers Believe About Names" article:

Introduction to testing with Python for beginners

Ivan Alejandro — Tue, 25 Jan 2022 16:54:14 +0000

Introduction

You started programming with Python, write code and solve problems. On this article we'll discuss how you can write tests for your code, you can run them quickly to make sure everything works instead of running your app over and over to make sure your changes work.

Our program and making sure it works

We will use a very simple example that will help you get the idea of the problem you may face and the solution tests can bring.
The idea is for the example to be super simple (dumb even) so you can focus on the new concept instead of on the example code iteself.

Let's say we have this program where we ask the user for two numbers and we multiply them.

# file: main.py
from mymath import multiply

print("Mutliply two numbers")
a = input("first number: ")
b = input("second number: ")
print("result:", multiply(int(a), int(b)))

Again, this is a simple program, in the real world you could be asking for data relevant to any problem and do complex calculations with them.

And say we have this implementation for multiplication:

# file: mymath.py
def multiply(a, b):
    # sum "a" "b" times, 2*3 -> 2+2+2
    result = 0
    for _ in range(b):
        result += a

    return result

Let's run the app on the command line:

$ python3 main.py
Mutliply two numbers
first number: 2
second number: 3
result: 6

$ python3 main.py
Mutliply two numbers
first number: 5
second number: 6
result: 30

So far so good, let's try a negative number:

$ python3 main.py
Mutliply two numbers
first number: -4
second number: 4
result: -16

Still works, let's try again:

$ python3 main.py
Mutliply two numbers
first number: 4
second number: -4
result: 0

Alright, we found a bug!

Testing our program with another program

When your program is larger and there are many more options than just one math operation, it will take you much more program runs to actually find some cases that are not working.

And more importantly, you can test all the things in a blink every time you make changes on your app without having to worry if your change broke something that you didn't notice.

Let's write a little program that do this testing for us:

# file: mymath_tests_v1.py
from mymath import multiply

if (multiply(2, 2) != 4):
    raise Exception("result error")

if (multiply(2, 4) != 8):
    raise Exception("result error")

if (multiply(2, -2) != -4):
    raise Exception("result error")

Let's run it:

$ python3 mymath_test_v1.py
Traceback (most recent call last):
  File "mymath_test_v1.py", line 10, in <module>
      raise Exception("result error")
      Exception: result error

Now, we are checking the same thing that we would check running the app, but with code. And as added value, we are documenting the use cases we support on our app, and the ones that are more relevant when we want to make sure that the program works.

This is basically what we can call a "test", or "unit test". Code that checks that make sure that your code works. There are other types of tests, for other purposes, but that's out of the scope of this article.

Improving our tests

The approach we just explored was only a crude implementation of tests using just conditionals, let's take it a step further.

Instead of manually writing conditionals and raising exceptions, we'll make use of the assert keyword.

It basically works like this:

$ python3
>>> assert(2 == 2)  # no error
>>> assert(2 == 3)  # throws exception
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AssertionError

Here's how we can use it for our tests:

# file: mymath_tests_v2.py
from mymath import multiply

assert(multiply(2, 2) == 4)
assert(multiply(2, 4) == 8)
assert(multiply(5, 6) == 30)

$ python3 mymath_tests_v2.py
Traceback (most recent call last):
  File "mymath_tests_v2.py", line 5, in <module>
    assert(multiply(2, -2) == -4)
AssertionError

As you may have noticed, not only our code is shorter but when an assertion fails, there's information on the exception about why it failed and instead of just getting the line where the problem appeared we get the expression we run, and that makes figuring out the problem much easier.

Improving our tests, using a framework

Testing can be improved even further, there are frameworks (sometimes called libraries, modules or packages) that provide some extra tools for us to make writing and running tests even easier, as well as providing much nicer results for tests that pass and fail.

Python comes with its own framework to run tests, it's called unittest. See its documentation

Here's how we would write our test using it:

# file: test_mymath_simple.py
import unittest
from mymath import multiply

class MyMathTest(unittest.TestCase):
    def test_basics(self):
        self.assertEqual(multiply(2, 2), 4)
        self.assertEqual(multiply(2, 4), 8)
        self.assertEqual(multiply(2, -2), -4)

If you're not familiar with class you can ignore the details and instead of writing MyMathTest you can write whatever you want, and all the functions have to start with test_.

You have many self.assert prefixed helper functions to test different things, we can stick with equality comparison for now.

Let's run these tests:

$ python3 -m unittest -v test_mymath_simple.py
test_basics (test_mymath_simple.MyMathTest) ... FAIL

======================================================================
FAIL: test_basics (test_mymath_simple.MyMathTest)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/ivan/data/Devel/blog/test_mymath_simple.py", line 9, in test_basics
    self.assertEqual(multiply(2, -2), -4)
AssertionError: 0 != -4

----------------------------------------------------------------------
Ran 1 test in 0.000s

FAILED (failures=1)

We are getting more output (partly because of the -v flag) and some of it is valuable: for example 0 != -4, that's exactly the condition that failed. Results are more explicit for us, so it's much easier to figure out the problem.

Remember, here's easy because of our really small example, but on larger programs gets much harder.

Using unittests like in the real world

# file: test_mymath.py
import unittest
from mymath import multiply

class MyMathTest(unittest.TestCase):
    def test_small(self):
        self.assertEqual(multiply(2, 2), 4)
        self.assertEqual(multiply(2, 4), 8)
        self.assertEqual(multiply(10, 10), 100)

    def test_zero(self):
        self.assertEqual(multiply(2, 0), 0)
        self.assertEqual(multiply(0, 2), 0)

    def test_negative(self):
        self.assertEqual(multiply(-2, 2), -4)
        self.assertEqual(multiply(-2, -2), 4)
        self.assertEqual(multiply(2, -2), -4)

On this example, we have different test "groups", in which we make sure different aspects of our program behave as it should.
Those are run separately and we'll get information about which of them work and which of them fail.

Let's run our new test "suite".

$ python3 -m unittest -v test_mymath.py
test_negative (test_mymath.MyMathTest) ... FAIL
test_small (test_mymath.MyMathTest) ... ok
test_zero (test_mymath.MyMathTest) ... ok

======================================================================
FAIL: test_negative (test_mymath.MyMathTest)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/ivan/data/Devel/blog/test_mymath.py", line 17, in test_negative
    self.assertEqual(multiply(-2, -2), 4)
AssertionError: 0 != 4

----------------------------------------------------------------------
Ran 4 tests in 0.001s

FAILED (failures=1)

You can have many test files, and as long as they start with test_ you can run python3 -m unittest -v and it'll run all your test, wherever they are.

Closing thoughts

Tests allow you to verify your program quickly, frequently and consistently. Using them you can have more confidence on your app and on the changes you make to it.

There's much more to learn about testing, but hopefully this introduction will be enough for you to get started testing your code.

Thre are several third party libraries that provide very nice functionalities on top of what you get from the standard library.
Once you're comfortable writing tests, you can give some of them a try and see how do you like them.

Unraveling callbacks with async functions

Ivan Alejandro — Wed, 10 Jul 2019 13:48:13 +0000

Requirements

I assume you are familiar with Javascript and these concepts:

Example and problems

This is a real life example of how a function that moves a file looked. This was part of one of our mobile apps.

The code is not really complex, but it was hard to read at a glance; it felt bad.
So I tried to refactor it a little to see if I could improve its readability.

import path from 'path';

/**
 * Moves a file from one directory to another.
 *
 * @param { String } basePath: the base path for both relativeSourcePath
 *                             and relativeDestinationPath.
 * @param { String } relativeSourcePath: the relative path of the file.
 * @param { String } relativeDestinationPath: the relative new path of the file.
 *
 * @return { Promise } resolves with no value if the file is
 *                     successfully moved.
 */
function move(basePath, relativeSourcePath, relativeDestinationPath) {
  return new Promise((resolve, reject) => {
    const destinationPath = path.dirname(relativeDestinationPath);
    const filename = path.basename(relativeDestinationPath);

    ensureDirectory(basePath, destinationPath).then(() => {
      window.resolveLocalFileSystemURL(basePath, baseDirEntry => {
        baseDirEntry.getFile(relativeSourcePath, {}, sourceFileEntry => {
          baseDirEntry.getDirectory(destinationPath, {}, destDirEntry => {
            sourceFileEntry.moveTo(destDirEntry, filename, resolve, reject);
          }, error => {
            console.error('[move] Error getting destination directory', error);
            reject(error);
          });
        }, error => {
          console.error('[move] Error getting source file', error);
          reject(error);
        });
      });
    }).catch(error => reject(error));
  });
}

The problem here is mainly that we have a deeply nested code, which makes it harder to reason about, maintain and debug.

The strategy

To understand what was going on, what I tried to do is to visually isolate callbacks, identify relevant data we were extracting from each call, and where we were using it.

After that, I wrapped the functions on await and Promise to simulate a regular function that returns a value.

Let's see how we go from a callback based function to an async function.

// you call this `doStuff` function to do something and you get `data` if it
// succeeds or an `error` if it fails.
doStuff(param1, param2,
    data => {
      /* do something with the data */
    },
    error => {
      /* problem with doStuff */
    }
  );

// We can extract our functions to handle success and failure like so:
const onSuccess = data => { /* do something with the data */ }
const onFailure = error => { /* problem with doStuff */ }

doStuff(param1, param2, onSuccess, onFailure);

Now, let's use a Promise to wrap our call and await for its result.

try {
  const data = await new Promise((resolve, reject) => {
    const onSuccess = data => resolve(data);
    const onFailure = error => reject(error);
    doStuff(param1, param2, onSuccess, onFailure);

    // we don't really need a separate definition for the functions
    // we can inline them like so:
    doStuff(param1, param2, data => resolve(data), error => reject(error));
  });

  /* do something with the data */
} catch(error) {
  /* problem with doStuff */
}

Or alternatively, as a one liner.

try {
  const data = await new Promise((resolve, reject) => doStuff(param1, param2, data => resolve(data), error => reject(error)));
  /* do something with the data */
} catch(error) {
  /* problem with doStuff */
}

The success/failure handlers are a bit redundant, so let's simplify that.

try {
  const data = await new Promise((resolve, reject) => doStuff(param1, param2, resolve, reject));
  /* do something with the data */
} catch(error) {
  /* problem with doStuff */
}

And there we go, our final shape. It doesn't look like much of a change, but this allows us to have a more shallow code instead of a really nested set of callbacks.

Final result

Here's how our function looks after refactoring it using the above strategy.

import path from 'path';

/**
 * Moves a file from one directory to another.
 *
 * @param { String } basePath: the base path for both relativeSourcePath
 *                             and relativeDestinationPath.
 * @param { String } relativeSourcePath: the relative path of the file.
 * @param { String } relativeDestinationPath: the relative new path of the file.
 *
 * @throws { Error } if there was a problem moving the file.
 */
async function move(basePath, relativeSourcePath, relativeDestinationPath) {
  const destinationPath = path.dirname(relativeDestinationPath);
  const filename = path.basename(relativeDestinationPath);

  try {
    await ensureDirectory(basePath, destinationPath)

    const baseDirEntry = await new Promise(resolve =>
      window.resolveLocalFileSystemURL(basePath, resolve)
    );

    const sourceFileEntry = await new Promise((resolve, reject) =>
      baseDirEntry.getFile(relativeSourcePath, {}, resolve, reject)
    );

    const destDirEntry = await new Promise((resolve, reject) =>
      baseDirEntry.getDirectory(destinationPath, {}, resolve, reject)
    );

    await new Promise((resolve, reject) =>
      sourceFileEntry.moveTo(destDirEntry, filename, resolve, reject)
    );
  } catch (error) {
    // here you can do something about this problem
    console.error('There was a problem moving the file.', error);
    throw error;
  }
}

For this particular case, it didn't make much sense to log two different errors, so I wrapped all the calls in a try/catch and just logged the problem there.

Your use case may vary and you may want to have more than one handling block or none at all and document that your function may throw different errors. This is useful if you don't want to perform a specific action on this function when an error occurs, and leave it to the caller.

Last words

With just a little of work, our code is now easier to read and maintain.

This problem is quite common and it's usually called "callback hell", as you can see here: http://callbackhell.com/

I hope this article gives you some ideas on how to make your life easier.

Disclaimer

I wrote this article for the SpiderOak engineering blog and it was published on Jul 10, 2019.
https://engineering.spideroak.com/unraveling-callbacks-with-async-functions/

The original post is licensed as: Creative Commons BY-NC-ND

Redux and single purpose functions

Ivan Alejandro — Tue, 02 Jul 2019 20:31:56 +0000

Preamble

On this post I will share a couple of lessons learned while working on SpiderOak Semaphor, where we use:

Javascript and React to build our UI components.
Jest to write our tests.
Redux to serve as single source of truth for our data.

Even though this post shows functions in the context of Redux, you can extrapolate the idea to any javascript function.
I'll show tests using Jest, but you could use any other tool you like. Jest tests are pretty readable on its own even if you haven't seen jest tests before.

You should be able to get some ideas from this post even if you don't know redux/jest.

TL;DR ?

Use single purpose functions to simplify your code.
Add tests to the mix and you'll have code that you can trust.
Factor out your reducer's logic into more manageable functions instead of a giant switch.
You now have a more maintainable and trustworthy codebase.

For more details, keep reading :)

Redux's reducers

Reducers specify how the application's state changes in response to actions sent to the store. Remember that actions only describe what happened, but don't describe how the application's state changes.
(from: https://redux.js.org/basics/reducers)

Reducers are presented (almost always) as large functions with a switch to decide what to do depending on the action received.

Let's see why this is a problem and how we can use a better approach.

Example and problems

Let's say we want to store some users on Redux. We'll need actions to add and remove a user.

This is usually how we see reducers on tutorials:

// e.g. src/actions/users.js
export const USER_ADD = "USER_ADD";
export const USER_REMOVE = "USER_REMOVE";

// e.g. src/reducers/usersById.js
export function usersById(state = {}, action) {
  let newState;
  switch (action.type) {
    case USER_ADD:
      return {
        ...state,
        [action.user.id]: action.user,
      };
    case USER_REMOVE:
      newState = { ...state };
      delete newState[action.id];
      return newState;
    default:
      return state;
  }
}

This approach has several problems:

The function gets very long and too nested, which makes it harder to read, harder to test, and more error prone.
The function has several responsibilities, which makes it harder to document. You would add a big docstring that explains all the things this function does.
Lexical scope sharing on the switch, read more about that here: https://eslint.org/docs/rules/no-case-declarations.
Is not obvious what data you expect to get from the action.

Note that these problems are really noticeable as the codebase grows, not really for such contrived example.

Adding tests

We will fix our problems by doing some refactor, but before that, we'll write some tests for our reducer.

Disclaimer: real world code will be more complex, and adding tests will make more sense than on this contrived example.

I recommend you write tests before starting to make changes to your working code, so you can be sure it still works after the changes.

Here's an example (using jest) of how a test for this use case could look:

// e.g. src/reducers/usersById.test.js
import { userAdd } from 'actions/users';
import { usersById } from 'reducers/usersById';

test('on USER_ADD, with empty state', () => {
  // define your initial state
  const initialState = {};

  // define payload for the action we'll use to test the reducer
  const user = { id: 'user-id-1', username: 'john-doe-01' };

  // define expected state
  const expectedState = {
    [user.id]: user,
  };

  // call our reducer
  const result = usersById(initialState, userAdd(user));

  // check that the result we got is what we need
  expect(result).toEqual(expectedState);

  // check that we don't mutate the state
  expect(result).not.toBe(initialState);
});

Note that to test our reducers we don't even need Redux, they are just functions.

We don't (directly) test our action creators since they should be as simple as:

// e.g. src/actions/users.js
export const USER_ADD = "USER_ADD";

export function userAdd(user) {
  return {
    type: USER_ADD,
    user,
  }
}

We test them indirectly by calling them within our reducer's test, which should be enough.

Single purpose functions

This is a very simple concept, nothing special, just a function with a single purpose instead of multiple ones.

Our reducer is presented as a "monolithic" function with a giant switch. It has several problems, as we listed above.

We'll split it up into smaller, single-purposed, and more manageable functions. Let's dig into it.

Refactoring

Now that we have tests for our reducer, we can confidently refactor them or swap implementations with a different one without breaking the rest of our code.

Let's tackle the problems we listed for our example.

Using the strategy proposed on the redux docs we can do some refactor on our reducers to make them look like this:

// e.g. src/actions/users.js
export const USER_ADD = "USER_ADD";
export const USER_REMOVE = "USER_REMOVE";

// e.g. src/reducers/usersById.js
export function usersById(state = {}, action) {
  switch (action.type) {
    case USER_ADD: return addUser(state, action.user);
    case USER_REMOVE: return removeUser(state, action.id);

    default: return state;
  }
}

function addUser(state, user) {
  return {
    ...state,
    [user.id]: user,
  };
}

function removeUser(state, id) {
  const newState = { ...state };
  delete newState[id];
  return newState;
}

The refactor should be pretty straightforward, just extract the usual reducer logic for each case, into functions.

Let's contrast this approach with the problems we saw on the earlier example:

Each function is pretty short and concise, which makes them easier to read and test.
Each function has its own scope.
You can add a simple docstring for each function. It should be easy to keep it short since it shouldn't do too much, especially comparing to the "do it all" previous approach.
It is obvious what data you expect to get from the action for each function.

Run some code

If you want to take a look at our example with more tests and a couple of extra actions go to this repo.

Or, to play with it live, thanks to CodeSandbox:

Disclaimer

I wrote this article for the SpiderOak engineering blog and it was published on Jan 18, 2019.
https://engineering.spideroak.com/redux-and-single-purpose-functions/

The original post is licensed as: Creative Commons BY-NC-ND

Simplify nested object property use

Ivan Alejandro — Mon, 17 Jun 2019 22:18:25 +0000

Use case and improvement

Here's a real life example that I found while reviewing code:

function isFileSizeTooLargeError(error) {
  if (!error) return false;
  if (!error.networkError) return false;
  if (!error.networkError.result) return false;
  if (!error.networkError.result.error) return false;
  return error.networkError.result.error.includes('file size too large');
}

Don't worry too much about what's going on, but if you want some context this is an error checking function for a GraphQL query response made with react-apollo.

For reasons that don't matter for this post, we can't be sure that we will have every piece of the object we are checking and we only care about the text included on the last error.

If we didn't do any check and we just ran the includes check, we may get different exceptions, like:

TypeError: Cannot read property 'includes' of undefined
TypeError: Cannot read property 'error' of undefined

That's why all those checks were included.

We can simplify our code by acknowledging that there may be exceptions and that we don't care about them.

function isFileSizeTooLargeError(error) {
  let fileSizeTooLarge = false;
  try {
    fileSizeTooLarge = error.networkError.result.error.includes('file size too large');
  } catch (ignoreThisError) {
    // something went wrong, we don't care exactly why,
    // the string we look for is not there
  }
  return fileSizeTooLarge;
}

Note that this implementation has more lines of code than the previous one, but there are fewer lines that actually do something.

Any exception on this context means that the string we are looking for isn't there, we can safely ignore it (empty catch).

Have in mind that this is no silver bullet; depending on your implementation it may be better to have several conditionals or handle different kind of exceptions.

Future

This is a well known problem and there are many ways of dealing with it. One of them is to improve Javascript itself.

There's work being done to include a new syntax to JS that simplifies use cases like this.

The proposed change is called Optional
Chaining, at the time of writing this it's on Stage 2.

Using that syntax our code would look like this:

function isFileSizeTooLargeError(error) {
  const fileSizeTooLarge = error?.networkError?.result?.error?.includes('file size too large');
  return Boolean(fileSizeTooLarge);
}

There's already a Babel plugin for this so you can play around with it, see https://github.com/babel/babel/pull/5813

Having said that, I don't think you should use this now on your apps :).

Disclaimer

I wrote this article for the SpiderOak engineering blog and it was published on May 22, 2019.
https://engineering.spideroak.com/simplifying-deep-object-property-getting/

The original post is licensed as: Creative Commons BY-NC-ND