Forem: TypeScript TV

It's Easy To Switch from CommonJS to ES Modules with TS2ESM

Benny Code — Mon, 30 Oct 2023 16:23:12 +0000

Migrating a TypeScript project from CommonJS to ESM is now incredibly simple, thanks to the TS2ESM tool and the configuration fixes in TS 5.2.

You can achieve this in just 5 simple steps:

Set type to module in your package.json
Set module to nodenext in your tsconfig.json
Set moduleResolution to nodenext in your tsconfig.json
Globally install ts2esm by running npm i -g ts2esm
Execute the ts2esm command within your project's directory

As a result, you'll see that all your relative import and export statements now either include an explicit ".js" extension or "index.js" suffix, as is required for ECMAScript modules.

The ts2esm command will also enhance imports from JSON files in your TypeScript code by using import assertions:

import fixtures from '../test/fixtures.json' assert {type: 'json'};

Video Tutorial

TypeChat: Eliminating Hallucinations in AI with TypeScript

Benny Code — Tue, 01 Aug 2023 17:00:00 +0000

Modern AI systems face a challenge called "hallucinations", where a Large Language Model (LLM) generates made-up responses to prompts. Even ChatGPT by OpenAI can experience this issue. ☠️

While it's okay for creative prompts, like "create a story about flying elephants playing soccer", we need often need reliable and accurate responses. That's where Microsoft's TypeChat comes to the rescue with its schema engineering approach.

Developers can define intent types using simple TypeScript. TypeChat then transforms prompts into JSON payloads matching with your business logic.

With just 5 minutes of setup, you're good to go! Say goodbye to AI hallucinations and welcome reliable and accurate responses with TypeChat:

What is control flow based narrowing in TypeScript?

Benny Code — Mon, 05 Jun 2023 17:44:33 +0000

Control flow based narrowing refers to a type inference technique that allows the TypeScript compiler to narrow down the type of a variable based on the analysis of its control flow within conditional statements (such as if statements and switch statements).

When TypeScript analyzes the control flow of a program, it can determine certain conditions that guarantee the state of a variable. This analysis helps TypeScript to infer a more specific type for that variable within the respective branch of the control flow.

Consider the following TypeScript code snippet:

function processValue(value: string | number) {
  if (typeof value === "string") {
    // TypeScript knows here that `value` is of type `string`
    console.log(value.toUpperCase());
  } else {
    // TypeScript knows here that `value` is of type `number`
    console.log(value.toFixed(2));
  }
}

In this example, TypeScript uses control flow based narrowing to determine that within the if block, the variable value is a string. Conversely, in the else block, it knows that value is a number.

This enables the compiler to provide more accurate type checking and enables developers to use the appropriate properties or methods specific to each type without explicit type assertions.

Control flow based narrowing is a powerful feature of TypeScript that enhances type safety and helps catch potential errors at compile-time by providing more precise type information based on the analysis of control flow within the code.

Control Flow Based Type Analysis

This video tutorial demonstrates control flow based narrowing:

Interested in learning more? 🎓

I've spent years working with the TypeScript programming language and have encountered its various challenges. That's why I've recorded a series of free TypeScript video tutorials, designed to help you enhancing your coding skills.

I invite you to take a look at them and provide your feedback on the videos. I'm eager to hear your thoughts and impressions. 👀

Why TypeScript is the better JavaScript

Benny Code — Sun, 07 May 2023 18:45:07 +0000

JavaScript is a powerful and widely used programming language for web applications. However, it can sometimes lead to unexpected results and errors due to its dynamic type system. In this blog post, we'll examine some of the most common errors that arise in JavaScript, and explore how TypeScript, a superset of JavaScript, can help prevent these issues with improved type safety and error handling.

Common JavaScript Errors

JavaScript is a beginner-friendly language due to its minimal setup requirements. However, the language's limited syntax and dynamic typing often lead to errors, making it challenging for even those who are familiar with the language.

Here are a few common errors when working with JavaScript:

Unexpected string concatenation: Mixing numbers and strings can lead to undesired results, such as console.log(10 + '100') outputting 10100 instead of the expected 110.

Stringified object concatenation: Using an object as an argument will result in a stringified version of the object combined with the other argument, e.g., console.log({} + '10') returns [object Object]10.

TypeError: Accessing properties of an object that are undefined or calling a non-function will trigger a TypeError, such as caught TypeError: Cannot read properties of undefined (reading 'data') when calling console.log({}.input.data).

NaN: Forgetting to pass an argument results in a non-existent number, commonly referred to as NaN for "Not a Number". Example: console.log(parseInt())

ReferenceError: Using an undeclared variable results in a ReferenceError, such as console.log(10 + abc).

Not defined functions: Calling functions that don't exist will also throw a ReferenceError. Example: console.log(abc())

TypeScript to the Rescue

TypeScript is a programming language developed and maintained by Microsoft that adds type safety to JavaScript. By using TypeScript, you can catch errors during design time (when writing code) rather than at runtime. This will help you catching common JavaScript errors before they appear in production. TypeScript code is compiled (or transpiled) to JavaScript, ensuring compatibility with web applications.

Why Use TypeScript?

TypeScript offers several benefits, including:

Strong type checking to catch errors before runtime
Code autocompletion in your IDE for a smoother coding experience
Fundamental linting rules, including detection of unused variables and parameters
Const assertions to avoid side effects in functional programming
Class decorators to facilitate dependency injection
Inherent support for JSX in the language itself
Downleveling to convert modern JavaScript to earlier versions of JavaScript
Compatibility with various module systems, such as CommonJS and ECMAScript modules (ESM)
Customizable output formatting options, including end-of-line sequence formatting
Support for polymorphism via class inheritance and interfaces in object-oriented programming

Getting Started with TypeScript

As an experienced TypeScript contributor, I've spent years working with the language and have encountered its various challenges. That's why I've created a free TypeScript video tutorials, designed to help you master the latest version and enhance your coding skills. This series focuses on the fundamentals of TypeScript, ensuring you not only grasp how things work, but also why they work the way they do.

