@ocfl/ocfl 0.1.0

package/README.md

@@ -0,0 +1,16 @@
+# ocfl-js - Common modules
+This is JavaScript/Node.js library to create and interact with Oxford Common File Layout (OCFL) storage and objects within it. 
+This package contains abstract classes definition. Do not use this package directly. To work with an actual OCFL storage and object, use the following concrete implementation:
+* ocfl-fs - File system storage backend
+
+## Extensions
+This library by default includes all the community extensions defined in the [OCFL Community Extensions page](https://github.com/OCFL/extensions). The implementation is organised in the ocfl-extensions package. 
+
+To implement a local extension in this library, first follow the description in that page, then create a function like in the following example:
+
+    const ocfl = require(ocfl-fs);
+    ocfl.extensions['9999-local-test'] = function (Storage, Object) {
+
+       
+    }
+

package/index.js

@@ -0,0 +1,131 @@
+/**
+ * @module ocfl
+ */
+
+const { OcflConstants, OcflDigest, OcflExtension, OcflStorageLayout, OcflStore,
+  OcflObject, OcflObjectImpl,
+  OcflObjectInventory, OcflObjectTransactionImpl,
+  OcflStorage, OcflStorageImpl,
+  createObjectProxy, createTransactionProxy,
+  extensions
+} = require('./lib/index.js');
+
+// const { FlatDirectStorageLayout,
+//   FlatOmitPrefixStorageLayout,
+//   HashAndIdNTupleStorageLayout,
+//   HashedNTupleStorageLayout,
+//   NTupleOmitPrefixStorageLayout } = extensions;
+
+/** @typedef {import('./lib/object.js').OcflObjectConfig} OcflObjectConfig */
+/** @typedef {import('./lib/storage.js').OcflStorageConfig} OcflStorageConfig */
+
+/**
+ * @typedef {Object} StorageLayout
+ * @property {typeof extensions.FlatDirectStorageLayout} [FlatDirectStorageLayout]
+ * @property {typeof extensions.FlatOmitPrefixStorageLayout} [FlatOmitPrefixStorageLayout]
+ * @property {typeof extensions.HashAndIdNTupleStorageLayout} [HashAndIdNTupleStorageLayout]
+ * @property {typeof extensions.HashedNTupleStorageLayout} [HashedNTupleStorageLayout]
+ * @property {typeof extensions.NTupleOmitPrefixStorageLayout} [NTupleOmitPrefixStorageLayout]
+ */
+/** @typedef {import('./lib/extension.js').OcflExtensionConfig} OcflExtensionConfig */
+
+/**
+ * Create a storage layout from extension name or config
+ * @param {string|OcflExtensionConfig} config - Layout name or config
+ */
+function layout(config) {
+  let name, c;
+  if (typeof config === 'string') {
+    name = config;
+  } else {
+    name = config.extensionName;
+    c = config;
+  }
+  return OcflStorageLayout.class(name).create(c);
+}
+let storageLayout = Object.assign(layout, /** @type {StorageLayout} */(OcflStorageLayout.layout))
+
+
+/**
+ * Top level OCFL API interface that provides storage and object creation.
+ * Any backend store implementation module must return the instance of this class. 
+ * @template SO
+ */
+class Ocfl {
+  #store;
+  #defaultOptions;
+
+  /**
+   * @param {typeof OcflStore} store 
+   * @param {SO} defaultOptions
+   */
+  constructor(store, defaultOptions) {
+    this.#store = store;
+    this.#defaultOptions = defaultOptions;
+  }
+
+  get OCFL_VERSIONS() { return OcflConstants.OCFL_VERSIONS; }
+
+  /** 
+   * Built-in storage layout classes
+   * @return {StorageLayout} 
+   */
+  get StorageLayout() { return OcflStorageLayout.layout }
+
+  /**
+   * Create a storage layout from extension name or config
+   * @param {string|OcflExtensionConfig} config - Layout name or config
+   */
+  storageLayout(config) {
+    let name, c;
+    if (typeof config === 'string') {
+      name = config;
+    } else {
+      name = config.extensionName;
+      c = config;
+    }
+    let cls = OcflStorageLayout.class(name)
+    if (!cls) throw new Error(`Layout "${name}" is not supported.`);
+    return cls.create(c);
+  }
+
+  /**
+   * Create an OCFL Object
+   * @param {OcflObjectConfig} config
+   * @param {SO} [storeOptions]
+   * @return {OcflObject}
+   */
+  object(config, storeOptions = this.#defaultOptions) {
+    return new OcflObjectImpl(config, this.#store.getInstance(storeOptions));
+  }
+
+  /**
+   * Create an OCFL Storage
+   * @param {OcflStorageConfig} config
+   * @param {SO} [storeOptions]
+   * @return {OcflStorage}
+   */
+  storage(config, storeOptions = this.#defaultOptions) {
+    return new OcflStorageImpl(config, this.#store.getInstance(storeOptions));
+  }
+}
+
+module.exports = {
+  OcflConstants,
+  OcflDigest,
+  OcflExtension, OcflStorageLayout,
+  OcflStore,
+  OcflObject,
+  OcflObjectImpl,
+  OcflObjectInventory,
+  OcflObjectTransactionImpl,
+  createObjectProxy,
+  createTransactionProxy,
+  OcflStorage, OcflStorageImpl,
+  Ocfl,
+  extensions
+};
+
+for (let name in extensions) {
+  extensions[name].register();
+}

package/index.mjs

@@ -0,0 +1,18 @@
+//@ts-check
+// export * from './lib/storage.js'; 
+// export * from './lib/object.js'; 
+// export * from './lib/digest.js'; 
+//export * from './lib/extension.js'; 
+//export * from './lib/constants.js'; 
+
+export * from './index.js'; 
+import ocfl from './index.js';
+export default ocfl;
+//export const { DIGEST, DIGEST_FIXITY, INVENTORY_NAME, NAMASTE_PREFIX_OBJECT, NAMASTE_PREFIX_STORAGE, OCFL_VERSION } = ocfl
+// export const { OcflObject, OcflObjectImpl, OcflObjectInventory, OcflObjectTransaction, OcflObjectTransactionImpl,
+//   OcflStorage, OcflStorageImpl,
+//   createProxy, digestFrom, digestFromFile, digestFromStream, 
+//   DIGEST, DIGEST_FIXITY, INVENTORY_NAME, NAMASTE_PREFIX_OBJECT, NAMASTE_PREFIX_STORAGE, OCFL_VERSION } = ocfl;
+//export const {} = ocfl;
+//export { default as ocfl } from './index.js';
+//export {Storage, Object} from './index.js';

package/lib/constants.js

@@ -0,0 +1,24 @@
+/**
+ * @module
+ * default constants 
+ */
+// module.exports = {
+//   OCFL_VERSION: 1.1,
+//   NAMASTE_PREFIX_OBJECT: '0=ocfl_object_',
+//   NAMASTE_PREFIX_STORAGE: '0=ocfl_',
+//   INVENTORY_NAME: 'inventory.json'
+// };
+const OcflConstants = {
+  OCFL_VERSION: '1.1',
+  OCFL_VERSIONS: Object.freeze(['1.1', '1.0']),
+  OCFL_LAYOUT: 'ocfl_layout.json',
+  NAMASTE_T: '0=',
+  NAMASTE_PREFIX_OBJECT: 'ocfl_object_',
+  NAMASTE_PREFIX_STORAGE: 'ocfl_',
+  INVENTORY_NAME: 'inventory.json',
+  EXTENSIONS_DIR: 'extensions',
+  EXTENSION_CONFIG: 'config.json',
+  DIGEST_ALGORITHM: 'sha512'
+};
+
+module.exports = { OcflConstants };

package/lib/digest.js

@@ -0,0 +1,138 @@
+//@ts-check
+
+//const hasha = require("hasha");
+const crypto = require("crypto");
+const fs = require("fs");
+const stream = require("stream/promises");
+//const worker = require('node:worker_threads');
+const { Enum } = require('./enum.js');
+const { Transform } = require('stream');
+
+/**
+ */
+class CONTENT extends Enum {
+  static sha256 = new this('sha256');
+  static sha512 = new this('sha512');
+};
+
+class FIXITY extends Enum {
+  static sha256 = new this('sha256');
+  static sha512 = new this('sha512');
+  static md5 = new this('md5');
+  static sha1 = new this('sha1');
+  static blake2b512 = new this('blake2b-512');
+};
+
+/**
+ * A pass through stream that pass data as it is and calculate the digest as data pass through.
+ */
+class HashThrough extends Transform {
+  constructor(hash, streamOptions) {
+    super(streamOptions);
+    this.hash = hash;
+  }
+  _transform(chunk, encoding, cb) {
+    try {
+      this.hash.update(chunk, encoding);
+      cb(null, chunk);
+    } catch (err) {
+      cb(err)
+    }
+  }
+  digest(encoding) {
+    return this.hash.digest(encoding || 'hex');
+  }
+}
+
+/**
+ * @type { Object.<string, function():crypto.Hash>}
+ */
+let algorithms = {};
+for (let algo of FIXITY) {
+  algorithms[algo.value] = function () { return crypto.createHash(algo.name); }
+}
+
+/**
+ * 
+ * @param {string} algorithm 
+ */
+function createStream(algorithm) {
+  const hash = algorithms[algorithm || 'sha512']();
+  hash.setEncoding('hex');
+  return hash;
+}
+
+/**
+ * 
+ * @param {string} algorithm 
+ */
+function createStreamThrough(algorithm, options) {
+  const hash = algorithms[algorithm || 'sha512']();
+  hash.setEncoding('hex');
+  return new HashThrough(hash, options);
+}
+
+/**
+ * 
+ * @param {string} algorithm 
+ * @param {Buffer | string | Array<Buffer | string>} input 
+ * @return {string}
+ */
+function digestSync(algorithm, input) {
+  const hash = algorithms[algorithm || 'sha512']();
+  let inputs = Array.isArray(input) ? input : [input];
+  for (let chunk of inputs) {
+    hash.update(chunk);
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * 
+ * @param {string} algorithm 
+ * @param {Buffer | string | Array<Buffer | string>} input 
+ */
+async function digestAsync(algorithm, input) {
+  return digestSync(algorithm, input);
+}
+
+/**
+ * 
+ * @param {string} algorithm 
+ * @param {NodeJS.ReadableStream} input 
+ */
+async function digestFromStream(algorithm, input) {
+  let hash = algorithms[algorithm]();
+  await stream.pipeline(input, hash);
+  return hash.digest('hex');
+}
+
+/**
+ * 
+ * @param {string} algorithm 
+ * @param {string} filePath 
+ */
+async function digestFromFile(algorithm, filePath) {
+  return await digestFromStream(algorithm, fs.createReadStream(filePath));
+}
+
+const OcflDigest = {
+  CONTENT,
+  FIXITY,
+  algorithms,
+  createStream, createStreamThrough,
+  digestAsync, digestSync,
+  digestFromStream, digestFromFile
+};
+
+module.exports = {
+  OcflDigest
+  // DIGEST,
+  // DIGEST_FIXITY,
+  // digestSync,
+  // digestAsync,
+  // digestFromStream,
+  // digestFromFile,
+  // digestStream,
+  // HashThrough
+};

package/lib/enum.js

@@ -0,0 +1,92 @@
+/**
+ * Enumeration tool for working with a set of options 
+ * @module enum
+ */
+
+/**
+ * Create enumeration type by extending the Enum class and 
+ * defining the name and value of each constant as static fields.
+ * @template V
+ */
+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];
+    }
+  }
+
+  /**
+   * 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;
+    }
+    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) ?? [] });
+    }
+    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;
+  }
+
+  get value() {
+    return this.#value ?? this.name;
+  }
+
+  toString() {
+    return this.value?.toString();
+  }
+
+}
+module.exports = { Enum };

package/lib/error.js

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,206 @@
+//const {} = require('./object');
+//const digest = require('./digest');
+
+const { NotImplementedError } = require("./error");
+
+/** Index by Registered extension name */
+const extensionByName = {};
+/** Index by extension class name */
+const extensionByClassName = {};
+/** @type {Object.<string, typeof OcflStorageLayout>} */
+const storageLayout = {};
+
+/** @typedef {{ extensionName?: string;[key: string]: any; }} OcflExtensionConfig */
+
+// class OcflExtensionConfig {
+//   /** User defined config */
+//   definedConfig;
+//   constructor(config) {
+//     this.definedConfig = config;
+//   }
+  
+// }
+
+/**
+ * @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'));
+  }
+
+  /**
+   * @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>}
+   */
+  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 setup(ocfl) { };
+  static get NAME() { return '0000-example-extension' }
+  static get DESCRIPTION() { return 'Example extension' }
+
+  /**
+   * 
+   * @param {OcflExtensionConfig} [config]
+   * @param {C} [defaultConfig]
+   */
+  constructor(config, defaultConfig) {
+    /** @type {C} */
+    this.parameters = defaultConfig ? 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 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); }
+
+  /**
+   * 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/0001-digest-algorithms.js

@@ -0,0 +1,41 @@
+//@ts-check
+
+const {OcflExtension} = require("../extension");
+const crypto = require('crypto');
+const blake2 = require('blake2');
+
+class DigestAlgorithm extends OcflExtension {
+  static get NAME() { return '0001-digest-algorithms' }
+
+  // static create() {
+  //   if (!instance) instance = new DigestAlgorithm();
+  //   return instance;
+  // }
+  /**
+   * 
+   * @param {import('ocfl')} ocfl 
+   */
+  static setup(ocfl) {
+    let {OcflDigest} = ocfl;
+    let { FIXITY } = OcflDigest;
+    class FIXITY_EX extends FIXITY {
+      static blake2b160 = new this('blake2b-160');
+      static blake2b256 = new this('blake2b-256');
+      static blake2b384 = new this('blake2b-384');
+      static ['sha512-256'] = new this('sha512/256');
+    };
+    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}); 
+      }
+    }
+    OcflDigest.algorithms['sha512/256'] = function() { 
+      return crypto.createHash('sha512-256'); 
+    }
+    //console.log(OcflDigest.algorithms);
+  }
+}
+
+module.exports = { DigestAlgorithm };