DEV Community: Nazeel

Writing a simple RESTful TypeScript web service with Bun.js

Nazeel — Mon, 05 Feb 2024 20:41:30 +0000

Bun.js is a JavaScript runtime written in Zig and powered by JavaScriptCore (which used in WebKit). It has native support for TypeScript, its own test runner, package manager, bundler and much much more.

In this blog post, I will attempt to guide you through the process of writing a simple feature flag RESTful web service with Bun.js and zod.

Yes, you read that right. No other dependencies, frameworks or libraries would be required to get this up and running.

Prerequisites

Not much! Just some basic knowledge around RESTful services, JavaScript, TypeScript will do. I will try my best to explain each step as descriptively as possible.

Remember when I said no other dependencies? I lied... sorta. You also need an API client like cURL, Postman or Insomnia.

Setting up

First, head over to the Bun installation and get bun installed. Execute the following command to see if bun is installed:



➜  bun --version
1.0.21

Awesome! We can now scaffold a simple bun project by running bun init command:



➜  bun init
bun init helps you get started with a minimal project and tries to guess sensible defaults. Press ^C anytime to quit

package name (feature-flag-service): 
entry point (index.ts): 

Done! A package.json file was saved in the current directory.
 + index.ts
 + .gitignore
 + tsconfig.json (for editor auto-complete)
 + README.md

To get started, run:
  bun run index.ts

Simple as that! Now let's install zod, of which more will be revealed further down this article.



➜  bun add zod
bun add v1.0.21 (837cbd60)

 installed zod@3.22.4

 1 package installed [130.00ms]

Amazing! Now let's create add a script that can start bun in hot reload mode so that we can have the latest version of our service without having to stop and start.



{
    "name": "feature-flag-service",
    "module": "index.ts",
    "type": "module",
    "devDependencies": {
        "@types/bun": "latest"
    },
    "peerDependencies": {
        "typescript": "^5.0.0"
    },
    "scripts": {
        "start": "bun --hot run index.ts"
    },
    "dependencies": {
        "zod": "^3.22.4"
    }

}

Run the start command like so:



➜  bun start
$ bun --hot run index.ts
Hello via Bun!

Let's update the index.ts file and see if bun hot reloads the file:



console.log("Hello via Bun!")
console.log("Initializing the feature flag service")

Save the file, and you should see that the terminal updates with both the console logs printed.



Hello via Bun!
Initializing the feature flag service

With that, we have our setup completed!

Creating a HTTP server in Bun

To create and HTTP server in Bun, the Bun.serve function can be used. This takes in an object with many parameters, but we are interested in 2 of them. Namely fetch; which handles the request and port which designates the port at which to listen to.

Let's add that into the end of the index.ts file:



Bun.serve({
    port: 8080,
    fetch(req) {
        return new Response("Bun!")
    },
})

Give yourself a pat on the back because you just created a HTTP server! Save this and go to localhost:8080 to confirm. You should see a webpage that displays Bun!.

Making it RESTful

If you inspect the response in the inspector, you will see that Bun is just wrapping whatever response we give pass to the Response constructor in a pre HTML tag.

Our service is going to be RESTful, so we should only send and receive in JSON. To make our server return a JSON, let's make some changes to the fetch function:



fetch(req) {
    return new Response(
        JSON.stringify({ message: 'Hello!' }),
        { headers: { 'Content-Type': 'application/json' } }
    )
}

Now if you refresh the webpage, you can see that the response has changed into JSON and depending on your browser, it should render either the JSON view or the plaintext JSON.

Feature flag service

A feature flag is a string key boolean value pair that determines if the key feature is enabled or not based on value. A feature flag service exposes endpoints that help you create/update and read feature flag values. These correspond to the PUT and GET HTTP verbs. The endpoint would be something like localhost:8080/flags.

Let's add some types at the top of the file to help us determine what type of call the client is trying to make.



// Types
type Path = '/flags'
type Method = 'GET' | 'PUT'
type ApiEndpoint = `${Method} ${Path}`

ApiEndpoint will be one of PUT /flags or GET /flags.

Routing

Let's update the fetch function to determine what type of call is coming through.



try {
    const url = new URL(req.url)
    const method = req.method

    const apiEndpoint: ApiEndpoint = `${method as Method} ${url.pathname as Path}`

    switch(apiEndpoint) {
        case 'PUT /flags':
            return new Response(
                JSON.stringify({ message: `You called PUT /flags` }),
                { headers: { 'Content-Type': 'application/json' }, status: 200 }
            )
        case 'GET /flags': 
            return new Response(
                JSON.stringify({ message: `You called GET /flags` }),
                { headers: { 'Content-Type': 'application/json' }, status: 200 }
            )
        default:
            return new Response(
                JSON.stringify({ message: `You called ${apiEndpoint}, which I don't know how to handle!` }),
                { headers: { 'Content-Type': 'application/json' }, status: 404 }
            )
    }
} catch(err) {
    console.log(err)
    return new Response(JSON.stringify({ message: 'Internal Server Error' }), { headers: { 'Content-Type': 'application/json' }, status: 500})
}

