@b2bc-devkit/sheetorm 0.1.0 → 1.0.0

package/{readme.md → README.md}

@@ -1,9 +1,15 @@
 # SheetORM
 
+<p>
+  <img src="assets/logo.png" alt="SheetORM logo" width="100%" />
+</p>
+
 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.
 
+<img src="assets/demo.gif" alt="SheetORM demo" />
+
 ## Features
 
 - **ActiveRecord pattern** — Extend `Record`, define fields, and call `save()` / `find()` / `delete()`
@@ -207,40 +213,11 @@ 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/Decorators.ts      — @Field, @Indexed, @Required property decorators
   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
@@ -269,11 +246,10 @@ src/
   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
+  utils/SheetOrmLogger.ts — Verbose logger for API-call tracing
   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)
@@ -283,18 +259,6 @@ 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)
@@ -419,19 +383,21 @@ const ids = indexStore.searchCombined("idx_Cars", "model", "320i");
 npm test
 ```
 
-Runs **128 unit and benchmark tests** across 9 test suites using Jest + ts-jest with in-memory mock adapters:
+Runs **333 unit and benchmark tests** across 11 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                              |
+| `record.test.ts`           | 74    | ActiveRecord API (save, find, query, Query)  |
+| `query-engine.test.ts`     | 60    | Filter, sort, paginate, group                |
+| `serialization.test.ts`    | 47    | Row ↔ Entity conversion                      |
+| `index-store.test.ts`      | 44    | Secondary index CRUD                         |
+| `query.test.ts`            | 41    | Fluent query API                             |
+| `sheet-repository.test.ts` | 35    | SheetRepository CRUD, batch, hooks           |
+| `cache.test.ts`            | 16    | MemoryCache TTL behavior                     |
+| `benchmark.test.ts`        | 6     | 1 000-record perf benchmark: Cars vs Workers |
+| `uuid.test.ts`             | 5     | UUID generation                              |
 | `parity-validator.test.ts` | 3     | Jest ↔ GAS runtime parity check              |
-| `benchmark.test.ts`        | 4     | 1 000-record perf benchmark: Cars vs Workers |
+| `sheetorm.test.ts`         | 2     | npm entry point smoke tests                  |
 
 ### Benchmark Tests (`benchmark.test.ts`)
 
@@ -482,7 +448,7 @@ npm test
 
 Run in Google Apps Script (real Sheets API):
 
-- `runTests()` — executes full runtime parity suite against the active spreadsheet
+- `runTestsStageOne()` / `runTestsStageTwo()` / `runTestsStageThree()` — staged runtime parity suite
 - `validateTests()` — validates mapping only (fast drift check)
 
 ### GAS Runtime Benchmark
@@ -497,25 +463,21 @@ Run in Google Apps Script (real Sheets API):
 
 ## Exposed GAS Functions
 
-Only three callable functions are surfaced as GAS globals (visible in the Apps Script editor Run menu and
+The following 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.
+| Function               | Purpose                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------------ |
+| `runTestsStageOne()`   | Stage-one parity tests (basic CRUD + query) against the active spreadsheet.                      |
+| `runTestsStageTwo()`   | Stage-two parity tests (indexes + search).                                                       |
+| `runTestsStageThree()` | Stage-three parity tests (advanced queries + pagination).                                        |
+| `validateTests()`      | Checks Jest ↔ GAS handler mapping parity — no Sheets API calls, fails immediately on drift.      |
+| `runBenchmark()`       | Write/read/query/delete cycle for Cars + Workers (100 records each); logs per-operation timings. |
+| `removeAllSheets()`    | Deletes every sheet in the active spreadsheet (destructive — use with caution).                  |
+| `demoCreate()`         | Creates 5 sample DemoCar records in the sheet.                                                   |
+| `demoRead()`           | Reads and logs DemoCar records using find/query/where.                                           |
+| `demoUpdate()`         | Updates existing DemoCar records and logs changes.                                               |
+| `demoDelete()`         | Deletes DemoCar records and verifies removal.                                                    |
 
 ## Available Scripts
 
@@ -526,8 +488,6 @@ Matrix: Node 18, 20, 22.
 | `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
 
@@ -543,18 +503,22 @@ Special sheets:
 
 ## Storage Adapters
 
