@topgunbuild/client 0.6.0 → 0.8.0

package/dist/index.js

@@ -45,6 +45,7 @@ __export(index_exports, {
   PartitionRouter: () => PartitionRouter,
   Predicates: () => import_core9.Predicates,
   QueryHandle: () => QueryHandle,
+  SearchHandle: () => SearchHandle,
   SingleServerProvider: () => SingleServerProvider,
   SyncEngine: () => SyncEngine,
   SyncState: () => SyncState,
@@ -769,6 +770,11 @@ var _SyncEngine = class _SyncEngine {
     // ============================================
     /** Message listeners for journal and other generic messages */
     this.messageListeners = /* @__PURE__ */ new Set();
+    // ============================================
+    // Full-Text Search Methods (Phase 11.1a)
+    // ============================================
+    /** Pending search requests by requestId */
+    this.pendingSearchRequests = /* @__PURE__ */ new Map();
     if (!config.serverUrl && !config.connectionProvider) {
       throw new Error("SyncEngine requires either serverUrl or connectionProvider");
     }
@@ -1654,6 +1660,21 @@ var _SyncEngine = class _SyncEngine {
         this.conflictResolverClient.handleMergeRejected(message);
         break;
       }
+      // ============ Full-Text Search Message Handlers (Phase 11.1a) ============
+      case "SEARCH_RESP": {
+        logger.debug({ requestId: message.payload?.requestId, resultCount: message.payload?.results?.length }, "Received SEARCH_RESP");
+        this.handleSearchResponse(message.payload);
+        break;
+      }
+      // ============ Live Search Message Handlers (Phase 11.1b) ============
+      case "SEARCH_UPDATE": {
+        logger.debug({
+          subscriptionId: message.payload?.subscriptionId,
+          key: message.payload?.key,
+          type: message.payload?.type
+        }, "Received SEARCH_UPDATE");
+        break;
+      }
     }
     if (message.timestamp) {
       this.hlc.update(message.timestamp);
@@ -2417,6 +2438,65 @@ var _SyncEngine = class _SyncEngine {
       }
     }
   }
+  /**
+   * Perform a one-shot BM25 search on the server.
+   *
+   * @param mapName Name of the map to search
+   * @param query Search query text
+   * @param options Search options (limit, minScore, boost)
+   * @returns Promise resolving to search results
+   */
+  async search(mapName, query, options) {
+    if (!this.isAuthenticated()) {
+      throw new Error("Not connected to server");
+    }
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingSearchRequests.delete(requestId);
+        reject(new Error("Search request timed out"));
+      }, _SyncEngine.SEARCH_TIMEOUT);
+      this.pendingSearchRequests.set(requestId, {
+        resolve: (results) => {
+          clearTimeout(timeout);
+          resolve(results);
+        },
+        reject: (error) => {
+          clearTimeout(timeout);
+          reject(error);
+        },
+        timeout
+      });
+      const sent = this.sendMessage({
+        type: "SEARCH",
+        payload: {
+          requestId,
+          mapName,
+          query,
+          options
+        }
+      });
+      if (!sent) {
+        this.pendingSearchRequests.delete(requestId);
+        clearTimeout(timeout);
+        reject(new Error("Failed to send search request"));
+      }
+    });
+  }
+  /**
+   * Handle search response from server.
+   */
+  handleSearchResponse(payload) {
+    const pending = this.pendingSearchRequests.get(payload.requestId);
+    if (pending) {
+      this.pendingSearchRequests.delete(payload.requestId);
+      if (payload.error) {
+        pending.reject(new Error(payload.error));
+      } else {
+        pending.resolve(payload.results);
+      }
+    }
+  }
   // ============================================
   // Conflict Resolver Client (Phase 5.05)
   // ============================================
@@ -2430,6 +2510,8 @@ var _SyncEngine = class _SyncEngine {
 };
 /** Default timeout for entry processor requests (ms) */
 _SyncEngine.PROCESSOR_TIMEOUT = 3e4;
+/** Default timeout for search requests (ms) */
+_SyncEngine.SEARCH_TIMEOUT = 3e4;
 var SyncEngine = _SyncEngine;
 
 // src/TopGunClient.ts
@@ -3095,6 +3177,216 @@ var EventJournalReader = class {
   }
 };
 
