Enhance query param types for Next.js

[nayukata]

Types of changes

• Bug fixes
• Features
  • resolves クエリパラメータの型安全性を拡張したい #189
• Maintenance
• Documentation

resolves Enhance query parameter type safety #XXX

Changes

Enhanced query parameter type safety by extending the type system to handle various parameter types and providing type conversion utilities.
クエリパラメータの型安全性を向上させ、様々な型のパラメータを扱えるように拡張し、型変換ユーティリティを提供

Additional context

[ja]
クエリパラメータの型安全性を向上させる機能を追加しました

1. buildSuffix関数の型拡張

   • 従来のRecord<string, string>から、より柔軟な型定義に拡張
   • number、boolean、配列型（string[]、number[]、boolean[]）をサポート
   • 全ての値は自動的に適切な文字列形式に変換

2. 型変換ユーティリティの追加

   • ToNextSearchParams型を追加し、Next.jsのsearchParamsとの型互換性を確保
   • 入力の型を自動的にNext.js互換の型（stringまたはstring[]）に変換

使用例：

// 入力の型定義
export type Query = {
  postId: number;  
  isActive: boolean; 
  categoryIds: number[]; 
};

// searchParamsの型として使用
type PageProps = {
  searchParams: ToNextSearchParams<Query>;
}; // => { postId: string; isActive: string; categoryIds: string[]; }

[en]
Added features to enhance query parameter type safety

1. Extended buildSuffix function types

   • Expanded from Record<string, string> to support more flexible type definitions
   • Added support for number, boolean, and array types (string[], number[], boolean[])
   • All values are automatically converted to appropriate string formats

2. Added type conversion utilities

   • Introduced ToNextSearchParams type to ensure compatibility with Next.js searchParams
   • Automatically converts input types to Next.js compatible types (string or string[])

Usage example:

// Input type definition
export type Query = {
  postId: number; 
  isActive: boolean;
  categoryIds: number[];
};

// Use as searchParams type
type PageProps = {
  searchParams: ToNextSearchParams<Query>;
};  // => { postId: string; isActive: string; categoryIds: string[]; }

[solufa]

早速のPR非常に助かります

Issue時点で気付けなかったのですが、ToNextSearchParamsは本体機能とは関係ない範囲で改善余地が残されてしまうため削除して欲しいです

今思いつくケースだと

type Query =
  | {
      kind: 'aa';
      aa: 1;
    }
  | {
      kind: 'bb';
      bb: 2;
    };

const fn = (query: ToNextSearchParams<Query>) => {
  query.kind // string
}

が期待通りの動作をしないためIssueが発生する可能性があります
しかしこのような要望に対応するコストはpathpidaが負うべきものではないと判断しました

[nayukata]

@solufa
レビューありがとうございます！
確かに、複雑なQueryになると期待通りに動作しなくなりますね。
ToNextSearchParams を削除して、本来の目的である buildSuffix の型拡張のみにします。

[solufa]

LGTM