In this short post, I wanted to go a little bit further and look at doing the same for react components. It's a common need for React developers to occasionally create wrappers for third-party components, to customize behavior that's re-usable within their applications.

But from time to time, you will come across third-party libraries that do not export types for their own component props, despite their existence.

What do you do in this case? You could manually annotate the types, but you run the risk of your types getting out of sync with the library's types if the library authors introduce breaking changes.

Fortunately for us, we have a better solution on our hands - the React.ComponentProps utility type. Let's see it in action.

Let's take the following component:

function HelloWorld({ name }: { name: string}) {
  // content of the component here, doesn't matter for the purpose of this article
}

As you can see, the types of props are inlined. Since this is in our control, we can refactor the props types to a reusable Typescript Type, but let's assume we can't and we wanted to re-use the prop types.

This is where React.CompoentProps comes in, and we can use it in combination with the typeof operator to  get the props type, as shown below:

type HelloWorldProps = React.ComponentProps<typeof HelloWorld>;

And in return, we get the following type back:

If you are interested, I wrote about the typeof operator, a while back in my All Things Typescript newsletter, you can find the article here.

And that's it. With a single Utility type - React.ComponentProps, we are able to fetch types from React Components and re-use them within our code with ease, giving us the flexibility to extend components as we need to.

Resources

• Looking up the Input and Output Types of a Function using the Parameters & ReturnType Utility Types
• Indexed Access Types in Typescript
• Using Zod Schemas as a Source of Truth for Typescript Types
• Typescript: How do you provide types for data from external sources?

But as your project grows, this can start to have negative impacts, for instance, slow deployment as Firebase has to build large functions, upload and figure out what changed and didn't change.

On top of that, it also makes it very difficult for multiple teams to work on the same project, making it hard to deploy and maintain, as teams work on their features.

Firebase Functions Codebases

So, how do you manage this? Firebase provides the concept of Firebase Functions Codebases, where Firebase functions can be organized into a collection in a way that makes sense to an organization, say a team owns them or by feature, and maintained and deployed together.

The functions collections can be in different repositories or in the same repository, in a mono-repo setup using something like NX in combination with the NX generator for Firebase that I built earlier this year.

Firebase codebase allows you to organize your Firebase functions collection in a way that makes sense to your organization. This could be by functionality or teams and so, allowing you to maintain and deploy them together.

By default, firebase has a single, default codebase, and your Firebase config file - firebase.json - looks like this.

{
  // ... other firebase services configurations i.e. hosting etc.
  "functions": [
    {
      "source": "dist/apps/functions",
      // default codebase
      "codebase": "default",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log"
      ],
      "predeploy": [
        "pnpm nx run functions:build"
      ]
    }
  ],
  "extensions": {}
}

We can configure a different codebase for our Firebase functions, for a second collection of functions by modifying the codebase property of one of our functions.

For instance, in the above example, we can add a second functions collection, with a different codebase, by adding a second config option to the functions property inside our firebase.json config file.

{
  // ... other firebase services configs
  "functions": [
    {
      "source": "dist/apps/functions",
      "codebase": "default",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log"
      ],
      "predeploy": [
        "pnpm nx run functions:build"
      ]
    },
     {
      "source": "dist/apps/functions",
      "codebase": "codebase-2",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log"
      ],
      "predeploy": [
        "pnpm nx run functions:build"
      ]
    }
  ]
}

In the case above, our different functions collections exist in the same repository - a mono-repo. We could have our functions collection exist in multiple repositories and in such cases, we would just need the only codebase inside the repository to be configured in our firebase.json config file.

{
  // ... other firebase services configs
  "functions": [
     {
      "source": "dist/apps/functions",
      "codebase": "codebase-2",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log"
      ],
      "predeploy": [
        "pnpm nx run functions:build"
      ]
    }
  ]
}

NB: Ensure that the codebase property is correct, as this could have unforeseen consequences, such as deleting other functions in the codebase that weren't found inside the repository.

Deploying your Functions

As always, firebase deploy and firebase deploy functions will deploy all Firebase functions within the current directory, in all codebases. On top of that, you can specify which codebase to deploy, by using the firebase deploy functions:codebase command.

firebase deploy functions:codebase

If your function collections are distributed in multiple repos, you can just use the firebase deploy command. Firebase CLI will not prompt you to delete existing Firebase function collections from other codebases.

But if your function collections are in a mono repo setup, you might find it beneficial to have your target to a specific codebase, instead of deploying all codebases within the mono repo.

firebase deploy functions:codebase

Firebase Functions NX Generator

For those of you using nx or want to use nx to manage your Firebase project, you might find it beneficial to try out the generator I created to create Firebase functions as NX apps. with full support for codebase - @nx-toolkits/firebase.  

Each Firebase functions codebase lives as an nx application, with all the benefits of NX such as codesharing between codebases and caching. For more information, check out this post about my motivations as to why I built the generator.

How it works

First, install the @nx-toolkits/firebase generator, using your favorite package manager.

// npm
npm i  @nx-toolkits/firebase

// yarn
yarn add @nx-toolkits/firebase

//pnpm
pnpm add  @nx-toolkits/firebase

To generate a function in the default codebase, just run the following command:

nx g @nx-toolkits/firebase:functions

NB: Please ensure that you have run Firebase initialization in the root directory of your project. In the future, I would like to be able to handle this as well.

This will create or override the default codebase application. To create an nx application, with a different codebase, just run the following command:

nx g @nx-toolkits/firebase:functions --codebase codebase-2

And that's it. Running the nx deploy command targeting the app you just generated, will only deploy functions of the correct codebase.

nx run my-functions-app:deploy

And that's it.

Conclusion

In this post, we looked at how we can use codebases in Firebase functions to organize our Firebase functions making it easy to maintain and deploy, as our app grows.

It's important for any project, to be able to enhance effectiveness and ensure different features can be developed and maintained with minimal conflicts and with speed.

Codebases make it easy for organizations to be able to decide how to organize Firebase functions as it makes sense to them, be it in a mono repo setup or even multiple repositories, so as to achieve business goals.

Resources

• Supercharge your Firebase App Development using NX
• The typeof and keyof operators - referencing variable types in Typescript
• Organize multiple functions
• Using Zod Schemas as a Source of Truth for Typescript Types
• My Blog is Overengineered

This is because when using Firebase CLI to scaffold Firebase functions, it usually creates a new Firebase directory with its dependencies isolated from the rest of the repository. There are good reasons for this, as Firebase needs to install packages consumed by your Firebase functions in the Firebase.

Installing NPM packages not being consumed by your functions would be less than ideal as it would slow down your deployments if they are too many. Imagine installing the dependencies for your Angular app to deploy your firebase functions. The impact wouldn't be negligible. Another disadvantage would be storage consumption, which could have unforeseen circumstances.

Disadvantages of The Default Setup

This kind of setup has a few disadvantages; the common one which I alluded to earlier, is code sharing between your frontend app and your Firebase functions. It's not impossible, but it may require you to do some work before making it work. Think of things like Types, Schemas, etc., which don't change whether they are consumed on the backend or the frontend. This can have unforeseen circumstances if they are out of sync.

The second is a smaller one; managing two sources of dependencies within your application will negatively impact the developer experience (DevX). You must ensure you switch to the correct directory to install dependencies, which requires some mental load. It would be much faster if we had a single source of truth.

And lastly has to do with caching build, lining, and testing results. For small applications, this doesn't matter, but for large applications, this could save you hours and hours, as a correct caching mechanism such as NX can allow you never to build, test, or lint on code that hasn't changed.

Nx Generator for Firebase - @nx-toolkits/firebase

Considering the above disadvantages, I have spent the last few days working on an NX generator for Firebase Functions - @nx-toolkits/firebase. I will expand this to include setting up hosting for NX apps in the future.

My goal was simple when using my NX generator; it would create a new NX app for Firebase functions, just like you would have an Express, React, NestJS, or Angular application. On top of creating an NX app, we would benefit from caching of linting, testing, and builds, and on top of that code, sharing that is enabled by NX mono repo, allowing you to share code between all your apps and libs.

In short, I am implying it needed to behave like any other NX app within your NX mono repo. Another goal I had in mind is to ensure that you can still use Firebase CLI as you would normally do, commands such as firebase deploy --only functions should work without you having to think.

And with those goals in mind, I went ahead and developed @nx-toolkits/firebase.

How does it work?

Just like any other NX plugin, we start by installing the plugin using NPM.

npm install -D @nx-toolkits/firebase

And once that has been installed, we can then go ahead and generate a Firebase functions app:

npx nx g @nx-toolkits/firebase:functions

You will need to provide the following options:

• name - Name of the NX App
• firebaseProject - the Firebase project id. This is optional if you already ran firebase init command in your project directory.
• codebase - This is a firebase config to organize Firebase functions collection when there are too many; please read the docs here for more information.
• nodeVersion - the runtime version of NodeJS for your Firebase function.

After generating the functions app, you can run the usual command with nx such as linting, testing, and building.

nx run my-functions-app:lint

And finally, you can deploy your Firebase app once you are done. There are two ways of doing this:

1. The first one is the common way to deploy firebase apps, using the firebase deploy command

firebase deploy --only functions

1. Or the second one is to run the NX executor to deploy the command.

npx nx run my-functions-app:deploy

Both of these commands work exactly the same way now, and none of them has an advantage over the other.

That's it; you have an NX app Firebase functions with all the benefits of NX at your Fingertips.

So, what's next for you

Try out the generator, and if you come across any bugs or have any ideas on areas of improvement, I would appreciate any feedback to improve this NX generator. You can find the source code here.

Conclusion

In this post, we saw how to supercharge your Firebase development experience using NX, and how we can bring the benefits of NX to Firebase app development and rip the benefits of NX. In the next few weeks, I will work on improving a few feature sets around hosting and functions, and if you have any feedback, please feel free to open an issue here.

NPM Imported Packages Lens Extension

Last week, I decided to do something about this. I created a VS Code Extension that will show you links to NPM, Github, and the Homepage (usually a docs site or GitHub ReadMe of the project) for an imported package right there in the Typescript/Javascript file. Click on whichever you want to open, and you will land on the correct page without the mental model involved in my previous process.

The extension currently shows three links: NPM, GitHub, and Homepage, and all of these are pulled from NPM for the latest version of the package - I will try and address the versioning issue as time goes on especially for the link to the Homepage. And the extension currently works for ES modules for Typescript, Javascript, and JSX/TSX files; I hope to add support for other frameworks such as Vue, Svelte, and Astro in the near future.

You can install the extension from here and find the Github repository here (please leave a star ⭐). Thank you.

Due to how trends work, it is easy for methods/tools to go out of fashion. This is not because it is less effective but because developers stop using them in favor of something else. This is what happened with Multi-Page Applications (MPAs), as developers started adopting popular web frameworks such as Angular, React, Vue, etc. This led to an uptick in SPA usage as the frameworks became more popular.

Due to how SPAs work, the impact has been that the amount of Javascript we ship to the browser has increased. i.e., you can't have a react web app without React to manage state and rendering. SPAs use Javascript to render the HTML to be displayed in the browser. In many cases, this makes sense, for instance, in web apps such as Facebook or YouTube, where managing the state is paramount. But in other cases, this does not make sense, for example, blogs, personal portfolios, etc.

Server-Side Rendering

When using a framework such as Angular or React and SPAs in general, the server does very little; all the rendering is done on the Client-Side, in what is known as Client-Side Rendering. To see the content, you first have to download the framework's runtime (JS needed to scaffold your web app) and also need an environment to render the content, i.e., the browser.

This has a few downsides, the notable ones being it's slow to show something on the screen, the impact of this is worse on low-end devices and slower internet connection and Search Engine Optimization - bots and crawlers are usually unable to render these pages and can't parse the content to show results.

We have two standard solutions to solve the above problems: Server-Side Rendering (SSR) and Rendering during build time - SSG. SSG is similar to SSR but at build time, removing the need to render on every request at the server. SSG is common for sites whose content isn't that dynamic. The problem with these two solutions is that they don't solve the problem with SPAs but rather postpone it.

If you want any sort of interactivity, say opening and closing the navbar on your web app, you will need to hydrate your rendered app from either SSG or SSR. This is the process of bootstrapping the framework you are using, transferring the state from the server so that the framework can take over. This usually happens after the first content is painted (after rendering the server-side rendered HTML from the server) but before the interactivity in your web app.

This means the JS needed by your framework has to be downloaded and parsed, and the user has to wait for all that to happen to interact with your web app. This would mean even on pages where you don't need interactivity, i.e., About Us Page, Terms and Conditions, etc., you still need to do all that, which is a bit unnecessary.

Islands

And this is where Islands Architecture comes in. Imagine this; what if you could create your web app with pure HTML and CSS for all the static content but then add in regions of dynamic content or interactivities - islands - that can use a framework to add interactivity. These regions would use any framework, and the framework runtime would only be downloaded only when on a page that uses it rather than on the initial load of the website.

Web frameworks such as Astro (My website is built with Astro), Marko, and most recently Qwik, among others, are implementing this architecture method. In the case of Astro, you have Astro components that use some variation of JSX but do not have a client-side state, so there is no runtime.

Astro

Astro uses the concept of JS opt-in, meaning by default, no Javascript is generated unless you tell Astro to include javascript. You can then either use Vanilla JS to include Javascript - the old fashioned way, as shown below:

<script>
  document.getElementById("menuToggle").addEventListener("click", () => {
    const collapsibleMenu = document.getElementById("collapsibleMenu");
    collapsibleMenu.classList.toggle("navbar-menu-show");
    collapsibleMenu.classList.toggle("navbar-menu-hidden");
  });
</script>

Astro components cannot be hydrated as they are HTML only templating components and any Javascript needs to be included as indicated above or via a framework such as React, SolidJS, etc.

The second option is to bring your framework, for example, React, Preact, Lit, Svelte, Vue, etc., to create components that add regions of interactivity (islands) in your web app.

// index.astro file
---
import ReactComponent from "./ReactComponent"

---

<ReactComponent />

You are also in control of when the necessary region is hydrated. This is done via directives that instruct Astro when to perform hydration. For instance, you might want an island to be hydrated on load or only when it becomes visible. There are several directives to help you achieve this, which you can learn more about here.

// index.astro file
---
import ReactComponent from "./ReactComponent"

---

<ReactComponent client:visible />

Marko and Qwik

While I am not an expert at either Marko.js or Qwik (the new kid in the block), I will link additional resources below if you are interested in learning more. Marko and Qwik take the concept of islands a little further when compared to Astro.

Marko is an MPA framework, and its Island architecture is a bit smarter in that it automatically decides to load JS needed for an Island, delaying it as far as possible, allowing for far more efficient islands. This is unlike the current Astro approach, which relies on the developer to tell Astro when to do hydration. Astro is still in the pre-release stage, and maybe this will change in the future.

Another key advantage Marko has over Astro is that Marko decides what is inside the Islands and what's not in it. This means components such as footers, headers, etc., that only display static content don't become islands, while forms and other rich components with dynamic content become islands that can be hydrated.

Qwik, on the other hand, takes this to a component level, breaking down how hydration is done so that it is done only when needed. This is achieved by aggressively breaking apart your website's JavaScript into multiple chunks, setting up global event listeners, and serializing points of interest directly into the HTML. For each distinct user interaction, Qwik has all it needs to load only the code required to perform the action and nothing more.

In return, this leads to smaller chunks, which are faster to load, parse and load only what the user needs. This is known as progressive hydration, which is out of scope for this article, and hopefully, I will write about it soon.

