1import { delay } from "@clo/lib/async.ts";
2import { assertEquals } from "@std/assert";
3import { QueryClient, QueryObserver, queryOptions } from "@tanstack/react-query";
4import { test, vi } from "vitest";
5import { MutationClient } from "../src/client.ts";
6import { queryClientOptimisticHelpers, reactiveFromQueryCache } from "../src/tanstack-query.ts";
7
8interface TestData {
9 name: string;
10 count: number;
11 active: boolean;
12 settings: {
13 theme: string;
14 notifications: boolean;
15 };
16 items: Array<{ id: number; label: string }>;
17 tags: string[];
18}
19
20interface TestArrayItem {
21 id: number;
22 label: string;
23}
24
25const initialData: TestData = {
26 name: "Test",
27 count: 10,
28 active: true,
29 settings: {
30 theme: "dark",
31 notifications: true,
32 },
33 items: [
34 { id: 1, label: "first" },
35 { id: 2, label: "second" },
36 { id: 3, label: "third" },
37 ],
38 tags: ["alpha", "beta", "gamma"],
39};
40
41const initialArrayItems: TestArrayItem[] = [
42 { id: 1, label: "first" },
43 { id: 2, label: "second" },
44 { id: 3, label: "third" },
45];
46
47function createTestQueryClient() {
48 const client = new QueryClient({
49 defaultOptions: { queries: { retry: false } },
50 });
51
52 const queryTest = queryOptions({
53 queryKey: ["test-data"],
54 queryFn: (): TestData => initialData,
55 });
56
57 client.setQueryData(queryTest.queryKey, structuredClone(initialData));
58
59 return { client, queryTest };
60}
61
62function createArrayQueryClient() {
63 const client = new QueryClient({
64 defaultOptions: { queries: { retry: false } },
65 });
66
67 const queryArray = queryOptions({
68 queryKey: ["test-array"],
69 queryFn: (): TestArrayItem[] => initialArrayItems,
70 });
71
72 client.setQueryData(queryArray.queryKey, structuredClone(initialArrayItems));
73
74 return { client, queryArray };
75}
76
77test("helpers can be spread and retain bound this", () => {
78 const { client, queryTest } = createTestQueryClient();
79
80 const helpers = queryClientOptimisticHelpers(client)({
81 onRestore: () => {},
82 onRefetch: () => {},
83 });
84 const spreadHelpers = { ...helpers };
85
86 assertEquals(Object.keys(spreadHelpers).includes("objIncrement"), true);
87
88 spreadHelpers.objIncrement(queryTest, ["count"], 2);
89
90 const result = client.getQueryData<TestData>(queryTest.queryKey);
91 assertEquals(result?.count, 12);
92});
93
94test("reactiveFromQueryCache derives and subscribes to query data", () => {
95 const { client, queryTest } = createTestQueryClient();
96 const reactive = reactiveFromQueryCache(
97 client,
98 queryTest,
99 (data) => data ? { name: data.name } : null,
100 );
101 let changes = 0;
102 const unsubscribe = reactive.sub(() => changes += 1);
103
104 assertEquals(reactive.get(), { name: "Test" });
105
106 client.setQueryData(queryTest.queryKey, { ...initialData, name: "Updated" });
107 assertEquals(reactive.get(), { name: "Updated" });
108 assertEquals(changes, 1);
109
110 unsubscribe();
111 client.setQueryData(queryTest.queryKey, { ...initialData, name: "Ignored" });
112 assertEquals(changes, 1);
113});
114
115// ============================================================================
116// set() tests
117// ============================================================================
118
119test("set - should set entire query data and create if doesn't exist", () => {
120 const { client } = createTestQueryClient();
121 const restoreFns: Array<() => void> = [];
122
123 const helpers = queryClientOptimisticHelpers(client)({
124 onRestore: (fn) => restoreFns.push(fn),
125 onRefetch: () => {},
126 });
127
128 const queryNew = queryOptions({
129 queryKey: ["new-query"],
130 queryFn: (): TestData => initialData,
131 });
132
133 const newData: TestData = {
134 name: "Created",
135 count: 99,
136 active: false,
137 settings: { theme: "light", notifications: false },
138 items: [],
139 tags: [],
140 };
141
142 helpers.set(queryNew, newData);
143
144 const result = client.getQueryData<TestData>(queryNew.queryKey);
145 assertEquals(result, newData);
146
147 // Restore should remove it since it didn't exist before
148 restoreFns[0]();
149 const restored = client.getQueryData<TestData>(queryNew.queryKey);
150 assertEquals(restored, undefined);
151});
152
153test("set - should update existing query data", () => {
154 const { client, queryTest } = createTestQueryClient();
155 const restoreFns: Array<() => void> = [];
156
157 const helpers = queryClientOptimisticHelpers(client)({
158 onRestore: (fn) => restoreFns.push(fn),
159 onRefetch: () => {},
160 });
161
162 const newData: TestData = {
163 name: "Updated",
164 count: 99,
165 active: false,
166 settings: { theme: "light", notifications: false },
167 items: [],
168 tags: [],
169 };
170
171 helpers.set(queryTest, newData);
172
173 const result = client.getQueryData<TestData>(queryTest.queryKey);
174 assertEquals(result, newData);
175
176 // Restore should revert to original
177 restoreFns[0]();
178 const restored = client.getQueryData<TestData>(queryTest.queryKey);
179 assertEquals(restored?.name, "Test");
180 assertEquals(restored?.count, 10);
181});
182
183test("set - should accept updater function", () => {
184 const { client, queryTest } = createTestQueryClient();
185
186 const helpers = queryClientOptimisticHelpers(client)({
187 onRestore: () => {},
188 onRefetch: () => {},
189 });
190
191 helpers.set(queryTest, (prev) => prev ? { ...prev, name: "Updated" } : prev);
192
193 const result = client.getQueryData<TestData>(queryTest.queryKey);
194 assertEquals(result?.name, "Updated");
195 assertEquals(result?.count, 10); // Other fields unchanged
196});
197
198// ============================================================================
199// updateExisting() tests
200// ============================================================================
201
202test("updateExisting - should update existing query data", () => {
203 const { client, queryTest } = createTestQueryClient();
204 const restoreFns: Array<() => void> = [];
205
206 const helpers = queryClientOptimisticHelpers(client)({
207 onRestore: (fn) => restoreFns.push(fn),
208 onRefetch: () => {},
209 });
210
211 const newData: TestData = {
212 name: "Updated",
213 count: 99,
214 active: false,
215 settings: { theme: "light", notifications: false },
216 items: [],
217 tags: [],
218 };
219
220 helpers.updateExisting(queryTest, newData);
221
222 const result = client.getQueryData<TestData>(queryTest.queryKey);
223 assertEquals(result, newData);
224
225 // Restore should revert to original
226 restoreFns[0]();
227 const restored = client.getQueryData<TestData>(queryTest.queryKey);
228 assertEquals(restored?.name, "Test");
229});
230
231test("updateExisting - should skip if query doesn't exist", () => {
232 const { client } = createTestQueryClient();
233 const restoreFns: Array<() => void> = [];
234
235 const helpers = queryClientOptimisticHelpers(client)({
236 onRestore: (fn) => restoreFns.push(fn),
237 onRefetch: () => {},
238 });
239
240 const queryNonexistent = queryOptions({
241 queryKey: ["nonexistent"],
242 queryFn: (): TestData => initialData,
243 });
244
245 helpers.updateExisting(queryNonexistent, { name: "test" } as any);
246
247 assertEquals(restoreFns.length, 0);
248});
249
250// ============================================================================
251// objSet() tests
252// ============================================================================
253
254test("objSet - should set property at path", () => {
255 const { client, queryTest } = createTestQueryClient();
256 const restoreFns: Array<() => void> = [];
257
258 const helpers = queryClientOptimisticHelpers(client)({
259 onRestore: (fn) => restoreFns.push(fn),
260 onRefetch: () => {},
261 });
262
263 helpers.objSet(queryTest, ["name"], "NewName");
264
265 const result = client.getQueryData<TestData>(queryTest.queryKey);
266 assertEquals(result?.name, "NewName");
267 assertEquals(result?.count, 10);
268
269 // Restore
270 restoreFns[0]();
271 const restored = client.getQueryData<TestData>(queryTest.queryKey);
272 assertEquals(restored?.name, "Test");
273});
274
275test("objSet - should set nested property", () => {
276 const { client, queryTest } = createTestQueryClient();
277 const restoreFns: Array<() => void> = [];
278
279 const helpers = queryClientOptimisticHelpers(client)({
280 onRestore: (fn) => restoreFns.push(fn),
281 onRefetch: () => {},
282 });
283
284 helpers.objSet(queryTest, ["settings", "theme"], "light");
285
286 const result = client.getQueryData<TestData>(queryTest.queryKey);
287 assertEquals(result?.settings.theme, "light");
288 assertEquals(result?.settings.notifications, true);
289
290 // Restore
291 restoreFns[0]();
292 const restored = client.getQueryData<TestData>(queryTest.queryKey);
293 assertEquals(restored?.settings.theme, "dark");
294});
295
296test("objSet - should accept updater function", () => {
297 const { client, queryTest } = createTestQueryClient();
298
299 const helpers = queryClientOptimisticHelpers(client)({
300 onRestore: () => {},
301 onRefetch: () => {},
302 });
303
304 helpers.objSet(queryTest, ["count"], (n) => n + 5);
305
306 const result = client.getQueryData<TestData>(queryTest.queryKey);
307 assertEquals(result?.count, 15);
308});
309
310// ============================================================================
311// objIncrement() tests
312// ============================================================================
313
314test("objIncrement - should increment by 1 by default", () => {
315 const { client, queryTest } = createTestQueryClient();
316 const restoreFns: Array<() => void> = [];
317
318 const helpers = queryClientOptimisticHelpers(client)({
319 onRestore: (fn) => restoreFns.push(fn),
320 onRefetch: () => {},
321 });
322
323 helpers.objIncrement(queryTest, ["count"]);
324
325 const result = client.getQueryData<TestData>(queryTest.queryKey);
326 assertEquals(result?.count, 11);
327
328 // Restore
329 restoreFns[0]();
330 const restored = client.getQueryData<TestData>(queryTest.queryKey);
331 assertEquals(restored?.count, 10);
332});
333
334test("objIncrement - should increment by custom amount", () => {
335 const { client, queryTest } = createTestQueryClient();
336
337 const helpers = queryClientOptimisticHelpers(client)({
338 onRestore: () => {},
339 onRefetch: () => {},
340 });
341
342 helpers.objIncrement(queryTest, ["count"], 5);
343
344 const result = client.getQueryData<TestData>(queryTest.queryKey);
345 assertEquals(result?.count, 15);
346});
347
348test("objIncrement - should skip if value is not a number", () => {
349 const { client, queryTest } = createTestQueryClient();
350 const restoreFns: Array<() => void> = [];
351
352 const helpers = queryClientOptimisticHelpers(client)({
353 onRestore: (fn) => restoreFns.push(fn),
354 onRefetch: () => {},
355 });
356
357 helpers.objIncrement(queryTest, ["name"] as any, 5);
358
359 const result = client.getQueryData<TestData>(queryTest.queryKey);
360 assertEquals(result?.name, "Test"); // Unchanged
361 assertEquals(restoreFns.length, 0); // No restore registered
362});
363
364// ============================================================================
365// objDecrement() tests
366// ============================================================================
367
368test("objDecrement - should decrement by 1 by default", () => {
369 const { client, queryTest } = createTestQueryClient();
370
371 const helpers = queryClientOptimisticHelpers(client)({
372 onRestore: () => {},
373 onRefetch: () => {},
374 });
375
376 helpers.objDecrement(queryTest, ["count"]);
377
378 const result = client.getQueryData<TestData>(queryTest.queryKey);
379 assertEquals(result?.count, 9);
380});
381
382test("objDecrement - should decrement by custom amount", () => {
383 const { client, queryTest } = createTestQueryClient();
384
385 const helpers = queryClientOptimisticHelpers(client)({
386 onRestore: () => {},
387 onRefetch: () => {},
388 });
389
390 helpers.objDecrement(queryTest, ["count"], 3);
391
392 const result = client.getQueryData<TestData>(queryTest.queryKey);
393 assertEquals(result?.count, 7);
394});
395
396// ============================================================================
397// objToggle() tests
398// ============================================================================
399
400test("objToggle - should toggle boolean value", () => {
401 const { client, queryTest } = createTestQueryClient();
402 const restoreFns: Array<() => void> = [];
403
404 const helpers = queryClientOptimisticHelpers(client)({
405 onRestore: (fn) => restoreFns.push(fn),
406 onRefetch: () => {},
407 });
408
409 helpers.objToggle(queryTest, ["active"]);
410
411 const result = client.getQueryData<TestData>(queryTest.queryKey);
412 assertEquals(result?.active, false);
413
414 // Restore
415 restoreFns[0]();
416 const restored = client.getQueryData<TestData>(queryTest.queryKey);
417 assertEquals(restored?.active, true);
418});
419
420test("objToggle - should toggle nested boolean", () => {
421 const { client, queryTest } = createTestQueryClient();
422
423 const helpers = queryClientOptimisticHelpers(client)({
424 onRestore: () => {},
425 onRefetch: () => {},
426 });
427
428 helpers.objToggle(queryTest, ["settings", "notifications"]);
429
430 const result = client.getQueryData<TestData>(queryTest.queryKey);
431 assertEquals(result?.settings.notifications, false);
432});
433
434test("objToggle - should skip if value is not boolean", () => {
435 const { client, queryTest } = createTestQueryClient();
436 const restoreFns: Array<() => void> = [];
437
438 const helpers = queryClientOptimisticHelpers(client)({
439 onRestore: (fn) => restoreFns.push(fn),
440 onRefetch: () => {},
441 });
442
443 helpers.objToggle(queryTest, ["count"] as any);
444
445 const result = client.getQueryData<TestData>(queryTest.queryKey);
446 assertEquals(result?.count, 10); // Unchanged
447 assertEquals(restoreFns.length, 0);
448});
449
450// ============================================================================
451// objSetMany() tests
452// ============================================================================
453
454test("objSetMany - should merge multiple properties", () => {
455 const { client, queryTest } = createTestQueryClient();
456 const restoreFns: Array<() => void> = [];
457
458 const helpers = queryClientOptimisticHelpers(client)({
459 onRestore: (fn) => restoreFns.push(fn),
460 onRefetch: () => {},
461 });
462
463 helpers.objSetMany(queryTest, ["settings"], {
464 theme: "light",
465 });
466
467 const result = client.getQueryData<TestData>(queryTest.queryKey);
468 assertEquals(result?.settings.theme, "light");
469 assertEquals(result?.settings.notifications, true); // Unchanged
470
471 // Restore
472 restoreFns[0]();
473 const restored = client.getQueryData<TestData>(queryTest.queryKey);
474 assertEquals(restored?.settings.theme, "dark");
475});
476
477test("objSetMany - should work at root level", () => {
478 const { client, queryTest } = createTestQueryClient();
479
480 const helpers = queryClientOptimisticHelpers(client)({
481 onRestore: () => {},
482 onRefetch: () => {},
483 });
484
485 helpers.objSetMany(queryTest, [], {
486 name: "Updated",
487 count: 99,
488 });
489
490 const result = client.getQueryData<TestData>(queryTest.queryKey);
491 assertEquals(result?.name, "Updated");
492 assertEquals(result?.count, 99);
493 assertEquals(result?.active, true); // Unchanged
494});
495
496// ============================================================================
497// arrayPush() tests
498// ============================================================================
499
500test("arrayPush - should add items to end of array", () => {
501 const { client, queryTest } = createTestQueryClient();
502 const restoreFns: Array<() => void> = [];
503
504 const helpers = queryClientOptimisticHelpers(client)({
505 onRestore: (fn) => restoreFns.push(fn),
506 onRefetch: () => {},
507 });
508
509 helpers.objArrayPush(
510 queryTest,
511 ["items"],
512 { id: 4, label: "fourth" },
513 { id: 5, label: "fifth" },
514 );
515
516 const result = client.getQueryData<TestData>(queryTest.queryKey);
517 assertEquals(result?.items.length, 5);
518 assertEquals(result?.items[3], { id: 4, label: "fourth" });
519 assertEquals(result?.items[4], { id: 5, label: "fifth" });
520
521 // Restore
522 restoreFns[0]();
523 const restored = client.getQueryData<TestData>(queryTest.queryKey);
524 assertEquals(restored?.items.length, 3);
525});
526
527test("arrayPush - should work with simple arrays", () => {
528 const { client, queryTest } = createTestQueryClient();
529
530 const helpers = queryClientOptimisticHelpers(client)({
531 onRestore: () => {},
532 onRefetch: () => {},
533 });
534
535 helpers.objArrayPush(queryTest, ["tags"], "delta", "epsilon");
536
537 const result = client.getQueryData<TestData>(queryTest.queryKey);
538 assertEquals(result?.tags, ["alpha", "beta", "gamma", "delta", "epsilon"]);
539});
540
541// ============================================================================
542// arrayUnshift() tests
543// ============================================================================
544
545test("arrayUnshift - should add items to beginning of array", () => {
546 const { client, queryTest } = createTestQueryClient();
547 const restoreFns: Array<() => void> = [];
548
549 const helpers = queryClientOptimisticHelpers(client)({
550 onRestore: (fn) => restoreFns.push(fn),
551 onRefetch: () => {},
552 });
553
554 helpers.objArrayUnshift(
555 queryTest,
556 ["items"],
557 { id: 0, label: "zeroth" },
558 );
559
560 const result = client.getQueryData<TestData>(queryTest.queryKey);
561 assertEquals(result?.items.length, 4);
562 assertEquals(result?.items[0], { id: 0, label: "zeroth" });
563 assertEquals(result?.items[1], { id: 1, label: "first" });
564
565 // Restore
566 restoreFns[0]();
567 const restored = client.getQueryData<TestData>(queryTest.queryKey);
568 assertEquals(restored?.items.length, 3);
569 assertEquals(restored?.items[0], { id: 1, label: "first" });
570});
571
572// ============================================================================
573// arrayRemoveItem() tests
574// ============================================================================
575
576test("arrayRemoveItem - should remove items matching predicate", () => {
577 const { client, queryTest } = createTestQueryClient();
578 const restoreFns: Array<() => void> = [];
579
580 const helpers = queryClientOptimisticHelpers(client)({
581 onRestore: (fn) => restoreFns.push(fn),
582 onRefetch: () => {},
583 });
584
585 helpers.objArrayRemove(
586 queryTest,
587 ["items"],
588 (item) => item.id === 2,
589 );
590
591 const result = client.getQueryData<TestData>(queryTest.queryKey);
592 assertEquals(result?.items.length, 2);
593 assertEquals(result?.items[0], { id: 1, label: "first" });
594 assertEquals(result?.items[1], { id: 3, label: "third" });
595
596 // Restore
597 restoreFns[0]();
598 const restored = client.getQueryData<TestData>(queryTest.queryKey);
599 assertEquals(restored?.items.length, 3);
600});
601
602test("arrayRemoveItem - should remove multiple items", () => {
603 const { client, queryTest } = createTestQueryClient();
604
605 const helpers = queryClientOptimisticHelpers(client)({
606 onRestore: () => {},
607 onRefetch: () => {},
608 });
609
610 helpers.objArrayRemove(
611 queryTest,
612 ["items"],
613 (item) => item.id > 1,
614 );
615
616 const result = client.getQueryData<TestData>(queryTest.queryKey);
617 assertEquals(result?.items.length, 1);
618 assertEquals(result?.items[0], { id: 1, label: "first" });
619});
620
621test("arrayRemoveItem - should work with simple arrays", () => {
622 const { client, queryTest } = createTestQueryClient();
623
624 const helpers = queryClientOptimisticHelpers(client)({
625 onRestore: () => {},
626 onRefetch: () => {},
627 });
628
629 helpers.objArrayRemove(
630 queryTest,
631 ["tags"],
632 (tag) => tag === "beta",
633 );
634
635 const result = client.getQueryData<TestData>(queryTest.queryKey);
636 assertEquals(result?.tags, ["alpha", "gamma"]);
637});
638
639// ============================================================================
640// arrayUpdateItem() tests
641// ============================================================================
642
643test("arrayUpdateItem - should update items matching predicate", () => {
644 const { client, queryTest } = createTestQueryClient();
645 const restoreFns: Array<() => void> = [];
646
647 const helpers = queryClientOptimisticHelpers(client)({
648 onRestore: (fn) => restoreFns.push(fn),
649 onRefetch: () => {},
650 });
651
652 helpers.objArrayUpdate(
653 queryTest,
654 ["items"],
655 {
656 filter: (item) => item.id === 2,
657 update: (item) => ({ ...item, label: "UPDATED" }),
658 },
659 );
660
661 const result = client.getQueryData<TestData>(queryTest.queryKey);
662 assertEquals(result?.items[1], { id: 2, label: "UPDATED" });
663 assertEquals(result?.items[0], { id: 1, label: "first" });
664
665 // Restore
666 restoreFns[0]();
667 const restored = client.getQueryData<TestData>(queryTest.queryKey);
668 assertEquals(restored?.items[1], { id: 2, label: "second" });
669});
670
671test("arrayUpdateItem - should update multiple items", () => {
672 const { client, queryTest } = createTestQueryClient();
673
674 const helpers = queryClientOptimisticHelpers(client)({
675 onRestore: () => {},
676 onRefetch: () => {},
677 });
678
679 helpers.objArrayUpdate(
680 queryTest,
681 ["items"],
682 {
683 filter: (item) => item.id > 1,
684 update: (item) => ({ ...item, label: item.label.toUpperCase() }),
685 },
686 );
687
688 const result = client.getQueryData<TestData>(queryTest.queryKey);
689 assertEquals(result?.items[0].label, "first"); // Unchanged
690 assertEquals(result?.items[1].label, "SECOND");
691 assertEquals(result?.items[2].label, "THIRD");
692});
693
694test("arrayUpdateItem - predicate receives index", () => {
695 const { client, queryTest } = createTestQueryClient();
696
697 const helpers = queryClientOptimisticHelpers(client)({
698 onRestore: () => {},
699 onRefetch: () => {},
700 });
701
702 helpers.objArrayUpdate(
703 queryTest,
704 ["items"],
705 {
706 filter: (_item, index) => index === 0,
707 update: (item) => ({ ...item, label: "FIRST" }),
708 },
709 );
710
711 const result = client.getQueryData<TestData>(queryTest.queryKey);
712 assertEquals(result?.items[0].label, "FIRST");
713});
714
715test("arrayUpdateItem - should update all items when filter is omitted", () => {
716 const { client, queryTest } = createTestQueryClient();
717
718 const helpers = queryClientOptimisticHelpers(client)({
719 onRestore: () => {},
720 onRefetch: () => {},
721 });
722
723 helpers.objArrayUpdate(
724 queryTest,
725 ["items"],
726 {
727 update: (item) => ({ ...item, label: item.label.toUpperCase() }),
728 },
729 );
730
731 const result = client.getQueryData<TestData>(queryTest.queryKey);
732 assertEquals(result?.items.map((item) => item.label), ["FIRST", "SECOND", "THIRD"]);
733});
734
735// ============================================================================
736// objArrayUpsert() tests
737// ============================================================================
738
739test("objArrayUpsert - should update matching items without inserting", () => {
740 const { client, queryTest } = createTestQueryClient();
741 const restoreFns: Array<() => void> = [];
742
743 const helpers = queryClientOptimisticHelpers(client)({
744 onRestore: (fn) => restoreFns.push(fn),
745 onRefetch: () => {},
746 });
747
748 const upsertResult = helpers.objArrayUpsert(
749 queryTest,
750 ["items"],
751 {
752 filter: (item) => item.id === 2,
753 update: (item) => ({ ...item, label: "UPDATED" }),
754 insert: () => ({ id: 4, label: "fourth" }),
755 },
756 );
757
758 const result = client.getQueryData<TestData>(queryTest.queryKey);
759 assertEquals(upsertResult, { inserted: false });
760 assertEquals(result?.items.length, 3);
761 assertEquals(result?.items[1], { id: 2, label: "UPDATED" });
762
763 restoreFns[0]();
764 const restored = client.getQueryData<TestData>(queryTest.queryKey);
765 assertEquals(restored?.items, initialData.items);
766});
767
768test("objArrayUpsert - should insert a new item when nothing matches", () => {
769 const { client, queryTest } = createTestQueryClient();
770 const restoreFns: Array<() => void> = [];
771
772 const helpers = queryClientOptimisticHelpers(client)({
773 onRestore: (fn) => restoreFns.push(fn),
774 onRefetch: () => {},
775 });
776
777 const upsertResult = helpers.objArrayUpsert(
778 queryTest,
779 ["items"],
780 {
781 filter: (item) => item.id === 4,
782 insert: () => ({ id: 4, label: "fourth" }),
783 },
784 );
785
786 const result = client.getQueryData<TestData>(queryTest.queryKey);
787 assertEquals(upsertResult, { inserted: true });
788 assertEquals(result?.items.length, 4);
789 assertEquals(result?.items[3], { id: 4, label: "fourth" });
790
791 restoreFns[0]();
792 const restored = client.getQueryData<TestData>(queryTest.queryKey);
793 assertEquals(restored?.items, initialData.items);
794});
795
796// ============================================================================
797// arrayUpsert() tests
798// ============================================================================
799
800test("arrayUpsert - should update matching items without inserting", () => {
801 const { client, queryArray } = createArrayQueryClient();
802 const restoreFns: Array<() => void> = [];
803
804 const helpers = queryClientOptimisticHelpers(client)({
805 onRestore: (fn) => restoreFns.push(fn),
806 onRefetch: () => {},
807 });
808
809 const upsertResult = helpers.arrayUpsert(
810 queryArray,
811 {
812 filter: (item) => item.id === 2,
813 update: (item) => ({ ...item, label: "UPDATED" }),
814 insert: () => ({ id: 4, label: "fourth" }),
815 },
816 );
817
818 const result = client.getQueryData<TestArrayItem[]>(queryArray.queryKey);
819 assertEquals(upsertResult, { inserted: false });
820 assertEquals(result?.length, 3);
821 assertEquals(result?.[1], { id: 2, label: "UPDATED" });
822
823 restoreFns[0]();
824 const restored = client.getQueryData<TestArrayItem[]>(queryArray.queryKey);
825 assertEquals(restored, initialArrayItems);
826});
827
828test("arrayUpsert - should insert a new item when nothing matches", () => {
829 const { client, queryArray } = createArrayQueryClient();
830 const restoreFns: Array<() => void> = [];
831
832 const helpers = queryClientOptimisticHelpers(client)({
833 onRestore: (fn) => restoreFns.push(fn),
834 onRefetch: () => {},
835 });
836
837 const upsertResult = helpers.arrayUpsert(
838 queryArray,
839 {
840 filter: (item) => item.id === 4,
841 insert: () => ({ id: 4, label: "fourth" }),
842 },
843 );
844
845 const result = client.getQueryData<TestArrayItem[]>(queryArray.queryKey);
846 assertEquals(upsertResult, { inserted: true });
847 assertEquals(result?.length, 4);
848 assertEquals(result?.[3], { id: 4, label: "fourth" });
849
850 restoreFns[0]();
851 const restored = client.getQueryData<TestArrayItem[]>(queryArray.queryKey);
852 assertEquals(restored, initialArrayItems);
853});
854
855test("arrayUpsert - should skip if query doesn't exist", () => {
856 const { client } = createTestQueryClient();
857 const restoreFns: Array<() => void> = [];
858
859 const helpers = queryClientOptimisticHelpers(client)({
860 onRestore: (fn) => restoreFns.push(fn),
861 onRefetch: () => {},
862 });
863
864 const queryNonexistent = queryOptions({
865 queryKey: ["nonexistent-array"],
866 queryFn: (): TestArrayItem[] => initialArrayItems,
867 });
868
869 const upsertResult = helpers.arrayUpsert(
870 queryNonexistent,
871 {
872 filter: (item) => item.id === 4,
873 insert: () => ({ id: 4, label: "fourth" }),
874 },
875 );
876
877 assertEquals(upsertResult, { inserted: false });
878 assertEquals(restoreFns.length, 0);
879});
880
881// ============================================================================
882// arrayInsertIndex() tests
883// ============================================================================
884
885test("arrayInsertIndex - should insert at specific index", () => {
886 const { client, queryTest } = createTestQueryClient();
887 const restoreFns: Array<() => void> = [];
888
889 const helpers = queryClientOptimisticHelpers(client)({
890 onRestore: (fn) => restoreFns.push(fn),
891 onRefetch: () => {},
892 });
893
894 helpers.objArrayInsertIndex(
895 queryTest,
896 ["items"],
897 1,
898 { id: 99, label: "inserted" },
899 );
900
901 const result = client.getQueryData<TestData>(queryTest.queryKey);
902 assertEquals(result?.items.length, 4);
903 assertEquals(result?.items[0], { id: 1, label: "first" });
904 assertEquals(result?.items[1], { id: 99, label: "inserted" });
905 assertEquals(result?.items[2], { id: 2, label: "second" });
906
907 // Restore
908 restoreFns[0]();
909 const restored = client.getQueryData<TestData>(queryTest.queryKey);
910 assertEquals(restored?.items.length, 3);
911});
912
913test("arrayInsertIndex - should insert at beginning", () => {
914 const { client, queryTest } = createTestQueryClient();
915
916 const helpers = queryClientOptimisticHelpers(client)({
917 onRestore: () => {},
918 onRefetch: () => {},
919 });
920
921 helpers.objArrayInsertIndex(
922 queryTest,
923 ["tags"],
924 0,
925 "prefix",
926 );
927
928 const result = client.getQueryData<TestData>(queryTest.queryKey);
929 assertEquals(result?.tags, ["prefix", "alpha", "beta", "gamma"]);
930});
931
932test("arrayInsertIndex - should insert at end", () => {
933 const { client, queryTest } = createTestQueryClient();
934
935 const helpers = queryClientOptimisticHelpers(client)({
936 onRestore: () => {},
937 onRefetch: () => {},
938 });
939
940 helpers.objArrayInsertIndex(
941 queryTest,
942 ["tags"],
943 3,
944 "suffix",
945 );
946
947 const result = client.getQueryData<TestData>(queryTest.queryKey);
948 assertEquals(result?.tags, ["alpha", "beta", "gamma", "suffix"]);
949});
950
951test("arrayInsertIndex - should insert multiple items", () => {
952 const { client, queryTest } = createTestQueryClient();
953
954 const helpers = queryClientOptimisticHelpers(client)({
955 onRestore: () => {},
956 onRefetch: () => {},
957 });
958
959 helpers.objArrayInsertIndex(
960 queryTest,
961 ["tags"],
962 1,
963 "one",
964 "two",
965 );
966
967 const result = client.getQueryData<TestData>(queryTest.queryKey);
968 assertEquals(result?.tags, ["alpha", "one", "two", "beta", "gamma"]);
969});
970
971// ============================================================================
972// removeQuery() tests
973// ============================================================================
974
975test("removeQuery - should remove query from cache", () => {
976 const { client, queryTest } = createTestQueryClient();
977 const restoreFns: Array<() => void> = [];
978
979 const helpers = queryClientOptimisticHelpers(client)({
980 onRestore: (fn) => restoreFns.push(fn),
981 onRefetch: () => {},
982 });
983
984 helpers.removeQuery(queryTest);
985
986 const result = client.getQueryData<TestData>(queryTest.queryKey);
987 assertEquals(result, undefined);
988
989 // Restore should bring it back
990 restoreFns[0]();
991 const restored = client.getQueryData<TestData>(queryTest.queryKey);
992 assertEquals(restored?.name, "Test");
993});
994
995test("removeQuery - should skip if query doesn't exist", () => {
996 const { client } = createTestQueryClient();
997 const restoreFns: Array<() => void> = [];
998
999 const helpers = queryClientOptimisticHelpers(client)({
1000 onRestore: (fn) => restoreFns.push(fn),
1001 onRefetch: () => {},
1002 });
1003
1004 const queryNonexistent = queryOptions({
1005 queryKey: ["nonexistent"],
1006 queryFn: (): TestData => initialData,
1007 });
1008
1009 helpers.removeQuery(queryNonexistent);
1010
1011 assertEquals(restoreFns.length, 0);
1012});
1013
1014// ============================================================================
1015// refetchOnSettled() tests
1016// ============================================================================
1017
1018test("refetchOnSettled - should schedule a refetch without modifying data", () => {
1019 const { client, queryTest } = createTestQueryClient();
1020 const refetchFns: Array<() => void> = [];
1021 const restoreFns: Array<() => void> = [];
1022
1023 const helpers = queryClientOptimisticHelpers(client)({
1024 onRestore: (fn) => restoreFns.push(fn),
1025 onRefetch: (fn) => refetchFns.push(fn),
1026 });
1027
1028 const originalData = client.getQueryData<TestData>(queryTest.queryKey);
1029
1030 helpers.refetchOnSettled(queryTest);
1031
1032 const result = client.getQueryData<TestData>(queryTest.queryKey);
1033 // Data should not be modified
1034 assertEquals(result, originalData);
1035
1036 // A refetch should have been scheduled
1037 assertEquals(refetchFns.length, 1);
1038
1039 // No restore callbacks should be registered
1040 assertEquals(restoreFns.length, 0);
1041});
1042
1043test("refetchOnSettled - should skip if query doesn't exist", () => {
1044 const { client } = createTestQueryClient();
1045 const refetchFns: Array<() => void> = [];
1046 const restoreFns: Array<() => void> = [];
1047
1048 const helpers = queryClientOptimisticHelpers(client)({
1049 onRestore: (fn) => restoreFns.push(fn),
1050 onRefetch: (fn) => refetchFns.push(fn),
1051 });
1052
1053 const queryNonexistent = queryOptions({
1054 queryKey: ["nonexistent"],
1055 queryFn: (): TestData => initialData,
1056 });
1057
1058 helpers.refetchOnSettled(queryNonexistent);
1059
1060 // No refetch should be scheduled for non-existent query
1061 assertEquals(refetchFns.length, 0);
1062 assertEquals(restoreFns.length, 0);
1063});
1064
1065test("refetchOnSettled - should deduplicate refetches for the same query", () => {
1066 const { client, queryTest } = createTestQueryClient();
1067 const refetchFns: Array<() => void> = [];
1068 const restoreFns: Array<() => void> = [];
1069
1070 const helpers = queryClientOptimisticHelpers(client)({
1071 onRestore: (fn) => restoreFns.push(fn),
1072 onRefetch: (fn) => refetchFns.push(fn),
1073 });
1074
1075 // Call refetchOnSettled multiple times on the same query
1076 helpers.refetchOnSettled(queryTest);
1077 helpers.refetchOnSettled(queryTest);
1078 helpers.refetchOnSettled(queryTest);
1079
1080 // Only one refetch should be scheduled (deduplicated by query hash)
1081 assertEquals(refetchFns.length, 1);
1082 assertEquals(restoreFns.length, 0);
1083});
1084
1085// ============================================================================
1086// Integration tests
1087// ============================================================================
1088
1089test("integration - multiple operations work together", () => {
1090 const { client, queryTest } = createTestQueryClient();
1091 const restoreFns: Array<() => void> = [];
1092
1093 const helpers = queryClientOptimisticHelpers(client)({
1094 onRestore: (fn) => restoreFns.push(fn),
1095 onRefetch: () => {},
1096 });
1097
1098 // Perform multiple operations
1099 helpers.objIncrement(queryTest, ["count"], 5);
1100 helpers.objArrayPush(queryTest, ["tags"], "delta");
1101 helpers.objToggle(queryTest, ["active"]);
1102 helpers.objArrayRemove(queryTest, ["items"], (item) => item.id === 2);
1103
1104 const result = client.getQueryData<TestData>(queryTest.queryKey);
1105 assertEquals(result?.count, 15);
1106 assertEquals(result?.tags, ["alpha", "beta", "gamma", "delta"]);
1107 assertEquals(result?.active, false);
1108 assertEquals(result?.items.length, 2);
1109
1110 // Restore in reverse order
1111 restoreFns.reverse().forEach((fn) => fn());
1112
1113 const restored = client.getQueryData<TestData>(queryTest.queryKey);
1114 assertEquals(restored?.count, 10);
1115 assertEquals(restored?.tags, ["alpha", "beta", "gamma"]);
1116 assertEquals(restored?.active, true);
1117 assertEquals(restored?.items.length, 3);
1118});
1119
1120// ============================================================================
1121// Mutation integration: each call owns the restores and refetches its helpers register
1122// ============================================================================
1123
1124function createToggleClient() {
1125 const queryClient = new QueryClient({
1126 defaultOptions: { queries: { retry: false } },
1127 });
1128 const server = { enabled: true, online: true, fetches: 0 };
1129
1130 const queryToggle = queryOptions({
1131 queryKey: ["toggle"],
1132 queryFn: async () => {
1133 server.fetches += 1;
1134 if (!server.online) throw new Error("offline");
1135 return { enabled: server.enabled };
1136 },
1137 });
1138 queryClient.setQueryData(queryToggle.queryKey, { enabled: true });
1139 // Observed, so invalidation refetches it; the refetch fails while offline.
1140 new QueryObserver(queryClient, queryToggle).subscribe(() => {});
1141
1142 const mutations = new MutationClient({
1143 context: {},
1144 getOptimisticHelpers: queryClientOptimisticHelpers(queryClient),
1145 reportError: () => {},
1146 });
1147
1148 const save = async (enabled: boolean) => {
1149 await delay(10);
1150 if (!server.online) throw new Error("offline");
1151 server.enabled = enabled;
1152 return enabled;
1153 };
1154 const read = () => queryClient.getQueryData(queryToggle.queryKey)?.enabled;
1155
1156 return { queryClient, queryToggle, server, mutations, save, read };
1157}
1158
1159test("a failure does not replay the helper restores of a call that succeeded", async () => {
1160 vi.useFakeTimers();
1161 const { queryToggle, server, mutations, save, read } = createToggleClient();
1162 const mutToggle = mutations.define({
1163 id: "toggle",
1164 mutate: save,
1165 optimistic: ({ helpers, args: [enabled] }) => {
1166 helpers.updateExisting(queryToggle, { enabled });
1167 },
1168 describe: "toggle",
1169 describeResult: null,
1170 });
1171 // `useMutate` keeps the channel alive between calls
1172 mutToggle.subscribe(mutToggle.key([true]), () => {});
1173
1174 mutToggle.run(false);
1175 await vi.advanceTimersByTimeAsync(100);
1176 assertEquals([server.enabled, read()], [false, false]);
1177
1178 server.online = false;
1179 mutToggle.run(true);
1180 assertEquals(read(), true);
1181 await vi.advanceTimersByTimeAsync(100);
1182 assertEquals(read(), false);
1183});
1184
1185test("a queued failure does not replay the helper restores of the call ahead of it", async () => {
1186 vi.useFakeTimers();
1187 const { queryToggle, server, mutations, save, read } = createToggleClient();
1188 const mutToggle = mutations.define({
1189 id: "toggle",
1190 mutate: save,
1191 optimistic: ({ helpers, args: [enabled] }) => {
1192 helpers.updateExisting(queryToggle, { enabled });
1193 },
1194 describe: "toggle",
1195 describeResult: null,
1196 });
1197
1198 mutToggle.run(false);
1199 mutToggle.run(true);
1200 await vi.advanceTimersByTimeAsync(10);
1201 assertEquals(server.enabled, false);
1202
1203 server.online = false;
1204 await vi.advanceTimersByTimeAsync(100);
1205 assertEquals(read(), false);
1206});
1207
1208test("a success retires its own onRestore callbacks, not the channel's oldest restores", async () => {
1209 vi.useFakeTimers();
1210 const { queryToggle, server, mutations, save, read } = createToggleClient();
1211 let lastChoice: boolean | null = null;
1212 const mutToggle = mutations.define({
1213 id: "toggle",
1214 mutate: save,
1215 optimistic: ({ helpers, args: [enabled], onRestore }) => {
1216 helpers.updateExisting(queryToggle, { enabled });
1217 const prev = lastChoice;
1218 lastChoice = enabled;
1219 onRestore(() => {
1220 lastChoice = prev;
1221 });
1222 },
1223 describe: "toggle",
1224 describeResult: null,
1225 });
1226 mutToggle.subscribe(mutToggle.key([true]), () => {});
1227
1228 mutToggle.run(false);
1229 await vi.advanceTimersByTimeAsync(100);
1230
1231 server.online = false;
1232 mutToggle.run(true);
1233 await vi.advanceTimersByTimeAsync(100);
1234 assertEquals([lastChoice, read()], [false, false]);
1235});
1236
1237test("an optimistic update that throws restores its helper updates", () => {
1238 const { queryToggle, mutations, save, read } = createToggleClient();
1239 const mutToggle = mutations.define({
1240 id: "toggle",
1241 mutate: save,
1242 optimistic: ({ helpers, args: [enabled] }) => {
1243 helpers.updateExisting(queryToggle, { enabled });
1244 throw new Error("optimistic update failed");
1245 },
1246 describe: "toggle",
1247 describeResult: null,
1248 });
1249
1250 mutToggle.run(false);
1251 assertEquals(read(), true);
1252});
1253
1254test("a skipped no-op call's helper restores are not replayed by a later failure", async () => {
1255 vi.useFakeTimers();
1256 const { queryClient, queryToggle, server, mutations, save, read } = createToggleClient();
1257 const mutToggle = mutations.define({
1258 id: "toggle",
1259 mutate: save,
1260 optimistic: ({ helpers, args: [enabled] }) => {
1261 helpers.updateExisting(queryToggle, { enabled });
1262 },
1263 snapshot: () => read(),
1264 describe: "toggle",
1265 describeResult: null,
1266 });
1267
1268 mutToggle.run(true);
1269 // Another client turns it off.
1270 server.enabled = false;
1271 queryClient.setQueryData(queryToggle.queryKey, { enabled: false });
1272
1273 server.online = false;
1274 mutToggle.run(true);
1275 await vi.advanceTimersByTimeAsync(100);
1276 assertEquals(read(), false);
1277});
1278
1279test("a debounced success retires the helper restores of every call it covers", async () => {
1280 vi.useFakeTimers();
1281 const { queryToggle, server, mutations, save, read } = createToggleClient();
1282 const mutToggle = mutations.define({
1283 id: "toggle",
1284 mutate: save,
1285 optimistic: ({ helpers, args: [enabled] }) => {
1286 helpers.updateExisting(queryToggle, { enabled });
1287 },
1288 describe: "toggle",
1289 describeResult: null,
1290 debounceMs: 50,
1291 });
1292 mutToggle.subscribe(mutToggle.key([true]), () => {});
1293
1294 mutToggle.run(false);
1295 mutToggle.run(false);
1296 await vi.advanceTimersByTimeAsync(200);
1297 assertEquals([server.enabled, read()], [false, false]);
1298
1299 server.online = false;
1300 mutToggle.run(true);
1301 await vi.advanceTimersByTimeAsync(200);
1302 assertEquals(read(), false);
1303});
1304
1305test("every call refetches the queries its helpers touched", async () => {
1306 vi.useFakeTimers();
1307 const { queryToggle, server, mutations, save } = createToggleClient();
1308 const mutToggle = mutations.define({
1309 id: "toggle",
1310 mutate: save,
1311 optimistic: ({ helpers, args: [enabled] }) => {
1312 helpers.updateExisting(queryToggle, { enabled });
1313 },
1314 describe: "toggle",
1315 describeResult: null,
1316 });
1317 mutToggle.subscribe(mutToggle.key([true]), () => {});
1318 await vi.advanceTimersByTimeAsync(0);
1319 const fetchesBefore = server.fetches;
1320
1321 mutToggle.run(false);
1322 await vi.advanceTimersByTimeAsync(100);
1323 assertEquals(server.fetches, fetchesBefore + 1);
1324
1325 mutToggle.run(true);
1326 await vi.advanceTimersByTimeAsync(100);
1327 assertEquals(server.fetches, fetchesBefore + 2);
1328});
1329
1330test("a queued call refetches after its own write, not with the call ahead of it", async () => {
1331 vi.useFakeTimers();
1332 const { queryToggle, server, mutations, save, read } = createToggleClient();
1333 const mutToggle = mutations.define({
1334 id: "toggle",
1335 mutate: save,
1336 optimistic: ({ helpers, args: [enabled] }) => {
1337 helpers.updateExisting(queryToggle, { enabled });
1338 },
1339 describe: "toggle",
1340 describeResult: null,
1341 });
1342
1343 mutToggle.run(false);
1344 mutToggle.run(true);
1345 await vi.advanceTimersByTimeAsync(100);
1346 assertEquals([server.enabled, read()], [true, true]);
1347});