Concurrent, Suspenseの文脈でキャッシュ管理と理想的なデータフェッチを考える (Recoil, Aspida, React Query, GraphQL)

https://zenn.dev/koushisa/articles/1d5272454576e1#応用編-再利用可能なデータフェッチのスライスを作成する

上記を書きながらRecoilにデータフェッチロジックを寄せることに可能性を感じたので考える。
正確には去年からぼんやりと考えていたのだが、プロダクションでRecoilとAspidaを運用しているうちに主にキャッシュ面で辛いところと、具体的にこうするとよさそうという設計案がいくつかでてきた。

思考整理を兼ねてRecoilでのデータフェッチを深堀りする。

データフェッチで考えられるシナリオ

• パラメータ無しのGET
• パラメータ有りのGET
• キャッシュ保持
• キャッシュのinvalidate
• キャッシュしたデータに対するモデリング
  • ReduxでいうcreateEntityAdapter的な
• プリフェッチ(+並行リクエスト)
• SSR対応
  • APIコールを行わずに初期値を渡せる

最大要件とインタフェースはReact Queryを参考にする
https://tanstack.com/query/v4/docs/reference/useQuery

すごいオプションあるけど実際に作ってて欲しくなるのは以下

• onStart
• onEnd
• onSuccess
• onError
• refetchOnMount( or staleTime)

また、ユーザー体験の観点で以下の要件を満たせると良い

• 楽観的UI
• Suspendせずにリフェッチ可能 (画面のチラつき防止)

こうして考えたときにReact Queryはほぼ全ての要求を満たしていてさすがだと思う。
キャッシュも効くのでReduxのサーバーステートをReact Queryに移行する人たちがいるのも理にかなっている。

アプリの規模によってはサーバーステートは全てReact Queryに寄せても問題なさそう。

でもReact Queryだけでは辛い場面もある。
Recoil(atomic state management)利用するモチベーションを整理する。

コンテキスト

大前提として、ライブラリは規模や目的にそって選定すべきなので、コンテキストを明確にしておく。
いわゆる、複雑なフロントエンドだと仮定しよう。

• SaaSのような事業モデルで開発コストが重視され、全体として開発効率や品質面への意識が高い
  • ソフトウェアの息が長い
  • 顧客の声を聞きながら継続的な改善や運用保守が必要
• 管理画面のSPA (SoR > SoE)
  • 更新頻度が高くリアルタイムな整合性が求められる
    • キャッシュを使うときとそうでないときの戦略を都度切り替えられる
  • マスタデータを元に動く画面がある
    • ユーザーのインタラクションによってN個のリソースをフェッチするようなケースが多め
  • ReadモデルとWriteモデルが一致しない
  • 状態の変化を素早く伝える必要がある
  • データ量が多く、パフォーマンスが求められる
• グローバルステートが存在する (ログインユーザー, マルチテナント ...etc)
• APIと画面が1:1ではない
  • 画面を表示するために複数のAPIコールが発生する
  • ウォーターフォールの注意が必要
  • 複雑な画面ではJSON自体もネストが深い
    • コンポーネントツリーも引きづられて深くなる
• フロントエンドにもある程度のビジネスロジックが求められる
  • クライアントのみの状態(フォーム, URL)からN個のAPIを集約してモデリングするなど
  • 権限によって画面切り替えるとか
• チーム開発 (開発と改善チームに分かれて3~10人程度で並行開発する)
  • 相互レビュー, タスク分担を容易にするために構造に一定の秩序を求める
  • ライブラリや設計の意思決定は客観的かつ論理的に判断される必要がある

React Queryの悩み

設計の文脈ではReact Queryだとスケール性が悩ましい。

• コンポーネントとサーバーステートが密結合になる
• キャッシュキーの管理
  • 一応メンテナが推奨している方法はある
    • https://tkdodo.eu/blog/leveraging-the-query-function-context#object-query-keys
    • エンドポイント毎にカスタムフック作るの...?
    • 全体整合性を取るためにルールを決めてレイヤードアーキテクチャっぽくせざるを得ない
    • これを一つずつ手で運用するのはちょっと大変そう
• そもそもhooksはロジックの分離には適していてもデータ構造をモデリングする用途には向いていない
  • クライアント状態を合成するところが肥大化しがち
  • カスタムフックがカスタムフックに依存していく
  • 経験のあるフロントエンドの専任者がいないと設計が破綻していく
  よくあるカスタムフック肥大化の例

  // component.ts
  
  // コンポーネントはカスタムフックによって一見クリーンに見えるが...
  const Component = () => {
      const [selectedDate, someData, actions] = useSomeData()
  
      return <>/*~*/</>
  
  }
  
  ---
  // useSomeData.ts
  
  // ロジックを抽象化したカスタムフック。これが肥大化していく
  
  // キャッシュキー
  const Keys = {
    data: "data"
  }
  
  // フェッチャー
  // OpenApiとかAspidaとか
  const fetchData = (payload) => {
      return fetch(payload)
  }
  
  // カスタムフックの本体
  const useSomeData = () => {
      // 画面上でカレンダーから日付選ぶみたいなの想定
      const [selectedDate,setSelectedDate] = useState<string>()  
      
      // データフェッチに利用する引数を組み立てる (下部のカスタムフック)
      const payload = useSomePayload(selectedDate)
      
      // React Queryでデータフェッチ
      // フェッチャーはパフォーマンス改善のためにメモ化しておく (可読性が低いので個人的に苦手だが...)
      const data = useQuery(Keys.data, useMemo(() => fetchData(payload), [payload]))
  
      // ビジネスロジックとかモデリングとか
      const domainModel = useMemo(()=> {
          return someBusinessLogic(data)
      }, [data])
  
      // コンポーネントに返すコールバック
      const actions = useCallback(() => {
          return {
            updateDate(date:string){
              setSelectedDate(date)
            },
  
            findDataById(id:number){
              return domainModel.find(data => data.id === id)
            }
        
            /* 
              コンポーネントのユースケースによって配列操作などのコールバックも増えていく 
              規模によってはここのコールバックやReact Queryのmutations、キャッシュ破棄系もカスタムフック化される。
              そうなると手に追えない。
              管理方法もきちんとチームで明文化して運用する必要があり、メンテナンスコストが増大する。
              データをhooksに寄せているためコールバックもhooksの中に混ざる。
              状態が更に増えるとパフォーマンス問題も発生する。
              再レンダリングを抑えるためのメモ化も辛くなってくる。
              コードベースが肥大化していく。
              これがhooksベースで設計する時の辛いところ。もっとシンプルにできないか。
             */
        
          },
      },[date, domainModel])
  
      // 利用側には日付、ドメインモデル、コールバックを返す
      return [selectedDate, domainModel, actions] as const
  }
  
  // クライアント状態を合成する
  const useSomePayload = (selectedDate: string) =>
      // 他のサーバーステートとの突き合わせ (カレンダーからの候補日を引いてくるみたいな)
      const candidateDates = useCandidateDatesFromSelectedDate(selectedDate)
  
      // フォームステート
      const {
          form: { getValues },
      } = useParentFormContext()
  
      // URLステート
      const { id } = useRouter().query
  
      // グローバルステート
      const user = useCurrentUser()
  
      const payload = {
          productId: id,
          userId: user.id,
          at: candidateDates ? getValues('at') : undefined,
          /*~*/
      }
  
      return payload
  }
  

