@ocfl/ocfl 0.3.0 → 1.0.0-beta.1

package/lib/enum.js

@@ -1,90 +0,0 @@
-/**
- * Enumeration tool for working with a set of options 
- * @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 passing the list of constants as arguments of string
- * @template {readonly string[]} const T
- * @param {T} constants
- */
-
-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 });
-    }
-    get name() { return this.#name }
-    get ordinal() { return this.#ordinal }
-    toString() {
-      return this.name;
-    }
-    /** @returns {Iterator<string>} */
-    static [Symbol.iterator]() {
-      return this[constantsSymbol][Symbol.iterator]();
-    }
-  }
-  /** @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));
-}
-
-/**
- * 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];
-      }
-    })();
-  }
-}
-
-/**
- * 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;
-}
-
-exports.enumeration = enumeration;
-exports.default = { ...enumeration };
-//export default { ...enumeration };

package/lib/error.js

@@ -1,19 +0,0 @@
-class ValidationError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'ValidationError';
-  }
-}
-
-class NotImplementedError extends Error {
-  constructor(methodName) {
-    let msg = methodName ? 'Method ' + methodName + ' has not been implemented' : '';
-    super(msg);
-    this.name = 'NotImplementedError';
-  }
-}
-
-module.exports = {
-  ValidationError,
-  NotImplementedError
-};

package/lib/extension.js

@@ -1,194 +0,0 @@
-const { NotImplementedError } = require("./error");
-
-/** Index by Registered extension name */
-const extensionByName = {};
-/** Index by extension class name */
-const extensionByClassName = {};
-
-const storageLayout = {};
-
-// class OcflExtensionConfig {
-//   /** User defined config */
-//   definedConfig;
-//   constructor(config) {
-//     this.definedConfig = config;
-//   }
-  
-// }
-/** @typedef {import('../index.js').StorageLayout} StorageLayout */
-
-/**
- * @template {{}} C
- */
-class OcflExtension {
-  static #object = {};
-  static #storage = {};
-  
-  /**
-   * Get an object-level extension
-   * @param {string} name - A registered extension name
-   */
-  static object(name) {
-    return this.#object[name];
-  }
-  /**
-   * Get an storage-level extension
-   * @param {string} name - A registered extension name
-   */
-  static storage(name) {
-    return this.#storage[name];
-  }
-
-  /** List all registered extension classes */
-  static get classes() {
-    return Object.values(extensionByName);
-  }
-
-  /**
-   * Find a registered extension with the specified name
-   * @param {string} name - extension class name or registered extension name
-   * @return {typeof OcflExtension} - the extension class
-   */
-  static class(name) {
-    return extensionByName[name] || extensionByClassName[name];
-  }
-
-  /**
-   * Register an extension
-   * @param {typeof OcflExtension} extensionClass 
-   */
-  static register(extensionClass = this) {
-    let name = extensionClass.NAME;
-    extensionByName[name] = extensionClass;
-    extensionByClassName[extensionClass.name] = extensionClass;
-    // if (extensionClass.forObject) {
-    //   if (this.#object[name]) throw new Error(`Extension ${name} already registered.`);
-    //   this.#object[name] = extensionClass;
-    // }
-    // if (extensionClass.forStorage) {
-    //   if (this.#storage[name]) throw new Error(`Extension ${name} already registered.`);
-    //   this.#storage[name] = extensionClass;
-    // }
-    extensionClass.setup(require('./index.js'));
-  }
-
-  /**
-   * Create an instance of the extension
-   * @type {<T extends typeof OcflExtension>(this: T, config?: OcflExtensionConfig) => InstanceType<T>}
-   */
-  static create = function (config) {
-    // @ts-ignore
-    if (!config?.extensionName || this.NAME === config.extensionName) return new this(config);
-    // @ts-ignore
-    return OcflExtension.class(config.extensionName).create(config);
-  }
-
-  static get forObject() { return false; }
-  static get forStorage() { return false; }
-  static get NAME() { return '0000-example-extension' }
-  static get DESCRIPTION() { return 'Example extension' }
-  static async setup(ocfl) { };
-
-  /**
-   * 
-   * @param {OcflExtensionConfig} [config]
-   * @param {C} [defaultConfig]
-   */
-  constructor(config, defaultConfig) {
-    /** @type {C} */
-    this.parameters = typeof defaultConfig === 'object' ? Object.create(/**@type{object}*/(defaultConfig)) : {};
-    if (typeof config === 'object') {
-      for (let k in config) {
-        if (k in defaultConfig) this.parameters[k] = config[k];
-      }
-    }
-  }
-
-  /** Return all the parameters in which the value has been set to non-default value */
-  get config() {
-    let paramNames = Object.keys(this.parameters);
-    if (paramNames.length > 0) {
-      return paramNames.reduce( (params, name) => (params[name] = this.parameters[name], params), {extensionName: this.name});
-    } 
-  }
-
-  get p() { return this.parameters; }
-  
-  /** Extension registered name */
-  get name() { return /** @type {typeof OcflExtension}*/(this.constructor).NAME }
-  get description() { return /** @type {typeof OcflExtension}*/(this.constructor).DESCRIPTION }
-  get minOcflVersion() { return "1.0" }
-  get version() { return "1.0" }
-  
-  /**
-   * Get the specified parameter value
-   * @param {string} param - The extension parameter name
-   * @return {*}
-   */
-  get(param) { return this.parameters[param]; }
-  
-  /**
-   * Set the specified parameter value
-   * @param {string} param  - The extension parameter name
-   * @param {*} value - The extension parameter value
-   */
-  set(param, value) { if (param in this.parameters) this.parameters[param] = value; }
-}
-
-
-/**
- * @template {{}} C
- * @extends {OcflExtension<C>}
- */
-class OcflStorageLayout extends OcflExtension {
-
-  static get layout() {
-    return /** @type StorageLayout */(storageLayout);
-  }
-
-  /**
-   * 
-   * @param {string} name 
-   * @return {typeof OcflStorageLayout} 
-   */
-  static class(name) {
-    let c = super.class(name);
-    if (c && c.prototype instanceof OcflStorageLayout) return /** @type {typeof OcflStorageLayout} */(c);
-  }
-
-  static get classes() {
-    return Object.values(storageLayout);
-  }
-
-  /**
-   * Register a storage layout extension
-   * @param {typeof OcflStorageLayout} extensionClass 
-   */
-  static register(extensionClass = this) {
-    super.register(extensionClass);
-    storageLayout[extensionClass.name] = extensionClass;
-  }
-
-  static get forStorage() { return true; }
-
-  /**
-   * 
-   * @param {OcflExtensionConfig} [config] 
-   * @param {C} [defaultConfig]
-   */
-  constructor(config, defaultConfig) { super(config, defaultConfig); }
-
-  async validate() {}
-
-  /**
-   * Map an object identifier to a path
-   * @param {string} id - The identifier of the OCFL Object
-   * @return {string} 
-   */
-  map(id) { throw new NotImplementedError(); }
-}
-
-module.exports = {
-  OcflExtension,
-  OcflStorageLayout
-};

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

@@ -1,60 +0,0 @@
-const { OcflStorageLayout } = require("../extension");
-const { OcflDigest } = require("../digest");
-const { enumeration } = require("../enum");
-const path = require("path");
-
-function encodeIdentifier(id) {
-  return encodeURIComponent(id).toLowerCase().replace(/\./g, '%2e');
-}
-
-const DefaultConfig = {
-  extensionName: '0003-hash-and-id-n-tuple-storage-layout',
-  digestAlgorithm: 'sha256',
-  tupleSize: 3,
-  numberOfTuples: 3,
-};
-
-/**
- * @extends {OcflStorageLayout<typeof DefaultConfig>}
- */
-class HashAndIdNTupleStorageLayout extends OcflStorageLayout {
-  static get NAME() { return DefaultConfig.extensionName }
-  static get DESCRIPTION() {
-    return "OCFL object identifiers are hashed and encoded as lowercase hex strings." +
-      " These digests are then divided into N n-tuple segments," +
-      " which are used to create nested paths under the OCFL storage root." +
-      " Finally, the OCFL object identifier is percent-encoded to create a directory name for the OCFL object root.";
-  }
-
-  /**
-   * @param {Partial<typeof DefaultConfig>} [config] 
-   */
-  constructor(config) {
-    super(config, DefaultConfig);
-    let c = this.parameters;
-    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 > digestLength) throw new Error('Product of numberOfTuples and tupleSize is greater than the number of characters in the hex encoded digest.');
-  }
-
-  /**
-   * @param {string} id
-   * @return {string} 
-   */
-  map(id) {
-    let digest = OcflDigest.digestSync(this.parameters.digestAlgorithm, id);
-    let segments = [];
-    let s = this.parameters.tupleSize;
-    let n = this.parameters.numberOfTuples;
-    let i;
-    for (i = 0; i < n; ++i) {
-      segments.push(digest.slice(s * i, s * i + s));
-    }
-    segments.push(encodeIdentifier(id));
-    return segments.join(path.sep);
-  }
-}
-
-module.exports = { HashAndIdNTupleStorageLayout };

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

