bunvim v1.1.11

Bunvim

Bunvim is a Bun client that allows you to interact with Neovim through RPC using TypeScript and JavaScript. If you're familiar with Neovim's Lua API, you'll find this client easy to use.

This client includes TypeScript definitions, generated from Neovim's api-metadata, describing API function signatures, including function parameters and return values.

All functionality is implemented in one file. If you're looking for higher levels of abstraction, take a look at neovim/node-client and neoclide/neovim. Good luck.

✅ Requirements

• Bun
• Neovim

📦 Installation

bun install bunvim

💻 Usage

For examples of plugins using Bunvim, take a look at ghost-text.nvim and github-preview.nvim.

You should keep a tab open with Neovim API docs when working with Bunvim. Although this client includes generated TypeScript types, you'll find the detailed descriptions in the official docs very helpful if not necessary.

Create a script:

// my-plugin.ts
import { attach } from "bunvim";

// RPC listenning address
const SOCKET = "/tmp/bunvim.nvim.socket";

const nvim = await attach({
  socket: SOCKET,
  client: { name: "my-plugin-name" },
});

// append "hello world" to current buffer
await nvim.call("nvim_buf_set_lines", [0, -1, -1, true, ["hello world"]]);

// disable relative numbers
await nvim.call("nvim_set_option_value", ["relativenumber", false, {}]);

// create a vertical split
await nvim.call("nvim_command", ["vs"]);

// print cursor position on cursor move
await nvim.call("nvim_create_autocmd", [
  ["CursorHold", "CursorHoldI"],
  {
    desc: "Print Cursor Position",
    command: `lua
            local cursor_pos = vim.api.nvim_win_get_cursor(0)
            vim.print(cursor_pos)`,
  },
]);

nvim.detach();

Initialize Neovim with the RPC listening address specified above:

nvim --listen /tmp/bunvim.nvim.socket

Execute your script from another terminal:

bun run my-plugin.ts

If your plugin is executed as a child process of Neovim:

-- somewhere in your neovim lua config files

local function run_script()

    -- neovim sets the environment variable NVIM in all its child processes
    -- NVIM = the RPC listening address assigned to the current neovim instance
    -- neovim sets an RPC listening address if you don't manually specify one
    -- https://neovim.io/doc/user/builtin.html#jobstart-env

    vim.fn.jobstart("bun run my-plugin.ts", {
        cwd = vim.fn.expand("~/path/to/plugin/"),
    })
end

vim.api.nvim_create_user_command("RunMyScript", run_script, {})

You could then open Neovim without manually specifying an RPC listening address, just nvim and then run the command :RunMyScript. Your Bun process would then have access to the NVIM environment variable.

// my-plugin.ts
import { attach } from "bunvim";

const SOCKET = process.env["NVIM"];
if (!SOCKET) throw Error("socket missing");

const nvim = await attach({
  socket: SOCKET,
  client: { name: "my-plugin-name" },
});

📖 API Reference

This module exports only one method attach and a bunch of TypeScript types. attach returns an Nvim object that can be used to interact with Neovim.

Used to call any of these functions. They're all typed. You should get function names autocompletion & warnings from TypeScript if the parameters don't match the expected types. Some function calls return a value, others don't.

const bufferContent = await nvim.call("nvim_buf_get_lines", [0, 0, -1, true]);

---

RPC Channel ID.

const channelId = nvim.channelId;

await nvim.call("nvim_create_autocmd", [
  ["CursorMove"],
  {
    desc: "Notify my-plugin",
    command: `lua
        vim.rpcnotify(${channelId}, "my-notification")`,
  },
]);

---

Registers a handler for a specific RPC Notification.

Notifications must be typed before you declare a handler for them, or TypeScript will complain.

import { attach, type BaseEvents, type EventsMap } from "bunvim";

// an interface to define your notifications and their args
interface MyEvents extends BaseEvents {
    requests: EventsMap; // default type
    notifications: {
        // declare custom notification: "cursor_move",
        // that would be called with args: [row: number, col: number]
        "cursor_move": [row: number, col: number];
    };
}

// attach to neovim
const nvim = await attach<MyEvents>({ ... })

let count = 0;

// register a handler for the notification "cursor_move"
nvim.onNotification("cursor_move", async ([row, col]) => {
    // "row" and "col" are of type "number" as specified above

    // CAUTION:
    // it's up to you to make sure the handler receives the correct args,
    // bunvim doesn't do any validations

    // print row and col in neovim
    await nvim.call("nvim_exec_lua", [`print("row: ${row} - col: ${col}")`, []]);

    // return `true` to remove handler
    return count++ >= 5;
});

