@b2bc-devkit/sheetorm 1.1.0 → 1.2.3

package/dist/npm/index/IndexStore.js

@@ -1,1102 +0,0 @@
-/**
- * IndexStore — secondary index manager for SheetORM.
- *
- * Manages per-class index sheets that accelerate lookup and full-text
- * search operations.  Each Record class with `@Indexed` fields gets a
- * single index sheet named `idx_{ClassName}s` (e.g. `idx_Cars`).
- *
- * **Sheet layout** (3-column, no header row):
- * ```
- *   Col A (field)    Col B (value)    Col C (entityId)
- *   "brand"          "Toyota"         "abc-123"
- *   "model"          "Corolla"        "abc-123"
- * ```
- *
- * **Search strategy**: Solr-like n-gram search (trigram by default).
- * Text is normalised → tokenised → trigram-indexed.  Queries intersect
- * posting lists and verify candidates with a substring match.
- *
- * **Performance optimisations** (codenames reference the B-series and
- * C-series GAS API reduction work):
- *
- *   - **B3/B5**: Known row count avoids `getAllData()` on the write path.
- *   - **B6**: Empty-table detection skips `getAllData()` entirely.
- *   - **C1**: `createCombinedIndex` seeds `indexRowCount` with one
- *     `getLastRow()` call so subsequent appends never need a full read.
- *   - **J1**: Newly created index sheets skip `setHeaders()` — column
- *     positions are hard-coded (0=field, 1=value, 2=entityId).
- *   - Sheet references are memoised in `indexSheetCache` to avoid
- *     repeated `getSheetByName()` API calls (~300 ms each in GAS).
- *   - Batch mode (`beginIndexBatch` / `flushIndexBatch`) accumulates
- *     all index writes in memory and flushes them in a single
- *     `writeRowsAt()` call per index table.
- *
- * @module IndexStore
- */
-import { SheetOrmLogger } from "../utils/SheetOrmLogger.js";
-/**
- * Manages secondary index sheets and provides n-gram text search.
- *
- * One IndexStore instance is owned by a {@link Registry} and shared
- * across all SheetRepository instances created from that registry.
- */
-export class IndexStore {
-    /**
-     * @param adapter - Spreadsheet adapter for sheet-level operations.
-     * @param cache   - Optional cache provider (e.g. MemoryCache) for index data.
-     */
-    constructor(adapter, cache) {
-        /** Registry of all declared indexes: key = "tableName::field" → IndexMeta. */
-        this.indexRegistry = new Map();
-        /** Lazy-built n-gram search indexes, keyed by "tableName::field". */
-        this.searchIndexCache = new Map();
-        /** Pending batch writes (tableName → rows), or null when batch mode is off. */
-        this.indexBatch = null;
-        /** Memoised sheet references — avoids duplicate getSheetByName() API calls within a session. */
-        this.indexSheetCache = new Map();
-        /** Tracks known row count per index table — avoids full getAllData() reads to determine append position. */
-        this.indexRowCount = new Map();
-        this.adapter = adapter;
-        this.cache = cache ?? null;
-    }
-    /**
-     * Build a composite registry key for a (tableName, field) pair.
-     * Used as the key in `indexRegistry` and for search cache invalidation.
-     */
-    registryKey(tableName, field) {
-        return `${tableName}::${field}`;
-    }
-    /**
-     * Retrieve all registered {@link IndexMeta} entries for a given table.
-     *
-     * @param tableName - Index table name (e.g. `"idx_Cars"`).
-     * @returns Array of IndexMeta for every indexed field in that table.
-     */
-    getIndexedFields(tableName) {
-        const result = [];
-        for (const meta of this.indexRegistry.values()) {
-            if (meta.tableName === tableName) {
-                result.push(meta);
-            }
-        }
-        return result;
-    }
-    /**
-     * Register an indexed field during schema initialisation.
-     *
-     * Called by {@link Registry.registerClass} for each `@Indexed` decorator
-     * found on a Record subclass.
-     *
-     * @param tableName - Index table name (e.g. `"idx_Cars"`).
-     * @param field     - Field name to index (e.g. `"brand"`).
-     * @param unique    - Whether the index enforces uniqueness.
-     */
-    registerIndex(tableName, field, unique) {
-        this.indexRegistry.set(this.registryKey(tableName, field), {
-            tableName,
-            field,
-            unique,
-        });
-    }
-    // ─── Batch index write buffering ────────────────────────────────────────────
-    // When batch mode is active (`indexBatch !== null`), all index writes are
-    // accumulated in an in-memory Map instead of hitting the sheet immediately.
-    // `flushIndexBatch()` writes all buffered rows in a single `writeRowsAt()`
-    // call per index table, reducing GAS API round-trips from N to 1.
-    /**
-     * Activate batch mode — subsequent `addAllFieldsToCombined` calls will
-     * buffer rows instead of writing to the sheet.
-     *
-     * Must be paired with either {@link flushIndexBatch} (commit) or
-     * {@link cancelIndexBatch} (rollback).
-     */
-    beginIndexBatch() {
-        this.indexBatch = new Map();
-        SheetOrmLogger.log(`[Index] beginIndexBatch`);
-    }
-    /**
-     * Flush all buffered index rows to their respective index sheets.
-     *
-     * For each index table with pending rows:
-     * - **With cache**: reads combined data, appends rows via `writeRowsAt`,
-     *   and updates the in-memory cache array.
-     * - **Without cache (B5)**: uses the known row count to write at the
-     *   correct offset, or falls back to `appendRows`.
-     *
-     * After flushing, batch mode is deactivated and the search index cache
-     * is invalidated for affected tables.
-     */
-    flushIndexBatch() {
-        if (!this.indexBatch)
-            return;
-        const batch = this.indexBatch;
-        this.indexBatch = null; // Deactivate batch mode before writing
-        for (const [indexTableName, rows] of batch) {
-            if (rows.length === 0)
-                continue;
-            const sheet = this.getIndexSheet(indexTableName);
-            if (!sheet)
-                continue;
-            SheetOrmLogger.log(`[Index:${indexTableName}] flushIndexBatch ${rows.length} rows`);
-            if (this.cache) {
-                // Cache path: read existing data, append new rows, update cache
-                const data = this.getCombinedData(indexTableName);
-                sheet.writeRowsAt(data.length, rows);
-                for (const row of rows)
-                    data.push(row);
-                this.indexRowCount.set(indexTableName, data.length);
-                this.invalidateSearchCacheForTable(indexTableName);
-            }
-            else {
-                // No-cache path: use known row count to avoid getAllData()
-                const knownCount = this.indexRowCount.get(indexTableName);
-                if (knownCount !== undefined) {
-                    sheet.writeRowsAt(knownCount, rows);
-                    this.indexRowCount.set(indexTableName, knownCount + rows.length);
-                }
-                else {
-                    // Fallback: let the adapter append (position unknown)
-                    sheet.appendRows(rows);
-                }
-                this.invalidateSearchCacheForTable(indexTableName);
-            }
-        }
-    }
-    /**
-     * Discard all buffered index rows without writing (error/rollback path).
-     */
-    cancelIndexBatch() {
-        SheetOrmLogger.log(`[Index] cancelIndexBatch`);
-        this.indexBatch = null;
-    }
-    /**
-     * Return a memoised sheet reference for the given index table name.
-     *
-     * On the first call for a table name, delegates to `adapter.getSheetByName()`
-     * (a GAS API call costing ~300 ms).  Subsequent calls return the cached
-     * reference from `indexSheetCache`.
-     *
-     * @param indexTableName - Sheet name (e.g. `"idx_Cars"`).
-     * @returns Sheet adapter, or `null` if the sheet does not exist.
-     */
-    getIndexSheet(indexTableName) {
-        const cached = this.indexSheetCache.get(indexTableName);
-        if (cached !== undefined)
-            return cached;
-        const sheet = this.adapter.getSheetByName(indexTableName);
-        if (sheet)
-            this.indexSheetCache.set(indexTableName, sheet);
-        return sheet;
-    }
-    // ─── Combined (per-class) index sheet methods ───────────────────────────────
-    // Each Record class with @Indexed fields gets ONE index sheet named
-    // idx_{ClassName}s.  All indexed fields for that class share the sheet,
-    // distinguished by column A ("field").
-    /**
-     * Create or recognise the combined index sheet for a Record class.
-     *
-     * - If the sheet does **not** exist: creates it via `insertSheet()` and
-     *   skips the header row (no header row needed in index sheets).
-     * - If the sheet **already** exists: seeds `indexRowCount` with a single
-     *   `getLastRow()` call so subsequent writes can append without reading all data.
-     *
-     * The caller can pass a pre-loaded sheet reference or `null` (confirmed
-     * non-existent) to avoid a redundant `getSheetByName()` lookup.
-     *
-     * @param indexTableName  - Sheet name (e.g. `"idx_Cars"`).
-     * @param preloadedSheet  - Optional: already-fetched sheet, or `null` to
-     *                          signal the sheet definitely does not exist.
-     */
-    createCombinedIndex(indexTableName, preloadedSheet) {
-        // undefined = not provided (fall back to getSheetByName)
-        // null      = caller confirmed the sheet does not exist (skip getSheetByName, go straight to insertSheet)
-        // ISheetAdapter = use this sheet directly
-        const existing = preloadedSheet !== undefined ? preloadedSheet : this.adapter.getSheetByName(indexTableName);
-        if (!existing) {
-            // Create new index sheet — no header row needed (column positions are hard-coded)
-            const sheet = this.adapter.insertSheet(indexTableName);
-            this.indexSheetCache.set(indexTableName, sheet);
-            this.indexRowCount.set(indexTableName, 0); // Brand new sheet has 0 data rows
-            SheetOrmLogger.log(`[Index] createCombinedIndex "${indexTableName}" → insertSheet (J1 no-header) rowCount=0`);
-        }
-        else {
-            // Sheet already exists — seed row count with one getLastRow() call
-            this.indexSheetCache.set(indexTableName, existing);
-            const rowCount = existing.getRowCount();
-            this.indexRowCount.set(indexTableName, rowCount);
-            SheetOrmLogger.log(`[Index] createCombinedIndex "${indexTableName}" → existing (C1) rowCount=${rowCount}`);
-        }
-    }
-    /**
-     * Check whether a combined index sheet exists for the given table name.
-     * Uses the memoised sheet cache when available.
-     */
-    existsCombined(indexTableName) {
-        return this.getIndexSheet(indexTableName) !== null;
-    }
-    /**
-     * Add a single (field, value, entityId) entry to the combined index sheet.
-     *
-     * Enforces unique index constraints: if a unique index already contains
-     * the value for a different entity, throws an error.
-     *
-     * @param indexTableName - Sheet name.
-     * @param field          - Indexed field name.
-     * @param value          - Field value to index.
-     * @param entityId       - Owning entity's UUID.
-     * @throws Error on unique index violation.
-     */
-    addToCombined(indexTableName, field, value, entityId) {
-        const meta = this.indexRegistry.get(this.registryKey(indexTableName, field));
-        const sheet = this.getIndexSheet(indexTableName);
-        if (!sheet)
-            return;
-        const valueStr = String(value);
-        // Unique constraint check: scan existing data for duplicate values
-        if (meta?.unique) {
-            const data = this.getCombinedData(indexTableName);
-            for (let i = 0; i < data.length; i++) {
-                if (String(data[i][0]) === field && String(data[i][1]) === valueStr) {
-                    if (String(data[i][2]) !== entityId) {
-                        throw new Error(`Unique index violation: ${indexTableName}.${field} already has value "${valueStr}" for entity ${String(data[i][2])}`);
-                    }
-                    // Same entity already indexed with this value — no-op
-                    return;
-                }
-            }
-        }
-        const newRow = [field, valueStr, entityId];
-        if (this.cache) {
-            // Cache path: append to both the sheet and the in-memory cache array
-            const data = this.getCombinedData(indexTableName);
-            sheet.writeRowsAt(data.length, [newRow]);
-            data.push(newRow);
-            this.indexRowCount.set(indexTableName, data.length);
-            this.searchIndexCache.delete(`${this.registryKey(indexTableName, field)}`);
-        }
-        else {
-            // No-cache path: use known row count or fall back to appendRow
-            const knownCount = this.indexRowCount.get(indexTableName);
-            if (knownCount !== undefined) {
-                sheet.writeRowsAt(knownCount, [newRow]);
-                this.indexRowCount.set(indexTableName, knownCount + 1);
-            }
-            else {
-                sheet.appendRow(newRow);
-            }
-            this.invalidateSearchCacheForTable(indexTableName);
-        }
-    }
-    /**
-     * Add index entries for **all** indexed fields of a single entity in one
-     * batch operation.  Reduces N separate `appendRow()` API calls to a single
-     * `writeRowsAt()` call (or buffers them if batch mode is active).
-     *
-     * Unique constraint checks are performed against both the existing sheet
-     * data AND any pending (unflushed) batch entries.
-     *
-     * @param indexTableName - Sheet name.
-     * @param entries        - Array of { field, value } pairs to index.
-     * @param entityId       - Owning entity's UUID.
-     * @throws Error on unique index violation.
-     */
-    addAllFieldsToCombined(indexTableName, entries, entityId) {
-        // Do NOT call getSheetByName here — in batch mode the sheet is never needed
-        // for the write path; fetching it per-entity causes 1000× GAS API calls.
-        const rows = [];
-        let data = null;
-        for (const { field, value } of entries) {
-            const valueStr = String(value);
-            const meta = this.indexRegistry.get(this.registryKey(indexTableName, field));
-            // Unique constraint check: scan existing data + pending batch entries
-            if (meta?.unique) {
-                if (!data)
-                    data = this.getCombinedData(indexTableName);
-                let alreadyIndexed = false;
-                // Check existing (committed) sheet data
-                for (let i = 0; i < data.length; i++) {
-                    if (String(data[i][0]) === field && String(data[i][1]) === valueStr) {
-                        if (String(data[i][2]) !== entityId) {
-                            throw new Error(`Unique index violation: ${indexTableName}.${field} already has value "${valueStr}" for entity ${String(data[i][2])}`);
-                        }
-                        alreadyIndexed = true;
-                        break;
-                    }
-                }
-                // Also check pending (unflushed) batch entries for the same table
-                if (!alreadyIndexed && this.indexBatch !== null) {
-                    const pending = this.indexBatch.get(indexTableName);
-                    if (pending) {
-                        for (let i = 0; i < pending.length; i++) {
-                            if (String(pending[i][0]) === field && String(pending[i][1]) === valueStr) {
-                                if (String(pending[i][2]) !== entityId) {
-                                    throw new Error(`Unique index violation: ${indexTableName}.${field} already has value "${valueStr}" for entity ${String(pending[i][2])}`);
-                                }
-                                alreadyIndexed = true;
-                                break;
-                            }
-                        }
-                    }
-                }
-                if (alreadyIndexed)
-                    continue; // Value already indexed for this entity — skip
-            }
-            rows.push([field, valueStr, entityId]);
-        }
-        if (rows.length > 0) {
-            if (this.indexBatch !== null) {
-                // ── Batch mode: accumulate rows in memory, no sheet API call needed ──
-                let pending = this.indexBatch.get(indexTableName);
-                if (!pending) {
-                    pending = [];
-                    this.indexBatch.set(indexTableName, pending);
-                }
-                for (const row of rows)
-                    pending.push(row);
-                return;
-            }
-            // ── Non-batch mode: write to sheet immediately ──
-            SheetOrmLogger.log(`[Index:${indexTableName}] addAllFieldsToCombined — non-batch, writing ${rows.length} rows entity=${entityId.slice(0, 8)}`);
-            if (this.cache) {
-                // Cache-enabled path: tries three strategies in order of cheapness:
-                //   1. Cache HIT   → use cached array length as append offset
-                //   2. Seeded row count → previously seeded by createCombinedIndex
-                //   3. Fallback     → full getAllData() read
-                const sheet = this.getIndexSheet(indexTableName);
-                if (!sheet)
-                    return;
-                const cacheKey = `cidx:${indexTableName}`;
-                const cachedData = this.cache.get(cacheKey);
-                if (cachedData !== null) {
-                    // Strategy 1: cache HIT — append at cached length
-                    sheet.writeRowsAt(cachedData.length, rows);
-                    for (const row of rows)
-                        cachedData.push(row);
-                    this.indexRowCount.set(indexTableName, cachedData.length);
-                }
-                else {
-                    const knownCount = this.indexRowCount.get(indexTableName);
-                    if (knownCount !== undefined) {
-                        // Strategy 2 (C1): row count known — skip getAllData()
-                        sheet.writeRowsAt(knownCount, rows);
-                        this.indexRowCount.set(indexTableName, knownCount + rows.length);
-                    }
-                    else {
-                        // Strategy 3: fallback — full read, then append
-                        const cacheData = this.getCombinedData(indexTableName);
-                        sheet.writeRowsAt(cacheData.length, rows);
-                        for (const row of rows)
-                            cacheData.push(row);
-                        this.indexRowCount.set(indexTableName, cacheData.length);
-                    }
-                }
-                this.searchIndexCache.clear(); // Invalidate n-gram search caches
-            }
-            else {
-                // No-cache path (B3): use known row count to avoid appendRows
-                const sheet = this.getIndexSheet(indexTableName);
-                if (!sheet)
-                    return;
-                const knownCount = this.indexRowCount.get(indexTableName);
-                if (knownCount !== undefined) {
-                    sheet.writeRowsAt(knownCount, rows);
-                    this.indexRowCount.set(indexTableName, knownCount + rows.length);
-                }
-                else {
-                    // Fallback: position unknown, let adapter append
-                    sheet.appendRows(rows);
-                }
-                this.searchIndexCache.clear(); // Invalidate n-gram search caches
-            }
-        }
-    }
-    /**
-     * Remove **all** index entries for a single entity from the combined sheet.
-     *
-     * Reads the sheet data once, filters out rows belonging to `entityId`,
-     * and rewrites the entire sheet with `replaceAllData()`.  This is far
-     * cheaper than N individual `deleteRow()` calls (each ~300 ms in GAS
-     * plus O(n) row-shifting).
-     *
-     * @param indexTableName - Sheet name.
-     * @param entityId       - Entity UUID whose entries should be removed.
-     */
-    removeAllFromCombined(indexTableName, entityId) {
-        const sheet = this.getIndexSheet(indexTableName);
-        if (!sheet)
-            return;
-        const data = this.getCombinedData(indexTableName);
-        const remaining = data.filter((row) => String(row[2]) !== entityId);
-        if (remaining.length === data.length)
-            return; // Nothing to remove
-        // Bulk rewrite: single replaceAllData() replaces N deleteRow() calls
-        sheet.replaceAllData(remaining);
-        this.indexRowCount.set(indexTableName, remaining.length);
-        if (this.cache) {
-            this.cache.set(`cidx:${indexTableName}`, remaining);
-            this.searchIndexCache.clear();
-        }
-        else {
-            this.clearCache();
-        }
-    }
-    /**
-     * Remove index entries for **multiple** entities in a single bulk operation.
-     *
-     * Reads sheet data once, filters out all rows whose entityId is in the
-     * provided set, and rewrites with `replaceAllData()`.  Use this instead
-     * of calling `removeAllFromCombined()` in a loop — it avoids N redundant
-     * sheet reads and writes.
-     *
-     * @param indexTableName - Sheet name.
-     * @param entityIds      - Array of entity UUIDs to remove.
-     */
-    removeMultipleFromCombined(indexTableName, entityIds) {
-        if (entityIds.length === 0)
-            return;
-        const sheet = this.getIndexSheet(indexTableName);
-        if (!sheet)
-            return;
-        // Convert to Set for O(1) membership checks during filtering
-        const idSet = new Set(entityIds);
-        const data = this.getCombinedData(indexTableName);
-        const remaining = data.filter((row) => !idSet.has(String(row[2])));
-        if (remaining.length === data.length)
-            return; // No matching rows found
-        sheet.replaceAllData(remaining);
-        this.indexRowCount.set(indexTableName, remaining.length);
-        if (this.cache) {
-            this.cache.set(`cidx:${indexTableName}`, remaining);
-            this.searchIndexCache.clear();
-        }
-        else {
-            this.clearCache();
-        }
-    }
-    /**
-     * Update index entries for an entity after its field values have changed.
-     *
-     * Reads the sheet data **once**, diffs old vs new values for each indexed
-     * field, then applies the minimal set of writes.  Two paths exist:
-     *
-     * 1. **In-place update** (fast): when no field is being cleared (old→null),
-     *    each changed row is overwritten at its current position with a single
-     *    `writeRowsAt()`.  New fields that previously had no value are appended.
-     * 2. **Fallback delete+insert**: when a field is cleared, the affected rows
-     *    are removed with `replaceAllData()` and new rows appended.
-     *
-     * Unique constraint checks run on the snapshot **before** any writes to
-     * prevent inconsistent state.
-     *
-     * @param indexTableName - Sheet name.
-     * @param entityId       - Entity UUID.
-     * @param oldValues      - Previous field values (before the update).
-     * @param newValues      - New field values (after the update).
-     * @throws Error on unique index violation.
-     */
-    updateInCombined(indexTableName, entityId, oldValues, newValues) {
-        const sheet = this.getIndexSheet(indexTableName);
-        if (!sheet)
-            return;
-        const indexedFields = this.getIndexedFields(indexTableName);
-        const changes = [];
-        for (const meta of indexedFields) {
-            const field = meta.field;
-            const oldVal = oldValues[field];
-            const newVal = newValues[field];
-            if (oldVal === newVal)
-                continue; // No change for this field
-            // Convert to string form (null/undefined/empty → null = "field has no value")
-            const oldStr = oldVal !== undefined && oldVal !== null && oldVal !== "" ? String(oldVal) : null;
-            const newStr = newVal !== undefined && newVal !== null && newVal !== "" ? String(newVal) : null;
-            changes.push({ field, oldStr, newStr, unique: meta.unique });
-        }
-        if (changes.length === 0)
-            return; // No indexed fields changed
-        // Read sheet data ONCE (may hit getCombinedData cache)
-        const data = this.getCombinedData(indexTableName);
-        // ── Uniqueness pre-check: validate all new values before any writes ──
-        for (const { field, newStr, unique } of changes) {
-            if (newStr !== null && unique) {
-                for (let i = 0; i < data.length; i++) {
-                    if (String(data[i][0]) === field &&
-                        String(data[i][1]) === newStr &&
-                        String(data[i][2]) !== entityId) {
-                        throw new Error(`Unique index violation: ${indexTableName}.${field} already has value "${newStr}" for entity ${String(data[i][2])}`);
-                    }
-                }
-            }
-        }
-        // ── Path 1: In-place update (no field is being cleared) ─────────────────
-        // When every change has a non-null newStr, we can overwrite each index row
-        // at its existing position.  This avoids replaceAllData()/deleteRow() which
-        // are expensive in GAS (~300 ms per deleteRow + O(n) row-shifting).
-        const hasPureDeletion = changes.some((c) => c.oldStr !== null && c.newStr === null);
-        if (!hasPureDeletion) {
-            // Build field → old/new string maps for single-pass lookup
-            const fieldOldMapOpt = new Map();
-            const fieldNewMapOpt = new Map();
-            for (const { field, oldStr, newStr } of changes) {
-                if (oldStr !== null)
-                    fieldOldMapOpt.set(field, oldStr);
-                if (newStr !== null)
-                    fieldNewMapOpt.set(field, newStr);
-            }
-            // Single pass over data: find rows matching (field, oldValue, entityId) and overwrite
-            for (let i = 0; i < data.length; i++) {
-                const fc = String(data[i][0]);
-                const oldStr = fieldOldMapOpt.get(fc);
-                if (oldStr === undefined || String(data[i][1]) !== oldStr || String(data[i][2]) !== entityId)
-                    continue;
-                const newStr = fieldNewMapOpt.get(fc);
-                if (newStr !== undefined) {
-                    const newRow = [fc, newStr, entityId];
-                    sheet.writeRowsAt(i, [newRow]); // Overwrite in-place
-                    data[i] = newRow; // Keep cache consistent
-                }
-            }
-            // Handle pure insertions: field was empty/null → now has a value (no existing row to overwrite)
-            const insertRows = changes
-                .filter((c) => c.oldStr === null && c.newStr !== null)
-                .map((c) => [c.field, c.newStr, entityId]);
-            if (insertRows.length > 0) {
-                if (this.cache) {
-                    sheet.writeRowsAt(data.length, insertRows);
-                    for (const r of insertRows)
-                        data.push(r);
-                    this.indexRowCount.set(indexTableName, data.length);
-                }
-                else {
-                    for (const r of insertRows)
-                        sheet.appendRow(r);
-                    const prev = this.indexRowCount.get(indexTableName);
-                    if (prev !== undefined)
-                        this.indexRowCount.set(indexTableName, prev + insertRows.length);
-                }
-            }
-            if (!this.cache)
-                this.clearCache();
-            else
-                this.searchIndexCache.clear();
-            return;
-        }
-        // ── Fallback path: handles clearing a field to empty/null (pure deletion) ─
-        const fieldOldMap = new Map();
-        for (const { field, oldStr } of changes) {
-            if (oldStr !== null)
-                fieldOldMap.set(field, oldStr);
-        }
-        const rowsToDelete = [];
-        for (let i = 0; i < data.length; i++) {
-            const fc = String(data[i][0]);
-            const oldStr = fieldOldMap.get(fc);
-            if (oldStr !== undefined && String(data[i][1]) === oldStr && String(data[i][2]) === entityId) {
-                rowsToDelete.push(i);
-            }
-        }
-        // ── Path 2: Fallback delete+insert (a field is being cleared) ─────────
-        // When a field value is set to empty/null, the corresponding index row
-        // must be removed.  We filter out stale rows, rewrite the sheet with
-        // replaceAllData(), then append new entries.
-        // Single replaceAllData instead of N individual deleteRow() calls —
-        // avoids the O(n) row-shift cost per call in GAS.
-        const deleteSet = new Set(rowsToDelete);
-        const filteredData = data.filter((_, i) => !deleteSet.has(i));
-        sheet.replaceAllData(filteredData);
-        // Update cached array reference in-place so subsequent writes land at correct offset
-        data.length = 0;
-        for (const row of filteredData)
-            data.push(row);
-        this.indexRowCount.set(indexTableName, data.length);
-        // Append new index entries for changed fields in a single batch
-        const newRows = [];
-        for (const { field, newStr } of changes) {
-            if (newStr !== null) {
-                newRows.push([field, newStr, entityId]);
-            }
-        }
-        if (newRows.length > 0) {
-            if (this.cache) {
-                sheet.writeRowsAt(data.length, newRows);
-                for (const row of newRows)
-                    data.push(row);
-                this.indexRowCount.set(indexTableName, data.length);
-                this.searchIndexCache.clear();
-            }
-            else {
-                for (const row of newRows)
-                    sheet.appendRow(row);
-                const prev = this.indexRowCount.get(indexTableName);
-                if (prev !== undefined)
-                    this.indexRowCount.set(indexTableName, prev + newRows.length);
-                this.clearCache();
-            }
-        }
-        else if (!this.cache) {
-            this.clearCache();
-        }
-        else {
-            this.searchIndexCache.clear();
-        }
-    }
-    /**
-     * Look up entity IDs that match a specific (field, value) pair in the index.
-     *
-     * Performs a linear scan of the combined data.  Deduplicates results
-     * using a Set to handle potential index corruption.
-     *
-     * @param indexTableName - Sheet name.
-     * @param field          - Indexed field name.
-     * @param value          - Value to look up.
-     * @returns Array of matching entity UUIDs (deduplicated).
-     */
-    lookupCombined(indexTableName, field, value) {
-        const data = this.getCombinedData(indexTableName);
-        const valueStr = String(value);
-        const seen = new Set();
-        const ids = [];
-        for (let i = 0; i < data.length; i++) {
-            if (String(data[i][0]) === field && String(data[i][1]) === valueStr) {
-                const id = String(data[i][2]);
-                if (!seen.has(id)) {
-                    seen.add(id);
-                    ids.push(id);
-                }
-            }
-        }
-        return ids;
-    }
-    /**
-     * Delete an entire combined index sheet and unregister all its fields.
-     *
-     * The sheet is physically deleted via the adapter, all caches are cleared,
-     * and the field registry entries are removed.  Cache must be cleared
-     * **before** removing registry entries because `clearCache()` iterates
-     * the registry to find cache keys to invalidate.
-     *
-     * @param indexTableName - Sheet name to drop.
-     */
-    dropCombinedIndex(indexTableName) {
-        this.adapter.deleteSheet(indexTableName);
-        this.indexSheetCache.delete(indexTableName);
-        this.indexRowCount.delete(indexTableName);
-        // Clear cache BEFORE removing registry entries — clearCache() reads indexRegistry
-        this.clearCache();
-        for (const [key, meta] of this.indexRegistry.entries()) {
-            if (meta.tableName === indexTableName) {
-                this.indexRegistry.delete(key);
-            }
-        }
-    }
-    // ─── N-gram search (Solr-like approach) ──────────────────────────────────
-    // Text search uses a Solr-inspired algorithm originally developed for the
-    // TyreSizeCatalog project.  The approach:
-    //   1. Normalise text → lowercase, collapse separators/whitespace.
-    //   2. Tokenise → split on spaces.
-    //   3. Build trigram posting lists for each indexed value.
-    //   4. At query time, intersect posting lists for query trigrams.
-    //   5. Verify surviving candidates with a substring match.
-    /**
-     * Normalise a string for search indexing and querying.
-     *
-     * Steps: lowercase → trim → convert dashes/underscores/em-dashes to spaces
-     * → remove commas → collapse whitespace.
-     *
-     * @param s - Raw string to normalise.
-     * @returns Normalised lowercase string.
-     */
-    static normalizeForSearch(s) {
-        if (!s)
-            return "";
-        let t = s.toLowerCase().trim();
-        // Convert dashes, em-dashes, underscores → space for uniform tokenisation
-        t = t.replace(/[\u2010-\u2015\-\u2013\u2014_]/g, " ");
-        // Remove commas
-        t = t.replace(/,/g, " ");
-        // Collapse whitespace
-        t = t.replace(/\s+/g, " ").trim();
-        return t;
-    }
-    /**
-     * Tokenise a normalised string into individual search tokens.
-     *
-     * @param normalized - Already-normalised string (via {@link normalizeForSearch}).
-     * @returns Array of non-empty tokens split on spaces.
-     */
-    static tokenize(normalized) {
-        if (!normalized)
-            return [];
-        return normalized.split(" ").filter((t) => t.length > 0);
-    }
-    /**
-     * Generate character-level n-grams from a string.
-     *
-     * Whitespace is stripped before generating grams so that token boundaries
-     * do not create artificial gaps.  For the default `NGRAM_SIZE = 3`, the
-     * string "toyota" produces {"toy", "oyo", "yot", "ota"}.
-     *
-     * @param s - Input string.
-     * @param n - N-gram length (typically 3 = trigram).
-     * @returns Set of unique n-gram substrings.
-     */
-    static ngrams(s, n) {
-        const out = new Set();
-        if (!s)
-            return out;
-        const t = s.replace(/\s+/g, ""); // Strip whitespace for contiguous grams
-        if (t.length < n)
-            return out;
-        for (let i = 0; i <= t.length - n; i++) {
-            out.add(t.substring(i, i + n));
-        }
-        return out;
-    }
-    /**
-     * Build an in-memory {@link SearchIndex} for a (tableName, field) pair.
-     *
-     * Scans all index rows for `field`, normalises each value, and builds:
-     *   - **Token postings**: exact-token → list of entry indices.
-     *   - **Trigram postings**: character-trigram → list of entry indices.
-     *     Trigrams are generated from both individual tokens and the
-     *     compacted (whitespace-free) normalised form.
-     *
-     * The result is cached in `searchIndexCache` and reused until the
-     * index table is modified.
-     *
-     * @param indexTableName - Sheet name.
-     * @param field          - Indexed field to build the search index for.
-     * @returns Fully populated SearchIndex.
-     */
-    buildSearchIndex(indexTableName, field) {
-        const data = this.getCombinedData(indexTableName);
-        const entries = [];
-        const normalized = [];
-        const tokenIndex = new Map(); // token → posting list
-        const ngramIndex = new Map(); // trigram → posting list
-        {
-            // Iterate over every row in the raw index data looking for rows belonging
-            // to `field`.  Each matching row contributes one entry to the search index.
-            for (let i = 0; i < data.length; i++) {
-                if (String(data[i][0]) !== field)
-                    continue; // Skip rows for other fields
-                const value = String(data[i][1]);
-                const entityId = String(data[i][2]);
-                const idx = entries.length; // Ordinal position within entries array
-                entries.push({ value, entityId });
-                const norm = IndexStore.normalizeForSearch(value);
-                normalized.push(norm);
-                // --- Token postings ---
-                // Split the normalised text into tokens and record which entry index
-                // each token appears in.  This allows O(1) exact-token lookup later.
-                const tokens = IndexStore.tokenize(norm);
-                for (const tk of tokens) {
-                    let postings = tokenIndex.get(tk);
-                    if (!postings) {
-                        postings = [];
-                        tokenIndex.set(tk, postings);
-                    }
-                    postings.push(idx);
-                }
-                // --- Trigram postings ---
-                // Collect trigrams from two sources:
-                //   1. Individual tokens  — captures within-word substrings.
-                //   2. Compacted (no-space) normalised form — captures cross-word
-                //      substrings for multi-word fuzzy matching.
-                const ngs = new Set();
-                for (const tk of tokens) {
-                    for (const ng of IndexStore.ngrams(tk, IndexStore.NGRAM_SIZE))
-                        ngs.add(ng);
-                }
-                for (const ng of IndexStore.ngrams(norm.replace(/ /g, ""), IndexStore.NGRAM_SIZE))
-                    ngs.add(ng);
-                for (const ng of ngs) {
-                    let postings = ngramIndex.get(ng);
-                    if (!postings) {
-                        postings = [];
-                        ngramIndex.set(ng, postings);
-                    }
-                    postings.push(idx);
-                }
-            }
-        }
-        return { entries, normalized, tokenIndex, ngramIndex };
-    }
-    /**
-     * Approximate a token's posting list using trigram intersection.
-     *
-     * When a query token does not appear verbatim in the `tokenIndex`, we
-     * fall back to n-gram matching: decompose the token into trigrams, look
-     * up each trigram's posting list, and intersect them all.  This yields
-     * candidate entries that share every trigram with the query token —
-     * a superset of true matches that is refined later by substring
-     * verification in {@link searchCombined}.
-     *
-     * @param token      - The query token to approximate.
-     * @param ngramIndex - Trigram → posting-list map from the search index.
-     * @returns Intersection of all trigram posting lists / empty if a trigram is missing.
-     */
-    static postingsForTokenViaNgrams(token, ngramIndex) {
-        const ngs = IndexStore.ngrams(token, IndexStore.NGRAM_SIZE);
-        if (ngs.size === 0)
-            return []; // Token too short for any trigram
-        const lists = [];
-        for (const ng of ngs) {
-            const p = ngramIndex.get(ng);
-            if (!p)
-                return []; // A missing trigram means no entry can match
-            lists.push(p);
-        }
-        // Sort shortest-first so that each intersection step works on the
-        // smallest possible set, improving performance.
-        lists.sort((a, b) => a.length - b.length);
-        return IndexStore.intersectPostingLists(lists);
-    }
-    /**
-     * Intersect N sorted posting lists into a single sorted result.
-     *
-     * Reduces pairwise from the first list onward.  Callers typically
-     * pre-sort the input lists by ascending length so the intermediate
-     * result stays small.
-     *
-     * @param lists - Array of sorted posting lists.
-     * @returns Sorted array of indices present in every input list.
-     */
-    static intersectPostingLists(lists) {
-        if (lists.length === 0)
-            return [];
-        let result = lists[0];
-        for (let i = 1; i < lists.length; i++) {
-            result = IndexStore.intersectTwo(result, lists[i]);
-            if (result.length === 0)
-                break; // Short-circuit: no common elements remain
-        }
-        return result;
-    }
-    /**
-     * Two-pointer intersection of two sorted integer arrays.
-     *
-     * Both `a` and `b` must be sorted in ascending order.  The output
-     * contains only values present in both arrays, preserving order.
-     *
-     * @param a - First sorted posting list.
-     * @param b - Second sorted posting list.
-     * @returns Sorted intersection.
-     */
-    static intersectTwo(a, b) {
-        const out = [];
-        let i = 0;
-        let j = 0;
-        while (i < a.length && j < b.length) {
-            if (a[i] === b[j]) {
-                out.push(a[i]); // Common element found
-                i++;
-                j++;
-            }
-            else if (a[i] < b[j]) {
-                i++; // Advance the smaller pointer
-            }
-            else {
-                j++; // Advance the smaller pointer
-            }
-        }
-        return out;
-    }
-    /**
-     * Search for entity IDs in a combined index by field using n-gram text search.
-     *
-     * Implements a Solr-like search algorithm (ported from TyreSizeCatalog):
-     *
-     * 1. **Normalise & tokenise** the query string.
-     * 2. **Token lookup**: for each query token, look up the exact posting
-     *    list.  If not found, fall back to trigram-based approximation
-     *    via {@link postingsForTokenViaNgrams}.  Tokens shorter than
-     *    `NGRAM_SIZE` skip trigram lookup and include all candidates.
-     * 3. **Intersect** posting lists across all query tokens — only entries
-     *    that match *every* token survive.
-     * 4. **Verify** each candidate by checking whether the normalised
-     *    query string is a substring of the normalised index value.
-     *    This eliminates trigram false-positives.
-     * 5. **Deduplicate** results by entity ID (multiple index rows can
-     *    reference the same entity via different field values).
-     *
-     * @param indexTableName - Combined index sheet name.
-     * @param field          - Indexed field to search within.
-     * @param query          - Free-text search query.
-     * @param limit          - Optional maximum number of results.
-     * @returns Array of matching entity IDs, up to `limit`.
-     */
-    searchCombined(indexTableName, field, query, limit) {
-        if (!query)
-            return [];
-        // Retrieve or build the in-memory search index for this (table, field) pair
-        const cacheKey = `${indexTableName}::${field}`;
-        let idx = this.searchIndexCache.get(cacheKey);
-        if (!idx) {
-            idx = this.buildSearchIndex(indexTableName, field);
-            this.searchIndexCache.set(cacheKey, idx);
-        }
-        if (idx.entries.length === 0)
-            return []; // No indexed data for this field
-        // Normalise the query for case/diacritic-insensitive matching
-        const pat = IndexStore.normalizeForSearch(query);
-        if (!pat)
-            return [];
-        const qTokens = IndexStore.tokenize(pat);
-        let candidates;
-        if (qTokens.length === 0) {
-            // Empty token list (e.g. query was only whitespace) → all entries are candidates
-            candidates = Array.from({ length: idx.entries.length }, (_, i) => i);
-        }
-        else {
-            // Gather posting lists for each query token
-            const postings = [];
-            for (const t of qTokens) {
-                const p = idx.tokenIndex.get(t);
-                if (p) {
-                    // Exact token match found in index
-                    postings.push(p);
-                }
-                else if (t.length < IndexStore.NGRAM_SIZE) {
-                    // Token is shorter than trigram size — cannot use n-gram approximation.
-                    // Include all candidates; substring verification will filter later.
-                    postings.push(Array.from({ length: idx.entries.length }, (_, i) => i));
-                }
-                else {
-                    // Approximate via trigram intersection
-                    const p2 = IndexStore.postingsForTokenViaNgrams(t, idx.ngramIndex);
-                    if (p2.length === 0)
-                        return []; // No trigram match → query cannot match any entry
-                    postings.push(p2);
-                }
-            }
-            // Sort shortest-first for efficient intersection
-            postings.sort((a, b) => a.length - b.length);
-            candidates = IndexStore.intersectPostingLists(postings);
-            if (candidates.length === 0)
-                return [];
-        }
-        // --- Substring verification pass ---
-        // Trigram intersection is approximate; verify each candidate by checking
-        // that the full normalised query appears as a substring of the normalised
-        // index value.  Also deduplicate by entity ID.
-        const maxResults = limit !== undefined && Number.isFinite(limit) && limit >= 0 ? Math.floor(limit) : candidates.length;
-        if (maxResults === 0)
-            return [];
-        const seen = new Set(); // Track seen entity IDs for deduplication
-        const out = [];
-        for (const pos of candidates) {
-            if (idx.normalized[pos].includes(pat)) {
-                const entityId = idx.entries[pos].entityId;
-                if (!seen.has(entityId)) {
-                    seen.add(entityId);
-                    out.push(entityId);
-                }
-                if (out.length >= maxResults)
-                    break; // Early exit once limit is reached
-            }
-        }
-        return out;
-    }
-    /**
-     * Retrieve the raw rows of a combined index sheet, with transparent caching.
-     *
-     * Avoids redundant `getAllData()` GAS API calls when multiple operations
-     * (lookup, search, update) access the same index sheet within a single
-     * save cycle.  The cache is invalidated via {@link clearCache} after any
-     * write operation.
-     *
-     * When `indexRowCount` records 0 rows for the table (e.g. immediately after
-     * {@link createCombinedIndex}), the method skips the `getAllData()` call
-     * entirely and returns an empty array.
-     *
-     * @param indexTableName - Combined index sheet name.
-     * @returns 2-D array of raw row data (`[field, value, entityId]` per row).
-     */
-    getCombinedData(indexTableName) {
-        if (this.cache) {
-            // --- Cached path ---
-            const cacheKey = `cidx:${indexTableName}`;
-            const cached = this.cache.get(cacheKey);
-            if (cached !== null) {
-                // Cache hit — return without touching GAS API
-                SheetOrmLogger.log(`[Index:${indexTableName}] getCombinedData cache HIT — ${cached.length} rows`);
-                return cached;
-            }
-            // Sheet is known-empty (just created via createCombinedIndex) — seed cache directly,
-            // skip the getAllData() API call that would wastefully read 0 rows from GAS.
-            if (this.indexRowCount.get(indexTableName) === 0) {
-                const empty = [];
-                this.cache.set(cacheKey, empty);
-                SheetOrmLogger.log(`[Index:${indexTableName}] getCombinedData cache SEED (empty, skip getAllData)`);
-                return empty;
-            }
-            // Cache miss — fetch from GAS and populate cache
-            const sheet = this.getIndexSheet(indexTableName);
-            const data = sheet ? sheet.getAllData() : [];
-            SheetOrmLogger.log(`[Index:${indexTableName}] getCombinedData cache MISS — read ${data.length} rows from sheet`);
-            this.cache.set(cacheKey, data);
-            this.indexRowCount.set(indexTableName, data.length); // Keep row count in sync
-            return data;
-        }
-        // --- No-cache path ---
-        // Skip getAllData() when table is known-empty
-        if (this.indexRowCount.get(indexTableName) === 0) {
-            SheetOrmLogger.log(`[Index:${indexTableName}] getCombinedData (no cache) — empty (skip getAllData)`);
-            return [];
-        }
-        const sheet = this.getIndexSheet(indexTableName);
-        const data = sheet ? sheet.getAllData() : [];
-        SheetOrmLogger.log(`[Index:${indexTableName}] getCombinedData (no cache) — read ${data.length} rows from sheet`);
-        this.indexRowCount.set(indexTableName, data.length); // Update tracked row count
-        return data;
-    }
-    /**
-     * Invalidate search-index cache entries for a specific index table.
-     *
-     * Iterates over all keys in `searchIndexCache` and removes any whose
-     * prefix matches `indexTableName::`.  Called after write operations so
-     * that subsequent searches rebuild their in-memory posting lists.
-     *
-     * @param indexTableName - Sheet name whose search cache should be cleared.
-     */
-    invalidateSearchCacheForTable(indexTableName) {
-        const prefix = `${indexTableName}::`;
-        for (const key of this.searchIndexCache.keys()) {
-            if (key.startsWith(prefix))
-                this.searchIndexCache.delete(key);
-        }
-    }
-    /**
-     * Clear all internal index caches — both in-memory search indexes and
-     * the data-level cache entries (prefixed `cidx:`).
-     *
-     * Does not clear the entire shared {@link ICacheProvider}; instead it
-     * selectively deletes only index-related keys to preserve other cached
-     * data (e.g. entity caches).
-     */
-    clearCache() {
-        this.searchIndexCache.clear(); // Drop all in-memory search indexes
-        if (!this.cache)
-            return;
-        // Only invalidate index-specific keys rather than clearing entire cache
-        const cleared = new Set();
-        for (const key of this.indexRegistry.keys()) {
-            const tableName = key.split("::")[0];
-            if (!cleared.has(tableName)) {
-                cleared.add(tableName);
-                this.cache.delete(`cidx:${tableName}`); // Remove cached raw row data
-            }
-        }
-    }
-    /**
-     * Public entry point for clearing all index caches (search + data).
-     * Called by {@link Registry.clearCache} to ensure full cache coherence
-     * when the Registry's data is invalidated.
-     */
-    clearAllCaches() {
-        this.clearCache();
-    }
-}
-/** Character-level n-gram length used for search indexing (trigram = 3). */
-IndexStore.NGRAM_SIZE = 3;
-//# sourceMappingURL=IndexStore.js.map