React Query運用の参考記事
https://zenn.dev/himorishige/articles/76e903bc5a1aa2

上記の肥大化したカスタムフックを高凝集、かつ小さくまとめるためにはモデリングレイヤが必要。
そこでRecoilの出番となる。

以前書いたコードを参考に
Recoilにデータを寄せれば色々と分離できて捗りそう。
ただキャッシュ系は完璧に隠蔽してしまうとエスケープハッチがなくなるのでオプションで制御できるようにしたい

利用側だけ見るとこんなかんじ？

// Recoilのstateとカスタムフックをtuple返す的な
const [[useTodos],[useTodosMutation]] = atomWithFetcher(fetchTodos)

const Component = () => {
  // RecoilLoadableでローディング系は抽象化する
  const todos = useTodos().getValue()

  const {
    // リフェッチ
    refetch,
    // プリフェッチ
    prefetch,
    // パラメータを指定してリフェッチ
    reload
  } = useTodosMutation()

  return (
    /*~*/
  )
}

リロードのイメージ

// fetcher 
type FetchTodosParams = {
  order: "asc" | "desc"
  name: string
}

const fetchTodos =(FetchTodosParams) => {
  return fetch(url,{ body})
}

const [[,useTodos], [useTodosMutation]] = atomWithFetcher(fetchTodos)

// component
const Component = () => {
  const todos = useTodos().getValue()

  const {
    refetch,
    prefetch,
    reload
  } = useTodosMutation()

  // reloadを呼ぶと指定したパラメータで再実行する
  const toOrderAsc = () => {
    reload({
      order: "asc"
    })
  }

  return (
    /*~*/
  )
}

レスポンスから派生データも作れるのでモデリングしやすい。
クライアント状態の合成、ビジネスロジックもselectorに凝集できる。

// user.ts

type User = {
  id: number,
  firstName:string,
  lastName:string
}

export const [[userState, useUser], [useUserMutation]] = atomWithFetcher(fetchUser({ id: 1 }))

// レスポンスから派生データを作れる
export const userFullNameState = selector({
  key:"userFullNameState"
  get({get}){
    const user = get(userState)

    return getFullName(user)
  }
})
``

^ のフェッチャー部分はエンドポイントによって構造が異なるので何らかの形で抽象化される必要があるが、ここはOpenAPI Generator, Aspida, GraphQLなどのエコシステムに丸投げする

データフローグラフの責務は依存関係の構築なので、薄くつくるに越したことはない。

フェッチャーに関してだが、GraphQLは今回はパス。
その思想は好きだが、大衆に浸透するのにまだ時間がかかりそうなのとエコシステムの発展の問題でチームで運用するには課題が多い。
日本で流行ってきたら考える。

REST APIを考えると、Open API Generator と Aspidaを選択肢に挙げる ※(2023だとOrvalも選択肢に入る)
それぞれ、パラメータの指定の仕方が微妙に違う

• OpenAPI Generator: パスパラメータとクエリパラメータをフラットに指定する
• Aspida: パスパラメータを関数で指定する

// OpenAPI Generator
const user = await api.getUser({
  id: 1,
  name: 'hoge'
})

// Aspida
const user = aspida.users._user_id(1).$get({
  query: {
    name: 'hoge'
  }
})

関数的に考えやすく、合成しやすいのはAspidaかなという感じ。
たとえば、http://hoge.com/users/:user_idのユーザーの画面でRecoilとAspidaを使うとこのようにまとめることができる。

// http://hoge.com/users/3の場合は `3`
const currentUserId = atom<number>({
  key: 'currentUserId',
  // urlのuser_idを引いてくる
  effects: [setUserIdFromUrlEffect]
})

// この例はnext/router
import SingletonRouter from 'next/router'
const setUserIdFromUrlEffect: AtomEffect<number> = ({
  trigger,
  setSelf,
}) => {
  const init = () => {
    const { query, isReady } = SingletonRouter

    if(!isReady){
       return
     }
    
    const userId = Number(query.userId)
    if(Number.isNaN(userId) || userId === 0){
      throw `userId ${userId} is not a number`
    }

    setSelf(userId)
  }

  // "atomへの初回の参照時だけ"というRecoilの方言
  if (trigger === 'get') {
    init()
  }
}

// URLのユーザーのAspidaクライアント
const currentUserApi = selector({
  key: 'currentUserApi',
  get:({get}){
    const userId = get(currentUserId)
    return aspida.users_user_id(userId)
  }
})

// 現在のユーザー
const currentUser = selector({
  key: 'currentUser'
  get:({get}){
    const api = get(currentUserApi)
    return api.$get()
  }
})

// 現在のユーザーの記事
const currentUserArticles = selector({
  key: 'currentUserArticles'
  get:({get}){
    const api = get(currentUserApi)
    return api.articles.$get()
  }
})

