node-fzf: Fuzzy CLI List Selector

Common errors

• SyntaxError: Named export 'nfzf' not found. The requested module 'node-fzf' is a CommonJS module, which may not support all module.exports as named exports.

  cause Attempting to `import { nfzf } from 'node-fzf'` or `import nfzf from 'node-fzf'` in an ES Module context.
  fix Change the import statement to `const nfzf = require('node-fzf');`

• Output is garbled or disappears unexpectedly during interaction.

  cause Concurrent `stdout` writes from other parts of the application or external processes interfere with `node-fzf`'s terminal rendering.
  fix Ensure `node-fzf` has exclusive control over the terminal's `stdout` and `stdin` during its operation. Avoid `console.log` calls or other terminal output from your application while `nfzf` is running. Consider piping `node-fzf` output if mixing with other CLI tools.

• TypeError: opts.update is not a function

  cause The `update` method is attached to the *list object itself* when using the array-based API (e.g., `nfzf(list, callback)`), or to the `opts.list` array when `opts` is passed to `nfzf`. It's not a global method on `nfzf` or implicitly available on a new array.
  fix Ensure you are calling `update()` on the *original list reference* that was passed to `nfzf`. For the object-based API, `opts.list.update(newList)` or if `api = nfzf(list, cb)`, then `api.update(newList)`.

• No match found for query: '...' (or selected is null)

  cause The user did not select any item from the list, either by pressing `Escape` or by typing a query that yielded no matches.
  fix Always check if `result.selected` is `null` or `undefined` after `nfzf` resolves. Provide appropriate user feedback or handle the `no selection` case gracefully in your application logic, as shown in the quickstart.

Warnings

• gotcha node-fzf directly interacts with and manipulates `stdout` and `stdin` to provide its interactive CLI. This can lead to messy or corrupted output if your application is concurrently writing to `stdout` or reading from `stdin` while `node-fzf` is active.
  Fix: Ensure all `stdout` writes and `stdin` reads are paused or buffered while `node-fzf` is running. Execute `node-fzf` in a separate child process or pipe its output carefully if integrating with other CLI tools.
• gotcha The package officially states 'windows - unable to test automatically', indicating potential instability or untested behavior on Windows operating systems. Users might encounter platform-specific issues or unexpected rendering problems.
  Fix: Thoroughly test `node-fzf` functionality in your specific Windows environment. Report any issues to the GitHub repository. Consider using Windows Subsystem for Linux (WSL) for a more robust experience.
• gotcha As of version 0.14.0, `node-fzf` is distributed as a CommonJS module. Attempting to use ES Module `import` syntax (`import nfzf from 'node-fzf'`) in an ES Module context without proper transpilation or Node.js loader configuration will result in a runtime error.
  Fix: Always use `const nfzf = require('node-fzf')` for importing `node-fzf` in your Node.js projects, or ensure your build setup correctly handles CommonJS module interoperability if you are in an ESM project.
• deprecated The callback-based API for `node-fzf` is less idiomatic in modern Node.js asynchronous programming. While still functional, the promise-based API is generally preferred for better error handling and readability.
  Fix: Migrate from `nfzf(list, callback)` to `await nfzf(opts)` using the promise-based API for new development and refactoring, leveraging `async/await`.

Install

• npm install node-fzf npm
• yarn add node-fzf yarn
• pnpm add node-fzf pnpm

Imports

• nfzf
  wrong:

  import nfzf from 'node-fzf'

  correct:

  const nfzf = require('node-fzf')

  As of v0.14.0, node-fzf is a CommonJS module and does not natively support ES Module `import` syntax. Attempting to use `import` will result in a runtime error in Node.js environments unless transpiled.
• nfzf.getInput
  wrong:

  import { getInput } from 'node-fzf'

  correct:

  const { getInput } = require('node-fzf'); // or nfzf.getInput

  The `getInput` method is a property of the main `nfzf` export. It should be accessed directly from the `require`'d object or destructured after requiring the package. It does not exist as a separate named export in CommonJS.

Quickstart

This quickstart demonstrates the promise-based API of `node-fzf` to present an interactive fuzzy selection list to the user, allowing them to pick an item from a predefined array. It showcases basic configuration, result handling, and interactive features.

const nfzf = require('node-fzf');

const opts = {
  list: ['apple', 'banana', 'orange', 'grape', 'strawberry', 'blueberry', 'raspberry', 'pineapple', 'mango', 'kiwi'],
  mode: 'fuzzy',
  query: '',
  selectOne: false,
  height: 50, // Use 50% of the screen height
  prelinehook: function (index) { return `[${index + 1}] `; },
  postlinehook: function (index) { return ` (${this.list[index].length} chars)`; }
};

(async function () {
  console.log('Starting fuzzy search. Use Ctrl-S to switch modes, Up/Down to navigate.');
  const result = await nfzf(opts);

  const { selected, query } = result;

  if (!selected) {
    console.log(`No match found for query: '${query}'`);
  } else {
    console.log(`\nSelected item: '${selected.value}' at index ${selected.index}`);
    console.log(`Original list item: '${opts.list[selected.index]}'`);
  }
  process.exit(0); // Ensure the process exits after selection
})();