BlockSuite API Documentation / @blocksuite/block-std / CommandManager

Class: CommandManager

Command manager to manage all commands

Commands are functions that take a context and a next function as arguments

const myCommand: Command<'count', 'count'> = (ctx, next) => {
 const count = ctx.count || 0;

 const success = someOperation();
 if (success) {
   return next({ count: count + 1 });
 }
 // if the command is not successful, you can return without calling next
 return;

You should always add the command to the global interface BlockSuite.Commands

declare global {
  namespace BlockSuite {
    interface Commands {
      'myCommand': typeof myCommand
    }
  }
}

Command input and output data can be defined in the Command type

// input: ctx.firstName, ctx.lastName
// output: ctx.fullName
const myCommand: Command<'firstName' | 'lastName', 'fullName'> = (ctx, next) => {
  const { firstName, lastName } = ctx;
  const fullName = `${firstName} ${lastName}`;
  return next({ fullName });
}

declare global {
  namespace BlockSuite {
    interface CommandContext {
      // All command input and output data should be defined here
      // The keys should be optional
      firstName?: string;
      lastName?: string;
      fullName?: string;
    }
  }
}

---

Commands can be run in two ways:

1. Using exec method exec is used to run a single command

const { success, ...data } = commandManager.exec('myCommand', payload);

2. Using chain method chain is used to run a series of commands

const chain = commandManager.chain();
const [result, data] = chain
  .myCommand1()
  .myCommand2(payload)
  .run();

---

Command chains will stop running if a command is not successful

const chain = commandManager.chain();
const [result, data] = chain
  .myCommand1() <-- if this fail
  .myCommand2(payload) <- this won't run
  .run();

result <- result will be `false`

You can use try to run a series of commands and if one of them is successful, it will continue to the next command

const chain = commandManager.chain();
const [result, data] = chain
  .try(chain => [
    chain.myCommand1(), <- if this fail
    chain.myCommand2(), <- this will run, if this success
    chain.myCommand3(), <- this won't run
  ])
  .run();

The tryAll method is similar to try, but it will run all commands even if one of them is successful

const chain = commandManager.chain();
const [result, data] = chain
  .try(chain => [
    chain.myCommand1(), <- if this success
    chain.myCommand2(), <- this will also run
    chain.myCommand3(), <- so will this
  ])
  .run();

Extends

• LifeCycleWatcher

Constructors

new CommandManager()

new CommandManager(std): CommandManager

Parameters

std

BlockStdScope

Returns

CommandManager

Inherited from

LifeCycleWatcher.constructor

Defined in

packages/framework/block-std/src/extension/lifecycle-watcher.ts:30

Properties

std

readonly std: BlockStdScope

Inherited from

LifeCycleWatcher.std

Defined in

packages/framework/block-std/src/extension/lifecycle-watcher.ts:30

---

key

readonly static key: "commandManager" = 'commandManager'

Overrides

LifeCycleWatcher.key

Defined in

packages/framework/block-std/src/command/manager.ts:130

Methods

add()

add<N>(name, command): CommandManager

Register a command to the command manager

Type Parameters

• N extends keyof Commands

Parameters

name

N

command

Commands[N]

Make sure to also add the command to the global interface BlockSuite.Commands

const myCommand: Command = (ctx, next) => {
  // do something
}

declare global {
  namespace BlockSuite {
    interface Commands {
      'myCommand': typeof myCommand
    }
  }
}

Returns

CommandManager

Defined in

packages/framework/block-std/src/command/manager.ts:302

---

chain()

chain(): Chain<InitCommandCtx>

Create a chain to run a series of commands

const chain = commandManager.chain();
const [result, data] = chain
  .myCommand1()
  .myCommand2(payload)
  .run();

Returns

Chain<InitCommandCtx>

[success, data] - success is a boolean to indicate if the chain is successful, data is the final context after running the chain

Defined in

packages/framework/block-std/src/command/manager.ts:261

---

created()

created(): void

Called when std is created.

Returns

void

Overrides

LifeCycleWatcher.created

Defined in

packages/framework/block-std/src/command/manager.ts:312

---

exec()

exec<K>(command, ...payloads): ExecCommandResult<K> & object

Execute a registered command by name

Type Parameters

• K extends keyof Commands

Parameters

command

K

payloads

...IfAllKeysOptional<Omit<InDataOfCommand<Commands[K]>, "std">, [void | Omit<InDataOfCommand<Commands[K]>, "std">], [Omit<InDataOfCommand<Commands[K]>, "std">]>

const { success, ...data } = commandManager.exec('myCommand', { data: 'data' });

Returns

ExecCommandResult<K> & object

• success is a boolean to indicate if the command is successful, data is the final context after running the command

Defined in

packages/framework/block-std/src/command/manager.ts:329

---

mounted()

mounted(): void

Called when editor host is mounted. Which means the editor host emit the connectedCallback lifecycle event.

Returns

void

Inherited from

LifeCycleWatcher.mounted

Defined in

packages/framework/block-std/src/extension/lifecycle-watcher.ts:60

---

rendered()

rendered(): void

Called when std.render is called.

Returns

void

Inherited from

LifeCycleWatcher.rendered

Defined in

packages/framework/block-std/src/extension/lifecycle-watcher.ts:65

---

unmounted()

unmounted(): void

Called when editor host is unmounted. Which means the editor host emit the disconnectedCallback lifecycle event.

Returns

void

Inherited from

LifeCycleWatcher.unmounted

Defined in

packages/framework/block-std/src/extension/lifecycle-watcher.ts:71

---

setup()

static setup(di): void

Parameters

di

Container

Returns

void

Inherited from

LifeCycleWatcher.setup

Defined in

packages/framework/block-std/src/extension/lifecycle-watcher.ts:34