@ff-labs/fff-bun 0.8.5-nightly.ccb1b9d → 0.9.0

package/README.md

@@ -1,257 +1,102 @@
 # fff - Fast File Finder
 
-High-performance fuzzy file finder for Bun, powered by Rust. Perfect for LLM agent tools that need to search through codebases.
+High-performance fuzzy file finder for Bun, 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.
 
-## Features
+Comes with built-in git status support, frecency access tracking, and a real-time file watcher, content indexing and many more! Designed for LLM agent tools that search through codebases or agentic RAG document search.
 
-- **Blazing fast** - Rust-powered fuzzy search with parallel processing
-- **Smart ranking** - Frecency-based scoring (frequency + recency)
-- **Git-aware** - Shows file git status in results
-- **Query history** - Learns from your search patterns
-- **Type-safe** - Full TypeScript support with Result types
+Faster than ripgrep & fzf on any workflow that runs more than once per process.
 
 ## Installation
 
 ```bash
-bun add @ff-labs/bun
+bun add @ff-labs/fff-bun
 ```
 
-The correct native binary for your platform is installed automatically via platform-specific packages (e.g. `@ff-labs/fff-bin-darwin-arm64`, `@ff-labs/fff-bin-linux-x64-gnu`). No GitHub downloads are needed.
+The correct native binary for your platform is installed automatically via platform-specific packages (e.g. `@ff-labs/fff-bin-darwin-arm64`, `@ff-labs/fff-bin-linux-x64-gnu`)
 
 ### Supported Platforms
 
-| Platform | Architecture | Package |
-|----------|-------------|---------|
-| macOS | ARM64 (Apple Silicon) | `@ff-labs/fff-bin-darwin-arm64` |
-| macOS | x64 (Intel) | `@ff-labs/fff-bin-darwin-x64` |
-| Linux | x64 (glibc) | `@ff-labs/fff-bin-linux-x64-gnu` |
-| Linux | ARM64 (glibc) | `@ff-labs/fff-bin-linux-arm64-gnu` |
-| Linux | x64 (musl) | `@ff-labs/fff-bin-linux-x64-musl` |
-| Linux | ARM64 (musl) | `@ff-labs/fff-bin-linux-arm64-musl` |
-| Windows | x64 | `@ff-labs/fff-bin-win32-x64` |
-| Windows | ARM64 | `@ff-labs/fff-bin-win32-arm64` |
+| Platform | Architecture          | Package                             |
+| -------- | --------------------- | ----------------------------------- |
+| macOS    | ARM64 (Apple Silicon) | `@ff-labs/fff-bin-darwin-arm64`     |
+| macOS    | x64 (Intel)           | `@ff-labs/fff-bin-darwin-x64`       |
+| Linux    | x64 (glibc)           | `@ff-labs/fff-bin-linux-x64-gnu`    |
+| Linux    | ARM64 (glibc)         | `@ff-labs/fff-bin-linux-arm64-gnu`  |
+| Linux    | x64 (musl)            | `@ff-labs/fff-bin-linux-x64-musl`   |
+| Linux    | ARM64 (musl)          | `@ff-labs/fff-bin-linux-arm64-musl` |
+| Windows  | x64                   | `@ff-labs/fff-bin-win32-x64`        |
+| Windows  | ARM64                 | `@ff-labs/fff-bin-win32-arm64`      |
 
 If the platform package isn't available, the postinstall script will attempt to download from GitHub releases as a fallback.
 
 ## Quick Start
 