This knowledge can be a valuable asset as you progress from a junior to a senior programmer, and can even assist you in tackling difficult questions during job interviews. The best part? This entire tutorial series is available at no cost, so tune in and enjoy your journey towards TypeScript mastery.

Understanding npm Versioning

Benny Code — Tue, 04 Apr 2023 15:00:00 +0000

In the world of software development with JavaScript and TypeScript, it is crucial to manage the versions of packages used in your projects. This blog post will show the details of npm package management, specifically focusing on the caret (^) and tilde (~) symbols, as well as other versioning notations. Get ready to better understand how to manage your project's dependencies and establish reproducible builds with consistency in package versions!

Major, minor, patch

The npm ecosystem uses semantic versioning where version numbers typically consist of three parts, separated by dots: major.minor.patch. These parts represent different types of changes made to the software, and are used to help developers and users understand the significance of a given version number.

Major version

The major version number is typically incremented when there are breaking changes to the software. It indicates that the software is no longer backwards compatible with previous versions, and users may need to make changes to their code in order to upgrade.

For instance, API contracts may change if parameters are modified:

Version 1.0.0



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

Version 2.0.0

The API contract for Version 1.0.0 has been violated due to changes in the input parameter types for a and b. As a result, Version 2.0.0 must be introduced to address this breaking change:



export function add(a: string, b: string): number {
  return parseInt(a, 10) + parseInt(b, 10);
}

Important: Following the npm guidelines, you can make breaking changes in your APIs as long as you are below version 1.0.0. When your package is in major version zero (e.g., 0.x.x), the semver rules change slightly. In this case, breaking changes occur in 0.x.x (minor-level), while new features and patches are implemented in 0.0.x (patch-level).

Minor version

The minor version number is typically incremented when new features are added to the software, or when there are significant enhancements or improvements to existing features. These changes are usually backwards compatible, meaning that users can upgrade to the new version without having to make major changes to their code.

Version 1.0.0



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

Version 1.1.0

The add function has been updated to accept an indefinite amount of numbers, improving on its original implementation. This update does not affect prior API calls, as the function can still be used by providing just two numeric arguments, maintaining backwards compatibility.

In addition to the existing add function, a new subtract function has been added. It requires a minor release (1.1.0) to introduce these new features:



export function add(...numbers: number[]): number {
  return numbers.reduce((sum, current) => sum + current, 0);
}

export function subtract(a: number, b: number): number {
  return a - b;
}

Patch version

The patch version number is typically incremented when bugs or security issues are fixed in the software. These changes are generally small, and do not involve major changes to the functionality or features of the software.

Let's assume we updated the subtract function from version 1.1.0 to 1.2.0, adding the ability to also accept an indefinite amount of numbers as input:

Version 1.2.0



export function subtract(...numbers: number[]): number {
  return numbers.reduce((sum, current) => sum - current, 0);
}

Suppose we've discovered that using 0 as the initial value for the subtract function was a mistake. Rather than subtracting from 0, we want the function to subtract from the first number that is given as input. As a result, we'll need to release a patch version (1.2.1) to fix this issue:

Version 1.2.1



export function subtract(...numbers: number[]): number {

  return numbers.reduce((sum, current) => sum - current);

}

Understanding Caret (`^`) and Tilde (`~`)

When specifying dependencies in our package.json file, the caret and tilde symbols have special significance in determining the range of acceptable package versions.

Video Tutorial

Caret (`^`)

The caret symbol indicates that npm should restrict upgrades to patch or minor level updates, without allowing major version updates. For example, given "^5.0.2", npm will permit updates within the same major version (e.g., 5.1.0, 5.0.3), but not a jump to a new major version (e.g., 6.0.0) when running npm update.

Tilde (`~`)

By altering the caret symbol to a tilde symbol, we would only receive updates at the patch level. If we were to use "~5.0.2", we would obtain version 5.0.3 if it were available, but not 5.1.0.

Trick to remember

A helpful way to remember the difference between these symbols is by envisioning a house: the tilde is the floor, while the caret represents the rooftop, enabling you to reach higher version numbers:

Alternative Versioning Notations

If you're not concerned with specifying the precise minimum version and simply want to obtain the most recent version in a certain range, you can use alternative notations.

Latest Patch Version

To get the latest patch version, use the notation 5.0.x. This will install the most recent version with the given major and minor numbers (e.g., 5.0.6).

Latest Minor and Patch Versions

Similarly, to obtain the latest minor version, along with its most recent patch, use the notation 5.x.x. This will permit updates within the same major version, but without restrictions on the minor version (e.g., 5.1.3 or 5.2.0).

Updating Dependencies

It's essential to properly manage your dependency updates when changing version numbers in your package.json file.

npm install

Executing the npm install command installs a package's dependencies and any dependencies that these dependencies rely on (transitive dependencies). It also creates a package-lock.json file if it doesn't exist.

Important: It is worth mentioning that npm install will download compatible versions when there is no package-lock.json file present. This means that the version you receive may not be the latest minor version, even if you've specified a version range using the caret symbol.

Example

If you've included typescript@^4.8.3 in the devDependencies section of your package.json file, you may expect to receive the latest minor version (currently 4.9.5) when you run npm install. However, you will receive the latest patch version (4.8.4) as it is compatible with your version range. In order to obtain 4.9.5, you will need to execute npm update.

Dependency	npm install	npm update
`typescript@~4.8.3`	`4.8.4`	`4.8.4`
`typescript@^4.8.3`	`4.8.4`	`4.9.5`
`typescript@4.8.X`	`4.8.4`	`4.8.4`
`typescript@4.X.X`	`4.9.5`	`4.9.5`

npm update

To apply changes to the version numbers in your package.json, use the npm update command. Unlike npm install, which only downloads a compatible version, npm update will also update the package to the latest version that matches the specified range. Additionally, the package-lock.json file will be updated.

Recording Exact Versions

