iTerm2 key bindings


I recently got a new Mac mini M1 and I wanted to share my [iTerm2](https://iterm2.com/) key bindings:

| Description                       | Keyboard shortcut | Action        | Value       |
| --------------------------------- | ----------------- | ------------- | ----------- |
| Move to the beginning of the line | ⌘ + ←             | Send Hex Code | `0x01`      |
| Move to the end of the line       | ⌘ + →             | Send Hex Code | `0x05`      |
| Deleting a line                   | ⌘ + ←Delete       | Send Hex Code | `0x15`      |
| Move forward a word               | ⌥ + →             | Send Hex Code | `0x1B 0x66` |
| Move backward a word              | ⌥ + ←             | Send Hex Code | `0x1B 0x62` |
| Deleting a word                   | ⌥ + ←Delete       | Send Hex Code | `0x17`      |

In order to set these key bindings, you need to go to **iTerm2** > **Preferences** > **Keys** > **Key Bindings** > **+** and then add the key bindings above.

## Nerd Deep Dive

Terminal emulators like iTerm2 simulate the behavior of physical terminals (like the [DEC VT100](https://en.wikipedia.org/wiki/VT100)) from the early days of computing. These physical terminals were hardware devices used to interact with a computer, allowing users to input commands and view the output. The communication between the terminal and the computer was standardized through specific codes and sequences, facilitating text manipulation and cursor movement, among other functions.

### ASCII Control Characters

[ASCII](https://en.wikipedia.org/wiki/ASCII), or _American Standard Code for Information Interchange_, is a character encoding standard for electronic communication. It includes a set of [control characters](https://en.wikipedia.org/wiki/Control_character) that are intended not to represent printable information but to control devices that use ASCII, such as terminals.

| Hex Code | Name                                                                     | Meaning                   | Usage Above           |
| -------- | ------------------------------------------------------------------------ | ------------------------- | --------------------- |
| `0x01`   | [SOH](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#SOH)         | Start of Heading          | move to start of line |
| `0x05`   | [ENQ](https://en.wikipedia.org/wiki/Enquiry_character)                   | Enquiry                   | move to end of line   |
| `0x15`   | [NAK](<https://en.wikipedia.org/wiki/Acknowledgement_(data_networks)>)   | Negative Acknowledgement  | delete line           |
| `0x17`   | [ETB](https://en.wikipedia.org/wiki/End-of-Transmission-Block_character) | End of Transmission Block | delete word           |

### ANSI Escape Sequences

[Escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) are strings of characters that start with the `ESC` character followed by a series of characters that instruct the terminal to perform a specific action, like moving the cursor or changing text colors.

For terminals that adhere to the [xterm](https://en.wikipedia.org/wiki/Xterm) protocol or similar, moving forward or backward by a word is often achieved through specific escape sequences rather than hex codes.

| Sequence    | Description          |
| ----------- | -------------------- |
| `ESC` + `f` | move forward a word  |
| `ESC` + `b` | move backward a word |

On iTerm2, you can actually use the "Send Escape Sequence" for such:

| Description          | Keyboard shortcut | Action               | Value |
| -------------------- | ----------------- | -------------------- | ----- |
| Move forward a word  | ⌥ + →             | Send Escape Sequence | `f`   |
| Move backward a word | ⌥ + ←             | Send Escape Sequence | `b`   |

So what is the deal with `0x1B 0x66` and `0x1B 0x62` above?

The `0x1B` is the hex code for the `ESC` character, and `0x66` and `0x62` are the hex values for `f` ([ASCII Character 102](https://www.ascii-code.com/102)) and `b` ([ASCII Character 98](https://www.ascii-code.com/98)), respectively.

This is just another way to represent the same escape sequences.


0xffffffffffffffffn: uint64 hack to decrement by one using addition


## Introduction

In the world of software development, there are often clever tricks and hacks that developers use to solve specific problems. One such trick involves using `uint64` (unsigned 64-bit integer) arithmetic to subtract `1` from a number without actually using subtraction. This might sound confusing at first, but with a simple analogy and some examples, it becomes clear!

## The Toy Cash Register Analogy

Imagine a child's toy cash register that can only count up to `9`. When it reaches `9`, and you try adding `1` more, it wraps around and returns to `0`. Now, if this toy didn't have a subtraction button, how could you subtract `1` from any number? The trick is to add `9`! When you add `9`, you essentially go full circle and land `1` number behind where you started.

## The Technical Explanation

In binary arithmetic, numbers are represented using bits. A `uint64` number uses 64 bits. When you add two numbers and the result is too big to fit in 64 bits, it wraps around, similar to our toy cash register.

The magic number `0xffffffffffffffffn` (which represents all `1`s in binary for a 64-bit number) acts like the number `9` in our analogy. When you add this number to any `uint64`, it's equivalent to subtracting `1`.

| Bit Position:        | 63-56    | 55-48    | 47-40    | 39-32    | 31-24    | 23-16    | 15-8     | 7-0      |
| -------------------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- |
| Previous Number: 3   | 00000000 | 00000000 | 00000000 | 00000000 | 00000000 | 00000000 | 00000000 | 00000011 |
| Magic Number to Add: | 11111111 | 11111111 | 11111111 | 11111111 | 11111111 | 11111111 | 11111111 | 11111111 |
| Result: 2            | 00000000 | 00000000 | 00000000 | 00000000 | 00000000 | 00000000 | 00000000 | 00000010 |

### Example Code

```javascript
// Convention for BigInts is to add an "n" at the end.
const previousNumber = 3n;

// Hexadecimal representation of 64-bit magic number.
const magicNumber = 0xffffffffffffffffn;

// Convert to 64-bit unsigned integer.
const result = BigInt.asUintN(64, previousNumber + magicNumber);

console.log(result); // This will be 2n.
```

## Why is this Useful?

In the realm of programming, there are instances where certain operations, like subtraction, might be restricted due to system constraints. This "magic number" trick offers a clever workaround for such situations.

Take, for example, [Deno KV](https://deno.com/kv). This key-value storage system in Deno provides an atomic [sum](https://docs.deno.com/kv/manual/operations#sum) operation, allowing you to add two [`Deno.KvU64`](https://deno.land/api@v1.37.0?s=Deno.KvU64&unstable=) values. This is particularly handy for incrementing numeric counters in an [ACID-compliant way](https://en.wikipedia.org/wiki/ACID). However, there's a catch: you can't directly decrement a value using this method since `Deno.KvU64` requires a positive number in the construction.

Here's how you'd typically increment a counter:

```typescript
await kv
  .atomic()
  .mutate({
    type: 'sum',
    key: ['users_count'],
    value: new Deno.KvU64(1n)
  })
  .commit();
```

But what if you wanted to decrease this counter? Enter our magic number trick. By using the magic number `0xffffffffffffffffn`, you can effectively subtract from the counter:

```typescript
await kv
  .atomic()
  .mutate({
    type: 'sum',
    key: ['users_count'],
    value: new Deno.KvU64(0xffffffffffffffffn)
  })
  .commit();
```

In essence, this approach leverages the properties of binary arithmetic to bypass system constraints. Pretty cool, right?

## Conclusion

Understanding the underlying principles of binary arithmetic can open the door to many clever tricks in programming. The `uint64` subtraction trick is just one example. Hopefully, you can find efficient solutions to complex problems by understanding and applying these concepts to your following projects.


Manually Create Coverage Badges Using GitHub Actions


Adding a coverage badge to your repository is an excellent way to demonstrate your project's test coverage and maintain a high level of code quality. By the end of this guide, you will be able to generate a dynamic coverage badge that updates automatically with each new push to your repository.

## Prerequisites

- A [Node.js](https://nodejs.org/) project with test coverage reports generated by a tool like [c8](https://github.com/bcoe/c8) or [Istanbul](https://github.com/istanbuljs/nyc).
- A GitHub repository for your project.
- [GitHub deploy keys](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-create-ssh-deploy-key) configured for your repository.

Let's get started!

## Step 1: Install Cheerio

Before anything else, make sure you have a coverage report generated by your testing tool. In our case, we will use the HTML report generated by [c8](https://github.com/bcoe/c8). This report will look something like this:

```html filename=./coverage/index.html
<!DOCTYPE html>
<html lang="en">
  <body>
    <div class="wrapper">
      <div class="pad1">
        <div class="clearfix">
          <div class="fl pad1y space-right2">
            <span class="strong">100%</span>
            <span class="quiet">Statements</span>
            <span class="fraction">786/786</span>
          </div>
          <div class="fl pad1y space-right2">
            <span class="strong">100%</span>
            <span class="quiet">Branches</span>
            <span class="fraction">74/74</span>
          </div>
          <div class="fl pad1y space-right2">
            <span class="strong">90.9%</span>
            <span class="quiet">Functions</span>
            <span class="fraction">33/33</span>
          </div>
          <div class="fl pad1y space-right2">
            <span class="strong">100%</span>
            <span class="quiet">Lines</span>
            <span class="fraction">786/786</span>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>
```

We will use [cheerio](https://github.com/cheeriojs/cheerio), a [jQuery](https://jquery.com/)-like library for server-side to extract the percentage data from the HTML. Install it to your `devDependencies` using the package manager of your choice:

```bash
# npm
npm install --save-dev cheerio

# yarn
yarn add --dev cheerio

# pnpm
pnpm add --save-dev cheerio
```

## Step 2: Create a Script to Extract Coverage Data

Next, we need to create the actual script that will extract the coverage data from the HTML report. Create a new file called `./scripts/generate-badges.js` and add the following code:

```js filename=./scripts/generate-badges.js
const fs = require('fs');
const https = require('https');
const cheerio = require('cheerio');

const coverageFile = './coverage/index.html';
const badgesDir = './coverage/badges';

// Read the coverage HTML file.
fs.readFile(coverageFile, 'utf-8', (err, data) => {
  if (err) {
    console.error(`Error reading coverage file: ${err}`);
    process.exit(1);
  }

  // Parse the HTML using Cheerio.
  const $ = cheerio.load(data);

  // Construct the shields.io URL for each badge.
  const statementsBadgeUrl = generateUrl('statements', extractPercentage($, 1));
  const branchesBadgeUrl = generateUrl('branches', extractPercentage($, 2));
  const functionsBadgeUrl = generateUrl('functions', extractPercentage($, 3));
  const linesBadgeUrl = generateUrl('lines', extractPercentage($, 4));

  // Create the badges directory if it does not exist.
  if (!fs.existsSync(badgesDir)) {
    fs.mkdirSync(badgesDir);
  }

  // Download each badge and save it to the badges directory.
  downloadBadge(statementsBadgeUrl, `${badgesDir}/statements.svg`);
  downloadBadge(branchesBadgeUrl, `${badgesDir}/branches.svg`);
  downloadBadge(functionsBadgeUrl, `${badgesDir}/functions.svg`);
  downloadBadge(linesBadgeUrl, `${badgesDir}/lines.svg`);

  console.log('Code coverage badges created successfully.');
});

/**
 * Generate a shields.io URL for a badge.
 *
 * Change the color of the badge based on the percentage.
 *
 * @param {string} text The text to display on the badge.
 * @param {number} percentage The percentage to display on the badge.
 * @returns {string} The shields.io URL.
 */
const generateUrl = (text, percentage) => {
  let color = 'brightgreen';
  if (percentage < 70) {
    color = 'red';
  } else if (percentage < 80) {
    color = 'yellow';
  } else if (percentage < 90) {
    color = 'orange';
  }
  return `https://img.shields.io/badge/coverage%3A${text}-${percentage}%25-${color}.svg`;
};

/**
 * Extract the code coverage percentage from the HTML.
 * @param {Cheerio} $ The Cheerio object.
 * @param {number} index The index of the element to extract.
 */
const extractPercentage = ($, index) => {
  const text = $(`.pad1y:nth-child(${index}) span.strong`) ?? '0';
  const percentage = text.text().trim().replace('%', '');
  return parseFloat(percentage);
};

/**
 * Download a badge from shields.io.
 * @param {string} url The shields.io URL.
 * @param {string} filename The filename to save the badge to.
 */
const downloadBadge = (url, filename) => {
  https.get(url, (res) => {
    if (res.statusCode !== 200) {
      console.error(`Error downloading badge: ${res.statusMessage}`);
      return;
    }

    const file = fs.createWriteStream(filename);
    res.pipe(file);
    file.on('finish', () => {
      file.close();
    });
  });
};
```

This is a fairly straightforward script that uses Cheerio to parse the HTML report and extract the coverage data. It then uses the data to generate the [shields.io](https://shields.io/) URLs for each badge type. Finally, it downloads each badge and saves it to the `./coverage/badges` directory.

Update your `package.json` to add a new script that will run the `generate-badges.js` script:

```json filename=package.json
{
  "scripts": {
    // ...
    "generate-badges": "node ./scripts/generate-badges.js"
  }
}
```

Run the script to generate the badges:

```bash
# generate the coverage report first
pnpm coverage

# generate the badges
pnpm generate-badges
```

## Step 3: Configure GitHub Actions

> **NOTE**: For this guide, we will use [pnpm](https://pnpm.io/), but the commands should be similar for other package managers.

> **NOTE**: This requires that you have an SSH Deploy Key configured for your repository. See [Create SSH Deploy Key](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-create-ssh-deploy-key) for more information.

In your repository, create a `.github/workflows` directory if it doesn't already exist. Then, create a new YAML file inside the workflows directory called `coverage-badge.yml`. This file will define the GitHub Actions workflow that generates the coverage badge.

Add the following content to `coverage-badge.yml`:

```yaml filename=.github/workflows/coverage-badge.yml
name: (main) coverage badge

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  coverage-badge:
    strategy:
      matrix:
        os:
          - ubuntu-latest
        node:
          - 18.14.2
        pnpm:
          - 7
    runs-on: ${{ matrix.os }}
    steps:
      - name: checkout repository
        uses: actions/checkout@v3
      - name: setup node
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - name: install pnpm
        uses: pnpm/action-setup@v2
        id: pnpm-install
        with:
          version: ${{ matrix.pnpm }}
          run_install: false
      - name: get pnpm store directory
        id: pnpm-cache
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
      - name: Setup pnpm cache
        uses: actions/cache@v3
        with:
          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-
      - name: install dependencies
        run: pnpm install
      - name: run coverage
        run: pnpm coverage
      - name: generate badges
        run: pnpm generate-badges
      - name: push coverage artifacts to another branch
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.COVERAGE_DEPLOY_KEY }}
          publish_dir: ./coverage
          publish_branch: coverage
          allow_empty_commit: true
```

Let's break down the workflow into its various sections:

```yaml
on:
  workflow_dispatch:
  push:
    branches:
      - main
```

The workflow is triggered when there's a push to the `main` branch or can be triggered manually ([`workflow_dispatch`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch)).

```yaml
jobs:
  covera:
    strategy:
      matrix:
        os:
          - ubuntu-latest
        node:
          - 18.14.2
        pnpm:
          - 7
    runs-on: ${{ matrix.os }}
```

We're using a matrix strategy to run the workflow on multiple operating systems, Node.js versions, and pnpm versions. For our purpose, we will only use one version of each, but this is a good practice to follow.

```yaml
- name: checkout repository
  uses: actions/checkout@v3
- name: setup node
  uses: actions/setup-node@v3
  with:
    node-version: ${{ matrix.node }}
```

This step checks out your repository using the [actions/checkout](https://github.com/actions/checkout) action. Then, it sets up Node.js using the [actions/setup-node](https://github.com/actions/setup-node) action.

```yaml
- name: install pnpm
  uses: pnpm/action-setup@v2
  id: pnpm-install
  with:
    version: ${{ matrix.pnpm }}
    run_install: false
```

This step installs pnpm using the [pnpm/action-setup](https://github.com/pnpm/action-setup) action and the specified pnpm version from the matrix. We're not installing any dependencies yet, so we don't need to run `pnpm install`.

```yaml
- name: get pnpm store directory
  id: pnpm-cache
  shell: bash
  run: |
    echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
- name: Setup pnpm cache
  uses: actions/cache@v3
  with:
    path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
    restore-keys: |
      ${{ runner.os }}-pnpm-store-
- name: install dependencies
  run: pnpm install
```

These steps will use the cache from [actions/cache](https://github.com/actions/cache) and install the project's dependencies using pnpm. We're using the cache to reduce installation time and to avoid downloading the same dependencies multiple times.

```yaml
- name: run coverage
  run: pnpm coverage
- name: generate badges
  run: pnpm generate-badges
```

This step runs the `coverage` script, which should generate a coverage report. Then, it runs the `generate-badges` script, which should generate the coverage badges.

```yaml
- name: push coverage artifacts to another branch
  uses: peaceiris/actions-gh-pages@v3
  with:
    deploy_key: ${{ secrets.COVERAGE_DEPLOY_KEY }}
    publish_dir: ./coverage
    publish_branch: coverage
    allow_empty_commit: true
```

Lastly, this step pushes the coverage artifacts, including the generated badges and the coverage report, to a separate coverage branch in your repository using the [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages) action.

Options:

- The `deploy_key` option is set to the `COVERAGE_DEPLOY_KEY` secret, which is a Deploy Key stored in your repository settings. This deploy key should have write access to the repository. Follow the instructions from [Create SSH Deploy Key](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-create-ssh-deploy-key) to generate it and add it to your repository.
- The `publish_dir` is set to `./coverage`, which is the directory containing the coverage report and badges.
- The `allow_empty_commit` option is set to true to allow empty commits if there are no changes in the coverage artifacts.
- The `publish_branch` is the name of the branch you want to push the coverage artifacts to. It's currently set to `coverage`, but you can change it to whatever you want.

## Step 4: Add Badge to README

To display the coverage badge in your README file, add the following line at the top of your `README.md` file:

```md filename=README.md
![Coverage: Statements](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/statements.svg)
![Coverage: Branches](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/branches.svg)
![Coverage: Functions](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/functions.svg)
![Coverage: Lines](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/lines.svg)
```

These lines will render the badges as an image. It should point to the latest badges in your `<PUBLISH_BRANCH_NAME>` branch.

## Conclusion

Congratulations! You have successfully created a dynamic coverage badge for your Node.js project. This badge will help you showcase your project's test coverage and encourage you to maintain a high level of code quality. Don't hesitate to customize this workflow to suit your needs and adapt it to different coverage tools and badge styles.

Happy coding!


Nap Joseph Calub

Recent Posts