概要

WRITE APIに対応した関数を追加しました。

テスト方法

create

• contentIdが指定されたパターンとそうでないパターンでそれぞれPOST, PUT APIが呼ばれたことを確認
• status=draftが指定できることを確認
• bodyが指定されたことを確認

update

• リスト形式とオブジェクト形式のAPIが呼ばれたことを確認
• bodyが指定されたことを確認

delete

• DELETE APIが呼ばれたことを確認
• contentIdが指定されていないときにエラーを返すことを確認

概要

node-fetchを利用した現在のSDKではVite環境でFetchのJSONパースに失敗することがあるためwindow.fetchを利用したい。

また、node環境ではv18が一般的になるまで、まだnode-fetchを利用する必要があるためnode-fetchを利用したい。 上記を叶えるためにfetchのプロキシとして動作するcross-fetchを利用する形へ実装方法を変更しました。

また、Cloudflare Workers環境などではパフォーマンスの観点からもWorkersのGlobal Fetchを利用したいため、createClientにカスタムfetchをオプションとして渡せるようにしています。

const client = createClient({
  serviceDomain: "YOUR_DOMAIN", // YOUR_DOMAIN is the XXXX part of XXXX.microcms.io
  apiKey: "YOUR_API_KEY",
  customFetcher: fetch.bind(globalThis), // Provide a custom `fetch` implementation as an option
});

概要

既存のコードに関してテストを追加しました。

• tests/utils/isCheckValue.test.ts

基本的な値に対してisXXX系関数のテストをしました。

• tests/utils/parseQuery.test.ts

fiedsに配列、数字、文字列を指定した場合とオブジェクトではない値を入力した際のテストをしました。

• tests/createClient.test.ts

意図通りの関数が返されるかと、未指定の引数があったときのエラーをテストしました。

• tests/get.test.ts

get関数を使って、 リスト形式、リスト形式の詳細、オブジェクト形式それぞれのアクセスでデータが取得できるかと、 未指定の引数があった時、サーバエラー時の処理をテストしました。

構成

テストツール: Jest モックサーバー: MSW

https://github.com/wantainc/microcms-js-sdk/issues/9 エラーハンドリング関連でPRさせていただきます。

const client = createClient({
  serviceDomain: "YOUR_DOMAIN",
  apiKey: "YOUR_API_KEY",
});

上記の定義時にserviceDomainを間違えるとmakeRequest関数内のfetchで”404”になり、同関数のcatch (error) {} 内でエラーがキャッチされていない気がしました。

検証内容 （/example/javascript のサンプルコードを使用） 存在しないであろうserviceDomainを入力した場合は下記の様なエラーがでます。

• Uncaught (in promise) SyntaxError: Unexpected end of JSON input

しかし、これはmakeRequest関数内のcatch (error) {} ではない場所からthrowされていると思われます。 （エラー発生の行がコンソールに出力されていない）

MDNからの一部引用ですが、fetch()は404の場合エラーをthrowしない様ですね。

ネットワークエラーに遭遇すると fetch() promise は TypeError を返して reject 状態になります。サーバー側の CORS が適切に設定されていない場合も同様です(アクセス権の問題ですけどね) — 一方で例えば 404 はネットワークエラーを構成しません。

Fetch の使用 - Web API | MDN

fetchに失敗した場合は適切にエラーが表示された方がよいかと思いますので、makeRequest関数内についてはresponse.okでエラーハンドリングした方が良いかもと思いました。 この変更によってコンソールにエラー箇所が表示されているかと思います。

エラーメッセージはもう少し表現を変えても良いかなと悩みました... 適宜変更していただければと思います。

概要

DELETE APIにおいて返却される値は空であるところ、response.json()をしてしまっていたので DELETEの場合は何も返さないように変更しました。

背景

delete関数を実行すると処理自体は完了するが、 node-fetchのInvalid JSONエラーが出る。

変更の種類

fix

概要

isCheckValueファイルの関数における型定義を実態に合わせる変更をしました。 また、isString 関数のチェックで、 nullじゃない判定 等価演算子を使った判定 がありましたので、適切な判定に修正しています。

なぜ

1. isString は文字列しか受け取れず、型の判定をするということができない。（例えばテストを書く際に文字列以外を渡せない）
2. 返り値をisアサーションにすることで、実装上もその型ガードの後の記述では想定通りの型となる

現在、queries.fieldsに渡す情報はカンマ区切りのstringですが、[ 'title', 'publishedAt' ]のようにstring[]も渡せるようにして欲しいです。

