Class: ConvexPaginatedQueryNode<Query>#

Defined in: retree-convex/src/ConvexPaginatedQueryNode.ts:60

Reactive paginated query node that subscribes to a Convex paginated query and exposes the loaded pages as Retree state.

Remarks#

Use this directly or through ConvexNode.paginatedQuery for live paginated lists. New pages update state, result, and error, which can emit Retree changes and re-render React subscribers.

This class is a Convex adapter over the backend-agnostic QueryNode from @retreejs/query, sharing its status machine, args lifecycle, and optimistic-update machinery with ConvexQueryNode. Optimistic transforms run against the loaded state.results rows; rollback baselines clone the loaded rows while keeping the loadMore function by reference.

Dispose the node when its owner is torn down. Use "skip" when the query should be temporarily disabled.

Example#

const messages = new ConvexPaginatedQueryNode(client, api.messages.list, {
    args: { channelId: "general" },
    initialNumItems: 20,
});

Extends#

• BaseConvexQueryNode<PaginatedQueryArgs<Query>, RetreePaginatedQueryResult<PaginatedQueryItem<Query>>>

Type Parameters#

Constructors#

Constructor#

new ConvexPaginatedQueryNode<Query>(
   client, 
   query, ...
options): ConvexPaginatedQueryNode<Query>;

Defined in: retree-convex/src/ConvexPaginatedQueryNode.ts:97

Create a node for a Convex paginated query subscription.

Parameters#

Returns#

ConvexPaginatedQueryNode<Query>

Remarks#

The subscription starts when the node is observed by Retree. This avoids opening Convex subscriptions for paginated state nobody is currently rendering or listening to.

Example#

const messages = Retree.root(
    new ConvexPaginatedQueryNode(client, api.messages.list, {
        args: { channelId: "general" },
        initialNumItems: 20,
    })
);

Overrides#

BaseConvexQueryNode.constructor

Properties#

Accessors#

dependencies#

Get Signature#

get dependencies(): never[];

Defined in: retree-query/bin/QueryNode.d.ts:122

Dependencies to listen for changes to.

Remarks

When any IReactiveDependency criteria is met, a change will be emitted for this ReactiveNode instance.

Defaults to [] (no dependencies). Subclasses only override this getter when the node should emit for changes to other nodes; plain state classes need no dependencies boilerplate.

Keep this getter deterministic. Do not start subscriptions, perform network work, or mutate state here. Use ReactiveNode.onObserved, ReactiveNode.onUnobserved, and ReactiveNode.onChanged for lifecycle work.

The returned array may change length or ordering while the node is observed. Retree treats added, removed, or reordered entries as invalidation and refreshes subscriptions. Use null when you want an inactive slot to keep its position, but it is not required for correctness.

Example

class ProjectSummary extends ReactiveNode {
    public tasks: { done: boolean }[] = [];

    get doneCount() {
        return this.tasks.filter((task) => task.done).length;
    }

    get dependencies() {
        return [this.dependency(this.tasks, [this.doneCount])];
    }
}

Returns

never[]

Inherited from#

BaseConvexQueryNode.dependencies

queryNodeName#

Get Signature#

get protected queryNodeName(): string;

Defined in: retree-convex/src/ConvexPaginatedQueryNode.ts:115

Name used in error and warning messages so failures pinpoint the concrete node class. Subclasses override this with their class name.

Returns

string

Overrides#

BaseConvexQueryNode.queryNodeName

Methods#

action()#

protected action<Action>(action): RetreeConvexAction<Action>;

Defined in: retree-convex/src/BaseConvexQueryNode.ts:90

Create a typed action function bound to this node's Convex client.

Type Parameters#

Parameters#

Returns#

RetreeConvexAction<Action>

A typed action function.

Remarks#

Actions are imperative calls. They do not emit Retree changes unless you write their result into a Retree-managed field.

Inherited from#

BaseConvexQueryNode.action

cloneState()#

protected cloneState(state): ConvexPaginatedQueryNodeState<Query>;

Defined in: retree-convex/src/ConvexPaginatedQueryNode.ts:294

Clone paginated state for optimistic rollback baselines.

Parameters#

Returns#

ConvexPaginatedQueryNodeState<Query>

Remarks#

structuredClone throws on the loadMore function stored in paginated state, so this clones the loaded rows and pagination status while keeping loadMore by reference.

Overrides#

BaseConvexQueryNode.cloneState

dependency()#

Call Signature#

dependency<TNode>(node, comparisons?): IReactiveDependency<TNode>;

Defined in: retree-core/bin/ReactiveNode.d.ts:413

Creates a new IReactiveDependency instance.

Type Parameters

Parameters

Returns

IReactiveDependency<TNode>

dependency object.

Remarks

Use this inside the ReactiveNode.dependencies getter or an @select dependency selector when one slot needs explicit comparison cells. If node is a Retree-managed object, it is observed with nodeChanged. If node is a primitive or unproxied value, Retree treats it as a comparison-only dependency.

Comparison cells should be deterministic. If their length/order changes, Retree treats that as invalidation and emits for this node. If no comparisons are provided, every nodeChanged event from the dependency emits for this node.

Example

get dependencies() {
    return [
        this.authStore,
        this.authStore.session?.userId,
        this.dependency(this.selectedProject ?? null, [this.projectId]),
    ];
}

Inherited from

BaseConvexQueryNode.dependency

Call Signature#

dependency<TValue>(value): IReactiveDependency;

Defined in: retree-core/bin/ReactiveNode.d.ts:414

Creates a new IReactiveDependency instance.

Type Parameters

Parameters

Returns

IReactiveDependency

dependency object.

Remarks

Use this inside the ReactiveNode.dependencies getter or an @select dependency selector when one slot needs explicit comparison cells. If node is a Retree-managed object, it is observed with nodeChanged. If node is a primitive or unproxied value, Retree treats it as a comparison-only dependency.

Comparison cells should be deterministic. If their length/order changes, Retree treats that as invalidation and emits for this node. If no comparisons are provided, every nodeChanged event from the dependency emits for this node.

Example

get dependencies() {
    return [
        this.authStore,
        this.authStore.session?.userId,
        this.dependency(this.selectedProject ?? null, [this.projectId]),
    ];
}

Inherited from

BaseConvexQueryNode.dependency

dispose()#

dispose(): void;

Defined in: retree-convex/src/ConvexPaginatedQueryNode.ts:244

Stop the active Convex paginated query subscription.

Returns#

void

Remarks#

Retree calls this automatically when the node loses its last active observer. Call it manually when tearing the owner down outside Retree observation. Disposing stops future Convex updates; it does not clear state, result, or error.

Disposal is sticky: writes to the node no longer reopen the subscription. The node resubscribes when it gains a new observer.

Example#

public dispose() {
    this.messages.dispose();
}

Overrides#

BaseConvexQueryNode.dispose

link()#

link<TNode>(node): RetreeLink<TNode>;

Defined in: retree-core/bin/ReactiveNode.d.ts:167

Create a reactive pointer to an existing Retree-managed node.

Type Parameters#

Parameters#

Returns#

RetreeLink<TNode>

A Retree-managed RetreeLink whose current points at node.

Remarks#

This is a convenience wrapper around Retree.link. Use it when a ReactiveNode method needs to return or store a pointer to a node owned elsewhere without reparenting that node.

Do not use link when ownership should move; use Retree.move or ReactiveNode.moveTo. Do not use it when two locations need independent state; use Retree.clone.

Example#

class EditorState extends ReactiveNode {
    public selected = null as RetreeLink<Task> | null;

    public select(task: Task) {
        this.selected = this.link(task);
    }
}

Inherited from#

BaseConvexQueryNode.link

loadMore()#

loadMore(numItems): boolean;

Defined in: retree-convex/src/ConvexPaginatedQueryNode.ts:211

Request more items for the active paginated query.

Parameters#

Returns#

boolean

Whether Convex started a load-more request.

Remarks#

Use this from UI actions such as "Load more" buttons or infinite scroll. It returns false when there is no active paginated state to extend. Passing a non-positive number throws.

Example#

const requested = messages.loadMore(20);
if (!requested) {
    console.log("No active page to extend");
}

memo()#

Call Signature#

protected memo<T>(fn, comparisons?): T;

Defined in: retree-core/bin/ReactiveNode.d.ts:486

Memoize the result of fn, scoped to this ReactiveNode instance.

Type Parameters

Parameters

Returns

T

Remarks

Two forms:

• Keyless (inside a getter): this.memo(fn, deps?) — derives the cache key from the active getter's property name. Throws if called outside a getter or more than once in the same getter.
• Explicit key: this.memo(key, fn, deps?) — works anywhere; required when stacking multiple memo cells in one getter, or memoizing inside a method.

Cache semantics for comparisons:

• Omitted/undefined: run fn under automatic dependency trapping and recompute when one of the trapped reads changes.
• []: compute once and cache forever for this instance.
• [a, b, ...]: recompute when any cell shallow-changes using Object.is. Tree-node cells are compared by their latest reproxy identity, so passing this.list correctly invalidates when list mutates.

memo is a cache, not a subscription. It does not emit nodeChanged or trigger React renders by itself. Pair it with dependencies, Retree.select, or useSelect when you also need notification behavior.

Example

class ListFilter extends ReactiveNode {
   list: Card[] = [];
   searchText = "";
   // Keyless form
   get filteredList() {
       return this.memo(
           () => this.list.filter((c) => c.text === this.searchText),
           [this.list, this.searchText]
       );
   }
   // Explicit-key form (e.g. when stacking two memos in one getter)
   get pair() {
       const a = this.memo("a", () => expensiveA(), [this.list]);
       const b = this.memo("b", () => expensiveB(), [this.searchText]);
       return { a, b };
   }
   get dependencies() { return [this.dependency(this.list)]; }
}

Inherited from

BaseConvexQueryNode.memo

Call Signature#

protected memo<T>(
   key, 
   fn, 
   comparisons?): T;

Defined in: retree-core/bin/ReactiveNode.d.ts:487

Memoize the result of fn, scoped to this ReactiveNode instance.

Type Parameters

Parameters

Returns

T

Remarks

Two forms:

• Keyless (inside a getter): this.memo(fn, deps?) — derives the cache key from the active getter's property name. Throws if called outside a getter or more than once in the same getter.
• Explicit key: this.memo(key, fn, deps?) — works anywhere; required when stacking multiple memo cells in one getter, or memoizing inside a method.

Cache semantics for comparisons:

• Omitted/undefined: run fn under automatic dependency trapping and recompute when one of the trapped reads changes.
• []: compute once and cache forever for this instance.
• [a, b, ...]: recompute when any cell shallow-changes using Object.is. Tree-node cells are compared by their latest reproxy identity, so passing this.list correctly invalidates when list mutates.

memo is a cache, not a subscription. It does not emit nodeChanged or trigger React renders by itself. Pair it with dependencies, Retree.select, or useSelect when you also need notification behavior.

Example

class ListFilter extends ReactiveNode {
   list: Card[] = [];
   searchText = "";
   // Keyless form
   get filteredList() {
       return this.memo(
           () => this.list.filter((c) => c.text === this.searchText),
           [this.list, this.searchText]
       );
   }
   // Explicit-key form (e.g. when stacking two memos in one getter)
   get pair() {
       const a = this.memo("a", () => expensiveA(), [this.list]);
       const b = this.memo("b", () => expensiveB(), [this.searchText]);
       return { a, b };
   }
   get dependencies() { return [this.dependency(this.list)]; }
}

Inherited from

BaseConvexQueryNode.memo

moveTo()#

Call Signature#

moveTo<TValue>(destination, key?): this;

Defined in: retree-core/bin/ReactiveNode.d.ts:137

Move this node to a new structural parent.

Type Parameters

Parameters

Returns

this

The latest reproxy for this node after it moves.

Remarks

This is a convenience wrapper around Retree.move. Use it from instance methods when a node should transfer ownership to another Retree-managed array, map, set, or object.

Do not call moveTo on a root node; roots have no parent to remove from. Do not manually remove the node from its current parent before moving.

Example

class Task extends ReactiveNode {
    public title = "";

    public complete(done: Task[]) {
        this.moveTo(done); // same as Retree.move(this, done)
    }
}

Inherited from

BaseConvexQueryNode.moveTo

Call Signature#

moveTo<TKey, TValue>(destination, key): this;

Defined in: retree-core/bin/ReactiveNode.d.ts:138

Move this node to a new structural parent.

Type Parameters

Parameters

Returns

this

The latest reproxy for this node after it moves.

Remarks

This is a convenience wrapper around Retree.move. Use it from instance methods when a node should transfer ownership to another Retree-managed array, map, set, or object.

Do not call moveTo on a root node; roots have no parent to remove from. Do not manually remove the node from its current parent before moving.

Example

class Task extends ReactiveNode {
    public title = "";

    public complete(done: Task[]) {
        this.moveTo(done); // same as Retree.move(this, done)
    }
}

Inherited from

BaseConvexQueryNode.moveTo

Call Signature#

moveTo<TValue>(destination): this;

Defined in: retree-core/bin/ReactiveNode.d.ts:139

Move this node to a new structural parent.

Type Parameters

Parameters

Returns

this

The latest reproxy for this node after it moves.

Remarks

This is a convenience wrapper around Retree.move. Use it from instance methods when a node should transfer ownership to another Retree-managed array, map, set, or object.

Do not call moveTo on a root node; roots have no parent to remove from. Do not manually remove the node from its current parent before moving.

Example

class Task extends ReactiveNode {
    public title = "";

    public complete(done: Task[]) {
        this.moveTo(done); // same as Retree.move(this, done)
    }
}

Inherited from

BaseConvexQueryNode.moveTo

Call Signature#

moveTo<TDestination>(destination, key): this;

Defined in: retree-core/bin/ReactiveNode.d.ts:140

Move this node to a new structural parent.

Type Parameters

Parameters

Returns

this

The latest reproxy for this node after it moves.

Remarks

This is a convenience wrapper around Retree.move. Use it from instance methods when a node should transfer ownership to another Retree-managed array, map, set, or object.

Do not call moveTo on a root node; roots have no parent to remove from. Do not manually remove the node from its current parent before moving.

Example

class Task extends ReactiveNode {
    public title = "";

    public complete(done: Task[]) {
        this.moveTo(done); // same as Retree.move(this, done)
    }
}

Inherited from

BaseConvexQueryNode.moveTo

mutation()#

protected mutation<Mutation>(mutation): RetreeConvexMutation<Mutation>;

Defined in: retree-convex/src/BaseConvexQueryNode.ts:74

Create a typed mutation function bound to this node's Convex client.

Type Parameters#

Parameters#

Returns#

RetreeConvexMutation<Mutation>

A typed mutation function with optional optimistic update support.

Remarks#

The returned function runs the Convex mutation. It does not update Retree state by itself. Pass withOptimisticUpdate when the mutation should immediately update a ConvexQueryNode; otherwise wait for the subscribed query to emit a server value.

Inherited from#

BaseConvexQueryNode.mutation

onChanged()#

protected onChanged(): void;

Defined in: retree-query/bin/QueryNode.d.ts:129

Runs after this ReactiveNode receives a fresh reproxy.

Returns#

void

Remarks#

Override this when a node needs to synchronize derived state only after a real Retree change. Retree runs this before nodeChanged / treeChanged listeners flush. If no transaction is already active, Retree starts one so state updates made here are batched with the reproxy that triggered the effect.

Use this for small synchronization writes that should happen only after Retree has confirmed a real change. Avoid writing unconditionally here; guard against loops by checking whether the derived value actually changed.

Example#

class SearchState extends ReactiveNode {
    public query = "";
    public normalizedQuery = "";

    protected onChanged() {
        const next = this.query.trim().toLowerCase();
        if (this.normalizedQuery !== next) {
            this.normalizedQuery = next;
        }
    }
}

Inherited from#

BaseConvexQueryNode.onChanged

onObserved()#

protected onObserved(): void;

Defined in: retree-query/bin/QueryNode.d.ts:128

Runs when this ReactiveNode gets its first active nodeChanged or treeChanged observer.

Returns#

void

Remarks#

Override this for work that requires the proxied instance, such as starting external subscriptions that write back into Retree state.

Keep setup idempotent. Retree calls this when the first active nodeChanged or treeChanged listener starts observing the node, not when the node is constructed.

Example#

class LiveValue extends ReactiveNode {
    public value = "";
    @ignore private unsubscribe: (() => void) | null = null;

    protected onObserved() {
        this.unsubscribe = subscribe((value) => {
            this.value = value; // ✅ emits through Retree
        });
    }
}

Inherited from#

BaseConvexQueryNode.onObserved

onUnobserved()#

protected onUnobserved(): void;

Defined in: retree-query/bin/QueryNode.d.ts:130

Runs when this ReactiveNode loses its last active nodeChanged or treeChanged observer.

Returns#

void

Remarks#

Use this to clean up resources created in ReactiveNode.onObserved. Do not rely on it as a destructor for unobserved nodes; it only runs after observation had started.

Example#

protected onUnobserved() {
    this.unsubscribe?.();
    this.unsubscribe = null;
}

Inherited from#

BaseConvexQueryNode.onUnobserved

optimisticUpdate()#

optimisticUpdate<Mutation>(transform): void;

Defined in: retree-convex/src/ConvexPaginatedQueryNode.ts:183

Apply an optimistic update to the loaded paginated results. If a mutation context is provided, rollback when its promise rejects unless a newer server value resolves the dirty state first.

Type Parameters#

Parameters#

Returns#

void

Remarks#

Use this from a mutation's withOptimisticUpdate callback when the UI should update immediately before Convex confirms the write. The transform mutates the existing paginated state (typically state.results) in place and emits through Retree.

Rollback restores the latest clean server baseline for the loaded rows and pagination status; the loadMore function is kept by reference and never cloned.

Example#

const toggle = this.mutation(api.tasks.toggleCompleted);
return toggle(
    { taskId },
    {
        withOptimisticUpdate: (ctx) => {
            this.messages.optimisticUpdate({
                ctx,
                apply(page) {
                    const task = page.results.find(
                        (item) => item._id === taskId
                    );
                    if (task) task.isCompleted = !task.isCompleted;
                },
            });
        },
    }
);

Overrides#

BaseConvexQueryNode.optimisticUpdate

peekInto()#

peekInto<TResult>(fn): TResult;

Defined in: retree-core/bin/ReactiveNode.d.ts:259

Run a read-only query against this node's raw object at native speed, then resolve the result back to its Retree-managed node when one exists.

Type Parameters#

Parameters#

Returns#

TResult

The callback result, resolved to its managed node when one exists.

Remarks#

This is a convenience wrapper around Retree.peekInto for this. The callback receives the raw object behind this node (ReactiveNode.raw), so reads inside it skip proxy traps and are not tracked as dependencies. If the returned value is an object that belongs to a Retree tree, the latest managed node (reproxy or base proxy) is returned instead; primitives and unmanaged objects are returned as-is.

Only the returned value itself is resolved. Containers built inside the callback (for example filter results) are returned unchanged, with raw elements. Children that have never been read through the managed tree have no proxy yet and resolve to their raw value; traverse the path once, or use prepareTree / autoPrepare, when a managed result is required.

Example#

class TaskList extends ReactiveNode {
    public tasks: Task[] = [];

    get dependencies() {
        return [this.dependency(this.tasks)];
    }

    public findTask(id: string): Task | undefined {
        // Scans raw at native speed; returns the managed task node.
        return this.peekInto((raw) =>
            raw.tasks.find((task) => task.id === id)
        );
    }
}

Inherited from#

BaseConvexQueryNode.peekInto

prepareTree()#

prepareTree(options?): void;

Defined in: retree-core/bin/ReactiveNode.d.ts:440

Prepare lazy Retree child proxies below this ReactiveNode.

Parameters#

Returns#

void

Remarks#

Retree lazily proxies plain object and array fields on ReactiveNodes. Call this when an app wants to pay that first-touch cost during a controlled phase, such as while showing a loading spinner. This walks only own data properties, so computed getters like dependencies are not evaluated or cached as child nodes. Fields marked with @ignore are skipped.

Do not call this for every render. Call it once during setup, loading, or before a known interaction that will traverse a large subtree.

Example#

class LargeNode extends ReactiveNode {
    public sections = [{ title: "Intro", cards: [] }];
}

const node = Retree.root(new LargeNode());
node.prepareTree({ depth: 1 });

Inherited from#

BaseConvexQueryNode.prepareTree

queryOnce()#

protected queryOnce<Query>(query, ...args): Promise<Awaited<FunctionReturnType<Query>>>;

Defined in: retree-convex/src/BaseConvexQueryNode.ts:108

Run a Convex query once without creating a subscription.

Type Parameters#

Parameters#

Returns#

Promise<Awaited<FunctionReturnType<Query>>>

Promise for the Convex query result.

Remarks#

Use this for imperative reads. It does not keep data live and does not emit Retree changes unless you assign the returned value into Retree state.

Inherited from#

BaseConvexQueryNode.queryOnce

raw()#

raw(): this;

Defined in: retree-core/bin/ReactiveNode.d.ts:201

Get the raw, unproxied object behind this node for read-only, non-reactive access.

Returns#

this

The raw object behind this node.

Remarks#

This is a convenience wrapper around Retree.raw for this. Reads on the returned object skip proxy traps entirely, so algorithms that scan large collections owned by this node can run at native speed.

Treat the result as read-only: direct mutations skip Retree change emission. Reads are invisible to reactivity, including this node's own auto-trapped @memo / @select dependency collection. Throws when the node is not yet Retree-managed (for example inside the constructor, before Retree.root(...) or tree attachment).

Example#

class Leaderboard extends ReactiveNode {
    public scores: number[] = [];

    get dependencies() {
        return [this.dependency(this.scores)];
    }

    get total() {
        // Raw scan; reactivity comes from `dependencies`.
        return this.raw().scores.reduce((sum, s) => sum + s, 0);
    }
}

Inherited from#

BaseConvexQueryNode.raw

restoreState()#

protected restoreState(next): void;

Defined in: retree-convex/src/ConvexPaginatedQueryNode.ts:254

Write a freshly emitted (or rollback) paginated result into state, reconciling loaded rows by _id so unchanged row nodes keep identity when any page updates or loadMore lands.

Parameters#

Returns#

void

Overrides#

BaseConvexQueryNode.restoreState

retry()#

retry(): void;

Defined in: retree-query/bin/QueryNode.d.ts:174

Re-subscribe to the query after result.status is "error".

Returns#

void

Remarks#

Use this from retry affordances in UI. It closes the errored subscription and opens a fresh one with the current args, moving the result to "pending" (or the cached value when the backend has one). Does nothing unless the current status is "error".

Example#

if (node.result.status === "error") {
    node.retry(); // ✅ re-opens the subscription
}

Inherited from#

BaseConvexQueryNode.retry

stateEquals()#

protected stateEquals(left, right): boolean;

Defined in: retree-convex/src/ConvexPaginatedQueryNode.ts:317

Compare paginated emissions by loaded rows and pagination status.

Parameters#

Returns#

boolean

Remarks#

Convex creates a fresh loadMore function per emission, so including it in the comparison would make every server echo look like a change and defeat the optimistic dirty-window logic.

Overrides#

BaseConvexQueryNode.stateEquals

tryDefaultReconcile()#

protected tryDefaultReconcile(_next): boolean;

Defined in: retree-query/bin/QueryNode.d.ts:225

Backend-convention reconciliation used when no explicit reconciler was configured. Return true when next was reconciled into the current state in place. The base implementation performs no reconciliation.

Parameters#

Returns#

boolean

Inherited from#

BaseConvexQueryNode.tryDefaultReconcile

untracked()#

untracked<T>(fn): T;

Defined in: retree-core/bin/ReactiveNode.d.ts:214

Run a synchronous function with Retree dependency tracking paused.

Type Parameters#

Parameters#

Returns#

T

The function's return value.

Remarks#

This is a convenience wrapper around Retree.untracked. Use it inside auto-trapped @memo, @fnMemo, and @select bodies when bulk reads should not become dependencies. Reads still go through Retree proxies; writes still emit normally.

Inherited from#

BaseConvexQueryNode.untracked

updateArgs()#

updateArgs(args): void;

Defined in: retree-convex/src/ConvexPaginatedQueryNode.ts:141

Update the query arguments and resubscribe when the arguments change (compared deeply, matching Convex's own structural comparison). Pass "skip" to disable the subscription.

Parameters#

Returns#

void

Remarks#

Updating args can emit because state, result, and error may change. Passing "skip" disables the active subscription and sets result.status to "skipped".

On a disposed node this records the new args without opening a subscription; the node resubscribes with the latest args when it is observed again.

Example#

messages.updateArgs({ channelId: "random" }); // ✅ may emit
messages.updateArgs("skip"); // ✅ emits skipped state and unsubscribes

Overrides#

BaseConvexQueryNode.updateArgs