Resumability without $ boundaries and serialization rules: controlled granularity component level Resumability

[maiieul]

What is it about?

Splitting Qwik apps only at the component level into instantiate and render segments, so that no $() wrappers and serialization rules are needed.

What's the motivation for this proposal?

Problems you are trying to solve:

• Serialization rules (https://qwik.dev/docs/concepts/resumable/#serialization)

Goals you are trying to achieve:

• No need for useSerializer$, classes and Stream just work, ecosystem and agnostic tools can make Qwik versions of their tool easily

---

Proposed Solution / Feature

What do you propose?

Splitting the code into QRL segments only at the component level into 1 instantiate and 1 render segment for each component.

This shifts the responsibility of splitting the code to the developer a little bit, but also gives them more control in keeping the logical pieces together. In the normal case they should not worry about it unless they write extremely big components. If the user experienced performance is similar, then maybe that's an acceptable or even desirable, less magical tradeoff for the developer.

Having separate segments for instantiate and render allows for not shipping render functions to the client in the case of SSR.

Code examples

Consider:

import { component$, useSignal, Signal, useTask } from "@qwik.dev/core";

export default () => {
  const count = useSignal(0);
  const handleClick = () => count.value++;
  
   useTask(({track}) => {
      track(count);
      if(count.value === 0) count.value++; // Runs on server
      if(count.value === 2) count.value++; // Runs on user click
   })

  return (
    <>
      <ChildButton handleClick={handleClick} parentCount={count} />
      <br/>
      <ChildButton handleClick={handleClick} parentCount={count} />
    </>
  );
};

export const ChildButton = ({ handleClick, parentCount }: { handleClick: () => void; parentCount: Signal<number> }) => {
    const count = useSignal(0);
    return (
      <>
        {parentCount.value}
        <button onClick={() => { 
            handleClick(); 
            count.value++;
         }}>
            {count.value}
         </button>
      </>
    );
  };

The optimizer would turn it into:

// App.js   — instantiate
// App.js   — instantiate (state + handlers + TASKS, all coarse in one chunk)
import { componentQrl, qrl, useSignal, useTask } from "./core-XXX.js";

export function App_instantiate(scope) {
  const count = useSignal(0, scope.count);

  useTask(({ track }) => {
    track(count);
    if (count.value === 0) count.value++;
    if (count.value === 2) count.value++;
  });

  const handleClick = () => count.value++;

  return { count, handleClick };
}

export const App = componentQrl({
  instantiate: qrl(import.meta, "App_instantiate"),
  render: qrl(() => import("./App-render-YYY.js"), "App_render"),
});
export default App;

// App-render-YYY.js   — render
import { _jsxSorted, componentQrl, qrl, Fragment } from "./core-XXX.js";

const ChildButton = componentQrl({
  instantiate: qrl(() => import("./ChildButton.js"), "ChildButton_instantiate"),
  render: qrl(() => import("./ChildButton-render-ZZZ.js"), "ChildButton_render"),
});

export function App_render(instance) {
  return _jsxSorted(Fragment, null, null, [
    _jsxSorted(ChildButton, {
      handleClick: { $instance: "self", sym: "handleClick" },
      parentCount: instance.count,
    }, null, null, 2, "ga_0", /* loc */),
    _jsxSorted("br", null, null, null, 3, null, /* loc */),
    _jsxSorted(ChildButton, {
      handleClick: { $instance: "self", sym: "handleClick" },
      parentCount: instance.count,
    }, null, null, 2, "ga_1", /* loc */),
  ], 1, "ga_2", /* loc */);
}

// ChildButton.js   — instantiate
import { componentQrl, qrl, useSignal } from "./core-XXX.js";

export function ChildButton_instantiate(scope) {
  const count = useSignal(0, scope.count);
  const onClick = () => { scope.handleClick(); count.value++; };
  return { count, onClick };
}

export const ChildButton = componentQrl({
  instantiate: qrl(import.meta, "ChildButton_instantiate"),
  render: qrl(() => import("./ChildButton-render-ZZZ.js"), "ChildButton_render"),
});
export default ChildButton;

// ChildButton-render-ZZZ.js   — render
import { _jsxSorted, Fragment } from "./core-XXX.js";

export function ChildButton_render(instance, scope) {
  return _jsxSorted(Fragment, null, null, [
    scope.parentCount,
    _jsxSorted("button", {
      "q-e:click": [{ $instance: "self", sym: "onClick" }],
    }, null, instance.count, 2, "ga_3", /* loc */),
  ], 1, null, /* loc */);
}

HTML output:

<body :="">
  0<button q-e:click="0" :="">0</button>
  <br :="">
  0<button q-e:click="9" :="">0</button>
  <script type="qwik/state" :="">[/* roots — decoded below */]</script>
  <script type="qwik/vnode" :="">$~H{...vPC1, vBtn1, vPC2, vBtn2...}</script>
  <script :="">(window._qwikEv||(window._qwikEv=[])).push("e:click")</script>
</body>

decoded state graph:

0  QRL "2#3@1"                            <- button 1's onClick: chunk@2, sym@3, scope@1
1  Object [                               <- ChildButton inst 1 scope (flat)
     {string} "handleClick"
     QRL "4#5@6"                          <- App.handleClick: chunk@4, sym@5, scope@6
     {string} "parentCount"
     Ref 7                                <- S_app
     {string} "count"
     Ref 8                                <- S_c1
   ]
2  {string} "../ChildButton.js"
3  {string} "onClick"
4  {string} "../App.js"
5  {string} "handleClick"
6  Object [ {string} "count" -> Ref 7 ]   <- App scope (flat)
7  Signal [{number} 1, subs: [11, 12, 13]]  <- S_app = 1 (post-task); subs: TASK + two <div> texts
8  Signal [{number} 0, subs: [14]]          <- S_c1 = 0; sub: child 1 button text
9  QRL "2#3@10"                            <- button 2's onClick: scope@10
10 Object [                               <- ChildButton inst 2 scope (flat)
     {string} "handleClick"
     QRL "4#5@6"
     {string} "parentCount"
     Ref 7
     {string} "count"
     Ref 15
   ]
11 TaskSubscription [                      <- App's useTask — subscriber of S_app
     scope: Ref 6                          <- materialize App (via ../App.js) to rebuild the task closure
     index: 0                              <- task #0 of this instance
   ]
12 EffectSubscription [ VNode "vDiv1" ]    <- child 1 <div> text ← S_app
13 EffectSubscription [ VNode "vDiv2" ]    <- child 2 <div> text ← S_app
14 EffectSubscription [ VNode "vBtn1" ]    <- child 1 button text ← S_c1
15 Signal [{number} 0, subs: [16]]         <- S_c2 = 0
16 EffectSubscription [ VNode "vBtn2" ]    <- child 2 button text ← S_c2

Example User Flow

click → q-e:click="0" → root 0 → ../ChildButton.js#onClick, scope root 1
      → preload ../ChildButton.js + ../App.js (via scope1.handleClick = QRL "4#5@6")  ‖
      → materialize ChildButton inst 1 (scope root 1): { count=S_c1(0), onClick }
      → invoke onClick():
          scope.handleClick() → resolve QRL "4#5@6":
            materialize App (scope root 6): useSignal restores count=S_app(1);
              useTask REGISTERS task (subscribes to count) — does NOT run (count unchanged at 1);
              returns { count, handleClick }
            invoke handleClick() → S_app: 1 → 2
              └─ count changed → notify subs [task 11, div 12, div 13]
                 task runs: count===2 → count++ → S_app: 2 → 3
                   └─ count changed → task re-runs: count===0? no, ===2? no → settle
                 div effects 12,13 → both <div> → "3"
          count.value++  (child's own) → S_c1: 0 → 1 → effect 14 → child-1 button → "1"

Loaded this click: 2 instantiate chunks (~a few hundred bytes). Render chunks: still none..

---

Links / References

No response