Stories by Jan Hesters on Medium

How to Set Up Next.js 15 for Production in 2024

Jan Hesters — Tue, 19 Nov 2024 10:49:17 GMT

I’ve worked on Next.js applications that scaled to over 100k monthly active users and landing pages with millions of monthly visitors. In this article, I’ll share all the lessons I’ve learned through countless iterations.

Whether you’re part of a small team of one, two, or three developers, or you work on a massive Next.js project with multiple teams on the same codebase, it’s critical to get the foundation of your app right from the start. Even if you’re working on an existing project, you will discover some hard-earned insights that you can apply to your app today.

Let me take you by the hand and show you all the steps and packages that you want to set up and explain to you why they’re useful, so your app scales smoothly.

https://medium.com/media/3029944b2bfc1454067d12f6327a4e56/href

Initialize Your Project

Begin by creating a new Next.js project.

npx create-next-app@latest

It may ask you if it can install the latest create-next-app version, just hit yes.

Need to install the following packages:
create-next-app@15.0.0
Ok to proceed? (y)

And then configure your project by hitting yeson everything (TypeScript, Tailwind, app router).

✔ **What is your project named?** … reactsquad-production
✔ **Would you like to use** **TypeScript****?** … No / Yes
Yes
✔ **Would you like to use** **ESLint****?** … No / Yes
Yes
✔ **Would you like to use** **Tailwind CSS****?** … No / Yes
Yes
✔ **Would you like to use** **`src/` directory****?** … No / Yes
Yes
✔ **Would you like to use** **App Router****? (recommended)** … No / Yes
Yes
✔ **Would you like to customize the default** **import alias** **(@/*)?** … No / No

Then change into the directory of your project and open it in your favorite editor.

$ cd nextjs-for-production
~/dev/nextjs-for-production (main) 🤯
$ cursor .

Run The Development Server

You want to verify that your setup worked.

Run npm run dev to start the development server.
Visit http://localhost:3000 to view your application.

Type Checks With TypeScript

Your project has TypeScript already configured, but you also want to add an explicit command to your package.json that checks all your files for type errors.

"type-check": "tsc -b"

You’re going to use this command later together with other automated static analysis checks.

Code Formatting

When you collaborate with a large team on a project, it’s important to unify the way that everyone writes code. Discuss choices like using semicolons, quote styles, and tabs versus spaces with your team.

Then use tools to enforce your style guide and format code automatically.

There are two tools for that: Prettier and ESLint.

Prettier

Prettier is an opinionated code formatter that eliminates style discussions during code reviews.

Install Prettier together with its Tailwind plugin.

npm install --save-dev prettier prettier-plugin-tailwindcss

Create aprettier.config.js file with your preferred rules.

module.exports = {
  arrowParens: 'avoid',
  bracketSameLine: false,
  bracketSpacing: true,
  htmlWhitespaceSensitivity: 'css',
  insertPragma: false,
  jsxSingleQuote: false,
  plugins: ['prettier-plugin-tailwindcss'],
  printWidth: 80,
  proseWrap: 'always',
  quoteProps: 'as-needed',
  requirePragma: false,
  semi: true,
  singleQuote: true,
  tabWidth: 2,
  trailingComma: 'all',
  useTabs: false,
};

Add a formatting script to your package.json.

"format": "prettier --write .",

Run the formatter to apply your style.

$ npm run format

> nextjs-for-production@0.1.0 format
> prettier --write .

next.config.mjs 4ms (unchanged)
package-lock.json 54ms (unchanged)
package.json 1ms (unchanged)
postcss.config.mjs 2ms (unchanged)
README.md 20ms (unchanged)
src/app/globals.css 17ms (unchanged)
src/app/layout.tsx 30ms (unchanged)
src/app/page.tsx 11ms (unchanged)
tailwind.config.ts 2ms (unchanged)
tsconfig.json 2ms (unchanged)

Your files are now “prettier”, but you also want to use ESLint.

ESLint

ESLint can scan your code for both stylistic and logical issues. Install ESLint and its plugins, like unicorn, playwright and import sort.

npm install --save-dev @typescript-eslint/parser eslint-plugin-unicorn eslint-plugin-import eslint-plugin-playwright eslint-config-prettier eslint-plugin-prettier eslint-plugin-simple-import-sort

Update your.eslintrc.json

{
  "extends": [
    "next/core-web-vitals",
    "plugin:unicorn/recommended",
    "plugin:import/recommended",
    "plugin:playwright/recommended",
    "plugin:prettier/recommended"
  ],
  "plugins": ["simple-import-sort"],
  "rules": {
    "simple-import-sort/exports": "error",
    "simple-import-sort/imports": "error",
    "unicorn/no-array-callback-reference": "off",
    "unicorn/no-array-for-each": "off",
    "unicorn/no-array-reduce": "off",
    "unicorn/prevent-abbreviations": [
      "error",
      {
        "allowList": {
          "e2e": true
        },
        "replacements": {
          "props": false,
          "ref": false,
          "params": false
        }
      }
    ]
  },
  "overrides": [
    {
      "files": ["*.js"],
      "rules": {
        "unicorn/prefer-module": "off"
      }
    }
  ]
}

This tutorial’s plugins offer different functions. For detailed descriptions, visit their respective GitHub pages.

But in short, they enforce coding standards, organize imports, and ensure correct use of modern JavaScript features. Since ESLint and Prettier can conflict, this setup makes them work together smoothly. The plugins also help prevent bugs and keep styles consistent, especially with tools like Vitest and Playwright.

Add a linting script to your package.json.

"lint:fix": "next lint --fix",

Run it to format all files according to your new rules.

$ npm run lint:fix

> nextjs-for-production@0.1.0 lint:fix
> next lint --fix

✔ No ESLint warnings or errors

If you get a TypeScript version warning, you can ignore that.

Note: As of this article’s writing, ESLint 9 is available, but this tutorial uses ESLint 8 because many plugins do not yet support the latest version.

Commitlint

When collaborating with a large team, it’s also helpful to enforce consistent commit messages to keep the project history clear. By choosing the right standards, you can automate changelog and release generation with correct semantic versioning.

Install Commitlint and its necessary configurations. This includes Husky, which helps manage Git hooks.

npm install --save-dev @commitlint/cli@latest @commitlint/config-conventional@latest husky@latest

Initialize Husky in your project to set up the basic configuration.

npx husky-init && npm install

Add hooks to automate linting and type checking before each commit, and customize your commit message workflow.

npx husky add .husky/pre-commit 'npm run lint && npm run type-check'
npx husky add .husky/prepare-commit-msg 'exec < /dev/tty && npx cz --hook || true'

The pre-commit hook runs after git commit, but before the commit message is finalized and runs linting and type-checking on your code.

The prepare-commit-msg hook runs after git commit is initiated but before the commit message editor opens. It runs commitizen CLI to let you craft conventional commit messages. You'll learn how to use this hook in a bit.

Remove the line that says npm test from .husky/_/pre-commit.

Make sure these scripts are executable.

chmod a+x .husky/pre-commit
chmod a+x .husky/prepare-commit-msg

Here, chmod stands for "change mode." This command allows you to change the access permissions or modes of a file or directory in Unix and Unix-like operating systems. The argument a+x adds execute permissions for all users.

Install Commitizen, which provides a CLI for crafting conventional commit messages.

npm install --save-dev commitizen cz-conventional-changelog

Configure Commitizen in your package.json to use the conventional changelog standard.

"config": {
  "commitizen": {
    "path": "cz-conventional-changelog"
  }
},

The conventional changeloge standard is a specification for adding human and machine-readable meaning to commit messages. It is designed to automate the producing of changelogs and releases based on the Git history of your project.

A future article will explain this standard in detail. It’s included in this tutorial because getting it right from the start is important. You can use it and benefit from it without needing an in-depth understanding.

Create your commitlint.config.cjs file with rules that suit your team's needs. This setup ensures your commit messages are consistent and relevant to the changes made.

const config = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'references-empty': [1, 'never'],
    'footer-max-line-length': [0, 'always'],
    'body-max-line-length': [0, 'always'],
  },
};

module.exports = config;

Run the following command to start crafting your commit messages using a guided CLI.

$ git add --all
$ npx cz
cz-cli@4.3.0, cz-conventional-changelog@3.3.0

? Select the type of change that you're
committing: (Use arrow keys)
❯ feat:     A new feature
  fix:      A bug fix
  docs:     Documentation only changes
  style:    Changes that do not affect the
meaning of the code (white-space, formatting,
missing semi-colons, etc)

The cz command asks a series of questions and then writes your commit message for you.

? Select the type of change that you\\'re committing: feat:     A new feature
? What is the scope of this change (e.g. component or file name): (press enter to skip)
? Write a short, imperative tense description of the change (max 63 chars):
 (61) set up TS type checks, ESLint, Prettier, Commitlint and Husky
? Provide a longer description of the change: (press enter to skip)
 Sets up package.json script to do TS type checks. Sets up Prettier and ESLint with good rules. Configures Husky and sets up Commitizen using the conventional commit standard.
? Are there any breaking changes? No
? Does this change affect any open issues? No
[main eb69ccd] feat(set up static analysis checks): set up TS type checks, ESLint, Prettier, Commitlint and Husky
 7 files changed, 3108 insertions(+), 159 deletions(-)
 create mode 100755 .husky/pre-commit
 create mode 100755 .husky/prepare-commit-msg
 create mode 100644 commitlint.config.cjs

As you answer all questions, the Husky hooks will automatically run TypeScript type checks and linting.

Folder structure

There are usually two popular ways to organize your code: grouping by type or grouping by feature.

Group by type looks like this:

.
├── components
│ ├── todos
│ └── user
├── reducers
│ ├── todos
│ └── user
└── tests
    ├── todos
    └── user

And grouping by feature looks like this:

.
├── todos
│ ├── component
│ ├── reducer
│ └── test
└── user
    ├── component
    ├── reducer
    └── test

Grouping files by feature in a project organizes all related components, reducers, and tests together, making it easier to manage and modify each feature. It has the following benefits:

Scalability: Large applications are easier to scale and maintain because each feature acts like a mini-application. You avoid scrolling up and down in your file list to find all the files you need.
Collaboration: Developers can focus on specific features without disrupting others’ work.
Onboarding: New developers understand the project structure faster, as all files for a feature are in one place.
Refactoring: Updating a feature is streamlined since all its elements are grouped together.
Modularity: Features can be reused, shared, or turned into standalone packages more easily.
Micro-frontends: If your application ever grows to 30 or more engineers, it is easy to refactor to micro-frontends.

Here is a more concrete example.

src/
├── app/
│   ├── ...
│   ├── (group)/
│   │   ├── about/
│   │   │   └── page.tsx
│   │   ├── settings/
│   │   │   └── page.tsx
│   │   └── layout.tsx
│   ├── dashboard/
│   │   ├── page.tsx
│   │   └── layout.tsx
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   ├── ...
│   └── header/
│       ├── header-component.tsx
│       ├── header-component.test.ts
│       └── header.module.css
├── features/
│   ├── ...
│   ├── todos/
│   │   ├── ...
│   │   ├── todos-component.tsx
│   │   ├── todos-component.test.ts
│   │   ├── todos-container.ts
│   │   ├── todos-reducer.ts
│   │   ├── todos-reducer.test.ts
│   │   └── todos-styles.ts
│   └── user/
│       ├── ...
│       ├── user-reducer.ts
│       └── user-reducer.test.ts
├── hocs/
│   ├── ...
│   └── with-layout.tsx
├── hooks/
├── redux/
│   ├── root-reducer.ts
│   ├── root-saga.ts
│   └── store.ts
├── ...
└── middleware.ts

This example shows you how you can organize your src/ directory. Generally, everything is grouped by feature. Tests files live next to their respective implementation files. But anything that is shared by multiple features is then grouped in general folders, such as components/ or HOCs/ or hooks/. Shared setup for state management - in this example for Redux - lives in a redux/ folder.

Some people also like to group by feature within the app/ folder. Here is how that would look like.

src/
├── app/
│   ├── ...
│   ├── (group)/
│   ├── dashboard/
│   │   ├── components/
│   │   │   ├── dashboard-header.tsx
│   │   │   ├── dashboard-header.test.ts
│   │   │   ├── dashboard-widgets.tsx
│   │   │   └── dashboard-widgets.test.ts
│   │   ├── services/
│   │   │   ├── fetch-data.ts
│   │   │   ├── fetch-data.test.ts
│   │   │   ├── auth-service.ts
│   │   │   └── auth-service.test.ts
│   │   ├── page.tsx
│   │   └── layout.ts
│   ├── layout.tsx
│   └── page.tsx
├── ...
└── middleware.ts

In this tutorial, you’re going to group files by feature in the first way.

Vitest

If you want to avoid bugs and prevent regressions, you need to write tests. Vitest is a great choice because it has the same API as the most popular framework, which is Jest, but it runs faster.

Install Vitest.

npm install -D vitest

And configure a testing command in your package.json.

"test": "vitest --reporter=verbose",

Then create anexample.test.ts file and write a short test to check to check Vitest works.

import { describe, expect, test } from 'vitest';

describe('example', () => {
  test('given a passing test: passes', () => {
    expect(1).toStrictEqual(1);
  });
});

It should pass.

$ npm test

> nextjs-for-production@0.1.0 test
> vitest --reporter=verbose


 DEV  v2.0.5 /Users/jan/dev/nextjs-for-production

 ✓ src/example.test.ts (1)
   ✓ example (1)
     ✓ given a passing test: passes

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  14:06:24
   Duration  203ms (transform 20ms, setup 0ms, collect 17ms, tests 1ms, environment 0ms, prepare 56ms)


 PASS  Waiting for file changes...
       press h to show help, press q to quit

If you want to learn how you can write better tests, check out this article that teaches you 12 evergreen testing principles that every senior developer should know.

React Testing Library

You also want to write tests for your React components. For that, you can use the React Testing Library, often abbreviated as RTL.

npm install --save-dev @testing-library/react @testing-library/dom @testing-library/jest-dom @testing-library/user-event @types/react @types/react-dom happy-dom @vitejs/plugin-react vite-tsconfig-paths

Then, create a vitest.config.ts file.

import react from '@vitejs/plugin-react';
import tsconfigPaths from 'vite-tsconfig-paths';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  server: {
    port: 3000,
  },
  test: {
    environment: 'happy-dom',
    globals: true,
    setupFiles: ['./src/tests/setup-test-environment.ts'],
    include: ['./src/**/*.{spec,test}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
    watch: {
      ignored: [
        String.raw`.*\\/node_modules\\/.*`,
        String.raw`.*\\/build\\/.*`,
        String.raw`.*\\/postgres-data\\/.*`,
      ],
    },
    coverage: {
      reporter: ['text', 'json', 'html'],
    },
  },
});

It sets up the development server, specifies testing parameters like that the environment is happy-dom and file paths, and defines coverage report formats.

And create a file called src/tests/setup-test-environment.ts to set up your test environment.

import '@testing-library/jest-dom/vitest';

// See .

// @ts-ignore
globalThis.IS_REACT_ACT_ENVIRONMENT = true;

The first line imports additional assertions, which extend Vitest’s built-in assertions, allowing you to more easily test DOM nodes. For example, you can check if an element is visible, has a certain text content, or includes specific attributes.

The global environment flag ensures that tests involving state updates work as expected without timing issues.

Next, you want to set up a custom render method src/tests/react-test-utils.tsx.

/* eslint-disable import/export */
import type { RenderOptions } from '@testing-library/react';
import { render } from '@testing-library/react';
import type { ReactElement } from 'react';

const customRender = (
  ui: ReactElement,
  options?: Omit,
) =>
  render(ui, {
    wrapper: ({ children }) => <>{children},
    ...options,
  });

// re-export everything
export * from '@testing-library/react';

// override render method
export { customRender as render };
export { default as userEvent } from '@testing-library/user-event';

You can use this to wrap your code in providers, for example, when using Redux, or adding layouts and styling.

Make sure your configuration worked by writing a test for a React component.

import { describe, expect, test } from 'vitest';

import { render, screen } from '@/tests/react-test-utils';

function MyReactComponent() {
  return My React Component
;
}

describe('MyReactComponent', () => {
  test('given no props: renders a text', () => {
    render();

    expect(screen.getByText('My React Component')).toBeInTheDocument();
  });
});

You import render and screen from your test utils file instead of from RTL directly.

toBeInTheDocument() is one of those special assertions that you configured earlier in your test environment setup file.

It should pass, too.

 ✓ src/features/example.test.tsx (1)
   ✓ MyReactComponent (1)
     ✓ given no props: renders a text

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  09:33:32
   Duration  402ms (transform 24ms, setup 55ms, collect 87ms, tests 9ms, environment 80ms, prepare 45ms)


 PASS  Waiting for file changes...
       press h to show help, press q to quit

Styling

Now let’s talk about styling. The two most important aspects to get right are accessibility and maintainability. One of the most popular libraries out there that nails both of these aspects is Shadcn. It uses Tailwind for streamlined style management and Radix for enhanced accessibility.

Initialize Shadcn in your project.

$ npx shadcn@latest init

✔ **Which** **style** **would you like to use?** › New York
✔ **Which color would you like to use as** **base color****?** › Slate
✔ **Would you like to use** **CSS variables** **for colors?** … no / yes

✔ Writing components.json...
✔ Initializing project...
✔ Installing dependencies...

Success! Project initialization completed. You may now add components.

$ npx shadcn@latest init

✔ **Which** **style** **would you like to use?** › New York
✔ **Which color would you like to use as** **base color****?** › Slate
✔ **Would you like to use** **CSS variables** **for colors?** … no / yes

✔ Writing components.json…
✔ Initializing project…
✔ Installing dependencies…

Success! Project initialization completed. You may now add components.

npx shadcn@latest add card

Internationalization

As your app scales, you want to translate it to multiple languages, so it can reach more users.

And adding internationalization — or i18n — in a later cycle of an app, can be a pain because you’ll have to find all hardcoded strings and replace them with translation function calls.

Install negotiator and a locale matcher.

npm install negotiator @formatjs/intl-localematcher

The @formatjs/intl-localematcher package selects the best language for your app's content based on a user's language preferences. The negotiator package helps your app to figure out what type of content (like language or format) your user's browser can handle best, based on the information the browser sends.

You’ll also need to install the TypeScript types for the negotiator package.

npm install --save-dev @types/negotiator

Then, create your i18n config in a new file at @src/features.internationalization/il8n-config.ts.

import { match } from '@formatjs/intl-localematcher';
import Negotiator from 'negotiator';
import { type NextRequest, NextResponse } from 'next/server';

import { i18n } from './i18n-config';

function getLocale(request: NextRequest) {
  const headers = {
    'accept-language': request.headers.get('accept-language') ?? '',
  };
  const languages = new Negotiator({ headers }).languages();
  return match(languages, i18n.locales, i18n.defaultLocale);
}

export function localizationMiddleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const pathnameHasLocale = i18n.locales.some(
    locale => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`,
  );

  if (pathnameHasLocale) {
    return;
  }

  const locale = getLocale(request);
  request.nextUrl.pathname = `/${locale}${pathname}`;
  return NextResponse.redirect(request.nextUrl);
}

Use that il8n config, in your localization-middleware at src/features/internationalization/localization-middleware.ts .

import { match } from '@formatjs/intl-localematcher';
import Negotiator from 'negotiator';
import { type NextRequest, NextResponse } from 'next/server';

import { i18n } from './i18n-config';

function getLocale(request: NextRequest) {
  const headers = {
    'accept-language': request.headers.get('accept-language') ?? '',
  };
  const languages = new Negotiator({ headers }).languages();
  return match(languages, i18n.locales, i18n.defaultLocale);
}

export function localizationMiddleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const pathnameHasLocale = i18n.locales.some(
    locale => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`,
  );

  if (pathnameHasLocale) {
    return;
  }

  const locale = getLocale(request);
  request.nextUrl.pathname = `/${locale}${pathname}`;
  return NextResponse.redirect(request.nextUrl);
}