+// src/SearchHandle.ts
+var SearchHandle = class {
+  constructor(syncEngine, mapName, query, options) {
+    /** Current results map (key → result) */
+    this.results = /* @__PURE__ */ new Map();
+    /** Result change listeners */
+    this.listeners = /* @__PURE__ */ new Set();
+    /** Whether the handle has been disposed */
+    this.disposed = false;
+    this.syncEngine = syncEngine;
+    this.mapName = mapName;
+    this._query = query;
+    this._options = options;
+    this.subscriptionId = crypto.randomUUID();
+    this.messageHandler = this.handleMessage.bind(this);
+    this.syncEngine.on("message", this.messageHandler);
+    this.sendSubscribe();
+  }
+  /**
+   * Handle incoming messages (both SEARCH_RESP and SEARCH_UPDATE).
+   */
+  handleMessage(message) {
+    if (message.type === "SEARCH_RESP") {
+      this.handleSearchResponse(message);
+    } else if (message.type === "SEARCH_UPDATE") {
+      this.handleSearchUpdate(message);
+    }
+  }
+  /**
+   * Get the current query string.
+   */
+  get query() {
+    return this._query;
+  }
+  /**
+   * Subscribe to result changes.
+   * Callback is immediately called with current results.
+   *
+   * @param callback - Function called with updated results
+   * @returns Unsubscribe function
+   */
+  subscribe(callback) {
+    if (this.disposed) {
+      throw new Error("SearchHandle has been disposed");
+    }
+    this.listeners.add(callback);
+    callback(this.getResults());
+    return () => {
+      this.listeners.delete(callback);
+    };
+  }
+  /**
+   * Get current results snapshot sorted by score (highest first).
+   *
+   * @returns Array of search results
+   */
+  getResults() {
+    return Array.from(this.results.values()).sort((a, b) => b.score - a.score);
+  }
+  /**
+   * Get result count.
+   */
+  get size() {
+    return this.results.size;
+  }
+  /**
+   * Update the search query.
+   * Triggers a new subscription with the updated query.
+   *
+   * @param query - New query string
+   */
+  setQuery(query) {
+    if (this.disposed) {
+      throw new Error("SearchHandle has been disposed");
+    }
+    if (query === this._query) {
+      return;
+    }
+    this.sendUnsubscribe();
+    this.results.clear();
+    this._query = query;
+    this.subscriptionId = crypto.randomUUID();
+    this.sendSubscribe();
+    this.notifyListeners();
+  }
+  /**
+   * Update search options.
+   *
+   * @param options - New search options
+   */
+  setOptions(options) {
+    if (this.disposed) {
+      throw new Error("SearchHandle has been disposed");
+    }
+    this.sendUnsubscribe();
+    this.results.clear();
+    this._options = options;
+    this.subscriptionId = crypto.randomUUID();
+    this.sendSubscribe();
+    this.notifyListeners();
+  }
+  /**
+   * Dispose of the handle and cleanup resources.
+   * After disposal, the handle cannot be used.
+   */
+  dispose() {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this.sendUnsubscribe();
+    this.syncEngine.off("message", this.messageHandler);
+    this.results.clear();
+    this.listeners.clear();
+  }
+  /**
+   * Check if handle is disposed.
+   */
+  isDisposed() {
+    return this.disposed;
+  }
+  /**
+   * Send SEARCH_SUB message to server.
+   */
+  sendSubscribe() {
+    this.syncEngine.send({
+      type: "SEARCH_SUB",
+      payload: {
+        subscriptionId: this.subscriptionId,
+        mapName: this.mapName,
+        query: this._query,
+        options: this._options
+      }
+    });
+  }
+  /**
+   * Send SEARCH_UNSUB message to server.
+   */
+  sendUnsubscribe() {
+    this.syncEngine.send({
+      type: "SEARCH_UNSUB",
+      payload: {
+        subscriptionId: this.subscriptionId
+      }
+    });
+  }
+  /**
+   * Handle SEARCH_RESP message (initial results).
+   */
+  handleSearchResponse(message) {
+    if (message.type !== "SEARCH_RESP") return;
+    if (message.payload?.requestId !== this.subscriptionId) return;
+    const { results } = message.payload;
+    if (Array.isArray(results)) {
+      for (const result of results) {
+        this.results.set(result.key, {
+          key: result.key,
+          value: result.value,
+          score: result.score,
+          matchedTerms: result.matchedTerms || []
+        });
+      }
+      this.notifyListeners();
+    }
+  }
+  /**
+   * Handle SEARCH_UPDATE message (delta updates).
+   */
+  handleSearchUpdate(message) {
+    if (message.type !== "SEARCH_UPDATE") return;
+    if (message.payload?.subscriptionId !== this.subscriptionId) return;
+    const { key, value, score, matchedTerms, type } = message.payload;
+    switch (type) {
+      case "ENTER":
+        this.results.set(key, {
+          key,
+          value,
+          score,
+          matchedTerms: matchedTerms || []
+        });
+        break;
+      case "UPDATE":
+        const existing = this.results.get(key);
+        if (existing) {
+          existing.score = score;
+          existing.matchedTerms = matchedTerms || [];
+          existing.value = value;
+        }
+        break;
+      case "LEAVE":
+        this.results.delete(key);
+        break;
+    }
+    this.notifyListeners();
+  }
+  /**
+   * Notify all listeners of result changes.
+   */
+  notifyListeners() {
+    const results = this.getResults();
+    for (const listener of this.listeners) {
+      try {
+        listener(results);
+      } catch (err) {
+        console.error("SearchHandle listener error:", err);
+      }
+    }
+  }
+};
+
 // src/cluster/ClusterClient.ts
 var import_core6 = require("@topgunbuild/core");
 
