soseki 0.0.1

package/src/core/_process-routes.ts

@@ -0,0 +1,56 @@
+import { parse } from "regexparam";
+import compareRoutePaths from "./_compare-route-paths.js";
+import encodePathname from "./_encode-pathname.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` オブジェクトの配列を返します。
+ */
+export default function processRoutes(routes: readonly RouteDefinition[]): readonly Route[] {
+  return processRoutesImpl(routes);
+}

package/src/core/_singleton.ts

@@ -0,0 +1,45 @@
+import isPromiseLike from "./_is-promise-like.js";
+
+declare global {
+  /**
+   * シングルトンインスタンスを管理するためのグローバルなキャッシュマップです。
+   */
+  var soseki__singleton: Map<unknown, any> | undefined;
+}
+
+/**
+ * 指定されたキーに基づいて値を一意に保持するシングルトンパターンを提供します。
+ *
+ * 初回実行時に生成された値をキャッシュし、以降の呼び出しではその値を返します。
+ *
+ * @template T 生成される値の型です。
+ * @param key インスタンスを識別するためのユニークなキーです。
+ * @param fn インスタンスを生成するためのファクトリー関数です。
+ * @returns キャッシュされた値、または非同期の場合はその解決値を返します。
+ */
+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);
+}

package/src/core/_unreachable.ts

@@ -0,0 +1,22 @@
+import captureStackTrace from "./_capture-stack-trace.js";
+import { UnreachableError } from "./errors.js";
+
+/**
+ * 網羅性チェックを行うためのユーティリティー関数です。
+ */
+function unreachable(): never;
+
+/**
+ * 網羅性チェックを行うためのユーティリティー関数です。`never` 型の変数に予期せぬ値が代入された場合にエラーを投げます。
+ *
+ * @param value `never` 型の変数です。ここには到達しないはずの値が入ります。
+ */
+function unreachable(value: never): never;
+
+function unreachable(...args: [never?]): never {
+  const error = new UnreachableError(args);
+  captureStackTrace(error, unreachable);
+  throw error;
+}
+
+export default unreachable;

package/src/core/_use-singleton.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+
+/**
+ * 初期化が一度だけ実行されることを保証するための特殊なシンボルです。`ref.current` の初期値として使用され、値がまだ設定されていない状態を示します。
+ */
+const NONE = Symbol.for("soseki/none");
+
+/**
+ * コンポーネントのライフサイクルを通じて、初期化関数 (`fn`) を一度だけ実行し、その結果を保持し続けるカスタムフックです。
+ *
+ * `useMemo` と異なり、依存配列が存在しないため、再レンダリングやフックの呼び出し順序に関係なく、最初のレンダリング時にのみ初期化が実行されることを保証します。
+ *
+ * @template T 初期化関数が返す値の型です。
+ * @param fn 一度だけ実行される初期化関数です。引数は取りません。
+ * @returns 初期化関数が返した、シングルトンとして保持される値です。
+ */
+export default function useSingleton<T>(fn: () => T): T {
+  const ref = React.useRef<T | typeof NONE>(NONE);
+  if (ref.current === NONE) {
+    ref.current = fn();
+  }
+
+  return ref.current;
+}

package/src/core/_valibot.ts

@@ -0,0 +1,147 @@
+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";
+
+/***************************************************************************************************
+ *
+ * 共通の型
+ *
+ **************************************************************************************************/
+
+/**
+ * Valibot のスキーマの基底型を抽出するための型定義です。
+ */
+type BaseSchema = typeof safeParse extends (schema: infer TSchema, ...args: any) => any ? TSchema
+  : never;
+
+/***************************************************************************************************
+ *
+ * 再エクスポート
+ *
+ **************************************************************************************************/
+
+export {
+  brand,
+  minValue,
+  nullable,
+  number,
+  object,
+  pipe,
+  safeInteger,
+  string,
+  union,
+  url,
+  uuid,
+} 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;
+// }
+
+/***************************************************************************************************
+ *
+ * expect
+ *
+ **************************************************************************************************/
+
+/**
+ * 指定されたスキーマに従って入力を検証し、失敗した場合は UnexpectedValidationError を投げます。
+ *
+ * @template TSchema 使用するスキーマの型です。
+ * @param schema 検証に使用する Valibot スキーマです。
+ * @param input 検証対象の入力値です。
+ * @returns 検証に成功した出力値です。
+ * @throws 検証に失敗した場合、UnexpectedValidationError を投げます。
+ */
+export function expect<const TSchema extends BaseSchema>(
+  schema: TSchema,
+  input: unknown,
+): InferOutput<TSchema> {
+  const result = safeParse(schema, input);
+  if (result.success) {
+    return result.output;
+  }
+
+  const error = new UnexpectedValidationError(result.issues, input);
+  captureStackTrace(error, expect);
+  throw error;
+}

