[rewrite] Rest of the API

[dead-claudia]

Since we're starting to get to that point, I think it's a good idea to start thinking of the rest of the high-level API. Here's some of my ideas:

• Mithril.m(type, attrs?, ...children)

  The familiar m() hyperscript API.

• var trust = Mithril.trust

• var mountpoint = Mithril.mount(window = global.window)

  Ideally, this should return an object you can use to do m.redraw()-like things and have multiple independent roots. The argument is for easy mocking, and effectively nullifies m.deps.

• mountpoint.window

  This is the window value argument passed to Mithril.mount(), defaulting to the global window. You can also use a JSDOM window if you want to use it in Node.

• var promise = mountpoint.redraw()

  This should do the equivalent of 0.2's async m.redraw(), but return a Promise.

• mountpoint.redrawSync()

  This should do the equivalent of 0.2's sync m.redraw(true), and return nothing.

• mountpoint.redrawStrategy = "all" | "diff" | "none"

  This fufulls the same purpose as m.redraw.strategy(). It might not be necessary with the lifecycle methods, though.

• var promise = mountpoint.compute(callback: () => Promise | void)

  This should take the place of m.startComputation and m.endComputation. It is roughly equivalent to the following code:

  m.startComputation()
  return Promise.resolve(callback()).then(() => {
      m.endComputation()
  })

• Mithril.prop(init?, observer?)

  m.prop is popular enough that it should probably stay in core. I do believe it should lose the Promise absorbing semantics, though, and it should be optionally observable.

• Mithril.withAttr(value, callback, thisArg)

  m.withAttr also seems popular enough that it could remain in core, with few modifications (mostly removing compat bloat).

---

The rest are generally not necessary/needed in the core distribution.

• m.route can be implemented on top of m.mount in a third-party module.
• m.component can (and should) die.
• m.request should be go away in favor of the native Fetch API, and there is an XHR-based polyfill if you need one. IMHO, redraw after request should be explicit, anyways.
• m.deferred and m.sync should go away in favor of native Promises. If necessary, there's a ton of libraries and polyfills for that.

/cc @tivac @lhorie

[tivac]

Given the amount of 0.2.x code we have I'm much more in favor of an API that keeps most of the broad strokes of the 0.2.x API intact.

