@ocfl/ocfl 0.3.0 → 1.0.0-beta.1

package/src/digest.ts

@@ -0,0 +1,258 @@
+import crypto from 'node:crypto';
+import zlib from 'node:zlib';
+import type { CommonHasher, IDataType, MultiHasher } from './types.ts';
+
+const CONTENT = ['sha256', 'sha512'] as const;
+type ContentAlgorithm = (typeof CONTENT)[number];
+
+/** OCFL algorithm name to node:crypto name */
+const NATIVE = {
+  md5: 'md5',
+  sha1: 'sha1',
+  sha256: 'sha256',
+  sha512: 'sha512',
+  'sha512/256': 'sha512-256',
+  'blake2b-512': 'blake2b512',
+};
+
+type Digest = CommonHasher['digest'];
+type MultiDigest = MultiHasher['digest'];
+type WritableStreamHasher = WritableStream & { update(data: IDataType): void; digest: Digest };
+type WritableStreamMultiHasher = WritableStream & { update(data: IDataType): void; digest: MultiDigest };
+type StreamThroughHash = TransformStream & { digest: MultiDigest };
+type StreamThroughOptions = { writableStrategy?: QueuingStrategy; readableStrategy?: QueuingStrategy };
+
+function toBytes(data: IDataType): string | Uint8Array {
+  if (typeof data === 'string' || data instanceof Uint8Array) {
+    return data;
+  }
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  return new Uint8Array(data);
+}
+
+interface HashState {
+  update(data: string | Uint8Array): void;
+  digest(): Uint8Array;
+  hex(): string;
+}
+
+function hasher(digestSize: number, start: () => HashState): CommonHasher {
+  let state = start();
+  return {
+    digestSize,
+    init() {
+      state = start();
+      return this;
+    },
+    update(data) {
+      state.update(toBytes(data));
+      return this;
+    },
+    digest: ((encoding?: 'binary' | 'hex') => (encoding === 'binary' ? state.digest() : state.hex())) as Digest,
+  };
+}
+
+const hasherFactory: { [key: string]: () => Promise<CommonHasher> } = {};
+const hasherSyncCache: { [key: string]: CommonHasher } = {};
+
+/**
+ * Register a hash algorithm and it's factory function.
+ */
+function registerHasherFactory(name: string, factory: () => Promise<CommonHasher>) {
+  if (typeof factory === 'function') {
+    hasherFactory[name] = factory;
+  }
+}
+
+function hasAlgorithm(name: string) {
+  return name in hasherFactory;
+}
+
+for (const [algo, nativeName] of Object.entries(NATIVE)) {
+  const digestSize = crypto.createHash(nativeName).digest().length;
+  registerHasherFactory(algo, async () =>
+    hasher(digestSize, () => {
+      const h = crypto.createHash(nativeName);
+      let result: Buffer | undefined;
+      const final = () => {
+        result ??= h.digest();
+        return result;
+      };
+      return { update: (d) => h.update(d), digest: () => new Uint8Array(final()), hex: () => final().toString('hex') };
+    }),
+  );
+}
+
+registerHasherFactory('crc32', async () =>
+  hasher(4, () => {
+    let crc = 0;
+    return {
+      update: (d) => {
+        crc = zlib.crc32(d, crc);
+      },
+      digest: () => {
+        const b = new Uint8Array(4);
+        new DataView(b.buffer).setUint32(0, crc);
+        return b;
+      },
+      hex: () => crc.toString(16).padStart(8, '0'),
+    };
+  }),
+);
+
+registerHasherFactory('size', async () =>
+  hasher(8, () => {
+    let size = 0;
+    return {
+      update: (d) => {
+        size += typeof d === 'string' ? Buffer.byteLength(d) : d.byteLength;
+      },
+      digest: () => new Uint8Array(new BigUint64Array([BigInt(size)]).buffer),
+      hex: () => `${size}`,
+    };
+  }),
+);
+
+/**
+ * Create a hasher instance for the given algorithm.
+ */
+async function createHasher(algorithm: string): Promise<CommonHasher> {
+  const factory = hasherFactory[algorithm];
+  if (!factory) {
+    throw new Error(`Unsupported digest algorithm: ${algorithm}`);
+  }
+  return (await factory()).init();
+}
+
+/**
+ * Create a hasher instance for calculating multiple types of digest in one go.
+ */
+async function createMultiHasher(algorithms: string | string[]): Promise<MultiHasher> {
+  const algoNames = Array.isArray(algorithms) ? (algorithms.length ? [...new Set(algorithms)] : ['sha512']) : [algorithms];
+  const hashers = await Promise.all(algoNames.map(async (name) => [name, await createHasher(name)] as const));
+  const multiHasher: MultiHasher = {
+    multi: true,
+    update(data) {
+      for (const [, hash] of hashers) {
+        hash.update(data);
+      }
+      return this;
+    },
+    digest: ((encoding?: 'binary' | 'hex') => {
+      const result: { [key: string]: string | Uint8Array } = {};
+      for (const [name, hash] of hashers) {
+        result[name] = hash.digest(encoding as 'hex');
+      }
+      return result;
+    }) as MultiDigest,
+  };
+  return multiHasher;
+}
+
+function createAnyHasher(algorithm: string | string[]): Promise<CommonHasher | MultiHasher> {
+  return Array.isArray(algorithm) ? createMultiHasher(algorithm) : createHasher(algorithm);
+}
+
+/**
+ * Create a hash instance that implements WritableStream.
+ * @param algorithm One or more digest algorithm names
+ */
+async function createStream(algorithm?: string): Promise<WritableStreamHasher>;
+async function createStream(algorithm: string[]): Promise<WritableStreamMultiHasher>;
+async function createStream(algorithm: string | string[] = 'sha512'): Promise<WritableStreamHasher | WritableStreamMultiHasher> {
+  const hash = await createAnyHasher(algorithm);
+  const ws = new WritableStream({
+    write(chunk) {
+      hash.update(chunk);
+    },
+  }) as WritableStreamHasher & WritableStreamMultiHasher;
+  ws.update = (data) => {
+    hash.update(data);
+  };
+  ws.digest = ((encoding?: 'binary' | 'hex') => hash.digest(encoding as 'hex')) as Digest & MultiDigest;
+  return ws;
+}
+
+/**
+ * Create a pass through stream that pass data as it is and calculate the digest as data pass through.
+ */
+async function createStreamThrough(algorithm: string | string[] = 'sha512', options?: StreamThroughOptions): Promise<StreamThroughHash> {
+  const hash = await createAnyHasher(algorithm);
+  const { writableStrategy, readableStrategy } = options || {};
+  const ts = new TransformStream(
+    {
+      transform(chunk, controller) {
+        controller.enqueue(chunk);
+        hash.update(chunk);
+      },
+    },
+    writableStrategy,
+    readableStrategy,
+  ) as StreamThroughHash;
+  ts.digest = ((encoding?: 'binary' | 'hex') => hash.digest(encoding as 'hex')) as MultiDigest;
+  return ts;
+}
+
+async function digest(algorithm: string[], input: IDataType | ReadableStream): Promise<{ [key: string]: string }>;
+async function digest(algorithm: string, input: IDataType | ReadableStream): Promise<string>;
+async function digest(algorithm: string | string[], input: IDataType | ReadableStream): Promise<string | { [key: string]: string }> {
+  if (input instanceof ReadableStream) {
+    const hash = await createStream(algorithm as string);
+    await input.pipeTo(hash);
+    return hash.digest();
+  }
+  const hash = await createAnyHasher(algorithm);
+  return hash.update(input).digest();
+}
+
+async function initSync(algorithm: string) {
+  if (!hasherSyncCache[algorithm]) {
+    const factory = hasherFactory[algorithm];
+    if (!factory) {
+      throw new Error(`Unsupported digest algorithm: ${algorithm}`);
+    }
+    hasherSyncCache[algorithm] = await factory();
+  }
+}
+
+/**
+ * For this sync function to work correctly, it requires a call to initSync() to be awaited for each algorithm before calling this function.
+ */
+function digestSync(algorithm: string, input: IDataType): string {
+  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: { [algorithm: string]: number } = {
+  md5: 32,
+  sha1: 40,
+  sha256: 64,
+  'sha512/256': 64,
+  sha512: 128,
+  'blake2b-512': 128,
+  crc32: 8,
+  size: 1,
+};
+
+function getHexDigestLength(algorithm: string) {
+  return HEX_DIGEST_LENGTH[algorithm] || 0;
+}
+
+const OcflDigest = {
+  CONTENT,
+  createStream,
+  createStreamThrough,
+  digest,
+  registerHasherFactory,
+  hasAlgorithm,
+  getHexDigestLength,
+  digestSync,
+  initSync,
+};
+
+export { type ContentAlgorithm, OcflDigest };

package/src/error.ts

@@ -0,0 +1,9 @@
+class NotImplementedError extends Error {
+  constructor(methodName?: string) {
+    const msg = methodName ? `Method ${methodName} has not been implemented` : '';
+    super(msg);
+    this.name = 'NotImplementedError';
+  }
+}
+
+export { NotImplementedError };

package/src/extension.ts

@@ -0,0 +1,206 @@
+import { NotImplementedError } from './error.ts';
+import type { StorageLayout } from './extensions/index.ts';
+import type { OcflExtensionConfig } from './types.ts';
+
+/** Index by Registered extension name */
+const extensionByName: { [name: string]: typeof OcflExtension } = {};
+/** Index by extension class name */
+const extensionByClassName: { [name: string]: typeof OcflExtension } = {};
+
+const storageLayout: { [className: string]: typeof OcflStorageLayout } = {};
+
+type ExtensionConstructor<T> = new (config?: OcflExtensionConfig) => T;
+
+class OcflExtension<C extends object = object> {
+  static #object: { [name: string]: typeof OcflExtension } = {};
+  static #storage: { [name: string]: typeof OcflExtension } = {};
+
+  parameters: C;
+
+  /**
+   * Get an object-level extension
+   * @param name - A registered extension name
+   */
+  static object(name: string) {
+    return OcflExtension.#object[name];
+  }
+
+  /**
+   * Get an storage-level extension
+   * @param name - A registered extension name
+   */
+  static storage(name: string) {
+    return OcflExtension.#storage[name];
+  }
+
+  /** List all registered extension classes */
+  static get classes(): (typeof OcflExtension)[] {
+    return Object.values(extensionByName);
+  }
+
+  /**
+   * Find a registered extension with the specified name
+   * @param name - extension class name or registered extension name
+   * @returns the extension class
+   */
+  static class(name: string): typeof OcflExtension | undefined {
+    return extensionByName[name] || extensionByClassName[name];
+  }
+
+  /**
+   * Register an extension
+   */
+  // biome-ignore lint/complexity/noThisInStatic: defaults to the subclass register() is called on
+  static register(extensionClass: typeof OcflExtension = this) {
+    const name = extensionClass.NAME;
+    extensionByName[name] = extensionClass;
+    extensionByClassName[extensionClass.name] = extensionClass;
+    import('./index.ts').then((ocfl) => extensionClass.setup(ocfl));
+  }
+
+  /**
+   * Create an instance of the extension
+   */
+  static create<T extends OcflExtension>(this: ExtensionConstructor<T>, config?: OcflExtensionConfig): T {
+    const name = config?.extensionName;
+    // biome-ignore lint/complexity/noThisInStatic: must be the subclass create() is called on, or it recurses
+    if (!name || (this as unknown as typeof OcflExtension).NAME === name) {
+      return new this(config);
+    }
+    return createByName(OcflExtension, 'Extension', name, config) as T;
+  }
+
+  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: typeof import('./index.ts')): Promise<void> {}
+
+  constructor(config?: OcflExtensionConfig, defaultConfig?: C) {
+    this.parameters = typeof defaultConfig === 'object' ? Object.create(defaultConfig) : {};
+    if (typeof config === 'object' && defaultConfig) {
+      for (const k in config) {
+        if (k in defaultConfig) {
+          (this.parameters as OcflExtensionConfig)[k] = config[k];
+        }
+      }
+    }
+  }
+
+  /** Return all the parameters in which the value has been set to non-default value */
+  get config(): OcflExtensionConfig | undefined {
+    const paramNames = Object.keys(this.parameters);
+    if (paramNames.length === 0) {
+      return undefined;
+    }
+    const params: OcflExtensionConfig = { extensionName: this.name };
+    for (const name of paramNames) {
+      params[name] = this.get(name);
+    }
+    return params;
+  }
+
+  get p() {
+    return this.parameters;
+  }
+
+  /** Extension registered name */
+  get name(): string {
+    return (this.constructor as typeof OcflExtension).NAME;
+  }
+  get description(): string {
+    return (this.constructor as typeof OcflExtension).DESCRIPTION;
+  }
+  get minOcflVersion() {
+    return '1.0';
+  }
+  get version() {
+    return '1.0';
+  }
+
+  /**
+   * Get the specified parameter value
+   * @param param - The extension parameter name
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: parameter values are extension specific
+  get(param: string): any {
+    return (this.parameters as OcflExtensionConfig)[param];
+  }
+
+  /**
+   * Set the specified parameter value
+   * @param param - The extension parameter name
+   * @param value - The extension parameter value
+   */
+  set(param: string, value: unknown) {
+    if (param in this.parameters) {
+      (this.parameters as OcflExtensionConfig)[param] = value;
+    }
+  }
+}
+
+class OcflStorageLayout<C extends object = object> extends OcflExtension<C> {
+  static get layout(): StorageLayout {
+    return storageLayout as unknown as StorageLayout;
+  }
+
+  static class(name: string): typeof OcflStorageLayout | undefined {
+    const c = OcflExtension.class(name);
+    if (c && c.prototype instanceof OcflStorageLayout) {
+      return c as typeof OcflStorageLayout;
+    }
+  }
+
+  static get classes(): (typeof OcflStorageLayout)[] {
+    return Object.values(storageLayout);
+  }
+
+  /**
+   * Register a storage layout extension
+   */
+  // biome-ignore lint/complexity/noThisInStatic: defaults to the subclass register() is called on
+  static register(extensionClass: typeof OcflStorageLayout = this) {
+    OcflExtension.register(extensionClass);
+    storageLayout[extensionClass.name] = extensionClass;
+  }
+
+  static get forStorage() {
+    return true;
+  }
+
+  async validate() {}
+
+  /**
+   * Map an object identifier to a path
+   * @param id - The identifier of the OCFL Object
+   */
+  map(_id: string): string {
+    throw new NotImplementedError();
+  }
+}
+
+type ExtensionRegistry<T> = { class(name: string): { create(config?: OcflExtensionConfig): T } | undefined };
+
+/** Create an instance of the extension registered as `name`, or throw if `registry` has none */
+function createByName<T extends OcflExtension>(
+  registry: ExtensionRegistry<T>,
+  kind: 'Extension' | 'Layout',
+  name: string | undefined,
+  config?: OcflExtensionConfig,
+): T {
+  const cls = name ? registry.class(name) : undefined;
+  if (!cls) {
+    throw new Error(`${kind} "${name}" is not supported.`);
+  }
+  return cls.create(config);
+}
+
+export { createByName, OcflExtension, OcflStorageLayout };