Conclusion

This article looked at Islands Architecture, why they exist, and the frameworks currently applying them. In the next series of articles, I want to dig deeper into the frameworks mentioned above - Astro, Marko, and Qwik, plus other frameworks such as Svelte, Angular, and React and how they differ internally from each other.

Resources

1. Why Progressive Hydration is Harder than You Think
2. From Static to Interactive: Why Resumability is the Best Alternative to Hydration
3. JavaScript vs. JavaScript. Fight!
4. Why Efficient Hydration in JavaScript Frameworks is so Challenging
5. Resumable JavaScript with Qwik
6. Conquering JavaScript Hydration Event delegation is the key to not running over the component... Apr 15
7. State of JavaScript 2021: Framework Reflections
8. A first look at Qwik - the HTML first framework WRITTEN BYMIŠKO HEVERY JULY 2, 2021

It's pretty common nowadays to find web developers specializing in a single framework. While there is nothing wrong with that, as long as you stick to its strengths, i.e., the right tool for the right job. The saying goes, "when you have a hammer, everything is a nail," and I have seen frontend developers who want to use the only Framework they know for everything, despite it not being the right fit for the task at hand.

Some Background

Before I can go any further, let me give you some context. I am from Kenya, and most of my friends have $200 or lower smartphones, and about half of those have a $100 or lower smartphone; some don't even have smartphones. This means the devices most of my friends own are quite limited performance-wise. And this is one crucial area we as developers need to understand as we tend to have more powerful devices at our disposal.

The other thing to be aware of is the state of internet connectivity. It's pretty decent, maybe even good, in some areas, primarily Urban areas, but the speed and reliability fall off the cliff when you start heading to informal settlements and rural areas. This trend can be replicated all over Africa, and I believe in large parts of the world.

Performance

So, why am I telling you this? When it comes to performance, you need to approach it in two folds: First, the number of KBs the user has to download and the device's capability the user has. The internet speed is impacted by the device in question capabilities, not just the internet coverage. Users with low-end devices tend to also live in areas with poor internet coverage and connectivity.

The more the KBs your JS script is, the longer it will take to download the script before we can get to parsing, which will also be slower due to device capability limitations. As you can imagine, both of these can take a frustrating longer time on a low-end device on a slow network. When we develop poor-performing websites, i.e., takes longer to load, huge scrips that take a toll on the processor and battery life, we negatively impact our users, especially the already disadvantaged.

When I am using my iPhone 13 Pro Max (or whatever the latest model is as you are reading this) on the latest 5g network, I will probably notice slow performance, but it will be a minor inconvenience. However, for someone on a $100 or lower smartphone on a slow network, the impact on performance will be huge. We have all been there, trying to load a website that refuses to load or is laggy either due to poor network connection or the toll the website places on both memory and the process. This could mean the difference between someone getting life-saving information in time or not getting it.

SPAs

One of the most popular ways of developing websites is using Single Page Applications (SPAs) frameworks popularized by React and Angular. These SPA frameworks have become a go-to for developers due to their excellent developer experience and ease of building websites, but this comes at a performance cost. SPA applications need to be bootstrapped, which means you ship your site in JavaScript for the browser to download, parse and render your website in what is known as Client-Side Rendering (CSR).

So, to recap, the user not only needs to download the Framework Code + your Application code, but they also need the browser to parse it before they can see content on your site. Depending on the size of the Framework and other libraries' sizes, this can quickly balloon to MBs of data.

Due to the above issues, we have come up with techniques to try and show the content as soon as possible such as Server-Side Rendering (SSR) and Static Site Generation (SSG). But these are not perfect solutions. They both need to put the Framework back into the rendered HTML after the initial content has been displayed for any interactivity, in a process called hydration.

This is okay (ish) if you are building a web app such as Facebook or YouTube (guess who is behind two of the most used SPA frameworks), where once the site loads, you can access a bazillion of content without having to load the site again. The examples I mentioned above behave more like apps than traditional websites.

In such instances, I may be okay paying the upfront tax, but subsequent navigations are faster, and requests and data exchange between the server and the client is more efficient. This, of course, is computationally expensive as the Framework in question has to update the DOM to create and removes nodes so that views can change.

But what if all I wanted to access was information on a single page? Think of a blog post or some instruction on applying for a government grant or social benefits. Do I have to download and run a whole web app to access this information?

As you can imagine, this can be very painful, especially for government sites, NGOs, and business services whose customer base has users with poor internet coverage and low-end devices or a combination of both.

To be honest, this should extend to everyone, no matter the internet connection speed or kind of device I have; I shouldn't have to download tons of JS code just to read your blog post.

In Conclusion

So, where am I going with this? The title of this article is "The Right Tool for the Right Job." I mean that as developers, we need to think about our users and the purpose of what we are building before choosing the tools to use. Whatever tools and frameworks we use, we need to emphasize more on the user experience we are providing. This means that we need to learn to have more than one tool in our toolkit and be open to learning more. Lately, we have seen an uptick in frameworks and libraries geared towards 0KB Javascript without sacrificing developer experience. I believe every front-end developer should know at least one.

We have a lot of tools at our disposal from SPAs frameworks such as Angular, React, Vue, etc., which have their use cases but should not be used for everything. On the other hand, we have frameworks and tools for building Multi-Page Applications (MPAs) and Static Sites, such as Astro, Hugo, Jekyll, etc., that are designed for shipping as little Javascript as possible while providing incredible speeds most SPAs frameworks can only dream off.

My point is as a developer; you should make sure you have a few of these tools in your tool kit; this will ensure that whenever you are choosing, you choose the right tool for the job.

Having worked with NodeJS based frameworks and frontend frameworks such as Angular and React, most (if not all) come with live reloading built-in. Some frameworks such as Flutter take this a little further with stateful hot reloading, which I won't go into details about.

Having switched to using Golang recently, I realized I needed to solve this problem. Lucky for me, there are a few great options out there to enable this behavior. One of them is the Air (github.com/cosmtrek/air) - a live reloading tool for Golang apps.

Installing Air

First, we are going to install air. There are a number of ways to install air, but the way I did it was using go install as I had Golang already installed:

go install github.com/cosmtrek/air@latest

There are a number of other installation options that you can find here.

Configuring Air

Next, we need to configure Air for our Golang project. You can do that by running the following command:

air init

This will create a air.toml file that will contain the default configurations for Air. Here is an example of what that looks like:

root = "."
testdata_dir = "testdata"
tmp_dir = "tmp"

[build]
  bin = "./tmp/main"
  cmd = "go build -o ./tmp/main ."
  delay = 1000
  exclude_dir = ["assets", "tmp", "vendor", "testdata"]
  exclude_file = []
  exclude_regex = ["_test.go"]
  exclude_unchanged = false
  follow_symlink = false
  full_bin = ""
  include_dir = []
  include_ext = ["go", "tpl", "tmpl", "html"]
  kill_delay = "0s"
  log = "build-errors.log"
  send_interrupt = false
  stop_on_error = true

[color]
  app = ""
  build = "yellow"
  main = "magenta"
  runner = "green"
  watcher = "cyan"

[log]
  time = false

[misc]
  clean_on_exit = false

[screen]
  clear_on_rebuild = false

Next, let me highlight a few notable configurations you might care about and might want to update for your project.

Under build in the air.toml; you might want to change the cmd property. If the entry of your golang application is in a different directory, say server, you can change the property to something like this:

cmd = "go build -o ./tmp/main ./server/main.go"

Another set of config properties that you might want to pay attention to are the include_dir, include_ext, exclude_dir and exclude_file entries. The include_dir and include_ext tell Air which dir and extensions to watch for changes when live reloading, while the exclude_dir and exclude_file tell air which directories, extensions, and files not to listen to changes from.

There is also the exclude_regex property that allows you to ignore files matching a certain pattern, i.e. test files as it does by default. These configs allow you to configure Air based on your app structure.

For more information about Air configurations, please refer to the example file here.

Running your App

Finally, the only part that is remaining is running our Golang application using Air. You can do this by running the air command:

air

After that, make changes to your project and watch air live-reload your Go application.

Conclusion

In this article, we learned how we can use Air to live-reload our go applications as we make changes to our codebase. We learned how we can initialize, the configuration we might want to change, and how to start our application afterward.

To continue learning more about Air, visit the Github repository here.

Busy TypeScript Developer's Guide to the TypeScript Type System

About the Talk

TypeScript is a strongly typed language that compiles to JavaScript. The key difference between TypeScript and JavaScript is the Type System, which enables developers to write type-safe programs with fewer errors and bugs. In this session, we will look to understand the TypeScript Type System and the features and tooling TypeScript provides us to write more concrete types.

Web Rush Episode 173: Getting the Best out of TypeScript with Maina Wycliffe

EPISODE SUMMARY

Maina Wycliffe talks with us about how to write better TypeScript. How does he decide when to use TypeScript? How do you deal with null? Are TypeScript Enums bad? What are our pet peeves in TypeScript? And thoughts on creating a type from another type.

EPISODE NOTES

Recording date: Feb 17, 2022

John Papa @John_Papa

Ward Bell @WardBell

Dan Wahlin @DanWahlin

Craig Shoemaker @craigshoemaker

Maina Wycliffe @mwycliffe_dev

Brought to you by

AG Grid

Narwhal

Visit nx.dev to get the preeminent open-source toolkit for monorepo development, today.

Resources:

• Yes, Bradley Cooper does voice Rocket
• AngularJS
• Angular
• TypeScript
• Nairobi, Kenya
• Basic types in TypeScript
• Non-null assertion operator in Typescript
• Union types in Typescript
• Enums in Typescript
• Kevin Chisholm
• Creating types from types in TypeScript
• Utility types in Typescript
• Type Assertions in TypeScript - why not?

Timejumps

• 01:03 Ward's haircut
• 02:06 Guest introduction
• 03:40 What made you want to use TypeScript?
• 05:51 How do you decide when to use TypeScript?
• 09:08 Sponsor: Ag Grid
• 10:07 How do you deal with null in TypeScript?
• 14:37 Are TypeScript enums are bad?
• 20:12 What are your pet peeves in TypeScript?
• 21:36 Sponsor: Nx
• 22:12 What's your second pest peeve?
• 27:25 Why would you create a type from another type?
• 35:52 Final thoughts

Podcast editing on this episode done by Chris Enns of Lemon Productions.

Object properties are Readonly

When you cast an object as const, the properties are marked as read-only and cannot be modified. Let's take the following variable person with name and age in it.

const person = {
    name: "John Doe",
    age: 25,
};

Its types are inferred as string and number as expected:

But if we assert it as const, the inferred types for the person object are marked as read-only and cannot be modified.

const person = {
    name: "John Doe",
    age: 25,
} as const;

If we tried to update the age field, we would get the following error: Cannot assign to 'age' because it is a read-only property

Arrays become Readonly Tuples

In my last article, we looked into tuples, which you can learn more about here. const assertions on an array allow us to mark an array as read-only Tuple i.e. content of the array in each position becomes a literal type that cannot be modified.

Let's take the following variable personNameAge, a normal array with the name at the first position and age at the second position:

const personNameAge = ["john doe", 25]

Typescript will infer this as an array of strings or numbers i.e. (string | number)[]:

But, if we used as const assertions, this becomes restricted to a readonly Tuple, with "john doe" in the first position and "25" in the second position:

And its values cannot be modified:

A variable value should be treated as Literal Type

Literal types allow us to define types that are more specific, instead of something that is generalized like string or number. For example:

type Switch: "On" | "Off";

const assertions allows us to mark a variable value as a literal type. For instance, if we had a variable onSwitch and assigned the value on, normally typescript will infer the type of the variable as a string:

But, if we used const assertions, it will be inferred as a literal type of On:

And cannot accept any other variable apart from On:

One thing to keep in mind is that const assertions can only be applied to simple expressions. So you can not do something like this:

function switchValue(input: boolean) {
    let onSwitch =  (input ? "On" : "Off") as const; // Won't work
    return onSwitch;
}

The above will throw an error: A 'const' assertions can only be applied to references to enum members, or string, number, boolean, array, or object literals.

To solve the above issue, we need to apply const assertions on each output value of our ternary operator:

function switchValue(input: boolean) {
    let onSwitch =  input ? "On" as const : "Off" as ;
    return onSwitch;
}

And the type of onSwitch variable get inferred to a literal type union On | Off:

Conclusion

In this article, we looked at const assertions and how we can use it within our code. We learned that we can use it to mark an object field as read-only, create a read-only Tuple, and mark a variable's value as a Literal type instead of widening it to its based type i.e. string, number, etc.

Thank you for reading this article, if you are interested in more typescript content, check out my previous articles here, follow me on Twitter and LinkedIn. And you can also join my new community on Twitter for all Typescript developers, where we can learn, share and connect with each other.

This is where a Tuple differentiates itself from an array. In a tuple, the type of each element, the length of the array, and the order in which the elements are ordered in the array are important. I.e. it should always return an array of length 2, with the first element being a string and the second element being a number.

To define a Tuple type, we use syntax similar to Javascript array syntax but instead of specifying the values, we specify the type in each index location, as shown below.

type PersonNameAge = [string, number];

In the example above, we are defining a Tuple type PersonaNameAge, as an array of length two, with the first element being a string for persons' name, and the next element being a number for persons' Age.

We can then go ahead and use the above tuple as follows:

const personNameAge: PersonNameAge = ["John Doe", 25] // this doesn't throw an error

If we don't provide enough elements matching the length of fields defined in the PersonNameAge tupple, then Typescript will throw the following error:

const personNameAge: PersonNameAge = []

// Error:
Type '[]' is not assignable to type 'PersonNameAge'.
  Source has 0 element(s) but target requires 2.

// the same thing happens if provide more elements
const personNameAge: PersonNameAge = ["John Doe",25, true]

// ERROR:
Type '[string, number, number]' is not assignable to type 'PersonNameAge'. 
  Source has 3 element(s) but target allows only 2.

And if we specified the types not matching the types specified in their index location, Typescript will throw the following error:

const personaNameAge: PersonNameAge = [25,"John Doe"]
                                            ~~ ERROR: Type 'string' is not assignable to type 'number'.(2322)

Why Tuple

Tuples have several benefits, the first one being able to return more than one value from a function. Take for instance the following function:

function doSomething(): [string, number] {
    // do something
}

It can return two values, a string and a number, which the caller can assign to variables. This leads to the second benefit, being able to destructure them easily to a variable name of choice i.e. being able to assign the return values of the tuple directly to their variables as shown below.

const [str, nmb] = doSomething();

If you returned an object instead of a tuple, destructing takes an extra step of needing to rename the field, especially if there is a variable name collision. You can also ignore the return type of Tuple by using an underscore (_) character if you wanted to access the value of a variable that is in a much higher index position.

const [_, nmb] = doSomething();

Examples of Tuples in Action

In this section, I thought it was prudent to highlight a few places where tuples are in use out in the wild:

Promise.all()

The Promise.all() method takes an iterable of promises as an input, and returns a single Promise that resolves to an array of the results of the input promises. - MDN Docs

This is a perfect use case of Tuples return type as each promise resolved is returned at the index position it was in inside the input. So, an input of promise a,b,c returns results of the promises of a,b,c in their respective index position in which they were in the input.

async function apiCall1() {
    return "";
}

async function apiCall2() {
    return 1;
}

async function apiCall3() {
    return false;
}

async function main() {
    const x = await Promise.all([apiCall1(), apiCall2(), apiCall3()])
}

