OcflObject
Defined in: src/ocfl-object.ts:45
An OCFL object as read at one moment.
Properties
Section titled “Properties”digestAlgorithm
Section titled “digestAlgorithm”
readonlydigestAlgorithm:DigestAlgorithm
Defined in: src/ocfl-object.ts:51
Algorithm of every OcflFile.digest in this object.
readonlyhead:Version
Defined in: src/ocfl-object.ts:55
The latest version.
readonlyid:string
Defined in: src/ocfl-object.ts:47
The object’s identifier.
ocflVersion
Section titled “ocflVersion”
readonlyocflVersion:OcflVersion
Defined in: src/ocfl-object.ts:49
OCFL version the object conforms to.
versions
Section titled “versions”
readonlyversions:ReadonlyMap<number,Version>
Defined in: src/ocfl-object.ts:53
Every version, keyed by version number, oldest first.
Methods
Section titled “Methods”checkFixity()
Section titled “checkFixity()”checkFixity(
options?):Promise<readonlyFixityProblem[]>
Defined in: src/ocfl-object.ts:105
Reads every stored file again and compares its digest with the inventory. An empty list means the object is intact.
Covers the versions this object knows about. Does not look for extra files or check the fixity block.
Each problem names its stored file by its path from the storage root, and lists the versions and logical paths that read it.
Problems are sorted by stored file.
onProgress is called after each stored file is checked, whether it passed, changed or is missing, and reaches every file before the check resolves.
Aborting signal stops the check, and no stored file is still open or being read once it rejects.
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”Promise<readonly FixityProblem[]>
Throws
Section titled “Throws”signal.reason if signal is aborted, before anything is read if it already is.
Throws
Section titled “Throws”Whatever onProgress throws, which stops the check.
Throws
Section titled “Throws”The file system error, such as EACCES or EIO, if a stored file can’t be read for any reason but being missing.
Example
Section titled “Example”const problems = await object.checkFixity({ signal: AbortSignal.timeout(10 * 60_000), onProgress: ({ checkedFiles, totalFiles }) => bar.update(checkedFiles / totalFiles),});isCurrent()
Section titled “isCurrent()”isCurrent():
Promise<boolean>
Defined in: src/ocfl-object.ts:126
Whether the object’s root inventory is still the file this object was read from: false once it has been replaced, changed or removed.
Every commit replaces the root inventory, so a commit by any writer makes it false; an update that hasn’t been committed doesn’t.
The object returned by StorageRoot.create or OcflObject.update is current straight away.
A cheap check, not a guarantee: one stat of the root inventory, comparing its device, inode, size and modification time with those
noted when it was read, and nothing read or validated. A file system can reuse an inode number, so a replaced root inventory of the same
size and modification time could still give true, though that is unlikely.
Returns
Section titled “Returns”Promise<boolean>
Throws
Section titled “Throws”The file system error if the root inventory can’t be checked for any reason but being missing.
Example
Section titled “Example”let object = cache.get(id);if (!object || !(await object.isCurrent())) { object = await root.open(id); cache.set(id, object);}update()
Section titled “update()”update(
details,change,options?):Promise<OcflObject>
Defined in: src/ocfl-object.ts:83
Commits one new version made from the draft changed by change. If change throws, everything is discarded.
Returns the object with the new version, or this object if the draft ended the same as the head.
The update is committed when the root inventory is replaced: any error but RECOVERY_NEEDED means it wasn’t committed and can be repeated.
This object never changes, whatever the outcome.
Parameters
Section titled “Parameters”details
Section titled “details”change
Section titled “change”(draft) => Promise<unknown>
options?
Section titled “options?”Returns
Section titled “Returns”Promise<OcflObject>
Throws
Section titled “Throws”OcflError INVALID_OBJECT if the object’s declaration has been damaged, or removed while anything remains in its object root, or now declares a later OCFL version than the storage root’s (E081), or the object is now inside another object, since it was opened.
Throws
Section titled “Throws”OcflError MUTABLE_HEAD_ACTIVE if the object has an active mutable head (extension 0005).
Throws
Section titled “Throws”OcflError VERSION_LIMIT_REACHED if the object’s version names are zero-padded and the next one couldn’t start with a zero, as OCFL requires (E011): v01 to v09 leaves none.
Throws
Section titled “Throws”OcflError OBJECT_OUT_OF_DATE if a later version has been committed, or the object removed, since this object was opened; open it again and retry.
Throws
Section titled “Throws”OcflError UPDATE_IN_PROGRESS if another writer is updating or removing this object, or died doing so; lockedAt says since when, and is absent if the lock couldn’t be read or was released meanwhile. The update never waits for it.
Throws
Section titled “Throws”OcflError CROSS_FILESYSTEM_MOVE if the workspace is on a different file system from the object.
Throws
Section titled “Throws”OcflError UNSUPPORTED_FILESYSTEM if the storage root’s file system doesn’t support hard links. Nothing is changed.
Throws
Section titled “Throws”OcflError RECOVERY_NEEDED if the update failed after the root inventory was replaced, failed replacing it in a way that may have replaced it, or failed earlier and what it made couldn’t all be removed; cause is the failure. The update may have been committed, and the object stays locked, so later updates throw UPDATE_IN_PROGRESS. Also thrown, before change runs, if an earlier update left an unfinished version in the workspace, or the update was refused and its lock couldn’t be released. Don’t simply repeat the update: recover the object’s unfinished write (StorageRoot.unfinishedWrite), then open the object again to see whether it was committed.
Throws
Section titled “Throws”TypeError if the message or the user’s name is missing or empty, the user’s address isn’t a string, or createdAt isn’t a valid Date or is earlier than the head version’s date. Nothing is changed.
Throws
Section titled “Throws”Error if change returned while draft operations it started were still running. Await every operation.
Throws
Section titled “Throws”options.signal.reason if the signal is aborted before the commit begins, even if change caught the error a draft operation rejected with; the update is discarded, and the object is as it was and isn’t locked. A signal already aborted is refused before the lock is taken.
Throws
Section titled “Throws”Whatever change or a draft operation throws; the update is discarded, and the object is as it was and isn’t locked.
Throws
Section titled “Throws”The file system error that stopped the update before the root inventory was replaced; the update is discarded.
Example
Section titled “Example”const updated = await object.update({ message: 'Fix transcript', user: { name: 'Alice' } }, async (draft) => { await draft.write('transcript.txt', corrected);});