// 他にも現在のユーザーの"XXX"というのは`currentUser`から派生できる
// 主体(ドメイン)を明示することで脳内メモリに優しく、オブジェクト指向的に処理をまとめやすい
// 例: 現在のユーザーのWrite Model
const currentUserAction = selector({
  key: 'currentUserAction',
  get: ({getCallback}) => {
    // currentUserApiに依存するノードのキャッシュ破棄
    const invalidate = getCallback(({refresh}) => () => {
      refresh(currentUserApi)
    });
  
    const update = getCallback(({snapshot}) => async (params) => {
      const api = await snapshot.getPromise(currentUserApi)
      api.$put(params).then(invalidate).catch(/*~*/)
    });

    const delete = getCallback(({snapshot}) => async () => {
      const api = await snapshot.getPromise(currentUserApi)
      api.$delete().then(invalidate).catch(/*~*/)
    });

    const hi = getCallback(({snapshot}) => async () => {
      const user = await snapshot.getPromise(currentUser);
      alert(user)
    });

    return {
      update,
      delete,
      hi
    };
  },
});


// コンポーネントはViewに集中できる
const User = () => {
  // Read Model
  const user = useRecoilValue(currentUser)
  const articles = useRecoilValue(currentUserArticles)
  
  /*~*/
}
const UserActions = () => {
  // WriteModel
  const {update, delete, hi} = useRecoilValue(currentUserAction)

  /*~*/
}

この例だと、コンポーネントが依存するのはReadModel/WriteModelのみとなっている。
コンポーネントは各Modelがどこから来て、何に依存しているかに関心を持たず、内部のデータ構造はデータフローグラフに隠蔽されている。
データとそれを描画するステップを明確に分けることで、

• コンポーネント: 宣言的UIの構築とイベントハンドラの割当に集中することができる(技術的な詳細は知らなくていい)
• データ: リファクタリングが容易で変化に強い

リソースに対するドメインモデルの構築という意味では、パスパラメータ(主体)を関数で明示的にできるAspidaはデータフローグラフと相性がいい。
(この構成はZustand, React Queryなどでも同様に出来るが、書き味、リアクティブ性、Suspense、エラーハンドリングなどの制約が異なる。本記事はRecoilを前提として話をすすめる)

ということでReact Queryを意識しつつも、RecoilとAspidaのヘルパーを作ることにする。

Aspidaはリソースごとにメソッドと型がまとめられている。

このリソースをget, post, deleteなどを集約した上位集合としてオブジェクト指向的に扱えるとうれしい。

• 入力: リソース
  • aspida.users
• 出力: 各エンドポイントのメソッド
  • get: aspida.users.$get
  • post: aspida.users.$post

この構造を上記の例で示したようにselectorで表現するヘルパーを作る。
コンポーネントはヘルパーを介してaspidaのapiを叩く。

似たことをReact Hooksで再現している記事
https://zenn.dev/meijin/articles/recommend-aspida-react-hooks

めっちゃ型ついててすごい

RecoilとAspidaのヘルパーはこんなイメージをしている

const [[, useUser],[useUserMutation]] = atomWithAspida({
  // Selectorのgetをコールバックで受け取れるので依存性注入が出来る
  endpoint({ get }) {
    const userId = get(currentUserId)
    return aspida.users.user_id(userId)
  },
})

const User = () => {
  const user = useUser().getValue()

  const {
    refetch,
  } = useUserMutation()

  return (
    /*~*/
  )
}

ユーザー一覧画面とかだとこんなイメージ

データフェッチのキャッシュ管理は中々鬼門なので(post後のリロードなど漏れがち)、post, putなどのタイミングでgetのキャッシュもinvalidateする仕組みがあるとよさそう。

RTK QueryではAutomated Re-fetchingというらしい

React QueryではQueryInvalidationというらしい

• https://tanstack.com/query/v4/docs/guides/invalidations-from-mutations
• https://zenn.dev/maro12/articles/ff825d35e8f776#queryinvalidation

// aspida.usersにはget, postのエンドポイントが定義されている想定

const [[userState, useUsers],[useUsersMutation]] = atomWithAspida({
  endpoint({ get }) {
    return aspida.users
  },
 // GETのクエリパラメータ
 // 初期値にも利用
 // 後述のreloadで状態変化を起こす
  getOption({ get }) {
    return {
      query: {
        page: 1,
        limit: 10
      },
    }
  },
})

const Users = () => {
  const users = useUsers().getValue()

  const {
    // GETのクエリパラメータを更新する
    reload,
    // aspida.users.$postと同じ
    post,
  } = useUsersMutation()

// 検索条件を反映する
 const handleSearch = (form: UserSearchForm) => {
   // reloadの内部でoptionを更新するとともに、APIレスポンスのキャッシュのinvalidateを行う
   // -> 指定したパラメータ(form)でAPIが呼び出されて画面に反映される
   reload(form)
 }

// ユーザーを登録する
const handleCreateUser = (user: User) => {
  // post成功時、内部的にAPIレスポンスのキャッシュをinvalidateする
  // -> 開発者はキャッシュを意識しなくとも、postしたら一覧画面に変更が伝搬する
  post({
    body: user,
    refetchOnSuccess: true
  })
}

  return (
    /*~*/
  )
}

プリフェッチ(+並行リクエスト)

React QueryやGraphQLを始めとするRender As Fetchパターンの設計上の利点としてはデータフェッチと利用するコンポーネントを近く配置するわかりやすさ、管理のしやすさにあると思う。
propsの受け渡しなどを行わず、ほしい時にオンデマンドにとれという考え方。
APIの呼び出しと利用側が近くなることで自然と凝集度が高まる。
これはキャッシュ機構が備わっていることで実現できている。

ただし、RESTの場合のRender As Fetchは、APIが増えてくるとデータフェッチのウォータフォールが発生するという懸念がある。(一画面で呼び出すAPIが10個とかになると明確に問題になる)
コンポーネントがマウントされるまでAPI呼び出しが行われないため、並行リクエストするのにちょっと手間がかかる。
カルーセルとかでも先読みができないとユーザー体験が悪くなる。

APIの改修や増減が発生するフェーズ(立ち上げ期など)では、気付いたらウォーターフォールになっちゃってるというのはありがち。
そして後からパフォーマンス改善で苦しむ。
REST APIでクライアントを実装する場合は設計時に並行リクエストする層を考慮するのは重要な観点。

