DEV Community: Maina Wycliffe

On-Device AI with the Google Chrome Prompt API

Maina Wycliffe — Mon, 17 Nov 2025 18:50:02 +0000

Unless you’ve been living under a rock, it’s hard to miss the rise of Generative AI. At the centre of this movement are Large Language Models (LLMs) such as Google’s Gemini and OpenAI’s ChatGPT. Typically, building solutions around these models involves sending data to their APIs and receiving a response.

But not everyone is comfortable with this approach. Concerns around privacy, trust, legal compliance, and governance often arise. This is where on-device AI comes in: data is processed locally, addressing most of these issues.

In this article, we’ll explore how to use the Chrome On-Device Prompt API to process data locally. This is the first in a series of articles covering Chrome’s on-device AI capabilities.

Step 1: Download Google Chrome & Enable Required Flags

Make sure you’re running the latest version of Chrome (currently version 142). These APIs are Chrome-specific for now, though they may eventually become web standards.

Enable the following flags by navigating to chrome://flags in your browser:

#prompt-api-for-gemini-nano
#optimization-guide-on-device-model
#prompt-api-for-gemini-nano-multimodal-input

Then, restart the browser, using the relaunch bar that will be displayed at the bottom of the page. You can learn more about Chrome Flags here.

We can confirm that the api is enabled by running the following code inside the browser console, as shown below:

if (typeof LanguageModel !== 'undefined') {
  console.log("Model is enabled")     
}

Step 2: Check Model Availability

Now that we have enabled the on-device model on Chrome, we need to check if the user has already downloaded the model to use, and if not, download it. Otherwise, we can't prompt the model until that is done.

We can do this by calling the LanguageModel.availability() method, as shown below:

 const status = await LanguageModel.availability();

The above model checks whether the user has downloaded the model and is ready for use. If it's not, the next step is to download the model.

If not yet downloaded, you’ll need to trigger the download (~1.5 GB). Note that user interaction is required before downloading. You can check this with:

if (navigator.userActivation.isActive) {
  // Create an instance of a built-in API
}

Another approach is to use a button to trigger the download, and then you wouldn't need to check for activation, as that would only be triggered when the user clicks the download button.

Step 3: Download the Model

Next, we can use the LanguageModel.create method to trigger the download of the model and monitor the progress, as shown below:

const aiSession = await LanguageModel.create({
  monitor: (m) => {
    m.addEventListener('downloadprogress', (e) => {
      const progress = e.loaded * 100;
      this.downloadProgress.set(progress);
    });
  }
});

Make sure to report the progress and inform the user of what's going on, as this is a large download and may take a while. For Angular, we can use signals in a service to report that back to the user, as shown below:

@Injectable({
  providedIn: 'root',
})
export class ChromeAiService {
  private session = signal<AILanguageModel | null>(null);
  readonly isAvailable = signal<boolean>(false);
  readonly availability = signal<AIAvailability>('no');
  readonly downloadProgress = signal<number>(0);
  readonly isDownloading = signal<boolean>(false);

  async initializeSession(): Promise<void> {
    if (!this.isAvailable()) {
      throw new Error('Chrome AI is not available');
    }

    try {
      this.isDownloading.set(true);
      this.downloadProgress.set(0);

      const aiSession = await LanguageModel.create({
        monitor: (m) => {
          m.addEventListener('downloadprogress', (e) => {
            const progress = e.loaded * 100;
            this.downloadProgress.set(progress);
          });
        },
      });

      this.session.set(aiSession);
      this.isDownloading.set(false);
      this.downloadProgress.set(100);
    } catch (error) {
      this.isDownloading.set(false);
      throw error;
    }
  }
}

Step 4: Prompt the Model

Once the model is downloaded, it's ready for use.

const stream = session.analyzeText(prompt);

const prompt = "YOUR PROMPT";
let result = '';

for await (const chunk of stream) {
  result += chunk;
}

Please note, the model is very small, with a very limited number of tokens.

We can also pass an initial prompt, which can be used to give it a persona and give it some ground rules, as shown below:

const languageModel = await LanguageModel.create({
  initialPrompts: [{
    role: 'system',
    content: 'You are a helpful assistant and you speak like a pirate.'
  }],
});

You can learn more about the Prompt API here.

Step 5: Clean up

Afterwards, always terminate the session when you are done.

session.destroy();

Conclusion

We’ve covered enabling the Prompt API, checking availability, downloading the model, prompting it, and cleaning up. This is just one of several on‑device ML APIs in Chrome — future articles will explore the rest.

Genkit Tool Calling: Give AI Models (LLMs) the Tools to Get Things Done

Maina Wycliffe — Mon, 16 Jun 2025 13:27:38 +0000

AI Models are taking over the world, and we are all looking for ways to use them to solve different problems. One common issue with Large Language Models (LLMs) is their training data, in that they only know what they were trained on. This is great when we want them to answer general questions, but not so useful when we want them to answer questions based on private data, i.e., customer data.

There are a number of ways to solve this issue other than training your own AI models. One of the options is Retrieval-Augmented Generation (RAG), where we ground the LLMs based on external data to improve the accuracy and relevance of the responses.

The other option is Function Calling, which is the subject of today’s article. Function calling—known as tool calling in Genkit—involves giving AI Models a structured way to interact with your application/system or external data sources (APIs) to accomplish various tasks and ensuring it has up-to-date data. The AI Model will then call those functions we provide to accomplish various tasks, such as to fetch user data, create a ticket for the user, and so on.

To demonstrate this, we will be building a simple customer support agent that will answer questions from customers, and the AI Model will use the tools we provide to determine which tools it needs to call to accomplish the customer’s goal.

If you are new to Genkit, please check out the official docs on how to get started, as this is beyond the scope of this post.

Please subscribe for future posts like this:

Subscribed

Defining Genkit Tools

In Genkit, tools are special functions that contain information about what they are meant to accomplish and the means to accomplish the intended task — a function.

A tool in Genkit is defined using the defineTool method which accepts two arguments: a config object and a function.

ai.defineTool(
  {
    name: 'toolName',
    description: 'Tool Description',
  },
  async ({ customerId }) => {
    // implementation to fetch customer details
  },
);

Please Note:

The ai instance is created by calling genkit function, passing in a number of configurations such as plugins for the AI Model you want to use, and the default model. For more information, checkout the Genkit documentation, here.
import { gemini20Flash, googleAI } from '@genkit-ai/googleai';
import { genkit } from 'genkit';

const ai = genkit({
  plugins: [googleAI()],
  model: gemini20Flash,
});

IMPORTANT!

Genkit tool calling support depends on the model, the model API, and the Genkit plugin for the model. Not all models support tool calling. Please consult the documentation to ensure that the model you intend to use supports Genkit tool calling.

For this post, we will be using Gemini 2.0 Flash, which supports tool calling.

A config is where we describe what the tool does; we give a descriptive name and a description that describes the tool's intended purpose. We can also include input and output JSON schemas (supports zod out of the box) among other options. Only the description and name are required.

The second argument is the function where we implement the tool’s objective. For instance, inside the function, we can make a DB call, an API call or any other deterministic operation, based on the tool’s intended objective.

For instance, in our case, we might want to define a tool to fetch customer information, given a customer ID. In this case, we would define a GetCustomerDetails tool that looks up the customer details from our database.

Please note we are providing an input and output schema to ensure data is returned in a very specific format, all the time, and we will ensure we provide a good description of our tool.

const getCustomerDetailsTool = ai.defineTool(
  {
    name: 'GetCustomerDetails',
    description: 'Fetches details of a customer by ID',
    inputSchema: z.object({
      customerId: z.string().describe('The ID of the customer to fetch details for'),
    }),
    outputSchema: customerSchema,
  },
  async ({ customerId }) => {
    // This could be a database call or an API request in a real application.
    const customer = customers.find((customer) => customer.id === customerId);
    if (!customer) {
      throw new Error(`Customer with ID ${customerId} not found`);
    }
    return customer;
  },
);

Now that we have created our first tool, we will need to pass it to the AI Model so it can use it, if need be, based on the customer’s question. In Genkit, there are several ways of achieving this, depending on whether we are using a flow, a prompt, or we are invoking the generate method directly inside the function.

When calling the generate method, passing the tool, in the tools’ options, alongside the prompt as shown below:

