Merge pull request #14 from pulsar-edit/rewrite-in-napi

Rewrite in N-API

Author: savetheclocktower

.github/workflows/tests.yml

@@ -6,7 +6,7 @@ on:
 
 jobs:
   test:
-    name: Run tests ('${{ matrix.node_version }}')
+    name: Run tests (${{ matrix.node_version }})
     if: |
       !startsWith(github.event.pull_request.title, '[skip-ci]') &&
       !startsWith(github.event.pull_request.title, '[skip-package-ci]')

.gitignore

@@ -2,6 +2,7 @@
 logs
 *.log
 npm-debug.log*
+.tool-versions
 
 # Runtime data
 pids

README.md

@@ -8,54 +8,7 @@ The scoring algorithm is heavily tuned for file paths, but should work for gener
 
 ## API
 
-```ts
-export type MatcherOptions = {
-  // Default: false
-  caseSensitive?: boolean,
-
-  // Default: infinite
-  maxResults?: number,
-
-  // Maximum gap to allow between consecutive letters in a match.
-  // Provide a smaller maxGap to speed up query results.
-  // Default: unlimited
-  maxGap?: number;
-
-  // Default: 1
-  numThreads?: number,
-
-  // Default: false
-  recordMatchIndexes?: boolean,
-
-  // can be either "fuzzaldrin" or anything else to use the file-based option
-  algorithm?: string
-}
-
-export type MatchResult = {
-  id: number,
-  value: string,
-
-  // A number in the range (0-1]. Higher scores are more relevant.
-  // 0 denotes "no match" and will never be returned.
-  score: number,
-
-  // Matching character index in `value` for each character in `query`.
-  // This can be costly, so this is only returned if `recordMatchIndexes` was set in `options`.
-  matchIndexes?: Array<number>,
-}
-
-export class Matcher {
-  constructor(candidates: Array<string>) {}
-
-  // Returns all matching candidates (subject to `options`).
-  // Will be ordered by score, descending.
-  match: (query: string, options?: MatcherOptions) => Array<MatchResult>;
-
-  addCandidates: (ids: Array<number>, candidates: Array<string>) => void;
-  removeCandidates: (ids: Array<number>) => void;
-  setCandidates: (ids: Array<number>, candidates: Array<string>) => void;
-}
-```
+Read `lib/main.d.ts` for the API of the `Matcher` class.
 
 See also the [spec](spec/fuzzy-native-spec.js) for basic usage.
 

binding.gyp

