@ocfl/ocfl-fs, from the ocfl-js repository, is a TypeScript library for keeping versioned digital objects under the Oxford Common File Layout (OCFL) on a local file system. It reads and writes storage roots and the OCFL objects in them.
Documentation: https://language-research-technology.github.io/ocfl-js/
pnpm add @ocfl/ocfl-fs@betaUntil 1.0 is released, @beta is needed: without it you get 0.4, which has a different API.
It needs Node.js 22.12 or later, and is an ES module with its own types; with TypeScript, it needs TypeScript 5.7 or later and @types/node. It supports the Node.js versions that still get updates; when a Node.js version stops getting updates, a minor release can drop it.
It's supported on Linux only, on a case-sensitive file system with hard links; WSL works, macOS and Windows aren't supported. It's designed for local file systems and NFS, but CI tests only on a local file system and simulates NFS's lost replies; see Sharing a storage root over NFS.
Upgrading from 0.x? See Upgrading from 0.x.
Create a storage root, deposit an object, add a version and read it back:
import { createStorageRoot } from '@ocfl/ocfl-fs';
const root = await createStorageRoot('/srv/ocfl', {
layout: { extensionName: '0004-hashed-n-tuple-storage-layout' },
});
const object = await root.create('greeting', { message: 'First version', user: { name: 'Alice' } }, async (draft) => {
await draft.write('hello.txt', 'Hello, world');
});
const updated = await object.update({ message: 'Add a note', user: { name: 'Alice' } }, async (draft) => {
await draft.write('notes/today.txt', 'Recorded in the field');
});
for (const [path, file] of updated.head.files) {
console.log(path, await file.text());
}The documentation site has guides to getting started, updating objects, concurrent writers and errors, and the full API reference. To see whether the library fits what you're building, read Use cases and best practices.
The library doesn't validate OCFL objects or storage roots against the OCFL specification. It reads and writes them; it doesn't tell you whether they conform. To check objects that another tool wrote, use an OCFL validator. See It doesn't validate on the overview for what the library does check, and why.
See CONTRIBUTING.md for how to set up, run the checks and send a pull request. To report a security vulnerability, see SECURITY.md. For releases, see RELEASING.md.