swal.update() doesn't update swal.params

[zenflow]

Replying to #1186 (comment) ...

Like I said in the PR:

the instance's params property (i.e. the "outer" params, which were defined with the user's call to Swal) should probably be updated when the update method is called, as this would likely be expected

This does affect the public API:

const swal = Swal.fire({ type: 'error' })
console.log(swal.params.type) // logs "error"
swal.update({ type: 'warning' })
console.log(swal.params.type) // logs "error" again, though you would expect it to log "warning"

Sorry, I don't have time to fill out the template for an bug I pointed out before it was merged

[limonte]

Thanks for the proper issue-report @zenflow I personally can understand reports much better reading the actual code rather than reading the humans language. Probably that's related to the fact I'm not the native English speaker.

This does affect the public API:

Public API is everything documented in https://sweetalert2.github.io

Accessing to the instance params isn't documented in https://sweetalert2.github.io, therefore it's not public API, therefore it's not a breaking change.

[zenflow]

Public API is everything documented in https://sweetalert2.github.io

@limonte Hmm.. I must disagree. That is the documented API. The public API is everything that is exposed to the public.

Documentation isn't the only way people figure out the the API; they also play around with it in the browser console, so it's very possible that projects in the wild are using swal.params.

[limonte]

This is a very good topic to discuss. What you're saying @zenflow makes sense but brings some complications. Now, we are dealing with two different things:

1. documented API
2. public API

Why would we have undocumented public API? Does "undocumented public API" make sense to you?

[limonte]

The public API is everything that is exposed to the public.

I actually disagree with this statement. The fact that users can do things like $('.swal2-content') doesn't mean that the swal2-content classname is a part of public API. It's not. It might be changed at any point.

Swal.getContent() is the public API, it's documented in https://sweetalert2.github.io/#methods

[zenflow]

Why would we have undocumented public API?

Not sure the point of the question, but a part of the API might be undocumented because (1) it was neglected, (2) it is just not feasible to document every little detail of the API, (3) it's experimental and might be removed in the next major release.

Does "undocumented public API" make sense to you?

Yes it does. It's the subset of the public API that is undocumented.

[zenflow]

I actually disagree with this statement. The fact that users can do things like $('.swal2-content') doesn't mean that the swal2-content classname is a part of public API. It's not. It might be changed at any point.

I am reminded that there is a fine line between "implementation detail" and "public API".

I would not look at the classnames as just implementation details (better to look at as public API), because people will often depend on them (and the whole HTML structure) to do their own css, even though it isn't documented, or in any way indicated to be anything other than an implementation detail. This should not be changed arbitrarily at any point.

I don't think the swal.params property could be confused for an implementation detail.. it's clearly a feature.

[limonte]

Public API is the fundamental term, I'd like to avoid any "fine lines" about it. Imagine traffic rules with "fine lines" about the green light. That would lead to deaths, injuries, and disputes about whose understanding of a fine line is correct.

To avoid misunderstandings it should be clearly defined what is Public API and what it not. 1 or 0. "I would (not) look" and other subjective opinions can't really be the part of the definition.

"Everything that is exposed to the public" can't be the definition as well because DOM structure and classnames are exposed and I do not have an intention to make them the part of Public API.

Public API is everything documented in https://sweetalert2.github.io

This is simple and easy to understand for everyone. swal.params is not the part of Public API yet, it will be once sweetalert2/sweetalert2.github.io#60 is resolved

[zenflow]

@limonte It would be nice if everything was so simple, and could be classified objectively as 1 or 0, black or white, but unfortunately reality is not like that. "Public API is everything documented in https://sweetalert2.github.io" is simple, but not very objective since doesn't adhere to the consensus idea of what a public API is.

Besides, even if we could use that definition of public API, there are still problems with it.

• There are lots of details that are not documented that we should fully expect user's to depend on. For example, the first documented option, title, will accept null and this is treated as "no title". The documentation does not state how this value will be handled, but if we make a change so that this value is actually used for the title (i.e. the title will be "null"), wouldn't you consider that to be a breaking change in the public API? It isn't really feasible to document every detail of the API.
• What about mistakes in the documentation? Does this definition mean we need to change the code to match the documentation (because the documentation is what defines the API)? I think it would make more sense (and cause fewer problems for users) if we changed the documentation to match the code. For an example see the "Default value" for inputOptions.

Documentation (as opposed to a spec, which our documentation is not) is supposed to reflect the API, not define it. The code defines the API.

The documentation documents the API, right? Then the API must be something separate and independent from the documentation, right?

The bottom line is that we should expect users to depend on all sorts of parts of the API that are not documented, and rightfully so, unless it's explicitly documented that they should not depend on it.

[limonte]

🎉 This issue has been resolved in version 8.7.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