@ocfl/ocfl 0.2.2 → 0.4.0

package/lib/enum.js

@@ -1,92 +1,90 @@
 /**
  * Enumeration tool for working with a set of options 
- * @module enum
+ * @module enumeration
  */
 
+// const COLOR = (c => {
+//   let r = /** @type {{[key in (typeof c)[number]]: string}} */({});
+//   return r;
+// })(/** @type {const} */(['red', 'green', 'blue']));
+// COLOR.blue
+const constantsSymbol = Symbol('constants');
+
 /**
- * Create enumeration type by extending the Enum class and 
- * defining the name and value of each constant as static fields.
- * @template V
+ * Create enumeration type by passing the list of constants as arguments of string
+ * @template {readonly string[]} const T
+ * @param {T} constants
  */
-class Enum {
-  /** @type {string} */
-  #name;
-  /** @type {V} */
-  #value;
 
-  /**
-   * Return an existing constant that represents the specified value
-   * @type {<T extends typeof Enum>(this: T, value: any) => InstanceType<T>}
-   */
-  static of = function (value, c=this) {
-    //if (value instanceof c) return value;
-    for (let name in c) {
-      if (c[name].value === value) return c[name];
+function enumeration(constants) {
+  class Enum {
+    /** @type {string} */
+    #name;
+    /** @type {number} */
+    #ordinal;
+    constructor(name, ordinal) {
+      this.#name = name;
+      this.#ordinal = ordinal;
+      //Object.defineProperty(this, 'name', { writable: false, enumerable: true, value: name });
+      //Object.defineProperty(this, 'ordinal', { writable: false, enumerable: true, value: ordinal });
     }
-  }
-
-  /**
-   * Check if the Enum type contains an Enum instance
-   * @param {Enum} instance 
-   */
-  static has(instance) {
-    for (let name in this) {
-      if (this[name] === instance) return true;
+    get name() { return this.#name }
+    get ordinal() { return this.#ordinal }
+    toString() {
+      return this.name;
     }
-    return false;
-  }
-
-  static ofOrdinal(index, c=this) {
-    return c['_enums'][index];
-  }
-
-  static freeze(c=this) {
-    return Object.freeze(c);
-  }
-
-  static size(c=this) {
-    return c['_enums'].length;
-  }
-
-  static [Symbol.iterator]() {
-    return this['_enums'][Symbol.iterator]();
-  }
-
-  /** 
-   * @param {V} [value]
-   */
-  constructor(value) {
-    let c = this.constructor;
-    if (!Object.hasOwn(c, '_enums')) {
-      let p = Object.getPrototypeOf(c);
-      Object.defineProperty(c, '_enums', { value: p['_enums']?.slice(0) ?? [] });
+    /** @returns {Iterator<string>} */
+    static [Symbol.iterator]() {
+      return this[constantsSymbol][Symbol.iterator]();
     }
-    this.#value = value;
-    this.ordinal = c['_enums'].length;
-    c['_enums'].push(this);
-    Object.freeze(this);
   }
-
-  get name() {
-    if (!this.#name) {
-      let ec = this.constructor;
-      for (let key in ec) {
-        if (ec[key] === this) {
-          this.#name = key;
-          break;
-        }
-      }
-    }
-    return this.#name;
+  /** @typedef { typeof Enum & {[key in T[number]]: Enum} } EnumType */
+  let count = 0;
+  for (let c of constants) {
+    Object.defineProperty(Enum, c, {
+      value: Object.freeze(new Enum(c, count++)),
+      writable: false,
+      enumerable: true
+    });
   }
+  Object.defineProperty(Enum, constantsSymbol, {
+    value: constants,
+    writable: false,
+    enumerable: false
+  });
+  return /** @type {EnumType} */(Object.freeze(Enum));
+}
 
-  get value() {
-    return this.#value ?? this.name;
+/**
+ * Return an existing constant that represents the specified value
+ * @type {{<T extends abstract new() => any>(type: T, value: any): InstanceType<T>}}
+ */
+enumeration.of = function (type, value) {
+  if (value instanceof type && type[value.name]) return value;
+  else if (typeof value === 'string') {
+    return type[/**@type {string}*/(value)] || (() => {
+      for (let name in type) {
+        if (name.toUpperCase() === value.toUpperCase()) return type[name];
+      }
+    })();
   }
+}
 
-  toString() {
-    return this.value?.toString();
-  }
+/**
+ * Return an existing constant based on the index
+ * @template T
+ * @param {new() => T} type
+ * @param {number} index
+ * @return {T}
+ */
+enumeration.at = function (type, index) {
+  return type[type[constantsSymbol][index]];
+}
 
+enumeration.size = function (type) {
+  return type[constantsSymbol].length;
 }
-module.exports = { Enum };
+
+exports.enumeration = enumeration;
+exports.default = { ...enumeration };
+//export default { ...enumeration };

package/lib/extension.js

@@ -1,6 +1,3 @@
-//const {} = require('./object');
-//const digest = require('./digest');
-
 const { NotImplementedError } = require("./error");
 
 /** Index by Registered extension name */
@@ -10,8 +7,6 @@ const extensionByClassName = {};
 
 const storageLayout = {};
 
-/** @typedef {{ extensionName?: string;[key: string]: any; }} OcflExtensionConfig */
-
 // class OcflExtensionConfig {
 //   /** User defined config */
 //   definedConfig;
@@ -20,6 +15,7 @@ const storageLayout = {};
 //   }
   
 // }
+/** @typedef {import('../index.js').StorageLayout} StorageLayout */
 
 /**
  * @template {{}} C
@@ -76,16 +72,6 @@ class OcflExtension {
     extensionClass.setup(require('./index.js'));
   }
 
-  /**
-   * @template {typeof OcflExtension} T
-   * @param {OcflExtensionConfig} [config]
-   * @this {T}
-   * @return {InstanceType<T>}
-   */
-   static create2(config){
-    if (!config?.extensionName || this.NAME === config.extensionName) return /**@type {InstanceType<T>}*/(new this(config));
-    return OcflExtension.class(config.extensionName).create2(config);
-  }
   /**
    * Create an instance of the extension
    * @type {<T extends typeof OcflExtension>(this: T, config?: OcflExtensionConfig) => InstanceType<T>}
@@ -99,9 +85,9 @@ class OcflExtension {
 
   static get forObject() { return false; }
   static get forStorage() { return false; }
-  static async setup(ocfl) { };
   static get NAME() { return '0000-example-extension' }
   static get DESCRIPTION() { return 'Example extension' }
+  static async setup(ocfl) { };
 
   /**
    * 
@@ -192,6 +178,8 @@ class OcflStorageLayout extends OcflExtension {
    */
   constructor(config, defaultConfig) { super(config, defaultConfig); }
 
+  async validate() {}
+
   /**
    * Map an object identifier to a path
    * @param {string} id - The identifier of the OCFL Object

package/lib/extensions/0003-hash-and-id-n-tuple-storage-layout.js

@@ -1,5 +1,6 @@
 const { OcflStorageLayout } = require("../extension");
 const { OcflDigest } = require("../digest");
+const { enumeration } = require("../enum");
 const path = require("path");
 
 function encodeIdentifier(id) {
@@ -31,10 +32,11 @@ class HashAndIdNTupleStorageLayout extends OcflStorageLayout {
   constructor(config) {
     super(config, DefaultConfig);
     let c = this.parameters;
-    if (!OcflDigest.FIXITY.of(c.digestAlgorithm)) throw new Error('Invalid digestAlgorithm');
-    let digest = OcflDigest.digestSync(c.digestAlgorithm, 'test');
+    const algo = enumeration.of(OcflDigest.FIXITY, c.digestAlgorithm)?.name;
+    if (!algo) throw new Error('Invalid digestAlgorithm');
+    let digestLength = OcflDigest.getHexDigestLength(algo);
     let p = c.numberOfTuples * c.tupleSize
-    if (p > digest.length) throw new Error('Product of numberOfTuples and tupleSize is greater than the number of characters in the hex encoded digest.');
+    if (p > digestLength) throw new Error('Product of numberOfTuples and tupleSize is greater than the number of characters in the hex encoded digest.');
   }
 
   /**

package/lib/extensions/0004-hashed-n-tuple-storage-layout.js

@@ -1,6 +1,7 @@
 const { OcflStorageLayout } = require("../extension");
 const { OcflDigest } = require("../digest");
 const path = require("path");
+const { enumeration } = require("../enum");
 
 const DefaultConfig = {
   extensionName: '0004-hashed-n-tuple-storage-layout',
@@ -28,11 +29,12 @@ class HashedNTupleStorageLayout extends OcflStorageLayout {
   constructor(config) {
     super(config, DefaultConfig);
     let c = this.parameters;
-    if (!OcflDigest.FIXITY.of(c.digestAlgorithm)) throw new Error('Invalid digestAlgorithm');
-    let digest = OcflDigest.digestSync(c.digestAlgorithm, 'test');
+    const algo = enumeration.of(OcflDigest.FIXITY, c.digestAlgorithm)?.name;
+    if (!algo) throw new Error('Invalid digestAlgorithm');
+    let digestLength = OcflDigest.getHexDigestLength(algo);
     let p = c.numberOfTuples * c.tupleSize
-    if (p > digest.length) throw new Error('Product of numberOfTuples and tupleSize is greater than the number of characters in the hex encoded digest.');
-    else if (p === digest.length && c.shortObjectRoot) throw new Error('shortObjectRoot cannot be set to true');
+    if (p > digestLength) throw new Error('Product of numberOfTuples and tupleSize is greater than the number of characters in the hex encoded digest.');
+    else if (p === digestLength && c.shortObjectRoot) throw new Error('shortObjectRoot cannot be set to true');
   }
 
   /**

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

@@ -0,0 +1,18 @@
+//@ts-check
+
+const {OcflExtension} = require("../extension");
+
+/**
+ * Notes: this implementation does nothing because the 0009 extension is implemented directly in the OcflDigest class.
+ */
+class DigestAlgorithm extends OcflExtension {
+  static get NAME() { return '0009-digest-algorithms' }
+
+  /**
+   * 
+   * @param {import('ocfl')} ocfl 
+   */
+  static async setup(ocfl) {}
+}
+
+module.exports = { DigestAlgorithm };

package/lib/extensions/index.js

@@ -1,6 +1,6 @@
 
 module.exports = {
-  ...require('./0001-digest-algorithms'),
+  ...require('./0009-digest-algorithms'),
   ...require('./0002-flat-direct-storage-layout'),
   ...require('./0003-hash-and-id-n-tuple-storage-layout'),
   ...require('./0004-hashed-n-tuple-storage-layout'),

package/lib/file.js

@@ -0,0 +1,147 @@
+/**
+ * @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.
+ * @property {Object.<string, string>} [fixity] - Fixity information of the file.
+ */
+
+/**
+ * @typedef {Object} FileStat
+ * @property {number} [size] - Size of the file in bytes.
+ * @property {Date} [atime] - Last access time of the file.
+ * @property {Date} [mtime] - Last modified time of the file.
+ * @property {Date} [ctime] - Creation time of the file.
+ */
+
+/**
+ * Represent a file in an OCFL object
+ */
+class OcflObjectFile {
+  #ocflObject;
+  #lastModified;
+  #size;
+
+  /**
+   * 
+   * @param {import('./object').OcflObject} ocflObject 
+   * @param {FileRef} fileRef 
+   */
+  constructor(ocflObject, fileRef) {
+    this.#ocflObject = ocflObject;
+    // for (const key in ['logicalPath', 'version', 'digest', 'contentPath']) {
+    //   if (fileRef[key]) this[key] = fileRef[key];
+    // }
+    if (fileRef.logicalPath) this.logicalPath = fileRef.logicalPath;
+    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;
+    if (fileRef.fixity != null) this.fixity = fileRef.fixity;
+  }
+
+  /**
+   * Resolve contentPath given either the `logicalPath` and `version`, `digest`, or `contentPath`.
+   */
+  async #resolveContentPath() {
+    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);
+      if (!contentPath) throw new Error(`Cannot find content "${this.toString()}" in the OCFL Object "${this.#ocflObject.id}" version "${this.version || 'latest'}"`);
+    }
+    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 props = [];
+    for (const key in ['logicalPath', 'version', 'digest', 'contentPath']) {
+      if (this[key]) props.push(key + ": '" + this[key] + "'");
+    }
+    return `{ ${props.join(', ')} }`;
+  }
+
+  /**
+   * Get the file content as a buffer
+   * @param {*} [options] Options to be passed to underlying data store specific implementation
+
+   * @return {Promise<Buffer>}
+   */
+  async buffer(options) {
+    return this.#ocflObject.readFile(await this.#resolveContentPath(), options);
+  }
+
+  /**
+   * @deprecated Use {@link buffer()}
+   */
+  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 Use {@link text()}
+   */
+  async asString(encoding = 'utf8') {
+    // @ts-ignore
+    return this.text(encoding);
+  }
+
+  /**
+   * Get the file content as a NodeJS stream
+   * @param {*} [options] Options to be passed to underlying data store specific implementation
+   * @return {Promise<ReadableStream>}
+   * @deprecated Use {@link stream()}
+   */
+  async asStream(options) {
+    return this.#ocflObject.createReadable(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);
+  }
+
+  /**
+   * Get the file stat info
+   * @param {*} [options] Options to be passed to underlying data store specific implementation
+   * @return {Promise<FileStat>}
+   */
+  async stat(options) {
+    return this.#ocflObject.stat(await this.#resolveContentPath());
+  }
+
+}
+
+module.exports = {
+  OcflObjectFile
+};

package/lib/index.js

@@ -1,16 +1,4 @@
 // this is an internal index.js to avoid circular dependencies problem
-// const { OcflStorage, OcflStorageImpl } = require('./storage.js');
-// const { OcflObject,
-//   OcflObjectImpl,
-//   OcflObjectInventory,
-//   OcflObjectTransactionImpl,
-//   createObject,
-//   createObjectProxy,
-//   createTransactionProxy } = require('./object.js');
-// const { OcflConstants } = require('./constants.js');
-// const { OcflDigest } = require('./digest.js');
-// const { OcflExtension } = require('./extension.js');
-
 module.exports = {
   ...require('./constants.js'),
   ...require('./digest.js'),