デコレータとコールバック関数の使い分けを考える #TypeScript

## これは何?

ふと，TypeScriptを書いていて，デコレータとコールバック関数って微妙に似ているなと思った。
デコレータもコールバック関数はどちらも関数を操作/制御する仕組みであり，同じようなことができそうだなと。

試しにある関数(ここでは`hello()`)の前後で処理を追加することを試してみたが，どちらを使っても同じことができる。

```shell
# デコレータ
cd /app && tsc && node dist/decorator.js
start
Hello, World!
end
```

<details><summary>デコレータの実装例</summary>

```typescript
/**
 * とりあえずのデコレータ
 */
function logging() {
  return function(
    originalMethod: any,
    context: ClassMethodDecoratorContext<any, any>
  ) {
    function replacementMethod(this: any, ...args: any[]) {
      console.log("start");
      const result = originalMethod.apply(this, args);
      console.log("end");
      return result;
    }
    
    return replacementMethod;
  };
}

/**
 * デコレータの使用するクラス
 */
class Greeter {
  /**
  * デコレータを使用するメソッド
  * @param name 名前
  */
  @logging()
  hello(name: string) {
    console.log(`Hello, ${name}!`);
  }
}

// インスタンスを作成して実行
const greeter = new Greeter();
greeter.hello("World");
```
</details>


```shell
# コールバック関数
cd /app && tsc && node dist/callback.js
start
Hello, World!
end
```

<details><summary>コールバック関数の使用例</summary>

```typescript
/**
 * とりあえず，コールバック関数を試すクラス
 */
class Greeter {
  /**
   *  コールバック関数を受け取るメソッド
   */
  static logger(callback: (greeter: Greeter) => void) {
    const greeter = new Greeter();
    console.log("start");
    callback(greeter);
    console.log("end");
  }
  /**
   * @param name 挨拶する相手の名前
   */
  hello(name: string) {
    console.log(`Hello, ${name}!`);
  }
}

Greeter.logger((greeter: Greeter) => {
  greeter.hello("World");
});
```

</details>

そのため，デコレータとコールバック関数について

- 概要
- どのような時に使われるか
- デコレータとコールバック関数どちらを使うべきなのか

をまとめてみた。
詳しい方がいればコメント欄等に意見をいただけると大変喜びます。

---

## デコレータについて

### デコレータの概要

デコレータというと自分の中ではPythonのイメージが強いので，Pythonの公式ドキュメントを引用した。

> decorator
> (デコレータ) 別の関数を返す関数で、通常、 @wrapper 構文で関数変換として適用されます。デコレータの一般的な利用例は、 classmethod() と staticmethod() です。
> 
> デコレータの文法はシンタックスシュガーです。次の2つの関数定義は意味的に同じものです:
>
> ```python3
> def f(arg):
>    ...
> f = staticmethod(f)
> ```
> 
> ```python3
> @staticmethod
> def f(arg):
> ```
> [^1]

:::note info
シンタックスシュガーとは

> 糖衣構文（とういこうぶん、英: syntactic sugar あるいは syntax sugar）は、プログラミング言語において、読み書きのしやすさのために導入される書き方であり、複雑でわかりにくい書き方と全く同じ意味になるものを、よりシンプルでわかりやすい書き方で書くことができるもののことである。 [^2]
:::

上の例について少し補足すると，`@staticmethod`を`f`関数につけること=関数を引数にとる関数`staticmethod()`の引数に`f`関数を渡し，`f`関数の定義を上書きしている。
つまり，`f("hoge")`を実行する場合を考えると，`f = staticmethod(f)`と定義しているので，
`f("hoge")` = `staticmethod(f)("hoge")`になる。
念の為，`staticmethod`の実装はどうなっているか確認しておく。
`staticmethod`は，通常の関数をstaticmethodにして返しているため，[^3][^4]
`f("hoge")` = `staticmethod(f)("hoge")` = `変換されたメソッド("hoge")`のようになる。

簡単にまとめると，「関数を引数にとる関数を使用することで，もとの関数を上書きする」というような動きをしている。

### 冒頭に記載したデコレータのサンプルコードについて

冒頭にも記載したコードにおいての，デコレータの動きを確認しておく。

