Skip to content

Updating objects

Every change to an OCFL object is one update, and every update adds at most one version. This guide covers what you can do in an update, the order things happen in, and what an update records.

object.update(details, change) gives your change function a draft: the changes being assembled for the next version. The draft starts with the files of the head version. Your function changes it, and when the function returns, the draft is committed as one new version.

import { createReadStream } from 'node:fs';
import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
const updated = await object.update({ message: 'Add the second session', user: { name: 'Alice', address: 'mailto:alice@example.org' } }, async (draft) => {
await draft.write('notes.txt', 'Recorded in the field');
await draft.write('raw/2.wav', createReadStream('/data/session-2/2.wav'));
await draft.import('/data/session-2/photos', { target: 'photos' });
await draft.copy('metadata.json', 'metadata.original.json');
await draft.rename('transcript.txt', 'transcripts/1.txt');
await draft.reinstate('consent.pdf', 1);
await draft.remove('scratch');
});
console.log(updated.head.number, [...updated.head.files.keys()]);
  • All or nothing. If change throws, or a draft operation throws and you let the error leave change, the whole update is discarded. The object is as it was and isn’t locked.
  • A new object comes back. update returns the object with its new version. The object you called it on never changes. Use the returned object for the next update: the old one is no longer the head, so updating it throws OBJECT_OUT_OF_DATE.
  • Only one writer at a time. An update takes the object’s lock before change runs. If another writer holds it, the update throws UPDATE_IN_PROGRESS straight away. See Concurrent writers and recovery for what to do then, and for what happens when two updates race.
  • Content is shared. Content the object already holds, in any version, isn’t stored again. Copying, renaming and reinstating store nothing new.

root.create(id, details, build) works the same way, except that the draft starts empty and becomes version 1.

Each operation takes logical paths: the paths of files as the object presents them, such as raw/1.wav. Paths are normalised first, so ./raw//1.wav is raw/1.wav. A path that is empty, absolute or has a .. segment throws INVALID_LOGICAL_PATH.

Operation What it does
write(path, content) Puts one file at path. content is text (stored as UTF-8), bytes, or a stream of either, such as a Node or web stream.
import(source, options?) Copies a file or directory from disk into the draft.
copy(source, target, options?) Copies a file, or every file below a directory, to another path in the draft.
rename(source, target, options?) Moves a file, or every file below a directory, to another path in the draft.
reinstate(path, version) Puts a file, or every file below a directory, back as it was in an earlier version, at the same path.
remove(path) Removes a file, or every file below a directory, from the draft. Earlier versions keep it.
clear() Removes every file from the draft.

There’s no separate replace operation. Writing, importing, copying, renaming or reinstating onto a path that already has a file replaces that file. See Replacing.

write stores the bytes as they were when you called it. A path that is a directory in the draft, or lies below a file, throws FILE_EXISTS.

import reads from your file system, not from the object.

  • With the target option, { target: 'raw' }, a file goes to that path and a directory’s contents go below it.
  • Without one, a file keeps its own name at the top of the object, and a directory’s contents go at the top. The directory itself isn’t included: importing /data/item-1 gives a.txt, not item-1/a.txt.
  • Everything below a directory is imported, including hidden files, unless the filter option leaves it out. See Leaving files out.
  • Files already at the same paths are replaced. Other files in the draft stay.
  • A symbolic link, or anything else that isn’t a regular file or directory, that the filter doesn’t leave out throws UNSUPPORTED_FILE_TYPE. A file that changes while it is being read throws SOURCE_CHANGED.
  • If any file fails, the first failure is thrown and the draft is left as it was before the import.

filter is called for each file, directory and symbolic link below the source, with its path relative to the source (using /, such as sub/.DS_Store) and its fs.Dirent. Return true to import the entry, or false to leave it out; anything else, such as a promise, throws a TypeError. A directory left out isn’t read, so everything below it is left out too, as with the filter option of Node’s fs.cp(). An entry left out never fails the import, so leaving out symbolic links below the source stops them throwing UNSUPPORTED_FILE_TYPE.

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
await object.update({ message: 'Deposit session 6', user: { name: 'Alice' } }, async (draft) => {
await draft.import('/data/session-6', {
filter: (_, entry) => entry.name !== '.git' && entry.name !== '.DS_Store' && !entry.name.startsWith('._') && !entry.isSymbolicLink(),
});
});

The filter isn’t called for the source itself: a source that is a file is imported, and one that is a symbolic link still throws UNSUPPORTED_FILE_TYPE.

copy and rename work within the draft, so their source is a logical path, not a path on disk. A source that isn’t in the draft throws FILE_NOT_FOUND. A target inside the source throws INVALID_LOGICAL_PATH. A source and target that are the same path do nothing.

A file copied or renamed onto an existing file replaces it. A directory copied or renamed onto a target that already has files throws FILE_EXISTS, unless you merge.

reinstate(path, version) takes a version number, as in object.versions. It puts back what was at path in that version and replaces whatever is there now. Other files stay. A version that doesn’t exist, or has nothing at path, throws FILE_NOT_FOUND.

Reinstating from the head version undoes what the draft has done to that path so far.

remove takes a file or a directory. A path that isn’t in the draft throws FILE_NOT_FOUND. clear removes everything and never throws for an empty draft. Both change only the new version: every earlier version keeps its files.

files lists what the draft holds: a map from each logical path to its digest, in lowercase and in the object’s digest algorithm, as OcflFile.digest gives it. Directories aren’t listed, and a new object’s draft starts empty. It takes its turn like any other operation, so it shows every operation called before it, awaited or not, and none called after. The map is a snapshot: later operations don’t change it. It gives no content.

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
const stub = JSON.stringify({ '@context': 'https://w3id.org/ro/crate/1.1/context', '@graph': [] });
await object.update({ message: 'Deposit session 4', user: { name: 'Alice' } }, async (draft) => {
await draft.import('/data/session-4');
// The draft as the import left it: each logical path with its digest
const files = await draft.files();
if (!files.has('ro-crate-metadata.json')) {
await draft.write('ro-crate-metadata.json', stub);
}
});