The purpose of this middleware is to automatically detect and redirect your users to the appropriate language version of the website based on their browser language preferences.

Then create a middleware file src/middleware.ts in the root of your project, and use your localization middleware there.

import { NextRequest } from 'next/server';

import { localizationMiddleware } from './features/internationalization/localization-middleware';

// Matcher ignoring `/_next/` and `/api/` and svg files.
export const config = { matcher: ['/((?!api|_next|.*.svg$).*)'] };

export function middleware(request: NextRequest) {
  return localizationMiddleware(request);
}

It’s time to add your translations. Create a json dictionary for your English translations at src/features/internalization/dictionaries/en-us.json.

{
  "counter": {
    "decrement": "Decrement",
    "increment": "Increment"
  },
  "landing": {
    "welcome": "Welcome"
  }
}

And then, create a file src/features/internalization/get-dictionaries.ts for your getDictionary function.

import "server-only";
import type { Locale } from "./i18n-config";

// We enumerate all dictionaries here for better linting and typescript support.
// We also get the default import for cleaner types.
const dictionaries = {
  "en-US": () => import("./dictionaries/en-US.json").then((module) => module.default),
};

export const getDictionary = async (locale: Locale) =>
  dictionaries[locale]?.() ?? dictionaries["en-US"]();

It takes in a locale and then returns the respective dictionary.

If you want to add a hook that lets your users pick their language, it can look like this.

import { usePathname } from 'next/navigation';

import { Locale } from './i18n-config';

export function useSwitchLocaleHref() {
  const pathName = usePathname();

  const getSwitchLocaleHref = (locale: Locale) => {
    if (!pathName) return '/';
    const segments = pathName.split('/');
    segments[1] = locale;
    return segments.join('/');
  };

  return getSwitchLocaleHref;
}

And then you can use that hook in a component, and use it’s return value in a like this.

{locale}

Change your URL structure to support i18n. Create a new folder [lang] in your app/ folder, which creates a dynamic segment for the language.

Move your page.tsx and layout.tsx files into that folder, and modify the layout to set the correct language on the tag.

import '../globals.css';

import type { Metadata } from 'next';
import { Inter } from 'next/font/google';

import { Locale } from '@/features/internationalization/i18n-config';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: "Jan Hesters' Next.js for production tutorial",
  description: 'Brought to you by ReactSquad.io',
};

export default function RootLayout({
  children,
  params,
}: Readonly<{
  children: React.ReactNode;
  params: { lang: Locale };
}>) {
  return (
    
      {children}
    
  );
}

Going forward, you can use the getDictionary function in any server component.

import { getDictionary } from '@/features/internationalization/get-dictionaries';
import { Locale } from '@/features/internationalization/i18n-config';

import { CounterComponent } from './counter-component';

export default async function IndexPage({
  params: { lang },
}: {
  params: { lang: Locale };
}) {
  const dictionary = await getDictionary(lang);

  return (
    
      Current locale: {lang}

      This text is rendered on the server: {dictionary.landing.welcome}

      
    

  );
}

For client components, you’ll want to pass in the respective dictionary instead.

'use client';

import { useState } from 'react';

import type { getDictionary } from '@/features/internationalization/get-dictionaries';

export function CounterComponent({
  dictionary,
}: {
  dictionary: Awaited>['counter'];
}) {
  const [count, setCount] = useState(0);

  return (
    
      This component is rendered on the client:
      
      {count}
      
    

  );
}

'use client';

import { useState } from 'react';

import type { getDictionary } from '@/features/internationalization/get-dictionaries';

export function CounterComponent({
  dictionary,
}: {
  dictionary: Awaited>['counter'];
}) {
  const [count, setCount] = useState(0);

  return (
    
      This component is rendered on the client:
      
      {count}
      
    

  );
}

Database

This tutorial is going to use Postgres for its database because it is well battle-tested, but you’re going to use the Prisma ORM to abstract away the database layer. This gives you the flexibility to use a variety of databases, and simplifies the API that you use to interact with it.

npm install prisma --save-dev

You’ll also need to install the Prisma client.

npm install @prisma/client

Initialize Prisma.

npx prisma init

This auto-generates yourprisma/schema.prisma file.

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  // Uses connection pooling
  url = env("DATABASE_URL")
}

model UserProfile {
  id                         String   @id @default(cuid())
  createdAt                  DateTime @default(now())
  updatedAt                  DateTime @updatedAt
  email                      String   @unique
  name                       String   @default("")
  acceptedTermsAndConditions Boolean  @default(false)
}

Add a aUserProfile model to it, which has an email and a name and a boolean whether they accepted your terms and conditions.

If you ran npx prisma init, rename your .env file to .env.local, otherwise create it and make sure it contains the credentials for your Prisma database.

DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"

Now create a src/lib/prisma.ts file, which will contain your Prisma client connection.

import { PrismaClient } from '@prisma/client';

declare global {
  var __database__: PrismaClient;
}

let prisma: PrismaClient;

if (process.env.NODE_ENV === 'production') {
  prisma = new PrismaClient();
} else {
  if (!global.__database__) {
    global.__database__ = new PrismaClient();
  }
  prisma = global.__database__;
}

export default prisma;

The re-assignment ensures that in a non-production environment (like during development or testing), only one instance of the Prisma client is created and reused across the entire application. This approach prevents the overhead of repeatedly initializing new connections to the database every time a module that needs database access is imported.

Modify your package.json to include the following helper commands for Prisma.

"prisma:deploy": "npx prisma migrate deploy && npx prisma generate",
"prisma:migrate": "npx prisma migrate dev --name",
"prisma:push": "npx prisma db push && npx prisma generate",
"prisma:reset-dev": "run-s prisma:wipe prisma:seed dev",
"prisma:seed": "tsx ./prisma/seed.ts",
"prisma:setup": "prisma generate && prisma migrate deploy && prisma db push",
"prisma:studio": "npx prisma studio",
"prisma:wipe": "npx prisma migrate reset --force && npx prisma db push",

Some of these commands use the run-s, tsxand dotenvpackages, which you’ll need to install.

npm install --save-dev npm-run-all tsx dotenv

Here’s an explanation of each Prisma command:

“prisma:deploy”: Deploys database migrations and generates Prisma Client. It runs migrations on production databases and updates the client API.
“prisma:migrate”: Creates a new migration from changes in the Prisma schema, applying it in the development environment. You must specify a name for the migration after the command.
“prisma:push”: Pushes the schema changes directly to the database and updates the Prisma Client. Useful for prototyping without creating migration files.
“prisma:reset-dev”: Resets the development database by wiping it, re-seeding it, and applying migrations in development mode.
“prisma:seed”: Runs a TypeScript seed script to populate the database with initial data.
“prisma:setup”: Generates the Prisma Client, deploys migrations to the database, and pushes the schema to the database.
“prisma:studio”: Opens Prisma Studio, a GUI for viewing and editing the database records.
“prisma:wipe”: Resets the database by forcefully dropping all data and migrations and then pushes the schema changes.

npm run prisma:setup

If your Prisma doesn’t recognize your .env.local, set your environment variable manually in your terminal. On Mac, this can be done using theexport command.

export DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"

Create a primsa/seed.ts. You can use it to seed your database with data for development.

import { exit } from 'node:process';

import { PrismaClient } from '@prisma/client';
import dotenv from 'dotenv';

dotenv.config({ path: '.env.local' });

const prisma = new PrismaClient();

const prettyPrint = (object: any) =>
  console.log(JSON.stringify(object, undefined, 2));

async function seed() {
  const user = await prisma.userProfile.create({
    data: {
      email: 'jan@reactsquad.io',
      name: 'Jan Hesters',
      acceptedTermsAndConditions: true,
    },
  });

  console.log('========= 🌱 result of seed: =========');
  prettyPrint({ user });
}

seed()
  .then(async () => {
    await prisma.$disconnect();
  })
  // eslint-disable-next-line unicorn/prefer-top-level-await
  .catch(async error => {
    console.error(error);
    await prisma.$disconnect();
    exit(1);
  });

If you run it, it’ll create your user.

$ npm run prisma:seed

> reactsquad-production@0.1.0 prisma:seed
> tsx ./prisma/seed.ts

========= 🌱 result of seed: =========
{
  "user": {
    "id": "clzekb5sp0000ock9gsp72p33",
    "createdAt": "2024-08-03T20:04:27.289Z",
    "updatedAt": "2024-08-03T20:04:27.289Z",
    "email": "jan@reactsquad.io",
    "name": "Jan Hesters",
    "acceptedTermsAndConditions": true
  }
}

In your server components, you can use prisma to fetch any data.

import prisma from '@/lib/prisma';
import {
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';

export default async function Dashboard() {
  const user = await prisma.userProfile.findUnique({
    where: { email: 'jan@reactsquad.io' },
  });

  return (
    
      
        User Profile
      
      
        {user ? (
          
            Name: {user.name}

            Email: {user.email}

          

        ) : (
          User not found.

        )}
      
    
  );
}

Use Facades

It’s a good idea to abstract away your database calls using facades. A facade is a design pattern where you provide a simplified interface to a complex subsystem.

Create a file that contains all facades related to your user profile model features/user-profile/user-profile-model.ts.

import { UserProfile } from '@prisma/client';

import prisma from '@/lib/prisma';

export async function retrieveUserProfileFromDatabaseByEmail(
  email: UserProfile['email'],
) {
  return await prisma.userProfile.findUnique({ where: { email } });
}

There are two main reasons for using facades.

Increase vendor resistance — You can switch third-party providers easily. For example, you might switch from Firebase to Supabase or vice versa. Instead of updating your whole codebase to reflect the change, you only update the facade.
Simplify your code — A facade can reduce the code you need to write in your application because it reduces the API to your specific application needs. Simultaneously, it makes your code easier to understand because you can give the facade descriptive names.

Then use your facade in your server component.

import { retrieveUserProfileFromDatabaseByEmail } from '@/features/user-profiles/user-profiles-model';
import {
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';

export default async function Dashboard() {
  const user =
    await retrieveUserProfileFromDatabaseByEmail('jan@reactsquad.io');

  return (
    
      
        User Profile
      

      
        {user ? (
          
            Name: {user.name}

            Email: {user.email}

          

        ) : (
          User not found.

        )}
      
    
  );
}

Vercel Postgres

You can use Vercel Postgres for your production deployment. They have an easy to follow guide, which you can check out in the Vercel documentation. But here are the steps real quick for your convenience.

To set up a database in your Vercel project, follow these steps:

Go to the Storage tab and click the Create Database button.
When the Browse Storage modal opens, choose Postgres and click Continue.

For creating a new database:

In the dialog box, type sample_postgres_db (or a name you prefer) in the Store Name field. Ensure the name has only alphanumeric characters, "_" or "-", and does not exceed 32 characters.
Choose a region. For lower latency, select a region close to your function region, which is US East by default.
Click Create.

Then you’ll need to add POSTGRES_URL_NON_POOLING to the datasource in your Prisma schema.

datasource db {
  provider  = "postgresql"
  // Uses connection pooling
  url       = env("DATABASE_URL")
  // Uses direct connection, ⚠️ make sure to keep this to `POSTGRES_URL_NON_POOLING`
  // or you'll have dangling databases from migrations
  directUrl = env("POSTGRES_URL_NON_POOLING")
}

Vercel uses connection poolers, which manage a pool of database connections that can be reused by different parts of an application, rather than establishing a new connection for each database request. The directUrl property is used to ensure operations requiring direct database access, such as migrations, can bypass the connection pooler for reliable execution.

You can get the environment variables for your Vercel database by pulling them from Vercel.

vercel env pull .env

Playwright

You also want to use E2E tests because E2E tests give you the most confidence that your app works as intended. E2E tests are skipped far too often, but you really should make it a habit to write them. The benefits are compounding.

Initialize Playwright.

$ npm init playwright@latest
Getting started with writing end-to-end tests with Playwright:
Initializing project in '.'
✔ Where to put your end-to-end tests? · playwright
✔ Add a GitHub Actions workflow? (y/N) · false
✔ Install Playwright browsers (can be done manually via 'npx playwright install')? (Y/n) · true

If this is your first time using Playwright, you can have a look through the test-examples/ folder that the initialization script creates, and then deleted it because you won't need it.

Modify the webServer key in your playwright.config.ts file.

webServer: {
  command: process.env.CI ? 'npm run build && npm run start' : 'npm run dev',
  port: 3000,
},

Add two scripts for your E2E tests to your package.json.

"test:e2e": "npx playwright test",
"test:e2e:ui": "npx playwright test --ui",

The first one runs your Playwright test in headless mode, while the second one runs your test in UI mode, which gives you time travel debugging, watch mode and more.

import { expect, test } from '@playwright/test';

test.describe('landing page', () => {
  test('given any user: shows the test user', async ({ page }) => {
    await page.goto('/');

    await expect(page.getByText('Jan Hesters')).toBeVisible();
    await expect(page.getByText('jan@reactsquad.io')).toBeVisible();
  });
});

Run your tests to check that your Playwright setup worked.

$ npm run test:e2e

> reactsquad-production@0.1.0 test:e2e
> npx playwright test


Running 3 tests using 3 workers
  3 passed (3.9s)

It ran three tests because by default Playwright is configured to run in Chrome, Safari, and Firefox.

GitHub Actions

It’s good practice to run your app with CI/CD. CI/CD stands for continuous delivery and continuous deployment.

Add a secret for your database URL to your repository’s settings in GitHub.

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/testdb"

Then create your GitHub Actions YAML configuration in a .github/workflows/pull-request.yml file for a comprehensive CI/CD pipeline including linting, type checking, testing, and more.

name: Pull Request

on: [pull_request]

jobs:
  lint:
    name: ⬣ ESLint
    runs-on: ubuntu-latest
    steps:
      - name: ⬇️ Checkout repo
        uses: actions/checkout@v3

      - name: ⎔ Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: 📥 Download deps
        uses: bahmutov/npm-install@v1

      - name: 🔬 Lint
        run: npm run lint

  type-check:
    name: ʦ TypeScript
    runs-on: ubuntu-latest
    steps:
      - name: ⬇️ Checkout repo
        uses: actions/checkout@v3

      - name: ⎔ Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: 📥 Download deps
        uses: bahmutov/npm-install@v1

      - name: 🔎 Type check
        run: npm run type-check --if-present

  commitlint:
    name: ⚙️ commitlint
    runs-on: ubuntu-latest
    if: github.actor != 'dependabot[bot]'
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - name: ⬇️ Checkout repo
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: ⚙️ commitlint
        uses: wagoid/commitlint-github-action@v4

  vitest:
    name: ⚡ Vitest
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:12
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
    steps:
      - name: ⬇️ Checkout repo
        uses: actions/checkout@v3

      - name: ⎔ Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: 📥 Download deps
        uses: bahmutov/npm-install@v1

      - name: 🛠 Setup Database
        run: npm run prisma:wipe
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/testdb

      - name: ⚡ Run vitest
        run: npm run test -- --coverage
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/testdb

  playwright:
    name: 🎭 Playwright
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:12
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
    steps:
      - name: ⬇️ Checkout repo
        uses: actions/checkout@v3

      - name: ⎔ Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: 📥 Download deps
        uses: bahmutov/npm-install@v1

      - name: 🌐 Install Playwright Browsers
        run: npx playwright install --with-deps

      - name: 🛠 Setup Database
        run: npm run prisma:wipe
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/testdb

      - name: 🎭 Playwright Run
        run: npx playwright test
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/testdb

      - name: 📸 Playwright Screenshots
        uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

Now every time you make a pull request to your app, it automatically runs your tests to ensure it works, runs TypeScript type checks and lints it, so that everyone contributes code with the same formatting.

What is Memoization? (In JavaScript & TypeScript)

Jan Hesters — Tue, 05 Nov 2024 09:38:11 GMT

Memoization and caching are foundational concepts in programming.

You want to understand memoization, so you can understand concepts that build upon memoization. For example, the memo higher-order component in React, useCallback and useMemo hooks in React, selectors in Redux and much more.

In this article, you’re going to get a detailed look into memoization with examples in JavaScript and TypeScript.

https://medium.com/media/dba5e88df6ae12d50d227fc0a2f02a43/href

What Is Memoization?

Memoization is a way to speed up performance by reducing computations.

When you first calculate a result, you save it. If you need the result for the same arguments again, you use the saved result instead of recalculating.

And there are two ways that you can implement memoization:

Implicit Caching
Decorator Functions

Implicit Caching

Implicit caching is when you manually implement caching logic within functions.

Let’s say you have a simple add function and you want to memoize it.

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

You can rewrite this add function, so that it memoizes its results.

If you want to code along with this article, initialize a new npm project.

npm init --y

Then write a function called memoizeAdd().

function memoizeAdd() {
  const cache = {};

  return function memoizedAdd(a, b) {
    const key = `${a},${b}`;

    if (key in cache) {
      return cache[key];
    } else {
      const result = a + b;

      cache[key] = result;

      return result;
    }
  };
}

const memoizedAdd = memoizeAdd();

console.log(memoizedAdd(3, 4));  // Computes and caches the result.
console.log(memoizedAdd(3, 4));  // Retrieves the result from cache.
console.log(memoizedAdd(5, 6));  // Computes and caches a new result.
console.log(memoizedAdd(3, 4));  // Still retrieves the result from cache.

Let’s break down what’s happening here.

In memoizeAdd() you create a cache, which is typically a hash table or an object, where you store the results of function calls. Each entry uses the function's input as the key and the output as the value.

const cache = {
  '3,1': 4,
  '9001,2012': 11_013,
};

Next, you return the memoizedAdd function, which takes in two numbers a and b.

Each unique combination of arguments corresponds to a key.

Before executing the main logic, the function checks the cache using the current input as the key. If the input is in the cache, it returns the cached result.

If the input is missing in the cache, the function computes the result, stores it in the cache, and then returns the result.

When you call the memoizedAdd function, the result is stored together with its parameters. If you call it again with the same parameters, the result comes from the cache. If the parameters are new, the function computes the result again.

When you run this code, you get the following output.

$ node implicit-caching.js
7
7
11
7

Decorator Functions For Memoization

In languages that support higher-order functions, you can use decorators to add memoization without changing the function’s core logic.

Higher-order functions are functions that take in functions and return functions.

If this concept is new to you, you might want to read “Unleash JavaScript’s Potential with Functional Programming”. This article explains higher-order functions and much more from first principles.

Now, check out this simple example of a decorator function for memoization.

function memoize(fn) {
  const cache = new Map();

  return function(...args) {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key);
    }

    const result = fn.apply(this, args);
    cache.set(key, result);

    return result;
  };
}

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

const memoizedAdd = memoize(add);

console.log(memoizedAdd(3, 4));  // Calculates and caches the result.
console.log(memoizedAdd(3, 4));  // Returns the cached result.
console.log(memoizedAdd(5, 6));  // Computes and caches a new result.
console.log(memoizedAdd(3, 4));  // Still retrieves the result from cache.

Let’s go through this code step by step, too.

First, you create a memoize function that takes another function, fn, as its argument.

It starts by initializing a cache using a Map. This cache will store the results of the function calls. A Map is used instead of an object because it can handle a wider variety of key types.

const cache = new Map();

// Use numbers as key for cache.
map.set('[3,1]', 4);
// Use functions as key for cache.
map.set('[function increment(), function double()]', 42);

The returned function accepts any number of arguments. It serializes these arguments into a string to use as a key for the cache.

Before executing the original function, the wrapper checks if the key already exists in the cache. If it does, the function returns the cached result.

If the key is missing in the cache, the wrapper calls the original function using fn.apply(this, args). It stores the result in the cache and returns it.

You can now memoize your add function by passing it to the memoize function.

The memoizedAdd function will work just like in the implicit caching example.

And running your code yields the same result.

$ node decorator-function.js
7
7
11
7

Recursion And The Fibonacci Sequence

The add function is computationally cheap.

To experience the benefits of memoization, you need to memoize an expensive function.

A classic example is the fibonacci function. Outside of memoization, learning about this function is useful because it's a common topic in coding interviews.

