@lexical/y/offline

Interfaces

YOfflineBinding

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

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

Experimental

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

status

readonly status: YStatus

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

Experimental

'active' when edits can be replayed into it.

Methods

freeze()

freeze(): YLocalEdits

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

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

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

Experimental

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

capturedAt

readonly capturedAt: number

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

Experimental

When it was captured (Unix ms).

claimed

readonly claimed: boolean

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

Experimental

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

differs

readonly differs: boolean

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

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

Experimental

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

id

readonly id: string

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

Experimental

Unique per key.

json

readonly json: unknown

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

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

Experimental

reason

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

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

Experimental

state

readonly state: Uint8Array

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

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

Experimental

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

---

YOfflineDescribeOptions

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

Experimental

What describeYOfflineCapture reads a capture with.

Properties

config

readonly config: HeadlessYConfig

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

Experimental

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

current

readonly current: Uint8Array

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

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

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

---

YOfflineError

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

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.

Properties

cause?

readonly optional cause?: unknown

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

Experimental

The underlying error, when there is one.

code

readonly code: YOfflineErrorCode

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

Experimental

epoch?

readonly optional epoch?: string | null

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

Experimental

With 'corrupt' or 'newer' from a slot: the slot's epoch (null: the never-synced slot), for store.clear(key, {epoch, captures: false}).

limit?

readonly optional limit?: "keys" | "bytes"

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

Experimental

With 'limit': which limit (see YOfflineLimits).

message

readonly message: string

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

Experimental

What happened and what the app can do about it.

salvage?

readonly optional salvage?: YOfflineSalvage

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

Experimental

With 'corrupt': what the readable rows hold (their merge, the base apart), so the app can offer it before clearing the slot.

---

YOfflineLimits

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

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

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

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

Experimental

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

---

YOfflineLoaded

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

Experimental

What loadYOffline read.

Properties

base

readonly base: Uint8Array<ArrayBufferLike> | null

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

Experimental

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

epoch

readonly epoch: string | null

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

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

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

Experimental

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

---

YOfflineLocks

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

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

Experimental

Returns

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

request()

request(name, callback): Promise<unknown>

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

Experimental

Parameters

name

string

callback

(lock) => Promise<unknown>

Returns

Promise<unknown>

---

YOfflineRecovered

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

Experimental

One capture of recoverYOfflineEdits' result.

Properties

capture

readonly capture: YOfflineCapture

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

Experimental

replay

readonly replay: YReplayResult | null

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

Experimental

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

report

readonly report: YOfflineResult<YOfflineReport>

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

Experimental

What is left to show, or why the capture could not be read.

---

YOfflineReport

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

Experimental

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

Extends

• YUnsyncedReport

Properties

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

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

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

Experimental

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

orderDiffers

readonly orderDiffers: boolean

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

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

---

YOfflineSalvage

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

Experimental

What a corrupt slot still holds (see YOfflineError).

Properties

readableRows

readonly readableRows: number

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

Experimental

state

readonly state: Uint8Array<ArrayBufferLike> | null

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

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

Experimental

---

YOfflineSession

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

Experimental

An attached session (see attachYOfflineSession).

Properties

ended

readonly ended: boolean

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

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

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

Experimental

Whether the document may hold edits the server lacks.

persisted

readonly persisted: boolean

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

Experimental

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

stage

readonly stage: YOfflineStage

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

Experimental

Methods

dispose()

dispose(): void

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

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

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

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>

markSynced()

markSynced(): void

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

Experimental

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 keep: 'unsynced', deleted). "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. A reload drops what the relay holds above that copy. 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).

Returns

void

serverEpoch()

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

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

Experimental

Tell the session the epoch the server's room is at: call it before the provider syncs this document (on every connect), and when the server says the room was replaced. The binding is frozen before this returns its promise, so nothing typed after a 'moved' is lost or written.

Parameters

epoch

string

options?

reason?

"stale" | "legacy" | "expired"

Returns

Promise<YOfflineVerdict>

---

YOfflineSessionOptions

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

Experimental

Options of attachYOfflineSession: binding, store, key, epoch, stage and onError are required.

Properties

binding

readonly binding: YOfflineBinding

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

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

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

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.

keep?

readonly optional keep?: "document" | "unsynced"

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

Experimental

What persistEdits keeps on the device:

• 'document' (the default): the whole document, always (its base and what came since), so the page can open it with no connection (loadYOffline);
• 'unsynced': 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 markSynced() deletes them.

Default Value

'document'

key

readonly key: string

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

Experimental

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

loaded?

readonly optional loaded?: YOfflineLoaded

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

Experimental

What loadYOffline returned, when the document was created from it: its base and its stored rows continue here.

now?

readonly optional now?: () => number

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

Experimental

The clock, for tests.

Returns

number

Default Value

Date.now

onError

readonly onError: (error) => void

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

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

persistEdits?

readonly optional persistEdits?: boolean

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

Experimental

true (the default): every update is stored as it is made, so the document survives a reload, a crash or a closed tab with no connection, and a later page captures what did not sync. false: only captures are stored (a moved epoch while the tab is open); unsynced edits live in the tab until it syncs, and adds no update listener. Whether the editor is editable before the server answers (offline editing) is the app's choice, made when it binds (synced), not this one.