An operation that is refused with an OcflError, such as FILE_NOT_FOUND, changes nothing in the draft. If you catch the error inside change, the update carries on without that operation. If you don’t, the update is discarded. Errors covers each code a draft operation can throw.

Operations take effect in the order you call them, even when you start them together with Promise.all. Starting several imports together lets them read from disk at the same time, but the draft still changes in call order, whichever finishes first.

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
const updated = await object.update({ message: 'Add the third session', user: { name: 'Alice' } }, async (draft) => {
await Promise.all([
draft.import('/data/session-3/audio', { target: 'raw' }),
draft.import('/data/session-3/photos', { target: 'photos' }),
draft.write('raw/README.txt', 'Recorded on a handheld recorder'),
]);
});
console.log(await updated.head.files.get('raw/README.txt')?.text());

Here raw/README.txt is the text written, even if /data/session-3/audio holds a README.txt too, because the write was called after the import.

When operations touch the same path, call order decides:

  • The last one wins. Two writes to one path leave the content of the one called second. A write after an import replaces the imported file, and an import after a write replaces the written one.
  • Each operation sees the draft as the earlier calls left it. A copy or rename takes its source as it stands after every earlier call, and a remove followed by a write to the same path leaves the new file.
  • A copy is independent of its source. Writing the source again after a copy leaves the copy as it was.

Await every operation you start before change returns. If any is still running when it returns, the update throws an Error and is discarded. A draft can’t be used once its update has finished: every operation then throws an Error.

To replace one file, write or import onto its path. To replace a directory with what is on disk, remove it first, then import, so files that are no longer on disk don’t stay behind:

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
await object.update({ message: 'Replace the photos', user: { name: 'Alice' } }, async (draft) => {
await draft.remove('photos');
await draft.import('/data/session-2/photos', { target: 'photos' });
});

To replace the whole content of an object, clear the draft and import or write the new content. Files that are the same in the old and new content are stored once, and earlier versions keep everything they had.

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
await object.update({ message: 'Replace with the corrected deposit', user: { name: 'Alice' } }, async (draft) => {
await draft.clear();
await draft.import('/data/item-1-corrected');
});

Copying or renaming a directory onto a target that already has files throws FILE_EXISTS. Pass { merge: true } to put the directory there file by file instead: files at the same paths are replaced, and the target’s other files stay.

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
await object.update({ message: 'Fold the drafts into the transcripts', user: { name: 'Alice' } }, async (draft) => {
await draft.rename('drafts', 'transcripts', { merge: true });
});

On a single file, or onto a target with no files, { merge: true } makes no difference. A file that would go where the target has a directory, or below a file, still throws FILE_EXISTS.

If the draft ends with exactly the files of the head version, no version is written and update returns the same object you called it on. You can test for that with ===.

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
const updated = await object.update({ message: 'Sync from the field laptop', user: { name: 'Alice' } }, async (draft) => {
await draft.import('/data/item-1');
});
if (updated === object) {
console.log(`Nothing changed: ${object.id} is still at version ${object.head.number}`);
}

The draft is compared as it ends, not by what you did to it. Writing a file and removing it again, or renaming a file and back, changes nothing. Importing files that are already in the object, at the same paths with the same content, changes nothing either, which makes repeating a sync safe.

The lock and the out-of-date check still happen before change runs, so an update that changes nothing can still throw UPDATE_IN_PROGRESS or OBJECT_OUT_OF_DATE.

A create always writes version 1, even with no files.

update and create take an optional third argument, { signal }, an AbortSignal such as a request’s or AbortSignal.timeout()’s.

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
// Give up on a slow deposit after ten minutes: nothing is committed, and the object isn't left locked
const signal = AbortSignal.timeout(10 * 60_000);
try {
await object.update({ message: 'Deposit session 5', user: { name: 'Alice' } }, (draft) => draft.import('/data/session-5'), { signal });
} catch (error) {
if (error !== signal.reason) {
throw error;
}
console.error('The deposit took too long and was discarded');
}
  • A signal that is already aborted rejects with its reason before the lock is taken, and nothing changes.
  • Once it is aborted, every draft operation called after that rejects with its reason, and an import stops between files rather than reading the rest.
  • When the callback returns or throws, if the signal is aborted, the draft is discarded as for any error: nothing is committed and the lock is released. The update rejects with the signal’s reason, even if the callback caught the error an operation rejected with.
  • The signal is checked one last time just before the commit begins. After that it is ignored, and the update finishes as usual.

The first argument of update and create is the version details the new version records:

  • message: why the version was made. Required, and can’t be empty.
  • user: who made it. user.name is required and can’t be empty. user.address is optional: a URI for the user, such as a mailto: address or an ORCID.
  • createdAt: when the version is dated. Optional: without it, the library dates the version when it commits it, by the clock of the host doing the update. Give it to keep a version’s original date, as in a migration. It can’t be earlier than the head version’s date; the same date, or one in the future, is allowed.

Details that break these rules throw a TypeError before anything else happens.

The inventory records the date as an ISO 8601 UTC timestamp. Each version gives back its number, createdAt, message and user. An object written by another tool may have versions with no message or user.

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
for (const version of object.versions.values()) {
const who = version.user?.name ?? 'unknown';
console.log(version.number, version.createdAt.toISOString(), who, version.message ?? '');
}

See Draft and OcflObject in the API reference for every error each operation throws.