Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rhysd/promised-neovim-client

node.js neovim client for modern JavaScript programmers
https://github.com/rhysd/promised-neovim-client

client neovim node

Last synced: about 2 months ago
JSON representation

node.js neovim client for modern JavaScript programmers

Awesome Lists containing this project

README 

        
Promisified neovim-client

=========================

[![Build Status](https://travis-ci.org/rhysd/promised-neovim-client.svg)](https://travis-ci.org/rhysd/promised-neovim-client)

[![npm version](https://badge.fury.io/js/promised-neovim-client.svg)](https://badge.fury.io/js/promised-neovim-client)

[![Coverage Status](https://coveralls.io/repos/github/rhysd/promised-neovim-client/badge.svg?branch=promisified)](https://coveralls.io/github/rhysd/promised-neovim-client?branch=promisified)



This is ES6 `Promise` version NeoVim msgpack-rpc client for modern JavaScript environment.

I'm dogfooding this package with [NyaoVim](https://github.com/rhysd/NyaoVim) and add many improvements.



## Installation



```sh

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](https://github.com/tarruda/node-msgpack5rpc), but

it provides an automatically generated API.



Examples:



```js

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:



```js

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.



```javascript

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

```



## TypeScript



A [typescript declaration file](index.d.ts) 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](scripts/generate-typescript-interfaces.js) at a

certain point in time, and may not correspond exactly to the API of your installed Nvim.



You need not use [DefinitelyTyped](https://github.com/borisyankov/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.



```typescript

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!'));

```



## Authors



- __Original Author__: `Thiago de Arruda `

- __Current Author__: `rhysd `