-SheetORM separates sheet I/O behind two interfaces defined in `src/core/types/ISheetAdapter.ts` and `src/core/types/ISpreadsheetAdapter.ts`:
+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`
+- **`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.
+One production adapter pair is provided:
 
 ### `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.
+Uses the native GAS `SpreadsheetApp` / `Sheet` objects directly. This is the default adapter — no
+configuration required.
 
 ```ts
 import { GoogleSpreadsheetAdapter } from "./src/storage/GoogleSpreadsheetAdapter";
@@ -569,93 +533,29 @@ Registry.getInstance().configure({
 });
 ```
 
-| 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).
+| 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                                  |
 
 ## 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();
-  }
+`src/index.ts` exports a single `GasEntrypoints` class. During bundling, the Vite GAS plugin maps its static
+methods to GAS globals and emits matching stub functions so that Apps Script shows them in the Run menu.
 
-  static validateTests(): void {
-    RuntimeParity.validate();
-  }
-
-  static runBenchmark(): void {
-    RuntimeBenchmark.run();
-  }
-}
-```
+GAS-callable methods include staged test runners (`runTestsStageOne`/`Two`/`Three`), `validateTests`,
+`runBenchmark`, `removeAllSheets`, and four CRUD demos (`demoCreate`, `demoRead`, `demoUpdate`, `demoDelete`).
+The class also exposes core API classes (`Record`, `Query`, `Decorators`, `IndexStore`, `Registry`,
+`SheetOrmLogger`) as static readonly fields for use inside GAS scripts.
 
-This keeps the source aligned with the repository rule of one public export per file while preserving the same
-three callable GAS entrypoints.
+This keeps the source aligned with the repository rule of one public export per file.
 
 ### Circular Dependencies
 
@@ -669,4 +569,4 @@ included in this template):
 
 ## License
 
-GPL-2.0 — see [license.md](license.md).
+GPL-3.0-or-later — see [license.md](license.md).

package/license.md

@@ -1,18 +1,475 @@
-MIT License
+# GNU GENERAL PUBLIC LICENSE
 
-Copyright (c) 2023 Ian Sanders
+Version 3, 29 June 2007
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
-documentation files (the "Software"), to deal in the Software without restriction, including without
-limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
-Software, and to permit persons to whom the Software is furnished to do so, subject to the following
-conditions:
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions
-of the Software.
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not
+allowed.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
-TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
-THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
-CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-DEALINGS IN THE SOFTWARE.
+## Preamble
+
+The GNU General Public License is a free, copyleft license for software and other kinds of works.
+
+The licenses for most software and other practical works are designed to take away your freedom to share and
+change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share
+and change all versions of a program--to make sure it remains free software for all its users. We, the Free
+Software Foundation, use the GNU General Public License for most of our software; it applies also to any other
+work released this way by its authors. You can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are
+designed to make sure that you have the freedom to distribute copies of free software (and charge for them if
+you wish), that you receive source code or can get it if you want it, that you can change the software or use
+pieces of it in new free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the
+rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you
+modify it: responsibilities to respect the freedom of others.
+
+For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the
+recipients the same freedoms that you received. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and
+(2) offer you this License giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free
+software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so
+that their problems will not be attributed erroneously to authors of previous versions.
+
+Some devices are designed to deny users access to install or run modified versions of the software inside
+them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting
+users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for
+individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version
+of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains,
+we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect
+the freedom of users.
+
+Finally, every program is threatened constantly by software patents. States should not allow patents to
+restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid
+the special danger that patents applied to a free program could make it effectively proprietary. To prevent
+this, the GPL assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and modification follow.
+
+## TERMS AND CONDITIONS
+
+### 0. Definitions.
+
+"This License" refers to version 3 of the GNU General Public License.
+
+"Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as
+"you". "Licensees" and "recipients" may be individuals or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright
+permission, other than the making of an exact copy. The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based on the Program.
+
+To "propagate" a work means to do anything with it that, without permission, would make you directly or
+secondarily liable for infringement under applicable copyright law, except executing it on a computer or
+modifying a private copy. Propagation includes copying, distribution (with or without modification), making
+available to the public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere
+interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient
+and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that
+there is no warranty for the work (except to the extent that warranties are provided), that licensees may
+convey the work under this License, and how to view a copy of this License. If the interface presents a list
+of user commands or options, such as a menu, a prominent item in the list meets this criterion.
+
+### 1. Source Code.
+
+The "source code" for a work means the preferred form of the work for making modifications to it. "Object
+code" means any non-source form of a work.
+
+A "Standard Interface" means an interface that either is an official standard defined by a recognized
+standards body, or, in the case of interfaces specified for a particular programming language, one that is
+widely used among developers working in that language.
+
+The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is
+included in the normal form of packaging a Major Component, but which is not part of that Major Component, and
+(b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for
+which an implementation is available to the public in source code form. A "Major Component", in this context,
+means a major essential component (kernel, window system, and so on) of the specific operating system (if any)
+on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used
+to run it.
+
+The "Corresponding Source" for a work in object code form means all the source code needed to generate,
+install, and (for an executable work) run the object code and to modify the work, including scripts to control
+those activities. However, it does not include the work's System Libraries, or general-purpose tools or
+generally available free programs which are used unmodified in performing those activities but which are not
+part of the work. For example, Corresponding Source includes interface definition files associated with source
+files for the work, and the source code for shared libraries and dynamically linked subprograms that the work
+is specifically designed to require, such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can regenerate automatically from other parts of
+the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same work.
+
+### 2. Basic Permissions.
+
+All rights granted under this License are granted for the term of copyright on the Program, and are
+irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission
+to run the unmodified Program. The output from running a covered work is covered by this License only if the
+output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or
+other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey, without conditions so long as your
+license otherwise remains in force. You may convey covered works to others for the sole purpose of having them
+make modifications exclusively for you, or provide you with facilities for running those works, provided that
+you comply with the terms of this License in conveying all material for which you do not control copyright.
+Those thus making or running the covered works for you must do so exclusively on your behalf, under your
+direction and control, on terms that prohibit them from making any copies of your copyrighted material outside
+their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is
+not allowed; section 10 makes it unnecessary.
+
+### 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling
+obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws
+prohibiting or restricting circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to
+the extent such circumvention is effected by exercising rights under this License with respect to the covered
+work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing,
+against the work's users, your or third parties' legal rights to forbid circumvention of technological
+measures.
+
+### 4. Conveying Verbatim Copies.
+
+You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all
+notices stating that this License and any non-permissive terms added in accord with section 7 apply to the
+code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License
+along with the Program.
+
+You may charge any price or no price for each copy that you convey, and you may offer support or warranty
+protection for a fee.
+
+### 5. Conveying Modified Source Versions.
+
+You may convey a work based on the Program, or the modifications to produce it from the Program, in the form
+of source code under the terms of section 4, provided that you also meet all of these conditions:
+
+- a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+- b) The work must carry prominent notices stating that it is released under this License and any conditions
+  added under section 7. This requirement modifies the requirement in section 4 to "keep intact all notices".
+- c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a
+  copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole
+  of the work, and all its parts, regardless of how they are packaged. This License gives no permission to
+  license the work in any other way, but it does not invalidate such permission if you have separately
+  received it.
+- d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the
+  Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make
+  them do so.
+
+A compilation of a covered work with other separate and independent works, which are not by their nature
+extensions of the covered work, and which are not combined with it such as to form a larger program, in or on
+a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting
+copyright are not used to limit the access or legal rights of the compilation's users beyond what the
+individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to
+the other parts of the aggregate.
+
+### 6. Conveying Non-Source Forms.
+
+You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also
+convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
+
+- a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium),
+  accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software
+  interchange.
+- b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium),
+  accompanied by a written offer, valid for at least three years and valid for as long as you offer spare
+  parts or customer support for that product model, to give anyone who possesses the object code either (1) a
+  copy of the Corresponding Source for all the software in the product that is covered by this License, on a
+  durable physical medium customarily used for software interchange, for a price no more than your reasonable
+  cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from
+  a network server at no charge.
+- c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding
+  Source. This alternative is allowed only occasionally and noncommercially, and only if you received the
+  object code with such an offer, in accord with subsection 6b.
+- d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer
+  equivalent access to the Corresponding Source in the same way through the same place at no further charge.
+  You need not require recipients to copy the Corresponding Source along with the object code. If the place to
+  copy the object code is a network server, the Corresponding Source may be on a different server (operated by
+  you or a third party) that supports equivalent copying facilities, provided you maintain clear directions
+  next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the
+  Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy
+  these requirements.
+- e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object
+  code and Corresponding Source of the work are being offered to the general public at no charge under
+  subsection 6d.
+
+A separable portion of the object code, whose source code is excluded from the Corresponding Source as a
+System Library, need not be included in conveying the object code work.
+
+A "User Product" is either (1) a "consumer product", which means any tangible personal property which is
+normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in
+favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical
+or common use of that class of product, regardless of the status of the particular user or of the way in which
+the particular user actually uses, or expects or is expected to use, the product. A product is a consumer
+product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless
+such uses represent the only significant mode of use of the product.
+
+"Installation Information" for a User Product means any methods, procedures, authorization keys, or other
+information required to install and execute modified versions of a covered work in that User Product from a
+modified version of its Corresponding Source. The information must suffice to ensure that the continued
+functioning of the modified object code is in no case prevented or interfered with solely because modification
+has been made.
+
+If you convey an object code work under this section in, or with, or specifically for use in, a User Product,
+and the conveying occurs as part of a transaction in which the right of possession and use of the User Product
+is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is
+characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation
+Information. But this requirement does not apply if neither you nor any third party retains the ability to
+install modified object code on the User Product (for example, the work has been installed in ROM).
+
+The requirement to provide Installation Information does not include a requirement to continue to provide
+support service, warranty, or updates for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed. Access to a network may be denied when the
+modification itself materially and adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a
+format that is publicly documented (and with an implementation available to the public in source code form),
+and must require no special password or key for unpacking, reading or copying.
+
+### 7. Additional Terms.
+
+"Additional permissions" are terms that supplement the terms of this License by making exceptions from one or
+more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as
+though they were included in this License, to the extent that they are valid under applicable law. If
+additional permissions apply only to part of the Program, that part may be used separately under those
+permissions, but the entire Program remains governed by this License without regard to the additional
+permissions.
+
+When you convey a copy of a covered work, you may at your option remove any additional permissions from that
+copy, or from any part of it. (Additional permissions may be written to require their own removal in certain
+cases when you modify the work.) You may place additional permissions on material, added by you to a covered
+work, for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you add to a covered work, you may (if
+authorized by the copyright holders of that material) supplement the terms of this License with terms:
+
+- a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this
+  License; or
+- b) Requiring preservation of specified reasonable legal notices or author attributions in that material or
+  in the Appropriate Legal Notices displayed by works containing it; or
+- c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such
+  material be marked in reasonable ways as different from the original version; or
+- d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
+- e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks;
+  or
+- f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material
+  (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability
+  that these contractual assumptions directly impose on those licensors and authors.
+
+All other non-permissive additional terms are considered "further restrictions" within the meaning of
+section 10. If the Program as you received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further restriction, you may remove that term. If a
+license document contains a further restriction but permits relicensing or conveying under this License, you
+may add to a covered work material governed by the terms of that license document, provided that the further
+restriction does not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must place, in the relevant source files,
+a statement of the additional terms that apply to those files, or a notice indicating where to find the
+applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or
+stated as exceptions; the above requirements apply either way.
+
+### 8. Termination.
+
+You may not propagate or modify a covered work except as expressly provided under this License. Any attempt
+otherwise to propagate or modify it is void, and will automatically terminate your rights under this License
+(including any patent licenses granted under the third paragraph of section 11).
+
+However, if you cease all violation of this License, then your license from a particular copyright holder is
+reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your
+license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable
+means prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder
+notifies you of the violation by some reasonable means, this is the first time you have received notice of
+violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30
+days after your receipt of the notice.
+
+Termination of your rights under this section does not terminate the licenses of parties who have received
+copies or rights from you under this License. If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same material under section 10.
+
+### 9. Acceptance Not Required for Having Copies.
+
+You are not required to accept this License in order to receive or run a copy of the Program. Ancillary
+propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive
+a copy likewise does not require acceptance. However, nothing other than this License grants you permission to
+propagate or modify any covered work. These actions infringe copyright if you do not accept this License.
+Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
+
+### 10. Automatic Licensing of Downstream Recipients.
+
+Each time you convey a covered work, the recipient automatically receives a license from the original
+licensors, to run, modify and propagate that work, subject to this License. You are not responsible for
+enforcing compliance by third parties with this License.
+
+An "entity transaction" is a transaction transferring control of an organization, or substantially all assets
+of one, or subdividing an organization, or merging organizations. If propagation of a covered work results
+from an entity transaction, each party to that transaction who receives a copy of the work also receives
+whatever licenses to the work the party's predecessor in interest had or could give under the previous
+paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in
+interest, if the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the rights granted or affirmed under this
+License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights
+granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a
+lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or
+importing the Program or any portion of it.
+
+### 11. Patents.
+
+A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which
+the Program is based. The work thus licensed is called the contributor's "contributor version".
+
+A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor,
+whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this
+License, of making, using, or selling its contributor version, but do not include claims that would be
+infringed only as a consequence of further modification of the contributor version. For purposes of this
+definition, "control" includes the right to grant patent sublicenses in a manner consistent with the
+requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's
+essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate
+the contents of its contributor version.
+
+In the following three paragraphs, a "patent license" is any express agreement or commitment, however
+denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to
+sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or
+commitment not to enforce a patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work
+is not available for anyone to copy, free of charge and under the terms of this License, through a publicly
+available network server or other readily accessible means, then you must either (1) cause the Corresponding
+Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this
+particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the
+patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the
+patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a
+country, would infringe one or more identifiable patents in that country that you have reason to believe are
+valid.
+
+If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by
+procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the
+covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then
+the patent license you grant is automatically extended to all recipients of the covered work and works based
+on it.
+
+A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the
+exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted
+under this License. You may not convey a covered work if you are a party to an arrangement with a third party
+that is in the business of distributing software, under which you make payment to the third party based on the
+extent of your activity of conveying the work, and under which the third party grants, to any of the parties
+who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of
+the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection
+with specific products or compilations that contain the covered work, unless you entered into that
+arrangement, or that patent license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to
+infringement that may otherwise be available to you under applicable patent law.
+
+### 12. No Surrender of Others' Freedom.
+
+If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the
+conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this License and any other pertinent
+obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that
+obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only
+way you could satisfy both those terms and this License would be to refrain entirely from conveying the
+Program.
+
+### 13. Use with the GNU Affero General Public License.
+
+Notwithstanding any other provision of this License, you have permission to link or combine any covered work
+with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and
+to convey the resulting work. The terms of this License will continue to apply to the part which is the
+covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning
+interaction through a network will apply to the combination as such.
+
+### 14. Revised Versions of this License.
+
+The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from
+time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program specifies that a certain numbered
+version of the GNU General Public License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that numbered version or of any later version published by the
+Free Software Foundation. If the Program does not specify a version number of the GNU General Public License,
+you may choose any version ever published by the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions of the GNU General Public License can
+be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that
+version for the Program.
+
+Later license versions may give you additional or different permissions. However, no additional obligations
+are imposed on any author or copyright holder as a result of your choosing to follow a later version.
+
+### 15. Disclaimer of Warranty.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED
+IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
+YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+### 16. Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER
+PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
+(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
+THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
+PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+### 17. Interpretation of Sections 15 and 16.
+
+If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect
+according to their terms, reviewing courts shall apply local law that most closely approximates an absolute
+waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability
+accompanies a copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+## How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest possible use to the public, the best way
+to achieve this is to make it free software which everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program. It is safest to attach them to the start of each source
+file to most effectively state the exclusion of warranty; and each file should have at least the "copyright"
+line and a pointer to where the full notice is found.
+
+    SheetORM — A TypeScript ORM for Google Sheets.
+    Copyright (C) 2025 b2bc-devkit
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b2bc-devkit/sheetorm",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "TypeScript ORM for Google Sheets (Google Apps Script runtime)",
   "type": "module",
   "license": "GPL-3.0-or-later",
@@ -49,6 +49,14 @@
     },
     "./package.json": "./package.json"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/b2bc-devkit/SheetORM.git"
+  },
+  "homepage": "https://github.com/b2bc-devkit/SheetORM#readme",
+  "bugs": {
+    "url": "https://github.com/b2bc-devkit/SheetORM/issues"
+  },
   "publishConfig": {
     "access": "public"
   },