useSearchParams

		// schemas.ts
import { z } from "zod";
// Version 3.24.0+
 
export const productSearchSchema = z.object({
	page: z.coerce.number().default(1),
	filter: z.string().default(""),
	sort: z.enum(["newest", "oldest", "price"]).default("newest")
});
	

		<script lang="ts">
import { useSearchParams } from "runed/kit";
import { productSearchSchema } from './schemas';
 
const params = useSearchParams(productSearchSchema);
// 파라미터에 직접 액세스
const page = $derived(params.page); // number (기본값 1)
const sort = $derived(params.sort); // 'newest' | 'oldest' | 'price'
 
// 파라미터 직접 업데이트
params.page = 2; // URL을 ?page=2로 업데이트
// URL을 ?page=3&sort=oldest로 업데이트
params.update({ page: 3, sort: 'oldest' });
// 모든 파라미터를 기본값으로 재설정
params.reset();
// 모든 현재 파라미터 값을 포함하는 URLSearchParams 객체 반환
params.toURLSearchParams();
/**
 * URLSearchParams 객체의 변경을 감시할 수 있습니다
 * 예를 들어:
 * watch(() => params.toURLSearchParams(), () => {
 *   // URLSearchParams 객체가 변경될 때마다 수행할 작업
 * })
 */
</script>
 
<-- 입력 필드에 바인딩하기 좋습니다 -->
<input type="text" bind:value={params.filter} />
	

		import { validateSearchParams } from "runed/kit";
import { productSearchSchema } from "./schemas";
 
export const load = ({ url, fetch }) => {
	// URLSearchParams 객체로 검증된 검색 파라미터 가져오기
	// useSearchParams에서 사용자 정의 compressedParamName을 사용하는 경우 여기에도 제공하세요:
	const { searchParams } = validateSearchParams(url, productSearchSchema);
 
	// fetch와 함께 URLSearchParams 직접 사용
	const response = await fetch(`/api/products?${searchParams.toString()}`);
	return {
		products: await response.json()
	};
};
	

		import { z } from "zod";
 
const productSearchSchema = z.object({
	page: z.number().default(1),
	filter: z.string().default(""),
	sort: z.enum(["newest", "oldest", "price"]).default("newest")
});
const params = useSearchParams(productSearchSchema);
// 파라미터에 직접 액세스
const page = $derived(params.page); // number (기본값 1)
const sort = $derived(params.sort); // 'newest' | 'oldest' | 'price'
	

		// URL에 기본값 표시, 300ms 디바운싱,
// 새로운 히스토리 항목 생성 안 함, 파라미터 압축
const params = useSearchParams(schema, {
  showDefaults: true,
  debounce: 300,
  pushHistory: false,
  compress: true,
  compressedParamName: '_compressed' // 충돌을 피하기 위한 사용자 정의 이름
});
// 입력 필드에 바인딩하기 좋습니다 (히스토리를 복잡하게 하지 않고 URL 업데이트)
<input type="text" bind:value={params.search} />
// 결과 URL은 다음과 같습니다: /?_compressed=N4IgDgTg9g...
	

		import * as v from "valibot";
const productSearchSchema = v.object({
	page: v.optional(v.fallback(v.number(), 1), 1),
	filter: v.optional(v.fallback(v.string(), ""), ""),
	sort: v.optional(v.fallback(v.picklist(["newest", "oldest", "price"]), "newest"), "newest")
});
const params = useSearchParams(productSearchSchema);
	

		import { type } from "arktype";
const productSearchSchema = type({
	page: "number = 1",
	filter: 'string = ""',
	sort: '"newest" | "oldest" | "price" = "newest"'
});
const params = useSearchParams(productSearchSchema);
	

		const productSearchSchema = createSearchParamsSchema({
	// 기본값이 있는 기본 타입
	page: { type: "number", default: 1 },
	filter: { type: "string", default: "" },
	sort: { type: "string", default: "newest" },
 
	// 특정 요소 타입을 가진 배열 타입
	tags: {
		type: "array",
		default: ["new"],
		arrayType: "" // string[] 타입 지정
	},
 
	// 특정 형태를 가진 객체 타입
	config: {
		type: "object",
		default: { theme: "light" },
		objectType: { theme: "" } // { theme: string } 타입 지정
	}
});
	

		import { validateSearchParams } from "runed/kit";
import { productSchema } from "./schemas";
 
export const load = ({ url, fetch }) => {
	// URLSearchParams 객체로 검증된 검색 파라미터 가져오기
	// useSearchParams에서 사용자 정의 compressedParamName을 사용하는 경우 여기에도 제공하세요:
	const { searchParams } = validateSearchParams(url, productSchema, {
		compressedParamName: "_compressed"
	});
 
	// fetch와 함께 URLSearchParams 직접 사용
	const response = await fetch(`/api/products?${searchParams.toString()}`);
	return {
		products: await response.json()
	};
};
	

		<script>
	const params = useSearchParams(schema);
 
	// 이들은 URL 업데이트를 트리거합니다
	params.page = 2;
	params.filter = "active";
	params.config = { theme: "dark", size: "large" };
	params.items = [...params.items, newItem];
