Draft
Defined in: src/draft.ts:91
The changes being assembled during an update, which become one new version or are discarded.
It starts with the files of the head version (none, for a new object). Operations take effect in call order,
even when started together. Every logical path is normalised first (./raw//1.wav is raw/1.wav).
Once the update’s signal is aborted, every operation started after that rejects with its reason, and an import stops between files.
Methods
Section titled “Methods”clear()
Section titled “clear()”clear():
Promise<void>
Defined in: src/draft.ts:214
Removes every file from the draft. Earlier versions keep them.
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”Error if the update this draft belongs to has finished.
Example
Section titled “Example”await object.update(details, async (draft) => { // Replace every file: start empty, then import the new set await draft.clear(); await draft.import('/data/rebuilt/item-1');});copy()
Section titled “copy()”copy(
source,target,options?):Promise<void>
Defined in: src/draft.ts:148
Copies a file, or every file below a directory, to target within the draft.
With merge, a directory goes file by file into a target that has files: files at the same path are replaced and the rest stay.
Parameters
Section titled “Parameters”source
Section titled “source”string
target
Section titled “target”string
options?
Section titled “options?”Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”OcflError FILE_NOT_FOUND if source is not in the draft.
Throws
Section titled “Throws”OcflError FILE_EXISTS if source is a directory and target already has files, unless merge is set; or if a file would go where a directory is, or below a file, as the draft stands before the operation.
Throws
Section titled “Throws”OcflError INVALID_LOGICAL_PATH if a path is empty or leaves the object, or target is inside source.
Throws
Section titled “Throws”TypeError if options is given and is not an object, or its merge is given and is not a boolean.
Throws
Section titled “Throws”Error if the update this draft belongs to has finished.
Example
Section titled “Example”await object.update(details, async (draft) => { await draft.copy('audio/1.wav', 'archive/1.wav');});files()
Section titled “files()”files():
Promise<ReadonlyMap<string,string>>
Defined in: src/draft.ts:231
The draft’s files: each logical path, with its digest in lowercase in the object’s digest algorithm, as OcflFile.digest gives it.
Directories aren’t listed. It takes its turn like any other operation, so it shows every operation started before it, and none started after.
The map is a snapshot that later operations don’t change. It gives no content.
Returns
Section titled “Returns”Promise<ReadonlyMap<string, string>>
Throws
Section titled “Throws”Error if the update this draft belongs to has finished.
Example
Section titled “Example”await object.update(details, async (draft) => { await draft.import(dir); const files = await draft.files(); if (!files.has('ro-crate-metadata.json')) await draft.write('ro-crate-metadata.json', stub);});import()
Section titled “import()”import(
source,options?):Promise<void>
Defined in: src/draft.ts:130
Copies a file or directory from disk into the draft, at the target option or at the top. Files already there are replaced; the rest stay.
Without a target, a directory’s contents go at the top and a file keeps its own name there.
Everything below a directory is copied, including hidden files, except entries the filter option leaves out.
If a file fails, the first failure is thrown and the draft is left as it was.
Parameters
Section titled “Parameters”source
Section titled “source”string
options?
Section titled “options?”Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”OcflError UNSUPPORTED_FILE_TYPE if source is anything but a regular file or directory, such as a symlink, or contains one the filter keeps.
Throws
Section titled “Throws”OcflError SOURCE_CHANGED if a file changed while it was being read.
Throws
Section titled “Throws”OcflError INVALID_LOGICAL_PATH if target is empty or leaves the object.
Throws
Section titled “Throws”OcflError FILE_EXISTS if a path would become both a file and a directory.
Throws
Section titled “Throws”TypeError if options is not an object, target is not a string, filter is not a function or it returns anything but true or false.
Throws
Section titled “Throws”Error if the update this draft belongs to has finished.
Throws
Section titled “Throws”The error filter throws.
Throws
Section titled “Throws”The file system error if source, or something below it, is missing or can’t be read.
Example
Section titled “Example”await object.update(details, async (draft) => { await draft.import('/data/incoming/item-1', { target: 'raw' });});reinstate()
Section titled “reinstate()”reinstate(
path,version):Promise<void>
Defined in: src/draft.ts:184
Puts a file, or every file below a directory, back as it was in an earlier version, at the same path.
Parameters
Section titled “Parameters”string
version
Section titled “version”number
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”OcflError FILE_NOT_FOUND if the version doesn’t exist or has nothing at path.
Throws
Section titled “Throws”OcflError FILE_EXISTS if a path would become both a file and a directory.
Throws
Section titled “Throws”OcflError INVALID_LOGICAL_PATH if path is empty or leaves the object.
Throws
Section titled “Throws”TypeError if version is not a number.
Throws
Section titled “Throws”Error if the update this draft belongs to has finished.
Example
Section titled “Example”await object.update(details, async (draft) => { // Undo a bad edit: the transcript as it was in version 2 await draft.reinstate('transcript.txt', 2);});remove()
Section titled “remove()”remove(
path):Promise<void>
Defined in: src/draft.ts:199
Removes a file, or every file below a directory, from the draft. Earlier versions keep it.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”OcflError FILE_NOT_FOUND if path is not in the draft.
Throws
Section titled “Throws”OcflError INVALID_LOGICAL_PATH if path is empty or leaves the object.
Throws
Section titled “Throws”Error if the update this draft belongs to has finished.
Example
Section titled “Example”await object.update(details, async (draft) => { await draft.remove('tmp');});rename()
Section titled “rename()”rename(
source,target,options?):Promise<void>
Defined in: src/draft.ts:166
Moves a file, or every file below a directory, to target within the draft.
With merge, a directory goes file by file into a target that has files: files at the same path are replaced and the rest stay.
Parameters
Section titled “Parameters”source
Section titled “source”string
target
Section titled “target”string
options?
Section titled “options?”Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”OcflError FILE_NOT_FOUND if source is not in the draft.
Throws
Section titled “Throws”OcflError FILE_EXISTS if source is a directory and target already has files, unless merge is set; or if a file would go where a directory is, or below a file, as the draft stands before the operation.
Throws
Section titled “Throws”OcflError INVALID_LOGICAL_PATH if a path is empty or leaves the object, or target is inside source.
Throws
Section titled “Throws”TypeError if options is given and is not an object, or its merge is given and is not a boolean.
Throws
Section titled “Throws”Error if the update this draft belongs to has finished.
Example
Section titled “Example”await object.update(details, async (draft) => { await draft.rename('scans', 'images', { merge: true });});write()
Section titled “write()”write(
path,content):Promise<void>
Defined in: src/draft.ts:106
Puts one file at path, replacing a file already there.
Parameters
Section titled “Parameters”string
content
Section titled “content”Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”OcflError INVALID_LOGICAL_PATH if path is empty or leaves the object.
Throws
Section titled “Throws”OcflError FILE_EXISTS if path is a directory, or lies below a file.
Throws
Section titled “Throws”TypeError if content is not a WriteContent.
Throws
Section titled “Throws”Error if the update this draft belongs to has finished.
Example
Section titled “Example”await object.update(details, async (draft) => { await draft.write('ro-crate-metadata.json', JSON.stringify(metadata));});