API reference / @docmentis/udoc-node / UDocSession

Interface: UDocSession

A session: one open document, driven on a worker thread of its own, so every call is asynchronous and none blocks the caller's event loop while the engine composes or rasterizes. As in the engine, the session is its document — opening one is the open, closing it is the close.

The thread is held until close. An idle session does not keep the process alive; a call in flight does.

Properties

Property	Description
readonly closed Promise<UDocError>	Settles once the session can take no more calls, with why: it was closed, or its engine crashed or its thread exited on its own — crashed. A host holding sessions watches this to let go of one that died.

Accessors

docType

get docType(): UDocType | undefined;

The open document's doc type ("portable", "presentation", …).

---

sourceFormat

get sourceFormat(): FileFormat | undefined;

The file format the document came from ("pdf", "pptx", …) — what saving it back means — or undefined for a package that recorded none.

---

fromPackage

get fromPackage(): boolean;

Whether the document was opened from a udoc package rather than imported from a file — which sourceFormat alone can't tell, since a package reports the format it recorded.

---

needsPassword

get needsPassword(): boolean;

Whether the document needs a password before it can be read — a PDF encrypted with a user password. Until authenticate unlocks it, every other call rejects; docType and sourceFormat are already known.

---

entitlements

get entitlements(): Entitlements | undefined;

What the license, or with none the permit, entitled the session to — the features a host checks before a call that needs one (the sync calls need collaboration). Advisory: the engine enforces each at the call it guards, rejecting with a notEntitled UDocError.

Methods

authenticate()

authenticate(password): Promise<boolean>;

Unlock the document, which needs a password, with password — its user or its owner password. Resolves true once it is open, and false when password is refused, the document waiting for another: try as often as it takes. Not a second open — no further permit is spent.

Parameters

Parameter	Type
password	string

---

pageCount()

pageCount(): Promise<number>;

How many pages the document's primary plane has.

A page is known only once it is composed, so this composes the whole plane — for a long flowing document, the cost of laying out all of it. Once paid it is not paid again: asking twice, or rendering any page after, reuses the composed pages. Rejects when a page fails to compose, since the count is then unknown.

---

saveToBytes()

saveToBytes(
   format, 
   strategy?, 
   delimiter?
): Promise<Uint8Array<ArrayBufferLike>>;

Save the document as format, faithfully — the bytes reopen as the same document. format is one of its doc type's own (a PDF saves to "pdf", a presentation to "pptx"); sourceFormat is what saving it back means. strategy is how much of the file it was opened from, the original, the saved bytes keep: a "delta" or "incremental" save writes over it, which a session opened with UDocNode.openRemote doesn't hold; without it, the one keeping the most of it that format saves by ("incremental" for a PDF, "rewrite" for a CSV, a TSV, a PSV or an image, else "delta"). delimiter is the character a CSV's fields are split by; without it, the one the document was opened with, else a comma. Rejects for a format its doc type doesn't save to, a format that never saves by strategy, a delimiter for a format that takes none, no original to write over, or a save that isn't built yet.

Parameters

Parameter	Type
format	FileFormat
strategy?	SaveStrategy
delimiter?	string

---

saveToPackage()

saveToPackage(version?): Promise<Uint8Array<ArrayBufferLike>>;

Save the document as a udoc package — the bytes of a .udoc zip, which UDocNode.open reopens. It records the source format, so a reopened package can still be saved back to it. version makes it a checkpoint, baseline v<version>, which keeps the edit log a reopen replays; without it the package is a flat baseline — the whole document and no log.

Parameters

Parameter	Type
version?	number

---

requestRemoteCopy()

requestRemoteCopy(strategy?): Promise<Uint8Array<ArrayBufferLike>>;

Ask the udoc server the document was opened from (UDocNode.openRemote) for a copy of it, saved as its sourceFormat by strategy, else by the engine's for it — a "delta" or "incremental" copy is the server's to save, since only it holds the original. Resolves with the copy's bytes. Asked with the global fetch, not the one the open was given, which only reads. Rejects for a document not opened with UDocNode.openRemote, or one that records no source format, and with the server's message for what it refuses.

Parameters

Parameter	Type
strategy?	SaveStrategy

---

requestRemoteCheckpoint()

requestRemoteCheckpoint(): Promise<RemoteCheckpointResponse>;

Ask the udoc server the document was opened from (UDocNode.openRemote) to checkpoint it: save its document as a new baseline. Resolves with that baseline's version. Nothing reopens: this session goes on as it was. Asked with the global fetch, as requestRemoteCopy is. Rejects for a document not opened with UDocNode.openRemote, and with the server's message for what it refuses.

---

exportToBytes()

exportToBytes(format): Promise<Uint8Array<ArrayBufferLike>>;

Export the whole document as format, "pdf" — a rendering of its laid-out pages, fixed and one-way. Rejects unsupported for a spreadsheet, whose sheets have no print pages yet.

Parameters

Parameter	Type
format	ExportFormat

---

exportPageToBytes()

exportPageToBytes(index, format): Promise<Uint8Array<ArrayBufferLike>>;

Export page index (0-based) of the document's primary plane as format: { png: { scale } }, where scale is output pixels per document point (1 is 72 DPI), or "svg", an SVG document sized in points.

Composes the document through that page first — not past it. Rejects notFound when the document turns out to have fewer pages; its message is the page count.

Parameters

Parameter	Type
index	number
format	PageExportFormat

---

snapshot()

snapshot(): Promise<Uint8Array<ArrayBufferLike>>;

The document's whole editing state — every edit since its baseline — for a peer that has none of it, to merge. For a peer that has some, patchSince sends only the rest.

---

versionVector()

versionVector(): Promise<Uint8Array<ArrayBufferLike>>;

Which edits this session holds, as the token a peer's patchSince takes to answer with only the ones this session lacks.

---

patchSince()

patchSince(peer): Promise<Uint8Array<ArrayBufferLike>>;

The edits this session holds that a peer — named by its versionVector — lacks, for that peer's merge.

Parameters

Parameter	Type
peer	Uint8Array

---

merge()

merge(patch): Promise<void>;

Apply a peer's edits — its snapshot or patchSince — to the document. Edits this session already holds are skipped, so merging the same patch twice changes nothing the second time. Rejects when the bytes aren't a patch.

Parameters

Parameter	Type
patch	Uint8Array

---

presence()

presence(): Promise<Uint8Array<ArrayBufferLike>>;

Every peer's presence this session knows of — each one's selection and name — for a peer's mergePresence. Transient: no history, never part of a save.

---

mergePresence()

mergePresence(presence): Promise<void>;

Take in a peer's UDocSession.presence, each peer's latest winning.

Parameters

Parameter	Type
presence	Uint8Array

---

close()

close(): Promise<void>;

Release the document and its thread. Calls still in flight reject.