[ivasilov]

Stacked on #2400 (which is stacked on #2376). This branch is based on ivasilov/supabase-e2e, so the diff also shows those commits until they merge. The new commits are 173400d9b, 052812fbf, 1e0934cdb, and f220600a4.

🎯 Changes

Adds experimental_queryOnce(callback, supabase) to @tanstack/supabase-db-collection (IFCS-154). This is PR 3 of 4.

1. feat(supabase-db-collection): add Supabase collection #2376: the collection and its unit tests.
2. test(supabase-db-collection): add e2e tests against a local Supabase stack #2400: e2e tests against a local Supabase stack, plus CI.
3. This PR (feat(supabase-db-collection): add experimental_queryOnce #2412): experimental_queryOnce.
4. docs(supabase-db-collection): add docs and publish the package #2413: docs and changeset, and removal of private: true.

What it adds

• The port from supabase/tanstack-db at 245600c:

  • query-once.ts;
  • serializeQueryIR and the query IR types in serialize.ts;
  • postgrest-filters/query-ir-to-search.ts;
  • their unit tests (query-once.test.ts, serialize.test.ts, and the queryIrToSearch block).

  It is exported only as experimental_queryOnce, because it reads TanStack DB's internal query IR. Changes to fit this repo:

  • descriptor sources;
  • ConditionalSelect in a select;
  • explicit null placement in order;
  • the X-Client-Info name.

• The queryOnce e2e cases. Reads gets back its one-shot query. Each filters case now reads through three paths: a live query, experimental_queryOnce, and executeQuery. Each path reads through a fresh collection.

• A server-aggregate oracle against the local stack, plus a migration that enables PostgREST aggregates (pgrst.db_aggregates_enabled) and adds the query_once_rows table.

• A fix the oracle found. The ported server path returned PostgREST's aggregate row as-is, so a query's answer depended on its route. The table shows each case.

Case	PostgREST (ported)	TanStack DB queryOnce
Empty match	[{ count: 0 }]	[] (findOne: undefined)
All-null sum/avg	null	0
avg of [1, null]	1	0.5
max(label) over a A b B	'B' (collation)	'b'
Column read with parse	raw text ('9' > '10')	parsed value
limit/offset without orderBy	[]	throws
Filter PostgREST cannot apply	throws	filters on the client

Per the decision on IFCS-154, experimental_queryOnce must match TanStack DB exactly. The server path now takes only count, sum, and avg of plain columns. Every filter must be pushable, and the query can't page, order, or use distinct. It requests a hidden count() and asks for each average as a sum, then applies TanStack DB's rules. Every other query, including min/max, runs through TanStack DB's queryOnce.

Please look at these

• Virtual fields are not compared. TanStack DB rows carry $key, $origin, $hasPendingWrites, and $collectionId, and server rows do not. The oracle compares only the select's aliases. This is a maintainer decision, recorded in the coverage map.
• A core defect, recorded and not fixed here. TanStack DB turns a null into 0 before min/max, and 'a' < 0 and 0 < 'a' are both false. So min(label) over 'a', null, null depends on row order. The oracle generates min/max only over columns that hold no text. The defect is in the coverage map's reusable-law backlog.
• Some TanStack DB rules may be bugs. All-null sum gives 0, and avg includes nulls in its row count. The server path reproduces both. If core changes them, the oracle will flag the server path.
• The Linear text says groupBy and having run in Postgres. Upstream #28 (in 245600c) already moved them to the client, and this PR keeps them there.

🔬 Oracle Coverage

Owner: the new coverage-map row "Supabase experimental_queryOnce server aggregates" (e2e/query-once-aggregate-oracle.e2e.test.ts).

• Law: experimental_queryOnce resolves to TanStack DB's queryOnce result over an eager Collection of the same table (IFCS-154). Results are compared at the settled promise. Rows are projected to the select's aliases, and a rejection must match a rejection.

• Reach, fixed seed 20261022, 40 histories:

  State	Histories
  server-route	22
  server-empty-match	12
  server-null-value	8
  server-find-one	10
  server-subquery-source	12
  client-route	33
  converted-column	13
  limit-or-offset	19
  unpushable-filter	6

  Four random campaigns reached every state.

• RED on the port (173400d9b), with SUPABASE_CLI="pnpm dlx supabase@2.116.0" pnpm exec vitest run --config vitest.e2e.config.ts e2e/query-once-aggregate-oracle.e2e.test.ts. Counterexample: rows [] and sum(id) gave expected [ { sum_id_0: null } ] to strictly equal [].

• GREEN: pnpm test:e2e passed 161 tests with 1 skipped (the existing skip from test(supabase-db-collection): add e2e tests against a local Supabase stack #2400).

• Mutants: each of these was rejected by an assertion failure:

  • the SQL row on empty input;
  • a null sum;
  • SQL avg;
  • min/max pushed to the server;
  • no pushability check;
  • sum over a parsed column;
  • paging pushed to the server;
  • subquery filters dropped.

• Limits:

  • one local stack (CLI 2.116.0) and one table;
  • min/max only over columns that hold no text;
  • small integers and decimals that doubles represent exactly;
  • no grouped, joined, or computed queries, which take TanStack DB's path on both sides.

✅ Checklist

• I have tested this code locally with pnpm test.

Unit tests: 705 passed and 18 todo, with no type errors. pnpm test:e2e passed 161 tests with 1 skipped. pnpm lint:changed is clean.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release). The package stays private: true until PR 4, which adds the changeset.

Size: the package's minified gzip bundle grows from 5,482 to 8,142 bytes. The port adds 2,325 of those, mostly the faithfully ported serializer and join-embedding code, which experimental_queryOnce cannot reach. The fix adds 335. pnpm size:compare reports no change for published packages.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: f220600

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Pre-merge checks: 2

Failed checks: 2 inconclusive

Check name	Status	Explanation	Resolution
Title check		This assessment has not completed. The check will be retried on the next pre-merge check run.
Description check		This assessment has not completed. The check will be retried on the next pre-merge check run.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn