Skip to content

Migrating from 0.4

Version 1.0 of @ocfl/ocfl-fs replaces the 0.4 API with a smaller one. You open a storage root, open or create an OCFL object in it by id, read its files from its versions, and change it by passing a callback that edits a draft. This page maps each 0.4 call to its 1.0 replacement.

The 0.4 snippets below are shown as you would have written them; they don’t run against 1.0. Every 1.0 example is type-checked against the package. New to 1.0 altogether? Start with Getting started.

Storage roots and objects that 0.4 wrote open and update in 1.0 as they are. There’s nothing to convert:

  • The layouts map ids to the same directories as before: 0002-flat-direct-storage-layout, 0004-hashed-n-tuple-storage-layout (the 0.4 default) and 000N-path-direct-storage-layout with string replace patterns.
  • An existing object keeps its digest algorithm and content directory. Only new objects are always sha512 with a content directory.
  • Every version stays readable, with the message, user and creation time it was committed with.
  • An existing fixity block is kept as it is in each new version.
  • OCFL 1.0 storage roots and objects stay OCFL 1.0.

A few storage roots and ids need attention. In each case 1.0 refuses the storage root or the id, or doesn’t find the object; it never changes anything on disk by itself:

What you have What 1.0 does What to do
A 0003-hash-and-id-n-tuple-storage-layout object whose id has upper-case letters, any of !'()*~, or more than 100 characters once percent-encoded Looks for it in a different directory, which the extension specifies; 0.4 named it wrongly Move it
A config.json whose replace pattern is {}, because 0.4 wrote a RegExp pattern that way INVALID_STORAGE_ROOT Write the pattern as a string
A config.json with a digestAlgorithm in another case, such as SHA256, or one that’s no longer supported: crc32, size, blake2b-160, blake2b-256 or blake2b-384 INVALID_STORAGE_ROOT Write a supported name in lower case; an algorithm that’s gone means the objects would need moving to new paths
A config.json with tupleSize or numberOfTuples above 32, or only one of them 0 INVALID_STORAGE_ROOT None in this library: the extension doesn’t allow these values
A path-direct suffix of '' or / INVALID_STORAGE_ROOT Let every update finish, move each object into a __object__ directory and drop suffix from config.json
A storage root using 0006-flat-omit-prefix-storage-layout or 0007-n-tuple-omit-prefix-storage-layout UNSUPPORTED_LAYOUT None: 0.4 could never map an id under these layouts
A path-direct id with a . or .. segment (such as a/../b), the suffix part-way through (such as a/__object__/b), or a segment longer than 255 bytes in UTF-8 ID_INCOMPATIBLE_WITH_LAYOUT Use another id. 0.4 resolved the dots, so such an object sits where the resolved id maps to
A flat-direct id longer than 255 bytes in UTF-8 ID_INCOMPATIBLE_WITH_LAYOUT Use another id

The digest directories haven’t changed, only the last directory, named by the encoded id. Listing still finds an object stored under its 0.4 name, because listing goes by the object declaration, but opening it by id doesn’t. To move such objects once no 0.4 writer is running, work out each name both ways and rename the directory where they differ:

import { createHash } from 'node:crypto';
import { existsSync } from 'node:fs';
import { rename } from 'node:fs/promises';
import path from 'node:path';
import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const layout = root.layout;
if (layout.extensionName !== '0003-hash-and-id-n-tuple-storage-layout') {
throw new Error('Not a 0003 storage root');
}
const { digestAlgorithm, tupleSize, numberOfTuples } = layout;
// Node's names for the OCFL algorithms it names differently
const nodeNames: Record<string, string> = { 'sha512/256': 'sha512-256', 'blake2b-512': 'blake2b512' };
const nodeAlgorithm = nodeNames[digestAlgorithm] ?? digestAlgorithm;
const digestOf = (id: string) => createHash(nodeAlgorithm).update(id).digest('hex');
const oldName = (id: string) => encodeURIComponent(id).toLowerCase().replace(/\./g, '%2e');
function newName(id: string) {
const encoded = encodeURIComponent(id)
.replace(/%[0-9A-F]{2}/g, (hexEscape) => hexEscape.toLowerCase())
.replace(/[.!'()*~]/g, (char) => `%${char.charCodeAt(0).toString(16)}`);
return encoded.length > 100 ? `${encoded.slice(0, 100)}-${digestOf(id)}` : encoded;
}
function tuples(id: string) {
const digest = digestOf(id);
return Array.from({ length: numberOfTuples }, (_, i) => digest.slice(i * tupleSize, (i + 1) * tupleSize));
}
for await (const entry of root.objects()) {
if ('error' in entry) {
continue;
}
const { id } = entry.object;
const parent = path.join(root.path, ...tuples(id));
const from = path.join(parent, oldName(id));
const to = path.join(parent, newName(id));
if (from !== to && existsSync(from) && !existsSync(to)) {
await rename(from, to);
}
}

Upgrade every writer of a storage root together. 1.0 takes a lock on an object before it changes it, and refuses a second writer while the lock is held. Writers on 0.4, or on a 1.0 beta from before the lock, don’t take it, so a 0.4 writer and a 1.0 writer can change the same object at once and damage it. Stop every 0.4 writer of a storage root before you start a 1.0 writer. The lock and Upgrade every writer together explain why.

Clear the old workspace. 0.4 assembled versions in extensions/workspace inside the storage root, or in the workspace you passed. 1.0 uses extensions/ocfl-js-workspace and ignores the old one. Once no 0.4 writer is running, delete the old workspace directory.

Check the objects 0.4 wrote. Some 0.4 updates could damage an object. See objects 0.4 may have damaged.

Install only @ocfl/ocfl-fs. It no longer depends on @ocfl/ocfl, so remove that package. Keeping it installs a second copy of the library, and instanceof OcflError fails for an error from the other copy.

Node.js 22.12 or later. The package is an ES module with its own types. CommonJS code can still require() it, because Node.js 22.12 can load ES modules that way. It has named exports only: createStorageRoot, openStorageRoot, OcflError and the types. Delete any hand-written type declarations for either package.

0.4 1.0
ocfl.storage({ root }), then create() or load() createStorageRoot(path, { layout }) or openStorageRoot(path)
ocfl.createStorage(config), ocfl.loadStorage(config) createStorageRoot(path, { layout }), openStorageRoot(path)
storage.exists() openStorageRoot(path), catching STORAGE_ROOT_NOT_FOUND
storage.object(id) for an existing object, then load() root.open(id)
storage.object(id) for a new object, then update() or import() root.create(id, details, build)
ocfl.object({ root }), storage.object({ root }) root.open(id): objects are opened only through their storage root
storage.has(id), object.exists() root.open(id), catching OBJECT_NOT_FOUND
for await (const o of storage), storage.objects() root.objects(), which yields { object }, or { error, objectRoot, id? } for an object it can’t open
storage.remove(id), delete(id), purge(id) (they only ever threw) root.remove(id)
storage.objectRoot(id), objectRootAbs(id), object.root None: the library doesn’t give out paths on disk. It names only what it found broken, by its path from the storage root: a damaged object root that root.objects() yields, and a stored file that object.checkFixity() reports
object.getInventory(), object.inventory object.head, object.versions
object.headVersion object.head.number
object.versions (version numbers) object.versions, a map from version number to version
object.files(version), object.count(version) object.versions.get(n)?.files, and its size
object.getFile(path), fileByLogicalPath(path) object.head.files.get(path)
object.getFile(path, 'v1') object.versions.get(1)?.files.get(path)
object.fileByDigest(digest), fileByContentPath(path) None: look a file up by its logical path
object.readFile(), stat(), createReadable() The methods of the file from files.get(path)
file.logicalPath file.path
file.text(encoding), asString() file.text(), which decodes UTF-8
file.buffer(), asBuffer() file.bytes()
await file.stream(), asStream() await file.stream(range?), which resolves to a Node Readable once the content is open
file.stat(), file.size file.size()
file.lastModified file.modifiedAt, when the version that gave the file its current content was committed. file.modifiedIn is that version
object.update(fn), update(fn, 'MERGE') object.update(details, fn), which returns the updated object
object.update(fn, 'REPLACE') object.update(details, fn), calling draft.clear() first
object.update() with no callback, then t.commit(options) or t.rollback() object.update(details, fn): it commits when fn returns and discards when it throws
object.import(source), object.add(source) object.update(details, (draft) => draft.import(source))
object.import([[source, target], …]) One draft.import(source, { target }) call for each, in one update
t.write(path, data, options) draft.write(path, content)
t.createWritable(path), createWriteStream(path) draft.write(path, stream)
t.import(source, target) draft.import(source, { target })
t.copy(source, target) draft.copy(source, target)
t.rename(source, target), t.move(source, target) draft.rename(source, target)
t.remove(path), t.delete(path) draft.remove(path)
t.reinstate(path, 'v1') draft.reinstate(path, 1)
t.purge(path), remove(path, { purge: true }) A new object without the file
object.export() (only ever threw) Write a version out yourself
object.validate(), verify() (only ever threw) None: use an OCFL validator. object.checkFixity() reads every stored file again
None root.unfinishedWrites(), root.unfinishedWrite(id) and write.recover(), after a writer dies

0.4:

import ocfl from '@ocfl/ocfl-fs';
let storage;
try {
storage = await ocfl.createStorage({ root: '/srv/ocfl', layout: { extensionName: '000N-path-direct-storage-layout' } });
} catch (error) {
storage = await ocfl.loadStorage({ root: '/srv/ocfl' });
}

1.0:

import { createStorageRoot, OcflError, openStorageRoot, type StorageRoot } from '@ocfl/ocfl-fs';
async function openOrCreate(path: string): Promise<StorageRoot> {
try {
return await openStorageRoot(path);
} catch (error) {
if (!(error instanceof OcflError && error.code === 'STORAGE_ROOT_NOT_FOUND')) {
throw error;
}
return createStorageRoot(path, { layout: { extensionName: '000N-path-direct-storage-layout' } });
}
}
const root = await openOrCreate('/srv/ocfl');
console.log(root.ocflVersion, root.layout.extensionName);
  • createStorageRoot() takes the path and a layout, which is now required. 0.4 used 0004-hashed-n-tuple-storage-layout when you gave none.
  • A layout is chosen only as { extensionName, ...parameters }. Class names such as 'HashedNTupleStorageLayout', layout objects such as new ocfl.StorageLayout.PathDirectStorageLayout(), and a bare name string are gone.
  • A parameter the layout doesn’t have, or a wrongly typed one, throws a TypeError from createStorageRoot(). 0.4 ignored it.
  • createStorageRoot() takes no other option. workspace, digestAlgorithm, contentDirectory, ocflVersion and fixityAlgorithms are gone, and so is the second { fs } argument. New storage roots are OCFL 1.1, and new objects are sha512 with a content directory.
  • openStorageRoot() reads the layout from the storage root’s own ocfl_layout.json and config.json. It throws STORAGE_ROOT_NOT_FOUND when the path doesn’t exist or is an empty directory, INVALID_STORAGE_ROOT when something else is there that isn’t a storage root, or its layout files are missing or wrong, and UNSUPPORTED_LAYOUT for a layout the library doesn’t have. 0.4 often carried on with no layout.
  • root.layout gives the layout’s parameters, defaults included. ocfl.storageLayout() and the layout classes are gone, so there’s no way to map an id to a path outside a storage root.

0.4:

const object = storage.object('arcp://name,corpus/item/1');
await object.load();
const file = object.getFile('ro-crate-metadata.json');
if (file) console.log(JSON.parse(await file.text()));
for (const f of await object.files()) console.log(f.logicalPath, f.digest);

1.0:

import { OcflError, openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
try {
const object = await root.open('arcp://name,corpus/item/1');
const metadata = object.head.files.get('ro-crate-metadata.json');
if (metadata) {
console.log(JSON.parse(await metadata.text()));
}
for (const [path, file] of object.head.files) {
console.log(path, file.digest, await file.size());
}
const first = object.versions.get(1);
console.log(first?.createdAt, first?.message, first?.user?.name, first?.files.size);
} catch (error) {
if (!(error instanceof OcflError && error.code === 'OBJECT_NOT_FOUND')) {
throw error;
}
console.log('No such object');
}
  • root.open(id) reads the inventory before it returns, so there’s no load(). It throws OBJECT_NOT_FOUND when there’s no object, instead of returning an object that later fails. Open the object and catch that error rather than checking first: a check can be overtaken by another writer. root.has(id) answers cheaply, without reading the inventory, when you only need to know whether an object exists.
  • An opened object is the object as it was read. It never changes, even after update(): that returns a new object. To see what another process has committed since, open it again.
  • Versions are numbers: object.versions.get(1), not 'v1'. object.head is the latest. Each version has its createdAt date, message, user and files, keyed by logical path. This replaces the inventory API (getInventory(), versionState(), diffState(), toJSON() and the rest): compare two versions’ files maps to see what changed.
  • A file’s digest is in lower-case hex. Files can’t be looked up by digest or content path, and content paths aren’t given out. The one place a stored file is named on disk is a fixity problem, which names a missing or changed stored file by its path from the storage root so you can restore it.
  • await file.stream() resolves to a Node Readable, and rejects first if the content can’t be read. It takes an optional byte range: await file.stream({ start: 0, end: 1023 }), with end included as in an HTTP Range header.
  • A stored file the inventory lists that is missing, or isn’t a regular file, is damage: size(), stream(), text() and bytes() reject with INVALID_OBJECT, with the file system error, if any, as its cause, not with ENOENT. Code that treats ENOENT as “not found” no longer answers 404 for a damaged object. A file that is there but can’t be read, such as EACCES, still rejects with the file system error.

0.4 created an object the first time it was updated. 1.0 creates it with root.create(), and update() works only on an object that exists. Every new version needs a message and a user: 0.4’s update(fn) couldn’t record them at all.

0.4:

const object = storage.object('arcp://name,corpus/item/1');
await object.import('/data/crates/item-1', 'REPLACE');

1.0:

import { OcflError, type OcflObject, openStorageRoot, type User } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
/** Makes the object's head hold exactly the files in `directory`. */
async function deposit(id: string, directory: string, user: User): Promise<OcflObject> {
for (let attempt = 1; ; attempt++) {
try {
return await depositOnce(id, directory, user);
} catch (error) {
const raced = error instanceof OcflError && (error.code === 'OBJECT_NOT_FOUND' || error.code === 'OBJECT_OUT_OF_DATE');
if (!raced || attempt === 3) {
throw error;
}
}
}
}
async function depositOnce(id: string, directory: string, user: User): Promise<OcflObject> {
try {
return await root.create(id, { message: 'First deposit', user }, async (draft) => {
await draft.import(directory);
});
} catch (error) {
if (!(error instanceof OcflError && error.code === 'OBJECT_EXISTS')) {
throw error;
}
}
const object = await root.open(id);
return object.update({ message: 'New deposit', user }, async (draft) => {
await draft.clear();
await draft.import(directory);
});
}
const object = await deposit('arcp://name,corpus/item/1', '/srv/uploads/item-1', { name: 'Alice' });
console.log(`${object.id} is at version ${object.head.number}`);

Try create() first and, when it throws OBJECT_EXISTS, open the object and update it. Checking whether it exists first can be beaten by another writer in between; the create can’t. Another writer can still remove the object or commit a version between the steps, so deposit starts again from create() on OBJECT_NOT_FOUND or OBJECT_OUT_OF_DATE. draft.clear() before draft.import() does what 'REPLACE' did. A deposit service explains this pattern in full.

0.4:

await object.update(async (t) => {
await t.write('notes.txt', 'Checked by Alice');
await t.import('/data/extra/scans');
await t.move('raw', 'audio');
await t.copy('audio/1.wav', 'preview/1.wav');
await t.delete('tmp');
await t.reinstate('README.md', 'v1');
});

1.0:

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('item-1');
const updated = await object.update({ message: 'Reorganise', user: { name: 'Alice' } }, async (draft) => {
await draft.write('notes.txt', 'Checked by Alice');
await draft.import('/data/extra/scans', { target: 'scans' });
await draft.rename('raw', 'audio');
await draft.copy('audio/1.wav', 'preview/1.wav');
await draft.remove('tmp');
await draft.reinstate('README.md', 1);
});
console.log(updated.head.number, updated === object);
  • update() takes the version’s details first and the callback second, and returns the updated object.
  • The draft starts with the head’s files, as 'MERGE' did. For 'REPLACE', call draft.clear() first.
  • If the callback throws, the update is discarded and the error is rethrown. If it ends with the files the same as the head, no version is written and update() returns the same object.
  • Await every operation. Operations take effect in the order they were called, even when you start them together with Promise.all. An operation still unfinished when the callback returns makes the update fail with an Error, and nothing is committed.
  • A draft can’t be used once its update has finished.

Moving content into OCFL from another system, give each version’s original date as createdAt in its details. Without it, every version is dated when it is committed. Dates must not go backwards: an update dated earlier than the head throws a TypeError, so add the versions oldest first.

import { type OcflObject, openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
// Versions exported from another system, oldest first
const history = [
{ directory: '/export/item-1/v1', message: 'Initial deposit', date: '2019-03-01T00:00:00Z' },
{ directory: '/export/item-1/v2', message: 'Corrected transcript', date: '2021-07-14T09:30:00Z' },
];
const user = { name: 'Migration', address: 'mailto:repository@example.org' };
let object: OcflObject | undefined;
for (const { directory, message, date } of history) {
const details = { message, user, createdAt: new Date(date) };
object = object
? await object.update(details, async (draft) => {
await draft.clear();
await draft.import(directory);
})
: await root.create('arcp://name,corpus/item/1', details, (draft) => draft.import(directory));
}

Updating objects describes each operation in full. What changed from 0.4:

  • import() without a target puts a directory’s contents at the top of the object, as object.import() did. 0.4’s t.import('/data/dir') put them under dir/, so pass the name, draft.import('/data/dir', { target: 'dir' }), to keep that. A file keeps its own name. A target of '' throws INVALID_LOGICAL_PATH: leave the target out instead.
  • import() copies hidden files too, and fails with UNSUPPORTED_FILE_TYPE on a symbolic link or anything else that isn’t a regular file or directory. Its filter option leaves entries out, such as .git directories, .DS_Store files and symbolic links. It fails with SOURCE_CHANGED when a file changes while it’s being read. An import that fails adds none of its files.
  • write() takes a string (written as UTF-8), a Uint8Array, or any async iterable of them, such as a ReadableStream or a Node.js stream. Its third options argument is gone: decode first, for example with Buffer.from(text, 'base64').
  • reinstate() takes a version number, returns nothing, and throws FILE_NOT_FOUND when that version had nothing at the path. A directory puts back every file that was below it.
  • remove() and rename() throw FILE_NOT_FOUND when nothing is at the path, instead of doing nothing.
  • copy(), rename(), write(), import() and reinstate() replace a file at the target. They throw FILE_EXISTS when a file would sit inside another file, or where a directory with files is. A directory copied or renamed onto one that has files needs { merge: true }: files at the same paths are replaced and the rest stay.
  • Paths are normalised, so ./raw//1.wav is raw/1.wav. An empty or absolute path, or one with a .. segment (\ counts as a separator), throws INVALID_LOGICAL_PATH, as does a target inside its source, such as rename('raw', 'raw/old').
  • move(), delete(), purge(), createWritable() and createWriteStream() are gone.

OCFL versions don’t change once committed, and the OCFL implementation notes say purging isn’t supported directly. 0.4’s purge() never removed the bytes anyway. To take a file out of an object’s history, create a new object without it, then remove the original:

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const original = await root.open('original-id');
await root.create('new-id', { message: 'Copy of original-id without secret.txt', user: { name: 'Alice' } }, async (draft) => {
for (const [path, file] of original.head.files) {
if (path !== 'secret.txt') {
await draft.write(path, await file.stream());
}
}
});
await root.remove('original-id');

The new object needs its own id. This copies only the head, so the new object starts with one version. To keep the history, create one version in the new object for each version of the original.

0.4’s object.export() only ever threw. To put a version’s files in a directory, write each one out under its logical path:

import { mkdir, writeFile } from 'node:fs/promises';
import path from 'node:path';
import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('item-1');
const targetDir = path.resolve('/tmp/item-1-v1');
for (const [logicalPath, file] of object.versions.get(1)?.files ?? []) {
const target = path.resolve(targetDir, logicalPath);
if (!target.startsWith(targetDir + path.sep)) {
throw new Error(`Logical path "${logicalPath}" is outside ${targetDir}`);
}
await mkdir(path.dirname(target), { recursive: true });
await writeFile(target, await file.stream());
}

The library doesn’t check the logical paths in an inventory it reads, so an object written by another tool, or a damaged one, can hold a path such as ../../etc/passwd. Check that each target stays inside the directory, as the example does, before you write it.

0.4:

for await (const object of storage) {
await object.load();
console.log(object.id, await object.count());
}

1.0:

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
for await (const entry of root.objects()) {
if ('error' in entry) {
const { objectRoot, id, error } = entry;
console.warn(`${objectRoot}${id ? ` (${id})` : ''}: ${error.ocflCode ?? error.code}`);
continue;
}
console.log(entry.object.id, entry.object.head.number);
}
  • Each object is yielded already opened. Listing goes in no particular order.
  • An object that can’t be opened is yielded as { error, objectRoot, id? }, where error has the code INVALID_OBJECT, and the listing carries on. A file system error, such as EACCES, is thrown and ends it.
  • Listing treats a directory as an object only if it has an object declaration, so it leaves out an object that has lost its declaration. It also leaves out an object whose creation hasn’t been committed, including one whose writer died; it is among root.unfinishedWrites(), and recovering it clears it.

root.remove(id) deletes an object with all its versions, and any parent directories that are left empty. It takes the object’s lock, so it never deletes an object while it’s being updated. It throws OBJECT_ROOT_CONFLICT for a directory that isn’t an object, and INVALID_OBJECT for an object it can’t read; delete that one by hand.

root.unfinishedWrites() lists every create, update or remove whose lock is still held, and root.unfinishedWrite(id) finds one. write.recover() clears what a writer that died left of the object, and releases its lock. Only call it when you know that writer is no longer alive: it destroys a live writer’s update. See Recovering and a create whose writer died.

0.4 threw plain Errors, so callers matched on messages. 1.0 throws an OcflError for anything a caller might handle. Test its code: the message isn’t part of the API and may change. Errors says what to do about each code, and Concurrent writers and recovery covers the lock, retrying and RECOVERY_NEEDED.

import { OcflError, openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const id = 'item-1';
try {
const object = await root.open(id);
await object.update({ message: 'Add notes', user: { name: 'Alice' } }, async (draft) => {
await draft.write('notes.txt', 'Field notes');
});
} catch (error) {
if (!(error instanceof OcflError)) {
throw error;
}
switch (error.code) {
case 'OBJECT_NOT_FOUND':
console.log(`There is no object ${id}`);
break;
case 'UPDATE_IN_PROGRESS':
console.log(`Another writer has held the lock since ${error.lockedAt?.toISOString() ?? 'an unknown time'}`);
break;
case 'INVALID_OBJECT':
console.log(`The object is damaged (${error.ocflCode ?? 'no OCFL code'}): ${error.message}`);
break;
default:
throw error;
}
}
code Thrown when
OBJECT_NOT_FOUND open() or remove() finds nothing where the id maps, or open() finds an object whose creation isn’t committed
OBJECT_EXISTS create() finds an object already there, or another writer created it first
OBJECT_OUT_OF_DATE update() finds that a later version was committed, or the object was removed, since it was opened
INVALID_OBJECT An object can’t be used safely: its inventory or sidecar is missing, damaged or inconsistent, its declaration is missing or wrong, or it is inside another object. ocflCode names the OCFL rule. objects() yields it as entry.error, with entry.objectRoot, instead of throwing
STORAGE_ROOT_NOT_FOUND openStorageRoot() is given a path that doesn’t exist, or an empty directory
INVALID_STORAGE_ROOT openStorageRoot() finds something with a missing or wrong declaration (E069, E080), a missing ocfl_layout.json or one naming no storage layout (E070), or a config.json that isn’t a JSON object, is for another storage layout or has parameters it refuses
UNSUPPORTED_LAYOUT openStorageRoot() finds a storage layout the library doesn’t have
ID_INCOMPATIBLE_WITH_LAYOUT The storage layout can’t map the id, or maps it to the storage root, outside it, into extensions or to a path too long for the file system; or create() and remove() find the object’s lock path too long
OBJECT_ROOT_CONFLICT The id’s directory holds an object with another id, or holds other files, is a file or is below one; create() would put the object inside another object; or unfinishedWrite() finds the lock of a writer of another id
DIRECTORY_NOT_EMPTY createStorageRoot() is given a directory that isn’t empty; rarely, create() when something appears in the new object’s directory
UPDATE_IN_PROGRESS create(), update() or remove() finds the object locked by another writer. lockedAt is when the lock was taken
RECOVERY_NEEDED A write failed after the commit point or in a way that may have committed, couldn’t remove what it made, or remove() stopped part-way; a write couldn’t release its lock; or an earlier writer left an unfinished version. cause is the underlying failure. Don’t simply retry
MUTABLE_HEAD_ACTIVE update() finds an active 0005-mutable-head extension
CROSS_FILESYSTEM_MOVE A new version can’t be moved from the workspace into the object, because they are on different file systems
UNSUPPORTED_FILESYSTEM create(), update() or remove() can’t take the object’s lock, because the storage root’s file system doesn’t support hard links
VERSION_LIMIT_REACHED An object with zero-padded version names, such as v01, has used them all up
FILE_NOT_FOUND copy(), rename() or remove() names a path with nothing in the draft, or reinstate() a path or version that doesn’t exist
FILE_EXISTS A file would go where a directory is or below another file, or copy() or rename() would put a directory onto one with files without { merge: true }
INVALID_LOGICAL_PATH A logical path is empty, absolute or has a .. segment; a copy() or rename() target is inside its source; or an import() target is empty or the top of the object
SOURCE_CHANGED import() finds a file changed while it was copied in
UNSUPPORTED_FILE_TYPE import() meets a symbolic link or anything else that isn’t a regular file or directory, and its filter doesn’t leave it out

Misuse, such as an argument of the wrong type, throws a plain TypeError, and file system errors such as ENOSPC pass through as they are. OcflError has no subclasses: 0.4’s ValidationError and NotImplementedError are gone.

  • Object content uses sha256 or sha512. The hashed layouts take md5, sha1, sha256, sha512, sha512/256 or blake2b-512, written exactly so; the FixityAlgorithm type names them, so TypeScript catches a typo. crc32 and size can no longer be a layout’s digestAlgorithm, and blake2b-160, blake2b-256 and blake2b-384 have gone.
  • OcflDigest is gone. Use createHash() from node:crypto to compute a digest yourself.
  • The layouts are a fixed set: 0002-flat-direct-storage-layout, 0003-hash-and-id-n-tuple-storage-layout, 0004-hashed-n-tuple-storage-layout and 000N-path-direct-storage-layout. They can’t be subclassed or registered.
  • The path-direct replace option takes [find, replacement] pairs of strings. Each replaces only the first occurrence of find.

Some 0.4 updates could leave an object damaged. object.checkFixity() reads every stored file the object’s manifest lists and reports each one that is missing (a manifest entry with no file) or changed (content that doesn’t match its digest). It doesn’t look for files the manifest doesn’t list, and it can’t tell when a logical path points at the wrong content, because the object doesn’t record what you meant to store. Check objects written by other tools, or for problems these checks don’t cover, with an OCFL validator. Checking fixity across a storage root shows the check run over every object.

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
for await (const entry of root.objects()) {
if ('error' in entry) {
console.warn(entry.objectRoot, entry.error.code);
continue;
}
for (const problem of await entry.object.checkFixity()) {
console.warn(entry.object.id, problem.problem, problem.storedFile, problem.affects);
}
}

Concurrent operations in one update. Operations started together in one 0.4 update could write content files that the manifest doesn’t list, which breaks the OCFL rule E023. The usual cause is importing a directory that holds two files with the same content, because 0.4 read a directory’s files concurrently. Concurrent writes to one logical path could also record the wrong content for it, or delete the only stored copy. A fixity check reports the deleted copies as missing; it doesn’t find the extra files or a path recording the wrong content.

Replacing a file within one update. Replacing a file more than once in one 0.4 update, or writing identical content to it again as a stream, could make a logical path read another file’s content or fail to read at all, and could lose content shared with another logical path. A fixity check reports the lost content as missing; it doesn’t find a logical path that reads another file’s content.

Renaming or removing a file within one update. Renaming a file added earlier in the same 0.4 update could leave a manifest entry for a file that isn’t on disk. Removing one could delete content another logical path still used, or leave a manifest entry for a file that’s gone. A fixity check reports both as missing.

Objects with no workspace. An object opened with ocfl.object({ root }) and no workspace could lose every version when an update failed, was rolled back or had no changes. With a shared workspace, an update could delete everything else in it. Objects from storage.object() had their own workspace and kept their versions. Versions already lost can’t be got back.

The library doesn’t repair damaged objects. To repair one, create a new object from the files you know are right, then remove the damaged one.

See the API reference for every function and type.