Async Style
How to write await, return, promise chains, catch and async functions. Lint rules in @venizia/dev-configs check these; turn them on with the two config arrays shown at the end.
Await stands alone
await is a whole statement, or the whole initializer of a declaration. It is not inside another expression.
// Not this
expect(await load()).toBe(1);
const name = (await load()).name;
send(await build(), await sign());
// This
const loaded = await load();
expect(loaded).toBe(1);
const { name } = await load();
const body = await build();
const signature = await sign();
send(body, signature);Tests follow the same rule. An assignment (value = await load()) is also not allowed: declare the value first, then assign.
When a branch decides whether to wait, write the branch with statements:
let value = fallback;
if (isCached) {
const cached = await readCache();
value = cached;
}Declare the instance, then await
Never call a method on a fresh instance inside an await. Declare the instance on its own line, then await on the next.
// Not this
await new RelationalMigrationRunner({ driver }).run({ migrations });
const text = await new Response(body).text();
const token = await new SignJWT(claims).setIssuer(issuer).sign(key);
// This
const runner = new RelationalMigrationRunner({ driver });
await runner.run({ migrations });
const response = new Response(body);
const text = await response.text();
const jwt = new SignJWT(claims).setIssuer(issuer);
const token = await jwt.sign(key);A builder chain declares the builder, then awaits its last call. await new Promise(...) is fine: no method is called on the new instance. await new X().prop is not a call and is fine too.
Return the promise
A function that ends with a promise returns it: return load(), not return await load().
Inside try, catch or finally, where the await decides which failures the catch sees, write the await on its own line:
try {
const loaded = await load();
return loaded;
} catch (error) {
return recover({ error });
}Await or chain, never both
One expression uses one style: await, inside try/catch when it can fail, or a promise chain (.then, .catch, .finally) that is not awaited.
// Not this
const user = await findUser({ id }).catch(() => null);
const names = await loadUsers().then((users) => users.map((user) => user.name));
// This
let user: IUser | null;
try {
const found = await findUser({ id });
user = found;
} catch (error) {
logger.error('findUser failed: %s', error);
user = null;
}
const users = await loadUsers();
const names = users.map((user) => user.name);A chain that is not awaited is fine: return load().then(parse), or load().then(show).catch(report) as a statement. So is await Promise.all(items.map(save)): the awaited call is not a chain. An await inside a callback of a chain is not reported either.
The rule reads the syntax only. ?.then(, ['then'](, ! and as around the chain count, and so does a thenable such as a query builder (await query.then(...)).
The fix covers one shape, const x = await f().catch(() => <value>), alone in its declaration. The value is a literal, an identifier, a read of the error ((error) => error.message), or an array or object literal of those. The const becomes a let; a type annotation stays. The fix is not made when:
- the call before
.catchholds a.then, a.finallyor anawait; - the handler has a block body, calls something, or is async;
xis written again;xhas no type annotation and is read inside a nested function, exported or used in atypeof;- the value is
[]with no annotation (a bareletwould type it asany[]); - a comment would be lost.
Every other awaited chain (.then, .finally, return await f().catch(h), an await as a whole statement) is reported for you to rewrite. The try also catches a synchronous throw of f(), which the chain let through.
Never swallow an error
A catch leaves a trace: it logs the error, rethrows it or wraps it. These are reported:
load().catch(() => null);
load().catch(() => {});
try {
await load();
} catch {
// ignore
}A handler or a catch block counts as silent when it does nothing, holds only a comment, or only returns or assigns a constant without reading the error. Any call (a log, a cleanup, a fallback), a throw, or a read of the error makes it handled. When a silent catch is what you want, keep it with // eslint-disable-next-line venizia/no-silent-catch -- <the reason>.
ESLint no-empty is different: it reports only an empty block, lets a block with a comment pass, and never sees .catch(() => null). Both report catch {}.
The fix of the chain rule keeps behaviour, so .catch(() => null) becomes catch { x = null; }, and this rule then reports it. That is on purpose: you decide what to log.
Hooks
- Never pass an async function to a
use...call. Pass a sync callback and handle the promise inside it with.then,.catchand.finally. - An effect callback (
useEffect,useLayoutEffect,useInsertionEffect) returns nothing on every path, or a cleanup function on every path. An early exit returns a no-op cleanup when another path returns a real one. - A hook method returns its promise only when a caller waits on it. Otherwise it just calls. No lint rule checks this one.
// Not this
useEffect(async () => {
const data = await load();
setData(data);
}, []);
// This
useEffect(() => {
load()
.then((data) => setData(data))
.catch((error) => report({ error }));
}, []);Turning the rules on
The rules are in houseConfigs, so one array turns them on:
// .configs/lints/eslint.config.mjs
import { houseConfigs } from '@venizia/dev-configs/linters';
export default houseConfigs;A project that adds its own entries spreads the array: [...houseConfigs, { ... }]. A React project uses reactHouseConfigs the same way: it carries the five async rules and the two hook rules (venizia/no-async-hook-callback, venizia/effect-cleanup-consistency).
To fix an existing codebase, run the codemod. It applies the safe fixes of no-inline-await, no-return-await, no-await-new-chain and no-await-promise-chain, and lists the rest with file, line and rule, including every silent catch, which it never fixes:
devz codemod async-style packages/my-package # dry run
devz codemod async-style packages/my-package --write # commit your work first; --write needs a path, or --all for the whole treeThe ESLint setup these rules extend is in Tooling.