The Fibonacci sequence is a series of numbers where each number is the sum of the two preceding ones. It usually starts with 0 and 1. Here’s how it begins:

0, 1, 1, 2, 3, 5, 8, 13, 21, 34, …

In mathematical terms, you can express this as:

function fibonacci(n) {
  if (n <= 1) {
    return n;
  }

  return fibonacci(n - 1) + fibonacci(n - 2);
}

f n is 0 or 1, the function returns n directly. These are the first two numbers in the Fibonacci sequence.

For values of n greater than 1, the function calls itself twice: once for fibonacci(n - 1) and once for fibonacci(n - 2), and adds the results of these two calls.

Here’s a table showing how the function computes fibonacci(4):

You can see that fibonacci(2) is calculated twice when calling fibonacci(4): once directly from fibonacci(4) and again from fibonacci(3).

The negative performance impacts of these redundant calculations compound as the input to the fibonacci function increases. You want to read this article until the end to learn how memoization can make this computation lightning fast.

Stack Tracing

Before memoizing your fibonacci function, add a name property to your memoized function. This makes stack tracing easier if your function throws an error.

function memoize(fn) {
  const cache = new Map();

  function memoizedFunction(...args) {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key);
    }

    const result = fn.apply(this, args);
    cache.set(key, result);

    return result;
  }

  Object.defineProperty(memoizedFunction, 'name', {
    value: `memoized_${fn.name}`,
    configurable: true
  });

  return memoizedFunction;
}

Use Object.defineProperty to set the name property of the memoizedFunction to a more descriptive value, like memoized_${fn.name}, where fn.name is the name of the original function. By setting this property to be configurable, you allow further modifications or deletion of the property if necessary.

Measuring Memoization Performance

Now you’re ready to measure the impact of memoization. Memoize your fibonacci function and time how long it takes to calculate large numbers.

function memoize(fn) {
  const cache = new Map();

  function memoizedFunction(...args) {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key);
    }

    const result = fn.apply(this, args);
    cache.set(key, result);

    return result;
  }

  Object.defineProperty(memoizedFunction, 'name', {
    value: `memoized_${fn.name}`,
    configurable: true
  });

  return memoizedFunction;
}

function fibonacci(n) {
  if (n <= 1) {
    return n;
  }

  return fibonacci(n - 1) + fibonacci(n - 2);
}

const memoizedFibonacci = memoize(fibonacci);

function measurePerformance(func, arg) {
  const startTime = process.hrtime.bigint();
  const result = func(arg);
  const endTime = process.hrtime.bigint();
  // Convert nanoseconds to milliseconds.
  const duration = (endTime - startTime) / BigInt(1000000);
  console.log(`${func.name}(${arg}) = ${result}, Time: ${duration}ms`);
}

const n = 42;

console.log("Starting performance measurement:");
measurePerformance(fibonacci, n);
measurePerformance(memoizedFibonacci, n);
// Second call to show caching effect.
measurePerformance(memoizedFibonacci, n);

The measurePerformance function evaluates and reports the execution time of a given function by capturing start and end times with process.hrtime.bigint(), which provides precise timestamps in nanoseconds. After executing the function with a given argument, it calculates the duration in milliseconds by subtracting the start time from the end time and converting the result from nanoseconds. It then logs the function name, argument, output, and execution duration to the console.

Using measurePerformance, you can compare the performance of the standard Fibonacci function with the memoized version.

Here are the results for the performance measurements.

$ node fibonacci.js
Starting performance measurement:
fibonacci(42) = 267914296, Time: 2405ms
memoized_fibonacci(42) = 267914296, Time: 2394ms
memoized_fibonacci(42) = 267914296, Time: 0ms

As you can see, running the memoized version the second time is instant because the result is retrieved from the cache.

Clearing Cache

When you use memoization, you want to implement .clear() method to manage your application's resources and performance. Here's why:

Memory management: It frees up resources by allowing you to manually purge the cache.
Data freshness: It ensures cached results stay accurate by removing outdated or incorrect data.
Control over cache behavior: It gives you the ability to reset the cache in response to events or conditions that affect data processing.
Testing and debugging: It allows you to operate your functions in a known state, without interference from cached data, which is important for reliable testing.
Performance optimization: It maintains cache efficiency by allowing periodic resets to manage size and lookup costs.

Now, add the ability to clear the cache.

function memoize(fn) {
  const cache = new Map();

  function memoizedFunction(...args) {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key);
    }

    const result = fn.apply(this, args);
    cache.set(key, result);

    return result;
  }

  memoizedFunction.clear = function clear() {
    cache.clear();
  };

  Object.defineProperty(memoizedFunction, 'name', {
    value: `memoized_${fn.name}`,
    configurable: true
  });

  return memoizedFunction;
}

function fibonacci(n) {
  if (n <= 1) {
    return n;
  }

  return fibonacci(n - 1) + fibonacci(n - 2);
}

const memoizedFibonacci = memoize(fibonacci);

function measurePerformance(func, arg) {
  const startTime = process.hrtime.bigint();
  const result = func(arg);
  const endTime = process.hrtime.bigint();
  // Convert nanoseconds to milliseconds.
  const duration = (endTime - startTime) / BigInt(1000000);
  console.log(`${func.name}(${arg}) = ${result}, Time: ${duration}ms`);
}

const n = 42;

// Measure memoized Fibonacci.
measurePerformance(memoizedFibonacci, n);

// Measure memoized Fibonacci second call.
measurePerformance(memoizedFibonacci, n);

// Clear cache and measure again.
console.log('Clearing cache and measuring again:');
memoizedFibonacci.clear();
measurePerformance(memoizedFibonacci, n);

Then modify your usage example to include a call of the .clear() method after the result has already been memoized successfully.

$ node fibonacci.js
memoized_fibonacci(42) = 267914296, Time: 2456ms
memoized_fibonacci(42) = 267914296, Time: 0ms
Clearing cache and measuring again:
memoized_fibonacci(42) = 267914296, Time: 2484ms

As you can see, clearing the cache causes the function to compute its result again.

Memoization In TypeScript

So far, all code has been written in JavaScript. Now you will translate the code examples into TypeScript.

Install TypeScript and the node types.

$ npm i --save-dev typescript @types/node

added 3 packages, and audited 4 packages in 1s

found 0 vulnerabilities

Then initialize a new TypeScript project.

$  npx tsc --init


Created a new tsconfig.json with:
                                                                      TS
  target: es2016
  module: commonjs
  strict: true
  esModuleInterop: true
  skipLibCheck: true
  forceConsistentCasingInFileNames: true


You can learn more at

Now you can write your memoize function in TypeScript.

type AnyFunction = (...args: any[]) => any;

interface MemoizedFunction extends CallableFunction {
  (...args: Parameters): ReturnType;
  clear: () => void;
}

function memoize(fn: T): MemoizedFunction {
  const cache = new Map>();

  const memoizedFunction = function(...args: Parameters): ReturnType {
    const key = JSON.stringify(args);

    if (cache.has(key)) {
      return cache.get(key)!;
    }

    const result = fn(...args);
    cache.set(key, result);

    return result;
  } as MemoizedFunction;

  memoizedFunction.clear = function clear() {
    cache.clear();
  };

  Object.defineProperty(memoizedFunction, 'name', {
    value: `memoized_${fn.name}`,
    configurable: true
  });

  return memoizedFunction;
}

function fibonacci(n: number): number {
  if (n <= 1) {
    return n;
  }

  return fibonacci(n - 1) + fibonacci(n - 2);
}

const memoizedFibonacci = memoize(fibonacci);

function measurePerformance(func: MemoizedFunction, arg: number) {
  const startTime = process.hrtime.bigint();
  const result = func(arg);
  const endTime = process.hrtime.bigint();
  // Convert nanoseconds to milliseconds.
  const duration = (endTime - startTime) / BigInt(1000000);
  console.log(`${func.name}(${arg}) = ${result}, Time: ${duration}ms`);
}

const n = 42;

// Measure memoized Fibonacci.
measurePerformance(memoizedFibonacci, n);

// Measure memoized Fibonacci second call.
measurePerformance(memoizedFibonacci, n);

// Clear cache and measure again.
memoizedFibonacci.clear();
measurePerformance(memoizedFibonacci, n);

Here, you create an AnyFunction type, which represents a generic function type in TypeScript. This type is flexible and allows for any function that takes an arbitrary number of arguments of any type and returns any type.

Next, you define a generic MemoizedFunction interface that extends the built-in CallableFunction interface and introduces a clear method. Here, T is a generic type parameter constrained to any function that matches the AnyFunction type. The interface ensures that your memoized function behaves like the original function in terms of accepting the same parameters and returning the same type and additionally exposes the clear method.

You can now implement your memoize function so that it returns the MemoizedFunction interface. Using the as keyword, you can let TypeScript know that the returned function is a MemoizedFunction.

Now when you hover over memoizedFibonacci, TypeScript knows the correct type of the function.

const memoizedFibonacci: MemoizedFunction<(n: number) => number>

And TypeScript also knows about the .clear() method on the memoized function.

(property) MemoizedFunction<(n: number) => number>.clear: () => void

Recursion With Memoization

Your function still has a shortcoming. Currently, the memoization only caches the results of the full function call for each argument, but does NOT cache the results of the intermediate recursive calls.

What is a potential drawback of using recursion without memoization for solving certain problems?

It is the significant increase in computational time and resource usage due to redundant calculations.

Call the function with a big number n and then with n + 1.

// ... previous code stays the same.

const n = 42;

measurePerformance(memoizedFibonacci, n);
measurePerformance(memoizedFibonacci, n + 1);

Then run your code to see the difference in performance between 42 and 43.

$ npx tsx example-5.ts
memoized_fibonacci(42) = 267914296, Time: 2442ms
memoized_fibonacci(43) = 433494437, Time: 3975ms

As you can see, fibonacci(43) takes much longer because it recalculates fibonacci(42) from scratch, even though the result is already cached. The same problem occurs with every other intermediate recursive call.

You can fix this by using memoization in the implementation of the fibonacci function.

// ... `memoize` is the same as above.

function fibonacci(n: number): number {
  if (n <= 1) {
    return n;
  }

  return memoizedFibonacci(n - 1) + memoizedFibonacci(n - 2);
}

const memoizedFibonacci = memoize(fibonacci);

function measurePerformance(func: MemoizedFunction, arg: number) {
  const startTime = process.hrtime.bigint();
  const result = func(arg);
  const endTime = process.hrtime.bigint();
  // Convert nanoseconds to milliseconds.
  const duration = (endTime - startTime) / BigInt(1000000);
  console.log(`${func.name}(${arg}) = ${result}, Time: ${duration}ms`);
}

const numbers = [10, 20, 30, 40, 42, 43, 500];

numbers.forEach(n => {
  measurePerformance(memoizedFibonacci, n);
});

When you define the fibonacci function, use its memoized version to calculate the next number.

Now, run the function on various large numbers.

$ npx tsx fibonacci.ts
memoized_fibonacci(10) = 55, Time: 0ms
memoized_fibonacci(20) = 6765, Time: 0ms
memoized_fibonacci(30) = 832040, Time: 0ms
memoized_fibonacci(40) = 102334155, Time: 0ms
memoized_fibonacci(42) = 267914296, Time: 0ms
memoized_fibonacci(43) = 433494437, Time: 0ms
memoized_fibonacci(500) = 1.394232245616977e+104, Time: 0ms

The calculation is now virtually instant for every function call no matter how large.

So when you memoize, ask yourself: “What do you want to memoize?” Do you want to memoize only the outer function, or do you want to also memoize intermediary results in the implementation?

Why Memoize? (Use Cases)

When do you want to use memoization?

Memoization is useful in:

Recursive algorithms: As shown with the Fibonacci sequence, recursive functions that repeat the same calculations can benefit greatly from memoization by avoiding redundant operations.
Database queries: You can cache results from expensive database queries.
Data fetching: In web development, memoization can cache responses from API calls. This reduces network traffic and speeds up response times by serving cached data for repeated requests with the same parameters.
Data transformation: You can cache results of transformations that are costly in processing time.
Preventing component rendering: In frontend frameworks like React, memoization can prevent unnecessary re-renders of components as long as their their props stay the same.

Memoization Trade-Offs

As you’ve learned, memoization improves performance by reducing time complexity of operations and lowering the load on compute resources by avoiding repeated calculations.

But memoization also comes with drawbacks.

Memory usage: Memoization increases memory consumption by storing function call results, which can be a problem in environments with limited memory.
Complexity: Adding memoization introduces complexity to your codebase, and requires careful cache management to avoid bugs and maintainability issues.
Cache management: You must implement strategies for cache eviction and invalidation to prevent outdated or incorrect data, which can be challenging.
side-effects: Functions with side-effects are can be problematic for memoization because the side-effects might need to occur with each function call. Memoization should primarily be used with pure functions.
Concurrency issues: In multi-threaded applications, memoization must be handled carefully to avoid race conditions and ensure thread safety when accessing the cache.

Subscribe to my YouTube channel for more great JavaScript and TypeScript tutorials!

Unleash JavaScript’s Potential with Functional Programming

Jan Hesters — Tue, 15 Oct 2024 13:50:59 GMT

Too many JavaScript developers have no idea what JavaScript is capable of.

This article will transform the way you write code and unleash your potential as a programmer.

By the end of this article and video, you will be able to read, understand and write code like this:

const curry =
 (f, array = []) =>
 (...args) =>
 (a => (a.length >= f.length ? f(...a) : curry(f, a)))([
 ...array,
 ...args,
 ]);
const add = curry((a, b) => a + b);
const inc = add(1);
const pipe = (...fns) => x => fns.reduce((y, f) => f(y), x);
const doubleInc = pipe(x => x * 2, inc);

https://medium.com/media/4b611b7a5683f5d4d8963ac62b792dd7/href

JavaScript is a two paradigm programming language because it supports OOP and FP. This article is your “step-by-step with no steps skipped” guide to functional programming, so you can use the language to its full capabilities and write more modular, deterministic and testable code. It literally goes from primitives all the way to advanced function composition.

Definition

If you look up functional programming you might get lost in academic lingo. If you’re lucky you will find some kind of simple definition like this:

“Functional programming is the process of building software by composing functions. Functional programming is declarative rather than imperative. Side-effects are isolated. And application state usually flows through pure functions.”

You can relax because this article will explain all of these terms and more. Starting at Primitives.

Primitives

Primitives are all datatypes that can hold only one value at a time. JavaScript has 7 primitive data types.

string: Represents text.
number: Represents numerical values.
boolean: Represents true or false.
undefined: Indicates a variable has not been assigned a value.
null: Represents an intentional absence of any object value.
Symbol: Creates unique identifiers.
BigInt: Handles numbers larger than the standard number type can.

// primitives.js
const string = "ReactSquad.io";
const number = 9001;
const boolean = true;
const notThere = undefined;
const weirdUndefined = null;
const noOneUsesThis = Symbol('🤯 ');
const bigInt = 1n;

Composite data types

Composite data types can store collections or combinations of values.

Object: A structure that can hold multiple values as named properties.
Array: A list-like structure that holds values in a specific order.
Map: A collection of keyed data items, similar to an object but with keys of any type and maintains the order of insertions.
Set: A collection of unique values. Like an array, but each value can only occur once.

// composite.js
const obj = { key: "value" };
const array = [1, 2, 3, 4, 5];

A Map in JavaScript is a collection of keyed data items that maintains the order of insertions and allows keys of any type.

// map.js
// Creating a new Map
const map = new Map();

// Setting key-value pairs in the Map
map.set('name', 'John');
map.set('age', 30);
map.set(1, 'one');

console.log(map);
// Output: Map(3) {'name' => 'John', 'age' => 30, 1 => 'one'}

// Retrieving a value by key.
console.log(map.get('name')); // Output: John

// Checking if a key exists.
console.log(map.has('age')); // Output: true

// Size of the Map.
console.log(map.size); // Output: 3
Unleash JavaScript's Potential With Functional Programming Article.md 2024-09-30
3 / 29

// Removing a key-value pair.
map.delete(1);

// Clearing all entries.
map.clear();

A Set in JavaScript is a collection of unique values, ensuring that each value appears only once.

// set.js
// Creating a new Set.
const set = new Set();

// Adding values to the Set.
set.add('apple');
set.add('banana');
set.add('apple'); // This will not be added again.

console.log(set);
// Output: Set(2) {'apple', 'banana'}
// Reminder: Sets delete duplicates.

// Checking if a value exists.
console.log(set.has('banana')); // Output: true

// Size of the Set.
console.log(set.size); // Output: 2

// Deleting a value.
set.delete('apple');

// Iterating over Set values.
set.forEach(value => {
 console.log(value);
});

// Clearing all values.
set.clear();

Functions

function sumDeclaration(a, b) {
 return a + b;
}
const sumArrow = (a, b) => a + b;

A function is a process that can take inputs, called parameters, and can produce some output called return value.

Parameters vs. Arguments

Parameters are variables defined in the function declaration. They act as placeholders for the values that a function will operate on.
Arguments are the actual values or data passed to the function when it is called. These values replace the parameters during the function’s execution.
An application happens when the arguments are used to replace the function’s parameters. This allows the function to perform its task using the provided arguments.

function myFunction(parameter) {
 return parameter;
}
const myArgument = "Some value";
myFunction(myArgument); // Output: "Some value";

A function can be a mapping, a procedure or handle I/O operations.

Mapping: Produce some output based on given inputs. A function maps input values to output values. (So the examples you saw earlier are mappings.)

const square = x => x * x;
square(7); // 49

Procedure: A function executes some steps in a sequence. The sequence is known as a procedure, and programming in this style is known as procedural programming.

function prepareTea(teaType) {
 let steps = [];
 steps.push("Boil water");
 steps.push("Add " + teaType);
 steps.push("Steep for 5 minutes");
 steps.push("Serve hot");
 return steps.join("\\n");
}

console.log(prepareTea("green tea"));
// Output: Boil water
// Add green tea
// Steep for 5 minutes
// Serve hot

function calculateCircleArea(radius) {
 if (radius <= 0) {
 return "Error: Radius must be greater than zero.";
 }

 const pi = Math.PI; // Use Math.PI for more accuracy
 const squaredRadius = radius * radius;
 const area = pi * squaredRadius;
 const roundedArea = Math.round(area * 100) / 100; // Round to 2 decimal
places
 return "Calculated area: " + roundedArea;
}

console.log(calculateCircleArea(5));
// Output: Calculated area: 78.54

console.log(calculateCircleArea(-1));
// Output: Error: Radius must be greater than zero.

I/O operations: I/O is short for input and output. Functions may handle interactions with system components like the screen, storage, logs, or network.

async function fetchData(url) {
 const response = await fetch(url);
 const data = await response.json();
 return data;
}

fetchData('https://jsonplaceholder.typicode.com/todos/1')
 .then(data => console.log(data));
// {
// "userId": 1,
// "id": 1,
// "title": "delectus aut autem",
// "completed": false
// }

Methods

Methods are functions attached to objects. They allow you to perform operations on the object’s data. In JavaScript, methods are commonly used with objects, arrays, and other built-in types.

const person = {
 name: 'John',
 greet: function() {
 console.log('Hello, ' + this.name);
 }
};

// Calling the greet method.
person.greet(); // Output: Hello, John

Earlier in this article, you saw how to use methods of the Map and Set objects.

Primitives also have methods because under the hood everything in JavaScript is an object.

const greeting = 'Hello, world';

// Changing case.
console.log(greeting.toUpperCase()); // Output: HELLO, WORLD

// Replacing part of the string.
console.log(greeting.replace('Hello', 'Goodbye')); // Output: Goodbye,
world

// Checking if it includes a substring.
console.log(greeting.includes('world')); // Output: true

Noop

A “noop” stands for “no operation.” It describes a function, operation, or command that does nothing. This can be useful for placeholders in code or to intentionally have no effect.

In JavaScript, a noop function looks like this:

function noop() {}
const noop = () => {};

Pure functions

A function is a pure function, if:

given the same inputs, it always returns the same output, and
it has no side-effects.

You’ve seen pure functions already. For example, both sum functions and the square function are pure.

Pure functions are deterministic. This is captured by the first property. A pure function will always produce the same output for the same set of inputs, no matter when or how many times it is called. This predictability is a key property of pure functions and is essential for reliable and testable code.

Here is an example for a function that violates the first rule.

/**
 * Generates a random integer between the start and end values, both
inclusive.
 *
 * @param {number} start - The starting value.
 * @param {number} end - The ending value.
 * @returns {number} - A random integer between the start and end.
 */
export const generateRandomInt = (start, end) =>
 Math.round(Math.random() * (end - start) + start);

generateRandomInt can be called with the same start and end values, but it produces different results because it uses Math.random().

And here is a example, which violates the second rule.

let externalArray = [];
function sideEffectingFunction(x) {
 externalArray.push(x); // Modifies external array
 return x;
}

console.log(sideEffectingFunction(5)); // 5, modifies externalArray
console.log(sideEffectingFunction(10)); // 10, modifies externalArray, too
console.log(externalArray); // Output: [5, 10]

Even though sideEffectingFunction returns something, it pushes code as a side-effect to an array and you can meaningfully call it without using it's return value.

“A dead giveaway that a function is impure is if it makes sense to call it without using its return value. For pure functions, that’s a noop.” — Eric Elliott

Idempotence

Another concept you need to know is idempotence.

Idempotence is a property of certain operations in which no matter how many times you perform the operation, the result remains the same after the first application. For example, setting a value to 5 is idempotent because no matter how often you do it, the value remains 5.

let number = 5;
number = 5; // still 5
number = 5; // no change, still 5

All pure functions are idempotent, but not all idempotent functions are pure functions. An idempotent function can cause idempotent side-effects. A pure function cannot. Deleting a record in a database by ID is idempotent, because the row of the table stays deleted after subsequent calls. Additional calls do nothing.

Here is a synchronous example.

const uniqueItems = new Set();
// This custom addItem function is idempotent because ...
function addItem(item) {
 uniqueItems.add(item);
 console.log(`Added item: ${item}`);
 return uniqueItems.size;
}

addItem("apple"); // Outputs "Added item: apple", returns 1
// ... calling addItem with the same item twice leaves the set unchanged.
addItem("apple"); // Outputs "Added item: apple", returns 1
addItem("banana"); // Outputs "Added item: banana", returns 2

Referential Transparency

Idempotent functions without side-effects have a feature known as referential transparency.

That means that if you have a function call:

const result = square(7);

You could replace that function call with the result of square(7) without changing the meaning of the program. So, for example if the result of square(7) is 49. Therefore, you could change the code above to:

const result = 49;

and your program would still work the same.

Functional Programming Prerequisites

A language needs three features to support functional programming, and JavaScript has all three:

First-class functions (and therefore higher-order functions),
closures, and
anonymous functions and concise lambda syntax.

First class functions

In JavaScript, functions are treated as first-class citizens. This means that functions can be stored in variables. Therefore, you can use functions as:

arguments to other functions,
return values from functions,
values to an objectʼs keys

// Storing a function in a variable.
const greet = function() {
 return "Hello, World!";
}

// Passing a function as an argument (callback).
function shout(fn) {
 const message = fn();
 console.log(message.toUpperCase());
}

shout(greet); // Output: "HELLO, WORLD!"

// Returning a function from another function.
function multiply(multiplicand) {
 return function (multiplier) {
 return multiplicand * multiplier;
 }
}

const double = multiply(2);
console.log(double(5)); // Output: 10

If you want to learn what first-class functions enable in React check out this article about higher-order components, link is in the description below.

Higher-order functions

The last example multiply that you saw is called a "higher-order function" because when you call it for the first time with a number, it returns a function.

Any function that takes in or returns a function is called a higher order function.

function greet() {
 return "Hello World!"
}

const identity = x => x; // Same as myFunction from earlier ❗
identity(greet)(); // "Hello World!"

Closure

The multiply function from earlier hid another key concept: Closure.

A closure happens when a function is bundled together with it’s lexical scope. In other words, a closure gives you access to an outer functionʼs scope from an inner function. Closures in JavaScript are created whenever a function is created, at function creation time.

To use a closure, define a function inside another function and expose it by returning the inner function or passing it to another function. The inner function can access variables in the outer function’s scope, even after the outer function has returned.

function multiply(multiplicand) {
 return function(multiplier) {
 return multiplicand * multiplier;
 }
}

// Multiplicand of 2 gets captured in the closure because the inner
// returned function has access to it, even though the outer `multiply`
// function already ran to completion.
const double = multiply(2);
console.log(double(5)); // Output: 10

Closures serve three purposes:

They provide data privacy for objects.
In functional programming, they enable partial application and currying.
They act as parameters for callback or higher-order functions like map, reduce, and filter.

You’re going to see 2.) and 3.) later in this article, so let’s take a look at the concept of data privacy.

const createCounter = () => {
 let count = 0;
 return function increment() {
 count = count + 1;
 return count;
 }
}

const counter1 = createCounter();
const counter2 = createCounter();
counter1(); // 1
counter1(); // 2
counter2(); // 1
let capturedCount = counter1(); // 3
capturedCount = capturedCount + 39; // 42
counter1(); // 4

No external influence can manipulate the count value of counter1. You need to call counter1 to increment it.

This matters because some applications require private state. A common pattern is to prefix the private key with __.

const user = {
 __secretKey: 'abcj'
}

However, junior developers might not know that __ signals: "Do NOT change this key.", so they mutate it. And senior developers sometimes think it's okay to change it because they believe they know better.

Closures give you a reliable way to enforce data privacy for everyone.

Imperative vs Declarative

As you learned at the start of this article, functional programming is declarative. But what does that mean?

Imperative code describes “how” to do things. The code contains the specific steps needed to achieve your desired result.

Declarative code describes “what” to do. The “how” gets abstracted away. In other words, imperative programming is about defining the process to reach an outcome. This is known as flow control, where you dictate each step of the computation.

Declarative programming, on the other hand, is about defining the outcome, known as data flow. Here, you describe what you want, and the system determines how to achieve it.

Here is an example for imperative code.

let numbers = [1, 2, 3, 4, 5];
let doubled = [];
for (let i = 0; i < numbers.length; i++) {
 doubled.push(numbers[i] * 2);
}
console.log(doubled); // Output: [2, 4, 6, 8, 10]

And here is another example of imperative code, but this time with a custom function.

function filterEvens(numbers) {
 let index = 0;
 
 while (index < numbers.length) {
 if (numbers[index] % 2 !== 0) {
 // Removes the item at the current index if it's odd.
 numbers.splice(index, 1);
 } else {
 // Only move to the next index if the current item was not removed
 // because the current index gets taken by the value after the
 // deleted one.
 index++;
 }
 }
}

let numbers = [1, 2, 3, 4, 5];
filterEvens(numbers);
console.log(numbers); // Output: [2, 4]

Before you look at declarative code, you need to understand immutability and abstraction.

Immutability

Immutability in programming means that an object or value cannot be modified after it is created; instead, any changes result in a new object or value.

const originalArray = [1, 2, 3];
// Creates a new array by spreading the original and adding a new element.
const newArray = [...originalArray, 4];

console.log(originalArray); // Output: [1, 2, 3]
console.log(newArray); // Output: [1, 2, 3, 4]

Similarly, mutable state is state that can be modified after you created it.

const array = [1, 2, 3];
array.push(4); // Modifies the original array by adding a new element.

console.log(array); // Output: [1, 2, 3, 4]

Immutability is a central concept of functional programming because with it, the data flow in your program is preserved. State history is maintained, and it helps prevent strange bugs from creeping into your software.

“non-determinism = parallel processing + mutable state” — Martin Odersky

You want determinism to make your programs easy to reason about, and parallel processing to keep your apps performant, so you have to get rid of mutable state.

Generally speaking, when you write your code using functional programming it becomes more deterministic, easier to reason about, easier to maintain, more modular and more testable.

Abstraction

Abstraction is a fundamental concept in programming that involves hiding the complex reality while exposing only the necessary parts of an object or a system.

There are two types of abstraction: generalization and specialization.

Generalization is when you create a more universal form of something for use in multiple contexts. This process identifies common features among different components and develops a single model to represent all variations.

This is what most people think of when they hear “abstraction” and what Eric Elliott refers to when he says:

“Junior developers think they have to write a lot of code to produce a lot of value. Senior developers understand the value of the code that nobody needed to write.” — Eric Elliott

Specialization is when you apply the abstraction to a specific use-case and add what makes the current situation different.

The hard part is knowing when to generalize and when to specialize. Unfortunately, there is no good rule of thumb for this — you develop a feel for both with experience.

And what you’re going to find is: Abstraction is the key to simplicity.

“Simplicity is about subtracting the obvious and adding the meaningful.” — John Maeda

Using the functional programming paradigm you can create the most beautiful abstractions.

At this point you’re probably starving for examples and you’re going to see some soon.

Now, it’s time to look at declarative code, which will also show you more immutability and some abstraction.

Array methods

Remember, declarative programming is about “what” to do.

The perfect example of declarative code in JavaScript are the native array methods. You’re going to see the three most common ones: map, filter and reduce.

map Take a look at the map function first. It does exactly what we did earlier with the for loop, but the code is a lot more concise.

const numbers = [1, 2, 3, 4, 5];
const doubled = numbers.map(n => n * 2); // Output: [2, 4, 6, 8, 10]

The map method is a perfect example of abstraction.

map removes the obvious: iterating over the array and changing each value. Since it takes in a function, the map method is a higher-order function.

You only supply the meaningful: the function that doubles a number, which map applies to every number in the array. This double function is an anonymous function using the concise lamda syntax.

In general, a concise lambda is a simplified way to write a function with minimal syntax. In JavaScript it refers to the arrow function syntax.

map is also immutable because it returns a new array. numbers and doubled are two distinct arrays and the numbers array still contains the numbers 1 through 5. You can verify this by mapping using the identity function that returns its input.

const numbers = [1, 2, 3, 4, 5];
const clone = numbers.map(x => x);
console.log(numbers === clone); // false

Even though numbers and clone are both an array with the numbers 1 through 5, they are different array instances.

You might be asking yourself: “Isn’t that generating tons of data that no one uses?” Well kinda, but compared to what modern laptops are capable of the data amount is tiny, and JavaScript has garbage collection which clears up the stale memory.

filter

const fruits = ['apple', 'banana', 'citrus'];
const containsA = fruits.filter(fruit => fruit.includes('a'));
// Output: ['apple', 'banana'];

The filter method takes in a special function called the "predicate". A predicate is a function that always returns only a boolean. It tests each element in the array. If it returns true, the element is included in the resulting array.

filter also returns a new array aka. it's immutable.

reduce

The reduce method in JavaScript processes an array to produce a single output value. It takes a reducer function and an optional initial value. The reducer function itself accepts two parameters: an accumulator (which holds the accumulated result) and the currentValue from the array. The reduce method is also immutable.

Here is an example where you can use reduce on an array of numbers from 1 to 4, summing them together.

const numbers = [1, 2, 3, 4];

const sumReducer = (accumulator, currentValue) => accumulator +
currentValue;

const total = numbers.reduce(sumReducer, 0); console.log(total); //
Output: 10

In this example, reduce is called on the numbers array. The sumReducer function is used to add each number to a running total, starting from 0. Here's what happens at each step:

Details of the Process:

Step 1: The accumulator starts at 0 (the initial value). The current value is the first element of the array, which is 1. They are added together to make the new accumulator value 1.
Step 2: The accumulator is now 1. The current value is the next element in the array, 2. Adding these gives 3.
Step 3: The accumulator is now 3, and the current value is 3. Adding these gives 6.
Step 4: The accumulator is now 6, and the current value is the last element, 4. Adding these gives the final result of 10.

At the end of the process, the reduce method returns 10, which is the sum of all elements in the array. This demonstrates how reduce can be used to transform an array into a single value through repeated application of a function.

reduce is the most powerful method because you can implement map and filter with reduce, but neither filter nor reduce with map and neither map or reduce with filter.

You can implement map with reduce like this:

const mapUsingReduce = (array, mapFunction) =>
 array.reduce(
 (accumulator, current) => [...accumulator, mapFunction(current)],
 [],
 );
 
const numbers = [1, 2, 3, 4];

const doubled = mapUsingReduce(numbers, x => x * 2);
console.log(doubled); // Output: [2, 4, 6, 8]

You can implement filter with reduce like this:

const filterUsingReduce = (array, filterFunction) =>
 array.reduce(
 (accumulator, current) =>
 filterFunction(current) ? [...accumulator, current] : accumulator,
 [],
 );
 
const numbers = [1, 2, 3, 4];

Expressions over Statements

In functional programming, you’ll see many expressions and few statements. Expressions avoid intermediate variables, while statements often bring side-effects and mutable state.

Statements

Imperative code frequently utilizes statements. A statement is a piece of code that performs an action.

Loops — for, while, etc.

// Loops:
// A for loop that logs numbers 0 to 4.
for (let i = 0; i < 5; i++) {
 console.log(i);
}
// A while loop that decrements x and logs it until x is no longer greater
than 0.
while (x > 0) {
 x--;
 console.log(x);
}

Control flow — if, switch, etc.

// An if...else statement that logs if x is positive or not.
if (x > 0) {
 console.log("x is positive");
} else {
 console.log("x is zero or negative"); 
}
// A switch statement that handles different color cases.
switch (color) {
 case "red":
 console.log("Color is red");
 break;
 case "blue":
 console.log("Color is blue");
 break;
 default:
 console.log("Color is not red or blue");
}

Error handling — try...catch, throw, etc.

// A try...catch block that handles errors from riskyFunction.
try {
 let result = riskyFunction();
} catch (error) {
 console.error(error);
}
throw new Error("Something went wrong"); // Throws a new error with a
message.

Except for functions, if it’s a keyword with curly braces, you’re likely dealing with a statement. (❗)

Expressions

Declarative code favors expressions. An expression evaluates to a value.

Literal expressions

42; // The number 42 is a literal expression.
"Hello"; // The string "Hello" is a literal expression.

Arithmetic expressions

5 + 3; // Evaluates to 8.
x * y; // Evaluates to the product of x and y.

Logical expressions

true && false; // Evaluates to false.
x || y; // Evaluates to x if x is true, otherwise y.

Function expressions

const funcExpr = function() { return 42; }; // Defines a function
expression.
const arrowFunc = () => 42; // Defines an arrow function expression.

Object and array initializers

{ name: "John", age: 30 }; // Object initializer expression.
[1, 2, 3]; // Array initializer expression.

Property access expressions

obj.name; // Accesses the "name" property of obj.
array[0]; // Accesses the first element of array.

Function calls

square(7); // Evaluates to 49.
Math.max(4, 3, 2); // Evaluates to 4.

Function composition

You’re about to unlock a new understanding of code and gain superpowers, so “lock-in”.

“All software development is composition: The act of breaking a complex problem down to smaller parts, and then composing those smaller solutions together to form your application.” — Eric Elliot

Whenever you use functions together, you’re “composing” them.

const increment = n => n + 1;
const double = n => n * 2;
function doubleInc(n) {
 const doubled = double(n);
 const incremented = increment(doubled);
 return incremented;
}

doubleInc(5); // 11

But with anything in life, you can do it better if you do it consciously. The code above is actually NOT the ideal way to write it because:

The more code you write, the higher the surface area for bugs to hide in.

less code = less surface area for bugs = less bugs

The obvious exception is clear naming and documentation. It’s fine if you give a function a longer name and supply doc strings to make it easier for your readers to understand your code.

You can reduce the surface area for bugs by avoiding the capturing of the intermediary results in variables.

const increment = n => n + 1;
const double = n => n * 2;

const doubleInc = n => inc(double(n));
doubleInc(5); // 11

In mathematics, function composition is taking two functions f and g and applying one function to the result of another function: h(x) = (f ∘ g)(x) = f(g(x)). Note: The hollow dot ∘ is called the composition operator.

In mathematical notation, if you have two functions f and g, and their composition is written as (f ∘ g)(x), this means you first apply g to x and then apply f to the result of g(x). For your example, f(n) = n1 and g(n) = 2n, the composition h(n) = f(g(n)) calculates 2n + 1.

Note: Generally mathematicians use x (or y or z etc.) to represent any variable, but in the code example above n is used to subtly hint at the parameter to be a number. The different name has no impact on the result.

You can abstract away the composition operator ∘ into a function called compose2 which takes two functions and composes them in mathematical order.

const compose2 = (f, g) => x => f(g(x)); // ∘ operator

const increment = n => n + 1; // f(n)
const double = n => n * 2; // g(n)

const doubleInc = compose2(increment, double); // h(n)
doubleInc(5); // 11

compose2 only works for two functions at a time.

But get ready, because this is where it gets powerful.

If you want to compose an arbitrary amount of functions, you can write a generalized compose.

const compose = (...fns) => x => fns.reduceRight((y, f) => f(y), x);
// reduceRight works like reduce, but iterates the array from
// the last item to the first item.

const increment = n => n + 1;
const double = n => n * 2;
const square = n => n * n;

const incDoubleSquare = compose(square, double, increment);
incDoubleSquare(3); // 64

The compose function here is written using the mathematical variable names. If you want to take the names that you might be used to from reduce, then you'd write it like this:

const compose =
 (...functions) =>
 initialValue =>
 functions.reduceRight(
 (accumulator, currentFunction) => currentFunction(accumulator),
 initialValue,
 );
 
const increment = n => n + 1;
const double = n => n * 2;
const square = n => n * n;

const incDoubleSquare = compose(square, double, increment);
incDoubleSquare(3); // 64

compose takes multiple functions as its arguments, and collects them into an array fns via the rest syntax.

It then returns a child function that takes in the initialValue x and returns the array fns with the reduceRight method applied to it. The reduceRight method then takes in a callback function and the initialValue x.

That callback function is the heart of compose. It takes in the accumulator y (starting from x) and the currentValue f, which is a function from the array fns. It then returns that function f - called with the accumulator y.

The result of that function call, then becomes the accumulator y for the next iteration. Here the next function f from fns get called with that new accumulator value. This repeats until the initialValue x has been passed and transformed through all functions from the array fns.

Many people who are used to reading texts from left to right find it unintuitive to compose functions in mathematical order. Many functional programming packages provide another function called commonly pipe, which composes function from left to right in reverse mathematical order.

const pipe = (...fns) => x => fns.reduce((y, f) => f(y), x);

const increment = n => n + 1;
const double = n => n * 2;
const square = n => n * n;

const incDoubleSquare = pipe(increment, double, square);
incDoubleSquare(3); // 64

trace

You might be asking right now. “But way, what if you want to debug your code? Then you need to capture the intermediate results in variables, right?”

You actually do not. You only need a helper higher-order function called trace.

const trace = msg => x => {
 console.log(msg, x);
 return x;
}

And here is how you can use it.

const pipe = (...fns) => x => fns.reduce((y, f) => f(y), x);
const trace = msg => x => {
 console.log(msg, x);
 return x;
}

const increment = n => n + 1;
const double = n => n * 2;
const square = n => n * n;

const incDoubleSquare = pipe(
 increment,
 trace('before double'),
 double,
 trace('after double'),
 square
);
incDoubleSquare(3); // 64
// Also logs out:
// before double 4
// after double 8

Currying

You saw another technique being used called currying.

Currying is a transformation of functions that translates a function from callable as f(a, b, c) into callable as f(a)(b)(c). In other words, a function is curried if it can take in each of it's parameters one at a time.

function addUncurried(a, b) {
 return a + b;
}

function addCurried(a) {
 return function(b) {
 return a + b;
 }
}

addUncurried(41, 1); // 42
addCurried(41)(1); // 42

With arrow functions, these definitions can become one-liners by leveraging their implicit returns.

const addUncurried = (a, b) => a + b;

const addCurried = a => b => a + b;

addUncurried(41, 1); // 42
addCurried(41)(1); // 42