The type of valuable x will be a Tuple: [string, number, boolea]:

We can destructure the above Promise.all() as follows, with each variable getting assigned the correct types.

const [str, num, bool] = await Promise.all([apiCall1(), apiCall2(), apiCall3()])

React - useState

Another use case can be found in React hooks - useState. useState is used to declare a state variable in react functional components and returns a tuple of value and a dispatch function to update the state variable.

const [count, setCount] = useState(0);

In the above example, the count variable is a number and the setCount variable is a dispatch function whose input parameter accepts a number. This allows you to have multiple state variables which are easily assigned unique variable names using array destructuring, as shown below:

const [count, setCount] = useState(0);
const [name, setName] = useState("John Doe")

There are other use cases but these are the most common ones I could come up with.

Conclusion

In this article, we covered the Tuple type in typescript, how and why we should use them. Tuples are special arrays that have their length predefined and the types at each index position of the array being predetermined and may vary from one index position to another. On top of that, we covered two particularly common use cases for Tuples and saw how we benefit from this Tuples usage in the real world.

Thank you for reading this article, if you are interested in more typescript content, check out my previous articles here, follow me on Twitter and LinkedIn. And you can also join my new community on Twitter for all Typescript developers, where we can learn, share and connect with each other.

Prerequisites

• Prior knowledge in MongoDB, Go, and Docker.
• Docker: You can find installation instructions can be found here.
• Golang: You can find installation instructions can be found here.

Getting Started

In this tutorial, we will run how we can use dockertest to write tests for our MongoDB database.

To demonstrate how to use dockertest for testing, we will build a very barebone todo app backend. It will have a few methods that will use MongoDB to store and retrieve the todos. We will have a few methods: AddTodo, DeleteTodo, GetTodo, ListTodos and ToggleTodo and here is the code implementation of the above methods:

package todos

import (
	"context"

	"github.com/mainawycliffe/todo-dockertest-golang-mongo-demo/model"
	"go.mongodb.org/mongo-driver/bson"
	"go.mongodb.org/mongo-driver/bson/primitive"
	"go.mongodb.org/mongo-driver/mongo"
)

type Todos struct {
	client *mongo.Client
}

func (todos *Todos) AddTodo(todo model.Todo) (model.Todo, error) {
	collection := todos.client.Database("todos").Collection("todos")
	result, err := collection.InsertOne(context.Background(), todo)
	todo.ID = result.InsertedID.(primitive.ObjectID)
	return todo, err
}

func (todos *Todos) DeleteTodo(id string) error {
	collection := todos.client.Database("todos").Collection("todos")
	objectID, err := primitive.ObjectIDFromHex(id)
	if err != nil {
		return err
	}
	_, err = collection.DeleteOne(context.Background(), model.Todo{
		ID: objectID,
	})
	return err
}

func (todos *Todos) GetTodo(id string) (model.Todo, error) {
	todo := model.Todo{}
	collection := todos.client.Database("todos").Collection("todos")
	objectID, err := primitive.ObjectIDFromHex(id)
	if err != nil {
		return model.Todo{}, err
	}
	err = collection.FindOne(context.Background(), bson.M{
		"_id": objectID,
	}).Decode(&todo)
	return todo, err
}

func (todos *Todos) GetTodos() ([]model.Todo, error) {
	collection := todos.client.Database("todos").Collection("todos")
	cursor, err := collection.Find(context.Background(), bson.M{})
	if err != nil {
		return nil, err
	}
	var todoList []model.Todo
	if err := cursor.All(context.Background(), &todoList); err != nil {
		return nil, err
	}
	return todoList, nil
}

func (todos *Todos) ToggleTodo(id string) error {
	collection := todos.client.Database("todos").Collection("todos")
	objectID, err := primitive.ObjectIDFromHex(id)
	if err != nil {
		return err
	}
	todo, err := todos.GetTodo(id)
	if err != nil {
		return err
	}
	_, err = collection.UpdateOne(context.Background(), bson.M{
		"_id": objectID,
	}, bson.M{
		"$set": bson.M{
			"isDone": !todo.IsDone,
		},
	})
	return err
}

Now that we have our barebone todo app backend, let's write tests for it using dockertest. The first thing we are going to do is install dockertest by running the following command:

go get -u github.com/ory/dockertest/v3

Setup and Teardown using TestMain

We are going to be using TestMain to set up our MongoDB container using dockertest for testing and remove the container after we are done running the tests.

TestMain in Go provides us with more control on how our tests are run, in our case, allowing us to use dockertest to set up a MongoDB container and connect to it and after the tests have run, remove it. This ensures that for every test we run, we have a fresh database to run tests against that is not contaminated by test data from the previous tests.

Setup MongoDB Docker Container

We are going to start by defining a database client variable to store the MongoDB connection to the test database that will be spun up. We will pass this client to the Todo struct that we will create when running the tests.

var db *mongo.Client

func TestMain(m *testing.M) {
  // setup and teardown code goes in here 
}

Next, inside the TestMain function, we are going to create a new Pool. A Pool is a dockertest struct that represents a connection to the Docker API and is used to create and remove the docker container when running tests.

pool, err := dockertest.NewPool("")

if err != nil {
	log.Fatalf("Could not connect to docker: %s", err)
}

NB: Please make sure to import dockertest properly - to include the version of dockertest: github.com/ory/dockertest/v3 and not github.com/ory/dockertest as VS Code might import it.

And then, we are going to define a few environment variables that will be passed to our MongoDB containers. For the MongoDB container, we need to pass the MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD which are going to set the credentials for the superuser for our MongoDB Database. The environment variables are defined as a String Array, with each entry of the array being a string in the following format: KEY=VALUE.

environmentVariables := []string{
	"MONGO_INITDB_ROOT_USERNAME=root",
	"MONGO_INITDB_ROOT_PASSWORD=password",
}

Next, we need to create a docker container using the pool.Run function which accepts the docker image to use, the tag, and the environment variables we defined above.

resource, err := pool.Run("mongo", "5.0", environmentVariables)
if err != nil {
	log.Fatalf("Could not start resource: %s", err)
}

And the final step for the setup is to try and connect to our MongoDB container and we will do this by creating a database client and pinging our database to ensure we can connect to our MongoDB container successfully.

if err = pool.Retry(func() error {
	var err error
	db, err = mongo.Connect(
		context.TODO(),
		options.Client().ApplyURI(
				fmt.Sprintf("mongodb://root:password@localhost:%s", resource.GetPort("27017/tcp")),
		),
	)
	if err != nil {
		return err
	}
	return db.Ping(context.TODO(), nil)
}); err != nil {
	log.Fatalf("Could not connect to docker: %s", err)
}

After that, we can seed our database with test data if we have any. And then we can run our package tests by calling m.Run().

// seed data

// Run tests
exitCode := m.Run()

Teardown

Once our tests are all done, we are going to kill and remove the container.

if err = pool.Purge(resource); err != nil {
	log.Fatalf("Could not purge resource: %s", err)
}

And finally, we can call os.Exit() passing the exit code from m.Run() above.

os.Exit(exitCode)

And that's it for our TestMain, here is what the method should look like now:

var db *mongo.Client

func TestMain(m *testing.M) {
	// Setup
	pool, err := dockertest.NewPool("")
	if err != nil {
		log.Fatalf("Could not connect to docker: %s", err)
	}
	
	environmentVariables := []string{
		"MONGO_INITDB_ROOT_USERNAME=root",
		"MONGO_INITDB_ROOT_PASSWORD=password",
	}
	
	resource, err := pool.Run("mongo", "5.0", environmentVariables)
	if err != nil {
		log.Fatalf("Could not start resource: %s", err)
	}

	// exponential backoff-retry, because the application in the container might not be ready to accept connections yet
	if err = pool.Retry(func() error {
		var err error
		db, err = mongo.Connect(
			context.TODO(),
			options.Client().ApplyURI(
				fmt.Sprintf("mongodb://root:password@localhost:%s", resource.GetPort("27017/tcp")),
			),
		)
		if err != nil {
			return err
		}
		return db.Ping(context.TODO(), nil)
	}); err != nil {
		log.Fatalf("Could not connect to docker: %s", err)
	}

	// seed data

	// Run tests
	exitCode := m.Run()

	// Teardown
	// When you're done, kill and remove the container
	if err = pool.Purge(resource); err != nil {
		log.Fatalf("Could not purge resource: %s", err)
	}

	// Exit
	os.Exit(exitCode)
}

Next, let's write a few tests for our code:

Writing Tests Against MongoDB

We will start by writing the simplest one, the AddTodo test. We are going to add a todo and then assert that error is nil and also check in the database to make sure that the todo exists in the database:

func TestAddTodo(t *testing.T) {
	todos := Todos{
		client: db,
	}
	createdAt := primitive.Timestamp{
		T: uint32(time.Now().Unix()),
		I: 0,
	}
	todo := model.Todo{
		Todo:      "test",
		IsDone:    false,
		CreatedAt: createdAt,
		UpdatedAt: createdAt,
	}
	// add todo
	todo, err := todos.AddTodo(todo)
	// assert error is nil
	assert.Nil(t, err)
	// assert todo ID is not not nil
	assert.NotNil(t, todo.ID)
	// fetch todo from the database
	todoGet, err := todos.GetTodo(todo.ID.Hex())
	// assert error is nil
	assert.Nil(t, err)
	// assert todo is equal to the todo returned from the database
	assert.Equal(t, todoGet, todo)
}

For the GetTodo test, we are going to add a new todo first and then use GetTodo method to retrieve the todo we added and assert that they are Equal:

func TestGetTodo(t *testing.T) {
	todos := Todos{
		client: db,
	}
	createdAt := primitive.Timestamp{
		T: uint32(time.Now().Unix()),
		I: 0,
	}
	todo := model.Todo{
		Todo:      "Test Get Todo",
		IsDone:    false,
		CreatedAt: createdAt,
		UpdatedAt: createdAt,
	}
	todoAdd, err := todos.AddTodo(todo)
	assert.Nil(t, err)
	todoGet, err := todos.GetTodo(todoAdd.ID.Hex())
	assert.Nil(t, err)
	assert.Equal(t, todoGet.Todo, todo.Todo)
}

And the final test I want to focus on is the test for ToggleTodo which marks a todo as done or vice versa based on the current status. In this one, we are going to add a todo and then toggle, retrieve it from the database and then check IsDone is not equal to the original IsDone property.

func TestToggleTodo(t *testing.T) {
	todos := Todos{
		client: db,
	}
	createdAt := primitive.Timestamp{
		T: uint32(time.Now().Unix()),
		I: 0,
	}
	todo := model.Todo{
		Todo:      "Test Toggle Todo",
		IsDone:    false,
		CreatedAt: createdAt,
		UpdatedAt: createdAt,
	}
	todoAdd, err := todos.AddTodo(todo)
	assert.Nil(t, err)
	err = todos.ToggleTodo(todoAdd.ID.Hex())
	assert.Nil(t, err)
	todoGet, err := todos.GetTodo(todoAdd.ID.Hex())
	assert.Nil(t, err)
	assert.NotEqual(t, todoGet.IsDone, todo.IsDone)
}

The rest of the tests can be found here on GitHub.

Conclusion

In this article, we learned how we can use dockertest to create MongoDB containers that we can write tests against. Dockertest uses docker to create a test container during the setup process and remove the docker container after all tests have run ensuring a sanitized test Database every time.

For more information on dockertest, you can find the repository here.

Source Code

You can find the source code for the examples given in this article here.

So, what are Type Assertions? Types assertion is a way of telling Typescript what the type of a variable is. This can be done either of two ways: using the as syntax or the angle bracket <Type> syntax, as shown below:

type Person = {
    firstname: string;
    lastname: string;
}

// using as syntax
const x : unknown = {};

// asserting it as Person using as syntax
const firstname = (x as Person).firstname;

// asserting it as Person using the angle brackets
const firstname = (<Person>x).firstname;

When we use type assertion we are basically telling the Typescript compiler that we know what the type is and it should trust us, i.e. we know what we are doing. The problem with this is that we prevent Typescript from helping us where it should and take on that responsibility ourselves.

In the above example, Typescript does not type check whether the variable x has the property firstname we are accessing because we are asserting the type, which will definitely introduce a bug into our system.

Non-null Assertions

Another common type of assertion is a non-null assertion. In this assertion, we use the ! operator after variable to tell the Typescript compiler that a variable isn't null.

function square(x: number) {
	return x * x;
}

const x : number | undefined;

const answer = square(x!);

This assertion should be used sparingly, especially if the null suggestion is coming from external API typing like environment variables, which are always typed as string | undefined. I have come across not-so-obvious bugs that were thrown in a completely different section of the code with a different error message because I allowed an undefined variable to be passed on. This happened because instead of handling the possibility of the environment variable being undefined, I decided non-null assertion was the way to go.

So, what are the Alternatives?

Narrowing of Types

Type narrowing is the process of moving a less precise type to a more precise type. For instance, taking a variable of type any and moving it to string. There are various ways of achieving this, which I have covered previously here, but I will take a look at a few notable ones.

Type Guards: You can use Type Guards to narrow the types of a union, unknown, any, etc. to a specific type:

function doSomething(x: string | number) {
    if(typeof x === "string") {
    	// do somethign with the string
    } else {
    	// do something with the number
    }
}

Truthiness Narrowing: You can check if a variable is truthy i.e. not undefined or null before using it:

function doSomething(x?: string) {
	if(x) {
		// type of x is now string
	}
}

Building Custom Type Guards: And finally, you can create type guards that do an exhaustive type checking on an object before asserting its type:

function isRectangle(shape: unknown): shape is Rectangle {
  if ("width" in shape && "height" in shape) {
  	// this is a rectangle
  	return true; 
  }
  // it's not a rectangle
  return false;
}

You can learn more about custom-type guards here.

You can learn more about the narrowing of types in Typescript in my previous article here.

Providing Default Values

This mostly works with null and undefined values, but instead of asserting to a string to remove the possibility of it being undefined, you can provide a default value that automatically becomes a string. You can achieve this by using either null coalescing operator (??) or the or ( ||) operator.

// using the nullish coalescing operator
const API_URL = process.ENV.API_URL ?? "DEFAULT URL";

// using the OR (||) logical operator
const API_URL = process.ENV.API_URL || "DEFAULT URL";

We can also use Javascripts Logical Assignment Operator to provide a default value:

let x : string | number;

// provide a default value if null or undefined
x ??= "Hello World"

// provide a default value if falsy
x ||= "Hello World"

Conclusion

In this article, we learned that by using type assertions, we are removing the ability of the Typescript compiler to do Type checking for us. We also covered a few techniques we can use to avoid type assertions in Typescript.

If you liked this article and would like to keep learning, visit my new series on Typescript - A Byte of Typescript. A Byte of Typescript is a new series that I will be publishing on a regular basis to help you demystify Typescript.

This is an extension of that but instead of having a concrete literal type, you can use a non-concrete literal type i.e. string, number, etc instead as part of the template literal type, and Typescript will be able to use it as a discriminant.

In order to understand this feature, we are going to start by creating two types: SuccessType and ErrorType. They are going to represent possible responses for different operations we can perform in a computer system i.e. HTTP Request, FTP Request, IO Request, etc. So, if an HTTP request succeeds we get a SuccessType data, if it fails we get an ErrorType data.

For the two types, each will have a type property, which we can use to discriminate between the two types when they are used in a union i.e. ResponseType union. But Instead of using a concrete literal type, we will use a template string type instead.