一方、GraphQLは一発でほしいもの全部取れるのでこういった悩みは減る。
けれどもREST, GraphQLともに複雑になってくるとデータフェッチロジックと呼び出しが分離されることで管理が大変になるという課題はある。
親でリクエストするけれども欲しいフィールドやデータ構造は子の関心となるので、親が子の構造をしっていないと効率的にデータフェッチロジックをかくのが難しく、双方向に依存してしまいメンテナンスコスト増加につながる。

たとえばRelayはフラグメントコロケーションで上記の課題を解決している。

そういう流れでGraphQLのクライアント実装では、データフェッチロジック自体は利用するコンポーネントと近く位置に配置しつつも、親が子のフラグメントを合成して一括でキャッシュの先行読み込みを行う設計が一般的。

いまとなってはデファクトスタンダードになりつつあり、設計の文脈ではこれをコロケーションという
参考:
https://gist.github.com/Quramy/566ea87d0121ceb8cd97ad9d14b63fd8

歴史を知ることで逆説的にデータフェッチの設計はどう在るべきかが見えてくる。

• データフェッチは末端に寄せる
  • データ構造と表示の構造の関数は描画ロジックと近いほど管理しやすい
  • 子の関心は子で閉じるべき
• レスポンスのキャッシュ機能
  • データの共用はキャッシュで透過的にやる
  • キャッシュの先行読み込みをなんらかの形で提供する
  • 任意のタイミングで再リクエスト可能
• データフェッチの発火は遅延束縛する
  • パラメータの組み立てと、発火の関心を分離する
  • 参照時のタイミングで遅延束縛されるようにする

これらに関してRecoilの公式ドキュメントで言及がある。

• Pre-Fetching
• Query Refresh

RecoilとGraphQLの開発元が一緒なだけあって、GraphQLとRESTのいい面を抽象化している^[1]

さて、Prefetch, QueryRefreshを使えばRESTでもコロケーションの設計が可能であることが分かった。
だけどいちいちRequest IDのatom用意するの面倒だし、Recoil Refresherも依存ノードを再帰的に初期化するので扱いづらい。

なのでこれらを隠蔽したatomExternalユーテリティを作った。

atomExternalは引数のgetに非同期処理を渡すとその結果をプロキシしているselectorが返ってくる。
戻り値は通常のselectorのように扱えて、拡張した点としてreset(selector)をするとgetで渡した非同期処理が再実行されるというもの。

// Referenced from
// https://scrapbox.io/study-react/atomRewind
// https://github.com/facebookexperimental/Recoil/issues/571#issuecomment-693364531
// https://recoiljs.org/docs/guides/asynchronous-data-queries#query-refresh

import {
  atom,
  DefaultValue,
  selector,
  GetCallback,
  GetRecoilValue,
  useRecoilValueLoadable,
  useRecoilCallback,
} from 'recoil'

type RawSelectorOptions = {
  get: GetRecoilValue
  getCallback: GetCallback
}

type AtomExternalOptions<T> = {
  key: string
  get: (opts: RawSelectorOptions) => Promise<T>
  dangerouslyAllowMutability?: boolean
}

/** Atom to rerun asynchronous query by reset() */
export function atomExternal<T>(options: AtomExternalOptions<T>) {
  const { key, dangerouslyAllowMutability } = options

  const delegatedQuery = selector({
    key: `${key}/delegatedQuery`,
    get: (opts) => {
      // for cache invalidation
      opts.get(invalidate)

      return options.get(opts)
    },
  })

  const invalidate = atom({
    key: `${key}/invalidate`,
    default: 0,
  })

  const baseAtom = atom({
    key: `${key}/baseAtom`,
    dangerouslyAllowMutability,
    default: selector({
      key: `${options.key}/baseAtom/default`,
      dangerouslyAllowMutability,
      get: ({ get }) => get(delegatedQuery),
    }),
  })

  const state = selector<T>({
    key,
    dangerouslyAllowMutability,
    get: ({ get }) => get(baseAtom),
    set: ({ set }, newValue) => {
      if (newValue instanceof DefaultValue) {
        set(invalidate, (count) => count + 1)
        return
      }

      set(baseAtom, newValue)
    },
  })

  const useExternalQuery = () => useRecoilValueLoadable(state)

  const useExternalQueryMutation = useRecoilCallback(
    ({ snapshot, reset }) =>
      () => ({
        prefetch() {
          snapshot.getLoadable(state)
        },

        refetch() {
          reset(state)
        },
      })
  )

  return [state, useExternalQuery, useExternalQueryMutation] as const
}

const userIdState = atom<number>({
  key: 'userIdState',
})

const [userState, useUser, useUserMutation] = atomExternal({
  key: 'userState',
  get: ({ get }) => {
    const userId = get(userIdState)
    return fetchUser(userId)
  },
})

const User = () => {
  // Suspendしつつ読み込む
  const user = useUser().getValue()

  // 明示的にキャッシュ先読み、リフェッチできる
  const { prefetch, refetch } = useUserMutation()

  return (
    <div>
      <p>{user.name}</p>
      <button onClick={() => refetch()}>refetch user</button>
    </div>
  )
}

このatomExternalをAspidaヘルパーの内部で利用する。

productionでも似たようなの使ってるが、チーム開発でもうまいこと要件を満たしてくれる。
主にデータフェッチ周りでRecoilの辛い部分が隠蔽されるのでオススメ。

もっといいやり方はあるかも。
あとからRecoilのDiscutionsに投稿してみて意見を募りたい。
需要ありそうだったらライブラリ化してもいいかもなぁ。

結構ハマったがRecoil x Aspidaで標題の要件を満たしたコードは出来た。

atomWithAspidaと命名する。

あとからコードサンドボックス作る。

1点だけrefetchOnMountで課題がある。
useEffectでリフェッチをしようとすると、Suspenseを利用した時に、初回マウント時に2回APIコールが走る。

// Recoil x Aspidaヘルパーのhooks部分だけ抜粋

const atomWithAspida = (/*~*/) => {
  /*~*/
  const useAspidaQuery: UseAspidaQuery<E> = (options) => {
    const query = useRecoilValueLoadable(queryState)
    const resetQuery = useResetRecoilState(queryState)

    // コンポーネントのマウント時にリフェッチする
    useEffectOnce(() => {
      if (options?.refetchOnMount) {
        resetQuery()
      }
    })

    return query
  }
}

