Index Search

/**
 * Basic full-text search index for simple string-based searches
 * @param options - Configuration options or preset name
 */
class Index<W extends WorkerType = false, S extends StorageInterface | boolean = false, R extends boolean = true> {
  constructor(options?: Preset | IndexOptions<S, R>);
  
  /** Database connection for persistent storage */
  db: Promise<S>;
}

/**
 * Add document to index
 * @param id - Unique document identifier
 * @param content - Text content to index
 * @returns Index instance or Promise for chaining
 */
add(id: Id, content: string): W extends false ? this : Promise<this>;

/**
 * Append text to existing document
 * @param id - Document identifier to append to
 * @param content - Additional text content
 * @returns Index instance or Promise for chaining
 */
append(id: Id, content: string): W extends false ? this : Promise<this>;

/**
 * Update existing document content
 * @param id - Document identifier to update
 * @param content - New text content
 * @returns Index instance or Promise for chaining
 */
update(id: Id, content: string): W extends false ? this : Promise<this>;

/**
 * Remove document from index
 * @param id - Document identifier to remove
 * @returns Index instance or Promise for chaining
 */
remove(id: Id): W extends false ? this : Promise<this>;

import { Index } from "flexsearch";

const index = new Index();

// Add documents
index.add(1, "The quick brown fox jumps over the lazy dog");
index.add(2, "A journey of a thousand miles begins with a single step");
index.add(3, "To be or not to be, that is the question");

// Update document
index.update(2, "A journey of a thousand miles begins with one step");

// Append to document
index.append(1, " The fox is very clever.");

// Remove document
index.remove(3);

/**
 * Search index and return matching document IDs
 * @param query - Search query string
 * @param options - Search configuration options
 * @returns Array of matching document IDs or Resolver instance
 */
search<R extends boolean = r>(query: string, options?: SearchOptions<R>): SearchResults<W, S, R>;
search<R extends boolean = r>(options: SearchOptions<R>): SearchResults<W, S, R>;

/**
 * Search with caching enabled for improved performance on repeated queries
 * @param query - Search query string
 * @param options - Search configuration options
 * @returns Cached search results
 */
searchCache<R extends boolean = r>(query: string, options?: SearchOptions<R>): SearchResults<W, S, R>;
searchCache<R extends boolean = r>(options: SearchOptions<R>): SearchResults<W, S, R>;

// Basic search
const results = index.search("quick fox");
console.log(results); // [1]

// Search with options
const limitedResults = index.search("journey", {
  limit: 5,
  suggest: true
});

// Cached search for repeated queries
const cachedResults = index.searchCache("brown");

// Search with suggestions enabled
const suggestedResults = index.search("jurney", { // intentional typo
  suggest: true,
  limit: 3
});

/**
 * Check if document exists in index
 * @param id - Document identifier to check
 * @returns Boolean indicating existence or Promise<boolean> for persistent storage
 */
contain(id: Id): S extends false ? boolean : Promise<boolean>;

/**
 * Clear all documents from index
 * @returns Index instance, void, or Promise depending on configuration
 */
clear(): W extends false ? S extends false ? this : Promise<void> : Promise<void>;

/**
 * Clean up index resources and free memory
 */
cleanup(): void;

// Check if document exists
if (index.contain(1)) {
  console.log("Document 1 exists");
}

// Clear entire index
index.clear();

// Clean up resources
index.cleanup();

/**
 * Asynchronously add document to index
 * @param id - Document identifier
 * @param content - Text content to index
 * @param callback - Optional completion callback
 * @returns Promise resolving to index instance
 */
addAsync(id: Id, content: string, callback?: AsyncCallback<void>): Promise<this>;

/**
 * Asynchronously append content to existing document
 * @param id - Document identifier
 * @param content - Additional text content
 * @param callback - Optional completion callback
 * @returns Promise resolving to index instance
 */
appendAsync(id: Id, content: string, callback?: AsyncCallback<void>): Promise<this>;

/**
 * Asynchronously update document content
 * @param id - Document identifier
 * @param content - New text content
 * @param callback - Optional completion callback
 * @returns Promise resolving to index instance
 */
updateAsync(id: Id, content: string, callback?: AsyncCallback<void>): Promise<this>;

/**
 * Asynchronously remove document from index
 * @param id - Document identifier
 * @param callback - Optional completion callback
 * @returns Promise resolving to index instance
 */
removeAsync(id: Id, callback?: AsyncCallback<void>): Promise<this>;

/**
 * Asynchronously search index
 * @param query - Search query string
 * @param options - Search configuration
 * @param callback - Optional completion callback
 * @returns Promise resolving to search results
 */
