@lexical/y/migrate

Classes

YMigrationError

Defined in: packages/lexical-y/src/internal/Runner.ts:177

Experimental

A migration refused or failed. Nothing was written: the caller's document and stored state are as they were.

Extends

• Error

Constructors

Constructor

new YMigrationError(code, message, problems?, root?): YMigrationError

Defined in: packages/lexical-y/src/internal/Runner.ts:183

Experimental

Parameters

code

YMigrationErrorCode

message

string

problems?

readonly string[] = []

root?

string | null

Returns

YMigrationError

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: YMigrationErrorCode

Defined in: packages/lexical-y/src/internal/Runner.ts:178

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

problems

readonly problems: readonly string[]

Defined in: packages/lexical-y/src/internal/Runner.ts:180

Experimental

Every problem found (for 'post-condition', every failed check).

root

readonly root: string | null

Defined in: packages/lexical-y/src/internal/Runner.ts:182

Experimental

The root concerned, null when the whole document is.

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

YLayoutMigration

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

Experimental

A frozen layout migration step: one root from layout from to from + 1, in place (see @lexical/y/migrate). The runner owns the traversal and calls the step per container (the root, nested containers, attribute-held types). Pure (no clock, randomness, app code, binding or editor) and frozen: it imports @y/y and its own copies of what it reads and writes, never the live binding. Any change to what it writes bumps revision.

Properties

from

readonly from: number

Defined in: packages/lexical-y/src/internal/Runner.ts:96

Experimental

The layout the step migrates from.

id

readonly id: string

Defined in: packages/lexical-y/src/internal/Runner.ts:92

Experimental

lexical-y/layout/<from>to<to>.

revision

readonly revision: number

Defined in: packages/lexical-y/src/internal/Runner.ts:94

Experimental

From 1; bumped on any change to what the step writes (hashed into the client).

to

readonly to: number

Defined in: packages/lexical-y/src/internal/Runner.ts:98

Experimental

from + 1, always.

v

readonly v: 1

Defined in: packages/lexical-y/src/internal/Runner.ts:90

Experimental

The execution contract the step is written against: 1, the methods below as this runner calls them. A runner refuses a step of a version it does not run before calling anything ('invalid-steps').

Methods

checkAfter()

checkAfter(container): readonly string[]

Defined in: packages/lexical-y/src/internal/Runner.ts:125

Experimental

The target layout's own invariants on one migrated container (problems; none: empty), so a step that only stamps the record cannot pass on equal reads.

Parameters

container

YNode

Returns

readonly string[]

migrateContainer()

migrateContainer(tr, container): void | { deleted: number; written: number; }

Defined in: packages/lexical-y/src/internal/Runner.ts:106

Experimental

Migrate one container's own sequence, inside the runner's transaction on an observer-free copy (the runner records the layout before the first container and the epoch after the last). Returns nothing, or what it wrote and deleted (informational and ignored: the receipt counts the transaction).

Parameters

tr

Transaction

container

YNode

Returns

void | { deleted: number; written: number; }

readAfter()

readAfter(container): readonly string[]

Defined in: packages/lexical-y/src/internal/Runner.ts:119

Experimental

Frozen read of layout to, in the same shape as readBefore.

Parameters

container

YNode

Returns

readonly string[]

readBefore()

readBefore(container): readonly string[]

Defined in: packages/lexical-y/src/internal/Runner.ts:117

Experimental

Frozen read of layout from: one normalized string per live countable unit of the container's own sequence, in order (each UTF-16 code unit of a string item, each embed or type item once). Compared with readAfter of the result unit by unit, so item splits and merges do not matter.

Parameters

container

YNode

Returns

readonly string[]

rewrites()

rewrites(key): boolean

Defined in: packages/lexical-y/src/internal/Runner.ts:130

Experimental

The format keys the step rewrites. Every other format item, and every attribute, is untouched.

Parameters

key

string

Returns

boolean

---

YLoadYMigrationStepsOptions

Defined in: packages/lexical-y/src/migrate.ts:43

Experimental

Options of loadYMigrationSteps (a later version may add some).

Properties

loaders?

readonly optional loaders?: YMigrationLoaders

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

Experimental

One loader per layout (() => import(...)); default: the published steps.

---

YMigrateOptions

Defined in: packages/lexical-y/src/internal/Runner.ts:253

Experimental

Options of migrateYDoc.

Extended by

• YMigrateStateOptions

Properties

clientID?

readonly optional clientID?: (input) => number

Defined in: packages/lexical-y/src/internal/Runner.ts:273

Experimental

An allocator of guaranteed-unique client ids, one per step run (default: the hash of the inputs). Its id must not be one the document holds.

Parameters

input

YMigrationStepInput

Returns

number

clientIDRange?

readonly optional clientIDRange?: ClientIDRange

Defined in: packages/lexical-y/src/internal/Runner.ts:268

Experimental

The range of the hashed client ids (default 'uint53'; 'uint32' for servers that read client ids as 32-bit numbers).

roots?

readonly optional roots?: readonly string[]

Defined in: packages/lexical-y/src/internal/Runner.ts:258

Experimental