You might wonder: "How can I determine which version was actually downloaded?" That's where the package-lock.json file comes in. This file records the exact version retrieved during the initial installation, or any subsequent updates.

With a package-lock.json file in place, future runs of npm install will download the same build, ensuring reproducible results for your project's dependencies. This is particularly important in collaborative development environments, where multiple team members work on the same project, as it guarantees consistency across all installations.

Traffic Light Control

If you use the Yarn Package Manager instead of npm and run the command yarn upgrade-interactive --latest, you'll see a color-coded legend that indicates the likelihood of a package update breaking your code:

Patch updates are indicated in green, as they typically include backward-compatible fixes and pose the least risk of breaking your application
Minor updates are indicated in yellow, as they typically involve more changes than patch updates and therefore carry a higher risk of causing issues if their package maintainers don't strictly adhere to semantic versioning guidelines
Major updates are indicated in red, as they often include backward-incompatible changes that may require you to update your code in order to maintain compatibility

Screenshot

Conventional Commits

As we've learned, major version updates should only be issued when there are breaking changes. To draw attention to a breaking change, the Conventional Commits specification suggests using an exclamation mark (!) after the type or scope in a commit message.

Example

refactor(api)!: use stringified numbers in calculations

Tools for publishing, such as Lerna (when using the --conventional-commit flag), follow this convention when incrementing package versions and generating changelog files.

Publishing packages

Publishing packages with npm is a crucial step in sharing your code with the wider community. The npm CLI provides commands (npm version and npm publish) to assist with proper versioning and release of your own packages, in accordance with semantic versioning rules.

Video

npm version

The npm version command is used to update the version of a package in the package.json file. If run in a Git repository, it will generate a Git tag and a new commit with a message that includes the version number.

npm publish

The npm publish command is used to publish the package to the registry, making it available for installation by others.

Release Workflow

The npm version and npm publish commands can be used to set up release workflows within the scripts section of a package.json file:



{

  "scripts": {

    "preversion": "git checkout main && git pull && npm install && npm test && npm run build",

    "release:major": "npm version major",

    "release:minor": "npm version minor",

    "release:patch": "npm version patch",

    "postversion": "git push origin && git push origin --tags && npm publish --access public"

  }

}

Conclusion

In this blog post, we've explored the significance of the caret and tilde symbols in npm versioning, as well as alternative versioning notations. We've also looked at how to use the npm update command and the importance of the package-lock.json file.

With a better understanding of npm package management and the tools available to manage dependency versions, you can ensure a stable, consistent, and reproducible development environment for your projects. Happy coding!

What is the difference between null and undefined?

Benny Code — Sun, 12 Mar 2023 17:28:15 +0000

The convention in TypeScript is that undefined values have not been defined yet, whereas null values indicate intentional absence of a value.

Example with `null`

The below function shows how null can be used by returning an object that always has the same structure, but with intentionally assigned null values when the function does not return an error or result:

function divide(a: number, b: number) {  
  if (b === 0) {  
    return {  
      error: 'Division by zero',  
      result: null  
    };  
  } else {  
    return {  
      error: null,  
      result: a / b  
    };  
  }  
}

Example with `undefined`

On the other hand, undefined represents the absence of any value. It is a value that is automatically assigned to a variable when no other value is assigned. It often indicates that a variable has been declared but not initialized. It can also signify a programming mistake, such as when a property or function parameter was not provided:

let ratio: number | undefined;  

if (ratio === undefined) {  
  console.log('Someone forgot to assign a value.');  
} else if (ratio === null) {  
  console.log('Someone chose not to assign a value.');  
}

Best Practice

The TypeScript Coding guidelines recommend using only undefined and discouraging the use of null values (see here). It is important to note, however, that these guidelines are tailored towards the TypeScript project's codebase and may not necessarily be applicable to your own projects.

Want more?

If you found this short explainer helpful, hit that subscribe button on my YouTube channel or give me a follow on Twitter to level up your TypeScript game.

Best practices with const assertions in TypeScript

Benny Code — Tue, 03 Jan 2023 18:38:14 +0000

TypeScript 3.4 introduced const assertions, a feature that allows you to claim a value as immutable. This feature is particularly valuable in combination with array literals, as it prevents new values from being pushed into an existing array.

const declarations

A const declaration only makes the array reference immutable.

Example

// 'const' only makes the array reference immutable
const myArray = [1, 2, 3];
// Values of the array can still be removed
myArray.pop();
// ...or pushed
myArray.push(4);
// ... but reassignments become impossible
// TS2588: Cannot assign to 'myArray' because it is a constant.
myArray = [4];

const assertions

With a const assertion you will get immutability for your array reference and array values at design-time.

Example

// A 'const assertion' protects the reference and elements of your array
const myArray = [1, 2, 3] as const;
// TS2339: Property 'pop' does not exist on type 'readonly [1, 2, 3]'.
myArray.pop();
// TS2339: Property 'push' does not exist on type 'readonly [1, 2, 3]'.
myArray.push(4);
// TS2588: Cannot assign to 'myArray' because it is a constant.
myArray = [4];

Important note

One important thing to note is that const assertions are a TypeScript feature at design-time and do not actually make values immutable at runtime. This means that you will still be able to modify values at runtime using plain JavaScript. If you want to achieve a higher level of immutability, you can make use the Object.freeze() API.

Example

const myArray = [1, 2, 3];
// The static 'freeze' method makes your array immutable at runtime
Object.freeze(myArray);
// This will happen when you try to manipulate your array in JavaScript:
// Uncaught TypeError: Cannot add property 4, object is not extensible
myArray.push(4);

Best Practice

You can combine a const assertion with Object.freeze to get type safety at design-time and runtime:

// Protection at design-time
const myArray = [1, 2, 3] as const;
// Protection at runtime
Object.freeze(myArray);

as const with objects

A const assertion can also protect an object literal by marking its properties as readonly:

// Protect your object properties from changes at design-time
const objectLiteral = {
  age: 35,
  name: 'Benny'
} as const;

