How should a normalized cache merge an incoming page into an already-cached list field?

## Why a rule is needed at all Once the window arguments — the cursor, the offset, the page size — are excluded from a field's storage key, every page of the list writes to the **same** entry. That is the point of excluding them, but it creates a new problem immediately: the cache now has an existing value and an incoming value for one key and no idea what the result should be. Its default is last-write-wins, which turns "load more" into "replace the list with the newest twenty-five rows". A merge rule is what you supply so the cache does something better. ## The signature A merge rule is a function of three things and returns one: - the **existing** value stored under the key — absent on the very first write, which the rule must handle; - the **incoming** value, in the raw shape the field has in the response: a connection object carrying edges plus page metadata, or a plain list; - the **arguments and variables of this request**, which is the only thing that tells the rule *where* the incoming window belongs. That third input is what separates a correct rule from a naive one. `existing.edges + incoming.edges` ignores it entirely. ## The four ways blind append breaks **A page can arrive twice.** A retry, a fetch policy that serves the cache and then the network, a component remounting and re-issuing its query — any of these can deliver a window you already merged. Concatenation duplicates every row in it. In a benefits enrolment list, a double-click on "load more" fired the same `after` cursor twice and produced twenty-five enrolments listed twice in a row, with duplicate render keys behind them. De-duplicate by item identity, or write at a computed position so a repeat overwrites rather than extends. **Direction.** Backward pagination hands you the window *before* what you hold. It belongs at the front of the accumulated list, and appending it puts older rows below newer ones. **A cursor-less request is a reset, not a page.** After a filter change, a pull-to-refresh, or the first mount following an eviction, the client asks for the head of the list with no cursor. A rule that appends turns that into a list containing the first page twice. Treat the absence of a cursor argument as "replace". **Page metadata goes stale.** The list travels with information about where the window ended and whether more exists. If the merge keeps the stored copy instead of the incoming one, the end cursor never moves — so the next "load more" sends the cursor it already used, merges the same window again, and the list stops advancing. The symptom in the UI is a button that spins and does nothing, and it is one of the most common merge bugs there is. Take the metadata from the incoming page. ## Writing at a position rather than concatenating The more robust shape of the rule is not "append" but "write this window at the position its arguments imply". With offset arguments that position is explicit: the offset is the index. With cursor arguments it is implicit, but the request's cursor identifies the tail the window follows, so the rule can check that it still matches the tail of the accumulated list, and reset or drop the write when it does not. That check is what stops two in-flight "load more" requests from interleaving when they come back out of order. ```pseudocode merge(existing, incoming, args): if args.after is null and args.before is null: return incoming # a fresh head fetch is a reset base = existing or emptyList() known = idsOf(base) fresh = [e for e in incoming.edges if e.node.id not in known] items = args.before ? fresh + base : base + fresh return { edges: items, pageInfo: incoming.pageInfo } ``` ## The cost of one accumulating entry The merged entry is, by construction, everything fetched so far. Scrolling seventy-four pages of twenty-five statements leaves eighteen hundred references live for the session, and every write to that entry can wake every view reading it. Three usual mitigations: pair the merge with a read rule that returns only the window a caller asked for, cap how many pages the entry retains, and evict or reset the entry when the view unmounts or the filter changes. ## Specified or conventional? Entirely conventional. The GraphQL specification defines how a server executes a document and shapes a response; it has no concept of a client store, a storage key, or a merge function. Two client caches can differ on every detail above — whether a merge receives the field arguments, whether page metadata is merged separately, whether reads are windowed. Answer in terms of the mechanism, not in terms of one library's option names.