Skip to content

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.

clear(): Promise<void>

Defined in: src/draft.ts:214

Removes every file from the draft. Earlier versions keep them.

Promise<void>

Error if the update this draft belongs to has finished.

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(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.

string

string

MergeOptions

Promise<void>

OcflError FILE_NOT_FOUND if source is not in the draft.

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.

OcflError INVALID_LOGICAL_PATH if a path is empty or leaves the object, or target is inside source.

TypeError if options is given and is not an object, or its merge is given and is not a boolean.

Error if the update this draft belongs to has finished.

await object.update(details, async (draft) => {
await draft.copy('audio/1.wav', 'archive/1.wav');
});

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.

Promise<ReadonlyMap<string, string>>

Error if the update this draft belongs to has finished.

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(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.

string

ImportOptions

Promise<void>

OcflError UNSUPPORTED_FILE_TYPE if source is anything but a regular file or directory, such as a symlink, or contains one the filter keeps.

OcflError SOURCE_CHANGED if a file changed while it was being read.

OcflError INVALID_LOGICAL_PATH if target is empty or leaves the object.

OcflError FILE_EXISTS if a path would become both a file and a directory.

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.

Error if the update this draft belongs to has finished.

The error filter throws.

The file system error if source, or something below it, is missing or can’t be read.

await object.update(details, async (draft) => {
await draft.import('/data/incoming/item-1', { target: 'raw' });
});

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.

string

number

Promise<void>

OcflError FILE_NOT_FOUND if the version doesn’t exist or has nothing at path.

OcflError FILE_EXISTS if a path would become both a file and a directory.

OcflError INVALID_LOGICAL_PATH if path is empty or leaves the object.

TypeError if version is not a number.

Error if the update this draft belongs to has finished.

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(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.

string

Promise<void>

OcflError FILE_NOT_FOUND if path is not in the draft.

OcflError INVALID_LOGICAL_PATH if path is empty or leaves the object.

Error if the update this draft belongs to has finished.

await object.update(details, async (draft) => {
await draft.remove('tmp');
});

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.

string

string

MergeOptions

Promise<void>

OcflError FILE_NOT_FOUND if source is not in the draft.

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.

OcflError INVALID_LOGICAL_PATH if a path is empty or leaves the object, or target is inside source.

TypeError if options is given and is not an object, or its merge is given and is not a boolean.

Error if the update this draft belongs to has finished.

await object.update(details, async (draft) => {
await draft.rename('scans', 'images', { merge: true });
});

write(path, content): Promise<void>

Defined in: src/draft.ts:106

Puts one file at path, replacing a file already there.

string

WriteContent

Promise<void>

OcflError INVALID_LOGICAL_PATH if path is empty or leaves the object.

OcflError FILE_EXISTS if path is a directory, or lies below a file.

TypeError if content is not a WriteContent.

Error if the update this draft belongs to has finished.

await object.update(details, async (draft) => {
await draft.write('ro-crate-metadata.json', JSON.stringify(metadata));
});