safe-action-advanced

next-safe-action の高度な機能

概要

機能	ユースケース
引数のバインド	.bind() を使ってアクションに追加の引数（リソース ID など）を渡します
メタデータ	ミドルウェアで使用する型付きメタデータをアクションに付与します
フレームワークエラー	アクション内で redirect、notFound、forbidden、unauthorized を処理します
型ユーティリティ	アクション関数とミドルウェアから型を推論します

サーバーレベルのアクションコールバック

.action() の第 2 引数では、サーバー上で（クライアント側のフックではなく）実行されるコールバックを指定できます。

export const createPost = authActionClient
  .inputSchema(schema)
  .action(
    async ({ parsedInput, ctx }) => {
      const post = await db.post.create(parsedInput);
      return post;
    },
    {
      onSuccess: async ({ data, parsedInput, ctx, metadata, clientInput }) => {
        // Runs on the server after successful execution
        await invalidateCache("posts");
      },
      onError: async ({ error, metadata, ctx, clientInput, bindArgsClientInputs }) => {
        // error: { serverError?, validationErrors? }
        await logError(error);
      },
      onSettled: async ({ result }) => {
        // Always runs
        await recordMetrics(result);
      },
      onNavigation: async ({ navigationKind }) => {
        // Runs when a framework error (redirect, notFound, etc.) occurs
        console.log("Navigation:", navigationKind);
      },
    }
  );

これらはフックのコールバック（useAction({ onSuccess })）とは別のものです。サーバーコールバックは Node.js ランタイムで実行され、フックのコールバックはブラウザーで実行されます。

throwServerError

サーバーエラーを result.serverError として返す代わりに、再スローします。

export const myAction = actionClient
  .inputSchema(schema)
  .action(serverCodeFn, {
    throwServerError: true,
    // The handled server error (return of handleServerError) is thrown
  });

これを returnServerError() と混同しないでください。throwServerError は、handleServerError で処理された後のエラーを返すのではなく、スローします。一方、returnServerError(payload) は handleServerError を完全に迂回して、型付きの予期されるエラーを result.serverError として返します（safe-action-client スキルのエラー処理に関するドキュメントを参照）。