axiodb/lib/Services/Index/ReadIndex.service.d.ts

The Pure JavaScript Alternative to SQLite. Embedded NoSQL database for Node.js with MongoDB-style queries, zero native dependencies, built-in InMemoryCache, and web GUI. Perfect for desktop apps, CLI tools, and embedded systems. No compilation, no platfor

import { IndexManager } from "./Index.service";
export declare class ReadIndex extends IndexManager {
    private indexCache;
    constructor(path: string);
    /**
     * Retrieve file path(s) from an index that match the provided query.
     *
     * OPTIMIZED: Uses in-memory index cache for O(1) lookups instead of disk I/O.
     * Falls back to disk on cache miss (cold start recovery).
     *
     * @param query - An object containing the value to look up. The concrete lookup key is determined
     *                by the matched index metadata's `fieldName` (i.e. the method will use
     *                query[metaContent.fieldName] to find entries).
     *
     * @returns A Promise that resolves to an array of string file paths associated with the query value.
     *          If no matching index metadata is found, the promise resolves to an empty array.
     *          If a matching index is found but no entries exist for the queried value, the returned
     *          value may be undefined at runtime (callers should guard against a missing entry).
     *
     * @remarks
     * - Tries memory cache first for maximum performance (no disk I/O)
     * - Falls back to disk on cache miss (cold start recovery)
     * - Skips index for complex operators ($regex, $in, $gt, etc.) - full scan required
     *
     * @throws The returned promise will reject if reading or parsing the index file fails (for example,
     *         due to I/O errors or converter failures).
     */
    getFileFromIndex(query: any): Promise<string[]>;
    /**
     * Retrieve file paths from an index for documents matching any value in the $in array.
     *
     * OPTIMIZED: Uses index lookups for each value in the $in array, unions the results.
     * This is significantly faster than full collection scan for indexed fields.
     *
     * @param fieldName - The field name to query (must have an index)
     * @param values - Array of values to match (from $in operator)
     *
     * @returns Promise resolving to array of unique file paths matching any value
     *
     * @remarks
     * - Uses Set for automatic deduplication of file paths
     * - Returns empty array if field has no index
     * - O(K) lookups where K = values.length (much faster than O(N) full scan)
     *
     * @example
     * // For query: { category: { $in: ['Electronics', 'Books'] } }
     * const files = await readIndex.getFilesForInOperator('category', ['Electronics', 'Books']);
     */
    getFilesForInOperator(fieldName: string, values: any[]): Promise<string[]>;
    /**
     * Retrieve file paths from an index for documents where field value starts with a prefix.
     *
     * OPTIMIZED: Uses index to filter values by prefix, avoiding full collection scan.
     * Works with hash-based indexes by filtering index keys.
     *
     * @param fieldName - The field name to query (must have an index)
     * @param prefix - The prefix string to match
     * @param caseInsensitive - Whether to perform case-insensitive matching (default: false)
     *
     * @returns Promise resolving to array of unique file paths where field starts with prefix
     *
     * @remarks
     * - Filters index keys for prefix matches (O(K) where K = index key count)
     * - Much faster than full collection scan for prefix patterns
     * - Falls back to empty array if field has no index
     * - Best used for regex patterns like /^John/ or /^admin@/
     *
     * @example
     * // For query: { name: { $regex: /^John/i } }
     * const files = await readIndex.getFilesForPrefixQuery('name', 'John', true);
     */
    getFilesForPrefixQuery(fieldName: string, prefix: string, caseInsensitive?: boolean): Promise<string[]>;
    /**
   * Finds index metadata entries that correspond to properties present on the provided document.
   *
   * Reads the index metadata file at `this.indexMetaPath`, converts its content into an object,
   * and returns the subset of metadata entries whose `indexFieldName` is an own property of `doc`.
   *
   * @param doc - The document to check for matching index fields. The function tests own properties
   *              (via `Object.prototype.hasOwnProperty.call`) rather than inherited properties.
   * @returns A Promise that resolves to an array of matching index metadata entries, or `undefined`
   *          if the index metadata file could not be successfully read. The array may be empty if
   *          no metadata entries match.
   *
   * @throws May propagate errors from `fileManager.ReadFile` or `converter.ToObject` if those
   *         operations throw or reject.
   */
    protected findMatchingIndexMeta(document: any): Promise<any | undefined>;
}