1. マウント
2. APIコール
3. suspend
4. アンマウント
5. Suspenseが解決される
6. マウント
7. refetchOnMountが評価される
8. APIコール

Suspenseから戻ってきたときも再マウント扱いとなるのでまあそうなるか...
ちょっと後段で考える。

React QueryはstaleTimeで制御してるっぽい。
https://github.com/TanStack/query/issues/3432#issuecomment-1079056894

atomExternalのhooksでstaleTimeを受け取るようにして、selectorのデータフェッチをポーリングする機構を追加した。

export function atomExternal<T, P extends SerializableParam>(
  options: AtomExternalOptions<T, P>
) {
  /*~*/

+  let lastRequestedAt: Date | undefined

  const delegatedQuery = selector({
    key: `${key}/delegatedQuery`,
    get: (opts) => {
      // for cache invalidation
      opts.get(invalidate)
+     lastRequestedAt = new Date()

      return options.get({ ...opts, param: {} as any })
    },
  })

/*~*/
  const useExternalQuery = (options?: { staleTime: number | undefined }) => {
+   const { staleTime = 0 } = options || {}
    const query = useRecoilValueLoadable(state)

+    const tryInvalidateCache = useRecoilCallback(
+      ({ reset }) =>
+        () => {
+          if (lastRequestedAt === undefined || staleTime === 0) {
+            return
+          }
+
+          const now = new Date().getTime()
+          const lastRequestedAtMs = lastRequestedAt.getTime()
+
+          if (now - staleTime > lastRequestedAtMs) {
+            reset(state)
+          }
+        },
+      []
+    )
+
+    useInterval(tryInvalidateCache, staleTime, true)
+
   return query
  }

/*~*/
  return [state, useExternalQuery, useExternalQueryMutation] as const
}

/* eslint-disable @typescript-eslint/no-empty-function */
/* eslint-disable react-hooks/exhaustive-deps */
// Borrowed from https://github.com/Hermanya/use-interval/blob/master/src/index.tsx
import { useEffect, useRef } from 'react'

const noop = () => {}

export function useInterval(
  callback: () => void,
  delay: number | null | false,
  immediate?: boolean
) {
  const savedCallback = useRef(noop)

  // Remember the latest callback.
  useEffect(() => {
    savedCallback.current = callback
  })

  // Execute callback if immediate is set.
  useEffect(() => {
    if (!immediate) return
    if (delay === null || delay === false) return
    savedCallback.current()
  }, [immediate])

  // Set up the interval.
  useEffect(() => {
    if (delay === null || delay === false) return undefined
    const tick = () => savedCallback.current()
    const id = setInterval(tick, delay)
    return () => clearInterval(id)
  }, [delay])
}

export default useInterval

利用側

const User = () => {
  // 1秒毎にポーリングする
  const user = useUser({ staleTime: 1000 }).getValue()

  return <p>{user.name}</p>
}

いい感じに宣言的。

SuspenseでAPIフェッチを済ませるとページングなどで一瞬画面がチラつく課題がある。
これはUXとしては気になると思う。
理想的には切り替えが終わるまでは以前の画面を表示しておきたい。

useStateで管理される状態の場合は以下のようにuseTransitionで解決できる。
https://qiita.com/stin_dev/items/74ae0b002bc2f98b71ce

RecoilもuseRecoilValue_TRANSITION_SUPPORT_UNSTABLEがあるが、まだUnstableなので利用は控えておく。

しかし、Suspenseのチラ付き問題や非同期関連の画面表示はUIと密接に関わるロジックなのでReact Hooksだけで完結できるものではない。
ユースケースも画面要件によって異なる。
さらにはデザインレベルで各パターン毎にどう在るべきかが考慮されている必要がある。

今回はThe five ui statesでいう、以下の5パターンを出し分け出来るデータ構造を考える。

1. 何も登録されていない状態 (Blank state)
2. ロードしている状態 (Loading state)
3. 不完全な状態 (Partial state)
4. エラーが起きている (Error state)
5. 理想的な状態 (Ideal state)

その上で、ローディング中は前回の状態を表示、リクエスト完了時に新しい状態を表示するという機構を作れたらページングのチラつき課題を解決できる

基本的にfive statesはRecoilLoadableのパターンマッチング(loading, hasValue, hasError)で表現できる。

LoadableはResult型のようになっていて非同期処理を抽象化している。

Incremental Loading Example

deeplから翻訳

この例では、複数のレイヤーを持つグラフをレンダリングします。
各レイヤーは、潜在的に高価なデータクエリを持っています。
まだ保留中の各レイヤーのスピナーを使用してすぐにチャートをレンダリングし、そのレイヤーのデータが届くと、チャートを更新して各新規レイヤーを追加します。
もしクエリにエラーがあるレイヤーがあれば、そのレイヤーだけがエラーメッセージを表示し、残りのレイヤーはレンダリングを継続します。

function MyChart({layerQueries}: {layerQueries: Array<RecoilValue<Layer>>}) {
  // layerQueriesがグラフデータフェッチを行う非同期処理
  // waitForNoneは呼び出し側のコンテキストでSelectorの状態をLoadableで返す関数
  // (メモ)useRecoilValueLoadable(layerQueries)との違いはなんだろう？

  const layerLoadables = useRecoilValue(waitForNone(layerQueries));

  return (
    <Chart>
      {layerLoadables.map((layerLoadable, i) => {
        switch (layerLoadable.state) {
          // 非同期処理が解決されている
          case 'hasValue':
            return <Layer key={i} data={layerLoadable.contents} />;

          // 非同期処理でエラーが発生している
          case 'hasError':
            return <LayerErrorBadge key={i} error={layerLoadable.contents} />;

          // リクエスト中
          case 'loading':
            return <LayerWithSpinner key={i} />;
        }
      })}
    </Chart>
  );
}

要はwaitFor*とLoadableを組み合わせればReactのConcurrent Modeと同じ文脈で並列レンダリングを行えるということ。

Loadable.getValueでSuspenseモードで使ってもいいし、上述のLoadable.stateによってViewを切り替えてもいい。