This means that the resulting template literal type could be any string combined with Success or Error  i.e. ${string}Success and ${string}Error. This will allow our success type to cover a number of possible operations like httpSuccess, ftpSuccess, etc. and the same goes for ErrorType.

type SuccessType = {
    type: `${string}Success`,
    data: Record<string, unknown>;
}

type ErrorType = {
    type: `${string}Error`,
    message: string;
}

type ResponseType = SuccessType | ErrorType;

function processHTTPResponse(response: ResponseType) {
    // function body here
}

In previous versions, Typescript won't be able to narrow down the type of the ResponseType union based on the type field, as shown below.

But as of the latest version (4.5 and above), typescript is able to narrow the type of response to SuccessType as shown below.

As you can imagine, this opens up a world of new possibilities by providing a literal type that is not concrete, typescript can discriminate between two unions as long as the field used to discriminate is contained in the string being compared to. Here is another rudimentary example:

type HttpOK = {
    status: `2${string}`;
    data: string;
}

type Http500 = {
    status: `5${number}`;
    message: string;
}

type Http300 = {
    status: `3${string}`;
    redirect: string;   
}

function processResponse(response: HttpOK | Http300 | Http500) {
    if(response.status === "200") {
        console.log(response.data);
    }

    if(response.status === "300") {
        console.log(response.redirect);
    }

    if(response.status === "500") {
        console.log(response.message);
    }
}

Here is a link to Typescript Playground for the above code.

Conclusion

In this brief article, we looked at a new feature coming to Typescript v4.5 for using Template String Types as a discriminant. This allows us to build more versatile types by relying on a template pattern for the discriminant property rather than an exact string.

The more specific we are, the more effective typescript can be at catching possible errors. In this article, we are going to look at how we can use discriminative unions to write better and more specific types and help typescript to be more helpful to us.

Let's take the simplest example I can think of - Shapes. In shapes, we can have Circles, Rectangles, Squares, etc; you get the idea. There is no way you can have a single type alias that can cover all shapes without compromising on something.

If we were to define a Shape type alias for just the above 3 shapes, it would need to account for the possibility that all fields are not there for all shapes, i.e. Circle only has a radius, which doesn't exist in either Rectangle or Square, while the circle doesn't have either width or height. As you can imagine, our problem only becomes bigger as you add more shapes.

So, our type alias would look like this.

type Shape = {
  radius?: Number; // Circle
  length?: Number; // Rectangle
  width?: Number; // Reactangle
  side?: Number; // Square side Length
}

As you can see, the type alias above is not very useful, since if you had a circle, you could easily leave out all fields or add all of them to Shape and typescript will not be able to help you at all.

This is especially not a good practice for third-party SDKs, where you have to keep referring to the documentation just to get an idea of the shape of the data you are dealing with. Types help us avoid making silly and avoidable mistakes, which we all make as it's in our nature as human beings.

On top of that, we also lose out on the ability to narrow types. It's not easy to narrow the above type to either Circle, Rectangle, or Square.

Type narrowing is the process of moving a type from a less precise type to a more precise type. You can learn more about type narrowing here.

Discriminated Unions

A discriminated type union is where you use code flow analysis to reduce a set of potential objects down to one specific object. - Typescript Docs

Now, let me offer a possible solution to the above problem. We will start by defining three different type-aliases. Each type alias will have a literal type member property - shape - distinguishing for its corresponding shape i.e. Rectangle, Circle, and Square for each of our shapes.

type Square = {
  shape: "Square";
  side: number;
}

type Rectangle = {
  shape: "Rectangle",
  length: number;
  width: number;
}

type Circle = {
  shape: "Circle"
  radius: number;
}

And then we can use a union of the three to declare a type alias of shape that can only be a single type of the above.

type Shape = Square | Rectangle | Circle;

The Shape type alias can only be Square, Rectangle or Circle.

So, what is the advantage of the above you may ask?

Strongly Typed Shapes

The first advantage is that our types are now strongly typed for each shape as compared to the previous solution. For instance, if you specify the shape to be Circle, then, we only provide radius and if it's missing, Typescript throws an error.

const x: Shape = {
  shape: "Circle",
  radius: 5,
  width: 5, // Error ---> Object literal may only specify known properties, and 'width' does not exist in type 'Circle'.
}

As you can see above, once you specify the shape property to be Circle, then you are restricted to only specifying properties available in the Circle type alias.

Trying to add fields that do not exist will result in the following error: // Error ---> Object literal may only specify known properties, and 'width' does not exist in type 'Circle'.

Type Narrowing is Now Possible

Type narrowing is now possible using the literal property shape.

if(shape.shape === "Circle") {
  // the type is now a Circle only
}

Learn more about Type Narrowing in typescript here.

Conclusion

In this article, we learned how we can use discriminated unions to write more specific types in Typescript, and thus better types overall and have an improved developer experience. This allows us in turn to write more type-safe code, which can help typescript eliminate a lot of bugs from our code that would otherwise slip through.

If you found this article informative and would like to keep learning about typescript, visit my series on Typescript - A Byte of Typescript. A Byte of Typescript is a new series that I will be publishing on a regular basis to help you demystify Typescript.

About this Episode

In this Podcast, I join the adventure in angular as a Guest to discuss the ins and outs of Typescript and several tips and tricks for using TypeScript in your Angular and other applications.

Panel

• Armen Vardanyan
• Subrat Mishra

Guest

• Wycliffe Maina

In this article, we are going to look at how we can create our own custom type guards. Custom type guards will help you to check if a variable is of a certain type before usage, which helps in Type narrowing.

Take for instance the following function, which calculates the area of a shape i.e. Circle or Rectangle.

function calculateArea(shape: Rectangle | Circle) {
	// calculate area
}

In order to calculate the area, we will need to determine whether the shape being passed in is a Rectangle or Circle. We can create a custom type guide that will check if the type of a Rectangle and calculate its area, otherwise calculates the area of a circle:

if(isRectangle(shape)) {
	// calculate area of a rectangle
} else {
	// calculate area of a circle
}

What is a Type Predicate?

A type predicate is a function return type that tells typescript a parameter is of a specific type. A predicate takes the following format: parameterName is Type, where parameterName must be the name of a parameter in the function parameter signature.

For instance, if we wanted to build the custom type guard isRectangle above, our type predicate would be shape is Rectangle, where shape is the parameter name, as shown below.

function isRectangle(shape: unknown): shape is Rectangle {
	// function body
}

Custom Type Guard

To define a custom type guard, we create a function that returns a type predicate. The function itself just needs to return true or false. If we take the example above for isRectangle type guard, we would check if the width and the height are present and return true, otherwise, return false.

function isRectangle(shape: unknown): shape is Rectangle {
  if ("width" in shape && "height" in shape) {
  	// this is a rectangle
  	return true; 
  }
  // it's not a rectangle
  return false;
}

In the above example, we are using Javascripts in operator to check if the width and height properties are in the shape object.

Usage

To use the custom type guard, we use it just like any other function that returns a boolean.

type Rectangle = {
  height: number;
  width: number;
}

type Circle = {
  radius: number;
}

const r: Rectangle = {
  height: 12,
  width: 15
}

const c: Circle = {
  radius: 10,
}

console.log(isReactangle(r)); // true
console.log(isReactangle(c)) // false

By using it within a control flow, you can narrow the type of the variable, just like other methods of narrowing types.

function area(shape: Rectangle | Circle) {
  if(isRectangle(shape)) {
    // Rectangle
    shape.height // no error
    shape.radius // error
  } else {
    // Circle
    shape.radius // no error
    shape.height // error
  }
}

Conclusion

In this brief article, we learned what a Type predicate is and how to build custom type guards. We learned that a type guard is a special function that returns a type predicate so that typescript is able to determine the type of a variable.

We will continue covering similar topics in Typescript in this series - A Byte of Typescript. A Byte of Typescript is a new series that I will be publishing on a regular basis to help you demystify Typescript.

If you are looking to learn more about Typescript, here are the previous articles I have published. Thank you 😄.

• Typescript: why you should use unknown instead of any
• Type Narrowing in TypeScript
• Types and Mocking - Typescript
• Template Literal Types in TypeScript
• Transforming Types in TypeScript with Utility Types

Take the following example for instance:

const x: any = {
  a: "a-value",
  b: "b-value"
};

You can access the properties of the object above, i.e. x.a and x.b and everything would work as expected. The problem is that if you tried to access x.c value, Typescript would not throw an error, since the object x can be anything.

const c = x.c
console.log(c)

As you can see, this can be a source of many bugs, since common errors which Typescript would catch during build time will be allowed through. This is because when you use any type, you opt out of type checking.

Why unknown?

The unknown type was introduced in version 3 of typescript as an accompanying type to any. The unknown type, when assigned to a variable, means that a variable type is not known.

And typescript doesn't allow you to use a variable of unknown type unless you either cast the variable to a known type or narrow its type. Type narrowing is the process of moving a less precise type to a more precise type. You can learn more about Type narrowing in Typescript here.

Take the following example.

const x: unknown = 1;

if we tried to square x above without narrowing the type, typescript will throw the following error:

Object is of type 'unknown'.

To fix the above error, we can use type guards to check if it's a number before squaring it.

if(typeof x === "number") {
  console.log(x * x);
}

The same thing with the initial example, if we changed the type to unknown and tried to access any of the properties, typescript would throw an error.

You would need to cast it, in order to typescript to allow you to use it.

const x: unknown = {
  a: "a-value",
  b: "b-value"
};

console.log((x as {a: string; b: string; }).b)

As you can see from the above examples, the unknown type forces you to determine what a variable typed as unknown is, either through type casting or type narrowing. This in turn leads to a better program, as typescript can then type checking the resulting type, leading to a more type-safe program.

Conclusion

In this article, we learned about the unknown type and why we should use it to write more type-safe typescript programs. We also learned why you should avoid using type any unless absolutely necessary.

If you found this article informative and would like to keep learning, visit my new series on Typescript - A Byte of Typescript. A Byte of Typescript is a new series that I will be publishing on a regular basis to help you demystify Typescript.

• Type Narrowing in TypeScript
• Types and Mocking - Typescript
• Template Literal Types in TypeScript
• Transforming Types in TypeScript with Utility Types

Let's start with a simple function:

function friends(input: string | number) {
	// code here
}

The above function can either take a number or a string. Let's say we want to perform different actions based upon whether input is a number or a string. In this case, we will use Javascripts type guards to check if it's a string or number, as shown below:

function someFunc(input: string | number) {
  if(typeof input === "string") {
    // do something with the string
    console.log("input is a string");
  }
  
  if(typeof input === "number") {
    // do something with number
    console.log("input is a number");
  }
}

Type Guards

In the above example, we used Javascripts type guards to narrow the type of input to either number or string. Type guards are used to check if a variable is of a certain type, i.e. number, string, object, etc. When a type guard is used, Typescript expects that variable to be of that type. It will automatically type check its usage based on that information.

Here is a list of Javascripts type guards available:

string

if(typeof param === "string") {
  // do something with string value
}

number

if(typeof param === "number") {
  // do something with number value
}

bigint

if(typeof param === "bigint") {
  // do something with bigint value
}

boolean

if(typeof param === "boolean") {
  // do something with boolean value
}

symbol

if(typeof param === "symbol") {
  // do something with symbol value
}

undefined

if(typeof param === "undefined") {
  // do something with undefined value
}

object

if(typeof param === "object") {
  // do something with object value
}

function

if(typeof param === "function") {
  // do something with the function
}

Truthiness Narrowing

In this type of narrowing, we check whether a variable is truthy before using it. When a variable is truthy, typescript will automatically remove the possibility of that variable being falsy i.e. undefined or null, etc, within the conditional check.

Take for instance the following example, where a function someFunction below takes an input, whose type is either a string or undefined (i.e. optional).

function someFunction(x?: string) {
  if(x) {
    console.log(typeof x) // "string"
  }
}

By checking whether input is truthy, the type of x becomes a string otherwise it's undefined.

Equality Narrowing

If two variables are equal, then the types of both variables must be the same. If one variable is of an imprecise type (i.e. unknown, any etc.) and is equal to another variable of a precise type, then typescript will use that information to narrow the type of the first variable.

Take the following function, which takes two parameters: x and y, with x being either a string or a number and y being a number. When the value of x is equal to the value of y, then the type of x is inferred to be a number and otherwise a string.

function someFunction(x: string | number, y: number) {
    if(x === y) {
        // narrowed to number
        console.log(typeof x) // number
    } else {
        // this is not narrowed
        console.log(typeof x) // number or string
    }
}

Discriminated Unions

In this approach, you create an object, with a literal member that can be used to discriminate between two different unions. Let's take an example of a function that calculates the square of different shapes - Rectangle and Circle. We will start by defining the type of Rectangle and Circle.

type Rectangle = {
    shape: "reactangle",
    width: number;
    height: number;
}

type Circle = {
    shape: "circle"
    radius: number;
}

From the above types, the objects will each have the literal field of shape, which can either be a circle or rectangle. We can use the shape field within our function to calculate area, that would accept a union of Rectangle and Circle, as shown below:

function calculateArea(shape: Rectangle | Circle) {
    if(shape.shape === "reactangle") {
        // you can only access the properties of reactangle and not circle
        console.log("Area of reactangle: " + shape.height * shape.width);
    }

    if(shape.shape === "circle") {
        // you can only access the properties of circle and not reactangle
        console.log("Area of circle: " + 3.14 * shape.radius * shape.radius);
    }
}

When the shape field is a rectangle, you only have access to properties available in the Rectangle type, that is width, height and shape. The same applies to when shape field is a circle, typescript will only allow you to access radius and circle and will throw an error otherwise.

Using the in Operator for Narrowing

The in operator is used to determine if an object has a property with a name in it. It's used in the format of "property" in object where property is the name of the property you want to check if it exists inside the object.

In the example above, we used discriminated unions to distinguish between a Circle and Rectangle. We can also use the in operator to achieve the same, but this time we will be checking if a shape contains certain properties i.e. radius for Circle, width and height for Rectangle, and the results would be the same.

type Circle = {
  radius: number;
};

type Reactangle = {
  width: number;
  height: number;
};

function calculateArea(shape: Circle | Reactangle) {
  if ("radius" in shape) {
    // now you can access radius from shape
    console.log("Area of circle: " + 3.14 * shape.radius * shape.radius);

    // any attempt to access height or width will result to an error
    shape.width; // Property 'width' does not exist on type 'Circle'.
    shape.height; // Error: Property 'height' does not exist on type 'Circle'
  }
  if ("width" in shape && "height" in shape) {
    // now you can access height and width from the shape object
    console.log("Area of reactangle: " + shape.height * shape.width);

    // any attempt to access raidus would result to an error
    shape.radius; // Error: Property 'radius' does not exist on type 'Reactangle'.ts
  }
}

Using Assignment Narrowing

In this type of narrowing, typescript will narrow the type of a variable once it's assigned a value. Take a variable x of union type of either number or string, if we assign it a number, the type becomes a number and if we assign it a string, the type changes to a string instead.

let x : number | string = 1;

console.log(typeof x) // "number"

x = "something"

console.log(typeof x) // "string"

Here is a detailed example at Code Sandbox:

Using instanceof for Narrowing

Javascripts' instanceof operator is used to check if a value is an instance of a certain class. It's used in the format of value instanceof value2 and returns a boolean. When you check if a value is an instanceof a class, Typescript will assign that type to the variable, thereby narrowing the type.

