Class ConvexPaginatedQueryNode<Query>

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.

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,
});

Type Parameters

Query extends PaginatedQueryReference

Hierarchy (View Summary)

BaseConvexNode
- ConvexPaginatedQueryNode

Index

Constructors

constructor

new ConvexPaginatedQueryNode<Query extends PaginatedQueryReference>(
    client: IConvexClient,
    query: Query,
    ...options: ConvexPaginatedQueryNodeOptionsArgs<Query>,
): ConvexPaginatedQueryNode<Query>
Create a node for a Convex paginated query subscription.
Type Parameters
- Query extends PaginatedQueryReference
Parameters
- client: IConvexClient
  Convex client used for the subscription.
- query: Query
  Convex paginated query function reference.
- ...options: ConvexPaginatedQueryNodeOptionsArgs<Query>
  Query arguments, initial page size, and optional initial state.
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 BaseConvexNode.constructor
- Defined in retree-convex/src/ConvexPaginatedQueryNode.ts:91

Properties

`Protected` `Readonly`client

client: IConvexClient

Convex client used by this node.

error

error: Error | null = null

Latest subscription error.

options

options: IRetreeNodeOptions

Runtime options for this Retree node.

Remarks

Retree ignores this field for reactivity so options do not emit or become part of the tree.

result

result: ConvexPaginatedQueryNodeResult<Query>

Latest structured query result.

RETREE_LINKED_KEYS_SYMBOL

RETREE_LINKED_KEYS_SYMBOL: Set<string | symbol>

RETREE_SELECT_GETTERS_SYMBOL

RETREE_SELECT_GETTERS_SYMBOL: Map<
    string
    | symbol,
    IReactiveSelectGetter<ReactiveNode, unknown>,
>

state

state: ConvexPaginatedQueryNodeState<Query>

Latest paginated query state emitted by Convex.

Accessors

dependencies

get dependencies(): never[]
Dependencies to listen for changes to.

Returns never[]
Remarks
When any IReactiveDependency criteria is met, a change will be emitted for this ReactiveNode instance.

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])];
    }
}
```
Overrides BaseConvexNode.dependencies
- Defined in retree-convex/src/ConvexPaginatedQueryNode.ts:106

Methods

`Protected`action

action<Action extends ActionReference>(
action: Action,
): RetreeConvexAction<Action>
Create a typed action function bound to this node's Convex client.
Type Parameters
- Action extends ActionReference
Parameters
- action: Action
  Convex action function reference.
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.
Example
```
const generateSummary = this.action(api.ai.generateSummary);
const summary = await generateSummary({ taskId });
this.summary = summary; // ✅ this write emits if `summary` is reactive state
```
Inherited from BaseConvexNode.action
- Defined in retree-convex/src/BaseConvexNode.ts:119

dependency

dependency<TNode extends object = object>(
node: OptionalNode<TNode>,
comparisons?: any[],
): IReactiveDependency<TNode>
Creates a new IReactiveDependency instance.
Type Parameters
- TNode extends object = object
Parameters
- node: OptionalNode<TNode>
  the node to listen to "nodeChanged" events for.
- Optionalcomparisons: any[]
  Optional. Values to compare between updates to node.
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 BaseConvexNode.dependency
- Defined in retree-core/bin/ReactiveNode.d.ts:334
dependency<TValue>(value: TValue): IReactiveDependency
Creates a new IReactiveDependency instance.
Type Parameters
- TValue
Parameters
- value: TValue
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 BaseConvexNode.dependency
- Defined in retree-core/bin/ReactiveNode.d.ts:335

dispose

dispose(): void
Stop the active Convex paginated query subscription.

Returns void
Remarks
Call this when the owner of the paginated query node is torn down. Disposing stops future Convex updates; it does not clear state, result, or error.
Example
```
public dispose() {
    this.messages.dispose();
}
```
- Defined in retree-convex/src/ConvexPaginatedQueryNode.ts:237

link

link<TNode extends object>(node: TNode): RetreeLink<TNode>
Create a reactive pointer to an existing Retree-managed node.
Type Parameters
- TNode extends object
Parameters
- node: TNode
  Existing Retree-managed node to point at.
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;

    get dependencies() {
        return [];
    }

    public select(task: Task) {
        this.selected = this.link(task);
    }
}
```
Inherited from BaseConvexNode.link
- Defined in retree-core/bin/ReactiveNode.d.ts:189

loadMore

