Typed commands

[zurfyx]

I'd like to add to #1412 and #1511 to propose a type-safe approach.

Problem:

Commands are currently heavily error-prone:

1. You can misspell the type and it will silently never trigger in your app
2. You can misinterpret the types

Part of this problem is caused by the ability to listen to multiple commands at once.

Proposal

Encourage type safety within Lexical core and user-created commands. Make it so that you can only listen to a specific command at once and
this command is strictly type safe and provided by Lexical core.

execCommand<T>(type: Command<T>, payload: T): void;
registerCommand<T>(type: Command<T>, payload: (T) => void): void;

class Command<T> {
  type: string;
  constructor(type: string) {
    this.type = type;
  }
}
const formatTextCommand = new Command<string>('formatText');
new LexicalEditor().execCommand(formatTextCommand, 'bold');
new LexicalEditor().registerCommand(formatTextCommand, (format) => {
  // bold
});

The generic type above, while seemingly unused, enables us to offer type safety for the payload.

[Optionally] We can do like transforms where we check for the command reference to ensure that we're strictly referring to the same command, in which case we don't even need the type.

class Command<T> {}
const formatTextCommand = new Command<string>();

Trade-offs

(+) It's type safe
(-) It's more costly, we have to provide an instance for every single command
(-) It more verbose, especially for some Lexical core/React. For most internal/real-life usages it should be equivalent though.

[amyworrall]

On iOS we do this:

public struct CommandType: RawRepresentable {
  public var rawValue: String
  public init(rawValue: String) {
    self.rawValue = rawValue
  }
  static let selectionChange = CommandType(rawValue: "selectionChange")
  static let click = CommandType(rawValue: "click")
  static let deleteCharacter = CommandType(rawValue: "deleteCharacter")
  static let insertLineBreak = CommandType(rawValue: "insertLineBreak")
  static let insertParagraph = CommandType(rawValue: "insertParagraph")
  ...
}

Then anyone can add their own commands by doing:

extension struct CommandType {
  static let myCommand = CommandType(rawValue: "myCommand")
}

and to use them, the type is CommandType, and the IDE will happily autocomplete .deleteCharacter or whatever.

[trueadm]

I like the idea, however I don't think we need to use classes for it.

import type {LexicalCommand} from 'lexical;
import {createCommand} from 'lexical';

const InsertTextCommand: LexicalCommand<string> = createCommand();

…

editor.dispatchCommand(InsertTextCommand);
editor.registerCommand(InsertTextCommand, (text: string) => {
 ...
}, Priority);

So it looks and feels a bit more like React Context.

[thegreatercurve]

Good idea! A union of enums should work in Flow and TS as well. We can then export the default commands:

export enum LexicalDefaultCommands {
    InsertText = 'InsertText'
}

enum UserDefinedCommands {
    Foo = 'Foo'
}

function registerCommandHandler<T, P>(type: LexicalDefaultCommands | T, callback: (payload: P) => void) {}
function execCommand<T, P>(type: LexicalDefaultCommands | T, payload: P) {}

registerCommandHandler(UserDefinedCommands.Foo, () => {})
execCommand(LexicalDefaultCommands.InsertText, '')

[trueadm]

We can't use enums unfortunately, open source Lexical should work without them (we strip out types) and also I couldn't get Flow enums working at all!

[trueadm]

How you might type this pattern in TS/Flow:

// From Lexical:

// eslint-disable-next-line no-unused-vars
type LexicalCommand<P> = {};

export function createCommand<P>(): LexicalCommand<P> {
  // Maybe we can avoid this with a FlowFixMe? seems expensive otherwise
  return Object.freeze({});
}

export function dispatchCommand<P>(command: LexicalCommand<P>, payload: P): boolean;

export function registerCommand<P>(command: LexicalCommand<P>, callback: (P) => boolean): () => void;

// In App code:

const InsertTextCommand = createCommand<string>();

editor.dispatchCommand(InsertTextCommand, 'Hello world');

editor.registerCommand(InsertTextCommand, (text: string) => {
  // Type safe!
})

[thegreatercurve]

The issue I'm having with implementing some of the above approaches is then re-implementing the types into LexicalEditor. For example in the listeners:

type Listeners<C> = {
  command: Map<LexicalCommand<C>, Array<Set<CommandListener>>>,
};

class LexicalEditor<C> {
  _listeners: Listeners<C>;
}

Will we require the user to have to define their custom command types when they instantiate the lexical editor? If so, it probably adds quite a bit of extra overhead, and we run into issues with using values as types from createCommand

[trueadm]

Let's avoid adding a generic to the Editor, for now just stick with Listeners<>? It's only for internal use, so we don't need the same level of type safety there.