See Github gist for the code.

I recently had to create a user-interface (UI) without the backend endpoints in place. The focus was on making the UI as responsive as possible so that the user can tell when an action is underway.

This mostly means that when an AJAX call is made, the UI should indicate so, and update correspondingly when the call completes.

To help with the development of the UI, I created a function to simulate AJAX calls. The function is able to:

• accept a delay (in milliseconds) to simulate the delay from making an actual AJAX call
• accept a probability of failing to simulate when an AJAX call fails
• return a supplied payload

The TypeScript code is below (see the gist for the complete code sample with the docstring):

export async function delay<T>(
  timeout: number,
  probability?: number,
  result?: T
): Promise<T> {
  return new Promise<T>((resolve, reject) => {
    setTimeout(() => {
      if (!probability || probability < 0 || probability > 1) {
        resolve(result);
        return;
      }

      const hit = Math.random();
      if (hit < probability) {
        resolve(result);
      } else {
        reject(
          `Placeholder rejection (${Math.round(
            hit * 100
          )}%) - this should NOT appear in production`
        );
      }
    }, timeout);
  });
}

To use this function:

async function handleButtonClick() {
  // Update the UI to show a loading indicator.

  try {
    // Make the call take 3 seconds, with a 10% chance of failure,
    // and return an array of users.
    const result = await delay(3000, 0.9, [
      {
        email: 'user1@example.com',
        username: 'User 1',
      },
    ]);

    // Update the UI when the call completes succesfully.
  } catch (err: any) {
    // Update the UI when the call fails.
  }
}

The JavaScript version of the same function below:

export async function delay(timeout, probability, result) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (
        !probability ||
        typeof probability !== 'number' ||
        probability < 0 ||
        probability > 1
      ) {
        resolve(result);
        return;
      }

      const hit = Math.random();
      console.log(hit, probability);
      if (hit < probability) {
        resolve(result);
      } else {
        reject(
          `Placeholder rejection (${Math.round(
            hit * 100
          )}%) - this should NOT appear in production`
        );
      }
    }, timeout);
  });
}

TL;DR​

This example here is one manifestation of such problems seen with TypeScript. Here, the problem occurs when FormData is used together with Object.fromEntries. E.g.

const form = evt.target as HTMLFormElement;
const formData = new FormData(form);
const data = Object.fromEntries(formData);

The IDE shows a wriggly line on formData with the following message:

No overload matches this call.
 Overload 1 of 2, '(entries: Iterable<readonly [PropertyKey, any]>): { [k: string]: any; }', gave the following error.
   Argument of type 'FormData' is not assignable to parameter of type 'Iterable<readonly [PropertyKey, any]>'.
     Property '[Symbol.iterator]' is missing in type 'FormData' but required in type 'Iterable<readonly [PropertyKey, any]>'

Two things to check:

1. Ensure that in tsconfig.json, the lib option contains minimally these two values in the array: DOM and DOM.Iterable (case-insensitive).
2. If the tsconfig.json file contains the references option, check the lib option in the locations specified under references as well.

Introduction​

TypeScript is a language that is based on JavaScript. Its website says that it is "JavaScript with syntax for types".

Indeed, after switching to use TypeScript, I've had the number of runtime issues reduced drastically compared to using JavaScript.