-```typescript
-import { FileFinder } from "fff";
-
-// Initialize with a directory
-const result = FileFinder.init({ basePath: "/path/to/project" });
-if (!result.ok) {
-  console.error(result.error);
-  process.exit(1);
-}
-
-// Wait for initial scan
-FileFinder.waitForScan(5000);
-
-// Search for files
-const search = FileFinder.search("main.ts");
-if (search.ok) {
-  for (const item of search.value.items) {
-    console.log(item.relativePath);
-  }
-}
-
-// Cleanup when done
-FileFinder.destroy();
-```
-
-## API Reference
-
-### `FileFinder.init(options)`
-
-Initialize the file finder.
-
-```typescript
-interface InitOptions {
-  basePath: string;           // Directory to index (required)
-  frecencyDbPath?: string;    // Frecency DB path (omit to skip frecency)
-  historyDbPath?: string;     // History DB path (omit to skip query tracking)
-  useUnsafeNoLock?: boolean;  // Faster but less safe DB mode
-}
-
-const result = FileFinder.init({ basePath: "/my/project" });
-```
-
-### `FileFinder.search(query, options?)`
-
-Search for files.
-
-```typescript
-interface SearchOptions {
-  maxThreads?: number;          // Parallel threads (0 = auto)
-  currentFile?: string;         // Deprioritize this file
-  comboBoostMultiplier?: number; // Query history boost
-  minComboCount?: number;        // Min history matches
-  pageIndex?: number;            // Pagination offset
-  pageSize?: number;             // Results per page
-}
-
-const result = FileFinder.search("main.ts", { pageSize: 10 });
-if (result.ok) {
-  console.log(`Found ${result.value.totalMatched} files`);
-}
-```
-
-### Query Syntax
-
-- `foo bar` - Match files containing "foo" and "bar"
-- `src/` - Match files in src directory
-- `file.ts:42` - Match file.ts with line 42
-- `file.ts:42:10` - Match with line and column
-
-### `FileFinder.trackAccess(filePath)`
-
-Track file access for frecency scoring.
+Each `FileFinder` instance owns an independent native index. Create one, wait
+for the initial scan, then run as many searches as you like.
 
 ```typescript
-// Call when user opens a file
-FileFinder.trackAccess("/path/to/file.ts");
-```
+import { FileFinder } from "@ff-labs/fff-bun";
 
-### `FileFinder.grep(query, options?)`
+// Create an instance bound to a directory
+const created = FileFinder.create({ basePath: "/path/to/project" });
+if (!created.ok) throw new Error(created.error);
 
-Search file contents with SIMD-accelerated matching.
+const finder = created.value;
 
-```typescript
-interface GrepOptions {
-  maxFileSize?: number;        // Max file size in bytes (default: 10MB)
-  maxMatchesPerFile?: number;  // Max matches per file (default: 200, set 0 to unlimited) 
-  smartCase?: boolean;         // Case-insensitive if all lowercase (default: true)
-  fileOffset?: number;         // Pagination offset (default: 0)
-  pageLimit?: number;          // Max matches to return (default: 50)
-  mode?: "plain" | "regex" | "fuzzy"; // Search mode (default: "plain")
-  timeBudgetMs?: number;       // Time limit in ms, 0 = unlimited (default: 0)
-}
+// Wait for the initial scan (non-blocking)
+await finder.waitForScan(5000);
 
-// Plain text search
-const result = FileFinder.grep("TODO", { pageLimit: 20 });
-if (result.ok) {
-  for (const match of result.value.items) {
-    console.log(`${match.relativePath}:${match.lineNumber}: ${match.lineContent}`);
+// 1. Fuzzy file search (typo resistant)
+const files = finder.fileSearch("typescropt.ts", { pageSize: 10 });
+if (files.ok) {
+  for (const item of files.value.items) {
+    console.log(item.relativePath, item.gitStatus);
   }
 }
 
-// Regex search
-const regexResult = FileFinder.grep("fn\\s+\\w+", { mode: "regex" });
+// 2. Glob filter — no fuzzy matching, 100% compatible with npm `glob`
+const globbed = finder.glob("src/**/*.ts");
+if (globbed.ok) console.log(`${globbed.value.totalMatched} TypeScript files`);
 
-// Fuzzy search
-const fuzzyResult = FileFinder.grep("imprt recat", { mode: "fuzzy" });
-
-// Pagination
-const page1 = FileFinder.grep("error");
-if (page1.ok && page1.value.nextCursor) {
-  const page2 = FileFinder.grep("error", {
-    cursor: page1.value.nextCursor,
-  });
+// 3. Content search (live grep) with pagination
+const grep = finder.grep("TODO", { mode: "plain", pageSize: 20 });
+if (grep.ok) {
+  for (const m of grep.value.items) {
+    console.log(`${m.relativePath}:${m.lineNumber}: ${m.lineContent}`);
+  }
 }
 
-// With file constraints
-const tsOnly = FileFinder.grep("*.ts useState");
-const srcOnly = FileFinder.grep("src/ handleClick");
-```
-
-### `FileFinder.trackQuery(query, selectedFile)`
+// 4. Directory search based on the query (typo resistant)
+const dirs = finder.directorySearch("components");
+if (dirs.ok) console.log(dirs.value.items.map((d) => d.relativePath));
 
