`subtle` namespace seems unnecesary

[titoBouzout]

Idea: Put subtle APIs in a subtle namespace, similar to crypto.subtle, to mark the line between APIs which are good to use for most developers, and the more advanced ones.

Personally, I do not like this sort of babysitting. The connotation of wording such "this is for advanced use" always gives me bad taste. You can already tell by the phrase "APIs which are good to use for most developers", implies that the other APIs are not good for some set of developers, which set? It gives me the feeling "I know what I am doing, and you don't, so I treat you in a special way" kind of thing that I do not welcome.

It's kind of unnecessary because, to do anything, really, you have to understand the system, so there's kind of no point on this warning. I know it takes time to understand reactivity and stuff gets tangled pretty quick, super hard to debug, but that won't be solved with any kind of wording on the api.

Besides, people willing to use functionality without understand it, will do it anyway even if subtle is on the name of the API calls.

I believe it will be more productive if the API could be shaped in a way that feels more natural to the problem faced.

The whole signals API is pretty much useless without an effect and to create an effect you have to use the subtle namespace, it's kind of weird if you ask me.

Avoiding having examples on which you read and write to a signal in the same place, specially on the readme, and showing how action reaction works is much more important to communicate properly the ideas behind the entire thing.

Also, if most of the APIs are behind a subtle namespace, it communicates the wrong idea, reactivity may be a bit hard to reason about but is not rocket science, and you don't need people with a PhD to use these APIs. Is not like someone wakes up with the feeling of "today lets use untrack" and they just slap untrack at random, they use untrack because they need it. They know what they are doing.

[NullVoxPopuli]

A lot of the subtle apis would be needed to make tooling for debugging, but we don't want all that to be commonplace in app code.

I think, in general, you're right that folks need to understand what they're doing and therefore would be annoyed by babysitting... However, i think folks with this opinion are easily in the top quartile of developers. And most devs donat actually know what theyre doing, and copy paste without understanding (for many years even!). They have features to ship, deadlines to hit, and want to look productive as a means to distract from imposter syndrome.

I wish it weren't this way, but here we are! Best we can do is identify when someone is coasting, or not improving, and help them out, educate, provide explanation as to why we'd make a decision, etc. ♥️

It's possible we need to update phrasing around the subtle API: like, not meant for library/app use, meant for debug tooling, etc.

Thoughts?

[justinfagnani]

and copy paste without understanding

What makes us think they won't do this with the subtle APIs? If someone posts a working answer on Stack Overflow that uses the subtle APIs, it'll still be copy and pasted.

[NullVoxPopuli]

that is a good point! (however, I don't think this means we shouldn't have our APIs be self-explaining about their intent (to the best of our abilities anyway))

[NullVoxPopuli]

what was crypto's motivation for their subtle namespace?

MDN says: https://developer.mozilla.org/en-US/docs/Web/API/Crypto/subtle

which can then be used to perform low-level cryptographic operations.

which aligns with the subtle used here -- very low-level operations

[andyg0808]

Another perspective: I like this sort of babysitting. I consider myself a skilled and relatively-careful programmer. Having something to explicitly indicate "this is the best way to use the library" helps me in several ways:

1. Namespacing like "subtle" splits the docs: the "normal" methods are on one page and the "subtle" methods are on another. I can start with the "normal" docs when trying to figure out how to do something.
2. Code review is easier if I don't have to memorize the list of methods which should trigger higher scrutiny. If I see a junior dev using a "subtle" API, I'll probably take an extra moment to think about whether there's a way to do the same thing without it. Similarly, when I'm looking at StackOverflow snippets, "subtle" pushes me to keep looking for a solution without it.
3. Knowing that I'm using a "discouraged" feature pushes me to rethink more of my system/design by clearly saying, "This is a special case." Maybe I'll end up using the "subtle" API. But maybe I'll realize there's a better design, and I'd not have realized that if there wasn't a "subtle" marker on the "obvious" way to do the thing.
4. I don't know that this aligns to the way y'all are using it, but it's also helpful to know that part of an API risks loosing features the API ordinarily provides. Compare Rust's unsafe: if I reach for unsafe, I know I can't rely on the same guarantees I normally can.

