Merge #316 rename getNvimFromEnv => findNvim

README.md

@@ -19,14 +19,14 @@ See below for a quickstart example that you can copy and run immediately.
 
 The `neovim` package exposes these functions:
 
-- `getNvimFromEnv`: Tries to find a usable `nvim` binary on the current system.
-- `attach`: The primary interface. Takes a process, socket, or pair of write/read streams and returns a `NeovimClient` connected to the `nvim` server.
+- `findNvim`: Tries to find a usable `nvim` binary on the current system.
+- `attach`: The primary interface. Takes a process, socket, or pair of write/read streams and returns a `NeovimClient` connected to an `nvim` process.
 
 ### Quickstart: connect to Nvim
 
 Following is a complete, working example.
 
-1. Install the `neovim` package _locally_ (i.e. without `-g`. Node will fail with `ERR_MODULE_NOT_FOUND` if a script tries to import a _globally_ installed package).
+1. Install the `neovim` package _locally_ (i.e. without `-g`. Node throws `ERR_MODULE_NOT_FOUND` if a script imports a _globally_ installed package).
    ```bash
    npm install neovim
    ```
@@ -38,11 +38,11 @@ Following is a complete, working example.
 ```js
 import * as child_process from 'node:child_process'
 import * as assert from 'node:assert'
-import { attach, getNvimFromEnv } from 'neovim'
+import { attach, findNvim } from 'neovim'
 
 // Find `nvim` on the system and open a channel to it.
 (async function() {
-  const found = getNvimFromEnv({ orderBy: 'desc', minVersion: '0.9.0' })
+  const found = findNvim({ orderBy: 'desc', minVersion: '0.9.0' })
   console.log(found);
   const nvim_proc = child_process.spawn(found.matches[0].path, ['--clean', '--embed'], {});
 
@@ -190,27 +190,28 @@ See the tests and [`scripts`](https://github.com/neovim/node-client/tree/master/
 
 ## Maintain
 
-Maintenance tasks:
-
 ### Release
 
 Only maintainers of the [neovim NPM package](https://www.npmjs.com/package/neovim) can publish a release. Follow these steps to publish a release:
 
-```bash
-cd packages/neovim
-# Choose major/minor/patch as needed.
-npm version patch
-cd -
-# Note: this copies the top-level README.md to packages/neovim.
-npm run publish:neovim
-
-# Post-relase
-export _VERSION=$(grep -o 'version": "[^"]\+' packages/neovim/package.json | sed 's/.*"//')
-git tag "v${_VERSION}"
-cd packages/neovim/
-npm version --no-git-tag-version prerelease --preid dev && git add package*.json && git commit -m bump
-git push --follow-tags
-```
+1. Update `CHANGELOG.md`.
+2. Update version. Build and publish the package. Tag the release and push.
+   ```bash
+   # Choose major/minor/patch as needed.
+   npm version -w packages/neovim/ patch
+   # Note: this copies the top-level README.md to packages/neovim.
+   npm run publish:neovim
+   export _VERSION=$(grep -o 'version": "[^"]\+' packages/neovim/package.json | sed 's/.*"//')
+   git tag "v${_VERSION}"
+   git push --follow-tags
+   ```
+3. Post-release tasks:
+   ```bash
+   cd packages/neovim/
+   npm version -w packages/neovim/ --no-git-tag-version prerelease --preid dev
+   git add package*.json && git commit -m bump
+   git push
+   ```
 
 ### Regenerate documentation website
 

packages/neovim/package.json

@@ -1,7 +1,7 @@
 {
   "name": "neovim",
   "description": "Nvim msgpack API client and remote plugin provider",
-  "version": "4.11.1-dev.0",
+  "version": "5.0.1-dev.0",
   "homepage": "https://github.com/neovim/node-client",
   "authors": [
     {

packages/neovim/src/index.ts

@@ -3,8 +3,4 @@ export { Neovim, NeovimClient, Buffer, Tabpage, Window } from './api/index';
 export { Plugin, Function, Autocmd, Command } from './plugin';
 export { NvimPlugin } from './host/NvimPlugin';
 export { loadPlugin } from './host/factory';
-export {
-  getNvimFromEnv,
-  GetNvimFromEnvOptions,
-  GetNvimFromEnvResult,
-} from './utils/getNvimFromEnv';
+export { findNvim, FindNvimOptions, FindNvimResult } from './utils/findNvim';

packages/neovim/src/utils/getNvimFromEnv.test.ts → packages/neovim/src/utils/findNvim.test.ts

@@ -1,11 +1,7 @@
 /* eslint-env jest */
 // eslint-disable-next-line import/no-extraneous-dependencies
 import which from 'which';
-import {
-  getNvimFromEnv,
-  exportsForTesting,
-  GetNvimFromEnvResult,
-} from './getNvimFromEnv';
+import { findNvim, exportsForTesting, FindNvimResult } from './findNvim';
 
 const parseVersion = exportsForTesting.parseVersion;
 const compareVersions = exportsForTesting.compareVersions;
@@ -19,7 +15,7 @@ try {
   );
 }
 
-describe('getNvimFromEnv', () => {
+describe('findNvim', () => {
   it('parseVersion()', () => {
     expect(parseVersion('0.5.0-dev+1357-g192f89ea1')).toEqual([
       0,
@@ -76,7 +72,7 @@ describe('getNvimFromEnv', () => {
   });
 
   /** Asserts that >=1 nvim binaries were found. */
-  function assertOneOrMore(nvimRes: Readonly<GetNvimFromEnvResult>) {
+  function assertOneOrMore(nvimRes: Readonly<FindNvimResult>) {
     expect(nvimRes).toEqual({
       matches: expect.any(Array),
       invalid: expect.any(Array),
@@ -93,17 +89,17 @@ describe('getNvimFromEnv', () => {
   }
 
   it('gets Nvim satisfying given min version', () => {
-    const nvimRes = getNvimFromEnv({ minVersion: '0.3.0', orderBy: 'desc' });
+    const nvimRes = findNvim({ minVersion: '0.3.0', orderBy: 'desc' });
     assertOneOrMore(nvimRes);
   });
 
   it('gets Nvim without specified min version', () => {
-    const nvimRes = getNvimFromEnv();
+    const nvimRes = findNvim();
     assertOneOrMore(nvimRes);
   });
 
   it('collects invalid matches separately', () => {
-    const nvimRes = getNvimFromEnv({ minVersion: '9999.0.0' });
+    const nvimRes = findNvim({ minVersion: '9999.0.0' });
     expect(nvimRes).toEqual({
       matches: [],
       invalid: expect.any(Array),

packages/neovim/src/utils/getNvimFromEnv.ts → packages/neovim/src/utils/findNvim.ts

@@ -15,7 +15,7 @@ export type NvimVersion = {
   readonly error?: Readonly<Error>;
 };
 
-export type GetNvimFromEnvOptions = {
+export type FindNvimOptions = {
   /**
    * (Optional) Minimum `nvim` version (inclusive) to search for.
    *
@@ -25,15 +25,15 @@ export type GetNvimFromEnvOptions = {
   /**
    * (Optional) Sort order of list of `nvim` versions.
    *
-   * - "desc" - Sort by version in descending order (highest to lowest).
+   * - "desc" - (Default) Sort by version in descending order (highest to lowest).
    *   - Example: `['0.5.0', '0.4.4', '0.4.3']`
-   * - "none" - (Default) Order is that of the searched `$PATH` components.
+   * - "none" - Order is that of the searched `$PATH` components.
    *   - Example: `['0.4.4', '0.5.0', '0.4.3']`
    */
   readonly orderBy?: 'desc' | 'none';
 };
 
-export type GetNvimFromEnvResult = {
+export type FindNvimResult = {
   /**
    * List of satisfying `nvim` versions found (if any) on the current system, sorted in the order
    * specified by `orderBy`.
@@ -115,10 +115,11 @@ function compareVersions(a: string, b: string): number {
 
 /**
  * Tries to find a usable `nvim` binary on the current system.
+ *
+ * @param opt.minVersion See {@link FindNvimOptions.minVersion}
+ * @param opt.orderBy See {@link FindNvimOptions.orderBy}
  */
-export function getNvimFromEnv(
-  opt: GetNvimFromEnvOptions = {}
-): Readonly<GetNvimFromEnvResult> {
+export function findNvim(opt: FindNvimOptions = {}): Readonly<FindNvimResult> {
   const paths = process.env.PATH.split(delimiter);
   const pathLength = paths.length;
   const matches = new Array<NvimVersion>();
@@ -163,7 +164,7 @@ export function getNvimFromEnv(
     }
   }
 
-  if (opt.orderBy === 'desc') {
+  if (opt.orderBy === undefined || opt.orderBy === 'desc') {
     matches.sort((a, b) => compareVersions(b.nvimVersion, a.nvimVersion));
   }