// TS2540: Cannot assign to 'age' because it is a read-only property.
objectLiteral.age = 30;

as const with strings

You can narrow the type for a string to a specific string using as const:

// Don't use an explicit return type to make use of type inference
function getName(firstName: string, lastName: string) {
  return `${firstName} ${lastName}` as const;
}

let displayName = getName('Benny', 'Code');
// TS2322: Type '"..."' is not assignable to type '`${string} ${string}`'.
displayName = '...';

Alternative Options

You can use the ReadonlyArray type of TypeScript 3.4 to disallow array value modifications at design-time:

Example

const array: ReadonlyArray<number> = [1, 2, 3];
// TS2339: Property 'pop' does not exist on type 'readonly number[]'.
array.pop();

Shorthand Syntax

const array: readonly number[] = [1, 2, 3];
// TS2339: Property 'pop' does not exist on type 'readonly number[]'.
array.pop();

Video Tutorial

Getting started with GitHub Actions and workflows

Benny Code — Sun, 03 Apr 2022 12:55:37 +0000

GitHub Actions are a great way to automate your own software development cycle. GitHub Actions are free of charge for public repositories and provide you with a whole CI/CD platform. It allows you to automate all parts of your software supply chain and run it in virtual environments or even your own environment using self-hosted runners.

Much of what used to be done with a Jenkins job can now be done with GitHub Actions. In this article, I will give you a quick start in GitHub Actions and explain what actions, workflows, events, jobs and steps are. As an example we take a JavaScript application for which we set up a test automation.

What are GitHub Actions?

GitHub Actions are reusable scripts that can be used on GitHub's platform for continuous integration and continuous delivery (CI/CD). You can write your own actions using JavaScript (and other languages) or use published actions from the GitHub Marketplace.

There are already actions for various tasks like sending a message to a Slack channel (slack-send), uploading code coverage reports (codecov) or deploying code to the Google Cloud (setup-gcloud). In this tutorial, we will use existing GitHub Actions and wire them together in a so-called "workflow".

What are workflows?

A workflow is a description for your CI/CD pipeline on GitHub Actions. A workflow always runs one or more jobs and each job consists of steps which can be calls to GitHub Actions or regular shell commands. A workflow is triggered by an event (e.g. a commit in your branch) and runs on a virtual environment on GitHub (called "hosted runner") or your own environment (called "self-hosted runner").

Test Automation with GitHub Actions

To ensure that pull requests are compatible with your code, you can setup a GitHub workflow to run a test automation pipeline. I will show you how to do this by using a JavaScript demo project for which we will run npm test when new code comes in.

Setting up a workflow

Setting up a workflow is done by creating a YAML file inside of the .github/workflows directory of your repository on GitHub. We will save our test automation in test.yml:

.github/workflows/test.yml



# Name of our workflow
name: 'Test'

# Events that will trigger our workflow
on: [ 'pull_request', 'push' ]

# List of custom jobs
jobs:
  # Job is called "test"
  test:
    # Using a "label" to assign job to a specific hosted runner
    runs-on: ubuntu-latest
    steps:
      # Checks-out our repository under "$GITHUB_WORKSPACE", so our job can access it
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      # Runs commands using the runners shell
      - name: 'Run tests'
        run: npm ci && npm test

Specify Node.js version

GitHub provides hosted runners which can run your workflow in different virtual environments. The "ubuntu-latest" environment already contains a recent version of Node.js which is ideal for testing JavaScript applications.

You can also use the setup-node action to configure any Node.js version you like to use:



name: 'Test'

on: [ 'pull_request', 'push' ]

jobs:
  test:
    # Using a build matrix to route workflow to hosted runner(s)
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      # Uses specific version of Node.js
      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: 'Run tests'
        run: npm ci && npm test

Define workflow triggers

Currently our workflow is executed on every git push event and every event in a Pull Request. Pushing commits in a PR triggers our action twice because it is a push event and an event in our PR. To prevent this, we can restrict the events that trigger our workflow. We will limit the push events to the "main" branch, which is useful when we squash and merge a PR into our "main" branch:



name: 'Test'

on:
  pull_request:
  # Limit push events to "main" branch
  push:
    branches: [ 'main' ]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: 'Run tests'
        run: npm ci && npm test

Note: Simply leave the value for pull_request empty to match any branch name.

Run workflow manually with `workflow_dispatch`

We can also define a workflow_dispatch trigger which will allow us to run a workflow manually from the "Actions" tab of our repository:



name: 'Test'

on:
  pull_request:
  push:
    branches: [ 'main' ]
  # The "workflow_dispatch" event gives us a button in GitHub's "Action" UI
  workflow_dispatch:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: 'Run tests'
        run: npm ci && npm test

Screenshot:

Run multiline shell commands

When working with TypeScript, it is advisable to check the validity of your types before running tests. This way errors can be catched even before setting up the test runner. We will accomplish this by running tsc --noEmit just before executing our test script. In order to have a better overview of our commands, we will replace the && link with a multiline command using the pipe (|):



name: 'Test'

on:
  pull_request:
  push:
    branches: [ 'main' ]
  workflow_dispatch:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:      
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      # Runs multiple commands using the "|" operator
      - name: 'Run tests'
        run: |
          npm ci
          npx tsc --noEmit
          npm test

Skip workflow execution

We can prevent our full test setup from running when adding a specific text (like [skip ci] or [ci skip]) in our commit message:



name: 'Test'

on:
  pull_request:
  push:
    branches: [ 'main' ]
  workflow_dispatch:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    # Condition to run the job using GitHub's event API
    if: |
      contains(github.event.commits[0].message, '[skip ci]') == false &&
      contains(github.event.commits[0].message, '[ci skip]') == false
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:      
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: 'Run tests'
        run: |
          npm ci
          npx tsc --noEmit
          npm test

Note: By default GitHub skips checks for commits that have two empty lines followed by skip-checks: true within the commit message before the closing quotation:



git commit -m "Some commit message
>
>
skip-checks: true"

Using expressions in workflows