• I don't think the arguments to m.mount() should change
• I don't think that m.route() should be dropped
• I don't think that m.request() should be dropped (to ease transition, long-term I agree that fetch is a better plan)
• m.component could just be an alias for m() with a warning (the semantics are slightly different, but that'd be fine for our code at least)
• Re-render isn't tied to rAF loops any more, so I don't think that differentiating sync/async redraws makes a ton of sense.

I'm working on a very rough-n-tumble version of what I think this should look like in a branch.

[tinchoz49]

@isiahmeadows Maybe is a stupid question haha but just to be sure.
Represent the API with Mithril.m, Mithril.trust... is only an abstract representation right? I mean with the rewrite we are going to use a modular approach or am i wrong?

for example:

var m = require("mithril/render/hyperscript");

[dead-claudia]

@tivac

• I can see what you mean by m.render. IMO in this case it is best either always sync or always async (without even a toggle). That also nullifies m.redraw, m.compute, etc.
• m.request and m.component can be inserted in a compatibility wrapper apart from core, just concatenated with the main output.
• Would you be fine if m.route and m.request were made into separate modules that depended on Mithril instead? The latter could almost be ripped out now.

As for multiple mount points, we could instead do this:

• m.mount(element, component?, window = window) would do the standard global mount. It would also return the global mount point.
• m.mount() would get the global mount point. (An element is always required for creating mount points.)
• m.localMount(element, component?, window = window) would do basically what I initially suggested, optionally initializing it with a component.

For remounting, there are these properties/methods:

• mountpoint.element is the element it was initialized with.
• mountpoint.component is the component it was initialized with.
• mountpoint.initialize(component) would initialize the mountpoint with the component, and Mithril.localMount(window, element, component) is the same as m.localMount(window, element).initialize(component).
• mountpoint.clear() would be morally equivalent to m.mount(element, null).

The old API could be roughly replicated with this (the breaking part is that it doesn't return the vdom state):

function mount(root, component) {
    if (component == null) {
        m.mount().clear()
    } else {
        m.mount(root, component)
    }
}

[dead-claudia]

@tinchoz49

Currently, even though it's been modularized, and you will have the option of requiring individual parts, there will be a global build of everything and just specific parts. This issue is mostly focused on starting down that direction, since not much thought has yet to be put in it.

[tinchoz49]

ahhh ok!! Thank you for explaining to me 😌 !

[lhorie]

FYI, I started doing some work on exposing a 0.2.x-like API to help @tivac test.

Currently there's m, render, trust, a rough mount, route, request and redraw and a version of threadit.js running from the bundle. It pretty much has the same API except for config: m.route and the new state / lifecycle API.

I'll push it when I get back to my desktop so you guys can take a look

There's only one issue that I would consider major wrt post-request redraws, that I need to do some work on

[lhorie]

@tivac https://github.com/lhorie/mithril.js/blob/rewrite/examples/threaditjs-bundle/app.js

The mountpoint now looks like 0.2.x: https://github.com/lhorie/mithril.js/blob/rewrite/examples/threaditjs-bundle/app.js#L178 and post-request redraws still need to be called manually (but the m.redraw hook does work) https://github.com/lhorie/mithril.js/blob/rewrite/examples/threaditjs-bundle/app.js#L34

The only other caveat is that currently, config: m.route is not overloaded, and instead it uses a submethod called m.route.link (and config itself is replaced with oncreate) https://github.com/lhorie/mithril.js/blob/rewrite/examples/threaditjs-bundle/app.js#L91

The bundle can be regenerated by running node bundler/bundler.js. There are three files of interest that are bundle-specific: ./router.js and ./mount.js expose familiar interfaces to their respective modules, and ./index.js that glues everything together. Bundled data is output to the ./mithril.js file

Oh, and now, this points to vnode.state within lifecycle methods

[tivac]

@lhorie Wow, that's... comprehensive. I'll try to dig into it some this weekend!

[Naddiseo]

I agree with @tivac wrt m.request(), and it shouldn't be dropped until native fetch implementations are cancellable and support the streaming API. (We currently have a file upload component written in mithril which has a progress bar, which uses xhr.onprogress via m.request, so removing m.request will require us to have yet another way to send data to the server.)

Other thoughts:

• I like the promise based API.
• Will redrawStrategy still be a prop?
• Personally, I like, and use, the promise absorbing semantics of m.prop, what would replace it if it were removed?
• The m.prop observer would have to not incur a performance penalty if not used.
• I'm +0 on m.component removal
• +1 on m.deferred and m.sync removal

I say all this, but I think I'd need to actually try writing something using the new API/code to have a more informed view-point.

[tivac]

@lhorie Finally got a chance to play w/ the compat shim, thanks for that. Yours is much cleaner than my attempt!

1. It works! (for the simple app I ported)
2. Redraws aren't capped at 60fps via rAF any more, which means that if you redraw on scroll (like for occlusion culling a huge list) you end up w/ a lot of redraws stomping on each other & blank UI.
3. There's no way to cancel a redraw from an event. We chatted in gitter about options last week, but just bringing it up again as something I'd like to be able to do.
4. No surprise that it feels really, really fast. This is delightful.

[lhorie]

@tivac Awesome, glad to hear that!

Items 2) and 3) are still in the list of things to do. I'm specially open to suggestions re: cancelling redraws.

The two options on the table currently are:

• reimplement m.redraw.strategy
• prevent redraw if the e object has a specific flag, e.g. e.skipRedraw = true

The second option could be abstracted w/ a function, e.g. m.skipRedraw(e), to make it composable with e.g. .pipe in ramda

[tivac]

Based on anecdotal evidence from gitter/GH I think m.redraw.strategy() was a layer of abstraction that a lot of folks had trouble grokking. Setting a property on the event object seems clear and concise. A helper method to set it in a functional way isn't something I'd use but I don't have an issue with it.

e.skipRedraw = true seems perilously close to a boolean trap, but off the top of my head I'd advocate for e.redraw = false and I'm not sure that'd be any better.

[tivac]

Just pushed #1047 as my attempt to address the over-redrawing issue.

[tivac]

And #1049 to allow for skipping a re-draw via event handlers. Went w/ my redraw = false proposal, but easy to change to something else if preferred.

All of this API stuff needs some sort of tests though, @lhorie is that something you want to figure out or should I take a crack at it?