The roots to migrate (default ['lexical-y']), run sorted by name and de-duplicated. Each must have a layout record or be pristine.

to?

readonly optional to?: number

Defined in: packages/lexical-y/src/internal/Runner.ts:263

Experimental

The layout to migrate to (default: MIN_LAYOUT of this build, so only roots below the floor migrate).

---

YMigrateStateOptions

Defined in: packages/lexical-y/src/internal/Runner.ts:277

Experimental

Options of migrateYState.

Extends

• YMigrateOptions

Properties

clientID?

readonly optional clientID?: (input) => number

Defined in: packages/lexical-y/src/internal/Runner.ts:273

Experimental

An allocator of guaranteed-unique client ids, one per step run (default: the hash of the inputs). Its id must not be one the document holds.

Parameters

input

YMigrationStepInput

Returns

number

Inherited from

YMigrateOptions.clientID

clientIDRange?

readonly optional clientIDRange?: ClientIDRange

Defined in: packages/lexical-y/src/internal/Runner.ts:268

Experimental

The range of the hashed client ids (default 'uint53'; 'uint32' for servers that read client ids as 32-bit numbers).

Inherited from

YMigrateOptions.clientIDRange

gc?

readonly optional gc?: boolean

Defined in: packages/lexical-y/src/internal/Runner.ts:282

Experimental

Yjs garbage collection of the document (default true, as clients store one): must equal the authority's stored documents' setting.

roots?

readonly optional roots?: readonly string[]

Defined in: packages/lexical-y/src/internal/Runner.ts:258

Experimental

The roots to migrate (default ['lexical-y']), run sorted by name and de-duplicated. Each must have a layout record or be pristine.

Inherited from

YMigrateOptions.roots

to?

readonly optional to?: number

Defined in: packages/lexical-y/src/internal/Runner.ts:263

Experimental

The layout to migrate to (default: MIN_LAYOUT of this build, so only roots below the floor migrate).

Inherited from

YMigrateOptions.to

---

YMigrationReceipt

Defined in: packages/lexical-y/src/internal/Runner.ts:231

Experimental

What a migration did. Its format version is v (1); the root and step receipts inside it are of the same version. An app may persist a receipt: a reader keeps fields it does not know, and shows a receipt of a version it does not know as it is, without acting on it. from and to are layout numbers in every version. The counts (written, deleted, the byte sizes) and ms are diagnostics: neither an identity of the migration nor a proof of what it did.

Properties

bytesAfter

readonly bytesAfter: number

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

Experimental

bytesBefore

readonly bytesBefore: number

Defined in: packages/lexical-y/src/internal/Runner.ts:239

Experimental

The encoded state's size before and after, in bytes.

changed

readonly changed: boolean

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

Experimental

Whether any root changed.

ms

readonly ms: number

Defined in: packages/lexical-y/src/internal/Runner.ts:241

Experimental

roots

readonly roots: readonly YMigrationRootReceipt[]

Defined in: packages/lexical-y/src/internal/Runner.ts:235

Experimental

One per root, sorted by name.

v

readonly v: 1

Defined in: packages/lexical-y/src/internal/Runner.ts:233

Experimental

The receipt's format version.

---

YMigrationResult

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

Experimental

What migrateYState returns.

Properties

pending

readonly pending: Uint8Array<ArrayBufferLike> | null

Defined in: packages/lexical-y/src/internal/Runner.ts:298

Experimental

The input's pending structs and pending delete set (V1), for the quarantine: never in state. Null when there are none or nothing ran.

receipt

readonly receipt: YMigrationReceipt

Defined in: packages/lexical-y/src/internal/Runner.ts:299

Experimental

state

readonly state: Uint8Array

Defined in: packages/lexical-y/src/internal/Runner.ts:291

Experimental

The migrated state (update format V1), without pending material; the input bytes themselves when nothing ran (store nothing then).

update

readonly update: Uint8Array<ArrayBufferLike> | null

Defined in: packages/lexical-y/src/internal/Runner.ts:293

Experimental

The update from the input's integrated state to state; null when nothing ran.

---

YMigrationRootReceipt

Defined in: packages/lexical-y/src/internal/Runner.ts:210

Experimental

What a migration did to one root.

Properties

changed

readonly changed: boolean

Defined in: packages/lexical-y/src/internal/Runner.ts:216

Experimental

epoch

readonly epoch: YMigrationEpoch | null

Defined in: packages/lexical-y/src/internal/Runner.ts:219

Experimental

The epoch the last step recorded, null when none ran.

from

readonly from: number | null

Defined in: packages/lexical-y/src/internal/Runner.ts:213

Experimental

The layout found, null for a pristine root (no record, no content).

root

readonly root: string

Defined in: packages/lexical-y/src/internal/Runner.ts:211

Experimental

steps

readonly steps: readonly YMigrationStepReceipt[]

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

Experimental

to

readonly to: number | null

Defined in: packages/lexical-y/src/internal/Runner.ts:215

Experimental

The layout after the migration (from when nothing ran).

---

YMigrationStepInput

Defined in: packages/lexical-y/src/internal/Runner.ts:245

Experimental

What a step writes with, for a clientID allocator.

