Skip to main content

@lexical/y

Classes​

YBinding​

Defined in: packages/lexical-y/src/internal/Binding.ts:1078

Experimental

A Yjs 14 binding for one editor and one shared root.

Every container (the root, and every node stored as its own Y.Node) holds one sequence of text, child nodes and line markers; see the package README for the layout.

Warnings (read only states, recoveries, the opt-in self-check) go to the editor's onWarn, typed by their code (see YWarning and isYWarning), once a remote change has been applied in full: never from inside a Yjs observer or transaction. A handler that throws does not affect syncing.

Constructors​

Constructor​

new YBinding(editor, doc, options): YBinding

Defined in: packages/lexical-y/src/internal/Binding.ts:1578

Experimental

Parameters​
editor​

LexicalEditor

doc​

YDoc

options​

YBindingOptions

Returns​

YBinding

Accessors​

doc​
Get Signature​

get doc(): YDoc

Defined in: packages/lexical-y/src/internal/Binding.ts:1509

Experimental

The shared document.

Returns​

YDoc

editor​
Get Signature​

get editor(): LexicalEditor

Defined in: packages/lexical-y/src/internal/Binding.ts:1504

Experimental

The bound editor.

Returns​

LexicalEditor

pins​
Get Signature​

get pins(): ReadonlyMap<string, { by?: readonly string[]; kind: StorageKind; }>

Defined in: packages/lexical-y/src/internal/Binding.ts:1524

Experimental

Storage kinds the document records per node type (see the README).

Returns​

ReadonlyMap<string, { by?: readonly string[]; kind: StorageKind; }>

root​
Get Signature​

get root(): YNode

Defined in: packages/lexical-y/src/internal/Binding.ts:1514

Experimental

The shared root this binding reads and writes.

Returns​

YNode

status​
Get Signature​

get status(): YBindingStatus

Defined in: packages/lexical-y/src/internal/Binding.ts:1519

Experimental

See YBindingStatus; onStatus reports changes.

Returns​

YBindingStatus

undoManager​
Get Signature​

get undoManager(): UndoManager | null

Defined in: packages/lexical-y/src/internal/Binding.ts:1532

Experimental

The collaborative undo manager; null when undo is disabled.

Returns​

UndoManager | null

Methods​

$resolveCursor()​

$resolveCursor(cursor): { anchor: PointType; focus: PointType; } | null

Defined in: packages/lexical-y/src/internal/Binding.ts:8388

Experimental

Resolve a cursor to Lexical points (call inside a read or update).

Parameters​
cursor​

YCursor

Returns​

{ anchor: PointType; focus: PointType; } | null

dispose()​

dispose(): void

Defined in: packages/lexical-y/src/internal/Binding.ts:2349

Experimental

Disconnect from the document and the editor (start returns this).

Returns​

void

getCursor()​

getCursor(): YCursor | null

Defined in: packages/lexical-y/src/internal/Binding.ts:8150

Experimental