The workflow syntax for GitHub Actions allows us to use expressions. There is a set of built-in functions, like success() and failure(), that can be used in expressions and are very handy to check the status of your workflow. We will use failure() to send a message to our Slack channel whenever our tests fail:



name: 'Test'

on:
  pull_request:
  push:
    branches: [ 'main' ]
  workflow_dispatch:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    if: |
      contains(github.event.commits[0].message, '[skip ci]') == false &&
      contains(github.event.commits[0].message, '[ci skip]') == false
    strategy:
      matrix:
        os: [ 'ubuntu-latest' ]
        node-version: [ '16.x' ]
    steps:
      - name: 'Checkout repository'
        uses: actions/checkout@v3

      - name: 'Use Node.js v${{ matrix.node-version }}'
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: 'Run tests'
        run: |
          npm ci
          npx tsc --noEmit
          npm test

      - name: 'Post error notification to Slack channel'
        uses: slackapi/slack-github-action@v1.18.0
        # Use built-in function in expression
        if: ${{ failure() }}
        with:
          channel-id: my-channel
          slack-message: 'Test run <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|${{ github.run_id }}> failed.'
        env:
          SLACK_BOT_TOKEN: ${{ secrets.MY_SLACK_BOT_TOKEN }}

Note: To make use of the Slack Action, you have to create a Slack App for your Slack workspace with an OAuth scope of chat.write. Afterwards, you have to make your "Bot User OAuth Token" available as environment variable (e.g. MY_SLACK_BOT_TOKEN) in your GitHub repository. This can be done in Settings → Secrets → Actions. It will then be accessible in your workflow file using the ${{ secrets.MY_SLACK_BOT_TOKEN }} expression.

Branch protection rules

Once you have a testing workflow and sufficient tests covering your code, you can setup a branch protection rule. This can be done by navigating to Settings → Branches → Branch protection rules → Add rule in your GitHub repository.

The "Branch name pattern" supports fnmatch syntax but also allows to set a single branch name (like "main"). In order to protect your branch from incompatible dependency updates you have to activate "Require status checks to pass before merging". You can use GitHub Actions as status checks by searching for their job names (e.g. "test").

Screenshot:

The branch protection rule will warn you when new code fails your testing pipeline. It will also prevent merging broken code into your "main" branch when you are not an administrator who can override such rules.

Running your GitHub Actions locally

If you want to have faster feedback loops, you can also run GitHub Actions locally using the act cli. It requires Docker and a local installation through your favorite package manager.

After installing "act", you can run it locally from your terminal by passing it the job name of your workflow, e.g. act -j test. It will then download the necessary Docker image. Depending on the complexity of your workflow, this image can be 20+ GB in size. For our small test setup a micro image (below 200 MB) that contains only Node.js is good enough when we remove our "skip ci" condition.

Screenshot:

Where to go from here?

Congratulations! You have just learned the fundamentals of GitHub Actions and you are now able to create your own workflows. With your newly acquired skills, you can build great CI/CD pipelines. 🎊

If you want to learn more about GitHub Actions, then I recommend the following topics:

Run Linux on Windows with WSL 2 & VS Code

Benny Code — Sun, 06 Feb 2022 13:53:42 +0000

The Windows Subsystem for Linux makes it easy to run a Linux environment on Windows. The integration is so seamless and powerful, that you can even connect VS Code to it and execute code automatically in a Linux terminal. With WSL 2 you no longer need Cygwin or MinGW.

Requirements 📝

To install the Windows Subsystem for Linux (WSL), you must have Windows 10 installed (Build 19041 and higher). WSL 2 also requires you to activate Microsoft Hyper-V. If these two conditions are met, you can proceed.

The following post is based on my video:

Install WSL 2 💾

Open Windows PowerShell
Execute wsl --install
Verify your installation with wsl --status

Install Linux 🐧

WSL 2 allows you to install different Linux distributions (Ubuntu, Debian, Alpine Linux & others) from the Microsoft Store. Just open the "Microsoft Store" app and search for your favorite Linux version:

Start Linux on Windows 🏁

Once the Linux installation is complete, you can run it from the Windows Start menu. Here is an example running Ubuntu:

Access Linux Files from Windows 📁

When you start your Linux distribution, all of its files become available in your Windows "Network". Here is how you can see your full Linux filesystem:

Start Linux (Ubuntu app)
Open File Explorer ("Win" + "E")
Enter \\wsl$ in the address bar

Screenshot:

Access Windows Files from Linux 📁

You can also access your Windows NTFS filesystem from Linux. It works like this:

Start Linux (Ubuntu app)
Access your C:\ drive using cd /mnt/c

Screenshot:

Connect Visual Studio Code with Linux 🔗

By default, VS Code on Windows uses the Command Prompt when opening a Terminal. However, you can also run your code from your installed Linux environment. Here's how to do it:

Install the Remote - WSL extension
Click in the lower left corner of your VS Code and choose "New WSL Window using Distro..."
A new VS Code window will open and use your Linux terminal by default

Screenshot:

Use Docker with WSL 2 🐳

You don't have to reinstall Docker on your Linux installation. Docker Desktop for Windows allows you to use Docker from your Linux distribution. You just need to select "Enable integration with my default WSL distro" in "Settings" ➝ "Resources" ➝ "WSL Integration".

Screenshot:

Run Linux GUI apps 🎨

If you have Windows 11 (Build 22000 and higher) installed, then you can also run Linux GUI apps from your Windows system.

Closing Note ✍

I hope you are as impressed by the Windows Subsystem for Linux as I am. Please follow me on Twitter or subscribe to my YouTube channel if you liked this post. I would love to hear from you what you are building. 🙂 Best, Benny

Typing React Props in TypeScript

Benny Code — Wed, 07 Jul 2021 14:31:44 +0000

One advantage of using React with TypeScript is that you can easily type the props of your (function) components. You don't have to use React's PropTypes because TypeScript already has its own typing system.

In the following, I will show you how to define custom props for a component in connection with already existing props like children.

