Nit: casing of "sub-namespace" Signal.subtle

[domenic]

I like the split into most-developer-facing vs. library-facing with the Signal namespace vs. the Signal.subtle sub-namespace. And this isn't very important, but... I can't get out of my head the mismatch between uppercase for namespaces and lowercase for sub-namespaces.

As some background, JS and the web built-ins have 2.5 kinds of "namespace-ish" things:

• Namespaces, i.e. POJSOs containing constructors etc. Examples include Reflect, Math, WebAssembly, CSS, and console. (console is a bit weird in multiple ways, casing included.)

• Singleton instances. These are extremely common on the web. Examples include navigator, crypto, crypto.subtle, performance, ...

• Constructor functions with static utility function members. I wouldn't really count constructor-ish things like Promise.resolve() here, but I would count things like Number.isNaN(), Object.hasOwn(), URL.createObjectURL(), WebAssembly.Module.exports(), etc.

The tension between namespaces and singleton instances on the web has always been uncomfortable for me. I don't think web developers really care that navigator is an instance of the Navigator class, or that performance is an instance of a Performance class. They just have to deal with the fact that some data and functions which are logically global are gated behind lowercase "namespace-ish" things, while others are not. By introducing namespaces into Web IDL I tried to make it easier for people to create namespaces for web APIs, but I think partially because the casing would depart from established platform convention, people have been hesitant to adopt them. I don't have a great answer here.

So with that background... here comes Signal.subtle. To my knowledge this is the first proper sub-namespace (in the POJSO sense) we have proposed for the platform. And you've chosen... uppercase for the outer namespace, and lowercase for the inner namespace? I don't know how to fit that into the above picture. Would you share your reasoning for the casing choice?

Outcomes I would find nice:

• Some explanation for the chosen casing that makes me slap my head and say "oh, that makes sense".

• Avoid the problem altogether by avoiding subnamespaces, e.g. by using a sibling namespace like SignalSubtle or SignalInfrastructureUtils. (Ideally combined with collapsing the top-level Signal namespace, e.g. to StateSignal and ComputedSignal, but that's not very important.)

• Signal.Subtle, setting the precedent that if we're going to do sub-namespaces they follow the same casing rules as top-level namespaces.

• signal.subtle, leaning into the web precedent of possibly-nested singleton objects. I don't think this makes a lot of sense but it's probably more understandable for developers than mixed case.

[littledan]

Thanks for the thoughts. It’s important that we get these naming conventions right and don’t draw too surprising of a line between JS and web APIs, so I appreciate the comparisons.

I share your unease with the singleton object vs semi-forbidden namespace split, and I suspect that it isn’t really reflected in JS developers’ mental model anyway (maybe people think of navigator as a singleton, but probably not crypto).

In recent TC39 times, we have made Namespace.Subnamespace the pattern in at least one case, Temporal.Now, so this would be the obvious pattern to follow for this Signal subtle namespace. On the other hand, I wanted to make a reference to crypto naming.

For now, I will leave the casing as is, but we definitely need to revisit this issue and draw a conclusion before asking for Stage 2.7.