Pretty simple.

We create a URL object by passing the request URL into the URL constructor. This gives us a handy way to access the URL, its params, and so on.
Then, we extract the request method into the method variable, which can be one of the HTTP verbs.
We then construct a string called apiEndpoint, concatenating the two values calculated above.
A switch block that tests against apiEndpoint, which effectively is our service router at this point.
Handlers for each route and method inside each case block.
Wrap this all in a nice try-catch block to catch any runtime errors for the implementations to follow!

Okay, let's try to access the endpoint now with out API client of choice (I'm using Insomnia, because it's 1:24 AM as I type this).

GET /flags:

PUT flags:

DELETE flags:

With that, we have created a service level router for all incoming requests. Now we can define each of our route functionalities more clearly...

... but before that, a bit of refactoring!

You may have noticed in the last code block, we blatantly violated the DRY principle in the form of all those 4 Response objects we created in each return statement. The pattern seems to be:



Response(
    JSON.stringify(someJSON), 
    { headers: { 'Content-Type': 'application/json' }, status: someNumber }
)

We have to keep in mind:

We always want to JSON stringify our response, this is to abide by the principle of RESTful services.
We always want to have the Content-Type header as application/json, due to the same reason above.

We could create a class that wraps some of these repeated functionalities so it's easier to use. At the top of the file, below the types, add the following:



// Constants
const responseHeaders = { headers: { 'Content-Type': 'application/json' } }

// Custom classes
class CustomResponse extends Response {
    constructor(response: Record<any, any>, headerOverride?: Bun.ResponseInit) {
        super(JSON.stringify(response), {...responseHeaders, ...headerOverride})
    }
}

This class extends the response class and does the JSON.stringify and header override for us. Now we can replace the fetch code with the following:



try {
    const url = new URL(req.url)
    const method = req.method

    const apiEndpoint: ApiEndpoint = `${method as Method} ${url.pathname as Path}`

    switch(apiEndpoint) {
        case 'PUT /flags':
            return new CustomResponse({ message: `You called PUT /flags` }, { status: 200 })
        case 'GET /flags': 
            return new CustomResponse({ message: `You called GET /flags` }, { status: 200 })
        default:
            return new CustomResponse({ message: `You called ${apiEndpoint}, which I don't know how to handle!` }, { status: 404 })
    }
} catch(err) {
    console.log(err)
    return new CustomResponse({ message: 'Internal Server Error' }, { status: 500 })
}

Wow, so much cleaner and readable!

Implementing PUT /flags

When accepting a new flag (or updation to an existing flag) We would like the PUT payload to follow a certain shape:



{
    key: string,
    value: boolean
}

We could use something like Object.hasOwnProperty to verify this, then assert that each key is a typeof boolean or string. Or, we could use zod, a static type inference as well as a runtime validator for a request object.

At the top, add the following code:



import { z } from "zod"

// Other types
const FeatureFlag = z.object({
    key: z.string().min(1),
    value: z.boolean()
})
type FeatureFlagType = z.infer<typeof FeatureFlag>

With this, we say that FeatureFlag is an object that has a key of type string with length of at least 1 and a value of type boolean. We can then infer the type into a static TS type by using z.infer.

Before we proceed, let's make our fetch function async so we can do a lot of the asynchronous tasks required to get the PUT /flags running.



Bun.serve({
    port: 8080,
    async fetch(req) {
        // fetch implementation
    }
})

Now we can flesh out the PUT route:



case 'PUT /flags': {
    const request = await req.json() as FeatureFlagType
    if (!FeatureFlag.safeParse(request).success) {
        return new CustomResponse({ message: 'Bad Request' }, { status: 400 })
    }

    const featureFlagToInsert = {
        [request.key]: request.value
    }

    let updatedFeatureFlagInfo = featureFlagToInsert

    // write to file
    try {
        const featureFlagFile = Bun.file('feature_flags.json', { type: "application/json" })

        if (await featureFlagFile.exists()) {
            const featureFlagObject = JSON.parse(await featureFlagFile.text())
            updatedFeatureFlagInfo = {
                ...featureFlagObject,
                ...updatedFeatureFlagInfo
            }
        }

        Bun.write(featureFlagFile, JSON.stringify(updatedFeatureFlagInfo))
    } catch(err) {
        console.log(err)
        return new CustomResponse({ message: 'Internal Server Error' }, { status: 500})
    }

    return new CustomResponse({ message: 'Created' }, { status: 201})
}