@@ -1,63 +0,0 @@
-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',
-  digestAlgorithm: 'sha256',
-  tupleSize: 3,
-  numberOfTuples: 3,
-  shortObjectRoot: false
-};
-/** @typedef {Partial<typeof DefaultConfig>} HashedNTupleStorageLayoutConfig */
-/**
- * @extends {OcflStorageLayout<typeof DefaultConfig>}
- */
-class HashedNTupleStorageLayout extends OcflStorageLayout {
-  static get NAME() { return DefaultConfig.extensionName; }
-  static get DESCRIPTION() {
-    return "OCFL object identifiers are hashed and encoded as lowercase hex strings." +
-      " These digests are then divided into N n-tuple segments," +
-      " which are used to create nested paths under the OCFL storage root.";
-  }
-
-  /**
-   * 
-   * @param {HashedNTupleStorageLayoutConfig} [config] 
-   */
-  constructor(config) {
-    super(config, DefaultConfig);
-    let c = this.parameters;
-    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 > 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');
-  }
-
-  /**
-   * @param {string} id
-   * @return {string} 
-   */
-  map(id) {
-    let digest = OcflDigest.digestSync(this.parameters.digestAlgorithm, id);
-    let segments = [];
-    let s = this.parameters.tupleSize;
-    let n = this.parameters.numberOfTuples;
-    let i;
-    for (i = 0; i < n; ++i) {
-      segments.push(digest.slice(s * i, s * i + s));
-    }
-    if (this.parameters.shortObjectRoot) {
-      segments.push(digest.slice(s * i));
-    } else {
-      segments.push(digest);
-    }
-    return segments.join(path.sep);
-  }
-
-}
-
-module.exports = { HashedNTupleStorageLayout };

