Feature request: more lifecycle callbacks.

[yyny]

Proposing:

• this.afterElement(callback?) - like this.after(...), but only executes when the passed value (the element) changes (loose inequality), passing the new element. Can be called without arguments to return a Promise that awaits an element change (and returns the new element).

• this.cleanupElement(callback?) - like this.after(...), but only executes when the passed value (the element) changes (loose inequality), passing the old element. The callback can also be called on this.cleanup(...) (but the callback only ever gets executed once). Can be called without arguments to return a Promise that awaits an element change (and returns the old element).

• this.scheduleEach(callback) - like this.schedule(...), but executes the callback before each render.

• this.afterEach(callback) - like this.after(...), but executes the callback after each render.

• this.afterEachElement(callback) - like this.afterEach(...), but only executes when the passed value (the element) changes (loose inequality), passing the new element.

• this.cleanupEachElement(callback) - like this.afterEach(...), but only executes when the the passed value (the element) changes (loose inequality), passing the old element. The callback also gets called on this.cleanup(...).

Note that the last four can just be implemented à la requestAnimationFrame, but they still save a few line of code and are a bit easier to read (plus it's nice to have symmetry in the API).

These proposed functions can be implemented in userspace with an injectHelpers(this) or something similar, but they can be hard to get right, and I think they are useful enough to be included in Crank itself.

afterEachElement and cleanupEachElement in particular are useful for managing element-based state like ResizeObserver more easily.

[brainkim]

Dank u wel for this careful API design proposal! I enjoyed thinking about your schedule()/after()/cleanup() variations while on a walk over the weekend. We can visualize the proposed methods via the following table:

Existing Method	+ Each	+ Element	+ Each + Element
schedule()	scheduleEach()	N/A?	N/A?
after()	afterEach()	afterElement()	afterEachElement()
cleanup()	N/A	cleanupElement()	cleanupEachElement()

You’ve proposed an “each” variation of schedule and after which runs each time the lifecycle happens. You can call schedule/after via a recursive function like you would with requestAnimationFrame(), as you noted, but you want a convenience API.

// workaround
function *Component({children}) {
  function eachAfter(el) {
    // execute some code after the DOM is fully rendered
    // recursive call like RAF
    this.after(eachAfter);
  }

  this.after(eachAfter);

  for ({children} of this) {
    yield children;
  }
}

I have good news and bad news. The bad news, I don’t think adding *Each() methods would be good for this use-case. The callback-based this.schedule() and this.after() methods only work because the callback is only called the next time the lifecycle moment happens, and if it were to repeat, we would need some way to unschedule() and unafter() to stop calling the callback if you want it to stop firing. The callback APIs are designed to be called in render loops, and the single callback API becomes much less ergonomic if the callbacks are persistent, repeated.

The good news, I do think being able to listen for schedule and after repeatedly is valid use-case, and I’m open to the idea of having special lifecycle events. Remember that Crank this contexts are EventTarget interfaces, so we could theoretically dispatch special events which map to the methods.

function *Component({children}) {
  function onafter(ev) {
    /* ... */
  }
  // no new methods, just new events
  this.addEventListener("after", onafter);
  this.removeEventListener("after", onafter);

  for ({children} of this) {
    yield children;
  }
}

This API would be much more economical (0 new methods, 3 new events which map to lifecycle), and it solves the unlistening problem. But this API raises questions, like what is the event which is passed into the listener, does this event have any data or methods, does the event types need to be namespaced?

Let me know what you think about this alternative.

You’ve proposed an “element” variation to the callbacks. These callbacks would trigger once/each time a component’s value has changed.

This is interesting but I have to remind you that Crank components have a zero to many relationship with the number of DOM nodes which are rendered, so “loose equality” would have to account for arrays of elements turning to null, null turning to arrays of elements, elements turning to text nodes, etc. Components can basically render anything, and this can be dynamic based on children or other data, so listening for when this “changes” will require you to handle a lot of cases. What does “loose equality” mean?

Typically, when you want to do DOM manipulation with a specific element, you want to wrap it closely and prefer that it exist for the lifecycle of the element (so <MyButton> always renders an HTML <button>). Additionally, you can already write logic in lifecycle methods to check old and new values. This will always be more explicit and less confusing than trying to figure out if cleanupEachElement() or afterEachElement() gives you new or old values. It would be even easier with lifecycle events, perhaps we can add oldResult to the event data.

Happy to hear further thoughts, and thank you for checking out Crank!

[yyny]

I can totally agree that there should be a way to break out of the repeated callbacks.

I briefly considered adding support for breaking out of the Each loop myself while writing the proposal, and even considered event listeners, but didn't come up with anything I was satisfied with.
The need to define an event class was something I ran in to myself as well.

This was before I added scheduleEach/afterEach to the proposal for symmetry reasons though, and I think there is a better argument for wanting to break out of those.

After all, afterEachElement should mostly be used in higher-order components where you don't know anything about the children, and so because of that, it is less likely that you can make an informed decision to suddenly stop receiving events from them. Then, for the rare case where a afterEachElement would still have to be stopped, there would always be the requestAnimationFrame()-based approach as a fallback.

Meanwhile for scheduleEach/afterEach, I can totally see use-cases for registering them temporarely, like from mouse enter until mouse leave for example.
And I think adding events for "schedule" and "after" makes more sense for that reason as well.

Allow me to make another proposal for breaking out of Each loops though:

afterEach(callback) {
  let quit = false;
  this.after(function afterEachHelper(...args) {
    callback(...args);
    if (!quit) this.after(afterEachHelper);
  });
  return () => quit = true;
};

const unsubscribe = this.afterEach(() => ...);

Then you could call unsubscribe() to stop the afterEach loop.

---

As for the "loose equality", this comes from confusion on my part at the time about what gets returned by the Crank renderer, before I fully read the documentation, but what I was trying to get at is that "similar" elements do not have to trigger an afterElement callback, for example when a null becomes undefined, or a 42 turns into a "42".
Now that I understand Crank a bit more though, I see that

1. This never happen for the DOM renderer, which only ever returns null | Node | Node[]. There is an argument to be made that Text nodes with the same content should still compare equal, but more importantly:
2. This can't be implemented generically in Crank, because as you were getting at, custom renderers can return anything.

I think both of these points are good enough arguments for not adding {schedule,after,cleanup}EachElement etc. into Crank itself, but rather into some kind of external library.

Let me pivot the proposal a little bit, then, to a literal shower thought I had yesterday.

I currently implement this external functionality with an injectHelpers(this) at the top of my components that assigns new functions directly onto the this object.
This adds noise though, and it is also bad for memory usage and performance.

What I think would be more ergonomic, and also more performant, would be if the "exclusive prefix" of the prototype chain of each component was prepended to the prototype chain of the received Context.

So if I have a component with prototype chain [MyComponent < MyHelpers < Object] or [MyComponent < MyHelpers < EventTarget < Object], it will receive a this (and second ctx argument) with a prototype chain [MyComponent < MyHelpers < Context < EventTarget < Object] (because Object (and EventTarget, in the second case), are already in the prototype chain).

function* MyComponent() {
    this.helper();
}
MyComponent.prototype.helper = function() { ... } // like this
MyComponent.prototype = MyHelpers; // or like this

It might also be nice if a prototype object could be passed to the renderer too, so render-specific helpers could also be added.
Something like [MyComponent < MyHelpers < MyRenderSpecificHelpers < Context < EventTarget < Object]

---

Finally, let me just thank you for coming up with Crank.

Crank ended up on my backlog somehow while researching effect handlers and the more general problem of mutable state management in programming languages, and now that I finally had an excuse to check it out this weekend, I have to say, using async and generators (which are a subset of effect handlers), is so much more pleasant than any other "reactive" framework I have ever looked at (and dreaded learning), even the nice ones, like Svelte, which effectively just reimplement a subset of effect handlers in their compiler.

I may be a bit biased because I never used any other framework to this extent before, but looking at the pitfalls and edge-cases of other "reactive" frameworks, I have to say, it makes me really happy that there is a reactive framework that can be picked up with no experience besides some universal programming language knowledge.

Using Crank has really convinced me a lot more that effect handlers are the right abstraction for encapsulating state changes.

[brainkim]

Thank you for the kind words! I’m glad you’re finding the framework to be pleasant.

Allow me to make another proposal for breaking out of Each loops...

Yes, this is great! This code could also be turned into “hooks” so as to avoid mutating the component/Crank prototype:

function useEachAfter(ctx, callback) {
  let quit = false;
  ctx.after(function afterEachHelper(...args) {
    callback(...args);
    if (!quit) ctx.after(afterEachHelper);
  });
  return () => quit = true;
}

I do wonder if using EventTarget might be more ergonomic. The reason I’m interested in lifecycle events is that schedule() and cleanup() can actually delay rendering/unmounting by returning promises, and this could be implemented via the Service Worker ExtendableEvent interface.

I’m curious about your use-case for each lifecycle events. You can actually implement the lifecycle as events if you’re experimenting with code like the following:

function useLifecycleEvents(ctx) {
  // Schedule event - fires before each render
  ctx.schedule(function scheduleDispatcher(result) {
    ctx.dispatchEvent(new CustomEvent("schedule", {
      detail: { result }
    }));
    ctx.schedule(scheduleDispatcher);
  });

  // After event - fires after each render
  ctx.after(function afterDispatcher(result) {
    ctx.dispatchEvent(new CustomEvent("after", {
      detail: { result }
    }));
    ctx.after(afterDispatcher);
  });

  // Cleanup event - fires on component cleanup
  ctx.cleanup((result) => {
    ctx.dispatchEvent(new CustomEvent("cleanup", {
      detail: { result }
    }));
  });
}

I haven’t tested this yet, and I haven’t implemented event.waitUntil, but you get the general idea. The reason I’m more interested in implementing EventTarget than adding new methods is that it’s cheaper (doesn’t increase Crank library filesize as much). I also think this was suggested a long time ago by others.

What I think would be more ergonomic, and also more performant, would be if the "exclusive prefix" of the prototype chain of each component was prepended to the prototype chain of the received Context.

This is a brilliant shower thought! Because components are JavaScript functions, every component has a prototype which we currently aren’t using. Having the Crank Context somehow inherit from the component prototype would allow users to define ad-hoc methods which the component can use, and like you said, it would reduce memory usage and remove boilerplate. This could probably be another issue.

This could also be the basis for class-based web components for Crank. I’m trying to add support for creating Custom Elements with Crank, but I haven’t figured out the right API yet. Your “use the prototype” idea could be worked into this.