-Track query completion for smart suggestions.
-
-```typescript
-// Call when user selects a file from search
-FileFinder.trackQuery("main", "/path/to/main.ts");
+// Free the resources when you don't need a file picker anymore
+finder.destroy();
 ```
 
-### `FileFinder.healthCheck(testPath?)`
-
-Get diagnostic information.
-
-```typescript
-const health = FileFinder.healthCheck();
-if (health.ok) {
-  console.log(`Version: ${health.value.version}`);
-  console.log(`Indexed: ${health.value.filePicker.indexedFiles} files`);
-}
-```
 
-### Other Methods
+## API Reference
 
-- `FileFinder.grep(query, options?)` - Search file contents
-- `FileFinder.scanFiles()` - Trigger rescan
-- `FileFinder.isScanning()` - Check scan status
-- `FileFinder.getScanProgress()` - Get scan progress
-- `FileFinder.waitForScan(timeoutMs)` - Wait for scan
-- `FileFinder.reindex(newPath)` - Change indexed directory
-- `FileFinder.refreshGitStatus()` - Refresh git cache
-- `FileFinder.getHistoricalQuery(offset)` - Get past queries
-- `FileFinder.destroy()` - Cleanup resources
+Verify the latest API in the local interface at [`./src/fff-api.ts`](./src/fff-api.ts). Every field and type is documented.
 
-## Result Types
+### Result Types
 
 All methods return a `Result<T>` type for explicit error handling:
 
+
 ```typescript
-type Result<T> = 
-  | { ok: true; value: T }
-  | { ok: false; error: string };
+type Result<T> = { ok: true; value: T } | { ok: false; error: string };
+
+const result = finder.fileSearch("foo");
 
-const result = FileFinder.search("foo");
 if (result.ok) {
   // result.value is SearchResult
 } else {
-  // result.error is string
+  // result.error is string error message
 }
 ```
 
-## Search Result Types
-
-```typescript
-interface SearchResult {
-  items: FileItem[];
-  scores: Score[];
-  totalMatched: number;
-  totalFiles: number;
-  location?: Location;
-}
-
-interface FileItem {
-  path: string;
-  relativePath: string;
-  fileName: string;
-  size: number;
-  modified: number;
-  gitStatus: string; // 'clean', 'modified', 'untracked', etc.
-}
-```
-
-## Grep Result Types
-
-```typescript
-interface GrepResult {
-  items: GrepMatch[];
-  totalMatched: number;
-  totalFilesSearched: number;
-  totalFiles: number;
-  filteredFileCount: number;
-  nextCursor: GrepCursor | null; // Pass to options.cursor for next page
-  regexFallbackError?: string;   // Set if regex was invalid
-}
-
-interface GrepMatch {
-  path: string;
-  relativePath: string;
-  fileName: string;
-  gitStatus: string;
-  lineNumber: number;    // 1-based
-  col: number;           // 0-based byte column
-  byteOffset: number;    // Absolute byte offset in file
-  lineContent: string;   // The matched line text
-  matchRanges: [number, number][]; // Byte offsets for highlighting
-  fuzzyScore?: number;   // Only in fuzzy mode
-}
-```
+This SDK calls a native compiled library for your platform at runtime. This is generally safe — fff is battle-tested and stable, and written in a memory-safe language — but there is a class of errors that can't be caught at the Bun/Node level. If you hit one, please report an issue!
 
 ## Building from Source
 
@@ -268,7 +113,7 @@ cargo build --release -p fff-c
 # The binary will be at target/release/libfff_c.{so,dylib,dll}
 ```
 
-## CLI Tools
+## CLI examples
 
 ```bash
 # Download binary manually (fallback if npm package unavailable)