Take the following example, where a function takes in a date, which can be either a string or a Date. If it's a Date, we want to convert it to a string and if it's a string, we will return it as is. We can use instanceof to check if it's an instance of a Date and convert it to string, as shown below.

function dateToString(value: string | Date) {
  if(value instanceof Date) {
    // The type now is Date and you can access Date methods
    return value.toISOString();
  }
  return value;
}

Conclusion

In this article, we learned various ways we can narrow types, from type guards to discriminated unions. In our next article, we will learn how we can build our own type guards using type predicates.

If you found this article informative and would like to keep learning, visit my new series on Typescript - A Byte of Typescript. A Byte of Typescript is a new series that I will be publishing on a regular basis to help you demystify Typescript.

Ship It! 13: A monorepo of serverless microservices – Listen on Changelog.com

In this episode, Gerhard talks to his Skyhook Adventure friends: Alan Cooney, Saul Cullen & Wycliffe Maina. They are the ones that introduced Gerhard to the world of serverless in the context of Amazon Web Services. Gerhard shared his experience with remote work, how to ship software with confidence and consistency, and what to look for in infrastructure as code.

At the heart of Skyhook Adventure are adventure trips, and 2020 was not a good one for this business. As you can already tell, code and infrastructure was not the biggest challenge for this team. Having said that, serverless, microservices, a monorepo and the event-based architecture played a big part in successfully navigating the challenges.

This is a story about what happens when a good team allows itself to be guided by solid experience and keeps doing the right thing, long-term. It’s fun, real, and it applies to many.

For instance, take an Angular project, this requires a few things to get started, like Typescript, NodeJS, Angular CLI, etc. This can easily be created using docker and once set up can easily be re-created on demand. As you can imagine, this can have several benefits, which we will look at later.

On its own, it still leaves much to be desired though. But, a while back the Visual Studio Code team released a pack of extensions for remote development. These extensions enabled you to work with development environment hosted remotely such as docker containers, among others and continue with development workflow as you would if they were on your local PC.

Combined with VS Code Remote - Container's extension, part of Visual Studio Remote extensions pack, which enables you to use docker as a full-fledged development environment. The Remote Container extension, provides you with tools to connect to a docker container and carry on with your development workflow on the container.

On top of that, it provides tools to:

• Generate Docker Environment Configurations for different environment requirements like Typescript, Golang, etc. This allows you fine-grained control over your development environment with exactly the dependencies you need to enable your development workflow.
• Clone a repository directly to docker containers. You can target different branches and PRs, allowing you to have a development environment per PR if need be.

Benefits For Development

For one, since docker containers are isolated environments, collision between different development environment dependencies is greatly reduced if not entirely eliminated. How many times have you required to have different versions of the same dependency installed, for instance NodeJS? Docker development container would eliminate such collisions entirely, reducing the need for tools such as NVM.

Secondly, it is easier to onboard developers, as the development environment are already specified and it's a matter of building the containers. This makes it easy to onboard developers as they can set up their environment faster and go straight to understanding what actually matters to the organization.

On top of on boarding new developers, reviewing PRs is easier, as you can easily and quickly create a new development environment per PR for review purpose. VS Code remote container extension provides you with tools to enable clone repository, branches or PRs into development containers, making this a more viable approach.

Another key benefit is keeping your development environments up to date across team members becomes easier. When you come back from a vacation, with a single command, you can update your development environment making easy to continue as if you never left with little to no hinderances.

Fully compatibility with GitHub Code Spaces. GitHub code spaces is a remote development environment that uses docker development containers under the hood. While still in beta and a lot could change, as of the moment of writing, they are fully compatible. This means that you can easily take your development environment on the road without needing to configure anything after the initial configuration. GitHub code spaces will provide you with all the computing power you need while on the road.

Cons

Steep learning curve. While VS Code helps to set up common development environments like NodeJS, Typescript, etc., setting a fine-grained environment will require you to understand docker and dockerfiles. This can be a barrier to people who aren't familiar to docker and adds an extra barrier to getting up to speed.

Conclusion

In this article, we looked at Docker development containers and the benefits of using them. I am hoping that the benefits we looked at above convinced you to give docker development containers a try.

If you are looking to get started, here some resources for you:

• Developing inside a Container using Visual Studio Code Remote Development
• Use containers for development | Docker Documentation
• Develop with Docker | Docker Documentation

So, what are template literal types?

Literal Types

In order to understand what template literal types are, we first need to have a brief look at literal types. Literal types allow us to define types that are more specific, instead of something that is generalized like string or number.

Let's say you have a switch; it can have the value of either on or off. One way of defining the types of this, is to use literal types, giving it the type of either On or Off:

type Switch = "On" | "Off"

In the case above, the value of any variable of type Switch can only be On or Off:

const x: Switch = "On"
const y: Switch = "Off"

If you tried to assign any other values other than On or Off, typescript will throw an error:

Template Literal Types

Template Literal Types build on this, allowing you to build new types using a template and can expand to many different string using Unions. This works just like template literal/strings, but instead of concatenating to form strings, it concatenates to form types.

const variable = "string";
type tVariable = "string";

// this results to a variable
const val = `This is a concatenated ${variable}`

// while this results to type
type X = `This is a concatenated ${tVariable}`

As you can see, they are similar in syntax apart from what they are defined as, the first being a variable and the second being a type. The type of the first definition will be string, while the second one will be of type This is a concatenated string and a variable of that type can only be assigned to that string.

NB: If you tried to use variable instead of a type when defining Template Literal Type, it will throw the following error: 'variable' refers to a value, but is being used as a type here. Did you mean 'typeof variable'?

If we take our example above of type Switch, we may want to have a function that returns the status of the switch, i.e. Switch is On or Switch is Off, and have it strongly typed, in that it can only return only those strings. With Template Literal Types, we can define this as follows:

type Switch = "On" | "Off"

const x: Switch = "On"
const y: Switch = "Off"


type SwitchStatus = `Switch is ${Switch}`;

And this in return gives us the types: Switch is On and Switch is Off:

Using To Build Types for Grid Items Coordinates

Let's say we are working with a grid system, and wanted to perform a task on various boxes in our grid, like placing something on a specific box given its coordinates. It would be nice if we could strongly type it and ensure we don't specify values outside the grid.

For instance, if we had a grid whose length was 3 smaller boxes on either side of the box. This makes it that we have 9 smaller box fitting on our big box. We can use literal types to create a type for each of our boxes, with the type being its position in the grid. So, the first gets L1-H1 and the last gets L3-H3 types, as shown below.

type SquareBoxes = "L1-H1" | "L1-H2" | "L1-H3" | "L2-H1" | "L2-H2" | "L2-H3" | "L3-H1" | "L3-H2" | "L3-H3"; 

Those are a lot of types to create by hand even for a small grid of 9 boxes. But, with template literals types, we could define just the type of the length of one side and use template string literals to expand the rest of the types:

type length = "1" | "2" | "3";

type SmallerBoxes = `L${length}-H${length}`

And this would yield the same result as before:

This makes our work easier and it is more versatile, because if the smaller boxes ever increased or decreased, you only need to adjust the size of the length.

// 16 boxes
type length = "1" | "2" | "3" | "4";

// 25 boxes
type length = "1" | "2" | "3" | "4" | "5";

// 4 boxes
type length = "1" | "2";

Combining With Generics

We can combine template literal types with generics to some amazing effect. Let's take with a Type of Person, which has two properties - name and age.

type Person = {
    name: string;
    age: number;
}

We want to add two methods to be called to update the values of name or age i.e. nameChanged or ageChanged. We can create a new type, that will take type Person as a generic, and for each property of type Person, we will add new properties with Changed appended the original properties of type Person i.e. nameChanged and ageChanged. We will used template literal types to create a new property by appending Changed to the property name.

type WithPersonChangedEvents<Type> = {
    [Property in keyof Type as `${string & Property}Changed`]: (newValue: Type[Property]) => void;
} & Type;

NB: The above example uses some advanced typescript technique for manipulating types on top of Template Literal Types which you can learn more here.

Now, we can use both of our Types (Person and WithPersonChangedEvent) above:

const person: WithPersonChangedEvents<Person> = {
    name: "Name",
    age: 20,
    nameChanged: (newName) => console.log(newName),
    ageChanged: (newAge) => console.log(newAge),
};

person.ageChanged(21); // Logs: 21
person.nameChanged("new Name"); // Logs: "new Name"

And as you can see, our object - person has 4 properties, with 2 being the added methods.

Conclusion

We have learned about Template Literal Types in Typescript and how they build on top Literal types to provide you even more flexibility when defining types. We have also looked at different use cases like in a grid system type definition for different boxes coordinates and combining them with generics to define extra properties for an object.

Resources

• Creating Types from Types - Link.
• Template Literal Types Documentation - Link.
• Template literals (Template strings) - Link.
• Types and Mocking - Typescript - Link.
• Transforming Types in TypeScript with Utility Types - Link.

For an RSS plugin, we will build a routeDiscoveryDone plugin, which is usually called when all routes have been discovered. This is going to use data discovered during the route discovery process to create an RSS feed. The route discovery process is done by a router plugin, which you can learn more about here.

Scully provides 9 types of plugins which are called during different stages of Scully build. For more information about different types of plugins, please visit the official documentation here.

Prerequisites

• Setup Scully for Your Angular Project - Link.

Building the Plugin

Getting Started

If you used schematics to setup your Scully for your Angular project, you should be able to spot a Scully directory at the root of the workspace. This directory contains a tsconfig file for Scully plugins and a plugins directory, which is where our plugin will live.

Inside the plugins directory - scully/plugins - we will create a new file named rss.ts, which is going to contain the source code for our plugin.

Plugin Code

To create our RSS feed, we will use the NPM package Feed, which make it easy to generate syndicated feed using Typescript.

Our RSS plugin will be called when Scully discovers all routes and it will receive a list of routes and route data associated with each route discovered.

const createRSSFeed = async (routes: HandledRoute[]) => {
  // code here
}

We will start by creating a new instance of Feed.

First, we need to import Feed.

import { Feed } from 'feed';

Then instantiate Feed.

const feed = new Feed({
  title: 'John Doe Blog',
  language: 'en-us',
  author: {
    email: 'johndoe@example.com',
    name: 'John Doe',
  },
  description: 'about you website or blog',
  id: 'https://example.com',
  link: 'https://example.com/blog',
  favicon: 'https://example.com/favicon.png',
  copyright: "John Doe Copyright"
});

NB: Update the content above according to your own specification.

Next, we will loop over the routes, and add an RSS Feed item for each.

routes.forEach((route) => {
	// add each item to an RSS Feed Article  
})

Then, for each route, we want to add an RSS item, and use the route data - route.data.* to fill in the different properties like title, date, content, etc.

routes.forEach((route) => {
  feed.addItem({
    title: route.data.title,
    date: new Date(route.data.publishedAt),
    link: route.data.link,
    // loop through the names of the authors if list
    author: [
      {
        email: route.data.author.email,
        name: route.data.author.email,
      },
    ],
    // uses tags as categories
    category: route.data?.tags?.map((t: Tag) => ({
      name: t.name,
    })),
    content: route.data.html,
    id: route.data.id,
    image: route.data.featured_image,
    published: new Date(route.data.publishedAt),
  });
})

NB: update the different properties of each item according to the structure of your data. For markdown content, this are the keys in the Front Matter.

Finally, we will save our RSS feed as an XML file inside the output directory of Scully. We can use fs-extra to do that, so we will start by installing the package.

Yarn:

yarn add --dev fs-extra

NPM:

npm i -D fs-extra

Then, we will import outputFileSync from fs-extra.

import { outputFileSync } from 'fs-extra';

Finally, we will save the RSS feed.

// the output directory of your scully builds artefacts
const outDir = './dist/static';

outputFileSync(join(outDir, 'blog', `feed.xml`), feed.rss2());

On top of that, we can also generate both JSON and Atom files:

outputFileSync(join(outDir, 'blog', `feed.atom`), feed.atom1());
outputFileSync(join(outDir, 'blog', `feed.json`), feed.json1());

That's it for the plugin, here is what the plugin function looks like.

const createRSSFeed = async (routes: HandledRoute[]) => {
  log(`Generating RSS Feed for Blog`);

   const feed = new Feed({
    title: 'John Doe Blog',
    language: 'en-us',
    author: {
      email: 'johndoe@example.com',
      name: 'John Doe',
    },
    description: 'about you website or blog',
    id: 'https://example.com',
    link: 'https://example.com/blog',
    favicon: 'https://example.com/favicon.png',
    copyright: "John Doe Copyright"
  });

  routes.forEach((route) => {
    feed.addItem({
      title: route.data.title,
      date: new Date(route.data.publishedAt),
      link: route.data.link,
      // loop through the names of the authors if list
      author: [
        {
          email: route.data.author.email,
          name: route.data.author.email,
        },
      ],
      // uses tags as categories
      category: route.data?.tags?.map((t: Tag) => ({
        name: t.name,
      })),
      content: route.data.html,
      id: route.data.id,
      image: route.data.featured_image,
      published: new Date(route.data.publishedAt),
    });
  })

  try {
    const outDir = './dist/static';
    outputFileSync(join(outDir, 'blog', `feed.xml`), feed.rss2());
    log(`✅ Created ${yellow(`${outDir}/blog/feed.xml`)}`);
    outputFileSync(join(outDir, 'blog', `feed.atom`), feed.atom1());
    log(`✅ Created ${yellow(`${outDir}/blog/feed.atom`)}`);
    outputFileSync(join(outDir, 'blog', `feed.json`), feed.json1());
    log(`✅ Created ${yellow(`${outDir}/blog/feed.json`)}`);
  } catch (error) {
    logError('❌ Failed to create RSS feed. Error:', error);
    throw error;
  }
};

NB: log and logError are helper functions from Scully, imported from @scullyio/scully.

Registering the Plugin

Next, we will give our plugin a name. First, we will declare and export a variable for the name of the plugin.

export const BlogRSSFeed = Symbol('BlogRSSFeed');

This variable can be imported in to the Scully config file to use the plugin.

Then, we will register our Scully plugin as a routeDiscoveryDone plugin.

registerPlugin('routeDiscoveryDone', BlogRSSFeed, createRSSFeed);

Using the Plugin

Finally, we can use the RSS plugin by adding to the array of postRederrers. This can be achieved using two approaches. The first one will be for all routes within our our application:

export const config: ScullyConfig = {
  projectRoot: './src',
  projectName: 'project-name',
  outDir: './dist/website',
  defaultPostRenderers: [BlogRSSFeed], // for all routes
  routes: {
    '/blog/:slug': {
     	// ...
    },
  },
};

While the second one can be specified for a specific route i.e. blog. This is useful when you only want to generate an RSS feed for a single section of your site like the blog section.

export const config: ScullyConfig = {
  // ...
  routes: {
    '/blog/:slug': {
      postRenderers: [BlogRSSFeed],
      // ...
    },
  },
};

Conclusion

In this article, we learnt how to create a Scully plugin to generate RSS feeds for our Angular app. We have created a routeDiscoveryDone plugin that's called after routes for our application have been discovered and uses the route data to generate RSS feed for each of our route.

Resources

• Speeding Up Angular Scully Builds in GitHub Actions - Link.
• Angular CDK - Platform Module - Link.
• Scully Documents - Link.

Let's take the following function, how do you mock it's inputs i.e. person:

interface Person {
    name: {
        firstName: string;
        lastName: string;
    }
    id: string;
    age: number;
    height: number;
    weight: number;
}