package/src/core/_weak-id-registry.ts

@@ -0,0 +1,125 @@
+import unreachable from "./_unreachable.js";
+
+/**
+ * 識別子（ID）の型エイリアスです。
+ *
+ * ID は増分カウンターを36進数エンコードしたものです。
+ */
+export type Id = string;
+
+/**
+ * `WeakIdRegistry` クラスは、オブジェクトに対する ID の割り当てと管理を行います。
+ *
+ * オブジェクト自体は `WeakMap` と `WeakRef` を使用して保持されるため、参照がなくなったオブジェクトはガベージコレクション（GC）の対象になります。
+ *
+ * @template TValue ID を割り当てる対象となるオブジェクトの型です。`object` 型のサブタイプである必要があります。
+ */
+export default class WeakIdRegistry<TValue extends object> {
+  /**
+   * ID 生成のための内部カウンターです。BigInt を使用することで、非常に大きな数値まで ID を生成できます。
+   */
+  private counter: bigint;
+
+  /**
+   * オブジェクト (関数を含む) から、割り当てられた ID へのマッピングを保持する `WeakMap` です。
+   *
+   * `WeakMap` を使用することで、キーであるオブジェクトが他の場所から参照されなくなった場合、このマッピングも自動的に破棄され、GC が可能になります。
+   */
+  private readonly v2id: WeakMap<TValue, Id>;
+
+  /**
+   * ID から、対応するオブジェクトへの弱い参照 (`WeakRef`) のマッピングを保持する `Map` です。
+   *
+   * オブジェクト自体が GC される可能性があるため、`WeakRef` を使用しています。
+   */
+  private readonly id2v: Map<Id, WeakRef<TValue>>;
+
+  /**
+   * オブジェクトが GC されたときに実行されるコールバックを登録するための `FinalizationRegistry` です。
+   *
+   * オブジェクトが GC されると、登録された ID がコールバックに渡され、その ID に対応するエントリーを `id2v` マップから削除するために使用されます。
+   */
+  private readonly gc: FinalizationRegistry<Id>;
+
+  /**
+   * `WeakIdRegistry` クラスの新しいインスタンスを作成します。
+   */
+  public constructor() {
+    this.counter = 0n;
+    this.v2id = new WeakMap();
+    this.id2v = new Map();
+    this.gc = new FinalizationRegistry(id => {
+      this.id2v.delete(id);
+    });
+  }
+
+  /**
+   * 指定されたオブジェクトに一意の ID を割り当てて登録します。
+   *
+   * すでに ID が割り当てられているオブジェクトであれば、既存の ID を返します。
+   *
+   * @param value ID を割り当てる対象のオブジェクトです。
+   * @returns 割り当てられた、または既存の一意の ID です。
+   */
+  public set(value: TValue): Id {
+    if (!this.v2id.has(value)) {
+      const id = (this.counter++).toString(36);
+      this.v2id.set(value, id);
+      this.id2v.set(id, new WeakRef(value));
+      // `FinalizationRegistry` にオブジェクトとそれに対応する ID を登録します。
+      // これにより、オブジェクトが GC されたときに `id2v` からエントリーが削除されます。
+      this.gc.register(value, id);
+
+      return id;
+    }
+
+    const id = this.v2id.get(value)!;
+    switch (typeof id) {
+      case "string":
+        return id;
+      default:
+        // `id` は必ず文字列になるはずです。
+        unreachable(id);
+    }
+  }
+
+  /**
+   * 指定されたオブジェクトに ID が割り当てられているかどうかを確認します。
+   *
+   * @param value 確認するオブジェクトです。
+   * @returns ID が割り当てられていれば `true`、そうでなければ `false` を返します。
+   */
+  public has(value: TValue): boolean {
+    return this.v2id.has(value);
+  }
+
+  /**
+   * 指定されたオブジェクトに対応する ID を取得します。
+   *
+   * オブジェクトが未登録の場合は `undefined` を返します。
+   *
+   * @param value 取得したい ID のオブジェクトです。
+   * @returns 対応する ID、またはオブジェクトが未登録の場合は `undefined` を返します。
+   */
+  public get(value: TValue): Id | undefined;
+
+  /**
+   * 指定された ID に対応するオブジェクトを取得します。
+   *
+   * オブジェクトが既に GC されている場合は `undefined` を返します。
+   *
+   * @param id 取得したいオブジェクトの ID です。
+   * @returns 対応するオブジェクト、またはオブジェクトが GC されている場合は `undefined` を返します。
+   */
+  public get(id: Id): TValue | undefined;
+
+  public get(idOrValue: Id | TValue): unknown {
+    if (typeof idOrValue === "string") {
+      const id = idOrValue;
+      return this.id2v.get(id)?.deref();
+    } else {
+      const value = idOrValue;
+      return this.v2id.get(value);
+    }
+  }
+}

