feat: defer directives (#864)

Author: tien

.changeset/tender-years-draw.md

@@ -0,0 +1,7 @@
+---
+"@reactive-dot/react": minor
+"@reactive-dot/core": minor
+"@reactive-dot/vue": minor
+---
+
+Introduced the `defer` directive to enable incremental loading for single queries, improving performance and user experience by allowing partial data to be rendered as it becomes available.

apps/docs/react/guides/incremental-loading.md

@@ -4,6 +4,36 @@ sidebar_position: 4
 
 # Incremental loading
 
+## `defer`
+
+The `defer` directive may be specified on a query to imply de-prioritization, that causes the data to be in [`pending`](/api/core#pending) state in the initial response, and delivered as a subsequent response afterward. For React, this can also be used to opt-out of suspending.
+
+:::info
+
+When you pass `{ defer: true }` to the query, the result will now be either:
+
+- A resolved value (the response you expect), or
+- A special [`pending`](/api/core#pending) symbol from `@reactive-dot/core`, indicating that the data hasn’t arrived yet.
+
+:::
+
+```tsx
+import { pending } from "@reactive-dot/core";
+import { useLazyLoadQuery } from "@reactive-dot/react";
+
+export function Tvl() {
+  const tvl = useLazyLoadQuery((query) =>
+    query.storage("NominationPools", "TotalValueLocked", [], { defer: true }),
+  );
+
+  if (tvl === pending) {
+    return <progress />;
+  }
+
+  return <p>Total value locked: {tvl}</p>;
+}
+```
+
 ## `stream`
 
 For multi-entry queries like `storages`, `runtimeApis`, etc., the `stream` directive allows the client to receive partial results as they become available, before the entire response is ready.
@@ -35,7 +65,7 @@ This works well for a small number of accounts, where results load quickly. But
 When you pass `{ stream: true }` to the query, each item in the result array will now be either:
 
 - A resolved value (the response you expect), or
-- A special `pending` symbol from `@reactive-dot/core`, indicating that the data for that item hasn’t arrived yet.
+- A special [`pending`](/api/core#pending) symbol from `@reactive-dot/core`, indicating that the data for that item hasn’t arrived yet.
 
 :::
 

apps/docs/vue/guides/incremental-loading.md

@@ -4,6 +4,34 @@ sidebar_position: 3
 
 # Incremental loading
 
+## `defer`
+
+The `defer` directive may be specified on a query to imply de-prioritization, that causes the data to be in [`pending`](/api/core#pending) state in the initial response, and delivered as a subsequent response afterward.
+
+:::info
+
+When you pass `{ defer: true }` to the query, the result will now be either:
+
+- A resolved value (the response you expect), or
+- A special [`pending`](/api/core#pending) symbol from `@reactive-dot/core`, indicating that the data hasn’t arrived yet.
+
+:::
+
+```vue
+<script setup lang="ts">
+import { useLazyLoadQuery } from "@reactive-dot/vue";
+
+const { data: tvl } = await useLazyLoadQuery((query) =>
+  query.storage("NominationPools", "TotalValueLocked", [], { defer: true }),
+);
+</script>
+
+<template>
+  <progress v-if="tvl === pending" />
+  <p v-else>Total staked: {{ totalStaked }}</p>
+</template>
+```
+
 ## `stream`
 
 For multi-entry queries like `storages`, `runtimeApis`, etc., the `stream` directive allows the client to receive partial results as they become available, before the entire response is ready.

packages/core/src/actions/query.test.ts

@@ -59,6 +59,9 @@ describe("preflight", () => {
       api: "foo",
       args: [],
       at: undefined,
+      directives: {
+        defer: undefined,
+      },
     } as SimpleQueryInstruction;
 
     expect(preflight(instruction)).toBe("promise");
@@ -71,6 +74,9 @@ describe("preflight", () => {
       storage: "foo",
       args: [],
       at: undefined,
+      directives: {
+        defer: undefined,
+      },
     } as SimpleQueryInstruction;
 
     expect(preflight(instruction)).toBe("observable");
@@ -83,6 +89,9 @@ describe("preflight", () => {
       storage: "foo",
       args: [],
       at: undefined,
+      directives: {
+        defer: undefined,
+      },
     } as SimpleQueryInstruction;
 
     expect(preflight(instruction)).toBe("observable");
@@ -95,6 +104,9 @@ describe("preflight", () => {
       storage: "foo",
       args: [1],
       at: "0x1234",
+      directives: {
+        defer: undefined,
+      },
     } as SimpleQueryInstruction;
 
     expect(preflight(instruction)).toBe("promise");
@@ -136,6 +148,9 @@ it('should handle "read-storage" instruction with at starting with "0x" (using g
     storage: "foo",
     args: [3],
     at: "0xabc",
+    directives: {
+      defer: undefined,
+    },
   } as SimpleQueryInstruction;
 
   const result = await query(fakeApi, instruction);
@@ -170,6 +185,9 @@ it('should handle "read-storage-entries" instruction with at starting with "0x"
     storage: "foo",
     args: [3],
     at: "0xabc",
+    directives: {
+      defer: undefined,
+    },
   } as SimpleQueryInstruction;
 
   const result = await query(fakeApi, instruction);

packages/core/src/contract/ink/query-builder.test.ts

@@ -21,6 +21,9 @@ describe("rootStorage", () => {
       [
         {
           "at": undefined,
+          "directives": {
+            "defer": undefined,
+          },
           "instruction": "read-storage",
           "key": undefined,
           "path": "",
@@ -35,6 +38,9 @@ describe("rootStorage", () => {
       [
         {
           "at": "finalized",
+          "directives": {
+            "defer": undefined,
+          },
           "instruction": "read-storage",
           "key": undefined,
           "path": "",
@@ -51,6 +57,9 @@ describe("storage", () => {
       [
         {
           "at": undefined,
+          "directives": {
+            "defer": undefined,
+          },
           "instruction": "read-storage",
           "key": undefined,
           "path": "test-path",
@@ -65,6 +74,9 @@ describe("storage", () => {
       [
         {
           "at": undefined,
+          "directives": {
+            "defer": undefined,
+          },
           "instruction": "read-storage",
           "key": "key-value",
           "path": "test-path",
@@ -81,6 +93,9 @@ describe("storage", () => {
       [
         {
           "at": "finalized",
+          "directives": {
+            "defer": undefined,
+          },
           "instruction": "read-storage",
           "key": "key-value",
           "path": "test-path",
@@ -98,6 +113,7 @@ describe("storages", () => {
         {
           "at": undefined,
           "directives": {
+            "defer": undefined,
             "stream": undefined,
           },
           "instruction": "read-storage",
@@ -121,6 +137,7 @@ describe("storages", () => {
         {
           "at": "finalized",
           "directives": {
+            "defer": undefined,
             "stream": undefined,
           },
           "instruction": "read-storage",
@@ -144,6 +161,9 @@ describe("message", () => {
         {
           "at": undefined,
           "body": undefined,
+          "directives": {
+            "defer": undefined,
+          },
           "instruction": "send-message",
           "name": "test-message",
           "origin": undefined,
@@ -161,6 +181,9 @@ describe("message", () => {
           "body": {
             "foo": "bar",
           },
+          "directives": {
+            "defer": undefined,
+          },
           "instruction": "send-message",
           "name": "test-message",
           "origin": undefined,
@@ -182,6 +205,9 @@ describe("message", () => {
           "body": {
             "foo": "bar",
           },
+          "directives": {
+            "defer": undefined,
+          },
           "instruction": "send-message",
           "name": "test-message",
           "origin": undefined,
@@ -210,6 +236,7 @@ describe("messages", () => {
             },
           ],
           "directives": {
+            "defer": undefined,
             "stream": undefined,
           },
           "instruction": "send-message",
@@ -240,6 +267,7 @@ describe("messages", () => {
             },
           ],
           "directives": {
+            "defer": undefined,
             "stream": undefined,
           },
           "instruction": "send-message",
@@ -265,6 +293,9 @@ describe("chaining", () => {
     expect(query.instructions[0]).toMatchInlineSnapshot(`
       {
         "at": undefined,
+        "directives": {
+          "defer": undefined,
+        },
         "instruction": "read-storage",
         "key": "key1",
         "path": "path1",
@@ -273,6 +304,9 @@ describe("chaining", () => {
     expect(query.instructions[4]).toMatchInlineSnapshot(`
       {
         "at": "finalized",
+        "directives": {
+          "defer": undefined,
+        },
         "instruction": "read-storage",
         "key": undefined,
         "path": "",