@ocfl/ocfl 0.1.1 → 0.1.2

package/README.md

@@ -1,7 +1,8 @@
 # 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
+
+* ocfl-fs - File system 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. 
@@ -14,3 +15,7 @@ To implement a local extension in this library, first follow the description in
        
     }
 
+
+## Implementation
+
+A new data store backend can be implemented by creating a new package with a store class that extends the `OcflStore` class and implements its methods. Please see the source code of ocfl-fs as an example implementation

package/index.js

@@ -73,7 +73,7 @@ class Ocfl {
   get StorageLayout() { return OcflStorageLayout.layout }
 
   /**
-   * Create a storage layout from extension name or config
+   * Instantiate a storage layout from extension name or config
    * @param {string|OcflExtensionConfig} config - Layout name or config
    */
   storageLayout(config) {
@@ -90,7 +90,7 @@ class Ocfl {
   }
 
   /**
-   * Create an OCFL Object
+   * Instantiate an OCFL Object object
    * @param {OcflObjectConfig} config
    * @param {SO} [storeOptions]
    * @return {OcflObject}
@@ -100,7 +100,7 @@ class Ocfl {
   }
 
   /**
-   * Create an OCFL Storage
+   * Instantiate an OCFL Storage object
    * @param {OcflStorageConfig} config
    * @param {SO} [storeOptions]
    * @return {OcflStorage}
@@ -109,16 +109,27 @@ class Ocfl {
     return new OcflStorageImpl(config, this.#store.getInstance(storeOptions));
   }
 
-}
-
-class Storage {
-  async create(config) {
-
+  /**
+   * 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();
   }
-  async load(config) {
 
+  /**
+   * 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 = {

package/lib/object.js

@@ -150,7 +150,7 @@ class OcflObject {
    * @param {ObjectUpdateMode} [mode=UPDATE_MODE.MERGE]
    * @return {Promise<?OcflObjectTransaction>}
    */
-  async update(updater, mode = UPDATE_MODE.MERGE) { throw new NotImplementedError() }
+  async update(updater, mode) { throw new NotImplementedError() }
 
   /**
    * Import one or more content files or directories to the object 
@@ -199,7 +199,8 @@ class OcflObject {
 
   /**
    * Iterate through the content files contained in the specified version. 
-   * Returns an array of FileRef which consists of logical path, content path, and digest, in no particular order
+   * Returns an Iterator that contains FileRef which consists of logical path, content path, and digest, in no particular order.
+   * The iterator is implemented as a generator.
    * @param {string} [version]
    * @return {Promise<Generator<OcflObjectFile, void, unknown>>}
    */
@@ -502,7 +503,6 @@ class OcflObjectImpl extends OcflObject {
   }
 
   async isObject(aPath) { }
-  async importDir(id, sourceDir) { }
   getVersionString(i) { }
   async determineVersion() { }
   nameVersion(version) {

package/lib/storage.js

@@ -7,8 +7,8 @@ const { OcflStorageLayout } = require("./extension");
 const { HashedNTupleStorageLayout } = require("./extensions/0004-hashed-n-tuple-storage-layout");
 const { OcflObject, OcflObjectImpl } = require("./object");
 const { isDirEmpty, findNamasteVersion } = require("./utils.js");
-const { OCFL_VERSION, OCFL_VERSIONS, OCFL_LAYOUT, 
-  EXTENSIONS_DIR, EXTENSION_CONFIG, 
+const { OCFL_VERSION, OCFL_VERSIONS, OCFL_LAYOUT,
+  EXTENSIONS_DIR, EXTENSION_CONFIG,
   NAMASTE_PREFIX_STORAGE, NAMASTE_PREFIX_OBJECT, NAMASTE_T } = require('./constants').OcflConstants;
 const DIGEST = require('./digest').OcflDigest.CONTENT;
 
@@ -66,42 +66,44 @@ class OcflStorage {
    * Create the storage root in the underlying storage backend
    * @param {Object} [options] - Additional options for creating storage root
    * @param {boolean} [options.ocflSpecText=false] - If true, create a copy of the OCFL specification text in the storage root
+   * @return {Promise<OcflStorage>}
    */
   async create(options) { throw new NotImplementedError(); }
 
-  /**
-   * Check if the storage root path points to an existing file or non-empty directory in the underlying backend store.
-   * The existing directory may or may not be a valid OCFL Storage.
-   * @return {Promise<boolean>}
-   */
-  async exists() { throw new NotImplementedError(); }
-
   /**
    * Check namaste, retrieve storage layout extension, and read its config file.
-   * @return {Promise<boolean>}
+   * @return {Promise<OcflStorage>}
    */
   async load() { throw new NotImplementedError(); }
 
+  /**
+  * Check if the storage root path points to an existing file or non-empty directory in the underlying backend store.
+  * The existing directory may or may not be a valid OCFL Storage.
+  * @return {Promise<boolean>}
+  */
+  async exists() { throw new NotImplementedError(); }
+
   /**
    * 
-   * @return {AsyncIterator<OcflObject>}
+   * @return {AsyncIterableIterator<OcflObject>}
    */
   [Symbol.asyncIterator]() { throw new NotImplementedError(); }
 
   /**
-   * Return all OCFL objects under this storage as array
-   * @return {Promise<OcflObject[]>}
+   * Return a new AsyncIterator that contains all the OCFL objects in this Storage.
+   * @return {AsyncIterableIterator<OcflObject>}
    */
-  async objects() {
-    const objects = []; 
-    for await(const o of this) objects.push(o); 
-    return objects;
+  objects() {
+    return this[Symbol.asyncIterator]();
+    // const objects = [];
+    // for await (const o of this) objects.push(o);
+    // return objects;
   }
 
   async delete(id) {
     return this.remove(id);
   }
-  
+
   async purge(id) {
     return this.remove(id);
   }
@@ -188,7 +190,7 @@ class OcflStorageImpl extends OcflStorage {
   object(opt) {
     let id, root;
     if (typeof opt === 'string') id = opt;
-    else ({id, root} = opt);
+    else ({ id, root } = opt);
     let relObjectRoot = root || this.objectRoot(id);
     return new OcflObjectImpl({
       id,
@@ -230,7 +232,7 @@ class OcflStorageImpl extends OcflStorage {
 
     //@todo: load storage level extensions
 
-    return true;
+    return this;
   }
 
   /**
@@ -264,11 +266,9 @@ class OcflStorageImpl extends OcflStorage {
     if (options?.ocflSpecText) {
 
     }
+    return this;
   }
 
-  /**
-   * @return {AsyncIterator<OcflObject, OcflObject>}
-   */
   [Symbol.asyncIterator]() {
     let store = this.#store;
     let workspace = this.#workspace;
@@ -276,6 +276,7 @@ class OcflStorageImpl extends OcflStorage {
     let root = this.root;
     let stack = [this.#store.opendir(this.root)];
     return {
+      [Symbol.asyncIterator]() { return this; },
       async next() {
         let dirp;
         while ((dirp = stack.pop())) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ocfl/ocfl",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Oxford Common File Layout (OCFL) JS library",
   "main": "index.js",
   "exports": {