loadMore(numItems: number): boolean
Request more items for the active paginated query.
Parameters
- numItems: number
  Number of additional items to load.
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");
}
```
- Defined in retree-convex/src/ConvexPaginatedQueryNode.ts:208

`Protected`memo

memo<T>(fn: () => T, comparisons?: unknown[]): T
Memoize the result of fn, scoped to this ReactiveNode instance.
Type Parameters
- T
Parameters
- fn: () => T
- Optionalcomparisons: unknown[]
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 BaseConvexNode.memo
- Defined in retree-core/bin/ReactiveNode.d.ts:411
memo<T>(key: string, fn: () => T, comparisons?: unknown[]): T
Memoize the result of fn, scoped to this ReactiveNode instance.
Type Parameters
- T
Parameters
- key: string
- fn: () => T
- Optionalcomparisons: unknown[]
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 BaseConvexNode.memo
- Defined in retree-core/bin/ReactiveNode.d.ts:412

moveTo

moveTo<TValue extends object = ConvexPaginatedQueryNode<Query>>(
    destination: ConvexPaginatedQueryNode<Query> extends TValue
        ? TValue[]
        : never,
    key?: number,
): this
Move this node to a new structural parent.
Type Parameters
- TValue extends object = ConvexPaginatedQueryNode<Query>
Parameters
- destination: ConvexPaginatedQueryNode<Query> extends TValue ? TValue[] : never
  Retree-managed destination collection or object.
- Optionalkey: number
  Optional array insertion index, map key, or object property key.
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 = "";

    get dependencies() {
        return [];
    }

    public complete(done: Task[]) {
        this.moveTo(done); // same as Retree.move(this, done)
    }
}
```
Inherited from BaseConvexNode.moveTo
- Defined in retree-core/bin/ReactiveNode.d.ts:155
moveTo<TKey = unknown, TValue extends object = ConvexPaginatedQueryNode<Query>>(
    destination: ConvexPaginatedQueryNode<Query> extends TValue
        ? Map<TKey, TValue>
        : never,
    key: TKey,
): this
Move this node to a new structural parent.
Type Parameters
- TKey = unknown
- TValue extends object = ConvexPaginatedQueryNode<Query>
Parameters
- destination: ConvexPaginatedQueryNode<Query> extends TValue ? Map<TKey, TValue> : never
  Retree-managed destination collection or object.
- key: TKey
  Optional array insertion index, map key, or object property key.
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 = "";

    get dependencies() {
        return [];
    }

    public complete(done: Task[]) {
        this.moveTo(done); // same as Retree.move(this, done)
    }
}
```
Inherited from BaseConvexNode.moveTo
- Defined in retree-core/bin/ReactiveNode.d.ts:156
moveTo<TValue extends object = ConvexPaginatedQueryNode<Query>>(
    destination: ConvexPaginatedQueryNode<Query> extends TValue
        ? Set<TValue>
        : never,
): this
Move this node to a new structural parent.
Type Parameters
- TValue extends object = ConvexPaginatedQueryNode<Query>
Parameters
- destination: ConvexPaginatedQueryNode<Query> extends TValue ? Set<TValue> : never
  Retree-managed destination collection or object.
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 = "";

    get dependencies() {
        return [];
    }

    public complete(done: Task[]) {
        this.moveTo(done); // same as Retree.move(this, done)
    }
}
```
Inherited from BaseConvexNode.moveTo
- Defined in retree-core/bin/ReactiveNode.d.ts:157
moveTo<TDestination extends object = object>(
destination: TDestination,
key: RetreeObjectMoveKey<TDestination, ConvexPaginatedQueryNode<Query>>,
): this
Move this node to a new structural parent.
Type Parameters
- TDestination extends object = object
Parameters
- destination: TDestination
  Retree-managed destination collection or object.
- key: RetreeObjectMoveKey<TDestination, ConvexPaginatedQueryNode<Query>>
  Optional array insertion index, map key, or object property key.
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 = "";

    get dependencies() {
        return [];
    }

    public complete(done: Task[]) {
        this.moveTo(done); // same as Retree.move(this, done)
    }
}
```
Inherited from BaseConvexNode.moveTo
- Defined in retree-core/bin/ReactiveNode.d.ts:158

`Protected`mutation

mutation<Mutation extends MutationReference>(
mutation: Mutation,
): RetreeConvexMutation<Mutation>
Create a typed mutation function bound to this node's Convex client.
Type Parameters
- Mutation extends MutationReference
Parameters
- mutation: Mutation
  Convex mutation function reference.
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.
Example
```
const toggle = this.mutation(api.tasks.toggleCompleted);
return toggle(
    { taskId },
    {
        withOptimisticUpdate: (ctx) => {
            this.tasks.optimisticUpdate({
                ctx,
                apply(tasks) {
                    const task = tasks.find((item) => item._id === taskId);
                    if (task) task.isCompleted = !task.isCompleted;
                },
            });
        },
    }
);
```
Inherited from BaseConvexNode.mutation
- Defined in retree-convex/src/BaseConvexNode.ts:96

`Protected`onChanged

onChanged(): void
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 = "";

    get dependencies() {
        return [];
    }

    protected onChanged() {
        const next = this.query.trim().toLowerCase();
        if (this.normalizedQuery !== next) {
            this.normalizedQuery = next;
        }
    }
}
```
Overrides BaseConvexNode.onChanged
- Defined in retree-convex/src/ConvexPaginatedQueryNode.ts:114

