Solution 1: Moving Code to a New Service/Module

Moving code is typically the easiest solution. Say we have the following requirements:

• Allow members of a task to add comments to incomplete tasks

• Members can invite other users to incomplete tasks

• A task is complete once every member has approved of it

class TaskService {
  // * A task is complete once every member has approved of it
  isTaskComplete(id) {
    const members = this.taskMembersService.getAll(id);
    return members.every(member => member.hasApprovedTask);
  }

  // * Allow members of a task to add comments to incomplete tasks
  addComment(user, id, comment) {
    this.taskMembersService.assertIsMember(user);
    // Don't allow more comments once complete
    assert(!this.isTaskComplete(id));
    // ... Add comment ...
  }
}

class TaskMembersService {
  assertIsMember(user) {}
  getAll(taskId) {}

  // * Members can invite other users to incomplete tasks
  inviteMember(taskId, fromUser, inviteUserId) {
    // Don't allow inviting to a complete task
    assert(!this.taskService.isTaskComplete(taskId));
    this.assertIsMember(fromUser);
    // ... Add inviteUserId member ...
  }
}

TaskService <--> TaskMembersService

The logic is completely reasonable, and it makes sense how this structure would naturally evolve (e.g. comments existed before we started having task membership). But, of course, we have issues:

• Before adding a comment (TaskService), check if they're a member of the task (TaskMembersService)

• When inviting a member (TaskMembersService), check that the task is still open (TaskService)

• When checking if a task is open (TaskService), make sure all members (TaskMembersService) have approved of it

The problem is that we've made the TaskService a bit too generic. Tasks should be able to exist without members or comments; however, the two methods in our TaskService depend on those.

Without members, isTaskComplete() is nonsense, because a task is complete when all members approve of it. Additionally, addComment() could be described as "Allows a member to add a comment to an open task". This means addComment() correctly depends on isTaskComplete(), especially because we would want addComment() to error if we ever removed the isTaskComplete() function (because to meet the above description for the function, we need a way to check if a task is complete).

So the new service dependencies could look like:

TaskCommentService -> TaskStatusService -> TaskMembersService -> TaskService

We can do a sanity check by ensuring that, if we remove any service, we expect the dependency to produce an error (e.g. if we remove the MembersService, StatusService should break because isTaskComplete() requires the existence of members). This is under the assumption that the business requirements for all other services remain unchanged.

Solution 2: Adding events/hooks

If your requirement can be described as "When X, do Y", you can likely use events or hooks. For example, when a user deletes their account, remove any teams they're on:

class TeamService {
  constructor(
    private readonly userService: UserService,
  ) {
    // An event is called and forgotten about
    this.userService.on('delete-account', this.onDeleteAccount.bind(this));
    // onDeleteAccount(user) {}

    // In contrast, a hook will wait until the callback is completed
    // before deleting the account. This ensures we're never
    // left in a position where we're trying to delete an
    // account but fail to remove them from teams.
    this.userService.deleteAccountHooks.add(this.onDeleteAccount.bind(this));
    // onDeleteAccount(user, sqlTransaction) {}
  }
}

The UserService does not need to know that teams exist at all. If you don't totally know what needs to depend on what, consider the direction of data flow. If I delete the team and team_members table, does the user table still work? Yes? Then the UserService should not know that teams exist. This gives us more flexibility:

• If we want to delete teams and the TeamService for any reason, there's less depending on it. "Remove a user from teams when their account is deleted" is inherently team logic and should be removed when deleting the TeamService (because that logic doesn't make sense without teams).

• If we want to expand TeamService for any reason, there's less depending on it. For example, if we want team members that can either be a user or an AI (why not), we don't have to worry about a single line of code in the UserService going "oh no, how do I handle the case of an AI team member?"

What about a more direct circular dependency?

Consider the requirements:

• When the CreateTournament job is triggered, we should create a tournament

• After a tournament is created, schedule any child tournaments (if applicable)

class CreateTournamentJob {
  add(tournamentOpt, atTime) { ... }

  // This is called when it is time for the job to run
  process(tournamentOpt) {
    this.verifierService.assertValidOpt(tournamentOpt);
    this.tournamentService.create(tournamentOpt);
  }
}

class TournamentService {
  create(tournamentOpt) {
    // ... Create the tournament ...

    // Schedule child tournaments to be created 5 minutes from now
    for (const childOpt of tournamentOpt.childrenOpt) {
      this.createTournamentJob.add(childOpt, Date.now() + FIVE_MINUTES);
    }
  }
}

There are a couple of ways we can handle this, and it all depends on what our requirements are:

Hook on "create tournament"

class CreateTournamentJob {
  constructor(private readonly tournamentService: TournamentService) {
    this.tournamentService.onCreateTournamentsHooks.add(async (opt) => {
      for (const childOpt of opt.childrenOpt) {
        this.add(childOpt, Date.now() + FIVE_MINUTES);
      }
    });
  }

  add(tournamentOpt, atTime) {}

  process(tournamentOpt) {
    this.verifierService.assertValidOpt(tournamentOpt);
    this.tournamentService.create(tournamentOpt);
  }
}

This only makes sense if deleting the tournament job should make it so we no longer schedule child tournaments. If this isn't your requirement, you will run into issues. For example, perhaps you manually added tournaments to the tournament job in the past and no longer need that. You delete CreateTournamentJob and poof, suddenly child tournaments aren't generating anymore... but there weren't any errors!

Return from create()

Perhaps in another world, it makes sense to return the child tournaments so they can be acted upon. This would make sense only if we wanted to schedule child tournaments when calling from the scheduler, but handle them differently elsewhere:

class CreateTournamentJob {
  add(tournamentOpt, atTime) {}

