Merge pull request #69 from vim-denops/improve-batch

Add `batch` module to handle `denops.batch` more flexibly

Author: lambdalisue

denops_std/batch/README.md

@@ -0,0 +1,108 @@
+# batch
+
+`batch` is a module to provide `denops.batch()` helper functions.
+
+- [API documentation](https://doc.deno.land/https/deno.land/x/denops_std/batch/mod.ts)
+
+## Usage
+
+### batch
+
+Use `batch()` to call multiple denops functions sequentially without overhead
+like:
+
+```typescript
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import { batch } from "https://deno.land/x/denops_std/batch/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  await batch(denops, async (denops) => {
+    await denops.cmd("setlocal modifiable");
+    await denops.cmd("setlocal noswap");
+    await denops.cmd("setlocal nobackup");
+  });
+}
+```
+
+The function can be nested thus users can use functions which may internally use
+`batch()` like:
+
+```typescript
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import { batch } from "https://deno.land/x/denops_std/batch/mod.ts";
+
+async function replace(denops: Denops, content: string): Promise<void> {
+  await batch(denops, (denops) => {
+    await denops.cmd("setlocal modifiable");
+    await denops.cmd("setlocal foldmethod=manual");
+    await denops.call("setline", 1, content.split(/\r?\n/));
+    await denops.cmd("setlocal nomodifiable");
+    await denops.cmd("setlocal nomodified");
+  });
+}
+
+export async function main(denops: Denops): Promise<void> {
+  await batch(denops, async (denops) => {
+    await denops.cmd("edit Hello");
+    await replace(denops, "Hello Darkness My Old Friend");
+  });
+}
+```
+
+Note that `denops.call()`, `denops.batch()`, or `denops.eval()` always return
+falsy value in `batch()`, indicating that you **cannot** write code like below:
+
+```typescript
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import { batch } from "https://deno.land/x/denops_std/batch/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  await batch(denops, async (denops) => {
+    // !!! DON'T DO THIS !!!
+    if (await denops.eval("&verbose")) {
+      await denops.cmd("echomsg 'VERBOSE'");
+    }
+    await denops.cmd("echomsg 'Hello world'");
+  });
+}
+```
+
+### gather
+
+Use `gather()` to call multiple denops functions sequentially without overhead
+and return values like:
+
+```typescript
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import { gather } from "https://deno.land/x/denops_std/batch/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  const results = await gather(denops, async (denops) => {
+    await denops.eval("&modifiable");
+    await denops.eval("&modified");
+    await denops.eval("&filetype");
+  });
+  // results contains the value of modifiable, modified, and filetype
+}
+```
+
+Not like `batch`, the function can NOT be nested.
+
+Note that `denops.call()`, `denops.batch()`, or `denops.eval()` always return
+falsy value in `gather()`, indicating that you **cannot** write code like below:
+
+```typescript
+import { Denops } from "https://deno.land/x/denops_std/mod.ts";
+import { batch } from "https://deno.land/x/denops_std/batch/mod.ts";
+
+export async function main(denops: Denops): Promise<void> {
+  const results = await gather(denops, async (denops) => {
+    // !!! DON'T DO THIS !!!
+    if (await denops.call("has", "nvim")) {
+      await denops.call("api_info").version;
+    } else {
+      await denops.eval("v:version");
+    }
+  });
+}
+```

denops_std/batch/batch.ts

@@ -0,0 +1,70 @@
+import { Context, Denops, Dispatcher, Meta } from "../deps.ts";
+
+class BatchHelper implements Denops {
+  #denops: Denops;
+  #calls: [string, ...unknown[]][];
+
+  constructor(denops: Denops) {
+    this.#denops = denops;
+    this.#calls = [];
+  }
+
+  static getCalls(helper: BatchHelper): [string, ...unknown[]][] {
+    return helper.#calls;
+  }
+
+  get name(): string {
+    return this.#denops.name;
+  }
+
+  get meta(): Meta {
+    return this.#denops.meta;
+  }
+
+  get dispatcher(): Dispatcher {
+    return this.#denops.dispatcher;
+  }
+
+  set dispatcher(dispatcher: Dispatcher) {
+    this.#denops.dispatcher = dispatcher;
+  }
+
+  call(fn: string, ...args: unknown[]): Promise<unknown> {
+    this.#calls.push([fn, ...args]);
+    return Promise.resolve();
+  }
+
+  batch(...calls: [string, ...unknown[]][]): Promise<unknown[]> {
+    this.#calls.push(...calls);
+    return Promise.resolve([]);
+  }
+
+  cmd(cmd: string, ctx: Context = {}): Promise<void> {
+    this.call("denops#api#cmd", cmd, ctx);
+    return Promise.resolve();
+  }
+
+  eval(expr: string, ctx: Context = {}): Promise<unknown> {
+    this.call("denops#api#eval", expr, ctx);
+    return Promise.resolve();
+  }
+
+  dispatch(name: string, fn: string, ...args: unknown[]): Promise<unknown> {
+    return this.#denops.dispatch(name, fn, ...args);
+  }
+}
+
+/**
+ * Perform batch call
+ */
+export async function batch(
+  denops: Denops,
+  main: (helper: BatchHelper) => Promise<void>,
+): Promise<void> {
+  const helper = new BatchHelper(denops);
+  await main(helper);
+  const calls = BatchHelper.getCalls(helper);
+  await denops.batch(...calls);
+}
+
+export type { BatchHelper };

denops_std/batch/batch_test.ts

@@ -0,0 +1,132 @@
+import { assertEquals, test } from "../deps_test.ts";
+import { batch } from "./batch.ts";
+
+test({
+  mode: "any",
+  name: "batch() sequentially execute 'denops.call()' as batch process.",
+  fn: async (denops) => {
+    await denops.cmd("let g:denops_batch_test = []");
+    await denops.cmd(
+      "command! -nargs=1 DenopsBatchTest let g:denops_batch_test += [<f-args>]",
+    );
+    await batch(denops, async (denops) => {
+      assertEquals(
+        await denops.call("execute", "DenopsBatchTest 1"),
+        undefined,
+      );
+      assertEquals(
+        await denops.call("execute", "DenopsBatchTest 2"),
+        undefined,
+      );
+      assertEquals(
+        await denops.call("execute", "DenopsBatchTest 3"),
+        undefined,
+      );
+    });
+    assertEquals(await denops.eval("g:denops_batch_test") as string[], [
+      "1",
+      "2",
+      "3",
+    ]);
+  },
+});
+test({
+  mode: "any",
+  name: "batch() sequentially execute 'denops.cmd()' as batch process.",
+  fn: async (denops) => {
+    await denops.cmd("let g:denops_batch_test = []");
+    await denops.cmd(
+      "command! -nargs=1 DenopsBatchTest let g:denops_batch_test += [<f-args>]",
+    );
+    await batch(denops, async (denops) => {
+      assertEquals(await denops.cmd("DenopsBatchTest 1"), undefined);
+      assertEquals(await denops.cmd("DenopsBatchTest 2"), undefined);
+      assertEquals(await denops.cmd("DenopsBatchTest 3"), undefined);
+    });
+    assertEquals(await denops.eval("g:denops_batch_test") as string[], [
+      "1",
+      "2",
+      "3",
+    ]);
+  },
+});
+test({
+  mode: "any",
+  name: "batch() sequentially execute 'denops.eval()' as batch process.",
+  fn: async (denops) => {
+    await denops.cmd("let g:denops_batch_test = []");
+    await batch(denops, async (denops) => {
+      assertEquals(
+        await denops.eval("add(g:denops_batch_test, string(1))"),
+        undefined,
+      );
+      assertEquals(
+        await denops.eval("add(g:denops_batch_test, string(2))"),
+        undefined,
+      );
+      assertEquals(
+        await denops.eval("add(g:denops_batch_test, string(3))"),
+        undefined,
+      );
+    });
+    assertEquals(await denops.eval("g:denops_batch_test") as string[], [
+      "1",
+      "2",
+      "3",
+    ]);
+  },
+});
+test({
+  mode: "any",
+  name: "batch() sequentially execute nested 'batch()' as batch process.",
+  fn: async (denops) => {
+    await denops.cmd("let g:denops_batch_test = []");
+    await denops.cmd(
+      "command! -nargs=1 DenopsBatchTest let g:denops_batch_test += [<f-args>]",
+    );
+    await batch(denops, async (denops) => {
+      assertEquals(
+        await denops.call("execute", "DenopsBatchTest 1"),
+        undefined,
+      );
+      assertEquals(
+        await denops.call("execute", "DenopsBatchTest 2"),
+        undefined,
+      );
+      await batch(denops, async (denops) => {
+        assertEquals(await denops.cmd("DenopsBatchTest 3"), undefined);
+        assertEquals(await denops.cmd("DenopsBatchTest 4"), undefined);
+        await batch(denops, async (denops) => {
+          assertEquals(
+            await denops.eval("add(g:denops_batch_test, string(5))"),
+            undefined,
+          );
+          assertEquals(
+            await denops.eval("add(g:denops_batch_test, string(6))"),
+            undefined,
+          );
+          assertEquals(
+            await denops.eval("add(g:denops_batch_test, string(7))"),
+            undefined,
+          );
+        });
+        assertEquals(await denops.cmd("DenopsBatchTest 8"), undefined);
+      });
+      assertEquals(
+        await denops.call("execute", "DenopsBatchTest 9"),
+        undefined,
+      );
+    });
+    assertEquals(await denops.eval("g:denops_batch_test") as string[], [
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "6",
+      "7",
+      "8",
+      "9",
+    ]);
+  },
+});

denops_std/batch/gather.ts

@@ -0,0 +1,69 @@
+import { Context, Denops, Dispatcher, Meta } from "../deps.ts";
+
+class GatherHelper implements Denops {
+  #denops: Denops;
+  #calls: [string, ...unknown[]][];
+
+  constructor(denops: Denops) {
+    this.#denops = denops;
+    this.#calls = [];
+  }
+
+  static getCalls(helper: GatherHelper): [string, ...unknown[]][] {
+    return helper.#calls;
+  }
+
+  get name(): string {
+    return this.#denops.name;
+  }
+
+  get meta(): Meta {
+    return this.#denops.meta;
+  }
+
+  get dispatcher(): Dispatcher {
+    return this.#denops.dispatcher;
+  }
+
+  set dispatcher(dispatcher: Dispatcher) {
+    this.#denops.dispatcher = dispatcher;
+  }
+
+  call(fn: string, ...args: unknown[]): Promise<unknown> {
+    this.#calls.push([fn, ...args]);
+    return Promise.resolve();
+  }
+
+  batch(..._calls: [string, ...unknown[]][]): Promise<unknown[]> {
+    throw new Error("The 'batch' method is not available on GatherHelper.");
+  }
+
+  cmd(cmd: string, ctx: Context = {}): Promise<void> {
+    this.call("denops#api#cmd", cmd, ctx);
+    return Promise.resolve();
+  }
+
+  eval(expr: string, ctx: Context = {}): Promise<unknown> {
+    this.call("denops#api#eval", expr, ctx);
+    return Promise.resolve();
+  }
+
+  dispatch(name: string, fn: string, ...args: unknown[]): Promise<unknown> {
+    return this.#denops.dispatch(name, fn, ...args);
+  }
+}
+
+/**
+ * Perform gather call
+ */
+export async function gather(
+  denops: Denops,
+  main: (helper: GatherHelper) => Promise<void>,
+): Promise<unknown[]> {
+  const helper = new GatherHelper(denops);
+  await main(helper);
+  const calls = GatherHelper.getCalls(helper);
+  return await denops.batch(...calls);
+}
+
+export type { GatherHelper };