Here a addCurried is a function that takes in a number a and returns a function b => a + b. You can read it like this:

const addCurried = (a => (b => a + b));

You can curry any function. For example, you can create custom map and reduce functions.

const map = fn => arr => arr.map(fn);
const reduce = fn => x => arr => arr.reduce(fn, x);

Map takes in two parameters and reduce takes in three. The number of parameters a function expects in its definition is called arity.

There are shorthand terms for functions that take in 1, 2 and 3 parameters.

Unary function: Takes one argument, e.g. square.
Binary function: Takes two arguments, e.g. map.
Ternary function: Takes three arguments, e.g. reduce.

In the context of currying, understanding arity is important because each step in a curried function reduces the arity by one until all expected arguments have been received and the final operation can be performed.

Additionally, the first function of a composition can have any arity, but ever following function needs to be unary.

const add3 = (a, b, c) => a + b + ; // Ternary
const double = n => n * 2; // Unary

const addThenDouble = pipe(add3, double);
addThenDouble(6, 7, 8); // 42

Exercise: create your own custom filter function that is curried and takes in a predicate pred and then an array arr and then filters the array based on the predicate.

Wouldn’t it be nice if you had a function that can curry any function?

const addUncurried = (a, b) => a + b;

const curry = /* ... magic? ... */

const addCurried = curry(addUncurried);

Well there it is.

const addUncurried = (a, b) => a + b;

const curry = (f, array = []) =>
 (...args) =>
 (a => (a.length >= f.length ? f(...a) : curry(f, a)))([
 ...array,
 ...args,
 ]);

// NOTE: because of f.length, this implementation of `curry` fails with
// functions that use default parameters.
const addCurried = curry(addUncurried);

const increment = addCurried(1);
increment(4); // 5
addCurried(1, 4); // 5
addCurried(1)(4); // 5

The previous example used the mathematical names for the variables .If you want to name the variables more descriptively to understand curry now, you can write the function like this:

const curry =
 (targetFunction, collectedArguments = []) =>
 (...currentArguments) =>
 (allArguments =>
 allArguments.length >= targetFunction.length
 ? targetFunction(...allArguments)
 : curry(targetFunction, allArguments))([
 ...collectedArguments,
 ...currentArguments,
 ]);

curry uses recursion, which is when a function calls itself for the purpose of iteration. Let's break it down:

f or targetFunction: The original function you want to curry.
array or collectedArguments: An array to collect the arguments of all currying calls. Each cycle (except for the last) new arguments get added.
args or currentArguments: An array of the arguments taken in with the current invocation of the curried function (in this case: addCurried).
a or allArguments: An array of arguments concatenated from the currentArguments and the collectedArguments from the previous calls.

When we call addCurried with one or more arguments, these current arguments get taken in as args in the child function of curry. This child function returns another function (grand-child function of curry).

The grand-child function immediately invokes itself with an array concatenated from the collected arguments array and the current arguments args, receiving these values from its grand-parent and parent closure. It takes this new array as the all arguments a and checks if the all arguments a contains the same or higher amount of arguments as the target function f is declared with.

If yes, this means all necessary currying calls have been performed: It returns a final call of the target function f invoked with the all arguments a. If not, it recursively invokes curry once again with the target function f and the new all arguments a, which then get taken in as the new collected arguments array. This repeats until the a.length condition is met.

Side notes:

During the first call, the all arguments a and the current arguments args are the same value, as the collected arguments array has nothing added to it yet.
The grand-child function’s immediate invocation happens before its parent function completes.

Partial Application

As you learned earlier, an application happens when the arguments are used to replace the function’s parameters. This allows the function to perform its task using the provided arguments.

const add = (a, b) => a + b;
const inc = n => add(1, n);

A partial application is the process of applying a function to some, but not all, of its arguments. This creates a new function, which you can store in a variable for later use. The new function needs fewer arguments to execute because it only takes the remaining parameters as arguments.

Partial applications are useful for specialization when you want to reuse a function with common parameters.

const add = a => b => a + b;
const inc = add(1); // point-free
const incPointed = n => add(1)(n); // pointed

Point-Free Style inc is defined in point-free style, which is when you write a function without mentioning the parameters.

inc uses closure because the argument 1 is captured in the closure of add as a. There are two requirements for your code to be composable: "data last" and the data needs to line up.

Data First vs. Data Last

“data last” means the data your functions operate on should be their last parameter. For the add and multiply functions you saw earlier the order of arguments is irrelevant because they are commutative.

const add = a => b => a + b;
const otherAdd = b => a => a + b;

const a = 41;
const b = 1;
console.log(add(41, 1) === otherAdd(41, 1)); // true

But division is NOT, so you’re going to learn the importance of the “data last” principle using a divide function.

const divideDataLast = (y) => (x) => x / y;
const divideDataFirst = (x) => (y) => x / y;

Let’s say you want to specialize and create a halve function that takes in a number and divides it by two.

Using the “data first” function, it’s impossible for you to define a halve function in point-free style.

const divideDataLast = (y) => (x) => x / y;

const divideDataFirst = (x) => (y) => x / y;

const halve = divideDataLast(2);
// const halveFail = divideDataFirst(2); 🚫 fails
const halvePointed = (n) => divideDataFirst(n)(2);

halfFail captures 2 in the closure of divideDataFirst. It is a function that takes in a number and when called divides 2 by that supplied number.

In general, you need to write your functions using the “data last” principle to enable partial application.

BTW, the best library for functional programming in the “data last” paradigm is Ramda. Here is an outlook what you can do with Ramda. You can understand this in-depth some time in the future.

import { assoc, curry, keys, length, pipe, reduce, values } from 'ramda';

const size = pipe(values, length);

size({ name: 'Bob', age: 42 }); // 2
size(['a', 'b', 'c', 'd']); // 4

const renameKeys = curry((keyReplacements, object) =>
 reduce(
 (accumulator, key) =>
 assoc(keyReplacements[key] || key, object[key], accumulator),
 {},
 keys(object),
 ),
);

const input = { firstName: 'Elisia', age: 22, type: 'human' };
const keyReplacements = { firstName: 'name', type: 'kind', foo: 'bar' };

renameKeys(keyReplacements)(input);
// Output: { name: 'Elisia', age: 22, kind: 'human' }

size is a function that can take in objects or arrays and returns how many properties or elements it has.

Remember, functional programming is meant to improve your code by making it more bug-free, modular, testable, refactorable, understandable and deterministic. So, if you mix imperative and declarative code, like in the definition for renameKeys that is totally fine. Relax if you need some time to understand implementations like this. As you play around with this new paradigm, go with what's easiest for you to write. There is no need to force functional programming.

You can call renameKeys with keyReplacements and an input to return a new object with it's keys renamed according to the keyReplacements.

Data Needs to Line Up

Similarly, only with “data last” can you compose functions effectively because the types of the arguments and return values of functions have to line up to compose them. For example, you can’t compose a function that accepts an object and returns a string with a function that receives an array and returns a number.

// (number, number) => number[]
const echo = (value, times) => Array(times).fill(value);
// number[] => number[]
const doubleMap = array => array.map(x => x * 2);

Mozart

Now it’s your turn. Try the following exercise to practice what you’ve learned from this article. If you get stuck, you can always scroll up and read it again. If you prefer not to do the exercise, just read the solution and follow along.

Create a function that takes in an array of numbers and filters all the even numbers (so it rejects the odd numbers), then doubles all the even numbers and lastly, sums up the result. Break down your functions to their most basic abstractions then compose them point-free. (Hint: You’ll need to look up the modulo operator % to check if a number is even.)

const curry =
 (f, array = []) =>
 (...args) =>
 (a => (a.length >= f.length ? f(...a) : curry(f, a)))([
 ...array,
 ...args,
 ]);
 
const add = curry((a, b) => a + b);
const multiply = a => b => a * b;

Lastly, is this more complicated than simply writing the following?

const mozart = numbers =>
 numbers
 .filter(n => n % 2 === 0)
 .map(n => n * 2)
 .reduce((a, b) => a + b, 0);
mozart([1, 2, 3, 4, 5]); // 12

Yes, absolutely! You should always use the simplest implementation for your requirements, also known as KISS (Keep It Simple, Stupid), or YAGNI (You Ain’t Going To Need It).

Functional programming shines as your app grows and you need to generalize and specialize your code so it scales well and stays maintainable. This way your code is more modular, and way easier to test, to reuse and to refactor. Future articles will show you real-world examples how to use these techniques.

You now know the 20% of functional programming that gives you 80% of the result.

JavaScript Generators Explained, But On A Senior-Level

Jan Hesters — Mon, 07 Oct 2024 19:11:55 GMT

Generators are powerful and underused by JavaScript developers. And many tutorials on generators only scratch the surface. In this article, you’re going to go deep and you’ll develop an advanced understanding of the theory behind generators.

But first, do you want to see this tutorial in action? Here’s the video version.

https://medium.com/media/bfc9523d0c24b55d45f8d687e1492d7d/href

Generators are most commonly seen in sagas, but there are more use cases for them. You’re going to see some of them in this article.

The short answer to the question “What is a generator?” is:

Generators are pull streams in JavaScript.

Let’s dissect this definition and then jump into some examples.

First, you need to understand two terms: “pull” and “stream”.

What is a stream?

A stream is data over time. There are two types of streams: push streams and pull streams.

What is a push stream?

A push stream is a mechanism where you are NOT in control WHEN the data comes through.

Examples for pull streams include:

a websocket,
reading a file from disk, and
server-sent events.

You can see a JavaScript example of a push stream using Node.js to read a large file from disk below.

const fs = require('fs');
const readStream = fs.createReadStream('./largeFile.txt');

readStream.on('data', chunk => {
  console.log('data received', chunk.length)
});

readStream.on('end', () => {
  console.log('finished reading file');
});

readStream.on('error', error => {
  console.log('an error occured while reading the file', error);
});

What is a pull stream?

A pull stream is when you ARE in control WHEN you want to request the data.

You will see code examples for pull streams in JavaScript soon when you’re going to see generator code, but first you need to understand another concept.

Lazy vs. eager

In programming, data can be processed in two fundamental ways: eagerly or lazily.

Eager

Eager means data is evaluated immediately, regardless of whether the result is needed in that moment. A push stream is eager. (Other examples: array methods, promises)

// Eager evaluation with array methods:
const numbers = [1, 2, 3, 4, 5];

// Map immediately processes all elements in the array.
const squares = numbers.map(num => {
    console.log(`Squaring ${num}`);
    return num * num;
});

console.log('squares:', squares); // [1, 4, 9, 16, 25]

You might be thinking: “Okay, but why are promises eager? Their result comes in late.”

Promises in JavaScript exhibit eager evaluation for several reasons.

Immediate Execution: The function passed to a new promise (known as the executor function) is executed immediately when the Promise is constructed.
Irreversible Operations: Once the executor function begins executing, it cannot be stopped or paused by the consuming code. The results of the operation it performs (either resolution or rejection) will be queued in the JavaScript event loop to be handled as soon as possible.
No Lazy Option: A promise lacks any built-in mechanism to defer or cancel the execution of its executor until a value is needed.
Side Effects: The eager nature of promises means that any side effects included in the executor (like API calls, timeouts, or I/O operations) will happen immediately as part of the promise creation.

The following example demonstrates how demonstrates how promises are executed immediately.

// Eager evaluation with promises and array methods

console.log("Before promise");

let promise = new Promise((resolve, reject) => {
    console.log("Inside promise executor");
    resolve("Resolved data");
});

console.log("After promise");

promise.then(result => {
    console.log(result);
});

This results in the following output.

$ node eager-promise-example.js
Before promise
Inside promise executor
After promise
Resolved data

Lazy

Lazy means only evaluated when the value is needed (not before). A pull stream is lazy.

A synchronous example would be the operand selector operators.

// Lazy evaluation with logical operators

function processData(data) {
    console.log(`Processing ${data}`); // This never logs out 🚫
    return data * data;
}

console.log('Lazy evaluation starts');
const data = 5;
const isDataProcessed = false;

// Lazy evaluation using the logical AND operator.
const result = isDataProcessed && processData(data);
console.log('Result:', result); // false

When you run this code, you’ll observe the following output.

$ node lazy-evaluation-example.js
Lazy evaluation starts
Result: false

Since isDataProcessed is false, the processData function never runs and you never see "Processing 5" in the console. This shows that the expression only evaluates what is needed to get the result.

What is a generator?

A generator is a pull stream in JavaScript. This means its a special kind of function where you can pause execution and resume it later.

The Generator object is returned by a generator function and it conforms to both the iterable protocol and the iterator protocol.

function* myGenerator() {
  yield "Hire senior";
  yield "React engineers";
  yield "at ReactSquad.io";
}

const iterator = myGenerator();

// Using the generator as an iterator.
console.log(iterator.next()); // { done: false, value: "Hire senior" }
console.log(iterator.next()); // { done: false, value: "React engineers" }
console.log(iterator.next()); // { done: false, value: "at ReactSquad.io" }
console.log(iterator.next()); // { done: true, value: undefined }

// Using the generator as an iterable.
for (let string of myGenerator()) {
  console.log(number); // "Hire senior" "React engineers" "at ReactSquad.io"
}

Apart from the .next() method, generators also have .return() and .throw().

.return() - The .return() method terminates the generator's execution and returns the specified value, also triggering any finally blocks.
.throw() - The .throw() method allows you to throw an error inside the generator at the point of the last yield, which can be caught and handled or allow the generator to clean up through a finally block. If uncaught, it stops the generator and marks it as done.

function* numberGenerator() {
  try {
    yield 1;
    yield 2;
    yield 3;
  } finally {
    console.log("Cleanup complete");
  }
}

const generator = numberGenerator();

// Using the generator normally.
console.log(generator.next()); // { done: false, value: 1 }
console.log(generator.next()); // { done: false, value: 2 }

// Using return() to finish the generator early.
console.log(generator.return(10)); // { done: true, value: 10 }
// After return(), no more values are yielded.
console.log(generator.next()); // { done: true, value: undefined }

// Resetting the generator for throw example.
const newGenerator = numberGenerator();
console.log(newGenerator.next()); // { done: false, value: 1 }

// Using throw() to signal an error.
try {
  newGenerator.throw(new Error("Something went wrong"));
} catch (e) {
  console.log(e.message); // "Something went wrong"
}
// After throw(), the generator is closed.
console.log(newGenerator.next()); // { done: true, value: undefined }

You can also pass in numbers or any other value to generators when you call next() with an argument.

Try to predict what will log out and when in the following example.

function* moreNumbers(x) {
    console.log('x', x);
    const y = yield x + 2;
    console.log('y', y);
    const z = yield x + y;
    console.log('z', z);
}

const it2 = moreNumbers(40);

console.log(it2.next());
console.log(it2.next(2012));
console.log(it2.next());

This example demonstrates how the generator function moreNumbers manipulates and yields values based on the input it receives during the sequence of .next() calls.

Take look at the output and check your prediction.

const it2 = moreNumbers(40);

// x: 40
console.log(it2.next()); // { value: 42, done: false }

// y: 2012
console.log(it2.next(2012)); // { value: 2052, done: false }

// z: undefined
console.log(it2.next()); // { value: undefined, done: true }

Let’s breakdown of each step of the moreNumbers generator function, so you understand it fully.

Use Cases for Generators

There are three main uses cases for generators.

Lazy evaluation — generate data on demand or process large or infinite data sets.
Asynchronous programming — handle asynchronous operations.
Iterators — allowing to stop in between steps for complex flows.

Earlier, you saw an example of reading a file from disk as a push stream. Below is how you would write the data reading using a generator to turn it into a pull stream.

const fs = require('fs');

function getChunkFromStream(stream) {
    return new Promise((resolve, reject) => {
        stream.once('data', (chunk) => {
            stream.pause();
            resolve(chunk);
        });

        stream.once('end', () => {
            resolve(null);
        });

        stream.once('error', (err) => {
            reject(err);
        });

        stream.resume();
    });
}

async function* readFileChunkByChunk(filePath) {
    const stream = fs.createReadStream(filePath);
    let chunk;

    while (chunk = await getChunkFromStream(stream)) {
        yield chunk;
    }
}

const generator = readFileChunkByChunk('./largeFile.txt');

(async () => {
    for await (const chunk of generator) {
        console.log("data received", chunk.length);
    }
})();

Real-World Examples

Sagas are a prime example of handling asynchronous I/O operations. But you’re going to learn how to use sagas in a future article, in a series of articles on Redux.

And then generally you use generators when you want to be in control WHEN to get a value.

Take a look at this test example.

test('given an onboarded owner user: shows the invite link creation UI as well as the members of the organization, and lets the user change their role', async ({ page }) => {
  // Generator for roles in the organization.
  function* roleGenerator() {
    const allRoles = Object.values(ORGANIZATION_MEMBERSHIP_ROLES);
    for (const role of allRoles) {
      yield role;
    }
  }
  const roleIterator = roleGenerator();
  const data = await setup({
    page,
    role: ORGANIZATION_MEMBERSHIP_ROLES.OWNER,
    numberOfOtherTeamMembers: allRoles.length,
  });
  const { organization, sortedUsers, user } = data;

  // Navigate to team members settings page.
  await page.goto(`/organizations/${organization.slug}/settings/team-members`);

  // Loop through each team member to assign roles using the generator.
  for (let index = 0; index < sortedUsers.length; index++) {
    const memberListItem = page.getByRole('list', { name: /team members/i }).getByRole('listitem').nth(index);
    const otherUser = sortedUsers[index];

    // Change role for each team member, except the current user.
    if (otherUser.id !== user.id) {
      await memberListItem.getByRole('button', { name: /member/i }).click();
      const role = roleIterator.next().value!;
      await page.getByRole('option', { name: role }).getByRole('button').click();
      await page.keyboard.press('Escape');
    }
  }

  await teardown(data);
});

In this test, you define a roleGenerator to sequentially provide a list of roles for users within an organization. This approach allows the test to dynamically assign each user a unique role from a predefined list as part of a role management feature in a UI.

The reason a generator — as opposed to an array — was used for this example is that the position of the main user in the test is unknown in the sortedUsers array and since a generator is a pull stream you can get the role values on demand.

‍

If you loved this, then you’ll love my YouTube channel. Check it out here!

12 Keys to Write Senior-Level Tests (Test Desiderata in JavaScript)

Jan Hesters — Fri, 04 Oct 2024 15:24:26 GMT

“Desiderata” is derived from the Latin word for “things desired.”

Kent Beck wrote an article called “Test Desiderata”. And together with Kelly Sutton, they created a YouTube playlist about that article that explains the desirable properties of automated tests. Some of these properties are trade-offs and not every test needs to have them.

The examples Kent and Kelly give are in Ruby. Consider this article and video a TL;DW with some additions and a translation into JavaScript.

https://medium.com/media/8d50b78e441c1049f14cc4498c45220a/href

The examples in this tutorial use RITEway because of its genius API that forces you to write good tests. It also uses Jest once, where RITEway prohibits you from writing bad tests. You should really watch Ken’s and Kelly’s playlist in addition to reading this article — even if you, like me, don’t know Ruby. Their explanations are fun and enlightening.

Obviously you should also learn Jest and Vitest because they are popular testing frameworks that every fullstack JavaScript developer should know. But that’s a topic for another article.

Let’s dive into the principles.

Behavioral-Sensitive

Tests should be sensitive to the behavior of your code.

const calculateSF = (hours, rate) => hours * Math.max(rate, 15);

const calculate = (hours, rate, zipCode = null) => {
  if (zipCode === '94103') {
    return calculateSF(hours, rate);
  } else {
    return hours * rate;
  }
};