```typescript
/**
 * とりあえずのデコレータ
 */
function logging() {
  return function(
    originalMethod: any,
    context: ClassMethodDecoratorContext<any, any>
  ) {
    function replacementMethod(this: any, ...args: any[]) {
      console.log("start");
      const result = originalMethod.apply(this, args);
      console.log("end");
      return result;
    }
    
    return replacementMethod;
  };
}

/**
 * デコレータの使用するクラス
 */
class Greeter {
  /**
  * デコレータを使用するメソッド
  * @param name 名前
  */
  @logging()
  hello(name: string) {
    console.log(`Hello, ${name}!`);
  }
}

// インスタンスを作成して実行
const greeter = new Greeter();
greeter.hello("World");
```
試しに`greeter.hello`をconsole.logで出力してみると，`replacementMethod`であることがわかる。

```shell
cd /app && tsc && node dist/decorator.js
[Function: replacementMethod]
```
つまり，`greeter.hello("World")`を実行すると`logging`で定義した`replacementMethod`が実行され，もとのメソッドの実行前に処理を追加することができている。

### デコレータの使うタイミングはいつか?

TypeScriptのドキュメント[^5]を見ると，デコレータは既存のクラスやメソッドに対して要素を追加するための方法として存在しているようだ。

> Decorators provide a way to add both annotations and a meta-programming syntax for class declarations and members.

:::note info
meta-programingとは
> メタプログラミング (英語: metaprogramming) [注釈 1]とはプログラミング技法の一種で、一般に「プログラムを記述するプログラム」を書くこと、またはそのプログラムを指す[1]。対象言語に埋め込まれたマクロ言語によって行われることもある。 [^6]
:::

一般的なデコレータを使割れるケースとしては，以下のようなケースで使われているイメージがあるが，

- ロギング: メソッドの呼び出しや終了時にログを出力する
- バリデーション: メソッドの引数のバリデーションチェックを行う
- 認可，アクセス制御: API使用前にトークンを検証する

主体はデコレートされるメソッドにある。

---

## コールバック関数について

### コールバック関数の概要

> コールバック関数は、引数として他の関数に渡され、外側の関数の中で呼び出されて、何らかのルーチンやアクションを完了させる関数のことです。
> 
> コールバックベースの API の利用者は、API に渡す関数を書きます。API の提供者（caller と呼ばれる）は関数を受け取り、呼び出し側の本体内のある時点で関数をコールバック（実行）します。呼び出し側はコールバック関数に正しい引数を渡す責任があります。また、呼び出し側はコールバック関数からの特定のな返値を期待することがあり、呼び出し側のさらなる動作を指示するために使用します。
> [^7]

つまり，コールバック関数は「他の関数に引数として渡される」関数である。

### 冒頭に記載したコールバック関数のサンプルコードについて

```typescript
/**
 * とりあえず，コールバック関数を試すクラス
 */
class Greeter {
  /**
   *  コールバック関数を受け取るメソッド
   */
  static logger(callback: (greeter: Greeter) => void) {
    const greeter = new Greeter();
    console.log("start");
    callback(greeter);
    console.log("end");
  }
  /**
   * @param name 挨拶する相手の名前
   */
  hello(name: string) {
    console.log(`Hello, ${name}!`);
  }
}

Greeter.logger((greeter: Greeter) => {
  greeter.hello("World");
});
```