const { text } = await ai.generate({
  prompt: `
  You are an eCommerce Customer Service AI.
  You can answer questions about customers and their orders.
  You have access to the following tools:
  - Get Customer Details: Fetches details of a customer by ID.
  - Get Customer Orders: Fetches orders for a specific customer, by customer ID.
  Use the tools to answer questions about customers and their orders.
  If you need to fetch customer details, use the Get Customer Details tool.
  If you need to fetch customer orders, use the Get Customer Orders tool.
  If you cannot answer a question, respond with "I don't know" or "I cannot answer that question".

  When answering questions, use the following format:
  - If the question is about customer details, provide the customer's name, email, and phone number.
  - If the question is about customer orders, provide the number of orders placed and details of the most recent order.
  - If the question is about a product, provide the product name, price, and description.

  Use all tools to fetch the necessary information, do not return IDs, instead return the relevant details the user is interested in.

  Example questions:
  - What is the email address of customer with ID 1?
  - How many orders has customer with ID 2 placed?

  The customer id is ${customerID} and the question is: ${question}
  `,
  tools: [getCustomerDetailsTool],
  toolChoice: 'auto',
});

As you can see, our prompt is rather detailed, as we have to clearly instruct the AI Model to behave exactly the way we want, and reduce instances of it hallucinating. In cases where it has no answer, we want the AI model to say it doesn’t know, instead of hallucinating.

We can put the above generate method call in a function, and call it as shown below. On top of that, we are passing our tool — getCustomerDetailsTool — in the tools section.

async function run() {
  const { text } = await ai.generate(...);
  // log our response
  console.log(text);
}

run();

However, running the above can be very difficult, as you need to pass in the inputs in the correct format and almost impossible to debug. This is where Genkit Developer UI comes in.

Genkit Developer UI

Genkit provides a developer UI where you can view, invoke and test your flows, prompts, tools, among others, in a very user-friendly UI, which enhances the developer experience.

To launch the Genkit Developer UI, you can do so by running the following command:
npx genkit start -- npx tsx --watch index.ts
In the above command, genkit is the genkit cli, and tsx is an NPM package for executing TypeScript files, without needing to transpile to Javascript first. index.ts is the file which contains our code, and the entry file of our project.

Since we have already defined our tool, running the above command, we should be able to see it in the UI and even interact with it, as shown below:

Defining a Genkit Flow

For our case, we are going to switch to a flow. We will define a flow using the defineFlow method, which takes two arguments — a config object and a function to be executed when the flow is called.

For the flow config object, we will set the name of the flow, the input and output schema, keeping things simple for now. In the function, we will call the generate method, just like we previously did. We will return the text, so we can see the response of the AI Model in the UI.

const assistant = ai.defineFlow(
  {
    name: 'eCommerceCustomerServiceAI',
    inputSchema: z.object({
      customerID: z.string().describe('The ID of the customer to fetch details for'),
      prompt: z.string().describe('The question or request for customer service'),
    }),
    outputSchema: z.string().describe('The response from the AI assistant'),
  },
  async ({ customerID, prompt }) => {
    const { text } = await ai.generate({
      prompt: `
      You are an eCommerce Customer Service AI.
      You can answer questions about customers and their orders.
      You have access to the following tools:
      - Get Customer Details: Fetches details of a customer by ID.
      - Get Customer Orders: Fetches orders for a specific customer, by customer ID.
      Use the tools to answer questions about customers and their orders.
      If you need to fetch customer details, use the Get Customer Details tool.
      If you need to fetch customer orders, use the Get Customer Orders tool.
      If you cannot answer a question, respond with "I don't know" or "I cannot answer that question".

      When answering questions, use the following format:
      - If the question is about customer details, provide the customer's name, email, and phone number.
      - If the question is about customer orders, provide the number of orders placed and details of the most recent order.
      - If the question is about a product, provide the product name, price, and description.

      Use all tools to fetch the necessary information, do not return IDs, instead return the relevant details the user is interested in.

      Example questions:
      - What is the email address of customer with ID 1?
      - How many orders has customer with ID 2 placed?

      The customer id is ${customerID} and the question is: ${prompt}
      `,
      tools: [getCustomerDetailsTool],
      toolChoice: 'auto',
    });

    return text;
  },
);

Our input schema will accept a customer ID and a question from the customer. The customer ID would likely come from the user session, while the question would be what the prompt the user entered in the chat input or system-generated, doesn't matter that much for this article.

Next, we can use the developer UI to test the flow and see if we can get some user details from our database (I know it’s fake).

You may be wondering, how do we know it’s working? The developer UI provides a stack trace to show you what exactly when during the execution, as shown below:

As you can see, this can be very helpful when troubleshooting your Genkit application and trying to figure out where things are going wrong. It will show you all the calls it made to the tools, including the inputs and outputs of each step.

Finalising the Agent

As it currently stands, no customer will be asking about their names, but hopefully, you get the idea. The customer would likely want to know the status of their orders, among other things. We will add more tools for getting order information and product information, following the template we have seen earlier, as shown below:

const getCustomerOrdersTool = ai.defineTool(
  {
    name: 'GetCustomerOrders',
    description: 'Fetches orders for a specific customer, by customer ID',
    inputSchema: z.object({
      customerId: z.string().describe('The ID of the customer to fetch orders for'),
    }),
    outputSchema: z.array(orderSchema),
  },
  async ({ customerId }) => {
    return orders.filter((order) => order.customerId === customerId);
  },
);

const getProductDetailsTool = ai.defineTool(
  {
    name: 'GetProductDetails',
    description: 'Fetches product details by product ID',
    inputSchema: z.object({
      productId: z.string().describe('The ID of the product to fetch details for'),
    }),
    outputSchema: productSchema,
  },
  async ({ productId }) => {
    const product = products.find((product) => product.id === productId);
    if (!product) {
      throw new Error(`Product with ID ${productId} not found`);
    }
    return product;
  },
);

And then, we will add the above tools to the tools section, in the generate method, next to the one we already have, as shown below:

const assistant = ai.defineFlow(
  {
    // ... nothing changes here
  },
  async ({ customerID, prompt }) => {
    const { text } = await ai.generate({
      prompt: `...`,
      tools: [
        getCustomerDetailsTool, 
        // we add the tools here
        getCustomerOrdersTool, 
        getProductDetailsTool
      ],
    });

    return text;
  },
);

And finally, we can use the Genkit Developer UI to test whether our flow and tools work.

As you can see, the AI model — in our case, Gemini — figures out the status of the customers’ orders and associates them with products by utilising the different tools we provided. While the prompt can be improved to allow the customer not to be very specific, and still accomplish the same goals, hopefully, you get the idea of how we can give LLMs the ability to interact with our systems to accomplish different goals.

If you are interested, you can find the above source code here.

Conclussion

In this post, we discussed function calling that allows you to give AI models access to your applications and system, so that they can get things done. We also looked at the Genkit Developer UI, for the purpose of testing and debugging our flows, tools and applications we are building on top of AI models.

I hope this article gave you ideas on how you can use Genkit to build AI agents to help accomplish various tasks on behalf of customers, and if you have any questions, please feel free to put them in the comment section below.

Until next time, keep on learning.

Ready to Move From AI Hype to Real-World Results?

At Unstacked Labs, we specialise in building practical AI agents, like the one in this article, that automate complex workflows and solve real business problems.

Let's discuss your company needs

Level Up Your Testing Game with Jest Spies and Asymmetric Matchers

Maina Wycliffe — Mon, 05 May 2025 15:27:19 +0000

Over my long career as a software engineer, unit testing involving third-party APIS, such as database calls, etc., has always proven challenging. And let’s be honest, it’s pretty rare to write an application where all functions are pure, i.e., self-contained, and don’t interact with third-party APIS—a topic I would really like to explore at some point in the future. For more on this and other topics, stay subscribed.

Let’s take the following simple function that gets items from the database - Dynamodb. Using the AWS SDK (v3), this function would look something like this:

const client = new DynamoDBClient();
const docClient = DynamoDBDocumentClient.from(client);

export async function getToDo(id: string) {
  const res = await docClient.send(
    new GetCommand({
      TableName: 'Todos',
      Key: {
        id: id,
      },
    }),
  );
  // Avoid assertions, whenever possible
  return res.Item as ExchangeRateDBObject;
}

The above function will use the AWS SDK to call the Dynamodb API and retrieve a to-do item with a given ID from the database. As long as you don’t have permission issues, it works.

On the other hand, writing unit tests for it might be tricky, as the test would require access to an actual AWS Account or a local version of Dynamodb, each with its own set of challenges.

There are several ways to handle this, which I won’t go into in this article, but one of my favourites is mocking the Dynamodb SDK (Or any other SDK). The problem I generally find with mocks is that developers do not check whether the mocked function was called correctly.

Jest Spies

To give you an example, when we mock out our Document Client above, we not only need to respond with the correct return signature—for instance, in our case, we only care about the Item property—but we also need to ensure that we passed in the correct information to the client.

In our case, the table name and the key must be correct; otherwise, if incorrect, our function would not work in the real world.