function getPersonsFullName(person: Person) {
    return `${person.name.firstName} ${person.name.lastName}`;
}

One common way, is to create an object of type Person with only the fields being used by function and then cast the object as any, as shown below:

const person = {
    name: {
        firstName: "Wycliffe",
        lastName: "Maina"
    }
}

console.log(getPersonsFullName(person as any));

This works, but you are losing the benefits of typescript typing system by casting as any, since the compiler won't type check the object person being passed to the function.

A good reason as to why this is not a good idea, is that if the function changes and starts using other properties or the shape of the input object changes, TypeScript will not help you. I am guilty of casting as any, especially when writing mocks for tests.

But, is there a better way? Yes, we can improve the function above, so that it is easier to mock the input without resulting to the above technique. One approach, which I really recommend, is to create a new type which only has the fields the function needs to run successfully, in this case the name property. This can easily be achieved in Typescript using Utility Types, which you can learn more about here.

We can use the Pick<T> utility type, to create a new type from Person, with only the name field i.e. picking the name field from the Person type.

function getPersonsFullName(person: Pick<Person, "name">) {
    return `${person.name.firstName} ${person.name.lastName}`;
}

This way, our mock example still works, but without resulting to casting as any:

const person = {
    name: {
        firstName: "Wycliffe",
        lastName: "Maina"
    }
}

console.log(getPersonsFullName(person));

The advantage of this is that you can still pass a person object with more properties as long as name property is present, as shown below:

const person = {
    name: {
        firstName: "Wycliffe",
        lastName: "Maina"
    },
    id: 21
}

// this still works
console.log(getPersonsFullName(person));

Utility types such as Omit, Pick, Partial, Required, etc. can help you create new types easily that define the shape of an input object for a function. This makes it possible to define with precision what a function input type is, with just a little extra work on your part. You can learn more about TypeScript utility types in my previous article here.

This makes your functions and methods more friendly since they are taking in only what they need, making it easy to mock as seen above. Another advantage is that your functions are more re-usable as they don't place an unnecessary burden on the consumer of the function by requiring larger input than they are using.

Typescript offers Utility Types, which are intended to solve this particular problem. In this article, we are going to have a look at these built-in utility types and a third-party library (with examples) that offers more utilities you might find helpful in achieving the above goal.

Built-in Utility Types

This section focuses on TypeScript built-in utility types, they are numerous and I won't be able to cover all of them, I will just look at a few key ones, with examples, in my own opinions.

Partial

This utility type constructs a new type from an existing one, with the keys at the top level being marked as optional (?).

interface Type {
    field: string;
}

type Type2 = Partial<Type>;

NB: This only runs one level, meaning keys below one level will not be affected. If you want to mark all keys as optional, regardless the level they are in, check out PartialDeep below.

Required

This utility type does the opposite of the above, constructing a new type with all keys from the old type that are optional being marked as required.

interface Type {
    field?: string;
    optional?: string;
}

type Type2 = Required<Type>;

Omit

This utility type constructs a new type from an existing type while omitting specified keys from the new type.

interface Type {
    field1?: string;
    field2: string;
    field3: string;
}

type Type2 = Omit<Type, "field3" | "field1">;

Pick

This utility type constructs a new type by picking keys specified from the old type. It does the opposite of Omit, as described above.

interface Type {
    field1?: string;
    field2: string;
    field3?: string;
    field4: string;
    field5?: string;
}

type Type2 = Pick<Type, "field2" | "field3">;

Readonly

This utility type constructs a new type from an existing one and marks all keys as read-only i.e. they cannot be re-assigned. This is useful for types of a frozen object - i.e. Object.freeze().

interface Type {
    field1?: string;
    field2: string;
    field3: string;
}

type Type2 = Readonly<Type>;

Record

This utility type constructs a new type with union members as keys and the type as the type of the keys.

interface Name {
    firstName: string;
    lastName: string;
}

type Names = "user1" | "user2";

type Type2 = Record<Names, Name>;

Above are a few built-in utility types that I find very useful, you can find out more about built-in utility types in the official documentation here.

Extending Built-in Utility Types

While the above built-in utility types are amazing, they don't cover all use cases, and this is where libraries that provide more utilities fill in the gap. A good example of such a library is type-fest, which provides even more utilities.

While I won't look in to all utilities provided by type-fest, I will highlight a few that are quite help and build on the built-in types utilities.

Except

This is a variation of the Omit utility type described above, but stricter. It constructs a new type by omitting specified keys from a Type, but unlike Omit, the keys being emitted must strictly exist in the Type.

import { Except } from "type-fest"

interface X {
  a: string;
  b: string;
  c: string;
}

// Omit Example
type Y = Omit<X, "d">

// Except Example
type Z = Except<X, "d" >

As you can see in the image below, Except throws an error if you provide a Key that doesn't exist.

Merge

Constructs a new type by merging two Types, with keys of the second type overriding the keys of the first type.

import { Merge } from "type-fest"

interface X {
  a: string;
  b: string;
  c: string;
}

interface Y {
  c: number;
  d: number;
  e: number;
}

type Z = Merge<X, Y>

const x : Z = {
  a: "is string",
  b: "is string",
  c: 1,
  d: 2,
  e: 3,
}

PartialDeep

This utility type constructs a new type where all keys in all levels are optional. This is quite similar to the Partial built-in utility type, with one significant difference, it runs deeply to all levels, while the former does it at the first level.

import { PartialDeep } from "type-fest";

interface X {
  a: string;
  b: string;
  c: string;
}

interface Y {
  c: number;
  d: number;
  e: number;
  f: X;
}

type Z = PartialDeep<Y>;

const x: Z = {};

ReadonlyDeep

This utility type constructs a new type with all keys on all levels marked as required. This is also similar to the built-in Readonly utility type, but unlike the built-in utility type, this one goes down to all keys in all levels, making them immutable.

Mutable

This utility type constructs a type that strips out readonly from a keys in a type, essentially the opposite of what the built-in utility type Readonly does.

import { Mutable } from "type-fest";

interface X {
  readonly a: string;
  readonly d: string;
}

type Y = Mutable<X>;

Conclusion

In this article, I looked into typescript utility types and how they can help you automatically create types from existing ones without resulting to duplicating eliminating the need to keep related types in sync.

I highlighted a few built-in utility types that I find particularly useful on my day to day job as a developer. On top of that, we looked into type-fest, a library with a lot of utility types that extends the built-in types, and highlighted just a few.

Resources

• Utility Types - Typescript Docs
• type-fest
  

It is common for most websites, that content can change without the source code of your website changing. Therefore, it can be wasteful to run an Angular build every time your website content changes.

Normally, Angular builds time are decent. But due to a number of factors, Angular builds could slow down, like in my case, running purge CSS against Tailwindcss extends the build time to over 7 minutes. Add everything else together, and my GitHub Actions would take over 12 minutes.

Using GitHub Releases

First, we are going to need a place to store our Angular build artifacts. GitHub releases are a nice way, as it allows you to have a long-term storage of your artifacts that you can use anytime you want. This combined with npm version means ones you have your features ready; you can cut a release that will be used by subsequent builds as you continue to work on other features and/or improvements.

So, we are going to build our workflow to have two jobs, the first job will take care of building our Angular app, and creating a release and uploading our build artifacts to the release. While the second job will take care of Scully builds using the latest artifacts stored in GitHub releases and publishing our website to our hosting platform.

Whenever a new tag is added to the repository, we will create a release with the version no. of the tag and upload our angular builds to that release.

Building our Angular App

Listening to Tags

First, we will need to trigger our GitHub workflow every time a new tag is created. We will be using tags to create release version. This will allow us to use npm version to create new build artifacts for us to use during the publishing process.

on:
  push:
    tags:
      - "*"

NB: In the publish our blog section, we will modify this section to listen to repository_dispatch, which we will use with webhooks to trigger the workflow when events outside our repository like blog post published occur, you can learn more here.

We will limit this job to only run when a new tag is created using startsWith(github.ref, 'refs/tags/'). This will allow us to utilize the same workflow file for building and publishing, with them being two separate jobs.

jobs:
  build:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest

Installing NPM Packages

Next, we will need to install NPM packages before we can build our angular app. In this case, we are using yarn but feel free to use your favorite package manager. We will start by checking out (git checkout) our repository. After that, we will then setup NodeJS and finally run yarn install to install our NPM packages.

steps:
  - uses: actions/checkout@v1
  - name: Setup Node
    uses: actions/setup-node@v1
    with:
      node-version: 12.x
  - name: yarn install
    run: yarn install

Building Angular Project

And then, we can add a step to run yarn build:prod to build our Angular app in production.

- name: yarn build
  run:  yarn build:prod

Creating a Release and Uploading Artifacts

Now that we have built our project, we are going to do two things next. We will zip the build artefacts and then create a release and upload our zipped artifact to the releases. We will use papeloto/action-zip action to zip the files:

- uses: papeloto/action-zip@v1
  with:
    files: "./dist/webapp/"
    dest: webapp.zip

Replace webapp with the output directory of your angular project build.

And then, we are going to create a GitHub release and upload the above zipped artifact to the GitHub release. We will be using ncipollo/release-action action, to accomplish this as shown below.

- name: Push Build to Releases
  uses: ncipollo/release-action@v1
  with:
    artifacts: "webapp.zip"
    token: ${{ secrets.GITHUB_TOKEN }}

Here is what our workflow looks so far:

name: Release a new Version

on:
  push:
    tags:
      - "*"

jobs:
  build:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      
      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: 12.x
          
      - name: yarn install
        run: yarn install
        
      - name: yarn build
        run:  yarn build:prod
        
      - uses: papeloto/action-zip@v1
        with:
          files: "./dist/webapp/"
          dest: webapp.zip
          
      - name: Push Build to Releases
        uses: ncipollo/release-action@v1
        with:
          artifacts: "webapp.zip"
          token: ${{ secrets.GITHUB_TOKEN }}

Building Scully and Publishing Blog

Next, we are going to add a second job - publishing - that will download our Angular build artifacts from our repos latest release, run Scully build and upload the artifacts to our hosting platform.

First, we will need to listen to the on repository_dispatch as this is how we will trigger our website rebuild when the content on our CMS changes, as explained here. Feel free to use any other GitHub action triggers suitable for your content management system i.e. on push to master on the blog directory if you are using markdown.

on:
  push:
    tags:
      - "*"
      
  repository_dispatch:
    types:
      - publish_blog

Next, we are going to create a publish job, which will run after the build job but if the build job doesn't run, it will run anyway. We will use the if: always() condition to run the job even if the build doesn't. This will run the publish job if a new blog post is published, which will skip the build job, but also when a new release is made, in which case you want the website to be published with changes that were released.

The one downside of this approach is that the publish job will run even if the build job fails.

publish:
  runs-on: ubuntu-latest
  needs: [build]
  if: always()

Next, we will need to setup Node and run yarn install to install NPM packages as Scully needs both to run.

steps:
  - uses: actions/checkout@v1
  - name: Setup Node
    uses: actions/setup-node@v1
    with:
      node-version: 12.x
  - name: yarn install
    run: yarn install

After that, we are going to download our build artifact that we uploaded to GitHub release - webapp.zip - and unzip the content to the dist/webapp directory. To download the artifact from GitHub release, we will be using the dsaltares/fetch-gh-release-asset action.

- uses: dsaltares/fetch-gh-release-asset@master
  with:
    repo: "USERNAME/REPOSITORY"
    version: "latest"
    file: "webapp.zip"
    target: "webapp.zip"
    token: ${{ secrets.GITHUB_PAT }}

NB: For private repository, you will need a GitHub Personal Access Token (PAT) with at least the org:hook scope. Learn more here.

Next, we will create a directory to put the angular webapp build artifacts in and then unzip webapp.zip which we downloaded from GitHub releases.

- name: create dist directory
  run: mkdir -p dist/webapp

- name: Decompress
  uses: TonyBogdanov/zip@1.0
  with:
      args: unzip -qq ./webapp.zip -d ./dist/webapp

And finally, run yarn scully for statically site generation of our Angular app:

- name: Run scully
  run: yarn scully

Now we can deploy the Scully build artifact to your website. In this case we will use firebase hosting, which you can do as shown below.

- name: deploy firebase webapp
  uses: w9jds/firebase-action@master
  with:
    args: deploy --only hosting
  env:
    FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }}

And now our final GitHub Action Workflow looks like this:

name: Publish Blog

on:
  push:
    tags:
      - "*"
 
  repository_dispatch:
    types:
      - publish_blog
      - build_site

jobs:
  build:
    if: startsWith(github.ref, 'refs/tags/')
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1

      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: 12.x

      - name: yarn install
        run: yarn install
        
      - name: yarn build
        run:  yarn build:prod

      - uses: papeloto/action-zip@v1
        with:
          files: "./dist/webapp/"
          dest: webapp.zip
          
      - name: Push Build to Releases
        uses: ncipollo/release-action@v1
        with:
          artifacts: "webapp.zip"
          token: ${{ secrets.GITHUB_TOKEN }}


  publish:
    runs-on: ubuntu-latest
    needs: [build]
    if: always()

    steps:
      - uses: actions/checkout@v1

      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: 12.x

      - name: yarn install
        run: yarn install
        
      - uses: dsaltares/fetch-gh-release-asset@master
        with:
          repo: "[USERNAME]/[REPO]"
          version: "latest"
          file: "webapp.zip"
          target: "webapp.zip"
          token: ${{ secrets.GITHUB_PAT }}

      - name: create dist directory
        run: mkdir -p dist/webapp

      - name: Decompress
        uses: TonyBogdanov/zip@1.0
        with:
            args: unzip -qq ./webapp.zip -d ./dist/webapp
            
      - name: Run scully
        run: yarn scully

      - name: deploy firebase webapp
        uses: w9jds/firebase-action@master
        with:
          args: deploy --only hosting
        env:
          FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }}

Conclusion

In this article, we have looked at how we can optimize our Scully build time by splitting Angular builds and Scully builds, where we store our Angular builds and re-use the artifacts in future Scully builds.

This may not be necessary for your application if you are not using tools like purge CSS to remove unused CSS, since Angular builds are usually fast for small to medium size applications.

There are few things I skipped like caching NPM dependencies, which can shave off a few more seconds from your build time and I highly recommend you implement following instructions here.

Links

• Use Webhooks to Trigger GitHub Actions - Link.
• Getting Started with Scully - Link.
• Getting Started with GitHub Actions - Link.
• About GitHub Releases - Link.
• Angular CDK - Platform Module - Link.

For instance, in a blogging platform, you might want to run a workflow to rebuild your statically generated website when the content is updated in a headless CMS. Most headless CMSs will request webhooks which they will send requests to when various events take place. For instance, when a new article is published or an old one is updated, you might want to just trigger a rebuild of your website.

Prerequisite

• GitHub Personal Access Token (PAT) - follow instructions here

NB: Please ensure you have selected the workflow on the scope of the GitHub Personal Access Token (PAT).

Basics First

GitHub actions provides a repository_dispatch event to allow us to manually trigger a GitHub action workflow. To use this, we are going to configure our GitHub action workflow to run on repository_dispatch.

And then, we will specify the types of event upon which they will be triggered by. These event types are user defined and can be anything you wish them to be.

You can learn more about repository_dispatch here.

For instance, here is an example of a GitHub action workflow config which runs when a new blog post is published:

on:
  # publish blog using webhook
  repository_dispatch:
    types: [publish_blog]
 
 # steps

