@ff-labs/fff-bun 0.10.4-nightly.e2cad2f → 0.10.5-dev.2a477d2

package/dist/ffi.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Bun FFI bindings for the fff-c native library
+ *
+ * This module uses Bun's native FFI to call into the Rust C library.
+ * All functions follow the Result pattern for error handling.
+ *
+ * The API is instance-based: `ffiCreate` returns an opaque handle that must
+ * be passed to all subsequent calls and freed with `ffiDestroy`.
+ */
+import { type JSCallback, type Pointer } from "bun:ffi";
+import type { DirSearchResult, GrepResult, MixedSearchResult, Result, ScanProgress, SearchResult, WatchEvent } from "./fff-api";
+/**
+ * Opaque native handle type. Callers must not inspect or modify this value.
+ */
+export type NativeHandle = Pointer;
+/**
+ * Create a new file finder instance.
+ *
+ * Hand-encodes a [`FffCreateOptions`] struct (88 bytes, locked offsets — see
+ * `crates/fff-c/src/ffi_types.rs::options_layout_tests`) into a Buffer and
+ * passes its pointer to `fff_create_instance_with`. Inner cstring addresses
+ * come from Bun's native `ptr(buffer)` primitive — no round-trip helpers,
+ * no struct support gaps.
+ *
+ * Adding new options later means: (1) appending the field to
+ * `FffCreateOptions` in Rust, (2) bumping `FFF_CREATE_OPTIONS_VERSION`,
+ * (3) extending `FFF_CREATE_OPTIONS_SIZE` + offsets here. The C entry point
+ * never changes.
+ */
+export declare function ffiCreate(basePath: string, frecencyDbPath: string, historyDbPath: string, _useUnsafeNoLock: boolean, enableMmapCache: boolean, enableContentIndexing: boolean, watch: boolean, aiMode: boolean, logFilePath: string, logLevel: string, cacheBudgetMaxFiles: bigint, cacheBudgetMaxBytes: bigint, cacheBudgetMaxFileSize: bigint, enableFsRootScanning: boolean, enableHomeDirScanning: boolean): Result<NativeHandle>;
+/**
+ * Destroy and clean up an instance.
+ */
+export declare function ffiDestroy(handle: NativeHandle): void;
+/**
+ * Perform fuzzy search.
+ */
+export declare function ffiSearch(handle: NativeHandle, query: string, currentFile: string, maxThreads: number, pageIndex: number, pageSize: number, comboBoostMultiplier: number, minComboCount: number): Result<SearchResult>;
+/**
+ * Glob-only search. Bypasses the regular query parser, applies the pattern
+ * as a single `Constraint::Glob`, ranks by frecency, paginates.
+ */
+export declare function ffiGlob(handle: NativeHandle, pattern: string, currentFile: string, maxThreads: number, pageIndex: number, pageSize: number): Result<SearchResult>;
+/**
+ * Perform fuzzy directory search.
+ */
+export declare function ffiSearchDirectories(handle: NativeHandle, query: string, currentFile: string | null, maxThreads: number, pageIndex: number, pageSize: number): Result<DirSearchResult>;
+/**
+ * Perform mixed (files + directories) fuzzy search.
+ */
+export declare function ffiSearchMixed(handle: NativeHandle, query: string, currentFile: string, maxThreads: number, pageIndex: number, pageSize: number, comboBoostMultiplier: number, minComboCount: number): Result<MixedSearchResult>;
+/**
+ * Live grep - search file contents.
+ */
+export declare function ffiLiveGrep(handle: NativeHandle, query: string, mode: string, maxFileSize: number, maxMatchesPerFile: number, smartCase: boolean, fileOffset: number, pageLimit: number, timeBudgetMs: number, beforeContext: number, afterContext: number, classifyDefinitions: boolean): Result<GrepResult>;
+/**
+ * Multi-pattern grep - Aho-Corasick multi-needle search.
+ */
+export declare function ffiMultiGrep(handle: NativeHandle, patternsJoined: string, constraints: string, maxFileSize: number, maxMatchesPerFile: number, smartCase: boolean, fileOffset: number, pageLimit: number, timeBudgetMs: number, beforeContext: number, afterContext: number, classifyDefinitions: boolean): Result<GrepResult>;
+/**
+ * Trigger file scan.
+ */
+export declare function ffiScanFiles(handle: NativeHandle): Result<void>;
+/**
+ * Check if scanning.
+ */
+export declare function ffiIsScanning(handle: NativeHandle): boolean;
+/**
+ * Get the base path of the file picker.
+ */
+export declare function ffiGetBasePath(handle: NativeHandle): Result<string | null>;
+/**
+ * Get scan progress.
+ */
+export declare function ffiGetScanProgress(handle: NativeHandle): Result<ScanProgress>;
+/**
+ * Wait for scan to complete.
+ */
+export declare function ffiWaitForScan(handle: NativeHandle, timeoutMs: number): Result<boolean>;
+/**
+ * Restart index in new path.
+ */
+export declare function ffiRestartIndex(handle: NativeHandle, newPath: string): Result<void>;
+/**
+ * Parse an FffWatchEventBatch delivered to a watch callback, then free it.
+ * Ownership of the batch transfers to JS at callback time, so this MUST be
+ * called exactly once per delivered batch pointer.
+ */
+export declare function readWatchEventBatch(batchPtr: Pointer | number | null): WatchEvent[];
+/**
+ * Register the instance-wide watch callback. Must be called before the
+ * first `ffiWatch`. The caller owns `callback` (a threadsafe `JSCallback`
+ * built in finder.ts) and must keep it alive until after `ffiDestroy`
+ * returns for this handle — that call is the delivery quiescence barrier.
+ */
+export declare function ffiSetWatchCallback(handle: NativeHandle, callback: JSCallback): Result<void>;
+/**
+ * Subscribe to filesystem changes; batches are delivered through the
+ * instance callback registered with `ffiSetWatchCallback`, tagged with the
+ * watch id this function returns.
+ *
+ * @returns The native watch id carried in `FffResult.int_value`.
+ */
+export declare function ffiWatch(handle: NativeHandle, pattern: string, ignore?: string[]): Result<number>;
+/**
+ * Remove a watch subscription. Returns true if the id was found.
+ */
+export declare function ffiUnwatch(handle: NativeHandle, watchId: number): Result<boolean>;
+/**
+ * Refresh git status.
+ */
+export declare function ffiRefreshGitStatus(handle: NativeHandle): Result<number>;
+/**
+ * Track query completion.
+ */
+export declare function ffiTrackQuery(handle: NativeHandle, query: string, filePath: string): Result<boolean>;
+/**
+ * Get historical query.
+ */
+export declare function ffiGetHistoricalQuery(handle: NativeHandle, offset: number): Result<string | null>;
+/**
+ * Health check.
+ *
+ * `handle` can be null for a limited check (version + git only).
+ */
+export declare function ffiHealthCheck(handle: NativeHandle | null, testPath: string): Result<unknown>;
+/**
+ * Ensure the library is loaded.
+ *
+ * Loads the native library from the platform-specific npm package
+ * or a local dev build. Throws if the binary is not found.
+ */
+export declare function ensureLoaded(): void;
+/**
+ * Check if the library is available.
+ */
+export declare function isAvailable(): boolean;
+//# sourceMappingURL=ffi.d.ts.map

