Merge pull request #331 from fcollonval/ft/command-description-2

Allow describedBy to be an async function

Author: afshin

packages/commands/src/index.ts

@@ -156,11 +156,18 @@ export class CommandRegistry {
    *
    * @param id - The id of the command of interest.
    *
+   * @param args - The arguments for the command.
+   *
    * @returns The description for the command.
    */
-  describedBy(id: string): { args: ReadonlyJSONObject | null } {
+  describedBy(
+    id: string,
+    args: ReadonlyPartialJSONObject = JSONExt.emptyObject
+  ): Promise<CommandRegistry.Description> {
     let cmd = this._commands[id];
-    return cmd?.describedBy ?? { args: null };
+    return Promise.resolve(
+      cmd?.describedBy.call(undefined, args) ?? { args: null }
+    );
   }
 
   /**
@@ -671,6 +678,11 @@ export namespace CommandRegistry {
    */
   export type Dataset = { readonly [key: string]: string };
 
+  /**
+   * Commands description.
+   */
+  export type Description = { args: ReadonlyJSONObject | null };
+
   /**
    * An options object for creating a command.
    *
@@ -704,7 +716,9 @@ export namespace CommandRegistry {
      * For now, the command arguments are the only one that can be
      * described.
      */
-    describedBy?: { args?: ReadonlyJSONObject };
+    describedBy?:
+      | Partial<Description>
+      | CommandFunc<Partial<Description> | Promise<Partial<Description>>>;
 
     /**
      * The label for the command.
@@ -1263,7 +1277,9 @@ namespace Private {
    */
   export interface ICommand {
     readonly execute: CommandFunc<any>;
-    readonly describedBy: { args: ReadonlyJSONObject | null };
+    readonly describedBy: CommandFunc<
+      CommandRegistry.Description | Promise<CommandRegistry.Description>
+    >;
     readonly label: CommandFunc<string>;
     readonly mnemonic: CommandFunc<number>;
     readonly icon: CommandFunc<VirtualElement.IRenderer | undefined>;
@@ -1287,7 +1303,18 @@ namespace Private {
   ): ICommand {
     return {
       execute: options.execute,
-      describedBy: { args: null, ...options.describedBy },
+      describedBy: asFunc<
+        CommandRegistry.Description | Promise<CommandRegistry.Description>
+      >(
+        typeof options.describedBy === 'function'
+          ? (options.describedBy as CommandFunc<
+              CommandRegistry.Description | Promise<CommandRegistry.Description>
+            >)
+          : { args: null, ...options.describedBy },
+        () => {
+          return { args: null };
+        }
+      ),
       label: asFunc(options.label, emptyStringFunc),
       mnemonic: asFunc(options.mnemonic, negativeOneFunc),
       icon: asFunc(options.icon, undefinedFunc),

packages/commands/tests/src/index.spec.ts

@@ -12,7 +12,7 @@ import { expect } from 'chai';
 
 import { CommandRegistry } from '@lumino/commands';
 
-import { JSONObject } from '@lumino/coreutils';
+import { JSONObject, ReadonlyJSONObject } from '@lumino/coreutils';
 
 import { Platform } from '@lumino/domutils';
 
@@ -329,7 +329,7 @@ describe('@lumino/commands', () => {
     });
 
     describe('#describedBy()', () => {
-      it('should get the description for a specific command', () => {
+      it('should get the description for a specific command', async () => {
         const description = {
           args: {
             properties: {},
@@ -344,16 +344,79 @@ describe('@lumino/commands', () => {
           describedBy: description
         };
         registry.addCommand('test', cmd);
-        expect(registry.describedBy('test')).to.deep.equal(description);
+        expect(await registry.describedBy('test')).to.deep.equal(description);
       });
 
-      it('should return an empty description if the command is not registered', () => {
-        expect(registry.describedBy('foo')).to.deep.equal({ args: null });
+      it('should accept a function', async () => {
+        const description = {
+          args: {
+            properties: {},
+            additionalProperties: false,
+            type: 'object'
+          }
+        };
+
+        let cmd = {
+          execute: (args: JSONObject) => {
+            return args;
+          },
+          describedBy: () => description
+        };
+        registry.addCommand('test', cmd);
+        expect(await registry.describedBy('test')).to.deep.equal(description);
       });
 
-      it('should default to an empty description for a command', () => {
+      it('should accept an asynchronous function', async () => {
+        const description = {
+          args: {
+            properties: {},
+            additionalProperties: false,
+            type: 'object'
+          }
+        };
+
+        let cmd = {
+          execute: (args: JSONObject) => {
+            return args;
+          },
+          describedBy: () => Promise.resolve(description)
+        };
+        registry.addCommand('test', cmd);
+        expect(await registry.describedBy('test')).to.deep.equal(description);
+      });
+
+      it('should accept args', async () => {
+        const description = {
+          properties: {},
+          additionalProperties: false,
+          type: 'object'
+        };
+
+        let cmd = {
+          execute: (args: JSONObject) => {
+            return args;
+          },
+          describedBy: (args: ReadonlyJSONObject) => {
+            return {
+              args
+            };
+          }
+        };
+        registry.addCommand('test', cmd);
+        expect(
+          await registry.describedBy('test', description as any)
+        ).to.deep.equal({ args: description });
+      });
+
+      it('should return an empty description if the command is not registered', async () => {
+        expect(await registry.describedBy('foo')).to.deep.equal({ args: null });
+      });
+
+      it('should default to an empty description for a command', async () => {
         registry.addCommand('test', NULL_COMMAND);
-        expect(registry.describedBy('test')).to.deep.equal({ args: null });
+        expect(await registry.describedBy('test')).to.deep.equal({
+          args: null
+        });
       });
     });