@b2bc-devkit/sheetorm 0.1.0

package/dist/npm/core/types/LifecycleHooks.d.ts

@@ -0,0 +1,32 @@
+import type { Entity } from "./Entity.js";
+/**
+ * Optional lifecycle hooks that can be attached to a SheetRepository.
+ *
+ * Hooks run synchronously during save / delete operations and can
+ * modify entities (beforeSave), validate data (onValidate), or
+ * perform side-effects (afterSave, afterDelete).
+ *
+ * @typeParam T - The entity type managed by the repository.
+ */
+export interface LifecycleHooks<T extends Entity> {
+    /**
+     * Called before an entity is written to the sheet.
+     * Return a modified partial to alter the data, or void to keep it unchanged.
+     */
+    beforeSave?(entity: Partial<T>, isNew: boolean): Partial<T> | void;
+    /** Called after an entity has been persisted to the sheet. */
+    afterSave?(entity: T, isNew: boolean): void;
+    /**
+     * Called before an entity is deleted.
+     * Return false to cancel the deletion.
+     */
+    beforeDelete?(id: string): boolean | void;
+    /** Called after an entity has been removed from the sheet. */
+    afterDelete?(id: string): void;
+    /**
+     * Validate entity data before save.
+     * Return an array of error messages to abort the save, or void to pass.
+     */
+    onValidate?(entity: Partial<T>): string[] | void;
+}
+//# sourceMappingURL=LifecycleHooks.d.ts.map

package/dist/npm/core/types/LifecycleHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LifecycleHooks.d.ts","sourceRoot":"","sources":["../../../../src/core/types/LifecycleHooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,MAAM;IAC9C;;;OAGG;IACH,UAAU,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAEnE,8DAA8D;IAC9D,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAE5C;;;OAGG;IACH,YAAY,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAE1C,8DAA8D;IAC9D,WAAW,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;OAGG;IACH,UAAU,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;CAClD"}

package/dist/npm/core/types/LifecycleHooks.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=LifecycleHooks.js.map

package/dist/npm/core/types/LifecycleHooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LifecycleHooks.js","sourceRoot":"","sources":["../../../../src/core/types/LifecycleHooks.ts"],"names":[],"mappings":""}

package/dist/npm/core/types/PaginatedResult.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Paginated query result returned by select() / Query.select().
+ *
+ * @typeParam T - Entity type of the paginated items.
+ */
+export interface PaginatedResult<T> {
+    /** Entities in the current page. */
+    items: T[];
+    /** Total number of entities matching the query (before pagination). */
+    total: number;
+    /** 0-based offset of the first item in the page. */
+    offset: number;
+    /** Maximum number of items per page. */
+    limit: number;
+    /** True if there are more items beyond this page. */
+    hasNext: boolean;
+}
+//# sourceMappingURL=PaginatedResult.d.ts.map

package/dist/npm/core/types/PaginatedResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PaginatedResult.d.ts","sourceRoot":"","sources":["../../../../src/core/types/PaginatedResult.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,oCAAoC;IACpC,KAAK,EAAE,CAAC,EAAE,CAAC;IAEX,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IAEd,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IAEf,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IAEd,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/npm/core/types/PaginatedResult.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=PaginatedResult.js.map

package/dist/npm/core/types/PaginatedResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PaginatedResult.js","sourceRoot":"","sources":["../../../../src/core/types/PaginatedResult.ts"],"names":[],"mappings":""}

package/dist/npm/core/types/QueryOptions.d.ts

@@ -0,0 +1,21 @@
+import type { Filter } from "./Filter.js";
+import type { SortClause } from "./SortClause.js";
+/**
+ * Declarative query descriptor used by SheetRepository.find() / count() / deleteAll().
+ *
+ * Supports AND-connected filters (where), OR-connected filter groups (whereGroups),
+ * multi-column sorting (orderBy), and pagination (offset / limit).
+ */
+export interface QueryOptions {
+    /** Filters combined with AND logic (mutually exclusive with whereGroups). */
+    where?: Filter[];
+    /** Filter groups combined with OR logic; each inner array is AND-connected. */
+    whereGroups?: Filter[][];
+    /** Sort clauses applied in order after filtering. */
+    orderBy?: SortClause[];
+    /** Maximum number of results to return. */
+    limit?: number;
+    /** Number of results to skip before returning (0-based). */
+    offset?: number;
+}
+//# sourceMappingURL=QueryOptions.d.ts.map

package/dist/npm/core/types/QueryOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryOptions.d.ts","sourceRoot":"","sources":["../../../../src/core/types/QueryOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IAEzB,qDAAqD;IACrD,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IAEvB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/npm/core/types/QueryOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=QueryOptions.js.map

package/dist/npm/core/types/QueryOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryOptions.js","sourceRoot":"","sources":["../../../../src/core/types/QueryOptions.ts"],"names":[],"mappings":""}

package/dist/npm/core/types/SortClause.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A single sort instruction used in QueryOptions.orderBy.
+ */
+export interface SortClause {
+    /** Entity field name to sort by (supports dot-separated nested paths). */
+    field: string;
+    /** Sort direction: ascending or descending. */
+    direction: "asc" | "desc";
+}
+//# sourceMappingURL=SortClause.d.ts.map