Whoa. Lots to unpack here, so let's go through it step by step.

We first get the request body by awaiting the req.json().
Using the power of almighty zod, we parse the object and verify that it is indeed conforming to our definition of the FeatureFlag zod validator. Note that we use safeParse instead of parse since the latter would throw an error and we'd have to handle that.
We then change the format so that we can insert the feature flag into our global feature flag object. But where do we store it? How can it be persisted?
Bun's file I/O comes swooping in to the rescue. Leveraging Bun.file which lazy loads an instance of a file, we create one.
If this file exists, we fetch the text, parse it into JSON, and update the object.
Finally, we write the updated object back into the file.

Let's see it in action:

That wraps up the PUT implementation of feature flags.

Implementing GET /flags

The GET endpoint logic is pretty simple.

We check the request URL search params for a key name. If it does not exist, we return with a 400 Bad Request response.
If the feature flag file exists, we parse it and fetch the key from the feature flag object. If it does not, we simply return that the key is not registered.
The fetched key is then converted into the FeatureFlagType type and returned.

So it'll look something like this:



case 'GET /flags': {
    const featureFlagFile = Bun.file('feature_flags.json', { type: "application/json" })

    const key = url.searchParams.get('key')

    if (!key) {
        return new CustomResponse({ message: 'Key missing in request' }, { status: 400 })
    }

    if (await featureFlagFile.exists()) {
        const featureFlagObject = JSON.parse(await featureFlagFile.text())
        const value = featureFlagObject[key]

        if (value === undefined) {
            return new CustomResponse({ message: 'Key is not registered' }, { status: 404 })
        }

        const response: FeatureFlagType = {
            key,
            value
        }

        return new CustomResponse(response, { status: 200})
    }

    return new CustomResponse({ message: 'Key is not registered' }, { status: 404 })
}

Now let's see it run!

Voila! We can also fetch this information from the service now.

Conclusion

In conclusion, we have learned how to:

Create a HTTP server in Bun.js
Tweak it to be a RESTful service
Create a service level router per method and endpoint
Implement the functionality of the feature flag service
Leverage Bun's File I/O to persist the feature flag information

Additional challenges

If you have been following along so far (you rock!) and still want to do more, I invite you to try to:

Add a DELETE /flags endpoint which deletes the key provided.
Replace the File I/O with an in-memory database to speed up the service.
Add a simple authentication to the feature flag service.
Bundle up this project using Bun.build and host it in a cloud provider (or any server, Raspberry Pie, etc) of your choice.

References:

Writing type safe API clients in TypeScript

Nazeel — Sat, 06 Jan 2024 09:54:25 +0000

Writing API integrations can be a daunting task. But it does not need to be. How many times have you had to deal with these problems?

You want type safe API calls with typified response types and request types.
You have manually typed your API response structures in the past and found it to be a cumbersome effort which is also prone to errors.
You do not want to deal with the complexity of setting up and maintaining something like GraphQL for making API integration simpler.
Your APIs are microservices and your frontend API layer is not able to keep up with the various changes in each microservice.

If you resonate with any of the above points, then you’re in for a treat. In this blog post, I will try to show you a way to build type safe API clients on any TypeScript frontend, CLI or SDK application.

In order to provide a middle ground between the chaos that is writing your own types and the complexity that is to set up something like GraphQL, we'll be using openapi-typescript. The API client I've chosen here is axios, but feel free to use any API client that allows you to define response types as generics.

So what is `openapi-typescript` anyway?

openapi-typescript is a TypeScript type generator that takes an openapi spec file and generates a TypeScript schema for you. This is advantageous in many ways:

It prevents any sort of margin for human error if you were to, say, write the types on your own.
It saves a lot of time.
You don't have to deal with setting up and maintaining something like GraphQL or tRPC, which can both be paradigm shifts for the team or in some cases, over-engineering.
It requires no additional dependencies.

Getting Started

To achieve this, I'll be using a simple typescript project that has three files, namely:

main.ts
api.ts
schema.ts (this is generated by openapi-typescript)

And I'll be using the OpenAPI Pet Store spec file as an example.

Of course, you'll also need a working node installation.

Generating the schema

Run the following command to generate the schema from the pet store api spec.



npx openapi-typescript https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml -o schema.ts

This will generate the schema.ts file which can then be used in our API file. Note that I opted for using the URL of the spec file, you can choose to reference a local file as well by providing the relative path from where the command is being run.

The file will look something like this:



/**

* This file was auto-generated by openapi-typescript.

* Do not make direct changes to the file.

*/

export interface paths {}

export type webhooks = Record<string, never>;

export interface components {}

