Skip to content

StorageRoot

Defined in: src/storage-root.ts:144

The base directory holding OCFL objects.

readonly layout: Layout

Defined in: src/storage-root.ts:150

The storage root’s layout, with every parameter present.


readonly ocflVersion: OcflVersion

Defined in: src/storage-root.ts:148

OCFL version of the storage root, and of objects created in it.


readonly path: string

Defined in: src/storage-root.ts:146

Absolute path of the storage root.

create(id, details, build, options?): Promise<OcflObject>

Defined in: src/storage-root.ts:213

Creates an object with the draft built by build as its first version. If build throws, nothing is created. The object uses sha512 digests and the content directory, at the storage root’s OCFL version.

string

VersionDetails

(draft) => Promise<unknown>

UpdateOptions

Promise<OcflObject>

OcflError OBJECT_EXISTS if an object with this id already exists.

OcflError DIRECTORY_NOT_EMPTY if something appeared in the object’s directory while its first version was being built. Nothing is created.

OcflError INVALID_OBJECT if an invalid object declaration appeared in the object’s directory while its first version was being built (E007). Nothing is created.

OcflError ID_INCOMPATIBLE_WITH_LAYOUT if the layout can’t map the id to a directory the file system can hold, with its lock in the workspace.

OcflError OBJECT_ROOT_CONFLICT if that directory holds something else, is a file or is below one, or is inside another object.

OcflError UPDATE_IN_PROGRESS if another writer is creating the same object, or died creating it; lockedAt says since when, and is absent if the lock couldn’t be read or was released meanwhile.

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 create failed after its root inventory was put in place, failed putting it in place in a way that may have done so, or failed earlier and what it made couldn’t all be removed; cause is the failure. The object may have been created, and stays locked. Also thrown, before build runs, if an earlier create left an unfinished version in the workspace, or the create was refused and its lock couldn’t be released. Don’t simply repeat the create: recover the object’s unfinished write (StorageRoot.unfinishedWrite), then open the object to see whether it was created.

TypeError if the id, 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. Nothing is created.

Error if build 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 build caught the error a draft operation rejected with; nothing of the object is left, and it isn’t locked. A signal already aborted is refused before the lock is taken.

Whatever build or a draft operation throws; nothing of the object is left, and it isn’t locked.

The file system error that stopped the create before its root inventory was put in place; nothing is created.

const object = await root.create(id, { message: 'Initial deposit', user: { name: 'Alice' } }, async (draft) => {
await draft.write('ro-crate-metadata.json', JSON.stringify(metadata));
});

has(id): Promise<boolean>

Defined in: src/storage-root.ts:186

Whether there is an object with this id: true exactly when StorageRoot.create would throw OBJECT_EXISTS. A create that another writer hasn’t committed gives false. The inventory isn’t read or checked, so a damaged object gives true, and StorageRoot.open then reports the damage.

Another writer can create the object between has() and a create(); to create an object only if it is absent, catch OBJECT_EXISTS from create() instead.

string

Promise<boolean>

OcflError ID_INCOMPATIBLE_WITH_LAYOUT if the layout can’t map the id to a directory the file system can hold.

TypeError if the id is missing or empty.

The file system error if the object’s directory, inventory or lock can’t be checked.

if (!(await root.has(id))) {
await root.create(id, details, build);
}

objects(): AsyncIterable<ListedObject>

Defined in: src/storage-root.ts:235

Lists every object in the storage root, in no particular order. Each object is read when the listing reaches it, and yielded as { object }. A damaged object root, one whose object can’t be opened, is yielded as { error, objectRoot, id? }, and the listing carries on. A directory with an invalid object declaration is a damaged object root: it isn’t searched for objects. So is an object whose OCFL version is later than the storage root’s (E081).

An object that another writer is creating and hasn’t committed is left out, and so is the extensions directory. Leaving the loop early closes every directory the listing opened.

AsyncIterable<ListedObject>

The file system error that stopped the listing.

for await (const entry of root.objects()) {
if ('error' in entry) {
console.warn(`${entry.objectRoot}: ${entry.error.code} ${entry.error.ocflCode ?? ''}`);
continue;
}
await index(entry.object.id, entry.object.head.files);
}