</script>
	

		<script>
	const params = useSearchParams(schema);
 
	// 이들은 URL 업데이트를 트리거하지 않습니다
	params.config.theme = "dark"; // 중첩된 객체 속성
	params.items.push(newItem); // 배열 메서드
	params.items[0].name = "updated"; // 배열 항목 속성
	delete params.config.oldProp; // 속성 삭제
</script>
	

		interface SearchParamsOptions {
	/**
	 * true일 때, 기본값으로 설정된 파라미터가 URL에 표시됩니다.
	 * false일 때, 기본값을 가진 파라미터는 URL에서 생략됩니다.
	 * @default false
	 */
	showDefaults?: boolean;
 
	/**
	 * 파라미터가 변경될 때 URL 업데이트를 지연시킬 밀리초 수.
	 * 값이 빠르게 변경될 때(예: 입력 필드에 타이핑 중) 브라우저 히스토리가 복잡해지는 것을 방지하는 데 도움이 됩니다.
	 * @default 0 (디바운싱 없음)
	 */
	debounce?: number;
 
	/**
	 * URL 업데이트가 새로운 브라우저 히스토리 항목을 생성할지 제어합니다.
	 * true(기본값)일 때, 각 업데이트가 브라우저 히스토리에 새 항목을 추가합니다.
	 * false일 때, 업데이트는 새 히스토리 항목을 생성하지 않고 현재 URL을 교체합니다.
	 * @default true
	 */
	pushHistory?: boolean;
 
	/**
	 * 모든 파라미터에 대해 lz-string 압축을 활성화합니다.
	 * true일 때, 모든 파라미터가 URL의 단일 파라미터로 압축됩니다.
	 * 이는 URL 길이를 줄이고 기본적인 파라미터 난독화를 제공하는 데 도움이 됩니다.
	 * @default false
	 */
	compress?: boolean;
 
	/**
	 * 압축이 활성화될 때 압축된 데이터를 저장하는 데 사용되는 파라미터의 이름.
	 * 스키마 파라미터와의 충돌을 피하기 위해 이를 사용자 정의할 수 있습니다.
	 * 예를 들어, 스키마가 이미 '_data'를 사용하는 경우 '_compressed' 또는 다른 고유한 이름을 사용할 수 있습니다.
	 * @default '_data'
	 */
	compressedParamName?: string;
 
	/**
	 * 파라미터가 변경될 때 URL을 업데이트할지 제어합니다.
	 * true(기본값)일 때, 파라미터 변경이 URL을 업데이트합니다.
	 * false일 때, 파라미터는 URL을 업데이트하지 않고 메모리에만 저장됩니다.
	 * 참고: false일 때 compress 옵션은 무시됩니다.
	 * @default true
	 */
	updateURL?: boolean;
}
 
type ReturnUseSearchParams<Schema extends StandardSchemaV1> = {
	[key: string]: any; // 타입이 지정된 반응형 파라미터
	/**
	 * 여러 파라미터를 한 번에 업데이트
	 *
	 * 하나의 URL 업데이트 또는 하나의 인메모리 저장소 업데이트만 트리거하기 때문에
	 * 여러 파라미터를 개별적으로 설정하는 것보다 효율적입니다.
	 *
	 * @param values 업데이트할 파라미터 키-값 쌍을 포함하는 객체.
	 *  예: params.update({ page: 1, sort: 'newest' })
	 */
	update(values: Partial<StandardSchemaV1.InferOutput<Schema>>): void;
	/**
	 * 모든 파라미터를 기본값으로 재설정
	 *
	 * 이 메서드는 모든 현재 URL 파라미터 또는 인메모리 파라미터를 제거하고
	 * 선택적으로 기본값이 아닌 값을 가진 파라미터를 기본값으로 되돌립니다.
	 *
	 * @param showDefaults 재설정 후 URL 또는 인메모리 저장소에 기본값을 표시할지 여부.
	 * 제공되지 않으면 인스턴스의 showDefaults 옵션을 사용합니다.
	 */
	reset(showDefaults?: boolean): void;
	/**
	 * 현재 스키마 파라미터를 URLSearchParams 객체로 변환
	 * URL에 있는지 여부에 관계없이 스키마에 정의된 모든 값이 포함됩니다
	 * @returns 모든 현재 파라미터 값을 포함하는 URLSearchParams 객체
	 */
	toURLSearchParams(): URLSearchParams;
};
 
/**
 * createSearchParamsSchema를 위한 스키마 타입
 * 배열과 객체에 대해 더 정확한 타입을 지정할 수 있습니다
 */
type SchemaTypeConfig<ArrayType = unknown, ObjectType = unknown> =
	| { type: "string"; default?: string }
	| { type: "number"; default?: number }
	| { type: "boolean"; default?: boolean }
	| { type: "array"; default?: ArrayType[]; arrayType?: ArrayType }
	| { type: "object"; default?: ObjectType; objectType?: ObjectType };