soseki 0.0.4 → 0.0.6

package/src/core/_match-route-path.ts

@@ -1,37 +1,43 @@
-import type { PathParams, Route } from "./route.types.js";
+import type { ReadonlyURL } from "./readonly-url.types.js";
+import type { Route, RoutePathParams } from "./route.types.js";
 
 /**
- * パスマッチングの結果を表す型定義です。
+ * パスマッチングの処理結果を表すオブジェクトの型定義です。
  */
 export type MatchPathResult = {
   /**
-   * パスから抽出されたパラメーターのキーと値のペアです。
+   * マッチした URL パスから抽出されたパラメーターのキーと値のオブジェクトです。
    */
-  params: PathParams;
+  params: RoutePathParams;
 };
 
 /**
- * 指定されたルートの正規表現パターンを使用して、パス名がマッチするかどうかを判定します。
+ * 指定されたルートの正規表現パターンと URL のパス部分を照合し、マッチング検証およびパラメーター抽出を行う関数です。
  *
- * @param route 判定対象となる前処理済みのルートオブジェクトです。
- * @param pathname マッチングを行う対象のパス名（URL のパス部分）です。
- * @returns マッチした場合はパラメーターを含むオブジェクトを返し、マッチしない場合は `null` を返します。
+ * ルーティングエンジンが、現在の遷移先 URL に適合するルートを特定し、動的セグメントの値を型安全に回収する目的で使用します。
+ *
+ * @param route 検証対象となるルートオブジェクトから、マッチングに必要な `paramKeys` と `pathPattern` を抽出したオブジェクトです。
+ * @param url マッチングの判定元となる、読み取り専用の URL オブジェクトです。
+ * @returns マッチした場合は抽出されたパラメーターを含む `MatchPathResult` を返し、マッチしなかった場合は `null` を返します。
  */
 export default function matchPath(
   route: Pick<Route, "paramKeys" | "pathPattern">,
-  pathname: string,
+  url: ReadonlyURL,
 ): MatchPathResult | null {
-  const matches = route.pathPattern.exec(pathname);
+  const matches = route.pathPattern.exec(url.pathname);
   if (!matches) {
     return null;
   }
 
   const params: Record<string, string> = {};
-  for (let i = 0, value: string | undefined; i < route.paramKeys.length; i++) {
-    value = matches[i + 1];
-    if (value !== undefined) {
-      // route.paramKeys のインデックスと matches のキャプチャーグループを対応させます。
-      params[route.paramKeys[i]!] = value;
+  for (let i = 0, param: string | undefined; i < route.paramKeys.length; i++) {
+    // exec メソッドの戻り値のインデックス 0 にはマッチした文字列全体が格納されているため、各パラメーターの値はインデックス 1 以降（i + 1）から取得します。
+    param = matches[i + 1];
+
+    // キャプチャーされたセグメントが存在し、かつ文字列型である場合にのみ、対応するパラメーターキーと値をマッピングします。
+    // オプショナルなパラメーターが URL 側で省略されている場合は undefined となるため、この条件節により除外されます。
+    if (typeof param === "string") {
+      params[route.paramKeys[i]!] = param;
     }
   }
 

package/src/core/_process-routes.ts

@@ -1,56 +1,54 @@
 import { parse } from "regexparam";
+
 import compareRoutePaths from "./_compare-route-paths.js";
-import encodePathname from "./_encode-pathname.js";
+import RoutePath from "./route-path.js";
 import type { Route, RouteDefinition } from "./route.types.js";
 
 /**
- * パスのプレフィックスを考慮しながら再帰的にルートを変換する内部実装です。
+ * 定義したルーティング設定の配列を、内部のルーティングエンジンが直接利用可能な正規化済みのルートオブジェクトの配列へと変換します。
  *
- * @param defs 処理対象のルート定義の配列です。
- * @param prefix 親ルートから引き継いだパスのプレフィックスです。
- * @returns 変換後のルート配列です。
- */
-function processRoutesImpl(routes: readonly RouteDefinition[], prefix = ""): readonly Route[] {
-  return routes
-    .map(route => {
-      const path = encodePathname(prefix + "/" + route.path);
-      const isIndex = !route.children;
-      const {
-        keys: paramKeys,
-        pattern: pathPattern,
-      } = parse(
-        path,
-        // インデックスルートでないとき loose オプションを `true` にして子ルートに対してもマッチするようにします。
-        !isIndex,
-      );
-
-      return {
-        path,
-        index: isIndex,
-        children: route.children
-          ? processRoutesImpl(route.children, path)
-          : [],
-        component: route.component,
-        dataFuncs: (route.dataFunctions || []).map(f => ({
-          action: f.action,
-          loader: f.loader,
-          // 未定義の場合は常に true を返すデフォルト関数を設定します。
-          shouldAction: f.shouldAction || (a => a.defaultShouldAction),
-          shouldReload: f.shouldReload || (a => a.defaultShouldReload),
-        })),
-        paramKeys,
-        pathPattern,
-      };
-    })
-    .sort((a, b) => compareRoutePaths(a.path, b.path));
-}
-
-/**
- * ルート定義の配列を再帰的に処理し、実行時に適した `Route` オブジェクトの配列に変換します。
+ * 実行内容:
+ * - 各ルートのパス正規化
+ * - 動的解析用の正規表現コンパイル
+ * - 詳細度に基づく優先順位ソート
  *
- * @param routes 変換前のルート定義の配列です。
- * @returns 前処理が施された `Route` オブジェクトの配列を返します。
+ * @param routes ルーティング定義を格納した読み取り専用の配列です。
+ * @returns 読み取り専用の正規化済みルートオブジェクトの配列です。
  */
 export default function processRoutes(routes: readonly RouteDefinition[]): readonly Route[] {
-  return processRoutesImpl(routes);
+  return (
+    routes
+      .map((route) => {
+        const path = RoutePath.encode(route.path);
+        const index = route.index === true;
+        const { keys: paramKeys, pattern: pathPattern } = parse(
+          path,
+          // インデックスルートでないとき loose オプションを `true` にして子ルートに対してもマッチするようにします。
+          // これにより、前方一致による階層的なマッチングが有効になります。
+          !index,
+        );
+
+        return {
+          path,
+          index,
+          action: route.action,
+          loader: route.loader,
+          // オブジェクト形式またはモジュール形式の双方を安全に評価し、描画対象となる React コンポーネントを確定します。
+          component:
+            typeof route.component === "function"
+              ? route.component
+              : Symbol.toStringTag in route &&
+                  route[Symbol.toStringTag] === "Module" &&
+                  typeof route.default === "function"
+                ? route.default
+                : undefined,
+          paramKeys,
+          pathPattern,
+          shouldReload: route.shouldReload || ((args) => args.defaultShouldReload),
+        };
+      })
+      // すべてのルートを正規化した後、compareRoutePaths 関数を用いて詳細度が高い順にソートします。
+      // マッチング漏れや誤ったルートへの誤認を防ぐため、制限の厳しい（具体的な）パスパターンを持つルートオブジェクトが配列のより前方に配置されます。
+      .sort((a, b) => compareRoutePaths(a.path, b.path))
+  );
 }

package/src/core/_singleton.ts

@@ -1,45 +1,20 @@
-import isPromiseLike from "./_is-promise-like.js";
+import { callFnOnce } from "call-fn-once";
 
-declare global {
-  /**
-   * シングルトンインスタンスを管理するためのグローバルなキャッシュマップです。
-   */
-  var soseki__singleton: Map<unknown, any> | undefined;
-}
+/**
+ * 初回実行時の生成結果を保持するためのグローバルなキャッシュ管理マップです。
+ */
+const cacheMap: callFnOnce.CacheMap = new Map();
 
 /**
- * 指定されたキーに基づいて値を一意に保持するシングルトンパターンを提供します。
+ * 指定された識別子に対して、渡されたファクトリー関数を一度だけ実行し、その生成結果をシングルトンとして永続化および共有します。
  *
- * 初回実行時に生成された値をキャッシュし、以降の呼び出しではその値を返します。
+ * 2回目以降の呼び出しでは、ファクトリー関数は実行されず、初回に生成されたキャッシュデータが即座に返されます。
  *
- * @template T 生成される値の型です。
- * @param key インスタンスを識別するためのユニークなキーです。
- * @param fn インスタンスを生成するためのファクトリー関数です。
- * @returns キャッシュされた値、または非同期の場合はその解決値を返します。
+ * @template T ファクトリー関数が生成するシングルトンオブジェクトの型定義です。
+ * @param key シングルトンオブジェクトをキャッシュ内で一意に識別するためのキーです。
+ * @param fn 初回呼び出し時にのみ実行される、オブジェクト生成用のファクトリー関数です。
+ * @returns 初回実行時に生成された、またはキャッシュから回収された型 `T` のシングルトンインスタンスを返します。
  */
-export default function singleton<T>(key: unknown, fn: (...args: any) => T): T | Awaited<T> {
-  const cache = globalThis.soseki__singleton ||= new Map<unknown, any>();
-  if (cache.has(key)) {
-    return cache.get(key);
-  }
-
-  let returns = fn();
-  if (isPromiseLike<T>(returns)) {
-    const promise = (async () => {
-      try {
-        const value = await returns;
-        cache.set(key, value);
-        return value;
-      } catch (ex) {
-        // エラーが発生した場合はキャッシュを削除し、エラーを投げます。
-        cache.delete(key);
-        throw ex;
-      }
-    })();
-    cache.set(key, promise);
-  } else {
-    cache.set(key, returns);
-  }
-
-  return cache.get(key);
+export default function singleton<T>(key: unknown, fn: (...args: any) => T): T {
+  return callFnOnce(cacheMap, key, fn);
 }

package/src/core/_unreachable.ts

@@ -1,21 +1,26 @@
-import captureStackTrace from "./_capture-stack-trace.js";
+import { tryCaptureStackTrace } from "try-capture-stack-trace";
+
 import { UnreachableError } from "./errors.js";
 
 /**
- * 網羅性チェックを行うためのユーティリティー関数です。
+ * 網羅性チェックにおいて、プログラムの制御フローが理論上決して到達しないはずの場所に達したことを示すための関数です。
  */
 function unreachable(): never;
 
 /**
- * 網羅性チェックを行うためのユーティリティー関数です。`never` 型の変数に予期せぬ値が代入された場合にエラーを投げます。
+ * 網羅性チェックにおいて、プログラムの制御フローが理論上決して到達しないはずの場所に達したことを示すための関数です。
+ *
+ * * `switch` 文の `default` 句などでこの関数に値を渡すことにより、すべての列挙型やユニオン型のケースが処理し尽くされているかを静的に検証します。
+ *
+ * 漏れがある場合、TypeScript は引数が `never` 型に適合しないというコンパイルエラーを報告します。
  *
- * @param value `never` 型の変数です。ここには到達しないはずの値が入ります。
+ * @param value すべての分岐が処理された結果として、理論上 `never` 型になっているべき変数です。
  */
 function unreachable(value: never): never;
 
-function unreachable(...args: [never?]): never {
-  const error = new UnreachableError(args);
-  captureStackTrace(error, unreachable);
+function unreachable(...actual: [never?]): never {
+  const error = new UnreachableError({ actual });
+  tryCaptureStackTrace(error, unreachable);
   throw error;
 }
 

package/src/core/_valibot.ts

@@ -1,19 +1,7 @@
-import { type InferOutput, rawTransform, type RawTransformAction, safeParse } from "valibot";
-import captureStackTrace from "./_capture-stack-trace.js";
-import isError from "./_is-error.js";
-import { UnexpectedValidationError } from "./errors.js";
+import { tryCaptureStackTrace } from "try-capture-stack-trace";
+import { type InferOutput, safeParse } from "valibot";
 
-/***************************************************************************************************
- *
- * 共通の型
- *
- **************************************************************************************************/
-
-/**
- * Valibot のスキーマの基底型を抽出するための型定義です。
- */
-type BaseSchema = typeof safeParse extends (schema: infer TSchema, ...args: any) => any ? TSchema
-  : never;
+import { UnexpectedValidationError } from "./errors.js";
 
 /***************************************************************************************************
  *
@@ -21,101 +9,10 @@ type BaseSchema = typeof safeParse extends (schema: infer TSchema, ...args: any)
  *
  **************************************************************************************************/
 
-export {
-  brand,
-  minValue,
-  nullable,
-  number,
-  object,
-  pipe,
-  safeInteger,
-  string,
-  union,
-  url,
-  uuid,
-} from "valibot";
+export { url, pipe, uuid, brand, number, string, minValue, nullable, safeInteger } from "valibot";
 export type { InferInput, InferOutput } from "valibot";
 
-/***************************************************************************************************
- *
- * transform
- *
- **************************************************************************************************/
-
-/**
- * 入力値を変換するアクションを作成します。例外が投げられた場合は Issue として登録します。
- *
- * @template TInput 入力値の型です。
- * @template TOutput 出力値の型です。
- * @param operation 変換処理を行う関数です。
- * @returns Valibot の RawTransformAction オブジェクトです。
- */
-export function transform<TInput, TOutput>(
-  operation: (input: TInput) => TOutput,
-): RawTransformAction<TInput, TOutput> {
-  return rawTransform<TInput, TOutput>(({ dataset, addIssue, NEVER }) => {
-    const input = dataset.value;
-    try {
-      return operation(input);
-    } catch (ex) {
-      let message: string;
-      if (isError(ex)) {
-        message = `${ex.name}: ${ex.message}`;
-      } else {
-        try {
-          message = JSON.stringify(ex);
-        } catch {
-          message = String(ex);
-        }
-      }
-
-      addIssue({
-        input,
-        message,
-      });
-
-      return NEVER;
-    }
-  });
-}
-
-/***************************************************************************************************
- *
- * parse
- *
- **************************************************************************************************/
-
-// /**
-//  * バリデーションエラーを生成するためのコンストラクター型インターフェースです。
-//  */
-// export interface IParseErrorConstructor {
-//   new(issues: [Issue, ...Issue[]], input: unknown): ValidationErrorBase<ErrorMeta>;
-// }
-
-// /**
-//  * 指定されたスキーマに従って入力を検証し、失敗した場合は指定されたエラーを投げます。
-//  *
-//  * @template TSchema 使用するスキーマの型です。
-//  * @param schema 検証に使用する Valibot スキーマです。
-//  * @param input 検証対象の入力値です。
-//  * @param Error バリデーション失敗時に投げるエラークラスです。デフォルトは InvalidInputError です。
-//  * @returns 検証に成功した出力値です。
-//  * @throws 検証に失敗した場合、指定された Error を投げます。
-//  */
-// export function parse<const TSchema extends BaseSchema>(
-//   schema: TSchema,
-//   input: unknown,
-//   Error: IParseErrorConstructor = InvalidInputError,
-// ): InferOutput<TSchema> {
-//   const result = safeParse(schema, input);
-//   if (result.success) {
-//     return result.output;
-//   }
-
-//   const error = new Error(result.issues, input);
-//   captureStackTrace(error, parse);
-//   throw error;
-// }
+export { object, transform } from "@tai-kun/valibot-extra-lab";
 
 /***************************************************************************************************
  *
@@ -123,14 +20,17 @@ export function transform<TInput, TOutput>(
  *
  **************************************************************************************************/
 
+type BaseSchema = typeof safeParse extends (schema: infer TSchema, ...args: any) => any
+  ? TSchema
+  : never;
+
 /**
- * 指定されたスキーマに従って入力を検証し、失敗した場合は UnexpectedValidationError を投げます。
+ * 指定されたスキーマに基づいて入力値の構造を検証し、成功した場合は型安全に解析済みの値を出力します。
  *
- * @template TSchema 使用するスキーマの型です。
- * @param schema 検証に使用する Valibot スキーマです。
- * @param input 検証対象の入力値です。
- * @returns 検証に成功した出力値です。
- * @throws 検証に失敗した場合、UnexpectedValidationError を投げます。
+ * @template TSchema 評価に使用する `valibot` 形式のスキーマ定義型です。
+ * @param schema 入力値を検証するためのスキーマ定義オブジェクトです。
+ * @param input 整合性を検証する対象となる未知のデータです。
+ * @returns スキマの定義に完全に合致し、型付けが完了した解析済みの出力データを返します。
  */
 export function expect<const TSchema extends BaseSchema>(
   schema: TSchema,
@@ -141,7 +41,10 @@ export function expect<const TSchema extends BaseSchema>(
     return result.output;
   }
 
-  const error = new UnexpectedValidationError(result.issues, input);
-  captureStackTrace(error, expect);
+  const error = new UnexpectedValidationError({
+    value: input,
+    issues: result.issues,
+  });
+  tryCaptureStackTrace(error, expect);
   throw error;
 }