@ocfl/ocfl 0.4.0 → 1.0.0-beta.2

package/src/extensions/000N-path-direct-storage-layout.ts

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import { OcflStorageLayout } from '../extension.ts';
+
+const DefaultConfig = {
+  extensionName: '000N-path-direct-storage-layout',
+  omitScheme: false,
+  replace: [] as [string | RegExp, string][],
+  suffix: '/__object__',
+};
+
+export type PathDirectStorageLayoutConfig = Partial<typeof DefaultConfig>;
+
+class PathDirectStorageLayout extends OcflStorageLayout<typeof DefaultConfig> {
+  static get NAME() {
+    return DefaultConfig.extensionName;
+  }
+  static get DESCRIPTION() {
+    return 'OCFL object identifiers are used directly as the path.';
+  }
+
+  constructor(config?: PathDirectStorageLayoutConfig) {
+    super(config, DefaultConfig);
+  }
+
+  map(id: string): string {
+    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 {
+      const u = new URL(p);
+      const 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)) {
+  }
+}
+
+export { PathDirectStorageLayout };

package/src/extensions/index.ts

@@ -0,0 +1,24 @@
+export { PathDirectStorageLayout } from './000N-path-direct-storage-layout.ts';
+export { FlatDirectStorageLayout } from './0002-flat-direct-storage-layout.ts';
+export { HashAndIdNTupleStorageLayout } from './0003-hash-and-id-n-tuple-storage-layout.ts';
+export { HashedNTupleStorageLayout } from './0004-hashed-n-tuple-storage-layout.ts';
+export { FlatOmitPrefixStorageLayout } from './0006-flat-omit-prefix-storage-layout.ts';
+export { NTupleOmitPrefixStorageLayout } from './0007-n-tuple-omit-prefix-storage-layout.ts';
+export { DigestAlgorithm } from './0009-digest-algorithms.ts';
+
+import type { PathDirectStorageLayout } from './000N-path-direct-storage-layout.ts';
+import type { FlatDirectStorageLayout } from './0002-flat-direct-storage-layout.ts';
+import type { HashAndIdNTupleStorageLayout } from './0003-hash-and-id-n-tuple-storage-layout.ts';
+import type { HashedNTupleStorageLayout } from './0004-hashed-n-tuple-storage-layout.ts';
+import type { FlatOmitPrefixStorageLayout } from './0006-flat-omit-prefix-storage-layout.ts';
+import type { NTupleOmitPrefixStorageLayout } from './0007-n-tuple-omit-prefix-storage-layout.ts';
+
+/** Built-in storage layout classes, keyed by class name */
+export type StorageLayout = {
+  FlatDirectStorageLayout: typeof FlatDirectStorageLayout;
+  FlatOmitPrefixStorageLayout: typeof FlatOmitPrefixStorageLayout;
+  HashAndIdNTupleStorageLayout: typeof HashAndIdNTupleStorageLayout;
+  HashedNTupleStorageLayout: typeof HashedNTupleStorageLayout;
+  NTupleOmitPrefixStorageLayout: typeof NTupleOmitPrefixStorageLayout;
+  PathDirectStorageLayout: typeof PathDirectStorageLayout;
+};

package/src/file.ts

