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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/paginated-query-errors.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
'convex-svelte': patch
---

### Fixes

- **Failed paginated queries no longer throw during setup** ([#61](https://github.com/get-convex/convex-svelte/issues/61)) - the Convex client throws from `getCurrentValue()` once a page has failed, and from `onPaginatedUpdate_experimental()` when another subscriber already holds the query in a failed state. `usePaginatedQuery`, `convexLoadPaginated` and `createDetachedPaginatedQuery` now report these errors through `error` instead of throwing, and always clean up their subscription.
- **`InvalidCursor` no longer resets forever** ([#61](https://github.com/get-convex/convex-svelte/issues/61)) - a paginated query resets once on `InvalidCursor`. If the cursor fails again before a page arrived, the error is shown instead of resetting in a loop. A loaded page, changed args or `reset()` allow the next reset.
- **`convexLoadPaginated` recovers from `InvalidCursor`** - it reset its state but never resubscribed, so it stayed in `LoadingFirstPage`. It now starts a fresh subscription, and a load waiting for its first page keeps waiting for it.
58 changes: 58 additions & 0 deletions src/lib/shared/paginated_query_state.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -230,3 +230,61 @@ describe('PaginatedQueryStateMachine keepPreviousData', () => {
});
});
});

describe('PaginatedQueryStateMachine InvalidCursor reset limit (#61)', () => {
const invalidCursor = () => new Error('InvalidCursor: the cursor is no longer valid');
const loadMore = () => false;

function machineWithArgs() {
const machine = new PaginatedQueryStateMachine<string>({ initialNumItems: 3 });
machine.onArgsChange('{}');
return machine;
}

it('resets once, then surfaces a repeated InvalidCursor as the error', () => {
const machine = machineWithArgs();

expect(machine.onError(invalidCursor())).toBe(true);
const afterReset = machine.getSnapshot();
expect(afterReset).toMatchObject({ status: 'LoadingFirstPage', error: undefined });

// The resubscription only reports its empty loading snapshot, then fails again.
machine.onUpdate({ results: [], status: 'LoadingFirstPage', loadMore });
expect(machine.onError(invalidCursor())).toBe(false);

expect(machine.getSnapshot()).toMatchObject({
isLoading: false,
resetKey: afterReset.resetKey
});
expect(machine.getSnapshot().error?.message).toContain('InvalidCursor');
});

it('surfaces an InvalidCursor without resetting when allowReset is false', () => {
const machine = machineWithArgs();
const before = machine.getSnapshot().resetKey;

expect(machine.onError(invalidCursor(), { allowReset: false })).toBe(false);

expect(machine.getSnapshot().resetKey).toBe(before);
expect(machine.getSnapshot().error?.message).toContain('InvalidCursor');
});

it('allows another reset once a page arrived', () => {
const machine = machineWithArgs();
machine.onError(invalidCursor());

machine.onUpdate({ results: ['a'], status: 'CanLoadMore', loadMore });

expect(machine.onError(invalidCursor())).toBe(true);
});

it('allows another reset after the args changed or after reset()', () => {
const machine = machineWithArgs();
machine.onError(invalidCursor());
machine.onArgsChange('{"other":true}');
expect(machine.onError(invalidCursor())).toBe(true);

machine.reset();
expect(machine.onError(invalidCursor())).toBe(true);
});
});
21 changes: 19 additions & 2 deletions src/lib/shared/paginated_query_state.ts
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,13 @@ export class PaginatedQueryStateMachine<T> {
* before the first server update). Flushed by `onUpdate`.
*/
private pendingLoadMoreNumItems: number | null = null;
/**
* Whether the next InvalidCursor may reset pagination. Disarmed by a reset
* and re-armed by a real result, changed args or `reset()`: if the cursor
* keeps failing (e.g. another subscriber holds the failed query alive), the
* second InvalidCursor is surfaced as an error instead of resetting forever.
*/
private invalidCursorResetArmed = true;