`Protected`onObserved

onObserved(): void
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;

    get dependencies() {
        return [];
    }

    protected onObserved() {
        this.unsubscribe = subscribe((value) => {
            this.value = value; // ✅ emits through Retree
        });
    }
}
```
Overrides BaseConvexNode.onObserved
- Defined in retree-convex/src/ConvexPaginatedQueryNode.ts:110

`Protected`onUnobserved

onUnobserved(): void
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 BaseConvexNode.onUnobserved
- Defined in retree-core/bin/ReactiveNode.d.ts:269

prepareTree

prepareTree(options?: IRetreePrepareTreeOptions): void
Prepare lazy Retree child proxies below this ReactiveNode.
Parameters
- Optionaloptions: IRetreePrepareTreeOptions
  Optional depth limit. Omit to prepare all reachable non-ignored child objects.
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: [] }];

    get dependencies() {
        return [];
    }
}

const node = Retree.root(new LargeNode());
node.prepareTree({ depth: 1 });
```
Inherited from BaseConvexNode.prepareTree
- Defined in retree-core/bin/ReactiveNode.d.ts:365

`Protected`queryOnce

queryOnce<Query extends QueryReference>(
query: Query,
...args: OptionalConvexArgs<Query>,
): Promise<Awaited<FunctionReturnType<Query>>>
Run a Convex query once without creating a subscription.
Type Parameters
- Query extends QueryReference
Parameters
- query: Query
  Convex query function reference.
- ...args: OptionalConvexArgs<Query>
  Query arguments. Optional for no-args queries.
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. Use ConvexNode.query when the value should stay subscribed.
Example
```
const task = await this.queryOnce(api.tasks.getById, { taskId });
this.selectedTaskPreview = task; // ✅ emits if this field participates in Retree
```
Inherited from BaseConvexNode.queryOnce
- Defined in retree-convex/src/BaseConvexNode.ts:143

updateArgs

updateArgs(args: ConvexPaginatedQueryArgs<Query>): void
Update the query arguments and resubscribe when the shallow argument comparison changes. Pass "skip" to disable the subscription.
Parameters
- args: ConvexPaginatedQueryArgs<Query>
  Next query arguments, or "skip".
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".
Example
```
messages.updateArgs({ channelId: "random" }); // ✅ may emit
messages.updateArgs("skip"); // ✅ emits skipped state and unsubscribes
```
- Defined in retree-convex/src/ConvexPaginatedQueryNode.ts:135

Class ConvexPaginatedQueryNode<Query>

Remarks

Example

Type Parameters

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns ConvexPaginatedQueryNode<Query>

Remarks

Example

Properties

Protected Readonlyclient

error

options

Remarks

result

RETREE_LINKED_KEYS_SYMBOL

RETREE_SELECT_GETTERS_SYMBOL

state

Accessors

dependencies

Returns never[]

Remarks

Example

Methods

Protectedaction

Type Parameters

Parameters

Returns RetreeConvexAction<Action>

Remarks

Example

dependency

Type Parameters

Parameters

Returns IReactiveDependency<TNode>

Remarks

Example

Type Parameters

Parameters

Returns IReactiveDependency

Remarks

Example

dispose

Returns void

Remarks

Example

link

Type Parameters

Parameters

Returns RetreeLink<TNode>

Remarks

Example

loadMore

Parameters

Returns boolean

Remarks

Example

Protectedmemo

Type Parameters

Parameters

Returns T

Remarks

Example

Type Parameters

Parameters

Returns T

Remarks

Example

moveTo

Type Parameters

Parameters

Returns this

Remarks

`Protected` `Readonly`client

`Protected`action

`Protected`memo

`Protected`mutation

`Protected`onChanged

`Protected`onObserved

`Protected`onUnobserved

`Protected`queryOnce