@@ -0,0 +1,161 @@
+import type { OcflObject } from './object.ts';
+
+export interface FileRef {
+  /** Actual path to the file location relative to the ocfl object root. */
+  contentPath?: string;
+  /** A path that represents a file’s location in the logical state of an object. */
+  logicalPath?: string;
+  /** An algorithmic characterization of the contents of a file conforming to a standard digest algorithm. */
+  digest?: string;
+  /** Version of the OCFL object. */
+  version?: string | undefined;
+  /** Last modified time of the file, in milliseconds since the UNIX epoch. */
+  lastModified?: number;
+  /** Size of the file in bytes. */
+  size?: number;
+  /** Fixity information of the file. */
+  fixity?: { [algorithm: string]: string };
+}
+
+export interface FileStat {
+  /** Size of the file in bytes. */
+  size?: number;
+  /** Last access time of the file. */
+  atime?: Date;
+  /** Last modified time of the file. */
+  mtime?: Date;
+  /** Creation time of the file. */
+  ctime?: Date;
+}
+
+const REF_KEYS = ['logicalPath', 'version', 'digest', 'contentPath'] as const;
+
+/**
+ * Represent a file in an OCFL object
+ */
+class OcflObjectFile {
+  #ocflObject: OcflObject;
+  #lastModified: number | undefined;
+  #size: number | undefined;
+  logicalPath?: string;
+  contentPath?: string;
+  digest?: string;
+  version?: string;
+  fixity?: { [algorithm: string]: string };
+
+  constructor(ocflObject: OcflObject, fileRef: FileRef) {
+    this.#ocflObject = ocflObject;
+    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(): Promise<string> {
+    let contentPath = this.contentPath;
+    if (!contentPath) {
+      const inv = await this.#ocflObject._requireInventory();
+      const version = !this.version || this.version === 'latest' ? inv.head : this.version;
+      contentPath = this.digest ? inv.getContentPath(this.digest) : this.logicalPath && inv.getFile(this.logicalPath, version)?.contentPath;
+      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() {
+    const props = REF_KEYS.filter((key) => this[key]).map((key) => `${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
+   */
+  async buffer(options?: unknown): Promise<Uint8Array> {
+    return this.#ocflObject.readFile(await this.#resolveContentPath(), options);
+  }
+
+  /**
+   * @deprecated Use {@link OcflObjectFile.buffer}
+   */
+  async asBuffer(options?: unknown) {
+    return this.buffer(options);
+  }
+
+  /**
+   * Get the file content as a string
+   * @param encoding String encoding, default to utf8
+   */
+  async text(encoding: BufferEncoding = 'utf8'): Promise<string> {
+    return this.#ocflObject.readFile(await this.#resolveContentPath(), encoding);
+  }
+
+  /**
+   * @deprecated Use {@link OcflObjectFile.text}
+   */
+  async asString(encoding: BufferEncoding = 'utf8') {
+    return this.text(encoding);
+  }
+
+  /**
+   * Get the file content as a ReadableStream
+   * @param options Options to be passed to underlying data store specific implementation
+   * @deprecated Use {@link OcflObjectFile.stream}
+   */
+  async asStream(options?: unknown): Promise<ReadableStream> {
+    return this.stream(options);
+  }
+
+  /**
+   * Get the file content as a ES Streams standard ReadableStream
+   * @param options Options to be passed to underlying data store specific implementation
+   */
+  async stream(options?: unknown): Promise<ReadableStream> {
+    return this.#ocflObject.createReadable(await this.#resolveContentPath(), options);
+  }
+
+  /**
+   * Get the file stat info
+   */
+  async stat(_options?: unknown): Promise<FileStat> {
+    return this.#ocflObject.stat(await this.#resolveContentPath());
+  }
+}
+
+export { OcflObjectFile };

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * @module ocfl
+ */
+
+import { OcflConstants } from './constants.ts';
+import { createByName, OcflStorageLayout } from './extension.ts';
+import * as extensions from './extensions/index.ts';
+import { OcflObject } from './object.ts';
+import { type OcflStorage, OcflStorageImpl } from './storage.ts';
+import type { OcflStore } from './store.ts';
+import type { OcflExtensionConfig, OcflObjectConfig, OcflStorageConfig } from './types.ts';
+
+export { OcflConstants } from './constants.ts';
+export { OcflDigest } from './digest.ts';
+export { OcflExtension, OcflStorageLayout } from './extension.ts';
+export type { PathDirectStorageLayoutConfig } from './extensions/000N-path-direct-storage-layout.ts';
+export type { HashedNTupleStorageLayoutConfig } from './extensions/0004-hashed-n-tuple-storage-layout.ts';
+export type { StorageLayout } from './extensions/index.ts';
+export type { FileRef, FileStat, OcflObjectFile } from './file.ts';
+export type { InventoryFile, OcflObjectInventoryMut, VersionNumber } from './inventory.ts';
+export { OcflObjectInventory } from './inventory.ts';
+export type { UpdateMode } from './object.ts';
+export { OcflObject } from './object.ts';
+export { OcflStorage, OcflStorageImpl } from './storage.ts';
+export type { ListedFile, ListOptions, WriteFileData } from './store.ts';
+export { OcflStore } from './store.ts';
+export type { CommitOptions, RemoveOptions } from './transaction.ts';
+export { OcflObjectTransaction, OcflObjectTransactionImpl } from './transaction.ts';
+export type * from './types.ts';
+export { extensions };
+
+/**
+ * Creates a new OCFL core API with a specific backend store.
+ * Any backend store implementation module must return the result of this method.
+ * @returns Top level OCFL API interface that provides storage and object creation.
+ */
+export function implementOcfl<SO extends object>(store: { getInstance(options?: SO): OcflStore }, defaultOptions?: SO) {
+  return {
+    OCFL_VERSIONS: OcflConstants.OCFL_VERSIONS,
+
+    /** Built-in storage layout classes */
+    StorageLayout: OcflStorageLayout.layout,
+
+    /**
+     * Instantiate a storage layout from extension name or config
+     * @param config - Layout name or config
+     */
+    storageLayout(config: string | OcflExtensionConfig): OcflStorageLayout {
+      let name: string | undefined;
+      let c: OcflExtensionConfig | undefined;
+      if (typeof config === 'string') {
+        name = config;
+      } else {
+        name = config.extensionName;
+        c = config;
+      }
+      return createByName<OcflStorageLayout>(OcflStorageLayout, 'Layout', name, c);
+    },
+
+    /**
+     * Instantiate an OCFL Object
+     */
+    object(config: OcflObjectConfig, storeOptions: SO | undefined = defaultOptions): OcflObject {
+      return new OcflObject(config, store.getInstance(storeOptions));
+    },
+
+    /**
+     * Instantiate an OCFL Storage root
+     */
+    storage(config: OcflStorageConfig, storeOptions: SO | undefined = defaultOptions): OcflStorage {
+      return new OcflStorageImpl(config, store.getInstance(storeOptions));
+    },
+
+    /**
+     * Create a new OCFL Storage
+     */
+    async createStorage(config: OcflStorageConfig, storeOptions: SO | undefined = defaultOptions): Promise<OcflStorage> {
+      return new OcflStorageImpl(config, store.getInstance(storeOptions)).create();
+    },
+
+    /**
+     * Load an existing OCFL Storage
+     */
+    async loadStorage(config: OcflStorageConfig, storeOptions: SO | undefined = defaultOptions): Promise<OcflStorage> {
+      return new OcflStorageImpl(config, store.getInstance(storeOptions)).load();
+    },
+  };
+}
+
+for (const ext of Object.values(extensions)) {
+  ext.register();
+}