feat: add Refiner type

Author: lambdalisue

mod.ts

@@ -4,6 +4,7 @@ export * from "./curator.ts";
 export * from "./item.ts";
 export * from "./matcher.ts";
 export * from "./previewer.ts";
+export * from "./refiner.ts";
 export * from "./renderer.ts";
 export * from "./sorter.ts";
 export * from "./source.ts";

refiner.ts

@@ -0,0 +1,33 @@
+import type { Denops } from "@denops/std";
+import type { Detail, DetailUnit, IdItem } from "./item.ts";
+
+/**
+ * Parameters for refining a source or curator.
+ */
+export type RefineParams<T extends Detail> = {
+  readonly items: AsyncIterable<IdItem<T>>;
+};
+
+/**
+ * Refiner that refine a source or curator.
+ */
+export type Refiner<
+  T extends Detail = DetailUnit,
+  U extends Detail = DetailUnit,
+> = {
+  __phantom?: (_: T) => void; // This is required for type constraint.
+
+  /**
+   * Refine a source or curator.
+   *
+   * @param denops Denops instance.
+   * @param params Parameters for refining.
+   * @param options - Additional options, including an abort signal.
+   * @returns An async iterator over the collected or curated items.
+   */
+  refine: <V extends T>(
+    denops: Denops,
+    params: RefineParams<V>,
+    options: { signal?: AbortSignal },
+  ) => AsyncIterableIterator<IdItem<V & U>>;
+};

refiner_test.ts

@@ -0,0 +1,28 @@
+import { assertType, type IsExact } from "@std/testing/types";
+import { DenopsStub } from "@denops/test/stub";
+import type { DetailUnit } from "./item.ts";
+import type { RefineParams, Refiner } from "./refiner.ts";
+
+Deno.test("Refiner", async (t) => {
+  const denops = new DenopsStub();
+
+  await t.step("without type constraint is equal to UnitDetail", () => {
+    assertType<IsExact<Refiner, Refiner<DetailUnit>>>(true);
+  });
+
+  await t.step("preview follows the type constraint", () => {
+    const previewer: Refiner<{ a: string }> = { refine: async function* () {} };
+    previewer.refine(denops, {} as RefineParams<{ a: string }>, {});
+    previewer.refine(
+      denops,
+      {} as RefineParams<{ a: string; b: string }>,
+      {},
+    );
+    // @ts-expect-error: 'a' is missing
+    previewer.refine(denops, {} as RefineParams<{ b: string }>, {});
+    // @ts-expect-error: 'a' is missing
+    previewer.refine(denops, {} as RefineParams<Detail>, {});
+    // @ts-expect-error: 'a' is missing
+    previewer.refine(denops, {} as RefineParams<DetailUnit>, {});
+  });
+});