Starting Example

PostPreview.tsx

import React from 'react';

export interface Props {
  heading: string;
}

const PostPreview = (props: Props) => {
  return (
    <div>
      <h1>{props.heading}</h1>
      {props.children}
    </div>
  );
};

export default PostPreview;

As you can see, our PostPreview component has a heading property. The component is supposed to render the heading and other components (children) below the heading. In technical terms this is called Containment.

Because our Props interface only defines the heading, the following error shows up:

TS2339: Property 'children' does not exist on type 'Props'.

Let me show you three different ways to solve this problem.

Solution 1: `PropsWithChildren`

The easiest way to solve the problem is to use the generic type PropsWithChildren. It supports a generic type variable, so that we can use our Props with it:

import React, {PropsWithChildren} from 'react';

export interface Props {
  heading: string;
}

const PostPreview = (props: PropsWithChildren<Props>) => {
  return (
    <div>
      <h1>{props.heading}</h1>
      {props.children}
    </div>
  );
};

export default PostPreview;

The solution is simple, but it doesn't describe our component very well. The compiler knows that our component can have children, but it doesn't know whether our component has other tag-specific properties. We also have to remind ourselves to import React. So let's take a look at a more advanced solution.

Solution 2: `React.FC`

React.FC specifies a function component and lets us also assign a type variable. It uses PropsWithChildren behind the scenes, so we don't have to worry about connecting our Props with it:

import React from 'react';

export interface Props {
  heading: string;
}

const PostPreview: React.FC<Props> = (props) => {
  return (
    <div>
      <h1>{props.heading}</h1>
      {props.children}
    </div>
  );
};

export default PostPreview;

Thanks to the use of React.FC, the TypeScript compiler now knows that our PostPreview constant is a React component. We no longer have to think about importing React ourselves, as the compiler already prompts us to do so. However, the compiler still does not know how our component looks like in detail. It cannot tell whether it is a <div> element or a <p> element or something else. Hence we come to solution number three.

Solution 3: `React.HTMLProps`

The most specialized version is to extend React.HTMLProps. The HTMLProps support a variety of tags (HTMLDivElement, HTMLFormElement, HTMLInputElement, etc.). Make sure that the type variable matches the outmost tag (the first tag, that is mentioned after return):

import React from 'react';

export interface Props extends React.HTMLProps<HTMLDivElement> {
  heading: string;
}

const PostPreview: React.FC<Props> = (props: Props) => {
  return (
    <div>
      <h1>{props.heading}</h1>
      {props.children}
    </div>
  );
};

export default PostPreview;

With this variant our component inherits all properties of a <div> element and extends them with custom props like heading.

Our PostPreview component can now be used as follows:

IndexPage.tsx

import React from 'react';
import PostPreview from './PostPreview';

const IndexPage: React.FC = () => {
  return (
    <div>
      <PostPreview heading="First Post">
        <p>#1</p>
      </PostPreview>

      <PostPreview heading="Second Post">
        <p>#2</p>
      </PostPreview>
    </div>
  );
};

export default IndexPage;

Tested with: React v17.0.2

Get connected 🔗

Please follow me on Twitter or subscribe to my YouTube channel if you liked this post. I would love to hear from you what you are building. 🙂 Best, Benny

6 ways to configure Webpack

Benny Code — Wed, 23 Jun 2021 15:04:47 +0000

Webpack is a build tool to make code, which was not primarily written for execution in browsers, executable in web browsers. With special plugins, webpack can manage many types of code, for example JavaScript, TypeScript, and Rust-generated WebAssembly.

There are webpack plugins to also compile, minify, shim, chunk, and bundle code. However, webpack was not designed to execute tasks such as linting, building, or testing your app. For this purpose, there are task runners such as Grunt, Gulp or npx.

In order to manage the functionality of webpack, it must be configured. Here are six different ways, in which webpack's configuration can be written.

1. Zero Config

As of webpack version 4, you are not required to specify a configuration. By default, webpack assumes that your code starts at src/index.js and will be bundled to dist/main.js. This is very convenient and promotes convention over configuration but it does not use webpack's full potential.

Without a configuration, webpack does not know whether code should be compressed for faster execution or bundled with source maps for better tracking of errors. Webpack expresses its confusion with the following warning:

WARNING in configuration

The 'mode' option has not been set, webpack will fallback to 'production' for this value.

Set 'mode' option to 'development' or 'production' to enable defaults for each environment.

You can also set it to 'none' to disable any default behavior. Learn more: https://webpack.js.org/configuration/mode/

Let's have a look at options to tell webpack how it should be configured.

2. Command Line Interface

To see all available commands and options to configure webpack from the command line interface, you can run webpack --help. This command will show you a list of arguments and how to use them. The following execution mimics the default (zero config) behaviour of webpack:

webpack --entry=./src/index.js --output-path=./dist --output-filename=main.js

As you can see, CLI configurations can become quite long. In order to minimize the writing effort, there is also a shorthand version of the above command:

webpack ./src/index.js -o ./dist

The simplified notation is at the expense of comprehensibility, which is why we will look at configuration files in the next step.

3. CommonJS Configuration File

Webpack can be instructed to read in a configuration file. By default, a file named webpack.config.js is being used. You can create it by using the npx webpack init command or by writing it yourself:

webpack.config.js

const path = require("path");

const config = {
  entry: "./src/index.js",
  mode: "development",
  module: {
    rules: [
      {
        exclude: /(node_modules)/,
        test: /\.(js|jsx)$/i,
        loader: "babel-loader"
      }
    ]
  },
  output: {
    path: path.resolve(__dirname, "dist")
  },
  plugins: []
};

module.exports = config;

The configuration uses the CommonJS module syntax with require and module.exports. Make sure that your package.json does not define "type": "module", otherwise you will receive the following error:

[webpack-cli] ReferenceError: require is not defined

The configuration file should also be in the root of your project.

4. ESM Configuration File

If your package.json file specifies "type": "module" and you want to make use of ECMAScript modules, then you can also modernize your webpack configuration:

webpack.config.js

import path from "path";

const config = {
  entry: "./src/index.js",
  mode: "development",
  module: {
    rules: [
      {
        exclude: /(node_modules)/,
        test: /\.(js|jsx)$/i,
        loader: "babel-loader"
      }
    ]
  },
  output: {
    path: path.resolve("./dist")
  },
  plugins: []
};

export default config;

If you have TypeScript installed, then TypeScript's compiler also allows you to check your Webpack configuration from a JavaScript file once you enable checkJs. All it requires is a @ts-check pragma in the first line of your configuration and a @type reference:

webpack.config.js

// @ts-check
const path = require('path');

/** @type {import('webpack').Configuration} */
const config = {
  entry: "./src/index.js",
  mode: "development",
  module: {
    rules: [
      {
        exclude: /(node_modules)/,
        test: /\.(js|jsx)$/i,
        loader: "babel-loader"
      }
    ]
  },
  output: {
    path: path.resolve("./dist")
  },
  plugins: []
};

export default config;

5. TypeScript Configuration File

For those of you who like to work with TypeScript, webpack offers the possibility to use a configuration file written in TypeScript.

Webpack v5 already ships with TypeScript definitions, so you don't have to install @types/webpack but you need to install typescript, ts-node and @types/node.

Because the extension .ts does not correspond to the standard .js extension, webpack has to be informed about this via the --config argument:

webpack --config webpack.config.ts

You also have to make sure that the test patterns of your "rules" and your "resolve" definitions include the TypeScript extension:

webpack.config.ts

import path from "path";
import { Configuration } from "webpack";

const config: Configuration = {
  entry: "./src/index.js",
  mode: "development",
  module: {
    rules: [
      {
        exclude: /(node_modules)/,
        test: /\.[tj]sx?$/,
        loader: "babel-loader"
      }
    ]
  },
  output: {
    path: path.resolve(__dirname, "./dist")
  },
  plugins: [],
  resolve: {
    extensions: [".js", ".jsx", ".ts", ".tsx"]
  }
};

export default config;

☝️ Because the exemplary webpack configuration loads Babel, we can still point to a JavaScript entry file as Babel makes it possible to use JavaScript and TypeScript code simultaneously.

