docs: update docs to be clearer

Ensure locks have a close method when creating the lock

Author: jacobheun

README.md

@@ -142,7 +142,7 @@ Arguments:
 
 * `path` (string, mandatory): the path for this repo
 * `options` (object, optional): may contain the following values
-  * `lock` (string *Deprecated* or [Lock](#lock)), string can be `"fs"` or `"memory"`: what type of lock to use. Lock has to be acquired when opening.
+  * `lock` ([Lock](#lock) or string *Deprecated*): what type of lock to use. Lock has to be acquired when opening. string can be `"fs"` or `"memory"`.
   * `storageBackends` (object, optional): may contain the following values, which should each be a class implementing the [datastore interface](https://github.com/ipfs/interface-datastore#readme):
     * `root` (defaults to [`datastore-fs`](https://github.com/ipfs/js-datastore-fs#readme) in Node.js and [`datastore-level`](https://github.com/ipfs/js-datastore-level#readme) in the browser). Defines the back-end type used for gets and puts of values at the root (`repo.set()`, `repo.get()`)
     * `blocks` (defaults to [`datastore-fs`](https://github.com/ipfs/js-datastore-fs#readme) in Node.js and [`datastore-level`](https://github.com/ipfs/js-datastore-level#readme) in the browser). Defines the back-end type used for gets and puts of values at `repo.blocks`.
@@ -302,12 +302,14 @@ IPFS Repo comes with two built in locks: memory and fs. These can be imported vi
 
 ```js
 const fsLock = require('ipfs-repo/src/lock')  // Default in Node.js
-const memLock = require('ipfs-repo/src/lock-memory')  // Default in browser
+const memoryLock = require('ipfs-repo/src/lock-memory')  // Default in browser
 ```
 
-#### `lock.open (dir, callback)`
+You can also provide your own custom Lock. It must be an object with the following interface:
 
-Sets the lock if one does not already exist.
+#### `lock.lock (dir, callback)`
+
+Sets the lock if one does not already exist. If a lock already exists, `callback` should be called with an error.
 
 `dir` is a string to the directory the lock should be created at. The repo typically creates the lock at its root.
 

src/index.js

@@ -159,7 +159,14 @@ class IpfsRepo {
    * @returns {void}
    */
   _openLock (path, callback) {
-    this._locker.lock(path, callback)
+    this._locker.lock(path, (err, lockfile) => {
+      if (err) {
+        return callback(err, null)
+      }
+
+      assert.equal(typeof lockfile.close, 'function', 'Locks must have a close method')
+      callback(null, lockfile)
+    })
   }
 
   /**

test/options-test.js

@@ -29,7 +29,7 @@ describe('custom options tests', () => {
     expect(repo.options).to.deep.equal(expectedRepoOptions())
   })
 
-  it('allows for a custom locker', () => {
+  it('allows for a custom lock', () => {
     const lock = {
       lock: (path, callback) => { },
       locked: (path, callback) => { }
@@ -41,6 +41,23 @@ describe('custom options tests', () => {
 
     expect(repo._getLocker()).to.deep.equal(lock)
   })
+
+  it('ensures a custom lock has a .close method', (done) => {
+    const lock = {
+      lock: (path, callback) => {
+        callback(null, {})
+      }
+    }
+
+    const repo = new Repo(repoPath, {
+      lock
+    })
+
+    expect(
+      () => repo._openLock(repo.path)
+    ).to.throw('Locks must have a close method')
+    done()
+  })
 })
 
 function noop () {}