Two Clarifications

[hamishwillee]

1. Spec changed from referring to files as a "Frozen Array" to a sequence. I have not heard of a frozen array before - can you tell me how a sequence differs practically from an array in Javascript? (or what type of Array this would mean?)
2. The share validation ends with two points:
   • Once the data has either been successfully transmitted to the share target, or successfully transmitted to the OS (if the transmission to the share target cannot be confirmed), resolve [[sharePromise]] with undefined.
   • Set [[sharePromise]] to null.

When does the last point happen? i.e. as a user I see my promise resolved with undefined - when does the setting of this value to null happen? I'm still working on my javascript so this may be a stupid question sorry!

[marcoscaceres]

Spec changed from referring to files as a "Frozen Array" to a sequence. I have not heard of a frozen array before - can you tell me how a sequence differs practically from an array in Javascript? (or what type of Array this would mean?)

It's just a regular array that's had Object.freeze() called on it 😁:

const frozenArray = Object.freeze(["a", "b", "c"]);
frozenArray.pop(); // exception
frozenArray.push("can't add me!"); // exception

The share validation ends with two points: Once the data has either been successfully transmitted to the share target, or successfully transmitted to the OS (if the transmission to the share target cannot be confirmed), resolve [[sharePromise]] with undefined. Set [[sharePromise]] to null.

When does the last point happen? i.e. as a user I see my promise resolved with undefined - when does the setting of this value >to null happen? I'm still working on my javascript so this may be a stupid question sorry!

These are great questions @hamishwillee! Don't be sorry.

So, let me illustrate this for you.

I click on the share button, and the promise goes into a "pending state" and the following native UI is shown:

The promise sits there waiting until the user either chooses something or clicks on the page again (dismissing the native UI).

So, imagine if I click on "✉️ mail": on MacOS, that needs to start up mail.app, etc. and the browser can't know if that's succeeded or not. So, at that point, the browser just throws its hands in the air and assumes everything went ok (promise resolves! and "Set [[sharePromise]] to null.").

Hope that made sense!

[hamishwillee]

Thanks @marcoscaceres

1. So freeze makes sense. How does a sequence differ? (i.e. the new definition in the spec). My guess from reading that is that it is essentially a list like type, just like an Array. So perhaps the change just means "the array no longer needs to be a frozen array. To summarise - I propose to document this property as "an Array of files to be shared."
2. Let me confirm.
   • The way I originally interpreted "2" is that after resolving with undefined at some later point the whole promise slot is set to a null value. Since this came at the end of the list of items it reads to me that even if you resolve with some other value, eventually the system will set that slot to null.
   • Now I think you are saying that on success a promise will resolve to undefined. On known failure it will resolve to some known error/exception. However if it sits there forever, eventually the browser will decide to resolve it null which presumably a caller should just ignore - is that right?

[marcoscaceres]

So freeze makes sense. How does a sequence differ? (i.e. the new definition in the spec).

Sequence is just a regular array. See the second algorithm here: https://heycam.github.io/webidl/#es-sequence

"An IDL sequence value S of type sequence is converted to an ECMAScript Array object as follows:"

My guess from reading that is that it is essentially a list like type, just like an Array. So perhaps the change just means "the array no longer needs to be a frozen array. To summarise - I propose to document this property as "an Array of files to be shared."

Yes. That would be correct.

[marcoscaceres]

Let me confirm. The way I originally interpreted "2" is that after resolving with undefined at some later point the whole promise slot is set to a null value. Since this came at the end of the list of items it reads to me that even if you resolve with some other value, eventually the system will set that slot to null. Now I think you are saying that on success a promise will resolve to undefined.

Correct. I might change the spec text to use an internal "flag" ("has pending share") instead of the promise. That might make things less confusing. The null is not something that is observable or something that is exposed to JavaScript.

On known failure it will resolve to some known error/exception.

Correct.

However if it sits there forever, eventually the browser will decide to resolve it null which presumably a caller should just ignore - is that right?

That's right, but just ignore the null part - it resolves with undefined (again, null is just an internal thing used by the algorithm).

[hamishwillee]

That is clear. The promise resolves to undefined on success or presumed success, and some error on known failure. The null is some kind of internal flag. I don't know how to best resolve that in the spec, as they are written for implementers, not end user developers. The MDN doc will end up addressing this audience.

Thank you so much! Nice to have such prompt and well thought out answers :-)

[marcoscaceres]

Closing as answered.

[hamishwillee]

Yes it is. Thanks!!!