Automatic code extraction #2 – no $() wrappers

[maiieul]

What is it about?

Automatically extracting inner helper functions inside components to reduce confusion, boilerplate and gotchas caused by QRL $() wrappers. Instead of extracting into QRLs through $() wrappers, we can extract by changing the functions signatures, accepting an extra argument.

The mental model shifts from "magic happens in $()", to "magic happens in component$ and hooks" – which is the actual place where it needs to happen in practice. With the former approach, the developer must learn to manually wrap functions with $() and how to deal with those boundaries, while with the latter the developer only needs to learn how to deal with the component$ and hooks boundaries.

What's the motivation for this proposal?

Problems you are trying to solve:

The $() API

• is confusing -> Where (outside or inside the components ?), when (why do I need to wrap inside the component but not outside?, should inner inner helper functions?), and how (should I wrap at the call site or assignment?)
• adds boilerplate -> forces the developer into wrapping every inner helpers with $()
• has gotchas -> synce QRLs are async, synchronous code will execute before non awaited QRLs on first interactions because of the browser event loop mechanism.
• has constraints -> $() only accepts serializable closures (e.g. no classes or factory functions).

The reason why we are currently forced to wrap inner helper functions with $() is because those functions need to be extracted. They need to be extracted so that event handlers and children can call the functions directly without waking up other handlers/children. To do this extraction, we use QRLs, which in turn makes those functions lazy-loadable. We therefore need to let the developer know that the API is async, and we do that with the explicit $() wrapper. In theory though, inner helper functions don't need to be lazy-loadable and should actually be synchronous, because helper functions can only be called by an actual event handler (e.g. onClick$, useTask$, useVisibleTask$, etc.) and cannot be called on their own. Event handlers are the only nodes that really need to be lazy-loadable on demand.

Note: even custom event props (e.g. onTripleClick$) can only be called through event handlers and should therefore be synchronous too in theory, but this would require the optimizer to transform Parent and Child code altogether and would make the optimizer logic hard to reason about. Perhaps it is achievable, but the change would be so big that this is out of scope for this proposal.

Goals you are trying to achieve:

Consider:

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

export default component$(() => {
  const count = useSignal(0);
  const increment$ = $(() => {
    console.log("incrementing");
    count.value++;
  });

  const decrement$ = $(() => {
    console.log("decrementing");
    count.value--;
  });
  return (
    <>
      <button
        onClick$={async () => {
          console.log("parent onClick$ increment");
          await increment$();
        }}
      >
        increment
      </button>
      <br />
      <ChildButton
        handleClick$={async () => {
          console.log("parent handleClick$ increment");
          await increment$();
        }}
        name="child increment"
      />
      <ChildButton
        handleClick$={async () => {
          console.log("parent handleClick$ decrement");
          await decrement$();
        }}
        name="child decrement"
      />
      <br />
      {count.value}
    </>
  );
});

export const ChildButton = component$(
  ({ handleClick$, name }: { handleClick$: QRL<() => void>; name: string }) => {
    return (
      <button
        onClick$={async () => {
          console.log("child onClick$");
          await handleClick$();
        }}
      >
        {name}
      </button>
    );
  },
);

could be simplified into:

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

export default component$(() => {
  const count = useSignal(0);
  const increment = () => {
    console.log("incrementing");
    count.value++;
  };

  const decrement = () => {
    console.log("decrementing");
    count.value--;
  };
  return (
    <>
      <button
        onClick$={() => {
          console.log("parent onClick$ increment");
          increment();
        }}
      >
        increment
      </button>
      <br />
      <ChildButton
        handleClick$={() => {
          console.log("parent handleClick$ increment");
          increment();
        }}
        name="child increment"
      />
      <ChildButton
        handleClick$={() => {
          console.log("parent handleClick$ decrement");
          decrement();
        }}
        name="child decrement"
      />
      <br />
      {count.value}
    </>
  );
});

export const ChildButton = component$(
  ({ handleClick$, name }: { handleClick$: QRL<() => void>; name: string }) => {
    return (
      <button
        onClick$={async () => {
          console.log("child onClick$");
          await handleClick$();
        }}
      >
        {name}
      </button>
    );
  },
);

Notice that both the increment and decrement functions now become synchronous, but the handleClick$ prop remains a QRL due to the optimizer 'one file transform at a time' constraint that we currently enforce.

This would:

• Reduce confusion -> All helper functions (inner and outer) are synchronous by default like vanilla js. No question about where/when/how to wrap with $(). Only the event handlers (e.g. onClick$) and component$, useTask$, useVisibleTask$, etc. are marked with $, clearly expressing that they need to be lazy loaded boundaries.
• Reduce boilerplate -> No more $() wrappers and resulting async/await calls.
• Reduce gotchas -> No more 'fire and forget' QRL calls that actually run after the synchrnous code below it because of the event loop. What is async and sync is a dictated by what the developer wants to do, not by the necessity of wrapping code with $().

Solution

What do you propose?

Instead of extracting through QRLs, I explored automatically extracting all the component inner helpers and add an object param (as the last param) that takes in the closed over variables.

So instead of trasforming

  const increment$ = $(() => {
    console.log("incrementing");
    count.value++;
  });

into

import { _captures } from "@qwik.dev/core";
export const TestButton_component_increment_V6FcLe11OrU = ()=>{
    const count = _captures[0];
    console.log("incrementing");
    count.value++;
};

which would then be called using captures:

import { _captures } from "@qwik.dev/core";
export const TestButton_component_Fragment_button_q_e_click_hOLZleZIsX4 = async ()=>{
    const increment$ = _captures[0];
    await increment$();
    console.log("incremented");
};

we'd transform

  const increment = () => {
    console.log("incrementing");
    count.value++;
  };

into

export const TestButton_component_increment_V6FcLe11OrU = ({count})=>{
    console.log("incrementing");
    count.value++;
};

which would then be called like

import { _captures } from "@qwik.dev/core";
import { TestButton_component_increment_V6FcLe11OrU } from "./test.tsx_TestButton_component_increment_V6FcLe11OrU.js";
export const TestButton_component_Fragment_button_q_e_click_hOLZleZIsX4 = ()=>{
    const count = _captures[0];
    TestButton_component_increment_V6FcLe11OrU({count});
    console.log("incremented");
};

Instead of capturing the function itself, the segments would capture it's closed over variables (count in this case).

See the diff here to see what the entire optimizer output would look like.

Now if the component inner helper functions don't need to be wrapped with $(), we can also change useOnDocument/useOnWindow/useOn to useOnDocument$/useOnWindow$/useOn$ and we can deprecate the need for a public $() API.

The contraints remain the same, inner helper functions inside component$ closing over other component$ values have special rules, but the mental model is closer to the practical constraint and therefore easier. Instead of telling the developer to wrap every inner helper functions with $() and that special rules apply to those functions, we only tell the developer that special rules apply inside of component$ (and in hooks, which are bound to be used in component$).

Playgrounds:

1. External non Qwik lib factory
2. useIncrement hook
3. External class

---

Links / References

No response