Skip to content

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.

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.

Terminal window
pnpm add @ocfl/ocfl-fs@beta

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

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.

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 address is optional; use a URI such as a mailto: 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.

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.

  • Add a version to an object with object.update. It works like create, 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.