fredkiss3/bunrest

An express-like API for bun server

🧄 bunrest

What is bunrest 👀

bunrest is an ExpressJs-like API for bun http server.

Features

1. ⚡ BLAZING FAST. Bun is super fast...

2. 0️⃣ dependencies, work seamlessly with Bun

3. 0️⃣ learning curve. If you know ExpressJs, you can start a bun server.

Table of Contents

• Set up
• Usage
• Router
• Middlewares
• Error handling
• Request and Response object
• Future

Get started

To download bun

curl -fsSL https://bun.sh/install | bash

To create a bun project

bun init

This will create a blank bun project

see reference here

Server set up

Download the package

bun install bunrest

import server from "bunrest";
const app = server();

Usage

After that, you can write http method just like on express

app.get('/test', (req, res) => {
  res.status(200).json({ message: req.query });
});

app.put('/test/:id', (req, res) => {
  res.status(200).json({ message: req.params.id });
});

app.post('/test/:id/:name', (req, res) => {
  res.status(200).json({ message: req.params });
});

Router

The same as above, we create a router by calling server.Router()

After creation, we attach the router to server by calling server.use(your_router_reference)

// add router
const router = app.router();

router.get('/test', (req, res) => {
  res.status(200).json({ message: 'Router succeed' });
})

router.post('/test', (req, res) => {
  res.status(200).json({ message: 'Router succeed' });
})

router.put('/test', (req, res) => {
  res.status(200).json({ message: 'Router succeed' });
})

app.use('/your_route_path', router);

Middlewares

We have two ways to add middlewares

1. use : Simply call use to add the middleware function.

2. Add middleware at the middle of your request function parameters.

// use
app.use((req, res, next) => {
  console.log("middlewares called");
  // to return result
  res.status(500).send("server denied");
});

app.use((req, res, next) => {
  console.log("middlewares called");
  // to call next middlewares
  next();
})

// or you can add the middlewares this way
app.get('/user', 
    (req, res, next) => {
      // here to handle middleware for path '/user'
    },
    (req, res) => {
      res.status(200).send('Hello');
    });

Error handling

To add a global handler, it's really similar to express but slightly different. The fourth argument is the error object, but I only get [native code] from error object, this might related to bun.

app.use((req, res, next, err) => {
    res.status(500).send('Error happened');
 });

At this time, if we throw an error on default path /

app.get('/', (req, res) => {
  throw new Error('Oops');
})

It will call the error handler callback function and return a response. But if we have not specified a response to return, a error page will be displayed on the browser on debug mode, check more on bun error handling

Start the server, listen to port

app.listen(3000, () => {
  console.log('App is listening on port 3000');
});

Request and Response object

To simulate the ExpressJs API, the default request and response object on bunjs is not ideal.

On bunrest, we create our own request and response object, here is the blueprint of these two objects.

Request interface

export interface BunRequest {
  method: string;
  request: Request;
  path: string;
  header?: { [key: string]: any };
  params?: { [key: string]: any };
  query?: { [key: string]: any };
  body?: { [key: string]: any };
  blob?: any;
}

Response interface

export interface BunResponse {
    status(code: number): BunResponse;
    option(option: ResponseInit): BunResponse;
    statusText(text: string): BunResponse;
    json(body: any): void;
    send(body: any): void;
    // nodejs way to set headers
    setHeader(key: string, value: any);
    // nodejs way to get headers
    getHeader();this.options.headers;
    headers(header: HeadersInit): BunResponse;
    getResponse(): Response;
    isReady(): boolean;turn !!this.response;
}

The req and res arguments inside every handler function is with the type of BunRequest and BunResponse.

So you can use it like on Express

const handler = (req, res) => {
  const { name } = req.params;
  const { id } = req.query;
  res.setHeader('Content-Type', 'application/text');
  res.status(200).send('No');
}

Next

Server rendering, websocket