@ocfl/ocfl 0.4.0 → 1.0.0-beta.2

package/lib/object.js

@@ -1,499 +0,0 @@
-//@ts-check
-"use strict";
-
-const path = require('path');
-const validation = require('./validation.js');
-const { enumeration } = require('./enum.js');
-const { OcflObjectInventory, OcflObjectInventoryMut, VersionNumber } = require('./inventory.js');
-const { OcflDigest } = require('./digest.js');
-const { OcflObjectTransaction, OcflObjectTransactionImpl } = require('./transaction.js');
-const { OcflStore } = require('./store.js');
-const { OcflExtension } = require('./extension.js');
-const { NotImplementedError } = require('./error.js');
-const { parallelize, isDirEmpty, findNamasteVersion } = require('./utils');
-const { OcflObjectFile } = require('./file.js');
-const { OCFL_VERSION, OCFL_VERSIONS, INVENTORY_NAME, NAMASTE_PREFIX_OBJECT, NAMASTE_T } = require('./constants').OcflConstants;
-
-const UPDATE_MODES = /** @type { const } */(['MERGE', 'REPLACE']);
-const UPDATE_MODE = enumeration(UPDATE_MODES);
-const DIGEST = OcflDigest.CONTENT;
-
-/**
- * @typedef {(typeof UPDATE_MODES)[number]} UpdateModeStr
- * @typedef { InstanceType<typeof UPDATE_MODE> | UpdateModeStr} UpdateMode
- * @typedef {string} LogicalPath
- * @typedef {{logicalPath: string, version?: string}} FileRefLogical
- * @typedef {{digest: string, version?: string}} FileRefDigest
- * @typedef {{contentPath: string, version?: string}} FileRefContent
- * @typedef {import('./types').Inventory} Inventory
- * @typedef {import('./types').OcflVersion} OcflVersion
- * @typedef {import('./types').OcflObjectConfig} OcflObjectConfig
- * 
- */
-
-/**
- * A class representing an OCFL Object allowing to read and write the content of an OCFL Object in the underlying store.
- */
-class OcflObject {
-
-  /** @type {OcflVersion} */
-  #ocflVersion;
-  /** @type {string} */
-  #root;
-  /** @type {string} */
-  #workspace;
-  /** @type {string} */
-  #id;
-  /** @type {('sha256' | 'sha512')} */
-  #digestAlgorithm;
-  /** @type {OcflExtension[]} */
-  #extensions;
-  /** @type {OcflStore} */
-  #store;
-  /** 
-   * A default list of digest algorithms to be calculated for each file in this object and added to the fixity block.
-   * @type {string[]} 
-   */
-  fixityAlgorithms;
-
-  /**
-   * Create a new OCFL Object
-   * @param {OcflObjectConfig} config
-   * @param {OcflStore} store
-   */
-  constructor(config, store) {
-    if (!store) throw new TypeError('[OcflObject] store is required.');
-    this.#store = store;
-    if (!config.root) throw new TypeError('[OcflObject] config.root is required.');
-    if (config.root === config.workspace) throw new Error('[OcflObject] config.root and config.workspace must be different.');
-    this.#root = path.resolve(config.root);
-    this.#ocflVersion = config.ocflVersion || /** @type {OcflVersion} */(OCFL_VERSION);
-    //this.contentVersion = null; // No content yet
-    this.#id = config.id;
-    this.#extensions = config.extensions;
-    //this.fixityDigest = config.fixityDigest ?? this.digestAlgorithm;
-    this.digestAlgorithm = config.digestAlgorithm || 'sha512';
-    this.#workspace = config.workspace ? path.resolve(config.workspace) : undefined;
-    this.contentDirectory = config.contentDirectory ?? 'content';
-    /** @type Object.<string, OcflObjectInventory> */
-    this._inventory = {};
-    this.fixityAlgorithms = config.fixityAlgorithms;
-  }
-
-  /** the digest algorithm used to identify files within the OCFL object */
-  get digestAlgorithm() { return this.#digestAlgorithm; }
-  set digestAlgorithm(algorithm) {
-    this.#digestAlgorithm = algorithm;
-    // @ts-ignore
-    this.#digestAlgorithm = enumeration.of(DIGEST, algorithm || 'sha512')?.name;
-    if (!this.#digestAlgorithm) throw new Error('Invalid digest algorithm. Must be one of `sha256` or `sha512`.');
-  }
-
-  /** 
-  * Identifier of the OCFL Object
-  * @return {string} 
-  */
-  get id() { return this.inventory?.id || this.#id; }
-
-  /** 
-  * Latest version number of the OCFL Object
-  * @return {VersionNumber} 
-  */
-  get headVersion() {
-    const head = this.inventory?.head;
-    if (head) return VersionNumber.fromString(head);
-  }
-
-  /** 
-  * All available version numbers in the OCFL Object
-  * @return {VersionNumber[]} 
-  */
-  get versions() {
-    return Object.keys(this.inventory?.versions || {}).map(v => VersionNumber.fromString(v));
-  }
-
-  /** 
-  * The absolute path to the root of this OCFL Object
-  * @return {string} 
-  */
-  get root() { return this.#root; }
-
-  /** 
-  * The absolute path to the temporary workspace of this OCFL Object
-  * @return {string} 
-  */
-  get workspace() { return this.#workspace; }
-
-  /** The raw OCFL version number the object adheres to , eg 1.0, 1.1) */
-  get ocflVersion() { return this.#ocflVersion; }
-
-  /**
-   * Create a new backend-specific update transaction
-   * @param {OcflObjectInventoryMut} inventory
-   * @return {Promise<OcflObjectTransaction>}
-   */
-  async #createTransaction(inventory) {
-    await this._validateObjectPath();
-    if (!this.workspace) await this._ensureNamaste();
-    let workspacePath = this.workspace || this.root;
-    return OcflObjectTransactionImpl.create(this, this.#store, inventory, workspacePath);
-  }
-
-  async _ensureNamaste() {
-    let prefix = NAMASTE_PREFIX_OBJECT;
-    let nv = await findNamasteVersion(this.#store, prefix, this.root);
-    if (nv === '') throw validation.createError(6, this.root);
-    if (nv) {
-      if (!this.ocflVersion) this.#ocflVersion = /** @type {OcflVersion} */(nv);
-      return;
-    }
-    // namaste not found, check if object root is not empty
-    let files;
-    try {
-      files = await this.#store.readdir(this.root);
-    } catch (error) {
-    }
-    if (files && files.length > 0) throw new Error('Cannot create an OCFL Object in a non-empty directory');
-    //create the namaste file
-    let filePath = path.join(this.root, NAMASTE_T + prefix + this.ocflVersion);
-    await this.#store.writeFile(filePath, prefix + this.ocflVersion + '\n', 'utf8');
-  }
-
-  /**
-   * Read and parse the inventory.json file
-   * @param {string} [version] - Full name of the version, eg: v1, v2, v3 
-   * @returns {Promise<OcflObjectInventory>}
-   */
-  async _readInventory(version = 'latest') {
-    let invPath = version === 'latest' ? INVENTORY_NAME : path.join(version, INVENTORY_NAME);
-    let datastr;
-    try {
-      datastr = /** @type string */(await this.readFile(invPath, 'utf8'));
-    } catch (err) {
-      if (err.code !== 'ENOENT') throw err;
-      //inventory does not exist yet
-      return;
-    }
-    let data = /** @type Inventory */(JSON.parse(datastr));
-    let [digest, actualDigest] = /** @type [string,string] */ (await Promise.all([
-      this.readFile(invPath + '.' + data.digestAlgorithm, 'utf8'),
-      OcflDigest.digest(data.digestAlgorithm, datastr)
-    ]));
-    digest = digest.match(/[^\s]+/)?.[0];
-    if (digest !== actualDigest) throw new Error(`Inventory file ${this.root}/${invPath} digest mismatch: recorded=${digest} actual=${actualDigest}`);
-    //return new OcflObjectInventory({ data, digest });
-    return new OcflObjectInventory(data);
-  }
-
-  /**
-   * Set the latest version of inventory in the cache
-   * @param {*} inventory 
-   * @param {*} version 
-   */
-  _setInventory(inventory, version = 'latest') {
-    //this._inventory['latest'] = this._inventory[inventory.head] = inventory;
-    this._inventory[version] = inventory;
-    if (version === 'latest') this._inventory[inventory.head] = inventory;
-  }
-
-  // all the parent directories cannot be an ocfl object
-  async _validateObjectPath() {
-    var p = this.root;
-    while (p !== '.' && p !== '/') {
-      p = path.dirname(p);
-      let nv = await findNamasteVersion(this.#store, NAMASTE_PREFIX_OBJECT, p);
-      if (nv) throw new Error(`Object root cannot be nested under another object ${p}`);
-    }
-  }
-
-  /**
-   * If a cache exists, return the cached inventory. Otherwise read it from the storage and cache it.
-   * If the inventory file does not exist, eg in a newly created object, returns undefined. 
-   * @param {string} [version] - Full name of the version, eg: v1, v2, v3  
-   * @returns {Promise<OcflObjectInventory>}
-   */
-  async getInventory(version = 'latest') {
-    if (!this._inventory[version]) {
-      let inv = await this._readInventory(version);
-      if (inv) this._setInventory(inv, version);
-    }
-    return this._inventory[version];
-  }
-
-  _baseInventory() {
-    return {
-      id: this.id,
-      digestAlgorithm: this.digestAlgorithm || 'sha512',
-      type: /** @type {Inventory["type"]} */(`https://ocfl.io/${this.ocflVersion}/spec/#inventory`),
-      contentDirectory: this.contentDirectory || 'content'
-    };
-  }
-
-  /**
-   * Update the content files or directories as one transaction and commit the changes as a new version.
-   * After obtaining the OcflObjectTransaction instance, make sure to either call the
-   * {@link OcflObjectTransaction#commit} or {@link OcflObjectTransaction#rollback} method to complete the transaction.
-   * If callback function `cb` is provided, all update operations can be done in the callback function
-   * and all changes are automatically commited at the end of the function.
-   * @param {function(OcflObjectTransaction):Promise<*>} [updater]
-   * @param {UpdateMode} [mode_]
-   * @return {Promise<?OcflObjectTransaction>}
-   */
-  async update(updater, mode_ = UPDATE_MODE.MERGE) {
-    const mode = enumeration.of(UPDATE_MODE, mode_);
-    if (!mode) throw new TypeError(`Invalid mode '${mode.toString()}'`);
-    const inv = await this.getInventory() ?? this._baseInventory();
-    const newInv = await OcflObjectInventory.newVersion(inv, mode === UPDATE_MODE.REPLACE);
-    const t = await this.#createTransaction(newInv);
-    if (typeof updater === 'function') {
-      try {
-        await updater(t);
-      } catch (error) {
-        // console.log(error);
-        await t.rollback();
-        throw error;
-      }
-      await t.commit();
-      return;
-    }
-    return t;
-  }
-
-
-  /**
-   * Import one or more content files or directories to the object 
-   * in one transaction and commit the changes as a new version. 
-   * Use this method to simplify copying all contents of a directory 
-   * in local filesystem to the OCFL Object content directory
-   * @param {string|string[]|string[][]} content - The source path(s) or an array of a tuple [source, logical path]
-   * @param {UpdateMode} [mode=UPDATE_MODE.MERGE] - Update mode.
-   */
-  async import(content, mode = UPDATE_MODE.MERGE) {
-    //let entries = /**@type {string[][]}*/(content);
-    if (typeof content === 'string') content = [[content, '']];
-    //else if (typeof content[0] === 'string') entries = /**@type {string[]}*/(content).map(src => [src, '']);
-
-    await this.update(async (t) => {
-      let res = await parallelize(/**@type {string[][]}*/(content), async (p) => {
-        if (typeof p === 'string') p = [p, ''];
-        let [source, target] = p;
-        return t.import(source, target);
-      });
-      let errors = [];
-      for (let i = 0; i < res.length; ++i) {
-        if (res[i] instanceof Error) errors.push(content[i][0]);
-      }
-      if (errors.length) {
-        let msg = "Cannot add the files: " + errors.join(', ');
-        throw new Error(msg);
-      }
-    }, mode);
-  }
-
-  /**
-   * Alias for import
-   * @see {@link OcflObject.import}
-   */
-  async add(sourceDir, mode = UPDATE_MODE.MERGE) {
-    await this.import(sourceDir, mode);
-  }
-
-  /**
-   * Count the number of files contained in this object
-   * @param {string} [version]
-   */
-  async count(version) {
-    let inv = await this.getInventory();
-    return [...inv.files(version)].length;
-  }
-
-  async createReadable(filePath, options) {
-    return this.#store.createReadable(path.join(this.root, filePath), options);
-  }
-
-  /**
-   * Check if the object root path points to an existing file or non-empty directory
-   * in the underlying backend store.
-   * The existing directory may or may not be a valid OCFL Object.
-   * @return {Promise<boolean>}
-   */
-  async exists() {
-    return !(await isDirEmpty(this.#store, this.root));
-  }
-
-  /**
-   * Copy all content of this Object to a directory in local filesystem
-   * @param {string} targetDir 
-   * @param {string} version 
-   */
-  async export(targetDir, version) { throw new Error('Not Implemented'); }
-
-  /**
-   * Iterate through the content files contained in the specified version. 
-   * Returns an Iterator that contains FileRef which consists of logical path, content path, and digest, in no particular order.
-   * The iterator is implemented as a generator.
-   * @param {string} [version]
-   * @return {Promise<Generator<OcflObjectFile, void, unknown>>}
-   */
-  async files(version) {
-    let inv = await this.getInventory();
-    let o = this;
-    function* files() {
-      for (const f of inv.files(version)) {
-        yield new OcflObjectFile(o, f);
-      }
-    }
-    return files();
-  }
-
-  /**
-   * Return a file representation by the content path and version,
-   * @param { string } contentPath 
-   * @param { string } [version='latest']
-   */
-  async fileByContentPath(contentPath, version) {
-    const inv = await this.getInventory();
-    const fr = inv?.getFileByContentPath(contentPath, version);
-    if (fr) return new OcflObjectFile(this, fr);
-  };
-
-  /**
-   * Return a file representation by the digest and version,
-   * @param { string } digest 
-   * @param { string } [version='latest']
-   */
-  async fileByDigest(digest, version) {
-    const inv = await this.getInventory();
-    const fr = inv?.getFileByDigest(digest, version);
-    if (fr) return new OcflObjectFile(this, fr);
-  };
-
-  /**
-   * Return a file representation by the logical path and version,
-   * @param { string } logicalPath 
-   * @param { string } [version='latest']
-   */
-  async fileByLogicalPath(logicalPath, version) {
-    const inv = await this.getInventory();
-    const fr = inv?.getFile(logicalPath, version);
-    if (fr) return new OcflObjectFile(this, fr);
-  };
-
-  /**
-   * Return a file representation by either the [logical path and version], digest, or content path. 
-   * The returned file object can be used to retrieve the content of a file either as string, buffer, or stream.
-   * If the object inventory file is not loaded, this file object will not include the full file metadata information.
-   * If version is omitted, it defaults to the last version.
-   * @param { LogicalPath | FileRefLogical | FileRefDigest | FileRefContent } opt A choice of logical path (eg: 'test') and version (eg: 'v1'), 
-   * digest of the file content, or content path (eg: 'v1/content/test')
-   * @param {string} [version='latest'] The object version name, eg: 'v1', 'v2'. Default to 'latest'. Only used if opt is a LogicalPath.
-   * @param {string} [lazy] If true, always return a file instance even if the object inventory file is not loaded.
-   */
-  getFile(opt, version, lazy) {
-    const inv = this.inventory;
-    /** @type {any} */
-    const file = typeof opt === 'string' ? { logicalPath: opt, version: version } : { ...opt };
-    if (inv) {
-      let fr;
-      if (file.logicalPath) {
-        fr = inv?.getFile(file.logicalPath, file.version);
-      } else if (file.digest) {
-        fr = inv?.getFileByDigest(file.digest, file.version);
-      } else if (file.contentPath) {
-        fr = inv?.getFileByContentPath(file.contentPath, file.version);
-      }
-      if (fr) return new OcflObjectFile(this, fr);
-    } else if (lazy) {
-      return new OcflObjectFile(this, file);
-    }
-  };
-
-  /**
-   * Return the latest version of the cached data from inventory.json which can be read using {@link getInventory()}
-   */
-  get inventory() {
-    return this._inventory.latest;
-  }
-
-  /** 
-   * Reads the object inventory file and cache it in the memory.
-   * Optionally, preloads and reads all files metadata from the underlying storage.
-   * @param {object} [options]
-   * @param {boolean} [options.filesMetadata] Whether to read file metadata from the underlying storage.
-   */
-  async load({ filesMetadata } = {}) {
-    this._inventory = {}; // reset inventory cache
-    const inv = await this.getInventory();
-    //await this.loadExtensions();
-    if (inv && filesMetadata) {
-      //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()
-        }
-      }
-    }
-  }
-
-  /** 
-   * Read the content of a file inside an object.
-   * @param {string} relPath - The file path relative to the object root.
-   * @param {*} options - Options to be passed to the underlying method
-   */
-  async readFile(relPath, options) {
-    return this.#store.readFile(path.join(this.root, relPath), options);
-  };
-
-  /** 
-   * Get the file metadata such as size and modification time.
-   * @param {string} relPath - The file path relative to the object root.
-   */
-  async stat(relPath) {
-    return this.#store.stat(path.join(this.root, relPath));
-  };
-
-  toString() { return `OcflObject { root: ${this.root}, id: ${this.id} }`; }
-
-  toJSON() { return { root: this.root, id: this.id }; }
-
-
-}
-
-
-/**
- * @implements {OcflObject}
- */
-class OcflObjectImpl extends OcflObject {
-
-  // async _resolveContentPath({ logicalPath = '', contentPath = '', digest = '', version = '' }) {
-  //   if (!contentPath) {
-  //     let inv = await this.getInventory();
-  //     version = version && version !== 'latest' ? version : inv.head;
-  //     contentPath = inv.getContentPath(digest || inv.getDigest(logicalPath, version));
-  //   }
-  //   return contentPath;
-  // }
-
-  async isObject(aPath) { }
-  static status(rootPath) { }
-  static exists(rootPath) { }
-
-  /**
-   * Validate this object
-   * @abstract
-   */
-  async validate() { throw new Error('Not Implemented'); }
-  async verify() { return this.validate(); }
-
-};
-
-
-module.exports = {
-  OcflObject,
-  OcflObjectInventory,
-  //OcflObjectTransaction,
-  OcflObjectTransactionImpl
-};