From fff49e23bd85dac3c233555bdc75456ddc542c36 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Mon, 9 Nov 2026 12:01:22 +0100 Subject: [PATCH 01/13] feat(supabase-db-collection): add Supabase collection Port @supabase-labs/tanstack-db (supabase/tanstack-db@245600c) into the monorepo as @tanstack/supabase-db-collection. queryOnce, e2e tests and docs follow in separate PRs; the package stays private until the docs PR. On top of the upstream source: - syncMode: 'eager' option (default 'on-demand') - per-column parse/serialize converters - multi-page reads also order by the key columns, so ties in the query's order no longer repeat or skip rows; the oversized-IN URL budget accounts for that extra order - QueryClient registry is a WeakMap - X-Client-Info version injected from package.json at build time Co-Authored-By: Claude Opus 5.5 (1M context) --- packages/supabase-db-collection/package.json | 66 ++ packages/supabase-db-collection/src/db.ts | 203 ++++ .../supabase-db-collection/src/functions.ts | 476 ++++++++ packages/supabase-db-collection/src/index.ts | 1 + .../src/postgrest-filters/common.ts | 230 ++++ .../src/postgrest-filters/index.ts | 12 + .../key-columns-to-search.ts | 16 + .../load-subset-options-to-search.ts | 79 ++ .../realtime-filters-to-search.ts | 101 ++ .../split-load-subset-options.ts | 258 ++++ .../subset-params-to-search.ts | 37 + .../src/postgrest-request.ts | 101 ++ .../src/query-client.ts | 30 + .../supabase-db-collection/src/realtime.ts | 449 +++++++ .../src/request-headers.ts | 13 + .../src/row-conversions.ts | 70 ++ .../supabase-db-collection/src/serialize.ts | 8 + .../supabase-db-collection/src/version.ts | 4 + .../tests/index.test.ts | 1034 +++++++++++++++++ .../tests/pagination.test.ts | 490 ++++++++ .../tests/pagination.utils.ts | 123 ++ .../tests/postgrest-filters.test.ts | 513 ++++++++ .../tests/postgrest-request.test.ts | 122 ++ .../tests/realtime.test.ts | 787 +++++++++++++ .../tests/request-headers.test.ts | 139 +++ .../tests/row-conversions.test.ts | 294 +++++ .../tests/split-load-fanout.test.ts | 377 ++++++ .../tests/split-load-subset-options.test.ts | 284 +++++ .../tests/sync-mode.test.ts | 183 +++ .../tests/test.utils.ts | 296 +++++ .../supabase-db-collection/tsconfig.docs.json | 9 + packages/supabase-db-collection/tsconfig.json | 24 + .../supabase-db-collection/vite.config.ts | 33 + pnpm-lock.yaml | 109 +- 34 files changed, 6967 insertions(+), 4 deletions(-) create mode 100644 packages/supabase-db-collection/package.json create mode 100644 packages/supabase-db-collection/src/db.ts create mode 100644 packages/supabase-db-collection/src/functions.ts create mode 100644 packages/supabase-db-collection/src/index.ts create mode 100644 packages/supabase-db-collection/src/postgrest-filters/common.ts create mode 100644 packages/supabase-db-collection/src/postgrest-filters/index.ts create mode 100644 packages/supabase-db-collection/src/postgrest-filters/key-columns-to-search.ts create mode 100644 packages/supabase-db-collection/src/postgrest-filters/load-subset-options-to-search.ts create mode 100644 packages/supabase-db-collection/src/postgrest-filters/realtime-filters-to-search.ts create mode 100644 packages/supabase-db-collection/src/postgrest-filters/split-load-subset-options.ts create mode 100644 packages/supabase-db-collection/src/postgrest-filters/subset-params-to-search.ts create mode 100644 packages/supabase-db-collection/src/postgrest-request.ts create mode 100644 packages/supabase-db-collection/src/query-client.ts create mode 100644 packages/supabase-db-collection/src/realtime.ts create mode 100644 packages/supabase-db-collection/src/request-headers.ts create mode 100644 packages/supabase-db-collection/src/row-conversions.ts create mode 100644 packages/supabase-db-collection/src/serialize.ts create mode 100644 packages/supabase-db-collection/src/version.ts create mode 100644 packages/supabase-db-collection/tests/index.test.ts create mode 100644 packages/supabase-db-collection/tests/pagination.test.ts create mode 100644 packages/supabase-db-collection/tests/pagination.utils.ts create mode 100644 packages/supabase-db-collection/tests/postgrest-filters.test.ts create mode 100644 packages/supabase-db-collection/tests/postgrest-request.test.ts create mode 100644 packages/supabase-db-collection/tests/realtime.test.ts create mode 100644 packages/supabase-db-collection/tests/request-headers.test.ts create mode 100644 packages/supabase-db-collection/tests/row-conversions.test.ts create mode 100644 packages/supabase-db-collection/tests/split-load-fanout.test.ts create mode 100644 packages/supabase-db-collection/tests/split-load-subset-options.test.ts create mode 100644 packages/supabase-db-collection/tests/sync-mode.test.ts create mode 100644 packages/supabase-db-collection/tests/test.utils.ts create mode 100644 packages/supabase-db-collection/tsconfig.docs.json create mode 100644 packages/supabase-db-collection/tsconfig.json create mode 100644 packages/supabase-db-collection/vite.config.ts diff --git a/packages/supabase-db-collection/package.json b/packages/supabase-db-collection/package.json new file mode 100644 index 0000000000..df3302ed21 --- /dev/null +++ b/packages/supabase-db-collection/package.json @@ -0,0 +1,66 @@ +{ + "name": "@tanstack/supabase-db-collection", + "private": true, + "version": "0.0.0", + "description": "Supabase collection for TanStack DB", + "author": "Supabase ", + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/TanStack/db.git", + "directory": "packages/supabase-db-collection" + }, + "homepage": "https://tanstack.com/db", + "keywords": [ + "supabase", + "postgrest", + "realtime", + "optimistic", + "typescript" + ], + "scripts": { + "build": "vite build", + "dev": "vite build --watch", + "lint": "eslint . --fix", + "test": "vitest run" + }, + "type": "module", + "main": "dist/cjs/index.cjs", + "module": "dist/esm/index.js", + "types": "dist/esm/index.d.ts", + "exports": { + ".": { + "import": { + "types": "./dist/esm/index.d.ts", + "default": "./dist/esm/index.js" + }, + "require": { + "types": "./dist/cjs/index.d.cts", + "default": "./dist/cjs/index.cjs" + } + }, + "./package.json": "./package.json" + }, + "sideEffects": false, + "files": [ + "dist", + "src" + ], + "dependencies": { + "@standard-schema/spec": "^1.1.0", + "@supabase/postgrest-js": "^2.107.0", + "@tanstack/db": "workspace:*", + "@tanstack/query-db-collection": "workspace:*" + }, + "peerDependencies": { + "@supabase/supabase-js": "^2.74.0", + "@tanstack/query-core": "^5.90.15", + "typescript": ">=4.7" + }, + "devDependencies": { + "@supabase/supabase-js": "^2.107.0", + "@tanstack/query-core": "^5.90.20", + "@vitest/coverage-istanbul": "^5.0.5", + "zod": "^4.6.7" + } +} diff --git a/packages/supabase-db-collection/src/db.ts b/packages/supabase-db-collection/src/db.ts new file mode 100644 index 0000000000..4537b16abe --- /dev/null +++ b/packages/supabase-db-collection/src/db.ts @@ -0,0 +1,203 @@ +import { BasicIndex } from '@tanstack/db' +import { queryCollectionOptions } from '@tanstack/query-db-collection' +import { + subsetOptionsToQueryKey, + supabaseOnDelete, + supabaseOnInsert, + supabaseOnUpdate, + supabaseQueryFn, +} from './functions' +import { getQueryClient } from './query-client' +import { syncTableSubscription } from './realtime' +import type { TableEntry } from './realtime' +import type { ColumnConversions, RowConversions } from './row-conversions' +import type { StringCollationConfig } from '@tanstack/db' +import type { QueryClient } from '@tanstack/query-core' +import type { SupabaseClient } from '@supabase/supabase-js' +import type { StandardSchemaV1 } from '@standard-schema/spec' + +interface SupabaseCollectionOptions< + TSchema extends StandardSchemaV1, +> extends RowConversions> { + /** + * Controls how string columns are compared when ordering, matching the + * database's collation settings. If omitted, TanStack DB's default is used. + */ + defaultStringCollation?: StringCollationConfig + /** + * The columns that uniquely identify a row. Used to extract the key for + * storing the item in the collection and to build the where clause for + * update and delete operations. + */ + keys: Array & string> + /** The query client */ + queryClient?: QueryClient + /** Whether to receive updates when a record has been inserted, updated, or deleted by another user */ + realtime?: boolean + /** + * Whether to push each query's WHERE clause to the Realtime subscription as a + * server-side `postgres_changes` filter. Only applies when `realtime` is on. + * Defaults to `false`, which subscribes to every change on the table and + * filters client-side — simpler, at the cost of more Realtime traffic. Set to + * `true` to narrow the subscription server-side. + */ + realtimeUseFilter?: boolean + /** The schema of the collection */ + schema: TSchema + /** The supabase browser client */ + supabase: SupabaseClient + /** + * When the table's rows are fetched. + * + * - `'on-demand'` (default): rows are loaded per live query, pushing each + * query's where/order/limit to PostgREST. + * - `'eager'`: the whole table is fetched (paging past PostgREST's + * `db-max-rows`) as soon as the collection starts syncing, regardless of + * the queries run against it. Realtime then subscribes to every change on + * the table. + */ + syncMode?: 'on-demand' | 'eager' + /** The name of the table in the database */ + tableName: string +} + +// Per-QueryClient registry of table entries, with a single cache subscription +// per client. Weakly keyed so a discarded QueryClient (and the Supabase clients +// and collections its entries reference) can be garbage collected. +const queryClientRegistries = new WeakMap< + QueryClient, + Map +>() + +const ensureQueryCacheSubscription = ( + queryClient: QueryClient, +): Map => { + const existing = queryClientRegistries.get(queryClient) + if (existing) { + return existing + } + + const tables = new Map() + queryClientRegistries.set(queryClient, tables) + + queryClient.getQueryCache().subscribe((args) => { + if (args.type !== 'observerAdded' && args.type !== 'observerRemoved') { + return + } + for (const [tableName, entry] of tables) { + syncTableSubscription(queryClient, tableName, entry) + } + }) + + return tables +} + +const registerTable = ( + queryClient: QueryClient, + tableName: string, + supabase: SupabaseClient, + realtimeUseFilter: boolean, +): TableEntry => { + const tables = ensureQueryCacheSubscription(queryClient) + + let entry = tables.get(tableName) + if (!entry) { + entry = { + supabase, + collectionRef: null, + conversions: {}, + realtimeChannel: null, + realtimeFiltersKey: null, + realtimePendingChannel: null, + realtimePendingFiltersKey: null, + rejectedFilterKeys: new Set(), + realtimeUseFilter, + } + tables.set(tableName, entry) + } + + return entry +} + +export const supabaseCollectionOptions = ({ + tableName, + keys, + schema, + queryClient, + supabase, + realtime, + realtimeUseFilter = false, + syncMode = 'on-demand', + defaultStringCollation, + parse, + serialize, +}: SupabaseCollectionOptions) => { + // if the query client is not provided, use the global query client + queryClient = queryClient ?? getQueryClient() + + type TItem = StandardSchemaV1.InferOutput + + // Derive the collection key from the configured key columns. The values are + // always joined into a string, so a single numeric `id` of 6 becomes `'6'`. + const getKey = (item: TItem): string | number => { + return keys.map((key) => item[key]).join('-') + } + + const conversions = { parse, serialize } as ColumnConversions + + // Key columns used to match rows on update and delete. + const keyColumns = keys as Array + + // A server-side Supabase client has no `channel`, so Realtime is a no-op there + // and the table is never registered. Checking here keeps attachSupabaseListeners + // able to always return a live subscription. + let entry: TableEntry | null = null + if (realtime && typeof supabase.channel === 'function') { + entry = registerTable(queryClient, tableName, supabase, realtimeUseFilter) + } + const config = queryCollectionOptions({ + id: tableName, + queryClient, + getKey, + schema, + queryKey: (ctx) => subsetOptionsToQueryKey(tableName, ctx), + syncMode, + // Known limitation: the initial fetch does not wait for the Realtime channel + // to finish subscribing. A row written in the window between this fetch and + // the subscription going live can be missed by both — the fetch ran before + // the row existed, and the subscription started after the change was + // published. Gating the fetch on the subscription closes this gap but couples + // every first load to Realtime connect latency, so it is intentionally left + // out and tracked separately. + queryFn: (ctx) => + supabaseQueryFn(supabase, tableName, ctx, { + keys: keyColumns, + conversions, + }), + onInsert: (ctx) => supabaseOnInsert(supabase, tableName, ctx, conversions), + onUpdate: (ctx) => + supabaseOnUpdate(supabase, tableName, keyColumns, ctx, conversions), + onDelete: (ctx) => + supabaseOnDelete(supabase, tableName, keyColumns, ctx, conversions), + autoIndex: 'eager', + defaultIndexType: BasicIndex, + defaultStringCollation, + }) + + const originalSync = config.sync.sync + + return { + ...config, + sync: { + sync: ( + ...args: Parameters + ): ReturnType => { + if (entry) { + entry.collectionRef = args[0].collection + entry.conversions = conversions + } + return originalSync(...args) + }, + }, + } +} diff --git a/packages/supabase-db-collection/src/functions.ts b/packages/supabase-db-collection/src/functions.ts new file mode 100644 index 0000000000..b3437bc9e7 --- /dev/null +++ b/packages/supabase-db-collection/src/functions.ts @@ -0,0 +1,476 @@ +import { DeleteOperationItemNotFoundError } from '@tanstack/query-db-collection' +import { + cursorCurrentToSearch, + cursorWhereFromToSearch, + keyColumnsToSearch, + loadSubsetOptionsToSearch, + splitLoadSubsetOptions, + subsetParamsToSearch, +} from './postgrest-filters' +import { postgrestRequest } from './postgrest-request' +import { isSynced } from './realtime' +import { parseRow, serializeRow } from './row-conversions' +import type { ColumnConversions } from './row-conversions' +import type { + DeleteMutationFnParams, + InsertMutationFnParams, + LoadSubsetOptions, + UpdateMutationFnParams, +} from '@tanstack/db' +import type { QueryClient, QueryMeta } from '@tanstack/query-core' +import type { SupabaseClient } from '@supabase/supabase-js' + +export const subsetOptionsToQueryKey = ( + tableName: string, + ctx: LoadSubsetOptions, +): Array => { + // The key shares the request URL's where/order/limit encoding + // (`subsetParamsToSearch`) so the two cannot drift; the constant `select` is + // excluded because it never distinguishes one subset from another. + // + // Pagination params (cursor/offset) ARE included: query-db-collection keys row + // ownership by this key, so distinct windows of the same subset (same + // where/order/limit, different cursor/offset) must not collide — otherwise a + // later page's result would take over the earlier page's rows and delete them. + // The key still starts with `[tableName]` so `syncTableSubscription` keeps + // matching every window of the table by prefix. + const search = subsetParamsToSearch(ctx) + if (ctx.cursor) { + try { + for (const [k, v] of cursorWhereFromToSearch(ctx.cursor)) { + search.append(k, v) + } + } catch { + // The queryKey function must never throw — query-db-collection calls it + // synchronously to key row ownership. If the cursor cannot be rendered + // (an un-pushable predicate), fall back to a deterministic discriminator + // so distinct windows still get distinct keys and cannot take over and + // delete each other's rows. + search.append('cursor', JSON.stringify(ctx.cursor.whereFrom)) + } + } + if (ctx.offset && !ctx.cursor) { + search.append('offset', `${ctx.offset}`) + } + const key = search.toString() + return key ? [tableName, key] : [tableName] +} + +type PageOptions = { + /** The caller's row limit; `undefined` means "the full matching set". */ + limit?: number + /** The starting offset (always 0 for cursor reads). */ + offset: number + signal?: AbortSignal + /** + * Columns that uniquely identify a row. Pages are ordered by them after the + * caller's order so that the rows tied on that order keep one position + * across the page requests; see {@link withKeyOrder}. + */ + keys: Array +} + +/** + * Extends the `order` param with the key columns it does not already sort by. + * + * Offset paging is only sound over a total order. When the caller's order has + * ties (or there is none), Postgres may order the tied rows differently for + * each page request, so a row can show up on two pages while another shows up + * on none. Ordering by the unique key last makes every page agree. + */ +function withKeyOrder( + search: URLSearchParams, + keys: Array, +): URLSearchParams { + const sorts = search.get('order')?.split(',') ?? [] + // Each sort is `column.direction[.nulls]`; the column is the first segment. + const sortedColumns = new Set(sorts.map((sort) => sort.split('.')[0])) + const missing = keys.filter((key) => !sortedColumns.has(key)) + if (missing.length === 0) { + return search + } + const ordered = new URLSearchParams(search) + ordered.set( + 'order', + [...sorts, ...missing.map((key) => `${key}.asc`)].join(','), + ) + return ordered +} + +/** + * Read a full matching set (or the caller's `limit` rows) with offset paging, + * looping past PostgREST's `db-max-rows` cap instead of silently truncating at + * it. The first request asks for `count=exact` so the loop knows the total up + * front and stops without a trailing empty probe; each later page advances the + * offset by the rows actually received (self-correcting under concurrent + * writes) and is capped by the observed page size and the rows still owed. + * + * A result that fits in one page is returned as read. When more pages are + * needed, the first page is read again under a total order (see + * {@link withKeyOrder}) so that all pages are cut from the same sequence. + */ +async function fetchAllPages( + supabase: SupabaseClient, + tableName: string, + baseSearch: URLSearchParams, + { limit, offset: startOffset, signal, keys }: PageOptions, +): Promise> { + // A zero limit is an empty window: return it without touching the network. + if (limit === 0) { + return [] + } + + // The base search already carries the caller's limit/offset (from the search + // builders), so the first request is sent verbatim — its URL stays identical + // to the single-request behaviour, and the query key that mirrors it. + const first = await postgrestRequest>(supabase, tableName, { + method: 'GET', + search: baseSearch, + signal, + count: 'exact', + }) + let rows: Array = first.data ? [...first.data] : [] + + // The rows the first page returned size the server's cap; a later page that + // comes back shorter than this means the server has no more rows. + const pageSize = rows.length + // `Content-Range` reports the whole matching set, so the rows reachable from + // the starting offset are what remains past it. When the count header is + // missing we fall back to paging until a short page appears. + const total = first.count ?? Number.POSITIVE_INFINITY + const remaining = Math.max(0, total - startOffset) + const target = limit === undefined ? remaining : Math.min(limit, remaining) + + // The first page was read under the caller's order, whose ties the server may + // break differently on the next request. If more pages follow, discard it and + // page through a total order instead. + let pagedSearch = baseSearch + if (pageSize > 0 && rows.length < target) { + pagedSearch = withKeyOrder(baseSearch, keys) + if (pagedSearch !== baseSearch) { + rows = [] + } + } + + let lastPageSize = pageSize + while (lastPageSize === pageSize && pageSize > 0 && rows.length < target) { + const pageSearch = new URLSearchParams(pagedSearch) + pageSearch.set('offset', `${startOffset + rows.length}`) + pageSearch.set('limit', `${Math.min(pageSize, target - rows.length)}`) + const page = await postgrestRequest>(supabase, tableName, { + method: 'GET', + search: pageSearch, + signal, + }) + const pageRows = page.data ?? [] + rows.push(...pageRows) + lastPageSize = pageRows.length + } + + return rows +} + +/** + * Read one already-in-budget subset's full window: the keyset tie request (if + * any) plus the main paged request. This is what runs once per chunk when + * `splitLoadSubsetOptions` had to split an oversized subset into several. + */ +async function loadWindow( + supabase: SupabaseClient, + tableName: string, + keys: Array, + options: LoadSubsetOptions, + signal: AbortSignal, +): Promise> { + const search = loadSubsetOptionsToSearch(options) + // Cursor reads pin their own window start, so they never carry an offset (see + // loadSubsetOptionsToSearch); only a cursor-less read advances from `offset`. + const startOffset = options.offset && !options.cursor ? options.offset : 0 + + // A keyset request whose boundary column has ties (e.g. `orderBy(created_at)` + // with repeated values) needs a second, unlimited request for the rows equal + // to the boundary; the limited `whereFrom` page alone would skip them. + // + // Do not drop this on the grounds that core's ordered-source loader also + // probes the boundary (`requestSnapshot({ where: eq(col, boundary) })`) and + // usually pre-loads the same tie class: that probe is a window-path + // optimization the adapter cannot assume ran. It is skipped when the boundary + // value is unchanged, falls back to a full-source load for non-keyset orders, + // and never runs for `loadSubset({ cursor })` calls made outside that path. + // Honouring `whereCurrent` here is what makes the cursor correct on its own. + const tiesSearch = cursorCurrentToSearch(options) + if (!tiesSearch) { + return await fetchAllPages(supabase, tableName, search, { + limit: options.limit, + offset: startOffset, + signal, + keys, + }) + } + + const [ties, rows] = await Promise.all([ + // The tie read is deliberately unbounded by the caller's limit — every row + // tied at the boundary must come back — but it is still paged so a tie class + // larger than the cap is not truncated. + fetchAllPages(supabase, tableName, tiesSearch, { + offset: 0, + signal, + keys, + }), + fetchAllPages(supabase, tableName, search, { + limit: options.limit, + offset: startOffset, + signal, + keys, + }), + ]) + // `whereCurrent` (== boundary) and `whereFrom` (> / < boundary) are disjoint, + // so concatenation never duplicates; the collection re-sorts locally. + return [...ties, ...rows] +} + +// PostgREST has no body-carried filters for reads and the Supabase API gateway +// rejects request lines over about 8 KB with 414, so a big `inArray(...)` +// predicate (the common shape a lazy join's on-demand collection produces) +// can make a subset's URL too long to send. This matches postgrest-js's own +// `urlLengthLimit` default so the two agree on what counts as "too long". +export const MAX_URL_LENGTH = 8000 + +// At most this many chunk requests run at once; splitting a large IN list can +// produce far more chunks than are worth having in flight simultaneously. +const MAX_CONCURRENT_CHUNKS = 6 + +// Pages after the first (`fetchAllPages`) set `offset` and `limit` on top of +// the subset's own search; no real value is wider than this one. +const WIDEST_PAGE_PARAM = `${Number.MAX_SAFE_INTEGER}` + +/** + * The length of the longest URL `fetchAllPages` could send for `search`: the + * base URL, the `?`, and the query string with the key-column tiebreak order + * that multi-page reads add (see {@link withKeyOrder}) and `offset`/`limit` at + * their widest, so every page — not only the first — stays within budget. + */ +function pagedUrlLength( + baseLength: number, + search: URLSearchParams, + keys: Array, +): number { + const paged = new URLSearchParams(withKeyOrder(search, keys)) + paged.set('offset', WIDEST_PAGE_PARAM) + paged.set('limit', WIDEST_PAGE_PARAM) + return baseLength + '?'.length + paged.toString().length +} + +/** + * The length of the longest URL a subset would produce: the main request's + * pages, and — when the subset has a cursor — the unlimited `whereCurrent` tie + * request's pages too, since `loadWindow` sends both for a cursor read. + * Measuring rendered URLs (rather than estimating) accounts for quoting and + * percent-encoding exactly. + */ +function measureSubset( + supabase: SupabaseClient, + tableName: string, + keys: Array, + options: LoadSubsetOptions, +): number { + const base = supabase.from(tableName).url.toString().length + const mainLength = pagedUrlLength( + base, + loadSubsetOptionsToSearch(options), + keys, + ) + const tiesSearch = cursorCurrentToSearch(options) + return tiesSearch + ? Math.max(mainLength, pagedUrlLength(base, tiesSearch, keys)) + : mainLength +} + +/** + * Runs one `loadWindow` per chunk with at most `MAX_CONCURRENT_CHUNKS` in + * flight at a time, and concatenates their rows. Chunks are disjoint on the + * split column (see `splitLoadSubsetOptions`), so concatenation order does not + * matter and needs no dedupe. + * + * On the first failure, every other chunk's request is aborted through a + * local `AbortController` combined with the caller's own signal + * (`AbortSignal.any`) — this keeps the same all-or-nothing semantics an + * unsplit request has ("one failed page fails the whole load") instead of + * surfacing a partial result, and the first error encountered is what + * `Promise.all` rejects with. + */ +async function loadChunks( + supabase: SupabaseClient, + tableName: string, + keys: Array, + chunks: Array, + signal: AbortSignal, +): Promise> { + const controller = new AbortController() + const combinedSignal = AbortSignal.any([signal, controller.signal]) + const results: Array> = new Array(chunks.length) + let nextIndex = 0 + + const runWorker = async (): Promise => { + while (nextIndex < chunks.length) { + const index = nextIndex++ + try { + results[index] = await loadWindow( + supabase, + tableName, + keys, + chunks[index]!, + combinedSignal, + ) + } catch (error) { + controller.abort() + throw error + } + } + } + + const workerCount = Math.min(MAX_CONCURRENT_CHUNKS, chunks.length) + await Promise.all(Array.from({ length: workerCount }, runWorker)) + return results.flat() +} + +/** + * Reads the rows a query needs, converted to the rows the collection holds + * (see {@link RowConversions}). + */ +export const supabaseQueryFn = async ( + supabase: SupabaseClient, + tableName: string, + ctx: { + client: QueryClient + queryKey: ReadonlyArray + signal: AbortSignal + meta: QueryMeta | undefined + pageParam?: unknown + direction?: unknown + }, + { + keys = [], + conversions = {}, + }: { keys?: Array; conversions?: ColumnConversions } = {}, +): Promise> => { + const options = ctx.meta?.loadSubsetOptions ?? {} + // The query key stays the full, unchunked subset (subsetOptionsToQueryKey + // never sees these chunks), so this fan-out is invisible to + // query-db-collection: one query still owns every row it returns. + const chunks = splitLoadSubsetOptions(options, { + maxUrlLength: MAX_URL_LENGTH, + measure: (chunkOptions) => + measureSubset(supabase, tableName, keys, chunkOptions), + }) + + const rows = + chunks.length === 1 + ? await loadWindow( + supabase, + tableName, + keys, + chunks[0]!, + ctx.signal, + ) + : await loadChunks(supabase, tableName, keys, chunks, ctx.signal) + return rows.map((row) => parseRow(row, conversions)) +} + +export const supabaseOnInsert = async ( + supabase: SupabaseClient, + tableName: string, + { transaction, collection }: InsertMutationFnParams, + conversions: ColumnConversions = {}, +) => { + await Promise.all( + transaction.mutations.map(async (mutation) => { + const { data } = await postgrestRequest(supabase, tableName, { + method: 'POST', + search: new URLSearchParams({ select: '*' }), + body: serializeRow(mutation.modified, conversions), + returnRows: true, + single: true, + }) + + // A single-row insert with `Prefer: return=representation` always returns + // the created row. + const inserted = parseRow(data as object, conversions) + mutation.modified = inserted + // The data has been inserted and confirmed by the server, so we can write + // it to the collection. Realtime may already have echoed the insert, in + // which case this is an update of the synced row rather than an insert. + await collection.utils.writeUpsert(inserted) + }), + ) +} + +export const supabaseOnUpdate = async ( + supabase: SupabaseClient, + tableName: string, + keys: Array, + { transaction, collection }: UpdateMutationFnParams, + conversions: ColumnConversions = {}, +) => { + await Promise.all( + transaction.mutations.map(async (mutation) => { + const { original, changes } = mutation + const search = keyColumnsToSearch( + keys, + serializeRow(original, conversions), + ) + search.set('select', '*') + const { data } = await postgrestRequest(supabase, tableName, { + method: 'PATCH', + search, + body: serializeRow({ ...original, ...changes }, conversions), + returnRows: true, + single: true, + }) + + // A single-row update with `Prefer: return=representation` always returns + // the updated row. + const updated = parseRow(data as object, conversions) + mutation.modified = updated + await collection.utils.writeUpdate(updated) + }), + ) +} + +export const supabaseOnDelete = async ( + supabase: SupabaseClient, + tableName: string, + keys: Array, + { transaction, collection }: DeleteMutationFnParams, + conversions: ColumnConversions = {}, +) => { + await Promise.all( + transaction.mutations.map(async (mutation) => { + await postgrestRequest(supabase, tableName, { + method: 'DELETE', + search: keyColumnsToSearch( + keys, + serializeRow(mutation.original, conversions), + ), + }) + + // The data has been deleted and confirmed by the server, so we can write + // it to the collection — unless Realtime already echoed the delete, in + // which case the synced row is gone and writing again would throw. + const key = collection.getKeyFromItem(mutation.original) + if (!isSynced(collection, key)) { + return + } + try { + await collection.utils.writeDelete(key) + } catch (error) { + // Direct writes are applied asynchronously, so a Realtime echo can + // remove the row between the check above and this write being applied. + // The row is gone either way, so the delete is already confirmed. + if (!(error instanceof DeleteOperationItemNotFoundError)) { + throw error + } + } + }), + ) +} diff --git a/packages/supabase-db-collection/src/index.ts b/packages/supabase-db-collection/src/index.ts new file mode 100644 index 0000000000..58a93e76de --- /dev/null +++ b/packages/supabase-db-collection/src/index.ts @@ -0,0 +1 @@ +export { supabaseCollectionOptions } from './db' diff --git a/packages/supabase-db-collection/src/postgrest-filters/common.ts b/packages/supabase-db-collection/src/postgrest-filters/common.ts new file mode 100644 index 0000000000..78f5aa8182 --- /dev/null +++ b/packages/supabase-db-collection/src/postgrest-filters/common.ts @@ -0,0 +1,230 @@ +import type { SerializedExpression as Expression } from '../serialize' + +type Comparison = { column: string; operator: string; value: string } +export type PostgrestParam = + ({ kind: 'column' } & Comparison) | { kind: 'group'; filter: string } + +interface FilterOptions { + mergeIn?: boolean + /** + * Quote top-level scalar values (the Realtime path). PostgREST sends each + * comparison as its own `column=op.value` query param, so top-level scalars + * must stay raw; Realtime comma-joins conditions into a single `filter`, so + * top-level scalars must be quoted to keep reserved characters (commas, + * whitespace) from splitting a condition. + */ + quoteScalars?: boolean + strict?: boolean + stripAlias?: boolean +} + +/** Set the comma-joined `order` param (independent of limit/offset). */ +export function appendOrder( + search: URLSearchParams, + sorts: Array<{ column: string; ascending: boolean }>, +): void { + if (sorts.length === 0) return + search.set( + 'order', + sorts + .map((sort) => `${sort.column}.${sort.ascending ? 'asc' : 'desc'}`) + .join(','), + ) +} + +export function appendLimit(search: URLSearchParams, limit: number): void { + search.set('limit', `${limit}`) +} + +export function appendOffset(search: URLSearchParams, offset: number): void { + search.set('offset', `${offset}`) +} + +/** Render params as the `URLSearchParams` sent to (and keyed by) PostgREST. */ +export function paramsToSearch(params: Array): URLSearchParams { + const search = new URLSearchParams() + for (const param of params) { + if (param.kind === 'column') + search.append(param.column, `${param.operator}.${param.value}`) + else search.append('or', `(${param.filter})`) + } + return search +} + +export function flattenAnd(expr: Expression): Array { + return expr.type === 'func' && expr.name === 'and' + ? expr.args.flatMap(flattenAnd) + : [expr] +} + +// PostgREST interpolates filter values into the URL as-is, and +// `Date.prototype.toString()` produces something Postgres cannot cast to a +// timestamp. Rendering it as ISO 8601 keeps the server query in agreement with +// the Realtime subscription, which serializes Dates the same way. +export const toScalarString = (value: unknown): string => + value instanceof Date ? value.toISOString() : `${value}` + +// Only lists and logical groups parse quoted values. Top-level scalar values +// must remain raw: col=eq."x" would match the quotes themselves. +const NEEDS_QUOTES = /^$|^\s|\s$|[,()"\\]/ +export const quoteValue = (value: unknown): string => { + const raw = toScalarString(value) + return NEEDS_QUOTES.test(raw) + ? `"${raw.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"` + : raw +} + +const SCALAR_OPERATORS = ['eq', 'gt', 'gte', 'lt', 'lte', 'like', 'ilike'] + +function renderComparison( + expr: Expression, + quoteScalars: boolean, + options: FilterOptions, +): Comparison | null { + if (expr.type !== 'func') return null + const [left, right] = expr.args + if (expr.name === 'not' && left) { + if (left.type === 'func' && left.name === 'not' && left.args[0]) { + return renderComparison(left.args[0], quoteScalars, options) + } + const inner = renderComparison(left, quoteScalars, options) + if (!inner) return null + // TanStack's NOT IN [] excludes nulls; PostgREST's NOT IN () includes them. + if (inner.operator === 'in' && inner.value === '()') { + return { ...inner, operator: 'not.is', value: 'null' } + } + return { + ...inner, + operator: `not.${inner.operator}`, + } + } + if (left?.type !== 'ref' || left.path[0] === '$selected') return null + const column = (options.stripAlias ? left.path.slice(1) : left.path).join('.') + if (!column) return null + if (expr.name === 'isNull') return { column, operator: 'is', value: 'null' } + if (right?.type !== 'val') return null + + if (expr.name === 'in') { + if (!Array.isArray(right.value)) return null + // TanStack's membership test ignores null list members for non-null rows. + const values = Array.from( + new Set(right.value.filter((value) => value != null)), + ) + // PostgREST treats IN ("") as an empty list, even when quoted. + if (values.length === 1 && values[0] === '') { + return { column, operator: 'eq', value: quoteScalars ? '""' : '' } + } + return { + column, + operator: 'in', + value: `(${values.map(quoteValue).join(',')})`, + } + } + if (!SCALAR_OPERATORS.includes(expr.name)) return null + let value = right.value + if (expr.name === 'like' || expr.name === 'ilike') { + // TanStack uses SQL %/_ wildcards, but treats * and backslashes literally. + // PostgREST always rewrites * to %, so such patterns cannot be pushed. + if (typeof value !== 'string' || value.includes('*')) return null + value = value.replace(/\\/g, '\\\\') + } + return { + column, + operator: expr.name, + value: quoteScalars ? quoteValue(value) : toScalarString(value), + } +} + +// Embedded expressions are all-or-nothing. Dropping a child of OR or NOT +// could narrow the response and permanently lose matching rows. +function toFilterString( + expr: Expression, + options: FilterOptions, + negated = false, +): string | null { + if (expr.type !== 'func') return null + if (expr.name === 'not') { + return expr.args[0] ? toFilterString(expr.args[0], options, !negated) : null + } + if (expr.name === 'and' || expr.name === 'or') { + if (expr.args.length === 0) return null + // Move NOT down to comparisons with De Morgan's laws. In particular, an + // empty IN list needs its null guard even under a negated logical group. + const operator = negated ? (expr.name === 'and' ? 'or' : 'and') : expr.name + const parts = expr.args.map((arg) => toFilterString(arg, options, negated)) + return parts.includes(null) ? null : `${operator}(${parts.join(',')})` + } + const comparison = renderComparison( + negated ? { type: 'func', name: 'not', args: [expr] } : expr, + true, + options, + ) + return comparison + ? `${comparison.column}.${comparison.operator}.${comparison.value}` + : null +} + +// Preserve the live adapter's union of duplicate IN demands. This deliberately +// fetches a superset, which TanStack re-filters. Never do this inside OR/NOT or +// for server aggregates, where client-side filtering cannot repair the result. +export function mergeInFilters(filters: Array): Array { + const merged: Array = [] + const valuesByField = new Map>() + for (const filter of filters) { + if (filter.type !== 'func' || filter.name !== 'in') { + merged.push(filter) + continue + } + const [left, right] = filter.args + if ( + left?.type !== 'ref' || + right?.type !== 'val' || + !Array.isArray(right.value) + ) { + merged.push(filter) + continue + } + const field = JSON.stringify(left.path) + const existing = valuesByField.get(field) + if (existing) { + existing.push(...right.value) + } else { + const values = [...right.value] + valuesByField.set(field, values) + merged.push({ ...filter, args: [left, { type: 'val', value: values }] }) + } + } + return merged +} + +export function toPostgrestParams( + expr: Expression | undefined | null, + options: FilterOptions = {}, +): Array { + if (!expr) return [] + const conjuncts = flattenAnd(expr) + const filters = options.mergeIn ? mergeInFilters(conjuncts) : conjuncts + return filters.flatMap((filter): Array => { + const comparison = renderComparison( + filter, + options.quoteScalars ?? false, + options, + ) + if (comparison) return [{ kind: 'column', ...comparison }] + const embedded = toFilterString(filter, options) + if (embedded !== null) { + return [ + { + kind: 'group', + filter: embedded.startsWith('or(') ? embedded.slice(3, -1) : embedded, + }, + ] + } + if (options.strict) { + throw new Error( + 'Cannot push WHERE expression to PostgREST; server aggregates require fully pushable filters', + ) + } + return [] + }) +} diff --git a/packages/supabase-db-collection/src/postgrest-filters/index.ts b/packages/supabase-db-collection/src/postgrest-filters/index.ts new file mode 100644 index 0000000000..ebe7243a7e --- /dev/null +++ b/packages/supabase-db-collection/src/postgrest-filters/index.ts @@ -0,0 +1,12 @@ +export { keyColumnsToSearch } from './key-columns-to-search' +export { + cursorCurrentToSearch, + cursorWhereFromToSearch, + loadSubsetOptionsToSearch, +} from './load-subset-options-to-search' +export { realtimeFiltersToSearch } from './realtime-filters-to-search' +export { + type SplitLoadSubsetOptionsConfig, + splitLoadSubsetOptions, +} from './split-load-subset-options' +export { subsetParamsToSearch } from './subset-params-to-search' diff --git a/packages/supabase-db-collection/src/postgrest-filters/key-columns-to-search.ts b/packages/supabase-db-collection/src/postgrest-filters/key-columns-to-search.ts new file mode 100644 index 0000000000..b2790a3f5b --- /dev/null +++ b/packages/supabase-db-collection/src/postgrest-filters/key-columns-to-search.ts @@ -0,0 +1,16 @@ +import { paramsToSearch, toScalarString } from './common' + +/** Build the `key.eq.value` search that matches one row by its key columns. */ +export function keyColumnsToSearch( + keys: Array, + item: object, +): URLSearchParams { + return paramsToSearch( + keys.map((key) => ({ + kind: 'column', + column: key, + operator: 'eq', + value: toScalarString(Reflect.get(item, key)), + })), + ) +} diff --git a/packages/supabase-db-collection/src/postgrest-filters/load-subset-options-to-search.ts b/packages/supabase-db-collection/src/postgrest-filters/load-subset-options-to-search.ts new file mode 100644 index 0000000000..986f1cb512 --- /dev/null +++ b/packages/supabase-db-collection/src/postgrest-filters/load-subset-options-to-search.ts @@ -0,0 +1,79 @@ +import { appendOffset, paramsToSearch, toPostgrestParams } from './common' +import { subsetParamsToSearch } from './subset-params-to-search' +import type { LoadSubsetOptions } from '@tanstack/db' + +/** + * Render the cursor's `whereFrom` (keyset "rows after boundary") filters. + * + * Uses the adapter's own {@link toPostgrestParams} renderer so it handles the + * composite cursors core emits for multi-column `orderBy` + * (`or(gt(c1,v1), and(eq(c1,v1), gt(c2,v2)))`) and serialises Date boundaries + * as ISO 8601 — both of which the pre-flattening `extractSimpleComparisons` + * path could not. `strict` surfaces any un-pushable cursor rather than silently + * dropping a predicate and widening the window. + */ +export function cursorWhereFromToSearch( + cursor: LoadSubsetOptions['cursor'], +): URLSearchParams { + if (!cursor) return new URLSearchParams() + return paramsToSearch(toPostgrestParams(cursor.whereFrom, { strict: true })) +} + +/** + * Build the full read query string for a TanStack DB subset load: the shared + * subset params ({@link subsetParamsToSearch}) plus `select=*` and the cursor's + * keyset (`whereFrom`) filters, or `offset` for cursor-less requests. + */ +export function loadSubsetOptionsToSearch( + options: LoadSubsetOptions, +): URLSearchParams { + const search = new URLSearchParams() + search.set('select', '*') + for (const [key, value] of subsetParamsToSearch(options)) { + search.append(key, value) + } + + for (const [key, value] of cursorWhereFromToSearch(options.cursor)) { + search.append(key, value) + } + + // Cursor and offset are mutually exclusive: core may send both, but the + // cursor already pins the window start, so an offset on top of it re-skips + // rows the cursor has already moved past. Honour offset only without a cursor. + if (options.offset && !options.cursor) { + appendOffset(search, options.offset) + } + return search +} + +/** + * Build the read query string for the boundary-tie request that accompanies a + * cursor load: the same `where`/`order` as the main request plus the cursor's + * `whereCurrent` (rows equal to the boundary value), and deliberately **no + * limit** — every tied row must come back or a row sharing the boundary value + * with `orderBy` would be skipped. Returns `null` when there is no cursor or no + * tie predicate, so the caller can fall back to the single main request. + */ +export function cursorCurrentToSearch( + options: LoadSubsetOptions, +): URLSearchParams | null { + if (!options.cursor) return null + const currentParams = toPostgrestParams(options.cursor.whereCurrent, { + strict: true, + }) + if (currentParams.length === 0) return null + + const search = new URLSearchParams() + search.set('select', '*') + // where + order only — no limit, no offset, no `whereFrom`. + for (const [key, value] of subsetParamsToSearch({ + where: options.where, + orderBy: options.orderBy, + })) { + search.append(key, value) + } + for (const [key, value] of paramsToSearch(currentParams)) { + search.append(key, value) + } + return search +} diff --git a/packages/supabase-db-collection/src/postgrest-filters/realtime-filters-to-search.ts b/packages/supabase-db-collection/src/postgrest-filters/realtime-filters-to-search.ts new file mode 100644 index 0000000000..4eb8aa69ea --- /dev/null +++ b/packages/supabase-db-collection/src/postgrest-filters/realtime-filters-to-search.ts @@ -0,0 +1,101 @@ +import { toPostgrestParams } from './common' +import type { PostgrestParam } from './common' +import type { LoadSubsetOptions } from '@tanstack/db' + +type WhereExpression = LoadSubsetOptions['where'] +type ColumnParam = Extract + +/** + * Realtime `postgres_changes` accepts only a top-level column compared with one + * of these operators (optionally negated with `not.`). Anything else — an + * embedded column, an OR group, a function — cannot be pushed and forces the + * catch-all. + */ +const REALTIME_OPERATOR = /^(?:not\.)?(?:eq|gt|gte|lt|lte|in|is)$/ +/** Realtime rejects `in` filters with more than this many values. */ +const MAX_IN_VALUES = 100 + +/** + * Whether a rendered PostgREST param is expressible as a single Realtime + * condition. Realtime shares PostgREST's WHERE grammar, so the shared renderer + * already produced the exact `operator.value` wire form; this only rejects the + * shapes Realtime cannot evaluate. + */ +const isRealtimeParam = (param: PostgrestParam): param is ColumnParam => { + // OR groups and other embedded filters have no single-column Realtime form. + if (param.kind !== 'column') { + return false + } + if (!REALTIME_OPERATOR.test(param.operator)) { + return false + } + // Realtime can only evaluate a top-level table column, never an embedded one. + if (param.column.includes('.')) { + return false + } + if (param.operator.endsWith('in')) { + // An empty IN list matches nothing; the catch-all keeps the subscription + // usable and lets the live query re-filter client-side. + if (param.value === '()') { + return false + } + // Splitting on commas overcounts values that quote a comma, which only ever + // trips the limit early and falls back to the (correct) catch-all. + const members = param.value.slice(1, -1).split(',') + if (members.length > MAX_IN_VALUES) { + return false + } + } + return true +} + +/** + * Build the Realtime `postgres_changes` filters for a table's active queries. + * + * The result is a single `URLSearchParams` with one repeated `filter` entry per + * active query, each value being that query's AND-ed conditions comma-joined + * into Realtime's wire form (e.g. `active=eq.true,id=gt.5`). Conditions and + * queries are sorted and deduplicated so an unchanged filter set produces a + * stable `toString()` key. An empty `URLSearchParams` is the catch-all: it is + * returned whenever any query is unfiltered or uses an expression Realtime + * cannot evaluate, since a narrower subscription would drop rows that query + * needs. + */ +export function realtimeFiltersToSearch( + whereExpressions: Array, +): URLSearchParams { + const groups = new Set() + + for (const where of whereExpressions) { + let params: Array + try { + // `strict` throws on anything unpushable (server aggregates, functions); + // `quoteScalars` matches the request path's quoting so reserved characters + // survive the comma-joined condition list. + params = toPostgrestParams(where, { quoteScalars: true, strict: true }) + } catch { + return new URLSearchParams() + } + + // A query with no pushable conditions matches every row, so the whole table + // must fall back to the catch-all. + if (params.length === 0) { + return new URLSearchParams() + } + + const conditions = new Set() + for (const param of params) { + if (!isRealtimeParam(param)) { + return new URLSearchParams() + } + conditions.add(`${param.column}=${param.operator}.${param.value}`) + } + groups.add(Array.from(conditions).sort().join(',')) + } + + const search = new URLSearchParams() + for (const filter of Array.from(groups).sort()) { + search.append('filter', filter) + } + return search +} diff --git a/packages/supabase-db-collection/src/postgrest-filters/split-load-subset-options.ts b/packages/supabase-db-collection/src/postgrest-filters/split-load-subset-options.ts new file mode 100644 index 0000000000..bd099beb1e --- /dev/null +++ b/packages/supabase-db-collection/src/postgrest-filters/split-load-subset-options.ts @@ -0,0 +1,258 @@ +import { IR } from '@tanstack/db' +import { flattenAnd, mergeInFilters } from './common' +import type { LoadSubsetOptions } from '@tanstack/db' +import type { SerializedExpression as Expression } from '../serialize' + +export interface SplitLoadSubsetOptionsConfig { + /** The longest URL (in characters) a single chunk's request may produce. */ + maxUrlLength: number + /** + * Renders the longest URL a given subset would produce (main request, and + * the `whereCurrent` tie request when the subset has a cursor). Injected so + * the splitter stays a pure function of its inputs — the caller supplies the + * real `supabase.from(table).url` + search rendering, tests supply a fake. + */ + measure: (options: LoadSubsetOptions) => number +} + +type SplittableConjunct = { + index: number + path: Array + values: Array +} + +// Mirrors `renderComparison`'s IN handling (common.ts): TanStack's membership +// test ignores null members, and duplicates contribute nothing extra to the +// rendered list, so both are stripped before we decide how big a conjunct is +// and before we hand out chunk values. +function dedupedValues(values: Array): Array { + return Array.from(new Set(values.filter((value) => value != null))) +} + +// Only a positive, top-level `in(ref, [...])` conjunct is safe to split: the +// union of its chunks is the same set of matching rows. `not(in(...))` and any +// IN nested in OR/NOT are left untouched by the caller (they never reach here +// as a candidate) because a chunked union is not equivalent to their meaning. +function splittableConjuncts( + conjuncts: Array, +): Array { + const candidates: Array = [] + conjuncts.forEach((conjunct, index) => { + if (conjunct.type !== 'func' || conjunct.name !== 'in') { + return + } + const [left, right] = conjunct.args + if ( + left?.type !== 'ref' || + right?.type !== 'val' || + !Array.isArray(right.value) + ) { + return + } + const values = dedupedValues(right.value) + if (values.length === 0) { + // Nothing to chunk (every member was null, or the list was empty); leave + // the conjunct exactly as it was rendered before. + return + } + candidates.push({ index, path: left.path, values }) + }) + // Largest first: the biggest IN list is the one worth splitting, and the + // fallback in `splitConjuncts` halves the next-largest one. + return candidates.sort((a, b) => b.values.length - a.values.length) +} + +function replaceConjunct( + conjuncts: Array, + candidate: SplittableConjunct, + values: Array, +): Array { + const copy = conjuncts.slice() + copy[candidate.index] = new IR.Func('in', [ + new IR.PropRef(candidate.path), + new IR.Value(values), + ]) + return copy +} + +function rebuildWhere( + conjuncts: Array, +): LoadSubsetOptions['where'] { + if (conjuncts.length === 0) { + return + } + const where = + conjuncts.length === 1 + ? conjuncts[0] + : new IR.Func('and', conjuncts as unknown as Array) + // `conjuncts` entries are either untouched pieces of the caller's own + // `where` (already real IR instances) or `IR.Func`/`IR.Value`/`IR.PropRef` + // instances built above, so this is a widen-then-narrow of the same runtime + // shape `toPostgrestParams` already accepts elsewhere in this package. + return where as unknown as LoadSubsetOptions['where'] +} + +// Applies the caller's `options` (limit/offset/cursor, orderBy, etc.) to one +// chunk's conjunct list, rewriting limit/offset per the plan: a cursor read +// keeps its limit unchanged (the cursor already pins the window start via a +// filter); a cursor-less read with an offset must ask each chunk for enough +// rows to cover the *whole* global window (`limit + offset`) starting at 0, +// because every row in that window ranks at most `offset + limit` inside its +// own chunk — the union of per-chunk windows then still contains the global +// window, with no cross-chunk merge needed since chunks are disjoint on the +// split column. +function buildChunkOptions( + options: LoadSubsetOptions, + conjuncts: Array, +): LoadSubsetOptions { + const chunk: LoadSubsetOptions = { + ...options, + where: rebuildWhere(conjuncts), + } + if (!options.cursor && options.offset) { + if (options.limit !== undefined) { + chunk.limit = options.limit + options.offset + } + chunk.offset = undefined + } + return chunk +} + +// Binary-search the longest prefix of `values` whose chunk still fits the +// budget; `fits` is monotonically decreasing in prefix length, so this is +// O(log n) renders instead of O(n). +function longestFittingPrefix( + fits: (length: number) => boolean, + count: number, +): number { + if (count === 0 || !fits(1)) { + return 0 + } + if (fits(count)) { + return count + } + let low = 1 + let high = count + while (low < high) { + const mid = low + Math.ceil((high - low) / 2) + if (fits(mid)) { + low = mid + } else { + high = mid - 1 + } + } + return low +} + +/** + * Split one oversized subset's conjunct list into several whose rendered URL + * fits `maxUrlLength`. The largest splittable IN is packed greedily; when not + * even one of its values fits because another IN is also huge, that other IN + * is halved and each half is split again from scratch. Halving (rather than + * packing the other IN as tightly as possible) leaves room for more than one + * value of the largest IN per chunk, so the chunk count stays close to the + * minimum. The resulting conjunct lists are a cartesian product of the split + * candidates and remain pairwise disjoint on the split column(s), so the union + * of their result sets is exactly the original subset's — no dedupe needed. + * + * Returns `undefined` when no split fits: something other than the split + * candidates (e.g. a huge `not(in(...))`) keeps even a single value over + * budget, so fanning out would only send more oversized requests. + */ +function splitConjuncts( + options: LoadSubsetOptions, + conjuncts: Array, + config: SplitLoadSubsetOptionsConfig, +): Array> | undefined { + const [current, ...rest] = splittableConjuncts(conjuncts) + if (!current) { + return [conjuncts] + } + + const chunks: Array> = [] + let remaining = current.values + while (remaining.length > 0) { + const fits = (length: number) => + config.measure( + buildChunkOptions( + options, + replaceConjunct(conjuncts, current, remaining.slice(0, length)), + ), + ) <= config.maxUrlLength + const fitLength = longestFittingPrefix(fits, remaining.length) + + if (fitLength > 0) { + chunks.push( + replaceConjunct(conjuncts, current, remaining.slice(0, fitLength)), + ) + remaining = remaining.slice(fitLength) + continue + } + + const other = rest.find((candidate) => candidate.values.length > 1) + if (!other) { + // Nothing left to shrink and even a single value does not fit. + return + } + + // Another IN is too big to leave room for even one of `current`'s values: + // halve it, and split each half (with `current`'s remaining values) again. + const withRemaining = replaceConjunct(conjuncts, current, remaining) + const middle = Math.ceil(other.values.length / 2) + for (const half of [ + other.values.slice(0, middle), + other.values.slice(middle), + ]) { + const halfChunks = splitConjuncts( + options, + replaceConjunct(withRemaining, other, half), + config, + ) + if (!halfChunks) { + return + } + chunks.push(...halfChunks) + } + remaining = [] + } + return chunks +} + +/** + * Split an oversized `loadSubset` request into several whose rendered URL each + * fit `maxUrlLength`, so a caller can run them as separate requests and + * concatenate the results. Returns `[options]` unchanged — the same object, + * not a copy — whenever it already fits, so the common path sends a + * byte-identical URL and keeps today's behaviour. + * + * Only a positive, top-level `AND`ed `in(ref, [...])` conjunct is ever split: + * splitting inside `OR`/`NOT`, or a top-level `not(in(...))`, would change + * which rows the union of chunks matches. When no such conjunct exists, + * `options.where` is absent, or no split brings every chunk within budget, + * this returns `[options]` and the caller sends the request as-is, letting the server's own error (if any) surface exactly + * as it does today. + */ +export function splitLoadSubsetOptions( + options: LoadSubsetOptions, + config: SplitLoadSubsetOptionsConfig, +): Array { + if (config.measure(options) <= config.maxUrlLength) { + return [options] + } + if (!options.where) { + return [options] + } + + const conjuncts = mergeInFilters(flattenAnd(options.where)) + if (splittableConjuncts(conjuncts).length === 0) { + return [options] + } + + const chunks = splitConjuncts(options, conjuncts, config) + if (!chunks) { + return [options] + } + return chunks.map((chunkConjuncts) => + buildChunkOptions(options, chunkConjuncts), + ) +} diff --git a/packages/supabase-db-collection/src/postgrest-filters/subset-params-to-search.ts b/packages/supabase-db-collection/src/postgrest-filters/subset-params-to-search.ts new file mode 100644 index 0000000000..d6a87f83ad --- /dev/null +++ b/packages/supabase-db-collection/src/postgrest-filters/subset-params-to-search.ts @@ -0,0 +1,37 @@ +import { parseOrderByExpression } from '@tanstack/db' +import { + appendLimit, + appendOrder, + paramsToSearch, + toPostgrestParams, +} from './common' +import type { LoadSubsetOptions } from '@tanstack/db' + +/** + * Encode the params that identify a cached subset — where filters, order, and + * limit. Deliberately excludes `select`, `cursor`, and `offset`: those are the + * per-page request details, not part of what distinguishes one subset from + * another. This is the shared core of the request URL and the query key, so the + * two cannot drift. + */ +export function subsetParamsToSearch( + options: LoadSubsetOptions, +): URLSearchParams { + const { where, orderBy, limit } = options + const search = paramsToSearch(toPostgrestParams(where, { mergeIn: true })) + appendOrder( + search, + parseOrderByExpression(orderBy).map((sort) => ({ + column: sort.field.join('.'), + ascending: sort.direction === 'asc', + })), + ) + // `limit: 0` is a real, distinct subset (an empty window). Guard on + // `undefined`, not falsiness, so it does not collide with the unlimited query + // on one cache key — otherwise the empty limit-0 result would take over and + // delete every row the unlimited query owns. + if (limit !== undefined) { + appendLimit(search, limit) + } + return search +} diff --git a/packages/supabase-db-collection/src/postgrest-request.ts b/packages/supabase-db-collection/src/postgrest-request.ts new file mode 100644 index 0000000000..358e8af3aa --- /dev/null +++ b/packages/supabase-db-collection/src/postgrest-request.ts @@ -0,0 +1,101 @@ +import { PostgrestError, PostgrestFilterBuilder } from '@supabase/postgrest-js' +import { CLIENT_INFO, CLIENT_INFO_HEADER } from './request-headers' +import type { SupabaseClient } from '@supabase/supabase-js' + +const SINGLE_ROW_ACCEPT = 'application/vnd.pgrst.object+json' + +interface PostgrestRequestOptions { + /** JSON body for insert/update. */ + body?: unknown + /** + * Ask PostgREST for the total matching-row count (`Prefer: count=…`). The + * count is read back off the `Content-Range` header; the paging loop uses it + * to fetch a set larger than the server's `db-max-rows` cap without probing. + */ + count?: 'exact' | 'planned' | 'estimated' + method: 'GET' | 'POST' | 'PATCH' | 'DELETE' + /** Ask PostgREST to return the affected rows (`Prefer: return=representation`). */ + returnRows?: boolean + /** The full query string, built by the params helpers. */ + search: URLSearchParams + /** Abort signal, threaded from the query's `ctx.signal`. */ + signal?: AbortSignal + /** Expect exactly one row (`Accept: application/vnd.pgrst.object+json`). */ + single?: boolean +} + +/** A PostgREST read result: the rows plus the total count when one was asked for. */ +export interface PostgrestResult { + /** Total matching rows when `count` was requested, else `null`. */ + count: number | null + /** The response body: an array of rows, a single row, or `null` when empty. */ + data: TData | null +} + +/** + * Issue a PostgREST request with a hand-built query string while leaving + * supabase-js in charge of auth, schema, tracing, timeout, and transport. + * + * `supabase.from(table)` yields a `PostgrestQueryBuilder` whose `url`, + * `headers`, `schema`, and `fetch` are the auth-injecting, timeout-wrapped + * request state (the `fetch` wrapper derives `apikey`/`Authorization`, the + * headers already carry the user's `global.headers`). We clone that state, + * swap in our own search string, and hand it to `PostgrestFilterBuilder` — a + * documented standalone entry point — so we reuse its `Accept-Profile`/ + * `Content-Profile`, response parsing, and error handling without re-deriving + * auth ourselves. + */ +export async function postgrestRequest( + supabase: SupabaseClient, + table: string, + { + method, + search, + body, + returnRows, + single, + count, + signal, + }: PostgrestRequestOptions, +): Promise> { + const queryBuilder = supabase.from(table) + + const url = new URL(queryBuilder.url.toString()) + url.search = search.toString() + + const headers = new Headers(queryBuilder.headers) + headers.set(CLIENT_INFO_HEADER, CLIENT_INFO) + if (returnRows) { + headers.append('Prefer', 'return=representation') + } + if (count) { + headers.append('Prefer', `count=${count}`) + } + if (single) { + headers.set('Accept', SINGLE_ROW_ACCEPT) + } + + // PostgrestFilterBuilder's generics describe database schema types that are + // unavailable without codegen and irrelevant here, since only `data`, `error` + // and `count` are read off the awaited response. Pinning them to `any` also + // keeps this call valid across postgrest-js versions that differ in the + // number of generic parameters. + const builder = new PostgrestFilterBuilder({ + method, + url, + headers, + schema: queryBuilder.schema, + body, + fetch: queryBuilder.fetch, + // The builder threads its own `signal` straight into the underlying fetch, + // so aborting the query cancels the in-flight request. + signal, + }) + + const { data, error, count: total } = await builder + if (error) { + throw error instanceof Error ? error : new PostgrestError(error) + } + // The caller states the response shape it expects for this request. + return { data: data as TData | null, count: total ?? null } +} diff --git a/packages/supabase-db-collection/src/query-client.ts b/packages/supabase-db-collection/src/query-client.ts new file mode 100644 index 0000000000..ac44b7b794 --- /dev/null +++ b/packages/supabase-db-collection/src/query-client.ts @@ -0,0 +1,30 @@ +import { QueryClient, isServer } from '@tanstack/query-core' + +function makeQueryClient() { + return new QueryClient({ + defaultOptions: { + queries: { + // With SSR, we usually want to set some default staleTime + // above 0 to avoid refetching immediately on the client + staleTime: 60 * 1000, + }, + }, + }) +} + +let browserQueryClient: QueryClient | undefined + +export function getQueryClient() { + if (isServer) { + // Server: always make a new query client + return makeQueryClient() + } + // Browser: make a new query client if we don't already have one + // This is very important, so we don't re-make a new client if React + // suspends during the initial render. This may not be needed if we + // have a suspense boundary BELOW the creation of the query client + if (!browserQueryClient) { + browserQueryClient = makeQueryClient() + } + return browserQueryClient +} diff --git a/packages/supabase-db-collection/src/realtime.ts b/packages/supabase-db-collection/src/realtime.ts new file mode 100644 index 0000000000..9b7d47c076 --- /dev/null +++ b/packages/supabase-db-collection/src/realtime.ts @@ -0,0 +1,449 @@ +import { REALTIME_SUBSCRIBE_STATES } from '@supabase/supabase-js' +import { + DeleteOperationItemNotFoundError, + UpdateOperationItemNotFoundError, +} from '@tanstack/query-db-collection' +import { realtimeFiltersToSearch } from './postgrest-filters' +import { parseRow } from './row-conversions' +import type { ColumnConversions } from './row-conversions' +import type { + RealtimePostgresChangesFilter, + RealtimePostgresDeletePayload, + RealtimePostgresUpdatePayload, + SupabaseClient, +} from '@supabase/supabase-js' +import type { Collection } from '@tanstack/db' +import type { QueryClient } from '@tanstack/query-core' + +type ChangeEvent = 'INSERT' | 'UPDATE' | 'DELETE' + +export type RealtimeSubscription = { + channel: ReturnType + /** + * Resolves with the terminal subscribe status — `SUBSCRIBED`, + * `CHANNEL_ERROR`, or `CLOSED`. It is not time-bounded: while realtime-js is + * still retrying the join (e.g. `TIMED_OUT`) it stays pending. Callers + * distinguish a filter rejection (`CHANNEL_ERROR` on a filtered subscription) + * from a transient connection error, so a dropped connection is not mistaken + * for a server rejection. + */ + outcome: Promise +} + +/** + * Whether a row is in the collection's synced store. + * + * `collection.has()` reflects the optimistic view, which includes local + * mutations that are still in flight. The manual sync writes here (and the + * delete guard in {@link ./functions}) validate against the synced store only, + * so that is the store to check: a Realtime echo of a pending local insert must + * not be treated as an update, and a row with a pending local delete is still + * there to be updated or deleted. + */ +export const isSynced = ( + collection: Collection, + key: TKey, +): boolean => collection._state.syncedData.has(key) + +/** + * Direct writes are applied asynchronously, so the row can be removed — e.g. by + * the local delete handler confirming the same delete — between the + * {@link isSynced} check and the write landing. The row is gone either way. + */ +const ignoreRemovedRow = (error: unknown) => { + if ( + error instanceof UpdateOperationItemNotFoundError || + error instanceof DeleteOperationItemNotFoundError + ) { + return + } + throw error +} + +/** + * Subscribes to Supabase Realtime changes for a table and writes inserts, + * updates, and deletes into the collection. + * + * Filters are applied to INSERT and UPDATE listeners only: a filtered event is + * Realtime telling us the row matches an active query, which is what makes it + * belong in the collection — including a row that an UPDATE moved into that + * query's window. Two extra unfiltered listeners cover what a filtered + * subscription cannot see: + * + * - UPDATE, so a row already in the collection still receives its changes after + * it stops matching the filter instead of going stale. + * - DELETE, because Realtime only delivers filtered delete events for tables + * with `replica identity full`, and delete payloads are just the key anyway. + * + * `filters` is the {@link ./postgrest-filters!realtimeFiltersToSearch} result: + * one `filter` entry per active query, each a comma-joined Realtime condition + * list. No entries means a catch-all subscription to every change on the table. + */ +export const attachSupabaseListeners = < + T extends Record, + TKey extends string | number, +>( + supabase: SupabaseClient, + topic: string, + tableName: string, + collection: Collection, + filters: URLSearchParams = new URLSearchParams(), + conversions: ColumnConversions = {}, +): RealtimeSubscription => { + const channel = supabase.channel(topic) + + const changesFilter = ( + event: TEvent, + filter?: string, + ): RealtimePostgresChangesFilter => { + const config: RealtimePostgresChangesFilter = { + event, + schema: 'public', + table: tableName, + } + if (filter) { + config.filter = filter + } + return config + } + + // The row matches an active query's filter, so it belongs in the collection + // whether or not we have seen it before. Upsert decides insert-vs-update on + // the synced store, which also makes replayed or racing events harmless. + const handleUpsert = (payload: { new: T }) => { + collection.utils.writeUpsert(parseRow(payload.new, conversions)) + } + + // Unfiltered updates arrive for every row in the table, so only rows the + // collection already holds are written — otherwise it would mirror the whole + // table locally. + const handleKnownUpdate = (payload: RealtimePostgresUpdatePayload) => { + const row = parseRow(payload.new, conversions) + if (isSynced(collection, collection.getKeyFromItem(row))) { + collection.utils.writeUpdate(row).catch(ignoreRemovedRow) + } + } + + const handleDelete = (payload: RealtimePostgresDeletePayload) => { + const id = collection.getKeyFromItem(parseRow(payload.old, conversions)) + if (isSynced(collection, id)) { + collection.utils.writeDelete(id).catch(ignoreRemovedRow) + } + } + + const conditions = filters.getAll('filter') + // A catch-all subscription registers one unfiltered INSERT/UPDATE pair. + for (const filter of conditions.length > 0 ? conditions : [undefined]) { + channel.on( + 'postgres_changes', + changesFilter('INSERT', filter), + handleUpsert, + ) + channel.on( + 'postgres_changes', + changesFilter('UPDATE', filter), + handleUpsert, + ) + } + + // The extra unfiltered UPDATE listener only earns its keep when the INSERT/ + // UPDATE listeners above are filtered; a catch-all already sees every update. + if (conditions.length > 0) { + channel.on( + 'postgres_changes', + changesFilter('UPDATE'), + handleKnownUpdate, + ) + } + + channel.on('postgres_changes', changesFilter('DELETE'), handleDelete) + + let resolveOutcome: (status: REALTIME_SUBSCRIBE_STATES) => void = () => + undefined + const outcome = new Promise((resolve) => { + resolveOutcome = resolve + }) + + channel.subscribe((status) => { + // SUBSCRIBED means the join succeeded. CHANNEL_ERROR is how the server + // rejects a subscription — typically a filter it cannot evaluate — but it is + // also emitted for a transient transport failure, so the caller tells the + // two apart. CLOSED is a terminal close before joining. TIMED_OUT is + // deliberately not terminal: realtime-js keeps retrying the join and reports + // the outcome through this same callback. + if ( + status === REALTIME_SUBSCRIBE_STATES.SUBSCRIBED || + status === REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR || + status === REALTIME_SUBSCRIBE_STATES.CLOSED + ) { + resolveOutcome(status) + } + }) + + return { channel, outcome } +} + +/** + * A table's Realtime channel lifecycle state, held by the registry in + * {@link ./db}. The joined channel and any in-flight swap are tracked + * separately so a replacement can be superseded or torn down without losing the + * channel that is still delivering changes. + */ +export interface TableEntry { + /** + * The collection receiving realtime writes. Its row type comes from the + * caller's schema, so the registry (keyed only by table name) cannot name it. + */ + collectionRef: Collection | null + /** Converts Realtime payload rows to the rows the collection holds. */ + conversions: ColumnConversions + /** The joined channel currently delivering changes (null when none). */ + realtimeChannel: ReturnType | null + /** Serialized set of Realtime filters the current channel was subscribed with */ + realtimeFiltersKey: string | null + /** + * A replacement channel that is still subscribing and has not joined yet. It + * is tracked separately from {@link realtimeChannel} so an in-flight swap can + * be superseded or torn down without losing the channel that is still + * delivering changes. + */ + realtimePendingChannel: ReturnType | null + /** Serialized set of Realtime filters {@link realtimePendingChannel} is subscribing with */ + realtimePendingFiltersKey: string | null + /** + * Whether WHERE clauses are pushed to Realtime as server-side filters. When + * `false`, the table always subscribes with a catch-all and filters + * client-side. + */ + realtimeUseFilter: boolean + /** + * Filter sets the server has rejected. They are replaced by a catch-all + * subscription instead of being retried on every observer change. + */ + rejectedFilterKeys: Set + supabase: SupabaseClient +} + +/** A subscription that receives every change for the table. */ +const CATCH_ALL_FILTERS = new URLSearchParams() +/** The registry key of the catch-all: an empty filter set serializes to "". */ +const CATCH_ALL_KEY = '' + +/** + * Channel topics are namespaced and numbered because `supabase.channel()` + * returns the *existing* channel for a topic that is already registered, and + * subscribing to an already-joined channel throws. Reusing the table name would + * hand back the channel currently being torn down, and could collide with a + * channel the application opened itself or with another QueryClient sharing the + * same Supabase client — so the counter is module-level, not per table. + */ +let channelCount = 0 + +/** + * Every channel this adapter opens for `tableName` has a topic starting with + * this prefix (supabase-js exposes it under its own `realtime:` prefix). + */ +export const realtimeChannelTopicPrefix = (tableName: string) => + `supabase-tanstack-db:${tableName}:` + +const nextChannelTopic = (tableName: string) => { + channelCount += 1 + return `${realtimeChannelTopicPrefix(tableName)}${channelCount}` +} + +/** + * Opens a channel for `filters` as the table's *pending* channel. The joined + * channel keeps listening until the replacement actually joins, so no change + * slips through while the swap is in flight; only then is the predecessor + * removed. A swap already in flight is superseded (and torn down) first. + * + * On a terminal failure the pending channel is disposed. A filter the server + * rejects is remembered and retried as a catch-all, while the previous channel + * keeps working. A `CHANNEL_ERROR` on the catch-all itself is treated as a + * transient connection error, not a rejection: if a previous channel is still + * working it is kept, otherwise the errored channel is retained so realtime-js + * reconnects it instead of leaving the table with no subscription at all. + */ +function subscribeToChanges( + queryClient: QueryClient, + entry: TableEntry, + tableName: string, + collection: Collection, + filters: URLSearchParams, + filtersKey: string, +) { + const previousChannel = entry.realtimeChannel + const previousFiltersKey = entry.realtimeFiltersKey + + // A swap already in flight is now stale: tear it down before opening the next + // so a superseded replacement never leaks. + if (entry.realtimePendingChannel) { + entry.supabase.removeChannel(entry.realtimePendingChannel) + entry.realtimePendingChannel = null + entry.realtimePendingFiltersKey = null + } + + const subscription = attachSupabaseListeners( + entry.supabase, + nextChannelTopic(tableName), + tableName, + collection, + filters, + entry.conversions, + ) + + entry.realtimePendingChannel = subscription.channel + entry.realtimePendingFiltersKey = filtersKey + + // True once a newer swap (or a teardown) has taken over this pending channel. + const superseded = () => entry.realtimePendingChannel !== subscription.channel + + const onJoined = () => { + if (superseded()) { + return + } + if (previousChannel) { + entry.supabase.removeChannel(previousChannel) + } + entry.realtimeChannel = subscription.channel + entry.realtimeFiltersKey = filtersKey + entry.realtimePendingChannel = null + entry.realtimePendingFiltersKey = null + } + + const onError = () => { + if (superseded()) { + entry.supabase.removeChannel(subscription.channel) + return + } + entry.realtimePendingChannel = null + entry.realtimePendingFiltersKey = null + + if (filtersKey !== CATCH_ALL_KEY) { + // A filtered subscription the server refused: drop it, remember it, and + // let syncTableSubscription pick the catch-all it now maps to — the same + // decision the observer makes — while the previous channel keeps working. + entry.supabase.removeChannel(subscription.channel) + entry.rejectedFilterKeys.add(filtersKey) + syncTableSubscription(queryClient, tableName, entry) + return + } + + // A catch-all has nothing to reject, so CHANNEL_ERROR here is a transient + // connection error rather than a filter rejection. + if (previousChannel) { + // A previous channel is still delivering changes: drop the failed + // catch-all and hand the swap back to the predecessor. + entry.supabase.removeChannel(subscription.channel) + entry.realtimeChannel = previousChannel + entry.realtimeFiltersKey = previousFiltersKey + return + } + // Nothing else is subscribed: keep the errored channel so realtime-js + // reconnects it (its listeners stay attached) instead of leaving the table + // with no subscription until an observer changes. + entry.realtimeChannel = subscription.channel + entry.realtimeFiltersKey = filtersKey + } + + const onClosed = () => { + // A terminal close before joining will not reconnect: drop it and hand the + // swap back to the still-open previous channel. + if (superseded()) { + entry.supabase.removeChannel(subscription.channel) + return + } + entry.supabase.removeChannel(subscription.channel) + entry.realtimeChannel = previousChannel + entry.realtimeFiltersKey = previousFiltersKey + entry.realtimePendingChannel = null + entry.realtimePendingFiltersKey = null + } + + subscription.outcome.then((status) => { + if (status === REALTIME_SUBSCRIBE_STATES.SUBSCRIBED) { + onJoined() + } else if (status === REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR) { + onError() + } else { + onClosed() + } + }) +} + +/** + * Reconcile one table's Realtime subscription with its active queries: tear the + * channel down when there are none, otherwise derive the filters and (re)open a + * channel unless the current (or in-flight) one already matches. This is the + * single place that maps active queries to filters, so both the cache observer + * and the rejection fallback route through it. + */ +export function syncTableSubscription( + queryClient: QueryClient, + tableName: string, + entry: TableEntry, +) { + const queries = queryClient.getQueryCache().findAll({ + queryKey: [tableName], + type: 'active', + }) + + // No active queries: tear down any existing subscription, including a swap + // still in flight, so neither the joined nor the pending channel leaks. + if (queries.length === 0) { + if (entry.realtimeChannel) { + entry.supabase.removeChannel(entry.realtimeChannel) + } + if (entry.realtimePendingChannel) { + entry.supabase.removeChannel(entry.realtimePendingChannel) + } + entry.realtimeChannel = null + entry.realtimeFiltersKey = null + entry.realtimePendingChannel = null + entry.realtimePendingFiltersKey = null + return + } + + if (!entry.collectionRef) { + return + } + + // Derive the Realtime filters from the WHERE clause of every active query so + // the subscription only receives changes that those queries care about. When + // server-side filtering is disabled, skip that and subscribe to every change. + let filters = CATCH_ALL_FILTERS + let filtersKey = CATCH_ALL_KEY + if (entry.realtimeUseFilter) { + const whereExpressions = queries.map( + (query) => query.meta?.loadSubsetOptions?.where, + ) + filters = realtimeFiltersToSearch(whereExpressions) + filtersKey = filters.toString() + if (entry.rejectedFilterKeys.has(filtersKey)) { + filters = CATCH_ALL_FILTERS + filtersKey = CATCH_ALL_KEY + } + } + + // Reuse the existing subscription when the set of filters hasn't changed. + // While a swap is in flight the pending channel already targets the new + // filters, so compare against it to avoid firing the same swap twice. + const currentFiltersKey = entry.realtimePendingChannel + ? entry.realtimePendingFiltersKey + : entry.realtimeFiltersKey + if ( + (entry.realtimeChannel || entry.realtimePendingChannel) && + currentFiltersKey === filtersKey + ) { + return + } + + subscribeToChanges( + queryClient, + entry, + tableName, + entry.collectionRef, + filters, + filtersKey, + ) +} diff --git a/packages/supabase-db-collection/src/request-headers.ts b/packages/supabase-db-collection/src/request-headers.ts new file mode 100644 index 0000000000..12ad8261fa --- /dev/null +++ b/packages/supabase-db-collection/src/request-headers.ts @@ -0,0 +1,13 @@ +import { VERSION } from './version' + +/** + * Header name and value used to identify requests made by this library. + * + * Chain `.setHeader(CLIENT_INFO_HEADER, CLIENT_INFO)` onto a + * `PostgrestQueryBuilder`/`PostgrestFilterBuilder` call to stamp the + * request. This intentionally REPLACES supabase-js's own default + * `X-Client-Info` header (matching the `@supabase/ssr` convention) rather + * than appending to or preserving it. + */ +export const CLIENT_INFO_HEADER = 'X-Client-Info' +export const CLIENT_INFO = `@tanstack/supabase-db-collection/${VERSION}` diff --git a/packages/supabase-db-collection/src/row-conversions.ts b/packages/supabase-db-collection/src/row-conversions.ts new file mode 100644 index 0000000000..1ff1c9c338 --- /dev/null +++ b/packages/supabase-db-collection/src/row-conversions.ts @@ -0,0 +1,70 @@ +/** + * Per-column conversions from a row as it travels over the wire to the row the + * collection holds (`parse`), and back (`serialize`). + * + * PostgREST and Realtime speak JSON, so a `timestamptz` arrives as a string and + * a `bigint` as a number (and `JSON.stringify` throws on a `bigint` request + * body). A collection whose schema declares `Date` or `bigint` columns needs + * these conversions to read and write them. + * + * A conversion is only called for a column that is present in the row and not + * `null` / `undefined`; those pass through unchanged, so nullable columns need + * no special handling. + */ +export interface RowConversions { + /** + * Converts a column value received from PostgREST or Realtime into the value + * the collection holds. Applies to rows read, rows returned by inserts and + * updates, and Realtime payloads. + */ + parse?: { + [K in keyof TItem]?: (value: unknown) => NonNullable + } + /** + * Converts a column value held by the collection into the JSON-serializable + * value sent to PostgREST in insert and update bodies, and used to match rows + * by key on update and delete. + */ + serialize?: { + [K in keyof TItem]?: (value: NonNullable) => unknown + } +} + +/** + * The conversions with their per-column types erased. The caller's options are + * type-checked against {@link RowConversions}; the plumbing that applies them + * only needs to look a column up by name. + */ +export interface ColumnConversions { + parse?: Record unknown> + serialize?: Record unknown> +} + +const convertRow = ( + row: object, + conversions: Record unknown> | undefined, +): Record => { + if (!conversions) { + return { ...row } + } + const converted: Record = { ...row } + for (const [column, convert] of Object.entries(conversions)) { + const value = converted[column] + if (value != null) { + converted[column] = convert(value as never) + } + } + return converted +} + +/** Applies `parse` to a row received from the server. */ +export const parseRow = ( + row: object, + { parse }: ColumnConversions, +): TItem => convertRow(row, parse) as TItem + +/** Applies `serialize` to a row about to be sent to the server. */ +export const serializeRow = ( + row: object, + { serialize }: ColumnConversions, +): Record => convertRow(row, serialize) diff --git a/packages/supabase-db-collection/src/serialize.ts b/packages/supabase-db-collection/src/serialize.ts new file mode 100644 index 0000000000..da076724b8 --- /dev/null +++ b/packages/supabase-db-collection/src/serialize.ts @@ -0,0 +1,8 @@ +// The expression shape the PostgREST filter renderer understands. TanStack DB's +// `IR.BasicExpression` is structurally assignable to it, so `loadSubset` where +// clauses can be rendered without converting them first. +export type SerializedExpression = + | { type: `ref`; path: Array } + | { type: `val`; value: unknown } + | { type: `func`; name: string; args: Array } + | { type: `agg`; name: string; args: Array } diff --git a/packages/supabase-db-collection/src/version.ts b/packages/supabase-db-collection/src/version.ts new file mode 100644 index 0000000000..f26fbe5d0c --- /dev/null +++ b/packages/supabase-db-collection/src/version.ts @@ -0,0 +1,4 @@ +// Injected at build time by the `define` in vite.config.ts from package.json. +declare const __SUPABASE_DB_COLLECTION_VERSION__: string + +export const VERSION: string = __SUPABASE_DB_COLLECTION_VERSION__ diff --git a/packages/supabase-db-collection/tests/index.test.ts b/packages/supabase-db-collection/tests/index.test.ts new file mode 100644 index 0000000000..94ecb0a107 --- /dev/null +++ b/packages/supabase-db-collection/tests/index.test.ts @@ -0,0 +1,1034 @@ +import { + add, + and, + avg, + coalesce, + concat, + count, + eq, + groupKeys, + gt, + gte, + ilike, + inArray, + include, + isNull, + isUndefined, + length, + like, + lower, + lt, + lte, + max, + min, + not, + or, + sum, + upper, +} from '@tanstack/db' +import { afterEach, beforeEach, describe, test } from 'vitest' +import { + createMockFetch, + createMockedTodosCollection, + createMockedUsersCollection, + createMockedUsersTodosCollection, + expectFetchUrls, + queryResult, +} from './test.utils' + +describe('PostgREST query generation', () => { + let mockFetch: ReturnType + let usersCollection: ReturnType + let utCollection: ReturnType + let todosCollection: ReturnType + + beforeEach(() => { + mockFetch = createMockFetch() + usersCollection = createMockedUsersCollection(mockFetch) + utCollection = createMockedUsersTodosCollection(mockFetch) + todosCollection = createMockedTodosCollection(mockFetch) + }) + + afterEach(() => { + usersCollection.cleanup() + utCollection.cleanup() + todosCollection.cleanup() + }) + + describe('FROM', () => { + test('SELECT * FROM users', async () => { + await queryResult((q) => q.from({ user: usersCollection })) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + }) + + describe('WHERE', () => { + test('WHERE active = true', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&active=eq.true']) + }) + + test('WHERE id = 1', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).where(({ user }) => eq(user.id, 1)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=eq.1']) + }) + + test("WHERE name = 'John'", async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.name, 'John')), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&name=eq.John']) + }) + + test('WHERE id > 5 (gt)', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).where(({ user }) => gt(user.id, 5)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=gt.5']) + }) + + test('WHERE id >= 5 (gte)', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).where(({ user }) => gte(user.id, 5)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=gte.5']) + }) + + test('WHERE id < 10 (lt)', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).where(({ user }) => lt(user.id, 10)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=lt.10']) + }) + + test('WHERE id <= 10 (lte)', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).where(({ user }) => lte(user.id, 10)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=lte.10']) + }) + + test('WHERE id IN (1, 2, 3)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => inArray(user.id, [1, 2, 3])), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=in.(1,2,3)']) + }) + + test('merges IN filters for the same column', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + and(inArray(user.id, [1, 2]), inArray(user.id, [2, 3])), + ), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=in.(1,2,3)']) + }) + + test('keeps IN filters for different columns separate', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + and(inArray(user.id, [1, 2]), inArray(user.name, ['Alice', 'Bob'])), + ), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&id=in.(1,2)&name=in.(Alice,Bob)', + ]) + }) + + test('WHERE NOT(active = false)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => not(eq(user.active, false))), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=not.eq.false', + ]) + }) + + test('WHERE NOT(id > 5)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => not(gt(user.id, 5))), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=not.gt.5']) + }) + + test('WHERE NOT(id IN (1, 2))', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => not(inArray(user.id, [1, 2]))), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=not.in.(1,2)']) + }) + + test('a Date value is sent as ISO 8601', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + gt(user.name, new Date('2026-01-02T03:04:05.000Z') as never), + ), + ) + // `Date.toString()` would produce something Postgres cannot cast. + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&name=gt.2026-01-02T03:04:05.000Z', + ]) + }) + + test('Date values inside an IN filter are sent as ISO 8601', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + inArray(user.name, [ + new Date('2026-01-02T03:04:05.000Z'), + new Date('2026-02-03T04:05:06.000Z'), + ] as never), + ), + ) + // Each list member goes through quoteValue, which must also render Dates + // as ISO 8601 rather than the locale string from `Date.toString()`. + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&name=in.(2026-01-02T03:04:05.000Z,2026-02-03T04:05:06.000Z)', + ]) + }) + + test('WHERE name IS NULL', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => isNull(user.name)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&name=is.null']) + }) + + test('WHERE NOT(name IS NULL)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => not(isNull(user.name))), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&name=not.is.null']) + }) + + test('a negated condition does not reuse the cache entry of the plain one', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).where(({ user }) => gt(user.id, 5)), + ) + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => not(gt(user.id, 5))), + ) + // Two fetches, not one: a shared query key would have served the second + // query the first query's rows. + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&id=gt.5', + '/rest/v1/users?select=*&id=not.gt.5', + ]) + }) + + test('AND: active = true AND id > 5', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => and(eq(user.active, true), gt(user.id, 5))), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&id=gt.5', + ]) + }) + + test('chained .where', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .where(({ user }) => gt(user.id, 5)), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&id=gt.5', + ]) + }) + + test("WHERE name LIKE '%Ali%'", async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => like(user.name, '%Ali%')), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&name=like.%25Ali%25', + ]) + }) + + test("WHERE name ILIKE '%ali%'", async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => ilike(user.name, '%ali%')), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&name=ilike.%25ali%25', + ]) + }) + + test('OR: active = true OR id = 1', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => or(eq(user.active, true), eq(user.id, 1))), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&or=(active.eq.true,id.eq.1)', + ]) + }) + + test('OR of ILIKEs (search across columns)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + or(ilike(user.name, '%ali%'), ilike(user.email, '%ali%')), + ), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&or=(name.ilike.%25ali%25,email.ilike.%25ali%25)', + ]) + }) + + test("nested AND/OR: active = true AND (id > 5 OR name = 'admin')", async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + and( + eq(user.active, true), + or(gt(user.id, 5), eq(user.name, 'admin')), + ), + ), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&or=(id.gt.5,name.eq.admin)', + ]) + }) + + test('nested AND/OR of ILIKEs', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + and( + eq(user.active, true), + or(ilike(user.name, '%ali%'), ilike(user.email, '%ali%')), + ), + ), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&or=(name.ilike.%25ali%25,email.ilike.%25ali%25)', + ]) + }) + + test('value containing a comma is quoted', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + or(ilike(user.name, '%a,b%'), eq(user.email, 'x,y')), + ), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&or=(name.ilike."%25a,b%25",email.eq."x,y")', + ]) + }) + + test('IN list quotes members containing reserved characters', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => inArray(user.name, ['plain', 'a,b', 'c(d)'])), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&name=in.(plain,"a,b","c(d)")', + ]) + }) + + test('AND drops only the unpushable conjunct', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + and(eq(user.active, true), eq(upper(user.name), 'ALICE')), + ), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&active=eq.true']) + }) + + test('OR containing an unpushable branch is dropped entirely', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + or(eq(user.active, true), eq(upper(user.name), 'ALICE')), + ), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + }) + + describe('SELECT columns (client-side)', () => { + test('subset of fields', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ id: user.id, name: user.name })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('field renaming', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ userId: user.id, fullName: user.name })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('computed boolean with eq', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + isActive: eq(user.active, true), + })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('upper(name)', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + upperName: upper(user.name), + })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('lower(email)', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + lowerEmail: lower(user.email), + })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test("concat(name, ' ', email)", async () => { + await queryResult((q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + nameAndEmail: concat(user.name, ' ', user.email), + })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('length(name)', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + nameLength: length(user.name), + })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('add(id, 1)', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + idPlusOne: add(user.id, 1), + })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test("coalesce(name, 'Unknown')", async () => { + await queryResult((q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + displayName: coalesce(user.name, 'Unknown'), + })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('spread + computed field', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + ...user, + highId: gt(user.id, 5), + })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + }) + + describe('Aggregate functions (client-side)', () => { + test('count(id)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ totalUsers: count(user.id) })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('sum(id)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ sumId: sum(user.id) })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('avg(id)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ avgId: avg(user.id) })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('min(id)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ minId: min(user.id) })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('max(id)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ maxId: max(user.id) })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('multiple aggregates', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + totalUsers: count(user.id), + maxId: max(user.id), + })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('order by $selected/computed field', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ + id: user.id, + name: user.name, + nameLength: length(user.name), + })) + .orderBy(({ $selected }) => $selected.nameLength, 'desc'), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + }) + + describe('GROUP BY (client-side)', () => { + test('single column groupBy', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .groupBy(groupKeys(({ user }) => user.active)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('single column GROUP BY with WHERE', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .groupBy(groupKeys(({ user }) => user.active)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?active=eq.true&select=*']) + }) + + test('multiple columns GROUP BY', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .groupBy(groupKeys(({ user }) => [user.active, user.name])), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('GROUP BY + aggregates', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + userCount: count(user.id), + })), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?active=eq.true&select=*']) + }) + }) + + describe('HAVING (client-side)', () => { + test('HAVING with direct aggregate', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + totalId: sum(user.id), + })) + .having(({ user }) => gt(sum(user.id), 10)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('HAVING with $selected fields', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + totalCount: count(user.id), + })) + .having(({ $selected }) => gt($selected.totalCount, 5)), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + }) + + describe('ORDER BY', () => { + test('default (asc)', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).orderBy(({ user }) => user.name), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&order=name.asc']) + }) + + test('explicit asc', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.name, 'asc'), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&order=name.asc']) + }) + + test('descending', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.name, 'desc'), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&order=name.desc']) + }) + + test('multi-column orderBy', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.name, 'asc') + .orderBy(({ user }) => user.id, 'desc'), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=name.asc,id.desc', + ]) + }) + }) + + describe('LIMIT', () => { + test.todo('basic limit', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.id) + .limit(10), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=id.asc&limit=10', + ]) + }) + }) + + describe('LIMIT + OFFSET', () => { + test.todo('pagination (page 2)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.id) + .limit(20) + .offset(20), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=id.asc&limit=20&offset=20', + ]) + }) + }) + + describe('Subquery in FROM', () => { + test('filtered query as source pushes filter down', async () => { + await queryResult((q) => { + const activeUsers = q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + return q.from({ activeUser: activeUsers }) + }) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&active=eq.true']) + }) + }) + + describe('findOne', () => { + test.todo('findOne with where pushes filter and limit', async () => { + // findOne doesn't use limit=1 in Tanstack DB + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.id, 1)) + .findOne(), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=eq.1&limit=1']) + }) + }) + + describe('DISTINCT (client-side)', () => { + test('single column distinct', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ name: user.name })) + .distinct(), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('multi column distinct', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ name: user.name, active: user.active })) + .distinct(), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('distinct with where clause', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .select(({ user }) => ({ name: user.name })) + .distinct(), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?active=eq.true&select=*']) + }) + }) + + describe('Combined queries', () => { + test.todo('WHERE + ORDER BY + LIMIT', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .orderBy(({ user }) => user.name, 'asc') + .limit(10), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&order=name.asc&limit=10', + ]) + }) + + test('WHERE + ORDER BY', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .orderBy(({ user }) => user.name, 'desc'), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&order=name.desc', + ]) + }) + + test('WHERE + ORDER BY + LIMIT', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .where(({ user }) => gt(user.id, 3)) + .orderBy(({ user }) => user.id) + .limit(5), + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&id=gt.3&order=id.asc&limit=5', + ]) + }) + + test('GROUP BY + HAVING + ORDER BY($selected) + LIMIT (client-side)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + userCount: count(user.id), + maxId: max(user.id), + })) + .having(({ $selected }) => gt($selected.userCount, 0)) + .orderBy(({ $selected }) => $selected.userCount, 'desc') + .limit(10), + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + }) + + describe('JOIN', () => { + test('basic inner join', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .innerJoin({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ), + ) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users_todos?select=*', + '/rest/v1/users?id=in.(user_1)&select=*', + ]) + }) + + test('(left) join with select', async () => { + await queryResult((q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + todos: include( + q + .from({ ut: utCollection }) + .where(({ ut }) => eq(ut.user_id, user.id)), + ), + })), + ) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + ]) + }) + + test('explicit inner join', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .join( + { ut: utCollection }, + ({ user, ut }) => eq(user.id, ut.user_id), + 'inner', + ), + ) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users_todos?select=*', + '/rest/v1/users?id=in.(user_1)&select=*', + ]) + }) + + test('left join', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .leftJoin({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ), + ) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + ]) + }) + + test('right join', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .rightJoin({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ), + ) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users_todos?select=*', + '/rest/v1/users?id=in.(user_1)&select=*', + ]) + }) + + test('full join', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .fullJoin({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ), + ) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*', + ]) + }) + + test('two chained joins (users -> users_todos -> todos)', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .join({ ut: utCollection }, ({ user, ut }) => eq(user.id, ut.user_id)) + .join({ todo: todosCollection }, ({ ut, todo }) => + eq(ut.todo_id, todo.id), + ), + ) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + '/rest/v1/todos?id=in.(todo_1)&select=*', + ]) + }) + + test('JOIN + WHERE + SELECT', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .join({ ut: utCollection }, ({ user, ut }) => eq(user.id, ut.user_id)) + .join({ todo: todosCollection }, ({ ut, todo }) => + eq(ut.todo_id, todo.id), + ) + .where(({ todo }) => eq(todo.completed, false)) + .select(({ user, todo }) => ({ + userName: user.name, + todoTitle: todo.title, + })), + ) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + '/rest/v1/todos?id=in.(todo_1)&select=*', + ]) + }) + + test('filtered subquery as join target', async () => { + await queryResult((q) => { + const activeUserTodos = q + .from({ ut: utCollection }) + .where(({ ut }) => gt(ut.todo_id, 0)) + return q + .from({ user: usersCollection }) + .join({ ut: activeUserTodos }, ({ user, ut }) => + eq(user.id, ut.user_id), + ) + }) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&todo_id=gt.0&user_id=in.(user_1)', + ]) + }) + + test('deduplicated subquery used in multiple joins', async () => { + await queryResult((q) => { + const userTodos = q.from({ ut: utCollection }) + return q + .from({ user: usersCollection }) + .join({ ut1: userTodos }, ({ user, ut1 }) => eq(user.id, ut1.user_id)) + .join({ ut2: userTodos }, ({ user, ut2 }) => eq(user.id, ut2.user_id)) + }) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + ]) + }) + + test('subquery with groupBy + aggregates joined to another query', async () => { + await queryResult((q) => { + const todoCountsByUser = q + .from({ ut: utCollection }) + .groupBy(({ ut }) => ut.user_id) + .select(({ ut }) => ({ + user_id: ut.user_id, + todoCount: count(ut.todo_id), + })) + return q + .from({ user: usersCollection }) + .join({ stats: todoCountsByUser }, ({ user, stats }) => + eq(user.id, stats.user_id), + ) + .select(({ user, stats }) => ({ + userName: user.name, + todoCount: stats.todoCount, + })) + }) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + ]) + }) + + test('find unmatched rows in left join', async () => { + await queryResult((q) => + q + .from({ user: usersCollection }) + .leftJoin({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ) + .where(({ ut }) => isUndefined(ut)), + ) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + ]) + }) + }) +}) diff --git a/packages/supabase-db-collection/tests/pagination.test.ts b/packages/supabase-db-collection/tests/pagination.test.ts new file mode 100644 index 0000000000..dc4ffe5421 --- /dev/null +++ b/packages/supabase-db-collection/tests/pagination.test.ts @@ -0,0 +1,490 @@ +import { createClient } from '@supabase/supabase-js' +import { + IR, + createCollection, + createLiveQueryCollection, + createLiveQueryWindowController, +} from '@tanstack/db' +import { QueryClient } from '@tanstack/query-core' +import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest' +import { z } from 'zod' +import { supabaseQueryFn } from '../src/functions' +import { supabaseCollectionOptions } from '../src/index' +import { getSearches, makePaginatingFetch } from './pagination.utils' +import { SUPABASE_KEY, SUPABASE_URL } from './test.utils' + +// A live infinite query (`useLiveInfiniteQuery`) is, without React, a +// `createLiveQueryWindowController` over an ordered+limited live query. Growing +// the window makes core hand the adapter keyset `LoadSubsetOptions.cursor`s, +// which is the path these tests exercise end to end against a mocked PostgREST. +// +// NOTE — two kinds of `=eq.` reads appear below: +// 1. Boundary probe: core's `OrderedSourceLoader.loadBoundary()` issues +// `requestSnapshot({ where: eq(col, boundary) })` — where only, no order, +// no limit — to settle the peek row that decides `hasNextPage`. The adapter +// renders it `select=*&=eq.`. +// 2. `whereCurrent` tie read: the adapter's `supabaseQueryFn` emits it when +// `LoadSubsetOptions.cursor` is set, paired with the `gt`/`lt` keyset read. +// It is ordered and unlimited (`select=*&order=...&=eq.`) so every +// row tied at the boundary loads even when the tie class exceeds the page. +// In the window path these overlap: the boundary probe already pulls the full +// tie class before the `whereCurrent` read runs, so the tie class is fetched +// twice. The adapter must still emit `whereCurrent` — it honors the cursor +// contract and cannot assume the boundary probe ran (`loadBoundary` skips when +// the boundary value is unchanged, falls back to a full-source load for +// non-keyset orders, and never runs for `loadSubset({ cursor })` calls outside +// the window path). Collapsing the duplication is core's call, not the adapter's. + +const itemsSchema = z.object({ id: z.number(), rank: z.number() }) + +// rank has a tie class (20) spanning ids 2–4 that straddles the first page. +const FIXTURE = [ + { id: 1, rank: 10 }, + { id: 2, rank: 20 }, + { id: 3, rank: 20 }, + { id: 4, rank: 20 }, + { id: 5, rank: 30 }, + { id: 6, rank: 40 }, +] + +/** A Supabase-backed source collection over the paginating mock. */ +function makeCollection(mockFetch: ReturnType) { + return createCollection( + supabaseCollectionOptions({ + tableName: 'items', + keys: ['id'], + schema: itemsSchema, + supabase: createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }), + }), + ) +} + +/** Wrap a live query in a window controller with an active subscriber. */ +function windowController( + live: ReturnType, + cleanups: Array<() => void>, + pageSize: number, +) { + const controller = createLiveQueryWindowController(live, { pageSize }) + // A subscriber activates the window lease so pages actually load. + const unsub = controller.subscribe(() => {}) + cleanups.push(() => { + unsub() + controller.dispose() + live.cleanup() + }) + return controller +} + +const ids = (snapshot: { data: ReadonlyArray }) => + snapshot.data.map((row) => (row as { id: number }).id) + +describe('live infinite query (windowed) pagination', () => { + let collection: ReturnType + let mockFetch: ReturnType + const cleanups: Array<() => void> = [] + + beforeEach(() => { + mockFetch = makePaginatingFetch(FIXTURE) + collection = makeCollection(mockFetch) + cleanups.push(() => { + collection.cleanup() + }) + }) + + afterEach(() => { + for (const cleanup of cleanups.splice(0).reverse()) { + cleanup() + } + }) + + test('fetches a single page without a keyset cursor', async () => { + const live = createLiveQueryCollection((q) => + q + .from({ item: collection }) + .orderBy(({ item }) => item.id) + .limit(2), + ) + const controller = windowController(live, cleanups, 2) + + await controller.preload() + const snapshot = controller.getSnapshot() + // One committed page of `pageSize`, with more rows available. + expect(snapshot.pages.map((page) => page.map((row) => row.id))).toEqual([ + [1, 2], + ]) + expect(ids(snapshot)).toEqual([1, 2]) + expect(snapshot.hasNextPage).toBe(true) + + // The first page is a plain ordered window (one peek row past the page) + // plus core's boundary probe — no keyset cursor (`gt`) and no offset yet. + expect(getSearches(mockFetch)).toEqual([ + 'select=*&order=id.asc&limit=3', // window + 1 peek row + 'select=*&id=eq.3', // boundary probe (loadBoundary) settles the peek + ]) + }) + + test('grows the window with a keyset cursor and never an offset', async () => { + const live = createLiveQueryCollection((q) => + q + .from({ item: collection }) + .orderBy(({ item }) => item.id) + .limit(2), + ) + const controller = windowController(live, cleanups, 2) + + await controller.preload() + expect(ids(controller.getSnapshot())).toEqual([1, 2]) + + await controller.fetchNextPage() + // Page 1 rows are preserved and the result is a contiguous ordered prefix. + expect(ids(controller.getSnapshot())).toEqual([1, 2, 3, 4]) + + // The exact PostgREST reads the flow emits. The next page is a keyset + // request from the boundary (id 3): ordered, limited, and — crucially — + // with no offset re-skipping rows. No request carries an offset. + expect(getSearches(mockFetch)).toEqual([ + 'select=*&order=id.asc&limit=3', // page 1: window + 1 peek row + 'select=*&id=eq.3', // boundary probe (loadBoundary) settles the peek + 'select=*&order=id.asc&id=eq.3', // page 2: whereCurrent tie read + 'select=*&order=id.asc&limit=2&id=gt.3', // page 2: whereFrom keyset read + 'select=*&id=eq.5', // boundary probe for the next peek + ]) + }) + + test('fetches the full boundary tie class so no tied row is skipped', async () => { + const live = createLiveQueryCollection((q) => + q + .from({ item: collection }) + .orderBy(({ item }) => item.rank) + .limit(2), + ) + const controller = windowController(live, cleanups, 2) + + await controller.preload() + expect(ids(controller.getSnapshot())).toEqual([1, 2]) + + await controller.fetchNextPage() + const result = ids(controller.getSnapshot()) + // The whole rank-20 tie class (ids 2–4) is loaded even though id 4 sits + // beyond page 1's peek, so the window stays a contiguous ordered prefix + // with no gaps and no duplicates. + expect(result).toContain(4) + expect(result).toEqual([1, 2, 3, 4]) + expect(new Set(result).size).toBe(result.length) + + // Same boundary values (rank 20) exercise `whereCurrent`. This test locks + // the shape the adapter must emit: the tie read (3rd) keeps the order, + // filters to the boundary with `eq`, and has no limit; the keyset read (4th) + // advances strictly past the boundary with `gt`; neither carries an offset. + // (Here id 4 is in fact already loaded by the boundary probe — 2nd read, + // `rank=eq.20`, no order — which makes the `whereCurrent` read redundant in + // the window path; see the module note. The adapter emits it regardless + // because it honors the cursor contract.) + expect(getSearches(mockFetch)).toEqual([ + 'select=*&order=rank.asc&limit=3', // page 1: window + 1 peek row + 'select=*&rank=eq.20', // boundary probe (loadBoundary): full tie class + 'select=*&order=rank.asc&rank=eq.20', // page 2: whereCurrent tie read + 'select=*&order=rank.asc&limit=1&rank=gt.20', // page 2: whereFrom keyset read + 'select=*&rank=eq.30', // boundary probe for the next peek + ]) + }) +}) + +// A collection load with no windowing (a plain subscribe) +// issues a single `supabaseQueryFn` call that must return the FULL matching set, +// looping past PostgREST's `db-max-rows` cap instead of truncating at it. +describe('db-max-rows paging loop (supabaseQueryFn)', () => { + // Ordered fixture the capped mock pages through. + const ROWS = [{ id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }, { id: 5 }] + + const ORDER_BY = [ + { + expression: new IR.PropRef(['id']), + compareOptions: { direction: 'asc' as const, nulls: 'last' as const }, + }, + ] + + const prefer = (call: Array): string => + new Headers((call[1] as RequestInit | undefined)?.headers).get('prefer') ?? + '' + + const run = ( + mockFetch: ReturnType, + loadSubsetOptions: Record, + signal: AbortSignal = new AbortController().signal, + ) => { + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + return supabaseQueryFn(supabase, 'items', { + client: new QueryClient(), + queryKey: ['items'], + signal, + meta: { loadSubsetOptions } as never, + }) + } + + test('pages through the whole set when it exceeds the server cap', async () => { + const mockFetch = makePaginatingFetch(ROWS, { cap: 2 }) + const rows = await run(mockFetch, { orderBy: ORDER_BY }) + + // Every row returned exactly once, in order. + expect((rows as Array<{ id: number }>).map((r) => r.id)).toEqual([ + 1, 2, 3, 4, 5, + ]) + // The first request has no artificial page-size limit — the cap sizes it — + // and each later page advances the offset by the rows received, capped by + // the rows still owed (the last page asks for just 1). + expect(getSearches(mockFetch)).toEqual([ + 'select=*&order=id.asc', + 'select=*&order=id.asc&offset=2&limit=2', + 'select=*&order=id.asc&offset=4&limit=1', + ]) + }) + + test('requests count=exact on the first page only', async () => { + const mockFetch = makePaginatingFetch(ROWS, { cap: 2 }) + await run(mockFetch, { orderBy: ORDER_BY }) + + const prefers = mockFetch.mock.calls.map(prefer) + expect(prefers[0]).toContain('count=exact') + for (const p of prefers.slice(1)) { + expect(p).not.toContain('count=') + } + }) + + test('an exact multiple of the cap needs no trailing empty request', async () => { + const mockFetch = makePaginatingFetch(ROWS.slice(0, 4), { cap: 2 }) + const rows = await run(mockFetch, { orderBy: ORDER_BY }) + + expect((rows as Array<{ id: number }>).map((r) => r.id)).toEqual([ + 1, 2, 3, 4, + ]) + // Two requests, not three: the count tells the loop it is done at offset 4. + expect(getSearches(mockFetch)).toEqual([ + 'select=*&order=id.asc', + 'select=*&order=id.asc&offset=2&limit=2', + ]) + }) + + test('a caller offset counts against the total: no trailing empty request', async () => { + // Six rows, offset 2, cap 2: rows 3-4 then 5-6 — the count (6) minus the + // offset (2) tells the loop it is done after two requests, not three. + const SIX = [...ROWS, { id: 6 }] + const mockFetch = makePaginatingFetch(SIX, { cap: 2 }) + const rows = await run(mockFetch, { orderBy: ORDER_BY, offset: 2 }) + + expect((rows as Array<{ id: number }>).map((r) => r.id)).toEqual([ + 3, 4, 5, 6, + ]) + expect(getSearches(mockFetch)).toEqual([ + 'select=*&order=id.asc&offset=2', + 'select=*&order=id.asc&offset=4&limit=2', + ]) + }) + + test('a set within the cap is a single request', async () => { + const mockFetch = makePaginatingFetch(ROWS.slice(0, 2), { cap: 2 }) + const rows = await run(mockFetch, { orderBy: ORDER_BY }) + + expect((rows as Array<{ id: number }>).map((r) => r.id)).toEqual([1, 2]) + expect(getSearches(mockFetch)).toEqual(['select=*&order=id.asc']) + }) + + test('the loop owns limit: a caller limit above the cap still pages', async () => { + const mockFetch = makePaginatingFetch(ROWS, { cap: 2 }) + const rows = await run(mockFetch, { orderBy: ORDER_BY, limit: 3 }) + + // Exactly the caller's 3 rows, fetched across cap-sized pages. + expect((rows as Array<{ id: number }>).map((r) => r.id)).toEqual([1, 2, 3]) + expect(getSearches(mockFetch)).toEqual([ + 'select=*&order=id.asc&limit=3', + 'select=*&order=id.asc&limit=1&offset=2', + ]) + }) + + describe('rows tied on the requested order', () => { + type TiedRow = { id: number; rank: number } + + // Every request orders the tied rows differently, like Postgres may when a + // top-N sort runs with a different limit and offset. Only an order that + // also sorts by the unique `id` pins one position per row. + const makeTieShufflingFetch = (fixture: Array, cap: number) => { + let requestCount = 0 + return vi.fn().mockImplementation((input) => { + requestCount += 1 + const params = new URL(String(input)).searchParams + const columns = (params.get('order') ?? '') + .split(',') + .filter(Boolean) + .map((sort) => sort.split('.')[0] as keyof TiedRow) + const arrival = + requestCount % 2 === 0 ? [...fixture].reverse() : [...fixture] + const rows = arrival.sort((a, b) => { + for (const column of columns) { + if (a[column] !== b[column]) return a[column] - b[column] + } + return 0 + }) + const offset = Number(params.get('offset') ?? 0) + const page = rows.slice(offset, offset + cap) + return Promise.resolve( + new Response(JSON.stringify(page), { + status: 200, + headers: { + 'content-type': 'application/json', + 'content-range': `${offset}-${offset + page.length - 1}/${rows.length}`, + }, + }), + ) + }) + } + + const TIED: Array = [ + { id: 1, rank: 1 }, + { id: 2, rank: 1 }, + { id: 3, rank: 1 }, + { id: 4, rank: 1 }, + { id: 5, rank: 2 }, + { id: 6, rank: 2 }, + ] + const RANK_ORDER = [ + { + expression: new IR.PropRef(['rank']), + compareOptions: { direction: 'asc' as const, nulls: 'last' as const }, + }, + ] + + const readTied = ( + mockFetch: ReturnType, + keys: Array, + loadSubsetOptions: Record = { orderBy: RANK_ORDER }, + ) => + supabaseQueryFn( + createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }), + 'items', + { + client: new QueryClient(), + queryKey: ['items'], + signal: new AbortController().signal, + meta: { loadSubsetOptions } as never, + }, + { keys }, + ) + + test('without key order the shuffled pages repeat and skip rows', async () => { + // Control for the model below: with no key to order by, the reads this + // mock serves are exactly the unstable ones the key order exists to fix. + const rows = await readTied(makeTieShufflingFetch(TIED, 2), []) + + expect(new Set(rows.map((row) => row.id)).size).toBeLessThan(TIED.length) + }) + + test('pages ordered by the key return each tied row exactly once', async () => { + const rows = await readTied(makeTieShufflingFetch(TIED, 2), ['id']) + + expect(rows.map((row) => row.id).sort()).toEqual([1, 2, 3, 4, 5, 6]) + }) + + test('the first page is read again under the key order when more pages follow', async () => { + const mockFetch = makeTieShufflingFetch(TIED, 2) + await readTied(mockFetch, ['id']) + + expect(getSearches(mockFetch)).toEqual([ + 'select=*&order=rank.asc', + 'select=*&order=rank.asc,id.asc&offset=0&limit=2', + 'select=*&order=rank.asc,id.asc&offset=2&limit=2', + 'select=*&order=rank.asc,id.asc&offset=4&limit=2', + ]) + }) + + test('an unordered read is paged in key order', async () => { + const mockFetch = makeTieShufflingFetch(TIED, 2) + const rows = await readTied(mockFetch, ['id'], {}) + + expect(rows.map((row) => row.id).sort()).toEqual([1, 2, 3, 4, 5, 6]) + expect(getSearches(mockFetch).slice(1)).toEqual([ + 'select=*&order=id.asc&offset=0&limit=2', + 'select=*&order=id.asc&offset=2&limit=2', + 'select=*&order=id.asc&offset=4&limit=2', + ]) + }) + + test('every key column missing from the order is appended', async () => { + const mockFetch = makeTieShufflingFetch(TIED, 2) + await readTied(mockFetch, ['rank', 'id']) + + // `rank` is already sorted by, so only `id` is added. + expect(getSearches(mockFetch)[1]).toBe( + 'select=*&order=rank.asc,id.asc&offset=0&limit=2', + ) + }) + + test('a set within one page is read once, as asked', async () => { + const mockFetch = makeTieShufflingFetch(TIED.slice(0, 2), 2) + await readTied(mockFetch, ['id']) + + expect(getSearches(mockFetch)).toEqual(['select=*&order=rank.asc']) + }) + }) + + test('limit: 0 returns an empty set with zero requests', async () => { + const mockFetch = makePaginatingFetch(ROWS, { cap: 2 }) + const rows = await run(mockFetch, { orderBy: ORDER_BY, limit: 0 }) + + expect(rows).toEqual([]) + expect(mockFetch).not.toHaveBeenCalled() + }) + + test('threads the abort signal to every request', async () => { + const mockFetch = makePaginatingFetch(ROWS, { cap: 2 }) + const signal = new AbortController().signal + await run(mockFetch, { orderBy: ORDER_BY }, signal) + + expect(mockFetch.mock.calls.length).toBeGreaterThan(1) + for (const call of mockFetch.mock.calls) { + expect((call[1] as RequestInit).signal).toBe(signal) + } + }) + + test('one failed page fails the whole load (no partial data)', async () => { + let calls = 0 + const failingFetch = vi.fn().mockImplementation(() => { + calls += 1 + if (calls === 1) { + return Promise.resolve( + new Response(JSON.stringify([{ id: 1 }, { id: 2 }]), { + status: 200, + headers: { + 'content-type': 'application/json', + 'content-range': '0-1/5', + }, + }), + ) + } + return Promise.resolve( + new Response(JSON.stringify({ message: 'boom' }), { + status: 500, + headers: { 'content-type': 'application/json' }, + }), + ) + }) + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: failingFetch }, + }) + + await expect( + supabaseQueryFn(supabase, 'items', { + client: new QueryClient(), + queryKey: ['items'], + signal: new AbortController().signal, + meta: { loadSubsetOptions: { orderBy: ORDER_BY } } as never, + }), + ).rejects.toBeDefined() + }) +}) diff --git a/packages/supabase-db-collection/tests/pagination.utils.ts b/packages/supabase-db-collection/tests/pagination.utils.ts new file mode 100644 index 0000000000..7626e540dd --- /dev/null +++ b/packages/supabase-db-collection/tests/pagination.utils.ts @@ -0,0 +1,123 @@ +import { vi } from 'vitest' + +type Row = Record + +const COMPARATORS: Record boolean> = { + gt: (a, b) => a > b, + gte: (a, b) => a >= b, + lt: (a, b) => a < b, + lte: (a, b) => a <= b, + eq: (a, b) => a === b, +} + +// Parses `in.(1,2,3)`'s value half (`(1,2,3)`) into its member list. Numeric +// ids are all the split-chunk tests need, so members are compared as numbers. +function parseInList(value: string): Array { + const inner = value.replace(/^\(/, '').replace(/\)$/, '') + return inner === '' ? [] : inner.split(',').map(Number) +} + +/** + * A mock `fetch` that serves a fixture like PostgREST would for the read paths + * the pagination adapter emits: single-column `order`, `limit`, `offset`, and + * `col=op.value` scalar filters (`gt`/`gte`/`lt`/`lte`/`eq`/`in`). Non-GET + * requests echo their body back so inserts/updates parse. + * + * `cap` simulates PostgREST's `db-max-rows`: no response ever returns more than + * `cap` rows, even when a larger `limit` is requested, while the Content-Range + * count still reports the true total — exactly the condition the paging loop + * exists to handle. + */ +export function makePaginatingFetch( + fixture: Array, + { cap }: { cap?: number } = {}, +) { + const columns = Object.keys(fixture[0] ?? {}) + return vi.fn().mockImplementation((input, init) => { + const method = init?.method ?? 'GET' + if (method !== 'GET') { + const body = init?.body ? JSON.parse(init.body as string) : {} + return Promise.resolve(json(body)) + } + + const params = new URL(String(input)).searchParams + let rows = [...fixture] + + for (const column of columns) { + for (const raw of params.getAll(column)) { + const [op = '', value = ''] = raw.split(/\.(.*)/s) + if (op === 'in') { + const members = new Set(parseInList(value)) + rows = rows.filter((r) => members.has(Number(r[column]))) + continue + } + const compare = COMPARATORS[op] + if (compare) { + const target = Number(value) + rows = rows.filter((r) => compare(Number(r[column]), target)) + } + } + } + + const order = params.get('order') + if (order) { + const [column = '', direction] = (order.split(',')[0] ?? '').split('.') + const sign = direction === 'desc' ? -1 : 1 + rows.sort((a, b) => (Number(a[column]) - Number(b[column])) * sign) + } + + // The total matching set before paging — what PostgREST reports in the + // Content-Range header when `count=exact` is requested. + const total = rows.length + const offset = params.get('offset') ? Number(params.get('offset')) : 0 + const limit = params.get('limit') + const requested = limit === null ? undefined : offset + Number(limit) + const upperBound = + cap === undefined + ? requested + : Math.min(requested ?? offset + cap, offset + cap) + rows = rows.slice(offset, upperBound) + const end = offset + rows.length - 1 + const contentRange = rows.length + ? `${offset}-${end}/${total}` + : `*/${total}` + return Promise.resolve(json(rows, contentRange)) + }) +} + +function json(body: unknown, contentRange?: string): Response { + const headers: Record = { + 'content-type': 'application/json', + } + if (contentRange !== undefined) { + headers['content-range'] = contentRange + } + return new Response(JSON.stringify(body), { status: 200, headers }) +} + +/** + * The decoded query strings of every GET the mock captured, in order, with the + * leading `?` stripped (e.g. `select=*&order=id.asc&limit=2&id=gt.3`). + */ +export function getSearches( + mockFetch: ReturnType, +): Array { + return mockFetch.mock.calls + .filter((call) => (call[1]?.method ?? 'GET') === 'GET') + .map((call) => + decodeURIComponent(new URL(String(call[0])).search).replace(/^\?/, ''), + ) +} + +/** + * The rendered (percent-encoded) URL of every GET the mock captured, in + * order — what actually crosses the wire, and so what a request-line budget + * is measured against. + */ +export function getRawUrls( + mockFetch: ReturnType, +): Array { + return mockFetch.mock.calls + .filter((call) => (call[1]?.method ?? 'GET') === 'GET') + .map((call) => String(call[0])) +} diff --git a/packages/supabase-db-collection/tests/postgrest-filters.test.ts b/packages/supabase-db-collection/tests/postgrest-filters.test.ts new file mode 100644 index 0000000000..ffe80b0491 --- /dev/null +++ b/packages/supabase-db-collection/tests/postgrest-filters.test.ts @@ -0,0 +1,513 @@ +import { + IR, + and, + eq, + gt, + gte, + ilike, + inArray, + isNull, + like, + lt, + lte, + not, + or, + upper, +} from '@tanstack/db' +import { describe, expect, test } from 'vitest' +import { subsetOptionsToQueryKey } from '../src/functions' +import { + cursorCurrentToSearch, + keyColumnsToSearch, + loadSubsetOptionsToSearch, + realtimeFiltersToSearch, + subsetParamsToSearch, +} from '../src/postgrest-filters' + +// A bare (unaliased) column ref, as the live subset loader receives them. +const col = (name: string) => new IR.PropRef([name]) + +const name = col('name') +const id = col('id') +const active = col('active') + +// A single orderBy clause, as LoadSubsetOptions carries them. +const sort = (ref: IR.PropRef, direction: 'asc' | 'desc') => ({ + expression: ref, + compareOptions: { direction, nulls: 'last' as const }, +}) + +// Each active query becomes one `filter` entry: its AND-ed conditions, +// comma-joined into Realtime's wire form. An empty result is the catch-all. +const realtimeEntries = (...where: Array>) => + realtimeFiltersToSearch(where).getAll('filter') + +describe('realtimeFiltersToSearch', () => { + test('builds decoded filter strings for supported comparisons', () => { + expect(realtimeEntries(eq(id, 1))).toEqual(['id=eq.1']) + // Shares the PostgREST renderer, so negated equality is `not.eq`, not `neq`. + expect(realtimeEntries(not(eq(active, false)))).toEqual([ + 'active=not.eq.false', + ]) + expect(realtimeEntries(isNull(name))).toEqual(['name=is.null']) + expect(realtimeEntries(inArray(id, [1, 2, 3]))).toEqual(['id=in.(1,2,3)']) + }) + + test('sorts and deduplicates AND conditions and active-query filters', () => { + const filter = and(gt(id, 5), eq(active, true), eq(active, true)) + const equivalent = and(eq(active, true), gt(id, 5)) + expect(realtimeEntries(filter, equivalent)).toEqual([ + 'active=eq.true,id=gt.5', + ]) + }) + + test('quotes reserved characters without URL-encoding the decoded value', () => { + expect(realtimeEntries(eq(name, 'Doe, Jane'))).toEqual([ + 'name=eq."Doe, Jane"', + ]) + }) + + // Shares PostgREST's quoteValue, so quoting matches the request path: reserved + // characters, surrounding whitespace, and the empty string are all quoted. + test.each([ + ['', '""'], + [' a ', '" a "'], + ['a"b\\c', '"a\\"b\\\\c"'], + ])('quotes value %j like the PostgREST request path', (value, quoted) => { + expect(realtimeEntries(eq(name, value))).toEqual([`name=eq.${quoted}`]) + // A single-member IN renders as an equality via the shared renderer, so the + // empty string collapses to `eq.""` rather than `in.("")`. + const inExpected = + value === '' ? `name=eq.${quoted}` : `name=in.(${quoted})` + expect(realtimeEntries(inArray(name, [value]))).toEqual([inExpected]) + }) + + test('serializes bigints and Dates', () => { + const when = new Date('2020-01-02T03:04:05.000Z') + expect(realtimeEntries(eq(id, 9_007_199_254_740_993n))).toEqual([ + 'id=eq.9007199254740993', + ]) + expect(realtimeEntries(eq(name, when))).toEqual([ + 'name=eq.2020-01-02T03:04:05.000Z', + ]) + // A non-finite number renders as `eq.Infinity`: the shared renderer no longer + // rejects it locally, so the server does (and the swap falls back to + // catch-all). Correctness is unaffected; only the fallback path differs. + expect(realtimeEntries(eq(id, Number.POSITIVE_INFINITY))).toEqual([ + 'id=eq.Infinity', + ]) + }) + + test('uses empty parameters as the catch-all for unsupported filters', () => { + expect(realtimeEntries()).toEqual([]) + expect(realtimeEntries(inArray(id, []))).toEqual([]) + expect(realtimeEntries(or(eq(id, 1), eq(id, 2)))).toEqual([]) + }) +}) + +// ── subsetParamsToSearch ──────────────────────────────────────────── +// Most tests here exercise the WHERE quoting/negation/IN/null/wildcard logic, +// which lives in a single internal translator shared by every builder; +// subsetParamsToSearch is its thinnest public wrapper. +describe('subsetParamsToSearch', () => { + const filters = (where: IR.BasicExpression) => + subsetParamsToSearch({ where }) + + test.each([ + [eq(id, 1), 'eq.1'], + [gt(id, 1), 'gt.1'], + [gte(id, 1), 'gte.1'], + [lt(id, 1), 'lt.1'], + [lte(id, 1), 'lte.1'], + [isNull(id), 'is.null'], + [inArray(id, [1, 2, 3]), 'in.(1,2,3)'], + ])('renders comparison operators: %s', (where, expected) => { + expect(filters(where).get('id')).toBe(expected) + }) + + test('leaves top-level scalar values raw (unquoted)', () => { + expect(filters(eq(name, 'a,b(c)')).get('name')).toBe('eq.a,b(c)') + }) + + test('preserves AND branches inside OR', () => { + expect( + filters(or(and(eq(active, true), gt(id, 1)), eq(name, 'Bob'))).get('or'), + ).toBe('(and(active.eq.true,id.gt.1),name.eq.Bob)') + }) + + test.each([and, or])('negates logical groups', (logical) => { + expect( + filters(not(logical(eq(active, true), eq(name, 'Bob')))).get('or'), + ).toBe( + logical === and + ? '(active.not.eq.true,name.not.eq.Bob)' + : '(and(active.not.eq.true,name.not.eq.Bob))', + ) + }) + + test('supports double negation of comparisons and logical groups', () => { + expect(filters(not(not(eq(name, 'Alice')))).get('name')).toBe('eq.Alice') + expect(filters(not(not(or(eq(name, 'Alice'), eq(id, 2))))).get('or')).toBe( + '(name.eq.Alice,id.eq.2)', + ) + }) + + test('preserves multiple OR parameters under AND', () => { + expect( + filters( + and(or(eq(id, 1), eq(id, 2)), or(eq(name, 'Alice'), eq(name, 'Bob'))), + ).getAll('or'), + ).toEqual(['(id.eq.1,id.eq.2)', '(name.eq.Alice,name.eq.Bob)']) + }) + + test.each([ + ['', '""'], + [' a ', '" a "'], + ['a,b(c)', '"a,b(c)"'], + ['a"b\\c', '"a\\"b\\\\c"'], + ['a.b:c&d=1+%', 'a.b:c&d=1+%'], + ])('quotes logical values and IN members: %j', (value, quoted) => { + expect(filters(or(eq(name, value), eq(id, 2))).get('or')).toBe( + `(name.eq.${quoted},id.eq.2)`, + ) + expect(filters(inArray(name, [value, value])).get('name')).toBe( + value === '' ? 'eq.' : `in.(${quoted})`, + ) + expect(filters(not(inArray(name, [value]))).get('name')).toBe( + value === '' ? 'not.eq.' : `not.in.(${quoted})`, + ) + }) + + test('renders negated comparisons inside OR', () => { + expect( + filters(or(not(isNull(name)), not(inArray(name, ['a,b', 'c'])))).get( + 'or', + ), + ).toBe('(name.not.is.null,name.not.in.("a,b",c))') + }) + + test('does not union IN constraints inside logical groups', () => { + expect( + filters( + or(and(inArray(id, [1, 2]), inArray(id, [2, 3])), eq(active, true)), + ).get('or'), + ).toBe('(and(id.in.(1,2),id.in.(2,3)),active.eq.true)') + }) + + test('renders empty IN lists with SQL null semantics', () => { + expect(filters(inArray(id, [])).get('id')).toBe('in.()') + expect(filters(not(inArray(id, []))).get('id')).toBe('not.is.null') + expect(filters(not(not(inArray(id, [])))).get('id')).toBe('in.()') + }) + + test('preserves null guards for empty IN inside a negated logical group', () => { + expect( + filters(not(and(inArray(name, []), eq(active, true)))).get('or'), + ).toBe('(name.not.is.null,active.not.eq.true)') + }) + + test('ignores null list members instead of matching literal null strings', () => { + expect(filters(inArray(name, ['Alice', null])).get('name')).toBe( + 'in.(Alice)', + ) + expect(filters(not(inArray(name, ['Alice', null]))).get('name')).toBe( + 'not.in.(Alice)', + ) + expect(filters(not(inArray(name, [null]))).get('name')).toBe('not.is.null') + }) + + test.each([like, ilike])( + 'preserves SQL wildcards and literal backslashes', + (match) => { + const op = match === like ? 'like' : 'ilike' + expect(filters(match(name, 'A_%')).get('name')).toBe(`${op}.A_%`) + expect(filters(not(match(name, 'a\\%'))).get('name')).toBe( + `not.${op}.a\\\\%`, + ) + }, + ) + + test.each([ + ['computed OR', or(eq(active, true), eq(upper(name), 'ALICE'))], + ['computed NOT AND', not(and(eq(active, true), eq(upper(name), 'ALICE')))], + ['literal asterisk', like(name, '*Ali*')], + ['negated literal asterisk', not(ilike(name, '*Ali*'))], + ])('drops unpushable %s, keeping the rest', (_, where) => { + expect([...filters(and(gt(id, 0), where))]).toEqual([['id', 'gt.0']]) + }) + + test('appends a single order direction', () => { + expect( + subsetParamsToSearch({ orderBy: [sort(id, 'asc')] }).get('order'), + ).toBe('id.asc') + expect( + subsetParamsToSearch({ orderBy: [sort(id, 'desc')] }).get('order'), + ).toBe('id.desc') + }) + + test('merges multiple order columns into one comma-joined value', () => { + const search = subsetParamsToSearch({ + orderBy: [sort(id, 'asc'), sort(name, 'desc')], + }) + expect(search.get('order')).toBe('id.asc,name.desc') + expect(search.getAll('order')).toHaveLength(1) + }) + + test('appends limit', () => { + expect(subsetParamsToSearch({ limit: 10 }).get('limit')).toBe('10') + }) + + test('merges duplicate top-level IN demands without mutating the input', () => { + const where = and(inArray(id, [1, 2]), inArray(id, [2, 3])) + const before = JSON.stringify(where) + expect(subsetParamsToSearch({ where }).getAll('id')).toEqual(['in.(1,2,3)']) + expect(JSON.stringify(where)).toBe(before) + }) + + test('excludes select, offset, and cursor (pagination/request details)', () => { + const search = subsetParamsToSearch({ + where: eq(id, 1), + limit: 5, + offset: 99, + cursor: { whereFrom: gt(id, 1), whereCurrent: eq(id, 1) }, + }) + expect(search.get('id')).toBe('eq.1') + expect(search.get('limit')).toBe('5') + expect(search.has('select')).toBe(false) + expect(search.has('offset')).toBe(false) + // The cursor's `gt(id, 1)` must not leak in as an id filter. + expect(search.getAll('id')).toEqual(['eq.1']) + }) +}) + +// ── loadSubsetOptionsToSearch ─────────────────────────────────────── +describe('loadSubsetOptionsToSearch', () => { + test('always requests all columns', () => { + expect(loadSubsetOptionsToSearch({}).get('select')).toBe('*') + }) + + test('empty options produce only select=*', () => { + expect([...loadSubsetOptionsToSearch({})]).toEqual([['select', '*']]) + }) + + test('includes where, order and limit from the subset params', () => { + const search = loadSubsetOptionsToSearch({ + where: eq(id, 1), + orderBy: [sort(id, 'asc')], + limit: 5, + }) + expect(search.get('id')).toBe('eq.1') + expect(search.get('order')).toBe('id.asc') + expect(search.get('limit')).toBe('5') + }) + + test('appends offset independently of limit', () => { + const search = loadSubsetOptionsToSearch({ offset: 20 }) + expect(search.get('offset')).toBe('20') + expect(search.has('limit')).toBe(false) + }) + + test('appends cursor filters: quotes IN members, leaves scalars raw', () => { + const search = loadSubsetOptionsToSearch({ + cursor: { + whereFrom: and(inArray(name, ['a,b', 'c']), gt(id, 5)), + whereCurrent: eq(id, 5), + }, + }) + expect(search.get('name')).toBe('in.("a,b",c)') + expect(search.get('id')).toBe('gt.5') + }) + + test('honours the cursor and skips offset when both are present', () => { + const search = loadSubsetOptionsToSearch({ + orderBy: [sort(id, 'asc')], + limit: 20, + offset: 20, + cursor: { whereFrom: gt(id, 40), whereCurrent: eq(id, 40) }, + }) + expect(search.get('id')).toBe('gt.40') + expect(search.get('limit')).toBe('20') + expect(search.has('offset')).toBe(false) + }) + + test('renders a composite multi-column cursor without throwing', () => { + const a = col('a') + const b = col('b') + const build = () => + loadSubsetOptionsToSearch({ + orderBy: [sort(a, 'asc'), sort(b, 'asc')], + limit: 20, + cursor: { + whereFrom: or(gt(a, 1), and(eq(a, 1), gt(b, 2))), + whereCurrent: eq(a, 1), + }, + }) + expect(build).not.toThrow() + expect(build().get('or')).toBe('(a.gt.1,and(a.eq.1,b.gt.2))') + }) + + test('serialises a Date cursor boundary as ISO 8601', () => { + const createdAt = col('created_at') + const boundary = new Date('2024-01-01T00:00:00.000Z') + const search = loadSubsetOptionsToSearch({ + orderBy: [sort(createdAt, 'asc')], + limit: 20, + cursor: { + whereFrom: gt(createdAt, boundary), + whereCurrent: eq(createdAt, boundary), + }, + }) + expect(search.get('created_at')).toBe('gt.2024-01-01T00:00:00.000Z') + }) +}) + +// ── cursorCurrentToSearch ─────────────────────────────────────────── +describe('cursorCurrentToSearch', () => { + test('returns null without a cursor', () => { + expect(cursorCurrentToSearch({ where: eq(id, 1) })).toBeNull() + }) + + test('renders where + order + whereCurrent, never limit', () => { + const search = cursorCurrentToSearch({ + where: eq(active, true), + orderBy: [sort(id, 'asc')], + limit: 20, + cursor: { whereFrom: gt(id, 40), whereCurrent: eq(id, 40) }, + }) + expect(search?.get('active')).toBe('eq.true') + expect(search?.get('order')).toBe('id.asc') + expect(search?.get('id')).toBe('eq.40') + expect(search?.has('limit')).toBe(false) + }) +}) + +// ── keyColumnsToSearch ────────────────────────────────────────────── +describe('keyColumnsToSearch', () => { + test('serializes Date keys as ISO timestamps', () => { + const timestamp = new Date('2024-01-01T12:30:00.123Z') + const search = keyColumnsToSearch(['recorded_at'], { + recorded_at: timestamp, + }) + + expect(search.get('recorded_at')).toBe('eq.2024-01-01T12:30:00.123Z') + }) + + test('serializes Date values in composite keys without changing other keys', () => { + const search = keyColumnsToSearch(['sensor_id', 'recorded_at'], { + sensor_id: 'east,1', + recorded_at: new Date('2024-01-01T14:30:00.123+02:00'), + }) + + expect([...search]).toEqual([ + ['sensor_id', 'eq.east,1'], + ['recorded_at', 'eq.2024-01-01T12:30:00.123Z'], + ]) + }) + + test('builds an eq filter for a single key column', () => { + expect(keyColumnsToSearch(['id'], { id: 1, name: 'x' }).get('id')).toBe( + 'eq.1', + ) + }) + + test('builds one eq filter per composite key, preserving order', () => { + const search = keyColumnsToSearch(['user_id', 'todo_id'], { + user_id: 1, + todo_id: 2, + title: 'ignored', + }) + expect(search.get('user_id')).toBe('eq.1') + expect(search.get('todo_id')).toBe('eq.2') + expect([...search.keys()]).toEqual(['user_id', 'todo_id']) + }) +}) + +// ── subsetOptionsToQueryKey ───────────────────────────────────────── +describe('subsetOptionsToQueryKey', () => { + const key = (where: IR.BasicExpression) => + subsetOptionsToQueryKey('users', { where }) + + test('collapses to [tableName] when nothing is pushable', () => { + expect(key(or(eq(name, 'Alice'), eq(upper(name), 'BOB')))).toEqual([ + 'users', + ]) + }) + + test('literal query delimiters cannot collide with extra filters', () => { + expect(key(eq(name, 'Alice&active=eq.true'))).not.toEqual( + key(and(eq(name, 'Alice'), eq(active, true))), + ) + }) + + test('distinguishes NOT, OR branches, and IN list boundaries', () => { + expect(key(eq(name, 'Alice'))).not.toEqual(key(not(eq(name, 'Alice')))) + expect(key(or(eq(name, 'Alice'), eq(active, true)))).not.toEqual( + key(or(eq(name, 'Bob'), eq(active, true))), + ) + expect(key(inArray(name, ['a,b', 'c']))).not.toEqual( + key(inArray(name, ['a', 'b,c'])), + ) + }) + + test('uses the merged IN request', () => { + expect( + key(and(inArray(name, ['a', 'b']), inArray(name, ['b', 'c']))), + ).toEqual(key(inArray(name, ['a', 'b', 'c']))) + }) + + test('gives distinct cursor windows of one subset distinct keys', () => { + const base = { orderBy: [sort(id, 'asc')], limit: 20 } + const page2 = subsetOptionsToQueryKey('users', { + ...base, + cursor: { whereFrom: gt(id, 20), whereCurrent: eq(id, 20) }, + }) + const page3 = subsetOptionsToQueryKey('users', { + ...base, + cursor: { whereFrom: gt(id, 40), whereCurrent: eq(id, 40) }, + }) + expect(page2).not.toEqual(page3) + // The prefix stays `[tableName]` so realtime keeps matching every window. + expect(page2[0]).toBe('users') + expect(page3[0]).toBe('users') + }) + + test('gives distinct offset windows of one subset distinct keys', () => { + const base = { orderBy: [sort(id, 'asc')], limit: 20 } + expect( + subsetOptionsToQueryKey('users', { ...base, offset: 20 }), + ).not.toEqual(subsetOptionsToQueryKey('users', { ...base, offset: 40 })) + }) + + test('gives distinct multi-column cursor windows distinct keys', () => { + const a = col('a') + const b = col('b') + const base = { orderBy: [sort(a, 'asc'), sort(b, 'asc')], limit: 20 } + const page2 = subsetOptionsToQueryKey('users', { + ...base, + cursor: { + whereFrom: or(gt(a, 1), and(eq(a, 1), gt(b, 2))), + whereCurrent: eq(a, 1), + }, + }) + const page3 = subsetOptionsToQueryKey('users', { + ...base, + cursor: { + whereFrom: or(gt(a, 3), and(eq(a, 3), gt(b, 4))), + whereCurrent: eq(a, 3), + }, + }) + expect(page2).not.toEqual(page3) + expect(page2[0]).toBe('users') + expect(page3[0]).toBe('users') + }) + + test('keeps limit: 0 distinct from an unlimited subset', () => { + const zero = subsetOptionsToQueryKey('users', { + where: eq(id, 1), + limit: 0, + }) + const unlimited = subsetOptionsToQueryKey('users', { where: eq(id, 1) }) + expect(zero).not.toEqual(unlimited) + expect(new URLSearchParams(zero[1]).get('limit')).toBe('0') + }) +}) diff --git a/packages/supabase-db-collection/tests/postgrest-request.test.ts b/packages/supabase-db-collection/tests/postgrest-request.test.ts new file mode 100644 index 0000000000..6a538b5038 --- /dev/null +++ b/packages/supabase-db-collection/tests/postgrest-request.test.ts @@ -0,0 +1,122 @@ +import { PostgrestError } from '@supabase/postgrest-js' +import { createClient } from '@supabase/supabase-js' +import { IR, and, eq, gt } from '@tanstack/db' +import { QueryClient } from '@tanstack/query-core' +import { describe, expect, test, vi } from 'vitest' +import { subsetOptionsToQueryKey, supabaseQueryFn } from '../src/functions' +import { postgrestRequest } from '../src/postgrest-request' +import { SUPABASE_KEY, SUPABASE_URL, createMockFetch } from './test.utils' + +describe('request-state escape hatch', () => { + // supabase-js changing these fields would silently drop auth; fail loudly. + test('supabase.from(table) exposes url, headers, and fetch', () => { + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY) + const qb = supabase.from('users') + expect(qb.url).toBeInstanceOf(URL) + expect(qb.url.toString()).toBe(`${SUPABASE_URL}/rest/v1/users`) + expect(qb.headers).toBeInstanceOf(Headers) + expect(typeof qb.fetch).toBe('function') + }) +}) + +describe('query key matches request URL', () => { + test('the cache key encodes the same filters as the sent request', async () => { + const name = new IR.PropRef(['name']) + const id = new IR.PropRef(['id']) + const where = and(eq(name, 'Alice&x=1'), gt(id, 3)) + + const [, keyString] = subsetOptionsToQueryKey('users', { where }) + + const mockFetch = createMockFetch() + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + await supabaseQueryFn(supabase, 'users', { + client: new QueryClient(), + queryKey: ['users'], + signal: new AbortController().signal, + meta: { loadSubsetOptions: { where } }, + }) + const sent = new URL(String(mockFetch.mock.calls[0]?.[0])).searchParams + sent.delete('select') + // Every filter param in the key is present verbatim in the request. + for (const [key, value] of new URLSearchParams(keyString)) { + expect(sent.getAll(key)).toContain(value) + } + }) +}) + +describe('cursor pagination fetches boundary ties', () => { + test('a cursor load issues an unlimited tie request and a limited keyset request', async () => { + const id = new IR.PropRef(['id']) + const mockFetch = createMockFetch() + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + + await supabaseQueryFn(supabase, 'users', { + client: new QueryClient(), + queryKey: ['users'], + signal: new AbortController().signal, + meta: { + loadSubsetOptions: { + orderBy: [ + { + expression: id, + compareOptions: { direction: 'asc', nulls: 'last' }, + }, + ], + limit: 20, + cursor: { whereFrom: gt(id, 40), whereCurrent: eq(id, 40) }, + }, + }, + }) + + expect(mockFetch).toHaveBeenCalledTimes(2) + const urls = mockFetch.mock.calls.map( + (call: Array) => new URL(String(call[0])).searchParams, + ) + const ties = urls.find((s) => s.get('id') === 'eq.40') + const keyset = urls.find((s) => s.get('id') === 'gt.40') + + expect(ties?.has('limit')).toBe(false) + expect(keyset?.get('limit')).toBe('20') + // Cursor pins the window; offset must never ride alongside it. + expect(keyset?.has('offset')).toBe(false) + }) +}) + +describe('postgrest errors are thrown as Error instances', () => { + test('a failed request throws a PostgrestError with the message preserved', async () => { + const errorBody = { + message: 'permission denied for table users', + details: 'insufficient privilege', + hint: null, + code: '42501', + } + const mockFetch = vi.fn().mockResolvedValue( + new Response(JSON.stringify(errorBody), { + status: 403, + headers: { 'content-type': 'application/json' }, + }), + ) + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + + const promise = postgrestRequest(supabase, 'users', { + method: 'GET', + search: new URLSearchParams(), + }) + + await expect(promise).rejects.toBeInstanceOf(PostgrestError) + await expect(promise).rejects.toMatchObject({ + message: 'permission denied for table users', + code: '42501', + }) + // The original bug: throwing a plain object stringified to "[object Object]". + await expect(promise).rejects.toSatisfy((e: unknown) => + String(e).includes('permission denied'), + ) + }) +}) diff --git a/packages/supabase-db-collection/tests/realtime.test.ts b/packages/supabase-db-collection/tests/realtime.test.ts new file mode 100644 index 0000000000..2ad6361798 --- /dev/null +++ b/packages/supabase-db-collection/tests/realtime.test.ts @@ -0,0 +1,787 @@ +import { + and, + createCollection, + eq, + gt, + gte, + inArray, + isNull, + liveQueryCollectionOptions, + lt, + lte, + not, +} from '@tanstack/db' +import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest' +import { realtimeFiltersToSearch } from '../src/postgrest-filters' +import { + createMockChannel, + createMockFetch, + createRealtimeUsersCollection, + emit, + filtersFor, + listenersFor, + nth, +} from './test.utils' +import type { Collection } from '@tanstack/db' +import type { MockChannel } from './test.utils' + +// Collections created during a test, torn down afterwards so their query +// observers are removed (and the realtime channel detached). +let createdCollections: Array> = [] + +function track>(collection: T): T { + createdCollections.push(collection) + return collection +} + +beforeEach(() => { + createdCollections = [] +}) + +afterEach(() => { + // Tear down in reverse creation order so dependent live queries are cleaned + // up before the source collections they depend on. + for (const collection of [...createdCollections].reverse()) { + collection.cleanup() + } +}) + +type QueryFn = Parameters[0]['query'] +type RealtimeCollection = ReturnType< + typeof createRealtimeUsersCollection +>['collection'] + +function startLiveQuery( + collection: RealtimeCollection, + buildQuery: (collection: RealtimeCollection) => QueryFn, +) { + const opts = liveQueryCollectionOptions({ query: buildQuery(collection) }) + return track( + createCollection(opts as Extract), + ) +} + +// Runs a live query against a fresh realtime users collection and waits for the +// realtime channel to be attached, then returns the recording mock channel. +async function captureChannel( + buildQuery: (collection: RealtimeCollection) => QueryFn, + // These tests exercise server-side filtering, which is opt-in on the + // collection (realtimeUseFilter defaults to false), so enable it by default + // here and let individual tests override it. + { realtimeUseFilter = true }: { realtimeUseFilter?: boolean } = {}, +) { + const mockFetch = createMockFetch() + const mockChannel = createMockChannel() + const { collection } = createRealtimeUsersCollection(mockFetch, mockChannel, { + realtimeUseFilter, + }) + track(collection) + + const live = startLiveQuery(collection, buildQuery) + + await live.preload() + await live.toArrayWhenReady() + await vi.waitFor(() => expect(mockChannel.on).toHaveBeenCalled()) + + return { mockChannel, collection } +} + +// The filters applied to INSERT listeners — the ones that decide which rows +// belong in the collection. +function insertFilters(mockChannel: MockChannel): Array { + return filtersFor(mockChannel, 'INSERT') +} + +describe('realtime filter propagation', () => { + describe('supported single-comparison filters', () => { + test('eq on a number column', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q.from({ user: collection }).where(({ user }) => eq(user.id, 1)), + ) + expect(insertFilters(mockChannel)).toEqual(['id=eq.1']) + }) + + test('eq on a boolean column', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => eq(user.active, true)), + ) + expect(insertFilters(mockChannel)).toEqual(['active=eq.true']) + }) + + test('gt', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q.from({ user: collection }).where(({ user }) => gt(user.id, 5)), + ) + expect(insertFilters(mockChannel)).toEqual(['id=gt.5']) + }) + + test('gte', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q.from({ user: collection }).where(({ user }) => gte(user.id, 5)), + ) + expect(insertFilters(mockChannel)).toEqual(['id=gte.5']) + }) + + test('lt', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q.from({ user: collection }).where(({ user }) => lt(user.id, 10)), + ) + expect(insertFilters(mockChannel)).toEqual(['id=lt.10']) + }) + + test('lte', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q.from({ user: collection }).where(({ user }) => lte(user.id, 10)), + ) + expect(insertFilters(mockChannel)).toEqual(['id=lte.10']) + }) + + test('inArray maps to in.(...)', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => inArray(user.id, [1, 2, 3])), + ) + expect(insertFilters(mockChannel)).toEqual(['id=in.(1,2,3)']) + }) + + test('not(eq) maps to not.eq', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => not(eq(user.active, false))), + ) + expect(insertFilters(mockChannel)).toEqual(['active=not.eq.false']) + }) + + test('isNull maps to is.null', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q.from({ user: collection }).where(({ user }) => isNull(user.name)), + ) + expect(insertFilters(mockChannel)).toEqual(['name=is.null']) + }) + + test('not(isNull) maps to not.is.null', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => not(isNull(user.name))), + ) + expect(insertFilters(mockChannel)).toEqual(['name=not.is.null']) + }) + + test('not(inArray) maps to not.in', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => not(inArray(user.id, [1, 2]))), + ) + expect(insertFilters(mockChannel)).toEqual(['id=not.in.(1,2)']) + }) + + test('not(gt) maps to not.gt', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q.from({ user: collection }).where(({ user }) => not(gt(user.id, 5))), + ) + expect(insertFilters(mockChannel)).toEqual(['id=not.gt.5']) + }) + + test('composite AND becomes a comma-separated filter', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => and(eq(user.active, true), gt(user.id, 5))), + ) + expect(insertFilters(mockChannel)).toEqual(['active=eq.true,id=gt.5']) + }) + }) + + describe('value serialization', () => { + test('a string containing a comma is PostgREST-quoted', async () => { + // Unquoted, the comma would read as a second ANDed condition. + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => eq(user.name, 'Doe, Jane')), + ) + expect(insertFilters(mockChannel)).toEqual(['name=eq."Doe, Jane"']) + }) + + test('a quote inside a value is escaped', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => eq(user.name, 'He said "hi", ok')), + ) + expect(insertFilters(mockChannel)).toEqual([ + 'name=eq."He said \\"hi\\", ok"', + ]) + }) + + test('a plain string is left unquoted', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => eq(user.name, 'Zed')), + ) + expect(insertFilters(mockChannel)).toEqual(['name=eq.Zed']) + }) + + test('an in list of exactly 100 values is still filtered', async () => { + const values = Array.from({ length: 100 }, (_, index) => index) + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => inArray(user.id, values)), + ) + expect(insertFilters(mockChannel)).toEqual([ + `id=in.(${values.join(',')})`, + ]) + }) + + test('an in list longer than 100 values falls back to a catch-all', async () => { + const values = Array.from({ length: 101 }, (_, index) => index) + const { mockChannel } = await captureChannel( + (collection) => (q) => + q + .from({ user: collection }) + .where(({ user }) => inArray(user.id, values)), + ) + expect(insertFilters(mockChannel)).toEqual([null]) + }) + }) + + describe('catch-all subscriptions (no filter)', () => { + test('no WHERE clause', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => q.from({ user: collection }), + ) + expect(insertFilters(mockChannel)).toEqual([null]) + }) + + test('no redundant unfiltered UPDATE listener is added', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => q.from({ user: collection }), + ) + expect(filtersFor(mockChannel, 'UPDATE')).toEqual([null]) + }) + + test('realtimeUseFilter: false subscribes catch-all despite a filterable WHERE', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q.from({ user: collection }).where(({ user }) => eq(user.id, 1)), + { realtimeUseFilter: false }, + ) + // The WHERE is representable as a Realtime filter, but filtering is off, + // so every listener subscribes to all changes and no redundant unfiltered + // UPDATE listener is added. + expect(insertFilters(mockChannel)).toEqual([null]) + expect(filtersFor(mockChannel, 'UPDATE')).toEqual([null]) + expect(filtersFor(mockChannel, 'DELETE')).toEqual([null]) + }) + + test('defaults to catch-all when realtimeUseFilter is omitted', async () => { + const mockFetch = createMockFetch() + const mockChannel = createMockChannel() + // No realtimeUseFilter option → the collection default (false) applies. + const { collection } = createRealtimeUsersCollection( + mockFetch, + mockChannel, + ) + track(collection) + + const live = startLiveQuery( + collection, + (c) => (q) => q.from({ user: c }).where(({ user }) => eq(user.id, 1)), + ) + await live.preload() + await live.toArrayWhenReady() + await vi.waitFor(() => expect(mockChannel.on).toHaveBeenCalled()) + + // A filterable WHERE is not pushed; every listener subscribes to all rows. + expect(insertFilters(mockChannel)).toEqual([null]) + expect(filtersFor(mockChannel, 'UPDATE')).toEqual([null]) + }) + }) + + describe('listener layout', () => { + test('filters apply to INSERT and UPDATE, never to DELETE', async () => { + const { mockChannel } = await captureChannel( + (collection) => (q) => + q.from({ user: collection }).where(({ user }) => eq(user.id, 1)), + ) + + expect(filtersFor(mockChannel, 'INSERT')).toEqual(['id=eq.1']) + // The filtered listener catches rows entering the window; the unfiltered + // one keeps rows already held up to date after they leave it. + expect(filtersFor(mockChannel, 'UPDATE')).toEqual(['id=eq.1', null]) + // Realtime only delivers filtered deletes with `replica identity full`. + expect(filtersFor(mockChannel, 'DELETE')).toEqual([null]) + }) + }) + + describe('payload routing into the collection', () => { + const row = { + id: 99, + name: 'Zed', + email: 'zed@test.com', + active: true, + } + + test('INSERT writes the new row', async () => { + const { mockChannel, collection } = await captureChannel( + (c) => (q) => q.from({ user: c }), + ) + + emit(mockChannel, { eventType: 'INSERT', new: row, old: {} }) + + expect(collection.has(collection.getKeyFromItem(row))).toBe(true) + }) + + test('INSERT for a row already held overwrites instead of throwing', async () => { + const { mockChannel, collection } = await captureChannel( + (c) => (q) => q.from({ user: c }), + ) + + emit(mockChannel, { eventType: 'INSERT', new: row, old: {} }) + expect(() => + emit(mockChannel, { + eventType: 'INSERT', + new: { ...row, name: 'Twice' }, + old: {}, + }), + ).not.toThrow() + + expect(collection.get(collection.getKeyFromItem(row))?.name).toBe('Twice') + }) + + test('UPDATE writes the updated row', async () => { + const { mockChannel, collection } = await captureChannel( + (c) => (q) => q.from({ user: c }), + ) + + emit(mockChannel, { eventType: 'INSERT', new: row, old: {} }) + emit(mockChannel, { + eventType: 'UPDATE', + new: { ...row, name: 'Updated' }, + old: {}, + }) + + expect(collection.get(collection.getKeyFromItem(row))?.name).toBe( + 'Updated', + ) + }) + + test('a matching UPDATE for an unseen row inserts it', async () => { + const { mockChannel, collection } = await captureChannel( + (c) => (q) => q.from({ user: c }).where(({ user }) => eq(user.id, 99)), + ) + const filtered = nth(listenersFor(mockChannel, 'UPDATE'), 0) + + // Realtime only delivers this to the filtered listener when the row + // matches, which means the row has moved into the query's window. + expect(() => + filtered.handler({ eventType: 'UPDATE', new: row, old: {} }), + ).not.toThrow() + + expect(collection.has(collection.getKeyFromItem(row))).toBe(true) + }) + + test('an unfiltered UPDATE for an unseen row is ignored', async () => { + const { mockChannel, collection } = await captureChannel( + (c) => (q) => q.from({ user: c }).where(({ user }) => eq(user.id, 1)), + ) + const catchAll = listenersFor(mockChannel, 'UPDATE').find( + (call) => !call.config.filter, + ) + + // Would otherwise mirror every row in the table into the collection. + expect(() => + catchAll?.handler({ eventType: 'UPDATE', new: row, old: {} }), + ).not.toThrow() + + expect(collection.has(collection.getKeyFromItem(row))).toBe(false) + }) + + test('INSERT for an already-present key with changed data does not throw', async () => { + const { mockChannel, collection } = await captureChannel( + (c) => (q) => q.from({ user: c }), + ) + const { handler } = nth(mockChannel.onCalls, 0) + + // Realtime replayed/duplicated the same INSERT with changed data: this + // is the exact shape of an unhandled write-conflict error. + handler({ eventType: 'INSERT', new: row, old: {} }) + expect(() => + handler({ + eventType: 'INSERT', + new: { ...row, name: 'Zed Prime' }, + old: {}, + }), + ).not.toThrow() + + const key = collection.getKeyFromItem(row) + expect(collection.get(key)?.name).toBe('Zed Prime') + }) + + test('UPDATE for a key not present in the collection does not throw', async () => { + const { mockChannel, collection } = await captureChannel( + (c) => (q) => q.from({ user: c }), + ) + const { handler } = nth(mockChannel.onCalls, 0) + + expect(() => + handler({ eventType: 'UPDATE', new: row, old: {} }), + ).not.toThrow() + + const key = collection.getKeyFromItem(row) + expect(collection.get(key)?.name).toBe('Zed') + }) + + test('DELETE removes the row, and is a no-op for an unknown key', async () => { + const { mockChannel, collection } = await captureChannel( + (c) => (q) => q.from({ user: c }), + ) + + emit(mockChannel, { eventType: 'INSERT', new: row, old: {} }) + const key = collection.getKeyFromItem(row) + expect(collection.has(key)).toBe(true) + + emit(mockChannel, { eventType: 'DELETE', new: {}, old: row }) + expect(collection.has(key)).toBe(false) + + // A delete for a key the collection never had must not throw. + expect(() => + emit(mockChannel, { + eventType: 'DELETE', + new: {}, + old: { id: 12_345, name: '', email: '', active: false }, + }), + ).not.toThrow() + }) + }) + + describe('fetching without waiting for the subscription', () => { + // Known limitation (see queryFn in src/db.ts): the initial fetch is not + // gated on the channel subscribing, so a row written in the window between + // the fetch and the subscription going live can be missed by both. + test('the first fetch does not wait for the channel to subscribe', async () => { + const mockFetch = createMockFetch() + const mockChannel = createMockChannel({ autoSubscribe: false }) + const { collection } = createRealtimeUsersCollection( + mockFetch, + mockChannel, + ) + track(collection) + + const live = startLiveQuery( + collection, + (c) => (q) => q.from({ user: c }).where(({ user }) => eq(user.id, 1)), + ) + await live.preload() + await live.toArrayWhenReady() + + // The fetch proceeds even though the channel never reported SUBSCRIBED. + expect(mockFetch).toHaveBeenCalled() + }) + }) + + describe('resubscribing when the filter set changes', () => { + test('uses a fresh channel topic and drops the previous channel', async () => { + const mockFetch = createMockFetch() + const channels: Array = [] + const { collection, supabase } = createRealtimeUsersCollection( + mockFetch, + () => { + const channel = createMockChannel() + channels.push(channel) + return channel + }, + { realtimeUseFilter: true }, + ) + track(collection) + + const first = startLiveQuery( + collection, + (c) => (q) => q.from({ user: c }).where(({ user }) => eq(user.id, 1)), + ) + await first.preload() + await first.toArrayWhenReady() + await vi.waitFor(() => expect(channels.length).toBe(1)) + + const second = startLiveQuery( + collection, + (c) => (q) => q.from({ user: c }).where(({ user }) => gt(user.id, 5)), + ) + await second.preload() + await second.toArrayWhenReady() + await vi.waitFor(() => expect(channels.length).toBe(2)) + + const topics = ( + supabase.channel as unknown as ReturnType + ).mock.calls.map(([topic]) => topic) + // A repeated topic would hand back the channel being torn down. + expect(new Set(topics).size).toBe(topics.length) + + // The union of both queries' filters is now subscribed. + expect(insertFilters(nth(channels, 1))).toEqual(['id=eq.1', 'id=gt.5']) + + // The old channel is only dropped once the replacement is subscribed. + await vi.waitFor(() => + expect(supabase.removeChannel).toHaveBeenCalledWith(nth(channels, 0)), + ) + }) + }) + + describe('racing local mutations', () => { + const row = { id: 77, name: 'Race', email: 'race@test.com', active: true } + + test('a Realtime echo of a pending local insert does not throw', async () => { + const { mockChannel, collection } = await captureChannel( + (c) => (q) => q.from({ user: c }), + ) + const key = collection.getKeyFromItem(row) + + const tx = collection.insert(row) + // The optimistic row is visible right away, but the synced store only + // learns about it once PostgREST answers — Realtime is usually faster. + expect(collection.has(key)).toBe(true) + expect(() => + emit(mockChannel, { eventType: 'INSERT', new: row, old: {} }), + ).not.toThrow() + + await expect(tx.when('settled')).resolves.toBeDefined() + expect(collection.get(key)?.name).toBe('Race') + }) + + test('a Realtime echo of a pending local delete does not throw', async () => { + const { mockChannel, collection } = await captureChannel( + (c) => (q) => q.from({ user: c }), + ) + emit(mockChannel, { eventType: 'INSERT', new: row, old: {} }) + const key = collection.getKeyFromItem(row) + + const tx = collection.delete(key) + expect(collection.has(key)).toBe(false) + expect(() => + emit(mockChannel, { eventType: 'DELETE', new: {}, old: row }), + ).not.toThrow() + + await expect(tx.when('settled')).resolves.toBeDefined() + expect(collection.has(key)).toBe(false) + }) + }) + + describe('swapping channels safely', () => { + // The first channel joins immediately; every replacement waits for the test + // to report its subscription status. + async function startSwap() { + const mockFetch = createMockFetch() + const channels: Array = [] + const { collection, supabase } = createRealtimeUsersCollection( + mockFetch, + () => { + const channel = createMockChannel({ + autoSubscribe: channels.length === 0, + }) + channels.push(channel) + return channel + }, + { realtimeUseFilter: true }, + ) + track(collection) + + const first = startLiveQuery( + collection, + (c) => (q) => q.from({ user: c }).where(({ user }) => eq(user.id, 1)), + ) + await first.preload() + await first.toArrayWhenReady() + await vi.waitFor(() => expect(channels.length).toBe(1)) + + const second = startLiveQuery( + collection, + (c) => (q) => q.from({ user: c }).where(({ user }) => gt(user.id, 5)), + ) + const secondPreloaded = second.preload() + await vi.waitFor(() => expect(channels.length).toBe(2)) + await vi.waitFor(() => + expect(nth(channels, 1).subscribe).toHaveBeenCalled(), + ) + + return { channels, collection, supabase, secondPreloaded } + } + + test('keeps the previous channel until the replacement reports SUBSCRIBED', async () => { + const { channels, supabase, secondPreloaded } = await startSwap() + + // Dropping it now would leave a window with no subscription at all. + expect(supabase.removeChannel).not.toHaveBeenCalled() + + nth(channels, 1).confirmSubscribed() + await secondPreloaded + await vi.waitFor(() => + expect(supabase.removeChannel).toHaveBeenCalledWith(nth(channels, 0)), + ) + }) + + test('falls back to a catch-all when the server rejects the filtered subscription', async () => { + const { channels, collection, supabase, secondPreloaded } = + await startSwap() + + nth(channels, 1).confirmSubscribed('CHANNEL_ERROR') + + await vi.waitFor(() => expect(channels.length).toBe(3)) + expect(insertFilters(nth(channels, 2))).toEqual([null]) + expect(supabase.removeChannel).toHaveBeenCalledWith(nth(channels, 1)) + // The working channel is only replaced once the fallback has joined. + expect(supabase.removeChannel).not.toHaveBeenCalledWith(nth(channels, 0)) + + nth(channels, 2).confirmSubscribed() + await vi.waitFor(() => + expect(supabase.removeChannel).toHaveBeenCalledWith(nth(channels, 0)), + ) + await secondPreloaded + + // The rejected filter set is remembered: a query that would produce it + // again reuses the catch-all instead of failing the same way twice. + const third = startLiveQuery( + collection, + (c) => (q) => q.from({ user: c }).where(({ user }) => gt(user.id, 5)), + ) + await third.preload() + await third.toArrayWhenReady() + expect(channels.length).toBe(3) + }) + + test('keeps the previous channel when even the catch-all is rejected', async () => { + const { channels, supabase, secondPreloaded } = await startSwap() + + nth(channels, 1).confirmSubscribed('CHANNEL_ERROR') + await vi.waitFor(() => expect(channels.length).toBe(3)) + nth(channels, 2).confirmSubscribed('CHANNEL_ERROR') + + await vi.waitFor(() => + expect(supabase.removeChannel).toHaveBeenCalledWith(nth(channels, 2)), + ) + expect(supabase.removeChannel).toHaveBeenCalledWith(nth(channels, 1)) + expect(supabase.removeChannel).not.toHaveBeenCalledWith(nth(channels, 0)) + expect(channels.length).toBe(3) + + // Data loading is never held hostage by a failed subscription. + await secondPreloaded + }) + + test('a transient error on the sole catch-all keeps the channel so it can reconnect', async () => { + const mockFetch = createMockFetch() + const channels: Array = [] + const { collection, supabase } = createRealtimeUsersCollection( + mockFetch, + () => { + const channel = createMockChannel({ autoSubscribe: false }) + channels.push(channel) + return channel + }, + // realtimeUseFilter defaults to false → a single catch-all subscription. + ) + track(collection) + + const live = startLiveQuery(collection, (c) => (q) => q.from({ user: c })) + const preloaded = live.preload() + await vi.waitFor(() => expect(channels.length).toBe(1)) + await vi.waitFor(() => + expect(nth(channels, 0).subscribe).toHaveBeenCalled(), + ) + + // The only channel reports a transient connection error before joining. A + // catch-all has nothing to reject, so this is not a filter rejection. + nth(channels, 0).confirmSubscribed('CHANNEL_ERROR') + await preloaded + + // It is NOT removed — realtime-js keeps retrying the join and its listeners + // stay attached — and no replacement is opened, so the table is never left + // without a channel until an observer changes. + expect(supabase.removeChannel).not.toHaveBeenCalled() + expect(channels.length).toBe(1) + }) + + test('tearing down all queries removes the joined and the in-flight channel', async () => { + const mockFetch = createMockFetch() + const channels: Array = [] + const { collection, supabase } = createRealtimeUsersCollection( + mockFetch, + () => { + const channel = createMockChannel({ + autoSubscribe: channels.length === 0, + }) + channels.push(channel) + return channel + }, + { realtimeUseFilter: true }, + ) + track(collection) + + const first = startLiveQuery( + collection, + (c) => (q) => q.from({ user: c }).where(({ user }) => eq(user.id, 1)), + ) + await first.preload() + await first.toArrayWhenReady() + await vi.waitFor(() => expect(channels.length).toBe(1)) + + // A second query opens a replacement channel that never joins, so it stays + // pending alongside the first, still-joined channel. + const second = startLiveQuery( + collection, + (c) => (q) => q.from({ user: c }).where(({ user }) => gt(user.id, 5)), + ) + const secondPreloaded = second.preload() + await vi.waitFor(() => expect(channels.length).toBeGreaterThan(1)) + await secondPreloaded + + // Tearing down every active query must dispose every channel this table + // opened — a joined channel and any swap still in flight — with none left + // behind. + await first.cleanup() + await second.cleanup() + + await vi.waitFor(() => { + for (const channel of channels) { + expect(supabase.removeChannel).toHaveBeenCalledWith(channel) + } + }) + }) + }) + + // `or(...)` (and other unsupported expressions) cannot be driven through the + // live-query path because the query's own supabaseQueryFn calls the same + // strict toPostgrestParams, which throws on an unpushable expression. Cover the + // defensive fallback directly. + describe('realtimeFiltersToSearch falls back instead of throwing', () => { + test('an unsupported expression yields a catch-all', () => { + const orExpression = { type: 'func', name: 'or', args: [] } as any + expect(realtimeFiltersToSearch([orExpression])).toEqual( + new URLSearchParams(), + ) + }) + }) +}) diff --git a/packages/supabase-db-collection/tests/request-headers.test.ts b/packages/supabase-db-collection/tests/request-headers.test.ts new file mode 100644 index 0000000000..d28538c6dc --- /dev/null +++ b/packages/supabase-db-collection/tests/request-headers.test.ts @@ -0,0 +1,139 @@ +import { createClient } from '@supabase/supabase-js' +import { createCollection } from '@tanstack/db' +import { afterEach, describe, expect, test } from 'vitest' +import pkg from '../package.json' +import { supabaseCollectionOptions } from '../src/index' +import { VERSION } from '../src/version' +import { + SUPABASE_KEY, + SUPABASE_URL, + createMockFetch, + createMockedUsersCollection, + getRequestHeaders, + queryResult, + usersSchema, +} from './test.utils' + +const EXPECTED_CLIENT_INFO = `@tanstack/supabase-db-collection/${VERSION}` + +test('VERSION stays in sync with package.json', () => { + expect(VERSION).toBe(pkg.version) +}) + +describe('automatic X-Client-Info header', () => { + let collection: ReturnType + + afterEach(() => { + collection.cleanup() + }) + + test('is present on select requests', async () => { + const mockFetch = createMockFetch() + collection = createMockedUsersCollection(mockFetch) + + await queryResult((q) => q.from({ user: collection })) + + expect(getRequestHeaders(mockFetch, 0).get('x-client-info')).toBe( + EXPECTED_CLIENT_INFO, + ) + }) + + test('is present on insert requests', async () => { + const mockFetch = createMockFetch() + collection = createMockedUsersCollection(mockFetch) + await queryResult((q) => q.from({ user: collection })) + + const tx = collection.insert({ + id: 2, + name: 'Bob', + email: 'bob@test.com', + active: true, + }) + await tx.when('settled') + + const lastCall = mockFetch.mock.calls.length - 1 + expect(getRequestHeaders(mockFetch, lastCall).get('x-client-info')).toBe( + EXPECTED_CLIENT_INFO, + ) + }) + + test('is present on update requests', async () => { + const mockFetch = createMockFetch() + collection = createMockedUsersCollection(mockFetch) + await queryResult((q) => q.from({ user: collection })) + + const insertTx = collection.insert({ + id: 2, + name: 'Bob', + email: 'bob@test.com', + active: true, + }) + await insertTx.when('settled') + + const updateTx = collection.update('2', (draft) => { + draft.name = 'Bobby' + }) + await updateTx.when('settled') + + const lastCall = mockFetch.mock.calls.length - 1 + expect(getRequestHeaders(mockFetch, lastCall).get('x-client-info')).toBe( + EXPECTED_CLIENT_INFO, + ) + }) + + test('is present on delete requests', async () => { + const mockFetch = createMockFetch() + collection = createMockedUsersCollection(mockFetch) + await queryResult((q) => q.from({ user: collection })) + + const insertTx = collection.insert({ + id: 2, + name: 'Bob', + email: 'bob@test.com', + active: true, + }) + await insertTx.when('settled') + + const deleteTx = collection.delete('2') + await deleteTx.when('settled') + + const lastCall = mockFetch.mock.calls.length - 1 + expect(getRequestHeaders(mockFetch, lastCall).get('x-client-info')).toBe( + EXPECTED_CLIENT_INFO, + ) + }) + + test("replaces supabase-js's own X-Client-Info rather than appending", async () => { + const mockFetch = createMockFetch() + collection = createMockedUsersCollection(mockFetch) + + await queryResult((q) => q.from({ user: collection })) + + const value = getRequestHeaders(mockFetch, 0).get('x-client-info') + expect(value).toBe(EXPECTED_CLIENT_INFO) + expect(value).not.toContain('supabase-js') + }) + + test('preserves user-supplied global headers', async () => { + const mockFetch = createMockFetch() + collection = createCollection( + supabaseCollectionOptions({ + tableName: 'users', + keys: ['id'], + schema: usersSchema, + supabase: createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { + fetch: mockFetch, + headers: { 'X-Custom-Header': 'custom-value' }, + }, + }), + }), + ) + + await queryResult((q) => q.from({ user: collection })) + + const headers = getRequestHeaders(mockFetch, 0) + expect(headers.get('x-custom-header')).toBe('custom-value') + expect(headers.get('x-client-info')).toBe(EXPECTED_CLIENT_INFO) + }) +}) diff --git a/packages/supabase-db-collection/tests/row-conversions.test.ts b/packages/supabase-db-collection/tests/row-conversions.test.ts new file mode 100644 index 0000000000..809aeda6f8 --- /dev/null +++ b/packages/supabase-db-collection/tests/row-conversions.test.ts @@ -0,0 +1,294 @@ +import { createClient } from '@supabase/supabase-js' +import { createCollection } from '@tanstack/db' +import { QueryClient } from '@tanstack/query-core' +import { afterEach, describe, expect, test, vi } from 'vitest' +import { z } from 'zod' +import { supabaseCollectionOptions } from '../src/index' +import { + SUPABASE_KEY, + SUPABASE_URL, + createMockChannel, + emit, +} from './test.utils' +import type { MockChannel } from './test.utils' + +const eventsSchema = z.object({ + id: z.bigint(), + title: z.string(), + startsAt: z.date(), + endsAt: z.date().nullable(), + tags: z.set(z.string()), +}) + +// What PostgREST and Realtime send for the schema above: a bigint is a JSON +// number, a timestamptz an ISO string and a text[] a JSON array. +type EventRecord = { + id: number + title: string + startsAt: string + endsAt: string | null + tags: Array +} + +const START = '2024-05-06T07:08:09.123+00:00' +const END = '2024-05-07T07:08:09.123+00:00' + +const cleanups: Array<() => void | Promise> = [] + +afterEach(async () => { + for (const cleanup of cleanups.splice(0).reverse()) { + await cleanup() + } +}) + +const json = (body: unknown, contentRange?: string) => + new Response(JSON.stringify(body), { + status: 200, + headers: { + 'content-type': 'application/json', + ...(contentRange ? { 'content-range': contentRange } : {}), + }, + }) + +/** A PostgREST stand-in holding `rows`, recording the write requests it gets. */ +function makeServer(rows: Array) { + const writes: Array<{ method: string; search: string; body: unknown }> = [] + const fetchMock = vi.fn().mockImplementation((input, init) => { + const method = init?.method ?? 'GET' + if (method === 'GET') { + return Promise.resolve(json(rows, `0-${rows.length - 1}/${rows.length}`)) + } + const body = JSON.parse(String(init?.body ?? '{}')) + writes.push({ method, search: new URL(String(input)).search, body }) + // PATCH and POST return the stored row, as `Prefer: return=representation` + // asks: bigints as JSON numbers, with a column the server filled in. + return Promise.resolve( + json({ ...body, id: Number(body.id ?? 1), endsAt: body.endsAt ?? null }), + ) + }) + return { fetchMock, writes } +} + +function makeEvents( + rows: Array, + { realtime = false }: { realtime?: boolean } = {}, +) { + const server = makeServer(rows) + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: server.fetchMock }, + }) + const channel: MockChannel = createMockChannel() + if (realtime) { + supabase.channel = vi.fn( + () => channel, + ) as unknown as typeof supabase.channel + supabase.removeChannel = vi.fn() as unknown as typeof supabase.removeChannel + } + const collection = createCollection( + supabaseCollectionOptions({ + tableName: 'events', + keys: ['id'], + schema: eventsSchema, + supabase, + queryClient: new QueryClient(), + syncMode: 'eager', + realtime, + parse: { + id: (value) => BigInt(value as number), + startsAt: (value) => new Date(value as string), + endsAt: (value) => new Date(value as string), + tags: (value) => new Set(value as Array), + }, + serialize: { + id: (value) => value.toString(), + startsAt: (value) => value.toISOString(), + endsAt: (value) => value.toISOString(), + // A Set would serialize to `{}`. + tags: (value) => [...value], + }, + }), + ) + cleanups.push(() => collection.cleanup()) + return { collection, channel, ...server } +} + +describe('parse and serialize', () => { + test('rows read from PostgREST are parsed into the schema types', async () => { + const { collection } = makeEvents([ + { + id: 7, + title: 'Launch', + startsAt: START, + endsAt: END, + tags: ['a', 'b'], + }, + ]) + await collection.preload() + + expect(collection.get('7')).toMatchObject({ + id: 7n, + title: 'Launch', + startsAt: new Date(START), + endsAt: new Date(END), + tags: new Set(['a', 'b']), + }) + }) + + test('null columns are not passed to parse', async () => { + const { collection } = makeEvents([ + { id: 7, title: 'Open ended', startsAt: START, endsAt: null, tags: [] }, + ]) + await collection.preload() + + expect(collection.get('7')?.endsAt).toBeNull() + }) + + test('columns without a conversion are left as received', async () => { + const { collection } = makeEvents([ + { id: 7, title: 'Launch', startsAt: START, endsAt: null, tags: [] }, + ]) + await collection.preload() + + expect(collection.get('7')?.title).toBe('Launch') + }) + + test('an insert sends serialized columns and stores the parsed server row', async () => { + const { collection, writes } = makeEvents([]) + await collection.preload() + + const tx = collection.insert({ + id: 42n, + title: 'Insert', + startsAt: new Date(START), + endsAt: null, + tags: new Set(['x', 'y']), + }) + await tx.when('settled') + + expect(writes).toEqual([ + { + method: 'POST', + search: '?select=*', + body: { + id: '42', + title: 'Insert', + startsAt: '2024-05-06T07:08:09.123Z', + endsAt: null, + tags: ['x', 'y'], + }, + }, + ]) + expect(collection.get('42')).toMatchObject({ + title: 'Insert', + startsAt: new Date(START), + tags: new Set(['x', 'y']), + }) + }) + + test('an update matches the row by its serialized key and sends serialized columns', async () => { + const { collection, writes } = makeEvents([ + { + id: 7, + title: 'Launch', + startsAt: START, + endsAt: END, + tags: ['a', 'b'], + }, + ]) + await collection.preload() + + const tx = collection.update('7', (draft) => { + draft.title = 'Relaunch' + }) + await tx.when('settled') + + expect(writes).toEqual([ + { + method: 'PATCH', + search: '?id=eq.7&select=*', + body: { + id: '7', + title: 'Relaunch', + startsAt: '2024-05-06T07:08:09.123Z', + endsAt: '2024-05-07T07:08:09.123Z', + tags: ['a', 'b'], + }, + }, + ]) + expect(collection.get('7')?.title).toBe('Relaunch') + }) + + test('a delete matches the row by its serialized key', async () => { + const { collection, writes } = makeEvents([ + { id: 7, title: 'Launch', startsAt: START, endsAt: null, tags: [] }, + ]) + await collection.preload() + + const tx = collection.delete('7') + await tx.when('settled') + + expect(writes).toMatchObject([{ method: 'DELETE', search: '?id=eq.7' }]) + expect(collection.has('7')).toBe(false) + }) + + describe('realtime', () => { + const attached = async (rows: Array = []) => { + const events = makeEvents(rows, { realtime: true }) + await events.collection.preload() + await vi.waitFor(() => expect(events.channel.on).toHaveBeenCalled()) + return events + } + + test('inserted rows are parsed', async () => { + const { collection, channel } = await attached() + + emit(channel, { + eventType: 'INSERT', + new: { + id: 8, + title: 'Live', + startsAt: START, + endsAt: null, + tags: ['live'], + }, + }) + + expect(collection.get('8')).toMatchObject({ + id: 8n, + startsAt: new Date(START), + endsAt: null, + tags: new Set(['live']), + }) + }) + + test('updated rows are parsed', async () => { + const { collection, channel } = await attached([ + { id: 8, title: 'Live', startsAt: START, endsAt: null, tags: [] }, + ]) + + emit(channel, { + eventType: 'UPDATE', + new: { + id: 8, + title: 'Live', + startsAt: START, + endsAt: END, + tags: ['a', 'b'], + }, + }) + + expect(collection.get('8')?.endsAt).toEqual(new Date(END)) + }) + + test('a deleted row is found by its parsed key', async () => { + const { collection, channel } = await attached([ + { id: 8, title: 'Live', startsAt: START, endsAt: null, tags: [] }, + ]) + + // A delete payload carries only the key columns of the old row. + emit(channel, { eventType: 'DELETE', old: { id: 8 } }) + + expect(collection.has('8')).toBe(false) + }) + }) +}) diff --git a/packages/supabase-db-collection/tests/split-load-fanout.test.ts b/packages/supabase-db-collection/tests/split-load-fanout.test.ts new file mode 100644 index 0000000000..317f866aee --- /dev/null +++ b/packages/supabase-db-collection/tests/split-load-fanout.test.ts @@ -0,0 +1,377 @@ +import { createClient } from '@supabase/supabase-js' +import { IR, and, inArray, not } from '@tanstack/db' +import { QueryClient } from '@tanstack/query-core' +import { describe, expect, test, vi } from 'vitest' +import { MAX_URL_LENGTH, supabaseQueryFn } from '../src/functions' +import { loadSubsetOptionsToSearch } from '../src/postgrest-filters' +import { + getRawUrls, + getSearches, + makePaginatingFetch, +} from './pagination.utils' +import { SUPABASE_KEY, SUPABASE_URL } from './test.utils' +import type { LoadSubsetOptions } from '@tanstack/db' + +// Same table shape `makePaginatingFetch` was built for: a bare numeric `id`. +const idRef = new IR.PropRef(['id']) + +// The base table URL `supabaseQueryFn` measures every subset's rendered URL +// against (see `measureSubset` in src/functions.ts) — computed once here so +// `idsExceedingLength` can size an id list against the same budget the +// production splitter uses. +const BASE_URL_LENGTH = createClient(SUPABASE_URL, SUPABASE_KEY) + .from('items') + .url.toString().length + +/** + * A dense `1..n` id list whose rendered `in(...)` filter, combined with the + * base table URL, is at least `minLength` characters — i.e. the URL a single, + * unsplit request for this list would produce. Sized against `MAX_URL_LENGTH` + * (rather than a hard-coded id count) so the tests below keep exercising the + * splitter even if that constant ever changes. + * + * A small sample list's rendered length estimates the average per-id cost + * (digits plus a percent-encoded comma); the list is then resized to that + * estimate. One correction pass is always enough — the only thing the sample + * can get wrong is the id width, which grows by at most a digit or two + * between the sample and the final count. + */ +function idsExceedingLength(minLength: number): Array { + let count = 100 + for (let attempt = 0; attempt < 10; attempt++) { + const ids = Array.from({ length: count }, (_, i) => i + 1) + const length = + BASE_URL_LENGTH + + loadSubsetOptionsToSearch({ + where: inArray(idRef, ids), + } as unknown as LoadSubsetOptions).toString().length + if (length >= minLength) { + return ids + } + const perId = (length - BASE_URL_LENGTH) / count + count = Math.ceil((minLength - BASE_URL_LENGTH) / perId) + 10 + } + throw new Error(`could not size an id list past ${minLength} characters`) +} + +const runWhere = ( + mockFetch: ReturnType | typeof fetch, + where: unknown, + signal: AbortSignal = new AbortController().signal, +) => { + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + return supabaseQueryFn(supabase, 'items', { + client: new QueryClient(), + queryKey: ['items'], + signal, + meta: { loadSubsetOptions: { where } } as never, + }) +} + +const run = ( + mockFetch: ReturnType | typeof fetch, + ids: Array, + signal: AbortSignal = new AbortController().signal, +) => runWhere(mockFetch, inArray(idRef, ids), signal) + +// The length of an `in(id, ids)` subset's first-page URL without its `?`: how +// `measureSubset` (src/functions.ts) used to measure it, before it counted the +// `?` and the `offset`/`limit` params later pages add. +const measuredLength = (ids: Array): number => + BASE_URL_LENGTH + + loadSubsetOptionsToSearch({ + where: inArray(idRef, ids), + } as unknown as LoadSubsetOptions).toString().length + +const FIVE_DIGIT_START = 10_000 +const SIX_DIGIT_START = 100_000 +const TRAILING_SIX_DIGIT_START = 200_000 + +/** + * An id list whose leading ids measure *exactly* `targetLength` (per + * `measuredLength`), followed by `trailing` more ids that cannot fit beside it + * and so spill into later chunks. Deterministic: the list is dense 5-digit ids + * up to the longest prefix within the target, then the last few of those are + * widened to 6 digits (+1 character each) to close the remaining gap exactly. + */ +function idsPackedTo(targetLength: number, trailing = 5): Array { + let count = 1 + const fiveDigit = (n: number) => + Array.from({ length: n }, (_, i) => FIVE_DIGIT_START + i) + while (measuredLength(fiveDigit(count + 1)) <= targetLength) { + count++ + } + const gap = targetLength - measuredLength(fiveDigit(count)) + const packed = fiveDigit(count).map((value, i) => + i >= count - gap ? SIX_DIGIT_START + i : value, + ) + if (measuredLength(packed) !== targetLength) { + throw new Error(`could not pack an id list to exactly ${targetLength}`) + } + const spill = Array.from( + { length: trailing }, + (_, i) => TRAILING_SIX_DIGIT_START + i, + ) + return [...packed, ...spill] +} + +describe('supabaseQueryFn: chunked fan-out for an oversized IN list', () => { + test('many ids produce multiple requests, every URL within budget, and every matching row comes back', async () => { + const ids = idsExceedingLength(MAX_URL_LENGTH * 1.5) + const fixture = ids.map((id) => ({ id })) + const mockFetch = makePaginatingFetch(fixture) + + const rows = await run(mockFetch, ids) + + expect( + (rows as Array<{ id: number }>).map((r) => r.id).sort((a, b) => a - b), + ).toEqual(ids) + const searches = getSearches(mockFetch) + // The list does not fit in one request at this budget, so it was split. + expect(searches.length).toBeGreaterThan(1) + // Every request the mock saw actually carried an `in.(...)` slice of the + // original list, proving the split happened on the `id` column. + for (const search of searches) { + expect(search).toMatch(/id=in\.\(/) + } + // Every rendered request line stays within the fixed budget. + for (const rawUrl of getRawUrls(mockFetch)) { + expect(rawUrl.length).toBeLessThanOrEqual(MAX_URL_LENGTH) + } + }) + + test('splitting and the db-max-rows cap compose: a chunk larger than the cap still pages', async () => { + const ids = idsExceedingLength(MAX_URL_LENGTH * 1.5) + const fixture = ids.map((id) => ({ id })) + // Small enough that each chunk (hundreds to low thousands of ids) needs + // several pages, but not so small that the paging loop needs thousands of + // requests to get through a chunk. + const cap = 100 + const mockFetch = makePaginatingFetch(fixture, { cap }) + + const rows = await run(mockFetch, ids) + + const returned = (rows as Array<{ id: number }>).map((r) => r.id) + expect(returned.sort((a, b) => a - b)).toEqual(ids) + expect(new Set(returned).size).toBe(ids.length) + const searches = getSearches(mockFetch) + // More requests than there are chunks: each chunk's own paging loop ran. + expect(searches.length).toBeGreaterThan(2) + }) + + test('one failing chunk rejects the load and aborts its sibling requests', async () => { + const ids = idsExceedingLength(MAX_URL_LENGTH * 3) + // Any id lands in exactly one chunk (chunks are disjoint slices of the + // sorted list), so failing whichever chunk holds this one exercises the + // abort path without depending on how many chunks came out. + const failId = ids[0]! + let abortedCount = 0 + + const failingFetch = vi + .fn() + .mockImplementation((input, init) => { + const params = new URL(String(input)).searchParams + const idFilter = params.get('id') ?? '' + const members = idFilter + .replace(/^in\.\(/, '') + .replace(/\)$/, '') + .split(',') + .map(Number) + // The chunk holding `failId` fails fast; every other chunk is slow + // enough that the abort raised by the failure reaches it first. + const isFailingChunk = members.includes(failId) + const signal = init?.signal as AbortSignal | undefined + + return new Promise((resolve, reject) => { + const settle = () => { + if (isFailingChunk) { + resolve( + new Response(JSON.stringify({ message: 'boom' }), { + status: 500, + headers: { 'content-type': 'application/json' }, + }), + ) + return + } + resolve( + new Response(JSON.stringify([]), { + status: 200, + headers: { + 'content-type': 'application/json', + 'content-range': '*/0', + }, + }), + ) + } + const timer = setTimeout(settle, isFailingChunk ? 0 : 50) + signal?.addEventListener('abort', () => { + clearTimeout(timer) + abortedCount += 1 + reject(new DOMException('Aborted', 'AbortError')) + }) + }) + }) + + await expect(run(failingFetch, ids)).rejects.toBeDefined() + // Give the aborted siblings' rejection handlers a turn to run. + await new Promise((resolve) => setTimeout(resolve, 60)) + expect(abortedCount).toBeGreaterThan(0) + }) + + test("concurrency never exceeds the fan-out's concurrency cap", async () => { + // MAX_CONCURRENT_CHUNKS (src/functions.ts) is 6; size the list well past + // that so the cap actually binds instead of every chunk fitting in one + // wave. + const ids = idsExceedingLength(MAX_URL_LENGTH * 10) + const fixture = ids.map((id) => ({ id })) + const base = makePaginatingFetch(fixture) + + let active = 0 + let peak = 0 + const trackedFetch = vi.fn(async (input, init) => { + active += 1 + peak = Math.max(peak, active) + // Yield so overlapping calls actually overlap instead of resolving + // synchronously one at a time. + await new Promise((resolve) => setTimeout(resolve, 5)) + try { + return await base(input, init) + } finally { + active -= 1 + } + }) + + const rows = await run(trackedFetch, ids) + + expect((rows as Array<{ id: number }>).length).toBe(ids.length) + const searches = getSearches(trackedFetch) + // Sizing above actually produced more chunks than the concurrency cap. + expect(searches.length).toBeGreaterThan(6) + // MAX_CONCURRENT_CHUNKS in src/functions.ts. + expect(peak).toBeLessThanOrEqual(6) + // The cap should actually bind here — otherwise this test would not have + // exercised the concurrency limiter at all. + expect(peak).toBeGreaterThan(1) + }) + + test('an unsplittable not(in) keeps the subset oversized: one request, not one per value', async () => { + const ids = Array.from({ length: 10 }, (_, i) => i + 1) + const hugeExcluded = Array.from({ length: 2000 }, (_, i) => `other-${i}`) + const where = and( + inArray(idRef, ids), + not(inArray(new IR.PropRef(['other']), hugeExcluded)), + ) + // Precondition: the unsplit URL is over budget because of the `not(in)`. + expect( + BASE_URL_LENGTH + + loadSubsetOptionsToSearch({ + where, + } as unknown as LoadSubsetOptions).toString().length, + ).toBeGreaterThan(MAX_URL_LENGTH) + const mockFetch = makePaginatingFetch(ids.map((id) => ({ id }))) + + const rows = await runWhere(mockFetch, where) + + expect((rows as Array<{ id: number }>).length).toBe(ids.length) + // Splitting the small `id` list cannot shrink the URL, so the subset goes + // out as-is, as a single request. + expect(getSearches(mockFetch)).toHaveLength(1) + }) + + test('a chunk packed to exactly the URL limit stays within it (the `?` counts)', async () => { + const ids = idsPackedTo(MAX_URL_LENGTH) + const mockFetch = makePaginatingFetch(ids.map((id) => ({ id }))) + + const rows = await run(mockFetch, ids) + + expect((rows as Array<{ id: number }>).length).toBe(ids.length) + const rawUrls = getRawUrls(mockFetch) + // The list was split, and one chunk measures exactly MAX_URL_LENGTH + // without its `?`. + expect(rawUrls.length).toBeGreaterThan(1) + for (const rawUrl of rawUrls) { + expect(rawUrl.length).toBeLessThanOrEqual(MAX_URL_LENGTH) + } + }) + + test("paging a packed chunk keeps every page's URL, with offset and limit, within the limit", async () => { + // One below the limit, so the first page's URL (with its `?`) is exactly + // at it; later pages then add `&offset=...&limit=...` on top. + const ids = idsPackedTo(MAX_URL_LENGTH - 1) + const mockFetch = makePaginatingFetch( + ids.map((id) => ({ id })), + { cap: 100 }, + ) + + const rows = await run(mockFetch, ids) + + expect((rows as Array<{ id: number }>).length).toBe(ids.length) + const rawUrls = getRawUrls(mockFetch) + // Pages past the first really were requested. + expect(rawUrls.some((rawUrl) => rawUrl.includes('offset='))).toBe(true) + for (const rawUrl of rawUrls) { + expect(rawUrl.length).toBeLessThanOrEqual(MAX_URL_LENGTH) + } + }) + + test("splitting and the key-order tiebreak compose: every page's URL, with the tiebreak, stays within the limit", async () => { + // Long key columns make the tiebreak order a large part of every paged + // URL, far wider than the slack the widest-offset measurement leaves, so a + // budget that ignored the tiebreak would send over-long page requests. + const keys = ['organization_identifier_column', 'id'] + const ids = idsExceedingLength(MAX_URL_LENGTH * 1.5) + const fixture = ids.map((id) => ({ + id, + organization_identifier_column: 1, + rank: id % 3, + })) + const mockFetch = makePaginatingFetch(fixture, { cap: 100 }) + + const rows = await supabaseQueryFn<{ id: number }>( + createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }), + 'items', + { + client: new QueryClient(), + queryKey: ['items'], + signal: new AbortController().signal, + meta: { + loadSubsetOptions: { + where: inArray(idRef, ids), + orderBy: [ + { + expression: new IR.PropRef(['rank']), + compareOptions: { + direction: 'asc' as const, + nulls: 'last' as const, + }, + }, + ], + }, + } as never, + }, + { keys }, + ) + + // Every matching row comes back exactly once. + expect(rows.map((row) => row.id).sort((a, b) => a - b)).toEqual(ids) + const searches = getSearches(mockFetch) + // The list was split, and its chunks paged past the cap. + const pagedSearches = searches.filter((search) => + search.includes('offset='), + ) + expect(pagedSearches.length).toBeGreaterThan(1) + // Multi-page chunks are read in key order after the query's own order. + for (const search of pagedSearches) { + expect(search).toContain( + 'order=rank.asc,organization_identifier_column.asc,id.asc', + ) + } + for (const rawUrl of getRawUrls(mockFetch)) { + expect(rawUrl.length).toBeLessThanOrEqual(MAX_URL_LENGTH) + } + }) +}) diff --git a/packages/supabase-db-collection/tests/split-load-subset-options.test.ts b/packages/supabase-db-collection/tests/split-load-subset-options.test.ts new file mode 100644 index 0000000000..1f0fedcabe --- /dev/null +++ b/packages/supabase-db-collection/tests/split-load-subset-options.test.ts @@ -0,0 +1,284 @@ +import { IR, and, eq, gt, inArray, not, or } from '@tanstack/db' +import { describe, expect, test } from 'vitest' +import { + cursorCurrentToSearch, + loadSubsetOptionsToSearch, + splitLoadSubsetOptions, +} from '../src/postgrest-filters' +import { flattenAnd } from '../src/postgrest-filters/common' +import type { LoadSubsetOptions } from '@tanstack/db' + +// A short stand-in for `supabase.from(table).url`; only its length matters. +const BASE_URL = 'http://localhost:54321/rest/v1/items' + +const id = new IR.PropRef(['id']) +const other = new IR.PropRef(['other']) +const active = new IR.PropRef(['active']) + +// A simplified `measureSubset` (src/functions.ts) without the real supabase +// client: renders the same query strings the adapter would send and measures +// them, leaving out the `?` and the paging params the real one also counts. +const measure = (options: LoadSubsetOptions): number => { + const mainLength = + BASE_URL.length + loadSubsetOptionsToSearch(options).toString().length + const tiesSearch = cursorCurrentToSearch(options) + return tiesSearch + ? Math.max(mainLength, BASE_URL.length + tiesSearch.toString().length) + : mainLength +} + +const split = (options: LoadSubsetOptions, maxUrlLength: number) => + splitLoadSubsetOptions(options, { maxUrlLength, measure }) + +// Every chunk's rendered URL (main request, plus the tie request when the +// subset has a cursor) must fit the budget. +const expectEveryChunkFits = ( + chunks: Array, + maxUrlLength: number, +) => { + for (const chunk of chunks) { + expect(measure(chunk)).toBeLessThanOrEqual(maxUrlLength) + } +} + +// Collects the values of every top-level `in(ref, [...])` conjunct matching +// `path`, across every chunk — the union a caller reconstructs by +// concatenating each chunk's rows. +const inValuesFor = ( + chunks: Array, + path: Array, +): Array => + chunks.flatMap((chunk) => { + if (!chunk.where) return [] + return flattenAnd(chunk.where).flatMap((expr) => { + if (expr.type !== 'func' || expr.name !== 'in') return [] + const [left, right] = expr.args + if ( + left?.type !== 'ref' || + JSON.stringify(left.path) !== JSON.stringify(path) || + right?.type !== 'val' || + !Array.isArray(right.value) + ) { + return [] + } + return right.value + }) + }) + +describe('splitLoadSubsetOptions', () => { + test('returns the identical object when the subset already fits', () => { + const options: LoadSubsetOptions = { where: inArray(id, [1, 2, 3]) } + const result = split(options, 8000) + expect(result).toEqual([options]) + expect(result[0]).toBe(options) + }) + + test('splits string ids with commas and quotes, and Dates, so every chunk fits', () => { + const values = [ + 'Alice, "A"', + 'Bob (the builder)', + 'back\\slash', + new Date('2024-01-01T00:00:00.000Z'), + new Date('2024-06-15T12:30:00.000Z'), + 'plain', + 'another, one', + ] + const options: LoadSubsetOptions = { where: inArray(id, values) } + const maxUrlLength = BASE_URL.length + 60 + const chunks = split(options, maxUrlLength) + + expect(chunks.length).toBeGreaterThan(1) + expectEveryChunkFits(chunks, maxUrlLength) + expect(new Set(inValuesFor(chunks, ['id']))).toEqual(new Set(values)) + }) + + test('the union of chunk values equals the deduped, null-free input', () => { + const values = [1, 2, 3, null, 2, 4, 5, null, 6, 7, 8, 9, 10] + const options: LoadSubsetOptions = { where: inArray(id, values) } + const maxUrlLength = BASE_URL.length + 30 + const chunks = split(options, maxUrlLength) + + expect(chunks.length).toBeGreaterThan(1) + expectEveryChunkFits(chunks, maxUrlLength) + const expected = new Set(values.filter((v) => v != null)) + expect(new Set(inValuesFor(chunks, ['id']))).toEqual(expected) + }) + + test('leaves a top-level not(in) unsplit', () => { + const values = Array.from({ length: 200 }, (_, i) => `id-${i}`) + const options: LoadSubsetOptions = { where: not(inArray(id, values)) } + const result = split(options, BASE_URL.length + 20) + expect(result).toEqual([options]) + expect(result[0]).toBe(options) + }) + + test('leaves an IN nested inside OR unsplit', () => { + const values = Array.from({ length: 200 }, (_, i) => `id-${i}`) + const options: LoadSubsetOptions = { + where: or(inArray(id, values), eq(active, true)), + } + const result = split(options, BASE_URL.length + 20) + expect(result).toEqual([options]) + expect(result[0]).toBe(options) + }) + + test('sends a subset as-is when an unsplittable not(in) keeps it oversized, even with a small top-level IN', () => { + const smallIds = Array.from({ length: 10 }, (_, i) => `id-${i}`) + const hugeExcluded = Array.from({ length: 2000 }, (_, i) => `other-${i}`) + const options: LoadSubsetOptions = { + where: and(inArray(id, smallIds), not(inArray(other, hugeExcluded))), + } + const maxUrlLength = 8000 + // Precondition: the subset really is oversized, and stays oversized for any + // single `id` value because of the `not(in)` alone. + expect(measure(options)).toBeGreaterThan(maxUrlLength) + + const result = split(options, maxUrlLength) + + // Splitting `id` cannot make this fit, so it must not fan out one request + // per value: the subset is sent as-is. + expect(result).toHaveLength(1) + expect(result[0]).toBe(options) + }) + + test('sends a subset as-is when an IN nested in OR keeps it oversized, even with a small top-level IN', () => { + const smallIds = Array.from({ length: 10 }, (_, i) => `id-${i}`) + const hugeNested = Array.from({ length: 2000 }, (_, i) => `other-${i}`) + const options: LoadSubsetOptions = { + where: and( + inArray(id, smallIds), + or(inArray(other, hugeNested), eq(active, true)), + ), + } + const maxUrlLength = 8000 + expect(measure(options)).toBeGreaterThan(maxUrlLength) + + const result = split(options, maxUrlLength) + + expect(result).toHaveLength(1) + expect(result[0]).toBe(options) + }) + + test('an unsplittable subset (no where) returns [options] unchanged', () => { + // Nothing to split, yet still "too long" per the fake budget: the + // splitter must not loop or throw, just hand the request back as-is. + const options: LoadSubsetOptions = {} + const result = split(options, -1) + expect(result).toEqual([options]) + expect(result[0]).toBe(options) + }) + + describe('limit/offset/cursor rewriting', () => { + const values = Array.from({ length: 100 }, (_, i) => i) + // Room for about ten values per chunk, so the list must split. + const budgetFor = (options: LoadSubsetOptions) => + measure({ ...options, where: inArray(id, values.slice(0, 10)) }) + + test('keeps limit unchanged and does not touch offset when a cursor is present', () => { + const options: LoadSubsetOptions = { + where: inArray(id, values), + limit: 20, + cursor: { whereFrom: gt(id, 5), whereCurrent: eq(id, 5) }, + } + const chunks = split(options, budgetFor(options)) + + expect(chunks.length).toBeGreaterThan(1) + for (const chunk of chunks) { + expect(chunk.limit).toBe(20) + expect(chunk.cursor).toBe(options.cursor) + } + }) + + test('folds offset into limit and drops offset when there is no cursor', () => { + const options: LoadSubsetOptions = { + where: inArray(id, values), + limit: 10, + offset: 5, + } + const chunks = split(options, budgetFor(options)) + + expect(chunks.length).toBeGreaterThan(1) + for (const chunk of chunks) { + expect(chunk.limit).toBe(15) + expect(chunk.offset).toBeUndefined() + } + }) + + test('drops offset without adding a limit when the caller had none', () => { + const options: LoadSubsetOptions = { + where: inArray(id, values), + offset: 5, + } + const chunks = split(options, budgetFor(options)) + + expect(chunks.length).toBeGreaterThan(1) + for (const chunk of chunks) { + expect(chunk.limit).toBeUndefined() + expect(chunk.offset).toBeUndefined() + } + }) + }) + + test('recurses into the next-largest IN when the largest alone cannot shrink enough', () => { + const idValues = Array.from({ length: 60 }, (_, i) => `id-${i}`) + const otherValues = Array.from({ length: 60 }, (_, i) => `other-${i}`) + const options: LoadSubsetOptions = { + where: and(inArray(id, idValues), inArray(other, otherValues)), + } + // Small enough that even a single `id` value alongside the full `other` + // list does not fit, forcing a split of `other` first. + const maxUrlLength = BASE_URL.length + 80 + const chunks = split(options, maxUrlLength) + + expect(chunks.length).toBeGreaterThan(1) + expectEveryChunkFits(chunks, maxUrlLength) + expect(new Set(inValuesFor(chunks, ['id']))).toEqual(new Set(idValues)) + expect(new Set(inValuesFor(chunks, ['other']))).toEqual( + new Set(otherValues), + ) + + // Every original (id, other) pair is covered by exactly one chunk's + // cartesian product, and chunks stay disjoint on both split columns. + const pairs = new Set() + for (const chunk of chunks) { + const chunkIds = inValuesFor([chunk], ['id']) + const chunkOthers = inValuesFor([chunk], ['other']) + for (const a of chunkIds) { + for (const b of chunkOthers) { + pairs.add(`${a}|${b}`) + } + } + } + expect(pairs.size).toBe(idValues.length * otherValues.length) + // Disjoint: no pair is fetched by more than one chunk. + const chunkPairCount = chunks.reduce( + (sum, chunk) => + sum + + inValuesFor([chunk], ['id']).length * + inValuesFor([chunk], ['other']).length, + 0, + ) + expect(chunkPairCount).toBe(pairs.size) + }) + + test('shrinks the next-largest IN against a single value of the largest, not its full list', () => { + const idValues = Array.from({ length: 300 }, (_, i) => `id-${i}`) + const otherValues = Array.from({ length: 300 }, (_, i) => `other-${i}`) + const options: LoadSubsetOptions = { + where: and(inArray(id, idValues), inArray(other, otherValues)), + } + // Neither full list fits alongside the other, but half of `other` does. + // Measuring `other`'s split against the full `id` list would shrink it to + // one value per chunk (~600 requests); measuring against one `id` value + // keeps it to a handful of `other` slices. + const maxUrlLength = BASE_URL.length + 2000 + const chunks = split(options, maxUrlLength) + + expectEveryChunkFits(chunks, maxUrlLength) + expect(new Set(inValuesFor(chunks, ['id']))).toEqual(new Set(idValues)) + expect(new Set(inValuesFor(chunks, ['other']))).toEqual( + new Set(otherValues), + ) + expect(chunks.length).toBeLessThan(150) + }) +}) diff --git a/packages/supabase-db-collection/tests/sync-mode.test.ts b/packages/supabase-db-collection/tests/sync-mode.test.ts new file mode 100644 index 0000000000..c184e18c59 --- /dev/null +++ b/packages/supabase-db-collection/tests/sync-mode.test.ts @@ -0,0 +1,183 @@ +import { createClient } from '@supabase/supabase-js' +import { + createCollection, + createLiveQueryCollection, + eq, + gt, +} from '@tanstack/db' +import { QueryClient } from '@tanstack/query-core' +import { afterEach, describe, expect, test, vi } from 'vitest' +import { z } from 'zod' +import { supabaseCollectionOptions } from '../src/index' +import { getSearches, makePaginatingFetch } from './pagination.utils' +import { + SUPABASE_KEY, + SUPABASE_URL, + createMockChannel, + createMockFetch, + createRealtimeUsersCollection, + filtersFor, +} from './test.utils' + +const itemsSchema = z.object({ id: z.number(), rank: z.number() }) + +const ROWS = [ + { id: 1, rank: 10 }, + { id: 2, rank: 20 }, + { id: 3, rank: 30 }, + { id: 4, rank: 40 }, + { id: 5, rank: 50 }, +] + +const cleanups: Array<() => void | Promise> = [] + +afterEach(async () => { + for (const cleanup of cleanups.splice(0).reverse()) { + await cleanup() + } +}) + +function makeItemsCollection( + mockFetch: ReturnType, + syncMode?: 'on-demand' | 'eager', +) { + const queryClient = new QueryClient() + const collection = createCollection( + supabaseCollectionOptions({ + tableName: 'items', + keys: ['id'], + schema: itemsSchema, + supabase: createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }), + queryClient, + syncMode, + }), + ) + cleanups.push(() => collection.cleanup()) + return { collection, queryClient } +} + +describe('syncMode: eager', () => { + test('fetches the whole table when the collection starts, paging past the server cap', async () => { + const mockFetch = makePaginatingFetch(ROWS, { cap: 2 }) + const { collection } = makeItemsCollection(mockFetch, 'eager') + + await collection.preload() + + expect(collection.size).toBe(ROWS.length) + // No subset params at all: no where/limit. The first read only sizes the + // server cap; because more pages follow, they are read again ordered by the + // key (the table is unordered, and offset paging needs a total order), with + // the offset advancing by the rows received on each page. + expect(getSearches(mockFetch)).toEqual([ + 'select=*', + 'select=*&order=id.asc&offset=0&limit=2', + 'select=*&order=id.asc&offset=2&limit=2', + 'select=*&order=id.asc&offset=4&limit=1', + ]) + }) + + test('requests count=exact on the first page only', async () => { + const mockFetch = makePaginatingFetch(ROWS, { cap: 2 }) + const { collection } = makeItemsCollection(mockFetch, 'eager') + + await collection.preload() + + const prefers = mockFetch.mock.calls.map((call) => + new Headers(call[1]?.headers).get('prefer'), + ) + expect(prefers[0]).toContain('count=exact') + for (const prefer of prefers.slice(1)) { + expect(prefer ?? '').not.toContain('count=') + } + }) + + test('live queries filter locally without issuing further requests', async () => { + const mockFetch = makePaginatingFetch(ROWS) + const { collection } = makeItemsCollection(mockFetch, 'eager') + + const live = createLiveQueryCollection((q) => + q.from({ item: collection }).where(({ item }) => gt(item.id, 3)), + ) + cleanups.push(() => live.cleanup()) + await live.preload() + + expect(live.toArray.map((item) => item.id).sort()).toEqual([4, 5]) + // Only the single eager fetch: the where clause is not pushed to PostgREST. + expect(getSearches(mockFetch)).toEqual(['select=*']) + }) + + test('keys the query by table name alone, whatever the live queries ask for', async () => { + const mockFetch = makePaginatingFetch(ROWS) + const { collection, queryClient } = makeItemsCollection(mockFetch, 'eager') + + const live = createLiveQueryCollection((q) => + q.from({ item: collection }).where(({ item }) => eq(item.id, 2)), + ) + cleanups.push(() => live.cleanup()) + await live.preload() + + expect( + queryClient + .getQueryCache() + .getAll() + .map((query) => query.queryKey), + ).toEqual([['items']]) + }) + + test('mutations write through without refetching the table', async () => { + const mockFetch = makePaginatingFetch(ROWS) + const { collection } = makeItemsCollection(mockFetch, 'eager') + await collection.preload() + + const tx = collection.insert({ id: 6, rank: 60 }) + await tx.when('settled') + + expect(collection.get('6')).toMatchObject({ id: 6, rank: 60 }) + expect(getSearches(mockFetch)).toEqual(['select=*']) + }) + + test('on-demand remains the default: the where clause is pushed to PostgREST', async () => { + const mockFetch = makePaginatingFetch(ROWS) + const { collection, queryClient } = makeItemsCollection(mockFetch) + + const live = createLiveQueryCollection((q) => + q.from({ item: collection }).where(({ item }) => gt(item.id, 3)), + ) + cleanups.push(() => live.cleanup()) + await live.preload() + + expect(getSearches(mockFetch)).toEqual(['select=*&id=gt.3']) + expect( + queryClient + .getQueryCache() + .getAll() + .map((query) => query.queryKey), + ).toEqual([['items', 'id=gt.3']]) + }) + + describe('realtime', () => { + test('subscribes to every change on the table even when filters are enabled', async () => { + const mockFetch = createMockFetch() + const mockChannel = createMockChannel() + const { collection } = createRealtimeUsersCollection( + mockFetch, + mockChannel, + { realtimeUseFilter: true, syncMode: 'eager' }, + ) + cleanups.push(() => collection.cleanup()) + + const live = createLiveQueryCollection((q) => + q.from({ user: collection }).where(({ user }) => eq(user.id, 1)), + ) + cleanups.push(() => live.cleanup()) + await live.preload() + await vi.waitFor(() => expect(mockChannel.on).toHaveBeenCalled()) + + expect(filtersFor(mockChannel, 'INSERT')).toEqual([null]) + expect(filtersFor(mockChannel, 'UPDATE')).toEqual([null]) + expect(filtersFor(mockChannel, 'DELETE')).toEqual([null]) + }) + }) +}) diff --git a/packages/supabase-db-collection/tests/test.utils.ts b/packages/supabase-db-collection/tests/test.utils.ts new file mode 100644 index 0000000000..0e26baaab7 --- /dev/null +++ b/packages/supabase-db-collection/tests/test.utils.ts @@ -0,0 +1,296 @@ +import { createClient } from '@supabase/supabase-js' +import { createCollection, liveQueryCollectionOptions } from '@tanstack/db' +import { QueryClient } from '@tanstack/query-core' +import { expect, vi } from 'vitest' +import { z } from 'zod' +import { supabaseCollectionOptions } from '../src/index' + +// --- Schemas --- + +export const usersSchema = z.object({ + id: z.number(), + name: z.string(), + email: z.string(), + active: z.boolean(), +}) + +export const usersTodosSchema = z.object({ + user_id: z.number(), + todo_id: z.number(), +}) + +export const todosSchema = z.object({ + id: z.number(), + title: z.string(), + description: z.string(), + completed: z.boolean(), +}) + +// --- Mock infrastructure --- + +export const SUPABASE_URL = 'http://localhost:54321' +export const SUPABASE_KEY = 'test-key' + +export const mockResponses: Record> = { + users: [ + { id: 'user_1', name: 'Alice', email: 'alice@test.com', active: true }, + ], + users_todos: [{ user_id: 'user_1', todo_id: 'todo_1' }], + todos: [ + { + id: 'todo_1', + title: 'Buy milk', + description: 'From the store', + completed: false, + }, + ], +} + +export function createMockFetch() { + return vi.fn().mockImplementation((input, init) => { + const url = new URL(typeof input === 'string' ? input : input.toString()) + const table = url.pathname.replace('/rest/v1/', '') + const method = init?.method ?? 'GET' + + // For insert/update requests, echo the request body back as the + // "representation" so `.select().single()` has something schema-shaped + // to parse, mirroring what PostgREST would return. + if (method === 'POST' || method === 'PATCH') { + const body = init?.body ? JSON.parse(init.body as string) : {} + return Promise.resolve( + new Response(JSON.stringify(body), { + status: 200, + headers: { 'content-type': 'application/json' }, + }), + ) + } + + const all = mockResponses[table] ?? [] + // Honour offset/limit so the pagination loop's follow-up pages terminate + // (a page past the data returns empty) instead of re-serving the same rows. + const params = url.searchParams + const offset = params.get('offset') ? Number(params.get('offset')) : 0 + const limit = params.get('limit') + const rows = all.slice( + offset, + limit === null ? undefined : offset + Number(limit), + ) + const end = offset + rows.length - 1 + return Promise.resolve( + new Response(JSON.stringify(rows), { + status: 200, + headers: { + 'content-type': 'application/json', + // The loop reads the total off Content-Range to size its paging; the + // format mirrors PostgREST's `-/`. + 'content-range': rows.length + ? `${offset}-${end}/${all.length}` + : `*/${all.length}`, + }, + }), + ) + }) +} + +/** Extract the headers of a captured `fetch` call as a `Headers` instance. */ +export function getRequestHeaders( + mockFetch: ReturnType, + callIndex = 0, +): Headers { + const init = mockFetch.mock.calls[callIndex]?.[1] + return new Headers(init?.headers) +} + +export function createMockedUsersCollection(mockFetch: typeof fetch) { + return createCollection( + supabaseCollectionOptions({ + tableName: 'users', + keys: ['id'], + schema: usersSchema, + supabase: createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }), + }), + ) +} + +export function createMockedUsersTodosCollection(mockFetch: typeof fetch) { + return createCollection( + supabaseCollectionOptions({ + tableName: 'users_todos', + keys: ['user_id', 'todo_id'], + schema: usersTodosSchema, + supabase: createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }), + }), + ) +} + +export function createMockedTodosCollection(mockFetch: typeof fetch) { + return createCollection( + supabaseCollectionOptions({ + tableName: 'todos', + keys: ['id'], + schema: todosSchema, + supabase: createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }), + }), + ) +} + +// --- Realtime mock infrastructure --- + +type MockChannelOnCall = { + type: string + config: { event: string; schema: string; table: string; filter?: string } + handler: (payload: any) => void +} + +export type MockChannel = { + onCalls: Array + on: ReturnType + subscribe: ReturnType + /** + * Reports a subscription status (SUBSCRIBED by default) when the channel was + * created with `autoSubscribe: false`. + */ + confirmSubscribed: (status?: string) => void +} + +export function createMockChannel({ + autoSubscribe = true, +}: { + autoSubscribe?: boolean +} = {}): MockChannel { + const onCalls: Array = [] + let pending: ((status: string) => void) | undefined + + const channel: MockChannel = { + onCalls, + on: vi.fn((type: string, config: any, handler: (payload: any) => void) => { + onCalls.push({ type, config, handler }) + return channel + }), + // The adapter drives channel swaps and the rejection fallback off the + // subscription status, so the mock reports one like the real channel does. + subscribe: vi.fn((callback?: (status: string) => void) => { + if (autoSubscribe) { + callback?.('SUBSCRIBED') + } else { + pending = callback + } + return channel + }), + confirmSubscribed: (status = 'SUBSCRIBED') => { + pending?.(status) + pending = undefined + }, + } + return channel +} + +/** Returns the postgres_changes listeners registered for a given event. */ +export function listenersFor(mockChannel: MockChannel, event: string) { + return mockChannel.onCalls.filter((call) => call.config.event === event) +} + +/** The filter strings of a given event's listeners (null when unfiltered). */ +export function filtersFor( + mockChannel: MockChannel, + event: string, +): Array { + return listenersFor(mockChannel, event).map( + (call) => call.config.filter ?? null, + ) +} + +/** Dispatches a payload to every listener registered for its event type. */ +export function emit(mockChannel: MockChannel, payload: any) { + for (const call of listenersFor(mockChannel, payload.eventType)) { + call.handler(payload) + } +} + +export function createRealtimeUsersCollection( + mockFetch: typeof fetch, + mockChannel: MockChannel | (() => MockChannel), + options: { + realtimeUseFilter?: boolean + syncMode?: 'on-demand' | 'eager' + } = {}, +) { + // A fresh QueryClient keeps the module-level realtime registry in db.ts + // isolated per test. + const queryClient = new QueryClient() + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + // The real client would open a live WebSocket, so stub the realtime surface. + supabase.channel = vi.fn(() => + typeof mockChannel === 'function' ? mockChannel() : mockChannel, + ) as unknown as typeof supabase.channel + supabase.removeChannel = vi.fn() as unknown as typeof supabase.removeChannel + + const collection = createCollection( + supabaseCollectionOptions({ + tableName: 'users', + keys: ['id'], + schema: usersSchema, + supabase, + realtime: true, + realtimeUseFilter: options.realtimeUseFilter, + syncMode: options.syncMode, + queryClient, + }), + ) + + return { collection, supabase, queryClient } +} + +// --- Query helpers --- + +export async function queryResult( + queryFn: Parameters[0]['query'], +) { + const opts = liveQueryCollectionOptions({ query: queryFn }) + const collection = createCollection( + opts as Extract, + ) + await collection.preload() + const data = await collection.toArrayWhenReady() + collection.cleanup() + return data +} + +// --- Assertion helpers --- + +export function normalizeFetchUrl(raw: string | URL | Request): string { + const url = new URL(typeof raw === 'string' ? raw : raw.toString()) + url.searchParams.sort() + return `${url.pathname}${decodeURIComponent(url.search)}` +} + +export function expectFetchUrls( + mockFetch: ReturnType, + expectedPaths: Array, +) { + const actual = mockFetch.mock.calls.map(([url]) => normalizeFetchUrl(url)) + const expected = expectedPaths.map((p) => + normalizeFetchUrl(new URL(p, SUPABASE_URL)), + ) + expect([...actual]).toEqual([...expected]) +} + +/** + * Index into an array, failing loudly when the element is missing. Keeps test + * assertions concise under `noUncheckedIndexedAccess`. + */ +export function nth(items: ReadonlyArray, index: number): T { + const item = items[index] + if (item === undefined) { + throw new Error(`Expected an element at index ${index}`) + } + return item +} diff --git a/packages/supabase-db-collection/tsconfig.docs.json b/packages/supabase-db-collection/tsconfig.docs.json new file mode 100644 index 0000000000..5a73feb023 --- /dev/null +++ b/packages/supabase-db-collection/tsconfig.docs.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "paths": { + "@tanstack/db": ["../db/src"] + } + }, + "include": ["src"] +} diff --git a/packages/supabase-db-collection/tsconfig.json b/packages/supabase-db-collection/tsconfig.json new file mode 100644 index 0000000000..9e639d56a7 --- /dev/null +++ b/packages/supabase-db-collection/tsconfig.json @@ -0,0 +1,24 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "target": "ES2020", + "module": "ESNext", + "lib": ["ES2024", "DOM"], + "moduleResolution": "Bundler", + "declaration": true, + "outDir": "dist", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "jsx": "react", + "paths": { + "@tanstack/store": ["../store/src"], + "@tanstack/db-ivm": ["../db-ivm/src"], + "@tanstack/db": ["../db/src"], + "@tanstack/query-db-collection": ["../query-db-collection/src"] + } + }, + "include": ["src", "tests", "vite.config.ts"], + "exclude": ["node_modules", "dist"] +} diff --git a/packages/supabase-db-collection/vite.config.ts b/packages/supabase-db-collection/vite.config.ts new file mode 100644 index 0000000000..ac93446e74 --- /dev/null +++ b/packages/supabase-db-collection/vite.config.ts @@ -0,0 +1,33 @@ +import { defineConfig, mergeConfig } from 'vitest/config' +import { tanstackViteConfig } from '@tanstack/vite-config' +import packageJson from './package.json' + +const config = defineConfig({ + // Inlines the published version at build time (and under vitest) so the + // `X-Client-Info` header can never drift from package.json. + define: { + __SUPABASE_DB_COLLECTION_VERSION__: JSON.stringify(packageJson.version), + }, + test: { + name: packageJson.name, + include: [`tests/**/*.test.ts`], + exclude: [`e2e/**/*`], + // Not jsdom: `isServer` from query-core is false under jsdom, which makes + // `getQueryClient()` hand every collection the same module-level + // QueryClient, so cached queries leak between tests. + environment: `node`, + coverage: { enabled: true, provider: `istanbul`, include: [`src/**/*`] }, + typecheck: { + enabled: true, + include: [`tests/**/*.test.ts`, `tests/**/*.test-d.ts`], + }, + }, +}) + +export default mergeConfig( + config, + tanstackViteConfig({ + entry: `./src/index.ts`, + srcDir: `./src`, + }), +) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 760d4bd295..55aa01e17f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1767,6 +1767,37 @@ importers: specifier: ^5.0.5 version: 5.0.5(@types/node@25.2.2)(@vitest/coverage-istanbul@5.0.5)(@vitest/ui@5.0.5)(jsdom@27.4.0)(vite@8.3.5(@types/node@25.2.2)(esbuild@0.28.1)(jiti@2.7.0)(sass@1.90.0)(terser@5.51.2)(tsx@4.21.0)(yaml@2.8.1)) + packages/supabase-db-collection: + dependencies: + '@standard-schema/spec': + specifier: ^1.1.0 + version: 1.1.0 + '@supabase/postgrest-js': + specifier: ^2.107.0 + version: 2.119.0 + '@tanstack/db': + specifier: workspace:* + version: link:../db + '@tanstack/query-db-collection': + specifier: workspace:* + version: link:../query-db-collection + typescript: + specifier: '>=4.7' + version: 5.9.3 + devDependencies: + '@supabase/supabase-js': + specifier: ^2.107.0 + version: 2.119.0 + '@tanstack/query-core': + specifier: ^5.90.20 + version: 5.90.20 + '@vitest/coverage-istanbul': + specifier: ^5.0.5 + version: 5.0.5(vitest@5.0.5) + zod: + specifier: ^4.6.7 + version: 4.6.7 + packages/svelte-db: dependencies: '@tanstack/db': @@ -6331,6 +6362,38 @@ packages: peerDependencies: eslint: '>=9.0.0' + '@supabase/auth-js@2.119.0': + resolution: {integrity: sha512-WI7KqJRxqZjm77PlRO/VfKretL4SG8g8stWfBmpyx9To+fFapZlSbXA8QkduoMvr72rRpIF24ZLrjktBrp+ZFA==} + engines: {node: '>=22.0.0'} + + '@supabase/functions-js@2.119.0': + resolution: {integrity: sha512-0aOdF/Y4lA+62K02nwZClfAthXmFEml0od42q3yy/9t3bBitomAOYEatTFSnxT/5UeeIDNn2DOnXTdAP0sqGNQ==} + engines: {node: '>=22.0.0'} + + '@supabase/phoenix@0.4.5': + resolution: {integrity: sha512-aAn9H9ovVyeApKy11OWOrrOGq8DV68yWeH4ud2lN9fzn4aO8Zb5GLL9m1pUg9nLqIcT+ZDfAcsZe0E/nqdv2lw==} + + '@supabase/postgrest-js@2.119.0': + resolution: {integrity: sha512-qBmcjEFO7Ptyf5qvOXYJa1s4bfA4zsMIFf2i+h2zd6RRTDLwquX8z1mnS9djNOJjbiO1OGFh5Y2Lc2k2pA8TMw==} + engines: {node: '>=22.0.0'} + + '@supabase/realtime-js@2.119.0': + resolution: {integrity: sha512-fPzxt+SAYweqsZUCSZma2dvN+HT6lVjwWj8BbkVwapW6wNf1odUi+ATYN7svX4Zm9vt0kz0l0VzINAUAA38FEg==} + engines: {node: '>=22.0.0'} + + '@supabase/storage-js@2.119.0': + resolution: {integrity: sha512-htx1dSCnSJVPlx2BNSgLSUDvLMxuGbYa6pUPl5xoCs4as4cIhBVwuxj78zbggCyPHxLnEXjsV/qvlDsVjpodKw==} + engines: {node: '>=22.0.0'} + + '@supabase/supabase-js@2.119.0': + resolution: {integrity: sha512-MKP49G6bJbPhvsZDegZ/IXS/ITApPgplDCF5+F65KZ5kIArS5Y90WFxwvWYALx2bsxdrSuHvkCiXHYr3dU8+sw==} + engines: {node: '>=22.0.0'} + peerDependencies: + '@opentelemetry/api': '>=1.0.0' + peerDependenciesMeta: + '@opentelemetry/api': + optional: true + '@sveltejs/acorn-typescript@1.0.13': resolution: {integrity: sha512-wgKggnhZVL9Bfx1OaKKTrYY9BFRk6C8UAkQNUcIv1+llzYrIqy+RZm5HPKzn0NpEBvTVhTqB4kQyllZywsRBRQ==} peerDependencies: @@ -9767,6 +9830,10 @@ packages: engines: {node: '>=18'} hasBin: true + iceberg-js@0.8.1: + resolution: {integrity: sha512-1dhVQZXhcHje7798IVM+xoo/1ZdVfzOMIc8/rgVSijRK38EDqOJoGula9N/8ZI5RD8QTxNQtK/Gozpr+qUqRRA==} + engines: {node: '>=20.0.0'} + iconv-lite@0.6.3: resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==} engines: {node: '>=0.10.0'} @@ -15174,7 +15241,7 @@ snapshots: jose: 6.2.12 kysely: 0.29.6 nanostores: 1.5.4 - zod: 4.6.6 + zod: 4.6.7 '@better-auth/drizzle-adapter@1.6.22(@better-auth/core@1.6.22(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.1)(better-call@1.3.7(zod@4.6.7))(jose@6.2.12)(kysely@0.29.6)(nanostores@1.5.4))(@better-auth/utils@0.4.2)(drizzle-orm@0.45.1(@op-engineering/op-sqlite@15.2.7(react-native@0.83.2(@babel/core@8.1.0)(@types/react@19.2.13)(react@19.2.4))(react@19.2.4))(@types/better-sqlite3@7.6.13)(@types/pg@8.16.0)(better-sqlite3@12.8.0)(expo-sqlite@57.0.3(expo@55.0.8)(react-native@0.83.2(@babel/core@8.1.0)(@types/react@19.2.13)(react@19.2.4))(react@19.2.4))(kysely@0.29.6)(pg@8.20.0)(postgres@3.4.8)(sql.js@1.14.1))': dependencies: @@ -19086,6 +19153,38 @@ snapshots: estraverse: 5.3.0 picomatch: 4.0.7 + '@supabase/auth-js@2.119.0': + dependencies: + tslib: 2.8.1 + + '@supabase/functions-js@2.119.0': + dependencies: + tslib: 2.8.1 + + '@supabase/phoenix@0.4.5': {} + + '@supabase/postgrest-js@2.119.0': + dependencies: + tslib: 2.8.1 + + '@supabase/realtime-js@2.119.0': + dependencies: + '@supabase/phoenix': 0.4.5 + tslib: 2.8.1 + + '@supabase/storage-js@2.119.0': + dependencies: + iceberg-js: 0.8.1 + tslib: 2.8.1 + + '@supabase/supabase-js@2.119.0': + dependencies: + '@supabase/auth-js': 2.119.0 + '@supabase/functions-js': 2.119.0 + '@supabase/postgrest-js': 2.119.0 + '@supabase/realtime-js': 2.119.0 + '@supabase/storage-js': 2.119.0 + '@sveltejs/acorn-typescript@1.0.13(acorn@8.18.0)': dependencies: acorn: 8.18.0 @@ -19526,7 +19625,7 @@ snapshots: jiti: 2.7.0 magic-string: 0.30.21 prettier: 3.9.9 - zod: 4.6.6 + zod: 4.6.7 transitivePeerDependencies: - supports-color @@ -19704,7 +19803,7 @@ snapshots: ufo: 1.6.4 vitefu: 1.1.3(vite@8.3.5(@types/node@25.2.2)(esbuild@0.25.11)(jiti@2.7.0)(sass@1.90.0)(terser@5.51.2)(tsx@4.21.0)(yaml@2.8.1)) xmlbuilder2: 4.0.3 - zod: 4.6.6 + zod: 4.6.7 optionalDependencies: vite: 8.3.5(@types/node@25.2.2)(esbuild@0.25.11)(jiti@2.7.0)(sass@1.90.0)(terser@5.51.2)(tsx@4.21.0)(yaml@2.8.1) transitivePeerDependencies: @@ -19743,7 +19842,7 @@ snapshots: ufo: 1.6.4 vitefu: 1.1.3(vite@8.3.5(@types/node@25.2.2)(esbuild@0.28.1)(jiti@2.7.0)(sass@1.90.0)(terser@5.51.2)(tsx@4.21.0)(yaml@2.8.1)) xmlbuilder2: 4.0.3 - zod: 4.6.6 + zod: 4.6.7 optionalDependencies: vite: 8.3.5(@types/node@25.2.2)(esbuild@0.28.1)(jiti@2.7.0)(sass@1.90.0)(terser@5.51.2)(tsx@4.21.0)(yaml@2.8.1) transitivePeerDependencies: @@ -23717,6 +23816,8 @@ snapshots: husky@9.1.7: {} + iceberg-js@0.8.1: {} + iconv-lite@0.6.3: dependencies: safer-buffer: 2.1.2 From 8b64aa4c17250c6ff793ede578abf09476447ec3 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Tue, 10 Nov 2026 12:32:56 +0100 Subject: [PATCH 02/13] fix(supabase-db-collection): encode composite keys unambiguously Joining composite key values with '-' gave distinct tuples the same collection key (['', '-'] and ['-', ''] both became '--'), so one row overwrote the other. Composite keys are now a JSON array of the values' string forms. Single-column keys are unchanged. A property test generates pairs of tuples cut from the same text and checks that keys are equal exactly when the tuples are; it fails on the '-' join. Co-Authored-By: Claude Opus 5.5 (1M context) --- packages/supabase-db-collection/src/db.ts | 9 ++- .../tests/collection-key.test.ts | 70 +++++++++++++++++++ 2 files changed, 76 insertions(+), 3 deletions(-) create mode 100644 packages/supabase-db-collection/tests/collection-key.test.ts diff --git a/packages/supabase-db-collection/src/db.ts b/packages/supabase-db-collection/src/db.ts index 4537b16abe..0298f813f7 100644 --- a/packages/supabase-db-collection/src/db.ts +++ b/packages/supabase-db-collection/src/db.ts @@ -137,10 +137,13 @@ export const supabaseCollectionOptions = ({ type TItem = StandardSchemaV1.InferOutput - // Derive the collection key from the configured key columns. The values are - // always joined into a string, so a single numeric `id` of 6 becomes `'6'`. + // Derive the collection key from the configured key columns. A single column + // keeps its string form (`6` becomes `'6'`). Composite keys encode each + // value's string form as a JSON array, so distinct tuples cannot share a key + // the way `'-'` joining let `['a-b', 'c']` and `['a', 'b-c']` do. const getKey = (item: TItem): string | number => { - return keys.map((key) => item[key]).join('-') + const values = keys.map((key) => `${item[key] ?? ``}`) + return values.length === 1 ? values[0]! : JSON.stringify(values) } const conversions = { parse, serialize } as ColumnConversions diff --git a/packages/supabase-db-collection/tests/collection-key.test.ts b/packages/supabase-db-collection/tests/collection-key.test.ts new file mode 100644 index 0000000000..94b96742c4 --- /dev/null +++ b/packages/supabase-db-collection/tests/collection-key.test.ts @@ -0,0 +1,70 @@ +import { createClient } from '@supabase/supabase-js' +import { fc, test as fcTest } from '@fast-check/vitest' +import { describe, expect } from 'vitest' +import { z } from 'zod' +import { supabaseCollectionOptions } from '../src/index' +import { SUPABASE_KEY, SUPABASE_URL } from './test.utils' + +// Collection keys are built from the configured key columns, whose values are +// strings. Two rows must share a key exactly when every key column is equal; +// otherwise one row overwrites the other in the collection. + +const columns = [`a`, `b`, `c`] as const + +const getKeyFor = (keys: Array<(typeof columns)[number]>) => + supabaseCollectionOptions({ + tableName: `rows`, + keys, + schema: z.object({ a: z.string(), b: z.string(), c: z.string() }), + supabase: createClient(SUPABASE_URL, SUPABASE_KEY), + }).getKey + +const rowOf = (values: Array) => ({ + a: values[0] ?? ``, + b: values[1] ?? ``, + c: values[2] ?? ``, +}) + +// Short strings over separator-like characters. +const unit = fc.constantFrom(`a`, `-`, `"`, `\\`, `,`, `[`, `]`) +const value = fc.string({ unit, maxLength: 3 }) + +// Splits `text` into `width` parts at the given cut points. +const split = (text: string, cuts: Array): Array => { + const bounds = [0, ...cuts.sort((x, y) => x - y), text.length] + return bounds.slice(1).map((end, index) => text.slice(bounds[index], end)) +} + +// Two tuples of `width` values cut from the same text. Independently drawn +// tuples almost never line up, so this is what makes distinct tuples with +// overlapping contents (`['a-', 'b']` and `['a', '-b']`) common. Equal cuts +// give equal tuples. +const compositePair = fc + .tuple(fc.integer({ min: 2, max: 3 }), fc.string({ unit, maxLength: 6 })) + .chain(([width, text]) => { + const cuts = fc.array(fc.integer({ min: 0, max: text.length }), { + minLength: width - 1, + maxLength: width - 1, + }) + return fc + .tuple(cuts, cuts) + .map(([left, right]) => [split(text, left), split(text, right)] as const) + }) + +describe(`collection keys`, () => { + fcTest.prop([compositePair], { numRuns: 500 })( + `composite keys are equal exactly when every key column is equal`, + ([left, right]) => { + const getKey = getKeyFor(columns.slice(0, left.length)) + const sameKey = getKey(rowOf(left)) === getKey(rowOf(right)) + expect(sameKey).toBe(left.every((part, index) => part === right[index])) + }, + ) + + fcTest.prop([value], { numRuns: 100 })( + `a single key column is the column value itself`, + (id) => { + expect(getKeyFor([`a`])(rowOf([id]))).toBe(id) + }, + ) +}) From 8dc456506b314e536cbbf746e9dc315be2a8b910 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Tue, 10 Nov 2026 12:44:02 +0100 Subject: [PATCH 03/13] fix(supabase-db-collection): keep query collection sync hooks The sync wrapper returned a new `sync: { sync }` object, dropping the factory query-db-collection attaches to its sync config. Without it a direct write such as `utils.writeUpsert` on an idle collection threw SyncNotInitializedError instead of starting sync. Spread the original sync config and replace only `sync`. Co-Authored-By: Claude Opus 5.5 (1M context) --- packages/supabase-db-collection/src/db.ts | 3 ++ .../tests/direct-writes.test.ts | 29 +++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 packages/supabase-db-collection/tests/direct-writes.test.ts diff --git a/packages/supabase-db-collection/src/db.ts b/packages/supabase-db-collection/src/db.ts index 0298f813f7..8faff98085 100644 --- a/packages/supabase-db-collection/src/db.ts +++ b/packages/supabase-db-collection/src/db.ts @@ -192,6 +192,9 @@ export const supabaseCollectionOptions = ({ return { ...config, sync: { + // Keeps the hooks query-db-collection attaches to its sync config, such + // as the factory that lets a direct write start an idle collection. + ...config.sync, sync: ( ...args: Parameters ): ReturnType => { diff --git a/packages/supabase-db-collection/tests/direct-writes.test.ts b/packages/supabase-db-collection/tests/direct-writes.test.ts new file mode 100644 index 0000000000..1ee2b74b00 --- /dev/null +++ b/packages/supabase-db-collection/tests/direct-writes.test.ts @@ -0,0 +1,29 @@ +import { afterEach, describe, expect, test } from 'vitest' +import { createMockFetch, createMockedUsersCollection } from './test.utils' + +// query-db-collection starts an idle collection when one of its direct-write +// utils is called (its ownership-lifecycle tests own that law). The Supabase +// adapter wraps the query collection's sync config, so the wrapped collection +// must keep the behavior. + +describe(`direct writes on an idle collection`, () => { + let collection: ReturnType | undefined + + afterEach(async () => { + await collection?.cleanup() + collection = undefined + }) + + test(`a direct write starts sync and stores the row without fetching`, () => { + const mockFetch = createMockFetch() + collection = createMockedUsersCollection(mockFetch) + expect(collection.status).toBe(`idle`) + + const row = { id: 7, name: `Grace`, email: `grace@test.com`, active: true } + collection.utils.writeUpsert(row) + + expect(collection.status).toBe(`ready`) + expect(collection.get(`7`)).toMatchObject(row) + expect(mockFetch).not.toHaveBeenCalled() + }) +}) From 24d907fd5ea05ded8621b618805700660772f5f6 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Tue, 10 Nov 2026 12:48:43 +0100 Subject: [PATCH 04/13] fix(supabase-db-collection): read through a DbClient's queryClient Spreading the query collection's options dropped its DbClient config factory, so `collectionOptions(supabaseCollectionOptions(...))` read through the default QueryClient instead of the client's `queryClient` dependency, and a second DbClient could not reuse the descriptor. Register a factory that rebuilds the whole Supabase config, including the Realtime wrapper, with the client's `queryClient`. Co-Authored-By: Claude Opus 5.5 (1M context) --- packages/supabase-db-collection/src/db.ts | 48 ++++++++++----- .../tests/db-client.test.ts | 61 +++++++++++++++++++ 2 files changed, 94 insertions(+), 15 deletions(-) create mode 100644 packages/supabase-db-collection/tests/db-client.test.ts diff --git a/packages/supabase-db-collection/src/db.ts b/packages/supabase-db-collection/src/db.ts index 8faff98085..3f1de21178 100644 --- a/packages/supabase-db-collection/src/db.ts +++ b/packages/supabase-db-collection/src/db.ts @@ -1,4 +1,4 @@ -import { BasicIndex } from '@tanstack/db' +import { BasicIndex, withCollectionConfigFactory } from '@tanstack/db' import { queryCollectionOptions } from '@tanstack/query-db-collection' import { subsetOptionsToQueryKey, @@ -119,21 +119,23 @@ const registerTable = ( return entry } -export const supabaseCollectionOptions = ({ - tableName, - keys, - schema, - queryClient, - supabase, - realtime, - realtimeUseFilter = false, - syncMode = 'on-demand', - defaultStringCollation, - parse, - serialize, -}: SupabaseCollectionOptions) => { +const createSupabaseConfig = ( + options: SupabaseCollectionOptions, +) => { + const { + tableName, + keys, + schema, + supabase, + realtime, + realtimeUseFilter = false, + syncMode = 'on-demand', + defaultStringCollation, + parse, + serialize, + } = options // if the query client is not provided, use the global query client - queryClient = queryClient ?? getQueryClient() + const queryClient = options.queryClient ?? getQueryClient() type TItem = StandardSchemaV1.InferOutput @@ -207,3 +209,19 @@ export const supabaseCollectionOptions = ({ }, } } + +export const supabaseCollectionOptions = ( + options: SupabaseCollectionOptions, +): ReturnType> => + // Each DbClient materializes its own config, reading through the client's + // `queryClient` dependency the way query-db-collection does. The config above + // spreads the query collection's options, which drops that collection's own + // factory; it would also skip the Realtime wrapper, so this one rebuilds the + // whole Supabase config. + withCollectionConfigFactory(createSupabaseConfig(options), (client) => + createSupabaseConfig({ + ...options, + queryClient: + client.getDependency(`queryClient`) ?? options.queryClient, + }), + ) diff --git a/packages/supabase-db-collection/tests/db-client.test.ts b/packages/supabase-db-collection/tests/db-client.test.ts new file mode 100644 index 0000000000..2049264ba5 --- /dev/null +++ b/packages/supabase-db-collection/tests/db-client.test.ts @@ -0,0 +1,61 @@ +import { createClient } from '@supabase/supabase-js' +import { DbClient, collectionOptions } from '@tanstack/db' +import { QueryClient } from '@tanstack/query-core' +import { afterEach, describe, expect, test } from 'vitest' +import { supabaseCollectionOptions } from '../src/index' +import { + SUPABASE_KEY, + SUPABASE_URL, + createMockFetch, + usersSchema, +} from './test.utils' + +// A collection descriptor is materialized once per DbClient. Like the query +// collection it builds on, a Supabase collection reads through the client's +// `queryClient` dependency, so each client's queries live in that client's +// cache rather than in the default QueryClient. + +describe(`DbClient materialization`, () => { + const cleanups: Array<() => Promise> = [] + + afterEach(async () => { + await Promise.all(cleanups.splice(0).map((cleanup) => cleanup())) + }) + + const createDbClient = () => { + const queryClient = new QueryClient() + const client = new DbClient({ queryClient }) + cleanups.push(async () => { + await client.cleanup() + queryClient.clear() + }) + return { client, queryClient } + } + + test(`each DbClient reads through its own queryClient`, async () => { + const descriptor = collectionOptions( + supabaseCollectionOptions({ + tableName: `users`, + keys: [`id`], + schema: usersSchema, + syncMode: `eager`, + supabase: createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: createMockFetch() }, + }), + }), + ) + + for (const { client, queryClient } of [ + createDbClient(), + createDbClient(), + ]) { + const collection = client.collection(descriptor) + await collection.preload() + + expect(collection.size).toBe(1) + expect( + queryClient.getQueryCache().findAll({ queryKey: [`users`] }), + ).not.toHaveLength(0) + } + }) +}) From 67bcfc1b02aeb6aacbb3eb46f1e3e3537fbd205f Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Tue, 10 Nov 2026 12:54:56 +0100 Subject: [PATCH 05/13] fix(supabase-db-collection): combine abort signals without AbortSignal.any React Native (Hermes) and Safari before 17.4 have no AbortSignal.any, so every read split for an oversized IN list threw a TypeError there. The chunk controller now follows the caller's signal through a listener, keeping the caller's abort reason, and removes the listener when the load settles, including on failure. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../supabase-db-collection/src/functions.ts | 25 ++++-- .../tests/split-load-fanout.test.ts | 89 ++++++++++++++++++- 2 files changed, 105 insertions(+), 9 deletions(-) diff --git a/packages/supabase-db-collection/src/functions.ts b/packages/supabase-db-collection/src/functions.ts index b3437bc9e7..7dadd9c2c1 100644 --- a/packages/supabase-db-collection/src/functions.ts +++ b/packages/supabase-db-collection/src/functions.ts @@ -293,11 +293,10 @@ function measureSubset( * matter and needs no dedupe. * * On the first failure, every other chunk's request is aborted through a - * local `AbortController` combined with the caller's own signal - * (`AbortSignal.any`) — this keeps the same all-or-nothing semantics an - * unsplit request has ("one failed page fails the whole load") instead of - * surfacing a partial result, and the first error encountered is what - * `Promise.all` rejects with. + * local `AbortController` that also follows the caller's own signal — this + * keeps the same all-or-nothing semantics an unsplit request has ("one failed + * page fails the whole load") instead of surfacing a partial result, and the + * first error encountered is what `Promise.all` rejects with. */ async function loadChunks( supabase: SupabaseClient, @@ -306,8 +305,14 @@ async function loadChunks( chunks: Array, signal: AbortSignal, ): Promise> { + // Not `AbortSignal.any`: React Native (Hermes) and Safari before 17.4 lack it. const controller = new AbortController() - const combinedSignal = AbortSignal.any([signal, controller.signal]) + const abortFromCaller = () => controller.abort(signal.reason) + if (signal.aborted) { + abortFromCaller() + } else { + signal.addEventListener('abort', abortFromCaller, { once: true }) + } const results: Array> = new Array(chunks.length) let nextIndex = 0 @@ -320,7 +325,7 @@ async function loadChunks( tableName, keys, chunks[index]!, - combinedSignal, + controller.signal, ) } catch (error) { controller.abort() @@ -330,7 +335,11 @@ async function loadChunks( } const workerCount = Math.min(MAX_CONCURRENT_CHUNKS, chunks.length) - await Promise.all(Array.from({ length: workerCount }, runWorker)) + try { + await Promise.all(Array.from({ length: workerCount }, runWorker)) + } finally { + signal.removeEventListener('abort', abortFromCaller) + } return results.flat() } diff --git a/packages/supabase-db-collection/tests/split-load-fanout.test.ts b/packages/supabase-db-collection/tests/split-load-fanout.test.ts index 317f866aee..5d77e62796 100644 --- a/packages/supabase-db-collection/tests/split-load-fanout.test.ts +++ b/packages/supabase-db-collection/tests/split-load-fanout.test.ts @@ -1,7 +1,7 @@ import { createClient } from '@supabase/supabase-js' import { IR, and, inArray, not } from '@tanstack/db' import { QueryClient } from '@tanstack/query-core' -import { describe, expect, test, vi } from 'vitest' +import { afterEach, describe, expect, test, vi } from 'vitest' import { MAX_URL_LENGTH, supabaseQueryFn } from '../src/functions' import { loadSubsetOptionsToSearch } from '../src/postgrest-filters' import { @@ -374,4 +374,91 @@ describe('supabaseQueryFn: chunked fan-out for an oversized IN list', () => { expect(rawUrl.length).toBeLessThanOrEqual(MAX_URL_LENGTH) } }) + + describe('abort signal plumbing', () => { + afterEach(() => { + vi.restoreAllMocks() + }) + + // Counts the caller's `abort` listeners still attached, so a test can + // check that the load removed what it added once it settled. + const liveAbortListeners = (signal: AbortSignal) => { + const add = vi.spyOn(signal, 'addEventListener') + const remove = vi.spyOn(signal, 'removeEventListener') + return () => { + const removed = new Set( + remove.mock.calls + .filter(([type]) => type === 'abort') + .map(([, listener]) => listener), + ) + return add.mock.calls.filter( + ([type, listener]) => type === 'abort' && !removed.has(listener), + ).length + } + } + + test('a split read works where AbortSignal.any is unavailable', async () => { + // React Native (Hermes) and Safari before 17.4 have no AbortSignal.any. + vi.spyOn(AbortSignal, 'any').mockImplementation(() => { + throw new TypeError('AbortSignal.any is not a function') + }) + const ids = idsExceedingLength(MAX_URL_LENGTH * 1.5) + const signal = new AbortController().signal + const live = liveAbortListeners(signal) + + const rows = await run( + makePaginatingFetch(ids.map((id) => ({ id }))), + ids, + signal, + ) + + expect(rows).toHaveLength(ids.length) + expect(live()).toBe(0) + }) + + test("a caller abort reaches every chunk request with the caller's reason", async () => { + const ids = idsExceedingLength(MAX_URL_LENGTH * 1.5) + const caller = new AbortController() + const reason = new Error('caller stopped') + const requestSignals: Array = [] + const hangingFetch = vi + .fn() + .mockImplementation((_input, init) => { + const signal = init!.signal! + requestSignals.push(signal) + // Like `fetch`, reject at once for a signal that is already aborted + // (supabase-js retries an aborted request with the same signal). + return new Promise((_resolve, reject) => { + if (signal.aborted) reject(signal.reason) + signal.addEventListener('abort', () => reject(signal.reason)) + }) + }) + const live = liveAbortListeners(caller.signal) + + const load = run(hangingFetch, ids, caller.signal) + await vi.waitFor(() => expect(requestSignals.length).toBeGreaterThan(1)) + caller.abort(reason) + + await expect(load).rejects.toThrow(reason.message) + for (const signal of requestSignals) { + expect(signal.reason).toBe(reason) + } + expect(live()).toBe(0) + }) + + test("a failed split read releases the caller's signal", async () => { + const ids = idsExceedingLength(MAX_URL_LENGTH * 1.5) + const signal = new AbortController().signal + const live = liveAbortListeners(signal) + const failingFetch = vi.fn().mockResolvedValue( + new Response(JSON.stringify({ message: 'boom' }), { + status: 500, + headers: { 'content-type': 'application/json' }, + }), + ) + + await expect(run(failingFetch, ids, signal)).rejects.toBeDefined() + expect(live()).toBe(0) + }) + }) }) From 1d9126afc96d584d9985e3ab5ca6eb42dfc42d76 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Tue, 10 Nov 2026 13:03:16 +0100 Subject: [PATCH 06/13] fix(supabase-db-collection): send null placement in the order param The order param dropped each sort's `nulls`. TanStack DB puts nulls first unless told otherwise, while Postgres puts them last for ascending order, so a limited ascending window over a nullable column loaded the wrong rows (e.g. [3, 1] instead of the null rows [2, 4]). Every sort the query asks for now carries `.nullsfirst` or `.nullslast`; the key-column tiebreak is unchanged. A new test compares limited windows over a nullable column, for each direction and null placement, with the same live query over a local-only collection, served by a mock that orders like Postgres. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../src/postgrest-filters/common.ts | 13 +- .../subset-params-to-search.ts | 1 + .../tests/index.test.ts | 24 ++- .../tests/order-nulls.test.ts | 157 ++++++++++++++++++ .../tests/pagination.test.ts | 48 +++--- .../tests/postgrest-filters.test.ts | 10 +- .../tests/split-load-fanout.test.ts | 2 +- 7 files changed, 214 insertions(+), 41 deletions(-) create mode 100644 packages/supabase-db-collection/tests/order-nulls.test.ts diff --git a/packages/supabase-db-collection/src/postgrest-filters/common.ts b/packages/supabase-db-collection/src/postgrest-filters/common.ts index 78f5aa8182..a26683dc53 100644 --- a/packages/supabase-db-collection/src/postgrest-filters/common.ts +++ b/packages/supabase-db-collection/src/postgrest-filters/common.ts @@ -18,16 +18,23 @@ interface FilterOptions { stripAlias?: boolean } -/** Set the comma-joined `order` param (independent of limit/offset). */ +/** + * Set the comma-joined `order` param (independent of limit/offset). Null + * placement is always explicit: Postgres puts nulls last for `asc`, while + * TanStack DB puts them first unless told otherwise. + */ export function appendOrder( search: URLSearchParams, - sorts: Array<{ column: string; ascending: boolean }>, + sorts: Array<{ column: string; ascending: boolean; nulls: 'first' | 'last' }>, ): void { if (sorts.length === 0) return search.set( 'order', sorts - .map((sort) => `${sort.column}.${sort.ascending ? 'asc' : 'desc'}`) + .map( + (sort) => + `${sort.column}.${sort.ascending ? 'asc' : 'desc'}.nulls${sort.nulls}`, + ) .join(','), ) } diff --git a/packages/supabase-db-collection/src/postgrest-filters/subset-params-to-search.ts b/packages/supabase-db-collection/src/postgrest-filters/subset-params-to-search.ts index d6a87f83ad..7f13b05fcd 100644 --- a/packages/supabase-db-collection/src/postgrest-filters/subset-params-to-search.ts +++ b/packages/supabase-db-collection/src/postgrest-filters/subset-params-to-search.ts @@ -24,6 +24,7 @@ export function subsetParamsToSearch( parseOrderByExpression(orderBy).map((sort) => ({ column: sort.field.join('.'), ascending: sort.direction === 'asc', + nulls: sort.nulls, })), ) // `limit: 0` is a real, distinct subset (an empty window). Guard on diff --git a/packages/supabase-db-collection/tests/index.test.ts b/packages/supabase-db-collection/tests/index.test.ts index 94ecb0a107..969f4f9a3d 100644 --- a/packages/supabase-db-collection/tests/index.test.ts +++ b/packages/supabase-db-collection/tests/index.test.ts @@ -643,7 +643,9 @@ describe('PostgREST query generation', () => { await queryResult((q) => q.from({ user: usersCollection }).orderBy(({ user }) => user.name), ) - expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&order=name.asc']) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=name.asc.nullsfirst', + ]) }) test('explicit asc', async () => { @@ -652,7 +654,9 @@ describe('PostgREST query generation', () => { .from({ user: usersCollection }) .orderBy(({ user }) => user.name, 'asc'), ) - expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&order=name.asc']) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=name.asc.nullsfirst', + ]) }) test('descending', async () => { @@ -661,7 +665,9 @@ describe('PostgREST query generation', () => { .from({ user: usersCollection }) .orderBy(({ user }) => user.name, 'desc'), ) - expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&order=name.desc']) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=name.desc.nullsfirst', + ]) }) test('multi-column orderBy', async () => { @@ -672,7 +678,7 @@ describe('PostgREST query generation', () => { .orderBy(({ user }) => user.id, 'desc'), ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=*&order=name.asc,id.desc', + '/rest/v1/users?select=*&order=name.asc.nullsfirst,id.desc.nullsfirst', ]) }) }) @@ -686,7 +692,7 @@ describe('PostgREST query generation', () => { .limit(10), ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=*&order=id.asc&limit=10', + '/rest/v1/users?select=*&order=id.asc.nullsfirst&limit=10', ]) }) }) @@ -701,7 +707,7 @@ describe('PostgREST query generation', () => { .offset(20), ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=*&order=id.asc&limit=20&offset=20', + '/rest/v1/users?select=*&order=id.asc.nullsfirst&limit=20&offset=20', ]) }) }) @@ -774,7 +780,7 @@ describe('PostgREST query generation', () => { .limit(10), ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=*&active=eq.true&order=name.asc&limit=10', + '/rest/v1/users?select=*&active=eq.true&order=name.asc.nullsfirst&limit=10', ]) }) @@ -786,7 +792,7 @@ describe('PostgREST query generation', () => { .orderBy(({ user }) => user.name, 'desc'), ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=*&active=eq.true&order=name.desc', + '/rest/v1/users?select=*&active=eq.true&order=name.desc.nullsfirst', ]) }) @@ -799,7 +805,7 @@ describe('PostgREST query generation', () => { .limit(5), ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=*&id=gt.3&order=id.asc&limit=5', + '/rest/v1/users?select=*&id=gt.3&order=id.asc.nullsfirst&limit=5', ]) }) diff --git a/packages/supabase-db-collection/tests/order-nulls.test.ts b/packages/supabase-db-collection/tests/order-nulls.test.ts new file mode 100644 index 0000000000..72bb530376 --- /dev/null +++ b/packages/supabase-db-collection/tests/order-nulls.test.ts @@ -0,0 +1,157 @@ +import { createClient } from '@supabase/supabase-js' +import { createCollection, localOnlyCollectionOptions } from '@tanstack/db' +import { describe, expect, test, vi } from 'vitest' +import { z } from 'zod' +import { supabaseCollectionOptions } from '../src/index' +import { SUPABASE_KEY, SUPABASE_URL, queryResult } from './test.utils' + +// A limited, ordered live query over an on-demand collection only sees the +// rows the server sends for that window. The server must therefore cut the +// window from the same order the client applies, including where nulls sort. +// TanStack DB places nulls first unless told otherwise, while Postgres places +// them last for ascending order, so the adapter has to say where they go. +// +// The reference is the same live query over a local-only collection holding +// every row: TanStack DB's own in-memory ordering, with no server involved. + +type Row = { id: number; rank: number | null } + +const rows: Array = [ + { id: 1, rank: 2 }, + { id: 2, rank: null }, + { id: 3, rank: 1 }, + { id: 4, rank: null }, + { id: 5, rank: 3 }, +] + +const schema = z.object({ id: z.number(), rank: z.number().nullable() }) + +/** + * Orders rows the way PostgREST does for an `order` param of + * `col.dir[.nullsfirst|.nullslast]` sorts: Postgres puts nulls last for `asc` + * and first for `desc` unless the sort names a placement. + */ +function postgresOrder(order: string) { + const sorts = order.split(`,`).map((sort) => { + const [column = ``, direction = `asc`, nulls] = sort.split(`.`) + const nullsFirst = + nulls === undefined ? direction === `desc` : nulls === `nullsfirst` + return { + column: column as keyof Row, + descending: direction === `desc`, + nullsFirst, + } + }) + return (a: Row, b: Row): number => { + for (const { column, descending, nullsFirst } of sorts) { + const left = a[column] + const right = b[column] + if (left === right) continue + if (left === null) return nullsFirst ? -1 : 1 + if (right === null) return nullsFirst ? 1 : -1 + return (left < right ? -1 : 1) * (descending ? -1 : 1) + } + return 0 + } +} + +const comparisons: Record boolean> = + { + eq: (value, target) => value === target, + gt: (value, target) => value > target, + gte: (value, target) => value >= target, + lt: (value, target) => value < target, + lte: (value, target) => value <= target, + } + +/** + * Keeps the rows a `col=op.value` filter matches, with SQL semantics: a null + * column matches only `is.null`. A filter the mock does not know throws, so a + * request it cannot serve fails the test instead of returning every row. + */ +function matches(row: Row, column: string, filter: string): boolean { + const [op = ``, operand = ``] = filter.split(/\.(.*)/s) + const value = row[column as keyof Row] + if (op === `is` && operand === `null`) return value === null + const compare = comparisons[op] + if (!compare) throw new Error(`mock cannot serve filter ${column}=${filter}`) + return value !== null && compare(value, Number(operand)) +} + +/** Serves `rows` for `order`, `limit` and simple column filters. */ +const postgrestFetch = () => + vi.fn().mockImplementation((input) => { + const params = new URL(String(input)).searchParams + let selected = [...rows] + for (const [name, filter] of params) { + if ([`select`, `order`, `limit`, `offset`].includes(name)) continue + selected = selected.filter((row) => matches(row, name, filter)) + } + const order = params.get(`order`) + if (order) selected.sort(postgresOrder(order)) + const total = selected.length + const limit = params.get(`limit`) + const body = limit === null ? selected : selected.slice(0, Number(limit)) + return Promise.resolve( + new Response(JSON.stringify(body), { + status: 200, + headers: { + 'content-type': `application/json`, + 'content-range': body.length + ? `0-${body.length - 1}/${total}` + : `*/${total}`, + }, + }), + ) + }) + +const cases = [ + { direction: `asc`, nulls: undefined }, + { direction: `asc`, nulls: `first` }, + { direction: `asc`, nulls: `last` }, + { direction: `desc`, nulls: undefined }, + { direction: `desc`, nulls: `first` }, + { direction: `desc`, nulls: `last` }, +] as const + +describe(`ordering with nulls`, () => { + test.each(cases)( + `a limited window ordered $direction with nulls $nulls matches in-memory ordering`, + async ({ direction, nulls }) => { + const supabaseRows = createCollection( + supabaseCollectionOptions({ + tableName: `items`, + keys: [`id`], + schema, + supabase: createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: postgrestFetch() }, + }), + }), + ) + const localRows = createCollection( + localOnlyCollectionOptions({ + id: `local-items-${direction}-${nulls}`, + getKey: (row) => String(row.id), + initialData: rows, + }), + ) + const window = async (collection: typeof localRows) => + ( + await queryResult((q) => + q + .from({ item: collection }) + .orderBy(({ item }) => item.rank, { direction, nulls }) + .limit(2) + .select(({ item }) => ({ id: item.id })), + ) + ).map((row) => row.id) + + const expected = await window(localRows) + const actual = await window(supabaseRows as unknown as typeof localRows) + + expect(actual).toEqual(expected) + await supabaseRows.cleanup() + await localRows.cleanup() + }, + ) +}) diff --git a/packages/supabase-db-collection/tests/pagination.test.ts b/packages/supabase-db-collection/tests/pagination.test.ts index dc4ffe5421..5c30d481b0 100644 --- a/packages/supabase-db-collection/tests/pagination.test.ts +++ b/packages/supabase-db-collection/tests/pagination.test.ts @@ -121,7 +121,7 @@ describe('live infinite query (windowed) pagination', () => { // The first page is a plain ordered window (one peek row past the page) // plus core's boundary probe — no keyset cursor (`gt`) and no offset yet. expect(getSearches(mockFetch)).toEqual([ - 'select=*&order=id.asc&limit=3', // window + 1 peek row + 'select=*&order=id.asc.nullsfirst&limit=3', // window + 1 peek row 'select=*&id=eq.3', // boundary probe (loadBoundary) settles the peek ]) }) @@ -146,10 +146,10 @@ describe('live infinite query (windowed) pagination', () => { // request from the boundary (id 3): ordered, limited, and — crucially — // with no offset re-skipping rows. No request carries an offset. expect(getSearches(mockFetch)).toEqual([ - 'select=*&order=id.asc&limit=3', // page 1: window + 1 peek row + 'select=*&order=id.asc.nullsfirst&limit=3', // page 1: window + 1 peek row 'select=*&id=eq.3', // boundary probe (loadBoundary) settles the peek - 'select=*&order=id.asc&id=eq.3', // page 2: whereCurrent tie read - 'select=*&order=id.asc&limit=2&id=gt.3', // page 2: whereFrom keyset read + 'select=*&order=id.asc.nullsfirst&id=eq.3', // page 2: whereCurrent tie read + 'select=*&order=id.asc.nullsfirst&limit=2&id=gt.3', // page 2: whereFrom keyset read 'select=*&id=eq.5', // boundary probe for the next peek ]) }) @@ -184,10 +184,10 @@ describe('live infinite query (windowed) pagination', () => { // the window path; see the module note. The adapter emits it regardless // because it honors the cursor contract.) expect(getSearches(mockFetch)).toEqual([ - 'select=*&order=rank.asc&limit=3', // page 1: window + 1 peek row + 'select=*&order=rank.asc.nullsfirst&limit=3', // page 1: window + 1 peek row 'select=*&rank=eq.20', // boundary probe (loadBoundary): full tie class - 'select=*&order=rank.asc&rank=eq.20', // page 2: whereCurrent tie read - 'select=*&order=rank.asc&limit=1&rank=gt.20', // page 2: whereFrom keyset read + 'select=*&order=rank.asc.nullsfirst&rank=eq.20', // page 2: whereCurrent tie read + 'select=*&order=rank.asc.nullsfirst&limit=1&rank=gt.20', // page 2: whereFrom keyset read 'select=*&rank=eq.30', // boundary probe for the next peek ]) }) @@ -239,9 +239,9 @@ describe('db-max-rows paging loop (supabaseQueryFn)', () => { // and each later page advances the offset by the rows received, capped by // the rows still owed (the last page asks for just 1). expect(getSearches(mockFetch)).toEqual([ - 'select=*&order=id.asc', - 'select=*&order=id.asc&offset=2&limit=2', - 'select=*&order=id.asc&offset=4&limit=1', + 'select=*&order=id.asc.nullslast', + 'select=*&order=id.asc.nullslast&offset=2&limit=2', + 'select=*&order=id.asc.nullslast&offset=4&limit=1', ]) }) @@ -265,8 +265,8 @@ describe('db-max-rows paging loop (supabaseQueryFn)', () => { ]) // Two requests, not three: the count tells the loop it is done at offset 4. expect(getSearches(mockFetch)).toEqual([ - 'select=*&order=id.asc', - 'select=*&order=id.asc&offset=2&limit=2', + 'select=*&order=id.asc.nullslast', + 'select=*&order=id.asc.nullslast&offset=2&limit=2', ]) }) @@ -281,8 +281,8 @@ describe('db-max-rows paging loop (supabaseQueryFn)', () => { 3, 4, 5, 6, ]) expect(getSearches(mockFetch)).toEqual([ - 'select=*&order=id.asc&offset=2', - 'select=*&order=id.asc&offset=4&limit=2', + 'select=*&order=id.asc.nullslast&offset=2', + 'select=*&order=id.asc.nullslast&offset=4&limit=2', ]) }) @@ -291,7 +291,7 @@ describe('db-max-rows paging loop (supabaseQueryFn)', () => { const rows = await run(mockFetch, { orderBy: ORDER_BY }) expect((rows as Array<{ id: number }>).map((r) => r.id)).toEqual([1, 2]) - expect(getSearches(mockFetch)).toEqual(['select=*&order=id.asc']) + expect(getSearches(mockFetch)).toEqual(['select=*&order=id.asc.nullslast']) }) test('the loop owns limit: a caller limit above the cap still pages', async () => { @@ -301,8 +301,8 @@ describe('db-max-rows paging loop (supabaseQueryFn)', () => { // Exactly the caller's 3 rows, fetched across cap-sized pages. expect((rows as Array<{ id: number }>).map((r) => r.id)).toEqual([1, 2, 3]) expect(getSearches(mockFetch)).toEqual([ - 'select=*&order=id.asc&limit=3', - 'select=*&order=id.asc&limit=1&offset=2', + 'select=*&order=id.asc.nullslast&limit=3', + 'select=*&order=id.asc.nullslast&limit=1&offset=2', ]) }) @@ -396,10 +396,10 @@ describe('db-max-rows paging loop (supabaseQueryFn)', () => { await readTied(mockFetch, ['id']) expect(getSearches(mockFetch)).toEqual([ - 'select=*&order=rank.asc', - 'select=*&order=rank.asc,id.asc&offset=0&limit=2', - 'select=*&order=rank.asc,id.asc&offset=2&limit=2', - 'select=*&order=rank.asc,id.asc&offset=4&limit=2', + 'select=*&order=rank.asc.nullslast', + 'select=*&order=rank.asc.nullslast,id.asc&offset=0&limit=2', + 'select=*&order=rank.asc.nullslast,id.asc&offset=2&limit=2', + 'select=*&order=rank.asc.nullslast,id.asc&offset=4&limit=2', ]) }) @@ -421,7 +421,7 @@ describe('db-max-rows paging loop (supabaseQueryFn)', () => { // `rank` is already sorted by, so only `id` is added. expect(getSearches(mockFetch)[1]).toBe( - 'select=*&order=rank.asc,id.asc&offset=0&limit=2', + 'select=*&order=rank.asc.nullslast,id.asc&offset=0&limit=2', ) }) @@ -429,7 +429,9 @@ describe('db-max-rows paging loop (supabaseQueryFn)', () => { const mockFetch = makeTieShufflingFetch(TIED.slice(0, 2), 2) await readTied(mockFetch, ['id']) - expect(getSearches(mockFetch)).toEqual(['select=*&order=rank.asc']) + expect(getSearches(mockFetch)).toEqual([ + 'select=*&order=rank.asc.nullslast', + ]) }) }) diff --git a/packages/supabase-db-collection/tests/postgrest-filters.test.ts b/packages/supabase-db-collection/tests/postgrest-filters.test.ts index ffe80b0491..11b59650e2 100644 --- a/packages/supabase-db-collection/tests/postgrest-filters.test.ts +++ b/packages/supabase-db-collection/tests/postgrest-filters.test.ts @@ -239,17 +239,17 @@ describe('subsetParamsToSearch', () => { test('appends a single order direction', () => { expect( subsetParamsToSearch({ orderBy: [sort(id, 'asc')] }).get('order'), - ).toBe('id.asc') + ).toBe('id.asc.nullslast') expect( subsetParamsToSearch({ orderBy: [sort(id, 'desc')] }).get('order'), - ).toBe('id.desc') + ).toBe('id.desc.nullslast') }) test('merges multiple order columns into one comma-joined value', () => { const search = subsetParamsToSearch({ orderBy: [sort(id, 'asc'), sort(name, 'desc')], }) - expect(search.get('order')).toBe('id.asc,name.desc') + expect(search.get('order')).toBe('id.asc.nullslast,name.desc.nullslast') expect(search.getAll('order')).toHaveLength(1) }) @@ -297,7 +297,7 @@ describe('loadSubsetOptionsToSearch', () => { limit: 5, }) expect(search.get('id')).toBe('eq.1') - expect(search.get('order')).toBe('id.asc') + expect(search.get('order')).toBe('id.asc.nullslast') expect(search.get('limit')).toBe('5') }) @@ -375,7 +375,7 @@ describe('cursorCurrentToSearch', () => { cursor: { whereFrom: gt(id, 40), whereCurrent: eq(id, 40) }, }) expect(search?.get('active')).toBe('eq.true') - expect(search?.get('order')).toBe('id.asc') + expect(search?.get('order')).toBe('id.asc.nullslast') expect(search?.get('id')).toBe('eq.40') expect(search?.has('limit')).toBe(false) }) diff --git a/packages/supabase-db-collection/tests/split-load-fanout.test.ts b/packages/supabase-db-collection/tests/split-load-fanout.test.ts index 5d77e62796..502bf1bab0 100644 --- a/packages/supabase-db-collection/tests/split-load-fanout.test.ts +++ b/packages/supabase-db-collection/tests/split-load-fanout.test.ts @@ -367,7 +367,7 @@ describe('supabaseQueryFn: chunked fan-out for an oversized IN list', () => { // Multi-page chunks are read in key order after the query's own order. for (const search of pagedSearches) { expect(search).toContain( - 'order=rank.asc,organization_identifier_column.asc,id.asc', + 'order=rank.asc.nullslast,organization_identifier_column.asc,id.asc', ) } for (const rawUrl of getRawUrls(mockFetch)) { From e79ced815163ac6217c2683abc875acd0061e375 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Tue, 10 Nov 2026 15:42:56 +0100 Subject: [PATCH 07/13] test(supabase-db-collection): add e2e tests against a local Supabase stack Port the package's own e2e tests from supabase/tanstack-db (reads, filters, mutations, realtime and realtime filters) and run the shared @tanstack/db-collection-e2e suites against PostgREST and Realtime. - The local Supabase project lives in supabase/, on ports 553xx so it runs alongside Electric. max_rows = 2 makes reads page. - The filters cases read through live queries; the queryOnce cases come with experimental_queryOnce. - The shared case "should maintain query state during data changes" is skipped: local Realtime adds about 500 ms per change, so the live query under test is cleaned up mid-test. - CI runs the suite in a new `supabase` group of the E2E workflow. Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/workflows/e2e-tests.yml | 26 +- docs/contributing/oracle-coverage.md | 2 +- .../supabase-db-collection/e2e/e2e.utils.ts | 164 ++++++ .../e2e/filters.e2e.test.ts | 109 ++++ .../e2e/global-setup.ts | 173 ++++++ .../e2e/mutations.e2e.test.ts | 116 ++++ .../e2e/reads.e2e.test.ts | 120 ++++ .../e2e/realtime-filters.e2e.test.ts | 513 ++++++++++++++++++ .../e2e/realtime.e2e.test.ts | 64 +++ packages/supabase-db-collection/e2e/setup.ts | 27 + .../e2e/supabase.e2e.test.ts | 366 +++++++++++++ packages/supabase-db-collection/package.json | 4 +- .../supabase/.gitignore | 8 + .../supabase/config.toml | 419 ++++++++++++++ .../migrations/00000000000000_e2e_schema.sql | 87 +++ .../00000000000001_shared_e2e_schema.sql | 84 +++ packages/supabase-db-collection/tsconfig.json | 6 +- .../vitest.e2e.config.ts | 47 ++ pnpm-lock.yaml | 3 + 19 files changed, 2333 insertions(+), 5 deletions(-) create mode 100644 packages/supabase-db-collection/e2e/e2e.utils.ts create mode 100644 packages/supabase-db-collection/e2e/filters.e2e.test.ts create mode 100644 packages/supabase-db-collection/e2e/global-setup.ts create mode 100644 packages/supabase-db-collection/e2e/mutations.e2e.test.ts create mode 100644 packages/supabase-db-collection/e2e/reads.e2e.test.ts create mode 100644 packages/supabase-db-collection/e2e/realtime-filters.e2e.test.ts create mode 100644 packages/supabase-db-collection/e2e/realtime.e2e.test.ts create mode 100644 packages/supabase-db-collection/e2e/setup.ts create mode 100644 packages/supabase-db-collection/e2e/supabase.e2e.test.ts create mode 100644 packages/supabase-db-collection/supabase/.gitignore create mode 100644 packages/supabase-db-collection/supabase/config.toml create mode 100644 packages/supabase-db-collection/supabase/migrations/00000000000000_e2e_schema.sql create mode 100644 packages/supabase-db-collection/supabase/migrations/00000000000001_shared_e2e_schema.sql create mode 100644 packages/supabase-db-collection/vitest.e2e.config.ts diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml index 486eb1e720..59ca56c439 100644 --- a/.github/workflows/e2e-tests.yml +++ b/.github/workflows/e2e-tests.yml @@ -18,7 +18,7 @@ jobs: strategy: fail-fast: false matrix: - group: [browser, desktop, cloud-mobile] + group: [browser, desktop, cloud-mobile, supabase] runs-on: ubuntu-latest timeout-minutes: 35 steps: @@ -76,6 +76,25 @@ jobs: --filter '@tanstack/react-native-db-sqlite-persistence...' build + - name: Setup Supabase CLI + if: matrix.group == 'supabase' + uses: supabase/setup-cli@689adcfb80d947100a1eab127289b97d1fb07b13 # v3.2.0 + with: + version: 2.116.0 + + - name: Start Supabase + if: matrix.group == 'supabase' + # The collection needs only the database, PostgREST, Realtime and the + # API gateway (Kong). Skipping the other services saves image pulls and + # startup time. The e2e global setup reuses this running stack. + working-directory: packages/supabase-db-collection + run: supabase start -x studio,mailpit,storage-api,imgproxy,postgres-meta,edge-runtime,logflare,vector,supavisor + + - name: Run Supabase E2E tests + if: matrix.group == 'supabase' + working-directory: packages/supabase-db-collection + run: pnpm test:e2e + - name: Run Electric E2E tests if: matrix.group == 'browser' run: | @@ -233,6 +252,11 @@ jobs: cd packages/db-collection-e2e/docker docker compose down -v + - name: Stop Supabase + if: always() && matrix.group == 'supabase' + working-directory: packages/supabase-db-collection + run: supabase stop --no-backup + - name: Upload test results if: failure() uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 diff --git a/docs/contributing/oracle-coverage.md b/docs/contributing/oracle-coverage.md index 4dea3ac188..ac25c6ee17 100644 --- a/docs/contributing/oracle-coverage.md +++ b/docs/contributing/oracle-coverage.md @@ -2089,7 +2089,7 @@ generic visitor behavior outside the named collectors. | SQLite expression-index planning | [Node expression-index oracle](https://github.com/TanStack/db/blob/main/packages/node-db-sqlite-persistence/tests/expression-index-oracle.test.ts) | RFC #1659 invariant 8 owns identical persisted-index and runtime-expression shapes. Independent expected keys are checked against direct captured SQL, adapter results, and named-index plans. Generated BigInts use SQLite's signed range; one fixed case checks legacy oversized-value reads. Other limits: bounded unqualified JSON paths/scalars, Node BetterSQLite, and no null, arbitrary raw SQL, or native-host planning. Run the package's `test:oracles` campaign. | | Offline execution | [scheduler](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/KeyScheduler-oracle.property.test.ts), [leadership](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/leadership-replay-oracle.property.test.ts), [settlement](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/transaction-settlement-oracle.property.test.ts), [serialization](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/transaction-serializer-oracle.property.test.ts), [web connectivity replay](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/connectivity-replay-oracle.test.ts), [review record](oracle-reviews/pr-1879-visible-replay.md) | Declarative FIFO eligibility, per-transaction outcomes, durable state and typed wire trees. The web connectivity owner checks a persisted write under a false browser online hint, then visible replay by event or explicit retry, at provider-call, outbox, and caller-settlement cuts. It uses controlled browser globals and fake storage; it does not prove actual browser network detection, genuine offline retry timing, multi-tab leadership transfer, or React Native behavior. Issued work may finish after ownership loss, but new work must not start. Exactly-once network execution is not promised. | | Frameworks | [React conformance](https://github.com/TanStack/db/blob/main/packages/react-db/tests/conformance.test.tsx), [React pagination](https://github.com/TanStack/db/blob/main/packages/react-db/tests/infinite-query-conformance.test.tsx), [shared framework contracts](https://github.com/TanStack/db/tree/main/packages/db/tests/conformance), [Vue synchronous publication](https://github.com/TanStack/db/blob/main/packages/vue-db/tests/useLiveQuery-publication-oracle.test.ts), [Preact conformance](https://github.com/TanStack/db/blob/main/packages/preact-db/tests/conformance.test.ts), [Preact binding witnesses](https://github.com/TanStack/db/blob/main/packages/preact-db/tests/useLiveQuery.test.ts) | Exact exposed rows/pages and each framework's own lifecycle cuts. Vue's synchronous watcher checks insert, update, and nonterminal delete through supplied Collection and identity query inputs; it does not cover an empty final result, multiple changes in one transaction, or query recompilation. A React witness does not prove Preact/Vue/Solid/Angular/Svelte scheduling. Preserve their receiving registrations. The Preact driver observes each result at commit through a layout-effect probe under an error boundary, because Preact runs passive effects after paint and `act` drains only those it scheduled; it has no Suspense, server-snapshot, or DbClient witness. Its binding witnesses check that a write between render and subscription publishes and that an equal `queryKey` or structurally equal query keeps its live-query Collection. Subscribing in a passive effect instead of a layout effect survives both, as allowed scheduling freedom. The query-identity laws (1.0, maintainer decisions 2026-10-22 and 2026-10-23) run through every live-query driver and the React, Preact, Vue, and Svelte infinite drivers, branching on each driver's public `comparesQueryIdentity` policy. In a binding that compares identity (React and Preact), a query without a nonempty `queryKey` whose IR has no stable hash throws `UnhashableQueryIRError` at mount and at recompilation; an empty key counts as none, and a nonempty key runs the query. React no longer accepts dependency arrays. Such a binding claims each source Collection ID it compiled, so A(x) -> C(y) -> A(x) is legal while a later B(x) throws `SourceCollectionIdReuseError`. A pairwise model judges 32 enumerated histories over A(x), B(x), C(y), and a disabled step, with declared reach for a swap after an intervening query, a swap after a disabled step, and a revisit after an intervening query. Reach labels name the steps between the claim and its test, so a direct swap does not count; removing the C(y) step fails reach. Claims that keep only the latest query, or reset at a disabled step, fail it. React retains two shared-suite registrations, but both now call the same derived-identity API; the registration still named `react (dependency list)` does not establish a second production path. The earlier five failures from skipping a dependency-list check at first compile were evidence for the removed API. A nonempty `queryKey` skips the claim: React and Preact witnesses swap a same-ID source under a changed key, and a key reader that ignores keys fails both. One query over two same-ID objects uses overlapping but different rows; an engine mutant that resolves each source through the Collection-ID map, so the last object serves both join sides, fails the live and infinite scenarios. A Svelte hydration witness checks that a `DbClient`-backed query with a dependency list hydrates `queryKey: []` exactly as it hydrates an omitted key. The infinite suite runs the same pairwise grammar over A(x), B(x), and C(y), 18 histories with declared reach for a swap and a revisit after an intervening query; it has no disabled or page-shape step, because one infinite handle changes either its query or its page shape. A new binding starts unclaimed. The former React dependency-list/`DbClient` witness is historical; it does not establish current reuse or hydration behavior. The shared conformance rejection scenarios currently check that, after a rejected rerender, two reads each throw or hold no rows. Reactive drivers accept an unhashable query, as described below. React unmounts a tree whose render throws. Preact keeps such a component mounted, so its driver mounts the hook under an error boundary, which unmounts it; a Preact component with no boundary keeps its last committed rows and is not witnessed here. It guards a future driver whose binding stays mounted; the `DbClient`-backed Svelte binding, which stays mounted, is checked field by field in fixed [descriptor release tests](https://github.com/TanStack/db/blob/main/packages/svelte-db/tests/descriptor-query-release.svelte.test.ts) (no oracle owner; tracked in #2264). A reactive binding (Vue, Solid, Angular, Svelte without a `DbClient`) runs the same histories and must publish the current input's rows: the unhashable query runs and recompiles when a captured value changes, and B(x) shows B's rows, never A's. One query over two same-ID objects is likewise rejected by a comparing binding and read through an inner join by a reactive one. The same mount-and-recompile split is not yet generated for `DbClient`-backed Svelte or React hooks beyond the receiving witnesses below. The [React source ID reuse oracle](https://github.com/TanStack/db/blob/main/packages/react-db/tests/source-id-reuse-oracle.test.tsx) owns the release law for `DbClient` descriptors: a rejected query releases every sync start it deferred. React exercises applicable causes (source-ID collision, unhashable IR, a descriptor factory that throws, a query rejected during compilation, a single-result infinite query, and a render abandoned by a sibling throw or suspension) through live, infinite, and Suspense hooks with derived identity or changed explicit `queryKey`, plus ordinary-hook configurations that disable reclamation, at initial mounts or rerenders and through four readers. Explicit keys bypass source-ID and derived-IR rejection; single-result rejection applies only to infinite hooks, and abandoned-after-hook histories exclude Suspense because its preload already starts the sources. Svelte crosses collision, unhashable, factory, compile, and abandoned-setup causes with eager and lazy sources and three readers, and its collision history reads every public result field separately after the rejection; dropping the guard from one getter, such as `isLoadingError`, fails all six collision cells. The earlier dependency-list Suspense cache-claim failures are historical. Current ordinary [source-ID tests](https://github.com/TanStack/db/blob/main/packages/react-db/tests/source-id-reuse.test.tsx) check separate client-scoped Suspense hooks and an initial suspended retry with different same-ID sources; they use the current derived-identity API. These fixed histories are supplemental tests, not a dimension of the claim grammar: that grammar's disabled step has no Suspense form, because `useLiveSuspenseQuery` rejects a disabled query. React ordinary/infinite hooks and Svelte's compiled query release at their render boundaries. The current React Suspense rejection histories fail within its shared ordinary-hook preparation; removing only the outer Suspense wrapper's catch is an unreached mutant, not a demonstrated kill. The former dependency-array SSR history was removed because its API is absent from the RC; it had executed no cells in the preceding grammar. Routing Svelte's getters around the compiled query fails its collision cells; `preload()` overrides a deferral, so those cells pass without the release by design. Declared reach: each enumerated release history asserts that the rejected query ran the shared descriptor's factory once before the reader, and a history that binds the failing descriptor first fails that check. A render that never commits (React: a sibling throws after the hook returns, or the render suspends; Svelte: setup throws after the hook returns) releases its deferral when garbage collection reclaims the live query it built (maintainer decision 2026-10-23), or after the unsubscribed GC floor when the hook's config disables that reclaim (`gcTime` 0 or `Infinity`, or `startSync: false`); both release grammars add these causes, React adds the three config paths and Svelte a `gcTime: 0` setup, and waiting only for the reclaim fails those cells; removing the reclaim release fails exactly them, and releasing at the end of render instead fails the descriptor binding owner's no-work-before-commit law. Known limit, owner the maintainer: the reclaim follows the 50 ms unsubscribed GC floor, so a render whose commit React holds past that floor releases its deferral, and its source may start, before it commits; that render then subscribes to a cleaned-up live query, which restarts. No history holds a commit past the floor, which needs a controlled React scheduler or fake timers; this joins the existing held-commit open cell in the infinite-query publication row. A keyed step records no claim and checks none (maintainer decision 2026-10-23): for a comparing binding the claim grammar adds keyed steps AK and BK over the same-ID objects, 108 histories with declared reach for a claim that crosses a keyed step and a keyed step after a claim; a keyed step that claims, or that resets earlier claims, fails it for the current React derived-identity path and for Preact. Each controllable driver records a publication log (`publication-log.ts`) at the end of each synchronous turn, plus the value on screen at the first paint after each `setParam`, once the framework has flushed and before any later task (maintainer decision 2026-10-23). After a same-ID swap, a reactive binding's every logged value holds only the new source's rows or none: a binding that keeps the old rows published until a later task fails it in Vue and Svelte. A value replaced within one synchronous turn is not logged, because the browser never paints it; Solid and Svelte publish the previous query's rows once inside the swap's own turn, for any input change, and pass. Accepted design (maintainer decision 2026-10-23): React claims source IDs during render, so a concurrent render that is abandoned before commit keeps its claim, as the React oracle states for a render that suspends, because that render's live query may still own the source until cleanup. Same-ID source objects stay legal; the claim, not `createCollection`, rejects a swap. Trace: committed C(y); a transition render reads B(x) and is interrupted; an urgent render reads A(x) and throws `SourceCollectionIdReuseError`. The abandoned-transition history has no witness. Adapter-specific `queryKey` change semantics stay with each adapter's own tests; React's infinite hook also has a focused witness that a `queryKey` array changed in place recompiles, because only React hands the caller's array to the shared window binding. The shared lifecycle histories distinguish adapter-created projections from caller-owned retention: omitted and explicitly `undefined` `gcTime` use the 1 ms adapter policy; `gcTime: 0`, a positive 100 ms retention, and supplied Collections keep caller authority. They observe retirement after unmount, replacement, disabling, and positive expiry, plus survival before that expiry. The shared suite also checks initial-query readiness over a lagging on-demand source, for a list and a `findOne` query and for the infinite query (React, Preact, Vue, and Svelte): not ready before the subset settles, ready at settlement while the source is still `loading`, and still ready after the source becomes ready. Solid's Suspense over that source has its own witness. A Solid Suspense witness also checks that a source's `reportError()` and `fail()` after readiness keep the boundary's rows shown and the query `ready`; a hook whose status follows the health tree fails it. A resource that suspends again on a tree change is not observable at that cut, because its refetch over a ready query settles before a fallback renders. A separate Solid two-resource Suspense witness holds one ready projection past the 50 ms unsubscribed floor while its sibling remains pending, then checks both commit and boundary abandonment release the temporary preload owner and preserve ordinary 1 ms teardown. | -| Backend Collection E2E | [shared provider suites](https://github.com/TanStack/db/tree/main/packages/db-collection-e2e/src/suites); [Electric registration](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/e2e/electric.e2e.test.ts); [Query registration](https://github.com/TanStack/db/blob/main/packages/query-db-collection/e2e/query.e2e.test.ts); [TrailBase registration](https://github.com/TanStack/db/blob/main/packages/trailbase-db-collection/e2e/trailbase.e2e.test.ts) | Electric, Query, and TrailBase register reusable predicate, pagination, join, and live-update checks at their provider boundaries; Electric also registers the move suite. These are receiving paths for core query and Collection laws, not framework render cuts. | +| Backend Collection E2E | [shared provider suites](https://github.com/TanStack/db/tree/main/packages/db-collection-e2e/src/suites); [Electric registration](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/e2e/electric.e2e.test.ts); [Query registration](https://github.com/TanStack/db/blob/main/packages/query-db-collection/e2e/query.e2e.test.ts); [TrailBase registration](https://github.com/TanStack/db/blob/main/packages/trailbase-db-collection/e2e/trailbase.e2e.test.ts); [Supabase registration](https://github.com/TanStack/db/blob/main/packages/supabase-db-collection/e2e/supabase.e2e.test.ts) | Electric, Query, TrailBase, and Supabase register reusable predicate, pagination, join, and live-update checks at their provider boundaries; Electric also registers the move suite. Supabase runs against a local Supabase stack (PostgREST and Realtime) and skips `should maintain query state during data changes`: local Realtime adds about 500 ms per change, so the case outlives the five-second cleanup of a live query without subscribers. These are receiving paths for core query and Collection laws, not framework render cuts. | | Window-controller overlap | [shared infinite-query conformance](https://github.com/TanStack/db/blob/main/packages/db/tests/conformance/infinite-suite-oracle.ts), [React driver](https://github.com/TanStack/db/blob/main/packages/react-db/tests/infinite-query-conformance.test.tsx), [Vue driver](https://github.com/TanStack/db/blob/main/packages/vue-db/tests/infinite-query-conformance.test.ts), [Svelte driver](https://github.com/TanStack/db/blob/main/packages/svelte-db/tests/infinite-query-conformance.svelte.test.ts), [Preact driver](https://github.com/TanStack/db/blob/main/packages/preact-db/tests/infinite-query-conformance.test.ts), [review record](oracle-reviews/dec-03-window-overlap.md) | Four or five ordered source rows, two window-settlement orders, and public snapshots after each settlement, a subscribed observer update, a detached controller read, and explicit recovery. Insertion and removal of the fifth row distinguish both continuation directions while an earlier error remains visible. The detached read follows a source change with no controller subscriber; its preloaded Collection retains the five-row window. The exact overlap uses the exported DB controller in each package realm. Framework hooks expose no controller preload, so this cell does not establish a hook scheduling path; direct hook paging remains in the adjacent shared scenarios. An unsubscribed controller has no notification claim. | | Infinite-query publication | [shared publication laws](https://github.com/TanStack/db/blob/main/packages/db/tests/conformance/infinite-suite-oracle.ts), [React render cuts](https://github.com/TanStack/db/blob/main/packages/react-db/tests/infinite-query-render-cuts-oracle.test.tsx), [Svelte hook tests](https://github.com/TanStack/db/blob/main/packages/svelte-db/tests/useLiveInfiniteQuery.svelte.test.ts), [review record](oracle-reviews/2026-10-05-infinite-first-paint.md) | Each driver records every value its framework published: React layout commits, Vue pre-flushes, and the Svelte construction value plus pre-effect runs. The shared suite checks that a synchronous source shows its ready first page on the first value, for a query callback and for a supplied collection that has not started, that every ready value in a fixed-source, fixed-query scenario equals the source prefix for its own page count, including an equal dependency replacement that keeps page depth, and that a mount requests an on-demand first window once, for a query callback and for a supplied collection whose finite window is wider than or equal to the one the hook needs, judged by the rows the on-demand source holds after mount. Under deferred acquisition, an on-demand first value is either the ready first page or a value with no rows, by framework: React and Svelte publish before the hook subscribes, Vue after. `preloaded-collection-first-paint` checks the documented route-loader pattern: a limited live query preloaded before mount shows its ready first page on the first value in every framework and asks the source for nothing more; a preload that does not count as demand never settles there. Pre-commit work has no shared form, because Vue setup is its commit. The React driver owns renders that never commit, StrictMode double renders (one first-window request on React 19), retries after GC, a mounted replacement whose startup error must reach the error boundary, and a collection kept from an abandoned render that enters terminal error before its query is selected again, each as under `useLiveQuery`. The React source ID reuse oracle drives the infinite hook too. Svelte owns construction and superseded recomputes before the subscribing effect. In both, the hook acquires an on-demand source as often as `useLiveQuery` does under the same history, for either input form, direct or behind a live-query Collection. On-demand requests from renders that never commit are now owned by the live-query deferred acquisition oracle; the React render-cut oracle checks that an abandoned render makes no acquisition. Open cells, owned here: React 18 StrictMode, where neither hook keeps refs across the double render; a React commit held after the 50 ms unsubscribed GC floor, where a controlled-premise controller witness shows no non-ready value but no React scheduling witness exists; ready values in scenarios that write the source or replace the query, which need a per-step source model; a join of eager and on-demand sources, which needs a zero-acquisition check before commit; a supplied collection with no `.limit`, which sends one unbounded request on `main` too, because the controller cannot narrow it before the source request; and Svelte `state_unsafe_mutation` when a start inside `$derived.by` synchronously writes rows a peer is waiting for, shared with Svelte's `useLiveQuery`, which a two-component probe reproduces and the deferred-acquisition follow-up removes. | | Structural values and ordered primitives | [hash values](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/hash-oracle.property.test.ts), [hash identity](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/hash-identity-oracle.property.test.ts), [MultiSet consolidation](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/multiset-consolidate-oracle.property.test.ts), [hash graphs](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/hash-graph-oracle.property.test.ts), [mixed hash graphs](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/hash-mixed-graph-oracle.property.test.ts), [hash retry](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/hash-failure-retry-oracle.property.test.ts), [murmur stream](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/murmur-stream-oracle.property.test.ts), [comparison](https://github.com/TanStack/db/blob/main/packages/db/tests/comparison-oracle.property.test.ts), [deep equality](https://github.com/TanStack/db/blob/main/packages/db/tests/utils-oracle.property.test.ts), [cursor](https://github.com/TanStack/db/blob/main/packages/db/tests/cursor-oracle.property.test.ts), [indexes](https://github.com/TanStack/db/blob/main/packages/db/tests/index-update-oracle.property.test.ts), [BTree Map](https://github.com/TanStack/db/blob/main/packages/db/tests/btree-map-oracle.test.ts), [query identity](https://github.com/TanStack/db/blob/main/packages/db/tests/query/identity-output-shape-oracle.test.ts), [LIKE semantics](https://github.com/TanStack/db/blob/main/packages/db/tests/query/compiler/evaluators-oracle.test.ts) | Independent flat values, graph topology, algebraic laws, structural object keys in code-unit order (the flat-value, identity and consolidation grammars include keys that tie under locale collation), murmur byte framing against a byte-at-a-time reference (block mixing, the finalizer and symbol framing have no owner there), Map/group/sort recomputation, expression denotation, custom comparator dispatch/reference identity/index compatibility, LIKE wildcard refinement, compiled output bags, declared value-pair agreement between D2 equality keys and IR equality operands, and Collection collation with exact public scan/index order and one-index reuse across repeated reads. The auto-index cells cross BasicIndex and BTreeIndex; scan cells omit indexes. Both paths cover lexical and numeric `en-US` locale defaults plus an explicit ordinary locale override of a numeric default. An unindexed six-row work cell bounds Collection collation resolution to at most two reads per ordered scan: one index-path check and one scan clause. Other locales and ordered histories are outside this owner. The identity pair grammar covers primitives, signed zero, NaN/invalid Date, valid Date/timestamp, binary/Buffer, Temporal, nested references, symbols, and functions; fixed and sampled pairs do not prove every JavaScript value or hash collision freedom. Ref proxies are expressions rather than literal values in this lane. The utility owner additionally generates widths 6–12 of ambiguous object-valued Sets. An independent count/capacity model judges equal reordered bags, late unmatched prototypes, multiplicity deficits, and a generic plain/class bridge that needs reassignment. Row comparison requires exact shape/value counts; generic equality permits keyed class/plain/null bridges. General and row comparison paths run in both directions, with acyclic members or links back to the Set. Separate cubic scalar-field-read and scoped native Map/Set-operation ceilings reject repeated-comparison and cached-candidate factorial searches without a timing assertion. Empty and singleton neighbors use the same model. Thirteen declared states each reach 200 histories. A paired-input lane adds widths 1,024–3,072, distinct/interchangeable members, and root-linked cycles. Its eight states each reach 20 histories; linear scalar-read and native-operation ceilings protect this equal corresponding-member family. Arbitrary unordered inputs retain the polynomial fallback; arbitrary graph topology and nested-value cost remain outside these bounded work laws. The deep-equality owner also pins that `deepEquals` ignores Map and Set insertion order, RegExp `lastIndex`, array holes, and typed-array class, the rules draft equality keeps. It also pins that `sameRowValue` preserves record prototypes (maintainer decision 2026-11-03), while exported `deepEquals` retains its established keyed-class/plain/null/cross-realm bridge, that a class instance without enumerable keys equals only itself, that URLs compare by `href`, and that typed-array elements compare like numbers. The hash-values owner checks equal-hash consequences for independently constructed flat values. Distinct type identities are checked by the hash-identity owner through `equalHashValues`, including forced digest collisions; distinct 32-bit digests are not promised. The hash-identity owner checks `hash` and `equalHashValues` against one spec-level identity model: primitives with signed zero, NaN, and bigint; reference leaves (functions, registered handles, `File`, binary over 128 bytes); Date, binary, Temporal, and RegExp headers; array length and holes; Map and Set insertion order; and object keys in any order, for acyclic values and for cycles through arrays, Map values, Sets, and plain objects. Map/Set order sensitivity is pinned current behavior, not a promise. Arrays from another realm, RegExps with a `NaN` `lastIndex`, getters, proxies, other cycle carriers, and pairs that differ only in a back-edge target are outside its grammar; pinned cases keep equality's cross-realm length check and strict RegExp field comparison. `hash-work.test.ts` pins how visited values and array/RegExp headers count toward the structural work cap, and that equality copies a shared Map's entries once per distinct pair ([code-weight hash dispatch review](oracle-reviews/code-weight-hash-dispatch.md)). Custom string indexes do not optimize ordinary ranges, and custom cursors remain unsupported. The LIKE owner covers boolean string matching and bounded work, not nullish three-valued logic or a general Unicode collation contract. Unsupported composite cursors reject. The MultiSet consolidation owner checks keyed, single-type, and structural identity, signed zero and NaN in keyed and single-number data, the retained first record, zero-sum removal, and input record contents. It does not assert output order. Its keyed grammar includes cross-type key and value collisions, non-finite numeric keys, the `\|` delimiter, symbol and function identity, and a direct-object/object-tuple delimiter control from #1948. Eight named collision witnesses and both generated campaigns are RED on `c879ba6d` and GREEN with the repair ([#1948 review record](oracle-reviews/issue-1948-keyed-consolidation.md)); the [code-weight consolidation review](oracle-reviews/code-weight-multiset-consolidation.md) records the earlier exclusion. The keyed reference uses direct value/reference equality, including SameValueZero for numeric keys. The unkeyed fallback keeps its original key and value domains. The direct `MultiSet` owner does not prove which `@tanstack/db` query shapes produce primitive keyed values or mixed-type source keys; that needs a live-query production witness. The index owner enforces one invalid-comparator law across both BasicIndex and BTreeIndex: for each comparator, accepted numeric prefix (including the empty prefix), and probe operation (add, update, eq/range lookup, take, build), the operation throws exactly when it receives a `NaN` or non-number result and never when every comparison is valid. A `signed infinity` comparator is the valid control, and a custom collation `compare` supplied through `compareOptions` is checked the same way. Two BTree Map split histories check inserted-key reads, exact whole-range payloads/order, size, and extrema, proving split placement follows the insertion index without a post-mutation comparison. A rejected index add or remove leaves the index refining its accepted rows; update and build are not atomic. At the Collection boundary, both index types and both write paths (optimistic insert, sync commit) crash the collection: status becomes `error` and the next mutation throws, so a usable collection never holds rows its subscribers were not told about. Open: a sync source can still commit writes on a collection in `error` state, which stores unpublished rows; this is existing `markError` behavior and needs a lifecycle-owner witness. Comparator transitivity is outside this evidence. | diff --git a/packages/supabase-db-collection/e2e/e2e.utils.ts b/packages/supabase-db-collection/e2e/e2e.utils.ts new file mode 100644 index 0000000000..660669a967 --- /dev/null +++ b/packages/supabase-db-collection/e2e/e2e.utils.ts @@ -0,0 +1,164 @@ +/* eslint-disable no-empty-pattern -- vitest fixtures without dependencies must destructure an empty context object */ +import { createClient } from '@supabase/supabase-js' +import { createCollection, createLiveQueryCollection } from '@tanstack/db' +import { QueryClient } from '@tanstack/query-core' +import { test as baseTest, expect, inject, vi } from 'vitest' +import { supabaseCollectionOptions } from '../src/index' +import { realtimeChannelTopicPrefix } from '../src/realtime' +import { usersSchema } from '../tests/test.utils' +import { makeAdminClient, resetE2e } from './setup' +import type { SupabaseClient } from '@supabase/supabase-js' + +// Shared polling window for awaiting async PostgREST/realtime propagation. +export const WAIT = { timeout: 15_000, interval: 200 } as const + +// A fresh Supabase client using the anon key, exactly like a browser would. +const makeSupabase = (): SupabaseClient => + createClient(inject('supabaseUrl'), inject('supabaseAnonKey')) + +// Each collection gets its own QueryClient: the realtime channel registry in +// src/db.ts is keyed by QueryClient, so a fresh one per collection prevents +// channels leaking across tests. +export const makeUsersCollection = ({ + realtime = false, + realtimeUseFilter = false, +} = {}) => { + const supabase = makeSupabase() + const collection = createCollection( + supabaseCollectionOptions({ + tableName: 'users', + keys: ['id'], + schema: usersSchema, + supabase, + queryClient: new QueryClient(), + realtime, + realtimeUseFilter, + }), + ) + return { collection, supabase } +} + +// A realtime collection that pushes each live query's WHERE down to the +// server-side postgres_changes filter (see realtimeUseFilter in src/db.ts). +export const makeFilteredRealtimeUsers = () => + makeUsersCollection({ realtime: true, realtimeUseFilter: true }) + +type UsersContext = ReturnType +type UsersCollection = UsersContext['collection'] + +// An on-demand collection only loads when a live query drives demand. This live +// query also creates the active query that the realtime channel attaches to. +const liveUsers = (base: UsersCollection) => + createLiveQueryCollection((q) => + q.from({ row: base }).select(({ row }) => ({ + id: row.id, + name: row.name, + email: row.email, + active: row.active, + })), + ) + +type LiveUsersCollection = ReturnType + +// Waits until one of the adapter's realtime channels for the table is actually +// joined, so changes written afterwards are guaranteed to be captured. The +// adapter numbers its channel topics (see realtimeChannelTopicPrefix in +// src/db.ts), and supabase-js exposes them under its own "realtime:" prefix. +export const waitForChannel = (supabase: SupabaseClient, table: string) => + vi.waitFor(() => { + const prefix = `realtime:${realtimeChannelTopicPrefix(table)}` + const joined = supabase + .getChannels() + .some((c) => c.topic.startsWith(prefix) && c.state === 'joined') + expect(joined).toBe(true) + }, WAIT) + +// A live query and its base collection both expose these; the helper below only +// needs to drive their lifecycle, not their query shape. +type Preloadable = { + preload: () => Promise + cleanup: () => Promise +} + +// Preloads one or more filtered realtime live queries over a shared collection +// and blocks until the channel has actually joined — which only happens once the +// server accepted the filters these queries emit, so it doubles as proof the +// emitted filter syntax is valid. Returns a cleanup to await in the test's +// `finally`, tearing down the live queries, the base collection, and the +// client's channels. +export const startFilteredRealtime = async ( + ctx: UsersContext, + ...lives: Array +) => { + await Promise.all(lives.map((live) => live.preload())) + await waitForChannel(ctx.supabase, 'users') + return async () => { + await Promise.all(lives.map((live) => live.cleanup())) + await ctx.collection.cleanup() + await ctx.supabase.removeAllChannels() + } +} + +const preloadSeeded = async (live: LiveUsersCollection) => { + await live.preload() + // The reset_e2e() seed always yields exactly Alice and Bob. + await vi.waitFor(() => expect(live.size).toBe(2), WAIT) +} + +// Fixtures are lazy: a test only pays for what it destructures. Teardown runs +// in reverse initialization order and ALWAYS runs, even when the test fails — +// unlike trailing cleanup calls in a test body. +export const test = baseTest.extend<{ + /** Base users collection + its anon client. */ + users: UsersContext + /** Preloaded live query over `users`, seeded rows awaited. */ + usersLive: LiveUsersCollection + /** Like `users` but with realtime enabled. */ + rtUsers: UsersContext + /** Preloaded live query over `rtUsers`, realtime channel joined. */ + rtUsersLive: LiveUsersCollection + /** A second anon client acting as "another user" for realtime writes. */ + other: SupabaseClient + /** Resets the users tables to the Alice/Bob fixture before every test. */ + resetDatabase: void +}>({ + resetDatabase: [ + async ({}, use) => { + await resetE2e(makeAdminClient()) + await use() + }, + { auto: true }, + ], + users: async ({}, use) => { + const ctx = makeUsersCollection() + await use(ctx) + await ctx.collection.cleanup() + await ctx.supabase.removeAllChannels() + }, + usersLive: async ({ users }, use) => { + const live = liveUsers(users.collection) + await preloadSeeded(live) + await use(live) + await live.cleanup() + }, + rtUsers: async ({}, use) => { + const ctx = makeUsersCollection({ realtime: true }) + await use(ctx) + await ctx.collection.cleanup() + await ctx.supabase.removeAllChannels() + }, + rtUsersLive: async ({ rtUsers }, use) => { + const live = liveUsers(rtUsers.collection) + await preloadSeeded(live) + // Wait until the realtime channel is joined before the test writes, + // otherwise a change could be published before the subscription exists. + await waitForChannel(rtUsers.supabase, 'users') + await use(live) + await live.cleanup() + }, + other: async ({}, use) => { + const client = makeSupabase() + await use(client) + await client.removeAllChannels() + }, +}) diff --git a/packages/supabase-db-collection/e2e/filters.e2e.test.ts b/packages/supabase-db-collection/e2e/filters.e2e.test.ts new file mode 100644 index 0000000000..91b267431a --- /dev/null +++ b/packages/supabase-db-collection/e2e/filters.e2e.test.ts @@ -0,0 +1,109 @@ +import { + IR, + and, + createLiveQueryCollection, + eq, + ilike, + inArray, + like, + not, + or, + upper, +} from '@tanstack/db' +import { expect } from 'vitest' +import { makeUsersCollection, test } from './e2e.utils' + +const name = new IR.PropRef([`user`, `name`]) +const active = new IR.PropRef([`user`, `active`]) +const id = new IR.PropRef([`user`, `id`]) + +// An on-demand live query sends its WHERE to PostgREST and becomes ready once +// that read has finished, so its rows are the server's answer filtered again +// on the client. A filter the server applies too strictly loses rows, which +// the client cannot add back. Each call reads through a fresh collection, so +// rows an earlier query loaded cannot hide the loss. +const liveNames = async (where: IR.BasicExpression) => { + const { collection, supabase } = makeUsersCollection() + const live = createLiveQueryCollection((q) => + q.from({ user: collection }).where(() => where), + ) + try { + await live.preload() + return live.toArray.map((row) => row.name).sort() + } finally { + await live.cleanup() + await collection.cleanup() + await supabase.removeAllChannels() + } +} + +const cases = [ + [`OR`, or(eq(name, `Alice`), eq(name, `Nobody`)), [`Alice`]], + [ + `nested AND/OR`, + or(and(eq(active, true), eq(name, `Bob`)), eq(id, 2)), + [`Bob`], + ], + [`NOT AND`, not(and(eq(active, true), eq(name, `Alice`))), [`Bob`]], + [`NOT OR`, not(or(eq(active, true), eq(name, `Nobody`))), [`Bob`]], + [`double NOT`, not(not(or(eq(active, true), eq(name, `Nobody`)))), [`Alice`]], + [`LIKE`, like(name, `A_i%`), [`Alice`]], + [`ILIKE`, ilike(name, `%ALI%`), [`Alice`]], + [`NOT LIKE`, not(like(name, `A%`)), [`Bob`]], + [ + `OR ILIKE`, + or(ilike(name, `%ali%`), ilike(name, `%bOB%`)), + [`Alice`, `Bob`], + ], + [`overlapping IN`, and(inArray(id, [1, 2]), inArray(id, [2, 3])), [`Bob`]], + [`empty IN`, inArray(id, []), []], + [`NOT empty IN`, not(inArray(id, [])), [`Alice`, `Bob`]], + [`NOT IN with null`, not(inArray(name, [`Alice`, null])), [`Bob`]], +] as const + +for (const [label, where, expected] of cases) { + test(`${label} returns matching rows through a live query`, async () => { + expect(await liveNames(where)).toEqual(expected) + }) +} + +for (const value of [``, ` a `, `a,b(c)`, `a"b\\c`, `a.b:c&d=1+%`, `{a,b}`]) { + test(`reserved value ${JSON.stringify(value)} round-trips through filters`, async ({ + other, + }) => { + const { error } = await other + .from(`users`) + .insert({ name: value, email: `special@test.com` } as unknown as never) + expect(error).toBeNull() + for (const where of [ + eq(name, value), + or(eq(name, value), eq(id, -1)), + inArray(name, [value]), + ]) { + expect(await liveNames(where), JSON.stringify(where)).toEqual([value]) + } + }) +} + +test(`LIKE treats backslashes literally`, async ({ other }) => { + const value = `a\\path` + const { error } = await other + .from(`users`) + .insert({ name: value, email: `slash@test.com` } as unknown as never) + expect(error).toBeNull() + for (const where of [ + like(name, `a\\%`), + or(like(name, `a\\%`), eq(id, -1)), + ]) { + expect(await liveNames(where), JSON.stringify(where)).toEqual([value]) + } +}) + +test(`unsupported OR and negated patterns retain rows for client filtering`, async () => { + expect( + await liveNames(or(eq(name, `Nobody`), eq(upper(name), `ALICE`))), + ).toEqual([`Alice`]) + // PostgREST would interpret * as a wildcard and remove Alice here, whereas + // TanStack treats it literally and should keep both seeded names. + expect(await liveNames(not(like(name, `*Ali*`)))).toEqual([`Alice`, `Bob`]) +}) diff --git a/packages/supabase-db-collection/e2e/global-setup.ts b/packages/supabase-db-collection/e2e/global-setup.ts new file mode 100644 index 0000000000..7a71deeca6 --- /dev/null +++ b/packages/supabase-db-collection/e2e/global-setup.ts @@ -0,0 +1,173 @@ +import { execFile } from 'node:child_process' +import { fileURLToPath } from 'node:url' +import { promisify } from 'node:util' +import { createClient } from '@supabase/supabase-js' +import type { TestProject } from 'vitest/node' + +const execFileAsync = promisify(execFile) + +// The Supabase project (config.toml and migrations) lives in this package, +// regardless of the directory vitest was launched from. +const PACKAGE_DIR = fileURLToPath(new URL(`..`, import.meta.url)) + +// Generous enough for a cold CI runner to pull the container images. +const START_TIMEOUT_MS = 600_000 +const STOP_TIMEOUT_MS = 120_000 + +// Realtime warm-up: a freshly started realtime container needs a moment before +// its Postgres replication is fully wired, so the first subscription can miss +// changes. We subscribe to the dedicated e2e_warmup scratch table and upsert +// rows into it until an event is actually delivered, guaranteeing realtime is +// live before any test runs - without ever touching the tables tests read. +const WARMUP_TIMEOUT_MS = 60_000 +const WARMUP_ATTEMPTS = 40 +const WARMUP_POKE_INTERVAL_MS = 1000 + +const delay = (ms: number): Promise => + new Promise((resolve) => { + setTimeout(resolve, ms) + }) + +// Values published to the e2e test workers via `inject(...)` (see setup.ts). +declare module 'vitest' { + export interface ProvidedContext { + supabaseAnonKey: string + supabaseServiceRoleKey: string + supabaseUrl: string + } +} + +interface SupabaseStatus { + API_URL?: string + ANON_KEY?: string + SERVICE_ROLE_KEY?: string +} + +// The CLI invocation, e.g. `supabase` (default) or `pnpm dlx supabase@2.116.0`. +const cliCommand = (): [string, Array] => { + const [command, ...args] = (process.env.SUPABASE_CLI ?? `supabase`) + .split(` `) + .filter(Boolean) + return [command ?? `supabase`, args] +} + +const runSupabase = (args: Array, timeout: number) => { + const [command, baseArgs] = cliCommand() + return execFileAsync(command, [...baseArgs, ...args], { + cwd: PACKAGE_DIR, + timeout, + }) +} + +// Returns the parsed `supabase status` JSON, or null when no stack is running. +const readStatus = async (): Promise => { + try { + const { stdout } = await runSupabase( + [`status`, `-o`, `json`], + STOP_TIMEOUT_MS, + ) + return JSON.parse(stdout.slice(stdout.indexOf(`{`))) as SupabaseStatus + } catch (error) { + // A missing CLI binary is a setup problem, not a stopped stack - surface it + // instead of falling through to a confusing `supabase start`. + if ((error as NodeJS.ErrnoException).code === `ENOENT`) { + throw new Error( + `Could not run the Supabase CLI. Install it, or point SUPABASE_CLI at it (e.g. SUPABASE_CLI="pnpm dlx supabase@2.116.0").`, + ) + } + // Non-zero exit (stack not running) or non-JSON output: treat as no stack. + return null + } +} + +const warmUpRealtime = async (url: string, anonKey: string): Promise => { + const client = createClient(url, anonKey) + let received = false + + // Upserts never conflict with rows left over from a previous run of the same + // stack, and every upsert produces a WAL change (INSERT or UPDATE) for the + // listener below. supabase-js resolves with { error } instead of throwing. + const poke = async (): Promise => { + for (let attempt = 0; attempt < WARMUP_ATTEMPTS && !received; attempt++) { + await client.from(`e2e_warmup`).upsert({ id: attempt }) + await delay(WARMUP_POKE_INTERVAL_MS) + } + } + + try { + await new Promise((resolve, reject) => { + const timer = setTimeout( + () => + reject( + new Error( + `Realtime warm-up timed out; is the realtime container healthy?`, + ), + ), + WARMUP_TIMEOUT_MS, + ) + client + .channel(`e2e-warmup`) + .on( + `postgres_changes`, + { event: `*`, schema: `public`, table: `e2e_warmup` }, + () => { + received = true + clearTimeout(timer) + resolve() + }, + ) + .subscribe((status) => { + if (status === `SUBSCRIBED`) { + poke().catch(() => undefined) + } + }) + }) + } finally { + await client.removeAllChannels() + } +} + +export default async function setup({ provide }: TestProject) { + let startedByUs = false + let url = process.env.SUPABASE_URL + let anonKey = process.env.SUPABASE_ANON_KEY + let serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY + + // Only touch Docker when creds were not already supplied by the environment. + if (!(url && anonKey && serviceRoleKey)) { + let status = await readStatus() + + if (!status) { + // Boots only the containers the adapter needs (db, kong, rest, realtime, + // auth); the rest are disabled in supabase/config.toml. + await runSupabase([`start`], START_TIMEOUT_MS) + startedByUs = true + status = await readStatus() + } + + if (!(status?.API_URL && status.ANON_KEY && status.SERVICE_ROLE_KEY)) { + throw new Error( + `Could not resolve local Supabase credentials. Is Docker running? Try \`supabase start\` in packages/supabase-db-collection.`, + ) + } + + url = status.API_URL + anonKey = status.ANON_KEY + serviceRoleKey = status.SERVICE_ROLE_KEY + } + + // Confirm realtime is actually delivering before tests rely on it. + await warmUpRealtime(url, anonKey) + + provide(`supabaseUrl`, url) + provide(`supabaseAnonKey`, anonKey) + provide(`supabaseServiceRoleKey`, serviceRoleKey) + + return async () => { + // Only stop the stack if this setup started it; never tear down a stack the + // developer (or CI) started separately. + if (startedByUs) { + await runSupabase([`stop`], STOP_TIMEOUT_MS) + } + } +} diff --git a/packages/supabase-db-collection/e2e/mutations.e2e.test.ts b/packages/supabase-db-collection/e2e/mutations.e2e.test.ts new file mode 100644 index 0000000000..3da74d1a9e --- /dev/null +++ b/packages/supabase-db-collection/e2e/mutations.e2e.test.ts @@ -0,0 +1,116 @@ +import { expect, vi } from 'vitest' +import { keyColumnsToSearch } from '../src/postgrest-filters' +import { postgrestRequest } from '../src/postgrest-request' +import { WAIT, test } from './e2e.utils' + +test('update and delete filters preserve timestamp key milliseconds', async ({ + other, +}) => { + const timestamp = new Date('2024-01-01T12:30:00.123Z') + const neighbor = '2024-01-01T12:30:00.456Z' + const { error: insertError } = await other.from('timestamp_keys').insert([ + { recorded_at: timestamp.toISOString(), label: 'target' }, + { recorded_at: neighbor, label: 'neighbor' }, + ]) + expect(insertError).toBeNull() + + await postgrestRequest(other, 'timestamp_keys', { + method: 'PATCH', + search: keyColumnsToSearch(['recorded_at'], { recorded_at: timestamp }), + body: { label: 'updated' }, + }) + const { data: updated, error: updateError } = await other + .from('timestamp_keys') + .select('label') + .order('recorded_at') + expect(updateError).toBeNull() + expect(updated).toEqual([{ label: 'updated' }, { label: 'neighbor' }]) + + await postgrestRequest(other, 'timestamp_keys', { + method: 'DELETE', + search: keyColumnsToSearch(['recorded_at'], { recorded_at: timestamp }), + }) + const { data: remaining, error: deleteError } = await other + .from('timestamp_keys') + .select('label') + expect(deleteError).toBeNull() + expect(remaining).toEqual([{ label: 'neighbor' }]) +}) + +test('inserts a row through PostgREST and reflects the server row', async ({ + users, + usersLive, +}) => { + const tx = users.collection.insert({ + id: 100, + name: 'Carol', + email: 'carol@test.com', + active: true, + }) + await tx.when('settled') + + await vi.waitFor( + () => + expect(usersLive.toArray.some((user) => user.name === 'Carol')).toBe( + true, + ), + WAIT, + ) + expect(usersLive.toArray.find((user) => user.name === 'Carol')?.id).toBe(100) + + // The row really exists in the database. + const { data, error } = await users.supabase + .from('users') + .select('*') + .eq('email', 'carol@test.com') + .single() + expect(error).toBeNull() + expect(data?.name).toBe('Carol') +}) + +test('updates a row through PostgREST and reflects the server row', async ({ + users, + usersLive, +}) => { + const alice = usersLive.toArray.find((user) => user.name === 'Alice') + + const tx = users.collection.update(String(alice?.id), (draft) => { + draft.name = 'Alice Updated' + }) + await tx.when('settled') + + await vi.waitFor( + () => + expect( + usersLive.toArray.find((user) => user.id === alice?.id)?.name, + ).toBe('Alice Updated'), + WAIT, + ) + + const { data, error } = await users.supabase + .from('users') + .select('*') + .eq('id', alice?.id) + .single() + expect(error).toBeNull() + expect(data?.name).toBe('Alice Updated') +}) + +test('deletes a row through PostgREST', async ({ users, usersLive }) => { + const bob = usersLive.toArray.find((user) => user.name === 'Bob') + + const tx = users.collection.delete(String(bob?.id)) + await tx.when('settled') + + await vi.waitFor( + () => + expect(usersLive.toArray.some((user) => user.id === bob?.id)).toBe(false), + WAIT, + ) + + const { data } = await users.supabase + .from('users') + .select('*') + .eq('id', bob?.id) + expect(data).toEqual([]) +}) diff --git a/packages/supabase-db-collection/e2e/reads.e2e.test.ts b/packages/supabase-db-collection/e2e/reads.e2e.test.ts new file mode 100644 index 0000000000..a868e0a24d --- /dev/null +++ b/packages/supabase-db-collection/e2e/reads.e2e.test.ts @@ -0,0 +1,120 @@ +import { createLiveQueryCollection, eq, inArray } from '@tanstack/db' +import { expect, vi } from 'vitest' +import { WAIT, test } from './e2e.utils' + +test('reads seeded rows through PostgREST', ({ usersLive }) => { + const names = usersLive.toArray.map((user) => user.name).sort() + expect(names).toEqual(['Alice', 'Bob']) +}) + +test('pushes a WHERE filter down to PostgREST', async ({ users }) => { + // Seeded fixture: Alice is active, Bob is not — so active=true returns one row. + const live = createLiveQueryCollection((q) => + q + .from({ row: users.collection }) + .where(({ row }) => eq(row.active, true)) + .select(({ row }) => ({ id: row.id, name: row.name })), + ) + + // finally (not fixture teardown) so this live query is cleaned up before the + // `users` fixture tears down the base collection it depends on. + try { + await live.preload() + await vi.waitFor(() => expect(live.size).toBe(1), WAIT) + expect(live.toArray[0]?.name).toBe('Alice') + } finally { + await live.cleanup() + } +}) + +test('reads a set larger than the server row cap across pages', async ({ + users, + other, +}) => { + // config.toml caps responses at 2 rows; reset_e2e seeds Alice + Bob, so three + // more rows push the matching set past the cap and force the paging loop. + const { error } = await other.from('users').insert([ + { name: 'Carol', email: 'carol@test.com', active: true }, + { name: 'Dave', email: 'dave@test.com', active: true }, + { name: 'Erin', email: 'erin@test.com', active: true }, + ] as unknown as never) + expect(error).toBeNull() + + const live = createLiveQueryCollection((q) => + q + .from({ row: users.collection }) + .select(({ row }) => ({ id: row.id, name: row.name })), + ) + + try { + await live.preload() + await vi.waitFor(() => expect(live.size).toBe(5), WAIT) + // The full set comes back despite the cap, with each row exactly once. + expect(live.toArray.map((row) => row.name).sort()).toEqual([ + 'Alice', + 'Bob', + 'Carol', + 'Dave', + 'Erin', + ]) + expect(new Set(live.toArray.map((row) => row.id)).size).toBe(5) + } finally { + await live.cleanup() + } +}) + +// Empirically confirmed against the local stack (Kong): a raw request with +// 1,500 sequential ids renders to ~9.4 KB and comes back `414 Request-URI Too +// Large` with an `error.message` mentioning the URI length. 500-1,200 ids +// (~3-7.3 KB) still succeed, so the failure is specifically the request-line +// limit this feature works around, not some unrelated cap. +test('a raw oversized IN filter is rejected by the gateway (baseline)', async ({ + other, +}) => { + const ids = Array.from({ length: 1500 }, (_, i) => i + 1) + const { data, error, status } = await other + .from('users') + .select() + .in('id', ids) + + expect(data).toBeNull() + expect(status).toBe(414) + expect(error?.message).toMatch(/too long/i) +}) + +test('the same oversized IN filter comes back complete through a collection', async ({ + users, + other, +}) => { + // Seed enough matching rows that the split spans more than one chunk: Alice + // (id 1) and Bob (id 2) from reset_e2e, plus 50 more (ids 3-52). + const extras = Array.from({ length: 50 }, (_, i) => ({ + name: `Extra ${i}`, + email: `extra${i}@test.com`, + active: true, + })) + const { error: insertError } = await other + .from('users') + .insert(extras as unknown as never) + expect(insertError).toBeNull() + + // Same size (and shape) as the raw request above, which the gateway + // rejected outright — this is the request the adapter must split. + const ids = Array.from({ length: 1500 }, (_, i) => i + 1) + const live = createLiveQueryCollection((q) => + q + .from({ row: users.collection }) + .where(({ row }) => inArray(row.id, ids)) + .select(({ row }) => ({ id: row.id, name: row.name })), + ) + + try { + await live.preload() + await vi.waitFor(() => expect(live.size).toBe(52), WAIT) + // Every matching row exactly once, despite coming back over several + // concatenated chunk requests. + expect(new Set(live.toArray.map((row) => row.id)).size).toBe(52) + } finally { + await live.cleanup() + } +}) diff --git a/packages/supabase-db-collection/e2e/realtime-filters.e2e.test.ts b/packages/supabase-db-collection/e2e/realtime-filters.e2e.test.ts new file mode 100644 index 0000000000..f9521af911 --- /dev/null +++ b/packages/supabase-db-collection/e2e/realtime-filters.e2e.test.ts @@ -0,0 +1,513 @@ +import { + and, + createLiveQueryCollection, + eq, + gt, + gte, + inArray, + isNull, + lt, + lte, + not, + or, +} from '@tanstack/db' +import { expect, vi } from 'vitest' +import { + WAIT, + makeFilteredRealtimeUsers, + startFilteredRealtime, + test, +} from './e2e.utils' + +// These tests drive the realtimeUseFilter path end to end: a live query's WHERE +// becomes a server-side postgres_changes filter via realtimeFiltersToSearch. +// Unit tests only prove we format the filter string correctly against a mock +// channel; these prove the REAL Supabase Realtime server both accepts that +// syntax and evaluates it — when the server rejects a filter the adapter +// silently falls back to catch-all, so a broken operator would pass unit tests +// yet stop filtering in production. Each test's waitForChannel (inside +// startFilteredRealtime) only resolves once the server accepted the filter. + +// Builds a filtered realtime users row payload. Ids stay above the Alice/Bob +// seed (1, 2) so inserts never collide with the reset_e2e() identity sequence. +const userRow = ( + id: number, + over: Partial<{ name: string; email: string; active: boolean }> = {}, +) => ({ id, name: `u${id}`, email: `u${id}@test.com`, active: true, ...over }) + +// ── Value quoting (reserved characters + whitespace) ────────────────── +// Names deliberately exercise quoteValue's branches: a comma (reserved) and +// surrounding whitespace (only quoted since realtimeFiltersToSearch adopted the +// shared quoteValue). Both must round-trip through the real server. +const QUOTED_NAMES = ['Doe, Jane', ' spaced '] as const + +for (const value of QUOTED_NAMES) { + test(`realtime filter on ${JSON.stringify(value)} delivers matching inserts`, async ({ + other, + }) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => eq(row.name, value)) + .select(({ row }) => ({ id: row.id, name: row.name })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + const { error } = await other + .from('users') + .insert([ + { ...userRow(300), name: value }, + userRow(301, { name: 'Someone Else' }), + ] as unknown as never) + expect(error).toBeNull() + + await vi.waitFor( + () => expect(live.toArray.map((row) => row.name)).toEqual([value]), + WAIT, + ) + expect(ctx.collection.toArray.some((r) => r.id === 301)).toBe(false) + } finally { + await cleanup() + } + }) +} + +// ── Operator matrix: does the real server accept each emitted operator? ─ +// Every case inserts one matching and one non-matching row and asserts only the +// match is delivered through the filtered subscription. Membership checks (not +// exact arrays) keep the assertions robust against seed rows a filter may also +// select (e.g. lt over ids includes Alice/Bob). +const COMPARISONS = [ + { op: 'gt', pivot: 100, match: 101, miss: 99 }, + { op: 'gte', pivot: 100, match: 100, miss: 99 }, + { op: 'lt', pivot: 500, match: 400, miss: 600 }, + { op: 'lte', pivot: 400, match: 400, miss: 600 }, +] as const + +for (const c of COMPARISONS) { + test(`realtime filter ${c.op} is accepted and evaluated by the server`, async ({ + other, + }) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => { + switch (c.op) { + case 'gt': + return gt(row.id, c.pivot) + case 'gte': + return gte(row.id, c.pivot) + case 'lt': + return lt(row.id, c.pivot) + default: + return lte(row.id, c.pivot) + } + }) + .select(({ row }) => ({ id: row.id })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + const { error } = await other + .from('users') + .insert([userRow(c.match), userRow(c.miss)] as unknown as never) + expect(error).toBeNull() + + await vi.waitFor( + () => expect(live.toArray.some((row) => row.id === c.match)).toBe(true), + WAIT, + ) + expect(live.toArray.some((row) => row.id === c.miss)).toBe(false) + // Under a correct server-side filter the excluded row is never delivered, + // so it must not reach the BASE collection either. A silent fallback to a + // catch-all subscription would sync it here, which the live query's own + // client-side re-filtering would otherwise hide. + expect(ctx.collection.toArray.some((row) => row.id === c.miss)).toBe( + false, + ) + } finally { + await cleanup() + } + }) +} + +test('realtime filter neq (boolean) delivers only non-matching-value rows', async ({ + other, +}) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => not(eq(row.active, true))) + .select(({ row }) => ({ id: row.id, active: row.active })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + const { error } = await other + .from('users') + .insert([ + userRow(300, { active: false }), + userRow(301, { active: true }), + ] as unknown as never) + expect(error).toBeNull() + + await vi.waitFor( + () => expect(live.toArray.some((row) => row.id === 300)).toBe(true), + WAIT, + ) + expect(live.toArray.some((row) => row.id === 301)).toBe(false) + // A silent fallback to catch-all would sync the excluded row into the base. + expect(ctx.collection.toArray.some((row) => row.id === 301)).toBe(false) + } finally { + await cleanup() + } +}) + +test('realtime filter not.gt (negated comparison) is accepted server-side', async ({ + other, +}) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => not(gt(row.id, 100))) + .select(({ row }) => ({ id: row.id })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + const { error } = await other + .from('users') + .insert([userRow(99), userRow(101)] as unknown as never) + expect(error).toBeNull() + + await vi.waitFor( + () => expect(live.toArray.some((row) => row.id === 99)).toBe(true), + WAIT, + ) + expect(live.toArray.some((row) => row.id === 101)).toBe(false) + // A silent fallback to catch-all would sync the excluded row into the base. + expect(ctx.collection.toArray.some((row) => row.id === 101)).toBe(false) + } finally { + await cleanup() + } +}) + +test('realtime filter in.(...) is accepted and matches list members', async ({ + other, +}) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => inArray(row.id, [301, 302])) + .select(({ row }) => ({ id: row.id })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + const { error } = await other + .from('users') + .insert([userRow(301), userRow(303)] as unknown as never) + expect(error).toBeNull() + + await vi.waitFor( + () => expect(live.toArray.some((row) => row.id === 301)).toBe(true), + WAIT, + ) + expect(live.toArray.some((row) => row.id === 303)).toBe(false) + // A silent fallback to catch-all would sync the excluded row into the base. + expect(ctx.collection.toArray.some((row) => row.id === 303)).toBe(false) + } finally { + await cleanup() + } +}) + +test('realtime filter not.in excludes list members', async ({ other }) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => not(inArray(row.id, [301]))) + .select(({ row }) => ({ id: row.id })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + const { error } = await other + .from('users') + .insert([userRow(302), userRow(301)] as unknown as never) + expect(error).toBeNull() + + await vi.waitFor( + () => expect(live.toArray.some((row) => row.id === 302)).toBe(true), + WAIT, + ) + expect(live.toArray.some((row) => row.id === 301)).toBe(false) + // A silent fallback to catch-all would sync the excluded row into the base. + expect(ctx.collection.toArray.some((row) => row.id === 301)).toBe(false) + } finally { + await cleanup() + } +}) + +// The seed schema has no nullable column (name is NOT NULL), so a matching row +// for `is.null` cannot exist. We therefore only smoke-test `not.is.null`: it +// proves the server accepts the is/not.is syntax and still delivers. The +// positive `is.null` match stays unit-tested. +test('realtime filter not.is.null is accepted and delivers rows', async ({ + other, +}) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => not(isNull(row.name))) + .select(({ row }) => ({ id: row.id })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + const { error } = await other + .from('users') + .insert([userRow(300)] as unknown as never) + expect(error).toBeNull() + + await vi.waitFor( + () => expect(live.toArray.some((row) => row.id === 300)).toBe(true), + WAIT, + ) + } finally { + await cleanup() + } +}) + +test('realtime filter accepts a 100-member in.(...) list', async ({ + other, +}) => { + const ids = Array.from({ length: 100 }, (_, i) => 300 + i) + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => inArray(row.id, ids)) + .select(({ row }) => ({ id: row.id })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + const { error } = await other + .from('users') + .insert([userRow(350), userRow(999)] as unknown as never) + expect(error).toBeNull() + + await vi.waitFor( + () => expect(live.toArray.some((row) => row.id === 350)).toBe(true), + WAIT, + ) + expect(live.toArray.some((row) => row.id === 999)).toBe(false) + // A silent fallback to catch-all would sync the excluded row into the base. + expect(ctx.collection.toArray.some((row) => row.id === 999)).toBe(false) + } finally { + await cleanup() + } +}) + +// A composite AND becomes a single comma-joined condition list +// (`id=gt.300,id=lt.500`). Unit tests prove we format it; this proves the real +// server accepts a multi-condition filter and evaluates every condition rather +// than silently rejecting it (which would fall back to catch-all). +test('realtime filter with two AND-ed conditions is accepted and evaluated', async ({ + other, +}) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => and(gt(row.id, 300), lt(row.id, 500))) + .select(({ row }) => ({ id: row.id })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + const { error } = await other + .from('users') + .insert([userRow(400), userRow(600)] as unknown as never) + expect(error).toBeNull() + + await vi.waitFor( + () => expect(live.toArray.some((row) => row.id === 400)).toBe(true), + WAIT, + ) + // 600 satisfies gt.300 but not lt.500: it must be excluded, proving the + // server honours both conditions and did not fall back to catch-all. + expect(live.toArray.some((row) => row.id === 600)).toBe(false) + expect(ctx.collection.toArray.some((row) => row.id === 600)).toBe(false) + } finally { + await cleanup() + } +}) + +// ── Filter-window UPDATE / DELETE correctness ───────────────────────── +// A row that leaves the filter window disappears from the live query (which +// re-filters client-side) but must stay fresh in the BASE collection, kept +// current by the extra unfiltered UPDATE listener. So these assert on the base +// collection, not the live query. +test('UPDATE moving a row out of the filter window keeps it fresh', async ({ + other, +}) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => eq(row.active, true)) + .select(({ row }) => ({ id: row.id, active: row.active })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + const aliceInBase = () => ctx.collection.toArray.find((r) => r.id === 1) + try { + // Seed: only Alice (id 1) is active, so she is synced into the base. + await vi.waitFor(() => expect(aliceInBase()).toBeDefined(), WAIT) + + // Move Alice out of the active=true window. + const { error } = await other + .from('users') + .update({ active: false } as unknown as never) + .eq('id', 1) + expect(error).toBeNull() + + // The unfiltered UPDATE listener still applied the change instead of + // leaving a stale active=true row behind. Applying it is a manual write, + // which makes query-db-collection revalidate its on-demand queries; the + // active=true query then no longer owns Alice, so she may also be dropped + // from the base entirely. Either outcome is fresh; only active=true is stale. + await vi.waitFor( + () => expect(aliceInBase()?.active ?? false).toBe(false), + WAIT, + ) + } finally { + await cleanup() + } +}) + +test('UPDATE moving a row into the filter window delivers it', async ({ + other, +}) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => eq(row.active, true)) + .select(({ row }) => ({ id: row.id })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + // Seed: Bob (id 2) is inactive, so he starts outside the window. + await vi.waitFor( + () => expect(live.toArray.some((r) => r.id === 2)).toBe(false), + WAIT, + ) + + const { error } = await other + .from('users') + .update({ active: true } as unknown as never) + .eq('id', 2) + expect(error).toBeNull() + + // The filtered UPDATE listener upserts the row now that it matches. + await vi.waitFor( + () => expect(live.toArray.some((r) => r.id === 2)).toBe(true), + WAIT, + ) + } finally { + await cleanup() + } +}) + +test('DELETE is delivered even while a server-side filter is active', async ({ + other, +}) => { + const ctx = makeFilteredRealtimeUsers() + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => eq(row.active, true)) + .select(({ row }) => ({ id: row.id })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + const aliceInBase = () => ctx.collection.toArray.some((r) => r.id === 1) + try { + await vi.waitFor(() => expect(aliceInBase()).toBe(true), WAIT) + + const { error } = await other.from('users').delete().eq('id', 1) + expect(error).toBeNull() + + // Deletes are never filtered; the unfiltered DELETE listener removes it. + await vi.waitFor(() => expect(aliceInBase()).toBe(false), WAIT) + } finally { + await cleanup() + } +}) + +// ── Multiple active queries & catch-all fallback ────────────────────── +test('two filtered live queries over one collection stay isolated', async ({ + other, +}) => { + const ctx = makeFilteredRealtimeUsers() + const liveX = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => eq(row.id, 301)) + .select(({ row }) => ({ id: row.id })), + ) + const liveY = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => eq(row.id, 302)) + .select(({ row }) => ({ id: row.id })), + ) + const cleanup = await startFilteredRealtime(ctx, liveX, liveY) + try { + const { error } = await other + .from('users') + .insert([userRow(301), userRow(302), userRow(303)] as unknown as never) + expect(error).toBeNull() + + await vi.waitFor(() => { + expect(liveX.toArray.map((r) => r.id)).toEqual([301]) + expect(liveY.toArray.map((r) => r.id)).toEqual([302]) + }, WAIT) + // 303 matches neither filtered subscription, so it never syncs. + expect(ctx.collection.toArray.some((r) => r.id === 303)).toBe(false) + } finally { + await cleanup() + } +}) + +test('an unsupported WHERE falls back to catch-all but still syncs', async ({ + other, +}) => { + const ctx = makeFilteredRealtimeUsers() + // OR is not pushable to a Realtime filter, so realtimeFiltersToSearch yields a + // catch-all (unfiltered) subscription; the live query re-filters client-side. + const live = createLiveQueryCollection((q) => + q + .from({ row: ctx.collection }) + .where(({ row }) => or(eq(row.name, 'Xavier'), eq(row.name, 'Yolanda'))) + .select(({ row }) => ({ id: row.id, name: row.name })), + ) + const cleanup = await startFilteredRealtime(ctx, live) + try { + const { error } = await other + .from('users') + .insert([ + userRow(300, { name: 'Xavier' }), + userRow(301, { name: 'Zoe' }), + ] as unknown as never) + expect(error).toBeNull() + + // The matching row arrives through the degraded (unfiltered) subscription + // and passes the client-side OR filter. + await vi.waitFor( + () => expect(live.toArray.map((r) => r.name)).toEqual(['Xavier']), + WAIT, + ) + } finally { + await cleanup() + } +}) diff --git a/packages/supabase-db-collection/e2e/realtime.e2e.test.ts b/packages/supabase-db-collection/e2e/realtime.e2e.test.ts new file mode 100644 index 0000000000..3bc86c6a14 --- /dev/null +++ b/packages/supabase-db-collection/e2e/realtime.e2e.test.ts @@ -0,0 +1,64 @@ +import { expect, vi } from 'vitest' +import { WAIT, test } from './e2e.utils' + +// The rtUsersLive fixture guarantees the realtime channel is joined before the +// test body runs, so writes from the `other` client always arrive as events. + +test('receives realtime inserts made by another client', async ({ + rtUsersLive, + other, +}) => { + const draft = { id: 200, name: 'Zoe', email: 'zoe@test.com', active: true } + const { error } = await other.from('users').insert(draft as unknown as never) + expect(error).toBeNull() + + await vi.waitFor( + () => + expect(rtUsersLive.toArray.some((user) => user.name === 'Zoe')).toBe( + true, + ), + WAIT, + ) +}) + +test('receives realtime updates made by another client', async ({ + rtUsersLive, + other, +}) => { + const alice = rtUsersLive.toArray.find((user) => user.name === 'Alice') + + const { error } = await other + .from('users') + .update({ name: 'Alice Realtime' }) + .eq('id', alice?.id) + expect(error).toBeNull() + + await vi.waitFor( + () => + expect( + rtUsersLive.toArray.find((user) => user.id === alice?.id)?.name, + ).toBe('Alice Realtime'), + WAIT, + ) +}) + +// Exercises the delete path, where the adapter derives the collection key from +// the realtime payload's `old`. That works here because the collection key is +// the primary key, which the default replica identity always includes. +test('receives realtime deletes made by another client', async ({ + rtUsersLive, + other, +}) => { + const bob = rtUsersLive.toArray.find((user) => user.name === 'Bob') + + const { error } = await other.from('users').delete().eq('id', bob?.id) + expect(error).toBeNull() + + await vi.waitFor( + () => + expect(rtUsersLive.toArray.some((user) => user.id === bob?.id)).toBe( + false, + ), + WAIT, + ) +}) diff --git a/packages/supabase-db-collection/e2e/setup.ts b/packages/supabase-db-collection/e2e/setup.ts new file mode 100644 index 0000000000..26b92a7aad --- /dev/null +++ b/packages/supabase-db-collection/e2e/setup.ts @@ -0,0 +1,27 @@ +import { createClient } from '@supabase/supabase-js' +import { inject } from 'vitest' + +/** + * A service_role (admin) client, which bypasses RLS. Only the e2e setup and + * seeding code uses it; the collections under test use the anon key. + */ +export const makeAdminClient = () => + createClient(inject('supabaseUrl'), inject('supabaseServiceRoleKey'), { + auth: { persistSession: false }, + }) + +/** + * Truncates the adapter's own test tables (restart identity) and re-seeds the + * fixture rows in a single transactional round trip, so every test starts from + * the same state: Alice (id 1, active) and Bob (id 2, inactive). + * + * This is opt-in per test file (via the `test` export of ./e2e.utils) rather + * than a global `beforeEach`, so it never runs for suites that own different + * tables, such as the shared @tanstack/db-collection-e2e suites. + */ +export const resetE2e = async (admin: ReturnType) => { + const { error } = await admin.rpc('reset_e2e') + if (error) { + throw new Error(`e2e reset failed: ${error.message}`) + } +} diff --git a/packages/supabase-db-collection/e2e/supabase.e2e.test.ts b/packages/supabase-db-collection/e2e/supabase.e2e.test.ts new file mode 100644 index 0000000000..d70d9cdc98 --- /dev/null +++ b/packages/supabase-db-collection/e2e/supabase.e2e.test.ts @@ -0,0 +1,366 @@ +/** + * Supabase Collection E2E Tests + * + * End-to-end tests against a local Supabase stack (PostgREST + Realtime), using + * the shared test suites from @tanstack/db-collection-e2e. The stack is booted + * by ./global-setup.ts and its schema lives in supabase/migrations. + */ + +import { afterEach, beforeEach, describe, expect, inject } from 'vitest' +import { createClient } from '@supabase/supabase-js' +import { createCollection } from '@tanstack/db' +import { QueryClient } from '@tanstack/query-core' +import { z } from 'zod' +import { + captureSeedData, + createCollationTestSuite, + createDeduplicationTestSuite, + createJoinsTestSuite, + createLiveUpdatesTestSuite, + createMutationsTestSuite, + createPaginationTestSuite, + createPredicatesTestSuite, + generateSeedData, +} from '@tanstack/db-collection-e2e' +import { supabaseCollectionOptions } from '../src/index' +import { makeAdminClient } from './setup' +import type { SupabaseClient } from '@supabase/supabase-js' +import type { Collection } from '@tanstack/db' +import type { + Comment, + E2ETestConfig, + Post, + SeedDataResult, + User, +} from '@tanstack/db-collection-e2e' + +/** + * Rows as PostgREST and Realtime deliver them: JSON, so timestamps are strings + * and bigints are numbers. The collections convert them into the `User`, + * `Post` and `Comment` types with `parse`, and back with `serialize`. + */ +const userSchema = z.object({ + id: z.string(), + name: z.string(), + email: z.string().nullable(), + age: z.number(), + isActive: z.boolean(), + createdAt: z.date(), + metadata: z.record(z.string(), z.unknown()).nullable(), + deletedAt: z.date().nullable(), +}) + +const postSchema = z.object({ + id: z.string(), + userId: z.string(), + title: z.string(), + content: z.string().nullable(), + viewCount: z.number(), + largeViewCount: z.bigint(), + publishedAt: z.date().nullable(), + deletedAt: z.date().nullable(), +}) + +const commentSchema = z.object({ + id: z.string(), + postId: z.string(), + userId: z.string(), + text: z.string(), + createdAt: z.date(), + deletedAt: z.date().nullable(), +}) + +const parseDate = (value: unknown) => new Date(value as string) +const dateToJson = (value: Date) => value.toISOString() + +const dateColumns = { + parse: parseDate, + serialize: dateToJson, +} + +const syncModes = [ + { syncMode: 'eager', suffix: 'eager' }, + { syncMode: 'on-demand', suffix: 'ondemand' }, +] as const + +type SyncMode = (typeof syncModes)[number]['syncMode'] + +function createCollectionsForSyncMode( + supabase: SupabaseClient, + syncMode: SyncMode, + own: (collection: { cleanup: () => Promise }) => void, +) { + // A QueryClient per collection: the realtime channel registry is keyed by + // QueryClient, so sharing one would make the collections share a channel. + const users = createCollection( + supabaseCollectionOptions({ + tableName: 'e2e_users', + keys: ['id'], + schema: userSchema, + supabase, + queryClient: new QueryClient(), + realtime: true, + syncMode, + parse: { + createdAt: dateColumns.parse, + deletedAt: dateColumns.parse, + }, + serialize: { + createdAt: dateColumns.serialize, + deletedAt: dateColumns.serialize, + }, + }), + ) + own(users) + + const posts = createCollection( + supabaseCollectionOptions({ + tableName: 'e2e_posts', + keys: ['id'], + schema: postSchema, + supabase, + queryClient: new QueryClient(), + realtime: true, + syncMode, + parse: { + // The column is text, so PostgREST sends every digit of the value. + largeViewCount: (value) => BigInt(value as string), + publishedAt: dateColumns.parse, + deletedAt: dateColumns.parse, + }, + serialize: { + // The column is text (see the migration), so the exact digits are sent. + largeViewCount: (value) => value.toString(), + publishedAt: dateColumns.serialize, + deletedAt: dateColumns.serialize, + }, + }), + ) + own(posts) + + const comments = createCollection( + supabaseCollectionOptions({ + tableName: 'e2e_comments', + keys: ['id'], + schema: commentSchema, + supabase, + queryClient: new QueryClient(), + realtime: true, + syncMode, + parse: { + createdAt: dateColumns.parse, + deletedAt: dateColumns.parse, + }, + serialize: { + createdAt: dateColumns.serialize, + deletedAt: dateColumns.serialize, + }, + }), + ) + own(comments) + + return { + users: users as unknown as Collection, + posts: posts as unknown as Collection, + comments: comments as unknown as Collection, + } +} + +/** Wire format of the seed rows, as sent to PostgREST. */ +function toRows(seedData: SeedDataResult) { + const toIso = (date: Date | null) => (date ? date.toISOString() : null) + return { + users: seedData.users.map((user) => ({ + ...user, + createdAt: toIso(user.createdAt), + deletedAt: toIso(user.deletedAt), + })), + posts: seedData.posts.map((post) => ({ + ...post, + largeViewCount: post.largeViewCount.toString(), + publishedAt: toIso(post.publishedAt), + deletedAt: toIso(post.deletedAt), + })), + comments: seedData.comments.map((comment) => ({ + ...comment, + createdAt: toIso(comment.createdAt), + deletedAt: toIso(comment.deletedAt), + })), + } +} + +async function seedDatabase(admin: SupabaseClient, seedData: SeedDataResult) { + // Wipe all pre-existing data, e.g. when reusing a stack from a previous run. + const reset = await admin.rpc('reset_e2e_shared') + if (reset.error) { + throw new Error(`e2e reset failed: ${reset.error.message}`) + } + + const rows = toRows(seedData) + const results = [ + await admin.from('e2e_users').insert(rows.users), + await admin.from('e2e_posts').insert(rows.posts), + await admin.from('e2e_comments').insert(rows.comments), + ] + const errors = results.flatMap(({ error }) => (error ? [error] : [])) + if (errors.length > 0) { + throw new AggregateError(errors, 'Supabase fixture insertions failed') + } +} + +/** + * Shared-suite cases that cannot pass against the local Supabase stack, by test + * name, with the reason. The suites cannot be edited to accommodate Supabase, + * so each case is skipped here and reported as skipped. + */ +const unsupportedCases = new Map([ + [ + 'should maintain query state during data changes', + // Verified: the same steps pass when the live query under test is held by a + // subscriber, so the collection itself keeps up with the changes. + 'Realtime delivers a change about 500ms after it is committed. This case ' + + 'inserts eleven rows one by one, waiting for each to be delivered, which ' + + 'takes longer than the five seconds a live query without subscribers ' + + 'survives, so the live query under test is garbage collected mid-test.', + ], +]) + +describe('Supabase Collection E2E Tests', async () => { + beforeEach(({ task, skip }) => { + const reason = unsupportedCases.get(task.name) + if (reason) skip(reason) + }) + + // The collections under test read and write with the anon key, like a + // browser would. Writes that stand in for "another client" use their own + // client so the collections only learn about them through Realtime. + const makeAnonClient = () => + createClient(inject('supabaseUrl'), inject('supabaseAnonKey')) + const other = makeAnonClient() + + const cleanups: Array<() => Promise> = [] + const own = (collection: { cleanup: () => Promise }) => { + cleanups.push(() => collection.cleanup()) + } + afterEach(async () => { + const errors: Array = [] + for (const cleanup of cleanups.splice(0).reverse()) { + try { + await cleanup() + } catch (error) { + errors.push(error) + } + } + if (errors.length === 1) throw errors[0] + if (errors.length > 1) + throw new AggregateError(errors, 'Supabase collection cleanup failed') + }) + + const seedData = generateSeedData() + const fixture = captureSeedData(seedData, { + registration: 'packages/supabase-db-collection/e2e/supabase.e2e.test.ts', + provider: 'Supabase local stack (PostgREST + Realtime)', + }) + await seedDatabase(makeAdminClient(), seedData) + + async function getConfig(): Promise { + const supabase = makeAnonClient() + cleanups.push(async () => { + await supabase.removeAllChannels() + }) + + const [eager, onDemand] = syncModes.map(({ syncMode }) => + createCollectionsForSyncMode(supabase, syncMode, own), + ) as [ + ReturnType, + ReturnType, + ] + + // Hold a subscriber on every collection for the length of the test, like a + // mounted component would. Without one, a collection that has lost all its + // subscribers is idle: its query observers are removed and the adapter + // closes the Realtime channel (there is nothing left to deliver changes to). + // Live queries the suites start are garbage collected five seconds after + // their last subscriber, which would otherwise silence a long-running test. + const subscribable: Array< + Pick, `subscribeChanges`> + > = [...Object.values(eager), ...Object.values(onDemand)] + for (const collection of subscribable) { + const subscription = collection.subscribeChanges(() => {}) + cleanups.push(() => Promise.resolve(subscription.unsubscribe())) + } + + // On-demand collections are marked ready immediately. + await Promise.all([ + onDemand.users.preload(), + onDemand.posts.preload(), + onDemand.comments.preload(), + ]) + + // Eager collections fetch the whole table before they are ready. + await Promise.all([ + eager.users.preload(), + eager.posts.preload(), + eager.comments.preload(), + ]) + expect(eager.users.size).toEqual(seedData.users.length) + expect(eager.posts.size).toEqual(seedData.posts.length) + expect(eager.comments.size).toEqual(seedData.comments.length) + + return { + fixture, + collections: { eager, onDemand }, + // Changes made through `mutations` reach the collections via Realtime. + hasReplicationLag: true, + // `progressive` is Electric-only, so it is not configured. + mutations: { + insertUser: async (user) => { + const { error } = await other + .from('e2e_users') + .insert(toRows({ ...seedData, users: [user] }).users) + if (error) throw error + }, + updateUser: async (id, updates) => { + // Only the columns being changed: a partial update must not touch the rest. + const changes = Object.fromEntries( + Object.entries(updates).map(([column, value]) => [ + column, + value instanceof Date ? value.toISOString() : value, + ]), + ) + const { error } = await other + .from('e2e_users') + .update(changes) + .eq('id', id) + if (error) throw error + }, + deleteUser: async (id) => { + const { error } = await other.from('e2e_users').delete().eq('id', id) + if (error) throw error + }, + insertPost: async (post) => { + const { error } = await other + .from('e2e_posts') + .insert(toRows({ ...seedData, posts: [post] }).posts) + if (error) throw error + }, + deletePost: async (id) => { + const { error } = await other.from('e2e_posts').delete().eq('id', id) + if (error) throw error + }, + }, + setup: async () => {}, + teardown: async () => {}, + } + } + + // Run all shared test suites. Progressive and Moves are Electric-specific + // (they rely on Electric's snapshot/swap transition and move-out semantics). + createPredicatesTestSuite(getConfig) + createPaginationTestSuite(getConfig) + createJoinsTestSuite(getConfig) + createDeduplicationTestSuite(getConfig) + createCollationTestSuite(getConfig) + createMutationsTestSuite(getConfig) + createLiveUpdatesTestSuite(getConfig) +}) diff --git a/packages/supabase-db-collection/package.json b/packages/supabase-db-collection/package.json index df3302ed21..aa6685ff83 100644 --- a/packages/supabase-db-collection/package.json +++ b/packages/supabase-db-collection/package.json @@ -22,7 +22,8 @@ "build": "vite build", "dev": "vite build --watch", "lint": "eslint . --fix", - "test": "vitest run" + "test": "vitest run", + "test:e2e": "vitest run --config vitest.e2e.config.ts" }, "type": "module", "main": "dist/cjs/index.cjs", @@ -59,6 +60,7 @@ }, "devDependencies": { "@supabase/supabase-js": "^2.107.0", + "@tanstack/db-collection-e2e": "workspace:*", "@tanstack/query-core": "^5.90.20", "@vitest/coverage-istanbul": "^5.0.5", "zod": "^4.6.7" diff --git a/packages/supabase-db-collection/supabase/.gitignore b/packages/supabase-db-collection/supabase/.gitignore new file mode 100644 index 0000000000..ad9264f0b1 --- /dev/null +++ b/packages/supabase-db-collection/supabase/.gitignore @@ -0,0 +1,8 @@ +# Supabase +.branches +.temp + +# dotenvx +.env.keys +.env.local +.env.*.local diff --git a/packages/supabase-db-collection/supabase/config.toml b/packages/supabase-db-collection/supabase/config.toml new file mode 100644 index 0000000000..878afc793e --- /dev/null +++ b/packages/supabase-db-collection/supabase/config.toml @@ -0,0 +1,419 @@ +# For detailed configuration reference documentation, visit: +# https://supabase.com/docs/guides/local-development/cli/config +# A string used to distinguish different Supabase projects on the same host. Defaults to the +# working directory name when running `supabase init`. +project_id = "tanstack-db-supabase-e2e" + +[api] +enabled = true +# Port to use for the API URL. +port = 55321 +# Schemas to expose in your API. Tables, views and stored procedures in this schema will get API +# endpoints. `public` and `graphql_public` schemas are included by default. +schemas = ["public", "graphql_public"] +# Extra schemas to add to the search_path of every request. +extra_search_path = ["public", "extensions"] +# The maximum number of rows returns from a view, table, or stored procedure. Limits payload size +# for accidental or malicious requests. Deliberately tiny for the e2e suite: it forces the read +# pagination loop (src/functions.ts `fetchAllPages`) to page through sets larger than the cap, so +# the multi-page path is exercised without seeding thousands of rows. +max_rows = 2 + +[api.tls] +# Enable HTTPS endpoints locally using a self-signed certificate. +enabled = false +# Paths to self-signed certificate pair. +# cert_path = "../certs/my-cert.pem" +# key_path = "../certs/my-key.pem" + +[db] +# Port to use for the local database URL. +port = 55322 +# Port used by db diff command to initialize the shadow database. +shadow_port = 55320 +# Maximum amount of time to wait for health check when starting the local database. +health_timeout = "2m" +# The database major version to use. This has to be the same as your remote database's. Run `SHOW +# server_version;` on the remote database to check. +major_version = 17 + +[db.pooler] +enabled = false +# Port to use for the local connection pooler. +port = 55329 +# Specifies when a server connection can be reused by other clients. +# Configure one of the supported pooler modes: `transaction`, `session`. +pool_mode = "transaction" +# How many server connections to allow per user/database pair. +default_pool_size = 20 +# Maximum number of client connections allowed. +max_client_conn = 100 + +# [db.vault] +# secret_key = "env(SECRET_VALUE)" + +[db.migrations] +# If disabled, migrations will be skipped during a db push or reset. +enabled = true +# Specifies an ordered list of schema files that describe your database. +# Supports glob patterns relative to supabase directory: "./schemas/*.sql" +schema_paths = [] + +[db.seed] +# The e2e suite seeds its own data (see e2e/ and the reset_e2e() function), so no seed files are used. +enabled = false +# Specifies an ordered list of seed files to load during db reset. +# Supports glob patterns relative to supabase directory: "./seeds/*.sql" +sql_paths = [] + +[db.network_restrictions] +# Enable management of network restrictions. +enabled = false +# List of IPv4 CIDR blocks allowed to connect to the database. +# Defaults to allow all IPv4 connections. Set empty array to block all IPs. +allowed_cidrs = ["0.0.0.0/0"] +# List of IPv6 CIDR blocks allowed to connect to the database. +# Defaults to allow all IPv6 connections. Set empty array to block all IPs. +allowed_cidrs_v6 = ["::/0"] + +# Uncomment to reject non-secure connections to the database. +# [db.ssl_enforcement] +# enabled = true + +[realtime] +enabled = true +# Bind realtime via either IPv4 or IPv6. (default: IPv4) +# ip_version = "IPv6" +# The maximum length in bytes of HTTP request headers. (default: 4096) +# max_header_length = 4096 + +[studio] +# Disabled: the e2e suite only needs db, kong, rest, and realtime. +enabled = false +# Port to use for Supabase Studio. +port = 55323 +# External URL of the API server that frontend connects to. +api_url = "http://127.0.0.1" +# OpenAI API Key to use for Supabase AI in the Supabase Studio. +openai_api_key = "env(OPENAI_API_KEY)" + +# Email testing server. Emails sent with the local dev setup are not actually sent - rather, they +# are monitored, and you can view the emails that would have been sent from the web interface. +[local_smtp] +# Disabled: the e2e suite only needs db, kong, rest, and realtime. +enabled = false +# Port to use for the email testing server web interface. +port = 55324 +# Uncomment to expose additional ports for testing user applications that send emails. +# smtp_port = 55325 +# pop3_port = 55326 +# admin_email = "admin@email.com" +# sender_name = "Admin" + +[storage] +# Disabled: the e2e suite only needs db, kong, rest, and realtime. +enabled = false +# The maximum file size allowed (e.g. "5MB", "500KB"). +file_size_limit = "50MiB" + +# Uncomment to configure local storage buckets +# [storage.buckets.images] +# public = false +# file_size_limit = "50MiB" +# allowed_mime_types = ["image/png", "image/jpeg"] +# objects_path = "./images" + +# Allow connections via S3 compatible clients +[storage.s3_protocol] +enabled = true + +# Image transformation API is available to Supabase Pro plan. +# [storage.image_transformation] +# enabled = true + +# Store analytical data in S3 for running ETL jobs over Iceberg Catalog +# This feature is only available on the hosted platform. +[storage.analytics] +enabled = false +max_namespaces = 5 +max_tables = 10 +max_catalogs = 2 + +# Analytics Buckets is available to Supabase Pro plan. +# [storage.analytics.buckets.my-warehouse] + +# Store vector embeddings in S3 for large and durable datasets +[storage.vector] +enabled = true +max_buckets = 10 +max_indexes = 5 + +# Vector Buckets is available to Supabase Pro plan. +# [storage.vector.buckets.documents-openai] + +[auth] +# Kept enabled so `supabase status` can report the anon key the e2e suite uses; +# together with db, kong, rest, and realtime this is the minimal set the adapter +# needs. All other services (studio, storage, analytics, inbucket, edge runtime) +# are disabled above. +enabled = true +# The base URL of your website. Used as an allow-list for redirects and for constructing URLs used +# in emails. +site_url = "http://127.0.0.1:3000" +# The public URL that Auth serves on. Defaults to the API external URL with `/auth/v1` appended. +# external_url = "" +# A list of *exact* URLs that auth providers are permitted to redirect to post authentication. +additional_redirect_urls = ["https://127.0.0.1:3000"] +# How long tokens are valid for, in seconds. Defaults to 3600 (1 hour), maximum 604,800 (1 week). +jwt_expiry = 3600 +# JWT issuer URL. If not set, defaults to auth.external_url. +# jwt_issuer = "" +# Path to JWT signing key. DO NOT commit your signing keys file to git. +# signing_keys_path = "./signing_keys.json" +# If disabled, the refresh token will never expire. +enable_refresh_token_rotation = true +# Allows refresh tokens to be reused after expiry, up to the specified interval in seconds. +# Requires enable_refresh_token_rotation = true. +refresh_token_reuse_interval = 10 +# Allow/disallow new user signups to your project. +enable_signup = true +# Allow/disallow anonymous sign-ins to your project. +enable_anonymous_sign_ins = false +# Allow/disallow testing manual linking of accounts +enable_manual_linking = false +# Passwords shorter than this value will be rejected as weak. Minimum 6, recommended 8 or more. +minimum_password_length = 6 +# Passwords that do not meet the following requirements will be rejected as weak. Supported values +# are: `letters_digits`, `lower_upper_letters_digits`, `lower_upper_letters_digits_symbols` +password_requirements = "" + +# Configure passkey sign-ins. +# [auth.passkey] +# enabled = false + +# Configure WebAuthn relying party settings (required when passkey is enabled). +# [auth.webauthn] +# rp_display_name = "Supabase" +# rp_id = "localhost" +# rp_origins = ["http://127.0.0.1:3000"] + +[auth.rate_limit] +# Number of emails that can be sent per hour. Requires auth.email.smtp to be enabled. +email_sent = 2 +# Number of SMS messages that can be sent per hour. Requires auth.sms to be enabled. +sms_sent = 30 +# Number of anonymous sign-ins that can be made per hour per IP address. Requires enable_anonymous_sign_ins = true. +anonymous_users = 30 +# Number of sessions that can be refreshed in a 5 minute interval per IP address. +token_refresh = 150 +# Number of sign up and sign-in requests that can be made in a 5 minute interval per IP address (excludes anonymous users). +sign_in_sign_ups = 30 +# Number of OTP / Magic link verifications that can be made in a 5 minute interval per IP address. +token_verifications = 30 +# Number of Web3 logins that can be made in a 5 minute interval per IP address. +web3 = 30 + +# Configure one of the supported captcha providers: `hcaptcha`, `turnstile`. +# [auth.captcha] +# enabled = true +# provider = "hcaptcha" +# secret = "" + +[auth.email] +# Allow/disallow new user signups via email to your project. +enable_signup = true +# If enabled, a user will be required to confirm any email change on both the old, and new email +# addresses. If disabled, only the new email is required to confirm. +double_confirm_changes = true +# If enabled, users need to confirm their email address before signing in. +enable_confirmations = false +# If enabled, users will need to reauthenticate or have logged in recently to change their password. +secure_password_change = false +# Controls the minimum amount of time that must pass before sending another signup confirmation or password reset email. +max_frequency = "1s" +# Number of characters used in the email OTP. +otp_length = 6 +# Number of seconds before the email OTP expires (defaults to 1 hour). +otp_expiry = 3600 + +# Use a production-ready SMTP server +# [auth.email.smtp] +# enabled = true +# host = "smtp.sendgrid.net" +# port = 587 +# user = "apikey" +# pass = "env(SENDGRID_API_KEY)" +# admin_email = "admin@email.com" +# sender_name = "Admin" + +# Uncomment to customize email template +# [auth.email.template.invite] +# subject = "You have been invited" +# content_path = "./supabase/templates/invite.html" + +# Uncomment to customize notification email template +# [auth.email.notification.password_changed] +# enabled = true +# subject = "Your password has been changed" +# content_path = "./templates/password_changed_notification.html" + +[auth.sms] +# Allow/disallow new user signups via SMS to your project. +enable_signup = false +# If enabled, users need to confirm their phone number before signing in. +enable_confirmations = false +# Template for sending OTP to users +template = "Your code is {{ `{{ .Code }}` }}" +# Controls the minimum amount of time that must pass before sending another sms otp. +max_frequency = "5s" + +# Use pre-defined map of phone number to OTP for testing. +# [auth.sms.test_otp] +# 4152127777 = "123456" + +# Configure logged in session timeouts. +# [auth.sessions] +# Force log out after the specified duration. +# timebox = "24h" +# Force log out if the user has been inactive longer than the specified duration. +# inactivity_timeout = "8h" + +# This hook runs before a new user is created and allows developers to reject the request based on the incoming user object. +# [auth.hook.before_user_created] +# enabled = true +# uri = "pg-functions://postgres/auth/before-user-created-hook" + +# This hook runs before a token is issued and allows you to add additional claims based on the authentication method used. +# [auth.hook.custom_access_token] +# enabled = true +# uri = "pg-functions:////" + +# Configure one of the supported SMS providers: `twilio`, `twilio_verify`, `messagebird`, `textlocal`, `vonage`. +[auth.sms.twilio] +enabled = false +account_sid = "" +message_service_sid = "" +# DO NOT commit your Twilio auth token to git. Use environment variable substitution instead: +auth_token = "env(SUPABASE_AUTH_SMS_TWILIO_AUTH_TOKEN)" + +# Multi-factor-authentication is available to Supabase Pro plan. +[auth.mfa] +# Control how many MFA factors can be enrolled at once per user. +max_enrolled_factors = 10 + +# Control MFA via App Authenticator (TOTP) +[auth.mfa.totp] +enroll_enabled = false +verify_enabled = false + +# Configure MFA via Phone Messaging +[auth.mfa.phone] +enroll_enabled = false +verify_enabled = false +otp_length = 6 +template = "Your code is {{ `{{ .Code }}` }}" +max_frequency = "5s" + +# Configure MFA via WebAuthn +# [auth.mfa.web_authn] +# enroll_enabled = true +# verify_enabled = true + +# Use an external OAuth provider. The full list of providers are: `apple`, `azure`, `bitbucket`, +# `discord`, `facebook`, `github`, `gitlab`, `google`, `keycloak`, `linkedin_oidc`, `notion`, `twitch`, +# `twitter`, `x`, `slack`, `spotify`, `workos`, `zoom`. +[auth.external.apple] +enabled = false +client_id = "" +# DO NOT commit your OAuth provider secret to git. Use environment variable substitution instead: +secret = "env(SUPABASE_AUTH_EXTERNAL_APPLE_SECRET)" +# Overrides the default auth callback URL derived from auth.external_url. +redirect_uri = "" +# Overrides the default auth provider URL. Used to support self-hosted gitlab, single-tenant Azure, +# or any other third-party OIDC providers. +url = "" +# If enabled, the nonce check will be skipped. Required for local sign in with Google auth. +skip_nonce_check = false +# If enabled, it will allow the user to successfully authenticate when the provider does not return an email address. +email_optional = false + +# Allow Solana wallet holders to sign in to your project via the Sign in with Solana (SIWS, EIP-4361) standard. +# You can configure "web3" rate limit in the [auth.rate_limit] section and set up [auth.captcha] if self-hosting. +[auth.web3.solana] +enabled = false + +# Use Firebase Auth as a third-party provider alongside Supabase Auth. +[auth.third_party.firebase] +enabled = false +# project_id = "my-firebase-project" + +# Use Auth0 as a third-party provider alongside Supabase Auth. +[auth.third_party.auth0] +enabled = false +# tenant = "my-auth0-tenant" +# tenant_region = "us" + +# Use AWS Cognito (Amplify) as a third-party provider alongside Supabase Auth. +[auth.third_party.aws_cognito] +enabled = false +# user_pool_id = "my-user-pool-id" +# user_pool_region = "us-east-1" + +# Use Clerk as a third-party provider alongside Supabase Auth. +[auth.third_party.clerk] +enabled = false +# Obtain from https://clerk.com/setup/supabase +# domain = "example.clerk.accounts.dev" + +# OAuth server configuration +[auth.oauth_server] +# Enable OAuth server functionality +enabled = false +# Path for OAuth consent flow UI +authorization_url_path = "/oauth/consent" +# Allow dynamic client registration +allow_dynamic_registration = false + +[edge_runtime] +# Disabled: the e2e suite only needs db, kong, rest, and realtime. +enabled = false +# Supported request policies: `oneshot`, `per_worker`. +# `per_worker` (default) — enables hot reload during local development. +# `oneshot` — fallback mode if hot reload causes issues (e.g. in large repos or with symlinks). +policy = "per_worker" +# Port to attach the Chrome inspector for debugging edge functions. +inspector_port = 8083 +# The Deno major version to use. +deno_version = 2 + +# [edge_runtime.secrets] +# secret_key = "env(SECRET_VALUE)" + +[analytics] +# Disabled: the e2e suite only needs db, kong, rest, and realtime. +enabled = false +port = 55327 +# Configure one of the supported backends: `postgres`, `bigquery`. +backend = "postgres" + +# Experimental features may be deprecated any time +[experimental] +# Configures Postgres storage engine to use OrioleDB (S3) +orioledb_version = "" +# Configures S3 bucket URL, eg. .s3-.amazonaws.com +s3_host = "env(S3_HOST)" +# Configures S3 bucket region, eg. us-east-1 +s3_region = "env(S3_REGION)" +# Configures AWS_ACCESS_KEY_ID for S3 bucket +s3_access_key = "env(S3_ACCESS_KEY)" +# Configures AWS_SECRET_ACCESS_KEY for S3 bucket +s3_secret_key = "env(S3_SECRET_KEY)" + +# pg-delta is the schema diff engine for db diff / db pull / db remote commit. +# Set enabled = false to fall back to the legacy migra engine. +[experimental.pgdelta] +enabled = true +# Directory under `supabase/` where declarative files are written. +# declarative_schema_path = "./database" +# JSON string passed through to pg-delta SQL formatting. +# format_options = "{\"keywordCase\":\"upper\",\"indent\":2,\"maxWidth\":80,\"commaStyle\":\"trailing\"}" diff --git a/packages/supabase-db-collection/supabase/migrations/00000000000000_e2e_schema.sql b/packages/supabase-db-collection/supabase/migrations/00000000000000_e2e_schema.sql new file mode 100644 index 0000000000..41b836e671 --- /dev/null +++ b/packages/supabase-db-collection/supabase/migrations/00000000000000_e2e_schema.sql @@ -0,0 +1,87 @@ +-- E2E test schema for @tanstack/supabase-db-collection. +-- +-- Column types mirror the Zod schemas in tests/test.utils.ts (ids are numeric, +-- so bigint identity keeps z.number() valid). This schema is intended for the +-- local Supabase stack the e2e suite boots — it is NOT a production schema. + +create table public.users ( + id bigint generated by default as identity primary key, + name text not null, + email text not null, + active boolean not null default true +); + +create table public.todos ( + id bigint generated by default as identity primary key, + title text not null, + description text not null default '', + completed boolean not null default false +); + +create table public.users_todos ( + user_id bigint not null references public.users (id) on delete cascade, + todo_id bigint not null references public.todos (id) on delete cascade, + primary key (user_id, todo_id) +); + +create table public.timestamp_keys ( + recorded_at timestamptz primary key, + label text not null +); + +-- Scratch table used only by the global-setup realtime warm-up: it inserts +-- rows here until a postgres_changes event is actually delivered, proving the +-- WAL -> realtime pipeline is live without touching the tables tests read. +-- Deliberately not truncated by reset_e2e(). +create table public.e2e_warmup ( + id bigint primary key +); + +-- Realtime: publish the tables so postgres_changes events fire for subscribers. +alter publication supabase_realtime add table public.users; +alter publication supabase_realtime add table public.todos; +alter publication supabase_realtime add table public.users_todos; +alter publication supabase_realtime add table public.e2e_warmup; + +-- Test-only posture: enable RLS with fully permissive policies. RLS must be ON +-- (not disabled) because Realtime's Postgres Changes uses SELECT policies to +-- decide what to broadcast — with RLS off, anon subscribers receive nothing. +-- The permissive policies let the anon key both CRUD via PostgREST and receive +-- every change. Do NOT copy this posture into a real application. +alter table public.users enable row level security; +alter table public.todos enable row level security; +alter table public.users_todos enable row level security; +alter table public.timestamp_keys enable row level security; +alter table public.e2e_warmup enable row level security; + +create policy "e2e allow all" on public.users + for all to public using (true) with check (true); +create policy "e2e allow all" on public.todos + for all to public using (true) with check (true); +create policy "e2e allow all" on public.users_todos + for all to public using (true) with check (true); +create policy "e2e allow all" on public.timestamp_keys + for all to public using (true) with check (true); +create policy "e2e allow all" on public.e2e_warmup + for all to public using (true) with check (true); + +-- Reset-and-seed helper called by the test setup (via the service_role key) +-- before every test. TRUNCATE has no PostgREST endpoint, so it is wrapped in a +-- function; seeding here keeps the reset to a single transactional round trip. +-- restart identity guarantees Alice gets id 1 and Bob id 2 in every test. +-- security definer runs it as the owner; execute is restricted to service_role. +create or replace function public.reset_e2e() +returns void +language sql +security definer +set search_path = '' +as $$ + truncate table public.users_todos, public.todos, public.users, public.timestamp_keys + restart identity cascade; + insert into public.users (name, email, active) values + ('Alice', 'alice@test.com', true), + ('Bob', 'bob@test.com', false); +$$; + +revoke execute on function public.reset_e2e() from public, anon, authenticated; +grant execute on function public.reset_e2e() to service_role; diff --git a/packages/supabase-db-collection/supabase/migrations/00000000000001_shared_e2e_schema.sql b/packages/supabase-db-collection/supabase/migrations/00000000000001_shared_e2e_schema.sql new file mode 100644 index 0000000000..bcede77e4d --- /dev/null +++ b/packages/supabase-db-collection/supabase/migrations/00000000000001_shared_e2e_schema.sql @@ -0,0 +1,84 @@ +-- Schema for the shared @tanstack/db-collection-e2e suites. Columns mirror the +-- `User`, `Post` and `Comment` types in packages/db-collection-e2e/src/types.ts +-- (and the tables the Electric e2e creates). This schema is intended for the +-- local Supabase stack the e2e suite boots - it is NOT a production schema. +-- +-- "largeViewCount" holds a value above Number.MAX_SAFE_INTEGER, which the suites +-- use to test bigint handling. PostgREST renders a `bigint` column as a JSON +-- number, which JavaScript's JSON.parse rounds to the nearest double (it cannot +-- tell 9007199254740993 from 9007199254740992), so a bigint column cannot +-- round-trip such values through PostgREST or Realtime. The column is `text` +-- instead, which keeps every digit; the fixture values all have the same +-- number of digits, so PostgREST's text comparisons order them like numbers. +-- The collections convert it to a bigint with `parse` and back with `serialize`. +-- +-- Timestamps are timestamptz, not timestamp: PostgREST and Realtime render +-- timestamptz values with a UTC offset, so `new Date(value)` and the ISO +-- strings the adapter sends in filters both address the same instant. A bare +-- `timestamp` would be rendered without an offset and parsed as local time. + +create table public.e2e_users ( + id uuid primary key, + name text not null, + email text, + age integer not null, + "isActive" boolean not null default true, + "createdAt" timestamptz not null default now(), + metadata jsonb, + "deletedAt" timestamptz +); + +create table public.e2e_posts ( + id uuid primary key, + "userId" uuid not null, + title text not null, + content text, + "viewCount" integer not null default 0, + "largeViewCount" text not null, + "publishedAt" timestamptz, + "deletedAt" timestamptz +); + +create table public.e2e_comments ( + id uuid primary key, + "postId" uuid not null, + "userId" uuid not null, + text text not null, + "createdAt" timestamptz not null default now(), + "deletedAt" timestamptz +); + +-- Realtime: publish the tables so postgres_changes events fire for subscribers. +alter publication supabase_realtime add table public.e2e_users; +alter publication supabase_realtime add table public.e2e_posts; +alter publication supabase_realtime add table public.e2e_comments; + +-- Test-only posture: RLS must be ON because Realtime's Postgres Changes uses +-- SELECT policies to decide what to broadcast; the allow-all policies let the +-- anon key both CRUD via PostgREST and receive every change. Do NOT copy this +-- posture into a real application. +alter table public.e2e_users enable row level security; +alter table public.e2e_posts enable row level security; +alter table public.e2e_comments enable row level security; + +create policy "e2e allow all" on public.e2e_users + for all to public using (true) with check (true); +create policy "e2e allow all" on public.e2e_posts + for all to public using (true) with check (true); +create policy "e2e allow all" on public.e2e_comments + for all to public using (true) with check (true); + +-- Empties the shared tables. TRUNCATE has no PostgREST endpoint, so it is +-- wrapped in a function. security definer runs it as the owner; execute is +-- restricted to service_role. +create or replace function public.reset_e2e_shared() +returns void +language sql +security definer +set search_path = '' +as $$ + truncate table public.e2e_comments, public.e2e_posts, public.e2e_users; +$$; + +revoke execute on function public.reset_e2e_shared() from public, anon, authenticated; +grant execute on function public.reset_e2e_shared() to service_role; diff --git a/packages/supabase-db-collection/tsconfig.json b/packages/supabase-db-collection/tsconfig.json index 9e639d56a7..769799d8e0 100644 --- a/packages/supabase-db-collection/tsconfig.json +++ b/packages/supabase-db-collection/tsconfig.json @@ -16,9 +16,11 @@ "@tanstack/store": ["../store/src"], "@tanstack/db-ivm": ["../db-ivm/src"], "@tanstack/db": ["../db/src"], - "@tanstack/query-db-collection": ["../query-db-collection/src"] + "@tanstack/query-db-collection": ["../query-db-collection/src"], + "@tanstack/db-collection-e2e": ["../db-collection-e2e/src"], + "@tanstack/electric-db-collection": ["../electric-db-collection/src"] } }, - "include": ["src", "tests", "vite.config.ts"], + "include": ["src", "tests", "e2e", "vite.config.ts", "vitest.e2e.config.ts"], "exclude": ["node_modules", "dist"] } diff --git a/packages/supabase-db-collection/vitest.e2e.config.ts b/packages/supabase-db-collection/vitest.e2e.config.ts new file mode 100644 index 0000000000..e8cd8f0e5d --- /dev/null +++ b/packages/supabase-db-collection/vitest.e2e.config.ts @@ -0,0 +1,47 @@ +import { resolve } from 'node:path' +import { defineConfig } from 'vitest/config' +import packageJson from './package.json' with { type: 'json' } + +const packagesDir = resolve(import.meta.dirname, '..') + +export default defineConfig({ + define: { + __SUPABASE_DB_COLLECTION_VERSION__: JSON.stringify(packageJson.version), + }, + test: { + name: `${packageJson.name}:e2e`, + include: [`e2e/**/*.e2e.test.ts`], + globalSetup: [`./e2e/global-setup.ts`], + // Not jsdom: `isServer` from query-core is false under jsdom, which makes + // `getQueryClient()` hand every collection the same module-level + // QueryClient, so cached queries leak between collections. + environment: `node`, + // The e2e tests share a single database that is truncated between tests, + // so files must not run in parallel against it. + fileParallelism: false, + hookTimeout: 120_000, + // A realtime test can chain several 15s poll windows; keep the test timeout + // above the worst-case sum so the innermost failing waiter reports before + // the whole test times out. + testTimeout: 60_000, + }, + resolve: { + alias: { + '@tanstack/db': resolve(packagesDir, 'db/src/index.ts'), + '@tanstack/db-ivm': resolve(packagesDir, 'db-ivm/src/index.ts'), + '@tanstack/db-collection-e2e': resolve( + packagesDir, + 'db-collection-e2e/src/index.ts', + ), + // The shared suites package re-exports Electric-only suites that import it. + '@tanstack/electric-db-collection': resolve( + packagesDir, + 'electric-db-collection/src/index.ts', + ), + '@tanstack/query-db-collection': resolve( + packagesDir, + 'query-db-collection/src/index.ts', + ), + }, + }, +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 55aa01e17f..5538f8de6a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1788,6 +1788,9 @@ importers: '@supabase/supabase-js': specifier: ^2.107.0 version: 2.119.0 + '@tanstack/db-collection-e2e': + specifier: workspace:* + version: link:../db-collection-e2e '@tanstack/query-core': specifier: ^5.90.20 version: 5.90.20 From 173400d9b55a7b165fddba3ad963baa12bd924ba Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Wed, 11 Nov 2026 12:07:45 +0100 Subject: [PATCH 08/13] feat(supabase-db-collection): add experimental_queryOnce Port queryOnce, the query IR serializer, and the IR-to-PostgREST translation from supabase/tanstack-db at 245600c, with their unit tests. The function is exported only as experimental_queryOnce because it reads TanStack DB's internal query representation. Adapted to this repo's IR: descriptor sources, conditional selects, and explicit null placement in the order param. Co-Authored-By: Claude Opus 5.5 (1M context) --- packages/supabase-db-collection/src/db.ts | 18 +- packages/supabase-db-collection/src/index.ts | 1 + .../src/postgrest-filters/index.ts | 1 + .../postgrest-filters/query-ir-to-search.ts | 406 +++++ .../supabase-db-collection/src/query-once.ts | 152 ++ .../supabase-db-collection/src/serialize.ts | 352 ++++ .../tests/postgrest-filters.test.ts | 121 ++ .../tests/query-once.test.ts | 1539 +++++++++++++++++ .../tests/serialize.test.ts | 48 + 9 files changed, 2637 insertions(+), 1 deletion(-) create mode 100644 packages/supabase-db-collection/src/postgrest-filters/query-ir-to-search.ts create mode 100644 packages/supabase-db-collection/src/query-once.ts create mode 100644 packages/supabase-db-collection/tests/query-once.test.ts create mode 100644 packages/supabase-db-collection/tests/serialize.test.ts diff --git a/packages/supabase-db-collection/src/db.ts b/packages/supabase-db-collection/src/db.ts index 3f1de21178..2e13ba9e15 100644 --- a/packages/supabase-db-collection/src/db.ts +++ b/packages/supabase-db-collection/src/db.ts @@ -11,7 +11,7 @@ import { getQueryClient } from './query-client' import { syncTableSubscription } from './realtime' import type { TableEntry } from './realtime' import type { ColumnConversions, RowConversions } from './row-conversions' -import type { StringCollationConfig } from '@tanstack/db' +import type { CollectionImpl, StringCollationConfig } from '@tanstack/db' import type { QueryClient } from '@tanstack/query-core' import type { SupabaseClient } from '@supabase/supabase-js' import type { StandardSchemaV1 } from '@standard-schema/spec' @@ -119,6 +119,21 @@ const registerTable = ( return entry } +/** + * Options key marking a collection created by this package, so queryOnce can + * tell a collection backed by a Supabase table from any other collection. + */ +const supabaseCollection = Symbol(`supabaseCollection`) + +/** Whether this package created `collection`, so it reads a Supabase table */ +export function isSupabaseCollection(collection: CollectionImpl): boolean { + return ( + (collection.config as { [supabaseCollection]?: boolean })[ + supabaseCollection + ] === true + ) +} + const createSupabaseConfig = ( options: SupabaseCollectionOptions, ) => { @@ -193,6 +208,7 @@ const createSupabaseConfig = ( return { ...config, + [supabaseCollection]: true, sync: { // Keeps the hooks query-db-collection attaches to its sync config, such // as the factory that lets a direct write start an idle collection. diff --git a/packages/supabase-db-collection/src/index.ts b/packages/supabase-db-collection/src/index.ts index 58a93e76de..89e7ba6387 100644 --- a/packages/supabase-db-collection/src/index.ts +++ b/packages/supabase-db-collection/src/index.ts @@ -1 +1,2 @@ export { supabaseCollectionOptions } from './db' +export { experimental_queryOnce } from './query-once' diff --git a/packages/supabase-db-collection/src/postgrest-filters/index.ts b/packages/supabase-db-collection/src/postgrest-filters/index.ts index ebe7243a7e..6cd6a588d5 100644 --- a/packages/supabase-db-collection/src/postgrest-filters/index.ts +++ b/packages/supabase-db-collection/src/postgrest-filters/index.ts @@ -10,3 +10,4 @@ export { splitLoadSubsetOptions, } from './split-load-subset-options' export { subsetParamsToSearch } from './subset-params-to-search' +export { isAggregateOnlySelect, queryIrToSearch } from './query-ir-to-search' diff --git a/packages/supabase-db-collection/src/postgrest-filters/query-ir-to-search.ts b/packages/supabase-db-collection/src/postgrest-filters/query-ir-to-search.ts new file mode 100644 index 0000000000..f85a7d1078 --- /dev/null +++ b/packages/supabase-db-collection/src/postgrest-filters/query-ir-to-search.ts @@ -0,0 +1,406 @@ +import { + appendLimit, + appendOffset, + appendOrder, + paramsToSearch, + toPostgrestParams, +} from './common' +import type { + SerializedExpression as Expression, + SerializedFrom, + SerializedJoinClause, + SerializedQueryIR, + SerializedSelect, + SerializedWhere, +} from '../serialize' + +// ── Serialized query IR → search ──────────────────────────────────── + +/** Extract column name from a ref expression (drops the table alias prefix) */ +function refToColumn(expr: Expression): string { + if (expr.type !== 'ref') { + throw new Error(`Expected ref expression, got ${expr.type}`) + } + return expr.path.slice(1).join('.') +} + +/** Unwrap a SerializedWhere to its expression */ +function getExpression(where: SerializedWhere): Expression { + if ('type' in where) return where + return (where as { expression: Expression }).expression +} + +/** Check if a where clause is residual (client-side only, cannot be pushed to PostgREST) */ +function isResidual(where: SerializedWhere): boolean { + if ('type' in where) return false + return (where as { residual?: boolean }).residual === true +} + +/** Check if a ref expression points to a computed/selected field */ +function isComputedRef(expr: Expression): boolean { + return expr.type === 'ref' && expr.path[0] === '$selected' +} + +/** Resolve a FROM clause to a base table name, collecting where clauses from subqueries */ +function resolveFrom(from: SerializedFrom): { + tableName: string + wheres: Array +} { + if (from.type === 'table') { + return { tableName: from.name, wheres: [] } + } + if (from.type === 'subquery') { + const inner = resolveFrom(from.query.from) + return { + tableName: inner.tableName, + wheres: [...inner.wheres, ...(from.query.where ?? [])], + } + } + // union / unionAll have no single base table to push to PostgREST + throw new Error( + `Cannot push a ${from.type} query to PostgREST; unions are not supported in queryOnce`, + ) +} + +interface EmbedNode { + alias: string + children: Array + hint: string + joinType: string + tableName: string +} + +/** + * Build the PostgREST select string from the IR. + * + * Handles: + * - Column refs: `alias:column` or just `column` + * - Aggregates: `alias:column.count()`, `alias:column.sum()`, etc. + * - Join embeddings: `table!fk!inner(*)`, `table!fk(*)` + * + * Falls back to `*` when select contains non-pushable expressions + * (func, computed refs, groupBy present). + */ +function buildSelectString(ir: SerializedQueryIR): string { + const parts: Array = [] + let hasExplicitColumns = false + + // Process select fields (aggregates and column refs) + // Skip pushing select when groupBy is present (aggregation done client-side) + if (ir.select && !ir.groupBy?.length) { + const selectParts = processSelectEntries(ir.select) + if (selectParts !== null) { + parts.push(...selectParts) + hasExplicitColumns = true + } + } + + if (!hasExplicitColumns) { + parts.push('*') + } + + // Add join resource embeddings + if (ir.join?.length) { + const embedStrings = buildJoinEmbeds(ir) + parts.push(...embedStrings) + } + + return stripSelectWhitespace(parts.join(', ')) +} + +/** + * Remove whitespace outside of quoted segments, mirroring postgrest-js's + * `.select()`. We build the select with `", "` separators for readability but + * PostgREST expects a compact list. + */ +function stripSelectWhitespace(select: string): string { + let quoted = false + let result = '' + for (const char of select) { + if (/\s/.test(char) && !quoted) continue + if (char === '"') quoted = !quoted + result += char + } + return result +} + +/** + * Convert a SerializedSelect map into PostgREST select parts. + * Returns null if any entry cannot be pushed (signals fallback to `*`). + */ +function processSelectEntries(select: SerializedSelect): Array | null { + const parts: Array = [] + + for (const [alias, value] of Object.entries(select)) { + // A spread (`...row`) can't be expressed as a fixed column list + if (alias.startsWith('__SPREAD_SENTINEL__')) return null + if ('type' in value) { + const part = exprToSelectPart(alias, value as Expression) + if (part === null) return null + parts.push(part) + } else { + // Nested select object — can't push to PostgREST + return null + } + } + + return parts.length > 0 ? parts : null +} + +/** Convert a single select expression to a PostgREST select part */ +function exprToSelectPart(alias: string, expr: Expression): string | null { + if (expr.type === 'ref') { + if (isComputedRef(expr)) return null + const column = refToColumn(expr) + return alias === column ? column : `${alias}:${column}` + } + if (expr.type === 'agg') { + return aggToSelectPart(alias, expr) + } + // func, val, includesSubquery — can't push + return null +} + +/** + * Convert an aggregate expression to PostgREST select syntax. + * + * - `count(column)` → `alias:column.count()` + * - `sum(column)` → `alias:column.sum()` + * - `avg(column)` → `alias:column.avg()` + * - `min(column)` → `alias:column.min()` + * - `max(column)` → `alias:column.max()` + */ +function aggToSelectPart(alias: string, expr: Expression): string | null { + if (expr.type !== 'agg') return null + + const { name, args } = expr + + if ( + name === 'count' || + name === 'sum' || + name === 'avg' || + name === 'min' || + name === 'max' + ) { + const [arg] = args + if (arg?.type === 'ref') { + const column = refToColumn(arg) + return `${alias}:${column}.${name}()` + } + if (name === 'count') { + return `${alias}:count` + } + return null + } + + return null +} + +/** + * Whether every select entry is an aggregate PostgREST can compute, so the + * response is exactly one row. A plain column beside an aggregate would make + * PostgREST group by it, and any other expression falls back to `select=*`. + */ +export function isAggregateOnlySelect( + select: SerializedSelect | undefined, +): boolean { + if (!select) return false + const entries = Object.entries(select) + return ( + entries.length > 0 && + entries.every( + ([alias, value]) => aggToSelectPart(alias, value as Expression) !== null, + ) + ) +} + +/** + * Build PostgREST resource embedding strings for joins. + * + * Constructs a tree of embed nodes to handle chained joins (e.g., + * `users JOIN users_todos JOIN todos` → nested embedding). + * + * Join type mapping: + * - `inner` → `!inner` + * - `left` → (default, no hint needed) + * - `right` → `!inner` (semantically: right table always present) + * - `full` → (default left embedding — partial semantics) + */ +function buildJoinEmbeds(ir: SerializedQueryIR): Array { + if (!ir.join?.length) return [] + + const fromAlias = ir.from.type === 'table' ? ir.from.alias : ir.from.alias + + // Build a tree: root is the FROM table, children are embedded joins + const root: EmbedNode = { + tableName: resolveFrom(ir.from).tableName, + alias: fromAlias, + hint: '', + joinType: '', + children: [], + } + + const nodeMap = new Map() + nodeMap.set(fromAlias, root) + + for (const join of ir.join) { + const { tableName: joinTable } = resolveFrom(join.from) + const joinAlias = + join.from.type === 'table' ? join.from.alias : join.from.alias + + const { parentAlias, fkHint } = resolveJoinParent(join, joinAlias, nodeMap) + + const node: EmbedNode = { + tableName: joinTable, + alias: joinAlias, + hint: fkHint, + joinType: join.type, + children: [], + } + + const parent = nodeMap.get(parentAlias) ?? root + parent.children.push(node) + nodeMap.set(joinAlias, node) + } + + return root.children.map(renderEmbedNode) +} + +/** + * Split a join condition into its left and right operands. `@tanstack/db` 1.0 + * models the condition as a single boolean `on` expression instead of separate + * `left` / `right` operands. A plain `eq(a, b)` yields its two operands; for an + * `and(...)` of conditions the first `eq` is used, as the rest cannot be + * expressed through a single PostgREST embedding hint. + */ +function joinOperands( + on: Expression, +): { left: Expression; right: Expression } | null { + if (on.type !== 'func') return null + const [left, right] = on.args + if (on.name === 'eq' && left && right && on.args.length === 2) { + return { left, right } + } + if (on.name === 'and') { + for (const arg of on.args) { + const operands = joinOperands(arg) + if (operands) return operands + } + } + return null +} + +/** + * Determine which existing node a join attaches to, and extract + * the foreign key hint from the join condition. + */ +function resolveJoinParent( + join: SerializedJoinClause, + joinAlias: string, + nodeMap: Map, +): { parentAlias: string; fkHint: string } { + const operands = joinOperands(join.on) + if (!operands) return { parentAlias: '', fkHint: '' } + const { left, right } = operands + + const leftAlias = left.type === 'ref' ? left.path[0] : null + const rightAlias = right.type === 'ref' ? right.path[0] : null + + // Left side is existing table, right side is the new join table + if (leftAlias && nodeMap.has(leftAlias) && rightAlias === joinAlias) { + const fk = right.type === 'ref' ? right.path.slice(1).join('.') : '' + return { parentAlias: leftAlias, fkHint: fk } + } + + // Right side is existing table, left side is the new join table + if (rightAlias && nodeMap.has(rightAlias) && leftAlias === joinAlias) { + const fk = left.type === 'ref' ? left.path.slice(1).join('.') : '' + return { parentAlias: rightAlias, fkHint: fk } + } + + // Fallback: attach to whichever side is already in the tree + if (leftAlias && nodeMap.has(leftAlias)) { + const fk = right.type === 'ref' ? right.path.slice(1).join('.') : '' + return { parentAlias: leftAlias, fkHint: fk } + } + if (rightAlias && nodeMap.has(rightAlias)) { + const fk = left.type === 'ref' ? left.path.slice(1).join('.') : '' + return { parentAlias: rightAlias, fkHint: fk } + } + + return { parentAlias: '', fkHint: '' } +} + +/** Render an embed node as a PostgREST resource embedding string */ +function renderEmbedNode(node: EmbedNode): string { + const hintStr = node.hint ? `!${node.hint}` : '' + const typeStr = + node.joinType === 'inner' || node.joinType === 'right' ? '!inner' : '' + + const innerParts = ['*'] + for (const child of node.children) { + innerParts.push(renderEmbedNode(child)) + } + + return `${node.tableName}${hintStr}${typeStr}(${innerParts.join(', ')})` +} + +/** + * Build the PostgREST query string (and resolve the base table) from a + * SerializedQueryIR. + * + * Pushes to PostgREST: + * - **select**: column refs, aggregates (count/sum/avg/min/max) + * - **joins**: resource embedding with `!inner` / `!left` hints + * - **where**: eq, gt, gte, lt, lte, like, ilike, isNull, in, not, and, or + * - **orderBy**: real column refs (skips computed/$selected) + * - **limit / offset** + * + * Falls back to `select=*` when: + * - select contains non-pushable expressions (func, computed refs) + * - groupBy is present (aggregation done client-side) + */ +export function queryIrToSearch(ir: SerializedQueryIR): { + tableName: string + search: URLSearchParams +} { + const { tableName, wheres: subqueryWheres } = resolveFrom(ir.from) + const allWheres = [...subqueryWheres, ...(ir.where ?? [])] + + const search = new URLSearchParams() + search.set('select', buildSelectString(ir)) + + // Apply pushable where filters (skip residual / client-side filters) + for (const w of allWheres) { + if (isResidual(w)) continue + const filters = paramsToSearch( + toPostgrestParams(getExpression(w), { stripAlias: true, strict: true }), + ) + for (const [key, value] of filters) { + search.append(key, value) + } + } + + // Apply order by (only real column refs, skip computed/$selected refs) + const sorts: Parameters[1] = [] + for (const ob of ir.orderBy ?? []) { + if (ob.expression.type === 'ref' && !isComputedRef(ob.expression)) { + sorts.push({ + column: refToColumn(ob.expression), + ascending: ob.direction === 'asc', + nulls: ob.nulls === 'first' ? 'first' : 'last', + }) + } + } + appendOrder(search, sorts) + + // limit and offset are independent params — no derived range + if (ir.limit !== undefined) { + appendLimit(search, ir.limit) + } + if (ir.offset !== undefined) { + appendOffset(search, ir.offset) + } + + return { tableName, search } +} diff --git a/packages/supabase-db-collection/src/query-once.ts b/packages/supabase-db-collection/src/query-once.ts new file mode 100644 index 0000000000..14100a1632 --- /dev/null +++ b/packages/supabase-db-collection/src/query-once.ts @@ -0,0 +1,152 @@ +import { Query, queryOnce } from '@tanstack/db' +import { isSupabaseCollection } from './db' +import { isAggregateOnlySelect, queryIrToSearch } from './postgrest-filters' +import { postgrestRequest } from './postgrest-request' +import { serializeQueryIR } from './serialize' +import type { + BaseQueryBuilder, + ExtractContext, + IR, + InferResultType, + InitialQueryBuilder, + QueryBuilder, +} from '@tanstack/db' +import type { SerializedQueryIR } from './serialize' +import type { SupabaseClient } from '@supabase/supabase-js' + +// ── Execution ─────────────────────────────────────────────────────── + +/** + * Execute a SerializedQueryIR against Supabase and return the results. + * + * Produces a single PostgREST request using resource embedding for joins + * and aggregate syntax for count/sum/avg/min/max. + */ +export async function executeQuery( + supabase: SupabaseClient, + ir: SerializedQueryIR, +): Promise> { + const { tableName, search } = queryIrToSearch(ir) + // queryOnce only sends aggregate-only selects here, whose output is one + // row, so the db-max-rows cap does not apply and no paging loop is needed. + const { data } = await postgrestRequest>(supabase, tableName, { + method: 'GET', + search, + }) + return data ?? [] +} + +/** Run an aggregate-only query on PostgREST, shaped like TanStack's result */ +async function executeServerAggregate( + supabase: SupabaseClient, + ir: SerializedQueryIR, +): Promise { + // A single aggregate row has nothing to order, and Postgres rejects ORDER BY + // on a column outside the aggregates. + const rows = await executeQuery(supabase, { ...ir, orderBy: undefined }) + return ir.singleResult ? rows[0] : rows +} + +// ── Server aggregate detection ────────────────────────────────────── + +/** + * Clauses the server aggregate path reproduces exactly: filters, paging, and + * the no-op order/distinct on its single row. findOne is unwrapped. + */ +const SERVER_AGGREGATE_CLAUSES = new Set([ + 'from', + 'select', + 'where', + 'orderBy', + 'limit', + 'offset', + 'distinct', + 'singleResult', +]) + +/** Clauses a subquery source may set and still be pushed down: its filters */ +const FILTER_ONLY_CLAUSES = new Set(['from', 'where']) + +/** Whether every clause the query sets is in `allowed` */ +function setsOnly(query: IR.QueryIR, allowed: Set): boolean { + return Object.entries(query).every( + ([clause, value]) => + allowed.has(clause) || + value === undefined || + (Array.isArray(value) && value.length === 0), + ) +} + +/** + * A Supabase table, or a subquery that only filters one (its where is pushed + * down). A collection this package did not create has no table to query. + */ +function isFilteredTable(from: IR.From): boolean { + if (from.type === 'collectionRef') { + return isSupabaseCollection(from.collection) + } + return ( + from.type === 'queryRef' && + setsOnly(from.query, FILTER_ONLY_CLAUSES) && + isFilteredTable(from.query.from) + ) +} + +/** + * Whether PostgREST alone produces the query's exact result: one row of + * aggregates over a single, optionally filtered table. executeQuery returns + * PostgREST's response as-is, so anything else (grouping, joins, unions, + * functional clauses, plain or computed select fields) is left to TanStack DB. + * This is an allow-list so that clauses added to the IR later default to the + * client-side path. + */ +function isServerAggregate( + ir: IR.QueryIR, + serialized: SerializedQueryIR, +): boolean { + return ( + setsOnly(ir, SERVER_AGGREGATE_CLAUSES) && + isFilteredTable(ir.from) && + isAggregateOnlySelect(serialized.select) + ) +} + +// ── Public API ────────────────────────────────────────────────────── + +/** + * Execute a TanStack DB query against Supabase in a one-shot manner. + * + * Experimental: this reads TanStack DB's internal query representation, which + * can change between releases. + * + * A query whose select contains only aggregates (count/sum/avg/min/max) over + * a single Supabase table, with no grouping, join, or functional clause, is + * translated to a single PostgREST request and computed by the server. It + * relies on PostgREST aggregate functions, which must be enabled with + * `pgrst.db_aggregates_enabled`. + * + * Every other query, including groupBy and having, runs through TanStack DB's + * own `queryOnce` over the collections: filters, ordering, and limits are + * pushed to PostgREST where possible, and the remaining operations (grouping, + * having, distinct, computed select expressions) are applied client-side over + * the fetched rows. + */ +export const experimental_queryOnce = < + TQueryFn extends (q: InitialQueryBuilder) => QueryBuilder, + TQuery extends QueryBuilder = ReturnType, +>( + callback: TQueryFn, + supabase: SupabaseClient, +): Promise>> => { + const q = new Query() + const ir = (callback(q) as unknown as BaseQueryBuilder)._getQuery() + const serialized = serializeQueryIR(ir) + if (isServerAggregate(ir, serialized)) { + return executeServerAggregate(supabase, serialized) as Promise< + InferResultType> + > + } + return queryOnce(callback as any) as Promise< + InferResultType> + > +} diff --git a/packages/supabase-db-collection/src/serialize.ts b/packages/supabase-db-collection/src/serialize.ts index da076724b8..d109f85593 100644 --- a/packages/supabase-db-collection/src/serialize.ts +++ b/packages/supabase-db-collection/src/serialize.ts @@ -1,3 +1,5 @@ +import { IR } from '@tanstack/db' + // The expression shape the PostgREST filter renderer understands. TanStack DB's // `IR.BasicExpression` is structurally assignable to it, so `loadSubset` where // clauses can be rendered without converting them first. @@ -6,3 +8,353 @@ export type SerializedExpression = | { type: `val`; value: unknown } | { type: `func`; name: string; args: Array } | { type: `agg`; name: string; args: Array } + | SerializedIncludesSubquery + | SerializedConditionalSelect + +export interface SerializedConditionalSelect { + branches: Array<{ + condition: SerializedExpression + value: SerializedExpression | SerializedSelect + }> + defaultValue?: SerializedExpression | SerializedSelect + type: `conditionalSelect` +} + +export interface SerializedIncludesSubquery { + childCorrelationField: SerializedExpression + correlationField: SerializedExpression + fieldName: string + materialization: string + parentFilters?: Array + parentProjection?: Array + query: SerializedQueryIR + scalarField?: string + type: `includesSubquery` +} + +export type SerializedFrom = + | { type: `table`; name: string; alias: string } + | { type: `subquery`; query: SerializedQueryIR; alias: string } + | { type: `union`; sources: Array; alias: string } + | { type: `unionAll`; queries: Array; alias: string } + +export type SerializedWhere = + | SerializedExpression + | { expression: SerializedExpression; residual?: boolean } + +export interface SerializedOrderByClause { + direction: string + expression: SerializedExpression + locale?: string + localeOptions?: object + nulls: string + stringSort?: string +} + +export interface SerializedJoinClause { + from: SerializedFrom + on: SerializedExpression + type: string +} + +export type SerializedSelect = { + [alias: string]: SerializedExpression | SerializedSelect +} + +export interface SerializedQueryIR { + distinct?: true + from: SerializedFrom + groupBy?: Array + having?: Array + join?: Array + limit?: number + offset?: number + orderBy?: Array + select?: SerializedSelect + singleResult?: true + where?: Array +} + +// ── Serialization functions ───────────────────────────────────────── + +export function serializeQueryIR(query: IR.QueryIR): SerializedQueryIR { + const result: SerializedQueryIR = { + from: serializeFrom(query.from), + } + + if (query.select) { + result.select = serializeSelect(query.select) + } + + if (query.join?.length) { + result.join = query.join.map(serializeJoinClause) + } + + if (query.where?.length) { + result.where = query.where.map(serializeWhere) + } + + if (query.groupBy?.length) { + result.groupBy = query.groupBy.map(serializeExpression) + } + + if (query.having?.length) { + result.having = query.having.map(serializeWhere) + } + + if (query.orderBy?.length) { + result.orderBy = query.orderBy.map(serializeOrderByClause) + } + + if (query.limit !== undefined) { + result.limit = query.limit + } + + if (query.offset !== undefined) { + result.offset = query.offset + } + + if (query.distinct) { + result.distinct = true + } + + if (query.singleResult) { + result.singleResult = true + } + + return result +} + +function serializeFrom(from: IR.From): SerializedFrom { + switch (from.type) { + case `collectionRef`: + return { + type: `table`, + name: from.collection.id, + alias: from.alias, + } + case `descriptorRef`: + // An unbound descriptor names its table by the descriptor's id. + return { + type: `table`, + name: from.descriptor.id, + alias: from.alias, + } + case `queryRef`: + return { + type: `subquery`, + query: serializeQueryIR(from.query), + alias: from.alias, + } + case `unionFrom`: + return { + type: `union`, + sources: from.sources.map(serializeFrom), + alias: from.alias, + } + case `unionAll`: + return { + type: `unionAll`, + queries: from.queries.map(serializeQueryIR), + alias: from.alias, + } + default: + throw new Error(`Unknown from type: ${(from as { type: string }).type}`) + } +} + +function serializeExpression( + expr: IR.BasicExpression | IR.Aggregate | IR.IncludesSubquery, +): SerializedExpression { + switch (expr.type) { + case `ref`: + return { type: `ref`, path: [...(expr).path] } + case `val`: + return { type: `val`, value: serializeValue((expr).value) } + case `func`: + return { + type: `func`, + name: (expr).name, + args: (expr).args.map(serializeExpression), + } + case `agg`: + return { + type: `agg`, + name: (expr).name, + args: (expr).args.map(serializeExpression), + } + case `includesSubquery`: + return serializeIncludesSubquery(expr) + default: + throw new Error(`Unknown expression type: ${(expr as any).type}`) + } +} + +function serializeIncludesSubquery( + expr: IR.IncludesSubquery, +): SerializedIncludesSubquery { + const result: SerializedIncludesSubquery = { + type: `includesSubquery`, + query: serializeQueryIR(expr.query), + correlationField: serializeExpression(expr.correlationField), + childCorrelationField: serializeExpression(expr.childCorrelationField), + fieldName: expr.fieldName, + materialization: expr.materialization, + } + + if (expr.parentFilters?.length) { + result.parentFilters = expr.parentFilters.map(serializeWhere) + } + + if (expr.parentProjection?.length) { + result.parentProjection = expr.parentProjection.map(serializeExpression) + } + + if (expr.scalarField !== undefined) { + result.scalarField = expr.scalarField + } + + return result +} + +function serializeWhere(where: IR.Where): SerializedWhere { + if (typeof where === `object` && `expression` in where) { + const result: { expression: SerializedExpression; residual?: boolean } = { + expression: serializeExpression(where.expression), + } + if (where.residual) { + result.residual = true + } + return result + } + return serializeExpression(where) +} + +/** A `...row` spread leaves an uncompiled ref proxy in the select IR */ +function isRefProxy(value: unknown): value is { __path: Array } { + return ( + typeof value === `object` && + value !== null && + (value as { __refProxy?: boolean }).__refProxy === true + ) +} + +function serializeSelect(select: IR.Select): SerializedSelect { + const result: SerializedSelect = {} + for (const [alias, value] of Object.entries(select)) { + result[alias] = serializeSelectValue(value) + } + return result +} + +function serializeSelectValue( + value: IR.SelectValueExpression, +): SerializedExpression | SerializedSelect { + // A spread (`...row`) is keyed by a `__SPREAD_SENTINEL__` alias and its + // value is a raw ref proxy rather than a compiled expression. Recursing + // into it would access proxy props endlessly, so serialize it as a plain + // ref and let consumers decide how to handle it (PostgREST falls back to + // `select=*`). + if (isRefProxy(value)) { + return { type: `ref`, path: [...value.__path] } + } + if (value instanceof IR.ConditionalSelect) { + const result: SerializedConditionalSelect = { + type: `conditionalSelect`, + branches: value.branches.map((branch) => ({ + condition: serializeExpression(branch.condition), + value: serializeSelectValue(branch.value), + })), + } + if (value.defaultValue !== undefined) { + result.defaultValue = serializeSelectValue(value.defaultValue) + } + return result + } + if ( + IR.isBasicOrAggregateExpression(value) || + value instanceof IR.IncludesSubquery + ) { + return serializeExpression(value) + } + // Nested Select object + return serializeSelect(value) +} + +function serializeJoinClause(clause: IR.JoinClause): SerializedJoinClause { + return { + from: serializeFrom(clause.from), + type: clause.type, + on: serializeExpression(clause.on), + } +} + +function serializeOrderByClause( + clause: IR.OrderByClause, +): SerializedOrderByClause { + const result: SerializedOrderByClause = { + expression: serializeExpression(clause.expression), + direction: clause.compareOptions.direction, + nulls: clause.compareOptions.nulls, + } + + if (clause.compareOptions.stringSort) { + result.stringSort = clause.compareOptions.stringSort + } + + if ( + clause.compareOptions.stringSort === `locale` && + `locale` in clause.compareOptions + ) { + result.locale = clause.compareOptions.locale + result.localeOptions = clause.compareOptions.localeOptions + } + + return result +} + +function serializeValue(value: unknown): unknown { + if (value === undefined) { + return { __type: `undefined` } + } + + if (typeof value === `number`) { + if (Number.isNaN(value)) { + return { __type: `nan` } + } + if (value === Number.POSITIVE_INFINITY) { + return { __type: `infinity`, sign: 1 } + } + if (value === Number.NEGATIVE_INFINITY) { + return { __type: `infinity`, sign: -1 } + } + } + + if ( + value === null || + typeof value === `string` || + typeof value === `number` || + typeof value === `boolean` + ) { + return value + } + + if (value instanceof Date) { + return { __type: `date`, value: value.toJSON() } + } + + if (Array.isArray(value)) { + return value.map((item) => serializeValue(item)) + } + + if (typeof value === `object`) { + return Object.fromEntries( + Object.entries(value as Record).map(([key, val]) => [ + key, + serializeValue(val), + ]), + ) + } + + return value +} diff --git a/packages/supabase-db-collection/tests/postgrest-filters.test.ts b/packages/supabase-db-collection/tests/postgrest-filters.test.ts index 11b59650e2..98cc809b42 100644 --- a/packages/supabase-db-collection/tests/postgrest-filters.test.ts +++ b/packages/supabase-db-collection/tests/postgrest-filters.test.ts @@ -20,12 +20,16 @@ import { cursorCurrentToSearch, keyColumnsToSearch, loadSubsetOptionsToSearch, + queryIrToSearch, realtimeFiltersToSearch, subsetParamsToSearch, } from '../src/postgrest-filters' // A bare (unaliased) column ref, as the live subset loader receives them. const col = (name: string) => new IR.PropRef([name]) +// An aliased ref (`user.column`), as the serialized query IR carries them; +// queryIrToSearch strips the alias prefix. +const userCol = (name: string) => new IR.PropRef(['user', name]) const name = col('name') const id = col('id') @@ -422,6 +426,123 @@ describe('keyColumnsToSearch', () => { }) }) +// ── subsetOptionsToQueryKey ───────────────────────────────────────── +describe('queryIrToSearch', () => { + const table = { type: 'table', name: 'users', alias: 'user' } as const + const build = (ir: Parameters[0]) => + queryIrToSearch(ir) + + test('resolves the base table name', () => { + expect(build({ from: table }).tableName).toBe('users') + }) + + test('builds an explicit select list and renames columns', () => { + expect( + build({ + from: table, + select: { + id: { type: 'ref', path: ['user', 'id'] }, + alias: { type: 'ref', path: ['user', 'name'] }, + }, + }).search.get('select'), + ).toBe('id,alias:name') + }) + + test('falls back to select=* for non-pushable select expressions', () => { + expect( + build({ + from: table, + select: { + upper: { + type: 'func', + name: 'upper', + args: [{ type: 'ref', path: ['user', 'name'] }], + }, + }, + }).search.get('select'), + ).toBe('*') + }) + + test('pushes where filters, stripping the table alias', () => { + expect( + build({ from: table, where: [eq(userCol('active'), true)] }).search.get( + 'active', + ), + ).toBe('eq.true') + }) + + test.each([ + [ + 'computed OR', + or(eq(userCol('active'), true), eq(upper(userCol('name')), 'A')), + ], + ['literal asterisk', like(userCol('name'), '*Ali*')], + ])('throws on non-pushable %s (strict)', (_, where) => { + expect(() => build({ from: table, where: [where] })).toThrow( + 'fully pushable filters', + ) + }) + + test('does not merge duplicate IN demands', () => { + expect( + build({ + from: table, + where: [inArray(userCol('id'), [1, 2]), inArray(userCol('id'), [2, 3])], + }).search.getAll('id'), + ).toEqual(['in.(1,2)', 'in.(2,3)']) + }) + + test('orders by real columns and skips computed/$selected refs', () => { + const search = build({ + from: table, + orderBy: [ + { + expression: { type: 'ref', path: ['user', 'id'] }, + direction: 'asc', + nulls: 'last', + }, + { + expression: { type: 'ref', path: ['$selected', 'score'] }, + direction: 'desc', + nulls: 'last', + }, + { + expression: { type: 'ref', path: ['user', 'name'] }, + direction: 'desc', + nulls: 'first', + }, + ], + }).search + expect(search.get('order')).toBe('id.asc.nullslast,name.desc.nullsfirst') + }) + + test('emits offset independently of limit', () => { + const search = build({ from: table, offset: 20 }).search + expect(search.get('offset')).toBe('20') + expect(search.has('limit')).toBe(false) + }) + + test("pushes a subquery FROM's where down and resolves the base table", () => { + const { tableName, search } = build({ + from: { + type: 'subquery', + alias: 'activeUser', + query: { from: table, where: [eq(userCol('active'), true)] }, + }, + }) + expect(tableName).toBe('users') + expect(search.get('active')).toBe('eq.true') + }) + + test('skips residual (client-side) where clauses', () => { + const search = build({ + from: table, + where: [{ expression: eq(userCol('id'), 1), residual: true }], + }).search + expect(search.has('id')).toBe(false) + }) +}) + // ── subsetOptionsToQueryKey ───────────────────────────────────────── describe('subsetOptionsToQueryKey', () => { const key = (where: IR.BasicExpression) => diff --git a/packages/supabase-db-collection/tests/query-once.test.ts b/packages/supabase-db-collection/tests/query-once.test.ts new file mode 100644 index 0000000000..5823757aec --- /dev/null +++ b/packages/supabase-db-collection/tests/query-once.test.ts @@ -0,0 +1,1539 @@ +import { createClient } from '@supabase/supabase-js' +import { + GroupByError, + add, + and, + avg, + coalesce, + concat, + count, + createCollection, + eq, + groupKeys, + gt, + gte, + ilike, + inArray, + include, + isNull, + length, + like, + localOnlyCollectionOptions, + lower, + lt, + lte, + max, + min, + not, + or, + sum, + upper, +} from '@tanstack/db' +import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest' +import { experimental_queryOnce } from '../src/index' +import { VERSION } from '../src/version' +import { makePaginatingFetch } from './pagination.utils' +import { + SUPABASE_KEY, + SUPABASE_URL, + createMockFetch, + createMockedTodosCollection, + createMockedUsersCollection, + createMockedUsersTodosCollection, + expectFetchUrls, + getRequestHeaders, + normalizeFetchUrl, +} from './test.utils' + +describe('queryOnce PostgREST query generation', () => { + let mockFetch: ReturnType + let supabase: ReturnType + let usersCollection: ReturnType + let utCollection: ReturnType + let todosCollection: ReturnType + + beforeEach(() => { + mockFetch = createMockFetch() + supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + usersCollection = createMockedUsersCollection(mockFetch) + utCollection = createMockedUsersTodosCollection(mockFetch) + todosCollection = createMockedTodosCollection(mockFetch) + }) + + afterEach(() => { + usersCollection.cleanup() + utCollection.cleanup() + todosCollection.cleanup() + }) + + describe('FROM', () => { + test('SELECT * FROM users', async () => { + await experimental_queryOnce( + (q) => q.from({ user: usersCollection }), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + }) + + describe('automatic X-Client-Info header', () => { + test('is present on the request', async () => { + await experimental_queryOnce( + (q) => q.from({ user: usersCollection }), + supabase, + ) + expect(getRequestHeaders(mockFetch, 0).get('x-client-info')).toBe( + `@tanstack/supabase-db-collection/${VERSION}`, + ) + }) + + test('is present on the server aggregate path', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expect(getRequestHeaders(mockFetch, 0).get('x-client-info')).toBe( + `@tanstack/supabase-db-collection/${VERSION}`, + ) + }) + }) + + describe('WHERE', () => { + test('WHERE active = true', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&active=eq.true']) + }) + + test('WHERE id = 1', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).where(({ user }) => eq(user.id, 1)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=eq.1']) + }) + + test("WHERE name = 'John'", async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.name, 'John')), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&name=eq.John']) + }) + + test('WHERE id > 5 (gt)', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).where(({ user }) => gt(user.id, 5)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=gt.5']) + }) + + test('WHERE id >= 5 (gte)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => gte(user.id, 5)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=gte.5']) + }) + + test('WHERE id < 10 (lt)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => lt(user.id, 10)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=lt.10']) + }) + + test('WHERE id <= 10 (lte)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => lte(user.id, 10)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=lte.10']) + }) + + test('WHERE id IN (1, 2, 3)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => inArray(user.id, [1, 2, 3])), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=in.(1,2,3)']) + }) + + test('WHERE NOT(active = false)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => not(eq(user.active, false))), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=not.eq.false', + ]) + }) + + test('WHERE name IS NULL', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => isNull(user.name)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&name=is.null']) + }) + + test('AND: active = true AND id > 5', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => and(eq(user.active, true), gt(user.id, 5))), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&id=gt.5', + ]) + }) + + test('chained .where', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .where(({ user }) => gt(user.id, 5)), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&id=gt.5', + ]) + }) + + test('OR: active = true OR id = 1', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => or(eq(user.active, true), eq(user.id, 1))), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&or=(active.eq.true,id.eq.1)', + ]) + }) + + test("nested AND/OR: active = true AND (id > 5 OR name = 'admin')", async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + and( + eq(user.active, true), + or(gt(user.id, 5), eq(user.name, 'admin')), + ), + ), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&or=(id.gt.5,name.eq.admin)', + ]) + }) + }) + + describe('SELECT columns', () => { + test('subset of fields', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ id: user.id, name: user.name })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('field renaming', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ userId: user.id, fullName: user.name })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('computed boolean with eq falls back to *', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + isActive: eq(user.active, true), + })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('upper(name) falls back to *', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + upperName: upper(user.name), + })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('lower(email) falls back to *', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + lowerEmail: lower(user.email), + })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('concat falls back to *', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + nameAndEmail: concat(user.name, ' ', user.email), + })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('length(name) falls back to *', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + nameLength: length(user.name), + })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('add(id, 1) falls back to *', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + idPlusOne: add(user.id, 1), + })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('coalesce falls back to *', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + displayName: coalesce(user.name, 'Unknown'), + })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('spread + computed field falls back to *', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + ...user, + highId: gt(user.id, 5), + })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + }) + + describe('Aggregate functions (pushed to PostgREST)', () => { + test('count(id)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count()', + ]) + }) + + test('sum(id)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ sumId: sum(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=sumId:id.sum()']) + }) + + test('avg(id)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ avgId: avg(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=avgId:id.avg()']) + }) + + test('min(id)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ minId: min(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=minId:id.min()']) + }) + + test('max(id)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ maxId: max(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=maxId:id.max()']) + }) + + test('multiple aggregates', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + totalUsers: count(user.id), + maxId: max(user.id), + })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count(),maxId:id.max()', + ]) + }) + + test('aggregate with where', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count()&active=eq.true', + ]) + }) + + // Only the server aggregate path reaches this package's own translator; + // every other query falls through to the collection loader. + test('aggregate with LIKE / ILIKE', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => like(user.name, '%Ali%')) + .where(({ user }) => ilike(user.email, '%ali%')) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count()&name=like.%25Ali%25&email=ilike.%25ali%25', + ]) + }) + + test('aggregate with OR of ILIKEs', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + or(ilike(user.name, '%ali%'), ilike(user.email, '%ali%')), + ) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count()&or=(name.ilike.%25ali%25,email.ilike.%25ali%25)', + ]) + }) + + test('aggregate with nested AND/OR of ILIKEs', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + and( + eq(user.active, true), + or(ilike(user.name, '%ali%'), ilike(user.email, '%ali%')), + ), + ) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count()&active=eq.true&or=(name.ilike.%25ali%25,email.ilike.%25ali%25)', + ]) + }) + + test('aggregate with an IN list inside an OR', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + or(inArray(user.id, [1, 2, 3]), eq(user.active, true)), + ) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count()&or=(id.in.(1,2,3),active.eq.true)', + ]) + }) + + test('aggregate quotes values containing a comma', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + or(ilike(user.name, '%a,b%'), eq(user.email, 'x,y')), + ) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count()&or=(name.ilike."%25a,b%25",email.eq."x,y")', + ]) + }) + + test('aggregate with a negated logical group', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + not(and(eq(user.active, true), ilike(user.name, '%ali%'))), + ) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count()&or=(active.not.eq.true,name.not.ilike.%25ali%25)', + ]) + }) + + test('aggregate rejects unsupported filters before making a request', async () => { + await expect( + experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + or(eq(user.active, true), eq(upper(user.name), 'ALICE')), + ) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ), + ).rejects.toThrow('fully pushable filters') + expect(mockFetch).not.toHaveBeenCalled() + }) + + test('aggregate with NOT(name LIKE …)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => not(like(user.name, '%Ali%'))) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count()&name=not.like.%25Ali%25', + ]) + }) + }) + + describe('GROUP BY (falls back to *, aggregation client-side)', () => { + test('single column groupBy', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .groupBy(groupKeys(({ user }) => user.active)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('single column GROUP BY with WHERE', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .groupBy(groupKeys(({ user }) => user.active)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&active=eq.true']) + }) + + test('GROUP BY + aggregates falls back to *', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + userCount: count(user.id), + })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&active=eq.true']) + }) + }) + + describe('HAVING (client-side)', () => { + test('HAVING with direct aggregate', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + totalId: sum(user.id), + })) + .having(({ user }) => gt(sum(user.id), 10)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('HAVING with $selected fields', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + totalCount: count(user.id), + })) + .having(({ $selected }) => gt($selected.totalCount, 5)), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + }) + + describe('ORDER BY', () => { + test('default (asc)', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).orderBy(({ user }) => user.name), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=name.asc.nullsfirst', + ]) + }) + + test('explicit asc', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.name, 'asc'), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=name.asc.nullsfirst', + ]) + }) + + test('descending', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.name, 'desc'), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=name.desc.nullsfirst', + ]) + }) + + test('multi-column orderBy', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.name, 'asc') + .orderBy(({ user }) => user.id, 'desc'), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=name.asc.nullsfirst,id.desc.nullsfirst', + ]) + }) + + test('order by $selected/computed field is skipped', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ + id: user.id, + name: user.name, + nameLength: length(user.name), + })) + .orderBy(({ $selected }) => $selected.nameLength, 'desc'), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + }) + + describe('LIMIT', () => { + test.todo('basic limit', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.id) + .limit(10), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&order=id.asc.nullsfirst&limit=10', + ]) + }) + }) + + describe('LIMIT + OFFSET', () => { + test.todo('pagination (page 2)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.id) + .limit(20) + .offset(20), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?order=id.asc.nullsfirst&limit=20&offset=20&select=*', + ]) + }) + }) + + describe('Subquery in FROM', () => { + test('filtered query as source pushes filter down', async () => { + await experimental_queryOnce((q) => { + const activeUsers = q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + return q.from({ activeUser: activeUsers }) + }, supabase) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&active=eq.true']) + }) + }) + + describe('findOne', () => { + test.todo('findOne with where pushes filter and limit', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.id, 1)) + .findOne(), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&id=eq.1&limit=1']) + }) + }) + + describe('DISTINCT (client-side, select=*)', () => { + test('single column distinct', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .select(({ user }) => ({ name: user.name })) + .distinct(), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('distinct with where clause', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .select(({ user }) => ({ name: user.name })) + .distinct(), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*&active=eq.true']) + }) + }) + + describe('Combined queries', () => { + test.todo('WHERE + ORDER BY + LIMIT', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .orderBy(({ user }) => user.name, 'asc') + .limit(10), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&order=name.asc.nullsfirst&limit=10', + ]) + }) + + test('WHERE + ORDER BY', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .orderBy(({ user }) => user.name, 'desc'), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&active=eq.true&order=name.desc.nullsfirst', + ]) + }) + + test('WHERE + ORDER BY + LIMIT (gt)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => gt(user.id, 3)) + .orderBy(({ user }) => user.id) + .limit(5), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*&id=gt.3&order=id.asc.nullsfirst&limit=5', + ]) + }) + + test('GROUP BY + HAVING + ORDER BY($selected) + LIMIT (client-side)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + userCount: count(user.id), + maxId: max(user.id), + })) + .having(({ $selected }) => gt($selected.userCount, 0)) + .orderBy(({ $selected }) => $selected.userCount, 'desc') + .limit(10), + supabase, + ) + // The limit applies to groups, not rows, so it must not reach PostgREST. + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test.todo('SELECT columns + WHERE + ORDER BY + LIMIT', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .select(({ user }) => ({ id: user.id, name: user.name })) + .orderBy(({ user }) => user.name, 'asc') + .limit(5), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?active=eq.true&limit=5&order=name.asc.nullsfirst&select=*', + ]) + }) + + test('aggregates + WHERE + LIMIT', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .select(({ user }) => ({ + totalUsers: count(user.id), + avgId: avg(user.id), + })) + .limit(1), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=totalUsers:id.count(),avgId:id.avg()&active=eq.true&limit=1', + ]) + }) + }) + + describe('JOIN (resource embedding)', () => { + test('basic inner join', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .innerJoin({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users_todos?select=*', + '/rest/v1/users?id=in.(user_1)&select=*', + ]) + }) + + test('left join', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .leftJoin({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + ]) + }) + + test('right join', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .rightJoin({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users_todos?select=*', + '/rest/v1/users?id=in.(user_1)&select=*', + ]) + }) + + test('full join', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .fullJoin({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*', + ]) + }) + + test('explicit inner join via .join()', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .join( + { ut: utCollection }, + ({ user, ut }) => eq(user.id, ut.user_id), + 'inner', + ), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users_todos?select=*', + '/rest/v1/users?id=in.(user_1)&select=*', + ]) + }) + + test('(left) join with select', async () => { + await experimental_queryOnce( + (q) => + q.from({ user: usersCollection }).select(({ user }) => ({ + id: user.id, + todos: include( + q + .from({ ut: utCollection }) + .where(({ ut }) => eq(ut.user_id, user.id)), + ), + })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + ]) + }) + + test('two chained joins (users -> users_todos -> todos)', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .join({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ) + .join({ todo: todosCollection }, ({ ut, todo }) => + eq(ut.todo_id, todo.id), + ), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + '/rest/v1/todos?id=in.(todo_1)&select=*', + ]) + }) + + test('JOIN + WHERE', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .join({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ) + .where(({ user }) => eq(user.active, true)), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?active=eq.true&select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + ]) + }) + + test('JOIN + WHERE + SELECT + ORDER BY', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .join({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ) + .join({ todo: todosCollection }, ({ ut, todo }) => + eq(ut.todo_id, todo.id), + ) + .where(({ todo }) => eq(todo.completed, false)) + .select(({ user, todo }) => ({ + userName: user.name, + todoTitle: todo.title, + })) + .orderBy(({ user }) => user.name, 'asc'), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?order=name.asc.nullsfirst&select=*', + '/rest/v1/users_todos?select=*&user_id=in.(user_1)', + '/rest/v1/todos?id=in.(todo_1)&select=*', + ]) + }) + + test('filtered subquery as join target', async () => { + await experimental_queryOnce((q) => { + const activeUserTodos = q + .from({ ut: utCollection }) + .where(({ ut }) => gt(ut.todo_id, 0)) + return q + .from({ user: usersCollection }) + .join({ ut: activeUserTodos }, ({ user, ut }) => + eq(user.id, ut.user_id), + ) + }, supabase) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=*', + '/rest/v1/users_todos?select=*&todo_id=gt.0&user_id=in.(user_1)', + ]) + }) + + test('aggregate over a join is computed client-side', async () => { + // Pushed as-is, `count(ut.todo_id)` would lose its alias and count a + // `todo_id` column on users, so the join stays on the collection loader. + const rows = await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .innerJoin({ ut: utCollection }, ({ user, ut }) => + eq(user.id, ut.user_id), + ) + .select(({ ut }) => ({ todoCount: count(ut.todo_id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users_todos?select=*', + '/rest/v1/users?id=in.(user_1)&select=*', + ]) + expect(rows).toMatchObject([{ todoCount: 1 }]) + }) + }) +}) + +describe('queryOnce pagination', () => { + // Five users behind a mock whose server cap is 2 rows per request. + const USERS = [ + { id: 1, name: 'A', email: 'a@t', active: true }, + { id: 2, name: 'B', email: 'b@t', active: true }, + { id: 3, name: 'C', email: 'c@t', active: true }, + { id: 4, name: 'D', email: 'd@t', active: true }, + { id: 5, name: 'E', email: 'e@t', active: true }, + ] + + test('a non-aggregate queryOnce returns the full multi-page set', async () => { + // Non-aggregate queryOnce loads its source collection through the same + // supabaseQueryFn as live queries, so it inherits the db-max-rows paging + // loop for free — the full set comes back despite the cap. + const mockFetch = makePaginatingFetch(USERS, { cap: 2 }) + const users = createMockedUsersCollection(mockFetch) + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + + const rows = await experimental_queryOnce( + (q) => q.from({ user: users }), + supabase, + ) + + expect( + (rows as Array<{ id: number }>).map((r) => r.id).sort((a, b) => a - b), + ).toEqual([1, 2, 3, 4, 5]) + + await users.cleanup() + }) + + test('an ungrouped aggregate queryOnce stays a single executeQuery request', async () => { + // Ungrouped aggregates are pushed to PostgREST and bypass supabaseQueryFn, + // so they do NOT paginate: exactly one request is issued. + const mockFetch = makePaginatingFetch(USERS, { cap: 2 }) + const users = createMockedUsersCollection(mockFetch) + const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + + await experimental_queryOnce( + (q) => + q + .from({ user: users }) + .select(({ user }) => ({ total: count(user.id) })), + supabase, + ) + + const gets = mockFetch.mock.calls.filter( + (call) => (call[1]?.method ?? 'GET') === 'GET', + ) + expect(gets).toHaveLength(1) + + await users.cleanup() + }) +}) + +describe('queryOnce GROUP BY / HAVING results', () => { + // Five users split across two groups, behind a mock whose server cap is 2 + // rows per request, so grouping must see every page to be correct. + const USERS = [ + { id: 1, name: 'A', email: 'a@t', active: true }, + { id: 2, name: 'B', email: 'b@t', active: false }, + { id: 3, name: 'C', email: 'c@t', active: true }, + { id: 4, name: 'D', email: 'd@t', active: true }, + { id: 5, name: 'E', email: 'e@t', active: false }, + ] + + let mockFetch: ReturnType + let users: ReturnType + let supabase: ReturnType + + beforeEach(() => { + mockFetch = makePaginatingFetch(USERS, { cap: 2 }) + users = createMockedUsersCollection(mockFetch) + supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + }) + + afterEach(async () => { + await users.cleanup() + }) + + const byActive = (rows: Array<{ active: boolean }>) => + [...rows].sort((a, b) => Number(b.active) - Number(a.active)) + + test('groups rows and computes aggregates across every page', async () => { + const rows = await experimental_queryOnce( + (q) => + q + .from({ user: users }) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + userCount: count(user.id), + idSum: sum(user.id), + })), + supabase, + ) + + expect(byActive(rows)).toMatchObject([ + { active: true, userCount: 3, idSum: 8 }, + { active: false, userCount: 2, idSum: 7 }, + ]) + }) + + test('applies WHERE before grouping', async () => { + const rows = await experimental_queryOnce( + (q) => + q + .from({ user: users }) + .where(({ user }) => gt(user.id, 2)) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + userCount: count(user.id), + })), + supabase, + ) + + expect(byActive(rows)).toMatchObject([ + { active: true, userCount: 2 }, + { active: false, userCount: 1 }, + ]) + }) + + test('filters groups with HAVING', async () => { + const rows = await experimental_queryOnce( + (q) => + q + .from({ user: users }) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + userCount: count(user.id), + })) + .having(({ $selected }) => gt($selected.userCount, 2)), + supabase, + ) + + expect(rows).toHaveLength(1) + expect(rows[0]).toMatchObject({ active: true, userCount: 3 }) + }) + + test('applies LIMIT to groups, not rows', async () => { + const rows = await experimental_queryOnce( + (q) => + q + .from({ user: users }) + .groupBy(({ user }) => user.active) + .select(({ user }) => ({ + active: user.active, + userCount: count(user.id), + })) + .orderBy(({ $selected }) => $selected.userCount, 'desc') + .limit(1), + supabase, + ) + + expect(rows).toHaveLength(1) + expect(rows[0]).toMatchObject({ active: true, userCount: 3 }) + }) + + test('groups a collection not backed by Supabase without a request', async () => { + const local = createCollection( + localOnlyCollectionOptions({ + getKey: (row: { id: number; active: boolean }) => row.id, + initialData: [ + { id: 1, active: true }, + { id: 2, active: true }, + ], + }), + ) + + const rows = await experimental_queryOnce( + (q) => + q + .from({ row: local }) + .groupBy(({ row }) => row.active) + .select(({ row }) => ({ rowCount: count(row.id) })), + supabase, + ) + + expect(mockFetch).not.toHaveBeenCalled() + expect(rows).toMatchObject([{ rowCount: 2 }]) + }) +}) + +describe('queryOnce server aggregate routing', () => { + // Five users behind a mock whose server cap is 2 rows per request. The mock + // ignores `select`, so a query wrongly sent down the server aggregate path + // would get raw user rows back instead of the aggregate. + const USERS = [ + { id: 1, name: 'A', email: 'a@t', active: true }, + { id: 2, name: 'B', email: 'b@t', active: false }, + { id: 3, name: 'C', email: 'c@t', active: true }, + { id: 4, name: 'D', email: 'd@t', active: true }, + { id: 5, name: 'E', email: 'e@t', active: false }, + ] + const AGGREGATE_SELECT = /\.(count|sum|avg|min|max)\(\)/ + + let mockFetch: ReturnType + let users: ReturnType + let supabase: ReturnType + + beforeEach(() => { + mockFetch = makePaginatingFetch(USERS, { cap: 2 }) + users = createMockedUsersCollection(mockFetch) + supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + }) + + afterEach(async () => { + await users.cleanup() + }) + + /** Asserts the rows were fetched and aggregated client-side */ + const expectClientSide = () => { + const urls = mockFetch.mock.calls.map(([url]) => normalizeFetchUrl(url)) + expect(urls.length).toBeGreaterThan(0) + for (const url of urls) { + expect(url).not.toMatch(AGGREGATE_SELECT) + } + } + + test('computes an aggregate beside a computed field client-side', async () => { + const rows = await experimental_queryOnce( + (q) => + q.from({ user: users }).select(({ user }) => ({ + total: count(user.id), + nextId: add(max(user.id), 1), + })), + supabase, + ) + + expectClientSide() + expect(rows).toMatchObject([{ total: 5, nextId: 6 }]) + }) + + test('does not group by a plain column selected beside an aggregate', async () => { + // PostgREST would group `select=active,total:id.count()` by `active`; + // TanStack DB rejects the query before any request is sent. + await expect( + experimental_queryOnce( + (q) => + q.from({ user: users }).select(({ user }) => ({ + active: user.active, + total: count(user.id), + })), + supabase, + ), + ).rejects.toThrow(GroupByError) + + for (const [url] of mockFetch.mock.calls) { + expect(normalizeFetchUrl(url)).not.toMatch(AGGREGATE_SELECT) + } + }) + + test('applies fn.where before aggregating', async () => { + const rows = await experimental_queryOnce( + (q) => + q + .from({ user: users }) + .fn.where(({ user }) => user.id > 2) + .select(({ user }) => ({ total: count(user.id) })), + supabase, + ) + + expectClientSide() + expect(rows).toMatchObject([{ total: 3 }]) + }) + + test('applies fn.having to the aggregate row', async () => { + const rows = await experimental_queryOnce( + (q) => + q + .from({ user: users }) + .select(({ user }) => ({ total: count(user.id) })) + .fn.having(({ $selected }) => $selected.total > 10), + supabase, + ) + + expectClientSide() + expect(rows).toEqual([]) + }) + + test('aggregates over a subquery that limits its source', async () => { + const rows = await experimental_queryOnce((q) => { + const firstTwo = q + .from({ user: users }) + .orderBy(({ user }) => user.id) + .limit(2) + return q + .from({ top: firstTwo }) + .select(({ top }) => ({ total: count(top.id) })) + }, supabase) + + expectClientSide() + expect(rows).toMatchObject([{ total: 2 }]) + }) +}) + +describe('queryOnce server aggregate path', () => { + // Answers every request the way PostgREST answers an aggregate-only select. + let mockFetch: ReturnType + let users: ReturnType + let supabase: ReturnType + + beforeEach(() => { + mockFetch = vi.fn().mockImplementation(() => + Promise.resolve( + new Response(JSON.stringify([{ total: 5 }]), { + headers: { 'content-type': 'application/json' }, + }), + ), + ) + users = createMockedUsersCollection(mockFetch) + supabase = createClient(SUPABASE_URL, SUPABASE_KEY, { + global: { fetch: mockFetch }, + }) + }) + + afterEach(async () => { + await users.cleanup() + }) + + test('findOne resolves to the aggregate row, not an array', async () => { + const result = await experimental_queryOnce( + (q) => + q + .from({ user: users }) + .select(({ user }) => ({ total: count(user.id) })) + .findOne(), + supabase, + ) + + expectFetchUrls(mockFetch, ['/rest/v1/users?select=total:id.count()']) + expect(result).toEqual({ total: 5 }) + }) + + test('does not push ORDER BY beside an aggregate', async () => { + // Postgres rejects ORDER BY on a column outside the aggregates, and a + // single row has nothing to order. + const rows = await experimental_queryOnce( + (q) => + q + .from({ user: users }) + .orderBy(({ user }) => user.name) + .select(({ user }) => ({ total: count(user.id) })), + supabase, + ) + + expectFetchUrls(mockFetch, ['/rest/v1/users?select=total:id.count()']) + expect(rows).toEqual([{ total: 5 }]) + }) + + test('pushes the filters of a filter-only subquery source', async () => { + const rows = await experimental_queryOnce((q) => { + const laterUsers = q + .from({ user: users }) + .where(({ user }) => gt(user.id, 2)) + return q + .from({ later: laterUsers }) + .select(({ later }) => ({ total: count(later.id) })) + }, supabase) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=total:id.count()&id=gt.2', + ]) + expect(rows).toEqual([{ total: 5 }]) + }) + + test('computes an aggregate over a collection not backed by Supabase client-side', async () => { + // A collection this package did not create has no table behind it, so + // pushing its aggregate would query a table named after its id. + const local = createCollection( + localOnlyCollectionOptions({ + getKey: (row: { id: number }) => row.id, + initialData: [{ id: 1 }, { id: 2 }], + }), + ) + + const rows = await experimental_queryOnce( + (q) => + q.from({ row: local }).select(({ row }) => ({ total: count(row.id) })), + supabase, + ) + + expect(mockFetch).not.toHaveBeenCalled() + expect(rows).toMatchObject([{ total: 2 }]) + }) +}) diff --git a/packages/supabase-db-collection/tests/serialize.test.ts b/packages/supabase-db-collection/tests/serialize.test.ts new file mode 100644 index 0000000000..2839502104 --- /dev/null +++ b/packages/supabase-db-collection/tests/serialize.test.ts @@ -0,0 +1,48 @@ +import { Query } from '@tanstack/db' +import { describe, expect, test } from 'vitest' +import { serializeQueryIR } from '../src/serialize' +import { + createMockFetch, + createMockedTodosCollection, + createMockedUsersCollection, +} from './test.utils' +import type {BaseQueryBuilder} from '@tanstack/db'; + +describe('serializeQueryIR FROM variants', () => { + const mockFetch = createMockFetch() + const usersCollection = createMockedUsersCollection(mockFetch) + const todosCollection = createMockedTodosCollection(mockFetch) + + test('serializes a plain collection FROM as a table', () => { + const ir = ( + new Query().from({ + user: usersCollection, + }) as unknown as BaseQueryBuilder + )._getQuery() + + const serialized = serializeQueryIR(ir) + expect(serialized.from).toMatchObject({ type: 'table', name: 'users' }) + }) + + // Regression: @tanstack/db 0.6.x widened IR.From to include UnionFrom / + // UnionAll. Serialization used to only accept CollectionRef | QueryRef, so + // the package no longer type-checked and a union FROM was unrepresentable. + test('serializes a unionAll FROM without throwing', () => { + const ir = ( + new Query().unionAll( + new Query().from({ user: usersCollection }), + new Query().from({ todo: todosCollection }), + ) as unknown as BaseQueryBuilder + )._getQuery() + + const serialized = serializeQueryIR(ir) + expect(serialized.from.type).toBe('unionAll') + if (serialized.from.type === 'unionAll') { + expect(serialized.from.queries).toHaveLength(2) + expect(serialized.from.queries[0]?.from).toMatchObject({ + type: 'table', + name: 'users', + }) + } + }) +}) From 052812fbf211446606332b08aaf46feb1db2d4b4 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Wed, 11 Nov 2026 12:07:51 +0100 Subject: [PATCH 09/13] test(supabase-db-collection): read e2e filters through queryOnce and executeQuery Restore the upstream queryOnce cases in the reads and filters e2e tests. Each filter case now checks the live query, experimental_queryOnce, and executeQuery paths, each through a fresh collection. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../e2e/filters.e2e.test.ts | 114 ++++++++++++++---- .../e2e/reads.e2e.test.ts | 14 +++ 2 files changed, 102 insertions(+), 26 deletions(-) diff --git a/packages/supabase-db-collection/e2e/filters.e2e.test.ts b/packages/supabase-db-collection/e2e/filters.e2e.test.ts index 91b267431a..db0e283094 100644 --- a/packages/supabase-db-collection/e2e/filters.e2e.test.ts +++ b/packages/supabase-db-collection/e2e/filters.e2e.test.ts @@ -11,32 +11,87 @@ import { upper, } from '@tanstack/db' import { expect } from 'vitest' +import { experimental_queryOnce } from '../src/index' +import { executeQuery } from '../src/query-once' import { makeUsersCollection, test } from './e2e.utils' const name = new IR.PropRef([`user`, `name`]) const active = new IR.PropRef([`user`, `active`]) const id = new IR.PropRef([`user`, `id`]) -// An on-demand live query sends its WHERE to PostgREST and becomes ready once -// that read has finished, so its rows are the server's answer filtered again -// on the client. A filter the server applies too strictly loses rows, which -// the client cannot add back. Each call reads through a fresh collection, so -// rows an earlier query loaded cannot hide the loss. -const liveNames = async (where: IR.BasicExpression) => { - const { collection, supabase } = makeUsersCollection() - const live = createLiveQueryCollection((q) => - q.from({ user: collection }).where(() => where), - ) +// Each case reads the same filter on three paths, and every path asserts the +// rows it returns, not the shape of a URL: +// +// - An on-demand live query sends its WHERE to PostgREST and becomes ready +// once that read has finished, so its rows are the server's answer filtered +// again on the client. +// - `experimental_queryOnce` runs the same one-shot query through TanStack +// DB's `queryOnce`. +// - `executeQuery` sends a serialized query IR straight to PostgREST, through +// the translation that server-side aggregates use. Nothing filters its rows +// again, so a filter the server applies too loosely shows up here. +// +// A filter the server applies too strictly loses rows, which the client +// cannot add back. Each call reads through a fresh collection, so rows an +// earlier query loaded cannot hide the loss. +const withUsers = async ( + read: (users: ReturnType) => Promise, +): Promise => { + const users = makeUsersCollection() try { - await live.preload() - return live.toArray.map((row) => row.name).sort() + return await read(users) } finally { - await live.cleanup() - await collection.cleanup() - await supabase.removeAllChannels() + await users.collection.cleanup() + await users.supabase.removeAllChannels() } } +const sortedNames = (rows: Array) => + rows.map((row) => (row as { name: string }).name).sort() + +const liveNames = (where: IR.BasicExpression) => + withUsers(async ({ collection }) => { + const live = createLiveQueryCollection((q) => + q.from({ user: collection }).where(() => where), + ) + try { + await live.preload() + return sortedNames(live.toArray) + } finally { + await live.cleanup() + } + }) + +const queryOnceNames = (where: IR.BasicExpression) => + withUsers(async ({ collection, supabase }) => + sortedNames( + await experimental_queryOnce( + (q) => q.from({ user: collection }).where(() => where), + supabase, + ), + ), + ) + +const serverNames = (where: IR.BasicExpression) => + withUsers(async ({ supabase }) => + sortedNames( + await executeQuery(supabase, { + from: { type: `table`, name: `users`, alias: `user` }, + where: [where], + }), + ), + ) + +const expectNamesOnEveryPath = async ( + where: IR.BasicExpression, + expected: ReadonlyArray, +) => { + const label = JSON.stringify(where) + expect(await liveNames(where), `live query ${label}`).toEqual(expected) + expect(await queryOnceNames(where), `queryOnce ${label}`).toEqual(expected) + expect(await serverNames(where), `executeQuery ${label}`).toEqual(expected) +} + const cases = [ [`OR`, or(eq(name, `Alice`), eq(name, `Nobody`)), [`Alice`]], [ @@ -62,8 +117,8 @@ const cases = [ ] as const for (const [label, where, expected] of cases) { - test(`${label} returns matching rows through a live query`, async () => { - expect(await liveNames(where)).toEqual(expected) + test(`${label} returns matching rows on every query path`, async () => { + await expectNamesOnEveryPath(where, expected) }) } @@ -80,12 +135,14 @@ for (const value of [``, ` a `, `a,b(c)`, `a"b\\c`, `a.b:c&d=1+%`, `{a,b}`]) { or(eq(name, value), eq(id, -1)), inArray(name, [value]), ]) { - expect(await liveNames(where), JSON.stringify(where)).toEqual([value]) + await expectNamesOnEveryPath(where, [value]) } }) } -test(`LIKE treats backslashes literally`, async ({ other }) => { +test(`LIKE treats backslashes literally on every query path`, async ({ + other, +}) => { const value = `a\\path` const { error } = await other .from(`users`) @@ -95,15 +152,20 @@ test(`LIKE treats backslashes literally`, async ({ other }) => { like(name, `a\\%`), or(like(name, `a\\%`), eq(id, -1)), ]) { - expect(await liveNames(where), JSON.stringify(where)).toEqual([value]) + await expectNamesOnEveryPath(where, [value]) } }) +// executeQuery is left out here: it returns PostgREST's rows without +// filtering them again, so a filter PostgREST cannot express has no exact +// answer on that path. test(`unsupported OR and negated patterns retain rows for client filtering`, async () => { - expect( - await liveNames(or(eq(name, `Nobody`), eq(upper(name), `ALICE`))), - ).toEqual([`Alice`]) - // PostgREST would interpret * as a wildcard and remove Alice here, whereas - // TanStack treats it literally and should keep both seeded names. - expect(await liveNames(not(like(name, `*Ali*`)))).toEqual([`Alice`, `Bob`]) + for (const read of [liveNames, queryOnceNames]) { + expect( + await read(or(eq(name, `Nobody`), eq(upper(name), `ALICE`))), + ).toEqual([`Alice`]) + // PostgREST would interpret * as a wildcard and remove Alice here, whereas + // TanStack treats it literally and should keep both seeded names. + expect(await read(not(like(name, `*Ali*`)))).toEqual([`Alice`, `Bob`]) + } }) diff --git a/packages/supabase-db-collection/e2e/reads.e2e.test.ts b/packages/supabase-db-collection/e2e/reads.e2e.test.ts index a868e0a24d..8315255297 100644 --- a/packages/supabase-db-collection/e2e/reads.e2e.test.ts +++ b/packages/supabase-db-collection/e2e/reads.e2e.test.ts @@ -1,5 +1,6 @@ import { createLiveQueryCollection, eq, inArray } from '@tanstack/db' import { expect, vi } from 'vitest' +import { experimental_queryOnce } from '../src/index' import { WAIT, test } from './e2e.utils' test('reads seeded rows through PostgREST', ({ usersLive }) => { @@ -27,6 +28,19 @@ test('pushes a WHERE filter down to PostgREST', async ({ users }) => { } }) +test('queryOnce runs a one-shot filtered query', async ({ users }) => { + const rows = await experimental_queryOnce( + (q) => + q + .from({ user: users.collection }) + .where(({ user }) => eq(user.active, true)), + users.supabase, + ) + + expect(rows).toHaveLength(1) + expect(rows[0]?.name).toBe('Alice') +}) + test('reads a set larger than the server row cap across pages', async ({ users, other, From 1e0934cdb114c892093bc0f05fb06ab0d7ccdc11 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Wed, 11 Nov 2026 13:40:02 +0100 Subject: [PATCH 10/13] test(supabase-db-collection): add the queryOnce server-aggregate oracle experimental_queryOnce must resolve to what TanStack DB's queryOnce resolves to for the same query over the same table state. The oracle generates table states and aggregate-only queries, runs both against a local Supabase stack with PostgREST aggregates enabled, and compares the selected fields. RED on the ported implementation: 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 [], sum(id) expected [ { sum_id_0: null } ] to strictly equal [] Co-Authored-By: Claude Opus 5.5 (1M context) --- .../query-once-aggregate-oracle.e2e.test.ts | 508 ++++++++++++++++++ .../00000000000002_query_once_aggregates.sql | 41 ++ 2 files changed, 549 insertions(+) create mode 100644 packages/supabase-db-collection/e2e/query-once-aggregate-oracle.e2e.test.ts create mode 100644 packages/supabase-db-collection/supabase/migrations/00000000000002_query_once_aggregates.sql diff --git a/packages/supabase-db-collection/e2e/query-once-aggregate-oracle.e2e.test.ts b/packages/supabase-db-collection/e2e/query-once-aggregate-oracle.e2e.test.ts new file mode 100644 index 0000000000..ead31101da --- /dev/null +++ b/packages/supabase-db-collection/e2e/query-once-aggregate-oracle.e2e.test.ts @@ -0,0 +1,508 @@ +/** + * Server-aggregate oracle for `experimental_queryOnce`. + * + * Law: for every query it accepts, `experimental_queryOnce(query, supabase)` + * resolves to the same result as TanStack DB's `queryOnce(query)` over the + * same table state. Routing a query to PostgREST is an optimization; it must + * not change the answer. Authority: IFCS-154 and the function's contract. + * Queries that are not aggregate-only "fall back to TanStack DB's own + * `queryOnce`", and the server path returns a result "shaped like TanStack's + * result", so a caller cannot choose a route and must not see one. + * + * Why generated histories: an aggregate-only select over one Supabase table is + * the only query the server path computes. Its answer depends on details that + * fixed examples rarely combine: + * + * - empty and all-null inputs, where SQL aggregates return `null` or `0`; + * - columns the collection reads through `parse`, which PostgREST never sees; + * - text ordering for `min`/`max`, which Postgres decides by collation; + * - `limit`, `offset`, and `findOne` on the single aggregate row; + * - a filter-only subquery source, whose `where` is pushed down too. + * + * Limits: one local Supabase stack (PostgREST with `db_aggregates_enabled`), + * one table, and the aggregates `count`, `sum`, `avg`, `min`, and `max`. + * Grouped, joined, and computed queries take TanStack DB's path on both sides; + * this oracle generates none of them, so it says nothing about them. The + * comparison is exact: it does not round averages. + */ +import { createClient } from '@supabase/supabase-js' +import { + and, + avg, + count, + createCollection, + eq, + gt, + inArray, + isNull, + max, + min, + not, + or, + queryOnce, + sum, +} from '@tanstack/db' +import { QueryClient } from '@tanstack/query-core' +import fc from 'fast-check' +import { expect, inject, it } from 'vitest' +import { z } from 'zod' +import { runOracleCampaign } from '../../db/tests/oracle-campaign' +import { oracleRuns } from '../../db/tests/oracle-config' +import { declareOracle } from '../../db/tests/oracle-declaration' +import { experimental_queryOnce, supabaseCollectionOptions } from '../src/index' +import { makeAdminClient } from './setup' +import type { InitialQueryBuilder } from '@tanstack/db' + +// ── History grammar ───────────────────────────────────────────────── +// +// A history is one table state, written through the service-role client, and +// one to three aggregate queries run against it. Values come from small +// domains so that ties, nulls, and empty matches are common: +// +// - `score` is a small integer, so sums and averages stay exact in a double; +// - `label` mixes case and the empty string, which text collations order +// differently; +// - `recorded_at` is a timestamptz, read into a `Date` with `parse`; +// - `big_count` is a bigint stored as text and read with `parse`, so `10` +// orders after `9` in the collection but before it in Postgres. +// +// Only aggregate-only selects over the `query_once_rows` table are generated, +// so every query is one the server path accepts. Illegal histories (a +// duplicate id, `sum` over text) are not generated. + +const COLUMNS = [`id`, `score`, `label`, `recorded_at`, `big_count`] as const +type Column = (typeof COLUMNS)[number] +const NUMERIC_COLUMNS = [`id`, `score`] as const +const CONVERTED_COLUMNS: ReadonlyArray = [`recorded_at`, `big_count`] + +interface SeedRow { + id: number + score: number | null + label: string | null + recorded_at: string | null + big_count: string | null +} + +type Aggregate = + | { fn: `count` | `min` | `max`; column: Column } + | { fn: `sum` | `avg`; column: (typeof NUMERIC_COLUMNS)[number] } + +type Filter = + | { kind: `gt`; value: number } + | { kind: `eq`; value: string } + | { kind: `isNull`; column: Column } + | { kind: `in`; ids: Array } + | { kind: `not`; inner: Filter } + | { kind: `and` | `or`; left: Filter; right: Filter } + +interface AggregateQuery { + aggregates: Array + where?: Filter + /** A filter applied inside a subquery source instead of the outer query */ + sourceWhere?: Filter + limit?: number + offset?: number + findOne: boolean +} + +const seedRows = fc + .uniqueArray(fc.integer({ min: 1, max: 12 }), { maxLength: 6 }) + .chain((ids) => + fc.tuple( + ...ids.map((id) => + fc.record({ + id: fc.constant(id), + score: fc.option(fc.integer({ min: -3, max: 3 })), + label: fc.option(fc.constantFrom(`a`, `A`, `b`, `B`, ``, `a b`)), + recorded_at: fc.option( + fc.constantFrom( + `2026-01-01T00:00:00+00:00`, + `2026-01-02T12:00:00+00:00`, + `2025-12-31T23:59:59+00:00`, + ), + ), + big_count: fc.option( + fc.constantFrom(`9`, `10`, `-1`, `9007199254740993`), + ), + }), + ), + ), + ) + +const aggregate: fc.Arbitrary = fc.oneof( + fc.record({ + fn: fc.constantFrom(`count` as const, `min` as const, `max` as const), + column: fc.constantFrom(...COLUMNS), + }), + fc.record({ + fn: fc.constantFrom(`sum` as const, `avg` as const), + column: fc.constantFrom(...NUMERIC_COLUMNS), + }), +) + +const filter: fc.Arbitrary = fc.letrec<{ filter: Filter }>((tie) => ({ + filter: fc.oneof( + { depthSize: `small`, withCrossShrink: true }, + fc.record({ + kind: fc.constant(`gt` as const), + value: fc.integer({ min: -3, max: 3 }), + }), + fc.record({ + kind: fc.constant(`eq` as const), + value: fc.constantFrom(`a`, `B`, ``), + }), + fc.record({ + kind: fc.constant(`isNull` as const), + column: fc.constantFrom(...COLUMNS), + }), + fc.record({ + kind: fc.constant(`in` as const), + ids: fc.uniqueArray(fc.integer({ min: 1, max: 12 }), { maxLength: 3 }), + }), + fc.record({ kind: fc.constant(`not` as const), inner: tie(`filter`) }), + fc.record({ + kind: fc.constantFrom(`and` as const, `or` as const), + left: tie(`filter`), + right: tie(`filter`), + }), + ), +})).filter + +const aggregateQuery: fc.Arbitrary = fc.record( + { + aggregates: fc.array(aggregate, { minLength: 1, maxLength: 3 }), + where: filter, + sourceWhere: filter, + limit: fc.constantFrom(0, 1, 5), + offset: fc.constantFrom(0, 1), + findOne: fc.boolean(), + }, + { requiredKeys: [`aggregates`, `findOne`] }, +) + +type History = typeof history extends fc.Arbitrary ? T : never + +const history = fc.record({ + rows: seedRows, + queries: fc.array(aggregateQuery, { minLength: 1, maxLength: 3 }), +}) + +// ── Production driver ─────────────────────────────────────────────── +// +// Both sides read the same table through a Supabase collection created by +// this package, with the same `parse` conversions: +// +// - The production side runs `experimental_queryOnce` over an on-demand +// collection (the default). Its Supabase client records every request, so +// the driver can tell whether PostgREST computed the aggregate. +// - The reference side runs TanStack DB's `queryOnce` over an eager collection, +// which loads every row and computes the aggregate in TanStack DB. It never +// asks PostgREST to filter or aggregate, so it shares no translation with +// the server path. + +const rowSchema = z.object({ + id: z.number(), + score: z.number().nullable(), + label: z.string().nullable(), + recorded_at: z.date().nullable(), + big_count: z.bigint().nullable(), +}) + +const conversions = { + parse: { + recorded_at: (value: unknown) => new Date(value as string), + big_count: (value: unknown) => BigInt(value as string), + }, + serialize: { + recorded_at: (value: Date) => value.toISOString(), + big_count: (value: bigint) => value.toString(), + }, +} + +function makeRowsCollection(syncMode: `eager` | `on-demand`) { + const requests: Array = [] + const supabase = createClient( + inject(`supabaseUrl`), + inject(`supabaseAnonKey`), + { + global: { + fetch: (input, init) => { + requests.push(new URL(input instanceof Request ? input.url : input)) + return fetch(input, init) + }, + }, + }, + ) + const collection = createCollection( + supabaseCollectionOptions({ + tableName: `query_once_rows`, + keys: [`id`], + schema: rowSchema, + supabase, + queryClient: new QueryClient(), + syncMode, + ...conversions, + }), + ) + return { collection, supabase, requests } +} + +type RowsCollection = ReturnType[`collection`] + +// The builders are typed for the collection's row refs; the generated query +// picks columns at run time, so refs are passed as `never`. +type RowRef = Record + +/** Renders a generated filter with TanStack DB's expression builders. */ +function where(row: RowRef, spec: Filter): ReturnType { + switch (spec.kind) { + case `gt`: + return gt(row.score, spec.value) + case `eq`: + return eq(row.label, spec.value) + case `isNull`: + return isNull(row[spec.column]) + case `in`: + return inArray(row.id, spec.ids) + case `not`: + return not(where(row, spec.inner)) + case `and`: + return and(where(row, spec.left), where(row, spec.right)) + case `or`: + return or(where(row, spec.left), where(row, spec.right)) + } +} + +const AGGREGATES: Record unknown> = { + count, + sum, + avg, + min, + max, +} + +/** + * The rows a generated query aggregates: the table, or a subquery that only + * filters it, then the outer filter. + */ +function filteredRows( + q: InitialQueryBuilder, + collection: RowsCollection, + spec: AggregateQuery, +) { + const { sourceWhere, where: outerWhere } = spec + const source = + sourceWhere === undefined + ? collection + : q + .from({ inner: collection }) + .where(({ inner }) => where(inner as unknown as RowRef, sourceWhere)) + const query = q.from({ row: source as RowsCollection }) + return outerWhere === undefined + ? query + : query.where(({ row }) => where(row as unknown as RowRef, outerWhere)) +} + +const aliasOf = (agg: Aggregate, index: number) => + `${agg.fn}_${agg.column}_${index}` + +/** + * Builds the generated query. Its select holds only aggregates, so both sides + * receive a query the server path accepts. + */ +function buildQuery(collection: RowsCollection, spec: AggregateQuery) { + return (q: InitialQueryBuilder) => { + let selected = filteredRows(q, collection, spec).select( + ({ row }) => + Object.fromEntries( + spec.aggregates.map((agg, index) => [ + aliasOf(agg, index), + AGGREGATES[agg.fn]((row as unknown as RowRef)[agg.column]), + ]), + ) as Record>, + ) + if (spec.limit !== undefined) selected = selected.limit(spec.limit) + if (spec.offset !== undefined) selected = selected.offset(spec.offset) + return spec.findOne ? selected.findOne() : selected + } +} + +// ── Refinement check ──────────────────────────────────────────────── +// +// Checkpoint: the settled promise of each query. Both results must be equal +// as values: the same number of rows, or `undefined` for `findOne` with no +// row, and in each row the same value of every selected alias. A `Date` +// equals only a `Date` at the same instant, a `bigint` only a `bigint`, and +// `null` only `null`. An error must match too: if the reference rejects, +// production must reject. +// +// The comparison projects each row to the select's aliases. TanStack DB's rows +// also carry the virtual fields `$key`, `$origin`, `$hasPendingWrites`, and +// `$collectionId`, which describe the temporary live-query Collection that +// `queryOnce` creates; `$collectionId` differs on every call. Rows that +// PostgREST computes have no such Collection. Authority: maintainer decision +// (Ivan Vasilov, 2026-11-11), recorded in docs/contributing/oracle-coverage.md. + +type Outcome = { ok: true; value: unknown } | { ok: false; error: string } + +async function settle(run: () => Promise): Promise { + try { + return { ok: true, value: await run() } + } catch (error) { + return { ok: false, error: String(error) } + } +} + +function projectToAliases(value: unknown, aliases: Array): unknown { + if (Array.isArray(value)) { + return value.map((row) => projectToAliases(row, aliases)) + } + if (value === undefined) return value + const row = value as Record + return Object.fromEntries(aliases.map((alias) => [alias, row[alias]])) +} + +function expectSameOutcome( + production: Outcome, + reference: Outcome, + aliases: Array, + label: string, +): void { + if (!reference.ok) { + expect(production.ok, `${label}: reference rejected`).toBe(false) + return + } + expect(production.ok, `${label}: production rejected`).toBe(true) + if (!production.ok) return + expect(projectToAliases(production.value, aliases), label).toStrictEqual( + projectToAliases(reference.value, aliases), + ) +} + +declareOracle({ check: [expectSameOutcome], grammar: [history] }) + +// ── Reach ─────────────────────────────────────────────────────────── +// +// Each state is credited from an observation, not from the generated intent: +// +// - `server-route`: production sent an aggregate select to PostgREST; +// - `empty-match`: the reference matched no rows; +// - `null-only-column`: an aggregated column is null in every matched row; +// - `converted-column`: an aggregate reads a parsed column with values; +// - `limit-or-offset`: the query set `limit` or `offset`; +// - `find-one`: the query used `findOne`; +// - `subquery-source`: the query read a filter-only subquery. + +const REACH_STATES = [ + `server-route`, + `empty-match`, + `null-only-column`, + `converted-column`, + `limit-or-offset`, + `find-one`, + `subquery-source`, +] as const +type ReachState = (typeof REACH_STATES)[number] + +const isAggregateSelect = (url: URL) => + /\.(count|sum|avg|min|max)\(\)/.test(url.searchParams.get(`select`) ?? ``) + +async function withCleanup( + body: () => Promise, + ...cleanups: Array<() => Promise> +): Promise { + let primary: { error: unknown } | undefined + try { + await body() + } catch (error) { + primary = { error } + } + const errors: Array = [] + for (const cleanup of cleanups) { + try { + await cleanup() + } catch (error) { + errors.push(error) + } + } + if (primary && errors.length > 0) { + throw new AggregateError( + [primary.error, ...errors], + `Comparison and cleanup failed`, + { cause: primary.error }, + ) + } + if (primary) throw primary.error + if (errors.length > 0) { + throw new AggregateError(errors, `Cleanup failed`, { cause: errors[0] }) + } +} + +async function runHistory( + { rows, queries }: History, + reached: (state: ReachState) => void, +): Promise { + const { error } = await makeAdminClient().rpc(`reset_query_once_rows`, { + rows: rows satisfies Array, + }) + if (error) throw new Error(`seeding failed: ${error.message}`) + + const production = makeRowsCollection(`on-demand`) + const reference = makeRowsCollection(`eager`) + await withCleanup( + async () => { + for (const [index, spec] of queries.entries()) { + const label = `query ${index}: ${JSON.stringify(spec)}` + production.requests.length = 0 + const actual = await settle(() => + experimental_queryOnce( + buildQuery(production.collection, spec), + production.supabase, + ), + ) + const expected = await settle(() => + queryOnce(buildQuery(reference.collection, spec)), + ) + expectSameOutcome(actual, expected, spec.aggregates.map(aliasOf), label) + + if (production.requests.some(isAggregateSelect)) reached(`server-route`) + const matched: Array> = await queryOnce((q) => + filteredRows(q, reference.collection, spec), + ) + if (matched.length === 0) reached(`empty-match`) + for (const { column } of spec.aggregates) { + const values = matched.map((row) => row[column]) + if (values.length > 0 && values.every((value) => value === null)) + reached(`null-only-column`) + if ( + CONVERTED_COLUMNS.includes(column) && + values.some((value) => value !== null) + ) + reached(`converted-column`) + } + if (spec.limit !== undefined || spec.offset !== undefined) + reached(`limit-or-offset`) + if (spec.findOne) reached(`find-one`) + if (spec.sourceWhere !== undefined) reached(`subquery-source`) + } + }, + () => production.collection.cleanup(), + () => reference.collection.cleanup(), + ) +} + +it(`experimental_queryOnce matches TanStack DB's queryOnce for generated aggregate queries`, async () => { + await runOracleCampaign( + `SUPABASE_QUERY_ONCE_AGGREGATE_ORACLE`, + REACH_STATES, + async (reach, parameters) => { + await fc.assert( + fc.asyncProperty(history, async (generated) => { + reach.beginHistory() + await runHistory(generated, (state) => reach.reach(state)) + }), + { numRuns: oracleRuns(25), ...parameters }, + ) + }, + ) +}, 300_000) diff --git a/packages/supabase-db-collection/supabase/migrations/00000000000002_query_once_aggregates.sql b/packages/supabase-db-collection/supabase/migrations/00000000000002_query_once_aggregates.sql new file mode 100644 index 0000000000..443ff4e1a9 --- /dev/null +++ b/packages/supabase-db-collection/supabase/migrations/00000000000002_query_once_aggregates.sql @@ -0,0 +1,41 @@ +-- Schema for the experimental_queryOnce server-aggregate oracle +-- (e2e/query-once-aggregate-oracle.e2e.test.ts). +-- +-- experimental_queryOnce computes an aggregate-only query with PostgREST's +-- aggregate functions, which are off by default. Supabase enables them per +-- project through the authenticator role's in-database PostgREST config. +alter role authenticator set pgrst.db_aggregates_enabled = 'true'; +notify pgrst, 'reload config'; + +-- Every column is nullable, so a generated history can aggregate an empty or +-- all-null column. "big_count" stores a bigint as text, which the collection +-- reads with `parse` (the way the shared suites store "largeViewCount"), so +-- Postgres orders it as text while the collection orders it as a bigint. +create table public.query_once_rows ( + id bigint primary key, + score integer, + label text, + recorded_at timestamptz, + big_count text +); + +alter table public.query_once_rows enable row level security; +create policy "e2e allow all" on public.query_once_rows + for all to public using (true) with check (true); + +-- Replaces every row with one generated history's rows in a single round +-- trip. Execute is restricted to service_role, like reset_e2e(). +create or replace function public.reset_query_once_rows(rows jsonb) +returns void +language sql +security definer +set search_path = '' +as $$ + truncate table public.query_once_rows; + insert into public.query_once_rows + select * from jsonb_populate_recordset(null::public.query_once_rows, rows); +$$; + +revoke execute on function public.reset_query_once_rows(jsonb) + from public, anon, authenticated; +grant execute on function public.reset_query_once_rows(jsonb) to service_role; From f220600a4249bf0aed0ca0d0722d9ab29ee2fec9 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Wed, 11 Nov 2026 14:13:38 +0100 Subject: [PATCH 11/13] fix(supabase-db-collection): make queryOnce server aggregates match TanStack DB experimental_queryOnce returned PostgREST's aggregate row as-is, so its result depended on the route: SQL returns a row for an empty match, a null sum, and an average over non-null values, while TanStack DB returns no row, sums a null as 0, and averages over every row. min and max compared text by collation and ignored parse conversions, and paging or an unpushable filter changed the outcome. The server path now takes only count, sum, and avg of plain columns, with every filter pushable and no paging, ordering, or distinct. It requests a hidden row count and each average as a sum, and maps the result to TanStack DB's rules. Every other query runs through TanStack DB's queryOnce. - Law: experimental_queryOnce resolves to TanStack DB's queryOnce result over the same table state (IFCS-154). Rows are compared on the select's aliases (maintainer decision, 2026-11-11). - Reach (fixed seed 20261022, 40 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 (port, 173400d9b): rows [], sum(id): expected [ { sum_id_0: null } ] to strictly equal []. - GREEN: SUPABASE_CLI="pnpm dlx supabase@2.116.0" pnpm test:e2e passes 161 tests (1 skipped). - Mutants, each rejected by an assertion: SQL row on empty input, null sum, SQL avg, min/max pushed, no pushability check, sum over a parsed column, paging pushed, subquery filters dropped. - Limits: min/max are generated only over non-text columns, because TanStack DB's own result over text with nulls depends on row order (recorded in the reusable-law backlog); one local stack and table. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/contributing/oracle-coverage.md | 13 + .../query-once-aggregate-oracle.e2e.test.ts | 286 +++++++++++++----- packages/supabase-db-collection/src/db.ts | 23 +- .../src/postgrest-filters/common.ts | 47 ++- .../src/postgrest-filters/index.ts | 3 +- .../postgrest-filters/query-ir-to-search.ts | 20 +- .../supabase-db-collection/src/query-once.ts | 192 +++++++++--- .../supabase-db-collection/src/serialize.ts | 12 +- .../00000000000002_query_once_aggregates.sql | 11 +- .../tests/query-once.test.ts | 173 +++++++---- .../tests/serialize.test.ts | 4 +- 11 files changed, 544 insertions(+), 240 deletions(-) diff --git a/docs/contributing/oracle-coverage.md b/docs/contributing/oracle-coverage.md index ac25c6ee17..c09e253c49 100644 --- a/docs/contributing/oracle-coverage.md +++ b/docs/contributing/oracle-coverage.md @@ -2090,6 +2090,7 @@ generic visitor behavior outside the named collectors. | Offline execution | [scheduler](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/KeyScheduler-oracle.property.test.ts), [leadership](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/leadership-replay-oracle.property.test.ts), [settlement](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/transaction-settlement-oracle.property.test.ts), [serialization](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/transaction-serializer-oracle.property.test.ts), [web connectivity replay](https://github.com/TanStack/db/blob/main/packages/offline-transactions/tests/connectivity-replay-oracle.test.ts), [review record](oracle-reviews/pr-1879-visible-replay.md) | Declarative FIFO eligibility, per-transaction outcomes, durable state and typed wire trees. The web connectivity owner checks a persisted write under a false browser online hint, then visible replay by event or explicit retry, at provider-call, outbox, and caller-settlement cuts. It uses controlled browser globals and fake storage; it does not prove actual browser network detection, genuine offline retry timing, multi-tab leadership transfer, or React Native behavior. Issued work may finish after ownership loss, but new work must not start. Exactly-once network execution is not promised. | | Frameworks | [React conformance](https://github.com/TanStack/db/blob/main/packages/react-db/tests/conformance.test.tsx), [React pagination](https://github.com/TanStack/db/blob/main/packages/react-db/tests/infinite-query-conformance.test.tsx), [shared framework contracts](https://github.com/TanStack/db/tree/main/packages/db/tests/conformance), [Vue synchronous publication](https://github.com/TanStack/db/blob/main/packages/vue-db/tests/useLiveQuery-publication-oracle.test.ts), [Preact conformance](https://github.com/TanStack/db/blob/main/packages/preact-db/tests/conformance.test.ts), [Preact binding witnesses](https://github.com/TanStack/db/blob/main/packages/preact-db/tests/useLiveQuery.test.ts) | Exact exposed rows/pages and each framework's own lifecycle cuts. Vue's synchronous watcher checks insert, update, and nonterminal delete through supplied Collection and identity query inputs; it does not cover an empty final result, multiple changes in one transaction, or query recompilation. A React witness does not prove Preact/Vue/Solid/Angular/Svelte scheduling. Preserve their receiving registrations. The Preact driver observes each result at commit through a layout-effect probe under an error boundary, because Preact runs passive effects after paint and `act` drains only those it scheduled; it has no Suspense, server-snapshot, or DbClient witness. Its binding witnesses check that a write between render and subscription publishes and that an equal `queryKey` or structurally equal query keeps its live-query Collection. Subscribing in a passive effect instead of a layout effect survives both, as allowed scheduling freedom. The query-identity laws (1.0, maintainer decisions 2026-10-22 and 2026-10-23) run through every live-query driver and the React, Preact, Vue, and Svelte infinite drivers, branching on each driver's public `comparesQueryIdentity` policy. In a binding that compares identity (React and Preact), a query without a nonempty `queryKey` whose IR has no stable hash throws `UnhashableQueryIRError` at mount and at recompilation; an empty key counts as none, and a nonempty key runs the query. React no longer accepts dependency arrays. Such a binding claims each source Collection ID it compiled, so A(x) -> C(y) -> A(x) is legal while a later B(x) throws `SourceCollectionIdReuseError`. A pairwise model judges 32 enumerated histories over A(x), B(x), C(y), and a disabled step, with declared reach for a swap after an intervening query, a swap after a disabled step, and a revisit after an intervening query. Reach labels name the steps between the claim and its test, so a direct swap does not count; removing the C(y) step fails reach. Claims that keep only the latest query, or reset at a disabled step, fail it. React retains two shared-suite registrations, but both now call the same derived-identity API; the registration still named `react (dependency list)` does not establish a second production path. The earlier five failures from skipping a dependency-list check at first compile were evidence for the removed API. A nonempty `queryKey` skips the claim: React and Preact witnesses swap a same-ID source under a changed key, and a key reader that ignores keys fails both. One query over two same-ID objects uses overlapping but different rows; an engine mutant that resolves each source through the Collection-ID map, so the last object serves both join sides, fails the live and infinite scenarios. A Svelte hydration witness checks that a `DbClient`-backed query with a dependency list hydrates `queryKey: []` exactly as it hydrates an omitted key. The infinite suite runs the same pairwise grammar over A(x), B(x), and C(y), 18 histories with declared reach for a swap and a revisit after an intervening query; it has no disabled or page-shape step, because one infinite handle changes either its query or its page shape. A new binding starts unclaimed. The former React dependency-list/`DbClient` witness is historical; it does not establish current reuse or hydration behavior. The shared conformance rejection scenarios currently check that, after a rejected rerender, two reads each throw or hold no rows. Reactive drivers accept an unhashable query, as described below. React unmounts a tree whose render throws. Preact keeps such a component mounted, so its driver mounts the hook under an error boundary, which unmounts it; a Preact component with no boundary keeps its last committed rows and is not witnessed here. It guards a future driver whose binding stays mounted; the `DbClient`-backed Svelte binding, which stays mounted, is checked field by field in fixed [descriptor release tests](https://github.com/TanStack/db/blob/main/packages/svelte-db/tests/descriptor-query-release.svelte.test.ts) (no oracle owner; tracked in #2264). A reactive binding (Vue, Solid, Angular, Svelte without a `DbClient`) runs the same histories and must publish the current input's rows: the unhashable query runs and recompiles when a captured value changes, and B(x) shows B's rows, never A's. One query over two same-ID objects is likewise rejected by a comparing binding and read through an inner join by a reactive one. The same mount-and-recompile split is not yet generated for `DbClient`-backed Svelte or React hooks beyond the receiving witnesses below. The [React source ID reuse oracle](https://github.com/TanStack/db/blob/main/packages/react-db/tests/source-id-reuse-oracle.test.tsx) owns the release law for `DbClient` descriptors: a rejected query releases every sync start it deferred. React exercises applicable causes (source-ID collision, unhashable IR, a descriptor factory that throws, a query rejected during compilation, a single-result infinite query, and a render abandoned by a sibling throw or suspension) through live, infinite, and Suspense hooks with derived identity or changed explicit `queryKey`, plus ordinary-hook configurations that disable reclamation, at initial mounts or rerenders and through four readers. Explicit keys bypass source-ID and derived-IR rejection; single-result rejection applies only to infinite hooks, and abandoned-after-hook histories exclude Suspense because its preload already starts the sources. Svelte crosses collision, unhashable, factory, compile, and abandoned-setup causes with eager and lazy sources and three readers, and its collision history reads every public result field separately after the rejection; dropping the guard from one getter, such as `isLoadingError`, fails all six collision cells. The earlier dependency-list Suspense cache-claim failures are historical. Current ordinary [source-ID tests](https://github.com/TanStack/db/blob/main/packages/react-db/tests/source-id-reuse.test.tsx) check separate client-scoped Suspense hooks and an initial suspended retry with different same-ID sources; they use the current derived-identity API. These fixed histories are supplemental tests, not a dimension of the claim grammar: that grammar's disabled step has no Suspense form, because `useLiveSuspenseQuery` rejects a disabled query. React ordinary/infinite hooks and Svelte's compiled query release at their render boundaries. The current React Suspense rejection histories fail within its shared ordinary-hook preparation; removing only the outer Suspense wrapper's catch is an unreached mutant, not a demonstrated kill. The former dependency-array SSR history was removed because its API is absent from the RC; it had executed no cells in the preceding grammar. Routing Svelte's getters around the compiled query fails its collision cells; `preload()` overrides a deferral, so those cells pass without the release by design. Declared reach: each enumerated release history asserts that the rejected query ran the shared descriptor's factory once before the reader, and a history that binds the failing descriptor first fails that check. A render that never commits (React: a sibling throws after the hook returns, or the render suspends; Svelte: setup throws after the hook returns) releases its deferral when garbage collection reclaims the live query it built (maintainer decision 2026-10-23), or after the unsubscribed GC floor when the hook's config disables that reclaim (`gcTime` 0 or `Infinity`, or `startSync: false`); both release grammars add these causes, React adds the three config paths and Svelte a `gcTime: 0` setup, and waiting only for the reclaim fails those cells; removing the reclaim release fails exactly them, and releasing at the end of render instead fails the descriptor binding owner's no-work-before-commit law. Known limit, owner the maintainer: the reclaim follows the 50 ms unsubscribed GC floor, so a render whose commit React holds past that floor releases its deferral, and its source may start, before it commits; that render then subscribes to a cleaned-up live query, which restarts. No history holds a commit past the floor, which needs a controlled React scheduler or fake timers; this joins the existing held-commit open cell in the infinite-query publication row. A keyed step records no claim and checks none (maintainer decision 2026-10-23): for a comparing binding the claim grammar adds keyed steps AK and BK over the same-ID objects, 108 histories with declared reach for a claim that crosses a keyed step and a keyed step after a claim; a keyed step that claims, or that resets earlier claims, fails it for the current React derived-identity path and for Preact. Each controllable driver records a publication log (`publication-log.ts`) at the end of each synchronous turn, plus the value on screen at the first paint after each `setParam`, once the framework has flushed and before any later task (maintainer decision 2026-10-23). After a same-ID swap, a reactive binding's every logged value holds only the new source's rows or none: a binding that keeps the old rows published until a later task fails it in Vue and Svelte. A value replaced within one synchronous turn is not logged, because the browser never paints it; Solid and Svelte publish the previous query's rows once inside the swap's own turn, for any input change, and pass. Accepted design (maintainer decision 2026-10-23): React claims source IDs during render, so a concurrent render that is abandoned before commit keeps its claim, as the React oracle states for a render that suspends, because that render's live query may still own the source until cleanup. Same-ID source objects stay legal; the claim, not `createCollection`, rejects a swap. Trace: committed C(y); a transition render reads B(x) and is interrupted; an urgent render reads A(x) and throws `SourceCollectionIdReuseError`. The abandoned-transition history has no witness. Adapter-specific `queryKey` change semantics stay with each adapter's own tests; React's infinite hook also has a focused witness that a `queryKey` array changed in place recompiles, because only React hands the caller's array to the shared window binding. The shared lifecycle histories distinguish adapter-created projections from caller-owned retention: omitted and explicitly `undefined` `gcTime` use the 1 ms adapter policy; `gcTime: 0`, a positive 100 ms retention, and supplied Collections keep caller authority. They observe retirement after unmount, replacement, disabling, and positive expiry, plus survival before that expiry. The shared suite also checks initial-query readiness over a lagging on-demand source, for a list and a `findOne` query and for the infinite query (React, Preact, Vue, and Svelte): not ready before the subset settles, ready at settlement while the source is still `loading`, and still ready after the source becomes ready. Solid's Suspense over that source has its own witness. A Solid Suspense witness also checks that a source's `reportError()` and `fail()` after readiness keep the boundary's rows shown and the query `ready`; a hook whose status follows the health tree fails it. A resource that suspends again on a tree change is not observable at that cut, because its refetch over a ready query settles before a fallback renders. A separate Solid two-resource Suspense witness holds one ready projection past the 50 ms unsubscribed floor while its sibling remains pending, then checks both commit and boundary abandonment release the temporary preload owner and preserve ordinary 1 ms teardown. | | Backend Collection E2E | [shared provider suites](https://github.com/TanStack/db/tree/main/packages/db-collection-e2e/src/suites); [Electric registration](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/e2e/electric.e2e.test.ts); [Query registration](https://github.com/TanStack/db/blob/main/packages/query-db-collection/e2e/query.e2e.test.ts); [TrailBase registration](https://github.com/TanStack/db/blob/main/packages/trailbase-db-collection/e2e/trailbase.e2e.test.ts); [Supabase registration](https://github.com/TanStack/db/blob/main/packages/supabase-db-collection/e2e/supabase.e2e.test.ts) | Electric, Query, TrailBase, and Supabase register reusable predicate, pagination, join, and live-update checks at their provider boundaries; Electric also registers the move suite. Supabase runs against a local Supabase stack (PostgREST and Realtime) and skips `should maintain query state during data changes`: local Realtime adds about 500 ms per change, so the case outlives the five-second cleanup of a live query without subscribers. These are receiving paths for core query and Collection laws, not framework render cuts. | +| Supabase `experimental_queryOnce` server aggregates | [server-aggregate oracle](https://github.com/TanStack/db/blob/main/packages/supabase-db-collection/e2e/query-once-aggregate-oracle.e2e.test.ts) | Differential law (IFCS-154): `experimental_queryOnce` resolves to what TanStack DB's `queryOnce` resolves to over an eager Collection of the same table. Generated histories against a local Supabase stack with PostgREST aggregates enabled vary the rows (nulls, an empty table, text, a timestamptz and two numbers stored as text read with `parse`), `count`/`sum`/`avg`/`min`/`max`, pushable and unpushable filters, a filter-only subquery source, `limit`/`offset`, and `findOne`. Reach credits the server route with an empty match, a null value, `findOne`, and a subquery source, and the TanStack DB route. The comparison projects each row to the select's aliases and drops the virtual fields `$key`, `$origin`, `$hasPendingWrites`, and `$collectionId` (maintainer decision, Ivan Vasilov, 2026-11-11): they describe the temporary live-query Collection that `queryOnce` creates, which the server path does not create. Limits: `min`/`max` are generated only over columns that hold no text, because TanStack DB's own result there depends on row order (see the reusable-law backlog); values are small integers and decimals that doubles represent exactly; one local stack and one table; no grouped, joined, or computed queries. | | Window-controller overlap | [shared infinite-query conformance](https://github.com/TanStack/db/blob/main/packages/db/tests/conformance/infinite-suite-oracle.ts), [React driver](https://github.com/TanStack/db/blob/main/packages/react-db/tests/infinite-query-conformance.test.tsx), [Vue driver](https://github.com/TanStack/db/blob/main/packages/vue-db/tests/infinite-query-conformance.test.ts), [Svelte driver](https://github.com/TanStack/db/blob/main/packages/svelte-db/tests/infinite-query-conformance.svelte.test.ts), [Preact driver](https://github.com/TanStack/db/blob/main/packages/preact-db/tests/infinite-query-conformance.test.ts), [review record](oracle-reviews/dec-03-window-overlap.md) | Four or five ordered source rows, two window-settlement orders, and public snapshots after each settlement, a subscribed observer update, a detached controller read, and explicit recovery. Insertion and removal of the fifth row distinguish both continuation directions while an earlier error remains visible. The detached read follows a source change with no controller subscriber; its preloaded Collection retains the five-row window. The exact overlap uses the exported DB controller in each package realm. Framework hooks expose no controller preload, so this cell does not establish a hook scheduling path; direct hook paging remains in the adjacent shared scenarios. An unsubscribed controller has no notification claim. | | Infinite-query publication | [shared publication laws](https://github.com/TanStack/db/blob/main/packages/db/tests/conformance/infinite-suite-oracle.ts), [React render cuts](https://github.com/TanStack/db/blob/main/packages/react-db/tests/infinite-query-render-cuts-oracle.test.tsx), [Svelte hook tests](https://github.com/TanStack/db/blob/main/packages/svelte-db/tests/useLiveInfiniteQuery.svelte.test.ts), [review record](oracle-reviews/2026-10-05-infinite-first-paint.md) | Each driver records every value its framework published: React layout commits, Vue pre-flushes, and the Svelte construction value plus pre-effect runs. The shared suite checks that a synchronous source shows its ready first page on the first value, for a query callback and for a supplied collection that has not started, that every ready value in a fixed-source, fixed-query scenario equals the source prefix for its own page count, including an equal dependency replacement that keeps page depth, and that a mount requests an on-demand first window once, for a query callback and for a supplied collection whose finite window is wider than or equal to the one the hook needs, judged by the rows the on-demand source holds after mount. Under deferred acquisition, an on-demand first value is either the ready first page or a value with no rows, by framework: React and Svelte publish before the hook subscribes, Vue after. `preloaded-collection-first-paint` checks the documented route-loader pattern: a limited live query preloaded before mount shows its ready first page on the first value in every framework and asks the source for nothing more; a preload that does not count as demand never settles there. Pre-commit work has no shared form, because Vue setup is its commit. The React driver owns renders that never commit, StrictMode double renders (one first-window request on React 19), retries after GC, a mounted replacement whose startup error must reach the error boundary, and a collection kept from an abandoned render that enters terminal error before its query is selected again, each as under `useLiveQuery`. The React source ID reuse oracle drives the infinite hook too. Svelte owns construction and superseded recomputes before the subscribing effect. In both, the hook acquires an on-demand source as often as `useLiveQuery` does under the same history, for either input form, direct or behind a live-query Collection. On-demand requests from renders that never commit are now owned by the live-query deferred acquisition oracle; the React render-cut oracle checks that an abandoned render makes no acquisition. Open cells, owned here: React 18 StrictMode, where neither hook keeps refs across the double render; a React commit held after the 50 ms unsubscribed GC floor, where a controlled-premise controller witness shows no non-ready value but no React scheduling witness exists; ready values in scenarios that write the source or replace the query, which need a per-step source model; a join of eager and on-demand sources, which needs a zero-acquisition check before commit; a supplied collection with no `.limit`, which sends one unbounded request on `main` too, because the controller cannot narrow it before the source request; and Svelte `state_unsafe_mutation` when a start inside `$derived.by` synchronously writes rows a peer is waiting for, shared with Svelte's `useLiveQuery`, which a two-component probe reproduces and the deferred-acquisition follow-up removes. | | Structural values and ordered primitives | [hash values](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/hash-oracle.property.test.ts), [hash identity](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/hash-identity-oracle.property.test.ts), [MultiSet consolidation](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/multiset-consolidate-oracle.property.test.ts), [hash graphs](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/hash-graph-oracle.property.test.ts), [mixed hash graphs](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/hash-mixed-graph-oracle.property.test.ts), [hash retry](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/hash-failure-retry-oracle.property.test.ts), [murmur stream](https://github.com/TanStack/db/blob/main/packages/db-ivm/tests/murmur-stream-oracle.property.test.ts), [comparison](https://github.com/TanStack/db/blob/main/packages/db/tests/comparison-oracle.property.test.ts), [deep equality](https://github.com/TanStack/db/blob/main/packages/db/tests/utils-oracle.property.test.ts), [cursor](https://github.com/TanStack/db/blob/main/packages/db/tests/cursor-oracle.property.test.ts), [indexes](https://github.com/TanStack/db/blob/main/packages/db/tests/index-update-oracle.property.test.ts), [BTree Map](https://github.com/TanStack/db/blob/main/packages/db/tests/btree-map-oracle.test.ts), [query identity](https://github.com/TanStack/db/blob/main/packages/db/tests/query/identity-output-shape-oracle.test.ts), [LIKE semantics](https://github.com/TanStack/db/blob/main/packages/db/tests/query/compiler/evaluators-oracle.test.ts) | Independent flat values, graph topology, algebraic laws, structural object keys in code-unit order (the flat-value, identity and consolidation grammars include keys that tie under locale collation), murmur byte framing against a byte-at-a-time reference (block mixing, the finalizer and symbol framing have no owner there), Map/group/sort recomputation, expression denotation, custom comparator dispatch/reference identity/index compatibility, LIKE wildcard refinement, compiled output bags, declared value-pair agreement between D2 equality keys and IR equality operands, and Collection collation with exact public scan/index order and one-index reuse across repeated reads. The auto-index cells cross BasicIndex and BTreeIndex; scan cells omit indexes. Both paths cover lexical and numeric `en-US` locale defaults plus an explicit ordinary locale override of a numeric default. An unindexed six-row work cell bounds Collection collation resolution to at most two reads per ordered scan: one index-path check and one scan clause. Other locales and ordered histories are outside this owner. The identity pair grammar covers primitives, signed zero, NaN/invalid Date, valid Date/timestamp, binary/Buffer, Temporal, nested references, symbols, and functions; fixed and sampled pairs do not prove every JavaScript value or hash collision freedom. Ref proxies are expressions rather than literal values in this lane. The utility owner additionally generates widths 6–12 of ambiguous object-valued Sets. An independent count/capacity model judges equal reordered bags, late unmatched prototypes, multiplicity deficits, and a generic plain/class bridge that needs reassignment. Row comparison requires exact shape/value counts; generic equality permits keyed class/plain/null bridges. General and row comparison paths run in both directions, with acyclic members or links back to the Set. Separate cubic scalar-field-read and scoped native Map/Set-operation ceilings reject repeated-comparison and cached-candidate factorial searches without a timing assertion. Empty and singleton neighbors use the same model. Thirteen declared states each reach 200 histories. A paired-input lane adds widths 1,024–3,072, distinct/interchangeable members, and root-linked cycles. Its eight states each reach 20 histories; linear scalar-read and native-operation ceilings protect this equal corresponding-member family. Arbitrary unordered inputs retain the polynomial fallback; arbitrary graph topology and nested-value cost remain outside these bounded work laws. The deep-equality owner also pins that `deepEquals` ignores Map and Set insertion order, RegExp `lastIndex`, array holes, and typed-array class, the rules draft equality keeps. It also pins that `sameRowValue` preserves record prototypes (maintainer decision 2026-11-03), while exported `deepEquals` retains its established keyed-class/plain/null/cross-realm bridge, that a class instance without enumerable keys equals only itself, that URLs compare by `href`, and that typed-array elements compare like numbers. The hash-values owner checks equal-hash consequences for independently constructed flat values. Distinct type identities are checked by the hash-identity owner through `equalHashValues`, including forced digest collisions; distinct 32-bit digests are not promised. The hash-identity owner checks `hash` and `equalHashValues` against one spec-level identity model: primitives with signed zero, NaN, and bigint; reference leaves (functions, registered handles, `File`, binary over 128 bytes); Date, binary, Temporal, and RegExp headers; array length and holes; Map and Set insertion order; and object keys in any order, for acyclic values and for cycles through arrays, Map values, Sets, and plain objects. Map/Set order sensitivity is pinned current behavior, not a promise. Arrays from another realm, RegExps with a `NaN` `lastIndex`, getters, proxies, other cycle carriers, and pairs that differ only in a back-edge target are outside its grammar; pinned cases keep equality's cross-realm length check and strict RegExp field comparison. `hash-work.test.ts` pins how visited values and array/RegExp headers count toward the structural work cap, and that equality copies a shared Map's entries once per distinct pair ([code-weight hash dispatch review](oracle-reviews/code-weight-hash-dispatch.md)). Custom string indexes do not optimize ordinary ranges, and custom cursors remain unsupported. The LIKE owner covers boolean string matching and bounded work, not nullish three-valued logic or a general Unicode collation contract. Unsupported composite cursors reject. The MultiSet consolidation owner checks keyed, single-type, and structural identity, signed zero and NaN in keyed and single-number data, the retained first record, zero-sum removal, and input record contents. It does not assert output order. Its keyed grammar includes cross-type key and value collisions, non-finite numeric keys, the `\|` delimiter, symbol and function identity, and a direct-object/object-tuple delimiter control from #1948. Eight named collision witnesses and both generated campaigns are RED on `c879ba6d` and GREEN with the repair ([#1948 review record](oracle-reviews/issue-1948-keyed-consolidation.md)); the [code-weight consolidation review](oracle-reviews/code-weight-multiset-consolidation.md) records the earlier exclusion. The keyed reference uses direct value/reference equality, including SameValueZero for numeric keys. The unkeyed fallback keeps its original key and value domains. The direct `MultiSet` owner does not prove which `@tanstack/db` query shapes produce primitive keyed values or mixed-type source keys; that needs a live-query production witness. The index owner enforces one invalid-comparator law across both BasicIndex and BTreeIndex: for each comparator, accepted numeric prefix (including the empty prefix), and probe operation (add, update, eq/range lookup, take, build), the operation throws exactly when it receives a `NaN` or non-number result and never when every comparison is valid. A `signed infinity` comparator is the valid control, and a custom collation `compare` supplied through `compareOptions` is checked the same way. Two BTree Map split histories check inserted-key reads, exact whole-range payloads/order, size, and extrema, proving split placement follows the insertion index without a post-mutation comparison. A rejected index add or remove leaves the index refining its accepted rows; update and build are not atomic. At the Collection boundary, both index types and both write paths (optimistic insert, sync commit) crash the collection: status becomes `error` and the next mutation throws, so a usable collection never holds rows its subscribers were not told about. Open: a sync source can still commit writes on a collection in `error` state, which stores unpublished rows; this is existing `markError` behavior and needs a lifecycle-owner witness. Comparator transitivity is outside this evidence. | @@ -4325,6 +4326,18 @@ boundary. Track the generalized repairs here instead of accumulating isolated regressions. Completion requires an executable owner, a production-path witness, a hostile wrong-answer control, and an explicit statement of remaining limits. +- [ ] **Order-dependent `min`/`max` over text with nulls.** TanStack DB maps + a null to `0` before `min` and `max` compare values with `<`, and + JavaScript orders text and `0` inconsistently (`'a' < 0` and `0 < 'a'` + are both false). Over labels `'a'`, `null`, `null` an ungrouped + `min(label)` returns `'a'` or `0` depending on the order in which rows + reach the reduction. The Supabase server-aggregate oracle found it on + November 11: the same query over an on-demand and an eager Collection of + the same table disagreed. Owner: Aggregate selects + (`packages/db/tests/query/aggregate-select-oracle.property.test.ts`). + Needed witness: `min`/`max` over a text column with nulls, compared + across two arrival orders of the same rows. The Supabase oracle generates + `min`/`max` only over columns that hold no text until this is decided. - [ ] **Unchanged `NaN` keys at optimistic mutation admission.** With an eager Collection keyed by `row.id`, preload a row whose `id` is `NaN`, then call `update(NaN, row => { row.label = "held" })`. Admission throws diff --git a/packages/supabase-db-collection/e2e/query-once-aggregate-oracle.e2e.test.ts b/packages/supabase-db-collection/e2e/query-once-aggregate-oracle.e2e.test.ts index ead31101da..e0f885cdb1 100644 --- a/packages/supabase-db-collection/e2e/query-once-aggregate-oracle.e2e.test.ts +++ b/packages/supabase-db-collection/e2e/query-once-aggregate-oracle.e2e.test.ts @@ -15,15 +15,21 @@ * * - empty and all-null inputs, where SQL aggregates return `null` or `0`; * - columns the collection reads through `parse`, which PostgREST never sees; - * - text ordering for `min`/`max`, which Postgres decides by collation; + * - `min`/`max`, which TanStack DB computes with JavaScript comparisons; * - `limit`, `offset`, and `findOne` on the single aggregate row; + * - a filter PostgREST cannot express, such as `eq(upper(label), 'A')`; * - a filter-only subquery source, whose `where` is pushed down too. * - * Limits: one local Supabase stack (PostgREST with `db_aggregates_enabled`), - * one table, and the aggregates `count`, `sum`, `avg`, `min`, and `max`. - * Grouped, joined, and computed queries take TanStack DB's path on both sides; - * this oracle generates none of them, so it says nothing about them. The - * comparison is exact: it does not round averages. + * Limits: + * + * - one local Supabase stack (PostgREST with `db_aggregates_enabled`) and one + * table; + * - the aggregates `count`, `sum`, `avg`, `min`, and `max`, with `min` and + * `max` only over columns that hold no text (see ORDERABLE_COLUMNS); + * - small integers and decimals that doubles represent exactly, so the + * comparison is exact and does not round averages; + * - no grouped, joined, or computed queries. Those take TanStack DB's path on + * both sides, so this oracle says nothing about them. */ import { createClient } from '@supabase/supabase-js' import { @@ -41,6 +47,7 @@ import { or, queryOnce, sum, + upper, } from '@tanstack/db' import { QueryClient } from '@tanstack/query-core' import fc from 'fast-check' @@ -64,16 +71,34 @@ import type { InitialQueryBuilder } from '@tanstack/db' // differently; // - `recorded_at` is a timestamptz, read into a `Date` with `parse`; // - `big_count` is a bigint stored as text and read with `parse`, so `10` -// orders after `9` in the collection but before it in Postgres. +// orders after `9` in the collection but before it in Postgres; +// - `amount` is a decimal stored as text and read with `parse`, so the +// collection can sum it while Postgres cannot sum text. // // Only aggregate-only selects over the `query_once_rows` table are generated, // so every query is one the server path accepts. Illegal histories (a // duplicate id, `sum` over text) are not generated. -const COLUMNS = [`id`, `score`, `label`, `recorded_at`, `big_count`] as const +const COLUMNS = [ + `id`, + `score`, + `label`, + `recorded_at`, + `big_count`, + `amount`, +] as const type Column = (typeof COLUMNS)[number] -const NUMERIC_COLUMNS = [`id`, `score`] as const -const CONVERTED_COLUMNS: ReadonlyArray = [`recorded_at`, `big_count`] +// TanStack DB orders a null as 0 in `min` and `max`, and JavaScript compares +// text with 0 inconsistently (`'a' < 0` and `0 < 'a'` are both false), so its +// result over a text column with nulls depends on row order. That is a +// @tanstack/db defect recorded in docs/contributing/oracle-coverage.md, so +// `min` and `max` are generated only over columns that hold no text. +const ORDERABLE_COLUMNS = COLUMNS.filter((column) => column !== `label`) +const CONVERTED_COLUMNS: ReadonlyArray = [ + `recorded_at`, + `big_count`, + `amount`, +] interface SeedRow { id: number @@ -81,15 +106,17 @@ interface SeedRow { label: string | null recorded_at: string | null big_count: string | null + amount: string | null } type Aggregate = | { fn: `count` | `min` | `max`; column: Column } - | { fn: `sum` | `avg`; column: (typeof NUMERIC_COLUMNS)[number] } + | { fn: `sum` | `avg`; column: `id` | `score` | `amount` } type Filter = | { kind: `gt`; value: number } | { kind: `eq`; value: string } + | { kind: `upper`; value: string } | { kind: `isNull`; column: Column } | { kind: `in`; ids: Array } | { kind: `not`; inner: Filter } @@ -106,14 +133,16 @@ interface AggregateQuery { } const seedRows = fc - .uniqueArray(fc.integer({ min: 1, max: 12 }), { maxLength: 6 }) + .uniqueArray(fc.integer({ min: 1, max: 12 }), { maxLength: 8 }) .chain((ids) => fc.tuple( ...ids.map((id) => fc.record({ id: fc.constant(id), - score: fc.option(fc.integer({ min: -3, max: 3 })), - label: fc.option(fc.constantFrom(`a`, `A`, `b`, `B`, ``, `a b`)), + score: fc.option(fc.integer({ min: -3, max: 3 }), { freq: 2 }), + label: fc.option(fc.constantFrom(`a`, `A`, `b`, `B`, ``, `a b`), { + freq: 2, + }), recorded_at: fc.option( fc.constantFrom( `2026-01-01T00:00:00+00:00`, @@ -124,61 +153,125 @@ const seedRows = fc big_count: fc.option( fc.constantFrom(`9`, `10`, `-1`, `9007199254740993`), ), + amount: fc.option(fc.constantFrom(`1.5`, `2`, `-0.25`)), }), ), ), ) +// Weights keep most queries on the server path (count, sum, and avg with +// pushable filters and no paging), while every other branch still appears in +// each campaign. Reach below counts both. const aggregate: fc.Arbitrary = fc.oneof( - fc.record({ - fn: fc.constantFrom(`count` as const, `min` as const, `max` as const), - column: fc.constantFrom(...COLUMNS), - }), - fc.record({ - fn: fc.constantFrom(`sum` as const, `avg` as const), - column: fc.constantFrom(...NUMERIC_COLUMNS), - }), + { + weight: 2, + arbitrary: fc.record({ + fn: fc.constant(`count` as const), + column: fc.constantFrom(...COLUMNS), + }), + }, + { + weight: 3, + arbitrary: fc.record({ + fn: fc.constantFrom(`sum` as const, `avg` as const), + // `score` is the nullable plain column, so it carries the null rules. + column: fc.oneof( + { weight: 2, arbitrary: fc.constant(`score` as const) }, + { + weight: 1, + arbitrary: fc.constantFrom(`id` as const, `amount` as const), + }, + ), + }), + }, + { + weight: 1, + arbitrary: fc.record({ + fn: fc.constantFrom(`min` as const, `max` as const), + column: fc.constantFrom(...ORDERABLE_COLUMNS), + }), + }, ) const filter: fc.Arbitrary = fc.letrec<{ filter: Filter }>((tie) => ({ filter: fc.oneof( { depthSize: `small`, withCrossShrink: true }, - fc.record({ - kind: fc.constant(`gt` as const), - value: fc.integer({ min: -3, max: 3 }), - }), - fc.record({ - kind: fc.constant(`eq` as const), - value: fc.constantFrom(`a`, `B`, ``), - }), - fc.record({ - kind: fc.constant(`isNull` as const), - column: fc.constantFrom(...COLUMNS), - }), - fc.record({ - kind: fc.constant(`in` as const), - ids: fc.uniqueArray(fc.integer({ min: 1, max: 12 }), { maxLength: 3 }), - }), - fc.record({ kind: fc.constant(`not` as const), inner: tie(`filter`) }), - fc.record({ - kind: fc.constantFrom(`and` as const, `or` as const), - left: tie(`filter`), - right: tie(`filter`), - }), + { + weight: 3, + arbitrary: fc.record({ + kind: fc.constant(`gt` as const), + value: fc.integer({ min: -3, max: 3 }), + }), + }, + { + weight: 3, + arbitrary: fc.record({ + kind: fc.constant(`eq` as const), + value: fc.constantFrom(`a`, `B`, ``), + }), + }, + { + weight: 3, + arbitrary: fc.record({ + kind: fc.constant(`isNull` as const), + column: fc.constantFrom(...COLUMNS), + }), + }, + { + weight: 3, + arbitrary: fc.record({ + kind: fc.constant(`in` as const), + ids: fc.uniqueArray(fc.integer({ min: 1, max: 12 }), { maxLength: 3 }), + }), + }, + { + weight: 3, + arbitrary: fc.record({ + kind: fc.constant(`not` as const), + inner: tie(`filter`), + }), + }, + { + weight: 3, + arbitrary: fc.record({ + kind: fc.constantFrom(`and` as const, `or` as const), + left: tie(`filter`), + right: tie(`filter`), + }), + }, + { + // Rarer than the pushable leaves: one unpushable leaf anywhere in a + // query sends it to TanStack DB. + weight: 1, + arbitrary: fc.record({ + kind: fc.constant(`upper` as const), + value: fc.constantFrom(`A`, `B`), + }), + }, ), })).filter -const aggregateQuery: fc.Arbitrary = fc.record( - { +/** `undefined` in three of four cases */ +const rarely = (arbitrary: fc.Arbitrary) => + fc.oneof( + { weight: 3, arbitrary: fc.constant(undefined) }, + { weight: 1, arbitrary }, + ) + +const aggregateQuery: fc.Arbitrary = fc + .record({ aggregates: fc.array(aggregate, { minLength: 1, maxLength: 3 }), - where: filter, - sourceWhere: filter, - limit: fc.constantFrom(0, 1, 5), - offset: fc.constantFrom(0, 1), + where: fc.option(filter, { nil: undefined, freq: 1 }), + sourceWhere: fc.option(filter, { nil: undefined, freq: 1 }), + paging: rarely( + fc.record( + { limit: fc.constantFrom(0, 1, 5), offset: fc.constantFrom(0, 1) }, + { requiredKeys: [] }, + ), + ), findOne: fc.boolean(), - }, - { requiredKeys: [`aggregates`, `findOne`] }, -) + }) + .map(({ paging, ...query }) => ({ ...query, ...paging })) type History = typeof history extends fc.Arbitrary ? T : never @@ -206,16 +299,19 @@ const rowSchema = z.object({ label: z.string().nullable(), recorded_at: z.date().nullable(), big_count: z.bigint().nullable(), + amount: z.number().nullable(), }) const conversions = { parse: { recorded_at: (value: unknown) => new Date(value as string), big_count: (value: unknown) => BigInt(value as string), + amount: (value: unknown) => Number(value), }, serialize: { recorded_at: (value: Date) => value.toISOString(), big_count: (value: bigint) => value.toString(), + amount: (value: number) => value.toString(), }, } @@ -260,6 +356,8 @@ function where(row: RowRef, spec: Filter): ReturnType { return gt(row.score, spec.value) case `eq`: return eq(row.label, spec.value) + case `upper`: + return eq(upper(row.label), spec.value) case `isNull`: return isNull(row[spec.column]) case `in`: @@ -383,27 +481,54 @@ declareOracle({ check: [expectSameOutcome], grammar: [history] }) // ── Reach ─────────────────────────────────────────────────────────── // -// Each state is credited from an observation, not from the generated intent: +// Each state is credited after the comparison passed, from an observation +// rather than from the generated intent. The server-route states are the +// ones where SQL and TanStack DB aggregates differ, so the server path must +// translate: // // - `server-route`: production sent an aggregate select to PostgREST; -// - `empty-match`: the reference matched no rows; -// - `null-only-column`: an aggregated column is null in every matched row; +// - `server-empty-match`: that query matched no rows, where SQL still +// returns one aggregate row; +// - `server-null-value`: an aggregated column held a null in a matched row, +// which SQL skips and TanStack DB counts as 0; +// - `server-find-one`: that query used `findOne`; +// - `server-subquery-source`: that query read a filter-only subquery, whose +// filter PostgREST applies too. +// +// The other states witness queries the server path must leave to TanStack DB: +// +// - `client-route`: production sent no aggregate select; // - `converted-column`: an aggregate reads a parsed column with values; // - `limit-or-offset`: the query set `limit` or `offset`; -// - `find-one`: the query used `findOne`; -// - `subquery-source`: the query read a filter-only subquery. +// - `unpushable-filter`: a filter used `upper`, which PostgREST cannot apply. const REACH_STATES = [ `server-route`, - `empty-match`, - `null-only-column`, + `server-empty-match`, + `server-null-value`, + `server-find-one`, + `server-subquery-source`, + `client-route`, `converted-column`, `limit-or-offset`, - `find-one`, - `subquery-source`, + `unpushable-filter`, ] as const type ReachState = (typeof REACH_STATES)[number] +const usesUpper = (spec: Filter | undefined): boolean => { + switch (spec?.kind) { + case `upper`: + return true + case `not`: + return usesUpper(spec.inner) + case `and`: + case `or`: + return usesUpper(spec.left) || usesUpper(spec.right) + default: + return false + } +} + const isAggregateSelect = (url: URL) => /\.(count|sum|avg|min|max)\(\)/.test(url.searchParams.get(`select`) ?? ``) @@ -465,25 +590,34 @@ async function runHistory( ) expectSameOutcome(actual, expected, spec.aggregates.map(aliasOf), label) - if (production.requests.some(isAggregateSelect)) reached(`server-route`) const matched: Array> = await queryOnce((q) => filteredRows(q, reference.collection, spec), ) - if (matched.length === 0) reached(`empty-match`) - for (const { column } of spec.aggregates) { - const values = matched.map((row) => row[column]) - if (values.length > 0 && values.every((value) => value === null)) - reached(`null-only-column`) - if ( - CONVERTED_COLUMNS.includes(column) && - values.some((value) => value !== null) - ) - reached(`converted-column`) + const aggregated = spec.aggregates.map(({ column }) => + matched.map((row) => row[column]), + ) + if (production.requests.some(isAggregateSelect)) { + reached(`server-route`) + if (matched.length === 0) reached(`server-empty-match`) + if (aggregated.some((values) => values.includes(null))) + reached(`server-null-value`) + if (spec.findOne) reached(`server-find-one`) + if (spec.sourceWhere !== undefined) reached(`server-subquery-source`) + } else { + reached(`client-route`) } + if ( + spec.aggregates.some( + ({ column }, position) => + CONVERTED_COLUMNS.includes(column) && + aggregated[position]!.some((value) => value !== null), + ) + ) + reached(`converted-column`) if (spec.limit !== undefined || spec.offset !== undefined) reached(`limit-or-offset`) - if (spec.findOne) reached(`find-one`) - if (spec.sourceWhere !== undefined) reached(`subquery-source`) + if ([spec.where, spec.sourceWhere].some(usesUpper)) + reached(`unpushable-filter`) } }, () => production.collection.cleanup(), @@ -501,7 +635,7 @@ it(`experimental_queryOnce matches TanStack DB's queryOnce for generated aggrega reach.beginHistory() await runHistory(generated, (state) => reach.reach(state)) }), - { numRuns: oracleRuns(25), ...parameters }, + { numRuns: oracleRuns(40), ...parameters }, ) }, ) diff --git a/packages/supabase-db-collection/src/db.ts b/packages/supabase-db-collection/src/db.ts index 2e13ba9e15..b1b75f207b 100644 --- a/packages/supabase-db-collection/src/db.ts +++ b/packages/supabase-db-collection/src/db.ts @@ -121,17 +121,22 @@ const registerTable = ( /** * Options key marking a collection created by this package, so queryOnce can - * tell a collection backed by a Supabase table from any other collection. + * tell a collection backed by a Supabase table from any other collection. Its + * value is the collection's `parse` conversions. */ const supabaseCollection = Symbol(`supabaseCollection`) -/** Whether this package created `collection`, so it reads a Supabase table */ -export function isSupabaseCollection(collection: CollectionImpl): boolean { - return ( - (collection.config as { [supabaseCollection]?: boolean })[ - supabaseCollection - ] === true - ) +/** + * The columns a collection created by this package reads through `parse`, or + * `null` for any other collection, which has no Supabase table behind it. + */ +export function parsedColumns(collection: CollectionImpl): Set | null { + const parse = ( + collection.config as { + [supabaseCollection]?: ColumnConversions[`parse`] + } + )[supabaseCollection] + return parse ? new Set(Object.keys(parse)) : null } const createSupabaseConfig = ( @@ -208,7 +213,7 @@ const createSupabaseConfig = ( return { ...config, - [supabaseCollection]: true, + [supabaseCollection]: conversions.parse ?? {}, sync: { // Keeps the hooks query-db-collection attaches to its sync config, such // as the factory that lets a direct write start an idle collection. diff --git a/packages/supabase-db-collection/src/postgrest-filters/common.ts b/packages/supabase-db-collection/src/postgrest-filters/common.ts index a26683dc53..56461d13df 100644 --- a/packages/supabase-db-collection/src/postgrest-filters/common.ts +++ b/packages/supabase-db-collection/src/postgrest-filters/common.ts @@ -204,6 +204,36 @@ export function mergeInFilters(filters: Array): Array { return merged } +/** One top-level conjunct as a PostgREST param, or `null` if it cannot be pushed */ +function toParam( + filter: Expression, + options: FilterOptions, +): PostgrestParam | null { + const comparison = renderComparison( + filter, + options.quoteScalars ?? false, + options, + ) + if (comparison) return { kind: 'column', ...comparison } + const embedded = toFilterString(filter, options) + if (embedded === null) return null + return { + kind: 'group', + filter: embedded.startsWith('or(') ? embedded.slice(3, -1) : embedded, + } +} + +/** + * Whether PostgREST applies every conjunct of `expr` exactly, so a result it + * computes from the matching rows needs no client-side filtering. + */ +export function isPushable( + expr: Expression, + options: FilterOptions = {}, +): boolean { + return flattenAnd(expr).every((filter) => toParam(filter, options) !== null) +} + export function toPostgrestParams( expr: Expression | undefined | null, options: FilterOptions = {}, @@ -212,21 +242,8 @@ export function toPostgrestParams( const conjuncts = flattenAnd(expr) const filters = options.mergeIn ? mergeInFilters(conjuncts) : conjuncts return filters.flatMap((filter): Array => { - const comparison = renderComparison( - filter, - options.quoteScalars ?? false, - options, - ) - if (comparison) return [{ kind: 'column', ...comparison }] - const embedded = toFilterString(filter, options) - if (embedded !== null) { - return [ - { - kind: 'group', - filter: embedded.startsWith('or(') ? embedded.slice(3, -1) : embedded, - }, - ] - } + const param = toParam(filter, options) + if (param) return [param] if (options.strict) { throw new Error( 'Cannot push WHERE expression to PostgREST; server aggregates require fully pushable filters', diff --git a/packages/supabase-db-collection/src/postgrest-filters/index.ts b/packages/supabase-db-collection/src/postgrest-filters/index.ts index 6cd6a588d5..470969824d 100644 --- a/packages/supabase-db-collection/src/postgrest-filters/index.ts +++ b/packages/supabase-db-collection/src/postgrest-filters/index.ts @@ -1,3 +1,4 @@ +export { isPushable } from './common' export { keyColumnsToSearch } from './key-columns-to-search' export { cursorCurrentToSearch, @@ -10,4 +11,4 @@ export { splitLoadSubsetOptions, } from './split-load-subset-options' export { subsetParamsToSearch } from './subset-params-to-search' -export { isAggregateOnlySelect, queryIrToSearch } from './query-ir-to-search' +export { queryIrToSearch } from './query-ir-to-search' diff --git a/packages/supabase-db-collection/src/postgrest-filters/query-ir-to-search.ts b/packages/supabase-db-collection/src/postgrest-filters/query-ir-to-search.ts index f85a7d1078..71f12b39ed 100644 --- a/packages/supabase-db-collection/src/postgrest-filters/query-ir-to-search.ts +++ b/packages/supabase-db-collection/src/postgrest-filters/query-ir-to-search.ts @@ -188,7 +188,7 @@ function aggToSelectPart(alias: string, expr: Expression): string | null { return `${alias}:${column}.${name}()` } if (name === 'count') { - return `${alias}:count` + return `${alias}:count()` } return null } @@ -196,24 +196,6 @@ function aggToSelectPart(alias: string, expr: Expression): string | null { return null } -/** - * Whether every select entry is an aggregate PostgREST can compute, so the - * response is exactly one row. A plain column beside an aggregate would make - * PostgREST group by it, and any other expression falls back to `select=*`. - */ -export function isAggregateOnlySelect( - select: SerializedSelect | undefined, -): boolean { - if (!select) return false - const entries = Object.entries(select) - return ( - entries.length > 0 && - entries.every( - ([alias, value]) => aggToSelectPart(alias, value as Expression) !== null, - ) - ) -} - /** * Build PostgREST resource embedding strings for joins. * diff --git a/packages/supabase-db-collection/src/query-once.ts b/packages/supabase-db-collection/src/query-once.ts index 14100a1632..8f706823e2 100644 --- a/packages/supabase-db-collection/src/query-once.ts +++ b/packages/supabase-db-collection/src/query-once.ts @@ -1,6 +1,6 @@ import { Query, queryOnce } from '@tanstack/db' -import { isSupabaseCollection } from './db' -import { isAggregateOnlySelect, queryIrToSearch } from './postgrest-filters' +import { parsedColumns } from './db' +import { isPushable, queryIrToSearch } from './postgrest-filters' import { postgrestRequest } from './postgrest-request' import { serializeQueryIR } from './serialize' import type { @@ -11,7 +11,12 @@ import type { InitialQueryBuilder, QueryBuilder, } from '@tanstack/db' -import type { SerializedQueryIR } from './serialize' +import type { + SerializedExpression, + SerializedQueryIR, + SerializedSelect, + SerializedWhere, +} from './serialize' import type { SupabaseClient } from '@supabase/supabase-js' // ── Execution ─────────────────────────────────────────────────────── @@ -36,37 +41,80 @@ export async function executeQuery( return data ?? [] } -/** Run an aggregate-only query on PostgREST, shaped like TanStack's result */ +type ServerAggregate = SerializedExpression & { type: 'agg' } + +/** + * Run an aggregate-only query on PostgREST and return TanStack DB's result for + * it. TanStack DB aggregates an ungrouped query as one group of the matching + * rows, with these rules (see `getAggregateFunction` in @tanstack/db): + * + * - no matching rows give no result row, where SQL gives one; + * - `count` counts the non-null values, as SQL does; + * - `sum` adds a null as 0, so an all-null column sums to 0, not null; + * - `avg` divides that sum by the number of matching rows, nulls included. + * + * So the request also counts the matching rows, and asks for each average as + * a sum. + */ async function executeServerAggregate( supabase: SupabaseClient, ir: SerializedQueryIR, + aggregates: Record, ): Promise { - // A single aggregate row has nothing to order, and Postgres rejects ORDER BY - // on a column outside the aggregates. - const rows = await executeQuery(supabase, { ...ir, orderBy: undefined }) - return ir.singleResult ? rows[0] : rows + let rowsAlias = 'rows' + while (rowsAlias in aggregates) rowsAlias = `_${rowsAlias}` + const select: SerializedSelect = { + [rowsAlias]: { type: 'agg', name: 'count', args: [] }, + } + for (const [alias, aggregate] of Object.entries(aggregates)) { + select[alias] = + aggregate.name === 'avg' ? { ...aggregate, name: 'sum' } : aggregate + } + const [row] = (await executeQuery(supabase, { + from: ir.from, + where: ir.where, + select, + })) as Array> + const rows = row?.[rowsAlias] ?? 0 + if (rows === 0) return ir.singleResult ? undefined : [] + + const result: Record = {} + for (const [alias, { name }] of Object.entries(aggregates)) { + const value = row![alias] ?? null + result[alias] = + name === 'count' + ? value + : name === 'sum' + ? (value ?? 0) + : (value ?? 0) / rows + } + return ir.singleResult ? result : [result] } // ── Server aggregate detection ────────────────────────────────────── /** - * Clauses the server aggregate path reproduces exactly: filters, paging, and - * the no-op order/distinct on its single row. findOne is unwrapped. + * Clauses the server aggregate path reproduces exactly. findOne is unwrapped. + * TanStack DB rejects limit and offset without orderBy, and decides ordering + * and distinct itself, so a query with any other clause runs through it. */ const SERVER_AGGREGATE_CLAUSES = new Set([ 'from', 'select', 'where', - 'orderBy', - 'limit', - 'offset', - 'distinct', 'singleResult', ]) /** Clauses a subquery source may set and still be pushed down: its filters */ const FILTER_ONLY_CLAUSES = new Set(['from', 'where']) +/** + * The aggregates whose PostgREST result maps exactly onto TanStack DB's. A + * `min` or `max` would compare text by the database collation and a null as + * nothing, where TanStack DB compares JavaScript values and a null as 0. + */ +const SERVER_AGGREGATES = new Set(['count', 'sum', 'avg']) + /** Whether every clause the query sets is in `allowed` */ function setsOnly(query: IR.QueryIR, allowed: Set): boolean { return Object.entries(query).every( @@ -78,37 +126,84 @@ function setsOnly(query: IR.QueryIR, allowed: Set): boolean { } /** - * A Supabase table, or a subquery that only filters one (its where is pushed - * down). A collection this package did not create has no table to query. + * The columns read through `parse` when `from` is a Supabase table, or a + * subquery that only filters one (its where is pushed down). `null` for any + * other source: a collection this package did not create has no table. */ -function isFilteredTable(from: IR.From): boolean { +function filteredTableParsedColumns(from: IR.From): Set | null { if (from.type === 'collectionRef') { - return isSupabaseCollection(from.collection) + return parsedColumns(from.collection) } - return ( - from.type === 'queryRef' && - setsOnly(from.query, FILTER_ONLY_CLAUSES) && - isFilteredTable(from.query.from) - ) + return from.type === 'queryRef' && setsOnly(from.query, FILTER_ONLY_CLAUSES) + ? filteredTableParsedColumns(from.query.from) + : null +} + +/** The where clauses of the query and of its subquery sources */ +function filtersOf(ir: SerializedQueryIR): Array { + return [ + ...(ir.where ?? []), + ...(ir.from.type === 'subquery' ? filtersOf(ir.from.query) : []), + ] +} + +/** A filter PostgREST applies exactly, so no row needs filtering afterwards */ +function isPushableFilter(where: SerializedWhere): boolean { + if ('type' in where) return isPushable(where, { stripAlias: true }) + return !where.residual && isPushable(where.expression, { stripAlias: true }) +} + +/** + * The select's aggregates when PostgREST can compute each one exactly: a + * count, sum, or average of one plain column. A sum or average of a column + * read through `parse` adds the parsed values in TanStack DB, so it is not. + */ +function serverAggregates( + select: SerializedSelect | undefined, + parsed: Set, +): Record | null { + const entries = Object.entries(select ?? {}) + if (entries.length === 0) return null + const aggregates: Record = {} + for (const [alias, value] of entries) { + if (!('type' in value) || value.type !== 'agg') return null + const [arg, ...rest] = value.args + const column = + arg?.type === 'ref' && arg.path.length === 2 ? arg.path[1]! : null + if ( + !SERVER_AGGREGATES.has(value.name) || + column === null || + rest.length > 0 || + (value.name !== 'count' && parsed.has(column)) + ) { + return null + } + aggregates[alias] = value + } + return aggregates } /** - * Whether PostgREST alone produces the query's exact result: one row of - * aggregates over a single, optionally filtered table. executeQuery returns - * PostgREST's response as-is, so anything else (grouping, joins, unions, - * functional clauses, plain or computed select fields) is left to TanStack DB. - * This is an allow-list so that clauses added to the IR later default to the - * client-side path. + * The query's aggregates when PostgREST alone produces TanStack DB's exact + * result: one row of counts, sums, and averages over a single, optionally + * filtered table, with every filter pushed down. Anything else (grouping, + * joins, unions, paging, functional clauses, plain or computed select fields, + * filters PostgREST cannot apply) is left to TanStack DB. This is an + * allow-list so that clauses added to the IR later default to that path. */ -function isServerAggregate( +function serverAggregateOf( ir: IR.QueryIR, serialized: SerializedQueryIR, -): boolean { - return ( - setsOnly(ir, SERVER_AGGREGATE_CLAUSES) && - isFilteredTable(ir.from) && - isAggregateOnlySelect(serialized.select) - ) +): Record | null { + const parsed = filteredTableParsedColumns(ir.from) + if ( + parsed === null || + !setsOnly(ir, SERVER_AGGREGATE_CLAUSES) || + !filtersOf(serialized).every(isPushableFilter) + ) { + return null + } + return serverAggregates(serialized.select, parsed) } // ── Public API ────────────────────────────────────────────────────── @@ -119,17 +214,17 @@ function isServerAggregate( * Experimental: this reads TanStack DB's internal query representation, which * can change between releases. * - * A query whose select contains only aggregates (count/sum/avg/min/max) over - * a single Supabase table, with no grouping, join, or functional clause, is - * translated to a single PostgREST request and computed by the server. It - * relies on PostgREST aggregate functions, which must be enabled with - * `pgrst.db_aggregates_enabled`. + * Either way it resolves to what TanStack DB's own `queryOnce` resolves to. + * A query whose select holds only counts, sums, and averages of columns of a + * single Supabase table, with filters PostgREST can apply and no grouping, + * join, paging, or functional clause, is computed by the server in a single + * PostgREST request. It relies on PostgREST aggregate functions, which must be + * enabled with `pgrst.db_aggregates_enabled`. * - * Every other query, including groupBy and having, runs through TanStack DB's - * own `queryOnce` over the collections: filters, ordering, and limits are - * pushed to PostgREST where possible, and the remaining operations (grouping, - * having, distinct, computed select expressions) are applied client-side over - * the fetched rows. + * Every other query, including min, max, groupBy, and having, runs through + * TanStack DB's `queryOnce` over the collections: filters, ordering, and + * limits are pushed to PostgREST where possible, and the remaining operations + * are applied client-side over the fetched rows. */ export const experimental_queryOnce = < TQueryFn extends (q: InitialQueryBuilder) => QueryBuilder, @@ -141,8 +236,9 @@ export const experimental_queryOnce = < const q = new Query() const ir = (callback(q) as unknown as BaseQueryBuilder)._getQuery() const serialized = serializeQueryIR(ir) - if (isServerAggregate(ir, serialized)) { - return executeServerAggregate(supabase, serialized) as Promise< + const aggregates = serverAggregateOf(ir, serialized) + if (aggregates) { + return executeServerAggregate(supabase, serialized, aggregates) as Promise< InferResultType> > } diff --git a/packages/supabase-db-collection/src/serialize.ts b/packages/supabase-db-collection/src/serialize.ts index d109f85593..8c8d579388 100644 --- a/packages/supabase-db-collection/src/serialize.ts +++ b/packages/supabase-db-collection/src/serialize.ts @@ -168,20 +168,20 @@ function serializeExpression( ): SerializedExpression { switch (expr.type) { case `ref`: - return { type: `ref`, path: [...(expr).path] } + return { type: `ref`, path: [...expr.path] } case `val`: - return { type: `val`, value: serializeValue((expr).value) } + return { type: `val`, value: serializeValue(expr.value) } case `func`: return { type: `func`, - name: (expr).name, - args: (expr).args.map(serializeExpression), + name: expr.name, + args: expr.args.map(serializeExpression), } case `agg`: return { type: `agg`, - name: (expr).name, - args: (expr).args.map(serializeExpression), + name: expr.name, + args: expr.args.map(serializeExpression), } case `includesSubquery`: return serializeIncludesSubquery(expr) diff --git a/packages/supabase-db-collection/supabase/migrations/00000000000002_query_once_aggregates.sql b/packages/supabase-db-collection/supabase/migrations/00000000000002_query_once_aggregates.sql index 443ff4e1a9..90c22583b4 100644 --- a/packages/supabase-db-collection/supabase/migrations/00000000000002_query_once_aggregates.sql +++ b/packages/supabase-db-collection/supabase/migrations/00000000000002_query_once_aggregates.sql @@ -8,15 +8,18 @@ alter role authenticator set pgrst.db_aggregates_enabled = 'true'; notify pgrst, 'reload config'; -- Every column is nullable, so a generated history can aggregate an empty or --- all-null column. "big_count" stores a bigint as text, which the collection --- reads with `parse` (the way the shared suites store "largeViewCount"), so --- Postgres orders it as text while the collection orders it as a bigint. +-- all-null column. Two columns store numbers as text, which the collection +-- reads with `parse` (the way the shared suites store "largeViewCount"): +-- "big_count" holds a bigint, which Postgres orders as text while the +-- collection orders it as a bigint, and "amount" holds a decimal, which the +-- collection can sum while Postgres cannot sum text. create table public.query_once_rows ( id bigint primary key, score integer, label text, recorded_at timestamptz, - big_count text + big_count text, + amount text ); alter table public.query_once_rows enable row level security; diff --git a/packages/supabase-db-collection/tests/query-once.test.ts b/packages/supabase-db-collection/tests/query-once.test.ts index 5823757aec..22033ccab3 100644 --- a/packages/supabase-db-collection/tests/query-once.test.ts +++ b/packages/supabase-db-collection/tests/query-once.test.ts @@ -44,6 +44,7 @@ import { getRequestHeaders, normalizeFetchUrl, } from './test.utils' +import type { InitialQueryBuilder } from '@tanstack/db' describe('queryOnce PostgREST query generation', () => { let mockFetch: ReturnType @@ -391,7 +392,7 @@ describe('queryOnce PostgREST query generation', () => { }) }) - describe('Aggregate functions (pushed to PostgREST)', () => { + describe('Aggregate functions', () => { test('count(id)', async () => { await experimental_queryOnce( (q) => @@ -401,7 +402,7 @@ describe('queryOnce PostgREST query generation', () => { supabase, ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count()', + '/rest/v1/users?select=rows:count(),totalUsers:id.count()', ]) }) @@ -413,7 +414,9 @@ describe('queryOnce PostgREST query generation', () => { .select(({ user }) => ({ sumId: sum(user.id) })), supabase, ) - expectFetchUrls(mockFetch, ['/rest/v1/users?select=sumId:id.sum()']) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=rows:count(),sumId:id.sum()', + ]) }) test('avg(id)', async () => { @@ -424,10 +427,14 @@ describe('queryOnce PostgREST query generation', () => { .select(({ user }) => ({ avgId: avg(user.id) })), supabase, ) - expectFetchUrls(mockFetch, ['/rest/v1/users?select=avgId:id.avg()']) + // TanStack DB averages over every matching row, nulls included, so the + // average is computed from the sum and the row count. + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=rows:count(),avgId:id.sum()', + ]) }) - test('min(id)', async () => { + test('min(id) runs through TanStack DB', async () => { await experimental_queryOnce( (q) => q @@ -435,10 +442,12 @@ describe('queryOnce PostgREST query generation', () => { .select(({ user }) => ({ minId: min(user.id) })), supabase, ) - expectFetchUrls(mockFetch, ['/rest/v1/users?select=minId:id.min()']) + // TanStack DB orders a null as 0 and text by code unit, which no + // PostgREST aggregate reproduces, so min and max run through it. + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) }) - test('max(id)', async () => { + test('max(id) runs through TanStack DB', async () => { await experimental_queryOnce( (q) => q @@ -446,10 +455,10 @@ describe('queryOnce PostgREST query generation', () => { .select(({ user }) => ({ maxId: max(user.id) })), supabase, ) - expectFetchUrls(mockFetch, ['/rest/v1/users?select=maxId:id.max()']) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) }) - test('multiple aggregates', async () => { + test('an aggregate beside min or max runs through TanStack DB', async () => { await experimental_queryOnce( (q) => q.from({ user: usersCollection }).select(({ user }) => ({ @@ -458,9 +467,7 @@ describe('queryOnce PostgREST query generation', () => { })), supabase, ) - expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count(),maxId:id.max()', - ]) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) }) test('aggregate with where', async () => { @@ -473,7 +480,7 @@ describe('queryOnce PostgREST query generation', () => { supabase, ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count()&active=eq.true', + '/rest/v1/users?select=rows:count(),totalUsers:id.count()&active=eq.true', ]) }) @@ -490,7 +497,7 @@ describe('queryOnce PostgREST query generation', () => { supabase, ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count()&name=like.%25Ali%25&email=ilike.%25ali%25', + '/rest/v1/users?select=rows:count(),totalUsers:id.count()&name=like.%25Ali%25&email=ilike.%25ali%25', ]) }) @@ -506,7 +513,7 @@ describe('queryOnce PostgREST query generation', () => { supabase, ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count()&or=(name.ilike.%25ali%25,email.ilike.%25ali%25)', + '/rest/v1/users?select=rows:count(),totalUsers:id.count()&or=(name.ilike.%25ali%25,email.ilike.%25ali%25)', ]) }) @@ -525,7 +532,7 @@ describe('queryOnce PostgREST query generation', () => { supabase, ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count()&active=eq.true&or=(name.ilike.%25ali%25,email.ilike.%25ali%25)', + '/rest/v1/users?select=rows:count(),totalUsers:id.count()&active=eq.true&or=(name.ilike.%25ali%25,email.ilike.%25ali%25)', ]) }) @@ -541,7 +548,7 @@ describe('queryOnce PostgREST query generation', () => { supabase, ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count()&or=(id.in.(1,2,3),active.eq.true)', + '/rest/v1/users?select=rows:count(),totalUsers:id.count()&or=(id.in.(1,2,3),active.eq.true)', ]) }) @@ -557,7 +564,7 @@ describe('queryOnce PostgREST query generation', () => { supabase, ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count()&or=(name.ilike."%25a,b%25",email.eq."x,y")', + '/rest/v1/users?select=rows:count(),totalUsers:id.count()&or=(name.ilike."%25a,b%25",email.eq."x,y")', ]) }) @@ -573,24 +580,36 @@ describe('queryOnce PostgREST query generation', () => { supabase, ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count()&or=(active.not.eq.true,name.not.ilike.%25ali%25)', + '/rest/v1/users?select=rows:count(),totalUsers:id.count()&or=(active.not.eq.true,name.not.ilike.%25ali%25)', ]) }) - test('aggregate rejects unsupported filters before making a request', async () => { - await expect( - experimental_queryOnce( - (q) => - q - .from({ user: usersCollection }) - .where(({ user }) => - or(eq(user.active, true), eq(upper(user.name), 'ALICE')), - ) - .select(({ user }) => ({ totalUsers: count(user.id) })), - supabase, - ), - ).rejects.toThrow('fully pushable filters') - expect(mockFetch).not.toHaveBeenCalled() + test('aggregate with a filter PostgREST cannot apply runs through TanStack DB', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => + or(eq(user.active, true), eq(upper(user.name), 'ALICE')), + ) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, ['/rest/v1/users?select=*']) + }) + + test('an aggregate beside ORDER BY runs through TanStack DB', async () => { + await experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .orderBy(({ user }) => user.name) + .select(({ user }) => ({ totalUsers: count(user.id) })), + supabase, + ) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?order=name.asc.nullsfirst&select=*', + ]) }) test('aggregate with NOT(name LIKE …)', async () => { @@ -603,7 +622,7 @@ describe('queryOnce PostgREST query generation', () => { supabase, ) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count()&name=not.like.%25Ali%25', + '/rest/v1/users?select=rows:count(),totalUsers:id.count()&name=not.like.%25Ali%25', ]) }) }) @@ -919,22 +938,24 @@ describe('queryOnce PostgREST query generation', () => { ]) }) - test('aggregates + WHERE + LIMIT', async () => { - await experimental_queryOnce( - (q) => - q - .from({ user: usersCollection }) - .where(({ user }) => eq(user.active, true)) - .select(({ user }) => ({ - totalUsers: count(user.id), - avgId: avg(user.id), - })) - .limit(1), - supabase, - ) - expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=totalUsers:id.count(),avgId:id.avg()&active=eq.true&limit=1', - ]) + test('aggregates + WHERE + LIMIT runs through TanStack DB', async () => { + // TanStack DB rejects LIMIT without ORDER BY, so the server must not + // answer this query either. + await expect( + experimental_queryOnce( + (q) => + q + .from({ user: usersCollection }) + .where(({ user }) => eq(user.active, true)) + .select(({ user }) => ({ + totalUsers: count(user.id), + avgId: avg(user.id), + })) + .limit(1), + supabase, + ), + ).rejects.toThrow('ORDER BY') + expect(mockFetch).not.toHaveBeenCalled() }) }) @@ -1449,14 +1470,16 @@ describe('queryOnce server aggregate routing', () => { describe('queryOnce server aggregate path', () => { // Answers every request the way PostgREST answers an aggregate-only select. + let response: Array> let mockFetch: ReturnType let users: ReturnType let supabase: ReturnType beforeEach(() => { + response = [{ rows: 5, total: 5 }] mockFetch = vi.fn().mockImplementation(() => Promise.resolve( - new Response(JSON.stringify([{ total: 5 }]), { + new Response(JSON.stringify(response), { headers: { 'content-type': 'application/json' }, }), ), @@ -1481,24 +1504,54 @@ describe('queryOnce server aggregate path', () => { supabase, ) - expectFetchUrls(mockFetch, ['/rest/v1/users?select=total:id.count()']) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=rows:count(),total:id.count()', + ]) expect(result).toEqual({ total: 5 }) }) - test('does not push ORDER BY beside an aggregate', async () => { - // Postgres rejects ORDER BY on a column outside the aggregates, and a - // single row has nothing to order. + test('no matching rows give no aggregate row, as in TanStack DB', async () => { + response = [{ rows: 0, total: null }] + const select = (q: InitialQueryBuilder) => + q.from({ user: users }).select(({ user }) => ({ total: sum(user.id) })) + + expect(await experimental_queryOnce(select, supabase)).toEqual([]) + expect( + await experimental_queryOnce((q) => select(q).findOne(), supabase), + ).toBeUndefined() + }) + + test('a sum of nulls is 0 and an average counts every row, as in TanStack DB', async () => { + response = [{ rows: 4, total: null, mean: 6 }] + const rows = await experimental_queryOnce( + (q) => + q.from({ user: users }).select(({ user }) => ({ + total: sum(user.id), + mean: avg(user.id), + })), + supabase, + ) + + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=rows:count(),total:id.sum(),mean:id.sum()', + ]) + expect(rows).toEqual([{ total: 0, mean: 1.5 }]) + }) + + test('the row count alias avoids a selected alias', async () => { + response = [{ _rows: 5, rows: 5 }] const rows = await experimental_queryOnce( (q) => q .from({ user: users }) - .orderBy(({ user }) => user.name) - .select(({ user }) => ({ total: count(user.id) })), + .select(({ user }) => ({ rows: count(user.id) })), supabase, ) - expectFetchUrls(mockFetch, ['/rest/v1/users?select=total:id.count()']) - expect(rows).toEqual([{ total: 5 }]) + expectFetchUrls(mockFetch, [ + '/rest/v1/users?select=_rows:count(),rows:id.count()', + ]) + expect(rows).toEqual([{ rows: 5 }]) }) test('pushes the filters of a filter-only subquery source', async () => { @@ -1512,7 +1565,7 @@ describe('queryOnce server aggregate path', () => { }, supabase) expectFetchUrls(mockFetch, [ - '/rest/v1/users?select=total:id.count()&id=gt.2', + '/rest/v1/users?select=rows:count(),total:id.count()&id=gt.2', ]) expect(rows).toEqual([{ total: 5 }]) }) diff --git a/packages/supabase-db-collection/tests/serialize.test.ts b/packages/supabase-db-collection/tests/serialize.test.ts index 2839502104..549ad91107 100644 --- a/packages/supabase-db-collection/tests/serialize.test.ts +++ b/packages/supabase-db-collection/tests/serialize.test.ts @@ -1,4 +1,4 @@ -import { Query } from '@tanstack/db' +import { Query } from '@tanstack/db' import { describe, expect, test } from 'vitest' import { serializeQueryIR } from '../src/serialize' import { @@ -6,7 +6,7 @@ import { createMockedTodosCollection, createMockedUsersCollection, } from './test.utils' -import type {BaseQueryBuilder} from '@tanstack/db'; +import type { BaseQueryBuilder } from '@tanstack/db' describe('serializeQueryIR FROM variants', () => { const mockFetch = createMockFetch() From 6cb30d15e4bca6145282d7b851bac4deb611fa57 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Wed, 11 Nov 2026 14:42:12 +0100 Subject: [PATCH 12/13] docs(supabase-db-collection): import the Supabase collection docs from the pre-split branch Brings the docs page, adapter skill reference, nav, installation, overview, reference-docs generation, and skill entries across unchanged, apart from merge conflicts with main. The next commit updates them to the current code. Co-Authored-By: Claude Opus 5.5 (1M context) --- .changeset/add-supabase-db-collection.md | 5 + _artifacts/skill_tree.yaml | 6 +- docs/collections/supabase-collection.md | 394 ++++++++++++++++++ docs/config.json | 16 + docs/installation.md | 10 + docs/overview.md | 4 +- domain_map.yaml | 4 + packages/db/skills/db-core/SKILL.md | 3 +- .../skills/db-core/collection-setup/SKILL.md | 7 +- .../references/supabase-adapter.md | 118 ++++++ scripts/generate-docs.ts | 12 + 11 files changed, 574 insertions(+), 5 deletions(-) create mode 100644 .changeset/add-supabase-db-collection.md create mode 100644 docs/collections/supabase-collection.md create mode 100644 packages/db/skills/db-core/collection-setup/references/supabase-adapter.md diff --git a/.changeset/add-supabase-db-collection.md b/.changeset/add-supabase-db-collection.md new file mode 100644 index 0000000000..e015b62f77 --- /dev/null +++ b/.changeset/add-supabase-db-collection.md @@ -0,0 +1,5 @@ +--- +'@tanstack/supabase-db-collection': minor +--- + +Add `@tanstack/supabase-db-collection`, a collection for syncing TanStack DB with Supabase through PostgREST queries, optimistic mutations, and Realtime subscriptions. Migrated from `@supabase-labs/tanstack-db@0.1.0` ([supabase/tanstack-db@3503c451](https://github.com/supabase/tanstack-db/commit/3503c451b2f2550ab4069067673881f39342b588)). Adds a `syncMode` option (`'on-demand'` by default, or `'eager'` to load the whole table). diff --git a/_artifacts/skill_tree.yaml b/_artifacts/skill_tree.yaml index 62a0098ea5..a6180e34f2 100644 --- a/_artifacts/skill_tree.yaml +++ b/_artifacts/skill_tree.yaml @@ -35,7 +35,8 @@ skills: description: > Creating typed collections with createCollection, queryCollectionOptions, electricCollectionOptions, powerSyncCollectionOptions, rxdbCollectionOptions, - trailbaseCollectionOptions, localOnlyCollectionOptions, localStorageCollectionOptions. + trailbaseCollectionOptions, supabaseCollectionOptions, localOnlyCollectionOptions, + localStorageCollectionOptions. CollectionConfig (getKey, schema, sync, gcTime, autoIndex, syncMode). StandardSchema validation with Zod/Valibot/ArkType. Collection lifecycle (idle/loading/ready/error/cleaned-up). Adapter-specific sync patterns. @@ -49,6 +50,7 @@ skills: - 'TanStack/db:docs/collections/powersync-collection.md' - 'TanStack/db:docs/collections/rxdb-collection.md' - 'TanStack/db:docs/collections/trailbase-collection.md' + - 'TanStack/db:docs/collections/supabase-collection.md' - 'TanStack/db:docs/collections/local-only-collection.md' - 'TanStack/db:docs/collections/local-storage-collection.md' - 'TanStack/db:packages/db/src/collection/index.ts' @@ -58,6 +60,7 @@ skills: - 'PowerSync adapter' - 'RxDB adapter' - 'TrailBase adapter' + - 'Supabase adapter' - 'Local-only' - 'localStorage' references: @@ -66,6 +69,7 @@ skills: - 'references/powersync-adapter.md' - 'references/rxdb-adapter.md' - 'references/trailbase-adapter.md' + - 'references/supabase-adapter.md' - 'references/local-adapters.md' - 'references/schema-patterns.md' diff --git a/docs/collections/supabase-collection.md b/docs/collections/supabase-collection.md new file mode 100644 index 0000000000..22c2d829de --- /dev/null +++ b/docs/collections/supabase-collection.md @@ -0,0 +1,394 @@ +--- +title: Supabase Collection +--- + +Supabase collections provide seamless integration between TanStack DB and [Supabase](https://supabase.com), keeping your UI in sync with Postgres through PostgREST queries, mutations, and Realtime subscriptions. + +> **Experimental.** The Realtime integration is still being stabilized and may consume more Realtime messages than expected. +> +> Test in orgs on the free plan or with a spend cap. Set `realtime: false` on individual collections to opt out. To narrow a subscription to only send the needed messages and cut Realtime traffic, try the experimental `realtimeUseFilter: true` option (see [Real-time Subscriptions](#real-time-subscriptions)). + +## Overview + +[Supabase](https://supabase.com) is an open source Postgres development platform with auto-generated REST APIs (PostgREST), Realtime, Auth, and Row Level Security (RLS). + +The `@tanstack/supabase-db-collection` package allows you to create collections that: + +- Load data from your Supabase tables, pushing `where`, `orderBy`, and `limit` down to PostgREST +- Apply inserts, updates, and deletes optimistically, then roll back automatically if the server rejects them +- Receive changes made by other clients through Supabase Realtime, with no subscription code +- Derive their types from a [Standard Schema](https://standardschema.dev) (e.g., Zod, Valibot), so queries and mutations are type-checked end to end + +Collections work with your Supabase project as it is and respect Row Level Security. Your Supabase database remains the source of truth: Postgres, RLS, Auth, and the rest of your stack stay unchanged, and no migration is required. + +Collections fetch on the client. TanStack DB does not yet support server-side rendering (SSR), so collections should not be used to render on the server. + +To see a working app, open the [example Todo app](https://todomvc-supabase-tanstack-db.vercel.app/). + +## Installation + +```bash +npm install @tanstack/supabase-db-collection @tanstack/react-db @tanstack/query-core @supabase/supabase-js +``` + +`@supabase/supabase-js` and `@tanstack/query-core` are peer dependencies. You also need an existing Supabase project with the client library and environment variables configured. If you have not set that up yet, follow the [Supabase getting started guide](https://supabase.com/docs/guides/getting-started). + +The examples on this page use React. TanStack DB also supports Vue, Angular, Solid, Svelte, and vanilla JavaScript; swap `@tanstack/react-db` for the package that matches your framework. + +> **Tip:** The [Supabase UI Library](https://supabase.com/ui/docs/nextjs/tanstack-db) provides a TanStack DB block that generates zod schemas and collections for every table in your database, so you do not have to write them by hand. + +## Basic Usage + +### 1. Enable Realtime for synced tables + +Realtime is optional, but required if you want changes from other clients to appear automatically. + +Enable Realtime for your table in the Supabase Table Editor, or run this in the SQL Editor: + +```sql +alter publication supabase_realtime add table "public"."todos"; +``` + +### 2. Define a collection + +In TanStack DB, a collection corresponds to a Postgres table. Create one collection for each table you want to access from your frontend: + +```typescript +import { createCollection } from '@tanstack/react-db' +import { supabaseCollectionOptions } from '@tanstack/supabase-db-collection' +import { createClient } from '@supabase/supabase-js' +import { z } from 'zod' + +const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY) + +const todoSchema = z.object({ + id: z.string(), + title: z.string(), + completed: z.boolean(), +}) + +export const todosCollection = createCollection( + supabaseCollectionOptions({ + tableName: 'todos', + schema: todoSchema, + keys: ['id'], // should match your primary key(s) + supabase, + realtime: true, + }) +) +``` + +### 3. Use the collection in components + +Query collections with `useLiveQuery`. Mutations are methods on the collection, so call `collection.insert`, `collection.update`, or `collection.delete` directly. No hooks or mutation objects are required. + +```tsx +import { useLiveQuery, eq } from '@tanstack/react-db' +import { todosCollection } from './collections' + +function Todos() { + const { data: todos, isLoading } = useLiveQuery( + (q) => + q + .from({ todo: todosCollection }) + .where(({ todo }) => eq(todo.completed, false)), + [] // re-run the query when these dependencies change + ) + + // These apply instantly in the UI and roll back if the server rejects them + const insertTodo = (title: string) => { + todosCollection.insert({ id: crypto.randomUUID(), title, completed: false }) + } + + const completeTodo = (id: string) => { + todosCollection.update(id, (draft) => { + draft.completed = true + }) + } + + const deleteTodo = (id: string) => { + todosCollection.delete(id) + } + + if (isLoading) return

Loading...

+ + return ( +
+ +
    + {todos.map((todo) => ( +
  • + {todo.title} + + +
    • + ))} +
+
+ ) +} +``` + +## Configuration Options + +The `supabaseCollectionOptions` function accepts the following options: + +### Required Options + +- `tableName`: Name of the Postgres table. Maps to the PostgREST endpoint +- `schema`: [Standard Schema](https://standardschema.dev) compatible schema (e.g., Zod, Valibot) describing a single row +- `keys`: Column or columns that uniquely identify a row. Should match the primary key(s) on your table. Used to derive the collection key and to match rows on update and delete. With a single column, the collection key is that column's value; with several, the values are joined with `-` +- `supabase`: Supabase client instance used for queries, mutations, and the Realtime subscription + +### Optional Options + +| Option | Type | Default | Description | +| ------------------- | ------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `syncMode` | `'on-demand'` \| `'eager'` | `'on-demand'` | Controls what is loaded into the collection. `'on-demand'` loads only the rows that live queries need, pushing `where`, `orderBy`, and `limit` to PostgREST. `'eager'` loads the whole table up front, paging past the PostgREST row cap, and evaluates queries against the local copy. See [How Sync Works](#how-sync-works). | +| `realtime` | `boolean` | `false` | When `true`, subscribes to Postgres changes and reconciles inserts, updates, and deletes from other clients into the collection. | +| `realtimeUseFilter` | `boolean` | `false` | **Experimental.** Only applies when `realtime` is `true`. When `true`, each active query's `WHERE` clause is pushed to the Realtime subscription as a `postgres_changes` filter, so the channel only receives changes those queries care about. When `false`, the collection subscribes to every change on the table and filters client-side. Queries whose `WHERE` cannot be expressed as a Realtime filter (e.g. `or(...)`) transparently fall back to the unfiltered subscription. | +| `queryClient` | `QueryClient` | shared client | TanStack Query client. If omitted, a shared global client is used. | +| `parse` | `{ [column]: (value) => … }` | none | Converts a column value received from PostgREST or Realtime into the value your schema describes. PostgREST speaks JSON, so a `timestamptz` arrives as a string: use `parse` to turn it into a `Date`. Applies to rows read, rows returned by inserts and updates, and Realtime payloads. Not called for `null` values. | +| `serialize` | `{ [column]: (value) => … }` | none | The reverse of `parse`: converts a column value held by the collection into the JSON value sent to PostgREST in insert and update bodies, and used to match rows by key on update and delete. Not called for `null` values. | + +PostgREST returns a `bigint` as a JSON number, which JavaScript rounds to the nearest double above `Number.MAX_SAFE_INTEGER` (9007199254740991). Values that large cannot round-trip through a `bigint` column; store them in a `text` column and convert them with `parse` and `serialize`. + +```ts +supabaseCollectionOptions({ + tableName: 'events', + keys: ['id'], + schema: eventSchema, // startsAt: z.date() + supabase, + parse: { startsAt: (value) => new Date(value as string) }, + serialize: { startsAt: (value) => value.toISOString() }, +}) +``` + +The `onInsert`, `onUpdate`, and `onDelete` handlers are provided by the adapter and write through PostgREST; they are not configurable. + +## How Sync Works + +Supabase collections are built on top of [Query Collection](./query-collection.md). Each live query is translated into PostgREST requests, the results are cached with TanStack Query, and Realtime events are merged into the same collection. + +### Sync modes + +- **`'on-demand'` (default):** the collection does not load anything until a live query subscribes. Each query fetches only the rows it needs, with filters, ordering, and limits sent to PostgREST. Use this for large tables or when each screen only shows a small slice of the data. +- **`'eager'`:** the whole table is loaded when the collection starts syncing, paging past the PostgREST row cap (see [Row cap and pagination](#row-cap-and-pagination)). Queries then run against the local copy. Use this for small, read-mostly tables that many queries touch. + +### Pushed to PostgREST + +Most query operations are translated to PostgREST filters and run server-side. A handful of operations run client-side instead. + +| Operation | Notes | +| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `FROM` | Maps to the PostgREST table endpoint. | +| `WHERE` (`eq`, `gt`, `gte`, `lt`, `lte`, `inArray`, `like`, `ilike`, `not`, `isNull`) | Translated to PostgREST filter syntax. | +| `AND` (multiple conditions or chained `.where`) | Translated to PostgREST filter syntax. A conjunct that cannot be pushed is dropped on its own; the request returns a superset and the client re-filters it. | +| `OR` and nested `AND`/`OR` | Translated to PostgREST's `or=(…)` syntax. All-or-nothing: if any branch cannot be pushed the whole `or` is dropped, because dropping one branch would narrow the result and lose matching rows. | +| `ORDER BY` (on source columns) | Translated to PostgREST ordering. | +| `LIMIT` | Translated to PostgREST limiting. | +| `JOIN` | Each table is fetched separately. The join key is pushed as an `in` filter on the second query. | + +`like` and `ilike` use TanStack's SQL wildcards: `%` matches any sequence and `_` matches one character (for example, `ilike(user.name, '%alice%')`). Patterns containing a literal `*` are evaluated client-side because PostgREST interprets `*` as a wildcard. Filter values containing commas, parentheses, quotes, or backslashes are escaped automatically. + +### Evaluated client-side + +These operations fetch the required rows and process them in memory: + +- `SELECT` column subsets, renaming, and computed fields (`upper`, `lower`, `concat`, `length`, `add`, `coalesce`) +- Aggregate functions: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` (except when using [`queryOnce`](#queryonce)) +- `GROUP BY` and `HAVING` +- `DISTINCT` +- `ORDER BY` on computed fields + +### Row cap and pagination + +PostgREST caps every response at its `db-max-rows` setting (1000 by default on Supabase). Collection reads and non-aggregate `queryOnce` queries page past this cap automatically: the adapter loops with `offset`, using a one-time `count=exact` on the first request to fetch the complete matching set (or the caller's `limit`). + +The aggregate / `GROUP BY` / `HAVING` path of `queryOnce` is the one exception. It issues a single request and is **not** paginated. Aggregate results are a few rows, so the cap is moot, but a `GROUP BY` / `HAVING` query whose grouped output exceeds `db-max-rows` is silently truncated at the cap. Add an explicit `limit`, or narrow the query, if you expect more grouped rows than the cap. + +Known limitations of the paging loop: + +- **Ordering.** Pages are stitched together with `offset`, and PostgreSQL does not guarantee a consistent row order across separate `LIMIT`/`OFFSET` queries unless the sort is total. When a read needs more than one page, the adapter therefore reads every page, including the first, ordered by the collection's `keys` after any `orderBy` of the query, so the pages come from one sequence. A read that fits in a single page is sent as written. +- **Concurrent writes.** Offset paging is not keyset-stable: a row inserted or deleted by another client while a multi-page read is in flight shifts the remaining rows by one offset, so a row can be missed or duplicated until the next refetch. +- **Count cost.** Every collection read issues one `Prefer: count=exact` on its first request so the loop knows when to stop. On very large tables, or under heavy RLS, that is a full `count(*)` per read. + +## Real-time Subscriptions + +With `realtime: true`, the collection subscribes to Postgres changes for its table and reconciles inserts, updates, and deletes made by other clients. The table must be added to the `supabase_realtime` publication (see [Basic Usage](#1-enable-realtime-for-synced-tables)). + +```typescript +const todosCollection = createCollection( + supabaseCollectionOptions({ + tableName: 'todos', + schema: todoSchema, + keys: ['id'], + supabase, + realtime: true, + // Experimental: only receive changes that match active queries + realtimeUseFilter: true, + }) +) +``` + +Row Level Security applies to Realtime, so clients only receive changes they are allowed to read. A server-side Supabase client has no Realtime channel, so `realtime` is a no-op there. + +Known limitation: the initial fetch does not wait for the Realtime channel to finish subscribing. A row written in the window between the fetch and the subscription going live can be missed by both. + +## Mutations and Optimistic Updates + +`insert`, `update`, and `delete` on the collection apply to the UI immediately, then are sent to Supabase through PostgREST. The adapter owns the persistence handlers: + +- **Insert** sends a `POST` and writes the row returned by the server back into the collection, so database defaults (generated ids, timestamps) appear without a refetch. +- **Update** sends a `PATCH` matched on the `keys` columns and writes back the returned row. +- **Delete** sends a `DELETE` matched on the `keys` columns. + +If the server rejects a mutation (for example, because an RLS policy denies it), the optimistic change is rolled back automatically. + +```typescript +// Applies instantly; rolls back if Postgres or RLS rejects it +todosCollection.update(todoId, (draft) => { + draft.completed = true +}) +``` + +See [Optimistic Mutations](../guides/mutations.md) for more on mutation lifecycles, transactions, and error handling. + +## queryOnce + +`queryOnce(callback, supabase)` runs a TanStack DB query once against Supabase and resolves with the result. It is non-reactive: it issues the needed requests and does not subscribe to changes. Use it for one-shot fetches such as API routes or form submissions where live updates are not needed. + +```typescript +import { eq } from '@tanstack/react-db' +import { queryOnce } from '@tanstack/supabase-db-collection' + +const completedTodos = await queryOnce( + (q) => + q + .from({ todo: todosCollection }) + .where(({ todo }) => eq(todo.completed, true)), + supabase +) +``` + +- `callback`: Builds the query using the same API as `useLiveQuery` +- `supabase`: Supabase client used to execute the request + +It returns a `Promise` that resolves to the query result, typed from the query you built. + +Filters, ordering, `limit`, `offset`, joins, and aggregate functions (`count`, `sum`, `avg`, `min`, `max`) are pushed to PostgREST. Operations that cannot be pushed fall back to fetching matching rows and processing them client-side. Fallback operations include `GROUP BY`, `HAVING`, `DISTINCT`, and computed `SELECT` expressions. + +The client-side filter fallback applies to live queries and ordinary `queryOnce` queries. The server aggregate path in `queryOnce` requires fully pushable `WHERE` expressions and throws for unsupported filters, rather than returning an aggregate over unfiltered rows. + +## Complete Example + +```tsx +import { createCollection, useLiveQuery, eq } from '@tanstack/react-db' +import { supabaseCollectionOptions } from '@tanstack/supabase-db-collection' +import { createClient } from '@supabase/supabase-js' +import { z } from 'zod' + +const supabase = createClient( + import.meta.env.VITE_SUPABASE_URL, + import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY +) + +// Define the schema for a single row +const todoSchema = z.object({ + id: z.string(), + title: z.string(), + completed: z.boolean(), +}) + +type Todo = z.infer + +// Create the collection +export const todosCollection = createCollection( + supabaseCollectionOptions({ + tableName: 'todos', + schema: todoSchema, + keys: ['id'], + supabase, + syncMode: 'on-demand', + realtime: true, + }) +) + +// Use in a component +function TodoList() { + const { data: todos, isLoading } = useLiveQuery( + (q) => + q + .from({ todo: todosCollection }) + .where(({ todo }) => eq(todo.completed, false)) + .orderBy(({ todo }) => todo.title, 'asc'), + [] + ) + + const addTodo = (title: string) => { + const todo: Todo = { id: crypto.randomUUID(), title, completed: false } + todosCollection.insert(todo) + } + + const toggleTodo = (todo: Todo) => { + todosCollection.update(todo.id, (draft) => { + draft.completed = !draft.completed + }) + } + + const removeTodo = (id: string) => { + todosCollection.delete(id) + } + + if (isLoading) return

Loading...

+ + return ( +
+ +
    + {todos.map((todo) => ( +
  • + toggleTodo(todo)} + /> + {todo.title} + +
    • + ))} +
+
+ ) +} +``` + +## FAQ + +**Will this work with my RLS policies?** + +Yes. Supabase collections go through PostgREST and Realtime, so your existing RLS policies apply automatically. + +**What if I do not use RLS?** + +Without RLS, all Realtime changes broadcast to every client. Depending on whether your app is public or private, that may not be what you want. + +**Can I use a Supabase collection and `supabase-js` in parallel?** + +Yes. The collection uses `supabase-js` under the hood, so they are compatible. Data fetched directly through `supabase-js` will not appear in the collection. + +Use `supabase-js` as a fallback for features TanStack DB does not cover, such as database functions through `.rpc` or complex `GROUP BY` queries. + +**Will this work with a custom API server?** + +This package targets Supabase and PostgREST tables. For custom backends, use [Query Collection](./query-collection.md) or write your own collection with the [Collection Options Creator guide](../guides/collection-options-creator.md). + +## Learn More + +- [Supabase Documentation](https://supabase.com/docs) +- [Supabase Realtime](https://supabase.com/docs/guides/realtime) +- [Supabase UI Library: TanStack DB block](https://supabase.com/ui/docs/nextjs/tanstack-db) +- [Example Todo app](https://todomvc-supabase-tanstack-db.vercel.app/) +- [Query Collection](./query-collection.md) +- [Optimistic Mutations](../guides/mutations.md) +- [Live Queries](../guides/live-queries.md) diff --git a/docs/config.json b/docs/config.json index 1bc477dd48..a987456847 100644 --- a/docs/config.json +++ b/docs/config.json @@ -87,6 +87,10 @@ "label": "TrailBase Collection", "to": "collections/trailbase-collection" }, + { + "label": "Supabase Collection", + "to": "collections/supabase-collection" + }, { "label": "RxDB Collection", "to": "collections/rxdb-collection" @@ -217,6 +221,18 @@ { "label": "indexedDBCollectionOptions", "to": "reference/functions/indexedDBCollectionOptions" + }, + { + "label": "Supabase DB Collection", + "to": "reference/supabase-db-collection/index" + }, + { + "label": "supabaseCollectionOptions", + "to": "reference/supabase-db-collection/functions/supabaseCollectionOptions" + }, + { + "label": "experimental_queryOnce", + "to": "reference/supabase-db-collection/functions/experimental_queryOnce" } ], "frameworks": [ diff --git a/docs/installation.md b/docs/installation.md index 070a005f8e..405f9df71a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -129,6 +129,16 @@ npm install @tanstack/trailbase-db-collection Use `trailBaseCollectionOptions` to sync records from TrailBase's Record APIs with built-in subscription support. +#### Supabase Collection + +For syncing with [Supabase](https://supabase.com) tables through PostgREST and Realtime: + +```sh +npm install @tanstack/supabase-db-collection @tanstack/query-core @supabase/supabase-js +``` + +Use `supabaseCollectionOptions` to load rows from Supabase tables, apply optimistic mutations, and receive changes from other clients through Realtime. Row Level Security is respected. + #### PowerSync Collection For offline-first sync with [PowerSync](https://powersync.com): diff --git a/docs/overview.md b/docs/overview.md index 66c02463b8..2acd515d35 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -225,6 +225,8 @@ TanStack DB provides several built-in collection types for different data source - **[TrailBaseCollection](./collections/trailbase-collection.md)** — Sync data into collections using TrailBase's self-hosted backend with real-time subscriptions. +- **[SupabaseCollection](./collections/supabase-collection.md)** — Sync data into collections from Supabase tables using PostgREST queries and Realtime subscriptions, respecting Row Level Security. + - **[RxDBCollection](./collections/rxdb-collection.md)** — Integrate with RxDB for offline-first local persistence with powerful replication and sync capabilities. - **[PowerSyncCollection](./collections/powersync-collection.md)** — Sync with PowerSync's SQLite-based database for offline-first persistence with real-time synchronization with PostgreSQL, MongoDB, and MySQL backends. @@ -291,7 +293,7 @@ The collection will use the schema for its type inference. If you provide a sche You can create your own collection types by implementing the `Collection` interface found in [`../packages/db/src/collection/index.ts`](https://github.com/TanStack/db/blob/main/packages/db/src/collection/index.ts). -See the existing implementations in [`../packages/db`](https://github.com/TanStack/db/tree/main/packages/db), [`../packages/query-db-collection`](https://github.com/TanStack/db/tree/main/packages/query-db-collection), [`../packages/electric-db-collection`](https://github.com/TanStack/db/tree/main/packages/electric-db-collection), [`../packages/trailbase-db-collection`](https://github.com/TanStack/db/tree/main/packages/trailbase-db-collection) and [`../packages/powersync-db-collection`](https://github.com/TanStack/db/tree/main/packages/powersync-db-collection) for reference. Also see the [Collection Options Creator guide](./guides/collection-options-creator.md) for a pattern to create reusable collection configuration factories. +See the existing implementations in [`../packages/db`](https://github.com/TanStack/db/tree/main/packages/db), [`../packages/query-db-collection`](https://github.com/TanStack/db/tree/main/packages/query-db-collection), [`../packages/electric-db-collection`](https://github.com/TanStack/db/tree/main/packages/electric-db-collection), [`../packages/trailbase-db-collection`](https://github.com/TanStack/db/tree/main/packages/trailbase-db-collection), [`../packages/supabase-db-collection`](https://github.com/TanStack/db/tree/main/packages/supabase-db-collection) and [`../packages/powersync-db-collection`](https://github.com/TanStack/db/tree/main/packages/powersync-db-collection) for reference. Also see the [Collection Options Creator guide](./guides/collection-options-creator.md) for a pattern to create reusable collection configuration factories. ### Live queries diff --git a/domain_map.yaml b/domain_map.yaml index 1d91bc7abf..b830e98ff5 100644 --- a/domain_map.yaml +++ b/domain_map.yaml @@ -52,6 +52,7 @@ skills: - 'queryCollectionOptions (@tanstack/query-db-collection)' - 'electricCollectionOptions (@tanstack/electric-db-collection)' - 'trailbaseCollectionOptions (@tanstack/trailbase-db-collection)' + - 'supabaseCollectionOptions (@tanstack/supabase-db-collection)' - 'powerSyncCollectionOptions (@tanstack/powersync-db-collection)' - 'rxdbCollectionOptions (@tanstack/rxdb-db-collection)' - 'localOnlyCollectionOptions' @@ -92,6 +93,9 @@ skills: - name: 'TrailBase adapter' package: '@tanstack/trailbase-db-collection' config_surface: 'recordApi, conversions' + - name: 'Supabase adapter' + package: '@tanstack/supabase-db-collection' + config_surface: 'tableName, keys, schema, supabase, queryClient, realtime, realtimeUseFilter, syncMode (on-demand default/eager)' - name: 'Local-only' package: '@tanstack/db' config_surface: 'getKey, schema, initialData' diff --git a/packages/db/skills/db-core/SKILL.md b/packages/db/skills/db-core/SKILL.md index 496c7405bc..b0b6873f0c 100644 --- a/packages/db/skills/db-core/SKILL.md +++ b/packages/db/skills/db-core/SKILL.md @@ -3,7 +3,8 @@ name: db-core description: > TanStack DB core concepts: createCollection with queryCollectionOptions, electricCollectionOptions, powerSyncCollectionOptions, rxdbCollectionOptions, - trailBaseCollectionOptions, localOnlyCollectionOptions. Live queries via + trailBaseCollectionOptions, supabaseCollectionOptions, + localOnlyCollectionOptions. Live queries via query builder (from, where, join, select, groupBy, orderBy, limit). Optimistic mutations with draft proxy (collection.insert, collection.update, collection.delete). createOptimisticAction, createTransaction, diff --git a/packages/db/skills/db-core/collection-setup/SKILL.md b/packages/db/skills/db-core/collection-setup/SKILL.md index 0d672663e4..48b68f6c0e 100644 --- a/packages/db/skills/db-core/collection-setup/SKILL.md +++ b/packages/db/skills/db-core/collection-setup/SKILL.md @@ -5,8 +5,8 @@ description: > queryCollectionOptions (REST/TanStack Query), electricCollectionOptions (ElectricSQL real-time sync), powerSyncCollectionOptions (PowerSync SQLite), rxdbCollectionOptions (RxDB), trailBaseCollectionOptions (TrailBase), - localOnlyCollectionOptions, localStorageCollectionOptions, - indexedDBCollectionOptions. CollectionConfig + supabaseCollectionOptions (Supabase), localOnlyCollectionOptions, + localStorageCollectionOptions, indexedDBCollectionOptions. CollectionConfig options: getKey, schema, sync, gcTime, autoIndex (default off), defaultIndexType, syncMode (eager/on-demand, plus progressive for Electric). StandardSchema validation with Zod/Valibot/ArkType. Collection lifecycle (idle/loading/ready/error). @@ -25,6 +25,7 @@ sources: - 'TanStack/db:docs/collections/rxdb-collection.md' - 'TanStack/db:docs/collections/trailbase-collection.md' - 'TanStack/db:docs/collections/indexed-db-collection.md' + - 'TanStack/db:docs/collections/supabase-collection.md' - 'TanStack/db:packages/db/src/collection/index.ts' --- @@ -87,6 +88,7 @@ const todoCollection = createCollection( | PowerSync (SQLite offline) | `powerSyncCollectionOptions` | `@tanstack/powersync-db-collection` | | RxDB (reactive database) | `rxdbCollectionOptions` | `@tanstack/rxdb-db-collection` | | TrailBase (event streaming) | `trailBaseCollectionOptions` | `@tanstack/trailbase-db-collection` | +| Supabase (Postgres + Realtime) | `supabaseCollectionOptions` | `@tanstack/supabase-db-collection` | | No backend (UI state) | `localOnlyCollectionOptions` | `@tanstack/db` | | Browser localStorage | `localStorageCollectionOptions` | `@tanstack/db` | | Browser IndexedDB | `indexedDBCollectionOptions` | `@tanstack/db` | @@ -464,6 +466,7 @@ Source: docs/collections/query-collection.md - [PowerSync adapter](references/powersync-adapter.md) - [RxDB adapter](references/rxdb-adapter.md) - [TrailBase adapter](references/trailbase-adapter.md) +- [Supabase adapter](references/supabase-adapter.md) - [Local adapters (local-only, localStorage)](references/local-adapters.md) - [Schema validation patterns](references/schema-patterns.md) diff --git a/packages/db/skills/db-core/collection-setup/references/supabase-adapter.md b/packages/db/skills/db-core/collection-setup/references/supabase-adapter.md new file mode 100644 index 0000000000..aeb0aa249a --- /dev/null +++ b/packages/db/skills/db-core/collection-setup/references/supabase-adapter.md @@ -0,0 +1,118 @@ +# Supabase Adapter Reference + +## Install + +```bash +pnpm add @tanstack/supabase-db-collection @tanstack/react-db @tanstack/query-core @supabase/supabase-js +``` + +## Required Config + +```typescript +import { createCollection } from '@tanstack/react-db' +import { supabaseCollectionOptions } from '@tanstack/supabase-db-collection' +import { createClient } from '@supabase/supabase-js' +import { z } from 'zod' + +const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY) + +const todoSchema = z.object({ + id: z.string(), + title: z.string(), + completed: z.boolean(), +}) + +const todosCollection = createCollection( + supabaseCollectionOptions({ + tableName: 'todos', + keys: ['id'], + schema: todoSchema, + supabase, + }), +) +``` + +- `tableName` -- Postgres table name (PostgREST endpoint); also used as the collection id +- `keys` -- column(s) that uniquely identify a row; match the primary key(s). Composite keys are joined with `-` to form the collection key +- `schema` -- Standard Schema (Zod, Valibot, ...) describing one row +- `supabase` -- `SupabaseClient` used for queries, mutations, and Realtime + +## Optional Config + +| Option | Default | Description | +| ------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `syncMode` | `'on-demand'` | `'on-demand'` loads only what live queries need (pushes where/orderBy/limit to PostgREST); `'eager'` loads the whole table, paging past `db-max-rows` | +| `realtime` | `false` | Subscribe to Postgres changes and reconcile other clients' inserts/updates/deletes | +| `realtimeUseFilter` | `false` | Experimental. Push each query's WHERE to Realtime as a `postgres_changes` filter to cut message volume | +| `queryClient` | shared global | TanStack Query client used for the cache | + +## Real-time Subscriptions + +Add the table to the `supabase_realtime` publication first: + +```sql +alter publication supabase_realtime add table "public"."todos"; +``` + +Then set `realtime: true`. RLS applies to Realtime. Without RLS every change is broadcast to every client. Realtime can consume more messages than expected; test with a spend cap. + +## Persistence Handlers + +The adapter owns `onInsert`, `onUpdate`, and `onDelete`: they write through PostgREST (`POST`/`PATCH`/`DELETE`, matching on the `keys` columns), write the server-returned row back into the collection, and roll back the optimistic change if the server rejects it. Custom mutation handlers are not part of the options. + +## Query Pushdown + +Pushed to PostgREST: `where` (`eq`, `gt`, `gte`, `lt`, `lte`, `inArray`, `like`, `ilike`, `not`, `isNull`, `and`, `or`), `orderBy` on source columns, `limit`, and join keys (`in` filter). Evaluated client-side: computed selects, aggregates, `groupBy`, `having`, `distinct`. Reads page past PostgREST's `db-max-rows` (1000 by default) with `offset`; order by a unique column when a collection may exceed the cap. + +## queryOnce + +```typescript +import { eq } from '@tanstack/react-db' +import { queryOnce } from '@tanstack/supabase-db-collection' + +const completed = await queryOnce( + (q) => + q + .from({ todo: todosCollection }) + .where(({ todo }) => eq(todo.completed, true)), + supabase, +) +``` + +One-shot, non-reactive fetch. Aggregates (`count`, `sum`, `avg`, `min`, `max`) and `groupBy`/`having` run server-side in a single, non-paginated request. + +## Complete Example + +```tsx +import { createCollection, useLiveQuery, eq } from '@tanstack/react-db' +import { supabaseCollectionOptions } from '@tanstack/supabase-db-collection' + +const todosCollection = createCollection( + supabaseCollectionOptions({ + tableName: 'todos', + keys: ['id'], + schema: todoSchema, + supabase, + syncMode: 'on-demand', + realtime: true, + }), +) + +function Todos() { + const { data } = useLiveQuery((q) => + q + .from({ todo: todosCollection }) + .where(({ todo }) => eq(todo.completed, false)), + ) + + const add = (title: string) => + todosCollection.insert({ id: crypto.randomUUID(), title, completed: false }) + + const complete = (id: string) => + todosCollection.update(id, (draft) => { + draft.completed = true + }) + + // ... +} +``` diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index cc4ffc37af..5b3cd6fbc5 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -133,6 +133,18 @@ await generateReferenceDocs({ ), exclude: [`packages/db/**/*`], }, + { + name: `supabase-db-collection`, + entryPoints: [ + resolve(__dirname, `../packages/supabase-db-collection/src/index.ts`), + ], + tsconfig: resolve( + __dirname, + `../packages/supabase-db-collection/tsconfig.docs.json`, + ), + outputDir: resolve(__dirname, `../docs/reference/supabase-db-collection`), + exclude: [`packages/db/**/*`], + }, { name: `vue-db`, entryPoints: [resolve(__dirname, `../packages/vue-db/src/index.ts`)], From 99abc713198ccd6563ce94e45e498bf751ed3147 Mon Sep 17 00:00:00 2001 From: Ivan Vasilov Date: Wed, 11 Nov 2026 14:49:33 +0100 Subject: [PATCH 13/13] docs(supabase-db-collection): match the docs to the code and publish the package Updates the imported docs to the code in #2376 and #2412: - `experimental_queryOnce` runs only aggregate-only `count`, `sum`, and `avg` on the server, needs `pgrst.db_aggregates_enabled`, and otherwise runs through TanStack DB's `queryOnce`; - collection keys are string forms, and composite keys are JSON arrays; - document `defaultStringCollation`, the `queryClient` default, and use with `DbClient`, replacing the stale "no SSR" note; - React examples use the 1.0 RC `useLiveQuery({ query })` API; - add a section on migrating from `@supabase-labs/tanstack-db`. Removes `private: true` and joins the 1.0 RC line: the package starts at 1.0.0-rc.0 in `pre.json`, and its minor changeset versions it to 1.0.0-rc.1. Co-Authored-By: Claude Opus 5.5 (1M context) --- .changeset/add-supabase-db-collection.md | 4 +- .changeset/pre.json | 1 + docs/collections/supabase-collection.md | 117 ++++++++++++++---- domain_map.yaml | 2 +- .../references/supabase-adapter.md | 67 +++++++--- packages/supabase-db-collection/package.json | 3 +- 6 files changed, 146 insertions(+), 48 deletions(-) diff --git a/.changeset/add-supabase-db-collection.md b/.changeset/add-supabase-db-collection.md index e015b62f77..657bc8f933 100644 --- a/.changeset/add-supabase-db-collection.md +++ b/.changeset/add-supabase-db-collection.md @@ -2,4 +2,6 @@ '@tanstack/supabase-db-collection': minor --- -Add `@tanstack/supabase-db-collection`, a collection for syncing TanStack DB with Supabase through PostgREST queries, optimistic mutations, and Realtime subscriptions. Migrated from `@supabase-labs/tanstack-db@0.1.0` ([supabase/tanstack-db@3503c451](https://github.com/supabase/tanstack-db/commit/3503c451b2f2550ab4069067673881f39342b588)). Adds a `syncMode` option (`'on-demand'` by default, or `'eager'` to load the whole table). +Add `@tanstack/supabase-db-collection`, a collection that syncs TanStack DB with Supabase through PostgREST queries, optimistic mutations, and Realtime subscriptions. It replaces `@supabase-labs/tanstack-db@0.1.0` ([supabase/tanstack-db@3503c451](https://github.com/supabase/tanstack-db/commit/3503c451b2f2550ab4069067673881f39342b588)). + +Compared with that package, it adds a `syncMode` option (`'on-demand'` by default, or `'eager'` to load the whole table), `parse` and `serialize` column conversions, a `defaultStringCollation` option, and materialization from a `DbClient`. Composite collection keys are now JSON arrays. `queryOnce` is now `experimental_queryOnce`, which runs only `count`, `sum`, and `avg` of plain columns on the server and always resolves to TanStack DB's `queryOnce` result. diff --git a/.changeset/pre.json b/.changeset/pre.json index b0c1ce4f14..d84538bfde 100644 --- a/.changeset/pre.json +++ b/.changeset/pre.json @@ -36,6 +36,7 @@ "@tanstack/react-router-with-db": "1.0.0-rc.0", "@tanstack/rxdb-db-collection": "1.0.0-rc.0", "@tanstack/solid-db": "1.0.0-rc.0", + "@tanstack/supabase-db-collection": "1.0.0-rc.0", "@tanstack/svelte-db": "1.0.0-rc.0", "@tanstack/tauri-db-sqlite-persistence": "1.0.0-rc.0", "@tanstack/tauri-db-sqlite-persistence-e2e-app": "0.0.49", diff --git a/docs/collections/supabase-collection.md b/docs/collections/supabase-collection.md index 22c2d829de..1889e1c735 100644 --- a/docs/collections/supabase-collection.md +++ b/docs/collections/supabase-collection.md @@ -21,8 +21,6 @@ The `@tanstack/supabase-db-collection` package allows you to create collections Collections work with your Supabase project as it is and respect Row Level Security. Your Supabase database remains the source of truth: Postgres, RLS, Auth, and the rest of your stack stay unchanged, and no migration is required. -Collections fetch on the client. TanStack DB does not yet support server-side rendering (SSR), so collections should not be used to render on the server. - To see a working app, open the [example Todo app](https://todomvc-supabase-tanstack-db.vercel.app/). ## Installation @@ -87,13 +85,12 @@ import { useLiveQuery, eq } from '@tanstack/react-db' import { todosCollection } from './collections' function Todos() { - const { data: todos, isLoading } = useLiveQuery( - (q) => + const { data: todos, isLoading } = useLiveQuery({ + query: (q) => q .from({ todo: todosCollection }) .where(({ todo }) => eq(todo.completed, false)), - [] // re-run the query when these dependencies change - ) + }) // These apply instantly in the UI and roll back if the server rejects them const insertTodo = (title: string) => { @@ -137,7 +134,7 @@ The `supabaseCollectionOptions` function accepts the following options: - `tableName`: Name of the Postgres table. Maps to the PostgREST endpoint - `schema`: [Standard Schema](https://standardschema.dev) compatible schema (e.g., Zod, Valibot) describing a single row -- `keys`: Column or columns that uniquely identify a row. Should match the primary key(s) on your table. Used to derive the collection key and to match rows on update and delete. With a single column, the collection key is that column's value; with several, the values are joined with `-` +- `keys`: Column or columns that uniquely identify a row. Should match the primary key(s) on your table. Used to derive the collection key and to match rows on update and delete. The collection key is built from the string form of each key column. With a single column, it is that value as a string, so `6` becomes `'6'`. With several columns, it is a JSON array of those strings, such as `'["a","b"]'`. Pass this key to `get`, `update`, and `delete` - `supabase`: Supabase client instance used for queries, mutations, and the Realtime subscription ### Optional Options @@ -147,7 +144,8 @@ The `supabaseCollectionOptions` function accepts the following options: | `syncMode` | `'on-demand'` \| `'eager'` | `'on-demand'` | Controls what is loaded into the collection. `'on-demand'` loads only the rows that live queries need, pushing `where`, `orderBy`, and `limit` to PostgREST. `'eager'` loads the whole table up front, paging past the PostgREST row cap, and evaluates queries against the local copy. See [How Sync Works](#how-sync-works). | | `realtime` | `boolean` | `false` | When `true`, subscribes to Postgres changes and reconciles inserts, updates, and deletes from other clients into the collection. | | `realtimeUseFilter` | `boolean` | `false` | **Experimental.** Only applies when `realtime` is `true`. When `true`, each active query's `WHERE` clause is pushed to the Realtime subscription as a `postgres_changes` filter, so the channel only receives changes those queries care about. When `false`, the collection subscribes to every change on the table and filters client-side. Queries whose `WHERE` cannot be expressed as a Realtime filter (e.g. `or(...)`) transparently fall back to the unfiltered subscription. | -| `queryClient` | `QueryClient` | shared client | TanStack Query client. If omitted, a shared global client is used. | +| `queryClient` | `QueryClient` | shared client | TanStack Query client. If omitted, the browser uses one shared client and the server creates a new client for each collection. When a [`DbClient`](#use-with-dbclient) materializes the collection, the client's `queryClient` dependency is used instead. | +| `defaultStringCollation` | `StringCollationConfig` | TanStack DB default | Controls how string columns are compared when ordering, so the local order can match your database collation. `StringCollationConfig` is exported by `@tanstack/db`. | | `parse` | `{ [column]: (value) => … }` | none | Converts a column value received from PostgREST or Realtime into the value your schema describes. PostgREST speaks JSON, so a `timestamptz` arrives as a string: use `parse` to turn it into a `Date`. Applies to rows read, rows returned by inserts and updates, and Realtime payloads. Not called for `null` values. | | `serialize` | `{ [column]: (value) => … }` | none | The reverse of `parse`: converts a column value held by the collection into the JSON value sent to PostgREST in insert and update bodies, and used to match rows by key on update and delete. Not called for `null` values. | @@ -196,16 +194,14 @@ Most query operations are translated to PostgREST filters and run server-side. A These operations fetch the required rows and process them in memory: - `SELECT` column subsets, renaming, and computed fields (`upper`, `lower`, `concat`, `length`, `add`, `coalesce`) -- Aggregate functions: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` (except when using [`queryOnce`](#queryonce)) +- Aggregate functions: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` (except an aggregate-only `COUNT`, `SUM`, and `AVG` in [`experimental_queryOnce`](#experimental_queryonce)) - `GROUP BY` and `HAVING` - `DISTINCT` - `ORDER BY` on computed fields ### Row cap and pagination -PostgREST caps every response at its `db-max-rows` setting (1000 by default on Supabase). Collection reads and non-aggregate `queryOnce` queries page past this cap automatically: the adapter loops with `offset`, using a one-time `count=exact` on the first request to fetch the complete matching set (or the caller's `limit`). - -The aggregate / `GROUP BY` / `HAVING` path of `queryOnce` is the one exception. It issues a single request and is **not** paginated. Aggregate results are a few rows, so the cap is moot, but a `GROUP BY` / `HAVING` query whose grouped output exceeds `db-max-rows` is silently truncated at the cap. Add an explicit `limit`, or narrow the query, if you expect more grouped rows than the cap. +PostgREST caps every response at its `db-max-rows` setting (1000 by default on Supabase). Collection reads, including those made by [`experimental_queryOnce`](#experimental_queryonce), page past this cap automatically: the adapter loops with `offset`, using a one-time `count=exact` on the first request to fetch the complete matching set (or the caller's `limit`). Known limitations of the paging loop: @@ -231,7 +227,7 @@ const todosCollection = createCollection( ) ``` -Row Level Security applies to Realtime, so clients only receive changes they are allowed to read. A server-side Supabase client has no Realtime channel, so `realtime` is a no-op there. +Row Level Security applies to Realtime, so clients only receive changes they are allowed to read. If the Supabase client has no `channel` method, `realtime` is a no-op. Known limitation: the initial fetch does not wait for the Realtime channel to finish subscribing. A row written in the window between the fetch and the subscription going live can be missed by both. @@ -254,31 +250,91 @@ todosCollection.update(todoId, (draft) => { See [Optimistic Mutations](../guides/mutations.md) for more on mutation lifecycles, transactions, and error handling. -## queryOnce +## Use with `DbClient` -`queryOnce(callback, supabase)` runs a TanStack DB query once against Supabase and resolves with the result. It is non-reactive: it issues the needed requests and does not subscribe to changes. Use it for one-shot fetches such as API routes or form submissions where live updates are not needed. +A `DbClient` gives each request, test, or tenant its own collections and its own `QueryClient`. Wrap the options in `collectionOptions` to create a descriptor, then materialize it from a client. A Supabase collection reads through the client's `queryClient` dependency, so its queries live in that client's cache. ```typescript -import { eq } from '@tanstack/react-db' -import { queryOnce } from '@tanstack/supabase-db-collection' +import { QueryClient } from '@tanstack/query-core' +import { DbClient, collectionOptions } from '@tanstack/db' +import { supabaseCollectionOptions } from '@tanstack/supabase-db-collection' + +export const todosDescriptor = collectionOptions( + supabaseCollectionOptions({ + tableName: 'todos', + schema: todoSchema, + keys: ['id'], + supabase, + }) +) + +export function createRequestClients() { + const queryClient = new QueryClient() + const dbClient = new DbClient({ queryClient }) + return { queryClient, dbClient } +} + +const { dbClient } = createRequestClients() +const todos = dbClient.collection(todosDescriptor) +await todos.preload() +``` + +`dbClient.collection(descriptor)` returns one collection per descriptor and client. A second `DbClient` materializes its own collection with its own `QueryClient`. See [Request-scoped QueryClient](./query-collection.md#request-scoped-queryclient) and [SSR and Hydration](../guides/ssr.md) for how descriptors and clients fit together. + +## experimental_queryOnce -const completedTodos = await queryOnce( +`experimental_queryOnce(callback, supabase)` runs a TanStack DB query once against Supabase and resolves with the result. It is non-reactive: it does not subscribe to changes. Use it for one-shot fetches such as API routes or form submissions where live updates are not needed. + +It is experimental because it reads TanStack DB's internal query representation, which can change between releases. + +```typescript +import { count, eq } from '@tanstack/db' +import { experimental_queryOnce } from '@tanstack/supabase-db-collection' + +const [summary] = await experimental_queryOnce( (q) => q .from({ todo: todosCollection }) - .where(({ todo }) => eq(todo.completed, true)), + .where(({ todo }) => eq(todo.completed, true)) + .select(({ todo }) => ({ completed: count(todo.id) })), supabase ) + +// `summary` is undefined when no todo matches +const completedCount = summary?.completed ?? 0 ``` - `callback`: Builds the query using the same API as `useLiveQuery` -- `supabase`: Supabase client used to execute the request +- `supabase`: Supabase client used to run the server request described below + +It returns a `Promise` that resolves to exactly what TanStack DB's own `queryOnce` resolves to for the same query, typed from the query you built. + +### Server aggregates + +When the query only computes `count`, `sum`, or `avg`, the server computes it in a single PostgREST request. This applies when all of these are true: + +- the source is a Supabase collection, or a subquery that only filters one +- the `select` holds only `count`, `sum`, or `avg` of a single plain column +- a `sum` or `avg` is not over a column read through `parse` +- every `WHERE` expression can be pushed to PostgREST +- the query has no `groupBy`, `having`, join, `orderBy`, `limit`, `offset`, `distinct`, or functional clause -It returns a `Promise` that resolves to the query result, typed from the query you built. +This path needs PostgREST aggregate functions, which are off by default. Enable them once per project: -Filters, ordering, `limit`, `offset`, joins, and aggregate functions (`count`, `sum`, `avg`, `min`, `max`) are pushed to PostgREST. Operations that cannot be pushed fall back to fetching matching rows and processing them client-side. Fallback operations include `GROUP BY`, `HAVING`, `DISTINCT`, and computed `SELECT` expressions. +```sql +alter role authenticator set pgrst.db_aggregates_enabled = 'true'; +notify pgrst, 'reload config'; +``` + +The result follows TanStack DB's aggregate rules, not SQL's: + +- A query that matches no rows resolves to `[]`, or to `undefined` with `findOne`. +- A `sum` over only `null` values is `0`. +- An `avg` divides the sum by the number of matching rows, including rows where the value is `null`. + +### Everything else -The client-side filter fallback applies to live queries and ordinary `queryOnce` queries. The server aggregate path in `queryOnce` requires fully pushable `WHERE` expressions and throws for unsupported filters, rather than returning an aggregate over unfiltered rows. +Any other query, including `min`, `max`, `groupBy`, and `having`, runs through TanStack DB's `queryOnce` over the collections. Their loads push filters, ordering, and `limit` to PostgREST, and the remaining operations run client-side. The `supabase` argument is not used on this path. ## Complete Example @@ -316,14 +372,13 @@ export const todosCollection = createCollection( // Use in a component function TodoList() { - const { data: todos, isLoading } = useLiveQuery( - (q) => + const { data: todos, isLoading } = useLiveQuery({ + query: (q) => q .from({ todo: todosCollection }) .where(({ todo }) => eq(todo.completed, false)) .orderBy(({ todo }) => todo.title, 'asc'), - [] - ) + }) const addTodo = (title: string) => { const todo: Todo = { id: crypto.randomUUID(), title, completed: false } @@ -363,6 +418,14 @@ function TodoList() { } ``` +## Migrating from `@supabase-labs/tanstack-db` + +- **Package name.** Replace `@supabase-labs/tanstack-db` with `@tanstack/supabase-db-collection`. +- **`queryOnce`.** It is now `experimental_queryOnce`. Its server path is narrower: only `count`, `sum`, and `avg` of plain columns run on the server. Everything else runs through TanStack DB's `queryOnce`. See [experimental_queryOnce](#experimental_queryonce). +- **Composite keys.** A collection key for several `keys` columns is now a JSON array of strings such as `'["a","b"]'`, not a `-` join. Update any code that builds a key by hand for `get`, `update`, or `delete`. +- **`syncMode`.** New option. The default, `'on-demand'`, keeps the old loading behavior. Set `syncMode: 'eager'` to load the whole table up front. +- **React hooks.** `useLiveQuery` takes `{ query }` and no dependency arrays. See the [1.0 RC migration guide](../guides/migrate-to-1-0-rc.md#update-react-live-query-hooks). + ## FAQ **Will this work with my RLS policies?** diff --git a/domain_map.yaml b/domain_map.yaml index b830e98ff5..0751efa0c2 100644 --- a/domain_map.yaml +++ b/domain_map.yaml @@ -95,7 +95,7 @@ skills: config_surface: 'recordApi, conversions' - name: 'Supabase adapter' package: '@tanstack/supabase-db-collection' - config_surface: 'tableName, keys, schema, supabase, queryClient, realtime, realtimeUseFilter, syncMode (on-demand default/eager)' + config_surface: 'tableName, keys, schema, supabase, queryClient, realtime, realtimeUseFilter, syncMode (on-demand default/eager), defaultStringCollation, parse, serialize' - name: 'Local-only' package: '@tanstack/db' config_surface: 'getKey, schema, initialData' diff --git a/packages/db/skills/db-core/collection-setup/references/supabase-adapter.md b/packages/db/skills/db-core/collection-setup/references/supabase-adapter.md index aeb0aa249a..37f569fe79 100644 --- a/packages/db/skills/db-core/collection-setup/references/supabase-adapter.md +++ b/packages/db/skills/db-core/collection-setup/references/supabase-adapter.md @@ -33,18 +33,20 @@ const todosCollection = createCollection( ``` - `tableName` -- Postgres table name (PostgREST endpoint); also used as the collection id -- `keys` -- column(s) that uniquely identify a row; match the primary key(s). Composite keys are joined with `-` to form the collection key +- `keys` -- column(s) that uniquely identify a row; match the primary key(s). The collection key is the column value as a string (`6` becomes `'6'`); composite keys are a JSON array of the string values, such as `'["a","b"]'`. Pass that key to `get`, `update`, and `delete` - `schema` -- Standard Schema (Zod, Valibot, ...) describing one row - `supabase` -- `SupabaseClient` used for queries, mutations, and Realtime ## Optional Config -| Option | Default | Description | -| ------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `syncMode` | `'on-demand'` | `'on-demand'` loads only what live queries need (pushes where/orderBy/limit to PostgREST); `'eager'` loads the whole table, paging past `db-max-rows` | -| `realtime` | `false` | Subscribe to Postgres changes and reconcile other clients' inserts/updates/deletes | -| `realtimeUseFilter` | `false` | Experimental. Push each query's WHERE to Realtime as a `postgres_changes` filter to cut message volume | -| `queryClient` | shared global | TanStack Query client used for the cache | +| Option | Default | Description | +| ------------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `syncMode` | `'on-demand'` | `'on-demand'` loads only what live queries need (pushes where/orderBy/limit to PostgREST); `'eager'` loads the whole table, paging past `db-max-rows` | +| `realtime` | `false` | Subscribe to Postgres changes and reconcile other clients' inserts/updates/deletes | +| `realtimeUseFilter` | `false` | Experimental. Push each query's WHERE to Realtime as a `postgres_changes` filter to cut message volume | +| `queryClient` | shared client | TanStack Query client used for the cache. Shared in the browser, new per call on the server; a `DbClient`'s `queryClient` dependency takes precedence | +| `defaultStringCollation` | TanStack DB default | `StringCollationConfig` from `@tanstack/db`; orders strings to match the database collation | +| `parse` / `serialize` | none | Per-column converters between PostgREST JSON and the schema type (e.g. `timestamptz` string to `Date`); skipped for `null` | ## Real-time Subscriptions @@ -62,15 +64,15 @@ The adapter owns `onInsert`, `onUpdate`, and `onDelete`: they write through Post ## Query Pushdown -Pushed to PostgREST: `where` (`eq`, `gt`, `gte`, `lt`, `lte`, `inArray`, `like`, `ilike`, `not`, `isNull`, `and`, `or`), `orderBy` on source columns, `limit`, and join keys (`in` filter). Evaluated client-side: computed selects, aggregates, `groupBy`, `having`, `distinct`. Reads page past PostgREST's `db-max-rows` (1000 by default) with `offset`; order by a unique column when a collection may exceed the cap. +Pushed to PostgREST: `where` (`eq`, `gt`, `gte`, `lt`, `lte`, `inArray`, `like`, `ilike`, `not`, `isNull`, `and`, `or`), `orderBy` on source columns, `limit`, and join keys (`in` filter). Evaluated client-side: computed selects, aggregates, `groupBy`, `having`, `distinct`, except an aggregate-only `count`/`sum`/`avg` in `experimental_queryOnce`. Reads page past PostgREST's `db-max-rows` (1000 by default) with `offset`; a multi-page read also orders by the `keys` columns so the pages form one sequence. -## queryOnce +## experimental_queryOnce ```typescript import { eq } from '@tanstack/react-db' -import { queryOnce } from '@tanstack/supabase-db-collection' +import { experimental_queryOnce } from '@tanstack/supabase-db-collection' -const completed = await queryOnce( +const completed = await experimental_queryOnce( (q) => q .from({ todo: todosCollection }) @@ -79,7 +81,37 @@ const completed = await queryOnce( ) ``` -One-shot, non-reactive fetch. Aggregates (`count`, `sum`, `avg`, `min`, `max`) and `groupBy`/`having` run server-side in a single, non-paginated request. +One-shot, non-reactive fetch. It always resolves to what TanStack DB's `queryOnce` returns, and it is experimental because it reads TanStack DB's internal query IR. + +A query runs as one PostgREST request only when its select holds just `count`, `sum`, or `avg` of a plain column of one Supabase table (not `sum`/`avg` over a `parse` column), every filter can be pushed, and it has no `groupBy`, `having`, join, `orderBy`, `limit`, `offset`, `distinct`, or functional clause. That path needs PostgREST aggregates: + +```sql +alter role authenticator set pgrst.db_aggregates_enabled = 'true'; +notify pgrst, 'reload config'; +``` + +Every other query, including `min`, `max`, `groupBy`, and `having`, runs through TanStack DB's `queryOnce` over the collections, which push filters, order, and limit to PostgREST. TanStack DB's aggregate rules apply: an empty match gives `[]` (`undefined` for `findOne`), and an all-null `sum` gives `0`. + +## Use with DbClient + +Under a `DbClient`, wrap the options in `collectionOptions` and materialize with `dbClient.collection`. The client's `queryClient` dependency is used for the cache. + +```typescript +import { QueryClient } from '@tanstack/query-core' +import { DbClient, collectionOptions } from '@tanstack/db' + +const todosDescriptor = collectionOptions( + supabaseCollectionOptions({ + tableName: 'todos', + keys: ['id'], + schema: todoSchema, + supabase, + }), +) + +const dbClient = new DbClient({ queryClient: new QueryClient() }) +const todos = dbClient.collection(todosDescriptor) +``` ## Complete Example @@ -99,11 +131,12 @@ const todosCollection = createCollection( ) function Todos() { - const { data } = useLiveQuery((q) => - q - .from({ todo: todosCollection }) - .where(({ todo }) => eq(todo.completed, false)), - ) + const { data } = useLiveQuery({ + query: (q) => + q + .from({ todo: todosCollection }) + .where(({ todo }) => eq(todo.completed, false)), + }) const add = (title: string) => todosCollection.insert({ id: crypto.randomUUID(), title, completed: false }) diff --git a/packages/supabase-db-collection/package.json b/packages/supabase-db-collection/package.json index aa6685ff83..598cc40365 100644 --- a/packages/supabase-db-collection/package.json +++ b/packages/supabase-db-collection/package.json @@ -1,7 +1,6 @@ { "name": "@tanstack/supabase-db-collection", - "private": true, - "version": "0.0.0", + "version": "1.0.0-rc.0", "description": "Supabase collection for TanStack DB", "author": "Supabase ", "license": "MIT",