package/dist/ffi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffi.d.ts","sourceRoot":"","sources":["../src/ffi.ts"],"names":[],"mappings":"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"}

package/dist/finder.d.ts

@@ -0,0 +1,378 @@
+/**
+ * FileFinder - High-level API for the fff file finder
+ *
+ * This class provides a type-safe, ergonomic API for file finding operations.
+ * Each instance owns an independent native file picker that can be created
+ * and destroyed independently. Multiple instances can coexist.
+ *
+ * All methods return Result types for explicit error handling.
+ */
+import type { DirSearchOptions, DirSearchResult, InitOptions as FFFInitOptions, FileFinderApi, GlobOptions, GrepOptions, GrepResult, HealthCheck, MixedSearchResult, MultiGrepOptions, Result, ScanProgress, SearchOptions, SearchResult, WatchBatchCallback, WatchOptions, WatchUnsubscribe } from "./fff-api";
+/**
+ * FileFinder - Fast file finder with fuzzy search
+ *
+ * Each instance is backed by an independent native file picker. Create as many
+ * as you need and destroy them when done.
+ *
+ * @example
+ * ```typescript
+ * import { FileFinder } from "fff";
+ *
+ * // Create an instance
+ * const finder = FileFinder.create({ basePath: "/path/to/project" });
+ * if (!finder.ok) {
+ *   console.error(finder.error);
+ *   process.exit(1);
+ * }
+ *
+ * // Wait for initial scan
+ * await finder.value.waitForScan(5000);
+ *
+ * // Search for files
+ * const search = finder.value.search("main.ts");
+ * if (search.ok) {
+ *   for (const item of search.value.items) {
+ *     console.log(item.relativePath);
+ *   }
+ * }
+ *
+ * // Cleanup
+ * finder.value.destroy();
+ * ```
+ */
+export declare class FileFinder implements FileFinderApi {
+    private handle;
+    /** Active watch subscriptions: native watch id -> JS batch handler. */
+    private watchHandlers;
+    /**
+     * ONE threadsafe JSCallback per instance, registered lazily with
+     * `fff_set_watch_callback` on the first subscription and closed in
+     * `destroy()` after `fff_destroy` returns (the quiescence barrier).
+     */
+    private watchJsCallback;
+    private constructor();
+    /**
+     * Create a new file finder instance.
+     *
+     * @param options - Initialization options
+     * @returns Result containing the new FileFinder instance or an error
+     *
+     * @example
+     * ```typescript
+     * // Basic initialization
+     * const finder = FileFinder.create({ basePath: "/path/to/project" });
+     *
+     * // With custom database paths
+     * const finder = FileFinder.create({
+     *   basePath: "/path/to/project",
+     *   frecencyDbPath: "/custom/frecency.mdb",
+     *   historyDbPath: "/custom/history.mdb",
+     * });
+     * ```
+     */
+    static create(options: FFFInitOptions): Result<FileFinder>;
+    /**
+     * Destroy and clean up all resources.
+     *
+     * Frees the native instance (unsubscribing all watches), then closes the
+     * instance watch trampoline. After calling this, the instance must not be
+     * used again.
+     */
+    destroy(): void;
+    /**
+     * Check if this instance has been destroyed.
+     */
+    get isDestroyed(): boolean;
+    /**
+     * Guard that returns an error if the instance has been destroyed.
+     */
+    private ensureAlive;
+    /**
+     * Search for files matching the query.
+     *
+     * The query supports fuzzy matching and special 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 file.ts with line 42, column 10
+     *
+     * @param query - Search query string
+     * @param options - Search options
+     * @returns Search results with matched files and scores
+     *
+     * @example
+     * ```typescript
+     * const result = finder.search("main.ts", { pageSize: 10 });
+     * if (result.ok) {
+     *   console.log(`Found ${result.value.totalMatched} files`);
+     *   for (const item of result.value.items) {
+     *     console.log(item.relativePath);
+     *   }
+     * }
+     * ```
+     */
+    fileSearch(query: string, options?: SearchOptions): Result<SearchResult>;
+    /**
+     * Glob-only search.
+     *
+     * The pattern is applied as a single pass SIMD optimized prefiltering
+     * without any fuzzy matching involved. Faster and 100% compatible to npm `glob`.
+     *
+     * @param pattern - Glob pattern (required, non-empty)
+     * @param options - Glob search options (pagination, max threads, current file)
+     * @returns Search results with files matching the glob
+     */
+    glob(pattern: string, options?: GlobOptions): Result<SearchResult>;
+    /**
+     * Search for directories matching the query.
+     *
+     * @param query - Search query string
+     * @param options - Directory search options
+     * @returns Search results with matched directories and scores
+     *
+     * @example
+     * ```typescript
+     * const result = finder.directorySearch("components", { pageSize: 10 });
+     * if (result.ok) {
+     *   console.log(`Found ${result.value.totalMatched} directories`);
+     *   for (const item of result.value.items) {
+     *     console.log(item.relativePath);
+     *   }
+     * }
+     * ```
+     */
+    directorySearch(query: string, options?: DirSearchOptions): Result<DirSearchResult>;
+    /**
+     * Search for files and directories together (mixed search).
+     *
+     * Results are interleaved by total score in descending order.
+     *
+     * @param query - Search query string
+     * @param options - Search options
+     * @returns Mixed search results with files and directories interleaved by score
+     *
+     * @example
+     * ```typescript
+     * const result = finder.mixedSearch("main", { pageSize: 20 });
+     * if (result.ok) {
+     *   for (const entry of result.value.items) {
+     *     if (entry.type === "file") {
+     *       console.log(`File: ${entry.item.relativePath}`);
+     *     } else {
+     *       console.log(`Dir: ${entry.item.relativePath}`);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    mixedSearch(query: string, options?: SearchOptions): Result<MixedSearchResult>;
+    /**
+     * Search file contents (live grep).
+     *
+     * Searches through the contents of indexed files using the specified mode:
+     * - `"plain"` (default): SIMD-accelerated literal text matching
+     * - `"regex"`: Regular expression matching
+     * - `"fuzzy"`: Smith-Waterman fuzzy matching per line
+     *
+     * Supports pagination for large result sets. The result includes a `nextCursor`
+     * that can be passed back to fetch the next page.
+     *
+     * The query also supports constraint syntax:
+     * - `*.ts pattern` - Only search in TypeScript files
+     * - `src/ pattern` - Only search in the src directory
+     *
+     * @param query - Search query string
+     * @param options - Grep options (mode, pagination, limits)
+     * @returns Grep results with matched lines and file metadata
+     *
+     * @example
+     * ```typescript
+     * // First page
+     * const result = finder.grep("TODO", { mode: "plain" });
+     * if (result.ok) {
+     *   for (const match of result.value.items) {
+     *     console.log(`${match.relativePath}:${match.lineNumber}: ${match.lineContent}`);
+     *   }
+     *   // Fetch next page
+     *   if (result.value.nextCursor) {
+     *     const page2 = finder.grep("TODO", {
+     *       cursor: result.value.nextCursor,
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    grep(query: string, options?: GrepOptions): Result<GrepResult>;
+    /**
+     * Multi-pattern OR search using Aho-Corasick.
+     *
+     * Searches for lines matching ANY of the provided patterns using
+     * SIMD-accelerated multi-needle matching. Faster than regex alternation
+     * for literal text searches.
+     *
+     * Supports pagination. The result includes a `nextCursor` that can be
+     * passed back to fetch the next page.
+     *
+     * @param options - Multi-grep options including patterns and optional constraints
+     * @returns Grep results with matched lines and file metadata
+     *
+     * @example
+     * ```typescript
+     * const result = finder.multiGrep({
+     *   patterns: ["VideoFrame", "video_frame", "PreloadedImage"],
+     * });
+     * if (result.ok) {
+     *   for (const match of result.value.items) {
+     *     console.log(`${match.relativePath}:${match.lineNumber}: ${match.lineContent}`);
+     *   }
+     * }
+     * ```
+     */
+    multiGrep(options: MultiGrepOptions): Result<GrepResult>;
+    /**
+     * Trigger a rescan of the indexed directory.
+     *
+     * This is useful after major file system changes that the
+     * background watcher might have missed.
+     */
+    scanFiles(): Result<void>;
+    /**
+     * Check if a scan is currently in progress.
+     */
+    isScanning(): boolean;
+    /**
+     * Get the base path of the file picker (the root directory being indexed).
+     */
+    getBasePath(): Result<string | null>;
+    /**
+     * Get the current scan progress.
+     */
+    getScanProgress(): Result<ScanProgress>;
+    /**
+     * Wait for the initial file scan to complete.
+     *
+     * Non-blocking: polls `isScanning` and yields to the event loop between
+     * checks, so other async work keeps running while waiting.
+     *
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+     * @returns true if scan completed, false if timed out
+     *
+     * @example
+     * ```typescript
+     * const finder = FileFinder.create({ basePath: "/path/to/project" });
+     * if (finder.ok) {
+     *   const completed = await finder.value.waitForScan(10000);
+     *   if (!completed.ok || !completed.value) {
+     *     console.warn("Scan did not complete in time");
+     *   }
+     * }
+     * ```
+     */
+    waitForScan(timeoutMs?: number): Promise<Result<boolean>>;
+    /**
+     * Wait for the initial file scan to complete, blocking the calling thread.
+     *
+     * Backed by the native `fff_wait_for_scan` call. Prefer {@link waitForScan}
+     * unless you specifically need synchronous blocking behaviour.
+     *
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+     * @returns true if scan completed, false if timed out
+     */
+    waitForScanBlocking(timeoutMs?: number): Result<boolean>;
+    /**
+     * Wait until the index is fully ready: the scan has finished and the warmup
+     * (content indexing / bigram) phase has completed.
+     *
+     * Non-blocking — polls `getScanProgress` and yields to the event loop.
+     *
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+     * @returns true if the index became ready, false if timed out
+     */
+    waitForIndexReady(timeoutMs?: number): Promise<Result<boolean>>;
+    /**
+     * Change the indexed directory to a new path.
+     *
+     * This stops the current file watcher and starts indexing the new directory.
+     *
+     * @param newPath - New directory path to index
+     */
+    reindex(newPath: string): Result<void>;
+    /**
+     * Refresh the git status cache.
+     *
+     * @returns Number of files with updated git status
+     */
+    refreshGitStatus(): Result<number>;
+    /**
+     * Track query completion for smart suggestions.
+     *
+     * Call this when a user selects a file from search results.
+     * This helps improve future search rankings for similar queries.
+     *
+     * @param query - The search query that was used
+     * @param selectedFilePath - The file path that was selected
+     */
+    trackQuery(query: string, selectedFilePath: string): Result<boolean>;
+    /**
+     * Get a historical query by offset.
+     *
+     * @param offset - Offset from most recent (0 = most recent)
+     * @returns The historical query string, or null if not found
+     */
+    getHistoricalQuery(offset: number): Result<string | null>;
+    /**
+     * Lazily create + register the instance-wide watch trampoline. Routes
+     * every delivered batch to the handler registered for its watch id;
+     * unknown ids (unsubscribe races) are benign — the batch is just freed.
+     */
+    private ensureWatchTrampoline;
+    /**
+     * Subscribe to filesystem changes matching `pattern` (glob, exact file,
+     * or directory subtree). Omit the pattern to watch the entire indexed
+     * tree. Normalized batches of up to 128 events are delivered on the JS event
+     * loop, with each path appearing at most once. See `FileFinderApi.watch`.
+     *
+     * @example
+     * ```typescript
+     * const sub = finder.watch("**\/*.ts", (events) => {
+     *   for (const e of events) console.log(e.kind, e.path);
+     * });
+     * if (sub.ok) sub.value(); // unsubscribe
+     *
+     * // no pattern: everything under the indexed base path
+     * const all = finder.watch((events) => console.log(events.length));
+     * ```
+     */
+    watch(callback: WatchBatchCallback, options?: WatchOptions): Result<WatchUnsubscribe>;
+    watch(pattern: string, callback: WatchBatchCallback, options?: WatchOptions): Result<WatchUnsubscribe>;
+    /**
+     * Remove a subscription from the routing map, then from the native side.
+     * Map removal is synchronous on the JS thread, so once this returns the
+     * handler can never run again (late native batches miss the lookup).
+     * Idempotent.
+     */
+    private unwatchById;
+    /**
+     * Get health check information.
+     *
+     * Useful for debugging and verifying the file finder is working correctly.
+     *
+     * @param testPath - Optional path to test git repository detection
+     */
+    healthCheck(testPath?: string): Result<HealthCheck>;
+    /**
+     * Check if the native library is available.
+     */
+    static isAvailable(): boolean;
+    /** Ensure the native library is loaded. */
+    static ensureLoaded(): void;
+    /**
+     * Get a health check without requiring an instance.
+     *
+     * Returns limited info (version + git only, no picker/frecency/query data).
+     *
+     * @param testPath - Optional path to test git repository detection
+     */
+    static healthCheckStatic(testPath?: string): Result<HealthCheck>;
+}
+//# sourceMappingURL=finder.d.ts.map