⚠️ Please note that TypeScript configuration files cannot be used with ESM (see ESM in webpack.config.ts isn't supported).

6. Node Interface

In addition to the execution via webpack-cli, webpack also supports a programmatic interface. This allows you to compile your frontend code on a Node.js server. Here is an example:

import express from "express";
import { webpack } from "webpack";
import webpackConfig, { webappDir } from "../webpack.config.js";

export function useWebpack(app: express.Express) {
  const webpackCompiler = webpack(webpackConfig);
  const webpackDevMiddleware = require("webpack-dev-middleware");
  const webpackHotMiddleware = require("webpack-hot-middleware");

  app.use(webpackDevMiddleware(webpackCompiler));
  app.use(webpackHotMiddleware(webpackCompiler));

  app.use(express.static(webappDir));
}

Instead of consuming your existing webpack.config.js file, you can also pass a configuration object to the webpack API.

Get connected 🔗

Please follow me on Twitter or subscribe to my YouTube channel if you liked this post. I would love to hear from you what you are building. 🙂 Best, Benny

Measure execution times in browsers & Node.js

Benny Code — Sun, 18 Apr 2021 17:55:36 +0000

Measuring your apps performance is very important when your code is being used in production. You should therefore know the execution time of your most frequently used functions. Modern browsers and the Node.js platform provide great APIs to measure performance. In this article, I am presenting a few selected ones using JavaScript and TypeScript code examples.

Business Logic

First of all, we need a function that mimics our business logic. To make it simple, I am using a function which will return a value after 2 seconds (2000ms):

function businessLogic(): Promise<number> {
  return new Promise((resolve) => {
    setTimeout(resolve, 2000);
  });
}

Console Timers (`console.time`)

The easiest way to print the execution time of a function to the console, is to use a console timer. Everything that has to be done, is calling console.time and console.timeEnd with the same identifier:

(async () => {
  console.time('businessLogic');
  await businessLogic();
  console.timeEnd('businessLogic');
})();

As a result, we get the execution time printed to our console in a human-readable format (can be milliseconds, seconds, or other resolutions):

businessLogic: 2.012s

High Resolution Timers (`performance.now`)

If you want to customize the output of your profiling, then you can use a high resolution timer like performance.now. It will return the measured execution time in 1 millisecond increments:

(async () => {
  const start = performance.now();
  await businessLogic();
  const stop = performance.now();
  const inSeconds = (stop - start) / 1000;
  const rounded = Number(inSeconds).toFixed(3);
  console.log(`businessLogic: ${rounded}s`);
})();

businessLogic: 2.012s

Time tracking util

You can also build your own utility function to track execution time with performance.now:

// Util function to track execution time in seconds
export async function trackInSeconds(fn: Function): Promise<string> {
  const start = performance.now();
  await fn();
  const end = performance.now();
  const inSeconds = (end - start) / 1000;
  return Number(inSeconds).toFixed(0);
}

(async () => {
  // Your business logic
  const myFunction = () => {
    return new Promise(resolve => {
      // Function completes after 5s
      setTimeout(resolve, 5000);
    });
  };

  const timeInSeconds = await trackInSeconds(myFunction);
  console.log(`Execution took ${timeInSeconds} seconds.`);
})();

Execution took 5 seconds.

Performance Hooks (`perf_hooks`)

Node.js provides performance measurement APIs to profile JavaScript and TypeScript functions. With the perf_hooks module it becomes very convenient to profile multiple functions at once.

TypeScript Typings

To use the perf_hooks module with TypeScript, we have to install type definitions that match our Node.js version (I am using v14):

npm install --save @types/node@14

Performance Observer

We have seen that console.time doesn't let us customize the output and performance.now is very difficult to control if you want to monitor several functions. That's why Node.js provides a performance observer. The performance observer can listen to different kinds of measurements and receives entries that return the measured time in milliseconds.

To make the performance collection asynchronous, the buffered flag can be used, so that multiple entries will be buffered internally:

import {PerformanceObserver} from 'perf_hooks';

const observer = new PerformanceObserver(list => list.getEntries().forEach(entry => console.info(entry)));
observer.observe({buffered: true, entryTypes: ['measure']});

Performance Marks (`performance.mark`)

After setting up the performance observer, we can start a measurement. The simplest way is to set markings. It works similar to the console.time approach with the difference that we need to use different labels for the start and the stop:

import {performance, PerformanceObserver} from 'perf_hooks';

function businessLogic(): Promise<number> {
  return new Promise((resolve) => {
    setTimeout(resolve, 2000);
  });
}

(async () => {
  const observer = new PerformanceObserver(list => list.getEntries().forEach(entry => console.info(entry)));
  observer.observe({buffered: true, entryTypes: ['measure']});

  performance.mark('start');
  await businessLogic();
  performance.mark('stop');

  performance.measure('Business Logic', 'start', 'stop');
})();

💡 Please note that our observer listens to entries of type 'measure'.

Output:

PerformanceEntry {
  name: 'Business Logic',
  entryType: 'measure',
  startTime: 3020.9561,
  duration: 2007.4025
}

Performance Instrumentation (`performance.timerify`)

For more convenience, there is the performance.timerify function. It wraps new functions automatically into performance marks, so that we don't need to declare start and stop. In that case our observer must listen to the entry type 'function':

(async () => {
  const observer = new PerformanceObserver(list => list.getEntries().forEach(entry => console.info(entry)));
  observer.observe({buffered: true, entryTypes: ['function']});

  const wrapped = performance.timerify(businessLogic);
  await wrapped();
})();

PerformanceEntry {
  name: 'businessLogic',
  entryType: 'function',
  startTime: 2221.5801,
  duration: 0.6079
}

💡 As you can see, the tracked duration is different from our measurements with performance.mark. That's because performance.timerify doesn't work out of the box with asynchronous functions on Node.js v14.

James M Snell from the Node team tweeted me that performance.timerify will work with async functions in Node v16 and above.

With Node.js v14 we have to use the async_hooks module to register callbacks tracking the lifetime of asynchronous resources. There is good documentation with an example on measuring the duration of async operations.

Completion of measurement

It's recommended to disconnect the performance observer from all incoming notifications, when you are done with your measurements:

observer.disconnect();

Inclusion in Unit Tests

If you want to ensure the execution speed of your functions in the long run, you can make them part of your unit tests. Many testing frameworks (like Jest, Jasmine, and others) allow you to set a timeout for the execution of your test. The timeout feature can be used to mark a test as failed if the tested function takes too long to execute.

Here is a timeout example with the Jasmine testing framework:

businessLogic.ts

export function businessLogic(): Promise<number> {
  return new Promise((resolve) => {
    setTimeout(resolve, 2000);
  });
}

businessLogic.test.ts

import {businessLogic} from './businessLogic';

describe('businessLogic', () => {
  it('does not take longer than 3 seconds (3000ms)', async () => {
    await businessLogic();
  }, 3000);
});

Get connected 🔗

Please follow me on Twitter or subscribe to my YouTube channel if you liked this post. I would love to hear from you what you are building. 🙂 Best, Benny

Forem: TypeScript TV

It's Easy To Switch from CommonJS to ES Modules with TS2ESM

Video Tutorial

TypeChat: Eliminating Hallucinations in AI with TypeScript

What is control flow based narrowing in TypeScript?

Control Flow Based Type Analysis

Interested in learning more? 🎓

Why TypeScript is the better JavaScript

Common JavaScript Errors

TypeScript to the Rescue

Why Use TypeScript?

Getting Started with TypeScript

Understanding npm Versioning

Major, minor, patch

Major version

Minor version

Patch version

Understanding Caret (^) and Tilde (~)

Video Tutorial

Caret (^)

Tilde (~)

Trick to remember

Alternative Versioning Notations

Latest Patch Version

Latest Minor and Patch Versions

Updating Dependencies

npm install

npm update

Recording Exact Versions

Traffic Light Control

Conventional Commits

Publishing packages

npm version

npm publish

Release Workflow

Conclusion

What is the difference between null and undefined?

Example with null

Example with undefined

Best Practice

Want more?

Best practices with const assertions in TypeScript

const declarations

const assertions

Important note

Best Practice

as const with objects

as const with strings

Alternative Options

Video Tutorial

Getting started with GitHub Actions and workflows

What are GitHub Actions?

What are workflows?

Test Automation with GitHub Actions

Setting up a workflow

Specify Node.js version

Define workflow triggers

Run workflow manually with workflow_dispatch

Run multiline shell commands

Skip workflow execution

Using expressions in workflows

Branch protection rules

Running your GitHub Actions locally

Where to go from here?

Run Linux on Windows with WSL 2 & VS Code

Requirements 📝

Install WSL 2 💾

Install Linux 🐧

Start Linux on Windows 🏁

Access Linux Files from Windows 📁

Access Windows Files from Linux 📁

Connect Visual Studio Code with Linux 🔗

Use Docker with WSL 2 🐳

Run Linux GUI apps 🎨

Closing Note ✍

Typing React Props in TypeScript

Starting Example

Solution 1: PropsWithChildren

Solution 2: React.FC

Solution 3: React.HTMLProps

Understanding Caret (`^`) and Tilde (`~`)

Caret (`^`)

Tilde (`~`)

Example with `null`

Example with `undefined`

Run workflow manually with `workflow_dispatch`

Solution 1: `PropsWithChildren`

Solution 2: `React.FC`

Solution 3: `React.HTMLProps`

Console Timers (`console.time`)

High Resolution Timers (`performance.now`)

Performance Hooks (`perf_hooks`)

Performance Marks (`performance.mark`)

Performance Instrumentation (`performance.timerify`)