describe('calculate', async assert => {
  const hours = 40;

  {
    const rate = 8;

    assert({
      given: 'your hours and your rate',
      should: 'return the total hourly wage',
      actual: calculate(hours, rate),
      expected: 320,
    });
  }

  {
    const rate = 14;
    const zipCode = '94103';

    assert({
      given:
        'your hours, your rate below $15 and your zip code is in San Francisco',
      should:
        'return the total hourly wage calculated with the minimum wage of $15',
      actual: calculate(hours, rate, zipCode),
      expected: 600,
    });
  }

  {
    const rate = 16;
    const zipCode = '94103';

    assert({
      given:
        'your hours, your rate above $15 and your zip code is in San Francisco',
      should:
        'return the total hourly wage calculated with your actual rate',
      actual: calculate(hours, rate, zipCode),
      expected: 640,
    });
  }
});

If you change the behavior of the code, the results of the tests should change, too. If you change the minimum wage in calculateSF to 150 dollars, the tests for the San Francisco zip code fail.

Structure-Insensitive

Tests should be insensitive to the internals of your code’s structure.

RITEway makes it nearly impossible to write structure sensitive tests because there is no mocking API like mock functions, spies or module mocks.

So the next example uses Jest to write structure-sensitive code by using spyOn. You need to create an hourlyWageCalculator object to be able to use spyOn.

const hourlyWageCalculator = {
  calculateSF(hours, rate) {
    return hours * Math.max(rate, 15);
  },
  calculate(hours, rate, zipCode = null) {
    if (zipCode === '94103') {
      return this.calculateSF(hours, rate);
    } else {
      return hours * rate;
    }
  },
};

describe('calculate', () => {
  const hours = 40;

  describe('given your hours, your rate below $15 and your zip code in San Francisco', () => {
    it('should return the total hourly wage calculated with the minimum wage of $15', () => {
      const rate = 14;
      const zipCode = '94103';
      const spy = jest.spyOn(hourlyWageCalculator, 'calculateSF');

      hourlyWageCalculator.calculate(rate, hours, zipCode);

      expect(spy).toHaveBeenCalledWith(rate, hours);

      spy.mockRestore();
    });
  });

  describe('given your hours, your rate above $15 and your zip code in San Francisco', () => {
    it('should return the total hourly wage calculated with your actual rate', () => {
      const rate = 16;
      const zipCode = '94103';
      const spy = jest.spyOn(hourlyWageCalculator, 'calculateSF');

      hourlyWageCalculator.calculate(rate, hours, zipCode);

      expect(spy).toHaveBeenCalledWith(rate, hours);

      spy.mockRestore();
    });
  });
});

Here we made the assumption that calculateSF exists and that we are using it. If we refactor the code to inline the San Francisco calculation, the tests fail because they are structure sensitive.

const hourlyWageCalculator = {
  calculate(hours, rate, zipCode = null) {
    if (zipCode === '94103') {
      return hours * Math.max(rate, 15);
    } else {
      return hours * rate;
    }
  },
};

If you refactor code without changing its behavior, the test results should stay the same. The RITEway tests from the behavior section above are invariant to the structure of the code. You might now this property as “avoid testing implementation details”.

Readable

“Tests, like code, are read more than written.” — Kent Beck

Some things that make code more readable actually reduce the readability of tests.

const defaultHours = 40;

