feat: Add subscribeOnce and waitUntil methods

[FrederikBolding]

Explanation

Add subscribeOnce and waitUntil utility methods to Messenger. These are useful for subscribing to and waiting for a certain event to fire without wanting to listen for more than one invocation.

Additionally the methods support a condition parameter which can be used as a predicate for whether the event should be consumed in the first place.

A similar approach is already in-use on mobile, this is a "native" replacement.

References

https://consensyssoftware.atlassian.net/browse/WPC-985

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

[FrederikBolding]

When not using a selector this just returns the first parameter of the event. The other option is returning the entire array, but that feels a bit complicated 🤔

[mcmire]

Hmm, why does it feel complicated? If it's easy to support, I say we give consumers the whole payload.

[Mrtenz]

What if you want to specify a condition, but not a selector? Like this for example:

// Subscribe to `KeyringController:unlock` and wait if condition is not met
await messenger.waitUntil(
  'KeyringController:unlock',
  () => !engineContext.KeyringController.isUnlocked()
);

Maybe it's easier to have an options object, so you could do something like this:

await messenger.waitUntil(
  'KeyringController:unlock',
  {
    condition: () => !engineContext.KeyringController.isUnlocked()
  }
);

[FrederikBolding]

I'm confused by this question, if KeyringController.isUnlocked is true you wouldn't want to wait for unlock in the first place. The condition is meant as a condition on the value itself and is only checked when an event fires, e.g.

await messenger.waitUntil(
  'TransactionController:transactionSuccess',
  (tx) => tx.hash === 'foo'
);

[FrederikBolding]

That being said, it would be nice if you could pass a condition without a selector. Potentially worth doing an options bag regardless.

[Mrtenz]

Then I was misunderstanding what the condition is supposed to do 😅

[Mrtenz]

I was under the impression that these would be equivalent:

await messenger.waitUntil(
  'KeyringController:unlock',
  {
    condition: () => !engineContext.KeyringController.isUnlocked()
  }
);

and

if (!engineContext.KeyringController.isUnlocked()) {
  await messenger.waitUntil('KeyringController:unlock');
}

[FrederikBolding]

I don't see an obvious way to solve for both that and the TransactionController example from above 🤔

[Mrtenz]

Yeah, we'd need to introduce a third property. But in hindsight, I'm not sure if it's necessary as the if statement seems clean enough.

[FrederikBolding]

Certainly better than what we have today

[FrederikBolding]

5907ef9

[mcmire]

How we expect waitUntil to be used? In Slack you gave this example:

  getUnlockPromise: () => {
    if (engineContext.KeyringController.isUnlocked()) {
      return Promise.resolve();
    }
    return new Promise<void>((resolve) => {
      controllerMessenger.subscribeOnceIf(
        'KeyringController:unlock',
        resolve,
        () => true,
      );
    });
  },

Is the idea that with this method you could shorten this to the following?

  getUnlockPromise: () => {
    return await controllerMessenger.waitUntil(
      'KeyringController:unlock',
      {
        condition: () => {
          return engineContext.KeyringController.isUnlocked();
        }
      }
    );
  },

Or is it that we would expect people to write this instead?

  getUnlockPromise: () => {
    return await controllerMessenger.waitUntil(
      'KeyringController:stateChange',
      {
        selector: (state) => state.isUnlocked,
      }
    );
  },

[mcmire]

Either way would we want to check the condition beforehand to make sure is not true before subscribing? (I guess the same goes for subscribeOnce as well.)