bnfn

bnfn is a Bun-native HTTP client with an Axios-shaped API and a required Zig primitive layer.

It is intended to run in one supported mode only:

• Bun runtime
• built Zig native library

It is not a full Axios reimplementation. The current scope is:

• Callable default export: bnfn(url, config?)
• Instance API: create(), request(), get(), post(), put(), patch(), delete(), head(), options()
• Request and response interceptors
• Config merging and baseURL/params support
• Header normalization through AxiosHeaders
• Bun fetch transport
• Required Zig acceleration for RFC 3986 percent-encoding and bulk query-entry serialization

Install

npm install @easydeploy/bnfn

npm install builds the Zig native library during postinstall. If zig is missing or the native build fails, installation fails.

The runtime-compatibility design and the latest benchmark output are documented in docs/compatibility-performance.md.

Project architecture, file layout, and the TypeScript surface are documented in docs/project.md.

Why this shape

Axios spends a meaningful amount of CPU time on object plumbing before network I/O: config merging, header normalization, and query serialization. This project keeps the higher-level API in JavaScript while pushing the bulk string/query work that benefits from native execution down into Zig, with no JavaScript fallback path for the supported Bun+Zig runtime.

Native layer

The native layer is required. Importing bnfn without Bun FFI or without a built native library is considered a setup error.

That means:

• Bun with a built library: supported
• Bun without a built library: unsupported
• Node: unsupported

Build the Zig library:

npm run build:native

Inspect native status:

npm run inspect:native

Run the axios comparison benchmark:

bun run bench:axios

Benchmark against an explicit axios installation:

bun run bench:axios -- --axios-root=/path/to/node_modules/axios

The benchmark resolves axios from the current project by default, or from --axios-root when you want to compare against another install. It compares bnfn against axios on:

• mergeConfig
• AxiosHeaders.from()/set()/toJSON()
• getUri(baseURL + params)

It also benchmarks the full client request pipeline with a no-op adapter through the public client API.

The build emits one of:

• native/libbunxios_primitives.dylib
• native/libbunxios_primitives.so
• native/libbunxios_primitives.dll

TypeScript

The runtime source stays in JavaScript, but the package now ships index.d.ts as its public type surface.

That gives Bun/TypeScript consumers typed access to:

• the callable default export
• request config and response shapes
• AxiosHeaders, AxiosError, and interceptor APIs
• native status inspection via native()

Usage

import bnfn from "@easydeploy/bnfn";

const api = bnfn.create({
  baseURL: "https://example.com/api",
  headers: {
    common: {
      Accept: "application/json"
    }
  }
});

api.interceptors.request.use((config) => {
  config.headers = {
    ...(config.headers ?? {}),
    "x-runtime": "bun"
  };
  return config;
});

const response = await api.get("/users", {
  params: {
    page: 1,
    q: "bun zig"
  }
});

console.log(response.data);

Limits

• Bun-only runtime
• Native Zig library is required
• No browser or Node runtime support
• Not all Axios edge cases are implemented