describe('calculate', async assert => {
  const hours = defaultHours;

You might see how most people work 40 hours per week and therefore create a defaultHours constant and re-use it in your test setups. But, drying up your tests often makes them less readable.

Avoid writing a test that is a few lines, but incomprehensible and impossible to understand without reading a lot of other lines of shared setup code.

“You’re not supposed to repeat yourself, unless you’re supposed to repeat yourself.” — Kent Beck

Tests should be self-contained and therefore tests can be verbose. The reader must be able to extract the motivation for the test and what happens in the test.

(Obviously, there are trade-offs and there are occasions where you want to generalize your tests setup.)

Writable

Tests should be easy to write. If the tests for your code are hard to write, it indicates your code has a bad API, is too tightly coupled or you lack good setup functions.

const calculate = employee => employee.weeklyHours * employee.hourlyRate;

const createEmployee = ({
  firstName = '',
  lastName = '',
  address = '',
  weeklyHours = 0,
  hourlyRate = 0,
}) => ({
  firstName,
  lastName,
  address,
  weeklyHours,
  hourlyRate,
});

describe('calculate', async assert => {
  {
    const employee = createEmployee({
      firstName: 'Kent',
      lastName: 'Beck',
      address: '1 Main St., Berkeley, CA, 94701',
      weeklyHours: 40,
      hourlyRate: 8,
    });

    assert({
      given: 'an employee',
      should: 'calculate the total hourly wages',
      actual: calculate(employee),
      expected: 320,
    });
  }

  {
    const employee = createEmployee({
      firstName: 'Kelly',
      lastName: 'Sutton',
      address: '1 Main St., San Francisco, CA, 94103',
      weeklyHours: 40,
      hourlyRate: 7,
    });

    assert({
      given: 'an employee',
      should: 'calculate the total hourly wages',
      actual: calculate(employee),
      expected: 280,
    });
  }
});

In these tests, firstName, lastName and address could be deleted and are irrelevant for calculate. Its the fault of the system that the tests are expensive relative to the code under test.

If you need dozens or hundreds of lines of test setup to test a few lines of code, that’s a design problem, not a test problem. For example, your tests might use a lot of mocks because your code is too tightly coupled and has many side-effects.

“If you’re unable to test it, you designed it wrong.” — Kent Beck

Fast

Tests should run quickly.

On average it takes your brain 23 minutes to re-focus on a task after it gets distracted. And those distractions can happen within seconds. Good tests help you stay in flow because they run fast.

const delay = seconds =>
  new Promise(resolve => {
    setTimeout(() => {
      resolve();
    }, seconds * 1000);
  });

Add this delay function before each assert in the tests.

await delay(5);

assert({
  given: // ...

Now run your tests and see how you feel. Watch how your mind drifts off while you wait for those tests to finish …

You can run your unit tests in under a second by isolating side-effects and composing your code from pure functions. Your CI / CD pipeline (including your integration and functional tests) should run in under 10 minutes.

Avoid interrupting flow to keep your engineering team productive.

Automated

Machines should do the testing, not humans.

Avoid Q&A teams having to manually test your release candidates for regressions. This is what automated tests are for.

The benefits of automated tests compound. Initially, it might be faster and cheaper to click through your app and writing the test takes longer.

However as your app grows, not investing into automated tests causes compounding debt.

It gets harder to add tests.
Manually going through your program’s flow takes longer than a machine clicking through it.
Machines have better memory than humans. Once a test is written, the machine doesn’t forget the test case and prevents regressions.
You pay a computer less per hour than an engineer.
While the automation (CI / CD pipeline) runs, you can work on new features.

Automated tests guarantee program correctness (- when your tests are good).

Isolated

Isolated tests can run in any order and in parallel. Whether one test passes or not should have no effect on whether another test passes. To achieve this, the state needs to be the same before and after each test.

let numberOfCalculations = 0;
const calculate = (hours, rate) => ++numberOfCalculations * hours * rate;

describe('calculate', async assert => {
  const hours = 40;

  {
    const rate = 8;

    assert({
      given: 'your hours and your rate',
      should: 'return the total hourly wage',
      actual: calculate(hours, rate),
      expected: 320,
    });
  }

  {
    const rate = 10;

    assert({
      given: 'your hours and your rate',
      should: 'return the total hourly wage',
      actual: calculate(hours, rate),
      expected: 560,
    });
  }
});

If you change the order of the tests, they both fail, even though the code is the same. If the code was right before, the tests should still pass and if it was wrong before, the tests should still fail.

In these tests the order matters because they both share mutable state. Tests should have no shared state and they should be isolated from their environment (e.g. DOM, database, scope etc.).

The tests depending on the order they run in points to a flaw in the code’s design. Prefer to write code where you initialize the state locally (in the scope of the test). If your code is correct and must change the state, you should restore the initial state after each test.

Composable

“The confidence provided by one test should combine with the confidence provided by other tests.” — Kent Beck

const inc = n => n + 1;
const double = n => n * 2;
const incDouble = n => double(inc(n));

describe('inc', async assert => {
  assert({
    given: 'a number',
    should: 'increment it by 1',
    actual: inc(41),
    expected: 42,
  });
});

describe('double', async assert => {
  assert({
    given: 'a number',
    should: 'return the number doubled',
    actual: double(21),
    expected: 42,
  });
});

describe('incDouble', async assert => {
  assert({
    given: 'a number',
    should: 'increment it by 1 and double the result',
    actual: incDouble(20),
    expected: 42,
  });
});

We ensure the correctness of inc and double and then ensure the correctness of the composed function incDouble. The calculation of inc is isolated from double and vice versa and both are isolated from incDouble.

To make your tests composable, your code needs to be composable, too.

Specific

A failing test should point you to the cause of failure.

If you break incDouble by changing the order in the function composition, your test points you to the failure.

const incDouble = n => inc(double(n)); // 🚫

incDouble
  ✖  Given a number: should increment it by 1 and double the result
  ------------------------------------------------------------------
      operator: deepEqual
      diff: "42" => "41"
      source: ...

The stack trace (given by RITEway in the source key) tells us exactly which test failed and therefore which component broke.

If you restore incDouble and break inc by having it add 2 to your number, two tests break.

const inc = n => n + 2; // 🚫

inc
  ✖  Given a number: should increment it by 1
  --------------------------------------------
      operator: deepEqual
      diff: "42" => "43"
      source: ...

double
  ✔  Given a number: should return the number doubled

incDouble
  ✖  Given a number: should increment it by 1 and double the result
  ------------------------------------------------------------------
      operator: deepEqual
      diff: "42" => "44"
      source: ...

Using the stack trace you can find the test that points you to the cause of both errors. When you encounter multiple errors in your stack, the leafs are likely the source of the error.

Deterministic

Given the same code, tests should produce the same results.

A few years ago, I helped with a project that had a flaky test.

const slice = 'userAuthentication';

const getExpirationDate = ({ [slice]: { expirationDate } }) => expirationDate;
const THIRTY_MINUTES = 30 * 60 * 1000;

const getShouldUpdateToken = state => {
  const now = new Date().getTime();
  const expirationDate = getExpirationDate(state);
  return now > expirationDate - THIRTY_MINUTES;
};

describe('user authentication reducer', async assert => {
  // ... more tests

  {
    const now = new Date().getTime();
    const state = { auth: { expirationDate: now + THIRTY_MINUTES } };

    assert({
      given:
        'an expiration date 30 minutes into the future and a get should update token selector',
      should: 'return false',
      actual: getShouldUpdateToken(state),
      expected: false,
    });
  }

  // ... more tests
});

What made this test flaky, was the side effect in getShouldUpdateToken. The selector creates a new Date object. Occasionally, this would happen a millisecond after the test setup and the test would fail.

You can make this test deterministic by making the unit under test a pure function and explicitly passing the arguments to the function in the test.

const getShouldUpdateToken = (state, now) => {
  const expirationDate = getExpirationDate(state);
  return now > expirationDate - THIRTY_MINUTES;
};

Tests shouldn’t be flaky (even though some test frameworks accommodated for unreliable tests). They should be independent of random number generations, times, dates, locations, language settings, operating systems etc.

BTW, the example that Kent and Kelly give in their video in Ruby excellently visualizes the problem for E2E tests.

Predictive

Passing tests should give you confidence to deploy to production.

Some environments and conditions are only created in production environments. Sometimes you can’t know a condition is going to exist and even if you know about it, it’s hard or impossible to replicate it.

If you find an error in production, you can write a test for it when you fix it and prevent the bug from resurfacing.

100% predictability can rarely be achieved in the real world.

To maximize predictability, aim for 100% case coverage instead of 100% code coverage by using unit tests and integration tests. You can have 100% of your code covered by unit tests, but your application is still broken.

Inspiring

Tests should give you that feeling of confidence.

Tests should make a difference to team productivity. Your team should be faster and merge more often. Good tests serve as documentation, help with onboarding and aid in understanding code that someone else wrote. (That someone else might be your past you.) They should allow you to increase your deploy frequency while decreasing your deploy risk. Tests make you relax. Tests allow you to rewrite or delete code.

“And finally, tests are a way to liberate energy, to move from worry to hope, creativity, and empathy, to demonstrate trustworthiness.

Passing tests should feel good.” — Kent Beck

‍

My YouTube channel has some more Javascript and React tutorials you’d love. You should check it out here.

Unit Testing Reducers

Jan Hesters — Tue, 13 Oct 2020 10:02:57 GMT

Pure functions are simple and so should be their tests (when using the correct techniques). Reducers, action creators (which aren’t thunks) and selectors are pure functions. After you read this article, when you apply these techniques, you’ll simplify your tests and improve your code.

Photo by Mike Lewinski on Unsplash

The tests in the examples are written with RITEway because it has a genius API that forces you to write good tests. RITEway only exposes an equality assertion, which is perfect for testing pure functions. (The examples work with Jest, too. 🃏)

https://medium.com/media/52c09a8ed1bbd66f76a31f7e37613016/href

I’ll let you read the code now first, and afterwards we analyse the structure of the tests.

https://medium.com/media/52c09a8ed1bbd66f76a31f7e37613016/href

In the example above, we combined the logic and the tests. Usually, the code would live in at least three files (counter-reducer.js, counter-reducer.test.js and root-reducer.js):

src/
├── ...
├── features/
│   ├── ...
│   └── counter/
│       ├── ...
│       └── counter-reducer.js
│       └── counter-reducer.test.js
├── redux/
│   ├── root-reducer.js
│   ├── root-saga.js
│   └── store.js
└── index.test.js

The first test ensures the reducer has the correct initial state. Use a createState factory function for this test and avoid exporting the initial state and using it for the assertion.

https://medium.com/media/6fe87ead728bb438c23efecf39de3053/href

You need to ensure the initial state is correct before you use it in your tests. If you export it and use it in your assertion, an error might slip through. The initial state could have wrong keys, or the wrong initial values for correct keys or be missing keys and your tests would still pass.

The first test tests the reducer without arguments. A reducer that returns its initial state when called without arguments is not in Redux’ official reducer specification. However, it’s helpful for selector tests (- we will see below exactly how -) or to populate initial state for the useReducer Hook.

const [state, dispatch] = useReducer(reducer, reducer());

Suppose you can’t call your reducers without arguments (for example because you’re using Redux Toolkit). In that case, you can write this test by passing undefined and an empty object.

assert({
  given: 'no state with an empty action',
  should: 'return the valid initial state',
  actual: reducer(undefined, {}),
  expected: createState(),
});

Note: If you are looking for an alternative to Redux Toolkit that supports empty argument reducers, check out Autodux.

Test the action creators tightly coupled to your reducer by invoking both in your tests. Avoid action creator tests that assert on their returned action object because all you care about is how they modify the state of your reducer. Using action creators and their handlers together is the most efficient and effective way to test action creators and reducer functions.

Use a factory function like createState to set up the tests for action creators. (For selectors, directly use the rootReducer in conjunction with your actions to compose the state.) You can easily debug the factory function, which allows you to describe the exact state shape that you want. Favor a factory function over inlining the reducer's complete state because it's shorter to overwrite the relevant keys. Avoid using actions creators in the setup for your action creator tests because you don't know whether they behave correctly at that point. Sometimes (e.g. for complex reducers with many keys) you should additionally use a createPopulatedState factory function.

const createPopulatedState = ({
  count: 14
  /* , ... more populated values for more keys */
} = {}) => createState({ count /* , ... more keys */ });

Furthermore, notice how the action creators are tightly coupled to their actions and the case statements, so there is no need to worry about importing or using the right constant. If you have an action creator, you have its type (via incrementBy.type, or incrementBy().type - the former is compatible with thunks).

You should always write at least two tests for each action creator. One to test how it affects the reducer with no prior state (= initial state), and one to test how it interacts with existing state (of the same slice, obviously). (Sometimes you need more than one test for the “with state” scenario.)

Using createPopulatedState you can simplify your "with existing state" action creator test cases.

https://medium.com/media/87a8fb50793aac6d2195c230dde42f55/href

And best of all, if your action creator tests pass, you know that they change the state the way you intended. At this point, it’s okay to use them in your selector tests to set up state. You also want to test the selectors with your rootReducer. (For local state with useReducer, you replace rootReducer with the reducer you're testing.) Using selectors in conjunction with action creators and your rootReducer gives you confidence that:

You hooked up your reducer to your rootReducer, and you did it correctly.
Your action creators work when interacting with each other (- if you use several to set up the test).
Your selectors return the correct value.

You should test selectors with at least two cases, too: One with default state and one with the desired populated state. For the default state, you can call the rootReducer without arguments to get the global initial state. And again, if you can't call your rootReducer without arguments to produce the default state (for example because you're using Redux Persist), you can create and export the rootState from your root-reducer.js file.

https://medium.com/media/77a6ef48e6d522de9a61e808dfbc8503/href

To test the selector’s behavior with state, you can create an actions array and reduce over it to build up the state. This is an excellent technique because it works well even if your reducer depends on several pieces of state controlled by multiple actions (and slices e.g. setOffset).

If you liked this article, you might want to follow me on Twitter and checkout janhesters.com because there is more.

Jan Hesters is a developer at Hopin. After studying physics, he ventured into the startup world and became a programmer. He is specialized in React and Node and has a strong passion for blockchain.

Master Higher-Order Components in React Today

Jan Hesters — Thu, 06 Feb 2020 19:44:57 GMT

Higher Order Components are Misunderstood in React

When you interview 100s of “senior” React developers, you’d be surprised how many fail to answer this simple question:

“What is a higher-order component?”

And even less can answer the follow-up question: “Why do higher-order components in React exist?”

In other words: “Did any React team member consciously create higher-order components as a concept and put them into React?”

In this article, and the video below, you’ll find out the correct answers to these questions, and learn everything you need to know about HOCs.

Note: Make sure you understand arrow functions and the basics of React.

https://medium.com/media/2125ff0a4b7b2f15d26389595dd7ca2c/href

Abstract

You’re first going to see the formal definition of HOCs and through the rest of this article you’ll understand the theory behind it. A Higher-Order component is a function that takes a component and returns a new component.

The React docs further state:

“A higher-order component (HOC) is an advanced technique in React for reusing component logic. HOCs are not part of the React API, per se. They are a pattern that emerges from React’s compositional nature.”

The theory behind HOCs comes from …

Function Composition

In mathematics, function composition is the act of combining functions to form a new function or a result, by applying one function to the result of another.

In JavaScript, this looks this:

const inc = n => n + 1; // f const double = n => n * 2; // g

// h(x) = (f ∘ g)(x) = f(g(x))

const doubleThenInc = x => inc(double(x)); // h

Notice how you assign the combined functions to a new variable called doubleThenInc, which you can do because JavaScript has first-class functions.

You can learn more about first-class functions in this article, which also explains the difference between useCallback and useMemo.

A programming language has first-class functions if it allows you to assign functions to variables.

You can abstract the composition to combine any two functions:

const compose2 = (f, g) => x => f(g(x));

const doubleThenInc2 = compose2(inc, double);

You omit the argument x in the definition of doubleThenInc2. This means doubleThenInc2 is defined point-free, which is when you define a function without mentioning its arguments.

const doubleThenInc = x => inc(double(x)); // mentions X 👉 pointed
const doubleThenInc2 = compose2(inc, double); // point-free

If you want to compose an arbitrary amount of functions, you need to generalize the composition function.

const compose = (...fns) => x => fns.reduceRight((y, f) => f(y), x);

const square = n => n * n;

const doubleThenInc3 = compose(inc, double);
const doulbeThenIncThenSquare = compose(square, inc, double);

More sophisticated versions of the compose function are frequently exposed by libraries that leverage HOCs such as Redux and Apollo.

The arguments and return values of functions have to line up to compose them. For example, you can’t compose a function that accepts an object and returns a string with a function that receives an array and returns a number.

// (number, number) => number[]
const echo = (value, times) => Array(times).fill(value);
// number[] => number[]
const doubleMap = array => array.map(x => x * 2);

// Correct composition. ✅
const echoAndDoubleMap = compose(doubleMap, echo);

console.log(echoAndDoubleMap(3, 4)); // [6, 6, 6, 6]

// Incorrect composition that will throw an error. ❌
const wrongOrder = compose(echo, doubleMap);

try {
  // This will fail because doubleMap expects an array,
  // instead of two numbers.
  console.log(wrongOrder(3, 4));
} catch (error) {
  console.error("Error:", error.message); // Error: array.map is not a function
}

Since inc and double both take and return numbers, you can compose them in any order.

// Composition that doubles then increments. ✅
const doubleThenInc = compose(inc, double);
console.log(doubleThenInc(3)); // 7

// Composition that increments then doubles. ✅
const incThenDouble = compose(double, inc);
console.log(incThenDouble(3)); 8

Additionally, compose2 and compose are higher-order functions.

A higher-order function is a function that either receives or returns a function or does both.

const multiply = multiplier => multiplicant => multiplier * multiplicant;
const double = multiply(2);

const map = f => arr => arr.map(f);

const doubleMap = map(double);

const numbers = [1, 2, 3];

doubleMap(numbers); // [2, 4, 6]

multiply IS a higher-order function because it takes in a number and returns a function.
double IS NOT a higher-order function because it neither receives nor returns a function. It is defined point-free.
map IS a higher-order function because it both accepts and returns a function.
doubleMap IS NOT a higher-order function because it neither receives nor returns a function. It is defined point-free.

React components can either be functions or classes.

import { Component } from 'react'

function MyFunctionComponent() {
  return Function

}

class MyClassComponent extends Component {
  render() {
    return Class

  }
}

In JavaScript, the class keyword is essentially a wrapper for the function keyword and handles prototypal inheritance. In other words, classes compile to constructor functions.

Therefore, since all components are functions in React and JavaScript has higher-order functions, you get HOCs for free. That is what the docs mean when they say HOCs “are a pattern that emerges from React’s compositional nature.”

Now you should understand the basic definition of HOCs:

A Higher-Order component is a function that takes a component and returns a new component.

Any function whose input and output is a React component is a HOC.

HOCs by Example

You probably want to see what a higher-order component looks like. Follow the rest of this tutorial to write your own using TDD. You’re going to use Vitest with React Testing Library to write the tests.

You can deduce two requirements from the definition of a higher-order component:

HOCs are functions.
HOCs take a component and return a component.

You can capture these requirements in a unit test.

import { render, screen } from '@testing-library/react';
import { describe, expect, test } from 'vitest';

import myHOC from './my-hoc';

function MyComponent({ title = 'Hello' }) {
  return {title}
;
}

describe('myHOC', () => {
  test('given a component: returns the component with a default title', () => {
    const WrappedComponent = myHOC(MyComponent);

    render();

    expect(screen.getByText('Hello')).toHaveTextContent('Hello');
  });
});

The test checks both requirements because when this test passes, you can logically deduce that your HOC is a function and that it returns a component without spelling out those requirements explicitly. If the HOC were not a function and you tried to call it, it would throw, and your unit test would fail with a clear stack trace. Likewise, the test renders the return value of the HOC, which ensures it is a React component.

Notice how you did NOT test for typeof function here. Unit tests which only test types are an anti-pattern. It's redundant with simply calling the function and checking its output value. In general, type checks are redundant with well-written unit tests. This is why unit tests can catch most type errors, without the need for additional measures like type annotations (though annotations and type inference can still be useful to enable IDE tooling).

You can get the test to pass by making your HOC the identity function.

export default Component => Component;

Your test result should now look like this.

✓ app/my-hoc.test.jsx (1)
   ✓ myHOC (1)
     ✓ given a component: returns the component with a default title

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  16:07:11
   Duration  128ms


 PASS  Waiting for file changes...
       press h to show help, press q to quit

Why HOCs?

Your current HOC does nothing. And you’re going to change that, soon.

In general, HOCs excel at abstracting logic or styling. They allow you to avoid unnecessary code duplication. If you find yourself repeating certain JSX or logic patterns in your component, you might be able to abstract them away using HOCs.

For example, if you have a page for your web site or a screen for your React Native app, most pages or screens have the same layout. They all share elements such as headers, footers or formatting containers.

Making Your HOC Useful

You can add styling abilities to our HOC and call it withLayout instead of MyHOC.

Start by adding a test that verifies that your HOC adds a layout to your component.

import { render, screen } from '@testing-library/react';
import { describe, expect, test } from 'vitest';

import withLayout from './with-layout';

function MyComponent({ title = 'Hello' }) {
  return {title}
;
}

describe('withLayout', () => {
  test('given a component: returns the component with a default title', () => {
    const WrappedComponent = withLayout(MyComponent);

    render();

    expect(screen.getByText('Hello')).toHaveTextContent('Hello');
  });

  test('given a component: renders the layout around the component', () => {
    const WrappedComponent = withLayout(MyComponent);

    render();

    expect(screen.getByRole('heading')).toHaveTextContent(/some title/i);
    expect(screen.getByRole('main')).toContainElement(screen.getByText('Hello'));
    expect(screen.getByRole('contentinfo')).toHaveTextContent(/some footer/i);
  });
});

Watch your test fail, then create a layout component.

export function Layout({ children }) {
  return (
    
      
        Some Title

      


      
        {children}
      


      
        Some footer

      

    

  );
}

Layouts can vary depending on the app and framework that you’re using. In React Native app, you find yourself writing similar layout HOCs using React Navigation’s . In a Remix app, you won't need a layout HOC because you can export a layout component from your root.tsx file.

Now, make your test pass by using the Layout component in your HOC.

import { Layout } from './layout';

export default Component => () => (
  
    
  
);

Your tests should both pass now.

✓ app/with-layout.test.jsx (2)
   ✓ withLayout (2)
     ✓ given a component: returns the component with a default title
     ✓ given a component: renders the layout around the component

 Test Files  1 passed (1)
      Tests  2 passed (2)
   Start at  16:05:39
   Duration  128ms


 PASS  Waiting for file changes...
       press h to show help, press q to quit

Notice how the withLayout HOC now takes in a component and then returns a function because before this change it actually was NOT a higher-order component.

This also shows the most common misconception about HOCs. Many developers answer the question of “What is a higher-order component” with “it’s a component that takes in a React component and returns it”.

They probably think of something like this.

// Wrong! ❌
function NotAHigherOrderComponent({ Component }) {
  return (
    
      Header added by NotAHigherOrderComponent

      
    

  );
}

function MyComponent() {
  return Hello, I am a regular component.
;
}

function App() {
  return (
    
      
    

  );
}

What you see above is a React component that takes in another React component as a prop.

But that’s is NOT a higher-order component because HOCs are functions and NOT components. You can NOT render a HOC.

Looking back at the your withLayout HOC, it contains a bug. Can you spot it?

If not, that is okay. You can write the following test to expose the error.

describe('withLayout', () => {
  // ... your other tests

  test('given props for the wrapped component: passes on the props to the wrapped component', () => {
    const WrappedComponent = withLayout(MyComponent);
    const customTitle = 'Custom Title';

    render();

    expect(screen.getByText(customTitle)).toHaveTextContent(customTitle);
  });
});

The new test fails.

❯ app/with-layout.test.jsx (3)
   ❯ withLayout (3)
     ✓ given a component: returns the component with a default title
     ✓ given a component: renders the layout around the component
     × given props for the wrapped component: passes on the props to the wrapped component

Now your tests pass because your HOC correctly passes on the props to the wrapped component.

✓ app/with-layout.test.jsx (3)
   ✓ withLayout (3)
     ✓ given a component: returns the component with a default title
     ✓ given a component: renders the layout around the component
     ✓ given props for the wrapped component: passes on the props to the wrapped component

 Test Files  1 passed (1)
      Tests  3 passed (3)
   Start at  16:55:45
   Duration  139ms


 PASS  Waiting for file changes...
       press h to show help, press q to quit

However, the abstraction capabilities of HOCs wouldn’t be as useful if they didn’t have another key feature. Eric Elliott describes it like this:

“The primary benefit of HOCs is not what they enable (there are other ways to do it); it’s how they compose together at the page root level.”

In other words, the key to using HOCs well is to know how and when you want to compose them. You you write a test to demonstrate the “how”. Spoiler: it is fundamentally function composition.

Here is a test that shows how you compose HOCs.

import { render, screen } from '@testing-library/react';
import { describe, expect, test } from 'vitest';

import withLayout from './with-layout';

function MyComponent({ title }) {
  return {title}
;
}

describe('withLayout', () => {
  // ... your other tests

  test('given used in composition with other HOCs: passes on the props of the other HOCs', () => {
    const compose = (...fns) => x => fns.reduceRight((y, f) => f(y), x);
    const withTitle = Component => props => (
      
    );
    const ComposedComponent = compose(
      withLayout,
      withTitle
    )(MyComponent);

    render();

    expect(screen.getByText('foo')).toHaveTextContent('foo');
  });
});

This test already passes.

You compose withLayout with withTitle. withTitle is a HOC that injects a title prop to a component.

Configuring HOCs

It is common for HOCs to accept configuration objects. You probably encounter this when using React Redux’ connect with mapStateToProps. (In fact, it accepts two more arguments: mapDispatchToProps and mergeProps.)

Assume that some pages should render without the header, so you modify your layout component to take in a prop that let’s you show and hide the header.

export function Layout({ children, showHeader = true }) {
  return (
    
      {showHeader && (
        
          Some Title

        

      )}

      {children}


      
        Some footer

      

    

  );
}

Now write a test that allows you to modify your HOC. You’ll also need to modify your existing tests to accommodate the fact that your HOC now takes in a configuration object.

import { render, screen } from '@testing-library/react';
import { describe, expect, test } from 'vitest';

import withLayout from './with-layout';

function MyComponent({ title = 'Hello' }) {
  return {title}
;
}

describe('withLayout', () => {
  test('given a component: returns the component with a default title', () => {
    const WrappedComponent = withLayout()(MyComponent);

    render();

    expect(screen.getByText('Hello')).toHaveTextContent('Hello');
  });

  test('given a component: renders the layout around the component', () => {
    const WrappedComponent = withLayout()(MyComponent);

    render();

    expect(screen.getByRole('heading')).toHaveTextContent(/some title/i);
    expect(screen.getByRole('main')).toContainElement(
      screen.getByText('Hello'),
    );
    expect(screen.getByRole('contentinfo')).toHaveTextContent(/some footer/i);
  });

  test('given props for the wrapped component: passes on the props to the wrapped component', () => {
    const WrappedComponent = withLayout()(MyComponent);
    const customTitle = 'Custom Title';

    render();

    expect(screen.getByText(customTitle)).toHaveTextContent(customTitle);
  });

  test('given used in composition with other HOCs: passes on the props of the other HOCs', () => {
    const compose =
      (...fns) =>
      x =>
        fns.reduceRight((y, f) => f(y), x);
    const withTitle = Component => props => (
      
    );
    const ComposedComponent = compose(withLayout(), withTitle)(MyComponent);

    render();

    expect(screen.getByText('foo')).toHaveTextContent('foo');
  });

  test('given a component and NOT rendering the header: does NOT render the header', () => {
    const WrappedComponent = withLayout({ showHeader: false })(MyComponent);

    render();

    expect(screen.queryByRole('heading')).toBeNull();
  });
});

Watch all your tests fail because your component still lacks the configuration object. Add it to make them pass.

import { Layout } from './layout';

export default ({ showHeader = true } = {}) =>
  Component =>
  props => (
    
      
    
  );

To answer the question of when to use composition for HOCs, remember what I told you learned earlier. HOCs are excellent if you want to abstract away common logic between many components. You chose to give your function a layout functionality because that is one area that most screens of your application will share. Using compose you can define a HOC that you can use to wrap all your pages with.

Real-World Example

Here is a real-world example of a SignInForm container component. See if you understand it, then read the explanation to check if you were correct.

import { withFormik } from 'formik';
import compose from 'ramda/src/compose.js';
import { connect } from 'react-redux';
import { withRouter } from 'react-router';
import SignInComponent from './sign-in-form-component.js';
import { isAuthenticating, signIn } from './user-authentication-reducer.js';
import { signInValidationSchema } from './validation-schema.js';

const initialFormValues = { email: '', password: '' };

const mapStateToProps = state => ({ loading: isAuthenticating(state) });

const formikConfig = {
  handleSubmit: ({ email, password }, { props: { signIn } }) => {
    signIn({ email, password });
  },
  mapPropsToValues: () => initialFormValues,
  validationSchema: signInValidationSchema,
};

export default compose(
  withRouter,
  connect(
    mapStateToProps,
    { signIn }
  ),
  withFormik(formikConfig),
)(SignInComponent);

In the example above, you composed 3 different HOCs.

withRouter is a HOC from React Router DOM. It injects the history object, which you can use to navigate to the password reset screen, when the user clicks the "Forgot Password" button.
connect is a HOC from React Redux. You use it to connect your component to your Redux store. You inject the loading prop and the signIn action creator.
withFormik is a HOC from Formik. Formik let's you control local form state and handles form validation for you.

Sometimes you need to copy over static properties such as propTypes, defaultProps and getStaticProps (if you are using Next.js) from the inner component to the resulting component. Here is a Higher-Order HOC (a function that returns a HOC), which does this for you.

import hoistNonReactStatics from 'hoist-non-react-statics';

const hoistStatics = higherOrderComponent => Component => {
 const WrappedComponent = higherOrderComponent(Component);
 hoistNonReactStatics(WrappedComponent, Component);
 return WrappedComponent;
};

BTW: When using HOCs you need to treat refs special, too. If you need to pass refs through a component hierarchy, you should probably be using a hook for the ref instead of a HOC.

Need to hire a senior React developer? Book a call with ReactSquad to get matched with one in 48 hours.

HOC Composition

You know from function composition that you can only compose functions whose types line up. Similarly, you need to pay attention to the order in which you compose your HOCs. One HOC can inject props that another might depend on. If the one that depends on the props gets injected before the prop injecting HOC, your app might break.

const formatTitleProp = ({ title, ...otherProps }) => ({
  title: title.toUpperCase(),
  ...otherProps,
});

const withTitle = Component => props => ;

const withFormattedTitle = Component => props => (
  
);

const breakingApp = compose(withFormattedTitle, withTitle)(App); // 🔴 Breaks!

const workingApp = compose(withTitle, withFormattedTitle)(App); // ✅ Correct order!

If you switch the order of HOCs in the real-world example above, it will break, too. withFormik(formikConfig) depends on signIn being defined, and transformProps depends on both history and the formikBag props.

HOCs with implicit dependencies on each other may be a code smell. In some cases, it may be better to make those dependencies explicit, by importing the shared functionality into the components that need them, or taking the dependency as a configuration parameter of the HOC. It’s probably ok to implicitly depend on something that’s pretty universal to all your pages, such as your store provider.

Now you can confidently:

Identify HOCs in your codebase.
Write your own HOCs to abstract common logic and styling across components.
Compose multiple HOCs to achieve more complex functionalities.

For a deeper dive into React, subscribe to my YouTube channel!

Multiple Environments with AWS Amplify

Jan Hesters — Tue, 27 Aug 2019 11:33:08 GMT

In this tutorial, you are going to learn how to use Amplify’s env command. We will walk through an example where two people collaborate on an Amplify project.

Note: This article was first posted on my blog. I publish each article two weeks later on Medium. You might want to subscribe to my newsletter because you will get content like this earlier! 💌

Another note: This article is a tutorial for developers who are familiar with the basics of Amplify. Do you want to learn how to accelerate the creation of your projects using Amplify 🚀? I recommend beginners to check out Nader Dabit’s free course on egghead, or Amplify’s ‘Getting Started’.

If you use Amplify in your team, you will have to know how to use the env command properly. Otherwise, your collaboration will be a mess. Done right, Amplify allows easy and effective collaboration on projects.

There are two ways you can share an Amplify project.

Each team member works in their own “sandbox” aka. their local version of the environment.
The team shares the same development environment.

The first approach is recommended. Let’s walk through each procedure, so you understand both and can decide which you prefer. You need to be familiar with Git to follow this tutorial.

1. Sandboxes

We start with the sandbox approach. Create a folder for this tutorial called multiple-env/.

mkdir multiple-env && cd multiple-env

Initialize the React project.

npx create-react-app env-one && cd env-one

Create React App automatically initializes a Git repository for us. The folder layout should later look like this.

└──multiple-env/
   ├── env-one/
   └── env-two/

Imagine env-two/ being on your co-worker's computer. Here we'll use the two apps on your computer to simulate multiple environments.

1. a) You

Initialize Amplify in your first environment and add authentication. Note: In some of these code examples, there will be several CLI commands that you have to run. Remember to double-check that you catch all and don’t miss any.

amplify initNote: It is recommended to run this command from the root of your app directory
? Enter a name for the project
env-one
? Enter a name for the environmentprod? Choose your default editor:
Visual Studio Code
? Choose the type of app that you\'re building
javascript
Please tell us about your project
? What javascript framework are you using
react
? Source Directory Path:
src
? Distribution Directory Path:
build
? Build Command:
npm run-script build
? Start Command:
npm run-script start
Using default provider  awscloudformation

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html

? Do you want to use an AWS profile?
Yes
? Please choose the profile you want to use
your-amplify-cli-user

✔ Successfully created initial AWS cloud resources for deployments.
✔ Initialized provider successfully.
Initialized your environment successfully.

Your project has been successfully initialized and connected to the cloud!

amplify add authDo you want to use the default authentication and security configuration?
Default configuration
Warning: you will not be able to edit these selections.
How do you want users to be able to sign in?
Email
Do you want to configure advanced settings?
No, I am done.

Nothing fancy going on here. Just make sure to name the first environment prod, master or something along those lines.

Push your changes to the cloud.

amplify push

If you run amplify status, you will see that your changes have been deployed.

amplify status

Current Environment: prod

| Category | Resource name  | Operation | Provider plugin   |
| -------- | -------------- | --------- | ----------------- |
| Auth     | envoneauth | No Change | awscloudformation |

Add the changes to git.

git add --all && git commit -m "Initialize Amplify and add authentication."

Set up a remote repository on GitHub or your version control provider of choice and upload your files.

git remote add origin https://github.com/janhesters/envtutorial.git
git push -u origin master

1. b) Your Co-Worker

You might want to use a second editor and terminal window to simulate the collaboration.

Clone the remote repository.

git clone https://github.com/janhesters/envtutorial.git env-two && cd env-two && yarn

If you run amplify status now, it will throw an error.

amplify status

Current Environment: undefined

Initialize the master branch using the prod environment.

amplify init
Note: It is recommended to run this command from the root of your app directory
? Do you want to use an existing environment?
Yes
? Choose the environment you would like to use:
prod
? Choose your default editor:
Visual Studio Code
Using default provider  awscloudformation

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html

? Do you want to use an AWS profile?
Yes
? Please choose the profile you want to use
your-amplify-cli-user

✔ Initialized provider successfully.
Initialized your environment successfully.

Your project has been successfully initialized and connected to the cloud!

In a real-world scenario, your collaborators might have different CLI profiles. Make sure everyone has the permissions to access the relevant resources.

Now, your co-worker has the environment, too.

amplify status

Current Environment: prod

| Category | Resource name | Operation | Provider plugin   |
| -------- | ------------- | --------- | ----------------- |
| Auth     | envoneauth    | No Change | awscloudformation |

1. c) You

Change back to env-one/. We want to add another feature.

Amplify environments work hand in hand with Git. We can create our sandbox by creating a new git branch, and running amplify init within it.

git checkout -b sandbox && amplify init
Switched to a new branch 'sandbox'
Note: It is recommended to run this command from the root of your app directory
? Do you want to use an existing environment?
No
? Enter a name for the environment
sandbox
Using default provider awscloudformation

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html

? Do you want to use an AWS profile?
Yes
? Please choose the profile you want to use
your-amplify-cli-user

Typically, you would give the branch a more meaningful name than "sandbox". Alternatively to amplify init we could've also used amplify env add.

The changes for this environment aren’t deployed yet.

amplify status

Current Environment: sandboxone

| Category | Resource name | Operation | Provider plugin   |
| -------- | ------------- | --------- | ----------------- |
| Auth     | envonesandbox | Create    | awscloudformation |

Note how it says our current environment is sandboxone. To list all environments run amplify env list.

amplify env list

| Environments |
| ------------ |
| prod         |
| *sandboxone  |

In this list, our current environment is marked with a star (*).

Let’s also add an API to the sandbox and deploy it.

amplify add api? Please select from one of the below mentioned services
GraphQL
? Provide API name:
AppSyncEnvOneSandbox
? Choose an authorization type for the API
Amazon Cognito User Pool
Use a Cognito user pool configured as a part of this project
? Do you have an annotated GraphQL schema?
No
? Do you want a guided schema creation?
Yes
? What best describes your project:
Single object with fields (e.g., “Todo” with ID, name, description)
? Do you want to edit the schema now?
No

amplify push
git add --all && git commit -m "Add API."

The sandbox now has an API as well as authentication. If we made our changes and want to merge them into the production environment, we can do that by using Git.

git checkout master
amplify env checkout prod
git merge sandbox
amplify push
git add --all && git commit -m "Merge API into production."

If you are done using your sandbox environment, you can delete it by running amplify env remove.

amplify env remove sandbox
? Do you also want to remove all the resources of the environment from the cloud?
Yes

1. d) Your Co-Worker

