Fuzzy String Scoring Utility

0.1.2 · abandoned · verified Sun Apr 19

Command-score is a JavaScript utility designed for fuzzy string matching, providing a numerical 'matchiness' score between 0 and 1 for a given query and target string. It was developed for use in autocompletion contexts within the Superhuman email client, where the set of potential results is relatively bounded. The library's scoring algorithm prioritizes various factors, including exact matches, case sensitivity, prefix matches, and penalties for word or character jumps and transpositions within the query. Scores are primarily comparable when the query remains constant across different target strings, allowing for a secondary sort on top of matchiness. The latest version, 0.1.2, was published in June 2016, and the project has seen no significant code updates since, indicating it is no longer actively maintained. As such, it does not support modern JavaScript module systems (ESM) natively.

Common errors

```
SyntaxError: Named export 'commandScore' not found. The requested module 'command-score' is a CommonJS module, which may not support all module.exports as named exports.
```
cause Attempting to use ES module named import syntax (`import { commandScore } from 'command-score';`) for a CommonJS-only package that exports a single function as `module.exports = function(...)`.

fix Use the CommonJS `require` syntax: `const commandScore = require('command-score');`.
```
TypeError: commandScore is not a function
```
cause This error often occurs when attempting to `import commandScore from 'command-score';` in an environment that tries to treat the CommonJS default export as an ESM default import, but the transpilation/interop fails, or when `require` is used in a way that doesn't capture the default function correctly.

fix Ensure you are using `const commandScore = require('command-score');` in CommonJS files. If in an ESM file, a bundler or Node.js's CJS-ESM interop might eventually resolve `import commandScore from 'command-score';` by wrapping the CJS export, but the officially supported method remains `require` for this package.

Warnings

breaking The `command-score` package is CommonJS-only and was last updated in 2016. It does not provide native ECMAScript Module (ESM) exports.
Fix: Ensure your project is configured to handle CommonJS modules (e.g., using `require()` in Node.js or a bundler like Webpack/Rollup that can transpile CJS to ESM). Avoid direct `import` statements in pure ESM contexts.
gotcha The project is considered abandoned, with no updates in nearly a decade. It may not receive bug fixes, security patches, or feature enhancements.
Fix: While still functional for its intended purpose, consider evaluating actively maintained alternatives like `Fuse.js`, `fzy`, or `fuzzaldrin` for new projects or if long-term support is critical.
gotcha Scores generated by `command-score` are primarily designed to be comparable when the `query` string is kept constant and matched against different target strings. Comparing scores for different queries or interpreting absolute score values across diverse scenarios may not yield meaningful results.
Fix: Always use the same query when sorting a list of items based on their `command-score`. Use secondary sorting criteria (like `localeCompare` for item names) to handle ties effectively, as many items can have the same match score.

Install

npm install command-score npm
yarn add command-score yarn
pnpm add command-score pnpm

Imports

commandScore
wrong:
```
import commandScore from 'command-score';
```
correct:
```
const commandScore = require('command-score');
```
This package is CommonJS-only and has not been updated since 2016. Direct ESM imports will not work without a build step that handles CommonJS interop.
commandScore
wrong:
```
import { commandScore } from 'command-score';
```
correct:
```
const commandScore = require('command-score');
```
The package exports a single default function, not named exports. Attempting a named import will result in an undefined value or an error in a pure ESM environment.

Quickstart

This example demonstrates how to import `command-score`, use it to calculate fuzzy match scores for a list of items against a query, filter out non-matching results, and then sort them by score (and alphabetically for ties).

const commandScore = require('command-score');

function getMatches(query) {
  const items = ["red", "green", "gold", "blue", "reindeer", "great-green-macaw", "goldenrod"];
  const results = [];

  items.forEach(function (item) {
    const score = commandScore(item, query);
    if (score > 0) {
      results.push({ score: score, item: item });
    }
  });

  return results.sort(function (a, b) {
    if (a.score === b.score) {
      return a.item.localeCompare(b.item);
    }
    return b.score - a.score;
  }).map(function (suggestion) {
    return suggestion.item;
  });
}

console.log(getMatches('re')); // Expected: ['red', 'reindeer', 'great-green-macaw']
console.log(getMatches('go')); // Expected: ['gold', 'goldenrod']
console.log(getMatches('bl')); // Expected: ['blue']

view raw JSON →