@b2bc-devkit/sheetorm 1.2.3 → 1.2.4

package/dist/npm/core/SheetRepository.js

@@ -0,0 +1,1041 @@
+/**
+ * Main CRUD and query interface for a single entity type.
+ *
+ * Each `SheetRepository<T>` manages one Google Sheets tab, converting
+ * between in-memory {@link Entity} objects and sheet rows via
+ * {@link Serialization}.  Inspired by the Repository pattern from
+ * common ORM architectures (Hibernate, TypeORM, etc.).
+ *
+ * Performance optimisations (referenced by codename in comments):
+ *   - **B5**  — Known row count passed from Registry avoids getLastRow().
+ *   - **B7**  — `sheetCache` memoises the ISheetAdapter for the tab.
+ *   - **K1**  — Reuses physicalRowCount across saves inside saveAll().
+ *   - **K2**  — Skips index sheet lookup when the class has no @Indexed fields.
+ *   - **L1**  — Defers header write to the first data flush (saves ~700 ms).
+ *   - **L2**  — Bulk delete rewrite for delete-only batch commits.
+ *
+ * @module SheetRepository
+ */
+import { SystemColumns } from "../core/types/SystemColumns.js";
+import { Uuid } from "../utils/Uuid.js";
+import { Serialization } from "../utils/Serialization.js";
+import { Query } from "../query/Query.js";
+import { QueryEngine } from "../query/QueryEngine.js";
+import { SheetOrmLogger } from "../utils/SheetOrmLogger.js";
+/**
+ * Repository providing CRUD, query, pagination, and batch operations
+ * for entities of type `T` stored in a single Google Sheet tab.
+ *
+ * @typeParam T - Entity type managed by this repository.
+ */
+export class SheetRepository {
+    /**
+     * Constructs a new repository for the given table schema.
+     *
+     * @param adapter         - Spreadsheet adapter providing sheet management.
+     * @param schema          - Table schema (name, fields, indexes).
+     * @param indexStore      - Shared IndexStore for secondary indexes.
+     * @param cache           - Optional cache provider for in-memory row caching.
+     * @param hooks           - Optional lifecycle hooks (onValidate, beforeSave, afterSave, beforeDelete, afterDelete).
+     * @param initialSheet    - Pre-resolved sheet adapter (avoids redundant getSheetByName call).
+     * @param initialRowCount - Pre-fetched row count (avoids redundant getLastRow call).
+     * @param headersDeferred - True if the sheet was just created and headers still need writing.
+     */
+    constructor(adapter, schema, indexStore, cache, hooks, initialSheet, initialRowCount, headersDeferred) {
+        /** Fast-lookup map: entity ID → 1-based sheet row index for O(1) row access. */
+        this.idToRowIndex = null;
+        /** Buffered operations when a batch is active (beginBatch/commitBatch). */
+        this.batchBuffer = null;
+        /**
+         * Entity batch accumulator used by saveAll().
+         * Each entry stores the entity, its serialised row, 0-based data index, and
+         * whether it is a "create" or "update".  Flushed via flushEntityBatch().
+         */
+        this.entityBatch = null;
+        /** Cached sheet reference for the duration of saveAll() — avoids 1000× getSheetByName(). */
+        this.batchSheet = null;
+        /** Row count captured once at saveAll() start — avoids 1000× getLastRow(). */
+        this.batchBaseRowCount = null;
+        /** Cached entity array used by updateCacheAfterSave in batch mode — avoids 1000× cache.get() log calls. */
+        this.batchCachedData = null;
+        /** Indexed fields metadata, cached for the duration of saveAll() — avoids 1000× getIndexedFields() array alloc. */
+        this.batchIndexedFields = null;
+        /** Physical sheet row count, tracked to avoid repeated getLastRow() API calls in non-batch save sequences. */
+        this.physicalRowCount = null;
+        /** True when idToRowIndex was built from a complete sheet scan (bootstrap or loadAllEntities/rowIndexById). */
+        this.idToRowIndexComplete = false;
+        /** Memoized sheet reference — avoids repeated getSheetByName() API calls within a session (B7). */
+        this.sheetCache = null;
+        this.adapter = adapter;
+        this.schema = schema;
+        this.indexStore = indexStore;
+        this.cache = cache ?? null;
+        this.hooks = hooks ?? {};
+        // Seed memoised sheet & row count when provided by Registry
+        this.sheetCache = initialSheet ?? null;
+        this.physicalRowCount = initialRowCount ?? null;
+        // Build column header array from field definitions (used for serialisation)
+        this.headers = Serialization.buildHeaders(schema.fields);
+        // Locate the __id column position for fast primary-key lookups
+        this.idColIdx = this.headers.indexOf(SystemColumns.ID);
+        // Pre-filter required and defaultable fields for validation/defaults in save()
+        this.requiredFields = schema.fields.filter((f) => f.required);
+        this.defaultableFields = schema.fields.filter((f) => f.defaultValue !== undefined);
+        // Cache key for the data cache (all-entity array)
+        this.dataCacheKey = `data:${schema.tableName}`;
+        // Pre-build field lookup map once (reused by entityToRow / rowToEntity)
+        this.fieldMap = new Map();
+        for (const f of schema.fields) {
+            this.fieldMap.set(f.name, f);
+        }
+        // Pre-build indexed-field name set once — avoids getIndexedFields() array alloc on every find()
+        this.indexedFieldNames = new Set(schema.indexes.map((idx) => idx.field));
+        // Defer header write to first data flush — saves one GAS API call per new sheet
+        this.headersDeferred = headersDeferred ?? false;
+        SheetOrmLogger.log(`[Repo:${schema.tableName}] constructor — ` +
+            `sheetCache=${initialSheet ? "seeded" : "null"} ` +
+            `physicalRowCount=${initialRowCount !== undefined ? String(initialRowCount) : "unknown"} ` +
+            `indexedFields=[${schema.indexes.map((i) => i.field).join(",")}]`);
+    }
+    // ─── CRUD ──────────────────────────────────────────
+    /**
+     * Save (create or update) an entity.
+     *
+     * When a batch is active (see {@link beginBatch}), the operation is buffered
+     * and deferred until {@link commitBatch} is called.  Otherwise delegates
+     * immediately to {@link doSave}.
+     *
+     * @param partial - Partial entity with optional `__id`.
+     * @returns The saved entity with system columns populated.
+     */
+    save(partial) {
+        if (this.batchBuffer) {
+            const now = new Date().toISOString();
+            const id = partial.__id ?? Uuid.generate();
+            // Heuristic: __id present *with* __createdAt → likely an existing entity (update).
+            // __id present *without* __createdAt → caller-supplied ID for a new entity.
+            const isLikelyUpdate = Boolean(partial.__id && partial.__createdAt);
+            const buffered = { ...partial, __id: id };
+            this.batchBuffer.push({ type: "save", data: buffered });
+            return {
+                ...buffered,
+                ...(!isLikelyUpdate ? { __createdAt: now } : {}),
+                __updatedAt: now,
+            };
+        }
+        return this.doSave(partial);
+    }
+    /**
+     * Internal save implementation — resolves existence, validates, applies
+     * defaults, and writes to the sheet or buffers into an entity batch.
+     *
+     * @param partial - Partial entity data with optional `__id`.
+     * @returns Fully populated entity with system columns.
+     */
+    doSave(partial) {
+        const sheet = this.batchSheet ?? this.getSheet();
+        // Per-entity log is suppressed in batch mode to avoid 1000× Logger.log() overhead in GAS
+        if (!this.entityBatch) {
+            SheetOrmLogger.log(`[Repo:${this.schema.tableName}] doSave — batchMode=false id=${partial.__id ?? "(new)"}`);
+        }
+        const now = new Date().toISOString();
+        // ── Existence check: prefer in-memory index, fall back to single API call ──
+        let existingIdx = null;
+        let existingEntity = null;
+        if (partial.__id) {
+            // Try in-memory lookup: idToRowIndex gives us the 0-based data row index,
+            // and the entity cache gives us the current field values (needed for UPDATE merge).
+            const cachedIdx = this.idToRowIndex?.get(partial.__id);
+            if (cachedIdx !== undefined && this.cache) {
+                const cached = this.cache.get(this.dataCacheKey);
+                if (cached) {
+                    const cachedEntity = cached[cachedIdx];
+                    // Validate that the cached ID matches — gap rows may cause cache index drift
+                    if (cachedEntity?.__id === partial.__id) {
+                        existingIdx = cachedIdx;
+                        existingEntity = cachedEntity;
+                    }
+                }
+            }
+            // Fallback: full-scan the sheet's ID column, deserialize only the matching row
+            if (existingIdx === null) {
+                if (this.idToRowIndex && this.idToRowIndexComplete && !this.idToRowIndex.has(partial.__id)) {
+                    // idToRowIndex covers all rows; entity's ID is absent → definitely new, skip sheet read.
+                }
+                else {
+                    const data = sheet.getAllData();
+                    const rowIndex = new Map();
+                    const col = this.idColIdx;
+                    for (let i = 0; i < data.length; i++) {
+                        const rowId = String(data[i][col]);
+                        rowIndex.set(rowId, i);
+                        if (rowId === partial.__id) {
+                            existingIdx = i;
+                            existingEntity = Serialization.rowToEntity(data[i], this.headers, this.schema.fields, this.fieldMap);
+                        }
+                    }
+                    // Rebuild the full index as a side effect of the scan
+                    this.idToRowIndex = rowIndex;
+                    this.physicalRowCount = data.length;
+                    this.idToRowIndexComplete = true;
+                }
+            }
+        }
+        const isNew = existingIdx === null;
+        if (!this.entityBatch) {
+            SheetOrmLogger.log(`[Repo:${this.schema.tableName}] doSave — isNew=${isNew}${existingIdx !== null ? ` rowIdx=${existingIdx}` : ""}`);
+        }
+        // ── Lifecycle: validate ──
+        if (this.hooks.onValidate) {
+            const errors = this.hooks.onValidate(partial);
+            if (errors && errors.length > 0) {
+                throw new Error(`Validation failed: ${errors.join(", ")}`);
+            }
+        }
+        // ── Lifecycle: beforeSave ──
+        let entityData = partial;
+        if (this.hooks.beforeSave) {
+            const result = this.hooks.beforeSave(partial, isNew);
+            if (result)
+                entityData = result;
+        }
+        // Apply defaults for fields with defaultValue (only when undefined)
+        for (let i = 0; i < this.defaultableFields.length; i++) {
+            const field = this.defaultableFields[i];
+            if (entityData[field.name] === undefined) {
+                entityData[field.name] = field.defaultValue;
+            }
+        }
+        // Validate required fields (must not be undefined, null, or empty string)
+        for (let i = 0; i < this.requiredFields.length; i++) {
+            const field = this.requiredFields[i];
+            const val = entityData[field.name];
+            if (val === undefined || val === null || val === "") {
+                throw new Error(`Required field "${field.name}" is missing for table "${this.schema.tableName}"`);
+            }
+        }
+        let entity;
+        if (isNew) {
+            // ── CREATE path ──
+            entity = {
+                ...entityData,
+                __id: entityData.__id ?? Uuid.generate(),
+                __createdAt: now,
+                __updatedAt: now,
+            };
+            const row = Serialization.entityToRow(entity, this.schema.fields, this.headers, this.fieldMap);
+            // Compute the 0-based data row index for writing.
+            // In batch mode (saveAll), batchBaseRowCount was captured once at batch start.
+            // Otherwise reuse physicalRowCount to avoid getLastRow() API calls.
+            const baseCount = this.batchBaseRowCount !== null
+                ? this.batchBaseRowCount
+                : this.physicalRowCount !== null
+                    ? this.physicalRowCount
+                    : sheet.getRowCount();
+            // Account for already-buffered CREATE entities that haven't been flushed yet
+            const dataIndex = baseCount + (this.entityBatch ? this.entityBatch.filter((item) => item.mode === "create").length : 0);
+            // Bootstrap idToRowIndex and cache when first entity is written to an empty sheet
+            if (!this.idToRowIndex) {
+                if (dataIndex === 0) {
+                    this.idToRowIndex = new Map();
+                    this.physicalRowCount = 0;
+                    this.idToRowIndexComplete = true;
+                    // Seed empty cache so subsequent finds are cache hits
+                    if (this.cache && !this.cache.has(this.dataCacheKey)) {
+                        this.cache.set(this.dataCacheKey, []);
+                    }
+                }
+            }
+            // In entity batch mode (saveAll): buffer the row; otherwise write immediately
+            if (this.entityBatch !== null) {
+                this.entityBatch.push({ entity, row, dataIndex, mode: "create" });
+            }
+            else {
+                // Write headers + first data row in a single API call for newly-created sheets
+                if (this.headersDeferred) {
+                    sheet.writeAllRowsWithHeaders(this.headers, [row]);
+                    this.headersDeferred = false;
+                }
+                else {
+                    sheet.updateRow(dataIndex, row);
+                }
+                // Keep physicalRowCount in sync
+                if (this.physicalRowCount !== null)
+                    this.physicalRowCount++;
+            }
+            // Add to secondary indexes (@Indexed fields)
+            this.addToIndexes(entity);
+            // Update in-memory row index (always, even in batch — so the next entity gets the correct dataIndex)
+            if (this.idToRowIndex) {
+                this.idToRowIndex.set(entity.__id, dataIndex);
+            }
+        }
+        else {
+            // ── UPDATE path — merge existing fields with new values ──
+            entity = {
+                ...existingEntity,
+                ...entityData,
+                __id: existingEntity.__id,
+                __createdAt: existingEntity.__createdAt,
+                __updatedAt: now,
+            };
+            const row = Serialization.entityToRow(entity, this.schema.fields, this.headers, this.fieldMap);
+            if (this.entityBatch !== null) {
+                this.entityBatch.push({ entity, row, dataIndex: existingIdx, mode: "update" });
+            }
+            else {
+                sheet.updateRow(existingIdx, row);
+            }
+            // Update secondary indexes with old → new value changes
+            const oldValues = {};
+            const newValues = {};
+            for (const field of this.schema.fields) {
+                oldValues[field.name] = existingEntity[field.name];
+                newValues[field.name] = entity[field.name];
+            }
+            if (this.schema.indexTableName) {
+                this.indexStore.updateInCombined(this.schema.indexTableName, entity.__id, oldValues, newValues);
+            }
+        }
+        // Update entity cache in place (avoid full invalidation after every save)
+        this.updateCacheAfterSave(entity, isNew);
+        // ── Lifecycle: afterSave ──
+        if (this.hooks.afterSave) {
+            this.hooks.afterSave(entity, isNew);
+        }
+        return entity;
+    }
+    /**
+     * Save multiple entities in a single optimised batch.
+     *
+     * 1. Captures the sheet reference and row count once (K1, B7).
+     * 2. Calls {@link doSave} for each entity — rows are buffered instead of
+     *    written individually.
+     * 3. Flushes all buffered rows via {@link flushEntityBatch} (single API call).
+     * 4. Flushes index writes via {@link IndexStore.flushIndexBatch}.
+     *
+     * On error the batch state is fully reset and the cache is invalidated.
+     *
+     * @param entities - Array of partial entities to save.
+     * @returns Array of fully populated saved entities.
+     */
+    saveAll(entities) {
+        if (entities.length === 0)
+            return [];
+        const sheet = this.getSheet();
+        SheetOrmLogger.log(`[Repo:${this.schema.tableName}] saveAll START — ${entities.length} entities`);
+        // Initialise batch state
+        this.entityBatch = [];
+        this.batchSheet = sheet;
+        // Reuse physicalRowCount when available — avoids a getLastRow() API call (~700 ms)
+        // when the row count is already known in-session (e.g. new table seeded to 0).
+        this.batchBaseRowCount = this.physicalRowCount !== null ? this.physicalRowCount : sheet.getRowCount();
+        if (this.schema.indexTableName) {
+            this.indexStore.beginIndexBatch();
+            // Pre-fetch indexed fields once — avoids N × getIndexedFields() array allocation
+            this.batchIndexedFields = this.indexStore.getIndexedFields(this.schema.indexTableName);
+        }
+        try {
+            // Execute all saves (rows buffered into this.entityBatch)
+            const results = entities.map((e) => this.doSave(e));
+            // Count how many new rows were created to update physicalRowCount
+            const savedCreates = (this.entityBatch ?? []).filter((i) => i.mode === "create").length;
+            // Flush buffered rows to the sheet in one updateRows() call
+            this.flushEntityBatch(sheet);
+            // Flush index batch (single write per index sheet)
+            if (this.schema.indexTableName) {
+                this.indexStore.flushIndexBatch();
+            }
+            // Update physicalRowCount with the number of new rows
+            if (this.batchBaseRowCount !== null) {
+                this.physicalRowCount = this.batchBaseRowCount + savedCreates;
+            }
+            // Clear batch state
+            this.batchSheet = null;
+            this.batchBaseRowCount = null;
+            this.batchCachedData = null;
+            this.batchIndexedFields = null;
+            SheetOrmLogger.log(`[Repo:${this.schema.tableName}] saveAll DONE — ${entities.length} entities`);
+            return results;
+        }
+        catch (err) {
+            // Error recovery: clear all batch state and invalidate caches
+            this.entityBatch = null;
+            this.batchSheet = null;
+            this.batchBaseRowCount = null;
+            this.batchCachedData = null;
+            this.batchIndexedFields = null;
+            if (this.schema.indexTableName) {
+                this.indexStore.cancelIndexBatch();
+            }
+            if (this.cache)
+                this.cache.delete(this.dataCacheKey);
+            this.idToRowIndex = null;
+            this.physicalRowCount = null;
+            this.idToRowIndexComplete = false;
+            throw err;
+        }
+    }
+    /**
+     * Find an entity by its primary key (`__id`).
+     *
+     * Uses a fast path when idToRowIndex + cache are populated, falling back
+     * to a full {@link loadAllEntities} scan otherwise.
+     *
+     * @param id - Entity `__id` value.
+     * @returns The matching entity or `null` if not found.
+     */
+    findById(id) {
+        // Fast path: hit cached row-index map to avoid full scan
+        if (this.idToRowIndex && this.cache) {
+            const rowIdx = this.idToRowIndex.get(id);
+            if (rowIdx === undefined)
+                return null;
+            const cached = this.cache.get(this.dataCacheKey);
+            if (cached) {
+                const hit = cached[rowIdx];
+                // Validate ID — gap rows may cause cache index drift
+                if (hit?.__id === id)
+                    return this.cloneEntity(hit);
+                // Index/cache divergence (e.g. gap rows): scan cached array directly
+                // to avoid unnecessary sheet re-read via loadAllEntities()
+                const found = cached.find((e) => e?.__id === id);
+                return found ? this.cloneEntity(found) : null;
+            }
+        }
+        // Slow path: load all entities from sheet (populates cache as a side-effect)
+        const all = this.loadAllEntities();
+        const found = all.find((e) => e.__id === id);
+        return found ? this.cloneEntity(found) : null;
+    }
+    /**
+     * Find entities matching query options (filter, sort, paginate, group).
+     *
+     * When a `search` operator targets an `@Indexed` field and a combined index
+     * sheet exists, the n-gram search index is used to narrow candidates before
+     * the full filter pipeline runs (Solr-like optimisation).
+     *
+     * @param options - Optional query options (where, whereGroups, orderBy, offset, limit).
+     * @returns Array of matching entities.
+     */
+    find(options) {
+        const all = this.loadAllEntities();
+        if (!options)
+            return this.cloneEntities(all);
+        if (options.where && !options.whereGroups && this.schema.indexTableName) {
+            // Separate search-operator filters (n-gram indexed) from other filters
+            const searchFilters = [];
+            const otherFilters = [];
+            for (const f of options.where) {
+                if (f.operator === "search" && this.isIndexedField(f.field)) {
+                    searchFilters.push({ field: f.field, value: String(f.value) });
+                }
+                else {
+                    otherFilters.push(f);
+                }
+            }
+            // N-gram index optimisation: narrow candidates via IndexStore.searchCombined
+            // before running the full filter pipeline (analogous to Solr pre-filtering)
+            if (searchFilters.length > 0) {
+                let candidateIds = null;
+                for (const sf of searchFilters) {
+                    const ids = this.indexStore.searchCombined(this.schema.indexTableName, sf.field, sf.value);
+                    const idSet = new Set(ids);
+                    // Intersect candidate sets across multiple search filters (AND semantics)
+                    if (candidateIds === null) {
+                        candidateIds = idSet;
+                    }
+                    else {
+                        for (const id of candidateIds) {
+                            if (!idSet.has(id))
+                                candidateIds.delete(id);
+                        }
+                    }
+                }
+                if (!candidateIds || candidateIds.size === 0)
+                    return [];
+                // Filter the in-memory entities to only those matching the index hits
+                const narrowed = all.filter((e) => candidateIds.has(e.__id));
+                return this.cloneEntities(QueryEngine.executeQuery(narrowed, {
+                    ...options,
+                    where: otherFilters.length > 0 ? otherFilters : undefined,
+                }));
+            }
+        }
+        // Standard path: run full QueryEngine pipeline on all entities
+        return this.cloneEntities(QueryEngine.executeQuery(all, options));
+    }
+    /**
+     * Find the first entity matching query options.
+     *
+     * Delegates to {@link find} with `limit: 1`.
+     *
+     * @param options - Optional query options.
+     * @returns The first matching entity or `null`.
+     */
+    findOne(options) {
+        const opts = { ...options, limit: 1 };
+        const results = this.find(opts);
+        return results.length > 0 ? results[0] : null;
+    }
+    /**
+     * Delete an entity by ID.
+     *
+     * When a batch is active, the delete is queued and `true` is returned
+     * immediately; actual removal happens on {@link commitBatch}.
+     *
+     * @param id - Entity `__id` to delete.
+     * @returns `true` if the entity was found and deleted (or queued).
+     */
+    delete(id) {
+        if (this.batchBuffer) {
+            this.batchBuffer.push({ type: "delete", data: id });
+            return true;
+        }
+        return this.doDelete(id);
+    }
+    /**
+     * Internal delete implementation.
+     *
+     * 1. Runs `beforeDelete` lifecycle hook (can veto deletion by returning `false`).
+     * 2. Resolves the row index via in-memory cache or sheet scan.
+     * 3. Removes from secondary indexes.
+     * 4. Deletes the sheet row and adjusts `idToRowIndex`.
+     * 5. Updates entity cache and runs `afterDelete` hook.
+     *
+     * @param id - Entity `__id` to delete.
+     * @returns `true` if the entity was found and deleted.
+     */
+    doDelete(id) {
+        // Lifecycle: beforeDelete — can veto deletion by returning false
+        if (this.hooks.beforeDelete) {
+            const result = this.hooks.beforeDelete(id);
+            if (result === false)
+                return false;
+        }
+        const sheet = this.getSheet();
+        // Fast path: verify entity from in-memory cache — avoids sheet.getRow() API call
+        // (a getRange().getValues() round-trip to GAS, ~200 ms per call).
+        let rowIdx = null;
+        if (this.idToRowIndex) {
+            const idx = this.idToRowIndex.get(id);
+            if (idx !== undefined) {
+                const cached = this.cache?.get(this.dataCacheKey);
+                if (cached?.[idx]?.__id === id) {
+                    rowIdx = idx;
+                }
+                else {
+                    // Cache cold or stale index — verify via sheet read
+                    const row = sheet.getRow(idx);
+                    if (row && String(row[this.idColIdx]) === id) {
+                        rowIdx = idx;
+                    }
+                    else {
+                        // Stale index — fall back to full scan
+                        rowIdx = this.rowIndexById(sheet, id);
+                    }
+                }
+            }
+        }
+        if (rowIdx === null) {
+            rowIdx = this.rowIndexById(sheet, id);
+        }
+        if (rowIdx === null)
+            return false;
+        // Remove from secondary indexes
+        if (this.schema.indexTableName) {
+            this.indexStore.removeAllFromCombined(this.schema.indexTableName, id);
+        }
+        // Delete the sheet row and adjust the tracked row count
+        sheet.deleteRow(rowIdx);
+        if (this.physicalRowCount !== null)
+            this.physicalRowCount--;
+        // Update idToRowIndex: remove deleted ID and shift rows above it down by one
+        if (this.idToRowIndex) {
+            this.idToRowIndex.delete(id);
+            for (const [key, idx] of this.idToRowIndex) {
+                if (idx > rowIdx) {
+                    this.idToRowIndex.set(key, idx - 1);
+                }
+            }
+        }
+        // Update entity cache in place (remove the deleted entity)
+        this.updateCacheAfterDelete(id);
+        // Lifecycle: afterDelete
+        if (this.hooks.afterDelete) {
+            this.hooks.afterDelete(id);
+        }
+        return true;
+    }
+    /**
+     * Delete all entities matching a query (or all entities if no options given).
+     *
+     * Uses bulk write (replaceAllData) for 3+ deletions — two API calls instead
+     * of N individual deleteRow() calls.  For 1–2 deletions, individual deletes
+     * are cheaper due to lower overhead.
+     *
+     * @param options - Optional query options to select entities to delete.
+     * @returns Number of entities deleted.
+     */
+    deleteAll(options) {
+        // In batch mode: queue deletes for later commitBatch()
+        if (this.batchBuffer) {
+            const entities = this.find(options);
+            for (const entity of entities) {
+                this.batchBuffer.push({ type: "delete", data: entity.__id });
+            }
+            return entities.length;
+        }
+        const all = this.loadAllEntities();
+        const toDelete = options ? QueryEngine.executeQuery(all, options) : [...all];
+        if (toDelete.length === 0)
+            return 0;
+        // For small batches (≤2), individual deletes are cheaper than replaceAllData
+        if (toDelete.length <= 2) {
+            let count = 0;
+            for (const entity of toDelete) {
+                if (this.doDelete(entity.__id))
+                    count++;
+            }
+            return count;
+        }
+        // ── Bulk delete: snapshot → filter out deleted → write back (2 API calls vs N) ──
+        const deleteIds = new Set();
+        for (const entity of toDelete) {
+            // beforeDelete can veto individual deletions
+            if (this.hooks.beforeDelete && this.hooks.beforeDelete(entity.__id) === false)
+                continue;
+            deleteIds.add(entity.__id);
+        }
+        if (deleteIds.size === 0)
+            return 0;
+        // Retain only entities not in the delete set
+        const remaining = all.filter((e) => !deleteIds.has(e.__id));
+        const sheet = this.getSheet();
+        const rows = remaining.map((e) => Serialization.entityToRow(e, this.schema.fields, this.headers, this.fieldMap));
+        // Replace the entire sheet data with the filtered rows
+        sheet.replaceAllData(rows);
+        // Clean up secondary indexes for all deleted entities
+        if (this.schema.indexTableName) {
+            this.indexStore.removeMultipleFromCombined(this.schema.indexTableName, [...deleteIds]);
+        }
+        // afterDelete hooks for each deleted entity
+        for (const id of deleteIds) {
+            if (this.hooks.afterDelete)
+                this.hooks.afterDelete(id);
+        }
+        // Rebuild cache and idToRowIndex from the remaining entities
+        if (this.cache) {
+            this.cache.set(this.dataCacheKey, remaining);
+        }
+        const rowIndex = new Map();
+        for (let i = 0; i < remaining.length; i++) {
+            rowIndex.set(remaining[i].__id, i);
+        }
+        this.idToRowIndex = rowIndex;
+        this.physicalRowCount = rows.length;
+        this.idToRowIndexComplete = true;
+        return deleteIds.size;
+    }
+    /**
+     * Count entities matching a query.
+     *
+     * @param options - Optional query options (only `where`/`whereGroups` are meaningful).
+     * @returns Total count of matching entities.
+     */
+    count(options) {
+        const all = this.loadAllEntities();
+        if (!options || (!options.where && !options.whereGroups))
+            return all.length;
+        return QueryEngine.executeQuery(all, options).length;
+    }
+    /**
+     * Paginated select — applies optional filters, then paginates.
+     *
+     * @param offset - 0-based offset.
+     * @param limit  - Maximum number of results.
+     * @param options - Optional query options applied before pagination.
+     * @returns {@link PaginatedResult} with `data`, `total`, `offset`, and `limit`.
+     */
+    select(offset, limit, options) {
+        let entities = this.cloneEntities(this.loadAllEntities());
+        if (options) {
+            // Filter/sort first, then paginate (offset/limit from options are stripped to avoid double application)
+            entities = QueryEngine.executeQuery(entities, { ...options, offset: undefined, limit: undefined });
+        }
+        return QueryEngine.paginateEntities(entities, offset, limit);
+    }
+    /**
+     * Group entities by a field value.
+     *
+     * @param field   - Field name to group by.
+     * @param options - Optional query options applied before grouping.
+     * @returns Array of {@link GroupResult} objects.
+     */
+    groupBy(field, options) {
+        let entities = this.cloneEntities(this.loadAllEntities());
+        if (options) {
+            entities = QueryEngine.executeQuery(entities, options);
+        }
+        return QueryEngine.groupEntities(entities, field);
+    }
+    /**
+     * Create a fluent {@link Query} builder for this repository.
+     *
+     * @returns A new Query instance backed by a snapshot of all current entities.
+     */
+    query() {
+        return new Query(() => this.cloneEntities(this.loadAllEntities()));
+    }
+    // ─── Batch Operations ──────────────────────────────
+    /**
+     * Start buffering save/delete operations for later atomic commit.
+     *
+     * Call {@link commitBatch} to apply all buffered operations, or
+     * {@link rollbackBatch} to discard them.
+     */
+    beginBatch() {
+        this.batchBuffer = [];
+    }
+    /**
+     * Commit all buffered operations from {@link beginBatch}.
+     *
+     * If the buffer contains only deletes, a bulk rewrite (replaceAllData) is
+     * used instead of N individual deleteRow() calls.
+     */
+    commitBatch() {
+        if (!this.batchBuffer)
+            return;
+        const buffer = this.batchBuffer;
+        this.batchBuffer = null;
+        try {
+            // Optimize delete-only batches (common for deleteAll() in batch mode)
+            // by applying one bulk rewrite instead of N × deleteRow() API calls.
+            if (buffer.length > 0 && buffer.every((op) => op.type === "delete")) {
+                this.commitDeleteBatch(buffer.map((op) => op.data));
+                return;
+            }
+            // Mixed batch: replay operations sequentially
+            for (const op of buffer) {
+                if (op.type === "save") {
+                    this.doSave(op.data);
+                }
+                else if (op.type === "delete") {
+                    this.doDelete(op.data);
+                }
+            }
+        }
+        catch (err) {
+            // On error: invalidate caches to avoid stale state
+            if (this.cache)
+                this.cache.delete(this.dataCacheKey);
+            this.idToRowIndex = null;
+            this.physicalRowCount = null;
+            this.idToRowIndexComplete = false;
+            throw err;
+        }
+    }
+    /**
+     * Commit a delete-only batch via bulk replaceAllData.
+     *
+     * Falls back to per-ID deletes for tiny (≤2) or duplicate-heavy batches
+     * to preserve semantics and avoid unnecessary full-sheet rewrites.
+     *
+     * @param ids - Array of entity IDs to delete.
+     */
+    commitDeleteBatch(ids) {
+        if (ids.length === 0)
+            return;
+        // For very small batches or duplicates, individual deletes are cheaper
+        const uniqueCount = new Set(ids).size;
+        if (ids.length <= 2 || uniqueCount !== ids.length) {
+            for (const id of ids) {
+                this.doDelete(id);
+            }
+            return;
+        }
+        const all = this.loadAllEntities();
+        if (all.length === 0)
+            return;
+        // Build set of existing IDs to skip deletes of already-removed entities
+        const existingIds = new Set(all.map((e) => e.__id));
+        const deleteIds = [];
+        // Preserve caller order; run beforeDelete hooks (can veto)
+        for (const id of ids) {
+            if (!existingIds.has(id))
+                continue;
+            if (this.hooks.beforeDelete && this.hooks.beforeDelete(id) === false)
+                continue;
+            deleteIds.push(id);
+        }
+        if (deleteIds.length === 0)
+            return;
+        // Filter out deleted entities and rewrite the entire sheet
+        const deleteSet = new Set(deleteIds);
+        const remaining = all.filter((e) => !deleteSet.has(e.__id));
+        const rows = remaining.map((e) => Serialization.entityToRow(e, this.schema.fields, this.headers, this.fieldMap));
+        const sheet = this.getSheet();
+        sheet.replaceAllData(rows);
+        // Clean up secondary indexes for deleted entities
+        if (this.schema.indexTableName) {
+            this.indexStore.removeMultipleFromCombined(this.schema.indexTableName, deleteIds);
+        }
+        // Run afterDelete hooks
+        if (this.hooks.afterDelete) {
+            for (const id of deleteIds) {
+                this.hooks.afterDelete(id);
+            }
+        }
+        // Rebuild cache and idToRowIndex from the remaining entities
+        if (this.cache) {
+            this.cache.set(this.dataCacheKey, remaining);
+        }
+        const rowIndex = new Map();
+        for (let i = 0; i < remaining.length; i++) {
+            rowIndex.set(remaining[i].__id, i);
+        }
+        this.idToRowIndex = rowIndex;
+        this.physicalRowCount = rows.length;
+        this.idToRowIndexComplete = true;
+    }
+    /**
+     * Discard all buffered operations without applying them.
+     */
+    rollbackBatch() {
+        this.batchBuffer = null;
+    }
+    /**
+     * Check whether batch mode is currently active.
+     *
+     * @returns `true` when {@link beginBatch} was called but not yet committed or rolled back.
+     */
+    isBatchActive() {
+        return this.batchBuffer !== null;
+    }
+    // ─── Internal Helpers ──────────────────────────────
+    /**
+     * Return the memoised ISheetAdapter for this table, resolving it once
+     * from the spreadsheet adapter and caching it for subsequent calls (B7).
+     *
+     * @throws Error if the sheet doesn't exist.
+     */
+    getSheet() {
+        if (this.sheetCache)
+            return this.sheetCache;
+        const sheet = this.adapter.getSheetByName(this.schema.tableName);
+        if (!sheet) {
+            throw new Error(`Sheet "${this.schema.tableName}" not found. Ensure Registry is configured and the table has been initialized.`);
+        }
+        this.sheetCache = sheet;
+        return sheet;
+    }
+    /**
+     * Load all entities from the sheet, deserialise them, and populate the cache.
+     *
+     * Returns the cached array on a cache hit.  On a cache miss, reads all rows
+     * from the sheet, converts them via {@link Serialization.rowToEntity},
+     * builds {@link idToRowIndex}, and stores the result.
+     *
+     * @throws Error if called during an active entity batch (saveAll).
+     * @returns Array of all entities in the table.
+     */
+    loadAllEntities() {
+        if (this.entityBatch) {
+            throw new Error("Cannot reload entities during active entity batch — lifecycle hooks must not trigger find/count during saveAll()");
+        }
+        // Cache hit path
+        if (this.cache) {
+            const cached = this.cache.get(this.dataCacheKey);
+            if (cached !== null)
+                return cached;
+        }
+        // Cache miss: read all rows from the sheet
+        const sheet = this.getSheet();
+        const data = sheet.getAllData();
+        const len = data.length;
+        const headers = this.headers;
+        const fields = this.schema.fields;
+        const fMap = this.fieldMap;
+        const entities = [];
+        const rowIndex = new Map();
+        // Deserialise each row, skipping rows with invalid/missing IDs
+        for (let i = 0; i < len; i++) {
+            const entity = Serialization.rowToEntity(data[i], headers, fields, fMap);
+            if (!entity.__id || entity.__id === "undefined" || entity.__id === "null")
+                continue;
+            rowIndex.set(entity.__id, i);
+            entities.push(entity);
+        }
+        // Update in-memory state
+        this.idToRowIndex = rowIndex;
+        this.physicalRowCount = data.length;
+        this.idToRowIndexComplete = true;
+        if (this.cache) {
+            this.cache.set(this.dataCacheKey, entities);
+        }
+        return entities;
+    }
+    /**
+     * Find the 0-based data row index for an entity by its `__id` via a full
+     * sheet scan.  Rebuilds {@link idToRowIndex} as a side-effect.
+     *
+     * @param sheet - The sheet adapter to read from.
+     * @param id    - Entity `__id` to search for.
+     * @returns 0-based row index, or `null` if not found.
+     */
+    rowIndexById(sheet, id) {
+        const data = sheet.getAllData();
+        const col = this.idColIdx;
+        if (col < 0)
+            return null;
+        // Populate idToRowIndex while scanning (we already have all the data)
+        const rowIndex = new Map();
+        let result = null;
+        for (let i = 0; i < data.length; i++) {
+            const rowId = String(data[i][col]);
+            rowIndex.set(rowId, i);
+            if (rowId === id)
+                result = i;
+        }
+        this.idToRowIndex = rowIndex;
+        this.physicalRowCount = data.length;
+        this.idToRowIndexComplete = true;
+        return result;
+    }
+    /**
+     * Add a newly-created entity to all relevant secondary indexes.
+     *
+     * In batch mode, uses pre-cached {@link batchIndexedFields} to avoid
+     * repeated `getIndexedFields()` allocations.
+     *
+     * @param entity - The entity to index.
+     */
+    addToIndexes(entity) {
+        if (this.schema.indexTableName) {
+            // Use pre-cached fields in batch mode to avoid N × getIndexedFields() array allocation
+            const indexedFields = this.batchIndexedFields ?? this.indexStore.getIndexedFields(this.schema.indexTableName);
+            const entries = [];
+            for (const meta of indexedFields) {
+                const value = entity[meta.field];
+                if (value !== undefined && value !== null && value !== "") {
+                    entries.push({ field: meta.field, value });
+                }
+            }
+            if (entries.length > 0) {
+                this.indexStore.addAllFieldsToCombined(this.schema.indexTableName, entries, entity.__id);
+            }
+        }
+    }
+    /**
+     * Flush all buffered entity rows to the sheet in a single API call.
+     *
+     * Called at the end of {@link saveAll}.  Sorts buffered entries by
+     * `dataIndex` to build a contiguous row array, then writes them via
+     * `sheet.updateRows()` (or `writeAllRowsWithHeaders` for the L1 path).
+     *
+     * @param sheet - The sheet adapter to write to.
+     */
+    flushEntityBatch(sheet) {
+        if (!this.entityBatch || this.entityBatch.length === 0) {
+            this.entityBatch = null;
+            return;
+        }
+        const batch = this.entityBatch;
+        this.entityBatch = null;
+        const creates = batch.filter((i) => i.mode === "create").length;
+        const updates = batch.filter((i) => i.mode === "update").length;
+        SheetOrmLogger.log(`[Repo:${this.schema.tableName}] flushEntityBatch ${batch.length} rows (creates=${creates} updates=${updates}); calling sheet.updateRows()`);
+        // Sort by dataIndex for contiguous writes
+        const sorted = [...batch].sort((a, b) => a.dataIndex - b.dataIndex);
+        // Write header row + data rows in a single API call for newly-created sheets
+        if (this.headersDeferred) {
+            sheet.writeAllRowsWithHeaders(this.headers, sorted.map((item) => item.row));
+            this.headersDeferred = false;
+        }
+        else {
+            sheet.updateRows(sorted.map((item) => ({ rowIndex: item.dataIndex, values: item.row })));
+        }
+    }
+    /** Shallow-clone an entity to prevent external mutation of cached data. */
+    cloneEntity(entity) {
+        return { ...entity };
+    }
+    /** Shallow-clone an array of entities. */
+    cloneEntities(entities) {
+        return entities.map((entity) => this.cloneEntity(entity));
+    }
+    /**
+     * Update the entity cache in place after a save (create or update).
+     *
+     * In batch mode, reuses {@link batchCachedData} to avoid repeated
+     * `cache.get()` calls that would trigger verbose logging overhead.
+     *
+     * @param entity - The saved entity.
+     * @param isNew  - Whether this was a create (append) or update (replace).
+     */
+    updateCacheAfterSave(entity, isNew) {
+        if (!this.cache)
+            return;
+        // In batch mode, reuse pre-fetched array ref to avoid N × cache.get() Logger.log() calls in GAS.
+        // batchCachedData is lazily initialised here on the first entity (after the cache entry is created
+        // by the CREATE path in doSave for entity #1 when dataIndex === 0).
+        let cached;
+        if (this.entityBatch !== null) {
+            if (!this.batchCachedData) {
+                this.batchCachedData = this.cache.get(this.dataCacheKey);
+            }
+            cached = this.batchCachedData;
+        }
+        else {
+            cached = this.cache.get(this.dataCacheKey);
+        }
+        if (!cached)
+            return;
+        if (isNew) {
+            // Append new entity to the cached array
+            cached.push(entity);
+        }
+        else {
+            // Replace existing entity in the cached array
+            for (let i = 0; i < cached.length; i++) {
+                if (cached[i]?.__id === entity.__id) {
+                    cached[i] = entity;
+                    return;
+                }
+            }
+        }
+    }
+    /**
+     * Remove a deleted entity from the entity cache.
+     *
+     * Note: {@link idToRowIndex} is updated separately in {@link doDelete}.
+     * This method only handles the entity array cache.
+     *
+     * @param id - The `__id` of the deleted entity.
+     */
+    updateCacheAfterDelete(id) {
+        if (!this.cache)
+            return;
+        const cached = this.cache.get(this.dataCacheKey);
+        if (!cached)
+            return;
+        for (let i = 0; i < cached.length; i++) {
+            if (cached[i]?.__id === id) {
+                cached.splice(i, 1);
+                return;
+            }
+        }
+    }
+    /**
+     * Check whether a field name has an `@Indexed` decorator.
+     *
+     * Uses the pre-built {@link indexedFieldNames} set for O(1) lookup.
+     *
+     * @param fieldName - Name of the field to check.
+     * @returns `true` if the field is indexed.
+     */
+    isIndexedField(fieldName) {
+        return this.indexedFieldNames.has(fieldName);
+    }
+}
+//# sourceMappingURL=SheetRepository.js.map