@b2bc-devkit/sheetorm 0.1.0

package/readme.md

@@ -0,0 +1,672 @@
+# SheetORM
+
+A TypeScript ORM for Google Sheets running in Google Apps Script (GAS). SheetORM brings a structured,
+type-safe persistence layer to spreadsheet-based applications with an **ActiveRecord** API — define a class,
+extend `Record`, and everything just works.
+
+## Features
+
+- **ActiveRecord pattern** — Extend `Record`, define fields, and call `save()` / `find()` / `delete()`
+  directly on instances and classes
+- **Zero configuration** — Tables, schemas, indexes, and repositories are auto-created on first use
+- **Predictable naming** — Sheet names follow `tbl_{ClassName}s` (e.g. `tbl_Cars`); combined index sheets
+  follow `idx_{ClassName}s` (e.g. `idx_Cars`)
+- **Fluent query builder** — `where()`, `and()`, `or()`, `orderBy()`, `limit()`, `offset()`
+- **`Query.from()`** — Start queries from a class reference or string name
+- **Secondary indexes** — Stored in a single combined index sheet (`idx_{ClassName}s`) for fast lookup by
+  indexed fields
+- **N-gram text search** — Solr-like trigram search on `@Indexed` fields via `IndexStore.searchCombined()`;
+  also available as the `search` filter operator in queries
+- **In-memory caching** — Configurable TTL cache to reduce sheet reads
+- **Lifecycle hooks** — `beforeSave`, `afterSave`, `beforeDelete`, `afterDelete`
+- **Batch operations** — `beginBatch` / `commitBatch` / `rollbackBatch` for safe bulk writes
+- **Pagination & grouping** — `select()` returns `PaginatedResult<T>`, `groupBy()` returns `GroupResult<T>`
+- **Zero runtime dependencies** — Bundles into a single `Code.js` via Vite
+
+## Quick Start
+
+### 1. Install & build
+
+```bash
+npm install
+npm run build
+```
+
+### 2. Deploy to Google Apps Script
+
+```bash
+npm run login   # once per device
+node scripts/publish-gas.mjs  # build + push + version (+ deploy if GAS_DEPLOYMENT_ID is set)
+```
+
+### 3. Define a model
+
+Extend `Record` and declare fields as plain TypeScript properties. Use `@Indexed()` for indexed fields,
+`@Required()` for required fields, and `@Field()` for extra options. Undecorated properties are
+auto-discovered as fields.
+
+```ts
+import { Record } from "./src/core/Record";
+import { Decorators } from "./src/core/Decorators";
+
+const { Indexed, Required } = Decorators;
+
+class Car extends Record {
+  @Indexed()
+  make: string;
+
+  @Required()
+  model: string;
+
+  year: number;
+  color: string;
+}
+```
+
+- No `tableName` needed in the common case — the sheet name defaults to `tbl_` + class name + `s` (`Car` →
+  `tbl_Cars`)
+- When any field is decorated with `@Indexed()`, a combined index sheet is automatically created with the name
+  `idx_` + class name + `s` (`Car` → `idx_Cars`). Classes without `@Indexed` fields do **not** get an index
+  sheet.
+- `@Indexed()` — marks a field as a secondary index (also implies `@Field`)
+- `@Required()` — marks a field as required using concise decorator syntax
+- `@Field(...)` — adds extra field options like `type`, `defaultValue`, or `referenceTable`
+- Plain properties (`year`, `color`) — auto-discovered as schema fields with type inferred at runtime
+
+If you want a custom sheet name, override the static getters:
+
+```ts
+class ArchivedCar extends Record {
+  static override get tableName() {
+    return "ArchivedCars";
+  }
+
+  static override get indexTableName() {
+    return "idx_ArchivedCars";
+  }
+}
+```
+
+### Available decorators
+
+SheetORM supports three TypeScript property decorators on `Record` models.
+
+#### `@Required()`
+
+Use `@Required()` when a field must be present before `save()` succeeds.
+
+```ts
+class Car extends Record {
+  @Required()
+  model: string;
+}
+```
+
+This decorator is shorthand for `@Field({ required: true })`.
+
+#### `@Field(options?)`
+
+Use `@Field()` when you want to describe schema metadata explicitly.
+
+```ts
+class Car extends Record {
+  @Field({ type: "date" })
+  purchasedAt: Date;
+
+  @Field({ type: "reference", referenceTable: "Owners" })
+  ownerId: string;
+}
+```
+
+Supported options:
+
+| Option           | Type        | Description                              |
+| ---------------- | ----------- | ---------------------------------------- |
+| `required`       | `boolean`   | Rejects save when the field is missing   |
+| `type`           | `FieldType` | Overrides runtime type inference         |
+| `defaultValue`   | `unknown`   | Value used when the field is empty       |
+| `referenceTable` | `string`    | Target table name for `reference` fields |
+
+#### `@Indexed(options?)`
+
+Use `@Indexed()` when the field should have a secondary index for faster lookups.
+
+```ts
+class Car extends Record {
+  @Indexed()
+  make: string;
+
+  @Indexed({ unique: true })
+  vin: string;
+
+  @Indexed({ type: "date" })
+  registeredAt: Date;
+}
+```
+
+Supported options:
+
+| Option   | Type                             | Description                      |
+| -------- | -------------------------------- | -------------------------------- |
+| `unique` | `boolean`                        | Enforces uniqueness in the index |
+| `type`   | `"string" \| "number" \| "date"` | Controls index value typing      |
+
+#### Plain properties without annotations
+
+Not everything needs a decorator. Plain class properties are still discovered automatically and become normal
+schema fields:
+
+```ts
+class Car extends Record {
+  make: string;
+  model: string;
+  year: number;
+}
+```
+
+Use decorators only when you need schema metadata or indexing behaviour.
+
+### 4. Use it
+
+```ts
+// Create — table auto-created on first save
+const car = new Car();
+car.make = "Toyota";
+car.model = "Corolla";
+car.year = 2024;
+car.color = "blue";
+car.save();
+
+// Or use the static factory
+const civic = Car.create({ make: "Honda", model: "Civic", year: 2023, color: "white" });
+civic.save();
+
+// Fluent set + save (chainable)
+new Car().set("make", "Honda").set("model", "Civic").set("year", 2023).save();
+
+// Static queries — return typed Car[]
+const toyotas = Car.where("make", "=", "Toyota").execute();
+const found = Car.findById(car.__id);
+const all = Car.find();
+
+// Query.from() — class ref (typed) or string
+const recent = Query.from(Car).where("year", ">=", 2023).orderBy("year", "desc").limit(10).execute();
+
+// Update
+car.color = "red";
+car.save();
+
+// Delete
+car.delete();
+
+// Count, pagination, grouping
+Car.count();
+Car.select(0, 10);
+Car.groupBy("make");
+```
+
+See [`examples/cars-crud.ts`](examples/cars-crud.ts) for a complete runnable example.
+
+## Publishing (Apps Script & npm)
+
+### Apps Script library
+
+- Prerequisites: `npm run login` (clasp), `appsscript.json` configured for your script, and a Script ID to share.
+- Run `npm run publish:gas` (or VS Code task “Publish: Apps Script library”). It lints, tests, builds, pushes via `clasp push -f`, creates a new version with `GAS_VERSION_MESSAGE` (default: “SheetORM Apps Script release”), and, if `GAS_DEPLOYMENT_ID` is set, deploys with that description.
+- In the Apps Script editor, add the library by Script ID. Use `GasEntrypoints.Record`, `GasEntrypoints.Query`, and `GasEntrypoints.Decorators` in your GAS project; callable menu functions stay limited to `runTests`, `validateTests`, and `runBenchmark`.
+
+### npm package
+
+- Build distributable JS + type definitions with `npm run build:npm` (emits to `dist/npm`).
+- Vite stays dedicated to the GAS bundle; the npm build is plain TypeScript output so consumers can use their own bundler.
+- Publish with `node scripts/publish-npm.mjs` (or VS Code task “Publish: npm package”); set `NPM_TAG` to publish under a dist-tag if needed. The script runs lint, tests, build, then `npm publish --access public`.
+- Import via the bundled aggregator:
+
+```ts
+import { SheetOrm } from "sheetorm";
+
+const { Record, Query, Decorators } = SheetOrm;
+```
+
+- Or import individual surfaces directly: `import { Record } from "sheetorm/core/Record";`, `import { Query } from "sheetorm/query/Query";`, `import { Decorators } from "sheetorm/core/Decorators";`.
+
+### VS Code tasks
+
+Two tasks are available in `.vscode/tasks.json`:
+
+- `Publish: Apps Script library` → runs `npm run publish:gas`
+- `Publish: npm package` → runs `npm run publish:npm`
+
+## Architecture
+
+```
+src/
+  core/Record.ts          — ActiveRecord base class (primary API); tableName = tbl_{Name}s, indexTableName = idx_{Name}s
+  core/RecordConstructor.ts — Constructor contract for Record subclasses
+  core/RecordStatic.ts    — Registry-facing static Record contract
+  core/Registry.ts        — Global singleton: adapter, repos, class map
+  core/SheetRepository.ts — Generic repository: CRUD, batch, hooks, cache
+  core/types/             — One exported type / interface / class per file
+    Entity.ts             —   Entity
+    FieldType.ts          —   FieldType
+    FieldDefinition.ts    —   FieldDefinition
+    IndexDefinition.ts    —   IndexDefinition
+    TableSchema.ts        —   TableSchema
+    FilterOperator.ts     —   FilterOperator
+    Filter.ts             —   Filter
+    SortClause.ts         —   SortClause
+    QueryOptions.ts       —   QueryOptions
+    PaginatedResult.ts    —   PaginatedResult
+    GroupResult.ts        —   GroupResult
+    LifecycleHooks.ts     —   LifecycleHooks
+    ISheetAdapter.ts      —   ISheetAdapter
+    ISpreadsheetAdapter.ts —  ISpreadsheetAdapter
+    ICacheProvider.ts     —   ICacheProvider
+    SystemColumns.ts      —   SystemColumns
+  query/Query.ts          — Fluent query API + Query.from()
+  query/QueryEngine.ts    — filter, sort, paginate, group pipeline
+  index/IndexMeta.ts      — Index metadata contract
+  index/IndexStore.ts     — Secondary index management
+  storage/GoogleSheetAdapter.ts — Native GAS sheet wrapper
+  storage/GoogleSpreadsheetAdapter.ts — Native GAS spreadsheet wrapper
+  storage/SheetsAPIv4SheetAdapter.ts — Buffered Sheets API v4 sheet wrapper
+  storage/SheetsAPIv4SpreadsheetAdapter.ts — Buffered Sheets API v4 spreadsheet wrapper
+  core/cache/MemoryCache.ts — In-memory cache implementation
+  utils/Uuid.ts           — UUID v4 generation (GAS / fallback)
+  utils/Serialization.ts  — Row ↔ Entity conversion
+  testing/ParityCatalog.ts  — Canonical Jest ↔ runtime test case list
+  testing/RuntimeParity.ts  — GAS runtime parity suite
+  testing/RuntimeBenchmark.ts — GAS runtime benchmark (Cars + Workers, 1 000 records)
+  SheetOrm.ts             — npm-facing aggregator for Record/Query/Decorators
+  index.ts                — `GasEntrypoints` export for GAS globals
+examples/
+  cars-crud.ts            — Full ActiveRecord example
+```
+
+## Code Organization Rules
+
+Repository conventions are intentionally strict:
+
+- one exported class / interface / type / enum per file
+- no barrel files and no multi-export "grab bag" modules
+- exported free functions are not allowed; behavior should live on classes as static methods
+- filenames must match the exported artifact name (for example `Record.ts`, `QueryOptions.ts`, `SystemColumns.ts`)
+- internal helpers may stay private to a file, but the file's public surface must stay singular and obvious
+
+When adding new files, follow these rules first and treat them as part of the repository contract.
+
+## API Reference
+
+### Record (ActiveRecord base class)
+
+Extend `Record` to define a model. Declare fields as plain class properties — they are auto-discovered. Use
+decorators and an optional static property to customize behavior:
+
+| Decorator / property          | Description                                                                  |
+| ----------------------------- | ---------------------------------------------------------------------------- |
+| `@Required()`                 | Shorthand for marking a field as required                                    |
+| `@Field(options?)`            | Explicit field with options (required, type, defaultValue)                   |
+| `@Indexed(options?)`          | Secondary index (implies `@Field`); auto-creates `idx_{ClassName}s`          |
+| `static get tableName()`      | Sheet name (defaults to `tbl_{ClassName}s` — e.g. `tbl_Cars` for `Car`)      |
+| `static get indexTableName()` | Combined index sheet name (defaults to `idx_{ClassName}s` — e.g. `idx_Cars`) |
+
+#### `@Required()`
+
+Use `@Required()` when a value must be present before saving.
+
+| Behavior            | Description                                                                |
+| ------------------- | -------------------------------------------------------------------------- |
+| Required validation | Rejects `save()` when the field is `undefined`, `null`, or an empty string |
+| Equivalent form     | Same as `@Field({ required: true })`                                       |
+
+#### `@Field` options
+
+| Option           | Type        | Default     | Description                                                                |
+| ---------------- | ----------- | ----------- | -------------------------------------------------------------------------- |
+| `required`       | `boolean`   | `false`     | Reject saves when the value is missing                                     |
+| `type`           | `FieldType` | auto-infer  | Explicit type (`string`, `number`, `boolean`, `date`, `json`, `reference`) |
+| `defaultValue`   | `any`       | `undefined` | Value used when the field is empty                                         |
+| `referenceTable` | `string`    | `undefined` | Target table for `reference` type fields                                   |
+
+#### `@Indexed` options
+
+| Option   | Type        | Default    | Description                     |
+| -------- | ----------- | ---------- | ------------------------------- |
+| `unique` | `boolean`   | `false`    | Enforce uniqueness in the index |
+| `type`   | `FieldType` | auto-infer | Index value type                |
+
+#### Auto-discovered fields
+
+Any property declared on a `Record` subclass that is **not** a system column (`__id`, `__createdAt`,
+`__updatedAt`) and is **not** a function is automatically treated as a schema field. Its type is inferred at
+runtime from the value (`typeof`). You only need `@Field()` when you want to set options like `required` or an
+explicit type.
+
+> In this repository, examples use direct source imports such as `./src/core/Record`. The GAS bundle itself
+> exposes callable globals through `GasEntrypoints`, not a general-purpose npm package surface.
+
+#### Instance methods
+
+| Method              | Returns   | Description                   |
+| ------------------- | --------- | ----------------------------- |
+| `save()`            | `this`    | Insert or update (chainable)  |
+| `delete()`          | `boolean` | Delete from sheet             |
+| `set(field, value)` | `this`    | Set a field value (chainable) |
+| `get(field)`        | `unknown` | Get a field value             |
+| `toJSON()`          | `object`  | Plain object with all fields  |
+
+#### Static methods
+
+| Method                            | Returns              | Description                           |
+| --------------------------------- | -------------------- | ------------------------------------- |
+| `create(data)`                    | `T`                  | Factory: create instance with data    |
+| `findById(id)`                    | `T \| null`          | Find by primary key                   |
+| `find(options?)`                  | `T[]`                | Find all (with optional filters/sort) |
+| `findOne(options?)`               | `T \| null`          | Find first matching entity            |
+| `where(field, op, value)`         | `Query<T>`           | Start a filtered query chain          |
+| `query()`                         | `Query<T>`           | Start an empty query chain            |
+| `count(options?)`                 | `number`             | Count matching entities               |
+| `deleteAll(options?)`             | `number`             | Delete matching entities              |
+| `select(offset, limit, options?)` | `PaginatedResult<T>` | Paginated query                       |
+| `groupBy(field, options?)`        | `GroupResult<T>[]`   | Group by field                        |
+
+### Query\<T\>
+
+```ts
+Car.where("make", "=", "Toyota")
+  .and("year", ">=", 2020)
+  .or("color", "=", "red")
+  .orderBy("year", "desc")
+  .limit(20)
+  .offset(40)
+  .execute(); // T[]
+// .first()      // T | null
+// .count()      // number
+// .groupBy("field") // GroupResult<T>[]
+```
+
+Start from any class:
+
+```ts
+Query.from(Car).where("year", ">=", 2023).execute();
+Query.from("Car").where("make", "=", "Toyota").first();
+```
+
+### Filter operators
+
+`=`, `!=`, `<`, `>`, `<=`, `>=`, `contains`, `startsWith`, `in`, `search`
+
+The `search` operator uses an in-memory **trigram (n-gram) index** built from the combined index sheet
+(`idx_{ClassName}s`). When the target field is `@Indexed`, the query is optimised: candidates are narrowed via
+the n-gram index first, then verified with a substring match. For non-indexed fields `search` falls back to a
+simple case-insensitive `contains`.
+
+```ts
+// Fast n-gram search on @Indexed field — uses idx_Cars
+const hits = Car.where("model", "search", "320i").execute();
+
+// Programmatic access via IndexStore
+const ids = indexStore.searchCombined("idx_Cars", "model", "320i");
+```
+
+### Field types
+
+`string`, `number`, `boolean`, `json`, `date`, `reference`
+
+## Testing
+
+```bash
+npm test
+```
+
+Runs **128 unit and benchmark tests** across 9 test suites using Jest + ts-jest with in-memory mock adapters:
+
+| Suite                      | Tests | Description                                  |
+| -------------------------- | ----- | -------------------------------------------- |
+| `record.test.ts`           | 34    | ActiveRecord API (save, find, query, Query)  |
+| `query-engine.test.ts`     | 21    | Filter, sort, paginate, group                |
+| `serialization.test.ts`    | 14    | Row ↔ Entity conversion                      |
+| `query.test.ts`            | 11    | Fluent query API                             |
+| `index-store.test.ts`      | 11    | Secondary index CRUD                         |
+| `cache.test.ts`            | 8     | MemoryCache TTL behavior                     |
+| `uuid.test.ts`             | 2     | UUID generation                              |
+| `parity-validator.test.ts` | 3     | Jest ↔ GAS runtime parity check              |
+| `benchmark.test.ts`        | 4     | 1 000-record perf benchmark: Cars vs Workers |
+
+### Benchmark Tests (`benchmark.test.ts`)
+
+Two benchmark suites exercise the complete Record API against **1 000 records**:
+
+| Suite             | Class    | Table         | Index sheet   | Notes                                |
+| ----------------- | -------- | ------------- | ------------- | ------------------------------------ |
+| Cars benchmark    | `Car`    | `tbl_Cars`    | `idx_Cars`    | All fields decorated with `@Indexed` |
+| Workers benchmark | `Worker` | `tbl_Workers` | _not created_ | No `@Indexed` fields                 |
+
+Both suites emit progress logs to stdout, covering every Record API operation: `save()`, `count()`,
+`findById()`, `find()`, `findOne()`, `where()`, `query()`, `select()`, `groupBy()`, `update via save()`,
+`set()/get()`, `delete()`, `deleteAll()`, `Query.from()`, `toJSON()`.
+
+A timing comparison is printed at the end:
+
+```
+════════════════════════════════════════
+BENCHMARK SUMMARY
+════════════════════════════════════════
+tbl_Cars  (with @Indexed):   311 ms
+tbl_Workers (no @Indexed):   28 ms
+Difference:                  283 ms
+Faster suite: tbl_Workers (by 283 ms)
+Note: in mock environment @Indexed adds write overhead (index sheet writes).
+      In real Google Sheets, @Indexed enables faster lookups (fewer API reads).
+════════════════════════════════════════
+```
+
+> **Note**: In the in-memory mock environment `@Indexed` adds write overhead (each indexed field value is
+> written to the `idx_Cars` sheet). In real Google Sheets, `@Indexed` trades additional write cost for faster
+> read lookups — beneficial when reading large datasets frequently.
+
+### Jest ↔ GAS Runtime Parity (1:1)
+
+Every Jest test has a matching handler in the GAS runtime parity suite. This ensures the library works
+identically with real Google Sheets:
+
+- `src/testing/ParityCatalog.ts` — canonical list of all Jest test cases
+- `src/testing/RuntimeParity.ts` — runtime suite executing against real Sheets API
+- `tests/parity-validator.test.ts` — fails when Jest and runtime cases diverge
+
+Run locally (mock adapters):
+
+```bash
+npm test
+```
+
+Run in Google Apps Script (real Sheets API):
+
+- `runTests()` — executes full runtime parity suite against the active spreadsheet
+- `validateTests()` — validates mapping only (fast drift check)
+
+### GAS Runtime Benchmark
+
+A runtime benchmark mirrors `tests/benchmark.test.ts` and runs against the real Sheets API:
+
+- `src/testing/RuntimeBenchmark.ts` — benchmark runner for Cars + Workers (100 records each)
+
+Run in Google Apps Script (real Sheets API):
+
+- `runBenchmark()` — executes full Cars + Workers benchmark and logs a timing summary
+
+## Exposed GAS Functions
+
+Only three callable functions are surfaced as GAS globals (visible in the Apps Script editor Run menu and
+callable as triggers). Everything else is an internal implementation detail bundled into `Code.js`.
+
+| Function        | Signature                | Purpose                                                                                                                                                                                                           | When to use                                                                                                                |
+| --------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `runTests`      | `runTests(): void`       | Executes the full runtime parity suite (all ~146 test cases) against the active Google Spreadsheet. Logs per-test PASS/FAIL to `Logger` and cleans up all temporary sheets after the run.                         | After deploying a new version of SheetORM to GAS to verify the real Sheets API behaves identically to the Jest mock suite. |
+| `validateTests` | `validateTests(): void`  | Checks that every Jest test case has a matching GAS handler (and vice versa). Throws immediately if the two catalogs have drifted — no Sheets API calls made.                                                     | Quick sanity check during development; runs in milliseconds without touching any spreadsheet.                              |
+| `runBenchmark`  | `runBenchmark(): void`   | Runs a write/read/query/delete cycle for Cars (with `@Indexed`) and Workers (without `@Indexed`) using 100 records each. Logs per-operation timings and a comparison summary to `Logger`.                         | Measuring real-world Sheets API performance and understanding the latency trade-off of `@Indexed` versus plain tables.     |
+
+## CI
+
+GitHub Actions workflow at `.github/workflows/ci.yml`:
+
+1. TypeScript type-check (`tsc --noEmit`)
+2. Unit tests (`npm test`)
+3. Production build (`npm run build`)
+4. Verify `Code.js` output exists
+
+Matrix: Node 18, 20, 22.
+
+## Available Scripts
+
+| Script           | Description                                  |
+| ---------------- | -------------------------------------------- |
+| `npm run build`  | Clean + compile TypeScript + bundle via Vite |
+| `npm test`       | Run all Jest tests                           |
+| `npm run lint`   | Lint with ESLint                             |
+| `npm run format` | Format with Prettier                         |
+| `npm run login`  | Authenticate with Google Apps Script (once)  |
+| `npm run push`   | Build + push to GAS                          |
+| `npm run deploy` | Build + push + create versioned deployment   |
+
+## Sheet Layout
+
+Each registered table occupies one sheet. Row 1 contains headers: `__id`, `__createdAt`, `__updatedAt`,
+followed by schema-defined fields. Data starts at row 2.
+
+Special sheets:
+
+- `tbl_{ClassName}s` — Data sheet (e.g. `tbl_Cars` for class `Car`)
+- `idx_{ClassName}s` — Combined secondary index sheet (e.g. `idx_Cars`). Created automatically when the class
+  has at least one `@Indexed` field. Columns: `[field, value, entityId]` — each row maps one indexed field
+  value to its owning record. Classes with no `@Indexed` fields do **not** get an index sheet.
+
+## Storage Adapters
+
+SheetORM separates sheet I/O behind two interfaces defined in `src/core/types/ISheetAdapter.ts` and `src/core/types/ISpreadsheetAdapter.ts`:
+
+- **`ISpreadsheetAdapter`** — spreadsheet-level operations: `getSheetByName`, `createSheet`, `deleteSheet`, `getSheetNames`
+- **`ISheetAdapter`** — sheet-level operations: read (`getAllData`, `getHeaders`, `getRow`, …), write (`appendRows`, `writeRowsAt`, `updateRow`, …), `clear`, `flush`
+
+Two production adapters are provided. Both implement the full interface; they differ only in how write calls reach Google Sheets.
+
+### `GoogleSpreadsheetAdapter` / `GoogleSheetAdapter`
+
+**Location**: `src/storage/GoogleSpreadsheetAdapter.ts`, `src/storage/GoogleSheetAdapter.ts`
+
+Uses the native GAS `SpreadsheetApp` / `Sheet` objects directly. This is the default adapter — no configuration required.
+
+```ts
+import { GoogleSpreadsheetAdapter } from "./src/storage/GoogleSpreadsheetAdapter";
+import { Registry } from "./src/core/Registry";
+
+Registry.getInstance().configure({
+  adapter: new GoogleSpreadsheetAdapter(), // uses active spreadsheet
+});
+// … or pass an explicit spreadsheet:
+Registry.getInstance().configure({
+  adapter: new GoogleSpreadsheetAdapter(SpreadsheetApp.openById("…")),
+});
+```
+
+| Property             | Value                                                              |
+| -------------------- | ------------------------------------------------------------------ |
+| Write mechanism      | `Range.setValues()` — GAS native API                               |
+| Calls per `saveAll`  | **2** — one `setValues` for entity sheet + one for index sheet     |
+| Flush required       | No — writes are synchronous and immediately visible                |
+| Quota impact         | Counts against SpreadsheetApp call budget (no daily UrlFetch quota)|
+| Read operations      | Native `Range.getValues()`                                         |
+| GAS V8 latency       | ~300–500 ms per `setValues` call on large ranges                   |
+| Best for             | All production use; default choice                                 |
+
+### `SheetsAPIv4SpreadsheetAdapter` / `SheetsAPIv4SheetAdapter`
+
+**Location**: `src/storage/SheetsAPIv4SpreadsheetAdapter.ts`, `src/storage/SheetsAPIv4SheetAdapter.ts`
+
+Buffers all write operations (`writeRowsAt`, `appendRows`) in memory as A1-notation `ValueRange` objects and sends them all in a **single HTTP `spreadsheets.values.batchUpdate` request** when `flushAllPending()` is called. Read operations still use the native GAS API (the ORM reads from in-memory cache after `saveAll`, so extra sheet reads are rare).
+
+```ts
+import { SheetsAPIv4SpreadsheetAdapter } from "./src/storage/SheetsAPIv4SpreadsheetAdapter";
+import { Registry } from "./src/core/Registry";
+
+const v4 = new SheetsAPIv4SpreadsheetAdapter(); // uses active spreadsheet
+Registry.getInstance().configure({ adapter: v4 });
+
+MyRecord.saveAll(items);     // buffers entity rows + index rows in memory
+v4.flushAllPending();        // ONE HTTP batchUpdate — both sheets at once
+```
+
+| Property             | Value                                                                      |
+| -------------------- | -------------------------------------------------------------------------- |
+| Write mechanism      | `UrlFetchApp.fetch()` → Sheets REST API v4 `values:batchUpdate`            |
+| Calls per `saveAll`  | **1** — entity sheet + index sheet rows combined in one HTTP request       |
+| Flush required       | **Yes** — call `v4.flushAllPending()` after each `saveAll` (or batch)      |
+| Auth                 | `ScriptApp.getOAuthToken()` — reuses the existing `spreadsheets` scope     |
+| Quota impact         | `UrlFetchApp` quota: 20 000 calls/day per script                           |
+| Read operations      | Native `Range.getValues()` — unchanged                                     |
+| GAS V8 latency       | 1 HTTP round-trip instead of N `setValues()` calls                         |
+| Best for             | Benchmarking / high-volume batch imports where minimising API calls matters |
+
+**Required OAuth scopes** (already set in `appsscript.json`):
+
+```json
+"oauthScopes": [
+  "https://www.googleapis.com/auth/spreadsheets",
+  "https://www.googleapis.com/auth/script.external_request"
+]
+```
+
+### Adapter comparison
+
+| Criterion                   | `GoogleSpreadsheetAdapter` | `SheetsAPIv4SpreadsheetAdapter` |
+| --------------------------- | :------------------------: | :-----------------------------: |
+| Setup complexity            | None                       | Requires `flushAllPending()` call |
+| Write batching              | 2 calls per `saveAll`      | 1 HTTP call per flush           |
+| Flush step needed           | No                         | Yes                             |
+| UrlFetch daily quota used   | No                         | Yes (1 per flush)               |
+| Works without internet auth | Yes (native GAS)           | No (needs `UrlFetchApp`)        |
+| In-band error visibility    | Immediate on write         | Deferred to flush               |
+| Recommended default         | ✅ Yes                     | Only for bulk-write optimisation |
+
+The `GoogleSpreadsheetAdapter` is the default and recommended choice for all production use. The `SheetsAPIv4SpreadsheetAdapter` is provided as an opt-in for scenarios where reducing the number of GAS API calls is the primary concern (e.g. large batch imports exceeding GAS execution-time limits).
+
+## Development Notes
+
+### Exposing Functions to GAS
+
+`src/index.ts` now exports a single `GasEntrypoints` class. During bundling, the Vite GAS plugin maps its
+static methods to GAS globals (`runTests`, `validateTests`, `runBenchmark`) and also emits matching stub
+functions so that Apps Script still shows them in the Run menu.
+
+```ts
+export class GasEntrypoints {
+  static runTests(): void {
+    RuntimeParity.run();
+  }
+
+  static validateTests(): void {
+    RuntimeParity.validate();
+  }
+
+  static runBenchmark(): void {
+    RuntimeBenchmark.run();
+  }
+}
+```
+
+This keeps the source aligned with the repository rule of one public export per file while preserving the same
+three callable GAS entrypoints.
+
+### Circular Dependencies
+
+Circular dependencies (files that depend on each other in a circular manner) can cause unexpected issues like
+"X is not a function" or "X is not defined". If you are seeing these errors in your project and you know they
+are wrong, try checking for circular dependencies using [`madge`](https://github.com/pahen/madge) (not
+included in this template):
+
+1. Install `madge` globally with `npm i --global madge`.
+2. Check for circular dependencies with `madge src/index.ts --circular`.
+
+## License
+
+GPL-2.0 — see [license.md](license.md).