Command Management

/**
 * An object which manages a collection of commands.
 * A command registry can be used to populate a variety of action-based
 * widgets, such as command palettes, menus, and toolbars.
 */
class CommandRegistry {
  constructor();
}

/**
 * Add a command to the registry.
 * @param id - The unique id of the command
 * @param options - The options for the command
 * @returns A disposable which will remove the command
 * @throws An error if the given id is already registered
 */
addCommand(id: string, options: CommandRegistry.ICommandOptions): IDisposable;

/**
 * Test whether a specific command is registered.
 * @param id - The id of the command of interest
 * @returns true if the command is registered, false otherwise
 */
hasCommand(id: string): boolean;

/**
 * List the ids of the registered commands.
 * @returns A new array of the registered command ids
 */
listCommands(): string[];

interface ICommandOptions {
  /** The function to invoke when the command is executed (required) */
  execute: CommandFunc<any | Promise<any>>;
  
  /** JSON Schemas describing the command */
  describedBy?: Partial<Description> | CommandFunc<Partial<Description> | Promise<Partial<Description>>>;
  
  /** The label for the command */
  label?: string | CommandFunc<string>;
  
  /** The index of the mnemonic character in the command's label */
  mnemonic?: number | CommandFunc<number>;
  
  /** The icon renderer for the command */
  icon?: VirtualElement.IRenderer | undefined | CommandFunc<VirtualElement.IRenderer | undefined>;
  
  /** The icon class for the command */
  iconClass?: string | CommandFunc<string>;
  
  /** The icon label for the command */
  iconLabel?: string | CommandFunc<string>;
  
  /** The caption for the command */
  caption?: string | CommandFunc<string>;
  
  /** The usage text for the command */
  usage?: string | CommandFunc<string>;
  
  /** The general class name for the command */
  className?: string | CommandFunc<string>;
  
  /** The dataset for the command */
  dataset?: Dataset | CommandFunc<Dataset>;
  
  /** A function which indicates whether the command is enabled */
  isEnabled?: CommandFunc<boolean>;
  
  /** A function which indicates whether the command is toggled */
  isToggled?: CommandFunc<boolean>;
  
  /** A function which indicates whether the command is toggleable */
  isToggleable?: boolean;
  
  /** A function which indicates whether the command is visible */
  isVisible?: CommandFunc<boolean>;
}

/**
 * Execute a specific command.
 * @param id - The id of the command of interest
 * @param args - The arguments for the command
 * @returns A promise which resolves with the result of the command
 * @throws The promise will reject if the command throws an exception or if the command is not registered
 */
execute(id: string, args?: ReadonlyPartialJSONObject): Promise<any>;

/**
 * Notify listeners that the state of a command has changed.
 * @param id - The id of the command which has changed. If more than one command has changed, this argument should be omitted
 * @throws An error if the given id is not registered
 */
notifyCommandChanged(id?: string): void;

import { CommandRegistry } from "@lumino/commands";

const registry = new CommandRegistry();

// Simple command with static properties
const disposable = registry.addCommand("simple-command", {
  execute: () => {
    console.log("Command executed!");
  },
  label: "Simple Command",
  caption: "A simple example command"
});

// Execute the command
await registry.execute("simple-command");

import { CommandRegistry } from "@lumino/commands";

const registry = new CommandRegistry();

// Command with dynamic properties based on arguments
registry.addCommand("dynamic-command", {
  execute: (args) => {
    console.log(`Processing ${args.filename}`);
    return Promise.resolve(`Processed ${args.filename}`);
  },
  label: (args) => args.filename ? `Process ${args.filename}` : "Process File",
  isEnabled: (args) => Boolean(args.filename),
  isVisible: (args) => Boolean(args.canProcess)
});

// Execute with different arguments
await registry.execute("dynamic-command", { 
  filename: "document.txt", 
  canProcess: true 
});

import { CommandRegistry } from "@lumino/commands";

const registry = new CommandRegistry();
let documentModified = false;

registry.addCommand("save-document", {
  execute: () => {
    console.log("Saving document...");
    documentModified = false;
    // Notify that command state has changed
    registry.notifyCommandChanged("save-document");
    return Promise.resolve();
  },
  label: "Save Document",
  isEnabled: () => documentModified,
  iconClass: () => documentModified ? "fa fa-save" : "fa fa-save disabled"
});

// Simulate document modification
documentModified = true;
registry.notifyCommandChanged("save-document");

// Now the save command will be enabled
await registry.execute("save-document");

import { CommandRegistry } from "@lumino/commands";

const registry = new CommandRegistry();

// Add multiple commands
const disposables = [
  registry.addCommand("cut", { execute: () => console.log("Cut") }),
  registry.addCommand("copy", { execute: () => console.log("Copy") }),
  registry.addCommand("paste", { execute: () => console.log("Paste") })
];

// List all registered commands
console.log(registry.listCommands()); // ["cut", "copy", "paste"]

// Check if commands exist
console.log(registry.hasCommand("cut")); // true
console.log(registry.hasCommand("undo")); // false

// Clean up all commands
disposables.forEach(d => d.dispose());
console.log(registry.listCommands()); // []

type CommandFunc<T> = (args: ReadonlyPartialJSONObject) => T;
type Dataset = { readonly [key: string]: string };
type Description = { args: ReadonlyJSONObject | null };