This is where Jest Spies come in. The Jest spy method allows us to monitor the behaviour of other functions without changing the underlying code for the purpose of testing. With spies, we can observe a few things, such as the times it was called and the parameters or inputs it was called with.

So, for instance, to test the above function, we would need to spy on docClient send method, returning the necessary response for our function to use, as shown below:

it('Should pass the correct Key to the DB', async () => {
  const spyOnDB = jest.spyOn(docClient, 'send').mockReturnValue({
    Item: mockToDo,
  } as any);

  await getToDo('123');
});

Now, if we run the above test, it will succeed using the mock test, as shown below.

But if you recall correctly, we have mocked (using the jest.spyOn method) out our SDK call, but we aren’t doing anything to verify that we are calling our SDK correctly, which was one of my gripes with mocks in the first place.

We can now use a number of methods from the Jest matchers, such as toHaveBeenCalled and toHaveBeenCalledWith to ensure that our SDK/ function we are spying on was called a number of times, once in our case and was with the correct inputs/parameters.

expect(spyOnDB).toHaveBeenCalled();

The above matcher checks that our SDK was called; it doesn’t check whether it was called once or twice. If we wanted to be specific, Jest provides a different matcher that you can use to ensure the number of calls - toHaveBeenCalledTimes method.

expect(spyOnDB).toHaveBeenCalledTimes(1);

If our SDK is called more than once or not called at all, the test will fail. Neat, right?

Next, we can check whether the SDK passed the correct parameters. For that, we will use the toHaveBeenCalledWith method to check whether the correct inputs were passed to our AWS SDK.

expect(spyOnDB).toHaveBeenCalledWith({
    TableName: 'Todos',
    Key: {
      id: '123',
    },
});

Unfortunately, while we care about the above input, the GetCommand class transforms our input and appends some metadata, which we don’t care about for our test, but is still important. Due to that, the above test will fail.

As seen above, our SDK input contains much more information than what we are checking, with the information we need nested somewhere in there. This is where Jest comes to the rescue with another feature—asymmetric Matchers.

Asymmetric Matchers in Jest

Asymmetric Matchers are magical in Jest, as they allow us flexibility when matching and asserting results in Jest, such as partial matching, as we want.

For instance, let’s say we have a random ID generator that’s prefixed, e.g., user_UUID_STRING. We could mock out the ID generator function to return a predetermined string—deterministic behaviour is important for testing. Another option is to use asymmetric matchers to check whether the returned ID contains our prefix, as shown below:

expect(res).toEqual({
    ...USER_DETAILS,
    // Ensure the id is a string and starts with "user_"
    id: expect.stringContaining("user_"),
    // Or ensure the date is in the correct format
    updatedAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/),
});

As you can see, we are ensuring that the ID starts with the user_ prefix and the updatedAt date is of the correct matchers.

Circling back to our previous example, we now know that we need to ensure that the object passed to our SDK spy contains the following object, as we don’t care about the metadata and other details that the GetCommand appends.

{
    input: {
      TableName: 'Todos',
      Key: {
        id: '123',
      },
    },
}

Jest provides an asymmetric matcher for just this situation - expect.objectContaining. And this will check the results to see whether it contains the object we pass in, instead of strictly checking it, as shown below:

expect(spyOnDB).toHaveBeenCalledWith(
    expect.objectContaining({
      input: expect.objectContaining({
        TableName: 'Todos',
        Key: {
          id: '123',
        },
      }),
    }),
);

In layman’s terms, we are doing a partial check, and as long as the fields that we specify exist within the results, our test will parse, as shown below:

On top of that, Jest provides a good number of asymmetric matchers that you can use to make your life a little bit easier.

Just keep in mind that you need to ensure you are testing the most critical aspect of your code, and don’t use this as a shortcut by overusing matchers such as expect.anything or expect.any, which can literally match any string.

You can learn more about Asymmetric Matchers here.

Conclusion

In conclusion, unit testing when dealing with third-party APIS can be challenging, especially when it comes to ensuring that mocks accurately reflect the interactions with the real SDKS.

By leveraging both Jest Spies and Asymmetric Matchers, developers can create more robust, reliable and more effective tests that not only verify the functionality of their own functions but also confirm that the SDKS are being called correctly with the right parameters.

This enhances the reliability of your tests and helps maintain the integrity of your application's behaviour. Remember, while mocking provides a useful abstraction layer, focusing on meaningful assertions that capture the critical aspects of your application when using asymmetric matchers is essential, making sure that critical elements are what they should be while ignoring everything else.

By doing so, you'll be well-equipped to navigate the complexities of unit testing in a world full of dependencies. Happy testing!

Exploring Routes Rendering Modes in Angular

Maina Wycliffe — Mon, 10 Feb 2025 09:37:27 +0000

Over the last few years, Angular has grown through some significant and important changes. One of those changes was incorporating server-side rendering into Angular instead of a library like it used to be with Angular Universal, the predecessor of Angular SSR (@angular/ssr).

Now, every angular application, out of the box, by default, uses SSR, which is an opt-out feature. For most people, when building Angular apps, it either needs to be server-side rendered or not; for instance, a dashboard behind a login wall doesn’t need SSR, while an e-commerce site needs it.

However, there are applications where there are some pages that are behind a login wall, and some public routes. If we circle back to our e-commerce site example, checkout pages, order pages, etc., are such examples that are probably behind a login wall, while product pages are public.

If you enable SSR on such a route behind a login wall, and someone visits the page, Angular will render the login page (or wherever the Auth Guards redirect them). When the page is loaded, Angular will determine the user is logged in and redirect them back to the actual page, as shown below:

This means the user will see a flash on the login page before seeing the actual page. This happens because, in our case, the authentication context is only available on the browser, not the server, and hence, on the server, the user is not logged in, but on the browser, the user is.

If you encountered this, like I did, before Angular 19, you would have to disable SSR, as that’s not an optimal user experience. However, the Angular team introduced in Angular 19 the concept of render modes for individual routes, or what is called hybrid rendering.

Instead of all routes either being client-side rendered (CSRd) or server-side rendered (SSRd), you can now choose what to do for each route. On top of that, they also added the ability to perform static site generation (SSG) for individual routes.

Let’s see some code.

Setting Up Server Routes Manually

Please note that this feature is in developer preview, so use it cautiously. For more information on what this means, please check out the following link on Angular versioning here.

Before we can go any further, ensure you are on Angular 19. Angular has introduced a concept for Server Routes in which you can declare what to do for certain routes. To take the example above, we have two routes, as shown below:

export const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    canActivate: [redirectIfNotLoggedInGuard],
  },
  {
    path: 'login',
    component: LoginComponent,
    canActivate: [redirectIfLoggedInGuard],
  },
];

For the above route configuration, we can add server route configurations using the path and the render mode we need. I chose to store them next to each other, but it can also live in its server routes file - whatever floats your boat.

...
import { RenderMode, ServerRoute } from '@angular/ssr';

...

export const serverRoutes: ServerRoute[] = [
  {
    path: '',
    renderMode: RenderMode.Client,
  },
  {
    path: 'login',
    renderMode: RenderMode.Server,
  },
];

The render mode accepts one of three values, RenderMode.Client, RenderMode.Server, and RenderMode.Prerender. For our very simple example above, we are RenderMode.Client for the home page, so it will not be server-side rendered, and then RenderMode.Server for the login page, it will be server-side rendered.

Please note, for now, you have to add all routes to the Server Routes.

Once we set up our routes, we finally need to provide the server routes in our app config so that Angular can use them. We achieve this by using the provideServerRouting function and passing in the server routes we configured.

...
import { provideServerRendering } from '@angular/platform-server';
import { provideServerRouting } from '@angular/ssr';
...

export const appConfig: ApplicationConfig = {
  providers: [
    ...
    provideServerRouting(serverRoutes),
    provideRouter(routes),
    ...
  ],
};

And that’s it. If we circle back to our example, you can see that the login page flash is completely gone.

You can find the code for the above application here.

Setting Up For New Projects

Of course, this is Angular we are talking about. With the magic of schematics, you can automate the above process; you will only have to configure your routes.

If you are starting a new project, Angular provides a flag --server-routing that enables this for the new project when setting it up.

ng add @angular/ssr --server-routing

Conclusion

In this brief article, we looked at Rendering Modes in Angular and how we can use them to provide a better user experience for our users. Before this, your options were limited; you could either use SSR or not use SSR if it broke the UX of your users. But with render modes, you can enable SSR where it makes sense, Prerender pages that make sense and CSR pages that make sense, ensuring a much better user experience for our users.

That’s it from me, and until next time, happy coding.

Why do we have const enums in Typescript?

Maina Wycliffe — Mon, 17 Jun 2024 13:33:22 +0000

