Make legacy fileOpen API accept configurable cleanup and rejection

[jmrog]

Here is a rough idea/proposal for handling the later discussion in #41.

[google-cla[bot]]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

:memo: Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[google-cla[bot]]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

:memo: Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[jmrog]

@googlebot I signed it!

[tomayac]

Thanks for opening this PR. I have to admit I'm not a fan of the way this complicates the API. Let me think a bit more if there is a different way.

I had more something in mind like the following:

import { fileOpen, supported } from 'browser-fs-access';

// … before
let file;
if (supported) {
  try {
    file = await fileOpen();
  } catch (err) {
    console.error(err);
  }
} else {
  file = await fileOpen();
}
// … after

I admit this looks not very elegant, but it makes clear that there is no magic. What do you think of this?

[jmrog]

Thanks for opening this PR. I have to admit I'm not a fan of the way this complicates the API. Let me think a bit more if there is a different way.

Yeah, it does complicate the API a bit. I'm inclined to think it doesn't complicate things too much, though, especially given the payoff: the only change surfaced to the library user is that you can, if you wish, provide an optional callback that can be used to set up the conditions under which a cancel/rejection is triggered in the legacy API. The callback just sets the rejectionHandler and then returns a method that will be called on "cleanup" (i.e., when success occurs, or when the rejection condition is hit). This is a bit analogous to React's useEffect hook or React Router's history.listen API, so there's something like "prior art" for it that people may be familiar with. The payoff is that you can, if you wish, completely configure how rejection is both triggered and handled for the legacy API; fewer need-to-fix bug reports on browser-fs-access and more control for the developer (but it's opt-in; you don't need to deal with this part of the API at all).

I should've included the example of how it would work here, rather than just in the issue comments for #41, so I'm dropping the example here just for reference (note that I've removed the comments this time, in case that made it look more complicated than it is):

const file = await fileOpen({
  setupLegacyCleanupAndRejection: (rejectionHandler) => {
    const timeoutId = setTimeout(rejectionHandler, 10000);
    return (reject) => {
      clearTimeout(timeoutId);
      if (reject) {
        reject('My error message here.');
      }
    };
  },
});

If you don't want to use the option to configure this stuff, you can still of course just do:

const file = await fileOpen();

I had more something in mind like the following:

import { fileOpen, supported } from 'browser-fs-access';

// … before
let file;
if (supported) {
  try {
    file = await fileOpen();
  } catch (err) {
    console.error(err);
  }
} else {
  file = await fileOpen();
}
// … after

I admit this looks not very elegant, but it makes clear that there is no magic. What do you think of this?

I don't think I understand this part. Wasn't the goal to make rejection behavior configurable, so that the user could control how/when rejection occurs (that's what I took from the last line of this comment)? The example above doesn't seem to do that anywhere, but I could be missing it. Is the example supposed to show that the library itself would handle rejection if and only if supported is true, but would otherwise not handle the rejection and instead leave the handling up to the developer? That wouldn't be enough for us (i.e., not enough to fix #41 for us), because the library would still do the rejecting immediately in Chrome over HTTP (at least with the current implementation), even if it were to then be left up to us how to handle the rejection. We need some control over when a "rejection" is triggered in the first place (or else we need the library just not to reject at all -- which is why we've temporarily reverted back to v0.13.1 of the library). EDIT: Ah, now that I look more closely, I'm wondering if perhaps the example is showing that the library will just not reject in the case where supported is false?