Refactor to new handle-based API (FileIndex) and update README

Author: andrestubbe

README.md

@@ -1,5 +1,7 @@
 # FastFileIndex
 
+Ultra-fast native file indexer with real-time metadata extraction and zero-copy directory traversal [ALPHA].
+
 [![Build](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
 [![Java](https://img.shields.io/badge/Java-17+-blue.svg)](https://www.java.com)
 [![Platform](https://img.shields.io/badge/Platform-Windows%2010+-lightgrey.svg)]()
@@ -22,7 +24,7 @@
 
 ## Description
 
-FastFileIndex creates a compact, append-only, mmap-friendly binary index of all files. It is the first module in the FastJava file search engine trilogy:
+FastFileIndex is the first module in the FastJava file search engine trilogy:
 
 - **FastFileIndex** - Full filesystem scan ? produces a binary, mmap-capable index of all files
 - **FastFileSearch** - Builds Prefix Trie, N-Gram index, Exact Match map, and Ranking engine on top of the index

examples/Demo/src/main/java/fastfileindex/Demo$1.class

@@ -0,0 +1,43 @@
+package fastfileindex;
+
+/**
+ * BuildOptions - Options for building the index.
+ */
+public class BuildOptions {
+    private boolean followSymlinks = false;
+    private boolean includeHidden = false;
+    private int maxDepth = -1;
+
+    public BuildOptions() {}
+
+    public BuildOptions followSymlinks(boolean value) {
+        this.followSymlinks = value;
+        return this;
+    }
+
+    public BuildOptions includeHidden(boolean value) {
+        this.includeHidden = value;
+        return this;
+    }
+
+    public BuildOptions maxDepth(int value) {
+        this.maxDepth = value;
+        return this;
+    }
+
+    public boolean followSymlinks() {
+        return followSymlinks;
+    }
+
+    public boolean includeHidden() {
+        return includeHidden;
+    }
+
+    public int maxDepth() {
+        return maxDepth;
+    }
+
+    public static BuildOptions defaults() {
+        return new BuildOptions();
+    }
+}

src/main/java/fastfileindex/BuildOptions.java

@@ -0,0 +1,13 @@
+package fastfileindex;
+
+/**
+ * FileEntry - File entry value type.
+ */
+public record FileEntry(
+        long id,
+        long parentId,
+        String path,
+        long size,
+        long modified,
+        FileType type
+) {}

src/main/java/fastfileindex/FastFileIndex.java

@@ -0,0 +1,105 @@
+package fastfileindex;
+
+/**
+ * FileIndex - Handle-based file index with mmap loading.
+ * 
+ * <p>FileIndex is the first module in the FastJava file search engine trilogy:
+ * <ul>
+ *   <li>FileIndex - Full filesystem scan → produces a binary, mmap-capable index of all files</li>
+ *   <li>SearchEngine - Builds Prefix Trie, N-Gram index, Exact Match map, and Ranking engine on top of the index</li>
+ *   <li>WatchService - Uses USN Journal to keep the index + search structures live-updated with zero rescans</li>
+ * </ul>
+ * 
+ * <p>This architecture is similar to Everything, Spotlight, VSCode, and fsearch but modular and embeddable.
+ * 
+ * <p><b>Key Features:</b>
+ * <ul>
+ *   <li>mmap-based loading (CreateFileMapping + MapViewOfFile)</li>
+ *   <li>Path-Blob + Offsets instead of std::string per entry</li>
+ *   <li>Parallel build with threadpool and lock-free append buffer</li>
+ *   <li>FNV-1a hashing for stable file IDs</li>
+ *   <li>Type detection (image, pdf, text, code)</li>
+ *   <li>Converts file timestamps to Unix seconds</li>
+ *   <li>Saves to files.idx (append-only)</li>
+ *   <li>Loads instantly (&lt;1-3 ms with mmap)</li>
+ *   <li>Zero-copy path access via string_view</li>
+ * </ul>
+ * 
+ * <p><b>Binary Format:</b>
+ * <ul>
+ *   <li>files.idx - FileEntryHeader with id, parentId, size, modified, type, pathOffset, pathLen</li>
+ *   <li>paths.bin - Path-Blob containing all paths in a single contiguous blob</li>
+ * </ul>
+ * 
+ * @since 1.0.0
+ * @version 1.0.0
+ */
+public final class FileIndex {
+    static {
+        try {
+            // Try System.loadLibrary first (default)
+            System.loadLibrary("fastcore");
+        } catch (UnsatisfiedLinkError e1) {
+            try {
+                // Fallback to absolute path (relative to user.dir)
+                String userDir = System.getProperty("user.dir");
+                String dllPath = userDir + "\\build\\fastcore.dll";
+                System.load(dllPath);
+            } catch (UnsatisfiedLinkError e2) {
+                System.err.println("Failed to load fastcore.dll: " + e2.getMessage());
+                throw e2;
+            }
+        }
+    }
+    
+    private final long nativeHandle;
+
+    private FileIndex(long nativeHandle) {
+        this.nativeHandle = nativeHandle;
+    }
+
+    public long handle() {
+        return nativeHandle;
+    }
+
+    /**
+     * Build index from roots.
+     */
+    public static native FileIndex build(String[] roots, BuildOptions options);
+
+    /**
+     * Open existing index from file.
+     */
+    public static native FileIndex open(String indexPath);
+
+    /**
+     * Save index to file.
+     */
+    public native void save(String indexPath);
+
+    /**
+     * Close index and free resources.
+     */
+    public native void close();
+
+    /**
+     * Get index metadata.
+     */
+    public native IndexMetadata metadata();
+
+    /**
+     * Get entry count.
+     */
+    public native long entryCount();
+
+    /**
+     * Get file entry by ID.
+     */
+    public native FileEntry get(long id);
+
+    public static void main(String[] args) {
+        System.out.println("=== FileIndex ===");
+        System.out.println("FileIndex - Binary file indexing with mmap support");
+        System.out.println("=== OK ===");
+    }
+}

src/main/java/fastfileindex/FileEntry.java

@@ -0,0 +1,18 @@
+package fastfileindex;
+
+/**
+ * FileType - File type enumeration.
+ */
+public enum FileType {
+    UNKNOWN,
+    DIRECTORY,
+    FILE,
+    IMAGE,
+    VIDEO,
+    AUDIO,
+    DOCUMENT,
+    ARCHIVE,
+    CODE,
+    TEXT,
+    BINARY
+}

src/main/java/fastfileindex/FileIndex.java

@@ -0,0 +1,11 @@
+package fastfileindex;
+
+/**
+ * IndexMetadata - Index metadata value type.
+ */
+public record IndexMetadata(
+        long entryCount,
+        long totalSize,
+        long buildTime,
+        String version
+) {}