@ocfl/ocfl 0.2.0 → 0.3.0

package/lib/inventory.js

@@ -1,55 +1,72 @@
+'use strict';
+
 //@ts-check
+/** @typedef {import('./types').Inventory} Inventory */
+/** @typedef {import('./types').InventoryDigests} InventoryDigests */
 
-const path = require('path');
-const { digestSync } = require('./digest.js').OcflDigest;
-//const {createHash} = require('crypto');
-
-function nextVersion(currentVersion) {
-  let zeroPaddingLength = 0;
-  let currentVer = currentVersion.replace('v', '');
-  if (currentVer.startsWith('0')) zeroPaddingLength = currentVer.length;
-  let newVer = '' + (parseInt(currentVer) + 1);
-  newVer = 'v' + (zeroPaddingLength ? newVer.padStart(zeroPaddingLength, '0') : newVer);
-  return newVer;
-}
+class VersionNumber {
+  value;
+  zeroPaddingLength;
+  /**
+   * 
+   * @param {number} num
+   * @param {number} [zeroPaddingLength]
+   */
+  constructor(num, zeroPaddingLength) {
+    this.value = num;
+    this.zeroPaddingLength = zeroPaddingLength;
+  }
+  valueOf() {
+    return this.value;
+  }
+  toString() {
+    return 'v' + (this.zeroPaddingLength ? (this.value + '').padStart(this.zeroPaddingLength, '0') : this.value);
+  }
+  next() {
+    return new VersionNumber(this.value + 1, this.zeroPaddingLength);
+  }
+  previous() {
+    const n = this.value - 1;
+    if (n > 0) return new VersionNumber(n, this.zeroPaddingLength);
+  }
+  /**
+   * 
+   * @param {number} num 
+   * @param {number} zeroPaddingLength 
+   */
+  static fromInt(num, zeroPaddingLength) {
+    return new VersionNumber(num, zeroPaddingLength);
+  }
+  /**
+   * 
+   * @param {string} versionLabel 
+   */
+  static fromString(versionLabel) {
+    const label = versionLabel.replace('v', '');
+    let zeroPaddingLength;
+    if (label.startsWith('0')) zeroPaddingLength = label.length;
+    return new VersionNumber(parseInt(label), zeroPaddingLength);
+  }
+
+  static next(versionLabel) {
+    return VersionNumber.fromString(versionLabel).next();
+  }
 
-function prevVersion(currentVersion) {
-  let zeroPaddingLength = 0;
-  let currentVer = currentVersion.replace('v', '');
-  if (currentVer.startsWith('0')) zeroPaddingLength = currentVer.length;
-  let prevVer = '' + (parseInt(currentVer) - 1);
-  prevVer = 'v' + (zeroPaddingLength ? prevVer.padStart(zeroPaddingLength, '0') : prevVer);
-  return prevVer;
+  static previous(versionLabel) {
+    return VersionNumber.fromString(versionLabel).previous();
+  }
 }
 
 /**
  * @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]
- */
-
+function findKey(file, obj) {
+  for (let digest in obj) {
+    const arr = obj[digest];
+    if (arr.includes(file)) return digest;
+  }
+}
 
 /**
  * Wrapper class for inventory data
@@ -57,30 +74,121 @@ function prevVersion(currentVersion) {
 class OcflObjectInventory {
   /** @type {Inventory} */
   #data;
-  /** @type {InventoryVersion} */
-  #version;
+  /** @type {{[key: string]: {[key:string]: {[key:string]: string}}}} */
+  #fileIndex = {};
+
+  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]
+   * Helper function to find the digest by logical file path and cached it by indexing
+   * @param {string} logicalPath
+   * @param {string} version
+   * @param {boolean} [onlyUsecache]
+   */
+  _indexGet(logicalPath, version, onlyUsecache) {
+    let digests = this.#fileIndex[version]?.[logicalPath];
+    if (!digests && !onlyUsecache) {
+      // search and then index
+      const fixity = this.fixity;
+      const algo = this.digestAlgorithm;
+      const digestArr = [];
+      const mainDigest = findKey(logicalPath, this.versionState(version));
+      if (mainDigest) {
+        digestArr.push([algo, mainDigest]);
+        if (fixity) {
+          const cp = this.getContentPath(mainDigest);
+          for (const fixityDigest in fixity) {
+            const digest = findKey(cp, fixity[fixityDigest]);
+            if (digest) digestArr.push([fixityDigest, digest]);
+          }
+        }
+      }
+      if (digestArr.length > 0) {
+        const verIndex = this.#fileIndex[version] = this.#fileIndex[version] || {};
+        digests = verIndex[logicalPath] = Object.fromEntries(digestArr);
+      }
+    }
+    return digests;
+  }
+
+  _indexAdd(logicalPath, version, digests) {
+    this.#fileIndex[version][logicalPath] = digests;
+  }
+
+  _indexRemove(logicalPath, version = this.head) {
+    const val = this.#fileIndex[version][logicalPath];
+    delete this.#fileIndex[version][logicalPath];
+    return val;
+  }
+
+  _indexBuild() {
+    // index fixity contentPaths
+    const fixity = this.fixity;
+    const fixityIndex = {};
+    if (fixity) {
+      for (const fixityAlgo in fixity) {
+        const digestBlock = fixity[fixityAlgo];
+        const fixityIndexDigest = fixityIndex[fixityAlgo] = {};
+        for (const digest in digestBlock) {
+          const cps = digestBlock[digest];
+          for (const cp of cps) {
+            fixityIndexDigest[cp] = digest;
+          }
+        }
+      }
+    }
+    // index logicalPaths
+    // { v1: { 'dir/file.txt': { sha512: 'abcdef' } } }
+    const index = this.#fileIndex = {};
+    const algo = this.digestAlgorithm;
+    for (const verName in this.versions) {
+      const ver = this.versions[verName];
+      const indexVer = index[verName] = {};
+      for (const digest in ver.state) {
+        for (const lp of ver.state[digest]) {
+          const file = indexVer[lp] = { [algo]: digest };
+          if (fixity) {
+            for (const fixityAlgo in fixityIndex) {
+              const fixityIndexDigest = fixityIndex[fixityAlgo];
+              const cps = this.manifest[digest] || [];
+              for (const cp of cps) {
+                if (fixityIndexDigest[cp]) file[fixityAlgo] = fixityIndexDigest[cp];
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  _indexFindPaths(prefix, version = this.head) {
+    const res = [];
+    const index = this.#fileIndex[version];
+    const prefixWithSlash = prefix.endsWith('/') ? prefix : prefix + '/';
+    for (const lp in index) {
+      if (index[lp] && (lp === prefix || lp.startsWith(prefixWithSlash))) res.push(lp);
+    }
+    return res;
+  }
+
+
+  /**
+   * Create a new mutable OcflObjectInventory from the object config or clone an existing inventory,
+   * and increase the inventory version number. If data.head is undefined, starts from v1.
+   * @param {Partial<Inventory> | OcflObjectInventory} data
    * @param {boolean} [cleanState] 
    */
   static newVersion(data, cleanState) {
+    if (data instanceof OcflObjectInventory) {
+      data = data.toJSON();
+    }
     if (!data.id || !data.digestAlgorithm || !data.type) throw new Error('Inventory must have an id, digestAlgorithm and type.');
     data.manifest = data.manifest || {};
     data.versions = data.versions || {};
     let prevVer;
     if (data.head) {
       prevVer = data.versions[data.head];
-      data.head = nextVersion(data.head);
+      data.head = VersionNumber.next(data.head).toString();
     } else {
       data.head = 'v1';
       cleanState = true;
@@ -99,31 +207,39 @@ class OcflObjectInventory {
    */
   constructor(data, version) {
     this.#data = data;
-    this.#version = data.versions[version || data.head];
+    this._indexBuild();
   }
 
   get id() { return this.#data.id }
   get type() { return this.#data.type }
   get digestAlgorithm() { return this.#data.digestAlgorithm }
   get head() { return this.#data.head }
+  /** The version number of the current head */
+  get versionNumber() { return VersionNumber.fromString(this.head); }
   get contentDirectory() { return this.#data.contentDirectory || 'content' }
   get manifest() { return this.#data.manifest }
   get versions() { return this.#data.versions }
+  get version() { return this.versions[this.head] }
   get fixity() { return this.#data.fixity }
-  get state() { return this.#version.state }
-  get created() { return this.#version.created }
-  get message() { return this.#version.message }
-  get user() { return this.#version.user }
-  get prevVersion() { return prevVersion(this.head); }
+  set fixity(val) { this.#data.fixity = val; }
+  /** The state of the current version */
+  get state() { return this.version.state }
+  get created() { return this.version.created }
+  get message() { return this.version.message }
+  get user() { return this.version.user }
+  //get nextVersion() { return this.versionNumber.next().toString(); }
+  //get prevVersion() { return this.versionNumber.previous()?.toString(); }
 
   /** Return true if there has been actual change to the state of current version compared to the previous version */
   get isChanged() {
-    let diff = this.diffState(this.head, prevVersion(this.head));
+    const prev = this.versionNumber.previous()?.toString();
+    if (!prev) return true;
+    let diff = this.diffState(this.head, prev);
     return Object.keys(diff[0]).length > 0 || Object.keys(diff[1]).length > 0;
   }
-  set created(val) { this.#version.created = val; }
-  set message(val) { this.#version.message = val; }
-  set user(val) { this.#version.user = val; }
+  set created(val) { this.version.created = val; }
+  set message(val) { this.version.message = val; }
+  set user(val) { this.version.user = val; }
 
   /**
    * Return the state of the specified version
@@ -138,11 +254,6 @@ class OcflObjectInventory {
     return JSON.stringify(this.#data, null, 2);
   }
 
-  /** Compute digest from current state of this inventory object*/
-  digest() {
-    return digestSync(this.#data.digestAlgorithm, this.toString());
-  }
-
   /**
    * @return {Inventory}
    */
@@ -170,7 +281,9 @@ class OcflObjectInventory {
           logicalPath,
           version,
           digest,
-          contentPath
+          contentPath,
+          fixity: this.getFixity(logicalPath, version),
+          ...this.metadata?.[contentPath]
         };
       }
     }
@@ -198,21 +311,64 @@ class OcflObjectInventory {
   }
 
   /**
-   * Get the content digest of the specified logicalPath
+   * Get the digest of a content represented by the logicalPath of the specified version
    * @param {string} logicalPath 
    * @param {string} [versionName] 
-   * @returns 
    */
-  getDigest(logicalPath, versionName) {
-    let state = this.versionState(versionName);
-    return Object.keys(state).find(d => state[d].includes(logicalPath));
+  getDigest(logicalPath, versionName = this.head) {
+    return this._indexGet(logicalPath, versionName, true)?.[this.digestAlgorithm];
+  }
+
+  /**
+   * Get the file information by the logicalPath of the specified version
+   * @param {string} logicalPath 
+   * @param {string} [versionName] 
+   */
+  getFile(logicalPath, versionName = this.head) {
+    const digest = this.getDigest(logicalPath, versionName);
+    const contentPath = this.getContentPath(digest);
+    const version = versionName;
+    if (digest) {
+      return {
+        logicalPath,
+        version,
+        digest,
+        contentPath,
+        fixity: this.getFixity(logicalPath, version),
+        ...this.metadata?.[contentPath]
+      }
+    }
+  }
+
+  getFileByDigest(digest, versionName) {
+    if (versionName) return this.getFile(this.versions[versionName].state[digest]?.[0], versionName);
+    for (const version in this.versions) {
+      const logicalPath = this.versions[version].state[digest]?.[0];
+      if (logicalPath) return this.getFile(logicalPath, version);
+    }
+  }
+
+  getFileByContentPath(contentPath, versionName) {
+    for (const digest in this.manifest) {
+      if (this.manifest[digest].includes(contentPath)) return this.getFileByDigest(digest, versionName);
+    }
+  }
+
+  /**
+   * Get the fixity of a content represented by the logicalPath of the specified version
+   * @param {string} logicalPath 
+   * @param {string} [versionName] 
+   */
+  getFixity(logicalPath, versionName = this.head) {
+    const { [this.digestAlgorithm]: digest, ...fixity } = this._indexGet(logicalPath, versionName, true) || {};
+    return fixity;
   }
 
   /**
    * 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 +393,7 @@ class OcflObjectInventory {
       return Object.fromEntries(r);
     });
 
-    return /** @type {[InventoryState, InventoryState]} */(result);
+    return /** @type {[InventoryDigests, InventoryDigests]} */(result);
   }
 }
 
@@ -246,41 +402,27 @@ class OcflObjectInventory {
  * Wrapper class with mutable methods for inventory data
  */
 class OcflObjectInventoryMut extends OcflObjectInventory {
-  /** @type {Object.<string,string>} */
-  #byPath;
 
   constructor(data) {
     super(data);
-    //index logicalPaths
-    let byPath = this.#byPath = {};
-    let state = this.state;
-    for (let d in state) {
-      let files = state[d];
-      for (let lp of files) {
-        byPath[lp] = d;
-      }
-    }
-  }
-
-  /**
-   * Get the digest of a content represented by the logicalPath of the specified version
-   * @param {string} logicalPath 
-   * @param {string} [versionName] 
-   * @return {string}
-   */
-  getDigest(logicalPath, versionName) {
-    if (versionName) return super.getDigest(logicalPath, versionName);
-    else return this.#byPath[logicalPath];
   }
 
   /**
    * Add a new file to the inventory or update the digest of an existing file
    * @param {string} digest
    * @param {string} logicalPath 
+   * @param {{[x: string]: string}} [fixity]
    * @return {boolean} - true if the state is changed
    */
-  add(logicalPath, digest) {
-    let state = this.state;
+  add(logicalPath, digest, fixity) {
+    const state = this.state;
+    const contentPath = this.head + '/' + this.contentDirectory + '/' + logicalPath;
+    // add fixity info
+    if (fixity) {
+      for (const digestName in fixity) {
+        this.addFixity(contentPath, digestName, fixity[digestName]);
+      }
+    }
     if (state[digest]) {
       // this is a file with identical content but different name
       if (state[digest].indexOf(logicalPath) < 0) state[digest].push(logicalPath);
@@ -290,19 +432,38 @@ class OcflObjectInventoryMut extends OcflObjectInventory {
       if (mf && mf.length > 0) {
         // this is a reinstatement
       } else {
-        // normal addition
-        this.manifest[digest] = [path.join(this.head, this.contentDirectory, logicalPath)];
+        // normal addition of a new file
+        this.manifest[digest] = [contentPath];
       }
-      if (this.#byPath[logicalPath]) {
+      if (this.getDigest(logicalPath)) {
         // this is an update, remove old digest
         this.delete(logicalPath);
       }
       state[digest] = [logicalPath];
     }
-    this.#byPath[logicalPath] = digest;
+    this._indexAdd(logicalPath, this.head, { [this.digestAlgorithm]: digest, ...fixity });
     return true;
   }
 
+  /**
+   * Low-level method to add a set of digest entries associated to file into the fixity block
+   * @param {string} contentPath 
+   * @param {string} digestName
+   * @param {string} digestValue
+   */
+  addFixity(contentPath, digestName, digestValue) {
+    if (!digestValue || !digestName) return;
+    const fixityBlock = this.fixity = this.fixity || {};
+    const digestBlock = fixityBlock[digestName] = fixityBlock[digestName] || {};
+    if (digestBlock[digestValue]) {
+      if (!digestBlock[digestValue].includes(contentPath)) {
+        digestBlock[digestValue].push(contentPath);
+      }
+    } else {
+      digestBlock[digestValue] = [contentPath];
+    }
+  }
+
   /**
    * Rename a logical path. This will overwrite dest if exists
    * @param {string} srcLogicalPath 
@@ -311,18 +472,17 @@ class OcflObjectInventoryMut extends OcflObjectInventory {
   rename(srcLogicalPath, destLogicalPath) {
     let srcPrefix = srcLogicalPath.endsWith('/') ? srcLogicalPath : srcLogicalPath + '/';
     let destPrefix = destLogicalPath.endsWith('/') ? destLogicalPath : destLogicalPath + '/';
-    let srcList = Object.keys(this.#byPath).filter(p => p.startsWith(srcPrefix));
+    let srcList = this._indexFindPaths(srcPrefix);
     let pairs = srcList.map(src => [src, destPrefix + src.slice(srcPrefix.length)]);
     if (pairs.length === 0) pairs.push([srcLogicalPath, destLogicalPath]);
     for (let [src, dest] of pairs) {
-      let digest = this.#byPath[src];
+      let digest = this.getDigest(src);
       let files = this.state[digest];
       let index = files?.indexOf(src);
       if (index >= 0) {
         this.delete(dest); //overwrite
         files[index] = dest;
-        this.#byPath[dest] = digest;
-        this.#byPath[src] = null;
+        this._indexAdd(dest, this.head, this._indexRemove(src, this.head));
       } else {
         /** @todo decide: throw error or silently ignore non-existant file? */
       }
@@ -337,21 +497,21 @@ class OcflObjectInventoryMut extends OcflObjectInventory {
   copy(srcLogicalPath, destLogicalPath) {
     let srcPrefix = srcLogicalPath.endsWith('/') ? srcLogicalPath : srcLogicalPath + '/';
     let destPrefix = destLogicalPath.endsWith('/') ? destLogicalPath : destLogicalPath + '/';
-    let srcList = Object.keys(this.#byPath).filter(p => p.startsWith(srcPrefix));
+    let srcList = this._indexFindPaths(srcPrefix);
     let pairs = srcList.map(src => [src, destPrefix + src.slice(srcPrefix.length)]);
     if (pairs.length === 0) pairs.push([srcLogicalPath, destLogicalPath]);
     for (let [src, dest] of pairs) {
       if (!dest) throw new Error(`Target logical path cannot be empty`);
-      let digest = this.#byPath[src];
+      let digest = this._indexGet(src, this.head, true);
       if (!digest) throw new Error(`Source logical path "${src}" does not exist in object [${this.id}]`);
       //console.log(this.state);
-      let files = this.state[digest];
+      let files = this.state[digest[this.digestAlgorithm]];
       let index = files?.indexOf(dest);
       if (index >= 0) {
         /** @todo decide: throw error or silently ignore existing dest file? */
       } else {
         files.push(dest);
-        this.#byPath[dest] = digest;
+        this._indexAdd(dest, this.head, digest);
       }
     }
   }
@@ -359,20 +519,23 @@ class OcflObjectInventoryMut extends OcflObjectInventory {
   /**
    * Delete a file
    * @param {string} logicalPath 
+   * @param {string} [version] 
    */
-  delete(logicalPath) {
-    let prefix = logicalPath.endsWith('/') ? logicalPath : logicalPath + '/';
-    let names = this.getDigest(logicalPath) ? [logicalPath] :
-      Object.keys(this.#byPath).filter(p => p.startsWith(prefix));
+  delete(logicalPath, version = this.head) {
+    const names = this._indexFindPaths(logicalPath, version);
     let count = 0;
+    const state = this.versionState(version);
     for (let lp of names) {
-      let digest = this.#byPath[lp];
-      let files = this.state[digest];
-      let index = files?.indexOf(lp);
+      const digest = this.getDigest(lp, version);
+      const files = state[digest];
+      const index = files?.indexOf(lp);
       if (index >= 0) {
-        files.splice(index, 1);
-        if (files.length === 0) delete this.state[digest];
-        this.#byPath[lp] = null;
+        if (files.length === 1) {
+          delete state[digest];
+        } else {
+          files.splice(index, 1);
+        }
+        this._indexRemove(lp, version);
         count++;
       }
     }
@@ -380,19 +543,17 @@ class OcflObjectInventoryMut extends OcflObjectInventory {
   }
 
   reinstate(logicalPath, versionName) {
-    let prefix = logicalPath.endsWith('/') ? logicalPath : logicalPath + '/';
-    let digest = this.getDigest(logicalPath, versionName);
-    /** @type {FileRef[]} */
-    let files = digest ? [{ logicalPath, digest }] :
-      [...this.find(f => f.logicalPath.startsWith(prefix), versionName)];
+    let names = this._indexFindPaths(logicalPath, versionName);
+    //let digest = this.getDigest(logicalPath, versionName);
     let state = this.state;
     let count = 0;
-    for (let f of files) {
-      if (this.getDigest(f.logicalPath)) {
-        let c = this.delete(f.logicalPath);
+    for (let lp of names) {
+      const digests = this._indexGet(lp, versionName);
+      if (digests) {
+        let c = this.delete(lp);
       }
-      state[f.digest] = [f.logicalPath];
-      this.#byPath[f.logicalPath] = f.digest;
+      state[digests[this.digestAlgorithm]] = [lp];
+      this._indexAdd(lp, this.head, digests);
       count++;
     }
     return count;
@@ -400,4 +561,4 @@ class OcflObjectInventoryMut extends OcflObjectInventory {
 
 }
 
-module.exports = { OcflObjectInventory, OcflObjectInventoryMut };
+module.exports = { OcflObjectInventory, OcflObjectInventoryMut, VersionNumber };