Typescript usually has two schools of thought—enums and unions—with strong supporters on both sides of the argument. In today's issue, I want to avoid that debate and focus solely on Enums, specifically a different, lesser-known version of enums: const enums.

Before we go any further, let’s briefly talk about what enums are: Enums allow developers to define a list of named constants representing distinct states within their application. For instance, if you wanted to have a switch button, the values can either be on or off, and an enum is perfect to represent this state, as shown below:

And you can use the above enum, just like any type in Typescript.

To understand the difference between enums and const enums, we first need to understand their behavior after compilation before the behavior is very similar.

If you want to learn Typescript with weekly lessons, please subscribe to my newsletter.

In the book Effective Typescript by Don Vanderkom (a strongly recommended read), the author says that typescript has no impact on Javascript runtime. This is because Types are removed during transpilation, leaving you with good old Javascript. You can learn more about this relationship in this issue, which we covered a few weeks ago.

Enums are one of the few features TypeScript has which is not a type-level extension of JavaScript—Official TS Docs.

Of course, this isn’t always the case, and Enums are one of those exceptions, with Enums getting converted into objects instead of being removed, as shown below:

So, when we pass an enum, the object that is produced during the transpilation process is referenced, as shown below.

Another thing to note about enums is that the values of each element in an Enum are numbers - incrementing from 0, from the top down, unless the first number is indicated - instead of the values we entered above, so in our case, ON would be 0 and Off would be 1. Below is a case where the initial number is indicated.

In this case, On is 100 and Off is 101

This isn’t always the desired behavior, but it can be fixed by explicitly adding the value of each element in the enum, such as having the value be a string.

String Enums

Or even an expression, as shown below:

Computed Enums

If you like my content and want to support my work, please consider supporting me (you can buy me a double latte, the juice that powers my creativity and determination ☕️) through Github Sponsors.

☕️ Consider buying me a cup of coffee

Const Enums

This isn’t always desired, and that's where const enums come in. They are just like regular enums, but they are prefixed by the const keyword before their declaration.

The other important difference is that const enum values get inlined instead of producing an object, taking us back to zero impact on the JS runtime, as const enums do not generate objects after transpilation.

Generally speaking, regular enums are valid solutions, but in those cases where you don’t want to pay the penalty of extra code generated by using regular enums, const enums are a very good solution, as they don’t generate any code for their support.

As you can see, no more Switch object is being created. Of course, just like with regular enums, we still have the same issue of enum element values being incremental numbers unless otherwise specified.

Conclusion

In this issue, we examined the difference between enums and const enums. Unlike regular enums, const enums don’t generate the javascript object; the code is inlined. This means that you are not paying the penalty for extra code generation that you get when using regular enums.

While this is normally not a concern for most projects, in some cases, it can have a negative impact, leading to large JS code being produced and longer build / transpilation times. This can easily be solved by using const enums, which would be easier to refactor compared to alternative solutions such as unions.

Making Generics Types Optional - Generics Fundamentals in Typescript

Maina Wycliffe — Tue, 30 Apr 2024 16:20:31 +0000

In the last two issues, we started exploring generics, where we looked at the fundamentals of generics and how to create generics constraints. I believe this has given you a good foundation for working with generics in Typescript.

In this issue, I wanted to explore how we can make a generic Type optional by providing a default for the Type variable, that can be used when no Type is passed in and Typescript cannot infer the Type. Before we can look at generics, let’s draw some parallels with functions and how defaults work values for functional arguments.

Let’s take the following simple example.

function doSomething(input: string) {
    // do something
}

In the above example, the function input parameter is required. In some cases, we want to provide a fallback value, that will be used if the function is called without a value.

For functions, the syntax to achieve this is the one shown below:

In the above example, we are simply telling Javascript that if the input parameter isn’t provided or undefined, use default-value as the value for the variable. This makes the input string optional, and not required.

While Typescript will type-check the function’s input parameter if provided an incorrect Type or if we simply don’t provide it, it also means that we need to provide the input every time we call the function.

By providing a default value, we made the parameter optional, but this also means we have also expanded the types from being just string to string and undefined and to consume it, we might need to narrow the type. You can learn more about type narrowing here.

However, by providing a default value, it means we don’t need to provide it, so we don’t have to do the extra step of checking if the input is string or undefined, avoiding the extra step for narrowing types, as we already have a fallback value, when undefined.

☕️ Consider buying me a cup of coffee

What does this have to do with generics?

Default Types for generics types work similarly. We can achieve the same thing we did with function parameters with Generics, where we can provide a fallback type for the type variable if not provided and cannot be inferred.

A type variable is a special kind of variable that works on types rather than values.

Let’s look at an example. Let’s create a simple utility type. Utility types utilize generics to help you do type transformation. Typescript has some in-built utility types that you can learn more about here.

Our utility type will take two types (that are key-value objects) and merge their properties into a single Type, with the properties from both Types.

Here is an example of what our implementation looks like:

We will go into the details of the above example, in a future issue (hopefully next week), as we explore Mapped Types and other Types in Typescript.

To use our utility type, we just need to provide two object types and we get a single object with properties from both types that were passed in, as shown below:

You can find the above code here.

Our example above doesn’t do much, but let’s say that in the future the requirements of our project change and we want to expand it so that we can merge two or three types.

The problem is that this would work with merging 3 Types, but to work with merging two Types, we would need to provide an empty object Type, as shown below:

Wouldn’t be nice if we could skip that part, and just provide our two types? And this is where Generic type variable defaults come to the rescue.

Just like function parameters, we can provide a default Type for our Type variable and essence making them optional, as shown below:

And now, our MergeObjectTypes utility type can accept either two or three Types and merge their properties into a single Type.

And we can go crazy now and add more type variables to merge 4, 5, or 10 even object properties while ensuring our utility types work with 2 to 10 types, and anywhere in between.

If you are interested, see if you can modify the above example to work with 5 types.

Rules for Default Types

Just like function parameters, there are a few rules to keep in mind for generic default Types.

The first and most obvious one is that when you provide a default value, a Type variable is deemed as optional.
- You are required to provide the required type variables.
- Remember, Type inference in most cases can help you, so you don’t provide the required Type variables.
- If you don’t provide an optional Type variable, then the default type is used, unless Typescript can infer a different type based on usage.
And just for functions, required type variables come first, followed by optional type variables.
If you are using a generics constraint, the default type must satisfy that constraint.
For classes and interfaces, when extending either a class or an interface, you can introduce a default for an existing Type parameter and you may also introduce a new Typer variable, as long as it’s optional (has a type variable).

Conclusion

In this issue, we looked at making generics Type variables optional by providing a default or fallback type. We drew parallels between Generics default types with functions parameters default values and how they behave almost the same, but with the key difference being one applies to variables while the other one applies to types.

To demonstrate how useful default generics types can be, we took a look at an example where we can create a custom utility type that we can use to merge properties for an object type, for either two or three types, and how we can utilize defaults to make this work seamless for either of the cases.

Generic Constraints - A Gentle Introduction to Generics in Typescript

Maina Wycliffe — Tue, 09 Apr 2024 07:43:40 +0000

In a previous issue, we learned about the fundamentals of Generics in Typescript and how we can use generics to make our lives easier as developers. You can find the last issue here.

But to quickly recap the last issue, Generics allows us to write our code in a way the data types we are dealing with will be specified later on. In Typescript, we do this using the type variable specified inside Angle <> brackets, which we can then use within our application.

A type variable is a special kind of variable that works on types rather than values.

Here is an example of a sortArray function, that can sort any array, accepting a SortType type variable, for the function input and output.

In the above functions sort generic functions, we need to specify the type of array we are sorting by providing the SortType type variable, just before we provide the arguments for functions, as shown below.

And this can be done for classes and when defining other types using either interface or type, to learn more, check out the previous issue here.

What are generic constraints?

Before we can try and define generic constraining, let’s define the word constraint, on its own. Stay with me here, I know this is a Typescript newsletter, not an English newsletter and I am probably the worst person to teach English, considering it’s probably my third language. I digress anyway.

According to the Cambridge Dictionary one of many definitions (I cherry-picked 🤷🏾), a constraint is something that controls what you do by keeping you within particular limits. The key part I want you to remember for this issue is keeping you within particular limits.

Back to Typescript and Generics, if we looked at the previous example we had, our sortArray function is meant to sort arrays, not other data types, which would probably require a different algorithm for arrays.

However, our function will accept array types as well as non-array types, and this is not the desired behavior. This isn’t type-safe, as the function will probably throw a runtime error if we attempt to sort a string data type when we wrote it to sort arrays.

Typescript was meant to eliminate these kinds of errors, but we just made it even simpler to make them, and no way to know ahead of time.