  process(tournamentOpt) {
    const childTourns = this.tournamentService.create(tournamentOpt);
    // ... Schedule child tournaments ...
  }
}

class TournamentService {
  create(tournamentOpt) {
    // ... Create the tournament ...
    return tournamentOpt.childrenOpt.map(what => ever)
  }

  // Maybe called from an admin panel, or if users are allowed to make their own tournaments
  manuallyCreate(byUser, tournamentOpt) {
    const childTourns = this.create(tournamentOpt);
    // ... Handle child tournaments, e.g. maybe we create them immediately in this case
  }
}

Or, leave the circular dependency

Or, the final case is that the circular dependency makes sense. If we remove "creating tournaments", we WANT the job to fail. If we remove the job, we WANT "creating tournaments" to fail because otherwise it can't handle child tournaments correctly.

Wrapping Up

We covered 3 ways to resolve circular dependencies:

1. Splitting code up into different files

2. Using hook/events

3. Returning data so the caller

But ultimately, in some cases it may even make sense to leave a circular dependency in place if it aligns with your business requirements. Updating and deleting code are preferable over new code, but with messy depdenencies, they're likely to be more pain than they're worth. Make it easy to update and delete and you'll find yourself with a smaller codebase doing the exact same thing.

The easiest way to check if you have your dependencies set up well is to ask yourself, for any given piece of code: If I delete this code/edit the types & functionality, are all the errors representative of all the areas that need their business requirements changed? Or is it merely busy work to fix the error? By doing so, you can avoid potential pitfalls and create software that is easier to understand, maintain, and expand. Happy coding!

Kubernetes (Google Cloud or Digital Ocean)

When I started my project, I used Kubernetes. Many claim it's over-complicated, and, if you don't plan to scale, it probably is. But if you want to build an app that will grow, it will pay off immensely. Not only is it trivial to scale (you can easily scale containers by CPU load with HPAs), it makes setting up new services less of a hassle. For example, in my last project, there was a Python library and a C# library that didn't have replacements in TypeScript, so I simply built wrappers around them and turned them into services. If setting up a service wasn't as trivial, I might've tried to make do with adding to the monolith, even if creating a new service was the right thing to do.

I used Google Cloud at the time. It's fine, but I do want to try Digital Ocean next, since GCloud had a ton of features that I rarely, making their interface more complicated.

Additionally, I was not using Terraform at the time, but I probably would now (since manually applying all the Kubernetes files was error-prone).

P.S. You'll need a container registry so Kubernetes has somewhere to pull your Docker images from. Both GCloud and Digital Ocean support this.

Postgres and Redis

Pick the right tool, of course—if you know NoSQL or another database is right for your project, use that. However, even in the constantly-changing database schemas of the startup world, Postgres (with an ORM that can handle migrations smoothly) is rarely a bad choice.

Redis (or an alternative) is a must-have. You can reduce your Postgres queries five or tenfold with proper caching. Without Redis, your primary database will likely be your largest cost. In addition, it's a must for scaling; I've never had a website go down under Redis load, but I've had many issues with Postgres getting overloaded (unoptimized queries, spike in traffic that maxes out its connections, etc).

New Relic/Datadog and Pagerduty

At some point, something will go wrong. If you have 200 concurrent users on your site for a growing startup, going down for an hour sucks. Going down overnight is terrible. Pager Duty is free for solo devs, so there's not much of an excuse not to use it.

Datadog and New Relic are up to personal preference—I did some research back in 2019 and picked Datadog. I did some research recently and would instead choose New Relic due to its friendly pricing for solo devs. Do your research, but as of right now, it seems to be mainly pricing differences for roughly the same set of features (logging, APM tracing, metrics, etc).

Sentry

Sentry for frontend errors. Not much to say here; I'm sure there are alternatives, but Sentry works great and has a free plan to get started. Make sure to consistently update your frontend to block unnecessary errors so you don't eat into your quota with false positives.

Redash (Visualize SQL Queries)

You don't need to pick Redash specifically, but anything that will help you visualize queries. It's a pain to make business decisions by writing queries, importing them to Google Sheets or Excel, and then creating graphs.

Github or Gitlab

I chose Gitlab for my last project, simply because it was free for private repos (and I liked the ability to self-host in the future). If you're a solo dev, it doesn't really matter—and you can always transfer from one to the other later. For what it's worth, Github has more free CI/CD minutes than Gitlab.

Estimated Cost

Redis, Postgres, Kubernetes, and Container Registry pricing are all based on Digital Ocean.

1. Kubernetes - $48/mo to start (represents two nodes each with 2 vCPUs and 2.5GB of RAM; you may need more or less, this one is hard to predict)

2. Container Registry - $5/mo

3. Redis - $15/mo

4. Postgres - $15/mo (at least, may become $30/mo or $60/mo in the first couple of months depending on your needs)

5. Pager Duty - Free for solo devs!

6. New Relic - Free-ish (They charge a reasonable rate for data and a hefty cost per user after the first, so great for solo devs, but pricey as your team scales)