理由としては、今後配列形式であれば APIスキーマ情報 をtypescriptで型定義することで、queries.fieldsなどに渡すパラメーターに型補完を効かせることができるのではないか？と考えたためです。 example: string[] => ( 'id' | 'title' | 'body' )[]

Before

client.get({
  endpoint: 'endpoint',
  queries: { fields: 'title,publishedAt' },
})

After

client.get({
  endpoint: 'endpoint',
  queries: { fields: [ 'title', 'publishedAt' ] },
})

Feature

type EndPointContent = {
  id: string
  name: string
  body: string
}


client.get<EndPointContent>({
  endpoint: 'endpoint',
  queries: { fields: [ 'id', 'name' ] }, // 型補完が効いている状態
})

型定義の見直しをしました。ご確認お願いします。

変更点

• types.tsの内容を参照できるように変更

以下のようにtypes.tsの内容をライブラリで参照できるようになります。

import { MicroCMSClient } from 'microcms-js-sdk';

• 共通の型を定義

追加した型定義は下記を参照。 https://github.com/microcmsio/microcms-js-sdk/blob/feature/types/src/types.ts

• getListの追加

TypeScriptでリスト形式のコンテンツを取得する際に使えるAPIを追加しました。

client.getList<Post>({ //値の定義 })

• getListDetailの追加

TypeScriptでリスト形式のコンテンツの詳細を取得する際に使えるAPIを追加しました。

client.getList<Post>({ //値の定義 })

• getObjectの追加

TypeScriptでオブジェクト形式のコンテンツを取得する際に使えるAPIを追加しました。

client.getObject<Post>({ //値の定義 })

なお、既存のgetメソッドに仕様変更はありません。

ビルド時にファイル名 + 各フォーマット.jsで出力するように変更しました。

変更点

• dist/cjs/microcms-js-sdk -> dist/microcms-js-sdk.js
• dist/esm/microcms-js-sdk -> dist/microcms-js-sdk.esm.js
• dist/umd/microcms-js-sdk -> dist/microcms-js-sdk.umd.js

影響

unpkgで参照しているumdファイルのパスが変わります。

<script src="https://unpkg.com/microcms-js-sdk@latest/dist/microcms-js-sdk.umd.js"></script>

Document: https://document.microcms.io/content-api/get-content#hefb095db2a

https://github.com/microcmsio/microcms-js-sdk/blob/f130f3d67cbc727ffc831fd77d19c8760ca4603c/src/types.ts#L19-L29

response.okがfalseの時にthrowされることによって、catch節に移動してしまい、 全て同じエラー内容が返されていましたのでそれを修正しました。 また、現状の実装ならcatch節に入るのはfetchでネットワークエラーになった場合のみなので、 そのようにエラーメッセージを修正しています。

SDKにリトライオプションがないためNext.jsなどでビルドを行う際にビルド全体が停止してしまうか一部のデータが不足してしまう可能性が高いです。 クライアント側でリトライ処理を書けば良いのですが、毎回その実装を行うのは手間がかかります。

提案

インタフェース提案を行いますがこの通りでなくても構いません。

• client 生成時にデフォルトのリトライ設定ができる

//例
const client = createClient({
  serviceDomain: "YOUR_DOMAIN", // YOUR_DOMAIN is the XXXX part of XXXX.microcms.io
  apiKey: "YOUR_API_KEY",
  retry: true, //新しいパラメータ
});

• getなどリクエスト実行時にリトライ設定ができる

//例
client
  .get({
    endpoint: 'endpoint',
    queries: { limit: 20, filters: 'createdAt[greater_than]2021' },
    retry: true, //新しいパラメータ
  })

考慮事項

• 実際にはAPIが返却するレスポンスステータスを見てリトライするかを判別する必要がありそうです。
  • 例えばAWSのリトライ仕様では以下の記載がありました。

Transient errors (HTTP status codes 400, 408, 500, 502, 503, and 504) and throttling errors (HTTP status codes 400, 403, 429, 502, 503, and 509) can all be retried.

• リトライの実装に関しては ExponentialBackoff を行うなどmicroCMSの制限事項に沿うための実装を行う必要があると考えます。

日頃からお世話になっております。

本番環境では公開済みのコンテンツのみを表示したいが、テスト環境では下書き状態のコンテンツも含めて表示し、一覧ページや詳細ページなどサイト全体の表示を確認したいという状況に直面しましたので、パラメータなどで叩く先を Management API に切り替えられるようにしていただけると大変ありがたいです…！