@topgunbuild/server 0.7.0 → 0.8.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as _topgunbuild_core from '@topgunbuild/core';
-import { Timestamp, LWWRecord, ORMapRecord, Principal, EventJournalImpl, EventJournalConfig, JournalEvent, PermissionPolicy, ConsistencyLevel, ReplicationConfig, LWWMap, ORMap, PermissionType, MigrationConfig, MigrationStatus, MigrationMetrics, PartitionMap, PartitionInfo, PartitionChange, ReplicationLag, ReplicationHealth, ReplicationResult, ClusterReadOptions, MerkleTree, EntryProcessorDef, EntryProcessorResult, HLC, MergeRejection, ConflictResolverDef, MergeContext, MergeResult, IndexedLWWMap, IndexedORMap } from '@topgunbuild/core';
+import { Timestamp, LWWRecord, ORMapRecord, Principal, EventJournalImpl, EventJournalConfig, JournalEvent, PermissionPolicy, ConsistencyLevel, ReplicationConfig, FullTextIndexConfig, LWWMap, ORMap, PermissionType, MigrationConfig, MigrationStatus, MigrationMetrics, PartitionMap, PartitionInfo, PartitionChange, ReplicationLag, ReplicationHealth, ReplicationResult, ClusterReadOptions, MerkleTree, EntryProcessorDef, EntryProcessorResult, HLC, MergeRejection, ConflictResolverDef, MergeContext, MergeResult, IndexedLWWMap, IndexedORMap, SearchUpdateType, FTSSearchOptions, SearchRespPayload, SearchOptions } from '@topgunbuild/core';
 import { WebSocket } from 'ws';
 import { Pool, PoolConfig } from 'pg';
 import pino from 'pino';
