TypeScript 版 Mackerel API クライアントライブラリを作った

作りました.

jsr.io

リポジトリはこっち.

github.com

(2024-05-12 現在, 筆者は Mackerel を開発している株式会社はてなの社員ですが, これは個人プロジェクトで, API ドキュメントなどの公開されている情報に基づいて作成されています.)

なぜ

JSR になんか publish したくなった
- 乗るしかないこのビッグウェーブ
TypeScript で Mackerel を操作するちょっとしたスクリプトを書きたかったが, 意外とクライアントライブラリがなかった
- 単に JSON を fetch してくるだけなら簡単だが, それだけでは型もないし使いづらい

使い方

1. JSR からインストール

# Deno
deno add @susisu/mackerel-client
# Node.js
npx jsr add @susisu/mackerel-client

2. スクリプトを書く

import { MackerelClient } from "@susisu/mackerel-client";

const cli = new MackerelClient("<YOUR API KEY>");

// ホストを一覧したり
const hosts = await cli.hosts.list();
console.log(hosts);

// サービスを作成したり
await cli.services.create({
  name: "myservice",
});

やったこと

Deno で開発して JSR に公開
リクエストやレスポンスのデータはそのままでは扱いづらいので加工

Deno と JSR

Deno
- Node.js (と npm, ESLint, Prettier など) の方が慣れているし設定内容も困らないけど, 少なくともちょっとしたスクリプトを動かすだけなら設定をコピペしたりする作業がない分 Deno の方が楽
- 気に食わない lint や format はあるものの慣れと時間の問題であろう
JSR
- Deno でライブラリを作るにあたって deps.ts があんまり好きになれなかったのだけれけど, ここは JSR が publish 時に import map を解決してくれるので考えなくて良くなった
- Node.js で npm パッケージとの共存もしやすい. 少なくとも GitHub Packages を使ったときのようなスコープの衝突は起こらないようになっている

データ加工

リクエストやレスポンスのデータ (JSON) に型をつけただけではまだ使いづらい
- オプショナルなデータに対して x: T | null を使うものと x?: T を使うものが混在している
- TypeScript の型システム的に安全に扱いやすい構造になっていない (discriminated union になっていない, index signature や optional property が多用される, など)
- 時刻がプリミティブなデータになっていて操作しづらい
- (これは半分くらいエゴだけど) 数値の単位がわからない, 命名がこなれていない, なぜか必須になっている入力があるなど, その他にもやや使いづらい箇所がある (が, API としては非互換変更になるので改善されづらい)
これらをちまちま加工していく...
- オプショナルなデータは x: T | undefined (またはリクエスト時の入力は x?: T | undefined) に統一する. null ではなく undefined なのは好みです
- discriminated union になるようタグとなるプロパティを含める, index signature は Map<K, V> にする
- 時刻は Date にする
- 命名や構造は適宜良い感じに調整する (例: notificationInterval → notificationIntervalMinutes)
(この手の API を設計するときには, もし TypeScript からの利用を想定するなら, あらかじめ TypeScript フレンドリーかも検討しておけると良さそう)