package/examples/glob-bench.ts

@@ -0,0 +1,159 @@
+#!/usr/bin/env bun
+/**
+ * Glob benchmark: fff.glob vs Bun.Glob vs npm `glob`.
+ *
+ * Each engine is asked to enumerate files in a directory matching the same
+ * pattern. We measure wall-clock time + result count. fff scans + indexes
+ * once on init; the subsequent glob call is a filter over the in-memory
+ * index — that's what we time.
+ *
+ * Usage:
+ *   bun examples/glob-bench.ts [dir] [pattern] [iterations]
+ *
+ *   dir         default: cwd
+ *   pattern     default: "**\/*.ts"
+ *   iterations  default: 5  (each engine runs N times, best+median reported)
+ *
+ * Install npm glob first:
+ *   bun add glob
+ */
+
+import { performance } from "node:perf_hooks";
+import { resolve } from "node:path";
+import { Glob as BunGlob } from "bun";
+import { FileFinder } from "../src/index";
+
+// npm glob — optional. Skip silently if not installed.
+let npmGlob:
+  | ((pattern: string, opts: { cwd: string }) => Promise<string[]>)
+  | null = null;
+try {
+  const mod: {
+    glob: (pattern: string, opts: { cwd: string }) => Promise<string[]>;
+  } =
+    // @ts-ignore - optional peer; resolved at runtime, may be absent
+    await import("glob");
+  npmGlob = mod.glob;
+} catch {
+  console.warn("npm `glob` not installed — skipping. Run: bun add glob");
+}
+
+const dir = resolve(process.argv[2] ?? process.cwd());
+const pattern = process.argv[3] ?? "**/lua/**/*.lua";
+const iterations = Number(process.argv[4] ?? 5);
+
+console.log(`dir:        ${dir}`);
+console.log(`pattern:    ${pattern}`);
+console.log(`iterations: ${iterations}\n`);
+
+interface Sample {
+  ms: number;
+  count: number;
+}
+
+function summarize(label: string, samples: Sample[]): void {
+  if (samples.length === 0) {
+    console.log(`${label.padEnd(16)} skipped`);
+    return;
+  }
+  const sorted = [...samples].sort((a, b) => a.ms - b.ms);
+  const best = sorted[0]!;
+  const median = sorted[Math.floor(sorted.length / 2)]!;
+  const worst = sorted[sorted.length - 1]!;
+  const counts = new Set(samples.map((s) => s.count));
+  const countStr =
+    counts.size === 1 ? `${best.count}` : `[${[...counts].join(", ")}]`;
+  console.log(
+    `${label.padEnd(16)} best=${best.ms.toFixed(2)}ms  median=${median.ms.toFixed(2)}ms  worst=${worst.ms.toFixed(2)}ms  count=${countStr}`,
+  );
+}
+
+async function bench<T>(
+  fn: () => Promise<T> | T,
+): Promise<{ ms: number; result: T }> {
+  const start = performance.now();
+  const result = await fn();
+  return { ms: performance.now() - start, result };
+}
+
+// ---------------------------------------------------------------------------
+// fff: init + warm scan, then time only the .glob() call. Init cost is
+// reported separately because it's amortized across many subsequent calls.
+// ---------------------------------------------------------------------------
+const fffInit = await bench(() => {
+  const result = FileFinder.create({
+    basePath: dir,
+    disableMmapCache: true,
+    disableContentIndexing: true,
+    disableWatch: true,
+  });
+  if (!result.ok) throw new Error(result.error);
+  return result.value;
+});
+const finder = fffInit.result;
+
+// Wait until initial scan done so the first .glob() doesn't see a partial
+// index. Returns true = completed, false = timed out.
+const scanReady = finder.waitForScanBlocking(30_000);
+if (!scanReady.ok || !scanReady.value) {
+  console.error("fff: initial scan did not finish in 30s — exiting");
+  process.exit(1);
+}
+console.log(`fff init+scan: ${fffInit.ms.toFixed(2)}ms\n`);
+
+const fffSamples: Sample[] = [];
+for (let i = 0; i < iterations; i++) {
+  const r = await bench(() => {
+    const out = finder.glob(pattern, { pageSize: 100 });
+    if (!out.ok) throw new Error(out.error);
+    return out.value;
+  });
+  fffSamples.push({ ms: r.ms, count: r.result.items.length });
+}
+
+// ---------------------------------------------------------------------------
+// Bun.Glob — sync iterator, returns relative paths.
+// ---------------------------------------------------------------------------
+const bunSamples: Sample[] = [];
+for (let i = 0; i < iterations; i++) {
+  const r = await bench(() => {
+    const g = new BunGlob(pattern);
+    let count = 0;
+    for (const _ of g.scanSync({ cwd: dir })) count++;
+    return count;
+  });
+  bunSamples.push({ ms: r.ms, count: r.result });
+}
+
+// ---------------------------------------------------------------------------
+// npm glob — async, returns absolute or relative paths depending on opts.
+// ---------------------------------------------------------------------------
+const npmSamples: Sample[] = [];
+if (npmGlob) {
+  for (let i = 0; i < iterations; i++) {
+    const r = await bench(() => npmGlob!(pattern, { cwd: dir }));
+    npmSamples.push({ ms: r.ms, count: r.result.length });
+  }
+}
+
+console.log("results:");
+summarize("fff.glob", fffSamples);
+summarize("Bun.Glob", bunSamples);
+summarize("npm glob", npmSamples);
+
+// Sanity: counts should be in the same ballpark. They won't match exactly
+// because indexing rules differ (fff respects gitignore + skips binaries by
+// default; Bun.Glob and npm glob do not).
+const counts = {
+  fff: fffSamples[0]?.count ?? 0,
+  bun: bunSamples[0]?.count ?? 0,
+  npm: npmSamples[0]?.count ?? 0,
+};
+console.log(
+  `\nNote: fff respects gitignore + skips binaries; Bun.Glob and npm glob walk the raw filesystem. Count differences are expected.`,
+);
+console.log(
+  `raw counts: fff=${counts.fff} bun=${counts.bun} npm=${counts.npm}`,
+);
+
+finder.destroy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ff-labs/fff-bun",
-  "version": "0.8.5-nightly.ccb1b9d",
+  "version": "0.9.0",
   "private": false,
   "description": "High-performance fuzzy file finder for Bun - perfect for LLM agent tools",
   "type": "module",