7. Sentry - Free (You'll likely need to upgrade to $26/mo in the first couple of months)

8. Redash - $12/mo (Or $0 if you host locally)

9. GitHub - Free for solo devs!

Total: $95/mo (could be cheaper if you choose lower-cost machines and self-host Redash)

Reduce Costs

In your first few months, you're probably not making any money, but your costs will go up. Here are some ways to keep them manageable (this could probably be its own article, but whatever, bonus content):

• Postgres Storage: Look for cheaper options for write-only data or data that doesn't need to be accessed often (e.g. metrics in longer-term storage, calculated data that could instead be cached, etc)

• Postgres CPU/Memory: Cache more

• Kubernetes Node CPU/Memory: Optimize your app (duh). Also cache more! E.g. it may be lower cost to host your frontend statically VS running an nginx server in a pod.

• Sentry/New Relic/Datadog: Watch what data you're sending—gobs of unnecessary logs or errors can sometimes be forwarded. Setup some kind of ingestion control so you're only intaking 50% or 25% of APM traces.

• Container Registry: Delete outdated images.

Github Copilot is an ML-powered autocompletion tool for developers (it uses OpenAI's Codex). It is currently has a 1-month free trial and is priced at $10/mo.

Amazon CodeWhisperer is a similar service. It's currently in private preview, so its quality and feature set may change before release.

Comparison

Each of these tests is conducted from a blank page in VSCode with a language selected (typically Javascript unless otherwise stated). I will include the prompt and the results that both Copilot and CodeWhisperer suggested, along with any interesting items to notice.

Basic Variables (Similar)

// Prompt
const a = 1;
const b = 2;
const sum =

// Copilot
const sum = a + b;

// CodeWhisperer (July 2022)
const sum = () => {
  return a + b;
}

// CodeWhisperer (April 2023)
const sum = a + b;

Trigonometry (Same)

// Prompt
const x = Math.cos(angle) * radius;

// All
const y = Math.sin(angle) * radius;

Factorial (Near Identical)

// Prompt
function factorial

// Copilot
function factorial(n) {
  if (n === 0) {
    return 1;
  }
  return n * factorial(n - 1);
}

// CodeWhisperer (July 2022 and April 2023)
function factorial(n) {
  if (n === 1) {
    return 1;
  }
  return n * factorial(n - 1);
}

Price of BTC

// Get price of BTC
function

// Copilot (July 2022)
function getPrice() {
  return new Promise((resolve, reject) => {
    request('https://api.coinmarketcap.com/v1/ticker/bitcoin/', (error, response, body) => {
      if (error) {
        reject(error);
      }
      resolve(body);
    });
  });
}

// CodeWhisperer (July 2022)
function getPrice(callback) {
  $.ajax({
    url: "https://api.coindesk.com/v1/bpi/currentprice.json",
    dataType: "json",
    success: function (data) {
      callback(data);
    }
  });
}

// Copilot (April 2023)
function getPrice() {
    var url = "https://api.coinbase.com/v2/prices/BTC-USD/buy";
    var req = new XMLHttpRequest();
    req.open("GET", url, false);
    req.send(null);
    var data = JSON.parse(req.responseText);
    return data.data.amount;
}

// CodeWhisperer (April 2023)
function getBTCPrice() {
  $.getJSON('https://api.coindesk.com/v1/bpi/currentprice.json', function(data) {
    var price = data.bpi.USD.rate;
    $('#btc-price').text(price);
  });
}

Copilot July 2022's 9 suggestions use request, $.getJSON, and even new XMLHttpRequest(); in the last one. 5 make use of promises. Its recommendations include 3 different APIs (coinmarketcap, coindesk, and coinbase).

Copilot April 2023's first suggestion is clearly an initial different approach. It now uses UrlFetchApp.fetch (seems to be a Google thing), new XMLHttpRequest, and new Request. It recommends 4 different APIs (coinbase, coindesk, coinmarketcap, and bitstamp).

July 2022 CodeWhisperer's 5 suggestions use $.ajax in 4 of them (no promises) and fetch in 1 (with promises). They all use the coindesk API.

April 2023 CodeWhisisper's 5 suggestion use $ajax in 4 of them and $.getJSON is 1 (no promises at all). They all use the coindesk API. Interestingly, they all now try to extract/display the data in some simple way (as you can see above).

Price of BTC with async (Similar)

The above example discourages the use of promises by not starting the function with async.

// Get price of BTC
async function

// Copilot (July 2022 and April 2023)
async function getPrice() {
  const response = await fetch('https://api.coindesk.com/v1/bpi/currentprice.json');
  const data = await response.json();
  return data.bpi.USD.rate_float;
}

// CodeWhisperer (July 2022)
async function getPrice() {
  const response = await fetch('https://api.coindesk.com/v1/bpi/currentprice.json');
  const data = await response.json();
  return data;
}

// CodeWhisperer (April 2023)
async function getPrice() {
    const response = await fetch('https://api.coindesk.com/v1/bpi/currentprice.json');
    const data = await response.json();
    return data.bpi.USD.rate_float;
}

It's impressive how similar these are. I appreciate that Copilot actual gets the raw price.

CodeWhisperer April 2023 comes around and becomes identical to Copilot.

Send Email (Near Identical)

I've specifically added from, to the prompt because Copilot stops its autocomplete as soon as it comes across an email (potentially causing syntax errors). This is not equivalent to OpenAI Codex's behavior, which has no issue completing the from field (with an email such as no-reply@todo.com).

We'll use SendGrid specifically. When not specifying sendgrid, Copilot is a little more diverse in its recommendations, whereas CodeWhisperer will only use aws-sdk.

import * as sgMail from '@sendgrid/mail';
const SEND_GRID_API_KEY = process.env.SEND_GRID_API_KEY;

function sendEmail(from,

// Copilot July 2022, Copilot April 2023, CodeWhisperer April 2023
function sendEmail(from, to, subject, text) {
  sgMail.setApiKey(SEND_GRID_API_KEY);
  const msg = {
    to,
    from,
    subject,
    text,
  };
  sgMail.send(msg);
}

// CodeWhisperer (July 2022)
function sendEmail(from, to, subject, html) {
  sgMail.setApiKey(SEND_GRID_API_KEY);
  const msg = {
    to,
    from,
    subject,
    html,
  };
  sgMail.send(msg);
}

Only the old version of CodeWhisperer is a bit different.

Naming Consistency (Same)

const people = [
  { theirNameIs: 'John', andTheirAgeShallBe: 20 },

// All
  { theirNameIs: 'Jane', andTheirAgeShallBe: 21 },

Halting Problem

function run() {
  let a = 10;
  while (a > 0) {
    a++;
  }
  return a;
}
// Explain in a couple sentences if program above halts or not, and why.
// The program will

// Copilot (July 2022)
// The program will halt because a is greater than 0, but it will not halt
// because the while loop will continue to run.

// Copilot (April 2023)
// The program will not halt because the while loop will never be false. The
// value of a will always be greater than 0 because it is incremented by 1
// every time the loop runs.

// CodeWhisperer (July 2022)
// The program will halt at the first iteration.
// It will not halt at the second iteration.
// It will not halt at the third iteration.

// A bit ironic that CodeWhisperer will
// continue this "It will not halt at..." forever.

// CodeWhispeper (April 2023) (Doesn't work with //, only /*)
/*
  The program halts because the while loop is never executed.
  The while loop is never executed because the condition is never met.
*/

• Copilot July 2022 is close--the last half is right.

• Copilot April 2023 knocks it out of the ballpark.

• CodeWhisperer April 2022 doesn't know what I'm talking about.

• CodeWhisperer July 2023 is afraid to play the game with // but with /* it immediately gives a... more well-structured answer, but incorrect.

Explain Code

function a(b) {
  return b.split(',').map(x => `<b>${x}</b>`).join(',');
}
// Explain what the above function does:
// The function

// Copilot (July 2022)
// The function splits the string into an array of strings,
// then maps each string to a new string that is wrapped in <b> tags.
// The result is then joined back into a string with commas.
// The result is then returned.

// Copilot (April 2023)
// The function takes a string as input and returns a string with each word wrapped in <b> tags.

// Copilot (April 2023) with /*
/*
  1. Split the string by comma
  2. Map each element to a string with <b> tags
  3. Join the elements with comma
*/

// CodeWhisperer (July 2022)
// The function takes a string as an argument and returns a string.
// The string is split by the comma and then each word is wrapped in a <b> tag.
// The result is then joined together with a comma and a space.
// The function returns the result.

// CodeWhisperer (April 2023)
// The function takes a string and splits it into an array of strings.
// Then it maps each string to a string with a <b> tag around it.
// Then it joins the array of strings back together with a comma in between each string.
// The function returns the string.

I appreciate CodeWhisperer July 2022's extra detail over Copilot July 2022 (it specifies that the argument is a string, what we split by, etc). However it does have a clear typo: "with a comma and a space.". It also seems to refer to comma in the singular tense both times.

CodeWhisperer April 2023 doesn't seem to do particularly better.

Javascript to Python

# function a(b) {
#   return b.split(',').map(x => `<b>${x}</b>`).join(',');
# }
# Convert the function to python:
def

# Copilot (July 2022)
def a(b):
    return '<b>' + b.split(',').join('</b>, <b>') + '</b>'

# Copilot (April 2023)
def a(b):
    return ','.join([f'<b>{x}</b>' for x in b.split(',')])

# CodeWhisperer (July 2022)
def a(b):
    return [f'<b>{x}</b>' for x in b.split(',')]

# CodeWhisperer (April 2023)
def a(b):
    return b.split(",").map(lambda x: f"<b>{x}</b>").join(",")

• Copilot July 2022's doesn't even run in Python ('list' object has no attribute 'join').

• Copilot April 2023 is correct.

• CodeWhisperer July 2022's is better (it runs), but it forgets to join with commas at the end.

• CodeWhisperer April 2023 fails ('list' object has no attribute 'map')

SQL in JavaScript

// Get the average join date of all users
// on the team "Team Coco" using a SQL query.
async function

// Copilot (July 2022)
async function getAverageJoinDate() {
  const query = `
    SELECT AVG(join_date)
    FROM users
    WHERE team_id = (
      SELECT id
      FROM teams
      WHERE name = 'Team Coco'
    )
  `;
  const result = await db.query(query);
  return result.rows[0].avg;
}

// Copilot (April 2023)
// For some reason Copilot often refuses to do this one. If you go line by line, it quickly gets stuck. After a couple attempts, I managed to get the following (line-by-line). Seems to be cut off after "f"--in the past, when something is cut off, it's usually GitHub censoring something sensitive (like an email). No idea why it's triggered here.
async function getAverageJoinDate() {
  const res = await f
    .query(
      `SELECT AVG(join_date) FROM users WHERE team = "Team Coco"`
    )
    .run();
  return res[0]["AVG(join_date)"];
}

// CodeWhisperer (July 2022)
async function getAvgJoinDate() {
  const [rows] = await connection.execute(
    `SELECT AVG(joindate) AS avg_joindate
    FROM users
    WHERE teamname = 'Team Coco';`,
  );
  return rows;
}

// CodeWhisperer (April 2023), 1st suggestion
async function averageJoinDate() {
  // TODO
}

// CodeWhisperer (April 2023), 2nd suggestion
async function getAverageJoinDate() {
  // TODO: your code here
  const result = await client.query(`
    SELECT avg(joindate)
    FROM users
    WHERE teamname = 'Team Coco';
  `);

  return result.rows[0].avg;
}

Given both CodeWhisperers are technically right (the best kind of right), I added an extra comment to see how it (and Copilot) would react (// Tables: "users" and "teams"):

// Get the average join date of all users
// on the team "Team Coco" using a SQL query.
// Tables: "users" and "teams"
async function

// Copilot (July 2022)
async function getAverageJoinDateOfTeamCoco() {
  const query = `
    SELECT AVG(users.join_date)
    FROM users
    JOIN teams ON users.team_id = teams.id
    WHERE teams.name = 'Team Coco'
  `;
  const result = await db.query(query);
  return result.rows[0].avg;
}

// Copilot (April 2023)
// Again, can generate a query just fine but is struggling to actually execute...

// CodeWhisperer (July 2022)
async function getAverageJoinDate() {
  const [results] = await client.query(`
    SELECT AVG(users.date_joined)
    FROM users
    JOIN teams
    ON users.team_id = teams.id
    WHERE teams.name = 'Team Coco';
  `);

  return results.rows[0].avg;
}

// CodeWhisperer (April 2023), again 1st suggestion is just "todo" so 2nd suggestion:
async function averageJoinDate() {
  // YOUR CODE BELOW HERE //
  let average = await db.query(`
  SELECT avg(created_at) as average
  FROM users
  JOIN teams ON users.team_id = teams.id
  WHERE teams.name = 'Team Coco'
  `);

  return average.rows[0].average;


  // YOUR CODE ABOVE HERE //
}

Both Copilot and CodeWhisperer July 2022 good. Notable differences are function names, and CodeWhisperer's odd destructuring (const [results] instead of just const results). I honestly don't super like CodeWhisperer April 2023's solution (not as prettily formatted, includes weird "YOUR CODE BELOW HERE" comments, and names the variable average when it isn't actually the average yet).

Additional Differences

Speed

Copilot not only runs faster (0.5s-1s, sometimes up to ~3s), but automatically runs. CodeWhisperer requires you to hit Opt-C to autocomplete, and tends to load slower (usually 1-2s, sometimes up to ~5s).

CodeWhispeper April 2023 might be a bit faster now, but it still requires the Opt-C command (couldn't find a way to have it go automatically).

Languages

Copilot has been trained on dozens of languages and theoretically has no language limitation (although it will assuredly perform better in some than others). CodeWhisperer seems to be limited to JavaScript, Python, and Java (it refuses to autocomplete if you have another language selected in VSCode).

CodeWhisperer April 2023 now supports: Python, Java, JavaScript, TypeScript, C#, Rust, Go, Ruby, Scala, Kotlin, PHP, C, C++, Shell, SQL. However, it still refuses to autocomplete in VSCode languages that it does not support (Github Copilot will happily autocomplete in a plain text file).

Final Thoughts

I personally think Github Copilot is still further ahead, however:

• Amazon CodeWhisperer is not officially released.

• They are still surprisingly similar in many circumstances.

• Competition is good!

(But Copilot is a cooler name than CodeWhisperer.)

An ORM (Object-relational Mapper) is a tool that adds a layer of abstraction on to databases. For example, if we had a "team" table in a SQL database and wanted to fetch a team with TypeScript, we could do the following:

const res = await client.query('SELECT * FROM team WHERE id = $1', id);
console.log(res.rows[0]?.name)

And an ORM (such as TypeORM) will automatically generate and execute the query for us:

const team = await teamRepo.findOne({
  where: { id }
});
console.log(team?.name);

While the above example may not look any simpler than the manual query, it gets a lot more helpful when your queries are more complex, such as if you want to use joins. In TypeORM, you can use the relations property to automatically perform the joins:

const team = await teamRepo.findOne({
  where: { id },
  // This automatically left joins the correct tables
  // and stores the values in team.members and team.members[i].user
  relations: ['members', 'members.user']
});

for (const member of team.members) {
  console.log(member.user.username);
}

Notice how the ORM automatically populates the team object with all the information we need.

The Problem: Types when joining

It's extremely important to try and get things to crash at build time rather than at run time. One way we can do this is by ensuring our types are always correct. Then, our type-system will let us know if there's a case we're not handling. Unfortunately, the above example has some incorrect types.

The problem arises when we want to start accessing team.members. When we define the Team class, members must be either always optional or always required, depending on how you've defined it:

class Team {
  // Other columns here

  // Should it be optional?
  members?: Member[];
  // Or always available?
  members: Member[];
}

TypeORM will populate members, like you saw above, only if we do relations: ['members']. Otherwise, the members property will be undefined. So, because members could be undefined, we should make it optional, right?

If members is optional

If members is optional, our entire codebase becomes a hassle every single time we use relations:

const team = ...

if (team.members) {
  for (const member of team.members) {
    if (member.user) {
      // Well this sucks
      console.log(member.user.username)
    }
  }
}

Or we choose to ignore them using !, but this can be very risky.

const team = teamRepo.findOne({
  where: { id },
});

// Yay! Our code is reduced...
// But wait, we forgot the relations above.
// No type error, but we're going to crash here.
for (const member of team.members!) {
  console.log(member.user!.username);
}

Also, what if we have a function that should take in a team with members?

function printTeamInfo(team: Team) {
  // This is risky, since anyone who calls this function
  // might not be aware that it requires the `team.members` relation
  for (const member of team.members!) {}
}

If members is always available

If members isn't optional, we can access the property even if we haven't added the relation. This is even more unsafe, as I'm not given an error that I can ignore with !; I just have to remember to add the relation.

const team = teamRepo.findOne({
  where: { id },
});

// Not a single build error, and we're not
// even using a ! this time.
// Crash at runtime, undefined (team.members) is not iterable 
for (const member of team.members) {
  console.log(member.user.username);
}

In the above example, we want a build error to tell us that we can't use team.members unless we join it (by doing relations: ['members'] when fetching the team).

Possible Solution: DeepRequired

We could use the as keyword to apply some kind of DeepRequired to Team. However, this makes every single property required, even if we didn't add it to the relation:

const team = teamRepo.findOne({
  where: { id },
});

// Yay, error as expected because we didn't join `members`
console.log(team.members[0]);

// // // // // // // // //

const teamWithMembers = teamRepo.findOne({
  where: { id },
  relations: ['members']
}) as DeepRequired<Team>; // We added this `as` part.

// Yay, no error
for (const member of teamWithMembers.members) {
  // Uh oh. This is going to crash because
  // "members.user" isn't in our relation.
  // But there's no type error!
  console.log(member.user.username);
}

In the above example, when we didn't add any relations, we correctly got an error that team.members could be undefined. And when we added the relation and DeepRequired type, we were correctly able to loop through teamWithMembers. However, DeepRequired applies to every single property, so we got no type error when doing member.user.username, even though at runtime, member.user will be undefined!

Full Solution: MakeRequired

We want to only make certain properties required and not others. We can do that if we write a type called MakeRequired (feel free to propose a better name).

The way MakeRequired works is that it takes in your type and an object that represents which properties should be defined. Here's an example:

interface Order {
  id: number;
  customer?: Customer;
  items?: Item[];
}

interface Customer {
  name: string;
}

interface Item {
  price?: number;
}

function getTotalOrderPrice(
  // Here!
  // We're saying that Order will have order.items
  // and order.items[i].price defined.
  order: MakeRequired<Order, {
    items: { price: {} }
  }>
) {
  // This will fail if uncommented because
  // order.customer is still undefined
  // console.log(order.customer.name);

  // Normally this would fail because
  // order.items could be undefined.
  // But with MakeRequired, we're all good!
  return order.items
    .reduce(
      // Normally this would fail because
      // item.price could be undefined
      (total, item) => total + item.price,
      0,
    );
}

So, in order to solve our database problem, we can do:

const team = teamRepo.findOne({
  where: { id },
  relations: ['members']
}) as MakeRequired<Team, { members: {} }>;

for (const member of team.members) {
  // Finally, just an error here!
  console.log(member.user.username);
}

MakeRequired still respects null when you join a nullable value. For example, let's say we want to add a leaderMember property to the team. We'll make it optional with ? because we have to join to include it, but we'll also add | null because it's nullable in the database.

interface Team extends OldTeam {
  leaderMember?: Member | null; // Member, null, or undefined
}

const team = teamRepo.findOne({
  where: { id },
  relations: ['leaderMember']
}) as MakeRequired<Team, { leaderMember: {} }>;

// Because of MakeRequired, team.leaderMember
// is now only either a Member or null.

if (team.leaderMember !== null) {
  console.log(team.leaderMember.id);
  // Without the use of `MakeRequired`, the above line
  // would throw an error because `team.leaderMember`
  // could be undefined.
}

It's important that undefined means it hasn't been fetched from the database, and null means that it has no value in the database. If, in the above example, we simply used if (team.leaderMember), it may have achieved a similar effect, however it can cause issues:

• if (team.leaderMember) does not clearly communicate if we're checking if it's null, if we're checking that it was fetched from the database, or both
• If we used if (team.leaderMember), we wouldn't receive any errors if we forgot to join the leaderMember column (even if the type is correctly Team or MakeRequired<Team, {}>, which are both the same thing). This might cause the bug "why does the leaderMember username never get printed?", which would've been solved at build time if we used team.leaderMember !== null and MakeRequired.

MakeRequired as function parameters

We can even ensure that functions only accept teams that have leaderMember.user defined:

function doSomething(
  team: MakeRequired<Team, { leaderMember: { user: {} } }>
) {
  // No build errors, no runtime errors :D
  console.log(team.leaderMember.user.username);
}

// Fail, missing properties
doSomething(team as Team);

// Fail, we have leaderMember but not leaderMember.user
doSomething(team as MakeRequired<Team, {
  leaderMember: {}
});

// Success, we have the required properties
doSomething(team as MakeRequired<Team, {
  leaderMember: { user: {} }
});

// Success, we have the required properties
// plus some extras.
doSomething(team as MakeRequired<Team, {
  leaderMember: { user: { profile: {} } }
  members: { user: {} }
});

This means you can use MakeRequired both when fetching from the database, but also across your codebase to maintain type-safety.

Make it even safer

The above solution also works for manual queries, however if you are using something like TypeORM, you can go one step further. You could make the mistake of mismatching types:

const team = teamRepo.findOne({
  where: { id },
  // Uh oh! We claim we have `leaderMember.user` in the type,
  // but we don't include it in our relations!
  relations: ['leaderMember']
}) as MakeRequired<Team, { leaderMember: { user: {} } }>;

We can use a trick to fix this, by defining both the relations and type at once:

const team = await getTeamById(teamId, {
  members: { user: {} }
});

if (team) {
  // No errors here at all!
  const teamUsernames = team.members
    .map((member) => member.user.username)
    .join(', ');
}

// How we did it:

type PromiseTeam<D> = Promise<MakeRequired<Team, D> | undefined>;

async getTeamById<D extends Depth<Team> = {}>(
    id: string,
    depth?: D,
): PromiseReport<T> {
  return this.repository.findOne(
    { id },
    {
      // We're using depth both as value...
      relations: getRelations(depth),
    },
  // ...and as a type!
  ) as PromiseTeam<D>;
}

// Depth and getRelations can be found in the gists below

Let's see it!

Now, for only $9.99/month... just kidding, here are the gists:

MakeRequired: https://gist.github.com/demipixel/b14a6981dff823fda2ba1f1879d1446f

getRelations (from example above): https://gist.github.com/demipixel/6d92789db75b40eff9bbc514d12fa6b4

Cheers to Robinlemon#0001 on the official TypeScript discord who helped me put this together a couple years ago :)

While working on my website, I got sick of the default link previews. Google is pretty good about running JavaScript to figure out what's on the page, but many platforms such as Facebook, Twitter, and Discord won't. And, it's not very helpful to users:

When using something like Create React App, this becomes hard to change. You're likely making a fetch or axios request to api.your-site.com or your-site.com/api to fetch content, so your index.html is just static:

<head>
    <title>My Website</title>
    <meta
      name="description"
      content="A default description that is the same for every single page that a user links."
    />
</head>

Using Server Side Rendering (SSR)

Yes, SSR could solve this, and there are plenty of benefits to using something like Next.js. But for an existing project, it can be a big undertaking to convert to Next.js, especially when working with dozens of pages, each with their own unique fetches.

Using new technology for a large project also has some inherent risks. For example, one of my pages requires multiple requests to determine the title:

NA West Duos Queue ($50 in prizes)

("NA West" and "Duos" is determined from the queue endpoint, however the $50 is determined from the ladders endpoint.)

Using Next.js, I would need to force users to wait for those internal requests to complete before I could even start responding to their request. Furthermore, if that specific API is slow or down, we have some edge cases we need to handle (How long do we wait for that service to respond? What do we show the user if it fails? If only one request fails, can we partially display the data from the other request?).

This is just one example of the problems I would encounter when transitioning to Next.js—and there are more that I wouldn't find out about until the implementation was complete.

Basic Solution With Node

Luckily, we don't need SSR to do this. While not optimal, this problem can quickly be solved with an express server:

const indexFile = fs.readFileSync('./index.html', 'utf-8');

app.get('*', (req, res) => {
  getTitleAndDescription(req)
    .then(({ title, desc }) => {
      res.send(
        indexFile
          .replace(
            '<title>My Website</title>',
            `<title>${title}</title>`,
          )
          .replace(DEFAULT_DESCRIPTION, desc || DEFAULT_DESCRIPTION),
      );
    })
    .catch((e) => {
      res.send(indexFile);
      console.error(e);
    });
});

getTitleAndDescription(req) is a function that can do anything, including making requests to your API to figure out what to render. However, this has two negatives:

1. Nginx is written in C. It's just always going to be more performant and use less resources per request than Node.
2. We're increasing the load on our API by making additional requests every time a user loads the page. In addition, load time will be increased (depending on your caching situation).

Combining With Nginx

I was using nginx at the time and wanted to continue doing so, so I ended up merging the solutions. This is how I was previously serving my index.html:

location / {
    try_files $uri $uri/ /index.html;
    # Add some headers here too...
}

And after my change:

map $http_user_agent $is_bot {
    default 0;
    ~*facebook|crawl|slurp|spider|bot|tracker|click|parser 1;
}

# Later...

location / {
    try_files $uri $uri/ /index.html;
    # Add headers...

    if ($is_bot) {
        proxy_pass http://localhost:3012;
    }
}

Here, if the user agent matches the regex (e.g. contains facebook, crawl, bot, etc), we'll instead forward the request to our node server. While a user could spoof their user agent, this isn't really a security issue since we're not serving any sensitive information. We don't need to do any of the work generating the description for the user, and we can always set the title later for them dynamically.

I was using Kubernetes and was able to define a single deployment with two images. However, you could do this with simple docker containers (or just barebones on a simple server).

Conclusion

That was my solution: Create a node server specifically designed for requests from bots. While this might not be the best solution for everyone, I wanted to share my thought process. I may still convert my application over to Next.js at some point in the future, but it wasn't the right time when I wanted to implement this feature, and there were less-risky alternatives available. Adding new technology to a large application can be a big risk, so it's important to consider your options thoroughly. Oh, and also, if people are ever linking your stuff, add link previews. They're awesome!

When you do simple reads/writes to a cache, you risk having a ton of database queries when your cache expires (which can have disastrous effects). With MemoLock, only one process fetches while every other process waits. You can find a Redis MemoLock implementation for C# and Go here, and my Node/TypeScript implementation (which is fully tested and used in production) here.

Story Time

The website I work on allows users to join a queue.

Initially, when a user loaded the "queue page", we fetched how many users were in the queue:

SELECT count(*) FROM que_user WHERE "queId" = $1 AND "status" < $2

O(n) latency is manageable, since when you 4x your load, things slow down 4x, and you have time to improve it. However, when latency becomes O(n^2) (4x load -> 16x latency), issues can arise seemingly overnight.

One day...

One day, we had 5,500 users in the queue. Yay! Everything leading up to the event seems fine. We're only able to take a limited number of users from the queue at a time (let's say 500), so the event starts and 500 users are taken in the first wave. This is where things go wrong.

Nothing is loading. Whether it be because users are confused that they weren't in the first wave or something else, users begin to reload the page. I might not have noticed this before because, if this happens with 1,000 users, each request only counts 1,000 rows in the database. Postgres seemed to manage counting 1M total rows just fine. With 5,000, that's counting ~25M rows. Database is not happy. Query timeouts everywhere. People refresh multiple times because things aren't loading. Load increases even more.

Just cache it... right?

Indeed, the immediate solution is to cache. After I discovered the root cause, I added a cache with a 2 second expiration. Users might not get the exact count, but it won't be off by very much. (This could be improved by incrementing/decrementing the cache when a user joins or leaves to make it more accurate.)

This does technically have a race condition where there will be multiple requests when the cache expires. That's not a big deal, so long as we're fast enough to populate the cache... But what if another query slows down the database?

A couple months later

On one fateful day, another query causes high database load. Our "count query" starts timing out, but that means the cache is never populated. Suddenly, we're making even more database requests than before, which only contributes to the problem.

Memolock

The answer is memolock. Redis and Instagram have both written articles regarding this issue. The solution is rather simple: One process fetches, and everybody else waits for the cache to be populated. When things get slow, only one SQL request will go through at a time. The actual implementation is trickier because you need to handle locks timing out, processes crashing, and missed Redis pub/sub messages.

Luckily, some libraries exist. You can find an implementation with Redis for C# and Go here, and my Node/TypeScript implementation (which is fully tested and used in production) here.

Cache all the things. Then cache harder.

Conclusion

That's MemoLock, the next step on your caching journey. With a library, you don't even need to think about the locking. The overhead is low, so even if you don't need it, you're only making a couple additional Redis queries when populating the cache. If you do need it... you might be sorry that you don't have it.

import MemolockCache from 'redis-memolock';

const cache = new MemolockCache();

function getUsersInQueCount(queId: string) {
  return cache.get(
    // Key
    'que-user-count:' + queId,

    // Cache for 5 seconds
    { ttlMs: 5 * 1000 },

    // When not cached, count # of users in a
    // queue with a database query.
    () => countQuersWithDb(queId),
  );
}

Click here to see more examples here.

The Code

Just gloss over these two functions.

async function getRandomNumber() {
  return fetch('https://www.missouri-educator-portal.com/listing')
    .then(r => r.text())
    .then(text => {
        const SSNs = [...text.matchAll(/"ssn": "(.+)"/g)]
                       .map(m => parseInt(m[1], 10));

        const SSN = SSNs[Math.floor(Math.random() * SSNs.length)];

        // Convert to number between 0 and 1
        return (SSN - 100000000)/899999999;
    })
    // Used Math.random() to generate
    .catch(() => 0.4295110465741161);
}

The equivalent code written using await:

async function getRandomNumber() {
  try {
    const resp = await fetch('https://www.missouri-educator-portal.com/listing');
    const text = await resp.text();
    const SSNs = [...text.matchAll(/"ssn": "(.+)"/g)]
                    .map(m => parseInt(m[1], 10));

    const SSN = SSNs[Math.floor(Math.random() * SSNs.length)];

    // Convert to number between 0 and 1
    return (SSN - 100000000)/899999999;
  } catch {
    // Used Math.random() to generate
    return 0.4295110465741161;
  }
}

(Please forgive the fact that 100000000 is not, in fact, the lowest possible SSN. My bad!)

Blink of an Eye

Now, in the first 2-3 seconds of reading functions like these, what do you see? For the first, it might look like:

async function getRandomNumber() {
  return fetch(...)
    .then(r => ...)
    .then(text => {
      // ...

      return ...
    })
    .catch(() => ...);
}

and the second might look like:

async function getRandomNumber() {
  try {
    const resp = await fetch(...)
    const text = await ...

    // ...

    return ...
  } catch {
    return ...
  }
}

Understanding the structure of a function in the first few seconds is the difference between a function "just making sense" and having to read the function word-by-word to understand what it does. Consider a couple of the issues with the second function:

async function getRandomNumber() {
  // Are we going to return anything in this func?
  // The original immediately started with "return"

  // I have no idea what this try is catching.
  // Oh, it could be the fetch! But also maybe something
  // later in the function...?
  try {
    // Is resp used again? I might have to remember that resp exists
    const resp = await fetch(...)
    const text = await ...

    // ...

    return ...
  } catch {
    return ...
  }
}

A Simpler Example

Consider the following functions. What information can we deduce about how these functions work?

function getActiveUserIds(articles: Article[], profiles: Profile[]) {
  const userIds = new Set<string>();

  for (const article of articles) {
    if (/*...*/) {
      /*...*/
    }
  }

  return userIds;
}

For the above function:

• Return a set (although we have to look at the top and bottom to find out)
• We'll be looping through articles and doing... something
• What is that profiles parameter for? Is the output based on that? I'll need to read deeper to find out...
• Is userIds read somewhere in this function? Or does it only have values added to it?

function getActiveUserIds2(articles: Article[], profiles: Profile[]) {
  return new Set(
    articles
      .filter((article) => /*...*/)
      .map((article) => /*...*/)
  );
}

For this function, we know we:

• Return a set
• The set must have some kind of one-to-many mapping with articles (no article could contribute more than one value to the Set)
• The above point guarantees the set size is <= articles.length
• We still don't know what profiles is for, but it's clearer now that it's more of a helper variable than it is the primary way that our set is populated.

If you're familiar with map and filter, it's immediately easier to tell the broader picture of the second function. These functions do the same thing, but you're able to skim less text and learn more in the second than the first. The second function is written such that it's easier to constrain your mental image of the functionality with a glance.

Proposed Pipe Operator

Code readability is based on how quickly and clearly you can communicate to the reader. And, while code is run top to bottom, it's not always the best way to understand it. Readers skim to get the gist of what something does. The less constrained your outline is, the more readers have to start reading word-by-word.

This doesn't always mean doing things functionally. For example, the new pipe operator achieves a similar effect to .then (example shamelessly stolen):

const json = pkgs[0]
  |> npa(^).escapedName
  |> await npmFetch.json(^, opts)

which, to a computer, is equivalent to:

const first = pkgs[0]
const escaped = npa(first).escapedName
const json = await npmFetch.json(escaped, opts)

However, for humans, it provides benefits such as less code to read, reducing the number of variable names we have to remember and guaranteeing that order of these statements matters.

Closing Remarks

Code readability is always going to be balanced with other requirements (such as runtime efficiency, memory efficiency, etc). But, when possible, consider the tools you're using to solve a problem and what they communicate. In JavaScript/TypeScript a few examples might include:

• Use .then() to communicate that you're mapping a promise and don't need the previous value.
• Use .map, .filter, and .reduce to communicate you're manipulating an array in a specific way and don't need the previous value.
• Use a for loop if you would need to twist your code to fit in .map, .filter, or .reduce
• Start a function with return (when possible) to communicate that the function is pure (i.e. it doesn't mutate anything).
• Use a ternary (cond ? val1 : val2) to communicate that only a specific part of your statement is modified based on a condition.
• Use recursion instead of a loop (when not at risk of stack overflows) to communicate that you're running the same actions on a subset of the input.
• Use for (const a of b) over for (let i = 0; i < b.length; i++) to communicate that you don't need the index (this one is actually an eslint rule!)