Properties

revision

readonly revision: number

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

Experimental

root

readonly root: string

Defined in: packages/lexical-y/src/internal/Runner.ts:246

Experimental

step

readonly step: string

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

Experimental

to

readonly to: number

Defined in: packages/lexical-y/src/internal/Runner.ts:249

Experimental

---

YMigrationStepReceipt

Defined in: packages/lexical-y/src/internal/Runner.ts:198

Experimental

One step a migration ran on one root.

Properties

client

readonly client: number

Defined in: packages/lexical-y/src/internal/Runner.ts:202

Experimental

The client id the step wrote with.

deleted

readonly deleted: number

Defined in: packages/lexical-y/src/internal/Runner.ts:206

Experimental

Items it deleted (an earlier epoch included).

id

readonly id: string

Defined in: packages/lexical-y/src/internal/Runner.ts:199

Experimental

revision

readonly revision: number

Defined in: packages/lexical-y/src/internal/Runner.ts:200

Experimental

written

readonly written: number

Defined in: packages/lexical-y/src/internal/Runner.ts:204

Experimental

Items the step's transaction wrote (the record and epoch included).

Type Aliases

YLayoutInfo

YLayoutInfo = { epoch: YMigrationEpoch | null; layout: number; root: string; status: "ready"; } | { empty: boolean; root: string; status: "missing"; } | { found: unknown; key: string; root: string; status: "invalid"; } | { epoch: YMigrationEpoch | null; features: readonly string[]; layout: number | null; min: number; reason: "older" | "newer" | "requires"; root: string; status: "unsupported"; supported: number; }

Defined in: packages/lexical-y/src/internal/Runner.ts:1664

Experimental

What getYLayoutInfo finds on a root, by status:

• 'ready': this version reads and writes it. It records layout, from MIN_LAYOUT to LAYOUT_VERSION, and its epoch (null: none, a document that never migrated).
• 'missing': no layout record. empty: the root is absent or holds nothing (a new document, seeded on bind); otherwise it holds content without a record (read only).
• 'invalid': a layout record, the epoch or a feature requirement is not well formed: key and its raw value found (read only).
• 'unsupported': well formed, but not for this version: 'older' (below min: migrate it), 'newer' (above supported) or 'requires' (features this version lacks). layout is null when the root records none.

The statuses and the 'unsupported' reasons are fixed: a later version never adds one (code may switch over them exhaustively). Later detail (a schema, a feature, a new category) goes into additive fields, or another helper.

---

YMigrationErrorCode

YMigrationErrorCode = YKnownMigrationErrorCode | string & object

Defined in: packages/lexical-y/src/internal/Runner.ts:171

Experimental

The code of a YMigrationError: one this version throws (see each code's documentation) or one a later version adds. Open on purpose: handle the codes you know and keep a fallback.

---

YMigrationLoaders

YMigrationLoaders = object

Defined in: packages/lexical-y/src/internal/Runner.ts:317

Experimental

Loaders of steps by the layout they migrate from, e.g. {1: () => import('@lexical/y/migrate/1to2')}. A loader may resolve to the step or to its module (default export). Other keys are ignored.

Index Signature

[from: number]: () => Promise<unknown>

Functions

getYLayoutInfo()

getYLayoutInfo(doc, root?): YLayoutInfo

Defined in: packages/lexical-y/src/internal/Runner.ts:1694

Experimental

The layout state of doc's root root (default 'lexical-y') as this version reads it: see YLayoutInfo. Reads only (an absent root is not created).

Parameters

doc

Doc

root?

string = DEFAULT_ROOT_NAME

Returns

YLayoutInfo

---

loadYMigrationSteps()

loadYMigrationSteps(from, to?, __namedParameters?): Promise<YLayoutMigration[]>

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

Experimental

Load the steps a root at layout from needs to reach to (default MIN_LAYOUT), only those, in parallel: by default the published steps (@lexical/y/migrate/<n>to<n+1>, each its own chunk), or loaders (one per layout, () => import(...)). Rejects with a 'missing-step' YMigrationError when a link has no loader, 'invalid-steps' when a loader gives something else than the step from that layout.

Parameters

from

number

to?

number = MIN_LAYOUT

__namedParameters?

YLoadYMigrationStepsOptions = {}

Returns

Promise<YLayoutMigration[]>

---

migrateYState()

migrateYState(state, steps, options?): YMigrationResult

Defined in: packages/lexical-y/src/internal/Runner.ts:1515

Experimental

Migrate a stored state (synchronous; for an authority with every session out, behind its barrier and compare-and-set over exactly these bytes). Every root below the target runs its chain of steps on an observer-free copy, each step checked there; any refusal or failed check throws a YMigrationError and nothing is returned. Pending structs, a pending delete set and skipped ranges (with everything after the gap and everything that depends on it) are split out (pending), never migrated or kept in state. When no root needs a step, the input bytes come back as state, with update: null and changed: false: store nothing.

Parameters

state

Uint8Array

steps

readonly YLayoutMigration[]

options?

YMigrateStateOptions = {}

Returns

YMigrationResult

References

YMigrationEpoch

Re-exports YMigrationEpoch