open(id): Promise<OcflObject>

Defined in: src/storage-root.ts:168

Reads an object’s inventory and returns the object as it is now. It does not change when later versions are committed.

string

Promise<OcflObject>

OcflError OBJECT_NOT_FOUND if there is no object with this id, or another writer is creating it and hasn’t committed it.

OcflError INVALID_OBJECT if the object’s inventory is missing, corrupt or inconsistent, the object has no declaration or an invalid one, its OCFL version is later than the storage root’s (E081), or it is inside another object (E082).

OcflError ID_INCOMPATIBLE_WITH_LAYOUT if the layout can’t map the id to a directory the file system can hold.

OcflError OBJECT_ROOT_CONFLICT if that directory holds an object with another id, or holds files that aren’t an object, is a file or is below one.

TypeError if the id is missing or empty.

The file system error if a file or directory the object is read from, or checked against, exists but can’t be read.

const object = await root.open('arcp://name,corpus/item/1');
const file = object.head.files.get('ro-crate-metadata.json');
const metadata = JSON.parse(await file!.text());

remove(id): Promise<void>

Defined in: src/storage-root.ts:255

Deletes an object and all its versions, and the parent directories that leaves empty. The object’s lock is held while it is deleted.

string

Promise<void>

OcflError OBJECT_NOT_FOUND if there is no object with this id.

OcflError UPDATE_IN_PROGRESS if the object is being updated or created, or a writer died doing so; lockedAt says since when. Nothing is deleted. After a dead writer, recover its unfinished write (StorageRoot.unfinishedWrite) and then remove again.

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

OcflError INVALID_OBJECT if the id’s directory holds an object whose inventory is missing, corrupt or inconsistent, so its id can’t be confirmed; nothing is deleted.

OcflError ID_INCOMPATIBLE_WITH_LAYOUT if the layout can’t map the id to a directory the file system can hold, with its lock in the workspace; nothing is deleted.

OcflError OBJECT_ROOT_CONFLICT if that directory holds an object with another id, or holds files that aren’t an object, is a file or is below one; nothing is deleted.

TypeError if the id is missing or empty.

OcflError RECOVERY_NEEDED if deleting the object failed part of the way through, or it was deleted and its lock couldn’t be released; cause is the failure. The object stays locked, and may be partly deleted: recovering its unfinished write (StorageRoot.unfinishedWrite) finishes removing it. Also thrown if the remove was refused and its lock couldn’t be released; nothing is deleted, and recovering only releases the lock, so remove again after it.

The file system error that stopped the remove before it began deleting; nothing is deleted.

await root.remove('arcp://name,corpus/item/1');

unfinishedWrite(id): Promise<UnfinishedWrite | undefined>

Defined in: src/storage-root.ts:287

The unfinished write of an object: its create, update or remove whose lock is still held. Nothing is changed.

string

Promise<UnfinishedWrite | undefined>

The write, or undefined if the object isn’t locked

OcflError ID_INCOMPATIBLE_WITH_LAYOUT if the layout can’t map the id to a directory the file system can hold.

OcflError OBJECT_ROOT_CONFLICT if that directory is locked by a writer of another id.

TypeError if the id is missing or empty.

The file system error if the object’s lock exists but can’t be read.

const write = await root.unfinishedWrite(id);
if (write) console.log(`Locked since ${write.lockedAt.toISOString()}`);

unfinishedWrites(): AsyncIterable<UnfinishedWrite>

Defined in: src/storage-root.ts:271

Lists every unfinished write in the storage root, in no particular order: each create, update or remove whose lock is still held. The library can’t tell whether a write’s writer is still working or died; lockedAt is what it offers towards deciding. Nothing is changed.

AsyncIterable<UnfinishedWrite>

The file system error that stopped the listing.

// After this host crashed: it was the storage root's only writer, so none of the writes before the crash is alive
for await (const write of root.unfinishedWrites()) {
if (write.lockedAt < crashedAt) await write.recover();
}