feat: make detail a bit stricter

Author: lambdalisue

action.ts

@@ -1,12 +1,12 @@
 import type { Denops } from "@denops/std";
 
 import type { Promish } from "./_typeutil.ts";
-import type { IdItem } from "./item.ts";
+import type { Detail, IdItem } from "./item.ts";
 
 /**
  * Parameters for invoking an action.
  */
-export type InvokeParams<T> = {
+export type InvokeParams<T extends Detail> = {
   /**
    * The item currently under the cursor.
    *
@@ -28,7 +28,7 @@ export type InvokeParams<T> = {
 /**
  * An action that can be invoked from the picker.
  */
-export type Action<T> = {
+export type Action<T extends Detail> = {
   /**
    * Invoke the action.
    *

curator.ts

@@ -1,6 +1,6 @@
 import type { Denops } from "@denops/std";
 
-import type { IdItem } from "./item.ts";
+import type { Detail, IdItem } from "./item.ts";
 
 /**
  * Parameters for curating items.
@@ -21,7 +21,7 @@ export type CurateParams = {
  *
  * Acts as an interactive `Source`.
  */
-export type Curator<T> = {
+export type Curator<T extends Detail> = {
   /**
    * Curates items based on the provided parameters.
    *

item.ts

@@ -1,7 +1,17 @@
+/**
+ * A detail attribute base type.
+ */
+export type Detail = Record<PropertyKey, unknown>;
+
+/**
+ * An empty detail attribute.
+ */
+export type EmptyDetail = Record<never, never>;
+
 /**
  * An item processed by the picker.
  */
-export type IdItem<T> = {
+export type IdItem<T extends Detail> = {
   /**
    * Unique identifier for the item.
    */
@@ -41,7 +51,7 @@ export type IdItem<T> = {
 /**
  * An item displayed in the picker.
  */
-export type DisplayItem<T> = IdItem<T> & {
+export type DisplayItem<T extends Detail> = IdItem<T> & {
   /**
    * Display label for the item in the picker.
    *

item_test.ts

@@ -0,0 +1,61 @@
+import { assertType, type IsExact } from "@std/testing/types";
+import type { Detail, EmptyDetail, IdItem } from "./item.ts";
+
+Deno.test("IdItem", async (t) => {
+  await t.step("id is 'unknown'", () => {
+    const item: IdItem<EmptyDetail> = {
+      id: "unknown",
+      value: "",
+      detail: {},
+    };
+    assertType<IsExact<typeof item, IdItem<EmptyDetail>>>(true);
+  });
+
+  await t.step("detail must be 'Detail'", () => {
+    const base = { id: "unknown", value: "" };
+    const _items: IdItem<Detail>[] = [
+      {
+        ...base,
+        // @ts-expect-error: number is not Detail
+        detail: 1,
+      },
+      {
+        ...base,
+        // @ts-expect-error: string is not Detail
+        detail: "",
+      },
+      {
+        ...base,
+        // @ts-expect-error: boolean is not Detail
+        detail: true,
+      },
+      {
+        ...base,
+        // @ts-expect-error: array is not Detail
+        detail: [],
+      },
+      {
+        ...base,
+        // @ts-expect-error: Date is not Detail
+        detail: new Date(),
+      },
+      {
+        ...base,
+        detail: {},
+      },
+      {
+        ...base,
+        detail: {
+          a: "string",
+          b: 1,
+          c: true,
+          d: [],
+          e: new Date(),
+          f: () => {},
+          0: "number",
+          [Symbol("g")]: "symbol",
+        },
+      },
+    ];
+  });
+});

matcher.ts

@@ -1,10 +1,11 @@
 import type { Denops } from "@denops/std";
-import type { IdItem } from "./item.ts";
+
+import type { Detail, IdItem } from "./item.ts";
 
 /**
  * Parameters for matching items.
  */
-export type MatchParams<T> = {
+export type MatchParams<T extends Detail> = {
   /**
    * User input query for filtering.
    */
@@ -18,8 +19,8 @@ export type MatchParams<T> = {
 /**
  * Matcher that filters items based on user input.
  */
-export type Matcher<T> = {
-  __phantom?: T; // This is required for type constraint.
+export type Matcher<T extends Detail> = {
+  __phantom?: (_: T) => void; // This is required for type constraint.
 
   /**
    * Matches items against the provided query.
@@ -29,9 +30,7 @@ export type Matcher<T> = {
    * @param options - Additional options, including an abort signal.
    * @returns An async iterator over matched `IdItem` elements.
    */
-  match<
-    V extends T,
-  >(
+  match<V extends T>(
     denops: Denops,
     params: MatchParams<V>,
     options: { signal?: AbortSignal },

mod.ts

@@ -1,14 +1,3 @@
-/**
- * Core types for [Fall](https://github.com/vim-fall/fall), a Vim/Neovim fuzzy
- * finder plugin powered by [Denops](https://github.com/vim-denops/denops.vim).
- *
- * > [!WARNING]
- * >
- * > This module is intended for internal use only and is not meant for external
- * > use.
- *
- * @module
- */
 export * from "./action.ts";
 export * from "./coordinator.ts";
 export * from "./curator.ts";

previewer.ts

@@ -1,11 +1,11 @@
 import type { Denops } from "@denops/std";
 import type { Promish } from "./_typeutil.ts";
-import type { IdItem, PreviewItem } from "./item.ts";
+import type { Detail, IdItem, PreviewItem } from "./item.ts";
 
 /**
  * Parameters for previewing an item.
  */
-export type PreviewParams<T> = {
+export type PreviewParams<T extends Detail> = {
   /**
    * The item to preview.
    */
@@ -15,7 +15,7 @@ export type PreviewParams<T> = {
 /**
  * Previewer that generates a preview for an item.
  */
-export type Previewer<T> = {
+export type Previewer<T extends Detail> = {
   /**
    * Generates a preview for the specified item.
    *

renderer.ts

@@ -1,11 +1,11 @@
 import type { Denops } from "@denops/std";
 import type { Promish } from "./_typeutil.ts";
-import type { DisplayItem } from "./item.ts";
+import type { Detail, DisplayItem } from "./item.ts";
 
 /**
  * Parameters for rendering items.
  */
-export type RenderParams<T> = {
+export type RenderParams<T extends Detail> = {
   /**
    * Array of items to render.
    */
@@ -15,7 +15,7 @@ export type RenderParams<T> = {
 /**
  * Renderer responsible for rendering items.
  */
-export type Renderer<T> = {
+export type Renderer<T extends Detail> = {
   /**
    * Renders items in place.
    *

sorter.ts

@@ -1,11 +1,11 @@
 import type { Denops } from "@denops/std";
 import type { Promish } from "./_typeutil.ts";
-import type { IdItem } from "./item.ts";
+import type { Detail, IdItem } from "./item.ts";
 
 /**
  * Parameters for sorting items.
  */
-export type SortParams<T> = {
+export type SortParams<T extends Detail> = {
   /**
    * Array of items to sort.
    */
@@ -15,7 +15,7 @@ export type SortParams<T> = {
 /**
  * Sorter that arranges items in order.
  */
-export type Sorter<T> = {
+export type Sorter<T extends Detail> = {
   /**
    * Sorts items in place.
    *

source.ts

@@ -1,5 +1,5 @@
 import type { Denops } from "@denops/std";
-import type { IdItem } from "./item.ts";
+import type { Detail, IdItem } from "./item.ts";
 
 /**
  * Parameters for collecting items.
@@ -14,7 +14,7 @@ export type CollectParams = {
 /**
  * Source that collects items.
  */
-export type Source<T> = {
+export type Source<T extends Detail> = {
   /**
    * Collects items.
    *