@ocfl/ocfl 0.2.2 → 0.3.0

package/index.js

@@ -3,22 +3,11 @@
  */
 
 const { OcflConstants, OcflDigest, OcflExtension, OcflStorageLayout, OcflStore,
-  OcflObject, OcflObjectImpl,
-  OcflObjectInventory, OcflObjectTransactionImpl,
+  OcflObject, 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
@@ -28,7 +17,10 @@ const { OcflConstants, OcflDigest, OcflExtension, OcflStorageLayout, OcflStore,
  * @property {typeof extensions.NTupleOmitPrefixStorageLayout} NTupleOmitPrefixStorageLayout
  * @property {typeof extensions.PathDirectStorageLayout} PathDirectStorageLayout
  */
-/** @typedef {import('./lib/extension.js').OcflExtensionConfig} OcflExtensionConfig */
+
+/** @typedef {import('./lib/types').OcflExtensionConfig} OcflExtensionConfig */
+/** @typedef {import('./lib/types').OcflObjectConfig} OcflObjectConfig */
+/** @typedef {import('./lib/types').OcflStorageConfig} OcflStorageConfig */
 
 /**
  * Create a storage layout from extension name or config
@@ -46,106 +38,89 @@ function layout(config) {
 }
 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. 
+ * Creates a new OCFL core API with a specific backend store.
+ * Any backend store implementation module must return the result of this method. 
+ * @param {typeof OcflStore} store 
+ * @param {SO} defaultOptions
  * @template SO
+ * @returns Top level OCFL API interface that provides storage and object creation.
  */
-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 }
-
-  /**
-   * Instantiate 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;
+function implementOcfl(store, defaultOptions) {
+  return {
+    OCFL_VERSIONS: OcflConstants.OCFL_VERSIONS,
+
+    /** Built-in storage layout classes */
+    StorageLayout: OcflStorageLayout.layout,
+
+    /**
+     * Instantiate 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);
+    },
+
+    /**
+     * Instantiate an OCFL Object
+     * @param {OcflObjectConfig} config
+     * @param {SO} [storeOptions]
+     */
+    object(config, storeOptions = defaultOptions) {
+      return new OcflObject(config, store.getInstance(storeOptions));
+    },
+
+    /**
+     * Instantiate an OCFL Storage root
+     * @param {OcflStorageConfig} config
+     * @param {SO} [storeOptions]
+     * @return {OcflStorage}
+     */
+    storage(config, storeOptions = defaultOptions) {
+      return new OcflStorageImpl(config, store.getInstance(storeOptions));
+    },
+
+    /**
+     * Create a new OCFL Storage
+     * @param {OcflStorageConfig} config
+     * @param {SO} [storeOptions]
+     * @return {Promise<OcflStorage>}
+     */
+    async createStorage(config, storeOptions = defaultOptions) {
+      return (new OcflStorageImpl(config, store.getInstance(storeOptions))).create();
+    },
+
+    /**
+     * Load an existing OCFL Storage
+     * @param {OcflStorageConfig} config
+     * @param {SO} [storeOptions]
+     * @return {Promise<OcflStorage>}
+     */
+    async loadStorage(config, storeOptions = defaultOptions) {
+      return (new OcflStorageImpl(config, store.getInstance(storeOptions))).load();
     }
-    let cls = OcflStorageLayout.class(name)
-    if (!cls) throw new Error(`Layout "${name}" is not supported.`);
-    return cls.create(c);
-  }
-
-  /**
-   * Instantiate an OCFL Object object
-   * @param {OcflObjectConfig} config
-   * @param {SO} [storeOptions]
-   * @return {OcflObject}
-   */
-  object(config, storeOptions = this.#defaultOptions) {
-    return new OcflObjectImpl(config, this.#store.getInstance(storeOptions));
-  }
-
-  /**
-   * Instantiate an OCFL Storage object
-   * @param {OcflStorageConfig} config
-   * @param {SO} [storeOptions]
-   * @return {OcflStorage}
-   */
-  storage(config, storeOptions = this.#defaultOptions) {
-    return new OcflStorageImpl(config, this.#store.getInstance(storeOptions));
-  }
-
-  /**
-   * Create a new OCFL Storage
-   * @param {OcflStorageConfig} config
-   * @param {SO} [storeOptions]
-   * @return {Promise<OcflStorage>}
-   */
-  async createStorage(config, storeOptions = this.#defaultOptions) {
-    return (new OcflStorageImpl(config, this.#store.getInstance(storeOptions))).create();
-  }
-
-  /**
-   * Load an existing OCFL Storage
-   * @param {OcflStorageConfig} config
-   * @param {SO} [storeOptions]
-   * @return {Promise<OcflStorage>}
-   */
-  async loadStorage(config, storeOptions = this.#defaultOptions) {
-    return (new OcflStorageImpl(config, this.#store.getInstance(storeOptions))).load();
   }
 }
 
-
-
 module.exports = {
   OcflConstants,
   OcflDigest,
   OcflExtension, OcflStorageLayout,
   OcflStore,
   OcflObject,
-  OcflObjectImpl,
   OcflObjectInventory,
   OcflObjectTransactionImpl,
-  createObjectProxy,
-  createTransactionProxy,
   OcflStorage, OcflStorageImpl,
-  Ocfl,
+  implementOcfl,
   extensions
 };
 

package/index.mjs

@@ -6,12 +6,12 @@
 //export * from './lib/constants.js'; 
 
 export * from './index.js'; 
-import ocfl from './index.js';
+import * as 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,
+// export const { OcflObject, OcflObjectInventory, OcflObjectTransaction, OcflObjectTransactionImpl,
 //   OcflStorage, OcflStorageImpl,
-//   createProxy, digestFrom, digestFromFile, digestFromStream, 
+//   createProxy, digestFrom, 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';

package/lib/digest.js

@@ -1,139 +1,307 @@
 //@ts-check
 
-//const hasha = require("hasha");
-const crypto = require("crypto");
-const fs = require("fs");
-const stream = require("stream/promises");
+const hashWasm = require('hash-wasm');
+const { sha512_256 } = require('js-sha512'); // fallback for sha512/256 algorithm, which is not included in hash-wasm
 //const worker = require('node:worker_threads');
-const { Enum } = require('./enum.js');
-const { Transform } = require('stream');
+const { enumeration } = require('./enum.js');
+const { testSymbol } = require('./utils.js');
+
+const CONTENT = enumeration(['sha256', 'sha512']);
+const FIXITY = enumeration(['sha256', 'sha512', 'md5', 'sha1', 'blake2b-512', 'blake2b-160', 'blake2b-256', 'blake2b-384', 'sha512/256', 'size', 'crc32']);
 
 /**
+ * @typedef {((outputType: "binary") => Uint8Array) & ((outputType?: "hex") => string)} IDigest
+ * @typedef {((outputType: "binary") => {[key:string]: Uint8Array}) & ((outputType?: "hex") => {[key:string]: string})} IMultiDigest
+ * @typedef {WritableStream & { update(data: IDataType): void, digest: IDigest }} WritableStreamHasher 
+ * @typedef {WritableStream & { update(data: IDataType): void, digest: IMultiDigest }} WritableStreamMultiHasher 
  */
-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');
-};
+/** 
+ * @type { Object.<string, CommonHasher[]> }
+ */
+const hasherCache = {};
+/** 
+ * @type { Object.<string, CommonHasher> }
+ */
+const hasherSyncCache = {};
+// for (let algo of FIXITY) {
+//   algorithms[algo] = function () { return crypto.createHash(algo); }
+// }
+
+/** @type { WeakMap<CommonHasher, boolean>} */
+const hasherPending = new WeakMap();
+
+/** @type { {[key: string]: () => Promise<CommonHasher>} } */
+const hasherFactory = {};
 
 /**
- * A pass through stream that pass data as it is and calculate the digest as data pass through.
+ * Register a hash algorithm and it's factory function.
+ * @param {string} name 
+ * @param {() => Promise<CommonHasher>} factory 
  */
-class HashThrough extends Transform {
-  constructor(hash, streamOptions) {
-    super(streamOptions);
-    this.hash = hash;
+function registerHasherFactory(name, factory) {
+  if (typeof factory === 'function') {
+    hasherFactory[name] = factory;
   }
-  _transform(chunk, encoding, cb) {
-    try {
-      this.hash.update(chunk, encoding);
-      cb(null, chunk);
-    } catch (err) {
-      cb(err)
+}
+
+function hasAlgorithm(name) {
+  return name in hasherFactory;
+}
+
+(function init() {
+  for (const algo of FIXITY) {
+    if (algo.startsWith('blake2b')) {
+      const bits = parseInt(algo.split('-')[1]);
+      registerHasherFactory(algo, async () => hashWasm.createBLAKE2b(bits));
+    } else if (algo === 'sha512/256') {
+      registerHasherFactory(algo, async () => {
+        let h = sha512_256.create();
+        /** @type {CommonHasher} */
+        const hasher = {
+          digestSize: 32,
+          init() { h = sha512_256.create(); return this; },
+          update(data) { h.update(/** @type {any} */(data)); return this },
+          // @ts-ignore
+          digest(encoding) {
+            if (encoding === 'binary') return new Uint8Array(h.digest());
+            else return h.hex();
+          }
+        };
+        return hasher;
+      });
+    } else if (algo === 'size') {
+      registerHasherFactory(algo, async () => {
+        let encoder;
+        let size = 0;
+        /** @type {CommonHasher} */
+        const hasher = {
+          digestSize: 1,
+          init() {
+            size = 0;
+            encoder = new TextEncoder();
+            return this;
+          },
+          update(data) {
+            if (data) {
+              if (typeof data === 'string') size += encoder.encode(data).length;
+              else size += data.byteLength;
+            }
+            return this;
+          },
+          // @ts-ignore
+          digest(encoding) {
+            if (encoding === 'binary') return new Uint8Array(new BigUint64Array([BigInt(size)]).buffer);
+            else return '' + size;
+          }
+        };
+        return hasher;
+      });
+    } else {
+      registerHasherFactory(algo, hashWasm['create' + algo.toUpperCase()]);
     }
   }
-  digest(encoding) {
-    return this.hash.digest(encoding || 'hex');
-  }
-}
+})();
+// (async () => {
+//   for (const name in hasherFactory) {
+//     const factory = hasherFactory[name];
+//     const h = await factory();
+//     console.log(name);
+//     console.log(h);
+//     console.log(h.init().update('test').digest().length)
+//   }
+// })();
 
 /**
- * @type { Object.<string, function():crypto.Hash>}
+ * 
+ * @param {*} hasher
+ * @returns {hasher is MultiHasher}
  */
-let algorithms = {};
-for (let algo of FIXITY) {
-  algorithms[algo.value] = function () { return crypto.createHash(algo.name); }
+function isMulti(hasher) {
+  return hasher.multi;
 }
 
 /**
- * 
+ * Create a hasher instance for the given algorithm or get it from cache if available.
  * @param {string} algorithm 
  */
-function createStream(algorithm) {
-  const hash = algorithms[algorithm || 'sha512']();
-  //hash.setEncoding('hex');
+async function createHasher(algorithm) {
+  const cacheArray = hasherCache[algorithm];
+  let hash = (cacheArray ?? []).find(hasher => !hasherPending.get(hasher));
+  if (!hash) {
+    const factory = hasherFactory[algorithm];
+    if (!factory) throw new Error(`Unsupported digest algorithm: ${algorithm}`);
+    hash = await factory();
+    if (cacheArray) cacheArray.push(hash);
+    else hasherCache[algorithm] = [hash];
+  }
+  hasherPending.set(hash, true);
+  hash.init();
   return hash;
 }
 
 /**
- * 
- * @param {string} [algorithm] 
- * @param {object} [options] 
+ * Create a hasher instance for calculating multiple types of digest in one go.
+ * @param {string|string[]} algorithms 
  */
-function createStreamThrough(algorithm = 'sha512', options) {
-  const hash = algorithms[algorithm]();
-  //hash.setEncoding('hex');
-  return new HashThrough(hash, options);
+async function createMultiHasher(algorithms) {
+  const algoNames = Array.isArray(algorithms) ? (algorithms.length ? [...(new Set(algorithms))] : ['sha512']) : [algorithms];
+  const hashers = await Promise.all(algoNames.map(createHasher));
+  return /** @type { MultiHasher } */({
+    multi: true,
+    update(data) {
+      for (const hash of hashers) {
+        hash.update(data);
+      }
+      return this;
+    },
+    digest(encoding) {
+      const result = {};
+      for (let i = 0; i < hashers.length; i++) {
+        hasherPending.set(hashers[i], false);
+        result[algoNames[i]] = hashers[i].digest(encoding);
+      }
+      return result;
+    }
+  });
 }
 
 /**
- * 
- * @param {string} algorithm 
- * @param {Buffer | string | Array<Buffer | string>} input 
- * @return {string}
+ * Create a hash instance that implements WritableStream.
+ * @overload
+ * @param {string} algorithm One or more digest algorithm names
+ * @return {Promise<WritableStreamHasher>}
  */
-function digestSync(algorithm, input) {
-  const hash = algorithms[algorithm || 'sha512']();
-  let inputs = Array.isArray(input) ? input : [input];
-  for (let chunk of inputs) {
-    hash.update(chunk);
+/**
+ * @overload
+ * @param {string[]} algorithm One or more digest algorithm names
+ * @return {Promise<WritableStreamMultiHasher>}
+ */
+async function createStream(algorithm = 'sha512') {
+  const hash = await (Array.isArray(algorithm) ? createMultiHasher(algorithm) : createHasher(algorithm));
+  /** @type {any} */
+  const ws = new WritableStream({
+    write(chunk) {
+      hash.update(chunk);
+    }
+  });
+  ws.update = function (data) {
+    hash.update(data);
+  };
+  ws.digest = function (encoding) {
+    if (!isMulti(hash)) hasherPending.set(hash, false);
+    return hash.digest(encoding);
   }
-  return hash.digest('hex');
+  return ws;
 }
 
+/** @typedef {TransformStream & { digest: IMultiDigest }} StreamThroughHash */
 /**
- * 
- * @param {string} algorithm 
- * @param {Buffer | string | Array<Buffer | string>} input 
+ * Create a pass through stream that pass data as it is and calculate the digest as data pass through.
+ * @param {string|string[]} [algorithm] 
+ * @param {object} [options]
+ * @return {Promise<StreamThroughHash>}
  */
-async function digestAsync(algorithm, input) {
-  return digestSync(algorithm, input);
+async function createStreamThrough(algorithm = 'sha512', options) {
+  const hash = await (Array.isArray(algorithm) ? createMultiHasher(algorithm) : createHasher(algorithm));
+  const { writableStrategy, readableStrategy } = options || {};
+  //hash.setEncoding('hex');
+  /** @type {any} */
+  const ts = new TransformStream({
+    transform(chunk, controller) {
+      controller.enqueue(chunk);
+      hash.update(chunk);
+    }
+  }, writableStrategy, readableStrategy);
+  ts.digest = function (encoding) {
+    if (!isMulti(hash)) hasherPending.set(hash, false);
+    return hash.digest(encoding);
+  }
+  return ts;
 }
 
 /**
  * 
+ * @overload
+ * @param {string[]} algorithm 
+ * @param {IDataType | ReadableStream} input 
+ * @return {Promise<{[key:string]: string}>}
+ */
+/**
+ * @overload
  * @param {string} algorithm 
- * @param {NodeJS.ReadableStream} input 
+ * @param {IDataType | ReadableStream} input 
+ * @return {Promise<string>}
  */
-async function digestFromStream(algorithm, input) {
-  let hash = algorithms[algorithm]();
-  await stream.pipeline(input, hash);
-  return hash.digest('hex');
+async function digest(algorithm, input) {
+  if (input instanceof ReadableStream) {
+    const hash = await createStream(algorithm);
+    await input.pipeTo(hash);
+    return hash.digest();
+  } else {
+    const hash = await (Array.isArray(algorithm) ? createMultiHasher(algorithm) : createHasher(algorithm));
+    if (!isMulti(hash)) hasherPending.set(hash, false);
+    return hash.update(input).digest();
+  }
+}
+
+async function initSync(algorithm) {
+  if (!hasherSyncCache[algorithm]) {
+    const factory = hasherFactory[algorithm];
+    if (!factory) throw new Error(`Unsupported digest algorithm: ${algorithm}`);
+    const hasher = await factory();
+    hasherSyncCache[algorithm] = hasher;
+  }
 }
 
 /**
- * 
+ * For this sync function to work correctly, it requires a call to initSync() to be awaited for each algorithm before calling this function. 
  * @param {string} algorithm 
- * @param {string} filePath 
+ * @param {IDataType} input 
  */
-async function digestFromFile(algorithm, filePath) {
-  return await digestFromStream(algorithm, fs.createReadStream(filePath));
+function digestSync(algorithm, input) {
+  const hasher = hasherSyncCache[algorithm];
+  if (!hasher) throw new Error(`Hasher for algorithm ${algorithm} is not initialized. Please call and await initSync('${algorithm}') before calling this function.`);
+  return hasher.init().update(input).digest();
+}
+
+const HEX_DIGEST_LENGTH = {
+  'md5': 32,
+  'sha1': 40,
+  'sha256': 64,
+  'sha512/256': 64,
+  'sha512': 128,
+  'blake2b-160': 40,
+  'blake2b-256': 64,
+  'blake2b-384': 96,
+  'blake2b-512': 128,
+  'crc32': 8,
+  'size': 1
+};
+
+function getHexDigestLength(algorithm) {
+  return HEX_DIGEST_LENGTH[algorithm] || 0;
 }
 
 const OcflDigest = {
   CONTENT,
   FIXITY,
-  algorithms,
-  createStream, createStreamThrough,
-  digestAsync, digestSync,
-  digestFromStream, digestFromFile
+  // algorithms,
+  createStream, createStreamThrough, digest,
+  registerHasherFactory, hasAlgorithm, getHexDigestLength,
+  digestSync, initSync
 };
 
 module.exports = {
-  OcflDigest
+  OcflDigest,
+  [testSymbol]: {
+    hasherCache
+  }
   // DIGEST,
   // DIGEST_FIXITY,
   // digestSync,
   // digestAsync,
   // digestFromStream,
-  // digestFromFile,
   // digestStream,
   // HashThrough
 };