In the case above, we will make a post request to create repository dispatch action endpoint with event_type of publish_blog and that's when the GitHub Action will get triggered and not by any other event type. The event_type allows you to trigger a specific GitHub action workflow.

Triggering the Action

In order to trigger the action above, we are going to send a POST request to the GitHub API endpoint for creating a repository dispatch event. The URL follows the following format:

https://api.github.com/repos/[USERNAME]/[REPOSITORY]/dispatches

Replace the [USERNAME] with your GitHub owner i.e. your username or organization and [REPOSITORY] with the name of the repository.

To specify the GitHub Workflow to trigger, you need to provide event_type in the body. The event_type specified must be listed in the types array section of the repository_dispatch.

NodeJS Example

For this example, we are going to use Got, a Node JS library for sending HTTP requests.

const url = 'https://api.github.com/repos/[USERNAME]/[REPOSITORY]/dispatches';
const githubPAT = "GITHUB_PAT"; // keep this secret
await got.post(url, {
  json: {
    event_type: 'publish_blog',
  },
  headers: {
    Authorization: "token " + githubPAT,
  },
});

NB: Remember to substitute [USERNAME], [REPOSITORY] and GITHUB_PAT with the appropriate values.

The above request is going to trigger all GitHub Actions workflows which are listening to event type publish_blog.

Building a Webhook

Now that we have the basics out, we are going to build a Webhook which we can use to trigger our workflow. While the GitHub dispatch event does qualify to be a webhook, you might want to simplify the API being exposed. This is because some systems where you might want to use the webhook in, will not be that configurable. Some will just give you the option of entering a URL and nothing more, which makes it difficult to use the GitHub Dispatches API directly.

For the purpose of this article, we will be using Firebase Cloud Functions, but any rest endpoint will do. This will expose a public GET endpoint that we can pass an action query param, which will be the type of event we want to trigger and will default to publish_blog. We will use Firebase Functions Config to pass the GitHub PAT to the function.

export const triggerGithubActionWorkflow = https.onRequest(async (req, res) => {
  const dispatchAction = req.query?.action ?? 'publish_blog';
  const url =
    'https://api.github.com/repos/[USERNAME]/[REPOSITORY]/dispatches';
  const githubPAT = config().github.pat;
  await got.post(url, {
    json: {
      event_type: dispatchAction,
    },
    headers: {
      Authorization: "token " + githubPAT,
    },
  });
  res
    .send({
      message: `Dispatch Github action event emitted successfully!`,
    })
    .status(200);
});

NB: The above Firebase function is public and might wise to add some security measures to prevent anyone from triggering your GitHub Action workflow.

Conclusion

In this article, we looked at how we can trigger GitHub Action workflows Webhooks. We used the create repository dispatch GitHub API endpoint to trigger our GitHub Action Workflow and created our own REST Endpoint to act as a Webhook to integrate with third party APIs.

Like I pointed out above, our example could use more security measures to ensure that not just anyone with the REST Endpoint can trigger the GitHub Action Workflow. This will most depend on how the web hook is called, if it's part of a dashboard, you could ensure the user in question has permission to perform the action in question or it could be as simple as using passphrase.

This enables you to identify the platform where your app is running on and modify the behavior of your Angular app appropriately. The CDK Platform Module makes the following information available to you:

• Is Android - Whether the OS is Android
• Is iOS - Whether the OS is iOS
• Is Firefox - Whether the browser is Firefox
• Is Edge - Whether the browser is Edge
• Is Safari - Whether the browser is Safari
• Is Blink - Whether the rendering engine is Blink
• Is Webkit - Whether the rendering engine is WebKit
• Is Trident - Whether the rendering engine is Trident
• Supported Input Types - A list of input form field types supported by the browser i.e. number, password, radio, range, reset, search, submit, tel, text, time, url, etc.
• Whether the browsers supports Scroll Behavior -
• And Whether the browser supports passive event listeners.

Installation

Using yarn:

$ yarn add @angular/cdk

Using NPM:

$ npm install @angular/cdk

Usage

First, we will need to import the PlatformModule from @angular/cdk/platform inside our app module, as shown below:

// other imports
import { PlatformModule } from '@angular/cdk/platform';

