diff --git a/CLAUDE.md b/CLAUDE.md index e82bb7f1..74d6fbd1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -490,8 +490,9 @@ total = QueryBuilder.from_table("orders") \ results = User.query().where("age > ?", [18]).order_by("name").get() # Methods: from_table(), select(), where(), or_where(), join(), left_join(), -# group_by(), having(), order_by(), limit(), get(), first(), count(), -# exists(), to_sql(), to_mongo() +# group_by(), having(), order_by(), limit(), offset(), skip(), take(), +# get(), first(), count(), exists(), to_sql(), to_mongo() +# (skip()/take() are the Mongo/Eloquent aliases of offset()/limit()) ``` NoSQL support: `to_mongo()` generates MongoDB query documents from the same fluent API. diff --git a/plan/query-builder-skip.md b/plan/query-builder-skip.md new file mode 100644 index 00000000..5d61410f --- /dev/null +++ b/plan/query-builder-skip.md @@ -0,0 +1,62 @@ +# Task: QueryBuilder chainable skip() / offset() / take() + +## Problem +An AI harness building on Tina4 reached for `QueryBuilder....skip(n)` and hit a wall: +the ORM query builder only exposes `limit(count, offset?)`, with the offset trapped as +`limit()`'s second positional arg. There is no chainable `skip()`, `offset()`, or +`take()`, even though the DocStore Mongo cursor HAS `.skip()` and QueryBuilder's own +`to_mongo()` already emits a `skip` key. Devs from Mongoose / Eloquent / Knex reach for +`.skip()` / `.offset()` and fail. + +## Scope +- [x] Measure all four: QB has only `limit(count, offset?)`, no `skip`/`offset`/`take` (confirmed) +- [x] Python — add `offset()`, `skip()` (→offset), `take()` (→limit) + tests (6, mutation-proven) +- [x] PHP — same + tests (6) +- [x] Ruby — same + tests (6) +- [x] Node — same + tests (8) + regenerated committed `types/orm/src/queryBuilder.d.ts` + +## Design (minimal, declarative) +Three thin fluent setters over existing internals (`_offset_val`, `_limit_val`): +- `offset(n)` — SQL-native name; exposes the already-stored offset as its own verb. +- `skip(n)` — alias of `offset`; the Mongo/Eloquent name; matches DocStore cursor + `to_mongo()`'s `skip` key. +- `take(n)` — alias of `limit`; the Eloquent name; pairs with `skip` (`.skip(20).take(10)`). +Both SQL `get()` and `to_mongo()` already read `_offset_val`/`_limit_val`, so no +further wiring is needed — the pagination flows to SQLite/Postgres/… AND to Mongo. + +## Parity +| Feature | Python | PHP | Ruby | Node | +|---------|--------|-----|------|------| +| offset() | ✅ | ✅ | ✅ | ✅ | +| skip() | ✅ | ✅ | ✅ | ✅ | +| take() | ✅ | ✅ | ✅ | ✅ | + +## Tests (written first, real — no mocks, positive + negative) +- [x] `.order_by(id).skip(2).limit(2)` returns the 3rd+4th rows (real SQLite) +- [x] `.offset(n)` behaves identically to skip (real SQLite) +- [x] `.take(n)` sets the limit (real SQLite) +- [x] `.skip(n)` over-skip past row count returns empty, not an error (negative, real SQLite) +- [x] `.skip(5)` → `to_mongo()` emits `{"skip": 5}` (Mongo path parity) +- [x] methods return the builder (chaining) + +## Verification (self-run at HEAD, real SQLite, no mocks) +| Framework | Command | Result | +|-----------|---------|--------| +| Python | `pytest tests/test_query_builder.py` | 59 passed | +| PHP | `phpunit tests/QueryBuilderTest.php` | 63 tests, 113 assertions, OK | +| Ruby | `rspec spec/query_builder_spec.rb` | 66 examples, 0 failures | +| Node | `tsx test/queryBuilder.test.ts` | 66 passed, 0 failed (+ build:types regenerated d.ts) | + +Python mutation proof: making `skip()` a no-op broke exactly the 3 skip-dependent +tests; restored → 6/6 pass. + +## Docs +- [x] QueryBuilder `Methods:` list in all four CLAUDE.md now lists offset/skip/take + (noting skip/take are the Mongo/Eloquent aliases) — docs match code. + +## Bugs +- (none — additive feature) + +## Commits +- (pending — one branch per repo off v3) + +## Status: Implemented + verified locally; ready to branch/PR per repo diff --git a/tests/test_query_builder.py b/tests/test_query_builder.py index 8a5e08fd..03333759 100644 --- a/tests/test_query_builder.py +++ b/tests/test_query_builder.py @@ -324,6 +324,65 @@ def test_limit_stored_internally(self, db): assert qb._offset_val == 5 +# --------------------------------------------------------------------------- +# 10b. skip() / offset() / take() — chainable pagination verbs +# (an AI harness reached for .skip() and it did not exist; tina4#skip) +# --------------------------------------------------------------------------- + +class TestSkipOffsetTake: + def test_skip_skips_leading_rows(self, db): + result = ( + QueryBuilder.from_table("users", db) + .order_by("id ASC") + .skip(2) + .limit(2) + .get() + ) + # Skips Alice + Bob, returns Charlie + Diana + assert [r["name"] for r in result.records] == ["Charlie", "Diana"] + + def test_offset_is_the_sql_native_alias(self, db): + result = ( + QueryBuilder.from_table("users", db) + .order_by("id ASC") + .offset(2) + .limit(2) + .get() + ) + assert [r["name"] for r in result.records] == ["Charlie", "Diana"] + + def test_take_sets_the_limit(self, db): + result = ( + QueryBuilder.from_table("users", db) + .order_by("id ASC") + .take(3) + .get() + ) + assert [r["name"] for r in result.records] == ["Alice", "Bob", "Charlie"] + + def test_skip_past_the_end_returns_empty_not_error(self, db): + # Negative: skipping beyond the row count yields no rows, not a crash. + result = ( + QueryBuilder.from_table("users", db) + .order_by("id ASC") + .skip(99) + .limit(5) + .get() + ) + assert result.records == [] + + def test_skip_flows_into_to_mongo(self, db): + # The Mongo path already names this concept "skip" — the SQL verb agrees. + mongo = QueryBuilder.from_table("users", db).skip(5).to_mongo() + assert mongo["skip"] == 5 + + def test_methods_return_the_builder(self, db): + qb = QueryBuilder.from_table("users", db) + assert qb.skip(1) is qb + assert qb.offset(1) is qb + assert qb.take(1) is qb + + # --------------------------------------------------------------------------- # 11. to_sql() generates correct SQL string # --------------------------------------------------------------------------- diff --git a/tina4_python/query_builder/__init__.py b/tina4_python/query_builder/__init__.py index cce6ea56..1416b3a1 100644 --- a/tina4_python/query_builder/__init__.py +++ b/tina4_python/query_builder/__init__.py @@ -464,6 +464,48 @@ def limit(self, count: int, offset: int = None) -> "QueryBuilder": self._offset_val = offset return self + def offset(self, count: int) -> "QueryBuilder": + """Set OFFSET (rows to skip) as its own chainable verb. + + ``limit(n, offset)`` buries the offset as a second positional arg; this + exposes it on its own, so ``.offset(20).limit(10)`` reads naturally and + matches the SQL keyword. + + Args: + count: Number of rows to skip. + + Returns: + self for chaining. + """ + self._offset_val = count + return self + + def skip(self, count: int) -> "QueryBuilder": + """Alias for :meth:`offset` — the Mongo/Eloquent name for the same thing. + + Mirrors the DocStore cursor's ``.skip()`` and the ``skip`` key that + :meth:`to_mongo` already emits, so a query reads the same whether it + targets SQL or MongoDB. + + Args: + count: Number of rows to skip. + + Returns: + self for chaining. + """ + return self.offset(count) + + def take(self, count: int) -> "QueryBuilder": + """Alias for :meth:`limit` — the Eloquent name; pairs with :meth:`skip`. + + Args: + count: Maximum rows to return. + + Returns: + self for chaining. + """ + return self.limit(count) + def to_sql(self) -> str: """Build and return the SQL string without executing.