ユーザー体験を最適化するならContainerコンポーネントがLoadable.stateのパターンマッチングでPresenterコンポーネントを切り替えるといったところだろう。

一般的にスピナーを表示するだけなら規模によってはContainer/Presenterを分けずにLoadable.getValueで親にローディングを任せるとかでもいい。

このあたりはLoadableに頼ればユースケースによって実装を切り替えられる。
最初はLoadable.getValueでやっといて後からプロダクトのデザインを最適化したくなったらLoadable.stateに切り替えるとかだと進めやすそう。
データフェッチのロジック自体はatom, selectorに隠蔽されるので、ロジックの後方互換性を保ったままViewを最適化できる。
並列リクエストしたければもっと上のレイヤで(layouts, pages, templates)prefetchすればいい。参照時にデータフェッチが走るのでキャッシュを先読みできる。
さらにLoadable.mapを使えばatom, selectorの値の整形をコンポーネント内で出来る。

const usersQuery = selector(/*~*/)

const users = useRecoilValueLoadable(usersQuery).map(users => {
  return {
    data: users,
    count: users.length
  }
}).getValue()

Loadableすごい。
リアルワールドのユースケースをほぼ網羅している気がする。

Recoilのドキュメントの中では度々backwards-compatible(後方互換性) のワードが出てくるが、これはRecoilのコアな思想であり、分割統治しつつも段階的に設計をスケールさせることを目的としていることを表現しているのだろう。

描画の関心はLoadableの仕組みに乗っかって、データ/ロジックの関心や実装詳細はatom, selectorに寄せるというのが重要な気がする。

ページングにおいて、チラつき回避のために

ローディング中は前回の状態を表示、リクエスト完了時に新しい状態を表示する

を実現できるデータ構造を考えてみよう。

Loadableを拡張してLoadable.getPreviousValue()みたいなのができるとうれしい

利用側はこんな感じで出し分けるみたいな

// ユーザー一覧的なの
const UsersContainer: React.FC = () => {
  const users = useUsers()

  switch (users.state) {
    case 'loading':
      // 前回の状態を表示する
      // 要件によってはスケルトンやスピナーでもよい
      return <Users users={users.getPreviousValue()} />

    case "hasValue":
     return <Users users={users.getValue()} />

    case "hasError":
     return <Error error={users.errorOrThrow} />
  }
}

独自のLoadable型つくれるっぽい？

https://recoiljs.org/docs/api-reference/core/Loadable/#creating-loadables

 // loadable.d.ts
 interface BaseLoadable<T> {
  getValue: () => T;
  toPromise: () => Promise<T>;
  valueOrThrow: () => T;
  errorOrThrow: () => any;
  promiseOrThrow: () => Promise<T>;
  is: (other: Loadable<any>) => boolean;
  map: <S>(map: (from: T) => Loadable<S> | Promise<S> | S) => Loadable<S>;
 }

 interface ValueLoadable<T> extends BaseLoadable<T> {
  state: 'hasValue';
  contents: T;
  valueMaybe: () => T;
  errorMaybe: () => undefined;
  promiseMaybe: () => undefined;
 }

 interface LoadingLoadable<T> extends BaseLoadable<T> {
  state: 'loading';
  contents: Promise<T>;
  valueMaybe: () => undefined;
  errorMaybe: () => undefined;
  promiseMaybe: () => Promise<T>;
 }

 interface ErrorLoadable<T> extends BaseLoadable<T> {
  state: 'hasError';
  contents: any;
  valueMaybe: () => undefined;
  errorMaybe: () => any;
  promiseMaybe: () => undefined;
 }

 export type Loadable<T> =
  | ValueLoadable<T>
  | LoadingLoadable<T>
  | ErrorLoadable<T>;

React QueryはkeepPreviousDataでSuspenseのチラつき問題を解決している。
参考になりそう。

https://tanstack.com/query/v4/docs/guides/paginated-queries#better-paginated-queries-with-keeppreviousdata

前回値の保持ロジックはatomExternalに寄せるとして、
利用側はこんな感じのインタフェースにすると仮定して実装してみる。

const [, useTodos] = atomExternal()

/*~*/

// staleTimeでミリ秒ごとのポーリング間隔を指定できる。
// keepPreviousでリフェッチ中はSuspendされず、前回の値が表示される
// 初回の読み込み時は前回の値が存在しないのでSuspendされる
const todos = useTodos({ staleTime: 1000, keepPrevious: true })

Suspend中に前回の値をフォールバックする実装はこんな感じで出来た

// atomExternal.ts

export type UseExternalQueryOptions = {
  staleTime?: number
+ keepPrevious?: boolean
}

/*~*/

 const useExternalQuery = (options?: UseExternalQueryOptions) => {
    const { staleTime = 0, keepPrevious = false } = options || {}

    const query = useRecoilValueLoadable(state)
+   const prevQuery = usePrevious(query)

+    const resultLoadable = useMemo(() => {
+      // return previous value while loading
+      if (
+        keepPrevious &&
+        prevQuery !== undefined &&
+        query.state === 'loading'
+      ) {
+        return prevQuery
+      }
+
+      return query
+    }, [keepPrevious, prevQuery, query])

  /*~*/

-    return query
+    return resultLoadable
  }

export function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T>()

  useEffect(() => {
    ref.current = value
  }, [value])

  return ref.current
}

React QueryからReactに非依存な部分を切り出したTanstack Queryのプロジェクトが進行しているらしい。キャッシュ周りも切り出されてるんじゃないかな？（みてないけど）

https://twitter.com/tannerlinsley/status/1549786557174804480

atomExternalの抽象化を見直しても良いかも。

1. Recoilでシンプルに非同期処理とReact Concurrentを扱うためのミニマムなユーティリティ (今回つくったatomExternal)
2. Tanstack Query のRecoilラッパー

今回は前者にフォーカスする。
Recoil x Aspidaの連携ではそれで十分なはず。

後者はまた別の路線で、ジェネリックなので実装量と求められる知識量は増えそう。
シンプルとは言い難いが、抽象化の深さはあるのでニッチな部分もカバーしてるはず。
興味が湧いたら別のスクラップで深堀りする。

atomExternalという名前がしっくりこないので別の名前にしたい

