トップレベルawaitのエラー解決方法

問題

TypeScriptで以下のコードを実行しようとするとエラーが発生します：

const stripe = require('stripe')('someID');
const account = await stripe.accounts.create({
  type: 'express',
});

エラーメッセージ：

Top-level 'await' expressions are only allowed when the 'module' option is set to 'esnext' or 'system', and the 'target' option is set to 'es2017' or higher.ts(1378)

このエラーは、トップレベルでのawait使用が現在のTypeScript設定で許可されていないことを示しています。

解決策

方法1: Async関数でラップする（簡易的な解決策）

最も簡単な方法は、awaitを使用するコードをasync関数でラップすることです：

const stripe = require('stripe')('someID');

const createAccount = async () => {
  const account = await stripe.accounts.create({
    type: 'express',
  });
  return account;
};

// 関数を呼び出して使用
createAccount().then(account => {
  console.log(account);
});

TIP

この方法はコードの修正が最小限で済みますが、非同期処理のネストが深くなる可能性があります。

方法2: TypeScript設定を変更する

プロジェクトでトップレベルawaitを本格的に使用したい場合は、tsconfig.jsonを修正します：

{
  "compilerOptions": {
    "esModuleInterop": true,
    "lib": ["es2020"],
    "module": "es2022",      // または "esnext"
    "moduleResolution": "node",
    "target": "es2022",      // または "es2017"以上
    "outDir": "dist",
    "strict": true,
    "sourceMap": true,
    "types": ["node"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

WARNING

tsconfig.jsonを変更した後も、tscコマンドで個別のファイルを指定してコンパイルすると設定が無視されることがあります。必ずtscのみを実行して全体をコンパイルしてください。

方法3: tsxを使用する（最新の推奨方法）

tsxはTypeScriptファイルを簡単に実行できる新しいツールです：

1. package.jsonにモジュール設定を追加：

{
  "type": "module"
}

2. tsxをインストール：

npm install tsx

3. TypeScriptファイルを実行：

npx tsx file.ts

メリット

• tsconfig.jsonがなくても動作
• トップレベルawaitをサポート
• セットアップが簡単
• ts-nodeよりエラーメッセージが分かりやすい

技術的背景

トップレベルawaitはECMAScript 2022で正式に仕様化された機能です。TypeScriptでは以下の条件を満たす必要があります：

• moduleオプション：es2022、esnext、systemのいずれか
• targetオプション：es2017以上
• モジュールシステムがES Modulesであること

まとめ

方法	適用場面	利点	欠点
Async関数ラップ	簡易的な修正	設定変更不要	コード構造が複雑化
TypeScript設定変更	本格的な使用	ネイティブサポート	環境構築が必要
tsx利用	開発環境	簡単セットアップ	本番環境では別途ビルド必要

プロジェクトの規模や要件に応じて最適な方法を選択してください。開発中はtsx、本番ビルドでは適切なTypeScript設定を使用するのがおすすめです。