@ocfl/ocfl 0.2.0 → 0.2.2

package/lib/digest.js

@@ -58,17 +58,18 @@ for (let algo of FIXITY) {
  */
 function createStream(algorithm) {
   const hash = algorithms[algorithm || 'sha512']();
-  hash.setEncoding('hex');
+  //hash.setEncoding('hex');
   return hash;
 }
 
 /**
  * 
- * @param {string} algorithm 
+ * @param {string} [algorithm] 
+ * @param {object} [options] 
  */
-function createStreamThrough(algorithm, options) {
-  const hash = algorithms[algorithm || 'sha512']();
-  hash.setEncoding('hex');
+function createStreamThrough(algorithm = 'sha512', options) {
+  const hash = algorithms[algorithm]();
+  //hash.setEncoding('hex');
   return new HashThrough(hash, options);
 }
 

package/lib/extension.js

@@ -99,7 +99,7 @@ class OcflExtension {
 
   static get forObject() { return false; }
   static get forStorage() { return false; }
-  static setup(ocfl) { };
+  static async setup(ocfl) { };
   static get NAME() { return '0000-example-extension' }
   static get DESCRIPTION() { return 'Example extension' }
 

package/lib/extensions/0001-digest-algorithms.js

@@ -2,7 +2,8 @@
 
 const {OcflExtension} = require("../extension");
 const crypto = require('crypto');
-const blake2 = require('blake2');
+//const blake2 = require('blake2');
+const { createBLAKE2b } = require('hash-wasm');
 
 class DigestAlgorithm extends OcflExtension {
   static get NAME() { return '0001-digest-algorithms' }
@@ -15,7 +16,7 @@ class DigestAlgorithm extends OcflExtension {
    * 
    * @param {import('ocfl')} ocfl 
    */
-  static setup(ocfl) {
+  static async setup(ocfl) {
     let {OcflDigest} = ocfl;
     let { FIXITY } = OcflDigest;
     class FIXITY_EX extends FIXITY {
@@ -26,9 +27,13 @@ class DigestAlgorithm extends OcflExtension {
     };
     OcflDigest.FIXITY = FIXITY_EX;
     //console.log(OcflDigest.FIXITY);
-    for (let len of [160, 256, 384]) {
-      OcflDigest.algorithms['blake2b-' + len] = function() { 
-        return blake2.createHash('blake2b', {digestLength: len/8}); 
+    const blake2b = Object.fromEntries(await Promise.all([160, 256, 384].map(bits => [bits, createBLAKE2b(bits)])));
+    
+    for (let bits of [160, 256, 384]) {
+      OcflDigest.algorithms['blake2b-' + bits] = function() { 
+        //return blake2.createHash('blake2b', {digestLength: len/8}); 
+        blake2b[bits].init();
+        return blake2b[bits];
       }
     }
     OcflDigest.algorithms['sha512/256'] = function() { 

package/lib/inventory.js

@@ -26,31 +26,6 @@ function prevVersion(currentVersion) {
  * @typedef {{logicalPath?: string; digest?: string; contentPath?: string;}} FileRef
  */
 
-/**
- * @typedef {Object.<string, string[]>} InventoryState
- */
-
-/**
- * @typedef {Object} InventoryVersion
- * @property {string} [created]
- * @property {InventoryState} state
- * @property {string} [message]
- * @property {{name:string, address:string}} [user]
- */
-
-/**
- * @typedef {Object} Inventory
- * @property {string} id - A unique identifier for the OCFL Object.
- * @property {string} type - The URI of the inventory section of the specification version matching the object conformance declaration.
- * @property {string} digestAlgorithm - The digest algorithm used for calculating digests for content-addressing within the OCFL Object and for the Inventory Digest.
- * @property {string} head - The version directory name of the most recent version of the object.
- * @property {string} [contentDirectory='content'] - The name of the designated content directory within the version directories.
- * @property {InventoryState} manifest
- * @property {Object.<string, InventoryVersion>} versions
- * @property {Object} [fixity]
- */
-
-
 /**
  * Wrapper class for inventory data
  */
@@ -59,18 +34,10 @@ class OcflObjectInventory {
   #data;
   /** @type {InventoryVersion} */
   #version;
-
+  metadata;
   /**
    * Create a mutable inventory and increase the inventory version number
-   * @param {Object} data
-   * @param {string} data.id
-   * @param {string} data.type
-   * @param {string} data.digestAlgorithm
-   * @param {string} [data.head]
-   * @param {string} [data.contentDirectory]
-   * @param {Object.<string, string[]>} [data.manifest]
-   * @param {Object.<string, InventoryVersion>} [data.versions]
-   * @param {Object} [data.fixity]
+   * @param {Inventory} data
    * @param {boolean} [cleanState] 
    */
   static newVersion(data, cleanState) {
@@ -170,7 +137,8 @@ class OcflObjectInventory {
           logicalPath,
           version,
           digest,
-          contentPath
+          contentPath,
+          ...this.metadata?.[contentPath]
         };
       }
     }
@@ -212,7 +180,7 @@ class OcflObjectInventory {
    * Compare the differences between the state of two versions
    * @param {string} version0
    * @param {string} version1 
-   * @return {[InventoryState, InventoryState]} - A tuple of [A, B] where A contains files
+   * @return {[InventoryDigests, InventoryDigests]} - A tuple of [A, B] where A contains files
    *     that are in `version0` but not in `version1` and B contains files
    *     that are in `version1` but not in `version0`
    */
@@ -237,7 +205,7 @@ class OcflObjectInventory {
       return Object.fromEntries(r);
     });
 
-    return /** @type {[InventoryState, InventoryState]} */(result);
+    return /** @type {[InventoryDigests, InventoryDigests]} */(result);
   }
 }
 

package/lib/object.js

@@ -11,7 +11,6 @@ const { OcflStore } = require('./store.js');
 const { OcflExtension } = require('./extension.js');
 const { NotImplementedError } = require('./error.js');
 const { parallelize, dataSourceAsIterable, isDirEmpty, findNamasteVersion } = require('./utils');
-const { format } = require('util');
 const { OCFL_VERSION, OCFL_VERSIONS, INVENTORY_NAME, NAMASTE_PREFIX_OBJECT, NAMASTE_T } = require('./constants').OcflConstants;
 
 class UPDATE_MODE extends Enum {
@@ -24,9 +23,9 @@ const DIGEST = OcflDigest.CONTENT;
 
 /**
  * @typedef {Object} OcflObjectConfig
- * @property {string} root - Absolute path to the ocfl object root
- * @property {string} [workspace] - Absolute path to object workspace directory
- * @property {('sha256' | 'sha512')} [digestAlgorithm] - Digest algorithm for content-addressing, must use either sha512 or sha256
+ * @property {string} root - Absolute path to the ocfl object root.
+ * @property {string} [workspace] - Absolute path to object workspace directory.
+ * @property {('sha256' | 'sha512')} [digestAlgorithm] - Digest algorithm for content-addressing, must use either sha512 or sha256.
  * @property {string} [id] - Identifier for the object.  Only be used in a newly created object.
  * @property {string} [contentDirectory='content'] - Content directory name. Only applies to a newly created object.
  * @property {string} [ocflVersion=c.OCFL_VERSION] - Ocfl version. Only applies to a newly created object.
@@ -35,14 +34,26 @@ const DIGEST = OcflDigest.CONTENT;
 /**
  * @typedef {UPDATE_MODE | ('MERGE' | 'REPLACE') } ObjectUpdateMode
  * 
- * @typedef {{logicalPath?: string, digest?: string, contentPath?: string, version?: string}} FileRef
+ * @typedef {Object} FileRef
+ * @property {string} [contentPath] - Actual path to the file location relative to the ocfl object root.
+ * @property {string} [logicalPath] - A path that represents a file’s location in the logical state of an object.
+ * @property {string} [digest] - An algorithmic characterization of the contents of a file conforming to a standard digest algorithm.
+ * @property {string} [version] - Version of the OCFL object.
+ * @property {string} [lastModified] - Last modified date of the file.
+ * @property {string} [size] - Size of the file in bytes.
  * @typedef {{logicalPath: string, version?: string}} FileRefLogical
  * @typedef {{digest: string}} FileRefDigest
  * @typedef {{contentPath: string}} FileRefContent
  */
 
+/**
+ * Represent a file in an OCFL object
+ */
 class OcflObjectFile {
   #ocflObject;
+  #lastModified;
+  #size;
+
   /**
    * 
    * @param {OcflObjectImpl} ocflObject 
@@ -57,6 +68,8 @@ class OcflObjectFile {
     if (fileRef.contentPath) this.contentPath = fileRef.contentPath;
     if (fileRef.digest) this.digest = fileRef.digest;
     if (fileRef.version) this.version = fileRef.version;
+    if (fileRef.lastModified != null) this.#lastModified = fileRef.lastModified;
+    if (fileRef.size != null) this.#size = fileRef.size;
   }
 
   /**
@@ -66,6 +79,7 @@ class OcflObjectFile {
     let contentPath = this.contentPath;
     if (!contentPath) {
       let inv = await this.#ocflObject.getInventory();
+      if (!inv) throw new Error(`OCFL Object "${this.#ocflObject.id}" does not exist`);
       let version = !this.version || this.version === 'latest' ? inv.head : this.version;
       let digest = this.digest || inv.getDigest(this.logicalPath, version);
       contentPath = inv.getContentPath(digest);
@@ -74,12 +88,22 @@ class OcflObjectFile {
     return contentPath;
   }
 
+  /**
+   * Returns the last modified time of the file, in millisecond since the UNIX epoch (January 1st, 1970 at Midnight).
+   */
+  get lastModified() { return this.#lastModified  }
+  
+  /**
+   * Returns the file size in bytes.
+   */
+  get size() { return this.#size }
+
   toString() {
-    let o = {};
+    let props = [];
     for (const key in ['logicalPath', 'version', 'digest', 'contentPath']) {
-      if (this[key]) o[key] = this[key];
+      if (this[key]) props.push(key + ": '" + this[key] + "'");
     }
-    return format('%O', o);
+    return `{ ${props.join(', ')} }`;
   }
 
   /**
@@ -88,28 +112,51 @@ class OcflObjectFile {
 
    * @return {Promise<Buffer>}
    */
-  async asBuffer(options) {
+  async buffer(options) {
     return this.#ocflObject.readFile(await this.#resolveContentPath(), options);
   }
+  /**
+   * @deprecated
+   */
+  async asBuffer(options) {
+    return this.buffer(options);
+  }
 
   /**
    * Get the file content as a string
    * @param {BufferEncoding} [encoding='utf8'] String encoding, default to utf8
    * @return {Promise<string>}
    */
+  async text(encoding = 'utf8') {
+    // @ts-ignore
+    return this.buffer(encoding);
+  }
+  /**
+   * @deprecated
+   */
   async asString(encoding = 'utf8') {
     // @ts-ignore
-    return this.asBuffer(encoding);
+    return this.text(encoding);
   }
 
   /**
-   * Get the file content as a stream
+   * Get the file content as a NodeJS stream
    * @param {*} [options] Options to be passed to underlying data store specific implementation
    * @return {Promise<NodeJS.ReadableStream>}
+   * @deprecated
    */
   async asStream(options) {
     return this.#ocflObject.createReadStream(await this.#resolveContentPath(), options);
   }
+
+  /**
+   * Get the file content as a ES Streams standard ReadableStream
+   * @param {*} [options] Options to be passed to underlying data store specific implementation
+   * @return {Promise<ReadableStream>}
+   */
+  async stream(options) {
+    return this.#ocflObject.createReadable(await this.#resolveContentPath(), options);
+  }
 }
 
 
@@ -196,12 +243,7 @@ class OcflObject {
     await this.import(sourceDir, mode);
   }
 
-  async load() {
-    this._inventory = {};
-    await this.getInventory();
-    //await this.loadExtensions();
-    return;
-  }
+  async load() { throw new NotImplementedError(); }
 
   /**
    * Iterate through the content files contained in the specified version. 
@@ -328,7 +370,7 @@ class OcflObjectImpl extends OcflObject {
       //inventory does not exist yet
       return;
     }
-    let data = /** @type import('./inventory.js').Inventory */(JSON.parse(datastr));
+    let data = /** @type Inventory */(JSON.parse(datastr));
     let [digest, actualDigest] = /** @type [string,string] */ (await Promise.all([
       this.readFile(invPath + '.' + data.digestAlgorithm, 'utf8'),
       OcflDigest.digestAsync(data.digestAlgorithm, datastr)
@@ -339,6 +381,23 @@ class OcflObjectImpl extends OcflObject {
     return new OcflObjectInventory(data);
   }
 
+  async load() {
+    this._inventory = {};
+    const inv = await this.getInventory();
+    //await this.loadExtensions();
+
+    //load file metadata from underlying storage
+    const metadata = inv.metadata = {};
+    for await (const file of await this.#store.list(this.root, { recursive: true })) {
+      const contentPath = file.path;
+      metadata[contentPath] = {
+        size: file.size,
+        lastModified: file.lastModified.getTime()
+      }
+    }
+    return;
+  }
+
   /**
    * @param {function(OcflObjectTransaction):Promise<*>} [updater]
    * @param {ObjectUpdateMode} [mode=UPDATE_MODE.MERGE]
@@ -363,10 +422,15 @@ class OcflObjectImpl extends OcflObject {
     return t;
   }
 
+  /** @deprecated */
   async createReadStream(filePath, options) {
     return this.#store.createReadStream(path.join(this.root, filePath), options);
   }
 
+  async createReadable(filePath, options) {
+    return this.#store.createReadable(path.join(this.root, filePath), options);
+  }
+
   /** 
   @typedef {import('fs').OpenMode} OpenMode
   @typedef {import('events').Abortable} Abortable

package/lib/storage.js

@@ -15,7 +15,9 @@ const DIGEST = require('./digest').OcflDigest.CONTENT;
 
 const DEFAULT_LAYOUT = HashedNTupleStorageLayout;
 
-/** 
+/**
+ * An abstraction to represent the OCFL Storage Root, which is
+ * a base directory used to store OCFL Objects, identified by a [NAMASTE] file “0=ocfl_1.1”.
  * @typedef {import('./extension').OcflExtensionConfig} OcflExtensionConfig
  * @typedef {import('./store').OcflStore} OcflStore
  */

package/lib/store.js

@@ -52,6 +52,7 @@ class OcflStore {
   * @param {string} filePath - Absolute path
   * @param {*} options 
   * @return {Promise<import('fs').ReadStream>}
+  * @deprecated
   */
   async createReadStream(filePath, options) { throw new Error('Not Implemented'); }
 
@@ -60,9 +61,26 @@ class OcflStore {
    * @param {string} relPath 
    * @param {*} options 
    * @return {Promise<import('fs').WriteStream>}
+   * @deprecated
    */
   async createWriteStream(relPath, options) { throw new Error('Not Implemented'); }
 
+  /**
+  * Create a ReadableStream to get the content of a file
+  * @param {string} filePath - Absolute path
+  * @param {*} options 
+  * @return {Promise<ReadableStream>}
+  */
+  async createReadable(filePath, options) { throw new Error('Not Implemented'); }
+
+  /**
+   * Create a WritableStream that writes data to {@link relPath}. 
+   * @param {string} relPath 
+   * @param {*} options 
+   * @return {Promise<WritableStream>}
+   */
+  async createWritable(relPath, options) { throw new Error('Not Implemented'); }
+
   /**
    * Provide a common interface to read a file inside an object. 
    * A concrete subclass MAY implement this method to provide read access to its underlying storage backend.
@@ -125,6 +143,18 @@ class OcflStore {
    */
   async readdir(filePath, options) { throw new Error('Not Implemented'); }
 
+  /**
+   * List all files contained in a directory including the metadata such as size and last modified date.
+   * The returned file.path is a relative path to the dirPath
+   * @param {string} dirPath 
+   * @param {object} [options]
+   * @param {BufferEncoding} [options.encoding]
+   * @param {number} [options.bufferSize]
+   * @param {boolean} [options.recursive]
+   * @return {Promise<AsyncIterableIterator<{name: string, path: string, size: number, lastModified: Date}>> }
+   */
+  async list(dirPath, { encoding='utf8', bufferSize=32, recursive=false} = {}) { throw new Error('Not Implemented'); }
+
   /**
   * Recursively create a directory if the storage backend supports it, otherwise do nothing
   * @param {string} filePath - The directory path

package/lib/types.d.ts

@@ -1,5 +1,5 @@
 
-type OcflExtensionCreate = <T extends typeof import('./extension').OcflExtension>(this: T, config?: OcflExtensionConfig) => InstanceType<T>;
+//type OcflExtensionCreate = <T extends typeof import('./extension').OcflExtension>(this: T, config?: OcflExtensionConfig) => InstanceType<T>;
 
 
 // import { Abortable } from "events";
@@ -51,3 +51,45 @@ type StorageLayout = {
   NTupleOmitPrefixStorageLayout: typeof import('./extensions/0007-n-tuple-omit-prefix-storage-layout').NTupleOmitPrefixStorageLayout
   PathDirectStorageLayout: typeof import('./extensions/000N-path-direct-storage-layout').PathDirectStorageLayout
 }
+
+interface InventoryDigests {
+  [key:string]: string[];
+}
+
+interface InventoryVersion {
+  created: string;
+  message?: string;
+  state: InventoryDigests;
+  user?: {
+    name: string;
+    address?: string;
+  };
+}
+
+interface Inventory {
+  /** A unique identifier for the OCFL Object. */
+  id: string;
+  /** The URI of the inventory section of the specification version matching the object conformance declaration. */
+  type: 'https://ocfl.io/1.0/spec/#inventory' | 'https://ocfl.io/1.1/spec/#inventory';
+  /** 
+   * The algorithm used for calculating digests for content-addressing 
+   * within the OCFL Object and for the Inventory Digest. 
+   * This MUST be the algorithm used in the manifest and state blocks 
+   */
+  digestAlgorithm: 'sha256' | 'sha512';
+  /** The version directory name of the most recent version of the object. */
+  head: string;
+  manifest: InventoryDigests;
+  versions: {
+    [key:string]: InventoryVersion;
+  };
+  fixity?: {
+    [key in 'md5'|'sha1'|'sha256'|'sha512'|'blake2b-512']: {};
+  };
+  /** 
+   * The name of the designated content directory within the version directories.
+   * @default content
+   */
+  contentDirectory?: string;
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ocfl/ocfl",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Oxford Common File Layout (OCFL) JS library",
   "main": "index.js",
   "exports": {
@@ -25,7 +25,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Arkisto-Platform/ocfl-js.git"
+    "url": "git+https://github.com/Language-Research-Technology/ocfl-js.git"
   },
   "author": "Alvin Sebastian (https://orcid.org/0000-0002-9086-1722)",
   "contributors": [
@@ -34,13 +34,13 @@
   ],
   "license": "GPL-3.0-or-later",
   "dependencies": {
-    "blake2": "^4.1.1"
+    "hash-wasm": "^4.11.0"
   },
   "devDependencies": {
     "@types/mocha": "^9.1.1",
     "@types/node": "^17.0.33",
-    "typedoc": "^0.23.15",
-    "mocha": "^10.0.0"
+    "mocha": "^10.7.3",
+    "typedoc": "^0.23.15"
   },
   "mocha": {
     "extension": [
@@ -51,9 +51,12 @@
     "recursive": true
   },
   "bugs": {
-    "url": "https://github.com/Arkisto-Platform/ocfl-js/issues"
+    "url": "https://github.com/Language-Research-Technology/ocfl-js/issues"
+  },
+  "homepage": "https://github.com/Language-Research-Technology/ocfl-js#readme",
+  "engines": {
+    "node": ">=17.0.0"
   },
-  "homepage": "https://github.com/Arkisto-Platform/ocfl-js#readme",
   "directories": {
     "lib": "lib",
     "test": "test"