package/dist/npm/core/types/SortClause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SortClause.d.ts","sourceRoot":"","sources":["../../../../src/core/types/SortClause.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IAEd,+CAA+C;IAC/C,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;CAC3B"}

package/dist/npm/core/types/SortClause.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=SortClause.js.map

package/dist/npm/core/types/SortClause.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SortClause.js","sourceRoot":"","sources":["../../../../src/core/types/SortClause.ts"],"names":[],"mappings":""}

package/dist/npm/core/types/SystemColumns.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Constants for the three system-managed column names.
+ *
+ * These columns are always present in every SheetORM table and occupy
+ * the first three columns of the header row:
+ *   [__id, __createdAt, __updatedAt, ...userFields]
+ */
+export declare class SystemColumns {
+    /** Primary key column — holds the UUID v4 identifier. */
+    static readonly ID = "__id";
+    /** Auto-set to the ISO 8601 timestamp when the record is first created. */
+    static readonly CREATED_AT = "__createdAt";
+    /** Auto-updated to the ISO 8601 timestamp on every save. */
+    static readonly UPDATED_AT = "__updatedAt";
+}
+//# sourceMappingURL=SystemColumns.d.ts.map

package/dist/npm/core/types/SystemColumns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SystemColumns.d.ts","sourceRoot":"","sources":["../../../../src/core/types/SystemColumns.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB,yDAAyD;IACzD,MAAM,CAAC,QAAQ,CAAC,EAAE,UAAU;IAE5B,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,CAAC,UAAU,iBAAiB;IAE3C,4DAA4D;IAC5D,MAAM,CAAC,QAAQ,CAAC,UAAU,iBAAiB;CAC5C"}

package/dist/npm/core/types/SystemColumns.js

@@ -0,0 +1,16 @@
+/**
+ * Constants for the three system-managed column names.
+ *
+ * These columns are always present in every SheetORM table and occupy
+ * the first three columns of the header row:
+ *   [__id, __createdAt, __updatedAt, ...userFields]
+ */
+export class SystemColumns {
+}
+/** Primary key column — holds the UUID v4 identifier. */
+SystemColumns.ID = "__id";
+/** Auto-set to the ISO 8601 timestamp when the record is first created. */
+SystemColumns.CREATED_AT = "__createdAt";
+/** Auto-updated to the ISO 8601 timestamp on every save. */
+SystemColumns.UPDATED_AT = "__updatedAt";
+//# sourceMappingURL=SystemColumns.js.map

package/dist/npm/core/types/SystemColumns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SystemColumns.js","sourceRoot":"","sources":["../../../../src/core/types/SystemColumns.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;;AACxB,yDAAyD;AACzC,gBAAE,GAAG,MAAM,CAAC;AAE5B,2EAA2E;AAC3D,wBAAU,GAAG,aAAa,CAAC;AAE3C,4DAA4D;AAC5C,wBAAU,GAAG,aAAa,CAAC"}

package/dist/npm/core/types/TableSchema.d.ts

@@ -0,0 +1,24 @@
+import type { FieldDefinition } from "./FieldDefinition.js";
+import type { IndexDefinition } from "./IndexDefinition.js";
+/**
+ * Complete schema descriptor for a SheetORM-managed table.
+ *
+ * Built automatically by Registry.ensureRepository() from the
+ * Record subclass's static tableName / indexTableName and the
+ * decorator-collected field and index metadata.
+ */
+export interface TableSchema {
+    /** Name of the data sheet tab (e.g. "tbl_Cars"). */
+    tableName: string;
+    /**
+     * Name of the combined index sheet tab (e.g. "idx_Cars").
+     * Omitted when the class has no @Indexed fields — avoids
+     * unnecessary getSheetByName() API calls on every save.
+     */
+    indexTableName?: string;
+    /** All user-defined fields discovered from decorators and class properties. */
+    fields: FieldDefinition[];
+    /** Secondary index definitions from @Indexed() decorators. */
+    indexes: IndexDefinition[];
+}
+//# sourceMappingURL=TableSchema.d.ts.map

package/dist/npm/core/types/TableSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TableSchema.d.ts","sourceRoot":"","sources":["../../../../src/core/types/TableSchema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,+EAA+E;IAC/E,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B,8DAA8D;IAC9D,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B"}

package/dist/npm/core/types/TableSchema.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=TableSchema.js.map

package/dist/npm/core/types/TableSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TableSchema.js","sourceRoot":"","sources":["../../../../src/core/types/TableSchema.ts"],"names":[],"mappings":""}

package/dist/npm/index/IndexMeta.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Lightweight metadata describing a single secondary index entry
+ * as stored in the combined index sheet.
+ *
+ * Used by IndexStore to track which fields are indexed and whether
+ * they enforce uniqueness.
+ */
+export interface IndexMeta {
+    /** Name of the entity table that owns this index (e.g. "tbl_Cars"). */
+    tableName: string;
+    /** Name of the indexed field (e.g. "make", "email"). */
+    field: string;
+    /** When true, the index enforces that no two entities share the same field value. */
+    unique: boolean;
+}
+//# sourceMappingURL=IndexMeta.d.ts.map