@@ -1858,6 +1858,8 @@ interface ServerCoordinatorConfig {
     eventJournalEnabled?: boolean;
     /** Event journal configuration */
     eventJournalConfig?: Partial<Omit<EventJournalServiceConfig, 'pool'>>;
+    /** Enable full-text search for specific maps */
+    fullTextSearch?: Record<string, FullTextIndexConfig>;
 }
 declare class ServerCoordinator {
     private httpServer;
@@ -1906,12 +1908,18 @@ declare class ServerCoordinator {
     private readReplicaHandler?;
     private merkleTreeManager?;
     private repairScheduler?;
+    private searchCoordinator;
     private readonly _nodeId;
     private _actualPort;
     private _actualClusterPort;
     private _readyPromise;
     private _readyResolve;
     constructor(config: ServerCoordinatorConfig);
+    /**
+     * Populate FTS indexes from existing map data.
+     * Called after storage initialization.
+     */
+    private backfillSearchIndexes;
     /** Wait for server to be fully ready (ports assigned) */
     ready(): Promise<void>;
     /**
@@ -1947,6 +1955,37 @@ declare class ServerCoordinator {
     getTaskletSchedulerStats(): TaskletSchedulerStats;
     /** Get tasklet scheduler for scheduling long-running operations */
     getTaskletScheduler(): TaskletScheduler;
+    /**
+     * Enable full-text search for a map.
+     * Can be called at runtime to enable FTS dynamically.
+     *
+     * @param mapName - Name of the map to enable FTS for
+     * @param config - FTS configuration (fields, tokenizer, bm25 options)
+     */
+    enableFullTextSearch(mapName: string, config: FullTextIndexConfig): void;
+    /**
+     * Disable full-text search for a map.
+     *
+     * @param mapName - Name of the map to disable FTS for
+     */
+    disableFullTextSearch(mapName: string): void;
+    /**
+     * Check if full-text search is enabled for a map.
+     *
+     * @param mapName - Name of the map to check
+     * @returns True if FTS is enabled
+     */
+    isFullTextSearchEnabled(mapName: string): boolean;
+    /**
+     * Get FTS index statistics for a map.
+     *
+     * @param mapName - Name of the map
+     * @returns Index stats or null if FTS not enabled
+     */
+    getFullTextSearchStats(mapName: string): {
+        documentCount: number;
+        fields: string[];
+    } | null;
     /**
      * Phase 10.02: Graceful cluster departure
      *
@@ -4442,4 +4481,266 @@ declare class MapFactory {
     getConfig(): ServerIndexConfig;
 }
 
-export { BufferPool, type BufferPoolConfig, type BufferPoolStats, type ClusterConfig, ClusterCoordinator, type ClusterCoordinatorConfig, type ClusterCoordinatorEvents, ClusterManager, type ClusterMember, type ClusterMessage, type CoalescingPreset, type CoalescingWriterMetrics, type CoalescingWriterOptions, ConflictResolverHandler, type ConflictResolverHandlerConfig, ConflictResolverService, type ConflictResolverServiceConfig, type ConnectionContext, ConnectionRateLimiter, DEFAULT_CLUSTER_COORDINATOR_CONFIG, DEFAULT_CONFLICT_RESOLVER_CONFIG, DEFAULT_FAILURE_DETECTOR_CONFIG, DEFAULT_INDEX_CONFIG, DEFAULT_JOURNAL_SERVICE_CONFIG, DEFAULT_LAG_TRACKER_CONFIG, DEFAULT_MERKLE_TREE_CONFIG, DEFAULT_READ_REPLICA_CONFIG, DEFAULT_REASSIGNER_CONFIG, DEFAULT_REPAIR_CONFIG, DEFAULT_SANDBOX_CONFIG, EntryProcessorHandler, type EntryProcessorHandlerConfig, EventJournalService, type EventJournalServiceConfig, type ExportOptions, type FailoverStatus, FailureDetector, type FailureDetectorConfig, type FailureDetectorEvents, FilterTasklet, ForEachTasklet, type IInterceptor, type IServerStorage, type IndexDefinition, IteratorTasklet, type IteratorTaskletConfig, type LagInfo, LagTracker, type LagTrackerConfig, LockManager, type Logger, MapFactory, type MapIndexConfig, MapTasklet, MapWithResolver, type MapWithResolverConfig, MemoryServerAdapter, type MergeWithResolverResult, type MerkleComparisonResult, MerkleTreeManager, type MerkleTreeManagerConfig, MigrationManager, type NativeModuleStatus, type NativeStats, type NodeState, type ORMapTombstones, type ORMapValue, ObjectPool, type ObjectPoolConfig, type ObjectPoolStats, type OpContext, type PartitionDistribution, type PartitionMerkleInfo, PartitionReassigner, type PartitionReassignerConfig, PartitionService, type PartitionServiceConfig, type PartitionServiceEvents, type PooledEventPayload, type PooledMessage, type PooledRecord, type PooledTimestamp, PostgresAdapter, type PostgresAdapterOptions, ProcessorSandbox, type ProcessorSandboxConfig, type ProgressState, RateLimitInterceptor, type RateLimiterConfig, type RateLimiterStats, type ReadReplicaConfig, ReadReplicaHandler, type ReadRequest, type ReadResult, type ReassignmentEvent, ReduceTasklet, type RepairConfig, type RepairMetrics, type RepairResult, RepairScheduler, type RepairTask, ReplicationPipeline, SecurityManager, ServerCoordinator, type ServerCoordinatorConfig, type ServerIndexConfig, type ServerOp, type SetWithResolverResult, type StorageValue, type Tasklet, TaskletScheduler, type TaskletSchedulerConfig, type TaskletSchedulerStats, TimestampInterceptor, coalescingPresets, createEventPayloadPool, createMessagePool, createRecordPool, createTimestampPool, getCoalescingPreset, getGlobalBufferPool, getGlobalEventPayloadPool, getGlobalMessagePool, getGlobalRecordPool, getGlobalTimestampPool, getNativeModuleStatus, getNativeStats, logNativeStatus, logger, mergeWithDefaults, setGlobalBufferPool, setGlobalEventPayloadPool, setGlobalMessagePool, setGlobalRecordPool, setGlobalTimestampPool, validateIndexConfig };
+/**
+ * SearchCoordinator - Server-side Full-Text Search Handler
+ *
+ * Manages FullTextIndex instances per map and handles search requests.
+ * Part of Phase 11.1a: Server-side BM25 Search.
+ * Phase 11.1b: Live Search Subscriptions with delta updates.
+ *
+ * @module search/SearchCoordinator
+ */
+
+/**
+ * Result item returned from server search.
+ */
+interface ServerSearchResult {
+    key: string;
+    value: unknown;
+    score: number;
+    matchedTerms: string[];
+}
+/**
+ * Configuration for enabling search on a map.
+ */
+interface SearchConfig extends FullTextIndexConfig {
+}
+/**
+ * Callback type for sending updates to clients.
+ */
+type SendUpdateCallback = (clientId: string, subscriptionId: string, key: string, value: unknown, score: number, matchedTerms: string[], type: SearchUpdateType) => void;
+/**
+ * Batched update for a single document change.
+ */
+interface BatchedUpdate {
+    key: string;
+    value: unknown;
+    score: number;
+    matchedTerms: string[];
+    type: SearchUpdateType;
+}
+/**
+ * Callback type for sending batched updates to clients.
+ */
+type SendBatchUpdateCallback = (clientId: string, subscriptionId: string, updates: BatchedUpdate[]) => void;
+/**
+ * SearchCoordinator manages full-text search indexes for the server.
+ *
+ * Responsibilities:
+ * - Maintain FullTextIndex per enabled map
+ * - Execute one-shot search queries
+ * - Update indexes when data changes
+ *
+ * @example
+ * ```typescript
+ * const searchCoordinator = new SearchCoordinator();
+ *
+ * // Enable FTS for a map
+ * searchCoordinator.enableSearch('articles', {
+ *   fields: ['title', 'body'],
+ *   tokenizer: { minLength: 2 },
+ *   bm25: { k1: 1.2, b: 0.75 }
+ * });
+ *
+ * // Search
+ * const results = searchCoordinator.search('articles', 'machine learning', {
+ *   limit: 20,
+ *   boost: { title: 2.0 }
+ * });
+ * ```
+ */
+declare class SearchCoordinator {
+    /** Map name → FullTextIndex */
+    private readonly indexes;
+    /** Map name → FullTextIndexConfig (for reference) */
+    private readonly configs;
+    /** Callback to get document value by key (injected by ServerCoordinator) */
+    private getDocumentValue?;
+    /** Subscription ID → SearchSubscription */
+    private readonly subscriptions;
+    /** Map name → Set of subscription IDs */
+    private readonly subscriptionsByMap;
+    /** Client ID → Set of subscription IDs */
+    private readonly subscriptionsByClient;
+    /** Callback for sending updates to clients */
+    private sendUpdate?;
+    /** Callback for sending batched updates to clients */
+    private sendBatchUpdate?;
+    /** Queue of pending notifications per map */
+    private readonly pendingNotifications;
+    /** Timer for batching notifications */
+    private notificationTimer;
+    /** Batch interval in milliseconds (~1 frame at 60fps) */
+    private readonly BATCH_INTERVAL;
+    constructor();
+    /**
+     * Set the callback for sending updates to clients.
+     * Called by ServerCoordinator during initialization.
+     */
+    setSendUpdateCallback(callback: SendUpdateCallback): void;
+    /**
+     * Set the callback for sending batched updates to clients.
+     * When set, notifications are batched within BATCH_INTERVAL (16ms) window.
+     * Called by ServerCoordinator during initialization.
+     *
+     * @param callback - Function to call with batched updates
+     */
+    setSendBatchUpdateCallback(callback: SendBatchUpdateCallback): void;
+    /**
+     * Set the callback for retrieving document values.
+     * Called by ServerCoordinator during initialization.
+     */
+    setDocumentValueGetter(getter: (mapName: string, key: string) => unknown | undefined): void;
+    /**
+     * Enable full-text search for a map.
+     *
+     * @param mapName - Name of the map to enable FTS for
+     * @param config - FTS configuration (fields, tokenizer, bm25 options)
+     */
+    enableSearch(mapName: string, config: SearchConfig): void;
+    /**
+     * Disable full-text search for a map.
+     *
+     * @param mapName - Name of the map to disable FTS for
+     */
+    disableSearch(mapName: string): void;
+    /**
+     * Check if FTS is enabled for a map.
+     */
+    isSearchEnabled(mapName: string): boolean;
+    /**
+     * Get enabled map names.
+     */
+    getEnabledMaps(): string[];
+    /**
+     * Execute a one-shot search query.
+     *
+     * @param mapName - Name of the map to search
+     * @param query - Search query text
+     * @param options - Search options (limit, minScore, boost)
+     * @returns Search response payload
+     */
+    search(mapName: string, query: string, options?: FTSSearchOptions): SearchRespPayload;
+    /**
+     * Handle document set/update.
+     * Called by ServerCoordinator when data changes.
+     *
+     * @param mapName - Name of the map
+     * @param key - Document key
+     * @param value - Document value
+     */
+    onDataChange(mapName: string, key: string, value: Record<string, unknown> | null | undefined, changeType: 'add' | 'update' | 'remove'): void;
+    /**
+     * Build index from existing map entries.
+     * Called when FTS is enabled for a map that already has data.
+     *
+     * @param mapName - Name of the map
+     * @param entries - Iterator of [key, value] tuples
+     */
+    buildIndexFromEntries(mapName: string, entries: Iterable<[string, Record<string, unknown> | null]>): void;
+    /**
+     * Get index statistics for monitoring.
+     */
+    getIndexStats(mapName: string): {
+        documentCount: number;
+        fields: string[];
+    } | null;
+    /**
+     * Clear all indexes (for testing or shutdown).
+     */
+    clear(): void;
+    /**
+     * Subscribe to live search results.
+     * Returns initial results and tracks the subscription for delta updates.
+     *
+     * @param clientId - ID of the subscribing client
+     * @param subscriptionId - Unique subscription identifier
+     * @param mapName - Name of the map to search
+     * @param query - Search query text
+     * @param options - Search options (limit, minScore, boost)
+     * @returns Initial search results
+     */
+    subscribe(clientId: string, subscriptionId: string, mapName: string, query: string, options?: SearchOptions): ServerSearchResult[];
+    /**
+     * Unsubscribe from a live search.
+     *
+     * @param subscriptionId - Subscription to remove
+     */
+    unsubscribe(subscriptionId: string): void;
+    /**
+     * Unsubscribe all subscriptions for a client.
+     * Called when a client disconnects.
+     *
+     * @param clientId - ID of the disconnected client
+     */
+    unsubscribeClient(clientId: string): void;
+    /**
+     * Get the number of active subscriptions.
+     */
+    getSubscriptionCount(): number;
+    /**
+     * Notify subscribers about a document change.
+     * Computes delta (ENTER/UPDATE/LEAVE) for each affected subscription.
+     *
+     * @param mapName - Name of the map that changed
+     * @param key - Document key that changed
+     * @param value - New document value (null if removed)
+     * @param changeType - Type of change
+     */
+    private notifySubscribers;
+    /**
+     * Score a single document against a subscription's query.
+     *
+     * OPTIMIZED: O(Q × D) complexity instead of O(N) full index scan.
+     * Uses pre-tokenized queryTerms and FullTextIndex.scoreSingleDocument().
+     *
+     * @param subscription - The subscription containing query and cached queryTerms
+     * @param key - Document key
+     * @param value - Document value
+     * @param index - The FullTextIndex for this map
+     * @returns Scored result or null if document doesn't match
+     */
+    private scoreDocument;
+    /**
+     * Queue a notification for batched processing.
+     * Notifications are collected and processed together after BATCH_INTERVAL.
+     *
+     * @param mapName - Name of the map that changed
+     * @param key - Document key that changed
+     * @param value - New document value (null if removed)
+     * @param changeType - Type of change
+     */
+    queueNotification(mapName: string, key: string, value: Record<string, unknown> | null, changeType: 'add' | 'update' | 'remove'): void;
+    /**
+     * Schedule a flush of pending notifications.
+     * Uses setTimeout to batch notifications within BATCH_INTERVAL window.
+     */
+    private scheduleNotificationFlush;
+    /**
+     * Flush all pending notifications.
+     * Processes each map's notifications and sends batched updates.
+     */
+    flushNotifications(): void;
+    /**
+     * Process batched notifications for a single map.
+     * Computes updates for each subscription and sends as a batch.
+     *
+     * @param mapName - Name of the map
+     * @param notifications - Array of pending notifications
+     */
+    private processBatchedNotifications;
+    /**
+     * Compute the update for a single document change against a subscription.
+     * Returns null if no update is needed.
+     *
+     * @param subscription - The subscription to check
+     * @param key - Document key
+     * @param value - Document value (null if removed)
+     * @param changeType - Type of change
+     * @param index - The FullTextIndex for this map
+     * @returns BatchedUpdate or null
+     */
+    private computeSubscriptionUpdate;
+}
+
+export { BufferPool, type BufferPoolConfig, type BufferPoolStats, type ClusterConfig, ClusterCoordinator, type ClusterCoordinatorConfig, type ClusterCoordinatorEvents, ClusterManager, type ClusterMember, type ClusterMessage, type CoalescingPreset, type CoalescingWriterMetrics, type CoalescingWriterOptions, ConflictResolverHandler, type ConflictResolverHandlerConfig, ConflictResolverService, type ConflictResolverServiceConfig, type ConnectionContext, ConnectionRateLimiter, DEFAULT_CLUSTER_COORDINATOR_CONFIG, DEFAULT_CONFLICT_RESOLVER_CONFIG, DEFAULT_FAILURE_DETECTOR_CONFIG, DEFAULT_INDEX_CONFIG, DEFAULT_JOURNAL_SERVICE_CONFIG, DEFAULT_LAG_TRACKER_CONFIG, DEFAULT_MERKLE_TREE_CONFIG, DEFAULT_READ_REPLICA_CONFIG, DEFAULT_REASSIGNER_CONFIG, DEFAULT_REPAIR_CONFIG, DEFAULT_SANDBOX_CONFIG, EntryProcessorHandler, type EntryProcessorHandlerConfig, EventJournalService, type EventJournalServiceConfig, type ExportOptions, type FailoverStatus, FailureDetector, type FailureDetectorConfig, type FailureDetectorEvents, FilterTasklet, ForEachTasklet, type IInterceptor, type IServerStorage, type IndexDefinition, IteratorTasklet, type IteratorTaskletConfig, type LagInfo, LagTracker, type LagTrackerConfig, LockManager, type Logger, MapFactory, type MapIndexConfig, MapTasklet, MapWithResolver, type MapWithResolverConfig, MemoryServerAdapter, type MergeWithResolverResult, type MerkleComparisonResult, MerkleTreeManager, type MerkleTreeManagerConfig, MigrationManager, type NativeModuleStatus, type NativeStats, type NodeState, type ORMapTombstones, type ORMapValue, ObjectPool, type ObjectPoolConfig, type ObjectPoolStats, type OpContext, type PartitionDistribution, type PartitionMerkleInfo, PartitionReassigner, type PartitionReassignerConfig, PartitionService, type PartitionServiceConfig, type PartitionServiceEvents, type PooledEventPayload, type PooledMessage, type PooledRecord, type PooledTimestamp, PostgresAdapter, type PostgresAdapterOptions, ProcessorSandbox, type ProcessorSandboxConfig, type ProgressState, RateLimitInterceptor, type RateLimiterConfig, type RateLimiterStats, type ReadReplicaConfig, ReadReplicaHandler, type ReadRequest, type ReadResult, type ReassignmentEvent, ReduceTasklet, type RepairConfig, type RepairMetrics, type RepairResult, RepairScheduler, type RepairTask, ReplicationPipeline, type SearchConfig, SearchCoordinator, SecurityManager, ServerCoordinator, type ServerCoordinatorConfig, type ServerIndexConfig, type ServerOp, type ServerSearchResult, type SetWithResolverResult, type StorageValue, type Tasklet, TaskletScheduler, type TaskletSchedulerConfig, type TaskletSchedulerStats, TimestampInterceptor, coalescingPresets, createEventPayloadPool, createMessagePool, createRecordPool, createTimestampPool, getCoalescingPreset, getGlobalBufferPool, getGlobalEventPayloadPool, getGlobalMessagePool, getGlobalRecordPool, getGlobalTimestampPool, getNativeModuleStatus, getNativeStats, logNativeStatus, logger, mergeWithDefaults, setGlobalBufferPool, setGlobalEventPayloadPool, setGlobalMessagePool, setGlobalRecordPool, setGlobalTimestampPool, validateIndexConfig };