@@ -4908,6 +5200,76 @@ var TopGunClient = class {
     return this.syncEngine.onBackpressure(event, listener);
   }
   // ============================================
+  // Full-Text Search API (Phase 11.1a)
+  // ============================================
+  /**
+   * Perform a one-shot BM25 search on the server.
+   *
+   * Searches the specified map using BM25 ranking algorithm.
+   * Requires FTS to be enabled for the map on the server.
+   *
+   * @param mapName Name of the map to search
+   * @param query Search query text
+   * @param options Search options
+   * @returns Promise resolving to search results sorted by relevance
+   *
+   * @example
+   * ```typescript
+   * const results = await client.search<Article>('articles', 'machine learning', {
+   *   limit: 20,
+   *   minScore: 0.5,
+   *   boost: { title: 2.0, body: 1.0 }
+   * });
+   *
+   * for (const result of results) {
+   *   console.log(`${result.key}: ${result.value.title} (score: ${result.score})`);
+   * }
+   * ```
+   */
+  async search(mapName, query, options) {
+    return this.syncEngine.search(mapName, query, options);
+  }
+  // ============================================
+  // Live Search API (Phase 11.1b)
+  // ============================================
+  /**
+   * Subscribe to live search results with real-time updates.
+   *
+   * Unlike the one-shot `search()` method, `searchSubscribe()` returns a handle
+   * that receives delta updates (ENTER/UPDATE/LEAVE) when documents change.
+   * This is ideal for live search UIs that need to reflect data changes.
+   *
+   * @param mapName Name of the map to search
+   * @param query Search query text
+   * @param options Search options (limit, minScore, boost)
+   * @returns SearchHandle for managing the subscription
+   *
+   * @example
+   * ```typescript
+   * const handle = client.searchSubscribe<Article>('articles', 'machine learning', {
+   *   limit: 20,
+   *   minScore: 0.5
+   * });
+   *
+   * // Subscribe to result changes
+   * const unsubscribe = handle.subscribe((results) => {
+   *   setSearchResults(results);
+   * });
+   *
+   * // Update query dynamically
+   * handle.setQuery('deep learning');
+   *
+   * // Get current snapshot
+   * const snapshot = handle.getResults();
+   *
+   * // Cleanup when done
+   * handle.dispose();
+   * ```
+   */
+  searchSubscribe(mapName, query, options) {
+    return new SearchHandle(this.syncEngine, mapName, query, options);
+  }
+  // ============================================
   // Entry Processor API (Phase 5.03)
   // ============================================
   /**
@@ -5521,6 +5883,7 @@ var import_core9 = require("@topgunbuild/core");
   PartitionRouter,
   Predicates,
   QueryHandle,
+  SearchHandle,
   SingleServerProvider,
   SyncEngine,
   SyncState,