And this is where generics constraints come in. They enable us to limit (restrict or constrain) the types that can be provided for our type variables. This way, our function will accept arrays, but it will not accept non-array types. We do this by using the extends keyword and providing the types we want to contain our type variable to.

For instance, in our sortArray function, we can restrict our type variable to be only an array of string, number, or boolean, as shown below.

And now, when we try to pass in a string, as we previously did, Typescript catches the type error for us, as shown below:

Typescript now catches and warns us that we can not pass a string type as the Type variable as it doesn’t satisfy the type constraint we provided. This works with Type inference too, as discussed in the previous issue.

As you can see generic constraints allow us to achieve type safety by restricting the Types for our application. By using Typescript generics constraints, we can now write our generics code knowing that we are dealing with a known pool of types rather than all types available. In our case, we are only dealing with arrays and not non-array types.

In the previous example. we looked at constraining it to be an array, but we can constrain it to any type, as shown below:

In the first case, we are constraining to only accept strings (and their subtypes), and in the second case, we want it to be a key-value object and in the last case, we are providing our type, to just demo the different ways you can constraint a Generic.

Type variable constrained by another Type Variable

So far, we have dealt with simple but useful cases. I don’t want to go into some of the most advanced use cases of generics yet, because this is still a gentle introduction to generics but let’s look at another common scenario.

For instance, let’s say we want to create a function that returns a property from a key-value object, given its key, as shown below:

As you can see, we are using a Generic constraint to ensure that the first argument is always a key-value object, but we have a slight problem. We would like the second function argument - key - to be only a key that exists inside the object we pass in. At the moment, we can pass anything and this could lead to undesired characteristics from our application.

We can fix this issue by adding a second type variable that we can call Key and whose type will be constrained to the keys of the object, for this we can use the keyof operator to get the keys of the first type variable, as shown below.

And now, if you try to provide keys that aren’t present in the object in the first argument, Typescript will warn you.

As you can see, we get a warning when we provide a key that doesn’t exist and Typescript provides suggestions for keys you can use.

Bonus

There is one final thing we can do to make the function more complete and type-safe. As you can see, our function return type is unknown, which doesn’t tell us much and we would need to narrow it before using it. But we can use our type variables - the object and the key passed in, to look up the type of that property in the object.

So, we are combining the type variables provided for the getProperty function, where we are annotating the return type of the function to be the type of the property for the key provided.

In Typescript, this is known as indexed access types. Indexed access types allow us to look up specific properties of other types. You can learn more about this in a previous issue here.

Conclusion

In today’s issue, we discussed generic constraints and why they are important in Typescript for increased type safety and improved developer experience. Generic constraints enable us to provide guard rails to the generics types so that we can be certain that the type of data that can be passed in is what is expected leading to enhanced type safety.

This hasn’t been an easy issue to write, breaking down the concepts into something easy to understand and I hope you found it very illuminating.

Bun - The One Tool for All Your JavaScript/Typescript Project's Needs?

Maina Wycliffe — Tue, 02 Apr 2024 17:27:06 +0000

In most issues for this newsletter, I have focussed on Typescript and its type system, which I will continue doing. This has been great for my readers (from the feedback I have received) but I have wanted to cover broader Typescript-related topics, such as today’s topic, after all this is All Things Typescript. I hope you will enjoy this topic and let me know if you want more like this.

What is Bun?

NodeJS is the dominant Javascript server runtime environment for Javascript and Typescript (sort of) projects. But over the years, we have seen several attempts to build alternative runtime environments such as Deno and Bun, today’s subject, among others.

These newer alternatives focus on providing much better runtime performance, much better support for Web APIs on the server, and generally better security among other features, we will look at in later sections. The NodeJS team also continues to make improvements to NodeJS and we have seen tremendous improvements in here as well.

“Develop, test, run, and bundle JavaScript & TypeScript projects—all with Bun. Bun is an all-in-one JavaScript runtime & toolkit designed for speed, complete with a bundler, test runner, and Node.js-compatible package manager.”

Compared to Deno, what I think makes Bun special, is that it’s a drop-in replacement for node (you don’t have to change much if anything at all). Unlike Deno which required you to make significant changes to your application at launch to adopt it, Bun doesn’t require you to make any changes to your codebase.

With Bun, you can go into any node-js-based project, like let’s a Next JS or React Application, and just run bun install (y_es, but install you read that correctly not npm install_) and then run the bun run dev (or whatever npm script you use to launch your project) and it should run your application, just like Node JS.

From my experience, this ran flawlessly all the time I tried it.

So, why use Bun?

So, now that I have briefly introduced you to Bun and why it’s a very interesting project, let's see some of the advantages of using Bun, over Node (where most of us are probably coming from), and the others.

Speed, it’s Fast, Really Fast

NodeJS is by no means a slow runtime, it wouldn’t be so popular if it was. But compared to Bun, it’s slow. Bun was built from the ground up with speed in mind, using both JavascriptCore and Zig. The Bun team spent an enormous amount of time and energy trying to make Bun fast, including lots of profiling, benchmarking, and optimizations.

Even the choice of the programming language to use Zig was done with performance in mind. The team chose Zig programming language as it allows them to have low-level control of memory management and lacks hidden control flow, making it easy to write fast software.

The same can be said about the team’s decision to go with JavascriptCore. Both NodeJS and Deno are based on Chrome V8 Engine, while Bun is based on Apple's JavaScriptCore. While not mind-blowingly faster than the V8 Engine, it’s a little bit faster. And these optimizations have paid off for Bun, as it’s faster than both Deno and NodeJS.

To demonstrate this I put my novice benchmarking skills to the test. To run the benchmarks, I used the latest versions of NodeJS, Deno, and Bun, as of the time of writing this issue.

For benchmarking, I used the following simple JS code:

for (let i = 0; i < 10000; i++) {
  console.log(`Count: ${i + 1}`);
}

And then I used hyperfine to run the benchmarks on my MacBook Pro 14 M2 Max, and here are the results:

As you can see, Bun is 2.20 faster than Deno and 2.88 faster than NodeJS. I also ran the same benchmarks on Windows 11 using WSL and Bun managed an even more impressive feat, being 3.06 times faster than node and 3.26 times faster than Deno, as shown below:

This benchmark was run on an Intel Core i9 11900H process and 40 GB of RAM

🤔 Interestingly, the Gap between NodeJS and Deno seems to be closing, let me know in the comment section below if you want me to do a deep in dive comparing the three on different workloads and different OSs.

If you want to dig into the performance comparison and a very good explanation of the internal workings (in relationship to Javascript Engines) of NodeJS, check out this amazing video by Chris Hay.

Compatibility with NodeJS and NPM

I touched on this earlier, if you are already using NodeJS and would love to switch to Bun, you can do so with minimal effort. You can visit any NodeJS-based project, run bun install and then run the server using Bun instead of NodeJS, no code changes are needed right out of the box.

“Bun is designed as a drop-in replacement for Node.js. It natively implements hundreds of Node.js and Web APIs, including fs, path, Buffer and more.”

For more information on NodeJS APIs implemented by Bun here.

And if all you just need is a much faster package manager, you can use Bun to replace NPM and use NodeJS for your server, no fuzz.

Built-in Tooling

One of the most frustrating or overwhelming things especially for novices about modern web development is the amount of tools that you need to learn. For starters, you will need node/deno/bun and npm, and if you decide to use Typescript, you will need a transpiler and maybe (by maybe I mean, most certainly) a bundler and the story goes on.

We, as web development veterans, sometimes forget how intimidating this can be for beginners, I guess you can call this Stockholm syndrome.

With Bun, you only need Bun. It’s a drop-in replacement for all of the above tools above. Want to install packages, bun has got you, with Bun package manager, it’s a runtime and bundler and will transpile and run typescript code, without you having to install a host of tools to achieve the same.

What about testing? Yeah, Bun still got you with an inbuilt test-runner, goodbye Jest?🤷🏾. Bun is fully compatible with jest syntax and you can use it as a drop-in replacement for jest, and you get all the benefits of Bun discussed in this article.

You can learn more about Bun testing here.

Web Standard API

One thing that serves as a divide depending on the runtime you are targeting is how some APIs are available on the browser, yet are missing on the server (NodeJS). This means that even for tasks you can perform in both the server and the browser, it’s possible to have two different APIs for achieving the same on both, despite the fact you using the same programming language.

A good example of this, until recently, was fetch, a common task like fetching data over HTTP, which you can perform on both the browser and the server. It was natively supported in the browser environment but not supported natively by NodeJS. This can be frustrating because despite the fact you are writing Javascript, the tooling changes based on your target environment.