Your co-worker can get the changes by running amplify env pull. cd into env-two/ and do that.

git pull && amplify env pull

When those commands are done your co-worker is synced up with the master branch.

amplify status

Current Environment: prod

| Category | Resource name        | Operation | Provider plugin   |
| -------- | -------------------- | --------- | ----------------- |
| Auth     | envoneauth           | No Change | awscloudformation |
| Api      | AppSyncEnvOneSandbox | No Change | awscloudformation |

Good job! 👏🏻 Now you know how to collaborate using sandboxes. Next, we’ll explore collaboration with …

2. Sharing backends

Sharing backends is as easy as using the sandbox. I like to mix both approaches. Meaning each team member develops using their custom sandbox, but before changes get merged into production, they get merged into the development environment.

2. a) You

Similar to the sandbox approach, create a dev branch with Git and an environment with Amplify in env-one/.

git checkout -b dev && amplify init
Switched to a new branch 'dev'
Note: It is recommended to run this command from the root of your app directory
? Do you want to use an existing environment?
No
? Enter a name for the environment
dev
Using default provider  awscloudformation

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html

? Do you want to use an AWS profile?
Yes
? Please choose the profile you want to use
your-amplify-cli-user

We might want to track our users using Amplify’s analytics, so let’s add that to our dev branch.

amplify add analytics
Using service: Pinpoint, provided by: awscloudformation
? Provide your pinpoint resource name:
AnaliticsDev
Adding analytics would add the Auth category to the project if not already added.
? Apps need authorization to send analytics events. Do you want to allow guests and unauthenticated users to send analytics events? (we recommend you allow this when getting started)
No
Authorize only authenticated users to send analytics events. Use "amplify update auth" to modify this behavior.
Successfully updated auth resource locally.
Successfully added resource AnaliticsDev locally

Push your changes to the cloud and GitHub.

amplify push
git add --all && git commit -m "Add analytics."
git push --set-upstream origin dev

2. b) You Co-Worker

Your co-worker, in env-two/, can get the remote branch by creating his local version and then fetching it.

git checkout -b dev && git fetch origin dev && git pull origin dev

Your co-worker can list all environments to see both the prod and the dev branch.

Moving code from dev to prod works the same way as we showed earlier when we moved from sandbox to prod.

If you liked this tutorial, you might want to read my other articles about Amplify because they cover advanced use cases and make you an Amplify expert.

Summary

Remember: Use Amplify’s env command parallel to Git.

We understood the two ways — sandbox and shared environments — to use env by looking at an example for each.

To clean up run amplify delete.

Note: This article was first posted on my blog. I publish each article two weeks later on Medium. You might want to subscribe to my newsletterbecause you will get content like this earlier! 💌

Interested in JavaScript, React or Amplify consulting for your team, or mentoring for yourself? Have another opportunity for me? My DMs are open.

Originally published at https://janhesters.com.

Lambda Triggers & Read-Only Permissions with AWS Amplify

Jan Hesters — Tue, 20 Aug 2019 09:16:58 GMT

In this tutorial, you are going to learn how you can trigger a Lambda function on authentication events with AWS Amplify. We are going to add users to a group to make specific data read-only for everyone but its owner.

Note: This article was first posted on my blog. I publish each article two weeks later on Medium. You might want to subscribe to my newsletterbecause you will get content like this earlier! 💌

Another note: This article is a tutorial for intermediate developers who are familiar with the basics of Amplify. Do you want to learn how to accelerate the creation of your projects using Amplify 🚀? I recommend beginners to check out Nader Dabit’s free course on egghead, or Amplify’s ‘Getting Started’.

An everyday use case for data is that some data is read-only, and other is not. Currently, the only way- Amplify lets you declare different permissions for users is by using static groups in Cognito and using attributes on the schema. We are going to leverage Amplify’s new support for Lambda triggers to add users to a static group upon sign up.

Let’s go! 👨🏻‍💻 I’m going to assume you have a new project ready created with amplify init.

Start by adding authentication to it. (Make sure you have the latest version of the CLI installed! 👉🏻 npm install -g @aws-amplify/cli)

amplify add auth
Using service: Cognito, provided by: awscloudformation

The current configured provider is Amazon Cognito.

? Do you want to use the default authentication and security configuration?
Manual configuration
? Select the authentication/authorization services that you want to use:
User Sign-Up, Sign-In, connected with AWS IAM controls (Enables per-user Storage features for images or other content, Analytics, and more)
? Please provide a friendly name for your resource that will be used to label this category in the project:
authtrigger
? Please enter a name for your identity pool.
triggeridentitypool
? Allow unauthenticated logins? (Provides scoped down permissions that you can control via AWS IAM)
No
? Do you want to enable 3rd party authentication providers in your identity pool?
No
? Please provide a name for your user pool:
triggeruserpool
Warning: you will not be able to edit these selections.
? How do you want users to be able to sign in?
Email and Phone Number
? Multifactor authentication (MFA) user login options:
OFF
? Email based user registration/forgot password:
Enabled (Requires per-user email entry at registration)
? Please specify an email verification subject:
Your verification code
? Please specify an email verification message:
Your verification code is {####}
? Do you want to override the default password policy for this User Pool?
No
Warning: you will not be able to edit these selections.
? What attributes are required for signing up? (Press to select, to toggle all, to invert selection)
Email
? Specify the app\'s refresh token expiration period (in days):
30
? Do you want to specify the user attributes this app can read and write?
No
? Do you want to enable any of the following capabilities?Add User to Group? Do you want to use an OAuth flow?No? Do you want to configure Lambda Triggers for Cognito?Yes? Which triggers do you want to enable for Cognito (Press to select, to toggle all, to invert selection)Post Confirmation? What functionality do you want to use for Post Confirmation (Press to select, to toggle all, to invert selection)Add User To Group? Enter the name of the group to which users will be added.everyoneSuccesfully added the Lambda function locally? Do you want to edit your add-to-group function now?NoSuccessfully added resource authtrigger locally

The steps are pretty self-explanatory. We define a Lambda function that triggers after a user confirms her/his sign-up and add the user to the everyone group.

Next, add an API.

amplify add api
? Please select from one of the below mentioned services
GraphQL
? Provide API name:
AppSyncTrigger
? Choose an authorization type for the API
Amazon Cognito User Pool
Use a Cognito user pool configured as a part of this project
? Do you have an annotated GraphQL schema?
No
? Do you want a guided schema creation?
Yes
? What best describes your project:
Single object with fields (e.g., “Todo” with ID, name, description)
? Do you want to edit the schema now?
Yes

Here is how the schema should look like.

https://medium.com/media/8507bfd73bb050f6667895cf0c176be7/href
Since we didn’t specify any operations for the owner, he is free to execute any query or mutation on the todos he owns. Every other user is only able to use the get and list queries on his todos. The available values for the operations key besides read are create, delete and update. Additionally, we add an optional owner attribute to the todo schema because we use it to verify that we are only allowed to read other users' todos. If you make it mandatory by adding a ! you will have to specify the owner manually when you create the todo. Leaving out the ! allows amplify to populate that field for you automatically.
Push your changes.
amplify push
Now, create two users and add a couple of todos for each of them. You don’t have to do that through your code. If you are coding along and want to save time, you can use the Cognito console to create the users and the AppSync console to execute the GraphQL operations. Remember when using the console to add users, the function will NOT be triggered. You will have to add the user to the "everyone" group manually.
mutation create {
createTodo(input: { title: "Buy groceries" }) {
id
title
owner
}
}
If you list the todos, you should see the todos of all users.
query list {
listTodos {
items {
id
title
owner
}
}
}
But if you try to mutate a todo that is not your own, you should get an error.
mutation update {
updateTodo(
input: { id: "id-of-other-users-todo", title: "different title" }
) {
id
title
owner
}
}
The error looks something like this.
{
"data": {
"updateTodo": null
},
"errors": [
{
"path": ["updateTodo"],
"data": {
"id": "09e9963f-bed8-432c-b55c-8eb798c50967",
"name": "Foo",
"owner": "eb8a7fa3-463f-4117-aca2-165419cff879"
},
"errorType": "DynamoDB:ConditionalCheckFailedException",
"errorInfo": null,
"locations": [
{
"line": 38,
"column": 3,
"sourceName": null
}
],
"message": "The conditional request failed (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: ConditionalCheckFailedException; Request ID: RO6DBNS6K8D7611RSL9HVRTSUVVV4KQNSO5AEMVJF66Q9ASUAAJG)"
}
]
}
Very good! 🤓 We implemented read-only permissions, and our users get added to a static Cognito group using Lambda triggers.
Note: This article was first posted on my blog. I publish each article two weeks later on Medium. You might want to subscribe to my newsletterbecause you will get content like this earlier! 💌
Originally published at https://janhesters.com.

Testing Lambda Functions (feat. Amplify)

Jan Hesters — Tue, 13 Aug 2019 10:38:09 GMT

You are going to learn how to write unit tests for Lambda functions. We are going to write integration tests, too, and use test-driven development to write our tests. We will break our express app into small modules to make its units composable and testable.
Note: This article was first posted on my blog. I publish each article two weeks later on Medium. You might want to subscribe to my newsletter because you will get content like this earlier! 💌
Another note: This article is a tutorial for intermediate developers who are familiar with the basics of Amplify or Lambda functions. Do you want to learn how to accelerate the creation of your projects using Amplify 🚀? I recommend beginners to check out Nader Dabit’s free course on egghead, or Amplify’s ‘Getting Started’.
I saw Lambda functions without tests and spaghetti code. In fact, I’m guilty of having written several of those myself. It’s part of the learning process as a developer to get better and write cleaner and more maintainable code as you gain experience.
You are going to learn the techniques I use to test and simplify Lambda functions. Simplifying means to isolate your program logic into separate, functional units, which makes it more composable and testable. We are going to use RITEway for unit tests, Supertest for integration tests and AWS Amplify to generate our Lambda functions.
Why these three tools? RITEway has a genius API that forces your tests to answer the five questions every unit test must answer. Supertest makes HTTP assertions in Node.js easy. And if you read this article, I won’t have to tell you how amazing Amplify is to manage AWS resources. Just check out the other articles of my blog.
Unit Tests
I assume you have a project with Amplify initialized ready. Create a new Lambda function using Amplify.
amplify add function
? Provide a friendly name for your resource to be used as a label for this category in the project:
lambdaTest
? Provide the AWS Lambda function name:
lambdaTest
? Choose the function template that you want to use:
Serverless express function (Integration with Amazon API Gateway)
? Do you want to access other resources created in this project from your Lambda function?
Yes
? Select the category (Press to select, to toggle all, to invert selection)

You can access the following resource attributes as environment variables from your Lambda function
var environment = process.env.ENV
var region = process.env.REGION

? Do you want to edit the local lambda function now?
No
Consequently, add RITEway and Supertest alongside tap-color. The ladder is for formatting our test output so that it looks pretty.
cd amplify/backend/function/lambdaTest/src/ && npm install --save-dev riteway tap-color supertest && npm i
Make sure to add a testing script to your package.json.
"test": "riteway '**/*.test.js' | tap-color"
We will need some functional programming helpers to compose our code. Either install a functional library like Ramda or create a file src/fp/index.js and add the following functions.
Note: If the following functions scare you, level up by reading “Professor Frisby’s Mostly Adequate Guide to Functional Programming”. I also explain the basics of currying in “Understanding Arrow Functions”. Nevertheless, for the sake of this tutorial, it’s okay if you don’t get all of this article’s code. Understanding the techniques is more important than the actual implementation.
https://medium.com/media/dbc656f5220946eb7931726e61b56649/href
I’m going to use Ramda. With the help of tap and pipe, we can write applyMiddleware in src/middleware/index.js, which lets us elegantly compose our middleware.
https://medium.com/media/a2e95cdf20bd3f0da55fc5a760c79085/href
Note: If you want to learn how you can functionally write your own custom middleware, you might want to read last weeks article “How to Access the User in Lambda Functions (with Amplify)”.
Using our test frameworks, we want to write some unit tests in src/routes/routes.test.js. We will write one for our "/items" GET route and one for the listener that logs out on which port the server is running on.
https://medium.com/media/664b2566527cb1fec2be3fa749537dd4/href
In true TDD fashion, we have to watch the tests fail. Write some dummy functions in src/routes/index.js.
https://medium.com/media/ca3e05465aec82b22718312ca8ef0dde/href
Watch the tests fail by running npm test. Afterwards, make the tests pass.
https://medium.com/media/e225c81995de7a013bce41430c4c1789/href
Now we can use them in our function. Note how we also deleted the comments and routes generated by Amplify.
https://medium.com/media/601d8f6cb420485a60991dacfaf6d269/href
I love how clean this code is 👌🏻. You can locally run your Express server by invoking the Lambda function. But before that, we need to modify src/event.json to ping the /items route with a GET request.
https://medium.com/media/0e143e6d0850bc4f00fe8298d28586c6/href
Moreover, you can pass keys like "query" to simulate URLs with "?" in them and "body" or "headers".
Now invoke the function.
amplify function invoke lambdaTest
Using service: Lambda, provided by: awscloudformation
? Provide the name of the script file that contains your handler function:
index.js
? Provide the name of the handler function to invoke:
handler

Running "lambda_invoke:default" (lambda_invoke) task

Listening on port 3000.
EVENT: {"httpMethod":"GET","path":"/items"}

Success! Message:
------------------
{
body: "{\"success\":\"get call succeeded\",\"items\":[\"vacuum cleaner\",\"knife\",\"computer\"]}",
headers: {
"access-control-allow-headers": "Origin, X-Requested-With, Content-Type, Accept",
"access-control-allow-origin": "*",
connection: "close",
"content-length": "78",
"content-type": "application/json; charset=utf-8",
date: "Sat, 13 Jul 2019 21:29:34 GMT",
etag: "W/\"4e-XNTYS3kI7G7czAiqg07A+69mhoQ\"",
"x-powered-by": "Express"
},
isBase64Encoded: false,
statusCode: 200
}
We won’t use these manual tests for the rest of the article. I just wanted to show them to you as another option to try out your functions on the fly. Sometimes you want to do that. However, it’s usually better to have your tests automatically confirm that your code works instead of you doing it manually. Let’s do that using …
Integration Tests
Testing Lambda functions involves I/O. We mocked res in our unit test for getItems, but generally, you want to avoid mocking because it is a code smell. While I'm going to explain how and why I test what I test, you should read "Mocking Is a Code Smell" by Eric Elliott because he explains testing asynchronous code in more detail.
Let’s rewrite "/items" to be "/addresses" which gets a list of users and returns their addresses. We are going to use the free JSONPlaceholder API for this.
To force us to write modular code, we want to write the GET route for /addresses using asyncPipe. A pipe always expects the data types to line up. The function that is passed to the route gets two arguments: request and response. We will lift them into a generic object context via a function we call liftReqRes. Using an object has the advantage that we can pass values through the pipe by attaching them to keys. If you don't understand this yet, wait until you see the code. The code will clear things up for you.
We start with the functional test using Supertest in src/app.test.js.
https://medium.com/media/6370c3020634fb82913b03686ff26e6a/href
Rename our route in app.js and routes/index.js to "addresses" and move handleListen to src/index.js. Otherwise, every test would cause our server to run, and the tests wouldn't stop.
Here is how app.js looks now.
https://medium.com/media/bbc54d69898019a48a1b7076accb412a/href
And here is src/index.js with app.listen.
https://medium.com/media/2bf6977cceccf9beeec7b4b07da718b6/href
Let’s implement the functions needed to compose getAddresses. First up is liftReqRes.
https://medium.com/media/5fbea22d20d5f4cb0353b3f85dc54e3a/href
Watch the test fail, then make it pass by implementing liftReqRes.
const liftReqRes = (request, response) => ({ request, response });
We are going to execute our GET request with axios.get. Install axios by running npm install axios in your function's directory. We need to install a library for requests since Lambda functions don't have fetch. You could also install node-fetch or a polyfill if you prefer fetch over axios.
If axios.get is successful, the response has the following shape:
https://medium.com/media/485f02da8d109876e878f996c84f63be/href
Here the data key comes from axios and not from the placeholder API.
const getAddressesFromData = R.pipe(
R.prop('data'),
R.pluck('address')
);
getAddressesFromData expects an object which's data key contains an array of objects. It returns a new array containing the values that belong to each of these objects' address keys.
Subsequently, we are going to write the fetch function.
https://medium.com/media/aa983f6151a87eefdc6da22b57d9dab5/href
We chain getAddressesFromData on our promise using .then. Notice how we also perform a type lift again.
We’ll also need to return a JSON response to our users. We can do that using res.json.
const jsonAddresses = ({ res, addresses }) => res.json({ addresses });
Wait a minute! Did we write three functions without unit tests? 😱
Yes, we did. 😏
The trick about testing a Lambda function — and async code in general — is to choose what to test and how. Generally, you only need integration tests for functions that have side effects. BUT, if you compose an async function with pure functions, you want to write unit tests for the pure functions. This way, when the integration test fails, but the unit tests pass you at least know where the error is NOT located. If both the integration test and the unit tests fail, the unit tests will identify the error for you.
fetchAddresses is the function containing the I/O, no unit tests needed here.
So why did we not test getAddressesFromData and jsonAddresses?
You can certainly make a solid argument for writing unit tests for them, too. But in this case, I chose not to. getAddressesFromData is composed solely out of well-tested Ramda functions with little specialization. Therefore, there is almost nothing that could go wrong. jsonAddresses, on the other hand, is also very simple and essential for our integration test. If that part fails, it will probably have a distinct error. In conclusion, not much is gained by writing unit tests for these two functions.
Notice how, depending on your function, you might not want to write any unit tests and just integration tests.
Now compose these functions to get our getAddresses function.
https://medium.com/media/a9aa1c859adc7d09339e2913471e8287/href
Run npm test.
TAP version 13
# /addresses
Missing x-apigateway-event or x-apigateway-context header(s)
ok 1 Given a GET request: should return an array of addresses
ok 2 Given a GET request: should return an array of addresses
# handleListen()
ok 3 Given a port of 8000 and a log() function: should call log() with 'Listening on port 8000.'
# liftReqRes
ok 4 Given a function, and two arguments (request and response): should lift the arguments into an object and invoke the function with it
1..4
# tests 4
# pass 4
# ok
Our integration tests and unit tests pass now! 🚀
If you liked this article, you might also like “How To Use AWS AppSync in Lambda Functions” because you are going to learn how to connect your Lambda functions to your AppSync API, making it more powerful.
Summary
We learned how to use function composition to make our code more modular. We wrote integration tests with Supertest and unit tests with RITEway for the Lambda function.
Note: This article was first posted on my blog. I publish each article two weeks later on Medium. You might want to subscribe to my newsletter because you will get content like this earlier! 💌
Originally published at https://janhesters.com.