Optionalpath: string | nullAdd a set of callbacks to receive notification.
The callbacks object.
Optionaloptions: IListener.Options
Options
A function that can be called to remove the listener.
Whether this source can be written back to (a silent re-save). A read-only source (e.g. a
fetched URL) returns false, signalling callers to prompt for a destination ("Save As").
The encryption envelope this source is wrapped in (e.g.
'offcrypto'), or null when it is plaintext.
The scheme actually on disk — discovered when the source is read, recorded when it is
written, and null until then. For "is or will be encrypted", which is what chrome and the
write path both actually ask, use isEncrypted.
Never the password: origins are rendered into logs and REPL output, and ride events and
progress callbacks, so a secret has no business here (see PROTECTION-DESIGN.md §5f).
Use it to show a lock affordance, and to recognise that writing plaintext over it would be a downgrade — IWorkbookIO.WriteOptions.password makes that refusal explicit.
Unrelated to sheet/workbook protection, which is a hash gate stored in the model.
The path's file extension, lower-cased and without the dot (e.g. 'xlsx'),
or null when the origin is unbound or its path has no extension.
The handle's physical type, as distinct from getFormat's semantic one: a format
key ('SheetXL') is not a file extension ('sxl'), and one is not derivable from the other
without the registry. Use this wherever a file name is being built (a suggested name, a
download name); use getFormat() to resolve a handler.
The resolved format key (e.g. 'xlsx'), or null if unknown. Derived from the
path extension when not set explicitly.
The handle's resource type — the analog of a File.type / Content-Type: most file
systems make the type part of the handle, and so does this one. The full
IWorkbookIO.FormatType (description, extensions, mime) is a
getReadFormats({ search: key }) / getWriteFormats({ search: key }) lookup away.
When the file was last modified, in milliseconds since the epoch, or null if unknown — a
stat-style property like getSize (the analog of File.lastModified), recorded when
the file is read and updated when it is written.
The display name (without extension), e.g. 'report' — derived from the
path when not set explicitly — or null for an unbound, unnamed origin.
Display fallbacks (e.g. a localized "Untitled") are a UI concern.
The session password, or null.
The privileged read channel, deliberately on the class and not on the IWorkbookIO.Origin interface — the same arrangement as update. Only the IO layer uses it, to encrypt on write; consumers can set a password but never read one back.
The full path or URL, e.g. './out/report.xlsx' or 'https://host/report.xlsx', or null
for an unbound (in-memory) origin.
The last-known size of the source in bytes, or null if unknown — a stat-style property
(the analog of FileSystemFileHandle.getFile().size), updated by the IO/store layer on
each read/write of this handle.
Whether this source is encrypted, or would be if written now.
true when the source was read as encrypted, was written encrypted, or has had a password
set via setPassword that no save has applied yet. That last case is why this exists
separately from getEncryption, which reports the scheme actually on disk and is null
until a save happens.
This is the question chrome asks (show a lock?) and the question a write asks (would writing plaintext be a downgrade?).
Set the display name (a label, without extension). Fires onChange (and, through the
workbook, onNameChange).
Sets — or clears, with null — the password this source is encrypted with, for this session.
Set-only. There is no getter on this interface: a password can be handed in and cleared,
never read back. A UI collects one and passes it here; keeping a copy buys nothing and only
widens the exposure. (The IO layer reads it through a privileged channel on the concrete
WorkbookOrigin, the same way it mutates the rest of the handle.)
Non-privileged, exactly like setName: both record what the next write should do,
and neither is on disk until it happens. Clearing with null is the "remove password" verb
and is carried into that write.
The password lives and dies with the handle — nothing survives the session, and a closed workbook takes it with it.
Returns a string representation of an object.
Update what is known about the file in place. Fires onChange if anything actually changed.
The privileged mutation channel (see DESIGN-IO.md) for the backing store and the IO layer:
the written size, the encryption on disk, the format key a read resolved. Never format handlers,
never the model, never chrome.
There is no path: an origin names one file for its whole life. A save that resolves another
destination mints a new origin for it (see DESIGN-IO.md §11).
Default, observable IWorkbookIO.Origin implementation vended by the IO layer — the concrete "light virtual file handle" (see
IO-DESIGN.md).Remarks
Names one file for its whole life. What is known about that file — its size, its encryption, its display label — can change in place (update, setName), firing
onChangeso holders — including the workbook, whosegetName()/onNameChangederive from this — follow. Source logic (paths, URLs, formats) lives here, in the IO layer, not in the workbook model.An unbound origin (
path: null) belongs to an in-memory workbook with no destination yet; a save that resolves one moves the workbook to a new origin, leaving this one as it was.