[yeomanse]

Seems like there is some simple clarification that can be done. The current wording in the proposal

Idea: Put subtle APIs in a subtle namespace, similar to crypto.subtle, to mark the line between APIs which are good to use for most developers, and the more advanced ones.

definitely gives off a weird vibe and the reaction in OP's initial comment is reasonable. However, the purpose of subtle is not quite to draw a line between advanced developers and non-advanced developers, but more to draw the line between API's to accomplish advanced goals and more typical goals. Advanced goals being implementing a framework, dev tools, etc and typical goals being instantiating signals for use with an existing framework.

For example, I myself am trying to implement a framework on top of this polyfil which of course means a need to use subtle APIs, but I am very new to reactivity and developing at this level so would not put myself in the "advanced developer" category. But I knew subtle was the right place for me because my goal of implementing a framework is the advanced usage. @titoBouzout if you are talking about implementing an effect than yes that requires the advanced APIs. But the key here is how many projects will actually implement effect or really require subtle APIs? 100 maybe? Versus how many will be instantiating a signal for use with something like Solidjs? 10s of thousands hopefully?

So basically I am for the subtle namespace but think we should reword that part of the proposal to talk more of the advance-ness of the goal rather than the developer.

[petetnt]

@NullVoxPopuli @yeomanse the actual reasoning behind subtle is stated in the SubtleCrypto page:

Warning: This API provides a number of low-level cryptographic primitives. It's very easy to misuse them, and the pitfalls involved can be very subtle.

Even assuming you use the basic cryptographic functions correctly, secure key management and overall security system design are extremely hard to get right, and are generally the domain of specialist security experts.

Errors in security system design and implementation can make the security of the system completely ineffective.

Please learn and experiment, but don't guarantee or imply the security of your work before an individual knowledgeable in this subject matter thoroughly reviews it. The Crypto 101 Course can be a great place to start learning about the design and implementation of secure systems.

Misusing something like Signals definitely does not fall into the same reasoning as potentially catastrophic cryptographic scenarios. If the same reasoning was used for all Web APIs, half the existing APIs would need to be under subtle namespace.

[NullVoxPopuli]

like Signals definitely does not fall into the same reasoning

for Signals in general, this is true, but I think the things currently under subtle namespace align with how Crypto uses the word, specifically, (and maybe only) the first line:

It's very easy to misuse them, and the pitfalls involved can be very subtle.

the later 3 sentences don't really feel applicable to signals as the stakes to getting something subtle wrong with signals are not as high as with crypto

half the existing APIs would need to be under subtle namespace.

:tada: :see_no_evil: lol, I mean, sharp tools?

[dead-claudia]

I will note that, from an implementation standpoint, it'd be much cleaner to implement most the existing subtle.* API if it were just instance getters/methods.

• The two symbols could just be simple string keys, which are a bit simpler to work with.
• untrack(cb) obviously would be roughly the same either way.
• The name of currentComputed() would feel a bit cleaner as Computed.getCurrent() or similar, but it's otherwise similar to untrack(cb) in that it doesn't matter much.
• introspectSources, as methods on Computed and Watcher, could access the inner node/etc. fields through a private field directly in polyfills, rather than needing to use a symbol or static { getFoo = f => f.#foo }. Same goes for hasSources and, for State and Computed, introspectSinks and hasSinks.

[littledan]

I just want to note that we can spend a long time debating this question before we need to draw a conclusion (before stage 2.7). Even if we leave the names as they are now at the moment, please do not interpret this as a rejection of the suggestions in this thread.

[dead-claudia]

Related: https://github.com/tc39/proposal-signals/issues/178