Bun aims to address this by providing and implementing a list of standard web APIs that are similar to the ones available in the browser environment. Of course not all APIs available in the browser are required in the server environment, think of the DOM and History APIs as good examples of this.

But common tasks in both environments such as making HTTP calls don’t need to have unique Web APIs for each environment. Bun implements the Web Standard APIs for some of this, instead of re-inventing the wheel, which makes our Job (especially full-stack developers) a tad bit easier.

You can find a comprehensive list of Web Standard APIs implemented by Bun here.

Supports Typescript and JSX/TSX out of the Box

With Bun, you don’t need to transpile your Typescript code to Javascript to execute it (or result in using something ts-node). You can execute your Typescript directly using Bun, and it’s going to do all the heavy lifting for you - the process of transpilation, and executing the resulting JS code, without you having to think about it.

One very important caveat, that I missed before and I was corrected in the comment section below, is that Bun doesn’t perform type-checking, unlike other build tools, just does transpilation. You will still need the Typescript compiler to Typecheck your code.

Bun treats TypeScript as a first-class citizen.

On top of that, it does support JSX (TSX by extension) out of the box, compiling it internally to JS code ready for execution. In both cases, Bun will respect your configurations (tsconfigs/jsconfig) during the transpilation/conversion process.

You can learn more about Typescript support here and JSX here.

Single File Executables

Ever wanted to run compile your javascript into binary executables that you can run directly? Bun got your back here as well, you can compile Typescript and Javascript projects, including all dependencies into a single executable binary that you can distribute and run, without needing to install dependencies or even Bun itself.

On top of that, you can embed files and even databases such as SQS Lite, if you want to. Please note, that if you embed SQL Lite, it runs in memory and the changes will be lost when the binary exists. This does give you several choices when it comes to distributing your projects, which doesn’t require the OS to have all the dependencies installed to run.

Bun Resources

Let’s say you are interested in learning more about Bun and probably give it a try. Bun has a website, where you can learn more about Bun and its features (including all the benchmark data captured in this issue), and here is the link.

Conclusion

In this issue, I have done something different from my usual content. We have gone over Bun, a Javascript server runtime environment which is a drop-in replacement for NodeJS. We took a look at some of the features that set Bun apart from NodeJS and which might tempt you to switch to Bun.

That’s it from me and until next time, keep on learning.

A Gentle Introduction to Generics in Typescript

Maina Wycliffe — Tue, 26 Mar 2024 07:21:09 +0000

One of the more advanced topics in Typescript is Generics and understanding and adding them to your Typescript coding toolbox can be very powerful. As we continue with our journey of learning Typescript and building amazing projects, we want to have more and more tools that we can use to make our job easier, without making compromises when possible.

What are generics?

Let’s see a useful case on why generics can be very important and even crucial. Let’s say we want to build a function to sort strings. It would look something like this.

function sortString(str: string[]): string[] {
    // sort algorithm
}

But after a while, the requirements of our project change, and we need to be able to sort numbers as well. The algorithm to sort the strings and numbers is the same but to have it strongly typed we would need to create a second function for that as well.

function sortNumber(num: number[]): number[] {
    // sort algorithm
}

In the future, the requirements of our project could change and we could end up sorting different types of variables. As you can see, we could end up duplicating the original function, more and more, as we need to be able to sort different types of arrays.

Can we use the `any` Type to solve this problem

Yes, we could. But this comes with one huge disadvantage, compared to having multiple functions, we lose type-safety and type precision, and we certainly don’t want this.

You can learn more about why you should avoid using the any type in one of my previous issues here.

function sort(num: any[]): any[] {
//                  ^ DON'T DO THIS
    // sort algorithm
}

Is there a better solution?

Before I can answer that, let’s recap. So, we want a solution that allows us to write a single sort function, without compromising type-safety and losing type precision. Back to the question, yes, there is a better solution.

What if, instead of writing a sort function with static types for arguments and return values as we did previously, we could write a function whose types can be specified when the function is being called?

So, in our case, we would allow the caller of our sort function to specify the type of function argument (the array to be sorted) and output (sorted array).

This is exactly what generics allow us to achieve in programming, and Wikipedia has a very good definition of it.

Generic programming is a style of computer programming in which algorithms are written in terms of data types to-be-specified-later that are then instantiated when needed for specific types provided as parameters.

To break the above down in relationship to our sort function requirement, we want to write our sort function algorithm, without tying that algorithm to a specific type - string, number, boolean, etc. but also allow the caller to let us know the type that we can use for type-checking.

So, how do they work?

In Typescript, we use generics by providing the type variable inside angle brackets (<Type>). A type variable is a special kind of variable that works on types rather than values. You have free reign in naming the type variables, just like the naming of other variables.

For instance, in functions, we provide the type variable, in angle brackets (<Type>), in between the function name and brackets used to specify the arguments. We will see about generic classes, types, and interfaces later on. The type specified here can then be used within the function, or for arguments and return types, as shown below.

function sort<SortType>(genericInput: SortType[]): SortType[] {
~~~~~~~~~~~~~~   ^ Type Variable
    return genericInput.sort();
}

In the above function, we are specifying the type variable, which is the SortType type, and then for the function argument, we use SortType as the type of the first function argument and output. And this is how we use the above function:

const x = sort<string>(["1", "2", "3"]);

We are providing the string type, as the type variable and now Typescript can use the information to type-check the function arguments and outputs.

This works for a variety of types:

const nums = sort<number>([1, 2, 4, 5])
//            ^? function sort(input: number[]): number[]

const str = sort<string>(["str", "str2"])
//            ^? function sort(input: string[]): string

// we can even mix up things now
const both = sort<string | number>([1, 2, "str"])
//            ^? function sort(input: (string | number)[]): (string | number)[]

If we try a different type other than the one provided in our generic type variable, Typescript is going to throw an error, as shown below:

Typescript will type-check the function arguments against the Type variable we provided.

And just like functions arguments, you can have multiple type variables:

function manyGenerics<A, B, C, D>(a: A, b: B, c: C, d: D): [A, B, C, D] {
    return [a,b,c,d]
}

Do I have to provide the type variable every time?

The answer is no, and this is because Typescript can use Type inference so you don’t have to provide the functions generic type with every call.

Typescript will use the type inferred for our generic input, as the type for our variable type, which can save you from having to always specify the type variable.

This is so good that many developers use generics daily without realizing it. For instance, the Array.sort() functions and other Array methods are generic functions.

For instance, the following Array.map method:

[1, 5, 3, 11, 6 ].map(x => x.toString());

It can also be written like this, with the type variable provided.

[1, 5, 3, 11, 6].map<string>(x => x.toString());

Where else can we use generics?

So far, we have seen generics in function space. But we can use generic in a variety of places, not just functions. Let’s see some of this:

Classes and Methods

Just like functions, when defining a class, we can request a type variable(s) for the class, which we can then use within the class.

class SomeClass<Type>{
// ~~~~~~~~~~~~~ ^ Type Variable

    property: Type;
    //         ^ We can use the Generic type for types of properties

    doSomething(input: Type): Type {
    //                  ^ and for methods input
    }
}

And on top of that, we can provide type variables for the methods themselves, if need be:

class SomeClass{
    doSomething<Type>(input: Type): Type {
        //       ^? Type Variable
    }
}

Types and Interfaces Definition for Key-Value Objects

When defining types for key-value objects using either interface or type, you can use generics to provide types for some of the properties.

type Person<Type> = {
//            ^ Type Variable
    name: string;
    id: string;
    properties: Type;
}

We can do the same with interfaces:

interface Person<Type> {
//                ^ Type Variable
    name: string;
    id: string;
    properties: Type;
}

What’s next?

So far, we have had a very brief introduction to Typescript generics, where we looked at creating Generics in Typescript and how we can use them. Generics are powerful and are very useful and in our latest issue, we looked at constraining our generic types, here is the issue.

See you next week and subscribe to not miss the next issue.

☕️ Consider buying me a cup of coffee

Conclusion

In this issue, we looked at Typescript generics. We looked at a simple example of a sorting function, that enabled us to see in which situations generics can be very useful and how generics can help us write less code without compromising type safety.

In the next issue, we will continue looking at generics and some advanced techniques that we can do with generics to even lead to more Type safety.

So, until next, keep on learning.

A Deep Dive into the satisfies operator in Typescript

Maina Wycliffe — Tue, 12 Mar 2024 19:36:44 +0000

In Typescript version 4.9, Typescript introduced the satisfies operator. Over the last few months, I have seen examples of it being used out in the world more often, and even I have found myself getting comfortable using it. In this issue, I want to do a deep dive and try and answer the following questions:

Why it exists
Why not annotations
Why not assertions
When to use it

What is the `satisfies` Typescript operator