@@ -62,14 +62,14 @@
   },
   "homepage": "https://github.com/dmtrKovalenko/fff#readme",
   "optionalDependencies": {
-    "@ff-labs/fff-bin-darwin-arm64": "0.8.5-nightly.ccb1b9d",
-    "@ff-labs/fff-bin-darwin-x64": "0.8.5-nightly.ccb1b9d",
-    "@ff-labs/fff-bin-linux-x64-gnu": "0.8.5-nightly.ccb1b9d",
-    "@ff-labs/fff-bin-linux-arm64-gnu": "0.8.5-nightly.ccb1b9d",
-    "@ff-labs/fff-bin-linux-x64-musl": "0.8.5-nightly.ccb1b9d",
-    "@ff-labs/fff-bin-linux-arm64-musl": "0.8.5-nightly.ccb1b9d",
-    "@ff-labs/fff-bin-win32-x64": "0.8.5-nightly.ccb1b9d",
-    "@ff-labs/fff-bin-win32-arm64": "0.8.5-nightly.ccb1b9d"
+    "@ff-labs/fff-bin-darwin-arm64": "0.9.0",
+    "@ff-labs/fff-bin-darwin-x64": "0.9.0",
+    "@ff-labs/fff-bin-linux-x64-gnu": "0.9.0",
+    "@ff-labs/fff-bin-linux-arm64-gnu": "0.9.0",
+    "@ff-labs/fff-bin-linux-x64-musl": "0.9.0",
+    "@ff-labs/fff-bin-linux-arm64-musl": "0.9.0",
+    "@ff-labs/fff-bin-win32-x64": "0.9.0",
+    "@ff-labs/fff-bin-win32-arm64": "0.9.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.8",