typescript-eslint: Enhancement: [no-floating-promises] Don't check coincidentally Promise-like (Thenable) type values by default

Before You File a Proposal Please Confirm You Have Done The Following…

My proposal is suitable for this project

  • I believe my proposal would be useful to the broader TypeScript community (meaning it is not a niche proposal).

Link to the rule’s documentation

https://typescript-eslint.io/rules/no-floating-promises

Description

Forwarding out from conversations with @mcollina, especially https://github.com/nodejs/node/issues/51292#issuecomment-1937792288: right now no-floating-promises will consider anything that looks like a Promise (i.e. is “Promise-like”) to be a potential floating value:

https://github.com/typescript-eslint/typescript-eslint/blob/5857356962060b19aa792bee778f9167ee54154b/packages/eslint-plugin/src/rules/no-floating-promises.ts#L353

But to my knowledge this hasn’t been particularly helpful. If something coincidentally happens to match the Thenable interface that doesn’t necessarily mean it shouldn’t float!

The historical context here is that it used to be common in JavaScript code to use alternative implementations of Promises, such as Bluebird. Promises were only added to some browsers in ~2014 and Node & co in ~2015 or so. Many sites still had to support old versions of Internet Explorer. The no-floating-promises typescript-eslint rule was implemented in 2019 when it was still not-unheard-of to use alternative Promises or at least have Promise types provided by a polyfill: https://github.com/typescript-eslint/typescript-eslint/pull/495.

Now that the vast majority of projects are using built-in Promise values & types, I think the value of detecting those values automatically is no longer worth the pain of flagging general thenables. I propose we modify the rule to:

  • (non-breaking) Add in an option to specify types to be considered Promises - using the same standard format as #7008
  • (breaking, as a followup issue & PR for v8) Change the rule to no longer detect Thenables, and instead only look for the built-in Promise type
    • Nuance: should users be able to remove the built-in Promise type from the list of checked types? I don’t think so, but that’s not a decision we’d need to make now…

I.e. this is the opposite of #7008. That issue is about adding an allowlist for types to be allowed to float. This one is adding a blocklist of types to not be allowed to float - instead of always detecting Thenables.

Fail

declare function createPending(): PromiseLike<void>;

createPending();

Pass

declare function createPending(): Promise<void>;

createPending();

Additional Info

After the proposed followup, if folks still want to detect floating PromiseLikes, they’d be able to use this option.

As to whether we’d want to give users a way to opt back into the current “check anything that looks like a Thenable” behavior… I don’t see why anybody would want that, but we could always make it an option if someone asks for it.

About this issue

  • Original URL
  • State: closed
  • Created 3 years ago
  • Reactions: 1
  • Comments: 15 (10 by maintainers)

Most upvoted comments

Yeah, I don’t think "always" / "strict" makes sense. Fastify is not “accidentally-thenable”, it’s very much on purpose. No one is going to implement then “by accident” and not expect it to work with await.

@mcollina what would be useful for us here and in https://github.com/fastify/fastify/pull/5506#discussion_r1631225510 would be: why does the FastifyInstance interface have a .then()? Can you share more on the design decision there?

For example, is it intentional that someone would await a value of type FastifyInstance? If so, why? If not, why the .then()?

(to be clear: not imparting judgement on the code, just trying to understand the context)

Ok so coming back to this: what is the consensus here? I’m:

  • Still in favor of making checking thenables an opt-in a la #9263
  • No longer suggesting we make it more granular than an always/never boolean

Note that .then(resolve, reject) would not fix us (https://github.com/typescript-eslint/typescript-eslint/issues/8433#issuecomment-2156412327). In other words, .then(resolve, reject) cannot guarantee Promise/A+ spec. You’ll likely have to use a different type for those edge cases.

Fastify has a rich plugin system, and all plugins load asynchronously.

We support an API like:

const app = fastify()
await app
  .register(myPlugin1)
  .register(myPlugin2)
  .register(myPlugin3)

This is also supported:

const app = fastify()
app.register(myPlugin1)
app.register(myPlugin2)
await app.register(myPlugin3)

Adding the await will call .then(), which will, in turn, start the plugins’ loading.

Note that awaiting the instance is entirely optional:

const app = fastify()
app.register(myPlugin1)
app.register(myPlugin2)
app.register(myPlugin3)
await app.listen({ port: 3000 })

There are also other methods on the app:

const app = fastify()
app.get('/', ...).post('/', ...)

await app.listen({ port: 3000 })

The FastifyInstance type does not have a .then() method because of the lack of this rule (and not being enabled by default). According to no-floating-promises, if we added a .then() function, we would need to:

const app = fastify()
await app.get('/', ...) // or void app.get('/', ...)
await app.post('/', ...)

await app.listen({ port: 3000 })

This would work, but it adds unnecessary overhead and worsens the framework’s DX.

Note that our Reply object has a then() method that will resolve when reply.send() is called. This allow us to support:

const app = fastify()

app.get('/simple', async function (req, reply) {
  return { hello: 'world' }
})

app.get('/complex', async function (req, reply) {
  // calling `.then()` here is incorrect, as it will wait for the response to be sent
  // however no-floating-promises forces the user to add a `void`
  void reply.header('x-foo', 'bar')
  setImmediate(() => {
    // Note that this break the promise chain
    reply.send('something')
  })
  return reply // this will can reply.then()
})

app.get('/empty', async function (req, reply) {
  // this will return an empty response
})

@Josh-Cena moving our comments from #9263 back over here for issue discussion:

@Josh-Cena: I don’t get the motivation for this, TBH. How can something “happen to be thenable” without noticing? Does then have any other meaning other than interoperating with promises? JavaScript itself resolves thenables, so if your thenable is not supposed to quack like a promise you will shoot yourself in the foot everywhere, like returning it from an async function, etc.

@JoshuaKGoldberg:

How can something “happen to be thenable” without noticing? https://github.com/DefinitelyTyped/DefinitelyTyped/blob/e40cab53d9971a3e0b34e8fb18ece74240d9425d/types/bluebird/index.d.ts#L59: older projects that have polyfills which generally intentionally match something like Promises/A+.

@Josh-Cena: The issue mentions node:test, but doesn’t test() return a real promise?

@Josh-Cena: the Node issue does, but our #8433 -> this PR isn’t around that I don’t think.

@Josh-Cena: That issue doesn’t mention a valid use case where you want a thenable to not be checked like a promise though. It just mentions polyfills but those are why we check thenables.

Ah, I think I see what you’re asking for - any reason why we would want to not check a thenable at all? That’s a good question.

I’d come into this assuming it was a generally-desirable feature, but now I’m questioning that. Maybe now that we have the allowForKnownSafePromises option from #9186 we don’t need this anymore?

Putting this issue into evaluating community engagement. If anybody can provide a real use case for not checking Thenables by default, please do - that would help us to justify adding #9263’s checkThenables option. ❤️

Thanks for pressing @Josh-Cena!