package/dist/finder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finder.d.ts","sourceRoot":"","sources":["../src/finder.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { binaryExists, findBinary } from "./download";
+export type { DbHealth, DirItem, DirSearchOptions, DirSearchResult, err, FileFinderApi, FileItem, GrepCursor, GrepMatch, GrepMode, GrepOptions, GrepResult, HealthCheck, InitOptions, Location, MixedItem, MixedSearchResult, MultiGrepOptions, ok, Result, ScanProgress, Score, SearchOptions, SearchResult, WatchBatchCallback, WatchEvent, WatchEventKind, WatchOptions, WatchUnsubscribe, } from "./fff-api";
+export { FileFinder } from "./finder";
+export { getLibExtension, getLibFilename, getNpmPackageName, getTriple, } from "./platform";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EACV,QAAQ,EACR,OAAO,EACP,gBAAgB,EAChB,eAAe,EACf,GAAG,EACH,aAAa,EACb,QAAQ,EACR,UAAU,EACV,SAAS,EACT,QAAQ,EACR,WAAW,EACX,UAAU,EACV,WAAW,EACX,WAAW,EACX,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,EAAE,EACF,MAAM,EACN,YAAY,EACZ,KAAK,EACL,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EACL,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,SAAS,GACV,MAAM,YAAY,CAAC"}