Default Value

true

stage

readonly stage: YOfflineStage

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

Experimental

The rollout stage (see YOfflineStage).

store

readonly store: YOfflineStore | null

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

Experimental

From openYOfflineStore; null only with stage 'off'.

writeDelay?

readonly optional writeDelay?: number

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

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.

Default Value

0

---

YOfflineSlot

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

Experimental

One (key, epoch) of a YOfflineStore.

Properties

epoch

readonly epoch: string | null

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

Experimental

Changes with YOfflineSlot.adopt.

key

readonly key: string

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

Experimental

rowsSinceCompaction

readonly rowsSinceCompaction: number

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

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

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

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

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

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): Promise<YOfflineResult<void>>

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

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.

Parameters

state

Uint8Array

Returns

Promise<YOfflineResult<void>>

discard()

discard(): Promise<YOfflineResult<void>>

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

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

load()

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

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

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

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

Experimental

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

Properties

epoch

readonly epoch: string | null

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

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

Experimental

key

readonly key: string

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

Experimental

rows

readonly rows: number

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

Experimental

updatedAt

readonly updatedAt: number

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

Experimental

When its newest row was written (Unix ms).

---

YOfflineStore

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

Experimental

The local store (see openYOfflineStore).

Methods

captures()

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

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

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

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): Promise<YOfflineResult<boolean>>

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

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.

Parameters

key

string

id

string

Returns

Promise<YOfflineResult<boolean>>

clear()

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

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

Experimental

Delete what is stored for key: one slot when what.epoch is given (null names the never-synced slot), else every slot; its captures too with what.captures.

Parameters

key

string

what

captures

boolean

epoch?

string | null

Returns

Promise<YOfflineResult<void>>

close()

close(): void

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

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

Experimental

Parameters

key

string

id

string

Returns

Promise<YOfflineResult<void>>

keys()

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

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

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

Experimental

Parameters

capture

YOfflineCapture

Returns

Promise<YOfflineResult<void>>

slot()

slot(key, epoch): YOfflineSlot

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

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

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

Experimental

What a slot holds (see YOfflineSlot.load).

Properties

base

readonly base: Uint8Array<ArrayBufferLike> | null

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

Experimental

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

hasUnsyncedEdits

readonly hasUnsyncedEdits: boolean

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

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

Experimental

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

---

YOfflineStoreOptions

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

Experimental

Options of openYOfflineStore.

Properties

databaseName?

readonly optional databaseName?: string

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

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

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

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

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

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

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

Experimental

What replayUnsyncedEdits did.

Properties

applied

readonly applied: readonly string[]

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

Experimental

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

notApplied

readonly notApplied: readonly object[]

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

Experimental

The blocks left for the panel, with why.

Type Aliases

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).

---

YOfflineResult

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

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

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

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': every edit is stored on the device as it is made (persistEdits), and a document whose epoch moved (a reconnect to a replaced or upgraded room) is frozen and stored with its base, for the Offline edits panel;
• 'replay': as 'persist', and recoverYOfflineEdits applies the blocks that are replayable.

---

YOfflineVerdict

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

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

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"; }

The document belongs to this epoch (or just adopted it): sync it.

---

Type Literal

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

The room moved on. The binding is frozen 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).

---

YReplaySkipReason

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

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

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

Experimental

Every YOfflineStage, in rollout order.

Functions

attachYOfflineSession()

attachYOfflineSession(options): YOfflineSession

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

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, store, key, epoch: loaded.epoch, loaded, stage, onError});
4. 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;
5. session.markSynced() when the server holds the document;
6. on the document the page syncs (a fresh one after 'moved'), await recoverYOfflineEdits({...}) for the Offline edits panel (and the replay, at stage 'replay').

Parameters

options

YOfflineSessionOptions

Returns

YOfflineSession

---

describeYOfflineCapture()

describeYOfflineCapture(capture, options): YOfflineResult<YOfflineReport>

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

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

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. There is nothing to ask serverEpoch until the server replaces the room.

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

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

Experimental

On a fresh document at the current epoch, after its first sync: gather what did not sync and, at stage 'replay', reapply what is safe. 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) has its replayable blocks applied as one undo step;
4. 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 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, for the panel to dismiss: until the server holds what was reapplied, the capture may be its only stored copy.

The result is the Offline edits panel's content. Stage 'off' returns an empty list and touches nothing.

Parameters

input

binding

YOfflineBinding

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

config

HeadlessYConfig

epoch

string

The epoch the fresh document is at.

key

string

migrate?

(state) => Uint8Array

now?

() => number

The clock, for tests.

Default Value

Date.now

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

YOfflineStage

store

YOfflineStore | null

Returns

Promise<YOfflineResult<YOfflineRecovered[]>>

---

replayUnsyncedEdits()

replayUnsyncedEdits(input): YReplayResult

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

Experimental

Apply a report's replayable blocks to the bound editor, as one editor update the binding writes and one undo step: 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 plain YUnsyncedReport, which does not carry the user's 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: it comes back in notApplied.

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.

Parameters

input

binding

YOfflineBinding

only?

readonly string[]

report

YUnsyncedReport | YOfflineReport

Returns

YReplayResult

Example

const {applied, notApplied} = replayUnsyncedEdits({binding, report});