// multiple handlers can be registered for the same notification
nvim.onNotification("cursor_move", async ([row, col]) => {
    // replace contents in current buffer lines 1 and 2
    await nvim.call("nvim_buf_set_lines", [0, 0, 2, true, [`row: ${row}`, `col: ${col}`]]);
});

const channelId = nvim.channelId;

// create autocommand to notify our plugin via `vim.rpcnotify`
// whenever the cursor moves
await nvim.call("nvim_create_autocmd", [
    ["CursorHold", "CursorHoldI"],
    {
        desc: "Notify on Cursor Move",
        command: `lua
            local cursor_pos = vim.api.nvim_win_get_cursor(0)
            local row = cursor_pos[1]
            local col = cursor_pos[2]
            vim.rpcnotify(${channelId}, "cursor_move", row, col)`,
    },
]);

---

Registers a handler for a specific RPC Request.

Requests must be typed before you declare a handler for them, or TypeScript will complain.

The difference between an RPC Notification and an RPC Request, is that requests block neovim until a response is returned. Notifications are non-blocking.

import { attach, type BaseEvents, type EventsMap } from "bunvim";
import { gracefulShutdown } from "./utils.ts";

// an interface to define your requests and their args
interface MyEvents extends BaseEvents {
    notifications: EventsMap; // default type
    requests: {
        // declare custom request: "before_exit",
        // that would be called with args: [buffer_name: string]
        "before_exit": [buffer_name: string];
    };
}

// attach to neovim
const nvim = await attach<MyEvents>({ ... })

// register a handler for the request "before_exit"
nvim.onRequest("before_exit", async ([buffer_name]) => {
    // "buffer_name" is of type "string" as specified above

    // CAUTION:
    // it's up to you to make sure the handler receives the correct args,
    // bunvim doesn't do any validations

    // this should actually never get called,
    // because this handler gets overwritten below
    console.log("buffer_name: ", buffer_name);

    // we must return something to unblock neovim
    return null;
});

// only one handler per request may be registered.
// if you call `nvim.onRequest` for an already registered handler,
// the older handler is replaced with the new one.
nvim.onRequest("before_exit", async ([buffer_name]) => {
    gracefulShutdown(buffer_name);
    return null;
});

const channelId = nvim.channelId;

// create autocommand to call our function via `vim.rpcrequest`
// whenever neovim is about to close
await nvim.call("nvim_create_autocmd", [
    ["VimLeavePre"],
    {
        desc: "RPC Request before exit",
        command: `lua
            local buffer_name = vim.api.nvim_get_current_buf()
            vim.rpcrequest(${channelId}, "before_exit", buffer_name)`,
    },
]);

---

Closes connection with neovim.

nvim.detach();

---

Instance of winston logger. May be undefined if logging was not enabled.

Used to log data to console and/or file. Does not log/print messages to Neovim.

See Logging.

// log functions sorted from highest to lowest priority:

nvim.logger?.error("error message");
nvim.logger?.warn("warn message");
nvim.logger?.info("info message");
nvim.logger?.http("http message");
nvim.logger?.verbose("verbose message");
nvim.logger?.debug("debug message");
nvim.logger?.silly("silly message");

---

🖨️ Logging

To enable logging to Console and/or File, a logging.level must be specified when calling the attach method.

const nvim = await attach({
  socket: SOCKET,
  client: { name: "my-plugin-name" },
  logging: {
    level: "debug", // <= LOG LEVEL
  },
});

nvim.logger?.info("hello world");

Bunvim internally logs with logger.debug() and logger.error(). Set logging.level higher than debug to not display bunvim's internal logs when printing logs for your plugin.

Levels from highest to lowest priority:

1. error
2. warn
3. info
4. http
5. verbose
6. debug
7. silly

Console

After setting a logging.level, you can see your logs live with the command bunvim logs and specifying the client.name you defined in your attach.

In a terminal, run the command:

# this process will listen for logs and print them to the console
# Ctrl-C to stop process

bunx bunvim logs my-plugin-name

For more information about the CLI tool, run the command:

bunx bunvim --help

File

You can also write your logs to a file by specifying a path when calling the attach method:

const nvim = await attach({
    socket: SOCKET,
    client: { name: "my-plugin-name" },
    logging: {
        level: "debug", // <= LOG LEVEL
        file: : "~/my-plugin-name.log" // <= PATH TO LOG FILE
    },
});

Neovim

If you want to log/print a message to the user in Neovim, use:

import { NVIM_LOG_LEVELS } from "bunvim";

await nvim.call("nvim_notify", ["some message", NVIM_LOG_LEVELS.INFO, {}]);