I love it! 🙌 Question about dollar-sign prefixes

[Tomburgs]

After using lexical for a brief moment I fell in love with it.
It's so nice & easy to understand which cannot be said about many other text editor frameworks.

I only have one question — why opt for using dollar-sign ($) prefixes for so many of the util functions? e.g $getRoot & $getSelection

I don't have anything in particular against them. I know there's other projects who utilize them as well, but there's typically a reason. For example styletron uses them for props that shouldn't be applied to the dom element. In case of lexical I could not figure it out. Is it purely a style choice?

Keep up the good work, and keep the documentation coming! 💜

[amyworrall]

It’s for methods that need to be called within a read or update block (since they rely on getActiveEditor() etc)

[zurfyx]

To expand on the why:

Originally, Lexical didn't have $ functions, instead these functions were provided to you through callback params:

// Mid 2020 API
editor.update((viewState) => {
  const getRoot = viewState.getRoot();
  ..
});
editor.addTextTransform((viewState) => {
  const getRoot = viewState.getRoot();
  ..
});

Internally, this approach raised some negative feedback:

1. The viewState terminology was confusing. It wasn't really a viewState, more like a toolkit to manipulate the EditorState
2. For complex updates and transforms devs had to carry params around on many layers

This is when we decided to leverage the "lexical" scope instead to perform EditorState manipulation, and the $ represents just that.

editor.update(() => ...);
editor.registerNodeTransform(FooNode, () => ...); 
editor.getEditorState().read(...);

^ In the above 3 where I added the ... you can use $ functions. The first 2 can read and write from the EditorState and the last can only read but ultimately the 3 of them are manipulating the EditorState. Furthermore, the use of $ functions makes it possible to manipulate an internally mutable EditorState that is seemingly immutable to the user (since you will only ever retrieve an immutable EditorState after the reconciliation has completed - through registerUpdateListener)

Additionally, the $ functions can extend beyond the functionality provided by the lexical package. If you've used React before they resemble hooks to certain extend.

A function of your own that uses a $ functions becomes a $ function to represent that it touches the EditorState, this becomes very intuitive to read and understand where you can use these functions. For example:

function $getFirstRootChild(): null | LexicalNode {
  const root = $getRoot();
  return root.getFirstChild();
}

Lastly, why the $? It's the most intuitive we could come up with and short - the second is particularly important because that's where most of your Lexical code will live.

[Tomburgs]

Thank you so much for this thorough explanation!