Skip to content
Language-Research-TechnologyPublic

About

Node.js library for creating and manipulating Oxford Common File Layout(OCFL) storage and object

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

2 watching

Forks

Latest commit

 

History

424 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

@ocfl/ocfl-fs

npm (beta) CI Licence: GPL-3.0-or-later

@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/

Installation

pnpm add @ocfl/ocfl-fs@beta

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

Example

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.

It doesn't validate

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.

Contributing

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.

About

Node.js library for creating and manipulating Oxford Common File Layout(OCFL) storage and object

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages