Getting started
This guide takes you from an empty directory to an OCFL object you can read back. It has three steps: create a storage root, create an OCFL object in it, then open the object and read a file.
Install
Section titled “Install”You need Node.js 22.12 or later, on Linux. The package is an ES module and ships its own types. It supports the Node.js versions that still get updates; when a Node.js version stops getting updates, a minor release can drop it.
pnpm add @ocfl/ocfl-fs@betaWith npm or Yarn, use npm install @ocfl/ocfl-fs@beta or yarn add @ocfl/ocfl-fs@beta. Until 1.0 is released, @beta is needed: without it you get 0.4, which has a different API.
With TypeScript, you need TypeScript 5.7 or later, and @types/node in your project.
Each example below is a module of its own. None of them use TypeScript syntax, so you can save one as step.mjs and run it with node step.mjs. Run them in order, from the same directory.
Create a storage root
Section titled “Create a storage root”A storage root is the directory that holds your OCFL objects. createStorageRoot makes one. The directory must be empty or not exist yet; the library creates it if it’s missing.
import { createStorageRoot } from '@ocfl/ocfl-fs';
const root = await createStorageRoot('ocfl-root', { layout: { extensionName: '0004-hashed-n-tuple-storage-layout' },});
console.log(root.path, root.ocflVersion);You choose a storage layout when you create the storage root. It decides which directory each object goes in, worked out from the object’s id. 0004-hashed-n-tuple-storage-layout spreads objects across directories named from a digest of the id. See Storage layouts for the others, and LayoutConfig for their parameters.
You only create a storage root once. From then on, open it with openStorageRoot, which reads the storage layout back from the storage root.
Create an object
Section titled “Create an object”root.create makes a new OCFL object with its first version. It takes:
- the object’s id
- the version’s details: a message saying why the version was made, and the user making it. The user’s
addressis optional; use a URI such as amailto:address or an ORCID. - a function that fills in a draft, the files the first version will hold
import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('ocfl-root');
const details = { message: 'First deposit', user: { name: 'Alice', address: 'mailto:alice@example.org' },};
const object = await root.create('item-1', details, async (draft) => { await draft.write('hello.txt', 'Hello, world'); await draft.write('notes/field-notes.txt', 'Recorded on site');});
console.log(object.id, object.head.number);draft.write puts text, bytes or a stream at a logical path: the file’s path inside the object, such as notes/field-notes.txt. To bring in files or a whole directory from disk, use draft.import instead.
Nothing is written to the object until your function returns. The library then commits the draft as version 1. If your function throws, the draft is discarded, no object is created, and create throws the same error. Await every draft operation inside the function.
create returns the new OcflObject. If an object with that id already exists, it throws an OcflError with code OBJECT_EXISTS.
Open an object and read a file
Section titled “Open an object and read a file”root.open reads an object by its id. If there’s no such object, it throws an OcflError with code OBJECT_NOT_FOUND. Errors covers how to catch an OcflError and what each code means.
import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('ocfl-root');const object = await root.open('item-1');
console.log(`Version ${object.head.number}: ${object.head.message}`);
for (const path of object.head.files.keys()) { console.log(path);}
const file = object.head.files.get('hello.txt');if (file) { console.log(await file.text());}object.head is the latest version. Its files map each logical path to an OcflFile, which you can read with text(), bytes() or stream(). A stream can cover just a byte range, which suits large files.
Every earlier version stays readable too: object.versions maps each version number to its version, so object.versions.get(1)?.files gives the files of version 1.
An opened object is the object as it was when you opened it. It doesn’t change when someone commits a later version; open it again to see that.
Next steps
Section titled “Next steps”- Add a version to an object with
object.update. It works likecreate, but the draft starts with the files of the head version. Updating objects covers every draft operation and the order they take effect in. - If more than one process writes to the same storage root, read Concurrent writers and recovery.
- See Use cases and best practices for a deposit service, a file server, an indexing job and a fixity check across a storage root.
- Check what the library does and doesn’t do in the overview. In particular, it doesn’t validate OCFL objects.
- The API reference lists every function, type and error.