JotaiはTanstack Queryのintegrationを提供している。

https://jotai.org/docs/integrations/query

コミュニティの大きさがそのまま質につながるのでその点はRecoilよりもJotaiが優れている。
わざわざ車輪の再発明をする必要もない。

Recoilじゃないとできないことは限られているのでintegration系とかデータフローグラフを設計に取り込みたいだけなら最初からJotaiを採用する方がメリット大きそう。
そのうちちゃんと比較するか。

atomWithAspidaでRESTのエンドポイント感の依存管理を分離しつつorganisms単位で分割統治する草案
コンポーネントの単位はatomic designの概念で書いているが、イメージしやすいようにそうしているだけで、atomic designを強制しているわけではない。

• TODO
  • 動作するサンドボックスをつくる
  • テストコードのサンプルをつくる
    • 単体テスト
    • 結合テスト

// 機能単位(organisms | features)で関心を分割するディレクトリ構成にする
pages/users/users.page.tsx
organisms/users/users.root.tsx //これが分割統治の親
organisms/users/users.list.tsx // 一覧 (Read Stack)
organisms/users/users.form.tsx // フォーム (Write Stack)

export const UsersPage: React.FC = () => {

  // pagesの処理

  return (
    <UserRoot/>
  )
}

// atomWithAspidaのオプション内のコールバックに渡ってくる`get`はRecoilのgetと同じ
// ここで検索条件のatomやURLステートなどと依存グラフを構築できる
// queryのusersStateはatom<ReturnType<typeof aspida.api.v1.users.$get()>>
// このusersStateから派生データ(例えばユースケースごとのPresentation Model)を作ることが出来る

export const {
  query: [usersState, useUsers],
  mutation: [useUsersMutation],
} = atomWithAspida({
  entry({ get }) {
    return aspida.api.v1.users
  },
  option({ get }, current) {
    return {
      query: {
          page:1,
          limit: 5
      },
    }
  },
})

export const UsersRoot: React.FC = () => {
  return (
    <>
      <h2>Users</h2>
      <AppSpinnerSuspense>
        <UsersList />
        <UsersForm
          formProps={{
            defaultValues: { name: '', description: '', disabled: false },
          }}
        />
      </AppSpinnerSuspense>
    </>
  )
}

import { useUsers } from '@/features/users/users.root'

export const UsersList: React.FC = () => {
  const users = useUsers()

  if (users.state === 'hasError') {
    return <ErrorDump error={users.errorMaybe()} />
  }

  return <List users={users.getValue()} />
}

const List: React.FC<{
  users: Users[]
}> = ({ users }) => {
  return (
    <>
      /* ユーザー一覧 */
      {users.map((user) => (
        <Accordion key={user.id} allowToggle>
          <AccordionItem>
            {({ isExpanded }) => (
              <>
                <h2>
                  <AccordionButton>
                    <Box flex='1' textAlign='left'>
                      {user.name}
                      {user.disabled && (
                        <Badge colorScheme='red' ml={2}>
                          無効中
                        </Badge>
                      )}
                    </Box>
                    <AccordionIcon />
                  </AccordionButton>
                </h2>
                /* ユーザー単体(省略) */
                {isExpanded ? <UserItem subjectId={user.id} /> : null}
              </>
            )}
          </AccordionItem>
        </Accordion>
      ))}
    </>
  )
}

type Form = {
  name: string
  description: string
  disabled: boolean
}

type UserFormProps = {
  // react-hook-form想定
  formProps: UseFormProps<Form, any>
}

// Context使わないならこのへんは不要
const useUserForm = () => useFormContext<Form>()
const Wrapper: React.FC<UserFormProps> = ({ formProps }) => {
  const form = useForm<Form>(formProps)

  return (
    <FormProvider {...form}>
      <UserForm />
    </FormProvider>
  )
}

const UserForm: React.FC = () => {
  const form = useUserForm()
  
  // `refetchOnSuccess`を指定するとatomWithApidaが内部でRead Stackへ更新を通知する
  const { postApi } = useUsersMutation({ refetchOnSuccess: true })

  return (
    <UserFormInput
      formStatus={
        <FormStatus
          formStatus={{
            success: postApi.success,
            pending: postApi.pending,
            error: postApi.error,
          }}
        />
      }
      onValid={(data) => {
        postApi.call({ body: data }).then(() => {
          form.reset()
        })
      }}
      onInValid={(err, evt) => {
        console.log({ err, evt })
      }}

      /* 楽観的更新したいならoptimisticDataを指定する ~
      onValid={(data) => {
        postApi.call({ body: data }, {optimisticData: (current) => [...current, data]}).then(() => {
          form.reset()
        })
      }}
      */
    />
  )
}

const UserFormInput: React.FC<{
  formStatus: React.ReactNode
  onValid: SubmitHandler<Form>
  onInValid?: SubmitErrorHandler<Form> | undefined
}> = (props) => {
  const { onValid, onInValid } = props

  const form = useUserForm()

  return (
    <form onSubmit={form.handleSubmit(onValid, onInValid)}>
      <>
        <div>
          <InputText
            label='name'
            placeholder='name'
            {...form.register('name')}
          />
        </div>
        <div>
          <InputText
            label='description'
            placeholder='description'
            {...form.register('name')}
          />
        </div>
        <div>
          <Checkbox {...form.register('disabled')}>disabled</Checkbox>
        </div>

        {FormStatus}
        <br />

        <div>
          <Button type='submit'>CREATE</Button>
        </div>
      </>
    </form>
  )
}

export { Wrapper as UserForm }

一ヶ月かけてアンラーニングしながら頭をからっぽにした状態で改めてこのスクラップ全体を見つつ振り返る。

思想

思想自体は違和感ない。
今でもとりあえず機能要件を満たすことを考えるならtanstack queryで十分だと思っている。
最初はそれでミニマムに作ることを目指すのがいい。
ただREST APIが複数登場したり、クライアントでform state, ui state, global stateなどと絡んで来るとやっぱり辛くなる。
このスクラップはそういった複雑GUIのデータフェッチ設計をシンプルにすることを目指した。

複雑GUIへの課題

https://zenn.dev/link/comments/238de1fb4a497d

