Brainstorming: what would a modernized jsdom API look like?

I feel like the current API is not the most user-friendly. Here are a few of my complaints:

• The lack of clear default export (require("jsdom") doing something useful)
• The split between env and jsdom, plus the under-loved jQuerify cousin
• jQuerify is a lot less convenient now that we require an explicit jQuery URL
• The util methods (createVirtualConsole etc.) are kind of sprouting everywhere
• env’s magic is often a bit too magical, especially the auto-detection of strings
• The document-centric interface is awkward; often you want a window
• The different default settings between env and jsdom is confusing
• The “features” configuration is a bit crazy

I think as a prerequisite to any redesign, we’d need to fix:

• #1039 so we don’t have the weird mix of error types during initialization (and in particular never have more than one “error”)
• #1128 so that we know what we’re doing with options (although maybe we’d fix this at the same time as doing this work)

If we got those down, here are some broad ideas on what I could imagine:

• A new type of class, Jsdom, which has stuff like:
  • A window getter
  • virtualConsole and cookieJar getters (which would just return the one you passed in, if you did)
  • A serialize() method
  • Other meta stuff? Maybe promises for when everything loads?
• A new set of top-level APIs:
  • jsdom: takes a HTML string and returns a Jsdom
  • jsdom.fromUrl: takes a URL and returns a Promise<Jsdom>
  • jsdom.fromFile: takes a filename and returns a Promise<Jsdom>
  • Each should take args in the form (relevantString, commonOptions, typeSpecificOptions)
  • commonOption defaults are all the same
  • current features stuff is rolled up into commonOptions (or possibly into resourceLoader?)

Alternately I was considering a “builder” class instead of a Jsdom class, which would allow things like .insertScript() to get back that jsdom.env/jsdom.jQueryify functionality, and other nicer methods… might be worth sketching that out too. We could put a promise-returning insertScript on Jsdom.prototype though perhaps.

[domenic]

The tentative idea is to provide a dom.loaded promise, as described at the bottom of the document. jsdom() is not synchronous for any external resources.

[domenic]

That doesn’t really seem to have anything to do with the new jsdom API, and is instead some kind of jsdom feature request that it support shadow DOM and custom elements and CSP?