package/{lib/extensions/0002-flat-direct-storage-layout.js → src/extensions/0002-flat-direct-storage-layout.ts}

@@ -1,35 +1,28 @@
-const path = require("path");
-const { OcflStorageLayout } = require("../extension");
-const { EXTENSIONS_DIR } = require("../constants").OcflConstants;
+import path from 'node:path';
+import { OcflConstants } from '../constants.ts';
+import { OcflStorageLayout } from '../extension.ts';
 
-/** @type {FlatDirectStorageLayout} */
-var instance;
+const { EXTENSIONS_DIR } = OcflConstants;
+
+let instance: FlatDirectStorageLayout;
 
 /**
  * OCFL object identifiers are mapped directly to directory names that are direct children of the OCFL storage root directory.
  */
-// @ts-ignore
 class FlatDirectStorageLayout extends OcflStorageLayout {
-  static get NAME() { return '0002-flat-direct-storage-layout' }
+  static get NAME() {
+    return '0002-flat-direct-storage-layout';
+  }
   static get DESCRIPTION() {
-    return "OCFL object identifiers are mapped directly to directory names" +
-      " that are direct children of the OCFL storage root.";
+    return 'OCFL object identifiers are mapped directly to directory names' + ' that are direct children of the OCFL storage root.';
   }
 
-  static create() {
-    if (!instance) instance = new FlatDirectStorageLayout();
-    return instance;
-  }
-  
-  constructor() {
-    super()
+  static create<T>(): T {
+    instance ??= new FlatDirectStorageLayout();
+    return instance as T;
   }
 
-  /**
-   * @param {string} id
-   * @return {string} 
-   */
-  map(id) {
+  map(id: string): string {
     if (path.basename(id) !== id) {
       throw new Error(`The object id <${id}> is incompatible with layout extension ${this.name} because it contains the path separator character.`);
     } else if (id === EXTENSIONS_DIR) {
@@ -43,4 +36,4 @@ class FlatDirectStorageLayout extends OcflStorageLayout {
   }
 }
 
-module.exports = { FlatDirectStorageLayout };
+export { FlatDirectStorageLayout };

package/src/extensions/0003-hash-and-id-n-tuple-storage-layout.ts

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import { OcflDigest } from '../digest.ts';
+import { OcflStorageLayout } from '../extension.ts';
+
+function encodeIdentifier(id: string) {
+  return encodeURIComponent(id).toLowerCase().replace(/\./g, '%2e');
+}
+
+const DefaultConfig = {
+  extensionName: '0003-hash-and-id-n-tuple-storage-layout',
+  digestAlgorithm: 'sha256',
+  tupleSize: 3,
+  numberOfTuples: 3,
+};
+
+class HashAndIdNTupleStorageLayout extends OcflStorageLayout<typeof DefaultConfig> {
+  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.'
+    );
+  }
+
+  constructor(config?: Partial<typeof DefaultConfig>) {
+    super(config, DefaultConfig);
+    const c = this.parameters;
+    const digestLength = OcflDigest.getHexDigestLength(c.digestAlgorithm);
+    if (!digestLength) {
+      throw new Error('Invalid digestAlgorithm');
+    }
+    const 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.');
+    }
+  }
+
+  map(id: string): string {
+    const digest = OcflDigest.digestSync(this.parameters.digestAlgorithm, id);
+    const segments = [];
+    const s = this.parameters.tupleSize;
+    const n = this.parameters.numberOfTuples;
+    let i: number;
+    for (i = 0; i < n; ++i) {
+      segments.push(digest.slice(s * i, s * i + s));
+    }
+    segments.push(encodeIdentifier(id));
+    return segments.join(path.sep);
+  }
+}
+
+export { HashAndIdNTupleStorageLayout };

package/src/extensions/0004-hashed-n-tuple-storage-layout.ts

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import { OcflDigest } from '../digest.ts';
+import { OcflStorageLayout } from '../extension.ts';
+
+const DefaultConfig = {
+  extensionName: '0004-hashed-n-tuple-storage-layout',
+  digestAlgorithm: 'sha256',
+  tupleSize: 3,
+  numberOfTuples: 3,
+  shortObjectRoot: false,
+};
+export type HashedNTupleStorageLayoutConfig = Partial<typeof DefaultConfig>;
+
+class HashedNTupleStorageLayout extends OcflStorageLayout<typeof DefaultConfig> {
+  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.'
+    );
+  }
+
+  constructor(config?: HashedNTupleStorageLayoutConfig) {
+    super(config, DefaultConfig);
+    const c = this.parameters;
+    const digestLength = OcflDigest.getHexDigestLength(c.digestAlgorithm);
+    if (!digestLength) {
+      throw new Error('Invalid digestAlgorithm');
+    }
+    const 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');
+    }
+  }
+
+  map(id: string): string {
+    const digest = OcflDigest.digestSync(this.parameters.digestAlgorithm, id);
+    const segments = [];
+    const s = this.parameters.tupleSize;
+    const n = this.parameters.numberOfTuples;
+    let i: number;
+    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);
+  }
+}
+
+export { HashedNTupleStorageLayout };

package/src/extensions/0006-flat-omit-prefix-storage-layout.ts

@@ -0,0 +1,9 @@
+import { OcflStorageLayout } from '../extension.ts';
+
+class FlatOmitPrefixStorageLayout extends OcflStorageLayout {
+  static get NAME() {
+    return '0006-flat-omit-prefix-storage-layout';
+  }
+}
+
+export { FlatOmitPrefixStorageLayout };

package/src/extensions/0007-n-tuple-omit-prefix-storage-layout.ts

@@ -0,0 +1,9 @@
+import { OcflStorageLayout } from '../extension.ts';
+
+class NTupleOmitPrefixStorageLayout extends OcflStorageLayout {
+  static get NAME() {
+    return '0007-n-tuple-omit-prefix-storage-layout';
+  }
+}
+
+export { NTupleOmitPrefixStorageLayout };

package/src/extensions/0009-digest-algorithms.ts

@@ -0,0 +1,12 @@
+import { OcflExtension } from '../extension.ts';
+
+/**
+ * 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';
+  }
+}
+
+export { DigestAlgorithm };