Skip to content

OcflObject

Defined in: src/ocfl-object.ts:45

An OCFL object as read at one moment.

readonly digestAlgorithm: DigestAlgorithm

Defined in: src/ocfl-object.ts:51

Algorithm of every OcflFile.digest in this object.


readonly head: Version

Defined in: src/ocfl-object.ts:55

The latest version.


readonly id: string

Defined in: src/ocfl-object.ts:47

The object’s identifier.


readonly ocflVersion: OcflVersion

Defined in: src/ocfl-object.ts:49

OCFL version the object conforms to.


readonly versions: ReadonlyMap<number, Version>

Defined in: src/ocfl-object.ts:53

Every version, keyed by version number, oldest first.

checkFixity(options?): Promise<readonly FixityProblem[]>

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.

FixityOptions

Promise<readonly FixityProblem[]>

signal.reason if signal is aborted, before anything is read if it already is.

Whatever onProgress throws, which stops the check.

The file system error, such as EACCES or EIO, if a stored file can’t be read for any reason but being missing.

const problems = await object.checkFixity({
signal: AbortSignal.timeout(10 * 60_000),
onProgress: ({ checkedFiles, totalFiles }) => bar.update(checkedFiles / totalFiles),
});

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.

Promise<boolean>

The file system error if the root inventory can’t be checked for any reason but being missing.

let object = cache.get(id);
if (!object || !(await object.isCurrent())) {
object = await root.open(id);
cache.set(id, object);
}

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.

VersionDetails

(draft) => Promise<unknown>

UpdateOptions

Promise<OcflObject>

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.

OcflError MUTABLE_HEAD_ACTIVE if the object has an active mutable head (extension 0005).

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.

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.

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.

OcflError CROSS_FILESYSTEM_MOVE if the workspace is on a different file system from the object.

OcflError UNSUPPORTED_FILESYSTEM if the storage root’s file system doesn’t support hard links. Nothing is changed.

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.

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.

Error if change returned while draft operations it started were still running. Await every operation.

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.

Whatever change or a draft operation throws; the update is discarded, and the object is as it was and isn’t locked.

The file system error that stopped the update before the root inventory was replaced; the update is discarded.

const updated = await object.update({ message: 'Fix transcript', user: { name: 'Alice' } }, async (draft) => {
await draft.write('transcript.txt', corrected);
});