package/dist/npm/index/IndexMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexMeta.d.ts","sourceRoot":"","sources":["../../../src/index/IndexMeta.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAElB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IAEd,qFAAqF;IACrF,MAAM,EAAE,OAAO,CAAC;CACjB"}

package/dist/npm/index/IndexMeta.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IndexMeta.js.map

package/dist/npm/index/IndexMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexMeta.js","sourceRoot":"","sources":["../../../src/index/IndexMeta.ts"],"names":[],"mappings":""}

package/dist/npm/index/IndexStore.d.ts

@@ -0,0 +1,399 @@
+/**
+ * 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 since J1 optimisation):
+ * ```
+ *   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 type { ISpreadsheetAdapter } from "../core/types/ISpreadsheetAdapter.js";
+import type { ISheetAdapter } from "../core/types/ISheetAdapter.js";
+import type { ICacheProvider } from "../core/types/ICacheProvider.js";
+import type { IndexMeta } from "./IndexMeta.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 declare class IndexStore {
+    /** Spreadsheet-level adapter for creating/deleting/finding sheets. */
+    private adapter;
+    /** Optional cache provider for memoising raw index data between reads. */
+    private cache;
+    /** Registry of all declared indexes: key = "tableName::field" → IndexMeta. */
+    private indexRegistry;
+    /** Lazy-built n-gram search indexes, keyed by "tableName::field". */
+    private searchIndexCache;
+    /** Pending batch writes (tableName → rows), or null when batch mode is off. */
+    private indexBatch;
+    /** Memoised sheet references — avoids duplicate getSheetByName() API calls within a session. */
+    private indexSheetCache;
+    /** Tracks known row count per index table — avoids full getAllData() reads to determine append position. */
+    private indexRowCount;
+    /** Character-level n-gram length used for search indexing (trigram = 3). */
+    private static readonly NGRAM_SIZE;
+    /**
+     * @param adapter - Spreadsheet adapter for sheet-level operations.
+     * @param cache   - Optional cache provider (e.g. MemoryCache) for index data.
+     */
+    constructor(adapter: ISpreadsheetAdapter, cache?: ICacheProvider);
+    /**
+     * Build a composite registry key for a (tableName, field) pair.
+     * Used as the key in `indexRegistry` and for search cache invalidation.
+     */
+    private registryKey;
+    /**
+     * 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: string): IndexMeta[];
+    /**
+     * 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: string, field: string, unique: boolean): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /**
+     * Discard all buffered index rows without writing (error/rollback path).
+     */
+    cancelIndexBatch(): void;
+    /**
+     * 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.
+     */
+    private getIndexSheet;
+    /**
+     * 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 (J1 optimisation — saves ~700 ms).
+     * - If the sheet **already** exists: seeds `indexRowCount` with a single
+     *   `getLastRow()` call (C1 optimisation) 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: string, preloadedSheet?: ISheetAdapter | null): void;
+    /**
+     * Check whether a combined index sheet exists for the given table name.
+     * Uses the memoised sheet cache when available.
+     */
+    existsCombined(indexTableName: string): boolean;
+    /**
+     * 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: string, field: string, value: unknown, entityId: string): void;
+    /**
+     * 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: string, entries: Array<{
+        field: string;
+        value: unknown;
+    }>, entityId: string): void;
+    /**
+     * 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: string, entityId: string): void;
+    /**
+     * 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: string, entityIds: string[]): void;
+    /**
+     * 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: string, entityId: string, oldValues: Record<string, unknown>, newValues: Record<string, unknown>): void;
+    /**
+     * 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: string, field: string, value: unknown): string[];
+    /**
+     * 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: string): void;
+    /**
+     * 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: string): string;
+    /**
+     * 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: string): string[];
+    /**
+     * 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: string, n: number): Set<string>;
+    /**
+     * 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.
+     */
+    private buildSearchIndex;
+    /**
+     * 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.
+     */
+    private static postingsForTokenViaNgrams;
+    /**
+     * 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.
+     */
+    private static intersectPostingLists;
+    /**
+     * 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.
+     */
+    private static intersectTwo;
+    /**
+     * 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: string, field: string, query: string, limit?: number): string[];
+    /**
+     * 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.
+     *
+     * **B6 optimisation**: 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, saving
+     * ~300 ms per call in Google Apps Script.
+     *
+     * @param indexTableName - Combined index sheet name.
+     * @returns 2-D array of raw row data (`[field, value, entityId]` per row).
+     */
+    private getCombinedData;
+    /**
+     * 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.
+     */
+    private invalidateSearchCacheForTable;
+    /**
+     * 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).
+     */
+    private clearCache;
+    /**
+     * 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(): void;
+}
+//# sourceMappingURL=IndexStore.d.ts.map

package/dist/npm/index/IndexStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexStore.d.ts","sourceRoot":"","sources":["../../../src/index/IndexStore.ts"],"names":[],"mappings":"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"}