searchAsync<R extends boolean = r>(query: string, options?: SearchOptions<R>, callback?: AsyncCallback<SearchResults<W, S, R>>): Promise<SearchResults<W, S, R>>;

/**
 * Asynchronously search with caching
 * @param query - Search query string
 * @param options - Search configuration
 * @param callback - Optional completion callback
 * @returns Promise resolving to cached search results
 */
searchCacheAsync<R extends boolean = r>(query: string, options?: SearchOptions<R>, callback?: AsyncCallback<SearchResults<W, S, R>>): Promise<SearchResults<W, S, R>>;

/**
 * Export index data using a handler function
 * @param handler - Function to handle exported key-value pairs
 * @returns void or Promise<void> for async handlers
 */
export(handler: ExportHandler): void;
export(handler: ExportHandlerAsync): Promise<void>;

/**
 * Import previously exported index data
 * @param key - Data key from export
 * @param data - Serialized data from export
 */
import(key: string, data: string): void;

/**
 * Serialize entire index to string representation
 * @param with_function_wrapper - Include function wrapper in serialization
 * @returns Serialized index as string
 */
serialize(with_function_wrapper?: boolean): SerializedFunctionString;

// Export index data
const exportedData = {};
index.export((key, data) => {
  exportedData[key] = data;
});

// Import index data
Object.entries(exportedData).forEach(([key, data]) => {
  index.import(key, data);
});

// Serialize index
const serialized = index.serialize(true);

/**
 * Mount persistent storage interface to index
 * @param db - Storage interface instance
 * @returns Promise resolving when mount is complete
 */
mount(db: StorageInterface): Promise<void>;

/**
 * Commit pending changes to persistent storage
 * @returns Promise resolving when commit is complete
 */
commit(): Promise<void>;

/**
 * Destroy persistent index and remove all data
 * @returns Promise resolving when destruction is complete
 */
destroy(): Promise<void>;

import IndexedDB from "flexsearch/db/indexeddb";

// Create persistent storage
const storage = new IndexedDB("my-search-index");

// Mount to index
await index.mount(storage);

// Add data - automatically persisted
index.add(1, "Persistent content");

// Manually commit changes
await index.commit();

// Clean up
await index.destroy();

interface IndexOptions<S extends StorageInterface | boolean = false, R extends boolean = true> {
  /** Predefined optimization preset */
  preset?: Preset;
  /** Tokenization strategy */
  tokenize?: Tokenizer;
  /** Enable result caching with optional cache size limit */
  cache?: boolean | number;
  /** Search resolution depth */
  resolution?: number;
  /** Context search configuration */
  context?: ContextOptions | boolean;
  /** Keystore configuration for memory optimization */
  keystore?: number;
  /** Enable fast update mode */
  fastupdate?: boolean;
  /** Processing priority level */
  priority?: number;
  /** Custom scoring function */
  score?: (content: string[], term: string, term_index: number, partial: string, partial_index: number) => number;
  /** Enable result resolution */
  resolve?: R;
  /** Persistent database interface */
  db?: S;
  /** Auto-commit changes to persistent storage */
  commit?: boolean;
  /** Text encoder configuration */
  encoder?: Encoders | EncoderOptions | Encoder;
  /** Custom encoding function */
  encode?: (text: string) => string[];
  /** Right-to-left language support */
  rtl?: boolean;
}

interface SearchOptions<R extends boolean = true> {
  /** Search query string */
  query?: string;
  /** Maximum number of results to return */
  limit?: number;
  /** Number of results to skip */
  offset?: number;
  /** Enable search suggestions for typos */
  suggest?: boolean;
  /** Search resolution level */
  resolution?: number;
  /** Enable context-aware search */
  context?: boolean;
  /** Enable result caching */
  cache?: R extends true ? boolean : false;
  /** Enable result resolution */
  resolve?: R;
}

type Id = number | string;
type Preset = "memory" | "performance" | "match" | "score" | "default";
type Tokenizer = "strict" | "exact" | "default" | "tolerant" | "forward" | "reverse" | "bidirectional" | "full";

type DefaultSearchResults = Id[];
type IntermediateSearchResults = Array<Id[]>;

type SearchResults<W, S, R> = R extends false
  ? Resolver<undefined, W, S>
  : W extends false
    ? S extends false
      ? DefaultSearchResults
      : Promise<DefaultSearchResults>
    : Promise<DefaultSearchResults>;

type ExportHandler = (key: string, data: string) => void;
type ExportHandlerAsync = (key: string, data: string) => Promise<void>;
type AsyncCallback<T> = (result?: T) => void;
type SerializedFunctionString = string;