According to the Typescript docs, the new satisfies operator lets us validate that the type of an expression matches some type, without changing the resulting type of that expression.

So, what does this mean? When we add type annotations to a variable, Typescript doesn’t usually infer the Type to its narrowest possible value. So, if we say a variable’s type is a string, Typescript takes our word for it and checks the value we assign to it against the type annotation we provided, as shown below:

const str: string = "hello"

In the case above, despite us using const, and having all the information at hand to narrow the above type to the hello literal type, Typescript doesn’t do that and instead takes our annotation as the type of the variable.

This is in contrast to when we allow type inference to work for us, instead of explicitly providing Type annotations, as shown below:

As you can see from the above example, when we use explicit type annotations, we lose the narrower type that we would have gotten if we had let Typescript infer the type for us.

Why is this important, you may ask? To answer this, let me show you an example, take the following two functions:

function a(input: string) {
  // do something
}

function b(input: "hello") {
  // do something 
}

The first function accepts a string and the second accepts a literal type - hello. With the first variable, we annotated the type explicitly, this can be passed to the first function without any issues.

But in the second function, despite the first variable value being hello, Typescript will make you jump through to accept the variable, simply because it expects a narrower type than the type of string we provided.

In the second function, you would need to narrow the variable for it to work, as shown below:

if(str === "hello")  b(str);

In our case above, we are using control flow to narrow the type of str variable to hello, from a broader type of string. You can learn more about type narrowing in this previous issue.

How does the `satisfies` operator help?

If you are wondering what this has to do with the satisfies operator, I am getting to the point in a moment.

What if you wanted to ensure that str is a string, without losing the narrowness of the inferred type? If you remember at the beginning, we said that the satisfies operator allows you to validate (think type-check) a variable type without changing the resulting type of that expression. The resulting type being the Type inferred by Typescript in the absence of explicit type annotation.

So, if we went back to our example, instead of using type annotation for our variable, and instead we used the satisfies operator, as shown below:

const str = "hello" satisfies string;

Our variable wouldn’t carry the type of string as it did previously when we used type annotations, but the resulting inferred type is retained.

And this means, we can now pass the variable to the second function without needing to narrow the type.

const str = "hello" satisfies string;
//    ^? type = "hello"

// this works now
b(str);

“Real-world” Example

Okay, I know what you are thinking, this isn’t a practical example. And that’s true, but I needed a straightforward example, that hopefully was easy to follow and understand, which I hope worked, and if it didn’t let me know in the comment section below.

Let’s see a more realistic example. Let’s say we want an object, with property names being string and values being either string, number, or boolean, as shown below:

const user = {
    firstName: "John",
    lastName: "Doe",
    age: 5,
    isMember: true
};

With the above object, we might want to have Typescript type-check the content of the object. In such a situation we have two options:

providing explicit type annotations
or the satisfies operator.

If we use type annotations and try accessing one of the properties, Typescript doesn’t know the properties that are inside the object or their types, this is despite us explicitly adding them and adding them upfront.

const user: Record<string, string | number | boolean> = {
    firstName: "John",
    lastName: "Doe",
    age: 5,
    isMember: true
};

In this case, Typescript goes with the type from our Type annotation for the property values.

This isn’t great, for one, we can include properties that don’t exist inside our user object or typos and which may introduce bugs within our codebase. However, if we went with the satisfies operator, then things work out quite differently and for the better.

const user = {
    firstName: "John",
    lastName: "Doe",
    age: 5,
} satisfies Record<string, string | number | boolean>

If we try and access the property firstName, we get both auto-completion 👌🏾 and it has the correct type, as shown below:

We also can’t access properties we didn’t explicitly add to the user object.

And we also get the excess property checking we got when we provided explicit type annotations.

This has a few benefits:

Improved type safety as demonstrated in the last example. This is twofold:
- validating the object properties and values are of certain types, and
- avoiding changing the objects’ inferred type, which means the property value types are narrow instead of wide.
Reduced the amount of code we write - we don’t need to engage in type narrowing to use our properties above, they already have a narrow type.

Use Cases

Now that we have seen how we can some of the use cases of the satisfies operator.

Constraining the type of variable

We can use the satisfies operator to constrain or limit the types that can be used for a variable, without interfering with the type inference. A good example of this is our example above, where we limited our variable str to string, but let it be inferred as a narrower type by typescript, using the available information.

const str = "hello" satisfies string;

Constraining the Property Names of an Object and Catching Excess Properties

We can use the satisfies operator to make sure our object only has the keys and nothing extra.

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

const circle = {
  shape: "circle",
  radius: 4,
  anotherKey: 4
  // this will throw an error as shown bolow
} satisfies Circle;

Constraining the values of Properties, the opposite of the above

The following will throw an error because the shape property is missing.

const circle = {
  radius: 4,
} satisfies Record<any, number>;

Ensuring an Interface is Implemented

interface Person {
  delete: () => void;
  get: () => Record<string, unknown>
}

const thisPersion = {
  delete:  () => {};
  get: () => ({})
} satisfies Person;

For more about the satisfies operator, check out the following issue, where the discussion for adding the satisfies operator to Typescript happened.

Conclusion

In this issue, we took a look at the satisfies Typescript operator, and how it can be used to validate a type, without changing the inferred type of the expression. This is different from how both type assertions and annotations work because Typescript takes that as the type of the object, which is sometimes not desired.

When using the satisfies operator, Typescript only type-checks our variable against the provided type while inferring the type using the information available (Learn more about Type Widening here).

The inferred type is usually narrower, meaning it can be used without the need for narrowing, which may not be the case for using assertions and annotations, while also type-checking it against a specific type, which ensures type safety isn’t compromised.

If you loved today’s content and would be interested in supporting my work, please consider supporting me (you can buy me a double latte, the juice that powers my creativity ☕️) through Github Sponsors.

Boost your productivity by mastering Oh My ZSH git aliases

Maina Wycliffe — Wed, 06 Mar 2024 07:03:05 +0000

Since I discovered Oh My Zsh a few years ago, it has been a god-sent gift to me. I believe it has impacted my productivity in a very positive way, for instance, with the history autocomplete plugin, I no longer have to keep hitting the up arrow until I get to the command I wanted, I can just start typing and Oh My Zsh will give me suggestion s based on my history. It’s just genius.

PS: If you are looking to get started with Oh My Zsh, you can find the installation instructions here.

I guess this is the one plugin I can probably not survive with, my flailing memory would suffer greatly to have to remember all my previous commands, even the ones I worked out myself. A close second plugin for my workflow and I believe vital for most developers is the git plugin. It’s just genius.

Subscribed

Of course, with Oh My Zsh, you have an arsenal of plugins that you can call upon to do your bidding, such as the docker, node, and npm, to mention a few. You can learn more about Oh My Zsh plugins (installation and list of plugins) in the official wiki here.

For a long time, I and the git plugin, have become very close buddies. Want to rebase, push (force push), pull, etc, the plugin will autocomplete everything for you including the git branches, I never get the spelling right on the first try, heck I am even known for copy-pasting them.

I even adapted my naming of git branches, starting with the issue number, followed by the title slug so that I can get even faster autocomplete. Don’t even ask what I was naming them before.

I digress

Oh My Zsh Git Aliases

A few months ago, I came across Oh My Zsh git aliases, and well this has transformed my workflow. I can type into my terminal a combination of letters (3 to 5 characters, sometimes 6) and accomplish the same thing I did with a whole sentence.

I know, we as developers have been accused of being overpaid 🤷🏾 and lazy and I am playing up to my character incredibly well here. I will take any shortcut I can to do more, by doing less. On the other hand, I am a huge fan of a good developer experience and I will put anything in my toolbox that improves it, including Github Copilot - I guess I owe another article here as well.

Examples

To show you what I mean, I will demonstrate why I am a huge fan of Git Aliases and why you should start using them. First, with the command that I have always had many struggles with, not because I can’t memorize it, but because I have to remember the branch name - git push -f branch-name.

If you work with Git issues, you probably create branch names for your issues, which could be anything. So, after a rebase against your main branch, you need to push the changes remotely to the PR (for those of us using Github, but there are equivalents for other remove hosting services such as Gitlab), so you need to type the above command:

git push -f whatever-the-****-your-branch-name-is

If you have Oh My Zsh and the Git Plugin, you will probably use it to autocomplete the branch name you want to force push, which is quite helpful. But you can make your life even more easier by using the following git alias:

ggf

Yeah, it’s that simple and will force-push your current branch without you having to worry whether you got the correct branch name or not (god forbid you are not force-pushing on the main branch 🙈). Magic. Now imagine this, you have a few branches that are behind that you want to rebase and force push remotely. This does make your life a little bit easier, doesn’t it?