JavaScript has gained widespread adoption due in large part to the ease in which beginning developers can get started. The popularity also meant that different browsers have different JavaScript runtimes that support different versions of the language (though that's less of a problem nowadays since many have chosen to use the Chromium base). There are also various Web APIs that are implemented in JavaScript.

This wide adoption truly speaks for the flexibility of the language but because it is so open, it can be difficult to identify exactly which API and properties/functions are available.

This is where TypeScript benefits the developer greatly. Its typed nature means that integrated development environments (IDEs) can expose productivity enhancements such as code hints and autocompletion.

What's the issue?​

For TypeScript to support the differing levels of the specification as well as the myriad libraries that are now available in JavaScript, it requires the use of a config file that is named tsconfig.json which is typically found in the root of the source project folder.

Learning all the options in tsconfig is an endeavour in and of itself.

I'd bet that most TypeScript developers (like, the overwhelming majority), myself included, know the syntax well, but not the configuration of tsconfig. In our defence, it is rare that tsconfig.json ever needs to be modified in the lifetime of a project once it is set up.

Having the correct options set will yield huge productivity benefits for the developer. Conversely, a wrongly configured file can create unexpected headaches.

One common problem is the error hints shown in the IDE.

Problem 1​

I have two machines, one Linux and one MacOS (M1), that I develop on.

With the same codebase on one machine, everything works fine. When I check out the repository on the other machine, I see this wriggly line error in VS Code.

The first thought that comes to mind is that there must be some issues with tsconfig.json. It's not a pleasant thought. Trying to fix issues with tsconfig is a trial-and-error most of the time.

Luckily, the cause of the error is sometimes very simple. In this case, the dependencies have not been installed. This is indicated by the wrigglies on the import statements like so:

Errors on all the import statements of npm packages mean that the dependencies have not been installed yet. In this case, the resolution is to simply install the dependencies first.

Solution to problem 1​

When you are stuck on some problem it can be easy to forget to install the dependencies on a freshly checked out codebase.

Furthermore, if there are no import statements in the file with the error, it is even less obvious.

This is why I've adopted the heuristic of always running npm install/pnpm install first.

Problem 2​

I am working on two TypeScript projects - one is a Next.js project, and the other is a codebase for a Chrome extension.

In both projects, I have the following code:

const form = evt.target as HTMLFormElement;
const formData = new FormData(form);
const data = Object.fromEntries(formData);

The code looks fine in the Next.js project.

But, in the Chrome extension project, the IDE complains:

Now, this happens after installing the dependencies so it's no longer just an easy fix of installing the dependencies.

Back to basics then. So the error says that Argument of type 'FormData' is not assignable to parameter of type 'Iterable<readonly [PropertyKey, any]>'.

This seems to suggest that the same FormData class in the extension codebase is of a different version from that in the Next.js codebase. I'm guessing this has to do with the version of TypeScript target or library specified in tsconfig.json

Looking at target, the version stated in Next.js (es5) is even older than the version in the extension codebase (ES2020). target can't be the problem then.

How about lib? In Next.js we're seeing esnext whereas in the Chrome extension codebase, we're seeing ES2020. Could this be it?! esnext refers to the latest specifications so this should be the problem right?!

Attempted solution 1 to problem 2​

So I changed lib. From this:

"target": "ES2020",
"useDefineForClassFields": true,
"lib": ["ES2020", "DOM", "DOM.Iterable", "WebWorker"],
"module": "ESNext",

to this:

"target": "ES2020",
"useDefineForClassFields": true,
"lib": ["ESNext", "DOM", "DOM.Iterable", "WebWorker"],
"module": "ESNext",

After saving this, the error persists.

"Okay," I'm thinking. "Let's just restart the TypeScript server for the change to take effect."

Nope. Error still shows in the IDE.

Attempted solution 2 to problem 2​

Alright. Let's inspect the other options in tsconfig.json.

Nothing stands out as to what could be the cause. So I copied the values over to make the options identical in both projects. No bueno.

Okay. Since the configurations are all the same already, let's take a closer look at the problem. It says that Property '[Symbol.iterator]' is missing in type 'FormData' but required in type 'Iterable<readonly [PropertyKey, any]>'. So this means that the FormData class used in the extension codebase does not have the properties to be Iterable. Why?

Attempted solution 3 to problem 2​

Ctrl/Cmd-clicking on the FormData class reveals two differences:

Code in Node.js

Code in extension codebase

In the Node.js codebase, there is a reference to lib.dom.iterable.d.ts whereas in the extension codebase, this is not present.

This makes sense since what is missing is the iterable property of FormData.

The second difference is that the Node.js codebase references @types+react@18.2.73 whereas the extension codebase references @types+react@18.2.48.

Could that be it?

Let's compare the package.json files of both codebases:

So there is a disparity between the versions. I'm not exactly sure what is going on, so I'm installing the latest version of @types/react for the extension codebase:

pnpm add -D @types/react@latest

After restarting the TS Server, the wriggly is still there. 😡

Attempted solution 4 to problem 2 - StackOverflow​

Next, I took to StackOverflow (being sceptical that AI could solve this problem).

This answer that I've found is answering the question why VS Code is not honouring the options in tsconfig.json. I'm not entirely sure this is the same problem, but at this stage, I'm willing to try anything.

So I added "typescript.tsdk": "node_modules/typescript/lib" to .vscode/settings.json.

After restarting TS Server, the problem persists. 🤬

Attempted solution 5 to problem 2 - ChatGPT​

Alright. Next up, AI. Let's see what this jobs-killer, revolutionary technology can do in this case.

Me:

VS Code is not reading lib.dom.iterable.d.ts for my TypeScript project. How can I solve this problem?

ChatGPT gave a few suggestions. Let's break them down:

ChatGPT:

To resolve the issue of VS Code not reading lib.dom.iterable.d.ts for your TypeScript project, follow these steps:

1. Check TypeScript Version:

Ensure you are using an up-to-date version of TypeScript. Update TypeScript globally and locally in your project if necessary.

npm install -g typescript
npm install typescript --save-dev

Huh. The extension is already using a newer version of TypeScript.

ChatGPT:

2. Update VS Code:

Make sure you are using the latest version of Visual Studio Code. Updates often include fixes for issues like this.

Well, I'm already on the latest version on both of my machines, and the same problem occurs on both of them.

ChatGPT:

3. Check tsconfig.json:

Ensure your tsconfig.json file includes the necessary library references. Your tsconfig.json should have a section like this:

{
  "compilerOptions": {
    "lib": ["dom", "es2015", "dom.iterable"]
  }
}

This explicitly includes dom.iterable as part of the TypeScript compilation process.

Yes, that's the first thing I've checked. (See Attempted solution 1)

ChatGPT:

4. Ensure TypeScript is Correctly Configured in VS Code:

Sometimes, VS Code may use a different TypeScript version than the one installed in your project. To ensure VS Code uses the correct version:

• Open the command palette (Ctrl+Shift+P or Cmd+Shift+P).
• Type and select "TypeScript: Select TypeScript Version".
• Choose "Use Workspace Version" to make sure it uses the TypeScript version specified in your project.

Non-starter. No such option.

Let's give it the benefit of the doubt - it might referring to a Workspace setting.

Oh! Tried this already. 😐

ChatGPT:

5. Reload VS Code Window:

After making changes to tsconfig.json, reload the VS Code window to ensure the new configuration is applied.

• Open the command palette and type "Reload Window", then select it.

Reload VS Code? I had been using Windows in my previous life. Of course I had reloaded VS Code already.

ChatGPT:

6. Verify File Presence:

Ensure the lib.dom.iterable.d.ts file is present in the node_modules/typescript/lib directory. If it's missing, reinstall TypeScript:

npm install typescript --save-dev

Yup it's there. And still using the setting "typescript.tsdk": "node_modules/typescript/lib".

What if I remove this line? Problem's still there. 😤

ChatGPT:

7. Check for Extensions:

Some extensions can interfere with TypeScript's configuration. Try disabling extensions one by one to see if any are causing the issue.

Not useful. I'm using the same editor with the same set of extensions on two projects giving two different behaviour.

ChatGPT:

8. Clear VS Code Cache:

Sometimes, clearing the TypeScript server's cache can resolve issues. You can do this by:

• Deleting the .vscode directory in your project.
• Restarting VS Code.

By following these steps, you should be able to resolve the issue of VS Code not reading lib.dom.iterable.d.ts in your TypeScript project.

Restarted already lah!

Attempted solution 6 to problem 2 - Meta AI​

Me:

VS Code is not reading lib.dom.iterable.d.ts for my TypeScript project. How can I solve this problem?

Meta AI:

Here are some steps you can take to troubleshoot why VS Code is not reading lib.dom.iterable.d.ts for your TypeScript project ¹ ² ³ ⁴:

• Ensure that your .d.ts file is open in your VS Code window for the changes to take effect.
• Make sure your tsconfig.json file is in the root directory, as VS Code will only read files in this directory.
• Try running the command "Reload Window" to see if this resolves the issue.
• Check that your .d.ts file is in the correct directory and that the file path is correct in your tsconfig.json file.
• Make sure that you are not skipping the library check in your tsconfig.json file by setting "skipLibCheck": false.
• If you are still having trouble, try restarting the TypeScript server or VS Code to see if this resolves the issue.

The only things that are new as suggested by Meta AI are the "Reload Window" command and setting "skipLibCheck": false. Both of which didn't solve the problem.

Attempted solution 7 to problem 2 - good ol' Google Search​

lib.dom.iterable.d.ts not read by vs code

First result from StackOverflow had many of the attempted solutions listed.

Time for something more drastic. I closed the editor, removed the entire node_modules directory, ran pnpm install, then started the editor back up again.

No luck 🫤

Attempted solution 8 to problem 2 - include​

This is the "I'll try anything" stage.

The include field in tsconfig.json did not specify the .ts and .tsx files in the extension codebase. Maybe the configuration is sensitive that way?

Result: Nope. ❌

Attempted solution 9 to problem 2 - exclude​

Another "I'll try anything" attempt.

I noticed that in the Next.js project, the node_modules directory was excluded.

So in this attempt, I'm adding node_modules to exclude:

"exclude": ["src/**__tests__/*", "node_modules"]

Of course this didn't work — I don't expect it to. 🙄

Attempted solution 10 to problem 2 - project references​

Grasping at straws now.

I noticed another difference between the two tsconfig.json files.

The tsconfig.node.json file in the extension codebase looks like this:

{
  "compilerOptions": {
    "composite": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "paths": {
      "~src/*": ["./src/*"],
      "~assets/*": ["./src/assets/*"],
      "~pages/*": ["./src/pages/*"],
      "~public/*": ["./src/public/*"]
    },
    "allowSyntheticDefaultImports": true
  },
  "include": ["vite.config.ts", "src", "scripts", "plugins"]
}

Huh. There's no lib option here. Could that be it? What if I added lib to this config file?

{
  "compilerOptions": {
    "composite": true,
    "lib": ["DOM", "DOM.Iterable"],
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "paths": {
      "~src/*": ["./src/*"],
      "~assets/*": ["./src/assets/*"],
      "~pages/*": ["./src/pages/*"],
      "~public/*": ["./src/public/*"]
    },
    "allowSyntheticDefaultImports": true
  },
  "include": ["vite.config.ts", "src", "scripts", "plugins"]
}

Took me four hours on a Sunday to figure it out and to write this post but I got it!

For whatever reason, the referenced project (tsconfig.node.json) is the one that VS Code is taking cue from instead of the one at the root (tsconfig.json).

No need for all the changes described in attempted solutions 1 to 8. All that's needed is just this one line "lib": ["DOM", "DOM.Iterable"] in the right file.

I had read project references before but never understood it well enough to internalise it. It's probably something I will procrastinate again until the next problem with tsconfig crops up. Again.

Part 2 here describes conventions that really depend on the developers following them. In particular, the conventions here are for JavaScript/TypeScript code.

Naming​

There are two hard things in Computer Science: cache invalidation, naming things, and off-by-1 errors.

— Leon Bambrick

General rule of thumb:

• Names of functions/variables should be spelled with letters only.
• Numbers in names should only be used for localised variables (i.e. variables that are used within a function), and only when it makes sense (e.g. data from two similar sources).
• Words can be abbreviated if the spelling is too long. E.g. abbr in place of abbreviation
• Never name anything with 2 or fewer letters unless the scope in which they are valid in is extremely small (e.g. in a for loop that doesn't require scrolling to see its entirety).
• When an acronym is used, letters in the acronym after the first letter must be lowercase. E.g. textXml.
• Casing for the first letter depends on context. Functions typically start with a lowercase (e.g. checkIpAddress) whereas classes typically start with an uppercase (e.g. HttpRequestHandler).

Functions/Methods​

• Use camelCasing.
• Use imperative verbs.
• Names should be no more than 4 words. E.g. queryUserEmail, checkNewUserPresence
• Functions that are used withn the same module (i.e. not exported) as helper functions should be prefixed with an underscore. E.g. _extractTitle.

Variables​

• Use camelCasing.
• Names should be no more than 3 words.
• Private variables should be named starting with an underscore (_) when it makes sense to differentiate them (for example local variables that should be differentiated from class properties).

Imports​

import statements should be placed at the top of the file. There needs to be a strong reason to place the import statements anywhere else than the top of the page.

If there is a docblock at the top of the file, the import statements should be placed after the docblock.

The statements should be grouped by the modules according to the following heuristics:

• Each group should be separated by an empty line.
• The first group should contain the import statements of public npm packages.
• The second group should contain the import statements of private npm packages, if applicable.
• The third group onwards should contain local import statements.
• They should also be further grouped by the level of traversal upwards.
• Within each group, the order of the import statements should be based on the alphabetical order of the packages/modules/files.

For example:

import { GetServerSideProps } from 'next';
import Link from 'next/link';
import { ReactElement } from 'react';
import { Grid } from 'react-bootstrap-icons';

import { PAGE_SETUP, TOKEN_TWITTER } from './constants';

import { logger } from '../lib/logger';

TypeScript​

Non-null assertion operator​

The non-null assertion operator (the exclamation mark used after a variable) must be accompanied by a comment when used. E.g.

// `where` is initialised before this line.
args.where!.year = { in: [2023] };

As an alternative to using this operator, consider if the following alternative works:

args.where = Object.assign({}, args.where, {
  year: { in: [2023] },
});

OR

args.where = { ...args.where, {
  year: { in: [2023] },
}}

Imports​

import statements should be placed at the top of the file. There needs to be a strong reason to place the import statements anywhere else than the top of the page.

If there is a docblock at the top of the file, the import statements should be placed after the docblock.

The statements should be grouped by the modules according to the following heuristics:

• Each group should be separated by an empty line.
• The first group should contain the import statements of public npm packages.
• The second group should contain the import statements of private npm packages, if applicable.
• The third group onwards should contain local import statements.
• They should also be further grouped by the level of traversal upwards.
• Within each group, the order of the import statements should be based on the alphabetical order of the packages/modules/files.

For example:

import { GetServerSideProps } from 'next';
import Link from 'next/link';
import { ReactElement } from 'react';
import { Grid } from 'react-bootstrap-icons';

import { PAGE_SETUP, TOKEN_TWITTER } from './constants';

import { logger } from '../lib/logger';

TypeScript​

Non-null assertion operator​

The non-null assertion operator (the exclamation mark used after a variable) must be accompanied by a comment when used. E.g.

// `where` is initialised before this line.
args.where!.year = { in: [2023] };

As an alternative to using this operator, consider if the following alternative works:

args.where = Object.assign({}, args.where, {
  year: { in: [2023] },
});

OR

args.where = { ...args.where, {
  year: { in: [2023] },
}}

React​

• Components should be named using PascalCasing.
• Names should be no more than 3 words. E.g. UsernameInput, Footer.
• Use functional components in conjunction with hooks.
• Types, constants and variables should be defined outside of the component if possible. If not, they should be placed at the top of the component code (see below).
• Hooks should be placed at the start of the component definition and should be written in the following order: useRouter, useContext, useState, useRef, useReducer, useCallback, useEffect.
• Custom hooks should be called after the other hooks.
• Define functions and event handlers next.
• Component code (code that is for the component and runs just once per render), if any, should then be placed before the return statement. Variables and constants should be defined at the start in this block.
• Callback functions passed to useEffect should be named even though anonymous functions are accepted. This will make the purpose of the useEffect calls much more clearer. E.g.

useEffect(function loadList() {
  ...
}, []);

Miscellaneous​

Constants​

The concept of constant is different in JavaScript/TypeScript as compared to other languages. The const keyword is used to define a variable as not changeable. This can have different effects depending on whether the type is a primitive (like string) or a reference (pointing to an object).

Here "constant" refers to values that are fixed, primitive values. These values do not change for the life time of the scope that they are used in. These variables are named in uppercase letters. Words are separated by underscores. E.g.

const GRAVITY_ON_MOON = 1.62;

A constant should be named with no more than 4 words.

If the "constant" is not a primitive value (e.g. an array), it should not be named in uppercase letters as the values in the array/object can be changed either by intention or not.

ESLint for backend​

The ESLint configuration file is as follows:

module.exports = {
  env: {
    browser: true,
    es2021: true,
  },
  extends: 'standard-with-typescript',
  overrides: [],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  plugins: ['@typescript-eslint'],
  rules: {
    'comma-dangle': 'off',
    '@typescript-eslint/comma-dangle': 'error',
    // https://futurestud.io/tutorials/how-to-allow-trailing-commas-comma-dangle-with-typescript-eslint
    '@typescript-eslint/no-unused-vars': ['error', 'only-multiline'],
  },
};

The file is generated using npx eslint --init (reference https://blog.logrocket.com/linting-typescript-eslint-prettier) and modified afterwards.

Note: If the project is scaffolded using public tools such as create-next-app, follow the ESLint configuration from the scaffold.

TSConfig​

The tsconfig.json file differs between that for the Web app and the server.

Backend​

{
  "include": ["src"],
  "exclude": ["node_modules"],
  "extends": "@tsconfig/node-lts/tsconfig.json",
  "compilerOptions": {
    "allowJs": false,
    "outDir": "./dist",
    "noImplicitAny": true
  }
}

The file is generated using npx tsc --init. It is complimented by the package @tsconfig/node-lts.

Web frontend​

The tsconfig.json file is created using Vite (npm create vite@latest).

TypeScript 5 Notes​

Starting from TypeScript 5.0, the option --verbatimModuleSyntax replaces --importsNotUsedAsValues and --preserveValueImports. This setting should be included in tsconfig.json with the value true.

Reference: https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax

Commits​

Check your Git username and email​

All too often I see programmers, particularly junior ones who have been using the same computer since they learnt Git, use the same username and email address for every project because they've set it globally! This makes it hard to identify and track down changes in the future.

Just have a look at this:

commit 551421f5251f9b6c0cb4fb5a7752ce58349b0ef8
Author: Spartacus Grizzly <cheekybear98@gmail.com>
Date:   Mon Mar 18 15:44:41 2024 +0800

How the hell is any one going to know who Spartacus Grizzly is? 🙄

If you're going to work on a company job, use a proper name and the company email address given to you!

We're not asking every developer to change the name and email address globally. Just use git config user.name and git config user.email to change the values for the project.

Never commit with an empty message.​

The fact that this has to be listed is frustrating. 😤

Each commit should be targeted​

Each commit should aim to add one feature, or to fix one thing only. Another way of saying this is to make each commit as small as possible.

Not only does this make it easy to review code commits, any issues can be more easily tracked down as well. Any necessary reverts can be done more easily as well.

Corrections should be made as amendments rather than new commits​

Commits that are basically corrections for the previous commit should included as part of the original commit as far as possible.

A common occurrence for this situation is when a file is modified but not saved before the commit. Or a file that should be included in the commit but was not.

Rather than making a new commit for this, the file should be staged and included with the previous commit using git commit --amend.

However, this should only be done for commits that are not pushed to the cloud repository. If the commit has already been pushed, this will cause the remote branch to be inconsistent with your local branch, causing the commit history to be more messy than adding a new commit.

At a high level, these are the steps.

1. Create a custom plugin that extends the original blog plugin (plugin-content-blog).
2. Disable the original blog plugin and use the new custom one.
3. Import the JSON file containing the recent articles.

For details of each step, see Option 2.

Preamble​

I'm in the camp of static site generators when it comes to creating a blog. Hands-down Docusaurus is the best that I've come across.

As soon as I got to understand Docusaurus, I ditched Hugo, my previous static site generator of choice. I knew that I will be using Docusaurus for the long term.

Despite my partiality towards Docusaurus, one function that I've found sorely missing is the ability to show the most recent blog posts in the home page. And I'm not the only one.

Ever since I moved my blog over in February 2023, I've been looking for a method to do this on and off over the past year.

Until recently, the best explanation that I've found describes in abstract terms how to do it but doesn't show any concrete steps.

Option 1​

After a few months, I decided that there was no easy way. So I thought of a method where I render the posts client side using the RSS feed from the blog.

It's really more of a workaround rather than an "actual" solution.

This is achieved by using useEffect that fetches and parses the RSS feed. Here is how I did it.

Import the useEffect function if not already done.​

import useEffect from 'react';

Fetch the RSS feed in useEffect:​

const [feed, setFeed] = useState<Record<string, any>[] | null>(null);

useEffect(function fetchFeed() {
  fetch(`${WEBSITE}/blog/rss.xml`)
    .then((resp) => resp.text())
    .then((xmlText) => {
      const xml = new window.DOMParser().parseFromString(xmlText, 'text/xml');

      const items = xml.querySelectorAll('item');

      const latestArticle = 0;
      const endingArticle = 2;
      const posts = extractPosts(items, latestArticle, endingArticle);

      setFeed(posts);
    });
}, []);

The fetch function retrieves the RSS feed from the published website (indicated by the variable WEBSITE). The feed is then converted into XML (line 7). The articles are contained in item elements (line 9). In this code segment, the latest article is selected (latestArticle = 0) along with the second latest one (endingArticle = 2), meaning that the newest 2 articles will be shown.

The posts are extracted using extractPosts.

Extract the posts​

function extractPosts(elements: NodeListOf<Element>, start = 0, count = 1) {
  let subset = [];

  for (let i = start; i < start + count; i++) {
    if (i < elements.length) {
      subset.push({
        title: elements[i].querySelector('title').textContent,
        link: elements[i].querySelector('link').innerHTML,
        pubDate: elements[i].querySelector('pubDate').textContent,
        description: elements[i].querySelector('description').textContent ?? '',
      });
    }
  }

  return subset;
}

This will make the recent articles are available in the index page (setFeed(posts)), so they can then be rendered to your desire.

Drawbacks​

While this method is straightforward, there are some drawbacks.

• First, it depends on the RSS feed from the production website, which means that it will not reflect the articles that you just added to the site in development.
• Second, since the list is rendered client-side, it will (generally) not be picked up by search engines. Granted, this may not impact the SEO performance much since it's just a short list of articles.
• Third, since the code is fetching another resource after the page is loaded, there will be a delay before the list is rendered. Depending on your preference and how you layout your page, this might be a dealbreaker.
• Fourth, depending on how the server hosting the site behaves, the feed may be stale i.e. the feed may not show the latest articles from the site, making the list show inaccurate data.

Despite all these shortcomings, this was the only solution I had for a while.

But the problem about showing stale data (problem #4) was painful enough for me to keep looking for a better solution.

Option 2​

After spending the better part of Easter Friday, I finally got something working.

I found an article that actually describes step-by-step how the recent articles can be placed in the index page. However, this method requires replacing the index page with the blog listing page. This was a bit more drastic than what I was expecting - I didn't want to have to redesign the blog listing page to look like the index page.

Instead I opted to use the method suggested by Sébastien Lorber (one of Docusaurus' maintainers) in this Github issue which is to create an intermediate JSON file. Then the index page will import this JSON file and render the posts on the index page.

As described in the TL;DR, the steps are:

Create a custom plugin that extends the original blog plugin (plugin-content-blog)​

const fs = require('node:fs');

const blogPluginExports = require('@docusaurus/plugin-content-blog');

const defaultBlogPlugin = blogPluginExports.default;

async function blogPluginEnhanced(...pluginArgs) {
  const blogPluginInstance = await defaultBlogPlugin(...pluginArgs);

  const dir = '.docusaurus';

  return {
    ...blogPluginInstance,
    contentLoaded: async function (data) {
      let recentPosts = [...data.content.blogPosts]
        // Only show published posts.
        .filter((p) => !p.metadata.unlisted)
        .slice(0, 3);

      recentPosts = recentPosts.map((p) => {
        return {
          id: p.id,
          metadata: p.metadata,
        };
      });

      fs.mkdirSync(dir, {
        recursive: true, // Avoid error if directory already exists.
      });
      const fd = fs.openSync(`${dir}/recent-posts.json`, 'w');
      fs.writeSync(fd, JSON.stringify(recentPosts));

      return blogPluginInstance.contentLoaded(data);
    },
  };
}

module.exports = {
  ...blogPluginExports,
  default: blogPluginEnhanced,
};

Create a plugins directory in root of the project (same level as src). Place the file recent-blog-posts.js into this directory as the plugin. (You can choose different names for the directory and file - they are not treated any differently.)

By including the plugin (line 3), the plugin is being extended.

Line 17 is of note. It checks to make sure that only listed posts will be included (filter((p) => !p.metadata.unlisted)). Remember that this value only takes effect in production.

On line 18, we tell the plugin to return the latest 3 posts.

Lines 20-25 are optional. They are there to keep the intermediate JSON file small by omitting the full contents of the posts.

Lines 30-31 write the posts into the intermediate JSON which is named recent-posts.json and placed in the .docusaurus directory.

Disable the original blog plugin and use the new custom one​

This step requires modifying the configuration file docusaurus.config.js. The exact changes depend on whether the blog plugin was added manually (standalone) or as part of the theme.

If the plugin is configured standalone, then it would be in the plugins array:

const config = {
  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        // rest of blog plugin options
      },
    ],
  ],
  // rest of config
};

To use the new custom plugin, swap out the original one with the new one.

const config = {
  plugins: [
    [
      './plugins/recent-blog-posts',
      {
        // rest of blog plugin options
      },
    ],
  ],
  // rest of config
};

If the plugin is included as part of a preset (e.g. the classic preset @docusaurus/preset-classic), like the majority of users who follow the installation guide do, then the configuration is placed in the presets array:

const config = {
  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        blog: {
          showReadingTime: true,
          // rest of blog plugin options
        },
        // rest of preset options
      }),
    ],
  ],
  // rest of config
};

