@topgunbuild/client 0.8.0 → 0.8.1

package/dist/index.js

@@ -39,6 +39,7 @@ __export(index_exports, {
   DEFAULT_CLUSTER_CONFIG: () => DEFAULT_CLUSTER_CONFIG,
   EncryptedStorageAdapter: () => EncryptedStorageAdapter,
   EventJournalReader: () => EventJournalReader,
+  HybridQueryHandle: () => HybridQueryHandle,
   IDBAdapter: () => IDBAdapter,
   LWWMap: () => import_core9.LWWMap,
   PNCounterHandle: () => PNCounterHandle,
@@ -775,6 +776,11 @@ var _SyncEngine = class _SyncEngine {
     // ============================================
     /** Pending search requests by requestId */
     this.pendingSearchRequests = /* @__PURE__ */ new Map();
+    // ============================================
+    // Hybrid Query Support (Phase 12)
+    // ============================================
+    /** Active hybrid query subscriptions */
+    this.hybridQueries = /* @__PURE__ */ new Map();
     if (!config.serverUrl && !config.connectionProvider) {
       throw new Error("SyncEngine requires either serverUrl or connectionProvider");
     }
@@ -2507,6 +2513,151 @@ var _SyncEngine = class _SyncEngine {
   getConflictResolverClient() {
     return this.conflictResolverClient;
   }
+  /**
+   * Subscribe to a hybrid query (FTS + filter combination).
+   */
+  subscribeToHybridQuery(query) {
+    this.hybridQueries.set(query.id, query);
+    const filter = query.getFilter();
+    const mapName = query.getMapName();
+    if (query.hasFTSPredicate() && this.stateMachine.getState() === "CONNECTED" /* CONNECTED */) {
+      this.sendHybridQuerySubscription(query.id, mapName, filter);
+    }
+    this.runLocalHybridQuery(mapName, filter).then((results) => {
+      query.onResult(results, "local");
+    });
+  }
+  /**
+   * Unsubscribe from a hybrid query.
+   */
+  unsubscribeFromHybridQuery(queryId) {
+    const query = this.hybridQueries.get(queryId);
+    if (query) {
+      this.hybridQueries.delete(queryId);
+      if (this.stateMachine.getState() === "CONNECTED" /* CONNECTED */ && query.hasFTSPredicate()) {
+        this.sendMessage({
+          type: "HYBRID_QUERY_UNSUBSCRIBE",
+          payload: { subscriptionId: queryId }
+        });
+      }
+    }
+  }
+  /**
+   * Send hybrid query subscription to server.
+   */
+  sendHybridQuerySubscription(queryId, mapName, filter) {
+    this.sendMessage({
+      type: "HYBRID_QUERY_SUBSCRIBE",
+      payload: {
+        subscriptionId: queryId,
+        mapName,
+        predicate: filter.predicate,
+        where: filter.where,
+        sort: filter.sort,
+        limit: filter.limit,
+        offset: filter.offset
+      }
+    });
+  }
+  /**
+   * Run a local hybrid query (FTS + filter combination).
+   * For FTS predicates, returns results with score = 0 (local-only mode).
+   * Server provides actual FTS scoring.
+   */
+  async runLocalHybridQuery(mapName, filter) {
+    if (!this.storageAdapter) {
+      return [];
+    }
+    const results = [];
+    const allKeys = await this.storageAdapter.getAllKeys();
+    const mapPrefix = `${mapName}:`;
+    const entries = [];
+    for (const fullKey of allKeys) {
+      if (fullKey.startsWith(mapPrefix)) {
+        const key = fullKey.substring(mapPrefix.length);
+        const record = await this.storageAdapter.get(fullKey);
+        if (record) {
+          entries.push([key, record]);
+        }
+      }
+    }
+    for (const [key, record] of entries) {
+      if (record === null || record.value === null) continue;
+      const value = record.value;
+      if (filter.predicate) {
+        const matches = (0, import_core.evaluatePredicate)(filter.predicate, value);
+        if (!matches) continue;
+      }
+      if (filter.where) {
+        let whereMatches = true;
+        for (const [field, expected] of Object.entries(filter.where)) {
+          if (value[field] !== expected) {
+            whereMatches = false;
+            break;
+          }
+        }
+        if (!whereMatches) continue;
+      }
+      results.push({
+        key,
+        value,
+        score: 0,
+        // Local doesn't have FTS scoring
+        matchedTerms: []
+      });
+    }
+    if (filter.sort) {
+      results.sort((a, b) => {
+        for (const [field, direction] of Object.entries(filter.sort)) {
+          let valA;
+          let valB;
+          if (field === "_score") {
+            valA = a.score ?? 0;
+            valB = b.score ?? 0;
+          } else if (field === "_key") {
+            valA = a.key;
+            valB = b.key;
+          } else {
+            valA = a.value[field];
+            valB = b.value[field];
+          }
+          if (valA < valB) return direction === "asc" ? -1 : 1;
+          if (valA > valB) return direction === "asc" ? 1 : -1;
+        }
+        return 0;
+      });
+    }
+    let sliced = results;
+    if (filter.offset) {
+      sliced = sliced.slice(filter.offset);
+    }
+    if (filter.limit) {
+      sliced = sliced.slice(0, filter.limit);
+    }
+    return sliced;
+  }
+  /**
+   * Handle hybrid query response from server.
+   */
+  handleHybridQueryResponse(payload) {
+    const query = this.hybridQueries.get(payload.subscriptionId);
+    if (query) {
+      query.onResult(payload.results, "server");
+    }
+  }
+  /**
+   * Handle hybrid query delta update from server.
+   */
+  handleHybridQueryDelta(payload) {
+    const query = this.hybridQueries.get(payload.subscriptionId);
+    if (query) {
+      if (payload.type === "LEAVE") {
+        query.onUpdate(payload.key, null);
+      } else {
+        query.onUpdate(payload.key, payload.value, payload.score, payload.matchedTerms);
+      }
+    }
+  }
 };
 /** Default timeout for entry processor requests (ms) */
 _SyncEngine.PROCESSOR_TIMEOUT = 3e4;
@@ -3387,6 +3538,236 @@ var SearchHandle = class {
   }
 };
 
+// src/HybridQueryHandle.ts
+var HybridQueryHandle = class {
+  constructor(syncEngine, mapName, filter = {}) {
+    this.listeners = /* @__PURE__ */ new Set();
+    this.currentResults = /* @__PURE__ */ new Map();
+    // Change tracking
+    this.changeTracker = new ChangeTracker();
+    this.pendingChanges = [];
+    this.changeListeners = /* @__PURE__ */ new Set();
+    // Track server data reception
+    this.hasReceivedServerData = false;
+    this.id = crypto.randomUUID();
+    this.syncEngine = syncEngine;
+    this.mapName = mapName;
+    this.filter = filter;
+  }
+  /**
+   * Subscribe to query results.
+   */
+  subscribe(callback) {
+    this.listeners.add(callback);
+    if (this.listeners.size === 1) {
+      this.syncEngine.subscribeToHybridQuery(this);
+    } else {
+      callback(this.getSortedResults());
+    }
+    this.loadInitialLocalData().then((data) => {
+      if (this.currentResults.size === 0) {
+        this.onResult(data, "local");
+      }
+    });
+    return () => {
+      this.listeners.delete(callback);
+      if (this.listeners.size === 0) {
+        this.syncEngine.unsubscribeFromHybridQuery(this.id);
+      }
+    };
+  }
+  async loadInitialLocalData() {
+    return this.syncEngine.runLocalHybridQuery(this.mapName, this.filter);
+  }
+  /**
+   * Called by SyncEngine with query results.
+   */
+  onResult(items, source = "server") {
+    logger.debug(
+      {
+        mapName: this.mapName,
+        itemCount: items.length,
+        source,
+        currentResultsCount: this.currentResults.size,
+        hasReceivedServerData: this.hasReceivedServerData
+      },
+      "HybridQueryHandle onResult"
+    );
+    if (source === "server" && items.length === 0 && !this.hasReceivedServerData) {
+      logger.debug(
+        { mapName: this.mapName },
+        "HybridQueryHandle ignoring empty server response"
+      );
+      return;
+    }
+    if (source === "server" && items.length > 0) {
+      this.hasReceivedServerData = true;
+    }
+    const newKeys = new Set(items.map((i) => i.key));
+    for (const key of this.currentResults.keys()) {
+      if (!newKeys.has(key)) {
+        this.currentResults.delete(key);
+      }
+    }
+    for (const item of items) {
+      this.currentResults.set(item.key, {
+        value: item.value,
+        score: item.score,
+        matchedTerms: item.matchedTerms
+      });
+    }
+    this.computeAndNotifyChanges(Date.now());
+    this.notify();
+  }
+  /**
+   * Called by SyncEngine on live update.
+   */
+  onUpdate(key, value, score, matchedTerms) {
+    if (value === null) {
+      this.currentResults.delete(key);
+    } else {
+      this.currentResults.set(key, { value, score, matchedTerms });
+    }
+    this.computeAndNotifyChanges(Date.now());
+    this.notify();
+  }
+  /**
+   * Subscribe to change events.
+   */
+  onChanges(listener) {
+    this.changeListeners.add(listener);
+    return () => this.changeListeners.delete(listener);
+  }
+  /**
+   * Get and clear pending changes.
+   */
+  consumeChanges() {
+    const changes = [...this.pendingChanges];
+    this.pendingChanges = [];
+    return changes;
+  }
+  /**
+   * Get last change without consuming.
+   */
+  getLastChange() {
+    return this.pendingChanges.length > 0 ? this.pendingChanges[this.pendingChanges.length - 1] : null;
+  }
+  /**
+   * Get all pending changes without consuming.
+   */
+  getPendingChanges() {
+    return [...this.pendingChanges];
+  }
+  /**
+   * Clear all pending changes.
+   */
+  clearChanges() {
+    this.pendingChanges = [];
+  }
+  /**
+   * Reset change tracker.
+   */
+  resetChangeTracker() {
+    this.changeTracker.reset();
+    this.pendingChanges = [];
+  }
+  computeAndNotifyChanges(timestamp) {
+    const dataMap = /* @__PURE__ */ new Map();
+    for (const [key, entry] of this.currentResults) {
+      dataMap.set(key, entry.value);
+    }
+    const changes = this.changeTracker.computeChanges(dataMap, timestamp);
+    if (changes.length > 0) {
+      this.pendingChanges.push(...changes);
+      this.notifyChangeListeners(changes);
+    }
+  }
+  notifyChangeListeners(changes) {
+    for (const listener of this.changeListeners) {
+      try {
+        listener(changes);
+      } catch (e) {
+        logger.error({ err: e }, "HybridQueryHandle change listener error");
+      }
+    }
+  }
+  notify() {
+    const results = this.getSortedResults();
+    for (const listener of this.listeners) {
+      listener(results);
+    }
+  }
+  /**
+   * Get sorted results with _key and _score.
+   */
+  getSortedResults() {
+    const results = Array.from(this.currentResults.entries()).map(
+      ([key, entry]) => ({
+        value: entry.value,
+        _key: key,
+        _score: entry.score,
+        _matchedTerms: entry.matchedTerms
+      })
+    );
+    if (this.filter.sort) {
+      results.sort((a, b) => {
+        for (const [field, direction] of Object.entries(this.filter.sort)) {
+          let valA;
+          let valB;
+          if (field === "_score") {
+            valA = a._score ?? 0;
+            valB = b._score ?? 0;
+          } else if (field === "_key") {
+            valA = a._key;
+            valB = b._key;
+          } else {
+            valA = a.value[field];
+            valB = b.value[field];
+          }
+          if (valA < valB) return direction === "asc" ? -1 : 1;
+          if (valA > valB) return direction === "asc" ? 1 : -1;
+        }
+        return 0;
+      });
+    }
+    let sliced = results;
+    if (this.filter.offset) {
+      sliced = sliced.slice(this.filter.offset);
+    }
+    if (this.filter.limit) {
+      sliced = sliced.slice(0, this.filter.limit);
+    }
+    return sliced;
+  }
+  /**
+   * Get the filter configuration.
+   */
+  getFilter() {
+    return this.filter;
+  }
+  /**
+   * Get the map name.
+   */
+  getMapName() {
+    return this.mapName;
+  }
+  /**
+   * Check if this query contains FTS predicates.
+   */
+  hasFTSPredicate() {
+    return this.filter.predicate ? this.containsFTS(this.filter.predicate) : false;
+  }
+  containsFTS(predicate) {
+    if (predicate.op === "match" || predicate.op === "matchPhrase" || predicate.op === "matchPrefix") {
+      return true;
+    }
+    if (predicate.children) {
+      return predicate.children.some((child) => this.containsFTS(child));
+    }
+    return false;
+  }
+};
+
 // src/cluster/ClusterClient.ts
 var import_core6 = require("@topgunbuild/core");
 
@@ -5270,6 +5651,43 @@ var TopGunClient = class {
     return new SearchHandle(this.syncEngine, mapName, query, options);
   }
   // ============================================
+  // Hybrid Query API (Phase 12)
+  // ============================================
+  /**
+   * Create a hybrid query combining FTS with traditional filters.
+   *
+   * Hybrid queries allow combining full-text search predicates (match, matchPhrase, matchPrefix)
+   * with traditional filter predicates (eq, gt, lt, contains, etc.) in a single query.
+   * Results include relevance scores for FTS ranking.
+   *
+   * @param mapName Name of the map to query
+   * @param filter Hybrid query filter with predicate, where, sort, limit, offset
+   * @returns HybridQueryHandle for managing the subscription
+   *
+   * @example
+   * ```typescript
+   * import { Predicates } from '@topgunbuild/core';
+   *
+   * // Hybrid query: FTS + filter
+   * const handle = client.hybridQuery<Article>('articles', {
+   *   predicate: Predicates.and(
+   *     Predicates.match('body', 'machine learning'),
+   *     Predicates.equal('category', 'tech')
+   *   ),
+   *   sort: { _score: 'desc' },
+   *   limit: 20
+   * });
+   *
+   * // Subscribe to results
+   * handle.subscribe((results) => {
+   *   results.forEach(r => console.log(`${r._key}: score=${r._score}`));
+   * });
+   * ```
+   */
+  hybridQuery(mapName, filter = {}) {
+    return new HybridQueryHandle(this.syncEngine, mapName, filter);
+  }
+  // ============================================
   // Entry Processor API (Phase 5.03)
   // ============================================
   /**
@@ -5877,6 +6295,7 @@ var import_core9 = require("@topgunbuild/core");
   DEFAULT_CLUSTER_CONFIG,
   EncryptedStorageAdapter,
   EventJournalReader,
+  HybridQueryHandle,
   IDBAdapter,
   LWWMap,
   PNCounterHandle,