constructor(config: PaginatedQueryConfig<T>) {
this.config = config;
Expand Down Expand Up @@ -244,6 +251,7 @@ export class PaginatedQueryStateMachine<T> {
this.state.argsKey = newArgsKey;
// A queued loadMore belongs to the previous args — drop it.
this.pendingLoadMoreNumItems = null;
this.invalidCursorResetArmed = true;

// Track when args change from initial
if (!this.state.haveArgsEverChanged && this.state.initialArgsKey !== newArgsKey) {
Expand Down Expand Up @@ -297,6 +305,10 @@ export class PaginatedQueryStateMachine<T> {
* "empty loading" snapshot to keep SSR-rendered content visible.
*/
onUpdate(update: PaginatedQueryUpdate<T>): void {
// A page arrived: the cursor works again. The empty loading snapshot right
// after a reset must not re-arm, or a persistent InvalidCursor loops.
if (update.status !== 'LoadingFirstPage') this.invalidCursorResetArmed = true;

// Hydration guard: if using initial data, ignore empty loading snapshots
// This keeps SSR-rendered content visible until real data arrives.
// Checked before keepPreviousData: SSR data is not "previous" data, and
Expand Down Expand Up @@ -350,10 +362,14 @@ export class PaginatedQueryStateMachine<T> {
*
* Detects InvalidCursor errors and triggers a pagination reset.
*
* @param options.allowReset - `false` surfaces even an InvalidCursor as the
* error, e.g. when resubscribing can't help.
* @returns `true` if we detected and handled an InvalidCursor (framework should resubscribe)
*/
onError(error: Error): boolean {
if (this.isInvalidCursorError(error)) {
onError(error: Error, options: { allowReset?: boolean } = {}): boolean {
const allowReset = options.allowReset ?? true;
if (allowReset && this.isInvalidCursorError(error) && this.invalidCursorResetArmed) {
this.invalidCursorResetArmed = false;
console.warn('PaginatedQueryStateMachine: InvalidCursor detected, resetting:', error.message);
this.pendingLoadMoreNumItems = null;
this.state = {
Expand Down Expand Up @@ -384,6 +400,7 @@ export class PaginatedQueryStateMachine<T> {
*/
reset(): void {
this.pendingLoadMoreNumItems = null;
this.invalidCursorResetArmed = true;
this.state = {
...this.state,
results: [],
Expand Down
134 changes: 134 additions & 0 deletions src/lib/shared/paginated_subscription.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
import { describe, expect, it, vi } from 'vitest';
import { makeFunctionReference } from 'convex/server';
import { subscribePaginated } from './paginated_subscription.js';

// The Convex client can throw instead of calling onError (get-convex/convex-js#193):
// from getCurrentValue() for a failed page, and from onPaginatedUpdate_experimental()
// itself. Those errors must reach onError, and a cleanup must always come back.

const ref = makeFunctionReference<'query'>('messages:paginatedList');
const page = { results: [1], status: 'CanLoadMore' as const, loadMore: () => true };

function clientWith(
impl: (onUpdate: () => void, onError: (e: Error) => void) => ReturnType<typeof vi.fn>
) {
return {
onPaginatedUpdate_experimental: vi.fn(
(_q: unknown, _a: unknown, _o: unknown, onUpdate: () => void, onError: (e: Error) => void) =>
impl(onUpdate, onError)
)
} as never;
}

describe('subscribePaginated', () => {
it('reports a failed cached page instead of throwing, and still returns a cleanup', () => {
const unsubscribe = Object.assign(vi.fn(), {
getCurrentValue: () => {
throw new Error('page failed');
}
});
const onSnapshot = vi.fn();
const onError = vi.fn();

const cleanup = subscribePaginated(
clientWith(() => unsubscribe),
ref,
{},
10,
onSnapshot,
onError
);

expect(onError).toHaveBeenCalledWith(new Error('page failed'), true);
expect(onSnapshot).not.toHaveBeenCalled();
cleanup();
expect(unsubscribe).toHaveBeenCalledOnce();
});

it('reports an error thrown by onPaginatedUpdate_experimental itself, as not retryable', () => {
const onError = vi.fn();
const client = {
onPaginatedUpdate_experimental: vi.fn(() => {
throw new Error('failed page held by another subscriber');
})
} as never;

const cleanup = subscribePaginated(client, ref, {}, 10, vi.fn(), onError);

// Not retryable: the client registered the subscription before throwing and
// shares it per args, so a retry would fail the same way (convex-js#193).
expect(onError).toHaveBeenCalledWith(
new Error('failed page held by another subscriber'),
false
);
expect(() => cleanup()).not.toThrow();
});

it('reports a failed page that getCurrentValue() throws inside the update callback', () => {
let fail = false;
let notify = () => {};
const unsubscribe = Object.assign(vi.fn(), {
getCurrentValue: () => {
if (fail) throw new Error('page failed');
return undefined;
}
});
const onError = vi.fn();
subscribePaginated(
clientWith((onUpdate) => {
notify = onUpdate;
return unsubscribe;
}),
ref,
{},
10,
vi.fn(),
onError
);

fail = true;
notify();

expect(onError).toHaveBeenCalledWith(new Error('page failed'), true);
});

it('delivers a snapshot the client reports synchronously while subscribing, once', () => {
const unsubscribe = Object.assign(vi.fn(), { getCurrentValue: () => page });
const onSnapshot = vi.fn();

subscribePaginated(
clientWith((onUpdate) => {
onUpdate(); // before the subscription is returned
return unsubscribe;
}),
ref,
{},
10,
onSnapshot,
vi.fn()
);

expect(onSnapshot).toHaveBeenCalledOnce();
expect(onSnapshot).toHaveBeenCalledWith(page);
});

it('does not read the value after the client reported an error synchronously', () => {
const getCurrentValue = vi.fn(() => page);
const onError = vi.fn();

subscribePaginated(
clientWith((_onUpdate, reportError) => {
reportError(new Error('boom'));
return Object.assign(vi.fn(), { getCurrentValue });
}),
ref,
{},
10,
vi.fn(),
onError
);

expect(onError).toHaveBeenCalledOnce();
expect(getCurrentValue).not.toHaveBeenCalled();
});
});
82 changes: 82 additions & 0 deletions src/lib/shared/paginated_subscription.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
/**
* Safe subscription to a Convex paginated query, shared by `usePaginatedQuery`
* and the detached paginated query behind `convexLoadPaginated`.
*
* The Convex client can throw instead of calling `onError`: from
* `getCurrentValue()` once a page has failed, and from
* `onPaginatedUpdate_experimental()` itself when another subscriber already
* holds the query in a failed state (get-convex/convex-js#193). Thrown errors
* are reported through `onError` here, so callers always get a cleanup function
* back and their state machine sees the error.
*
* When `onPaginatedUpdate_experimental()` throws, the client has already
* registered the subscription but returned no handle to release it — only a
* fix in the client can roll that back (convex-js#193). Such errors are
* reported as not retryable: the client shares one paginated query per args, so
* a retry would hit the same failure and leave another registration behind.
*/
import type { ConvexClient, PaginationStatus } from 'convex/browser';
import type { FunctionArgs, FunctionReference } from 'convex/server';

/** One update of a paginated query, as delivered by the Convex client. */
export type PaginatedSnapshot = {
results: unknown[];
status: PaginationStatus;
loadMore: (numItems: number) => boolean;
};

const toError = (error: unknown) => (error instanceof Error ? error : new Error(String(error)));

/**
* Subscribe and report every snapshot or error. Returns a function that ends
* the subscription; safe to call when subscribing failed.
*/
export function subscribePaginated<Query extends FunctionReference<'query'>>(
client: Pick<ConvexClient, 'onPaginatedUpdate_experimental'>,
query: Query,
args: FunctionArgs<Query>,
initialNumItems: number,
onSnapshot: (snapshot: PaginatedSnapshot) => void,
onError: (error: Error, retryable: boolean) => void
): () => void {
let subscription: ReturnType<ConvexClient['onPaginatedUpdate_experimental']> | undefined;
let failed = false;

const read = () => {
let current: PaginatedSnapshot | undefined;
try {
current = subscription?.getCurrentValue() as PaginatedSnapshot | undefined;
} catch (error) {
failed = true;
onError(toError(error), true);
return;
}
if (current) onSnapshot(current);
};

try {
subscription = client.onPaginatedUpdate_experimental(
query,
args,
{ initialNumItems },
// A callback the client runs synchronously, before `subscription` is
// assigned, is covered by the read below.
() => {
if (subscription) read();
},
(error: Error) => {
failed = true;
onError(error, true);
}
);
} catch (error) {
onError(toError(error), false);
return () => {};
}

// Cached value of a query another subscriber already holds, or a snapshot
// delivered synchronously while subscribing.
if (!failed) read();

return () => subscription?.();
}
Loading
Loading