[RFC] async object creation support

[koresar]

Whilst this specification was being created the stampit v2 had a feature the spec didn't borrow. Stampit v2 could create objects even if its initialisers are async functions (return Promises). Stampit v3 comply to specs, so had to remove that feature.

Let's bring back async object creation. Why?

• Occasionally people do need it. I met 3 so far.
• It would be a great argument against classic OOP classes.
• This is a low hanging fruit.

Proposal. Add this line:

If one of the initializers returns a "thenable" then the whole object instantiation becomes async.

const MyStamp = stampit({ 
  async init({ uri }) { 
    this.data = await fetch(uri); 
  }
});

const obj = await MyStamp({ uri: "example.com" });

Here is a sample implementation of the object creation bit:

    if (initializers && initializers.length > 0) {
      let returnedValue: void | object;
      const args = [options, ...moreArgs];
      for (let i = 0; i < initializers.length; i++) {
        const initializer = initializers[i];
        if (isFunction<Initializer>(initializer)) {
          returnedValue = initializer.call(instance, options, {
            instance,
            stamp: Stamp as Stamp,
            args,
          });

          // New code
          if (isFunction(returnedValue?.then) && i !== initializers.length - 1) return returnedValue.then(asyncReturnedValue => {
              for (i++; i < initializers.length; i++) {
                const initializer = initializers[i];
                if (isFunction<Initializer>(initializer)) {
                    asyncReturnedValue = await initializer.call(instance, options, { // await !!!
                    instance,
                    stamp: Stamp as Stamp,
                    args,
                  });
                  if (asyncReturnedValue !== undefined) instance = asyncReturnedValue;
                }
              }
              return instance;
          });

          if (returnedValue !== undefined) instance = returnedValue;
        }
      }

As you can see, such implementation:

• Won't be async until a returned value is a Thenable (aka async function).
• Does not rely on global Promise variable (it might not be available everywhere).
• Will work in esm, Babel, native JS engines, everywhere!
• Compatible with npmjs.com/~stamp stamps.
• Backwards compatible with existing code bases.

[sammys]

I've spent a few days thinking this through from the perspective of calling code. If the goal is to run async initialisers synchronously then the code you've posted will achieve that. I'd like to say it will require no modification but I'm unsure whether any JS implementation supports the async keyword without offering a global Promise.

That brings me to a question. Given that Promise support was pronounced stable at NodeJS version 4 (i.e. ES6/ES2015) and @stamp targets ES2017 in master at the time of posting, which platforms are targeted that don't have global Promise available?

Calling code gains no asynchronous benefits when asynchronous functions are executed synchronously using await. For now, I don't see any reason to hold back committing something like what you've posted. Like you wrote, it is low hanging fruit. It will give developers the flexibility to build stamps with asynchronous initialisers in preparation for the later performance benefit.

As far as the performance benefit goes, I haven't experienced any issues in my code when a Promise is returned from an initialiser. Though it must be emphasised that there is a caveat for code cleanliness – calling code must use sync exclusively (including the code you posted) or async exclusively. There is no half way that is simple and sticking to this has kept me sane. For this reason, I would recommend that an alternative compose with full async support be available as a sub-export or another package.

You did mention some potential problems with the full async support in the PR this RFC arose from and full async support is on the cards I reckon some sample code + tests might help confirm/deny their existence and any workarounds required.

I'm utterly outside the scope of the stamp standard in this post and in my mind. I imagine some consideration might be necessary regarding asynchronous program flow. Even more complicated would be asynchronous composition hehe... but that's another RFC.

Hope this is helpful.

[sammys]

Addendum: "There is no half way that is simple" should read... There is no half way (supported in all tooling) that is simple

However, on the bright side, there will be a simple solution once all tooling supports it. Here is some information for us to use as a quick reference.

The sample code above uses await inside a synchronous function, which is a syntax violation unless top-level await is enabled. V8 lists the following supporting environments:

• Chromium 89+
• Node.js 14+

The functionality has existed in Node.js before version 14 hiding behind experimental flags. So, here's a clearer listing for Node.js:

• 14.4+: Available out of the box
• 13.3+: V8 engine implementation via --harmony-top-level-await flag
• 10.0.0+: Available in REPL by using --experimental-repl-await flag

Some transpilers also support it:

• typescript: target: ES2017 and module: esnext [or system] added in 3.8
• webpack: experiments.topLevelAwait added in version 5
• rollup: experimentalTopLevelAwait though I can't seem to find any current documentation on it

I haven't read into it so can't say for sure but they might transpile top-level await code to work in browsers that don't support top-level await natively.

One final thing I can think of noting is that top-level await is only supported in ES modules. It means command line node scripts not using .mjs extension, e.g. node script.js, will need to use --input-type=module plus one of the other flags listed above if the version requires it.