Svelte入門：リファレンス @sveltejs/kit -Vol.17-

よっしー

こんにちは。よっしーです(^^)

今日は、SvelteKitのリファレンスについて解説しています。

背景
@sveltejs/kit
おわりに

背景

SvelteKitのリファレンスについて調査する機会がありましたので、その時の内容を備忘として記事に残しました。

@sveltejs/kit

ServerLoad

PageServerLoadとLayoutServerLoadの汎用形式です。直接ServerLoadを使用するのではなく、（生成された型を参照して）./$typesからそれらをインポートするべきです。

type ServerLoad
	Params extends Partial<Record<string, string>> = Partial
		Record<string, string>
	>,
	ParentData extends Record<string, any> = Record
		string,
		any
	>,
	OutputData extends Record<string, any> | void = Record
		string,
		any
	> | void,
	RouteId extends string | null = string | null
> = (
	event: ServerLoadEvent<Params, ParentData, RouteId>
) => MaybePromise<OutputData>;

解説

このコードは、SvelteKitフレームワークでのサーバーロード関数の型定義に関するものです。

ServerLoadは、PageServerLoadとLayoutServerLoadの基本となる汎用型です。これは直接使用するのではなく、SvelteKitが自動生成する型定義ファイル./$typesからPageServerLoadまたはLayoutServerLoadをインポートして使用することが推奨されています。

型定義の詳細：

Params: ルートパラメータの型で、文字列のキーと文字列の値を持つオブジェクトの部分集合
ParentData: 親コンポーネントから受け取るデータの型
OutputData: この関数が返すデータの型（オブジェクトまたはvoid）
RouteId: ルートの識別子の型（文字列またはnull）

この型は、ServerLoadEventオブジェクトを受け取り、MaybePromise<OutputData>（非同期または同期的な出力データ）を返す関数を表しています。

SvelteKitでは、このロード関数はルートが訪問されたときにサーバーサイドでデータを取得または処理するために使用されます。

ServerLoadEvent

interface ServerLoadEvent
	Params extends Partial<Record<string, string>> = Partial
		Record<string, string>
	>,
	ParentData extends Record<string, any> = Record
		string,
		any
	>,
	RouteId extends string | null = string | null
> extends RequestEvent<Params, RouteId> {…}

parent: () => Promise<ParentData>;

await parent()は親の+layout.server.jsのload関数からのデータを返します。 await parent()を使用する際に意図しないウォーターフォール（連続的な処理の遅延）を導入しないよう注意してください。例えば、親データを返される出力に単に統合したいだけなら、他のデータをフェッチした後に呼び出してください。

depends: (...deps: string[]) => void;

この関数は、load関数が一つ以上のURLまたはカスタム識別子に依存していることを宣言します。その後、これらはinvalidate()と共に使用してloadを再実行させることができます。ほとんどの場合、fetchがあなたの代わりにdependsを呼び出すため、これは必要ありません — これはfetchをバイパスするカスタムAPIクライアントを使用している場合にのみ必要です。 URLは絶対パスでも読み込まれるページからの相対パスでもよく、エンコードされている必要があります。カスタム識別子はURI仕様に準拠するために、1つ以上の小文字の後にコロンが続く接頭辞を持つ必要があります。以下の例は、カスタム識別子への依存関係を登録するためにdependsを使用する方法を示しており、ボタンクリック後にinvalidateされ、load関数が再実行されます。

src/routes/+page.server.js

let count = 0;
export async function load({ depends }) {
	depends('increase:count');

	return { count: count++ };
}

src/routes/+page.svelte

<script>
	import { invalidate } from '$app/navigation';

	let { data } = $props();

	const increase = async () => {
		await invalidate('increase:count');
	}
</script>

<p>{data.count}<p>
<button on:click={increase}>Increase Count</button>

untrack: <T>(fn: () => T) => T;

この関数を使用して、コールバック内で同期的に呼び出されるすべてのものについて依存関係の追跡をオプトアウトします。例：

src/routes/+page.server.js

export async function load({ untrack, url }) {

	// url.pathnameの追跡をオプトアウトして、パス変更が再実行をトリガーしないようにする
	if (untrack(() => url.pathname === '/')) {
		return { message: 'Welcome!' };
	}
}

解説

ServerLoadEventインターフェースはRequestEventを拡張し、サーバーサイドのload関数で使用される特別なイベントオブジェクトです。以下の主要なメソッドが含まれています：

parent():
- 親レイアウト（+layout.server.js）のload関数から返されたデータを非同期的に取得します。
- パフォーマンスに関する注意点として、不必要な処理の連鎖（ウォーターフォール）を避けるため、他のデータ取得が完了した後に呼び出すべきケースがあります。
depends(...deps: string[]):
- load関数が特定のURLやカスタム識別子に依存していることを宣言します。
- 通常はfetchが自動的に依存関係を登録するため、カスタムAPIクライアントを使用する場合のみ必要です。
- これにより、invalidate()を使って特定の依存関係が変更された際にload関数を再実行できます。
- カスタム識別子は小文字+コロンで始まる必要があります（例: increase:count）。
untrack(fn: () => T):
- 特定のコードブロックで依存関係の追跡を無効にします。
- 例えば、URLのパス変更がload関数の再実行をトリガーしないようにするために使用できます。

この機能セットは、SvelteKitアプリケーションでのデータ取得とリアクティブな更新を効率的に管理するために設計されています。特に、依存関係の宣言と無効化の仕組みは、必要なときだけデータを再取得するための洗練された方法を提供しています。

Snapshot

Snapshot ページまたはレイアウトコンポーネントからエクスポートされる export const snapshot の型。

interface Snapshot<T = any> {…}

capture: () => T;

restore: (snapshot: T) => void;

解説

Snapshotインターフェースは、ページやレイアウトコンポーネントからexport const snapshotとして外部に公開される型定義です。このインターフェースには主に2つのメソッドがあります：

capture: () => T:
- コンポーネントの現在の状態をキャプチャして保存するためのメソッドです。
- 任意の型Tのデータを返します。このデータはコンポーネントの状態を表現します。
- ナビゲーション時やページ遷移前に呼び出され、その時点のコンポーネントの状態を保存します。
restore: (snapshot: T) => void:
- 以前にcapture()メソッドで保存された状態をコンポーネントに復元するためのメソッドです。
- T型のスナップショットデータを受け取り、コンポーネントの状態をそのデータに基づいて復元します。
- ブラウザの「戻る」「進む」ボタンでナビゲーションした時などに、以前の状態を復元するために使用されます。