※これはデコレータ本来の使い方では無い気がする。しょうさいは[考察](https://qiita.com/sigma_devsecops/items/c8c1997f50f5b3052416#%E8%80%83%E5%AF%9F-%E7%B5%90%E5%B1%80%E3%83%87%E3%82%B3%E3%83%AC%E3%83%BC%E3%82%BF%E3%81%A8%E3%82%B3%E3%83%BC%E3%83%AB%E3%83%90%E3%83%83%E3%82%AF%E9%96%A2%E6%95%B0%E3%81%AE%E9%81%95%E3%81%84%E3%81%AF%E3%81%AA%E3%81%AB%E3%81%8B)を参照

試しに，static methodにしてみた。
(デコレータのコードと対称でないが，まあ一旦いいやとしている)

やっている処理としては，`Greeter`クラスのstatic methodである`logger()`を呼び出し，そのコールバック関数として`hello`を実行している。



### コールバック関数を使うタイミングはいつか?

#### 非同期処理やイベントハンドラ 

よく見るのは，イベントハンドラー等で使うケースである。

:::note info
イベントリスナ/ハンドラとは

> イベントハンドラ(event handler)とは，コンピュータプログラムで特定の出来事(イベント)が発生した時に実行するよう定められた処理のこと。
> [^8]

ハンドラとリスナには大きな違いはなさそう

> 「イベントハンドラ」と「イベントリスナ」は特に区別されずほぼ同義とみなされることが多い
> [^8]
:::

```javascript
// ボタンクリック時に実行する処理を定義
button.addEventListener("click", (event) => {
  console.log("button is clicked!");
});
```

```typescript
// MCP Server側で，MCP Clientからの使用可能なツールの一覧を取得するリクエストに対するリクエストハンドラ
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "create_or_update_file",
        description: "Create or update a single file in a GitHub repository",
        inputSchema: zodToJsonSchema(files.CreateOrUpdateFileSchema),
      },
      ...
```

#### 依存性注入

```typescript
class McpClient {

  static async session(callback: (client: McpClient) => Promise<void>) {
    const client = new McpClient()
    try {
      await callback(client)
    } catch (error: any) {
      console.log("error");
    } finally {
      await client.close() // セッションや接続の後始末
    }
  }
  ...
}

await McpClient.session(async (client) => {
  await client.doSomething() // 後始末やエラーハンドリングを気にしなくて良い
})
```

- 呼び出し側が`close()`を呼び出し忘れることを防げる
- 呼び出し側が`.doSomething()`の変わりに別の関数を渡したり，追加したりできるなどカスタマイズ性が高い
  ```typescript
  // session()が使用する関数をハードコーディングする例
  class McpClient {

  static async session() {
    const client = new McpClient()
    try {
      await client.doSomething(); // カスタマイズができない
    } catch (error: any) {
      console.log("error");
    } finally {
      await client.close() // セッションや接続の後始末
    }
  }
  ```

#### (配列操作など)

競技プログラミングとかで便利そう?

```typescript
const testList = [1, 2, 3].map(x => x * 2); // [2, 4, 6]
```

---

## 考察: 結局，デコレータとコールバック関数の違いはなにか

いろいろ調べた結果の自分の見解だが，それぞれが対象とする領域は異なると思う。

### デコレータを選択する時

デコレータは実装の詳細を共通化したい時に使う。観察可能な振る舞い(observable behavior)つまり，メインのロジックを書く時には使わない。

- あくまで，関数やクラスに処理を付け加える(修飾する)もの。処理の主体はデコレートされる関数にあり，デコレータではない。
- デコレータが対象とする領域はロギング，バリデーション，認可/アクセス制御といったボイラープレート的なコードが多そう。
- デコレータ側に共通処理が書くことで，コードの再利用性を高める

### コールバック関数を選択するとき

逆に，コールバック関数は観察可能な振る舞いを変化させるのに使う。

- 引数として関数を渡すのがコールバック関数なので，観察可能な振る舞いが変化する。コールバック関数側も処理の主体である
- コールバック関数によって観察可能な振る舞いを変化させることができるので，コールバックを引数に取る関数側の再利用性を高める

まとめると，デコレータを使うべきなのか，それともコールバック関数を使うべきかに迷った際には，実装の詳細を書きたいのか，それとも観察可能な振る舞いを書きたいのかをもとに判断すると良いのではないだろうか。

---

## Reference

[^1]: [用語集 Python 3.13.3](https://docs.python.org/ja/3.13/glossary.html)
[^2]: [糖衣構文 Wikipedia](https://ja.wikipedia.org/wiki/%E7%B3%96%E8%A1%A3%E6%A7%8B%E6%96%87)
[^3]: [typeshed/stdlib/bultins.pyi](https://github.com/python/typeshed/blob/main/stdlib/builtins.pyi)
[^4]: [Built-in Functions staticmethod](https://docs.python.org/3/library/functions.html#staticmethod)
[^5]: [TypeScript: Documentations decorators](https://www.typescriptlang.org/docs/handbook/decorators.html)
[^6]: [メタプログラミング Wikipedia](https://ja.wikipedia.org/wiki/%E3%83%A1%E3%82%BF%E3%83%97%E3%83%AD%E3%82%B0%E3%83%A9%E3%83%9F%E3%83%B3%E3%82%B0)
[^7]: [Callback function (コールバック関数)](https://developer.mozilla.org/ja/docs/Glossary/Callback_function)
[^8]: [イベントハンドラ](https://e-words.jp/w/%E3%82%A4%E3%83%99%E3%83%B3%E3%83%88%E3%83%8F%E3%83%B3%E3%83%89%E3%83%A9.html)