StorageRoot
Defined in: src/storage-root.ts:144
The base directory holding OCFL objects.
Properties
Section titled “Properties”layout
Section titled “layout”
readonlylayout:Layout
Defined in: src/storage-root.ts:150
The storage root’s layout, with every parameter present.
ocflVersion
Section titled “ocflVersion”
readonlyocflVersion:OcflVersion
Defined in: src/storage-root.ts:148
OCFL version of the storage root, and of objects created in it.
readonlypath:string
Defined in: src/storage-root.ts:146
Absolute path of the storage root.
Methods
Section titled “Methods”create()
Section titled “create()”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.
Parameters
Section titled “Parameters”string
details
Section titled “details”(draft) => Promise<unknown>
options?
Section titled “options?”Returns
Section titled “Returns”Promise<OcflObject>
Throws
Section titled “Throws”OcflError OBJECT_EXISTS if an object with this id already exists.
Throws
Section titled “Throws”OcflError DIRECTORY_NOT_EMPTY if something appeared in the object’s directory while its first version was being built. Nothing is created.
Throws
Section titled “Throws”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.
Throws
Section titled “Throws”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.
Throws
Section titled “Throws”OcflError OBJECT_ROOT_CONFLICT if that directory holds something else, is a file or is below one, or is inside another object.
Throws
Section titled “Throws”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.
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 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.
Throws
Section titled “Throws”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.
Throws
Section titled “Throws”Error if build 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 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.
Throws
Section titled “Throws”Whatever build or a draft operation throws; nothing of the object is left, and it isn’t locked.
Throws
Section titled “Throws”The file system error that stopped the create before its root inventory was put in place; nothing is created.
Example
Section titled “Example”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.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<boolean>
Throws
Section titled “Throws”OcflError ID_INCOMPATIBLE_WITH_LAYOUT if the layout can’t map the id to a directory the file system can hold.
Throws
Section titled “Throws”TypeError if the id is missing or empty.
Throws
Section titled “Throws”The file system error if the object’s directory, inventory or lock can’t be checked.
Example
Section titled “Example”if (!(await root.has(id))) { await root.create(id, details, build);}objects()
Section titled “objects()”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.
Returns
Section titled “Returns”AsyncIterable<ListedObject>
Throws
Section titled “Throws”The file system error that stopped the listing.
Example
Section titled “Example”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()
Section titled “open()”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.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<OcflObject>
Throws
Section titled “Throws”OcflError OBJECT_NOT_FOUND if there is no object with this id, or another writer is creating it and hasn’t committed it.
Throws
Section titled “Throws”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).
Throws
Section titled “Throws”OcflError ID_INCOMPATIBLE_WITH_LAYOUT if the layout can’t map the id to a directory the file system can hold.
Throws
Section titled “Throws”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.
Throws
Section titled “Throws”TypeError if the id is missing or empty.
Throws
Section titled “Throws”The file system error if a file or directory the object is read from, or checked against, exists but can’t be read.
Example
Section titled “Example”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()
Section titled “remove()”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.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”OcflError OBJECT_NOT_FOUND if there is no object with this id.
Throws
Section titled “Throws”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.
Throws
Section titled “Throws”OcflError UNSUPPORTED_FILESYSTEM if the storage root’s file system doesn’t support hard links. Nothing is deleted.
Throws
Section titled “Throws”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.
Throws
Section titled “Throws”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.
Throws
Section titled “Throws”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.
Throws
Section titled “Throws”TypeError if the id is missing or empty.
Throws
Section titled “Throws”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.
Throws
Section titled “Throws”The file system error that stopped the remove before it began deleting; nothing is deleted.
Example
Section titled “Example”await root.remove('arcp://name,corpus/item/1');unfinishedWrite()
Section titled “unfinishedWrite()”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.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<UnfinishedWrite | undefined>
The write, or undefined if the object isn’t locked
Throws
Section titled “Throws”OcflError ID_INCOMPATIBLE_WITH_LAYOUT if the layout can’t map the id to a directory the file system can hold.
Throws
Section titled “Throws”OcflError OBJECT_ROOT_CONFLICT if that directory is locked by a writer of another id.
Throws
Section titled “Throws”TypeError if the id is missing or empty.
Throws
Section titled “Throws”The file system error if the object’s lock exists but can’t be read.
Example
Section titled “Example”const write = await root.unfinishedWrite(id);if (write) console.log(`Locked since ${write.lockedAt.toISOString()}`);unfinishedWrites()
Section titled “unfinishedWrites()”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.
Returns
Section titled “Returns”AsyncIterable<UnfinishedWrite>
Throws
Section titled “Throws”The file system error that stopped the listing.
Example
Section titled “Example”// After this host crashed: it was the storage root's only writer, so none of the writes before the crash is alivefor await (const write of root.unfinishedWrites()) { if (write.lockedAt < crashedAt) await write.recover();}