Skip to main content

@lexical/y/offline

Interfaces​

YAutoReplayRequiredPassReplayableNoneOrMaxBaseAge​

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

Experimental

The required autoReplay of replayUnsyncedEdits and recoverYOfflineEdits. A call without it does not compile, and the compiler names this type: pass autoReplay: 'replayable', autoReplay: 'none', or autoReplay: {maxBaseAge: 3 * 24 * 3600 * 1000}.

Properties​

autoReplay​

readonly autoReplay: YAutoReplay

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:186

Experimental

Which blocks are written over the document by themselves: 'replayable', 'none' (all to leftovers), or {maxBaseAge} (ms: 'none' for an older copy). See YAutoReplay.


YLeftoversContext​

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

Experimental

What a YLeftoversWrap is told about one call.

Properties​

after​

readonly after: string | null

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

Experimental

The id of the top-level block the output is written after; null when it is written at the top of the document ('top', or no block of the user's before these is left).

capturedAt​

readonly capturedAt: number

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:58

Experimental

When the edits were captured (Unix ms).

placement​

readonly placement: YLeftoversPlacement

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

Experimental

reason​

readonly reason: YUnsyncedReason

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

Experimental

Why the edits did not sync.

Methods​

hasNode()​

hasNode(type): boolean

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:62

Experimental

Whether the editor has a node of this type ('quote', 'heading').

Parameters​
type​

string

Returns​

boolean


YLeftoversHandled​

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:127

Experimental

Take the blocks that cannot be replayed yourself: nothing of them is written, handle is called with them, and a stored capture stays until your app deletes it (store.deleteCapture). Show them to the user (an Offline edits panel): this is the only place they go.

Properties​

handle​

readonly handle: YLeftoversHandle

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:128

Experimental

placement?​

readonly optional placement?: undefined

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

Experimental

wrap?​

readonly optional wrap?: undefined

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:129

Experimental


YLeftoversInserted​

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

Experimental

One place a replay wrote leftover blocks at.

Properties​

after​

readonly after: string | null

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:244

Experimental

The id of the block they were written after; null: at the top.

blocks​

readonly blocks: readonly string[]

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

Experimental

The report's ids of the blocks written here, in the order given to wrap.

fallback​

readonly fallback: string | null

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

Experimental

Null when wrap's output was written. Otherwise why it was not (the fix is in the text): the blocks were written as they are instead.

inserted​

readonly inserted: readonly string[]

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:242

Experimental

The new ids of the top-level blocks written, in document order ('#<index>', their positions, in an editor without block ids).


YLeftoversRequiredPassWrapOrHandle​

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

Experimental

The required leftovers of replayUnsyncedEdits and recoverYOfflineEdits. A call without it does not compile, and the compiler names this type: pass leftovers: {wrap: wrapLeftoversAsQuote('…')} or leftovers: {handle: blocks => …}.

Properties​

leftovers​

readonly leftovers: YLeftovers

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:154

Experimental

What to do with the blocks that cannot be replayed: pass leftovers: {wrap: wrapLeftoversAsQuote('…')} (write them into the document) or leftovers: {handle: blocks => …} (take them yourself).


YLeftoversWrapped​

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

Experimental

Write the blocks that cannot be replayed into the document, through wrap, in the update that replays the rest (one undo step). wrapLeftoversAsQuote('Offline edits that did not merge') is a ready wrap.

Properties​

handle?​

readonly optional handle?: undefined

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

Experimental

placement?​

readonly optional placement?: YLeftoversPlacement

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

Experimental

'after-block' (the default): after the block of the same id; when it is gone, after the nearest block before it in the user's document that is left (a nested one counts as the top-level block it is in), else at the top. 'top': all of them at the top of the document, in one call of wrap.

Default Value​

'after-block'

wrap​

readonly wrap: YLeftoversWrap

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:108

Experimental


YOfflineBinding​

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

Experimental

What the offline layer uses of a binding: a YCollabBinding (createYBinding, or YCollabExtension's collab) is one. An app that built a YBinding itself passes the binding, its status, and a freeze() that stops it and hands over its edits (from binding.quiesce()).

Properties​

binding​

readonly binding: YBinding

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:127

Experimental

The YBinding: its document, editor and undo manager are read.

status​

readonly status: YStatus

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:129

Experimental

'active' when edits can be replayed into it.

Methods​

freeze()​

freeze(): YLocalEdits

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:131

Experimental

Stop reading and writing, and hand over the local edits (11.6).

Returns​

YLocalEdits


YOfflineCapture​

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:186

Experimental

A frozen copy of a client's document that did not sync, with the base it was made against: what the Offline edits panel shows.

Properties​

base​

readonly base: Uint8Array<ArrayBufferLike> | null

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:218

Experimental

The document the edits were made against, or null when unknown.

baseAt?​

readonly optional baseAt?: number | null

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:201

Experimental

When the base (the document the edits were made against) was last known to be on the server (Unix ms): how old the copy the edits were made on is. Null or absent when unknown (a capture of an earlier release, or a store of your own); see autoReplay's maxBaseAge.

capturedAt​

readonly capturedAt: number

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:194

Experimental

When it was captured (Unix ms).

claimed​

readonly claimed: boolean

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:220

Experimental

Set once a replay stage took the capture (see claimCapture).

claimedAt?​

readonly optional claimedAt?: number

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:226

Experimental

When the capture was claimed (Unix ms): set by claimCapture of the store of openYOfflineStore. A claim that is old and never resolved was made by a tab that is gone (see recoverYOfflineEdits).

claimedWrite?​

readonly optional claimedWrite?: object

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

Experimental

The ids the first blocks the claimant writes for the leftovers get, chosen before it writes (recoverYOfflineEdits, with block ids). A retake whose document holds any of them holds the write, and resolves the capture instead of writing it again.

ids​

readonly ids: readonly string[]

differs​

readonly differs: boolean

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

Experimental

Whether the editor held edits the document did not (freeze()'s differs): the report then reads json, else state.

epoch​

readonly epoch: string | null

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:191

Experimental

The epoch the edits were made against; null: never synced.

id​

readonly id: string

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:188

Experimental

Unique per key.

json​

readonly json: unknown

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:209

Experimental

The editor's content as Lexical JSON (freeze()'s), or null for a capture made from storage alone (a tab that closed before it could freeze).

key​

readonly key: string

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:189

Experimental

reason​

readonly reason: "stale" | "legacy" | "expired"

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:192

Experimental

resolved?​

readonly optional resolved?: object

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

Experimental

Set once a recovery wrote everything of the capture into the document (recoverYOfflineEdits with leftovers: {wrap}): when (Unix ms), and the new ids of the top-level blocks written for the blocks that could not be replayed. Nothing of a resolved capture is left to show; it is deleted once the server holds the document.

at​

readonly at: number

inserted​

readonly inserted: readonly string[]

vector​

readonly vector: Uint8Array

The state vector of the document right after it was written: a recovery on another document deletes the capture only once that document holds this write, and takes it again when it still does not a minute later (the tab that wrote it closed before it synced).

state​

readonly state: Uint8Array

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:203

Experimental

The whole document as the client held it (a Yjs update).

text​

readonly text: string | null

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

Experimental

The plain text of the editor, for Copy; null as json is.


YOfflineClear​

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:338

Experimental

What YOfflineStore.clear deletes for a key. Slots hold the document and its unsynced edits; captures hold edits that did not sync, for the Offline edits panel.

  • slots: {epoch} one slot (null names the never-synced slot), 'all' every slot of the key (every epoch's, every tab's: unsynced edits included), 'none' no slot.
  • captures: 'all', 'unreadable' (only captures this release cannot read, what a 'corrupt' error with where: 'captures' names) or 'none'.

Properties​

captures​

readonly captures: "none" | "all" | "unreadable"

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:340

Experimental

slots​

readonly slots: "none" | "all" | { epoch: string | null; }

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:339

Experimental


YOfflineDescribeOptions​

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1320

Experimental

What describeYOfflineCapture reads a capture with.

Properties​

config​

readonly config: HeadlessYConfig

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1324

Experimental

The headless configuration of your editor (its nodes, schemaVersion).

current​

readonly current: Uint8Array

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1322

Experimental

The document as it is now (encodeStateAsUpdate(doc) of the fresh one).

migrate?​

readonly optional migrate?: (state) => Uint8Array

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1331

Experimental

Brings a state this release cannot read (a layout below MIN_LAYOUT) up to one it can, with your app's migration steps (migrateYState on @lexical/y/migrate). Without it, such a base is reported as gone (nothing replayable) and such a capture without JSON cannot be read.

Parameters​
state​

Uint8Array

Returns​

Uint8Array


YOfflineLimits​

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:124

Experimental

Caps a store keeps by refusing writes ('limit'), never by evicting: what is stored stays until the app clears it.

Properties​

bytesPerKey?​

readonly optional bytesPerKey?: number

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:134

Experimental

Most bytes stored per key: its rows' updates and its captures' states and bases (a capture's JSON and text are not counted). Each connection counts what it last read of the key plus what it wrote since; another tab's writes count from its next read (a compaction, a confirmation, a capture), so tabs writing at once can pass it by what they wrote since.

group?​

readonly optional group?: (key) => string

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:139

Experimental

The group a key counts in for keys, e.g. its viewer for keys viewer|doc: key => key.split('|')[0]. Default: one group.

Parameters​
key​

string

Returns​

string

keys?​

readonly optional keys?: number

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

Experimental

Most keys stored per group (a new key past it is refused).


YOfflineLoaded​

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:135

Experimental

What loadYOffline read.

Properties​

base​

readonly base: Uint8Array<ArrayBufferLike> | null

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:141

Experimental

The state the server is known to hold, or null.

baseAt​

readonly baseAt: number | null

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:145

Experimental

When base was stored (Unix ms), or null when unknown.

epoch​

readonly epoch: string | null

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:137

Experimental

The epoch the stored document was made against; null: none, or never synced.

hasUnsyncedEdits​

readonly hasUnsyncedEdits: boolean

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:143

Experimental

Whether the stored document holds edits the server may lack.

state​

readonly state: Uint8Array<ArrayBufferLike> | null

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:139

Experimental

The stored document (for createYDoc(state)), or null when none is stored.

unsyncedInLiveTabs​

readonly unsyncedInLiveTabs: boolean

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:152

Experimental

Whether every one of those edits is in rows a tab still open holds (another tab of the document, offline): that tab syncs them, or captures them when it learns its epoch moved, so this page's session does not capture them as its own unless it edits too.


YOfflineLocks​

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:436

Experimental

The part of the Web Locks API the store uses.

Methods​

query()​

query(): Promise<{ held?: readonly object[]; }>

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

Experimental

Returns​

Promise<{ held?: readonly object[]; }>

request()​

request(name, callback): Promise<unknown>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:437

Experimental

Parameters​
name​

string

callback​

(lock) => Promise<unknown>

Returns​

Promise<unknown>


YOfflineRecovered​

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:2184

Experimental

One capture of recoverYOfflineEdits' result.

Properties​

capture​

readonly capture: YOfflineCapture

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:2186

Experimental

The capture; resolved is set once its leftovers are in the document.

replay​

readonly replay: YReplayResult | null

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:2196

Experimental

What the replay stage applied and inserted; null when it did not run for this capture in this call.

report​

readonly report: YOfflineResult<YOfflineReport>

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:2191

Experimental

What is left to show (nothing, for a capture whose leftovers were written into the document), or why the capture could not be read.


YOfflineReport​

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1234

Experimental

A capture's report: describeUnsyncedEdits' without the blocks the document already holds as the user had them.

Extends​

Properties​

baseAt​

readonly baseAt: number | null

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1241

Experimental

When the copy the edits were made on was last known to be on the server (the capture's baseAt), or null when unknown: what autoReplay's maxBaseAge reads.

baseAvailable​

readonly baseAvailable: boolean

Defined in: packages/lexical-y/src/headless.ts:410

Experimental

False when base was null: changes are judged against the current document only, and nothing is replayable.

Inherited from​

YUnsyncedReport.baseAvailable

blocks​

readonly blocks: readonly YUnsyncedBlock[]

Defined in: packages/lexical-y/src/headless.ts:412

Experimental

One entry per block the user changed, in their document's order.

Inherited from​

YUnsyncedReport.blocks

capturedAt​

readonly capturedAt: number

Defined in: packages/lexical-y/src/headless.ts:405

Experimental

Inherited from​

YUnsyncedReport.capturedAt

captureId​

readonly captureId: string

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1235

Experimental

fragment​

readonly fragment: readonly SerializedLexicalNode[]

Defined in: packages/lexical-y/src/headless.ts:414

Experimental

Every block the user added or changed, as they saw it.

Inherited from​

YUnsyncedReport.fragment

inDocument​

readonly inDocument: readonly string[]

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1248

Experimental

Blocks left out because the document already holds them as the user had them.

order​

readonly order: readonly string[]

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1246

Experimental

The ids of the user's blocks, in their document's order (what places a replayed added block).

Overrides​

YUnsyncedReport.order

orderDiffers​

readonly orderDiffers: boolean

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1254

Experimental

Whether the blocks both documents hold are in another order in the user's (they, or someone since, moved a block): no entry of blocks says so, and a capture with it is kept until the user dismisses it.

reason​

readonly reason: YUnsyncedReason

Defined in: packages/lexical-y/src/headless.ts:404

Experimental

Inherited from​

YUnsyncedReport.reason

shifted?​

readonly optional shifted?: readonly string[]

Defined in: packages/lexical-y/src/headless.ts:430

Experimental

Without block ids only: the ids of blocks the current document holds as the user had them, found by content (each current block counted once, the user's unchanged blocks first). Paired by position, one block added or removed offline makes every later one an entry; a replay does not write these again.

Inherited from​

YUnsyncedReport.shifted


YOfflineSalvage​

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:143

Experimental

What a corrupt slot still holds (see YOfflineError).

Properties​

readableRows​

readonly readableRows: number

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

Experimental

state​

readonly state: Uint8Array<ArrayBufferLike> | null

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:145

Experimental

The merge of every readable row, or null when none is.

unreadableRows​

readonly unreadableRows: number

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

Experimental


YOfflineSession​

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:388

Experimental

An attached session (see attachYOfflineSession).

Properties​

ended​

readonly ended: boolean

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:397

Experimental

True once the epoch moved (the binding is frozen) or after dispose().

epoch​

readonly epoch: string | null

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:391

Experimental

The epoch the document belongs to; null until the server names one.

hasUnsyncedEdits​

readonly hasUnsyncedEdits: boolean

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:393

Experimental

Whether the document may hold edits the server lacks.

persisted​

readonly persisted: boolean

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:395

Experimental

False after a storage failure, until a write succeeds again.

stage​

readonly stage: YOfflineStage

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:389

Experimental

Methods​

dispose()​

dispose(): void

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:424

Experimental

Stop listening. What is stored stays (use store.clear to drop it).

Returns​

void

flush()​

flush(): Promise<YOfflineResult<void>>

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:422

Experimental

Resolves once everything queued so far is stored (or failed to be).

Returns​

Promise<YOfflineResult<void>>

freeze()​

freeze(options?): Promise<YOfflineVerdict>

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:418

Experimental

The server says the room was replaced, and the new epoch is not known yet: the same as serverEpoch with a new epoch. The binding is frozen before this returns its promise, what it holds is captured into the store (for recoverYOfflineEdits on the new document), and the session ends. Call it on the live session, before disposing it.

Parameters​
options?​
reason?​

"stale" | "legacy" | "expired"

Returns​

Promise<YOfflineVerdict>

serverEpoch()​

serverEpoch(epoch, options?): Promise<YOfflineVerdict>

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:407

Experimental

Tell the session the epoch the server's room is at: call it before the provider syncs this document (on every connect, and once right after attaching a document the page fetched from the server), and when the server says the room was replaced. The binding is frozen and stopSync called before this returns its promise, so nothing typed after a 'moved' is lost or written. A 'same' verdict carries markSynced().

Parameters​
epoch​

string

options?​
reason?​

"stale" | "legacy" | "expired"

Returns​

Promise<YOfflineVerdict>


YOfflineSessionOptions​

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

Experimental

Options of attachYOfflineSession: every choice an app must make is required (binding, key, epoch, loaded, offline, onError, stopSync).

Properties​

binding​

readonly binding: YOfflineBinding

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:289

Experimental

The bound editor: what createYBinding returns, YCollabExtension's collab, or any YOfflineBinding.

compactAfter?​

readonly optional compactAfter?: number

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

Experimental

Stored updates before they are compacted into one.

Default Value​

Y_OFFLINE_DEFAULTS.compactAfter

epoch​

readonly epoch: string | null

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

Experimental

The epoch (generation) the document was made against, as a string: loaded.epoch for a document created from loadYOffline, the server's for one fetched from it, null for one that never synced.

key​

readonly key: string

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

Experimental

The document's name in your app (its id).

loaded​

readonly loaded: YOfflineLoaded | null

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:306

Experimental

What loadYOffline returned when the document was created from it (its base, its unsynced edits and its stored rows continue here), or null for a document that was not (fetched from the server, or new). Required: a document created from a load but attached without it would start with no base and no unsynced edits, so a moved epoch would capture nothing of what it holds.

now?​

readonly optional now?: () => number

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

Experimental

The clock, for tests.

Returns​

number

Default Value​

Date.now

offline​

readonly offline: YOfflineMode

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:308

Experimental

The stage, and the store it uses (see YOfflineMode).

onError​

readonly onError: (error) => void

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:314

Experimental

Called with every storage failure (a full quota, a closed store): tell the user their edits are not saved on this device. Editing goes on, and the next write retries.

Parameters​
error​

YOfflineError

Returns​

void

stopSync​

readonly stopSync: () => void

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:322

Experimental

Stop syncing this document for good: disconnect or destroy its provider. The session calls it when the epoch moved (serverEpoch or freeze answering 'moved'), right after it froze the binding and before the capture is stored, so the frozen document never syncs into the room that replaced it, whatever the app does with the verdict.

Returns​

void

writeDelay?​

readonly optional writeDelay?: number

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:330

Experimental

Milliseconds to wait for updates to pause before storing them (0: store each at once). While they do not pause, they are stored at least every ten times this. flush() stores at once; call it on pagehide: what a delay holds back is lost with a closed tab.

Default Value​

0


YOfflineSlot​

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:255

Experimental

One (key, epoch) of a YOfflineStore.

Properties​

epoch​

readonly epoch: string | null

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

Experimental

Changes with YOfflineSlot.adopt.

key​

readonly key: string

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:256

Experimental

rowsSinceCompaction​

readonly rowsSinceCompaction: number

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

Experimental

since rows this handle wrote since it last compacted or confirmed.

Methods​

adopt()​

adopt(epoch): Promise<YOfflineResult<void>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:324

Experimental

Move a slot that never synced (epoch null) to the epoch the server gave it: this handle's rows, and those it loaded whose writer is gone. A live tab's rows stay for that tab to move.

Parameters​
epoch​

string

Returns​

Promise<YOfflineResult<void>>

append()​

append(update): Promise<YOfflineResult<void>>

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

Experimental

Store one update the document made or received.

Parameters​
update​

Uint8Array

Returns​

Promise<YOfflineResult<void>>

close()​

close(): void

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:318

Experimental

Release the handle's writer lock (see locks): its rows become another handle's to replace. Call it when the document is closed; a closed tab releases it on its own.

Returns​

void

compact()​

compact(since?): Promise<YOfflineResult<void>>

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

Experimental

Replace this handle's since rows by one: since when given (what the document holds beyond the base), else their merge.

Parameters​
since?​

Uint8Array<ArrayBufferLike>

Returns​

Promise<YOfflineResult<void>>

confirm()​

confirm(state, confirmedAt?): Promise<YOfflineResult<void>>

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

Experimental

The server holds state (the whole document, which holds every row of this handle): it becomes the base and this handle's rows are removed. confirmedAt: when the server was known to hold it (Unix ms), which load returns as baseAt; null or absent when unknown.

Parameters​
state​

Uint8Array

confirmedAt?​

number | null

Returns​

Promise<YOfflineResult<void>>

discard()​

discard(): Promise<YOfflineResult<void>>

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

Experimental

Delete this handle's rows (the ones it loaded or wrote), and no other: for a document that was captured, whose rows another tab at the same epoch may still be adding to.

Returns​

Promise<YOfflineResult<void>>

discardWritten()?​

optional discardWritten(): Promise<YOfflineResult<void>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:300

Experimental

Delete only the rows this handle wrote; the rows it loaded stay. What a moved epoch does when the only unsynced edits the page loaded are a live tab's (YOfflineLoaded.unsyncedInLiveTabs) and the page made none: nothing is captured, and the rows that tab's recovery builds on (a base row of a gone writer) are kept. Optional for stores of your own (the session falls back to discard()).

Returns​

Promise<YOfflineResult<void>>

load()​

load(options?): Promise<YOfflineResult<YOfflineStored | null>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:266

Experimental

Read the slot: null when it holds nothing. The rows read become this handle's (create the document from state, so it holds them). With {writers: 'gone'}, only rows whose writer is gone (no live tab holds them): what recovery captures, leaving a live tab's rows to that tab. Without Web Locks (locks: null) that is every row.

Parameters​
options?​
writers?​

"all" | "gone"

Returns​

Promise<YOfflineResult<YOfflineStored | null>>

moveIntoCapture()?​

optional moveIntoCapture(capture): Promise<YOfflineResult<void>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:308

Experimental

In one transaction: put capture (when not null) and delete the rows discard() would, the capture checked against limits with those rows already counted as removed. What a moved epoch does with a frozen document. Optional for stores of your own (the session falls back to putCapture then discard).

Parameters​
capture​

YOfflineCapture | null

Returns​

Promise<YOfflineResult<void>>


YOfflineSlotInfo​

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:172

Experimental

One slot of a key (see YOfflineStore.slots).

Properties​

epoch​

readonly epoch: string | null

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:175

Experimental

The epoch the slot's document was made against; null: never synced.

hasUnsyncedEdits​

readonly hasUnsyncedEdits: boolean

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

Experimental

key​

readonly key: string

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:173

Experimental

rows​

readonly rows: number

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:179

Experimental

updatedAt​

readonly updatedAt: number

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

Experimental

When its newest row was written (Unix ms).


YOfflineStore​

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:344

Experimental

The local store (see openYOfflineStore).

Methods​

captures()​

captures(key): Promise<YOfflineResult<YOfflineCapture[]>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:350

Experimental

The captures stored for key, oldest first.

Parameters​
key​

string

Returns​

Promise<YOfflineResult<YOfflineCapture[]>>

captureSlot()?​

optional captureSlot(key, epoch, build): Promise<YOfflineResult<YOfflineCapture | null>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:385

Experimental

In one transaction: read the rows of slot (key, epoch) whose writer is gone, and when any is past the base, put the capture build makes of them, and delete them. Two tabs that call it at once make one capture: the second finds no rows. Resolves to the capture, or null when there was nothing past the base (the rows are deleted either way). Rows it cannot read stay, and the result is 'corrupt' or 'newer' with the slot's epoch. Optional for stores of your own (recovery falls back to load, putCapture, discard).

Parameters​
key​

string

epoch​

string | null

build​

(stored) => YOfflineCapture

Returns​

Promise<YOfflineResult<YOfflineCapture | null>>

claimCapture()​

claimCapture(key, id, options?): Promise<YOfflineResult<boolean>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:364

Experimental

Mark a capture as taken by a replay: true for the one caller that gets it (a second tab, or a second call, gets false), so a capture is replayed automatically at most once. Set claimedAt to the time with it, so a claim whose tab closed before it wrote the capture can be told from one being written now (without it, such a claim counts as old).

With retake, take a capture already claimed instead, only if its claimedAt is still the one given (null: none), in the same atomic step: set a new claimedAt and remove resolved. Of two tabs taking the same old claim again, one gets true.

Parameters​
key​

string

id​

string

options?​
retake?​

{ claimedAt: number | null; }

retake.claimedAt​

number | null

Returns​

Promise<YOfflineResult<boolean>>

clear()​

clear(key, what): Promise<YOfflineResult<void>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:374

Experimental

Delete what is stored for key: both choices are required, so a call names what it deletes (see YOfflineClear).

Parameters​
key​

string

what​

YOfflineClear

Returns​

Promise<YOfflineResult<void>>

close()​

close(): void

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:393

Experimental

Close the database: later calls return 'closed'.

Returns​

void

deleteCapture()​

deleteCapture(key, id): Promise<YOfflineResult<void>>

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

Experimental

Parameters​
key​

string

id​

string

Returns​

Promise<YOfflineResult<void>>

keys()​

keys(): Promise<YOfflineResult<string[]>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:391

Experimental

Every key that holds a slot or a capture (for clearing by owner).

Returns​

Promise<YOfflineResult<string[]>>

putCapture()​

putCapture(capture): Promise<YOfflineResult<void>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:351

Experimental

Parameters​
capture​

YOfflineCapture

Returns​

Promise<YOfflineResult<void>>

slot()​

slot(key, epoch): YOfflineSlot

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

Experimental

A handle on one slot; nothing is read or written until it is used.

Parameters​
key​

string

epoch​

string | null

Returns​

YOfflineSlot

slots()​

slots(key): Promise<YOfflineResult<YOfflineSlotInfo[]>>

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

Experimental

The slots stored for key, newest first.

Parameters​
key​

string

Returns​

Promise<YOfflineResult<YOfflineSlotInfo[]>>


YOfflineStored​

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:156

Experimental

What a slot holds (see YOfflineSlot.load).

Properties​

base​

readonly base: Uint8Array<ArrayBufferLike> | null

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:160

Experimental

The state the server is known to hold, or null when none was confirmed.

baseAt?​

readonly optional baseAt?: number | null

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:168

Experimental

When the server was known to hold base (Unix ms): the session's markSynced() that made it, as passed to confirm. Null or absent when unknown (a store of your own may leave it out).

hasUnsyncedEdits​

readonly hasUnsyncedEdits: boolean

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:162

Experimental

Whether updates were stored after base: the server may lack them.

state​

readonly state: Uint8Array

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:158

Experimental

The whole document: base and since merged (a Yjs update).


YOfflineStoreOptions​

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:397

Experimental

Options of openYOfflineStore.

Properties​

databaseName?​

readonly optional databaseName?: string

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:411

Experimental

The database's name: one per app.

Default Value​

Y_OFFLINE_DEFAULTS.databaseName

idb​

readonly idb: object

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:403

Experimental

The IndexedDB to use. Required, so every caller decides: pass {indexedDB, IDBKeyRange} from globalThis in a browser, or a fake's in Node (the store works without a DOM).

IDBKeyRange​

readonly IDBKeyRange: ({(): IDBKeyRange; prototype: IDBKeyRange; bound: IDBKeyRange; lowerBound: IDBKeyRange; only: IDBKeyRange; upperBound: IDBKeyRange; }) | undefined

Union Members​
Function​

{(): IDBKeyRange; prototype: IDBKeyRange; bound: IDBKeyRange; lowerBound: IDBKeyRange; only: IDBKeyRange; upperBound: IDBKeyRange; }

Returns​

IDBKeyRange

prototype​

prototype: IDBKeyRange

bound()​

bound(lower, upper, lowerOpen?, upperOpen?): IDBKeyRange

The bound() static method of the IDBKeyRange interface creates a new key range with the specified upper and lower bounds. The bounds can be open (that is, the bounds exclude the endpoint values) or closed (that is, the bounds include the endpoint values). By default, the bounds are closed.

MDN Reference

Parameters​
lower​

any

upper​

any

lowerOpen?​

boolean

upperOpen?​

boolean

Returns​

IDBKeyRange

lowerBound()​

lowerBound(lower, open?): IDBKeyRange

The lowerBound() static method of the IDBKeyRange interface creates a new key range with only a lower bound. By default, it includes the lower endpoint value and is closed.

MDN Reference

Parameters​
lower​

any

open?​

boolean

Returns​

IDBKeyRange

only()​

only(value): IDBKeyRange

The only() static method of the IDBKeyRange interface creates a new key range containing a single value.

MDN Reference

Parameters​
value​

any

Returns​

IDBKeyRange

upperBound()​

upperBound(upper, open?): IDBKeyRange

The upperBound() static method of the IDBKeyRange interface creates a new upper-bound key range. By default, it includes the upper endpoint value and is closed.

MDN Reference

Parameters​
upper​

any

open?​

boolean

Returns​

IDBKeyRange


undefined

indexedDB​

readonly indexedDB: IDBFactory | undefined

limits?​

readonly optional limits?: YOfflineLimits

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:422

Experimental

Caps kept by refusing writes, never by evicting. Default: none.

locks?​

readonly optional locks?: YOfflineLocks | null

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

Experimental

The Web Locks the store tells live tabs by: each writing handle holds a lock, and no handle removes rows a live handle wrote (they may be what that tab's later rows build on). Rows of a handle that is gone (a closed tab, an earlier page load) are replaced by the next handle that loads them. Null: every other handle counts as live, so rows of earlier page loads are kept until the app clears them.

Default Value​

navigator.locks, where there is one, else null

now?​

readonly optional now?: () => number

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:413

Experimental

The clock, for tests.

Returns​

number

Default Value​

Date.now

openTimeout?​

readonly optional openTimeout?: number

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:420

Experimental

Milliseconds to wait for the database to open before answering 'unavailable' (some browsers never answer an open in some states). A connection that opens later is closed.

Default Value​

Y_OFFLINE_DEFAULTS.openTimeout


YReplayResult​

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1527

Experimental

What replayUnsyncedEdits did.

Properties​

applied​

readonly applied: readonly string[]

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1529

Experimental

The ids of the blocks applied, in the order applied.

handled​

readonly handled: readonly string[]

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1549

Experimental

The report's ids of the blocks given to leftovers.handle.

inserted​

readonly inserted: readonly string[]

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1545

Experimental

The new ids of every top-level block written for the leftovers, in document order (all of leftovers[].inserted).

leftovers​

readonly leftovers: readonly YLeftoversInserted[]

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1547

Experimental

Each place leftover blocks were written at (leftovers: {wrap}).

notApplied​

readonly notApplied: readonly object[]

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1537

Experimental

The blocks not applied, with why. Each is accounted for: written into the document (leftovers), given to the handler (handled), or with nothing to write ('in-document', 'not-in-report', or a deletion of the user's, which leaves the current block). Only 'not-written' (the update failed) leaves blocks neither applied nor accounted for.

Type Aliases​

YAutoReplay​

YAutoReplay = "replayable" | "none" | { maxBaseAge: number; }

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:172

Experimental

Which blocks a replay writes over the document by itself.

  • 'replayable': every replayable block (one only the user changed), as it is; the rest go to leftovers.
  • 'none': no block is replayed; every block the user added or changed goes to leftovers (a block they deleted stays, listed in notApplied).
  • {maxBaseAge}: 'replayable' when the copy the edits were made on is at most maxBaseAge milliseconds old (the report's baseAt), else 'none'. A report whose baseAt is unknown (a capture of an earlier release, a report built by describeUnsyncedEdits) counts as older. The longer a copy was apart from the document, the more a replay of it can undo what happened since without anything to show for it.

YLeftoverBlock​

YLeftoverBlock = YUnsyncedBlock & object

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:41

Experimental

A leftover block with content: one the user added or changed that the replay cannot apply. yours is the block as they had it.

Type Declaration​

yours​

readonly yours: SerializedLexicalNode


YLeftovers​

YLeftovers = YLeftoversWrapped | YLeftoversHandled

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:139

Experimental

What a replay does with the blocks it cannot apply. There is no default, so they cannot be forgotten: pass leftovers: {wrap: wrapLeftoversAsQuote('…')} to write them into the document, or leftovers: {handle: blocks => …} to take them yourself.


YLeftoversHandle​

YLeftoversHandle = (blocks, context) => void

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:91

Experimental

Takes the blocks a replay did not apply (see YLeftoversHandled).

Parameters​

blocks​

readonly YUnsyncedBlock[]

context​
captureId​

string | null

The stored capture's id, in recoverYOfflineEdits; else null.

report​

YUnsyncedReport

The report the blocks are from (a YOfflineReport in a recovery).

Returns​

void


YLeftoversPlacement​

YLeftoversPlacement = "after-block" | "top"

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

Experimental

Where YLeftoversWrapped.wrap's output is written.


YLeftoversWrap​

YLeftoversWrap = (blocks, context) => readonly SerializedLexicalNode[]

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

Experimental

Turns leftover blocks into the top-level blocks written into the document, as serialized nodes (for example one collapsible "Offline edits that didn't merge" node of your app around them). It is called once per place: with 'after-block', once for the blocks that go after the same block; with 'top', once.

The output must hold every block it was given, in the order given, each as a node of its own: one whose text is exactly the block's (its yours, or another node around the same text: a paragraph may become a quote), or, for a block without text, its yours as it is. Named slots count as children. It must use node types the editor has, and each top-level node must be a block. Output that fails any of that is not written: the blocks are written as they are instead, and the result says why (fallback). Block ids in the output are ignored: every block written gets a new one.

Parameters​

blocks​

readonly YLeftoverBlock[]

context​

YLeftoversContext

Returns​

readonly SerializedLexicalNode[]


YOfflineError​

YOfflineError = YOfflineErrorBase & object | YOfflineErrorBase & object | YOfflineErrorBase & object | YOfflineErrorBase & object | YOfflineErrorBase & object

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:87

Experimental

A failure of the local store. Nothing here throws for a storage failure: every call returns a YOfflineResult, and message says what to do. A union by code (and where, for 'corrupt'): narrow on it to reach the fields that code carries, such as the readable rows of a corrupt slot (salvage), which the app offers the user before it clears the slot.


YOfflineErrorCode​

YOfflineErrorCode = "unavailable" | "blocked" | "quota" | "corrupt" | "closed" | "limit" | "newer" | "failed"

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

Experimental

What failed (see YOfflineError).


YOfflineMode​

YOfflineMode = { stage: "off"; } | { persist: YOfflinePersist; stage: "persist" | "replay"; store: YOfflineStore; }

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

Experimental

The offline layer's mode: one value, so a store is there exactly when the stage uses it. Build it in one expression: opened.ok ? {persist: 'document', stage, store: opened.value} : {stage: 'off'}.

Union Members​

Type Literal​

{ stage: "off"; }

Nothing is persisted, captured or replayed (see YOfflineStage).


Type Literal​

{ persist: YOfflinePersist; stage: "persist" | "replay"; store: YOfflineStore; }

persist​

readonly persist: YOfflinePersist

What is kept on the device (see YOfflinePersist).

stage​

readonly stage: "persist" | "replay"

store​

readonly store: YOfflineStore

From openYOfflineStore.


YOfflinePersist​

YOfflinePersist = "document" | "unsynced" | "captures-only"

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:261

Experimental

What persist keeps on the device (see YOfflineMode):

  • 'document': every update as it is made, the whole document (its base and what came since), so the page can open it with no connection (loadYOffline) and a later page captures what did not sync;
  • 'unsynced': the same, but only while the document holds edits the server lacks: nothing is stored while it is synced, the first local edit stores the base and what came since, and the verdict's markSynced() deletes them;
  • 'captures-only': no edit is stored as it is made, only a capture when the epoch moves while the tab is open. Unsynced edits live in the tab alone: a reload, a crash or a closed tab with no connection loses them.

YOfflineRecoverInput​

YOfflineRecoverInput = object & YLeftoversRequiredPassWrapOrHandle & YAutoReplayRequiredPassReplayableNoneOrMaxBaseAge

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:2212

Experimental

What recoverYOfflineEdits takes.

Type Declaration​

binding​

readonly binding: YOfflineBinding

The fresh document's binding: active, synced, at epoch.

config​

readonly config: HeadlessYConfig

epoch​

readonly epoch: string

The epoch the fresh document is at.

key​

readonly key: string

migrate?​

readonly optional migrate?: (state) => Uint8Array

Parameters​
state​

Uint8Array

Returns​

Uint8Array

now?​

readonly optional now?: () => number

The clock, for tests.

Returns​

number

Default Value​

Date.now

session?​

readonly optional session?: YOfflineSession

The fresh document's offline session: with it, a capture the server already holds (its session reports no unsynced edits) is deleted.

stage​

readonly stage: YOfflineStage

store​

readonly store: YOfflineStore | null


YOfflineResult​

YOfflineResult<T> = { ok: true; value: T; } | { error: YOfflineError; ok: false; }

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:151

Experimental

A value, or the error that kept it from being made.

Type Parameters​

T​

T


YOfflineStage​

YOfflineStage = "off" | "persist" | "replay"

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:112

Experimental

The rollout stage of the offline layer, an explicit choice of every call that takes it:

  • 'off': nothing is persisted, captured or replayed (the calls return at once), so an app can ship the code dark;
  • 'persist': edits are stored on the device as offline.persist says (every edit as it is made, with 'document'), and a document whose epoch moved (a reconnect to a replaced or upgraded room) is frozen and stored with its base. Nothing is written into the new document: the edits stay stored;
  • 'replay': as 'persist', and recoverYOfflineEdits applies the blocks that are replayable and, with leftovers: {wrap}, writes every other block into the document.

YOfflineVerdict​

YOfflineVerdict = { kind: "off"; } | { kind: "same"; markSynced: () => void; } | { capture: YOfflineCapture | null; kind: "moved"; saved: YOfflineResult<void>; }

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:341

Experimental

What YOfflineSession.serverEpoch decided.

Union Members​

Type Literal​

{ kind: "off"; }

Stage 'off': nothing was done. Handle the epoch as the app did before.


Type Literal​

{ kind: "same"; markSynced: () => void; }

The document belongs to this epoch (or just adopted it): sync it, and call markSynced() once the server holds everything it holds.

kind​

readonly kind: "same"

markSynced​

readonly markSynced: () => void

The authoritative copy holds everything this document holds: the document as it is now becomes the base later edits are judged against, and what is stored since is replaced by it (with persist: 'unsynced', deleted). Only a 'same' verdict carries it, so it cannot run before the session confirmed the room's epoch: on a document of a replaced room it would make its unsynced edits the base, and the capture would hold none of them.

"Holds" means persisted by the copy a reload or replace of the room is seeded from: for a relay in front of a product's store (a connector), the product's save, not the relay's acknowledgement. Call it only when that copy holds every update this document has (nothing newer since): an edit made after what was persisted would fold into the base, and a later capture would not list it. With a relay that acknowledges nothing, call it when the provider has synced; that leaves a window (an edit sent in that sync that never arrived is in the base). A verdict stays callable after a reconnect: call the one from the connection that synced. Once the session has ended (a moved epoch, dispose()) it does nothing.

Returns​

void


Type Literal​

{ capture: YOfflineCapture | null; kind: "moved"; saved: YOfflineResult<void>; }

The room moved on. The binding is frozen, stopSync was called and the session has ended: never sync this document. Open a fresh one at the new epoch and call recoverYOfflineEdits there. capture is what was kept (null when the document held nothing the server lacked); saved says whether it reached the store (when not, capture is all there is: keep the tab open and offer Copy).


YReplayInput​

YReplayInput = object & YLeftoversRequiredPassWrapOrHandle & YAutoReplayRequiredPassReplayableNoneOrMaxBaseAge

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1553

Experimental

What replayUnsyncedEdits takes.

Type Declaration​

binding​

readonly binding: YOfflineBinding

now?​

readonly optional now?: () => number

The clock autoReplay's maxBaseAge reads, for tests.

Returns​

number

Default Value​

Date.now

only?​

readonly optional only?: readonly string[]

Only these block ids (a panel's Reapply button).

report​

readonly report: YOfflineReport | YUnsyncedReport


YReplaySkipReason​

YReplaySkipReason = "not-replayable" | "changed-since" | "no-block-ids" | "unreadable" | "in-document" | "not-in-report" | "not-auto-replayed" | "not-written"

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1501

Experimental

Why a block was not replayed.

Variables​

Y_OFFLINE_DEFAULTS​

const Y_OFFLINE_DEFAULTS: object

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

Experimental

The defaults of the optional fields of @lexical/y/offline, by name, so code can say which it relies on.

Type Declaration​

compactAfter​

readonly compactAfter: number

databaseName​

readonly databaseName: string

openTimeout​

readonly openTimeout: number


Y_OFFLINE_STAGES​

const Y_OFFLINE_STAGES: readonly YOfflineStage[]

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:115

Experimental

Every YOfflineStage, in rollout order.

Functions​

attachYOfflineSession()​

attachYOfflineSession(options): YOfflineSession

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1161

Experimental

Attach the offline layer to a bound editor. Start here:

  1. const opened = await openYOfflineStore({idb: {indexedDB, IDBKeyRange}});
  2. const loaded = await loadYOffline({store, key}), and create the document from loaded.state (null: none stored, fetch it);
  3. const session = attachYOfflineSession({binding, key, epoch: loaded.epoch, loaded, offline: {stage, store, persist: 'document'}, onError, stopSync});
  4. const verdict = await session.serverEpoch(epoch) whenever the server names its epoch: before the provider syncs (every connect and reconnect), and when the room is replaced or upgraded. 'same' means sync, 'moved' means the document was frozen and captured and stopSync was called;
  5. verdict.markSynced() (a 'same' verdict's) when the server holds the document;
  6. on the document the page syncs (a fresh one after 'moved'), await recoverYOfflineEdits({..., leftovers}): at stage 'replay' it reapplies what did not sync and writes the rest into the document (leftovers: {wrap: wrapLeftoversAsQuote('…')}).

Parameters​

options​

YOfflineSessionOptions

Returns​

YOfflineSession


describeYOfflineCapture()​

describeYOfflineCapture(capture, options): YOfflineResult<YOfflineReport>

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1341

Experimental

What a capture changed, block by block (describeUnsyncedEdits), against the document as it is now. Blocks the document already holds as the user had them are left out (an edit that did reach the server, or one already reapplied): an empty blocks with orderDiffers false means the capture can be deleted.

Parameters​

capture​

YOfflineCapture

options​

YOfflineDescribeOptions

Returns​

YOfflineResult<YOfflineReport>


loadYOffline()​

loadYOffline(input): Promise<YOfflineResult<YOfflineLoaded>>

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:179

Experimental

Read the document stored for key. Pass the result to attachYOfflineSession as loaded, with epoch: loaded.epoch.

  • Without epoch (bind, then sync: the page starts from the store, with no connection): the newest slot. Create the document from state, and call session.serverEpoch(epoch) when the server names its epoch.
  • With epoch, the server's (sync, then bind: the page has the server's document and epoch before it binds): only the slot at that epoch. Apply its state to the server's document (the same lineage, so it merges: the edits that did not sync go out on the next sync), and bind. A slot at another epoch is never loaded: recoverYOfflineEdits turns it into a capture. Call session.serverEpoch(epoch) once after attaching (it answers 'same' at once): its verdict's markSynced() is how the session learns the server holds the document.

Rows of a tab still open (with its writer lock) are read too, so a page shows what another tab of the document holds; where they are the only unsynced edits (unsyncedInLiveTabs), the session does not capture them as this page's when the epoch moved (that tab does). A key has more than one slot only when a tab was left at an earlier epoch.

Parameters​

input​
epoch?​

string

The epoch the server's room is at, when the page knows it before binding.

key​

string

store​

YOfflineStore

Returns​

Promise<YOfflineResult<YOfflineLoaded>>


openYOfflineStore()​

openYOfflineStore(options): Promise<YOfflineResult<YOfflineStore>>

Defined in: packages/lexical-y/src/internal/OfflineStore.ts:1739

Experimental

Open the local store: one IndexedDB database per app, which holds every document's slots and captures. Never throws for a storage failure: a browser without IndexedDB returns 'unavailable', and the app goes on without local persistence.

Parameters​

options​

YOfflineStoreOptions

Returns​

Promise<YOfflineResult<YOfflineStore>>

Example​

const opened = await openYOfflineStore({
idb: {indexedDB: globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange},
});
if (!opened.ok) showNotSavedLocally(opened.error.message);

recoverYOfflineEdits()​

recoverYOfflineEdits(input): Promise<YOfflineResult<YOfflineRecovered[]>>

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:2266

Experimental

On a fresh document at the current epoch, after its first sync: gather what did not sync and, at stage 'replay', put it back. In order:

  1. every slot of key left at another epoch (a tab that closed before it could freeze), or never synced (edits made on this device that never reached a server: their base is unknown, so nothing of them is replayable), becomes a capture;
  2. each capture is described against the document as it is now;
  3. at stage 'replay', each capture this call claims (once, across tabs) is written in one editor update, one undo step: its replayable blocks are applied, and with leftovers: {wrap} every other block the user added or changed is written through wrap (see replayUnsyncedEdits). The capture is then resolved (capture.resolved): nothing of it is left to show. A capture claimed more than a minute ago and never resolved (its tab closed, or its blocks went to a handler) is taken again;
  4. with leftovers: {handle}, the handler is called with the blocks each capture has left (at 'persist', all of them; at 'replay', those not applied), and the capture stays until your app deletes it;
  5. a capture with nothing left to show is deleted once the server holds the document: only with session, the document's offline session, reporting no unsynced edits (after its 'same' verdict's markSynced()). Without it, or while the document holds edits the server lacks (a replay that has not synced), such a capture is returned with no blocks: until the server holds what was written, the capture may be its only stored copy.

The result is the Offline edits panel's content: at 'replay' with wrap, what was reapplied and where the rest was inserted. Stage 'off' returns an empty list and touches nothing.

Parameters​

input​

YOfflineRecoverInput

Returns​

Promise<YOfflineResult<YOfflineRecovered[]>>


replayUnsyncedEdits()​

replayUnsyncedEdits(input): YReplayResult

Defined in: packages/lexical-y/src/internal/OfflineSession.ts:1819

Experimental

Apply a report to the bound editor, as one editor update the binding writes and one undo step. Nothing of the report is dropped:

  • a replayable block is applied: a changed block replaces the current one, an added block is inserted after the nearest block before it that the document holds (before the nearest after it when there is none; at the end for a report built by hand without order), a deleted block is removed. Each is checked again against the editor as it is now (the block still equals the base, an added block's id is still absent), so a block someone else changed is never overwritten;
  • every other block the user added or changed (both sides changed it, it is gone, the report has no base or no ids, it changed since the report) goes where the required leftovers says: with {wrap: wrapLeftoversAsQuote('…')}, into the document in the same update, through wrap, with new block ids (inserted); with {handle: blocks => …}, to your handler, which is then the only place they are.

only limits it to those block ids (the panel's Reapply button). Call it outside an editor update (not from an update listener or a command handler): the edit must be written before it returns. With wrap, call it once per report: a second call (or a Reapply of a block it already wrote) writes the leftovers again, since nothing tells written copies from the user's (recoverYOfflineEdits keeps that record on the capture, resolved). It throws, with nothing written, when the editor update fails or the binding does not store it (it turns read only).

Parameters​

input​

YReplayInput

Returns​

YReplayResult

Example​

const {applied, inserted} = replayUnsyncedEdits({
autoReplay: 'replayable',
binding,
report,
leftovers: {wrap: wrapLeftoversAsQuote('Offline edits that did not merge')},
});

wrapLeftoversAsQuote()​

wrapLeftoversAsQuote(label): YLeftoversWrap

Defined in: packages/lexical-y/src/internal/OfflineLeftovers.ts:616

Experimental

A ready YLeftoversWrap: a paragraph with label in bold, then each block the user had. A paragraph with text becomes a quote where the editor has quotes (@lexical/rich-text); every other block (a heading, a list, a table, an empty paragraph), and a paragraph where it has none, stays as it was. It needs only the paragraph and text nodes every editor has.

label may be a function of the call's context, to name the time or the place:

Parameters​

label​

string | ((context) => string)

Returns​

YLeftoversWrap

Example​

recoverYOfflineEdits({
// ...
leftovers: {
wrap: wrapLeftoversAsQuote(
({capturedAt}) =>
`Offline edits that did not merge · ${new Date(capturedAt).toLocaleString()}`,
),
},
});