The local selection as relative positions (JSON), or null. While a remote change is not read yet, the positions are taken in a Yjs transaction that changes nothing (the document's transaction observers see it), or in the one running; called again from that transaction's observers, it returns the positions it just took.

Returns​

YCursor | null

initialize()​

initialize(): void

Defined in: packages/lexical-y/src/internal/Binding.ts:2430

Experimental

Call after the provider's first sync. An empty root is marked with this layout and gets the editor's current content, unless an older layout's root (root, root-v2) has content: such a document is read only, and must be converted instead (a binding with convert: true writes the layout root next to the old one). Anything else is read.

The initial content (including an update still pending, such as editor.update(seed) right before this call) is not part of the undo history. It is written once, under a client id derived from those exact bytes (see seedUpdate), applied to the document as they are and read back like any document, so that two clients initializing the same document with the same content at once write the same items (one copy), and one id never holds two payloads. That holds for a root inside another shared type and for a root that held content, deleted since, as for a new document.

Called before start() (from an extension's register, before YCollabExtension starts the binding), it runs when the binding starts, once the editor has its initial state.

Returns​

void

quiesce()​

quiesce(): YQuiescedState

Defined in: packages/lexical-y/src/internal/Binding.ts:2260

Experimental

EXPERIMENTAL. Hand this replica off (D102, the recovery handoff before a client replaces a document its server migrated). Ends an IME composition and commits what the editor holds (an update not committed yet, the binding's own pending work) into the document as ordinary local writes, so it gets Yjs identities; then turns the binding read only for good, local and programmatic edits included (they are not written, and the editor shows the document again). Returns a YQuiescedState.

  • Stop the app's providers and persistence first: what they deliver after the handoff is not in the returned state.
  • Call it outside an editor update (inside one it throws, and changes nothing).
  • A binding already read only (for any reason) ends the composition and drains the editor's pending work too, but writes nothing: what the editor held uncommitted is the draft, with differs.
  • Calling it again, before or after dispose(), writes nothing and returns a copy of the first call's result: the same state and the same draft, differs included (a batched update the first call could not write stays in the draft, though the editor no longer shows it). It recomputes nothing: what was written to the document since is not in it.
  • Called first after dispose(), it writes nothing either: it returns the document's state and the editor's state as the draft.
  • The draft is the editor state's JSON (what a quarantine record stores): a NodeState value is as JSON.stringify writes it (a Date is its ISO string), in every result. Before draining, it checks that the pending and the shown editor states serialize as JSON: a failure there (a BigInt NodeState value, a cycle) throws a TypeError without draining or quiescing. If app code makes the state unserializable during the drain (an update listener's update), the final serialization throws a TypeError after local work may have been written and the composition ended, and nothing is cached: fix the state and call it again, and don't assume earlier edit callbacks did not run.
  • Every result, the first included, is its own copy (the state's bytes, the draft parsed again): changing one changes no other. A warning handler or status listener that calls it during the first call gets that call's result.
Returns​

YQuiescedState

redo()​

redo(): boolean

Defined in: packages/lexical-y/src/internal/Binding.ts:7791

Experimental

Redo what undo undid; see undo.

Returns​

boolean

start()​

start(): () => void

Defined in: packages/lexical-y/src/internal/Binding.ts:1624

Experimental

Start listening; read the document if it is already initialized.

Returns​

() => void

undo()​

undo(): boolean

Defined in: packages/lexical-y/src/internal/Binding.ts:7786

Experimental

Undo this client's last change in the document (collaborative undo). Returns whether there was one; false while the binding is not active.

Returns​

boolean

YUnsupportedYjsError​

Defined in: packages/lexical-y/src/internal/YjsContract.ts:346

Experimental

Thrown by createYDoc, by the YBinding constructor (so by YCollabExtension) and by the headless helpers when the @y/y the app runs is not the one @lexical/y supports, before anything is written. Fix: install exactly @y/y@<data.supported>, once per app. There is no way to turn the check off.

Extends​

Constructors​

Constructor​

new YUnsupportedYjsError(data): YUnsupportedYjsError

Defined in: packages/lexical-y/src/internal/YjsContract.ts:349

Experimental

Parameters​
data​

YUnsupportedYjsData

Returns​

YUnsupportedYjsError

Overrides​

Error.constructor

Properties​

cause?​

optional cause?: unknown

Defined in: typescript/lib/lib.es2022.error.d.ts:24

Experimental

Inherited from​

Error.cause

code​

readonly code: "@lexical/y/unsupported-yjs"

Defined in: packages/lexical-y/src/internal/YjsContract.ts:347

Experimental

data​

readonly data: YUnsupportedYjsData

Defined in: packages/lexical-y/src/internal/YjsContract.ts:348

Experimental

message​

message: string

Defined in: typescript/lib/lib.es5.d.ts:1075

Experimental

Inherited from​

Error.message

name​

name: string

Defined in: typescript/lib/lib.es5.d.ts:1074

Experimental

Inherited from​

Error.name

stack?​

optional stack?: string

Defined in: typescript/lib/lib.es5.d.ts:1076

Experimental

Inherited from​

Error.stack

stackTraceLimit​

static stackTraceLimit: number

Defined in: @types/node/globals.d.ts:67

Experimental

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from​

Error.stackTraceLimit

Methods​

captureStackTrace()​

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: @types/node/globals.d.ts:51

Experimental

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters​
targetObject​

object

constructorOpt?​

Function

Returns​

void

Inherited from​

Error.captureStackTrace

isError()​

static isError(error): error is Error

Defined in: typescript/lib/lib.esnext.error.d.ts:21

Experimental

Indicates whether the argument provided is a built-in Error instance or not.

Parameters​
error​

unknown

Returns​

error is Error

Inherited from​

Error.isError

prepareStackTrace()​

static prepareStackTrace(err, stackTraces): any

Defined in: @types/node/globals.d.ts:55

Experimental

Parameters​
err​

Error

stackTraces​

CallSite[]

Returns​

any

See​

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from​

Error.prepareStackTrace

Interfaces​

YBindingOptions​

Defined in: packages/lexical-y/src/internal/Binding.ts:744

Experimental

Options of YBinding (and YCollabExtension).

Properties​

captureTimeout?​

optional captureTimeout?: number | null

Defined in: packages/lexical-y/src/internal/Binding.ts:756

Experimental

Undo capture timeout in ms (default 500); null disables undo.

clientIDRange?​

optional clientIDRange?: ClientIDRange

Defined in: packages/lexical-y/src/internal/Binding.ts:802

Experimental

The range of the document's client ids: 'uint53' (default, Yjs 14's ids, left as they are) or 'uint32' (kept in 32 bits, for servers on yrs before 0.28; see ClientIDRange).

convert?​

optional convert?: boolean

Defined in: packages/lexical-y/src/internal/Binding.ts:785

Experimental

Initialize even when an older layout's root has content: for a converter writing the layout root of an existing document.

layoutUpgrade?​

optional layoutUpgrade?: YLayoutUpgradeHandle | null

Defined in: packages/lexical-y/src/internal/Binding.ts:796

Experimental

How documents below MIN_LAYOUT are upgraded (see y.md "Layout upgrades"): a handle from createYServerLayoutUpgrade (the document's server migrates them on load) or null (they stay read only). The binding behaves the same with either: a document below the floor is read only until it is migrated, and the 'older' warning says which was declared (upgrade). Left out (plain JavaScript, or a config written without createYCollabConfig), such a document also brings UNSUPPORTED_CONFIG_WARNING 'missing-layout-upgrade'.

onStatus?​

optional onStatus?: (status) => void

Defined in: packages/lexical-y/src/internal/Binding.ts:762

Experimental

Called when status changes, once the binding's work is done and Yjs is idle (like warnings, never inside a Yjs observer or transaction). Several changes in one such step report the last.

Parameters​
status​

YBindingStatus

Returns​

void

root?​

optional root?: YNode<any>

Defined in: packages/lexical-y/src/internal/Binding.ts:754

Experimental

The shared root to bind; defaults to doc.get('lexical-y').

schemaVersion​

schemaVersion: number

Defined in: packages/lexical-y/src/internal/Binding.ts:752

Experimental

The version of your editor's nodes: registered node classes, their fields and NodeState. Bump it when you add, remove or change one, not on every release. Required: start at 1. The document records the highest version that wrote to it; a binding whose version is lower opens it read only (UNSUPPORTED_SCHEMA_WARNING). An integer from 1.

selfCheck?​

optional selfCheck?: boolean

Defined in: packages/lexical-y/src/internal/Binding.ts:773

Experimental

Read every line a local write touched back from Yjs and compare it with the editor; mismatches are reported to the editor's onWarn (see SELF_CHECK_WARNING). Structural changes (and remote changes) also compare a fresh read of the whole container: every time for containers of up to 256 lines and nodes, and with probability 256 / size for bigger ones, so the expected cost of an edit stays bounded. Default: off. A debugging aid: turn it on in tests and development builds to catch binding bugs.

selfCheckSample?​

optional selfCheckSample?: number

Defined in: packages/lexical-y/src/internal/Binding.ts:780

Experimental

The fraction of changes the self-check samples (default 1): of local writes, and of remote changes, where a sampled check that finds the editor differing from the shared content also reads those containers again (see selfCheck).

YClientSession​

Defined in: packages/lexical-y/src/internal/LayoutUpgrade.ts:30

Experimental

What a client sends before any sync message (see checkYSession).

Properties​

generation​

readonly generation: string | null

Defined in: packages/lexical-y/src/internal/LayoutUpgrade.ts:32

Experimental

The generation its material was made against, null when it has none.

material​

readonly material: boolean

Defined in: packages/lexical-y/src/internal/LayoutUpgrade.ts:34

Experimental

Whether it holds material: unsent edits or a cached state.

YCollabConfig​

Defined in: packages/lexical-y/src/internal/YExtension.ts:84

Experimental

The configuration of YCollabExtension (what configExtension takes, partially, and what the extension reads). Its existing fields stay as they are, and every field a later release adds to it is optional, with its default resolved inside the extension: a complete YCollabConfig written today keeps compiling. New code configures the extension with createYCollabConfig and YCollabInput.

Properties​

captureTimeout​

captureTimeout: number | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:109

Experimental

Undo capture timeout in ms; null disables collaborative undo.

clientIDRange​

clientIDRange: ClientIDRange

Defined in: packages/lexical-y/src/internal/YExtension.ts:111

Experimental

See YBindingOptions.clientIDRange (default 'uint53').

convert​

convert: boolean

Defined in: packages/lexical-y/src/internal/YExtension.ts:120

Experimental

See YBindingOptions.convert (default false).

doc​

doc: YDoc | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:89

Experimental

The shared document, made by createYDoc (with a stored state: createYDoc(state)). Required.

layoutUpgrade?​

optional layoutUpgrade?: YLayoutUpgradeHandle | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:126

Experimental

See YCollabInput.layoutUpgrade. Left out (a config written without createYCollabConfig), a document below MIN_LAYOUT is read only and also brings UNSUPPORTED_CONFIG_WARNING 'missing-layout-upgrade'.

root​

root: YNode<any> | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:101

Experimental

The shared root; defaults to doc.get('lexical-y').

schemaVersion​

schemaVersion: number

Defined in: packages/lexical-y/src/internal/YExtension.ts:99

Experimental

The version of your editor's nodes: registered node classes, their fields and NodeState. Bump it when you add, remove or change one, not on every release. Required: start at 1. The document records the highest version that wrote to it, and a client whose version is lower opens it read only (UNSUPPORTED_SCHEMA_WARNING), so an out-of-date client never edits content it cannot read in full. An integer from 1; the extension throws without one.

selfCheck​

selfCheck: boolean | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:116

Experimental

See YBindingOptions.selfCheck; null keeps the default (off). Warnings go to the editor's onWarn.

selfCheckSample​

selfCheckSample: number | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:118

Experimental

See YBindingOptions.selfCheckSample; null keeps the default (1).

synced​

synced: boolean

Defined in: packages/lexical-y/src/internal/YExtension.ts:107

Experimental

Initialize as soon as the binding starts: use it when the document is already synced (a headless writer, a converter, tests). Otherwise call binding.initialize() after the provider's first sync.

YCollabInput​

Defined in: packages/lexical-y/src/internal/YExtension.ts:51

Experimental

What an app writes to configure YCollabExtension through createYCollabConfig: doc, layoutUpgrade and schemaVersion are required, and every option that has a default is optional, so a later release adds options without breaking code typed with it.

Properties​

captureTimeout?​

readonly optional captureTimeout?: number | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:69

Experimental

clientIDRange?​

readonly optional clientIDRange?: ClientIDRange

Defined in: packages/lexical-y/src/internal/YExtension.ts:70

Experimental

convert?​

readonly optional convert?: boolean

Defined in: packages/lexical-y/src/internal/YExtension.ts:73

Experimental

doc​

readonly doc: YDoc

Defined in: packages/lexical-y/src/internal/YExtension.ts:53

Experimental

See YCollabConfig.doc.

layoutUpgrade​

readonly layoutUpgrade: YLayoutUpgradeHandle | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:60

Experimental

Required: how documents below MIN_LAYOUT are upgraded (see y.md "Layout upgrades"). createYServerLayoutUpgrade(): the document's server migrates them on load; null: they stay read only. The editor opens such a document read only either way.

root?​

readonly optional root?: YNode<any> | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:67

Experimental

schemaVersion​

readonly schemaVersion: number

Defined in: packages/lexical-y/src/internal/YExtension.ts:66

Experimental

The version of your editor's nodes: registered node classes, their fields and NodeState. Bump it when you add, remove or change one, not on every release. An integer from 1 (see YCollabConfig.schemaVersion).

selfCheck?​

readonly optional selfCheck?: boolean | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:71

Experimental

selfCheckSample?​

readonly optional selfCheckSample?: number | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:72

Experimental

synced?​

readonly optional synced?: boolean

Defined in: packages/lexical-y/src/internal/YExtension.ts:68

Experimental

YCursor​

Defined in: packages/lexical-y/src/internal/Binding.ts:824

Experimental

A selection as Yjs relative positions, from YBinding#getCursor (for an awareness-based cursor UI).

Properties​

anchor​

anchor: unknown

Defined in: packages/lexical-y/src/internal/Binding.ts:825

Experimental

focus​

focus: unknown

Defined in: packages/lexical-y/src/internal/Binding.ts:826

Experimental

YDoc​

Defined in: packages/lexical-y/src/internal/RawYDoc.ts:44

Experimental

A Y.Doc made by createYDoc: Yjs's format cleanup is off from its creation, so applying an update to it never deletes format items of its own accord.

Extends​

Properties​

_item​

_item: any

Defined in: @y/y/dist/src/utils/Doc.d.ts:66

Experimental

If this document is a subdocument - a document integrated into another document - then _item is defined.

Inherited from​

Doc._item

_observers​

_observers: Map<string, Set<any>>

Defined in: lib0/dist/observable.d.ts:15

Experimental

Some desc.

Inherited from​

Doc._observers

_transaction​

_transaction: any

Defined in: @y/y/dist/src/utils/Doc.d.ts:53

Experimental

Inherited from​

Doc._transaction

_transactionCleanups​

_transactionCleanups: Transaction[]

Defined in: @y/y/dist/src/utils/Doc.d.ts:57

Experimental

Inherited from​

Doc._transactionCleanups

[createdByCreateYDoc]​

readonly [createdByCreateYDoc]: true

Defined in: packages/lexical-y/src/internal/RawYDoc.ts:46

Experimental

Phantom brand: only createYDoc makes a YDoc.

$type​

$type: Schema<Doc>

Defined in: @y/y/dist/src/utils/Doc.d.ts:140

Experimental

Inherited from​

Doc.$type

autoLoad​

autoLoad: boolean

Defined in: @y/y/dist/src/utils/Doc.d.ts:68

Experimental

Inherited from​

Doc.autoLoad

cleanupFormatting​

cleanupFormatting: boolean

Defined in: @y/y/dist/src/utils/Doc.d.ts:44

Experimental

Inherited from​

Doc.cleanupFormatting

clientID​

clientID: number

Defined in: @y/y/dist/src/utils/Doc.d.ts:40

Experimental

Inherited from​

Doc.clientID

collectionid​

collectionid: string | null

Defined in: @y/y/dist/src/utils/Doc.d.ts:42

Experimental

Inherited from​

Doc.collectionid

gc​

gc: boolean

Defined in: @y/y/dist/src/utils/Doc.d.ts:38

Experimental

Inherited from​

Doc.gc

gcFilter​

gcFilter: (arg0) => boolean

Defined in: @y/y/dist/src/utils/Doc.d.ts:39

Experimental

Parameters​
arg0​

Item

Returns​

boolean

Inherited from​

Doc.gcFilter

guid​

guid: string

Defined in: @y/y/dist/src/utils/Doc.d.ts:41

Experimental

Inherited from​

Doc.guid

isDestroyed​

isDestroyed: boolean

Defined in: @y/y/dist/src/utils/Doc.d.ts:85

Experimental

Inherited from​

Doc.isDestroyed

isLoaded​

isLoaded: boolean

Defined in: @y/y/dist/src/utils/Doc.d.ts:76

Experimental

This is set to true when the persistence provider loaded the document from the database or when the sync event fires. Note that not all providers implement this feature. Provider authors are encouraged to fire the load event when the doc content is loaded from the database.

Inherited from​

Doc.isLoaded

isSuggestionDoc​

isSuggestionDoc: boolean

Defined in: @y/y/dist/src/utils/Doc.d.ts:43

Experimental

Inherited from​

Doc.isSuggestionDoc

isSynced​

isSynced: boolean

Defined in: @y/y/dist/src/utils/Doc.d.ts:84

Experimental

This is set to true when the connection provider has successfully synced with a backend. Note that when using peer-to-peer providers this event may not provide very useful. Also note that not all providers implement this feature. Provider authors are encouraged to fire the sync event when the doc has been synced (with true as a parameter) or if connection is lost (with false as a parameter).

Inherited from​

Doc.isSynced

meta​

meta: any

Defined in: @y/y/dist/src/utils/Doc.d.ts:69

Experimental

Inherited from​

Doc.meta

share​

share: Map<string, YNode<any>>

Defined in: @y/y/dist/src/utils/Doc.d.ts:48

Experimental

Inherited from​

Doc.share

shouldLoad​

shouldLoad: boolean

Defined in: @y/y/dist/src/utils/Doc.d.ts:67

Experimental

Inherited from​

Doc.shouldLoad

store​

store: StructStore

Defined in: @y/y/dist/src/utils/Doc.d.ts:49

Experimental

Inherited from​

Doc.store

subdocs​

subdocs: Set<Doc>

Defined in: @y/y/dist/src/utils/Doc.d.ts:61

Experimental

Inherited from​

Doc.subdocs

whenLoaded​

whenLoaded: Promise<any>

Defined in: @y/y/dist/src/utils/Doc.d.ts:89

Experimental

Promise that resolves once the document has been loaded from a persistence provider.

Inherited from​

Doc.whenLoaded

whenSynced​

whenSynced: Promise<any>

Defined in: @y/y/dist/src/utils/Doc.d.ts:90

Experimental

Inherited from​

Doc.whenSynced

Methods​

destroy()​

destroy(): void

Defined in: lib0/dist/observable.d.ts:45

Experimental

Returns​

void

Inherited from​

Doc.destroy

emit()​

emit<NAME>(name, args): void

Defined in: lib0/dist/observable.d.ts:44

Experimental

Emit a named event. All registered event listeners that listen to the specified name will receive the event.

Type Parameters​
NAME​

NAME extends "load" | "update" | "sync" | "destroy" | "updateV2" | "beforeAllTransactions" | "beforeTransaction" | "beforeObserverCalls" | "afterTransaction" | "afterTransactionCleanup" | "afterAllTransactions" | "subdocs"

Parameters​
name​

NAME

The event name.

args​

Parameters<DocEvents[NAME]>

The arguments that are applied to the event listener.

Returns​

void

Todo​

This should catch exceptions

Inherited from​

Doc.emit

get()​

get(key?, name?): YNode

Defined in: @y/y/dist/src/utils/Doc.d.ts:128

Experimental

Define a shared data type.

Multiple calls of ydoc.get(name) yield the same result and do not overwrite each other. I.e. ydoc.get(name) === ydoc.get(name)

After this method is called, the type is also available on ydoc.share.get(name).

Parameters​
key?​

string

name?​

string | null

Type-name

Returns​

YNode

Inherited from​

Doc.get

getSubdocGuids()​

getSubdocGuids(): Set<string>

Defined in: @y/y/dist/src/utils/Doc.d.ts:100

Experimental

Returns​

Set<string>

Inherited from​

Doc.getSubdocGuids

getSubdocs()​

getSubdocs(): Set<Doc>

Defined in: @y/y/dist/src/utils/Doc.d.ts:99

Experimental

Returns​

Set<Doc>

Inherited from​

Doc.getSubdocs

load()​

load(): void

Defined in: @y/y/dist/src/utils/Doc.d.ts:98

Experimental

Notify the parent document that you request to load data into this subdocument (if it is a subdocument).

load() might be used in the future to request any provider to load the most current data.

It is safe to call load() multiple times.

Returns​

void

Inherited from​

Doc.load

off()​

off<NAME>(name, f): void

Defined in: lib0/dist/observable.d.ts:33

Experimental

Type Parameters​
NAME​

NAME extends "load" | "update" | "sync" | "destroy" | "updateV2" | "beforeAllTransactions" | "beforeTransaction" | "beforeObserverCalls" | "afterTransaction" | "afterTransactionCleanup" | "afterAllTransactions" | "subdocs"

Parameters​
name​

NAME

f​

DocEvents[NAME]

Returns​

void

Inherited from​

Doc.off

on()​

on<NAME>(name, f): DocEvents[NAME]

Defined in: lib0/dist/observable.d.ts:21

Experimental

Type Parameters​
NAME​

NAME extends "load" | "update" | "sync" | "destroy" | "updateV2" | "beforeAllTransactions" | "beforeTransaction" | "beforeObserverCalls" | "afterTransaction" | "afterTransactionCleanup" | "afterAllTransactions" | "subdocs"

Parameters​
name​

NAME

f​

DocEvents[NAME]

Returns​

DocEvents[NAME]

Inherited from​

Doc.on

once()​

once<NAME>(name, f): void

Defined in: lib0/dist/observable.d.ts:27

Experimental

Type Parameters​
NAME​

NAME extends "load" | "update" | "sync" | "destroy" | "updateV2" | "beforeAllTransactions" | "beforeTransaction" | "beforeObserverCalls" | "afterTransaction" | "afterTransactionCleanup" | "afterAllTransactions" | "subdocs"

Parameters​
name​

NAME

f​

DocEvents[NAME]

Returns​

void

Inherited from​

Doc.once

toJSON()​

toJSON(): object

Defined in: @y/y/dist/src/utils/Doc.d.ts:137

Experimental

Converts the entire document into a js object, recursively traversing each yjs type Doesn't log types that have not been defined (using ydoc.getType(..)).

Returns​

object

Deprecated​

Do not use this method and rather call toJSON directly on the shared types.

Inherited from​

Doc.toJSON

transact()​

transact<T>(f, origin?, local?): T

Defined in: @y/y/dist/src/utils/Doc.d.ts:113

Experimental

Changes that happen inside of a transaction are bundled. This means that the observer fires after the transaction is finished and that all changes that happened inside of the transaction are sent as one message to the other peers.

Type Parameters​
T​

T

Parameters​
f​

(arg0) => T

The function that should be executed as a transaction

origin?​

any

Origin of who started the transaction. Will be stored on transaction.origin

local?​

boolean

Returns​

T

T

Inherited from​

Doc.transact

YLayoutUpgradeHandle​

Defined in: packages/lexical-y/src/internal/LayoutUpgrade.ts:47

Experimental

How documents below MIN_LAYOUT are upgraded, for layoutUpgrade (made by createYServerLayoutUpgrade; null declares that such documents stay read only). Open on purpose: kind names the strategy ('server', the only one this release makes: the document's server migrates it on load) and later releases may add kinds and fields. The binding behaves the same with any handle (a document below the floor is read only until it is migrated); the handle says what the app declared, in the 'older' warning, and builds the session handshake.

Properties​

[LAYOUT_UPGRADE]​

readonly [LAYOUT_UPGRADE]: true

Defined in: packages/lexical-y/src/internal/LayoutUpgrade.ts:48

Experimental

kind​

readonly kind: string

Defined in: packages/lexical-y/src/internal/LayoutUpgrade.ts:50

Experimental

The strategy: 'server'.

Methods​

handshake()​

handshake(session): YSessionHandshake

Defined in: packages/lexical-y/src/internal/LayoutUpgrade.ts:56

Experimental

The complete handshake a client sends before any sync message (checkYSession): this release's layouts, seed layout and features, with the session's generation and material.

Parameters​
session​

YClientSession

Returns​

YSessionHandshake

YMigrationEpoch​

Defined in: packages/lexical-y/src/internal/Layouts.ts:44

Experimental

What a migration records under lexical-y-epoch (see @lexical/y/migrate): the transition that last changed the root. Each field has one job:

  • layout is the destination: the layout the document is in after the migration (from 1).
  • step plus revision is the receipt: which frozen step, at which immutable revision, wrote it (step is an opaque, namespaced id such as lexical-y/layout/1to2: readers never parse it).
  • client and clock identify the migration's first written item: the transition identity the generation (generationOf) uses.
  • kind names the family: 'layout' for a layout migration, the only one this release writes. A missing kind reads as 'layout'; readers keep any other as a label.
  • schema, when present, names an app schema and its version.

Readers accept fields they do not know and keep them in the document; an epoch of another format version (v), or one whose known fields are not well formed, closes writes (read only), as a malformed layout record does.

Properties​

client​

readonly client: number

Defined in: packages/lexical-y/src/internal/Layouts.ts:48

Experimental

clock​

readonly clock: number

Defined in: packages/lexical-y/src/internal/Layouts.ts:49

Experimental

kind​

readonly kind: string

Defined in: packages/lexical-y/src/internal/Layouts.ts:46

Experimental

layout​

readonly layout: number

Defined in: packages/lexical-y/src/internal/Layouts.ts:47

Experimental

revision​

readonly revision: number

Defined in: packages/lexical-y/src/internal/Layouts.ts:51

Experimental

schema?​

readonly optional schema?: object

Defined in: packages/lexical-y/src/internal/Layouts.ts:52

Experimental

id​

readonly id: string

version​

readonly version: number

step​

readonly step: string

Defined in: packages/lexical-y/src/internal/Layouts.ts:50

Experimental

v​

readonly v: 1

Defined in: packages/lexical-y/src/internal/Layouts.ts:45

Experimental

YOtherWarningData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:146

Experimental

The data every code may carry besides its own variants: a condition a later version reports under an existing code, detailCode naming it (with optional details). Permanent: a switch over a code's reason handles 'other', so a new condition never breaks it.

Properties​

detailCode​

readonly detailCode: string

Defined in: packages/lexical-y/src/internal/Warnings.ts:148

Experimental

details?​

readonly optional details?: unknown

Defined in: packages/lexical-y/src/internal/Warnings.ts:149

Experimental

reason​

readonly reason: "other"

Defined in: packages/lexical-y/src/internal/Warnings.ts:147

Experimental

YQuiescedState​

Defined in: packages/lexical-y/src/internal/Binding.ts:812

Experimental

What YBinding.quiesce() returns: the document's state (pending updates included), to hand to the server, and a draft, the editor's state as JSON taken before it turned read only, with differs when the editor shows something the document does not hold (a local change the binding could not write).

Properties​

draft​

readonly draft: object

Defined in: packages/lexical-y/src/internal/Binding.ts:814

Experimental

differs​

readonly differs: boolean

json​

readonly json: SerializedEditorState

state​

readonly state: Uint8Array

Defined in: packages/lexical-y/src/internal/Binding.ts:813

Experimental

YRawYjsWriteData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:431

Experimental

data of a RAW_YJS_WRITE_WARNING (development builds).

Properties​

key​

readonly key: string | null

Defined in: packages/lexical-y/src/internal/Warnings.ts:441

Experimental

kind​

readonly kind: "format" | "attribute" | "content"

Defined in: packages/lexical-y/src/internal/Warnings.ts:440

Experimental

What the transaction changed first under the root: a text format ('format', key its name), a node attribute ('attribute', key its name) or other content ('content', key null).

origin​

readonly origin: string

Defined in: packages/lexical-y/src/internal/Warnings.ts:443

Experimental

The transaction origin's constructor name ('null' for none).

reason​

readonly reason: "raw-write"

Defined in: packages/lexical-y/src/internal/Warnings.ts:432

Experimental

root​

readonly root: string

Defined in: packages/lexical-y/src/internal/Warnings.ts:434

Experimental

The binding's root, by its name in the document ('lexical-y').

YRecoveredReadData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:368

Experimental

data of a RECOVERED_READ_WARNING: a remote change ('remote-change') or a read of the binding's own ('reread') threw error, and the editor was rebuilt from the document.

Properties​

error​

readonly error: unknown

Defined in: packages/lexical-y/src/internal/Warnings.ts:370

Experimental

reason​

readonly reason: "remote-change" | "reread"

Defined in: packages/lexical-y/src/internal/Warnings.ts:369

Experimental

YRecoveredWriteData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:377

Experimental

data of a RECOVERED_WRITE_WARNING: writing a local change threw error, and the document was rewritten from the editor.

Properties​

error​

readonly error: unknown

Defined in: packages/lexical-y/src/internal/Warnings.ts:379

Experimental

reason​

readonly reason: "local-change"

Defined in: packages/lexical-y/src/internal/Warnings.ts:378

Experimental

YSelfCheckData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:358

Experimental

data of a SELF_CHECK_WARNING: the self-check found the editor and the document disagree after a local change ('local') or a remote one ('remote', read again in full).

Properties​

problems​

readonly problems: readonly string[]

Defined in: packages/lexical-y/src/internal/Warnings.ts:360

Experimental

reason​

readonly reason: "local" | "remote"

Defined in: packages/lexical-y/src/internal/Warnings.ts:359

Experimental

YStoredAs​

Defined in: packages/lexical-y/src/internal/Warnings.ts:237

Experimental

How the document stores a node type, or how a class would.

Properties​

by?​

readonly optional by?: readonly string[]

Defined in: packages/lexical-y/src/internal/Warnings.ts:240

Experimental

A group's or format's identity: the fields it merges by.

kind​

readonly kind: "format" | "nested" | "line" | "group"

Defined in: packages/lexical-y/src/internal/Warnings.ts:238

Experimental

YUnknownNodeTypesData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:269

Experimental

data of an UNKNOWN_NODE_TYPES_WARNING (the binding is read only): types the editor does not register ('unregistered'), or slots the document holds that are not a block node ('malformed-slot': the slot's key, or the type of the inline node in it).

Properties​

reason​

readonly reason: "unregistered" | "malformed-slot"

Defined in: packages/lexical-y/src/internal/Warnings.ts:270

Experimental

types​

readonly types: readonly string[]

Defined in: packages/lexical-y/src/internal/Warnings.ts:271

Experimental

YUnreadableContentData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:283

Experimental

data of an UNKNOWN_NODE_TYPES_WARNING whose reason is 'unreadable' (the binding is read only): stored content the editor's classes throw on when they read it (its importJSON or updateFromJSON, a NodeState parse), of types, with the first error thrown. The editor shows the rest of the document. types is empty, and the editor keeps what it showed before and reads nothing more, where a read failed without a class to name (it threw again on a fresh read of the document).

Properties​

error​

readonly error: unknown

Defined in: packages/lexical-y/src/internal/Warnings.ts:286

Experimental

reason​

readonly reason: "unreadable"

Defined in: packages/lexical-y/src/internal/Warnings.ts:284

Experimental

types​

readonly types: readonly string[]

Defined in: packages/lexical-y/src/internal/Warnings.ts:285

Experimental

YUnsupportedSlotsData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:295

Experimental

data of an UNSUPPORTED_SLOTS_WARNING (the change is not written and the binding is read only): types hold named slots on a node stored as a line, a format or a group ('stored-host'), or on the root ('root').

Properties​

reason​

readonly reason: "root" | "stored-host"

Defined in: packages/lexical-y/src/internal/Warnings.ts:296

Experimental

types​

readonly types: readonly string[]

Defined in: packages/lexical-y/src/internal/Warnings.ts:297

Experimental

YUnsupportedYjsData​

Defined in: packages/lexical-y/src/internal/YjsContract.ts:326

Experimental

The data of YUnsupportedYjsError.

Properties​

found​

readonly found: readonly string[]

Defined in: packages/lexical-y/src/internal/YjsContract.ts:335

Experimental

What the check found instead: for 'changed-internals', each missing or changed part of the contract ('getItemCleanStart', 'Item#parentSub', 'UndoManager@stack-cleared'); for 'other-copy', what came from the other copy.

reason​

readonly reason: YUnsupportedYjsReason

Defined in: packages/lexical-y/src/internal/YjsContract.ts:336

Experimental

supported​

readonly supported: string

Defined in: packages/lexical-y/src/internal/YjsContract.ts:328

Experimental

The exact @y/y version this @lexical/y supports.

YUnsyncedValueData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:451

Experimental

data of an UNSYNCED_VALUE_WARNING: property ('<type>.<field>' or 'NodeState <key>') holds a value that is not plain JSON, so it is not synchronized.

Properties​

property​

readonly property: string

Defined in: packages/lexical-y/src/internal/Warnings.ts:453

Experimental

reason​

readonly reason: "not-json"

Defined in: packages/lexical-y/src/internal/Warnings.ts:452

Experimental

Type Aliases​

ClientIDRange​

ClientIDRange = "uint53" | "uint32"

Defined in: packages/lexical-y/src/internal/ClientID.ts:25

Experimental

The range of the client ids a document writes with.

  • 'uint53': Yjs 14's default (random 53-bit ids).
  • 'uint32': ids that fit in 32 bits, for servers that read client ids as 32-bit numbers (yrs before 0.28, e.g. y-crdt relays on 0.23): with a 53-bit id, such a server stores the author's content under a truncated id, and the author receives its own content back as another client's on reconnect, duplicating the document.

StorageKind​

StorageKind = "line" | "format" | "group" | "nested"

Defined in: packages/lexical-y/src/internal/Schema.ts:270

Experimental

How @lexical/y stores an element type; see describeStorage.

YBindingStatus​

YBindingStatus = "pending" | "active" | "readonly"

Defined in: packages/lexical-y/src/internal/Binding.ts:725

Experimental

The state of a YBinding.

YDocOptions​

YDocOptions = ConstructorParameters<typeof Doc>[0]

Defined in: packages/lexical-y/src/internal/RawYDoc.ts:50

Experimental

The options of new Y.Doc(options).

YNestedFallbackData​

YNestedFallbackData = { method: string; reason: "merge-override"; type: string; } | { properties: readonly string[]; reason: "undeclared-properties"; type: string; } | { reason: Exclude<YNestedFallbackReason, "merge-override" | "undeclared-properties">; type: string; }

Defined in: packages/lexical-y/src/internal/Warnings.ts:409

Experimental

data of a NESTED_FALLBACK_WARNING.

YNestedFallbackReason​

YNestedFallbackReason = "merge-override" | "inline-slots" | "inline-incomplete-schema" | "type-name" | "merge-incomplete-schema" | "merge-slots" | "group-children" | "group-state-merge" | "group-incomplete-schema" | "undeclared-properties"

Defined in: packages/lexical-y/src/internal/Warnings.ts:386

Experimental

Why a class type whose declarations make it a line, a format or a group is stored as a nested node.

YStorageMismatchData​

YStorageMismatchData = { found: unknown; key: string; reason: "malformed"; type: string; } | { declared: YStoredAs; reason: "declaration-changed"; stored: YStoredAs; type: string; }

Defined in: packages/lexical-y/src/internal/Warnings.ts:247

Experimental

data of a STORAGE_MISMATCH_WARNING (the binding is read only), one per node type.

Union Members​

Type Literal​

{ found: unknown; key: string; reason: "malformed"; type: string; }

The record at key for type is not a storage record.

Type Literal​

{ declared: YStoredAs; reason: "declaration-changed"; stored: YStoredAs; type: string; }

The class of type cannot be stored as the document stores it.

YUnsupportedConfigData​

YUnsupportedConfigData = { options: readonly string[]; reason: "repair-transforms"; } | { reason: "cleanup-formatting"; } | { reason: "missing-layout-upgrade"; }

Defined in: packages/lexical-y/src/internal/Warnings.ts:304

Experimental

data of an UNSUPPORTED_CONFIG_WARNING (nothing is written and the binding is read only), one warning per reason.

Union Members​

Type Literal​

{ options: readonly string[]; reason: "repair-transforms"; }

options ('<extension>.<option>') are set to a value the binding cannot write with.

Type Literal​

{ reason: "cleanup-formatting"; }

The document runs Yjs's format cleanup (doc.cleanupFormatting is not false): it was not made by createYDoc.

Type Literal​

{ reason: "missing-layout-upgrade"; }

No layoutUpgrade was declared (a config written without createYCollabConfig, or plain JavaScript), and the document is below MIN_LAYOUT: read only, as with layoutUpgrade: null. Sent with the 'older' layout warning.

YUnsupportedEditData​

YUnsupportedEditData = { reason: "read-only"; } | { reason: "refused-at-write"; record: "layout" | "schema"; } | { reason: "held-composition"; }

Defined in: packages/lexical-y/src/internal/Warnings.ts:337

Experimental

data of an UNSUPPORTED_EDIT_WARNING, a local change that was not written:

  • 'read-only': the binding is read only (code edited the editor, which is not editable); an earlier warning says why.
  • 'refused-at-write': the binding is active, but as the change was written the root's record ('layout': the layout record, or the epoch or a feature requirement; 'schema': a schema record) did not admit writes. It changed in the same transaction (an app's, or a remote update a provider applied while the editor was updating). Not retried; the binding may stay active (when the record is put back), so this is not a read-only state.

Union Members​

Type Literal​

{ reason: "read-only"; }

Type Literal​

{ reason: "refused-at-write"; record: "layout" | "schema"; }

Type Literal​

{ reason: "held-composition"; }

While the binding is active: a local change that would delete or leave behind text a collaborator wrote in the line being composed with an IME, which the composition holds back until it ends (it moves, replaces or removes what holds that text, or takes text out of the inline element composed in). Nothing is written, the editor reads the document again (the change is undone), and the composition goes on; edit again.

YUnsupportedLayoutData​

YUnsupportedLayoutData = { found: number; reason: "newer"; supported: number; } | { found: unknown; key: string; reason: "malformed"; supported: number; } | { reason: "missing" | "removed"; supported: number; } | { found: number; min: number; reason: "older"; supported: number; upgrade: "server" | "read-only" | string & object; } | { features: readonly string[]; reason: "requires"; supported: number; } | { reason: "legacy-roots"; roots: readonly string[]; supported: number; }

Defined in: packages/lexical-y/src/internal/Warnings.ts:157

Experimental

data of an UNSUPPORTED_LAYOUT_WARNING (the binding is read only). supported: the newest layout this version reads (it reads 1 to supported).

Union Members​

Type Literal​

{ found: number; reason: "newer"; supported: number; }

The layout record names a newer layout, found.

Type Literal​

{ found: unknown; key: string; reason: "malformed"; supported: number; }

The record at key is not a layout record; found is its value.

Type Literal​

{ reason: "missing" | "removed"; supported: number; }

The root has content, or records such as an epoch, but no layout record ('missing'), or the record was removed while the binding was writing ('removed').

Type Literal​

{ found: number; min: number; reason: "older"; supported: number; upgrade: "server" | "read-only" | string & object; }

The root records layout found, older than min, the oldest this version reads (MIN_LAYOUT): migrate the document (see @lexical/y/migrate). A document below the floor is an expected state for an app whose server migrates: handle this reason in onWarn (its development default throws).

found​

readonly found: number

min​

readonly min: number

reason​

readonly reason: "older"

supported​

readonly supported: number

upgrade​

readonly upgrade: "server" | "read-only" | string & object

What the app declared (layoutUpgrade): 'server' (its server upgrades such documents, so this one should have been migrated) or 'read-only' (none, or not declared). A later release may add kinds.

Type Literal​

{ features: readonly string[]; reason: "requires"; supported: number; }

The root requires features this version does not support, features (lexical-y-require:<feature>): shown, kept, never rewritten.

Type Literal​

{ reason: "legacy-roots"; roots: readonly string[]; supported: number; }

Older layouts' roots, roots, hold content.

YUnsupportedSchemaData​

YUnsupportedSchemaData = { found: number; reason: "newer"; supported: number; } | { found: unknown; key: string; reason: "malformed"; supported: number; }

Defined in: packages/lexical-y/src/internal/Warnings.ts:217

Experimental

data of an UNSUPPORTED_SCHEMA_WARNING (the binding is read only). supported: the binding's schemaVersion.

Union Members​

Type Literal​

{ found: number; reason: "newer"; supported: number; }

A client whose schemaVersion is found, higher than supported, wrote to the document: the app is out of date (render your own banner, such as one that asks to reload).

Type Literal​

{ found: unknown; key: string; reason: "malformed"; supported: number; }

The record at key is not a schema record; found is its value.

YUnsupportedYjsReason​

YUnsupportedYjsReason = "changed-internals" | "other-copy"

Defined in: packages/lexical-y/src/internal/YjsContract.ts:323

Experimental

Why YUnsupportedYjsError refused:

  • 'changed-internals': the @y/y the app loaded is not the supported version: exports, members or events the binding uses are missing or changed (data.found names them).
  • 'other-copy': the document comes from another copy of @y/y than the one @lexical/y loaded, so the binding's instanceof checks on its items would fail.

YWarning​

YWarning<C> = LexicalWarning & object

Defined in: packages/lexical-y/src/internal/Warnings.ts:493

Experimental

A warning the binding passes to the editor's onWarn: a LexicalWarning whose code decides the type of its data. YWarning (any code) is open: its data is unknown until narrowed. Narrow it with isYWarning(value, code), which gives YWarning<code>, then switch over data.reason, 'other' included.

Type Declaration​

code​

readonly code: C

data​

readonly data: YWarningData<C>

Type Parameters​

C​

C extends string = YWarningCode

YWarningCode​

YWarningCode = YKnownWarningCode | string & object

Defined in: packages/lexical-y/src/internal/Warnings.ts:138

Experimental

A warning code: one this version reports (an editor completes them) or one a later version adds. Open on purpose: handle the codes you know, with isYWarning(value, code), and keep a fallback for the others.

YWarningData​

YWarningData<C> = C extends YKnownWarningCode ? YWarningDataByCode[C] | YOtherWarningData : unknown

Defined in: packages/lexical-y/src/internal/Warnings.ts:477

Experimental

The data of the warnings with code C: its variants (and YOtherWarningData) for a code this version knows, unknown for another.

Type Parameters​

C​

C extends string = string

Variables​

DEFAULT_ROOT_NAME​

const DEFAULT_ROOT_NAME: "lexical-y" = 'lexical-y'

Defined in: packages/lexical-y/src/internal/constants.ts:17

Experimental

The default name of the shared root, which @lexical/yjs clients never write to (they use root and root-v2).

LAYOUT_VERSION​

const LAYOUT_VERSION: number = 3

Defined in: packages/lexical-y/src/internal/constants.ts:37

Experimental

The newest layout version this binding reads and writes. A new document records version 1; the first member entry of a set-valued NodeState written into a document also records 2 (clients that only read version 1 then open it read only instead of missing the members).

MIN_LAYOUT​

const MIN_LAYOUT: number = 3

Defined in: packages/lexical-y/src/internal/constants.ts:50

Experimental

The oldest layout version this binding reads and writes: layout 3 only (paired format runs). A root below it binds read only (UNSUPPORTED_LAYOUT_WARNING, 'older') until it is migrated (see @lexical/y/migrate, @lexical/y/migrate/2to3); the migration runner's default target.

NESTED_FALLBACK_WARNING​

const NESTED_FALLBACK_WARNING: "@lexical/y/nested-fallback" = '@lexical/y/nested-fallback'

Defined in: packages/lexical-y/src/internal/Warnings.ts:50

Experimental

A class whose declarations make it a line, a format or a group is stored as a nested node. Once per class and reason. data: YNestedFallbackData.

RAW_YJS_WRITE_WARNING​

const RAW_YJS_WRITE_WARNING: "@lexical/y/raw-yjs-write" = '@lexical/y/raw-yjs-write'

Defined in: packages/lexical-y/src/internal/Warnings.ts:107

Experimental

Development builds only: a local transaction that is not the binding's (nor a Y.UndoManager's, nor a migration's) changed the Yjs content under the binding's root. The encoding under the root is private to the binding and unsupported for direct writes: change the document through the editor (or editYState). Once per binding and origin; nothing else happens (the binding reads the change as it reads a remote one). A diagnostic, not a complete detector: it judges a transaction by its origin and locality, and only once the binding has read its document (not while it is pending), so a raw write made through a provider-like remote update, or before the binding reads, is not reported. A transaction the binding also wrote in (an editor edit, initialize() or binding.undo() inside an app's doc.transact, which joins it) is not checked either, so an app's raw write in that same transaction goes unreported: it may miss a raw write, never report the binding's own. data: YRawYjsWriteData.

RECOVERED_READ_WARNING​

const RECOVERED_READ_WARNING: "@lexical/y/recovered-read" = '@lexical/y/recovered-read'

Defined in: packages/lexical-y/src/internal/Warnings.ts:39

Experimental

A change could not be read: the editor was rebuilt from the document. data: YRecoveredReadData.

RECOVERED_WRITE_WARNING​

const RECOVERED_WRITE_WARNING: "@lexical/y/recovered-write" = '@lexical/y/recovered-write'

Defined in: packages/lexical-y/src/internal/Warnings.ts:44

Experimental

A local change could not be written: the document was rewritten from the editor. data: YRecoveredWriteData.

SEED_LAYOUT​

const SEED_LAYOUT: number = IDENTITY_LAYOUT_VERSION

Defined in: packages/lexical-y/src/internal/constants.ts:59

Experimental

The layout a new document's seed records (written by initialize() and seedYState): what a client sends as seed in the handshake of @lexical/y/server, so an authority admits a seeder of a pristine room only at its own seed layout (D22).

SELF_CHECK_WARNING​

const SELF_CHECK_WARNING: "@lexical/y/self-check" = '@lexical/y/self-check'

Defined in: packages/lexical-y/src/internal/Warnings.ts:34

Experimental

The self-check (selfCheck, off by default) found the editor and the document disagree. data: YSelfCheckData.

STORAGE_MISMATCH_WARNING​

const STORAGE_MISMATCH_WARNING: "@lexical/y/storage-mismatch" = '@lexical/y/storage-mismatch'

Defined in: packages/lexical-y/src/internal/Warnings.ts:29

Experimental

The document stores a node type in a way its class cannot be stored: read only. data: YStorageMismatchData.

SUPPORTED_YJS_VERSION​

const SUPPORTED_YJS_VERSION: string = '14.0.0-rc.29'

Defined in: packages/lexical-y/src/internal/SupportedYjs.ts:17

Experimental

The one @y/y version this @lexical/y supports: its exact peer dependency. YUnsupportedYjsError reports it as data.supported.

UNKNOWN_NODE_TYPES_WARNING​

const UNKNOWN_NODE_TYPES_WARNING: "@lexical/y/unknown-node-types" = '@lexical/y/unknown-node-types'

Defined in: packages/lexical-y/src/internal/Warnings.ts:24

Experimental

The document has node types the editor cannot build, or stored content its classes throw on: read only. data: YUnknownNodeTypesData, or YUnreadableContentData.

UNSUPPORTED_CONFIG_WARNING​

const UNSUPPORTED_CONFIG_WARNING: "@lexical/y/unsupported-config" = '@lexical/y/unsupported-config'

Defined in: packages/lexical-y/src/internal/Warnings.ts:66

Experimental

The editor or the document is configured in a way the binding cannot write with: nothing is written, read only. data: YUnsupportedConfigData.

UNSUPPORTED_EDIT_WARNING​

const UNSUPPORTED_EDIT_WARNING: "@lexical/y/unsupported-edit" = '@lexical/y/unsupported-edit'

Defined in: packages/lexical-y/src/internal/Warnings.ts:82

Experimental

A local change was not written; what it changed is read again (once the document cannot be read, the editor shows what it showed before the update again), so the editor keeps showing the document. data: YUnsupportedEditData, with three reasons:

  • 'read-only': the binding is read only (code edited the editor, which is not editable). Reported once each time the binding goes read only.
  • 'refused-at-write': the binding is active, but the write's own transaction changed the layout or schema record (record). Reported for each such write; it promises nothing about the binding's later status.
  • 'held-composition': the binding is active, and the change would delete or leave behind text a collaborator wrote in the line being composed, which the composition holds back. Reported for each such change.

UNSUPPORTED_LAYOUT_WARNING​

const UNSUPPORTED_LAYOUT_WARNING: "@lexical/y/unsupported-layout" = '@lexical/y/unsupported-layout'

Defined in: packages/lexical-y/src/internal/Warnings.ts:18

Experimental

The document's layout is one this version cannot read or write: read only. data: YUnsupportedLayoutData.

UNSUPPORTED_SCHEMA_WARNING​

const UNSUPPORTED_SCHEMA_WARNING: "@lexical/y/unsupported-schema" = '@lexical/y/unsupported-schema'

Defined in: packages/lexical-y/src/internal/Warnings.ts:88

Experimental

A client of a newer version of the app (a higher schemaVersion) wrote to the document: read only. data: YUnsupportedSchemaData.

UNSUPPORTED_SLOTS_WARNING​

const UNSUPPORTED_SLOTS_WARNING: "@lexical/y/unsupported-slots" = '@lexical/y/unsupported-slots'

Defined in: packages/lexical-y/src/internal/Warnings.ts:60

Experimental

A node holds named slots where the document cannot store them: not written, read only. data: YUnsupportedSlotsData.

UNSUPPORTED_YJS_ERROR​

const UNSUPPORTED_YJS_ERROR: "@lexical/y/unsupported-yjs" = '@lexical/y/unsupported-yjs'

Defined in: packages/lexical-y/src/internal/YjsContract.ts:312

Experimental

The code of YUnsupportedYjsError.

UNSYNCED_VALUE_WARNING​

const UNSYNCED_VALUE_WARNING: "@lexical/y/unsynced-value" = '@lexical/y/unsynced-value'

Defined in: packages/lexical-y/src/internal/Warnings.ts:55

Experimental

A node property or NodeState value is not plain JSON, so it is not synchronized. Once per property. data: YUnsyncedValueData.

YCollabExtension​

const YCollabExtension: LexicalExtension<YCollabConfig, "@lexical/y/Collab", { binding: YBinding; status: ReadonlySignal<YBindingStatus>; }, unknown>

Defined in: packages/lexical-y/src/internal/YExtension.ts:161

Experimental

Binds the editor to a Yjs 14 document with the block-marker layout, and provides collaborative undo (UNDO_COMMAND / REDO_COMMAND, CAN_UNDO_COMMAND / CAN_REDO_COMMAND). Its output has the binding and a status signal ('pending' until the layout record is read, then 'active' or 'readonly'). It conflicts with the history extensions.

The binding starts once the editor has its initial state: after every extension has registered, and after InitialStateExtension has applied $initialEditorState. That state is only ever the content of an empty document (initialize() writes it there; called while extensions register, it runs when the binding starts). On a document that has content, the editor shows the document. An extension that depends on this one and changes content in its own afterRegistration makes an edit.

Functions​

createYCollabConfig()​

createYCollabConfig(input): NormalizedLexicalExtensionArgument<YCollabConfig, "@lexical/y/Collab", { binding: YBinding; status: ReadonlySignal<YBindingStatus>; }, unknown>

Defined in: packages/lexical-y/src/internal/YExtension.ts:136

Experimental

The configured YCollabExtension, for an editor's dependencies: createYCollabConfig({doc, schemaVersion, layoutUpgrade}). The way to configure the extension: its input type requires every decision the app must make (layoutUpgrade included), and options a later release adds are optional.

Parameters​

input​

YCollabInput

Returns​

NormalizedLexicalExtensionArgument<YCollabConfig, "@lexical/y/Collab", { binding: YBinding; status: ReadonlySignal<YBindingStatus>; }, unknown>

createYDoc()​

createYDoc(state?, options?): YDoc

Defined in: packages/lexical-y/src/internal/YDoc.ts:34

Experimental

A Y.Doc for @lexical/y: a client's (YCollabExtension's doc), or a relay's or server's that loads a document's state (to store, compact or merge it). Yjs's format cleanup is turned off (cleanupFormatting = false) before anything is applied to it: applying an update to a document with it on deletes format items the binding keeps, and the document then reads differently from its peers once someone types there. state, a stored state, is applied when given; options are those of new Y.Doc(options) (the default document is garbage collected, as clients store one). Merging updates with mergeUpdates needs no document. Throws a YUnsupportedYjsError, before the document is made, when the @y/y the app loaded is not the one @lexical/y supports.

Parameters​

state?​

Uint8Array<ArrayBufferLike> | null

options?​

DocOpts

Returns​

YDoc

createYServerLayoutUpgrade()​

createYServerLayoutUpgrade(): YLayoutUpgradeHandle

Defined in: packages/lexical-y/src/internal/LayoutUpgrade.ts:82

Experimental

Declare that the document's server upgrades documents below MIN_LAYOUT (it migrates them on load, see y-server.md): the handle for layoutUpgrade. Its handshake() builds the session handshake, so an app never assembles one by hand.

Returns​

YLayoutUpgradeHandle

describeStorage()​

describeStorage(editor, binding?): Record<string, StorageKind | "text">

Defined in: packages/lexical-y/src/internal/Describe.ts:30

Experimental

How @lexical/y stores each node type: 'line', 'format', 'group' or 'nested' for elements (derived from the classes' $config() declarations, or the kind a document recorded when binding is given), 'text' for text and line breaks, 'nested' for decorators. The root is left out.

Parameters​

editor​

LexicalEditor

binding?​
pins​

ReadonlyMap<string, { kind: StorageKind; }>

Returns​

Record<string, StorageKind | "text">

isYLayoutUpgradeHandle()​

isYLayoutUpgradeHandle(value): value is YLayoutUpgradeHandle

Defined in: packages/lexical-y/src/internal/LayoutUpgrade.ts:95

Experimental

Whether value is a layout upgrade handle (any copy's): the brand, a non-empty kind and a handshake function. A handle declares what the app expects and builds the handshake; it is not proof that a server is wired to migrate.

Parameters​

value​

unknown

Returns​

value is YLayoutUpgradeHandle

isYWarning()​

Call Signature​

isYWarning<C>(value, code): value is YWarning<C>

Defined in: packages/lexical-y/src/internal/Warnings.ts:527

Experimental

Whether value (what the editor's onWarn receives) is a warning of the binding's: with code, one with that code, its data typed by it; without, any of its codes (an open YWarning).

Type Parameters​
C​

C extends YKnownWarningCode

Parameters​
value​

unknown

code​

C

Returns​

value is YWarning<C>

Call Signature​

isYWarning(value): value is YWarning<YWarningCode>

Defined in: packages/lexical-y/src/internal/Warnings.ts:531

Experimental

Whether value (what the editor's onWarn receives) is a warning of the binding's: with code, one with that code, its data typed by it; without, any of its codes (an open YWarning).

Parameters​
value​

unknown

Returns​

value is YWarning<YWarningCode>

onYMigrationEpoch()​

onYMigrationEpoch(doc, fn, root?): () => void

Defined in: packages/lexical-y/src/internal/Layouts.ts:248

Experimental

Call fn once every transaction listener of a transaction that changed root's epoch (a migration) has run, an UndoManager's capture included (in afterAllTransactions). The hook for an app's own UndoManagers: clear them there, since their stacks name items the migration replaced (the binding clears its own). fn gets the epoch, null when it is malformed. root: a root's name (default 'lexical-y') or the root itself. Returns a function that stops listening.

Parameters​

doc​

Doc

fn​

(epoch) => void

root?​

string | YNode<any>

Returns​

() => void