👍 Add lambda module and deprecate anonymous

Author: lambdalisue

denops_std/anonymous/mod.ts

@@ -2,6 +2,7 @@
  * A module to provide anonymous function which is callable from
  * outside of the plugin (Vim or other plugins.)
  *
+ * @deprecated Use `lambda` module instead.
  * @module
  */
 import type { Denops } from "https://deno.land/x/denops_core@v3.4.1/mod.ts";
@@ -55,6 +56,8 @@ export type Callback = (...args: unknown[]) => Promise<unknown> | unknown;
  *   });
  * }
  * ```
+ *
+ * @deprecated Use `lambda.register()` function instead.
  */
 export function add<N extends number>(
   denops: Denops,
@@ -98,6 +101,8 @@ export function add<N extends number>(
  *   await denops.dispatch(denops.name, ids[0]);
  * }
  * ```
+ *
+ * @deprecated Use `lambda.register()` function instead.
  */
 export function once<N extends number>(
   denops: Denops,
@@ -147,6 +152,8 @@ export function once<N extends number>(
  *   await denops.dispatch(denops.name, ids[1]);
  * }
  * ```
+ *
+ * @deprecated Use `lambda.unregister()` function instead.
  */
 export function remove<N extends number>(
   denops: Denops,

denops_std/lambda/mod.ts

@@ -0,0 +1,144 @@
+/**
+ * A module to provide lambda function that is callable from the outside of the plugin.
+ *
+ * Use `denops#callback#register()` and `denops#callback#call()` functions instead if you'd like
+ * to create a lambda function of Vim script that is callable from Deno.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as lambda from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   // Add lambda function
+ *   const id = lambda.register(
+ *     denops,
+ *     () => {
+ *       // Do what ever you want.
+ *     },
+ *   );
+ *
+ *   // Use id to dispatch added function from Deno
+ *   await denops.dispatch(denops.name, id);
+ *
+ *   // Or from Vim
+ *   await denops.cmd("call denops#notify(name, id, [])", {
+ *     name: denops.name,
+ *     id,
+ *   });
+ * }
+ * ```
+ *
+ * @module
+ */
+
+import type { Denops } from "https://deno.land/x/denops_core@v3.4.1/mod.ts";
+
+/**
+ * Lambda function identifier
+ */
+export type Identifier = string;
+
+/**
+ * Lambda function
+ */
+export type Fn = (...args: unknown[]) => unknown;
+
+/**
+ * Register options
+ */
+export interface Options {
+  /** Register the function as a one-time lambda function that will be removed when the function has called */
+  once?: boolean;
+}
+
+/**
+ * Register a lambda function as a denops API and return the identifier.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as lambda from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   // Add lambda function
+ *   const id = lambda.register(
+ *     denops,
+ *     () => {
+ *       // Do what ever you want.
+ *     },
+ *   );
+ *
+ *   // Use id to dispatch added function from Deno
+ *   await denops.dispatch(denops.name, id);
+ *
+ *   // Or from Vim
+ *   await denops.cmd("call denops#notify(name, id, [])", {
+ *     name: denops.name,
+ *     id,
+ *   });
+ * }
+ * ```
+ *
+ * If you need an one-time lambda function, use `once` option like
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import * as lambda from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   // Add lambda function
+ *   const id = lambda.register(
+ *     denops,
+ *     () => {
+ *       // Do what ever you want.
+ *     },
+ *     {
+ *       once: true,
+ *     },
+ *   );
+ *
+ *   // Use id to dispatch added function from Deno
+ *   await denops.dispatch(denops.name, id);
+ *
+ *   // Second call would throw error
+ *   await denops.dispatch(denops.name, id);
+ * }
+ * ```
+ */
+export function register(
+  denops: Denops,
+  fn: Fn,
+  options: Options = {},
+): Identifier {
+  const uuid = crypto.randomUUID();
+  const id = `lambda:${denops.name}:${uuid}`;
+  if (options.once) {
+    denops.dispatcher[id] = async (...args: unknown[]) => {
+      try {
+        return await fn(...args);
+      } finally {
+        unregister(denops, id);
+      }
+    };
+  } else {
+    denops.dispatcher[id] = async (...args: unknown[]) => {
+      return await fn(...args);
+    };
+  }
+  return id;
+}
+
+/**
+ * Unregister a lambda function from a denops API identified by the identifier
+ *
+ * It returns `true` if the lambda function is unregistered. Otherwise it returns `false`.
+ */
+export function unregister(
+  denops: Denops,
+  id: Identifier,
+): boolean {
+  if (id in denops.dispatcher) {
+    delete denops.dispatcher[id];
+    return true;
+  }
+  return false;
+}

denops_std/lambda/mod_test.ts

@@ -0,0 +1,65 @@
+import {
+  assertEquals,
+  assertRejects,
+} from "https://deno.land/std@0.170.0/testing/asserts.ts";
+import { test } from "https://deno.land/x/denops_test@v1.0.1/mod.ts";
+import * as lambda from "./mod.ts";
+
+test({
+  mode: "all",
+  name: "lambda",
+  fn: async (denops, t) => {
+    await t.step({
+      name: "register() registers a lambda function",
+      fn: async () => {
+        const id = lambda.register(
+          denops,
+          () => Promise.resolve("0"),
+        );
+        assertEquals(await denops.dispatch(denops.name, id), "0");
+        assertEquals(await denops.dispatch(denops.name, id), "0");
+      },
+    });
+
+    await t.step({
+      name:
+        "register() registers an oneshot lambda functions when 'once' option is specified",
+      fn: async () => {
+        const id = lambda.register(
+          denops,
+          () => Promise.resolve("0"),
+          { once: true },
+        );
+        assertEquals(await denops.dispatch(denops.name, id), "0");
+
+        // The method will be removed
+        await assertRejects(
+          async () => {
+            await denops.dispatch(denops.name, id);
+          },
+          `No method '${id}' exists`,
+        );
+      },
+    });
+
+    await t.step({
+      name:
+        "unregister() unregisters a lambda function identified by the identifier",
+      fn: async () => {
+        const id = lambda.register(
+          denops,
+          () => Promise.resolve("0"),
+        );
+        assertEquals(lambda.unregister(denops, id), true);
+
+        // The method is removed
+        await assertRejects(
+          async () => {
+            await denops.dispatch(denops.name, id);
+          },
+          `No method '${id}' exists`,
+        );
+      },
+    });
+  },
+});