To use the new custom plugin, disable the blog plugin in the preset:

const config = {
  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        blog: false,
        // rest of preset options
      }),
    ],
  ],
  // rest of config
};

And add the custom plugin into the plugins array (you may have to create the entire plugins property if it is not already present):

const config = {
  plugins: [
    [
      './plugins/recent-blog-posts',
      {
        showReadingTime: true,
        // rest of blog plugin options
      },
    ],
  ],
  // rest of config
};

Import the JSON file containing the recent articles​

Add the following import statement into your index page (or component) and you can access the recent articles.

import recentPosts from '@site/.docusaurus/recent-posts.json';

Conclusion​

I would have preferred to be able to specify the number of recent posts to display by specifying the number as an option in docusaurus.config.js but I couldn't get it to work.

Adding an additional option for the plugin like this:

const config = {
  plugins: [
    [
      './plugins/recent-blog-posts',
      {
        showReadingTime: true,
        recentPosts: 5,
        // rest of blog plugin options
      },
    ],
  ],
  // rest of config
};

raises this error:

[ERROR] ValidationError: "recentPosts" is not allowed

This is due to the validation of options by the original plugin. I do not think there is much value in modifying the original plugin (or to fork it) to achieve this minor enhancement.

I'm pretty happy with this outcome as it is. Nevertheless, if you have an idea of how to make the number of recent posts configurable in docusaurus.config.js, hit me up on Twitter.