コンテキストは上記のコメントにも記載したが、プロダクトのグロースに応じてGUIが複雑化していく中で、REST API + tanstack queryのみだと依存関係の追跡やステートの分断, モデリングのレイヤが不足する課題がある。

他にもいくつか目指したところ

• React Hooksのdeps, ServerStateのキャッシュをデータフローグラフに任せる
• 楽観的UIの実現
• コンポーネント設計の方針を立てる
  • 機能(関心)単位、リソース単位で分割統治してスケールする設計
  • 改修時に追加/変更/削除しやすい、ステートとドメインを扱う箇所が局所化された設計
  • 親と末端でリアクティブとパフォーマンスを両立

アプローチ

• RecoilとAspidaをベースにREST APIをリソース単位で抽象化をした
  • ex. aspida.api.usersに対するget, post, put, patch, deleteなどのエンドポイントをusersというリソースとして扱う
• リソースを境界線としてorganisms単位で分割統治する
  • こちらはこのコメントに記載 https://zenn.dev/link/comments/c762aa47242900
  • API呼び出し、キャッシュ管理、派生データなどをRecoilのデータフローグラフで表現した
  • 各コンポーネントはgetCallback, hooksを利用することでusers.getApi, users.postApiのように扱える
• 複雑かつボイラープレートな状態管理/CRUDを隠蔽する
  • 楽観的UI、キャッシュ破棄を直感的に行えるように
  • CRUD的なリソース操作を定義しなくてよい
    • コード量が減ってリソース操作/ユースケース組み立ての認知コストが下がる
• データの実体はRecoilが持つ
  • コンポーネントツリーのネストが深くても同じ状態を共有できる
  • 末端のViewコンポーネントは派生セレクターでレスポンスの整形/ユースケースの組み立てに集中でき、影響範囲も子に閉じることができる

// aspida.api.usersの抽象化

const {
  query: [usersState, useUsers],
  mutation: [useUsersMutation],
} = atomWithAspida({
  entry({ get }) {
    return aspida.api.users
  },
  option({ get }, currentOption) {
    return {
      query: currentOption.query,
    }
  },
})

const UsersList = () => {
  // aspida.api.users.$getをRender As You FetchしながらSuspendできる
  const users = useUsers().getValue()

  return (/*~*/)
}

const UserForm = () => {
  const post = useUsersMutation()

  // 楽観的UI, postのレスポンスを待つことなくgetのstateが書き変えられる
  post(body, {optimisticData: /*~*/})

  // キャッシュ破棄, post成功時に自動的にリフェッチされる
  post(body, {refetchOnSucess:true})
}

上述の複雑GUIの課題はREST特有となっていて、GraphQLだと別のレイヤでこれらの複雑性が緩和されてクライアントのロジックが減る。（GraphQLのスキーマがリソース/ユースケースの両方を兼ねている）
fragmentが使えたりApolloだとキャッシュの正規化機構が搭載されてたりするのでatomWithAspidaのような設計はそもそもいらないと思っている。(一歩間違えるとオレオレフレームワークとなるので)

GraphQLのServerState管理で迷ったら下記記事のようにtanstack query使っとけば間違いないんじゃないかな。次点でApolloとかurql。
https://zenn.dev/mitsuruokura/articles/7372ae1be233c4

Atomic State Managementの哲学や導入するモチベーションを改めて整理する

• 状態グラフとReactのレンダリングの整合性を保ったまま一貫性のあるレンダリングができる
• その上で再描画をコントロールできる
• Form, URL, Globalなどのブラウザ上の各種ステートやライブラリ間を疎結合に連携できる
• ステートを集約させるプレゼンテーションロジックをコンポーネント上ではなく状態グラフに分離できる

自分が魅力だと思ったのはこのあたりか。
特にプレゼンテーションロジックの依存関係の解決を状態グラフに分離できるのは嬉しい。
非同期を含む場合もSuspenseによって同期的に処理できるためメンタルモデルとの乖離が減る。

Recoil/Jotaiは、状態グラフの構築（宣言、同期、破棄等のライフサイクル)や派生データ構築)だけに責務をもって薄くつかいたい。

テストをどう書くかは意見が様々だが、これはAtomic State Managementに何を求めているかによって変わると思われる。

自分がAtomic State Managementに求めているのはレンダリングに一貫性のある状態伝搬だ。
そのためAtom, Selector自体をテストすることはあまり考えてない。
それはライブラリをテストしているのと同義だと思っていて意味のあるテストだとは思えないため。

だからSelectorはロジックを書く場所というよりはただのsubscriberとして捉えている。
入力をgetだけして、エンティティの知識を扱うようなビジネスロジックは純粋関数に切り出す。
その純粋関数をテストする。

イメージは下記である。
https://scrapbox.io/koushisa/Recoilのデータフェッチとドメイン抽象例

色々と発散したので収束させる。

現時点(2022年)のReactにおいては、以下のような考え方がベストプラクティスに沿った犠牲的アーキテクチャの構築に役立つのではなかろうか。

• Reactはレンダリング(=UIの構築)だけ任せる
  • プレゼンテーション層の分離はカスタムフックかAtomic State Managementに任せる
• 状態を扱う技術詳細やインタフェースはその時代や要件に合わせ特化したライブラリに任せる
  • データフェッチならtanstack query
  • フォームならreact-hook-form
• ライブラリ間の統合や整合性が重要となった場合にAtomic State Managementに任せる
  • 状態グラフを構築する
• 状態のインタフェースは極力action, set, getのみに絞る
  • 特にactionでステートマシンを作るのはカプセル化のために重要で、ここはReduxの思想を知るとイメージしやすい
  • 副作用や集約の関心はコンポーネントから逃がす
• APIは「叩く」のではなく「叩かれる」

細かい思想はScrapboxに詳細を書いた。

https://scrapbox.io/koushisa/Async_Selector:_APIは「叩く」のではなく「叩かれる」もの

https://scrapbox.io/koushisa/宣言的UIにおけるドメインの単位はコンポーネント

WEBフロントエンドは3年もたてばパラダイムごと変わるので、価値を見つめ直して作り直すほうがコスパが良いと思われる。

特に2023はRSCだったりNext 13のappDirなどで新たなパラダイムが生まれようとしている。
ここは引き続き観測しつづけたい。