fix(types): improve type inference and correct some return types

[rafaelss95]

• With the current version ReadonlyMap isn't supported in inputOptions. This PR offers support for both versions: Map and ReadonlyMap;
• DOM utilities could return null at some point and so it should be correctly represented with the type: HTMLElement | null;
• SweetAlertOptions can accept two generic types now: one for preConfirm result and another for preConfirm callback value, e.g.:

// Note that both arguments are optional
const sweetAlertOptions: SweetAlertOptions<Promise<number>, string> = {
  // preConfirm: () => Promise.resolve(10),
  preConfirm: awesomeValue => Promise.resolve(10), // `awesomeValue` is inferred as `string`
  titleText: 'some fancy text',
};
// Previously we had to do some typecasts, now `sweetAlertResult.value` 
// is inferred automatically.
// In this case, it's inferred as `number`.
const { value } = await Swal.fire(sweetAlertOptions);

• queue function accepts a generic type to get a typed response and also ReadonlyArray.
• mixin's function parameter is required now;
• update's function parameter now only accepts the UpdatableParameters described in

  sweetalert2/src/utils/params.js

  Line 80 in 91700e7

  export const updatableParams = [

• All the keys in SweetAlertOptions are now readonly to better represent that even if you set something manually, it has no effect, like:

const sweetAlertOptions = { titleText: 'some fancy text' };
// With this PR, TS doesn't allow this: Cannot assign to 'titleText' 
// because it is a read-only property. You can achieve this effect using Swal.update(...)
sweetAlertOptions.titleText = 'no effect';

[rafaelss95]

I guess it was wrong. Can you confirm it, @limonte?

[limonte]

Confirming 👍

[rafaelss95]

It would be better to export this to perhaps use it in other packages like ngx-sweetalert2?

[limonte]

Agree, please do export UpdatableParameters

[rafaelss95]

Done :)

[limonte]

Amazing contribution @rafaelss95!

Please export UpdatableParameters and I'll merge this PR.

[limonte]

Confirming 👍

[limonte]

Agree, please do export UpdatableParameters

[rafaelss95]

In the last commit, I've updated some @default in docs.

[limonte]

Great contribution, thank you so much @rafaelss95!

[limonte]

🎉 This PR is included in version 9.13.3 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[rafaelss95]

@limonte Pff, I just noticed that I forgot to add the SweetAlert prefix in UpdatableParameters 😞

[limonte]

@limonte Pff, I just noticed that I forgot to add the SweetAlert prefix in UpdatableParameters disappointed

No worries at all! just send another PR with the fix and I'll release the fix!

[limonte]

I believe 0 users started to use UpdatableParameters since I merged this PR :)

[rafaelss95]

I believe 0 users started to use UpdatableParameters since I merged this PR :)

Haha, done. #1984.

[limonte]

Hey @rafaelss95

In our Angular integration this change seem to cause the issue: https://github.com/sweetalert2/ngx-sweetalert2/runs/747983015

src/lib/swal.component.ts:132:21 - error TS2540: Cannot assign to 'allowOutsideClick' because it is a read-only property.

132             options[prop] = this[prop as keyof this];

https://github.com/sweetalert2/ngx-sweetalert2/blob/bce7c7059c549aaab9586f3fa8270858f067b836/projects/ngx-sweetalert2/src/lib/swal.component.ts#L132

Should we revert Readonly or you can think of any better solution?

[rafaelss95]

Hey @rafaelss95

In our Angular integration this change seem to cause the issue: https://github.com/sweetalert2/ngx-sweetalert2/runs/747983015

src/lib/swal.component.ts:132:21 - error TS2540: Cannot assign to 'allowOutsideClick' because it is a read-only property.

132             options[prop] = this[prop as keyof this];

https://github.com/sweetalert2/ngx-sweetalert2/blob/bce7c7059c549aaab9586f3fa8270858f067b836/projects/ngx-sweetalert2/src/lib/swal.component.ts#L132

Should we revert Readonly or you can think of any better solution?

Hello, I guess we can simply solve this without mutations, using reduce instead of forEach... something like this:

public get swalOptions(): SweetAlertOptions {
  return Array.from(this.touchedProps).reduce<SweetAlertOptions>((previousValue, currentValue) => ({
    ...previousValue,
    [currentValue]: this[currentValue as keyof this]
  }), {});
}

[toverux]

Hello,

I did not step in when you posted (cool PR btw!) but I think I should have ; my only concern was the addition of the readonly modifier. Technically, those properties aren't really readonly.
After all, readonly was added to signal frozen properties to the type system and we should be careful when using it strictly for documentation purposes.

For example, you may totally do :

const options: SweetAlertOptions = { title: '...' };

if (something) {
    options.onClose = () => { ... }
}

In fact, that's what I do in ngx-sweetalert2. It's just legit.

While I get that this provides some semantic information about how the options should be maipulated in general (and that's the good part and that's why I didn't intervene in the first place), it is also a constraint that's technically not really justified and now it caused problems.

I don't have a very strong opinion on this though.

What do you think ? :)

On another subject : some of the improvements on the types here were not made before because of backwards compatibility. For example, generic types with default values (in SweetAlertOptions) were not possible before. However, I think that now may be a good time, it has been implemented in TypeScript for a while now (along with Pick for update() I think). But I wanted to warn about this since it hadn't been mentioned yet.

You two have a great day!

[limonte]

I can see that the Readonly modifier created a bit of hassle in another integration: Basaingeal/Razor.SweetAlert2#724

If possible, I'd like to ask you @rafaelss95 to rollback the Readonly modifier as per @toverux's reasoning. Thank you in advance and apologies about not thinking about this carefully during the review!

[rafaelss95]

Hello @toverux... I could argue that if the options are directly mutated it can hide bugs in first place, because if someone try to update a non updatable parameter, like below, it'll fail silently at static analysis. I know there's a warning in update's function, but in really we still lose that ability we gain from TS:

options.target = '#someId';

---

For example, you may totally do :

const options: SweetAlertOptions = { title: '...' };

if (something) {
    options.onClose = () => { ... }
}

In fact, that's what I do in ngx-sweetalert2. It's just legit.

Well, since there's the update method created for these situations, shouldn't it be better to use it instead?

if (something) {
  swal.update({
    onClose = () => { ... }
  })
}

Btw, what's the file/line that you do this there?

---

I can see that the Readonly modifier created a bit of hassle in another integration: Basaingeal/Razor.SweetAlert2#724

@limonte Hmm, I didn't go deep into this code, but shouldn't swal.update({ someOption: undefined }) be sufficient?

I mean... before it was: delete swalSettings[OPTION], after couldn't be: swal.update({ [OPTION]: undefined })?

If possible, I'd like to ask you @rafaelss95 to rollback the Readonly modifier as per @toverux's reasoning. Thank you in advance and apologies about not thinking about this carefully during the review!

No problem :). That all being said, I have no problem in create a PR rollbacking this. I'll do this ASAP. I just wanted to point that IMHO the readonly is a very powerful feature that we gain in TS side to prevent slightly bugs and, unless I'm missing something, all the possible mutations can be done via update method.

[toverux]

Well, since there's the update method created for these situations, shouldn't it be better to use it instead?

if (something) {
  swal.update({
    onClose = () => { ... }
  })
}

It's not the same use-case. You can legitimately mutate the options object before showing the swal. That's what I meant by saying "that's what I do in ngx-sweetalert2": I don't have this particular code, instead I was talking about my foreach function to mutate the object before showing the swal.

I know we can use reduce instead, and I prefer that too, but some may prefer the imperative style, or can't use reduce, like in my example. Instead, with readonly modifiers, they'd have do to something like this:

const options: SweetAlertOptions = {
    ...someCondition ? { onClose() { /* ... */ } } : {}
};

I am aware that these are rare use cases though.

[rafaelss95]

It's not the same use-case. You can legitimately mutate the options object before showing the swal. That's what I meant by saying "that's what I do in ngx-sweetalert2": I don't have this particular code, instead I was talking about my foreach function to mutate the object before showing the swal.

Hmm, when I read it yesterday I thought you're talking about a open swal. Sorry for the confusion.