package/lib/extensions/0006-flat-omit-prefix-storage-layout.js

@@ -1,7 +0,0 @@
-const {OcflStorageLayout} = require("../extension");
-
-class FlatOmitPrefixStorageLayout extends OcflStorageLayout {
-  static get NAME() { return '0006-flat-omit-prefix-storage-layout' }
-}
-
-module.exports = { FlatOmitPrefixStorageLayout };

package/lib/extensions/0007-n-tuple-omit-prefix-storage-layout.js

@@ -1,7 +0,0 @@
-const {OcflStorageLayout} = require("../extension");
-
-class NTupleOmitPrefixStorageLayout extends OcflStorageLayout {
-  static get NAME() { return '0007-n-tuple-omit-prefix-storage-layout' }
-}
-
-module.exports = { NTupleOmitPrefixStorageLayout };

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

@@ -1,18 +0,0 @@
-//@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/000N-path-direct-storage-layout.js

@@ -1,61 +0,0 @@
-const { OcflStorageLayout } = require("../extension");
-const { OcflDigest } = require("../digest");
-const path = require("path");
-
-const DefaultConfig = {
-  extensionName: '000N-path-direct-storage-layout',
-  omitScheme: false,
-  /** @type {any} */
-  replace: [],
-  suffix: '/__object__'
-};
-
-/** @typedef {Partial<typeof DefaultConfig>} PathDirectStorageLayoutConfig */
-/**
- * @extends {OcflStorageLayout<typeof DefaultConfig>}
- */
-class PathDirectStorageLayout extends OcflStorageLayout {
-  static get NAME() { return DefaultConfig.extensionName; }
-  static get DESCRIPTION() {
-    return "OCFL object identifiers are used directly as the path.";
-  }
-
-  /**
-   * 
-   * @param {PathDirectStorageLayoutConfig} [config] 
-   */
-  constructor(config) {
-    super(config, DefaultConfig);
-  }
-
-  /**
-   * @param {string} id
-   * @return {string} 
-   */
-  map(id) {
-    var suffix = this.parameters.suffix;
-    if (suffix && id.endsWith(suffix)) throw new Error(`Identifier cannot end with '${suffix}'`);
-    var p = id ?? '';
-    for (const r of this.parameters.replace) {
-      p = p.replace(r[0], r[1]);
-    }
-    try {
-      let u = new URL(p);
-      let parts = [];
-      if (!this.parameters.omitScheme && u.protocol !== 'file:') {
-        parts.push(u.protocol.replace(':', ''));
-      }
-      if (u.hostname) {
-        parts.push(u.hostname.replace(',', '_').replace(';', '/'));
-      }
-      p = path.join(parts.join('_'), u.pathname + u.search + u.hash);
-    } catch (error) {
-    }
-    p = p.replace(/^\/+/, '').replace(/\/+$/, '');
-    return path.join(p, this.parameters.suffix);
-    //if (/^\w+:/.test(id)) {
-  }
-
-}
-
-module.exports = { PathDirectStorageLayout };

package/lib/extensions/index.js

@@ -1,13 +0,0 @@
-
-module.exports = {
-  ...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'),
-//  ...require('./0005-mutable-head'),
-  ...require('./0006-flat-omit-prefix-storage-layout'),
-  ...require('./0007-n-tuple-omit-prefix-storage-layout'),
-  ...require('./000N-path-direct-storage-layout')
-  //...require('./0008-schema-registry')
-};
-//const { DigestAlgorithm } = require('./0001-digest-algorithms.js');

package/lib/file.js

@@ -1,129 +0,0 @@
-/**
- * @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.
- */
-
-/**
- * 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);
-  }
-}
-
-module.exports = {
-  OcflObjectFile
-};

package/lib/index.js

@@ -1,13 +0,0 @@
-// this is an internal index.js to avoid circular dependencies problem
-module.exports = {
-  ...require('./constants.js'),
-  ...require('./digest.js'),
-  ...require('./transaction.js'),
-  ...require('./extension.js'),
-  ...require('./store.js'),
-  ...require('./object.js'),
-  ...require('./storage.js'),
-  extensions: {
-    ...require('./extensions/index.js')
-  }
-};