@sakiori/fff-node 0.11.1-sakiori.20261109.1 → 1.0.0

package/README.md

@@ -1,10 +1,32 @@
-# fff - Fast File Finder
-
-High-performance fuzzy file finder for Node.js, powered by Rust. Extremely fast live file, content, and directory search with a typo-resistant algorithm. As well as regex, plain-text, multi-occurrence and typo-resistant content search.
-
-Comes with built-in git status support, frecency ranking, content indexing and many more! Designed for LLM agent tools that search through codebases or agentic RAG document search.
-
-This is the Node package of the fork of fff at <https://gitlab.com/sakiori-oss/fff>. Its indexes live in the shared fff service of the current OS user, which `fff-mcp` agents of the same release use too, so a directory that an application and its agents search is indexed once.
+# @sakiori/fff-node
+
+Fast, typo-resistant file, directory and content search for Node.js, from the
+[sakiori-oss fork of fff](https://gitlab.com/sakiori-oss/fff). The search itself is upstream
+fff's: fuzzy path matching, globs, plain-text, regex and multi-pattern grep, git status and
+frecency ranking.
+
+The difference is where the index lives. Upstream's `@ff-labs/fff-node` keeps it in your
+process. This package keeps it in the shared fff service of the current OS user, which the
+`fff-mcp` agents of the same fork release use too, so an application and its agents index a
+directory once.
+
+Compared with `@ff-labs/fff-node`, this package:
+
+- returns a Promise from `FileFinder.create` and from every instance method except
+  `getBasePath`, `isDestroyed` and the methods listed as unavailable below, and runs each
+  call off the event loop; upstream's `destroy`, `isScanning`, searches and greps are
+  synchronous. Results keep upstream's `Result` shape;
+- fails a call after a bound when the service does not answer (`timeoutMs` in
+  `FileFinder.create`, see [Timeouts](#timeouts));
+- adds `notifyChanged` for files your program changes, `excludeFrecency` for rankings
+  without the shared frecency, `serviceDir` for a separate service namespace, and repository
+  and ref events in `watch`;
+- shares a service only with the `fff-mcp` of the same fork release, which has the
+  package's version;
+- has no `waitForScanBlocking`; `trackQuery`, `getHistoricalQuery` and `refreshGitStatus`
+  return an error, `reindex` rescans only the instance's own directory, `historyDbPath` is
+  not supported, and `cacheBudgetMaxBytes` and `cacheBudgetMaxFileSize` are ignored
+  ([Unavailable methods](#unavailable-methods)).
 
 ## Installation
 
@@ -25,10 +47,16 @@ The native library and the `fff-mcp` service executable come in platform package
 
 The package installs on macOS, Linux and FreeBSD, on x64 and ARM64; npm and pnpm refuse it on any other platform (`EBADPLATFORM`). FreeBSD has no platform package: build the native files from source (see [Platforms without a prebuilt package](#platforms-without-a-prebuilt-package)), or `FileFinder.create` fails with `unsupportedPlatform`. An install that omits optional dependencies has no native files, and `FileFinder.create` fails with `libraryUnavailable`. The glibc packages need glibc 2.28 or later.
 
-A project that imports the upstream name `@ff-labs/fff-node` keeps its imports with a package-manager alias: `npm install @ff-labs/fff-node@npm:@sakiori/fff-node@<version>`.
+A project that imports the upstream name `@ff-labs/fff-node` can keep its imports with a package-manager alias, `npm install @ff-labs/fff-node@npm:@sakiori/fff-node@^1.0.0`, but its calls still need the changes listed at the top.
 
 Requires Node.js 20.19 or later in the 20 line, or 22.12 and later. The package is an ES module; CommonJS `require` loads the same module, which relies on `require` of ES modules in those Node.js versions. In Electron, that takes a release whose bundled Node.js is one of them.
 
+### Versions
+
+The package is published at the version of the fork release that builds it, a semantic version of the fork's own: a breaking change of the package's API or its `exports` raises the major version, an addition the minor, and a fix the patch. A change of the platforms or Node.js versions it supports raises at least the minor version, and the maintainers mark one that drops support as breaking; a release that changes only the native code is a new version too. Depend on a range of one major, such as the `^1.0.0` that `npm install` writes, to take every later release of it. The platform packages come at exactly the Node package's version. The package shares its service with the `fff-mcp` archives of the same version; the release's notes name the upstream fff release it carries.
+
+Versions before 1.0.0, `0.11.1-sakiori.<date>.<n>`, were prereleases, which a range does not follow past their own `major.minor.patch`; replace an exact pin of one with `^1.0.0`.
+
 ### Electron
 
 Unpack the platform package's whole directory from the application archive (for example with electron-builder's `asarUnpack`). The package then loads the library and starts the service from `app.asar.unpacked`, and reports an error when only one of the two files is unpacked.
@@ -147,7 +175,7 @@ A service that does not answer makes `FileFinder.create` fail after 90 seconds a
 
 ## Unavailable methods
 
-`trackQuery`, `getHistoricalQuery` and `refreshGitStatus` have no shared service equivalent and return an error naming them as unavailable over the shared service; the service keeps the index and git status current itself. `reindex` rescans the instance's own directory; create a new instance for another directory. `historyDbPath` is not supported.
+`waitForScanBlocking` does not exist; await `waitForScan` or `waitForIndexReady`. `trackQuery`, `getHistoricalQuery` and `refreshGitStatus` have no shared service equivalent and return an error naming them as unavailable over the shared service; the service keeps the index and git status current itself. `reindex` rescans the instance's own directory; create a new instance for another directory. `historyDbPath` is not supported.
 
 ## API Reference
 

package/dist/index.d.ts

@@ -43,7 +43,7 @@
  */
 export { binaryExists, findBinary, findNativeFiles, findServiceExecutable, type NativeFiles, unpackedAsarPath, } from "./binary.js";
 export { closeLibrary, nativeInstanceCount } from "./ffi.js";
-export type { DbHealth, DirItem, DirSearchOptions, DirSearchResult, FileItem, GrepCursor, GrepMatch, GrepMode, DefinitionMode, GrepOptions, GrepResult, HealthCheck, InitOptions, Location, MixedItem, MixedSearchResult, MultiGrepOptions, ScanProgress, Score, SearchOptions, SearchResult, WatchBatchCallback, WatchEvent, WatchEventKind, WatchOptions, WatchUnsubscribe, } from "./fff-api.js";
+export type { DbHealth, DirItem, DirSearchOptions, DirSearchResult, FileItem, GlobOptions, GrepCursor, GrepMatch, GrepMode, DefinitionMode, GrepOptions, GrepResult, HealthCheck, InitOptions, Location, MixedItem, MixedSearchResult, MultiGrepOptions, ScanProgress, Score, SearchOptions, SearchResult, WatchBatchCallback, WatchEvent, WatchEventKind, WatchOptions, WatchUnsubscribe, } from "./fff-api.js";
 export { ErrorCode, type Failure, type Result, err, ok } from "./errors.js";
 export { FileFinder } from "./finder.js";
 export { getLibExtension, getLibFilename, getNpmPackageName, getServiceExecutableFilename, getTriple, } from "./platform.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EACL,YAAY,EACZ,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,KAAK,WAAW,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC7D,YAAY,EACV,QAAQ,EACR,OAAO,EACP,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,UAAU,EACV,SAAS,EACT,QAAQ,EACR,cAAc,EACd,WAAW,EACX,UAAU,EACV,WAAW,EACX,WAAW,EACX,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,KAAK,EACL,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,SAAS,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,4BAA4B,EAC5B,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EACL,YAAY,EACZ,UAAU,EACV,eAAe,EACf,qBAAqB,EACrB,KAAK,WAAW,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC7D,YAAY,EACV,QAAQ,EACR,OAAO,EACP,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,WAAW,EACX,UAAU,EACV,SAAS,EACT,QAAQ,EACR,cAAc,EACd,WAAW,EACX,UAAU,EACV,WAAW,EACX,WAAW,EACX,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,KAAK,EACL,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,SAAS,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,4BAA4B,EAC5B,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sakiori/fff-node",
-  "version": "0.11.1-sakiori.20261109.1",
+  "version": "1.0.0",
   "private": false,
   "description": "Fuzzy file finder for Node.js over the shared fff service - perfect for LLM agent tools",
   "type": "module",
@@ -22,6 +22,8 @@
     "build": "npm run build:bundle && npm run build:types",
     "build:bundle": "tsup src/index.ts src/watch-delivery.ts --format esm --platform node --target node20 --external ffi-rs --sourcemap",
     "build:types": "tsc -p tsconfig.build.json",
+    "api:update": "npm run build:types && api-extractor run --local",
+    "api:check": "npm run build:types && api-extractor run",
     "test": "node --test --test-concurrency=1 test/e2e.mjs test/service.mjs",
     "typecheck": "tsc --noEmit"
   },
@@ -65,16 +67,17 @@
     "ffi-rs": "^1.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.0.0",
+    "@microsoft/api-extractor": "7.60.1",
     "@types/node": "^22.0.0",
-    "tsup": "^8.5.0"
+    "tsup": "^8.5.0",
+    "typescript": "5.9.3"
   },
   "optionalDependencies": {
-    "@sakiori/fff-bin-darwin-arm64": "0.11.1-sakiori.20261109.1",
-    "@sakiori/fff-bin-darwin-x64": "0.11.1-sakiori.20261109.1",
-    "@sakiori/fff-bin-linux-arm64-gnu": "0.11.1-sakiori.20261109.1",
-    "@sakiori/fff-bin-linux-arm64-musl": "0.11.1-sakiori.20261109.1",
-    "@sakiori/fff-bin-linux-x64-gnu": "0.11.1-sakiori.20261109.1",
-    "@sakiori/fff-bin-linux-x64-musl": "0.11.1-sakiori.20261109.1"
+    "@sakiori/fff-bin-darwin-arm64": "1.0.0",
+    "@sakiori/fff-bin-darwin-x64": "1.0.0",
+    "@sakiori/fff-bin-linux-arm64-gnu": "1.0.0",
+    "@sakiori/fff-bin-linux-arm64-musl": "1.0.0",
+    "@sakiori/fff-bin-linux-x64-gnu": "1.0.0",
+    "@sakiori/fff-bin-linux-x64-musl": "1.0.0"
   }
 }