And did I mention, that it even makes rebasing way easier? So, let’s say, you notice that your branch is behind the origin main branch, instead of checking out the main branch and pulling the changes, you can simply fetch the remote main and merge your branch against it, as shown below:

git fetch origin
git rebase origin/main

If you think typing the above is a lot of work, like me, you can simplify that by using the following Git Aliasis.

gfo && grbom

The above two aliases will fetch the origin branches and rebase the current branch against the origin main branch. And now you can simply run ggf to force push remotely.

Impressed?

Yes, there is a learning curve, of course, you have to memorize the above Aliases, nothing good comes for free. But I believe it’s worth it and they will come naturally to you with time.

Another thing I want to emphasize is that as you go on your way to memorizing and becoming a 10x lazier developer, learn the underlying Git commands, and understand what each Alias you use maps to and what the command does, this way, you will know when not to use an Alias and when to find a different one.

So, if you hear me and want to start using Git Aliases with Oh My Zsh, where do I start? Here are some of the most useful links to installing Oh My Zsh and a cheat sheet for the Aliases to help you memorize them.

Conclusion

In this post, we took a look at how can use Oh My ZSH git aliases to boost our productivity and improve our developer experience, With git aliases we can accomplish more while writing less, this is especially useful when performing rebates and pushing changes across multiple branches where the actions are compressed into just a few characters.

I hope this post convinced you to add Git Aliases to your developer toolbox.

Thank you for reading and until next time, keep on learning.

A deep dive into new control flow syntax for Angular (17)

Maina Wycliffe — Mon, 20 Nov 2023 15:18:19 +0000

With the release of Angular 17, I wanted to explore the control flow syntax in Angular and demonstrate its benefits. The new syntax, which was part of the release for v17 of Angular, alongside a torn of other features we are going to look at in the future, is a big deal and a huge departure from how we accomplished control flow in Angular.

Control flow is the order in which statements are executed by the computer in a script. We can use conditions (if…else, switch statements) to determine which statements to execute and which to skip when certain conditions are met. We can even repeatedly execute statements using loops.

Subscribed

Angular is getting a new syntax for control flow, a major departure from what things were (I will refer to it as the old syntax), and still are, as the new control flow syntax is still in the developer preview.

First, let’s compare the new syntax with the old syntax.

If Conditions

Let’s say we want to show a section of our template if the conditions are true. With the old syntax, we would do it like this:

Old if….else conditional syntax in Angular

But now, with the all-new syntax, this would look like this:

New Angular if…else conditional syntax

Or can be further simplified to:

For Loop

What about for loops:

Old

For Loop before V17

New

New Angular For Loop Syntax

As you can see, we are also passing a tracking expression that yields a unique key that we can use to associate the array items and their place in the DOM for performance reasons. This is required in the new control flow syntax, while before with the old syntax, it was optional.

NgSwitch

Here is an example of the old syntax

And here is what that looks like now, with the new syntax

Notice something? The new syntax is more readable (I know, it’s subjective, but I think we can both subjectively agree) and familiar, it looks like the very familiar syntax you would come across while writing Typescript or Javascript (or most languages for that matter). If you are new to Angular, good luck understanding the old syntax without a few head scratches and squinting your eyes.

And then there is another huge benefit, syntax highlighting and formatting. In the old syntax, we didn’t have much in the syntax highlighting corner, as the structural directive we part of the HTML attribute. Since now the control flow isn’t part of the HTML tags, syntax highlighting is already available. On top of that, the prettier npm package (update to the latest version) now supports formatting of the new Angular syntax and it’s just glorious.

Combine these two, and you can now easily tell where one block ends and the other one starts and any nested blocks within the template are easy to identify. This should aid in code readability and improve it exponentially.

And did I mention there is no more unnecessary ng-container and ng-template for conditional HTML blocks? This leads to much cleaner code with less boilerplate.

I wish things were that simple

So far we have seen if and for syntaxes, what about the switch, here is an example.

Improvements over the Old Syntax

→ for loop: required track expression

With the new syntax, providing a track expression that yields a key to keep track of each item in the array to the view location in the DOM for improved performance, especially over large lists is required.

Trying to leave it out, you get the following error:

@for loop must have a "track" expression

On top of that, Angular is using a new optimized algorithm for the for loop so that it’s more performant by making DOM operations as a response to collection changes minimal and hence more efficient.

→ for loop @empty Keyword

On top of that, we now have an @empty keyword that we can use to handle situations where the list is empty, which is kind of neat.

→ readable else

As we saw earlier, doing else in the old control flow syntax in Angular was not really readable and required a lot of boilerplate code, however with the new control flow, it’s much more readable and more familiar, especially for developers just starting out in Angular.

What about the Async Pipe?

Just like before, we can still the async pipe to subscribe to observables just like before.

Within for loops, this is how we can achieve this:

The same can be done for the if blocks:

I am sold, how do I switch?

First, make sure you have updated your Angular project to v17 and then you can run the following schematic to convert existing control flow syntax to the new control flow syntax.

ng g @angular/core:control-flow-migration

When prompted for a path, enter the path to your project and that’s it.

A word of caution, which is a huge step forward in Angular, is that the control flow syntax is in the developer preview. This means some things may change under the hood without following semantic versioning, as it gives the Angular team flexibility to move first and fix issues and concerns that may arise before it’s generally available with the same guarantees Angular provides for all its features.

Next on Unstacked: The all-new @defer syntax

On top of that, Angular is getting a new @defer syntax that can be used to lazy load components, directives, and pipes in the template, until certain conditions are met. I am going to go over this in the next issue of Unstacked in the next couple of weeks as this post is becoming overly long for a newsletter.

Conclusion

In this post, we took a look at the new control flow syntax for angular and the benefits it brings along as compared to the old syntax. We learned that the new control flow syntax is more familiar and subjectively more readable as compared to the old one, and requires less mental gymnastics to understand what’s going on, even for experienced Angular devs, let alone newbies. We also learned how the new syntax not only replaces the old syntax but improves upon it by bringing in extra helpers such as @empty and required track by expression for improved performance.

That’s it from me, and until next time, keep on learning.

DEV Community: Maina Wycliffe

On-Device AI with the Google Chrome Prompt API

Step 1: Download Google Chrome & Enable Required Flags

Step 2: Check Model Availability

Step 3: Download the Model

Step 4: Prompt the Model

Step 5: Clean up

Conclusion

Genkit Tool Calling: Give AI Models (LLMs) the Tools to Get Things Done

Defining Genkit Tools

Genkit Developer UI

Defining a Genkit Flow

Finalising the Agent

Conclussion

Ready to Move From AI Hype to Real-World Results?

Level Up Your Testing Game with Jest Spies and Asymmetric Matchers

Jest Spies

Asymmetric Matchers in Jest

Conclusion

Exploring Routes Rendering Modes in Angular

Setting Up Server Routes Manually

Setting Up For New Projects

Conclusion

Why do we have const enums in Typescript?

Const Enums

Conclusion

Making Generics Types Optional - Generics Fundamentals in Typescript

What does this have to do with generics?

Rules for Default Types

Conclusion

Generic Constraints - A Gentle Introduction to Generics in Typescript

What are generic constraints?

Type variable constrained by another Type Variable

Bonus

Conclusion

Bun - The One Tool for All Your JavaScript/Typescript Project's Needs?

What is Bun?

So, why use Bun?

Speed, it’s Fast, Really Fast

Compatibility with NodeJS and NPM

Built-in Tooling

Web Standard API

Supports Typescript and JSX/TSX out of the Box

Single File Executables

Bun Resources

Conclusion

A Gentle Introduction to Generics in Typescript

What are generics?

Can we use the any Type to solve this problem

Is there a better solution?

So, how do they work?

Do I have to provide the type variable every time?

Where else can we use generics?

Classes and Methods

Types and Interfaces Definition for Key-Value Objects

What’s next?

Conclusion

A Deep Dive into the satisfies operator in Typescript

What is the satisfies Typescript operator

How does the satisfies operator help?

“Real-world” Example

Use Cases

Constraining the type of variable

Constraining the Property Names of an Object and Catching Excess Properties

Constraining the values of Properties, the opposite of the above

Ensuring an Interface is Implemented

Conclusion

Boost your productivity by mastering Oh My ZSH git aliases

Oh My Zsh Git Aliases

Examples

Conclusion

A deep dive into new control flow syntax for Angular (17)

If Conditions

For Loop

NgSwitch

Improvements over the Old Syntax

→ for loop: required track expression

→ for loop @empty Keyword

→ readable else

What about the Async Pipe?

Can we use the `any` Type to solve this problem

What is the `satisfies` Typescript operator

How does the `satisfies` operator help?