@@ -2,7 +2,10 @@
   'targets': [
     {
       'target_name': 'fuzzy-native',
-      'include_dirs': [ '<!(node -e "require(\'nan\')")' ],
+      'include_dirs': [
+        '<!@(node -p "require(\'node-addon-api\').include")'
+      ],
+      'defines': ['NAPI_DISABLE_CPP_EXCEPTIONS'],
       'cflags': [
         '-std=c++20',
         '-O3',
@@ -16,7 +19,7 @@
         'MACOSX_DEPLOYMENT_TARGET': '10.7',
       },
       'sources': [
-        'src/binding.cpp',
+        'src/fuzzy-native.cpp',
         'src/fuzzaldrin_score.cpp',
         'src/score_match.cpp',
         'src/MatcherBase.cpp',

lib/main.d.ts

@@ -0,0 +1,119 @@
+
+/**
+ * The options that can be passed to {@link Matcher#match}.
+ */
+export type MatcherOptions = {
+  /** Whether matching is case-sensitive. Defaults to `false`. */
+  caseSensitive?: boolean;
+
+  /** How many results to return at the maximum. Defaults to no limit. */
+  maxResults?: number;
+
+  /**
+   * Maximum “gap” to allow between consecutive letters for a match candiate.
+   * Provide a smaller value to speed up query results. Defaults to no limit.
+   */
+  maxGap?: number;
+
+  /**
+   * How many threads to use while searching. Defaults to `1`.
+   */
+  numThreads?: number;
+
+  /**
+   * Whether to return metadata about the indices of the characters that
+   * matched in each returned max. Defaults to `false`.
+   */
+  recordMatchIndexes?: boolean;
+
+  /**
+   * The algorithm to use for fuzzy-matching. If `"fuzzaldrin"`, will use that
+   * algorithm for legacy support. Any other value, including the default of
+   * `undefined`, will trigger use of the default algorithm.
+   */
+  algorithm?: 'fuzzaldrin' | undefined;
+};
+
+/**
+ * A single result returned by {@link Matcher#match}.
+ */
+export type MatchResult = {
+  /** A unique identifier for the match. */
+  id: number;
+
+  /** The string value of the match. */
+  value: string;
+
+  /**
+   * A number in the range (0, 1] — i.e., the maximum value is `1` and the
+   * minimum value is the smallest possible positive value. Higher scores mean
+   * more relevant matches. `0` means “no match” and will never be returned.
+   */
+  score: number;
+
+  /**
+   * Matching charcter index in `value` for each character in `query`. This can
+   * be costly, so this information is returned only when
+   * {@link MatcherOptions.recordMatchIndexes} is `true`.
+   */
+  matchIndexes?: number[];
+}
+
+export class Matcher {
+  /**
+   * Construct a new {@link Matcher} object.
+   *
+   * You may specify candidates at instantiation time (with the same arguments
+   * used by {@link addCandidates} and {@link setCandidates}) or you may wait
+   * and add candidates later.
+   *
+   * @param ids A list of numeric IDs. Must correspond to the candidates
+   *  themselves.
+   * @param candidates A list of candidates against which we will be matching.
+   */
+  constructor();
+  constructor(ids: number[], candidates: string[]);
+
+  /**
+   * Find all candidates that match the given query.
+   *
+   * @param query The input against which candidates will be searched.
+   * @param options Any {@link MatcherOptions}.
+   */
+  match(query: string, options?: MatcherOptions): MatchResult[];
+
+  /**
+   * Add candidates to the list.
+   *
+   * You are responsible for ensuring that the IDs you use do not match the IDs
+   * of any candidates that are already present in the `Matcher`. Any
+   * candidates whose IDs already exist in the `Matcher` are silently ignored.
+   *
+   * @param ids A list of numeric IDs. Must correspond to the candidates
+   *  themselves.
+   * @param candidates A list of candidates against which we will be matching.
+   */
+  addCandidates(ids: number[], candidates: string[]): void;
+
+  /**
+   * Remove candidates from the list.
+   *
+   * @param ids The unique identifiers for each of the candidates you want to
+   *  remove. Must be an array; if you want to remove only one candidate, wrap
+   *  the value in an array first.
+   */
+  removeCandidates(ids: number[]): void;
+
+  /**
+   * Set a complete list of candidates, removing any candidate that may already
+   * be defined.
+   *
+   * If you want to add candidates instead without removing any that may
+   * already exist, use {@link addCandidates}.
+   *
+   * @param ids A list of numeric IDs. Must correspond to the candidates
+   *  themselves.
+   * @param candidates A list of candidates against which we will be matching.
+   */
+  setCandidates(ids: number[], candidates: string[]): void;
+}

package-lock.json

@@ -3,6 +3,7 @@
   "version": "1.3.2",
   "description": "Native C++ implementation of a fuzzy string matcher.",
   "main": "lib/main.js",
+  "types": "lib/main.d.ts",
   "scripts": {
     "test": "jasmine-node --captureExceptions spec"
   },
@@ -21,7 +22,7 @@
   "repository": "https://github.com/pulsar-edit/fuzzy-native",
   "license": "MIT",
   "dependencies": {
-    "nan": "^2.18.0"
+    "node-addon-api": "^8.8.0"
   },
   "devDependencies": {
     "jasmine-node": "^1.14.5",

package.json

@@ -8,12 +8,14 @@ function values(results) {
   });
 }
 
+/** @returns {[number[], string[]]} */
 function genIds(values) {
   return [Array.from({length: values.length}, (_, i) => i), values];
 }
 
 describe('fuzzy-native', function() {
-  var matcher;
+  /** @type {import('../lib/main').Matcher} */
+  let matcher;
   beforeEach(function() {
     const paths = [
       '',
@@ -108,8 +110,12 @@ describe('fuzzy-native', function() {
 
   it('can match empty strings for alternate scoring', function() {
     matcher.setCandidates([1, 2, 3], ["hello", "is", "it"]);
+    // An empty query scores every candidate as 1, and 'is'/'it' are also
+    // tied on length, so only 'hello' is guaranteed to sort last.
     let results = matcher.match('', {algorithm: 'fuzzaldrin'});
-    expect(values(results)).toEqual([ 'is', 'it', 'hello' ]);
+    const emptyQueryResults = values(results);
+    expect(emptyQueryResults.slice(0, 2).sort()).toEqual(['is', 'it']);
+    expect(emptyQueryResults[2]).toEqual('hello');
 
     results = matcher.match('it', {algorithm: 'fuzzaldrin'});
     expect(values(results)).toEqual([ 'it' ]);
@@ -332,13 +338,15 @@ describe('fuzzy-native', function() {
       ['/path1/path2/path3/zzz', '/path1/path2/path3/zzz_ooo', '/path1/path2/path3/zzz/ooo']
     );
 
-    expect(
-      values(matcher.match('path1/path2/path3/zzz', {caseSensitive: true}))
-    ).toEqual([
-      '/path1/path2/path3/zzz',
+    // The exact match should rank first; the other two candidates are an
+    // exact score tie for this query (same matched prefix, same length),
+    // so their relative order isn't guaranteed.
+    const exactMatches = values(matcher.match('path1/path2/path3/zzz', {caseSensitive: true}));
+    expect(exactMatches[0]).toEqual('/path1/path2/path3/zzz');
+    expect(exactMatches.slice(1).sort()).toEqual([
       '/path1/path2/path3/zzz/ooo',
       '/path1/path2/path3/zzz_ooo'
-    ]);
+    ].sort());
     expect(
       values(matcher.match('zzz_ooo', {caseSensitive: true}))
     ).toEqual([