export type $defs = Record<string, never>;

export type external = Record<string, never>;

export interface operations {}

There are 3 core exported interfaces that we are interested in. Let's break each one down:

components - The gold we need resides here which are the schemas that are used by the API, including their shapes and the type of each attribute.
operations - Operations refer to each of the possible operations defined in the API spec, their query parameters (if any) and their possible response types (based on success or error statuses), all referencing the the corresponding components entry based on the operation.
paths - This contains all the API endpoints that are exposed as per the API spec, grouped by the endpoint and including the REST operations allowed (GET, POST, etc) and links them to the corresponding operations. This will be the most used exported module of this file.

Alright, now that we've got the schema out of the way, let's look at how we can bring this into our APIs.

Integrating with the API layer

First, let's import our axios, schema modules and split the api.ts file into 3 sections:



import axios from 'axios'
import { paths } from './schema'

// Request shape

// Response shape

// API client

// API definitions

The request shape section has all the types that are required to make an API call for a specific operation.
The response shape section has all the types associated with the response of the API
In the API client section, we define the API client and other client related code such as interceptors to add auth headers, etc.
In the API definitions, we define each API, with the help of all the above ingredients.

Request shape

The request shape can be derived from the paths bit of the schema. Let's add in the request shape for all the APIs.



// Request shape
type GetPetsRequest = paths['/pets']['get']['parameters']
type GetPetByIdRequest = paths['/pets/{petId}']['get']['parameters']

Response Shape

Similarly, the response shape can also be derived from the operations bit of the schema. Let's add in the response shape for all the APIs.



// Response shape

type GetPetsResponse = paths['/pets']['get']['responses']['200']['content']['application/json']
type GetPetByIdResponse = paths['/pets/{petId}']['get']['responses']['200']['content']['application/json']

API Client

Here we define the actual API client which will be used for making all of the calls to the petstore service:




// API client

const petAPIClient = axios.create({
    baseURL: 'https://api.petstore.com/'
})

petAPIClient.interceptors.request.use(
    async config => {
        return {
            ...config,
            headers: {
                'Authorization': 'Bearer abcd'
            } as any
        }
    }
)

API Definitions

And finally, let's use all of the above ingredients to cook up a nice little API meal for our application to consume!



// update the import for the Method type
import axios, { type Method } from 'axios'

// API definitions

export const getPets = ({
    params
} : {
    params: GetPetsRequest
}) => petAPIClient.request<GetPetsResponse>({
    method: 'GET' as Method,
    params: {
        limit: params.query?.limit
    }
})

export const getPetById = ({
    params
} : {
    params: GetPetByIdRequest
}) => petAPIClient.request<GetPetByIdResponse>({
    url: `${params.path.petId}/`,
    method: 'GET' as Method
})

Voila! You've successfully set up the API layer of the frontend application. Onward to integration!

Integrating with the application

Integrating with the application is as simple as declaring the API call using a dedicated function.



import { getPets } from "./api"

const fetchAllPets = async () => {
    try {
        const result = await getPets({
            params: {
                query: {
                    limit: 1
                }
            }
        })
        console.log(result.data[0].id)
    } catch (err) {
        console.log(err)
    }
}

If you're tagging along with me, you will notice that all the intellisense goodness just works when you try to make an API call! Here is a gif to demonstrate this.

Isn't that a sight to behold?

Conclusion

What we've achieved here are type safe API calls in the frontend with a very minimal setup and no additional dependencies. Any changes in the schema will cause TypeScript compiler to scream wherever the changes are breaking so all nooks and crannies are covered when something changes in the API spec!

Of course, there are some caveats with this approach:

You need to be in constant sync with the backend engineer to make sure that any changes in the API spec also need to be communicated well in advance so you can coordinate the changes in the frontend. However, one argument to this is any breaking changes need to be versioned by the API and a new spec file is to be generated so that we can repeat the process and upgrade the frontend to the latest API gracefully.
You'll need to watch out for any changes made to the schema file in pull requests to make sure that it is not changed unintentionally. Obviously, any changes made would also mean corresponding invocations and unit tests would break the TS compiler, so this stands at less of a risk than the above.

Links & References:

DEV Community: Nazeel

Writing a simple RESTful TypeScript web service with Bun.js

Prerequisites

Setting up

Creating a HTTP server in Bun

Making it RESTful

Feature flag service

Routing

... but before that, a bit of refactoring!

Implementing PUT /flags

Implementing GET /flags

Conclusion

Additional challenges

References:

Writing type safe API clients in TypeScript

So what is openapi-typescript anyway?

Getting Started

Generating the schema

Integrating with the API layer

Request shape

Response Shape

API Client

API Definitions

Integrating with the application

Conclusion

So what is `openapi-typescript` anyway?