Promised-neovim-client NPM

Promisified neovim-client

This is ES6 Promise version NeoVim msgpack-rpc client for modern JavaScript environment. I'm dogfooding this package with NyaoVim and add many improvements.

Installation

npm install --global promised-neovim-client

Requirements

Node.js v4.4 or later
Neovim v0.1.6 or later

Usage

This package exports a single attach() function which takes a pair of write/read streams and returns a promise with a Nvim API object. This is similar to node-msgpack5rpc, but it provides an automatically generated API.

Examples:

var cp = require('child_process');
var attach = require('promised-neovim-client').attach;

var nvim_proc = cp.spawn('nvim', ['-u', 'NONE', '-N', '--embed'], {});
attach(nvim_proc.stdin, nvim_proc.stdout).then(function(nvim) {
  nvim.on('request', function(method, args, resp) {
    // handle msgpack-rpc request
  });

  nvim.on('notification', function(method, args) {
    // handle msgpack-rpc notification
  });

  nvim
    .command('vsp')
    .then(() => nvim.listWins())
    .then(windows => {
      console.log(windows.length);  // 2
      console.log(windows[0] instanceof nvim.Window); // true
      console.log(windows[1] instanceof nvim.Window); // true
      return nvim.setCurrentWindow(windows[1])
        .then(() => nvim.getCurrentWindow())
        .then(win => {
          console.log(win.equals(windows[1]))  // true
          nvim.quit();
          nvim.on('disconnect', () => console.log("Nvim exited!"));
        });
    }).catch(err => console.log(err.message));

}).catch(err => console.log(err.message));

Methods are attached to buffers, windows and tabpages according to the msgpack-rpc name:

nvim
  .getCurrentBuffer()
  .then(buf => {
    console.log(buf instanceof nvim.Buffer);  // true
    return buf
      .getLineSlice(0, -1, true, true);
      .then(lines => {
        console.log(lines);  // ['']
        return buf.setLineSlice(0, -1, true, true, ['line1', 'line2']);
      }).then(() => getLineSlice(0, -1, true, true))
      .then(lines => console.log(lines))  // ['line1', 'line2']
  });

Notification

A client always send request on calling remote APIs. This is because client's methods can't know the caller actually uses the returned Promise value. So I added notify boolean parameter as the last one of method parameters. If it is set to true, the client sends notification instead of request and it won't return Promise value. Simply will return undefined and we cannot know when the API call finishes.

Notification is faster than request because nvim needs not to return the response to the client.

nvim.command('echo "This is notification"', true);

TypeScript

A typescript declaration file is available as documentation of the API and also for typescript users that seek to use this library. Note that the interfaces are automatically generated at a certain point in time, and may not correspond exactly to the API of your installed Nvim.

You need not use DefinitelyTyped to use this package with TypeScript. It is automatically imported if you install this package with npm. TypeScript 1.6 or later is needed. Please install @types/node also for child_process module.

Below is an example using TypeScript and async/await.

import {attach, RPCValue} from 'promised-neovim-client';
import {spawn} from 'child_process';

async function run() {
    const proc = spawn('nvim', ['-u', 'NONE', '-N', '--embed'], {cwd: __dirname });

    const nvim = await attach(proc.stdin, proc.stdout);
    nvim.on('request', (method: string, args: RPCValue[], resp: RPCValue) => {
        // handle msgpack-rpc request
    });

    nvim.on('notification', (method: string, args: RPCValue[]) => {
        // handle msgpack-rpc notification
    });
    await nvim.uiAttach(80, 24, {rgb: false});

    const v = await nvim.getVersion();
    console.log('Version:', v);

    await nvim.command('vsp');
    const wins = await nvim.listWins();
    await nvim.setCurrentWin(wins[1]);
    const win = await nvim.getCurrentWin();
    console.log('Current window:', win);

    let lines: string[];
    const buf = await nvim.getCurrentBuf();
    lines = await buf.getLineSlice(0, -1, true, true);
    console.log('Before lines:', lines);
    await buf.setLineSlice(0, -1, true, true, ['line1', 'line2']);
    lines = await buf.getLineSlice(0, -1, true, true);
    console.log('After lines:', lines);
    await nvim.quit();
}

run().then(() => console.log('Done!'));