Consider TypeScript?

[jcbhmr]

For packages that apply things globally, I like to use something like this to get accurate types:

import Thing_ from "./Thing.js";

declare global {
  type Thing = Thing_
  var Thing: typeof Thing_;
  interface WindowEventMap {
    onthing: Event;
  }
}

globalThis.Thing = Thing_;

I also think that TypeScript could come in handy with its less verbose type syntax since this package has a lot of un-inferrable types that need to be manually specified.

I understand if you want to stick with plain JavaScript, but I'd at least recommend using JSDoc + tsc --allowJs --checkJs to make sure that things are good type-wise. 😊

[jimmywarting]

I prefer build-less setups
I often use typescript for most things, but not the TS syntax.
i have allowJs checkJs on by default in VScode for all projects. This is what my settings.json looks like:

// settings.json

{
  // The 3 most important one:
  // Enable semantic checking of JavaScript files.
  // Existing jsconfig.json or tsconfig.json files override this setting.
  "js/ts.implicitProjectConfig.checkJs": true,
  // Enable suggestion to complete JSDoc comments.
  "javascript.suggest.completeJSDocs": true,
  // Preferred path ending with extension (good for ESM & cjs).
  "javascript.preferences.importModuleSpecifierEnding": "js",
  
  // Other suggestions useful stuff:
  // Complete functions with their parameter signature.
  "javascript.suggest.completeFunctionCalls": true,
  // Enable auto import suggestions.
  "javascript.suggest.autoImports": true
}

I like vanilla JS + JSDoc cuz

• it is easier to debug cuz you look at the original source code.
• Easier to apply quick fixes in node_modules. cuz see the original code and you can modify it anyway you like.
• Browser are never ever going to ship TypeScript syntax to the browser so it's never going to work with TS.
• Dose not have to install any dependencies to help out and contribute to the library.
• Dose not need to wait for anything to compile.
• TypeScript did not always produced "good" generated source code. having had to deal with things like lazy import() being converted into __importStar(require('esm-only-pkg'))) even tough CJS did support async import().
• and it never fixed strict esm import paths that requires you to define the full path with extension. (extensionless import and index is bad)
• And you should actually be using # instead of private keywords: use private class fields kenchris/urlpattern-polyfill#118

I'm very much like the svelte creator Rich who now also prefer JSDoc over typescript. he decided to switch the entire v4 codebase back to vanilla js + jsdoc

https://www.youtube.com/watch?v=MJHO6FSioPI&t=214s

But sure, we could include a jsconfig.json + allowJs checkJs if you would like that.
In some cases it isn't even needed. cuz TS can scan give type hinting even without that using type inferences or scanning for jsdocs

if we need complex types then we could always do a .d.ts and include it with @typedef imports.
So we don't need any build steps.

[jimmywarting]

Well, by using # instead of WeakMap then you wouldn't have to depend on using WeakMap.get() that may or not may return null
kind of by doing:

const key = Symbol('Private')

class DedicatedWorkerGlobalScope extends WorkerGlobalScope {
  #name

  /**
   * @param {typeof key} key
   * @param {string} name
   * @param {WorkerLocation} workerLocation
   */
  constructor (key, name, workerLocation) {
    super()

    if (key !== key) {
      throw new TypeError('Illegal constructor')
    }
    
    this.#name = name
  }

  get name() {
    return this.#name
  }

  // ...
}

const dedicatedWorkerGlobalScope = new DedicatedWorkerGlobalScope(
  key, 'foobar', location
)

export {
  DedicatedWorkerGlobalScope,
  dedicatedWorkerGlobalScope
}

The only thing you really need to annotate here is the constructor arguments, the rest like get name() { ... } will be completely understood by TS in the way that it will return a string

But yea, i have missed non-null assertion also from few occasions. and they have mostly been around using document.querySelector

and for that i have sometimes just used like your example: (/** @type {NodeWorker} **/ nodeWorker.get(worker))

or if i used it a lot: made something like a non-null checker:

then i don't have to use body?.innerText or something like it.

[jimmywarting]

and for typing your your weakmap, then you can do:

/** @type {WeakMap<DedicatedWorkerGlobalScope, WorkerLocation>}*/
const location = new WeakMap()

[jimmywarting]

if i don't want to have to use both nn + querySelector all the time then i could combine it to one function and compose them:

// jQuery style selector that returns a non-null element
const $ = (selector = '') => nn(document.querySelector(selector))

const body = $('body')

[jcbhmr]

Well, by using # instead of WeakMap then you wouldn't have to depend on using WeakMap.get() that may or not may return null
kind of by doing:

Problem is you can't set the outside the class now though! Like "set internal slot of other object to V" in another algorithm could use a WeakMap.set() but not a .#private = V 🤷‍♀️

[jimmywarting]

There is kind of a weird ugly hack of doing it that i have encounter upon before:

class Person {
  #name = 'Jimmy'

  get name () {
    return this.#name
  }

  /** @private */
  setName (name) {
    this.#name = name
  }
}

const setName = Person.prototype.setName
delete Person.prototype.setName

const person = new Person()
console.log(person.name) // Jimmy

setName.call(person, 'James')
console.log(person.name) // James

export { Person, person }

And yes i have seen this kind of pattern in NodeJS source code 🤪

[jcbhmr]

I've been eyeing https://github.com/tc39/proposal-decorators and since it's already in TS, you can use it without another Babel toolchain step 😃 demo

Something like a @eventHandlerIDLAttribute decorator like this:

function eventHandlerIDLAttribute() {
  // ...
}

class Thing extends EventTarget {
  @eventHandlerIDLAttribute
  onclick;

  @eventHandlerIDLAttribute
  accessor onerror;
}

could be interesting... 🤔

This is something you can't really do nicely in plain JS 😅

[jimmywarting]

I know, have been kind of waiting for decorators for quite some time now too. but maybe it's too early to start using it now.
have to wait for they to land into stage 4. until i will start consider using them