package/src/core/constants.ts

@@ -0,0 +1,4 @@
+/**
+ * 特定のアクションを実行させるためのフォームフィールド名です。
+ */
+export const ACTION_ID_FORM_DATA_NAME: string = "_soseki_action_id";

package/src/core/data-map.types.ts

@@ -0,0 +1,28 @@
+import type DeferredPromise from "./deferred-promise.js";
+import type { IAction, ILoader } from "./route.types.js";
+
+/**
+ * 読み取り専用のデータマップを表すインターフェースです。
+ *
+ * ルートに関連付けられたアクションやローダーの関数をキーとし、その実行結果を値として保持します。
+ *
+ * @template TDataFunction アクションまたはローダーの型定義です。デフォルトは `IAction | ILoader` です。
+ * @template TData 遅延評価されるプロミスの型定義です。デフォルトは `DeferredPromise<unknown>` です。
+ */
+export interface IReadonlyDataMap<
+  TDataFunction extends IAction | ILoader = IAction | ILoader,
+  TData = DeferredPromise<unknown>,
+> extends ReadonlyMap<TDataFunction, TData> {}
+
+/**
+ * 書き込み可能なデータマップを表すインターフェースです。
+ *
+ * ルートに関連付けられたアクションやローダーの関数をキーとし、その実行結果を値として保持・操作します。
+ *
+ * @template TDataFunction アクションまたはローダーの型定義です。デフォルトは `IAction | ILoader` です。
+ * @template TData 遅延評価されるプロミスの型定義です。デフォルトは `DeferredPromise<unknown>` です。
+ */
+export interface IDataMap<
+  TDataFunction extends IAction | ILoader = IAction | ILoader,
+  TData = DeferredPromise<unknown>,
+> extends Map<TDataFunction, TData> {}

package/src/core/data-store.types.ts

@@ -0,0 +1,25 @@
+import type { IDataMap } from "./data-map.types.js";
+import type { HistoryEntryId } from "./history-entry-id-schema.js";
+import type { IAction, ILoader } from "./route.types.js";
+
+/**
+ * 読み取り専用のデータストアを表すインターフェースです。
+ *
+ * 履歴エントリーの ID をキーとし、それに関連付けられたデータマップを値として管理します。
+ *
+ * @template TDataFunction データマップ内で使用されるアクションまたはローダーの型定義です。
+ */
+export interface IReadonlyDataStore<TDataFunction extends IAction | ILoader = IAction | ILoader>
+  extends Readonly<Map<HistoryEntryId, IDataMap<TDataFunction>>>
+{}
+
+/**
+ * 書き込み可能なデータストアを表すインターフェースです。
+ *
+ *  履歴エントリーの ID ごとに、ルートに関連するデータの読み書きを行います。
+ *
+ * @template TDataFunction データマップ内で使用されるアクションまたはローダーの型定義です。
+ */
+export interface IDataStore<TDataFunction extends IAction | ILoader = IAction | ILoader>
+  extends Map<HistoryEntryId, IDataMap<TDataFunction>>
+{}