Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
62 changes: 62 additions & 0 deletions plan/query-builder-skip.md
Original file line number Diff line number Diff line change
@@ -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
59 changes: 59 additions & 0 deletions tests/test_query_builder.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
# ---------------------------------------------------------------------------
Expand Down
42 changes: 42 additions & 0 deletions tina4_python/query_builder/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading