rescript-bun

rescript-bun

Use Bun with ReScript.

Currently alpha state software. You're encouraged to start using it, but please report all issues. There will be both bindings missing and some bindings will probably be wrong/suboptimal. We're going to work through the API surface as we go. Report all issues you find!

Getting started

Template repo to get up and running quickly: https://github.com/zth/rescript-bun-starter

You need to be on ReScript v12 >=12.0.0-alpha.4.

Install rescript-bun:

npm i rescript-bun@2.0.0-alpha.1

Include them in your rescript.json:

{
  "bs-dependencies": ["rescript-bun"]
}

rescript-bun is namespaced, so you'll find all modules listed under the main module RescriptBun.

You're strongly encouraged to open RescriptBun globally, to get the best possible developer experience. You do that by adding this to your rescript.json:

{
  "bsc-flags": ["-open RescriptBun", "-open RescriptBun.Globals"]
}

Notice -open RescriptBun.Globals. This will expose all Bun globals. This might be a matter of taste, but I recommend opening it to get the best experience.

This will make all of Bun available to you without needing to dip into the RescriptBun module explicitly.

Credits

This lib copies rescript-nodejs for Bun's Node compatible bindings. Shout out to the maintainers of that project!

Examples

Here's a few examples of how it looks. More examples (often inspired by https://bun.sh/guides) can be found in the playground/examples directory in this repo.

Testing

To write tests using Bun's built in test runner, just open Test and you'll have everything available to you to write your tests:

open Test

describe("Playing around with tests", () => {
  test("addition works", () => {
    expect(1 + 1)->Expect.toBe(2)
  })
})

This will make all of Bun's testing utilities available to you in the global scope.

Setting up a simple server

Here's setting up a simple web server.

let server = Bun.serve({
  fetch: async (request, _server) => {
    let userName =
      request
      ->Request.headers
      ->Headers.get("x-user-name")
      ->Option.getWithDefault("Unknown user")

    Response.make(`Hello ${userName}!`, ~options={status: 200})
  },
})

let port =
  server
  ->Bun.Server.port
  ->Int.toString

let hostName = server->Bun.Server.hostname

Console.log(`Server listening on http://${hostName}:${port}!`)

Hashing and verifying a password

let password = "super-secure-pa$$word"

let bcryptHash = await Bun.Password.hash(
  password,
  ~algorithm=BCryptAlgorithm({
    cost: 4, // number between 4-31
  }),
)

let isMatch = await Bun.Password.verify(password, ~hash)

Using the file system router

let router = Bun.FileSystemRouter.make({
  style: NextJs,
  dir: "./pages",
  origin: "https://mydomain.com",
  assetPrefix: "_next/static/",
})

let matches = router->Bun.FileSystemRouter.match("/")

Using HTMLRewriter to rewrite HTML

// Rewrite all <div> to <section>

let rewriter = HTMLRewriter.make()->HTMLRewriter.on(
  "*",
  {
    element: element => {
      if element.tagName === "div" {
        element.tagName = "section"
      }
    },
  },
)

let response = await fetch("https://bun.sh")
let transformedResponse = rewriter->HTMLRewriter.transform(response)

let html = await transformedResponse->Response.text

Console.log(html)

Current project state

Currently, bindings exist for the most common things. There's still a good amount of bindings missing. Some bindings will be covered as we go along, while others won't be added.

Missing bindings

Crucial

• Globals
• Bun
• Tests
• Fs
• Stream (some stream utils already exist in Globals + Bun)
• Path

Prio 2

• AsyncHooks
• Crypto
• Buffer
• Child_process (needs Stream?)
• HTML Rewriter
• Os
• Sqlite
• Perf hooks
• StringDecoder
• Readline (needs Stream?)
• WorkerThreads

Prio 3

• FFI
• Util
• SupportsColors
• Timers
• Tls
• Tty

Unclear if needed

• Assert
• Diagnostics channel
• Dns
• Domain
• Events
• JSC
• Module
• Net
• VM
• WS (already multiple websocket things present)
• Zlib (bun has its own gzip?)
• Http (Nodes built in HTTP, should use Bun's own, right?)

Definitively not needed

• URL (available in globals)
• Constants (deprecated)
• Querystring (deprecated)
• Punycode (deprecated)
• Console (Core has it)

Other things to figure out

• How to reuse/contribute to rescript-webapi instead of rolling our own bindings. I've intentionally not reused any other existing library because I wanted to start from scratch and follow ReScript v11+ idioms as much as possible. But once all of this settles, we need to figure out and share the common denominator with rescript-webapi and other similar projects to this.

Contributing

Contributions are very welcome. We're aiming to cover close to 100% of the Bun API surface, which is quite huge task. But, it's definitively possible and the initial large effort pays dividends over time.

If you do want to contribute, please open an issue saying you're starting work on module X. So we don't accidentally double work.