@NgModule({
  declarations: [
    AppComponent,
    // ... components
  ],
  imports: [
  	// ... other modules
    PlatformModule,
  ],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

NB: If you are using feature or shared modules, you will need to import PlatformModule inside the module where the component using it is located.

Then, we are going to inject the Platform service into the component where we want to use the platform information.

import { Platform } from '@angular/cdk/platform';
// ... other imports

@Component({
 // ... component metadata
})
export class Component  {
  constructor(private platform: Platform) {}
}

And finally, we can determine the browser platform information as shown below.

this.platform.ANDROID; // check if OS is android
this.platform.FIREFOX // check if Browser is Firefox
this.platform.IOS; // check if OS is iOS
this.platform.BLINK; // check if render engine is Blink
this.platform.isBrowser; // check if the app is being rendered on the browser

For an up-to-date reference for the API, please refer to the official docs here.

Example

We are going to implement a share functionality for our web app, where on mobile devices i.e. iOS and Android, we will use native share while on Desktop, we will use share buttons for each Social Media Platform.

We will use the PlatformModule to determine if the user is on iOS and Android, and then we will use the WebShare API. For other devices i.e. On the desktop, we will just show a simple twitter share button instead. Here is what our component looks like:

import { Platform } from '@angular/cdk/platform';

// ... component metadata
export class CustomSocialShareComponent implements OnInit {
  @Input()
  shareUrl: string;

  @Input()
  title: string;

  @Input()
  text: string;

  @Input()
  hashtags: string;

  tweetShareUrl: string;

  isNativeShareSupported = false;

  constructor(private platform: Platform) {}

  ngOnInit(): void {
    // show native share if on Android and IOS and if it is supported
    this.isNativeShareSupported =
      navigator.share && (this.platform.ANDROID || this.platform.IOS);
    const baseUrl = 'https://twitter.com/intent/tweet';
    this.tweetShareUrl =
      baseUrl +
      '?url=' +
      this.shareUrl +
      '&via=mwycliffe_dev&text=' +
      this.title +
      '&hashtags=' +
      this.hashtags;
  }

  async nativeShare() {
    if (navigator.share) {
      await navigator.share({
        title: this.title,
        text: this.text.substr(0, 200),
        url: this.shareUrl,
      });
    }
  }
}

Our share component above, has a property named isNativeShareSupported - which is a boolean. We are checking whether the current browser supports native share, and the platform is iOS or Android before setting that property to true. And then we can use this property to show the correct UI, as shown below:

<ng-container *ngIf="isNativeShareSupported; else showSocialShareButton">
  <a (click)="nativeShare()" class="space-x-2">
    <span>Share this article</span>
  </a>
</ng-container>

<ng-template #showSocialShareButton>
  Share on this article: <a target="_blank" [href]="tweetShareUrl">Twitter</a>
</ng-template>

Conclusion

In this article, we have learned how to use CDK Platform Module to check the platform details in which our app is running on. This is a simple and quite useful way of modifying the behavior of your Angular app based on the platform being used. This can lead to an improved UX as you can enable enhanced features to users with access to them while providing a decent fallback to users without access to the enhanced features.

Links

• CDK Documentation on Platform Module - Link.
• Integrate with the OS sharing UI with the Web Share API - Link.
• Does not use passive listeners to improve scrolling performance - Link.
• scroll-behavior - Link.
• How to build a reusable Modal Overlay/Dialog Using Angular CDK - Link.
• Building a Custom Stepper using Angular CDK - Link.

Where to start? Let's start by looking at the stack that went into building this blog.

The Stack

To easily manage the content, I went with Ghost CMS, which gives me an effortless way to add, update content. My previous blog was built with Hugo, which uses markdown and as much that was fun to work with initially, the process from writing a post all the way to publishing got exceedingly long and quite tiresome. I found myself posting less and less.

For the frontend, I decided to go with Angular and use Scully to generate static version website for the blog, with Tailwind for the UI. And then, the website itself is hosted on Firebase Hosting.

If you think that's it, then you clearly didn't read the title of this post. Since the website is statically generated, it means the content is fetched at build time instead of REST API request on load. This means that the website doesn't serve live updates or new articles unless it's rebuilt. To solve this problem, I am using web hooks to trigger a CI to do a rebuild and deploy the new site.

Why?

I know what is going on your mind, why go into all the trouble for a simple blog. I could have easily gotten the same or even better results on Medium or WordPress. I don't know what to say, but I enjoy building stuff. Working on this gave me an opportunity to create something and have fun at the same time.

In this case, I got interested in trying out some innovative technologies that otherwise I wouldn't get a chance at work or anywhere else to work with. So, having already an existing blog - codinglatte.com - I had a few requirements I need for a blog.

The first was, I needed an effortless way to add and manage blog posts, a UI quite like what is provided by WordPress or Medium. Ghost CMS provides an easy-to-use UI that's quite intuitive, on top of that, I can easily manage when posts go live via their schedule feature.

The second requirement I had was I needed to be able to add new features on top of the blog. I have dreams for this to evolve beyond a blog to a platform where I can interact and provide move value to my readers. For this I turned to Angular, with Scully for SSG, but this could have easily been Gatsby or Next.JS. The biggest benefit of this is having all the blogs posts and pages, progenerated to static HTML, which would allow the website to load fast and be responsive, while being cost effective.

And lastly, I needed to be able to hit publish and the blog would be re-built, and the recent changes push lived without me having to do anything extra. For this, I turned to GitHub Actions to handle the build process and Ghost CMS Webhooks to trigger the build GitHub Action.

As you can see, this gave me an opportunity to work with a few tools that I could not resist. This was my first foray into Scully, and I could not turn down the opportunity of learning how it works with a real project with potential of being used by thousands of people down.

Conclusion

So, after going through that process, would I do it again? The simple answer for me yes. I have learned a great deal from this, and I am looking to share what I have learned here, among other stuff on this blog. It was fun, challenging and gave me an opportunity to learn and improve my skills.

Would I recommend you do the same? The answer is it depends, as I stated earlier, you can easily get a blog up and learning with medium or some other platform with excellent results, and all you have to think about are the posts themselves.

On the other hand, building out your platform presents you with a lot of flexibility and is quite rewarding when everything is working. It also gives you the opportunity to experiment and learn while working on project that will be used by quite a few people, probably thousands if your blog posts are great.

Improved Stability

I know, this sounds like a moot point but the RxJS team has made some changes on how they release new versions to improve stability.

The RxJS team is partnering with Google, thus ensuring smooth and stable releases. Google will run pre-release versions of RxJS against their mono-repo build targets where RxJS is used widely.

If anything breaks, they work together with RxJS core team to resolve the issues. The goal here is to ensure that releases are as stable as possible especially patch and minor releases which should be safe to update to.

Latest Typescript Version Support

RxJS is adopting features from the latest versions of Typescript. By supporting the latest version of Typescript, we get the following benefits:

Type Inference

Type inference around n-argument is being improved, by allowing TypeScript to do all the type inference. Before, there was a limit of around 8 argument before RxJS could not infer the type anymore, but thanks to TypeScript, this limit no longer exists. This allows RxJS to return an observable whose types closely match the arguments passed.

Union Types Improvements

Unions types are also being improved, ensuring type inference around return types are accurate without needing to explicitly type things.

Fixing Bad Types

Another fix that will be coming along in v7 is for bad types. A good example is the toPromise operator, in v7, it will also return union type alongside the actual type, since if an observable completes without emitting anything, it returns undefined instead of throwing an error. From v7, you will need to check if the returned promise value is undefined before using it.

toPromise Operator is being deprecated

The toPromise operator is getting deprecated in RxJS 7 and will get removed completely in v8. In its place, there are two operators – lastValueFrom() and firstValueFrom(). The lastValueFrom() waits from the last value of an observable before resolving the promise. On the other hand, the firstValueFrom() resolves on the first value from an observable before unsubscribing and resolving the promise.

There are two reasons the operator is being deprecated, the first being, it is unclear to users when the promise resolve and returns undefined instead of throwing an error. The two replacement operators will throw an empty error if the observable completes without a value. The toPromise() operator would have returned undefined instead of throwing an error. The second reason is that they are more explicit on when the promise resolves i.e. whether it is the first value or the last value that will be resolved.

Before:

const numbers$ = of(1,2,3,4,5)

// toPromise() will return the last value of the observable
numbers$.toPromise().then(n => console.log("toPromise(): " + n))

After:

const numbers$ = of(1,2,3,4,5)

// lastValueFrom() will return the last value just like to promise
lastValueFrom(numbers$).then(n => console.log("lastValueFrom(): " + n))

// firstValueFrom() will return the first value of the observable
firstValueFrom(numbers$).then(n => console.log("firstValueFrom(): " + n))

new animationFrame() method

animationFrame() is a new static method that fires an observable that gives the amount of time elapsed in milliseconds since the start of the observable. This provides a method to measure the progress of an observable without the need of a deeper understanding of how RxJS works under the hood. With animationFrame(), you can control the animation of an object using RxJS.

Consuming AsyncIterable Support

AsyncIterable objects are now fully supported in an array of RxJS operators and will be accepted anywhere where an observable or a promise is accepted.

Take for instance the following range object:

const range = {
  from: 1,
  to: 5,

  [Symbol.asyncIterator]() { // (1)
    return {
      current: this.from,
      last: this.to,

      async next() { // (2)
        await wait(1000);
        if (this.current <= this.last) {
          return { done: false, value: this.current++ };
        } else {
          return { done: true };
        }
      }
    }; 
  }
};

We can consume the above AsyncIterable object as follows:

from(range).subscribe(x => console.log(x))

Example:

NB: You can use the rxjs-for-await library by Ben Lesh to make your observables compatible with AsyncIterables.

Renamed Operators

Some of the legacy operators including deprecated ones that has the same names as their creation methods, have been renamed to reduce collision. This has been done by adding with at the end of the operators. For instance, the following operators: zip, combineLatest, merge, concat have been renamed to zipWith, combineLatestWith, mergeWith, concatWith.

NB: The Deprecated operators with be removed in the next major version of RxJS.

new resetOnSuccess option for retry

A new option called resetOnSuccess has been added to the retry options, which lets you reset the counter back to zero whenever it’s successful. In version 6, the counter is never reset and if the retries becomes successful for a while and then start failing, it would pick up where it left. This would lead the retries being exhausted faster in subsequent retries.

retry({
  count: 5, 
  resetOnSuccess: true 
})

Reducing Scheduler Footprint

Some operators include the Scheduler which means the Scheduler ends up within your final bundle even if you are not using it. The goal is to ensure that extra code from the Scheduler ends up in your final bundle when you explicitly need it.

To Achieve this, a new TimeStampProvider has been added that has a now method in it. This allows the third argument of the replaySubject to be defaulted to the date objected, which is native and does not need to be shipped. You can override this by passing any object that has a now method. RxJS will continue over the course of v7 to try and reduce the bundle size that is shipped with your application in non-breaking ways.

Scheduler Arguments are being Deprecated

Passing Scheduler arguments is being deprecated, instead you should switch to scheduled() or observeOn() APIs. The Scheduler arguments are not going to disappear completely but will be retained in operators that still need them such as timer and interval.

Removing Subscription and Tap Callback Options

Passing multiple callback methods when subscribing or tapping to an observable will be deprecated. From v7 onwards, you can use a single callback or an object with data, error, and complete fields for respective callbacks. By removing the multiple callback option, most of the logic that goes to determine which callback method you used can be removed. This will lead to a leaner and faster RxJS library.

Deprecated:

source$.pipe(tap(
  data => console.log(data),
  error => console.log(error)
)).subscribe(
  data => console.log(data),
  error => console.log(error)
)

The following are acceptable:

Passing a single callback:

source$.pipe(tap(
  data => console.log(data)
)).subscribe(
   data => console.log(data)
)

Passing an object with multiple callbacks:

source$.pipe(
  tap({ 
    next: data => console.log(data),
    error: e => console.log(e)
  })
).subscribe(
  {
    next:  data => console.log(data), 
    error:  err => console.log(err),
  }
)

subscription.add() returns a void

subscription.add() is used to put together multiple subscriptions so that you can unsubscribe to all of them together. in v6, you could chain subscription.add() when adding multiple subscription. The API for chaining is being removed as it led to inconsistent un-subscription behavior.

In v7, you will have to add the subscriptions one at a time.

Beyond v7.0

Version 7.1

In line with semantic versioning, v7.1 is a minor change with non-breaking features and improvements. We are likely to see the following in v7:

ESLint Rules and Transformations - This is expected in v7.1 and the goal is to help developer to gradually remove and replace deprecated operators that will be removed. There will also be minor improvements and a lot of preparation for version 8.

Version 8

In v8, we will see the deprecations where the team was able to add ESLint code transformations removed. This is to ensure that developers have an uncomplicated way of replacing deprecated APIs and are following the best practices. On top of that, there are some experiments being done by the RxJS team in progress and the impact is a smaller bundle size, in some cases, as small as 40% of the current size. RxJS is also going try and keep up with the latest versions of Typescript and JavaScript, whenever it is possible.

Additional Resources

• Rxjs + For + Await… What? - RxJS inDepth
• Async iteration and generators
• for await...of
• The State of RxJS by Ben Lesh

This is going to be the first of a few articles, focusing on ways you can
utilize Angular CDK to implement common interaction patterns within your
application.

Demo and Source Code

You can find the link to the demo here and the GitHub repo for this post here.

Prerequisites

Install Angular CLI and create a new Angular project – link.

Setup Bulma inside your Angular Project.

Install Angular CDK – npm i @angular/cdk or yarn add @angular/cdk

The article is divided into two sections:

• The Basics - a Quick look at how to use Angular CDK Overlay
• Building a Reusable Modal Overlay - A detailed guide into building a reusable
  modal overlay.

The Basics

Let us get the basics out of the way first. Assuming you have installed Angular CDK you will need to import OverlayModule into your app module.

import {OverlayModule} from '@angular/cdk/overlay';

And then, inject the Overlay service and ViewContainerRef into your component.

constructor(private overlay: Overlay, private viewContainerRef: ViewContainerRef) {}

To show a modal overlay, you need either a Template or an Angular Component holding the content you would like to show. Let’s look at how you can use both below:

Using a Template

Inside the template of our component, let’s define a new template and add our overlay content:

<ng-template #tpl>
  <div class="modal-card">
  <header class="modal-card-head">
    …
  </header>
  <section class="modal-card-body">
    …
  </section>
  <footer class="modal-card-foot">
    …
  </footer>
 </div>
</ng-template>

Then, add a method to show the overlay and it accepts an ng-template reference as the parameter.

openWithTemplate(tpl: TemplateRef<any>) {}

Then, Inside the above method, we are going to create an overlay. We will start by defining the configs of the overlay – OverlayConfig. In our case, we will just set the hasBackdrop and backdropClass properties. For backdropClass we are using modal-background a Bulma CSS Framework class. You can find all the Overlay Configurations you can add here.

const configs = new OverlayConfig({
 hasBackdrop: true,
 panelClass: ['modal', 'is-active'],
 backdropClass: 'modal-background'
});

NB: For backdrop click to dismiss the modal overlay to work, you might need
to disable pointer-events for your modal, for some CSS Frameworks like
Bulma. This is because CDK Overlay doesn't add them to DOM in the nested order
of modal ➡ modal-background ➡ modal-content, but rather modal ➡ modal-content, while the backdrop is a separate div tag not nested under
modal, but on a level above modal class div tag.

For Bulma CSS framework case, you can override the default behavior like this:

.modal {
  pointer-events: none !important;
}

.modal-content {
  pointer-events: all !important;
}

Then, let’s create an OverlayRef, by using the create method of the Overlay service and pass the configs we just created above:

const overlayRef = this.overlay.create(configs);

And then we can attach our template, using TemplatePortal, passing our template and ViewContainerRef which we injected into our component:

overlayRef.attach(new TemplatePortal(tpl, this.viewContainerRef));

Now, we can trigger the method with a click of a button:

<button (click)="openWithTemplate(tpl)" >
 Show
</button>

Using a Component

The difference between the two is that we will be using ComponentPortal instead of TemplatePortal to attach the component to the OverlayRef.

this.overlayRef.attach(
 new ComponentPortal(OverlayComponent, this.viewContainerRef)
);

NB: The component must be added to the list of entryComponents in your App Module.

Closing Modal Overlay on Backdrop Clip

You can close the overlay when the backdrop is clicked by subscribing to the backdropClick() and then calling the dispose method.

overlayRef.backdropClick().subscribe(() => overlayRef.dispose());

Making a Re-usable Modal Overlay

Building modal overlays as shown above works very well if you are building one or two of them, however, it does not really scale very well. Wouldn’t it be nice if you could build a re-usable modal overlay that you can then use across your Angular project or projects? Wouldn’t it also be nice if we could be able to pass data to and receive data from the modal?

Objective

A service to open the modal, than can be injected into any component

A way to subscribe to when the modal is closed and access the response.

Pass data to the modal

Pass data as a String, Template or Component.

Overlay Ref Class

We are going to start by extending the OverlayRef. We will create a custom OverlayRef, creatively named MyOverlayRef, which is going to accept the OverlayRef, content and the data to pass to our modal overlay. The content can be of type string, TemplateRef or Component.

// R = Response Data Type, T = Data passed to Modal Type
export class MyOverlayRef<R = any, T = any> {
 …
 constructor(public overlay: OverlayRef, public content: string | TemplateRef<any> | Type<any>, public data: T ) {
  …
 }
 …
}

Then, Inside the MyOverlayRef class, we are going to add a BehaviorSubject property named afterClosed$ which we can subscribe to get data once the overlay is closed.

afterClosed$ = new Subject<OverlayCloseEvent<R>>();

The behavior subject is going to pass back an OverlayCloseEvent, which contains the data from modal and how the modal was closed. Feel free to modify this to cover your needs.

export interface OverlayCloseEvent<R> {
 type: 'backdropClick' | 'close';
 data: R;
}

Next, we need to add a private method to close the overlay. The method will dispose off the overlay, pass the OverlayCloseEvent back to the subscriber and complete the afterClosed$ Observable.

private _close(type: 'backdropClick' | 'close', data: R) {
  this.overlay.dispose();
  this.afterClosed$.next({
   type,
   data
  });

  this.afterClosed$.complete();
 }

And then, we are going to add a second public close method. It will only accept data as a parameter and will call the private _close method, to close the modal.

close(data?: R) {
 this._close('close', data);
}

And finally, we are going to subscribe to backdropClick and close the modal when clicked. We are adding this subscriber to the MyOverlayRef constructor.

overlay.backdropClick().subscribe(() => this._close('backdropClick', null));

Overlay Component

Next, we are going to add a special component that we will use to show our modal content. If it is a simple string, we will bind it to a div, while we can use either ngTemplateOutlet and ngComponentOutlet to load the template and component respectively.

Component Class

We are going to start by injecting an instance of our MyOverlayRef into the component.

constructor(private ref: MyOverlayRef) {}

And then, let’s define 3 more properties inside our component class:

contentType: 'template' | 'string' | 'component' = 'component';
content: string | TemplateRef<any> | Type<any>;
context;

Then, OnInit, we need to determine the content type and set the above properties appropriately.

ngOnInit() {
  if (typeof this.content === 'string') {
   this.contentType = 'string';
  } else if (this.content instanceof TemplateRef) {
   this.contentType = 'template';
   this.context = {
    close: this.ref.close.bind(this.ref)
   };
  } else {
   this.contentType = 'component';
  }
}

And finally, we are going to be adding a global close button, so let’s add a close method:

close() {
 this.ref.close(null);
}

And finally, remember to add the Overlay component as an entryComponent in your app module.

Component Template

In the template, we are going to use ngSwitch to switch between content type and add a global close button for our modal.

<div class="modal-content">
 <ng-container [ngSwitch]="contentType">
  <ng-container *ngSwitchCase="'string'">
      <div class="box">
        <div [innerHTML]="content"></div>
   </div>
  </ng-container>
  
  <ng-container *ngSwitchCase="'template'">
   …
  </ng-container>

  <ng-container *ngSwitchCase="'component'">
   …
  </ng-container>
 </ng-container>
</div>

<!-- You can also add a global close button -->
<button (click)="close()" class="modal-close is-large" aria-label="close"></button>

For template content type, we will use ngTemplateOutlet, passing the template, which is the content and then pass the context:

<ng-container *ngTemplateOutlet="content; context: context"></ng-container>

And while for component content type, we will use ngComponentOutlet, passing the Component, which is the content:

<ng-container *ngComponentOutlet="content"></ng-container>

The Overlay Service

Next, we are going to create an Overlay service, which we can inject into any component we want to use our modal overlay. Where we are going to inject Overlay Service and the Injector.

export class OverlayService {
  constructor(private overlay: Overlay, private injector: Injector) {}
}

Then, add an open method, which will accept content and data. The data param, in this case, is the data you would like to pass to your modal.

open<R = any, T = any>(
 content: string | TemplateRef<any> | Type<any>,data: T): MyOverlayRef<R> {
 …
}

Inside the method, first, we need to create an OverlayRef object by using the Overlay create method. Feel free to customize the configs to suit your needs.

const configs = new OverlayConfig({
 hasBackdrop: true,
 panelClass: ['modal', 'is-active'],
 backdropClass: 'modal-background'
});

const overlayRef = this.overlay.create(configs);

Then, let’s instantiate our MyOverlayRef Class passing the OverlayRef object we created above, then content and the data, both from the method parameters.

const myOverlayRef = new MyOverlayRef<R, T>(overlayRef, content, data);

Create an injector using PortalInjector, so that we can inject our custom MyOverlayRef object to the overlay component, we created above.

const injector = this.createInjector(myOverlayRef, this.injector);

And finally use ComponentPortal, to attach the OverlayComponent we created above and the newly created injector and return a MyOverlayRef object.

overlayRef.attach(new ComponentPortal(OverlayComponent, null, injector));
return myOverlayRef;

And here is the method for creating a custom injector using PortalInjector:

createInjector(ref: MyOverlayRef, inj: Injector) {
 const injectorTokens = new WeakMap([[MyOverlayRef, ref]]);
 return new PortalInjector(inj, injectorTokens);
}

And that’s it, we now have a re-usable modal overlay, that we can use anywhere inside our application.

Usage

First, inject the Overlay Service in the component where you would like to open a new modal overlay.

constructor(private overlayService: OverlayService) {}

Then, inside the method you would want to trigger the modal overlay, you just
use the open method and pass the content and any data you want to pass to the
modal overlay.

const ref = this.overlayService.open(content, null);

ref.afterClosed$.subscribe(res => {
 console.log(res);
});

The content can be a simple string or a Template or a Component.

String

const ref = this.overlayService.open("Hello World", null);

Template

<ng-template #tpl let-close="close">
  <div class="modal-card">
  <section class="modal-card-body">
   A yes no dialog, using template
  </section>
  <footer class="modal-card-foot">
   <div class="buttons">
    <button (click)="close('yes')" type="button" class="button is-success">Yes</button>
    <button (click)="close('no')" type="button" class="button is-danger">No</button>
   </div>
  </footer>
 </div>
</ng-template>

And a button to open the modal:

<button (click)="open(tpl)" class="button is-small is-primary">
 Show
</button>

And then open the overlay with an open method:

open(content: TemplateRef<any>) {
 const ref = this.overlayService.open(content, null);
 ref.afterClosed$.subscribe(res => {
  console.log(res);
 });
}

Component

open() {
 const ref = this.overlayService.open(YesNoDialogComponent, null);
 ref.afterClosed$.subscribe(res => {
  console.log(res);
 });
}

You can also inject the MyOverlayRef inside the component to access data and the close method.

constructor(private ref: MyOverlayRef) {}

This allows you to pass data to the component and trigger the closing of the modal from within the component.

close(value: string) {
 this.ref.close(value);
}

NB: Please remember to add the component as an entryComponent inside your App Module.

You can find all of the above code here and the demo here.

Additional Resources

• Angular Component Development Kit (CDK)
• Creating Powerful Components with Angular CDK
• API reference for Angular CDK overlay
• Angular ng-template, ng-container and ngTemplateOutlet - The Complete Guide To Angular Templates

Infinite scrolling is a technique where loading of content is done continuously as the user scrolls down, without any action from the user. This has popularized by social media sites and apps such as Twitter, where Twitter loads more tweets as you scroll down. This is a form of pagination but requires no user input to load the next page but instead watches scroll position. When they get close to the end, the next bunch of tweets gets loaded, as shown below:

Prerequisite

• Flutter Installation and Setup – Link.

Creating a ListView

We are going to start by creating a ListView to display GitHub Repositories. We will use the GraphQL package for flutter and will load then in bunches of 20. We are also going to display a loading animation when adding fetching new GitHub repositories.

ListView(
  children: <Widget>[
    for (var repository in repositories)
      // .. list of widgets
    if (result.loading)
      Row(
        mainAxisAlignment: MainAxisAlignment.center,
        children: <Widget>[
          CircularProgressIndicator(),
        ],
      ),
  ],
),

Use ScrollController to Detect Scroll Position

Next, we need to determine when to load more GitHub Repositories, i.e. when we are at or near the bottom of the list view. To achieve this, we are going to use ScrollController – Link. We are going to listen to ScrollController, which will let us know whenever we scroll. We can then check if we are at the end or near the end of ListView, and in that case, we load more Repositories.

We will start by declaring a new widget property, named _scrollController.

class Widget extends StatelessWidget {
  // ...
  
  ScrollController _scrollController = new ScrollController();

  @override
  Widget build(BuildContext context) {
    // ...
  }
}

Then, we need to attach our ScrollController to our ListView above.

ListView(
  controller: _scrollController,
  children: <Widget>[
    // ... widgets
  ],
),

And finally, we need to listen to ScrollController and check where the user is at scrolling.

_scrollController
  ..addListener(() {
    if (_scrollController.position.pixels ==
        _scrollController.position.maxScrollExtent) {
      // ... call method to load more repositories
    }
  });

From the above code, we are waiting until the scroll position is at the very end. This might not be convenient for you and you might want to trigger the method to fetch more items earlier, let’s say at 90%.

_scrollController
  ..addListener(() {
    var triggerFetchMoreSize =
        0.9 * _scrollController.position.maxScrollExtent;

    if (_scrollController.position.pixels >
        triggerFetchMoreSize) {
      // call fetch more method here
    }
  });

Final Thoughts

This is a simple way to implement infinite scrolling inside a ListView in flutter. You can find the above demo in my GitHub account here.

Additional Resource

• GraphQL Package for Flutter – Link.
• ListView API Reference – Link.
• ScrollController API Reference – Link.
• GitHub GraphQL Explorer – Link.