Regardless, unlike artists, developers have to work as a team. That means that they have to follow the team's conventions regardless of their preferences.

Many conventions can now be easily enforced via configurations settings, thanks to the ubiquity of VS Code and, to a lesser extent, Prettier.

This article looks at the easy steps we can take to enforce coding conventions easily for a Next.js project.

The preference settings in VS Code, together with a formatter (such as Prettier), can handle most of the coding conventions that a team wants to establish.

One thing to note about the settings in VS Code is that some are conventions that should established for all team members, some are personal preferences, which should remain personal.

My understanding is that workspace settings (specified by the file .vscode/settings.json) override user settings. (If the setting is not specified at the workspace level, it naturally takes the value from the user level.) Therefore it is important to specify what should be set and what should not be.

Below are contents of settings.json that I set for my projects:

{
  "editor.detectIndentation": true,
  "editor.insertSpaces": false,
  "editor.indentSize": "tabSize",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "prettier.arrowParens": "always"
}

These settings achieve the following:

1. Prefer for VS Code to determine whether to use tabs or spaces based on what is currently being used in the file being edited. ("editor.detectIndentation": true)
2. If the file is empty (or if VS Code cannot determine the pre-existing indentation convention in the file), tell VS Code to use tabs instead of spaces for indentation. ("editor.insertSpaces": false)
3. Use the indentation space specified by the tabSize setting whose value should be specified by the programmer at the user level. ("editor.indentSize": "tabSize")
4. Format the file when it is saved. ("editor.formatOnSave": true)
5. Use the Prettier formatter to format the file when saving. This is required for the above setting to have any effect. ("editor.defaultFormatter": "esbenp.prettier-vscode")

Other settings such as the tabSize ("editor.tabSize": 2) are not specified here because they are meant to be personal preferences.

For Next.js projects that are scaffolded using npx create-next-app there should be a file .eslintrc.json which contains the contents below:

{
  "extends": "next/core-web-vitals"
}

I leave this untouched as the defaults have worked well for me.

What is most important is the use of the Prettier plugin that performs the task of formatting the files before they are saved. The plugin can be configured using the .prettierrc file in the project.

{
  "useTabs": true,
  "printWidth": 80,
  "singleQuote": true,
  "trailingComma": "es5",
  "semi": true
}

These settings are applied when the files are saved in VS Code:

1. Use tabs to indent the lines of code. ("useTabs": true)
2. Wrap the line if there are more than 80 characters in the line. ("printWidth": 80)
3. Use single quotes where possible. ("singleQuote": true)
4. Apply a trailing comma in the style ECMAScript 5, which means commas are added to the last line in a multi-line JSON definition. ("trailingComma": "es5")
5. Always place a semicolon at the end of a statement. (I'm old school that way) ("semi": true)

These configurations might seem trivial but they go a long way in ensuring that code review is not unnecessary hampered by redundant changes such as tabs being replaced with spaces. Take a look below:

This diff essentially has no differences between the changes except that one is indented by spaces (new) and one is indented by tabs (old).

Now imagine this expanded to multiple files.

This is no exaggeration. I was a consultant to a project team for a while. They had hired a remote developer who was maintaining a legacy Java codebase.

No one ever reviews the code made by the remote developer not because no one in the team could do it but because every commit involved thousands of lines of code across multiple files. This happened because there wasn't a lead who enforced coding conventions for the team. The thousands of lines of changes were mostly a change in the indentation characters. 🤦 As a result, no one in the team knew what changes the remote developer had made.

This experience further consolidated my view that coding conventions are not a nice-to-have but a must-have for a team.

One last thing to note, the changes made by Prettier as specified in .pretterrc are enforced when the programmer saves the file in VS Code itself that has the Prettier formatter. I thought this was obvious, but sometimes the obvious bears repeating.

Writing a commit message​

Every commit should have one main theme - one main purpose for why the change was made.

This should be made clear by the first sentence in the commit message.

The first sentence should be separated from the rest of the message with an empty line.

The body of the commit message should be written in point form, denoted by a dash at the first of the line. (Remember that the purpose of the message is for sending a clear message, not for writing essays.)

Each point should be written as a full sentence, properly punctuated. Why? The purpose of punctuation rules is to facilitate clear written communication. What’s the use of having (punctuation) rules if nobody follows them?

A useful tip to remember is that the project lead should understand from the commit message what changes are included in the commit without having to look at the code. The code should only be looked at if the lead wants to review the correctness of the code, not for trying to understand the purpose and scope of the commit.

Example​

Here is an example of the type of commit message that I think is good:

Added the user avatar next to the comment.

- Modified the user API payload to return the avatar URL.

Since the commit message is supposed to describe what was done, it should be written in the past tense.

For consistency, my preference is to have the message written in the active voice. Below is an example of the same message written in the passive voice.

User avatar added.

- User API payload modified to return the avatar URL.

What not to write​

What is a definite no-no is to write something along the lines of

made code changes

No sh*t genius!

This is just pure laziness and it makes my blood boil. 😠 A one-liner stating the obvious wastes the reviewer’s time and makes history traversal that much more difficult in the future.

Leaving the commit message empty is just as bad. It reflects the lack of care on the part of the programmer to think for the team or anyone else who will take over the code. (The grammar police in me is also triggered by the lack of a full-stop/period at the end of the sentence and the lowercase letter at the start.)

The other extreme - an extremely wordy write-up describing the commits - is also to be avoided. An overly detailed write-up defeats the purpose of the commit message, which is to summarise the key changes made in the commit.

If the reviewer wants more details, he/she should read the actual code changes.

Although this is to be avoided, it doesn't trigger me as much as an empty/redundant message because at least it shows that the programmer owns the work and puts in effort (albeit in the wrong direction).

Conclusion​

As mentioned, this is my highly opinionated take on the approach to writing commit messages. In the next article in the series, I’ll share a few useful, but not frequently used, Git commands.

One of the things that they will be doing is to check out an existing codebase to work on. To do that, they need to know Git.

I'm quite certain that the basics of checking in and out code is no problem for them if they have any Github profiles. However, every organization has its own conventions and requirements when it comes to maintenance of their codebases. This post documents my preferences in code maintenance.

Branching strategy​

When taking on a new codebase, one of the first things to understand is the branching strategy used by the organization. A branching strategy isn't a Git command or function. Rather it is a set of conventions that determine the approach to handle code changes in terms of code releases, bug fixes and new feature development. The things to consider are the convention for creating and naming of new branches, and the guidelines for when and how to merge changes.

There are several popular ones out there:

• GitFlow
• GitHub Flow
• GitLab Flow

One factor affecting the choice of strategy is the size of the team. The size of the team has a direct (but not necessarily proportional) bearing on the number of concurrent branches. It is important to be judicious about selecting the suitable strategy. Each strategy yields different benefits but also introduces additional overhead.

A strategy perfect for a team of hundreds is likely to be too onerous for a team of three.

Some of the strategies above are also outdated in the sense that they do not lend well to the modern strategies of continous integration/continuous deployment (CI/CD).

For a small team of less than five, here are my heuristics (Maybe I should call it SimpleFlow 🤔):

• A production branch should be branched off the main (or master) branch.
• All releases are made on the production branch.
• Each release should be accompanied by a tag.
• This implies that the main branch contains the latest, tested changes.
• Feature development should take place on branches based off the main branch - these are called feature branches.
• Feature branches should rebase from the main branch frequently.
• Feature branch should be merged back into the main branch when development is done.
• Hotfixes should only be made on branches based off the production branch and merged back into production for release.

By keeping all releases on the production branch only, any CI/CD pipeline can be honoured during deployment.

Example​

Here is an example scenario:

Say Alice is tasked to create a new feature for users to select one of a few preset avatars. She checks out the codebase which defaults to the main branch.

$ git checkout git@github.com:coy-project
$ cd coy-project

She then creates a new branch preset-avatar.

$ git checkout -b preset-avatar

She starts work in this branch.

Halfway through her work, she receives instructions to investigate a reported bug in the production system. She stashes any outstanding work in her branch before switching to the production branch to start investigation work. She creates a new branch hotfix-broken-image to start her code changes. (Before creating the new branch, she should make sure to have the latest commits from production as well.)

# In `preset-avatar` branch.
$ git stash # Put her current work away.
$ git checkout production
$ git pull
$ git checkout -b hotfix-broken-image

She makes the necessary code changes to fix the bug. Then she commits the code to the hotfix branch. Before she makes a pull request (PR) to the production branch, she pulls in the changes one last time. There should not be any more changes to production in this scenario, but edge cases can occur.

$ git commit -m "Fixed broken link to image."
$ git checkout production
$ git pull
$ git checkout hotfix-broken-image
$ git rebase production # Only if there are new changes from `git pull`

The project lead will review the changes. Notice there isn't a command for PRs. PRs are artefacts of the centralised service (i.e. the likes of Github and Gitlab) that provides the centralised Git service - they're not part of the core Git functionality.

After the changes are approved, she will merge the changes into the production branch. In some cases, changes to the production branch are restricted to project leads, so only the project leads can merge the pull request.

$ git checkout production
$ git merge hotfix-broken-image

Regardless of who merges the hotfix into the production branch, Alice goes back to continue to her work on the preset-avatar branch by restoring the changes that she had stashed away earlier.

$ git checkout preset-avatar
$ git stash pop # Restore the work she previously put away.

From this point on, she continues her work.

Identity​

One other thing that I require collborators to do is to set the name and email of the Git identity that is registered in the Git history.

$ git config user.name "<Your name here>"
$ git config user.email <your@email.com>

This is so that the Git history reflects clearly who made which commits.

I want to avoid entries that look like this when I run git log:

commit 012bf3d06e6f707a23b1786c9bd94f59f851d576
Author: juju <ilovejuju@MacBook-Air.local>
Date:   Thu Jul 7 08:48:16 2022 +0800

    made code changes

The name and email should be the formal identity registered with the company.

Conclusion​

This article covers the high-level, strategic approach that I've used for small projects.

The next few articles will cover the more strategic, tactical uses of Git.

Problem​

Error in Node.js output

Error: error:0308010C:digital envelope routines::unsupported

Easiest solution​

Create a .npmrc file in the root of the project (same location as your package.json file) with following contents:

node-options="--openssl-legacy-provider"

The problem​

This problem typically occurs in projects that were developed with Node.js version 16 and earlier, and then run in version 17 or later. It is a result of Node.js version 17 using OpenSSL 3.0.

The problem has to do with deprecated SSL connection options in Node.js versions 17 or later.

The solution​

There are several solutions to this issue.

Like many computer problems, there is the quick fix solution that "solves" the problem by making the error message go away (treating the symptom), and there is the "correct" solution that addresses the root cause (treating the root cause).

The quickfix​

This solution makes the problem go away by telling Node not to reject the weaker connection.

This is done by setting the environment variable like so:

export NODE_OPTIONS=--openssl-legacy-provider

As an alternative, the environment variable can be specified as a prefix to the npm command:

NODE_OPTIONS=--openssl-legacy-provider npm run dev

The "permanent" quickfix​

One nifty alternative is to create a .npmrc file with the following contents:

I like this option because this file can be committed into version control and solve the problem "permanently".

The right solution​

The "right" solution is to update the application or packages. The error occurs because the application or a module in the application is using an algorithm or key that is not supported by OpenSSL 3.0 by default.

Caveats​

The main issue with the quick fix solution is that it overrides the stronger security safeguards imposed by newer versions of Node.js

Normally this is a bad idea. However, there is a use case where this isn't a problem. And that is to generate static websites. For this use case, Node.js is only used to generate the static web pages (i.e. HTML, CSS and client-side JS) and not used in production. Thus, it is not a concern if it uses a weaker connection since it is never used in production.

A practical scenario is the use of Nuxt to generate static websites and then host the sites using a Web server like NGINX or Caddy Web Server.

// Solution 1
type LabelEntry = { label: string };
type ImageEntry = { image: string };
type Entry = LabelEntry | ImageEntry;

// Solution 2
type Entry = Record<'label' & 'image', string>;

An object type that I find myself creating very frequently is one that has one or all of several properties. For example, I can create an entry with a text label, one with an image, or one with both:

const textEntry = {
  label: 'Fluffy cloud',
};
const imgEntry = {
  image: 'cloud.jpg',
};
const bothEntry = {
  label: 'Fluffy cloud',
  image: 'cloud.jpg',
};

The problem​

Intuituively, I would declare the type for this kind of objects to be like this:

type Entry = {
  label?: string;
  image?: string;
};

There's a problem with this type. You can see the problem in the next listing with entry3:

const entry1: Entry = {
  label: 'Fluffy cloud',
};
const entry2: Entry = {
  image: 'cloud.jpg',
};
const entry3: Entry = {};
// We don't want to allow this to happen.

With this type definition, entry3 can be assigned an empty object. This is not the outcome that we want.

Solution 1​

One solution to the problem is to create two types and create an intersection type like so:

type LabelEntry = {
  label: string;
};

type ImageEntry = {
  image: string;
};

type Entry = LabelEntry | ImageEntry;

The entry3 variable above will show an error Type '{}' is not assignable to type 'Entry'. because it contains an empty object.

Instead it must have either one (or both) label or image as its property.

const entry1: Entry = {
  label: 'Fluffy cloud',
};
const entry2: Entry = {
  image: 'cloud.jpg',
};
const entry3: Entry = {
  label: 'Fluffy cloud',
  image: 'cloud.jpg',
};

Solution 2​

If coming up with names is not your strongest forte or you want to have fewer redundant lines of code, this might be your preferred solution:

type Entry = Record<'label' & 'image', string>;

Record is an utility type that helps to define the keys and values of an object type easily.

P.S. A mistake that I made before was using union (|) instead of intersection (&) for the key values (i.e. Record<'label' | 'image', string>). This would have made entry1 and entry2 invalid.

This post is a knowledgebase article on Prisma with PostgreSQL.

The typical model in a Prisma schema has an id field that auto-increments:

model User {
  id Int @id @default(autoincrement())
  name String
}

The following is working (most of the time) code that inserts a new entry:

prisma.user.create({
  data: { name: 'Some User' },
});

However, the following error may occur:

Unique constraint failed on the fields: (id)

This is baffling - if the field auto-increments, how can the unique constraint be violated?

Why?​

The answer (for PostgreSQL at least) is that this error typically happens if there is an entry created before that was not created using the auto-incremented ID. In other words, if there is an entry that was created where the ID was explicitly set, a conflict arises when Prisma tries to set its own auto-incremented ID.

Solution​

So, where possible, avoid setting the ID explicitly for tables which have the primary key field being an auto-incremented number field.

But what about...​

Alright, so we know what to avoid doing in the future. But is there a solution for tables that already have entries with manual IDs created?

As a matter of fact, there is!

SELECT setval(pg_get_serial_sequence('"User"', 'id'), coalesce(max(id)+1, 1), false) FROM "User";

Notice that the table name is encapsulated within a pair of single quotes and a pair of double quotes ('"User"')? This is because the name of the table begins with an uppercase character (U). This is a quirk of PostgreSQL. If the table name does not begin with an uppercase letter, the inner double quotes is not necessary (e.g. 'user').

See this discussion in Prisma's Github Discussions.

The source material came from this article by Thomasdevshare. His article describes a similar authentication scheme for Docusaurus with Firebase as the identity provider whereas this article describes the same approach using Google API directly.

The main concepts described in this article will be largely the same as that written by Thomas. The main differences:

• instead of depending on the Firebase package, the @react-oauth package is used, and
• a new section on designating allowed users to access the page.

(The example in this document is written in TypeScript but it should be easily applicable to JavaScript.)

Pre-requisites​

These are the things that you need to set up:

1. Google credential​

This step can be done at https://console.cloud.google.com/apis/credentials

Follow the Google instructions to configure your project and create a client ID for Web application.

For local development, add http://localhost and http://localhost:<port_number> to the Authorized JavaScript origins for @react-oauth to work. When deploying to production, specify the actual URL of your site.

Note the Client ID field for the OAuth 2.0 Client - this needs to be placed into the .env file (see below).

2. Add the @react-oauth/google dependency​

npm i @react-oauth/google

This dependency makes it easy to incorporate the Google SSO implicit-authorization flow.

3. Specify Google Client ID and allowed users​

Create a file .env in the root of the directory (same location as docusaurus.config.js) and add the following contents, replacing the text in arrow brackets with actual values:

GOOGLE_CLIENTID=<google client ID>

ALLOWED_USERS=<email addresses separated by commas>

GOOGLE_CLIENTID=1111111111111-djfh38dhf467as1hdgg3f2df334msd.apps.googleusercontent.com

ALLOWED_USERS=user1@example.com, user2@example.com, user3@example.com

The Google credentials obtained in Step 1 should replace <google client ID>.

<email addresses separated by commas> should be replaced with actual email addresses e.g. email1@example.com, email2@example.com

(The space after the comma will be trimmed by the plugin so it doesn't matter if the commas are followed by spaces.)

4. Configure docusaurus.config.js to read the environment variables​

Docusaurus is only able to read the environment variable during pre-processing. This means that the values in the .env file have to be "transferred" to the configuration file.

This is done by first adding the following line to docusaurus.config.js:

require('dotenv').config();

Then, somewhere in the file below, assign the process environment variables to properties under customFields:

const config = {
  title: 'Me3 Technical Documentation',
  customFields: {
    allowedUsers: process.env.ALLOWED_USERS,
    googleClientId: process.env.GOOGLE_CLIENTID,
  },
  // ...
};

Log-in Component​

Next create the log-in component. This component displays the Google sign-in button for the user to authenticate himself/herself.

Create a file src/components/login-google/index.tsx

import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import {
  CredentialResponse,
  GoogleLogin,
  GoogleOAuthProvider,
} from '@react-oauth/google';
import React from 'react';

export function LoginGoogle(props: {
  login: (string) => void,
  denied?: boolean,
}) {
  const {
    siteConfig: { customFields },
  } = useDocusaurusContext();

  const clientId = customFields.googleClientId as string;

  function handleError() {
    console.error('Failed to sign in with Google.');
  }

  function handleSuccess(creds: CredentialResponse) {
    const plaintext = decode(creds.credential);

    if (!plaintext) {
      return;
    }
    const payload = JSON.parse(plaintext);
    if (isAllowed(payload.email)) {
      props.login(payload.email);
    } else {
      props.login(null);
    }
  }

  // Checks if the supplied email address is allowed to see the page.
  function isAllowed(email: string): boolean {
    let allowedUsers = [];
    if (typeof customFields.allowedUsers === "string") {
      allowedUsers = customFields.allowedUsers.split(",").map((e) => e.trim());
    }
    if (allowedUsers.includes(email)) {
      return true;
    }
    return false;
  }

  return (
    <GoogleOAuthProvider clientId={clientId}>
      <div
        style={{
          display: 'flex',
          flexFlow: 'column nowrap',
          alignItems: 'center',
          margin: '5rem auto',
          textAlign: 'center',
        }}
      >
        <h2>Please sign in to your Google account to get access.</h2>
        {props.denied ? (
          <em>Not authorised</em>
        ) : (
          <GoogleLogin
            onSuccess={handleSuccess}
            onError={handleError}
          ></GoogleLogin>
        )}
      </div>
    </GoogleOAuthProvider>
  );
}

// Function to decode the JWT from Google to get the user's email address.
function decode(jwt: string): string {
  const parts = jwt.split('.');
  if (parts.length !== 3) {
    return '';
  }
  return window.atob(parts[1]);
}

Swizzle the Root Component​

Swizzling is a term describing the overridding of an existing component with a custom implementation of it.

The Root component is the component to swizzle as it covers all generated pages.

import React, { useState } from 'react';

import { LoginGoogle } from '@site/src/components/login-google';

export default function Root({ children }) {
  // `email` is used to determine if user is allowed.
  const [email, setEmail] = (useState < string) | (null > '');

  if (!email) {
    return <LoginGoogle login={setEmail} denied={email === null}></LoginGoogle>;
  }

  return <>{children}</>;
}

Conclusion​

One thing to note: the authentication information is only persisted in memory. What this means is that the authentiction is temporary (the correct term is ephemeral). The implication is that as soon as the user refreshes the page, the authenticated information (i.e. email address) is lost and the user gets "logged out".

This piece is a quick, non-technical introduction to domain names.

When I set out to write this article, I did not expect to write several drafts only to completely throw them away.

As I planned the outline of the article, I began to realise the depth and complexity of the topic. It was a challenge not to turn this into a technical write-up on DNS and nameservers in my attempt to elucidate the jargon and economics surrounding domain names.

So I decided to take on a consulting mindset for writing this article. I began with the question "What is the first thing that a small business owner would ask about his/her domain?"

The answer?

Cost​

The first thing that comes to mind for any small business owner is cost. It is only natural—even expected—that, as a (potential) business owner, you want to keep costs low as much as possible.

So let's start with that.

There are two types of costs you need to be concerned with: the acquisition cost and the renewal cost.

The acquisition cost is based on the domain name you want. For available domain names (names not yet claimed by anyone), the cost is very affordable - less than a hundred Sing dollars. You can purchase available domains on-the-spot easily with a credit card.

Then there are domain names that are held for sale. These domain names are kept for no other purpose than profit. This practice is known as cybersquatting.

I have not had to purchase a domain from cybersquatters before but the lowest price you are looking at is typically a four-figure sum. For comparison, a fresh .com domain costs around US$15. This huge price difference is why all my clients and friends have chosen to brainstorm for a fresh domain rather than to shelve out large sums of money to get an existing one. If cost savings is important to you, this is what I would recommend as well.

For a new domain, the renewal price is usually the same as what you paid for. That has changed now—there are tiered price domains that are sold at a higher price than what it costs to renew them.

So if there is a domain name that you very much want, but comes with a higher price tag, take a look again. The difference might be small enough (some might be a few hundred dollars) for you to stomach the one-time acquisition cost if the renewal cost is nominal. (See next section for examples.) Just chalk it off as a capital expenditure. 🤷🤷‍♂️

The renewal cost of a domain is usually based on its top-level domain (TLD). In simple terms, the TLD is the right most part of a domain name.

You should be familiar with .com - it is the most common TLD. Together with it, .net and .org are among the earliest TLDs introduced to the domain name system (DNS).

There are others, but I will only go through the types that are of relevance to this article in the next section on…

Types of Domain Names​

As mentioned in the previous section, .com, .net and .org are among the earliest domains introduced in the DNS. Coincidentally, they are also the cheapest to renew.

Acquiring them is not easy though. Being the earliest TLDs, they are also the most used. I think it is safe to say that any English word you can think of, the .com domain is probably taken.

If you can think of a new word or phrase then you will be able to get the .com easily without paying a premium.

To combat this shortage of names, ICANN has created other TLDs such as .app, .tech, .club, etc. For these TLDs though, some unclaimed domains already command a premium right out the gate. As mentioned previously these are tiered price domains. Below are a few examples of them:

My friends and customers target primarily the Singapore market. For them, either a .com or .sg/.com.sg TLD works fine. However, I do think that a .sg/.com.sg domain removes the ambiguity altogether for your target audience. In a way, it acts as a filter for traffic coming to your website, and for your audience, an implicit assurance that you are operating in Singapore.

Domains that end with a country specific suffix like .sg have country code top-level domains (ccTLDs). A ccTLD domain is likely more expensive than a generic TLD like .com, the reason being that the ccTLD has to be administered by a country-specific intermediary called a Network Information Centre. For Singapore, this entity is called SGNIC.

To have an idea of the kind of price difference, a typical .com domain costs around S$18 (US$13). A typical .sg/.com.sg costs around S$45.

Domains ending with .com.sg can only be registered by a Singaporean company entity. Domains ending with .sg may be registered by anyone residing in Singapore. To get a Singapore ccTLD, there is an additional verification of identity implemented by the VerifiedID@SG scheme. Singaporeans can access this scheme using their SingPass accounts.

Getting the Domain Name​

Most of you reading this would probably leave it to your appointed vendor to register the domain for you. This is totally fine, if your vendor is reliable.

As mentioned in the previous article, it is important that the registrant information is registered as your own.

The following scenario that I am going to describe is a worst-case scenario that I have not had to deal with yet.

Suppose your vendor registered his/her own information for all four pieces of information (billing, tech, admin, and registrant) for the domain (probably for no other reason than for convenience). If your vendor is a solopreneur/freelancer, all formal records would show that he/she is the sole registrant. In the event that he/she is not contactable for whatever reason, imagine how would you recover your domain?

Now, I am not saying that having your name lodged as the registrant will guarantee that you can recover your domain. But not having your name in any of the records will definitely not help you at all.

Therefore, you have to emphasize to your vendor/developer to make sure to enter your information for the registrant. Incidentally, if you are getting a .sg or .com.sg domain, you are required by the VerifiedID@SG scheme to verify your identity using your SingPass account. Note that this is in addition to the registrant info, so be sure that both are in order.

If you are inclined, it is perfectly fine for you to register the domain name by yourself. But be aware that at some point, you will need to map the DNS records for your domain to the server where your website resides. Alternatively, rather than doing it yourself, you may also pass your credentials to your vendor to make those changes for you.

What I recommend though (if you registered the domain name yourself) is to have your vendor change those settings in front of you. On the day when you "go live" (i.e. putting your website online), have the vendor come to your office. Sign in to your registrar's control panel, and let him/her change the DNS settings on the spot. This way, you need not reveal your password and worry about potential security issues.

I will not be describing the DNS settings in this article. It is too complex to describe in a reasonable length. You should leave this part to your vendor/developer to handle.

WWW or not?​

The last thing to mention is the www prefix. Unbeknownst to many, the www prefix, known as a subdomain, is an optional part of the domain name that is determined by your DNS settings.

From what I understand, this prefix also has an impact on your search rankings. Depending on configurations, it is possible to have your website served on both the www and naked domain (i.e. without the www). Google seems to frown upon this though - it considers them to be duplicate content. How it affects your website's ranking in the search results, I'm not exactly sure. All I know is that Google recommends not having the same content at different URLs. The naked domain and the www subdomain are considered different URLs.

My recommendation is that you ask your developer to redirect traffic from one to the other. It is usually a matter of preference whether to serve your website on the naked domain or the subdomain. My stance is that having a www subdomain makes it absolutely clear that what you are referring to is a website. This is all the more important if your chosen TLD is not a .com (e.g. www.example.app, www.example.tech, etc.)

Note that I am recommending the www prefix for your website, not your email address. It is absolutely unnecessary to have the prefix for your email address. In fact it is cumbersome to include the prefix for your email address. (Compare charles@school.com and charles@www.school.com)

This article has gone on long enough already. If the opportunity arises, I will discuss domain transfer and other topics in another article.

(Also posted on Medium and LinkedIn.)

I decided to write down all the advice on website building that I always give my friends and customers so that I don't ever miss anything out. This is the first of several articles.

I've been making webpages since the 90s. So I think I know a thing or two about building websites.

I really ought to since I've already built more than a handful of websites professionally and for my business owner friends.

Every time I do so, I find that I have to explain the same things to my clients and friends—the things to watch out for, the parts that make up the website, the available kinds of hosting options, etc.

The thing is, there are so many things to mention that each time I explain, I inevitably miss something out. So I decided to write it all down in the form of articles, listicles, or checklists that are easy to read and digest. My target readers are the average people and small business owners. I try to be as concise and non-technical as possible, so that they can read, understand, do it right, and get on with their lives.

To keep the length of this article manageable, I will discuss just the three fundamental things to look out for.

1. Make Sure Domain Ownership is Clear​

If there is only one thing I can share, it is this: make sure you own the domain!

"Why would I not own the domain? I paid for it!"

That's the typical response I get. The reason is that domain names are registered with ICANN through registrars. When a domain name is registered, there are 4 pieces of contact information that needs to be provided—registrant, admin, tech, and billing.

Most important among them is the registrant information—the entity/person that has registered for the domain.

So why would that be a problem? The issue is actually due to human behaviour. You see, people loathe to enter data into fields. The cognitive burden when entering fields for four contacts is even higher. As a result, many vendors are often tempted to enter one set of information (his/her own) and use the same for all four contacts (this is usually made possible by the user interface).

Most of the time, this is not a problem, but when it does become a problem, there is generally no recourse for the site owner. The problem typically manifests itself when the working relationship between the vendor and the site owner turns sour.

I have not had to deal with this yet, fortunately. But imagine if the vendor became hostile and denies the domain to you, the site owner, there would be no records of ownership as far as ICANN is concerned. If the vendor is not cooperative, it would take you a king's ransom and a long time in order to reclaim the domain.

This is why it is so, so important for you to make sure that the selected vendor is a reliable and trustworthy one. Otherwise, it might be better to just handle the domain portion personally.

I will be writing a piece on domain names separately to delve into more details.

2. Costs Are Not Necessarily Indicative of Quality​

Creating a website is not like buying a car where there are clear boundaries that links quality with the right price tag.

Two vendors (developers) can quote the same price for a website but deliver wildly different results.

In my next piece on website fundamentals, I discuss the dirty little secrets of the industry (among other reasons) that explain why there is now such a large variation of quality.

So if price is not the answer, then what is?

There are generally two ways to make sure you hire the right developer.

One, check out the developer's previous work. For most of you reading this, the only criterion by which the work can be judged is through the aesthetics. That is well and good, but may not be sufficient, as I'll explain in another article.

Two, have the developer create the mock-up (also sometimes referred to as the prototype) of the website before starting actual programming work. This way you can have an idea of what the final product will look like much more quickly (and cheaply) than waiting for the site to be fully developed. This is the way it is because it takes a lot more work and time to create the actual website than to illustrate what the final design will look like.

To make it fair for both parties, I always recommend creating the mock-up first. Let's be clear, the mock-up isn't some sketch or hand-drawn representation of the site. Rather, it is an almost exact replica of the website. There are tools now that do not even cost money that the vendor can use to present the final look-and-feel without writing a single line of code.

I also recommend that you pay a fair sum of money for this prototype. While no code is written, it still takes time, effort and creative brain juice to think of and create the design. There is no right figure as the price of a website may differ greatly. Generally though, some 10% to 25% may be a ballpark figure to pay for this mock-up. It is a good way to hedge the risk and still be fair to both you and the vendor.

3. Check the Email Service Provider​

From my experience, when a business owner wants to create his or her own website, that usually means there is no decent email service as well.

By "decent" I mean an email address ending in the same domain as your website. That means no @singnet.com.sg, @gmail.com, or @outlook.com addresses.

This is another topic that warrants another article. For now just be aware that there are many email server options that may be close in price but vary greatly in terms of features and functions.

I think that Gmail has set the gold standard for email service. To me, an inbox capacity of less than a gigabyte is not considered usable given the propensity for people to send large attachments nowadays.

Yet, there are still traditional providers that provide (understandably small capacity) email accounts along with web hosting as a package on the cheap. While that might sound nice, especially for the start where you think "I can just change when my business grows", the reality is typically different.

Email is a critical business function in the work environment. When you start outgrowing your meagre inbox capacity, you'll start to experience all the inefficiencies and potential lost businesses due to a full inbox.

If you then want to switch to a bigger inbox, and you wish to move the contents from the old inbox to the new one, there is then this email migration cost that you will have to factor in. This migration cost is significantly higher than the subscription price of your email service. Unless… you are alright with putting up with the inconvenience of switching between your old inbox and the new one (and potential confusion that comes with it).

Bear in mind that this does not affect just yourself but the other coworkers in your company that have an inbox. So any inefficiency/lost productivity is magnified.

In summary, if you want to avoid this kind of headaches and potential lost productivity, be sure to get your email hosting solution right at the start.

(If you want to have the Gmail equivalent experience for your inbox, use G Suite! If you decide to go with that, hit me up! I've got promotion codes for you that give you 20% off the first year subscription per user. Also, I get a commission 😉)

So that's it. These are the three things that I would advise anyone thinking of commissioning a website to establish a web presence. Reach me on Twitter (@chuacheehow) if you have any questions.

(Also posted on Medium and LinkedIn.)

My thanks go to Abdul Rahman for helping with proofreading.

Two months ago I left the company which I co-founded 13 years back. Here are some of my takeaways after 13 years as its CTO.

But first, an introduction.

Back story​

We are a company focused on education technologies that improve the pedagogical aspects of learning in schools.

Throughout our 13 years of operation, we've taken on work and projects of different scopes. We started with software training for adults. Back then Photoshop and its ilk from Adobe, and Dreamweaver and the Macromedia suite of applications were the must-knows for image manipulation and Web development.

Business was slow. A year or two after we started, we reached an inflection point. We had to decide to wind up or to pivot to a different business scope. Being the young and full-spirited youngsters we were, we wanted to give entrepreneurship another shot before throwing in the towel. With a stroke of luck, through the relationship that one of the founders had with people from Novell, we got on board a programme to supply training services to public schools.

Back then, there was a strong emphasis on graphical programs and interactive multimedia as a result of the Ministry of Education (MOE) IT Master Plan. With the fortuitous early investment (of time) I made into learning the Adobe and Macromedia suite of programs (think Photoshop, Flash, Dreamweaver and the likes), I was able to conduct the courses that we pitched to the schools.

Thanks to our partnership with Novell, we were able to gain some traction with school trainings. As Novell had acquired SUSE Linux not too long back, we also had the privilege of introducing Linux to schools. It was also then that I really sunk my teeth into Linux. (Since then, I've switched to using Linux on the desktop exclusively. I'm very thankful for that chance to really learn Linux well.)

The margins from training were already slim back then. Competition was intense, coming from one-person shops to existing incumbents. We thus had to be opportunistic, grabbing all kinds of deals that came our way. Along the way, through Novell and other channels, we also got a few deals that involved server deployment - completely unrelated to education.

As the sole technical founder, I had to equip myself with knowledge of Linux server deployment to perform the actual deployment while also conducting trainings in schools.

When it comes to the choice of projects, we were really not discerning, all in the name of survival. In 2006 (I think), we even clinched the deal for technical support for the Nokia phones distributed to the attendees of the International Monetary Fund (IMF) conference in Singapore.

Google​

Sometime between 2006 and 2008, we had our first contact with Google. At that time, they were located at Shenton Way where they took up an entire floor (or was it two?) in AXA Tower.

It was also then when we were introduced to what is now known as G Suite. We were early to the party. Being education focused, we were the first to introduce Google Apps, as it was then called, to schools.

We also became a reseller, selling Google Apps to commercial entities (the education edition is free of charge to educational institutes).

That went on for a while until we also became a Chrome Device Management license reseller with our own brand of Chromebooks.

Applications​

Along the journey, we also created a plethora of applications:

• Chromeclass (software to manage student Chromebooks),
• Woma (workload management tool for Google Classroom),
• WebNap (cyber safety testing tool),
• Jotterlab (this name was used for different projects as we groomed and killed a few initiatives along the way),
• VLS (stands for Virtual Lab for Science),
• Trusted Network Extension (an IP tracking tool),
• GFlip (video repository for flipped learning),
• Ductbooks (a book delivery and management system),
• Edurious (a component of an learning management platform for low bandwidth environments), and
• Locus (a shared access terminal for Chromebooks with more controls than a Chromebook in Public Terminal mode).

Among these, a third of them were just proof-of-concept. One third of these is still being used by customers. The remaining are in the trash.

Unified vision​

So that was the story for 13 years in a nutshell. When we started, there were four shareholders. When I left, there were only two key decision makers, including myself.

Probably as a result of having only two decision makers, some of my realisations were more palpable than others.

In order for a company to move as a whole, there must be a clear direction to move towards. In corporate speak, this is the company vision and mission.

If there is no consensus as to what the company vision and mission are, then the baseline mission is profit maximisation. The organization then behaves like an indiscriminate eater, gobbling up every piece of morsel that comes its way, regardless if it's toxic or nutritious.

In some cases, a one-off project with seemingly low returns, if any at all, may be necessary as part of an overarching strategy, to augment the company's position in the market. These projects are necessary evils, medicine that the company must take to further its business interests.

In other cases, such one-off projects with seemingly high (potential) returns may feel like the sweet flesh of low lying fruits but they draw the company's resources away from its core focus. In the best case, they are profitable distractions. In the worst case(s), they are loss-making adventures that hold the company back.

Gauging product market fit​

Before committing to making a product, make sure that a good part of the market wants it.

We made the critical mistake of “surveying a market of one”. We didn't do enough market research to identify the market demand for the Web app we were planning to make.

Just because we hear the need from one or two potential customers, it does not mean there is a market demand for a solution. This statement sounds so obvious that it is almost redundant to state it. The problem is that we often fall to the trap of hearing only what we want to hear. When the person at the other end is in 100% consensus with you, it can feel like the whole world is in agreement.

One trick to identify this kind of conversation is when the person makes sweeping statements like “Oh, everyone will need this solution.” It is not so much the accuracy or correctness of the statement (because who knows for sure?) that is the problem but rather that such statements lull the subconscious into thinking that they are facts rather than opinions or guesses.

Ease of use trumps value proposition​

The value proposition provided by an application must be a magnitude greater than the effort to achieve it.

I learnt this lesson from the same failed project that showed the importance of market demand.

The software was to help students become better essay writers by making incremental improvements to their essays through a methodology called “process writing”. With this methodology, students write several versions of an essay. Their peers and teachers can the review the essay and make comments on areas that need improving.

This all sounds good.

The problem is that we did not realise the amount of work required in this process, for both the students and teachers. From the perspective of students, writing just one essay is already a lot of work. To have them write the same essay more than once, in addition to their other assignments, is a tall order. Ditto for the teachers, whose workload is already too much. There is little to no incentive to use such an application.

Despite the premise of the program, it was simply too much additional work for the users. The project was doomed to fail at conception.

What it takes to make good software​

Being able to rapidly prototype an application to validate an idea does not mean it is trivial to write good software.

Very often, in the quest for rapid development, developers have to take shortcuts. Such shortcuts may meet the project's current and immediate goals but are typically detrimental to its future development. Such shortcuts are known as technical debt.

Like financial debt, the more you take on, the deeper you sink. Without understanding this, it is so easy to fall into the trap of thinking that a software project is done once all the checkboxes are ticked.

Feedback loop with early customers has to be proactive and regular. A software product is almost always never done. There are always features to add, and bugs to fix.

The people who put money with you before you have any traction is trusting you with their money. There is a moral imperative to reciprocate that trust by making the product/service the best that it can be. If, however, you need to keep getting different projects then either a) the model of creating your own software is not tenable, or b) the project is not something that the market needs i.e. the project should not exist, and should be trimmed to make space for (allocate resources to) other projects that might have a better chance of succeeding in the market.

In conclusion​

The company is now, and has been for a few years, stable and growing the Chrome business. We would not have imagined the hardware business making up the main chunk of the revenue, and yet, the company now stands as the Singapore's leading company for G Suite and Chrome technology in the education sector. With any luck, the company may still soar to greater heights in the right direction and focus. I wish for only the best to the company and my former colleagues.

(Also posted on Medium and LinkedIn.)

In the previous article, I wrote about my attempt at improving my pitches. I left off from that piece with the promise of a formula that can improve the quality of your slide decks immediately.

The answer: storytelling.

The problem with this statement is it seems too simple, even patronizing, an answer.

From another perspective, it could be that because the answer is so simple, it is easy to dismiss.

But if you can take a moment to digest this answer, you will begin to realise that it makes sense. Notice that in any TV series, every episode tries to end with a cliffhanger. Producers do that because they know that it makes the audience look forward to watching the next episode to find out what happens next, that they want to “fill in the gap” in the whole story.

Storytelling is a process from the start to the end. Anything missing in this process is a gap. No one likes gaps. Everyone wants closure. That’s why it is more painful to lose a loved one suddenly because we lose the chance to say our last words - closure.

Every Hollywood movie nowadays have equally stunning visual effects but what makes one movie A-grade and another subpar is really the quality of the story, an element that is not as much observed as it is felt.

“If storytelling is the answer, then what is the formula?” I can already imagine this question surfacing in your mind as you read this.

The answer can be found from this Medium piece by Andy Raskin.

I replicate below the points which he made in that article:

1. Name the enemy
2. Answer “Why now?”
3. Show the promised land before explaining how you’ll get there
4. Identify obstacles—then explain how you’ll overcome them
5. Present evidence that you’re not just blowing hot air

If you are really interested in brushing up your presentations, go read that piece. It’s only a 5-minute read.

I also like to share this video series on YouTube featuring Ira Glass from This American Life where he talks about creating compelling storylines using anecdotes and a series of actions and questions.

I’m certainly no presentation expert (far from it), but by just applying what I’ve learnt from the Raskin article and Glass videos, I do think that my works have improved from what they were before.

I hope they will do the same for you. Share your thoughts with me in the comments below or on Twitter @chuacheehow

(Also posted on Medium and LinkedIn)

I’m always looking for ways to improve my presentations. Oftentimes, I only get one chance to get my point across and I want to make every such opportunity count.

I had once thought that the key to well done presentations is a slick, animated slideshow with concise key points. Now I know better. What you use as the visual material is secondary to what you are saying and how you say it.

I would attribute the “how you say it” to the command and fluency of the language that you are presenting in. This has to do with the richness of your vocabulary and the structure of the sentences that you articulate during the presentation. Your language skills, like any other skills, can only be improved through repeated practice. So there’s that.

“What you say” though are the contents of your presentation. Some might argue that how you say it is more important then what you say. That argument, I think, is probably only true for the very few speakers who seem to naturally exude such charisma that can charm the masses. Needless to say, that is certainly not an attribute that the large majority of us can emulate.

Contents, however, are highly malleable. They are the one thing in the presentation that you can change with ease. What is not as easy is to know what to change it to.

We all want an easy-to-apply formula that we can use on our presentation decks right now while we polish up our language skills and vocabulary gradually. But does such a formula exist? If so, it sounds too good to be true, isn’t it?

What if there is such a thing? And that it is the same formula that differentiates an A-grade movie from a B-grade one.

If you feel that all the presentations that you have ever done in your life are, how should I say, lacklustre, then you can probably see a great improvement in your slide decks simply by applying this formula. I know that it works for me.

Like any good show, I am going to leave this post on a cliff-hanger and come back with the second and final part of this article next time.

(Also posted on Medium and LinkedIn)

Several months back I was addicted to Twitter. Any time I can pull out my phone, I would be checking my Twitter feed.

It's a time waster. Prolific YouTuber Dr Derek Muller describes it as a part of the distraction economy.

I had even gone to the extent of checking for more updates when I had finished everything in my feed. What was the use of that? Is there anything to gain from all that time spent reading little messages from strangers?

Given that each message is at most 140 characters, surely Twitter's only value is for newsy stuff right? Well, that's mostly true but every now and then, you can find a gem of wisdom among the stream of ramblings.

And found one I did. I don't remember the exact wording but the gist revolves around these two sentences:

"Why is this job important?"

"What you will learn in this job."

This was posted by someone who was in the position of hiring (programmers I think). He found that by including these two points in a job advertisement, it helped to attract more quality candidates than not.

After parsing through the sentences, I can see why. The first point "What is this job important?" probably does not make sense to a lot of people why it would help. The second point "What you will learn in this job." is probably more obvious. Clearly it speaks to people who want to learn more. Beyond that though, if we delve a little deeper into the characteristics of the people who place emphasis on it, we can easily see that these are people who want and desire to acquire new knowledge.

Naturally, if I were to infer another characteristic that makes such a person perpetually curious, it would be interest, or for some, passion. Only when you have interest/passion in a job, would you be always keen to learn more. And a person who is interested/passionate can be counted on to complete the tasks satisfactorily, not necessarily to the supervisor but simply to herself.

What about the first point? What can we infer from it?

A disassociated worker likely doesn't give a damn about why the job is important. I can think of two traits in an individual who does give a damn.

One is the ability to think at a higher level, "see the big picture", and understand and appreciate the role that she is playing in the organization for the job that she is doing.

The other is an innate desire for self actualization. For some people, the knowledge that one has a significant role to play in the company provides the extra motivation to work hard. I think that's probably the reason why some people stay behind after office hours to complete the task at hand whereas others adopt a "couldn't care less" attitude in the office.

Simply adding these two points in the job advertisement will not magically filter out the dispassionate candidates, but you can leverage these two points during the interview to "suss" out these hidden personality traits in the candidates.

If you are in a position of hiring, try this out the next time a position is available and see if it works for you.

Given the setup below, I would have been a little hesitant as to what the right answer is.

function Alpha() {
    this.name = 'A';
}

Alpha.prototype.say = function () {
    return this.name;
}

function Beta() {
    this.name = 'B';
}

Beta.prototype.say = function () {
    return this.name;
}

var name = 'G';

function say() {
    return this.name;
}

function echo(action) {
    console.log(action());
}

a = new Alpha();
b = new Beta();

a.say(); // returns A
b.say(); // returns B
say(); // returns G

Nothing fancy up to this point. But the next 2 lines will make me think a bit.

echo(a.say);
// Output: 'G'
echo(a.say.bind(a))
// Output: 'A'

This next part is the kicker.

function Delta() {
    this.name = 'D';
    this.say = this.say.bind(this);
}

Delta.prototype.say = function () {
    return this.name;
}

d = new Delta();

d.say();
echo(d.say);

What do you think the output is?

ANSWER​

Both lines output "D".

This example shows that there is a case for early binding even on prototype methods.

At that point in time, the G4 was considered slightly below par compared to the Note 5, in terms of price and branding. I had aimed for a V10 but there was completely no news about it being available in Singapore.

Despite being a flagship phone for Samsung, there were plenty of reasons for not choosing the Note 5 then - the stylus problem, the non-removable battery and the lack of external storage. I had no regrets not selecting the Note 5.

Notwithstanding all the shortcomings, I had a more pragmatic reason for choosing the G4 over the Note 5 though - price. To me, it was that I did not think that the Note 5 was worth the extra money over the G4; all the features that the phone touted (and the Samsung branding) were not worth the premium over the G4.

Now, my stance is more opinionated - I think the support for LG is simply better than the Samsung. In the time between my wife getting her Note 5 to her first OS upgrade from Android 5.1 to Android 6, I had already gotten three updates. My G4 was revved up to Android M months before her Note 5 was upgraded. My G4 also got another update recently, though I'm not sure what the upgrade was - my assumption is that it is for some security patches.

Regardless of the reason for the latest update, the fact that LG has provided more frequent updates than Samsung has (for its flagship phone no less) is enough reason for me to not choose Samsung phones again.

P.S. I had begun writing this article before the Note 7 battery problems surfaced so the battery problem wasn't the genesis for my opinion.

(2023 February note: Disqus was not enabled after the switch to Docusaurus)