feat: base types

- adds types
- removes fake async
- fixes tests for async errors that now are sync
- adds local types for merge-options

Author: hugomrdias

package.json

@@ -43,7 +43,13 @@
     "npm": ">=3.0.0"
   },
   "devDependencies": {
-    "aegir": "^30.0.1",
+    "@types/bytes": "^3.1.0",
+    "@types/debug": "^4.1.5",
+    "@types/err-code": "^2.0.0",
+    "@types/memdown": "^3.0.0",
+    "@types/ncp": "^2.0.4",
+    "@types/rimraf": "^3.0.0",
+    "aegir": "^30.3.0",
     "it-all": "^1.0.2",
     "it-drain": "^1.0.1",
     "it-first": "^1.0.2",
@@ -58,24 +64,28 @@
     "bignumber.js": "^9.0.0",
     "bytes": "^3.1.0",
     "cids": "^1.0.0",
-    "datastore-core": "^2.0.0",
-    "datastore-fs": "^2.0.0",
-    "datastore-level": "^2.0.0",
+    "datastore-core": "ipfs/js-datastore-core#feat/ts-types",
+    "datastore-fs": "ipfs/js-datastore-fs#feat/ts-types",
+    "datastore-level": "ipfs/js-datastore-level#feat/ts-types",
     "debug": "^4.1.0",
     "err-code": "^2.0.0",
-    "interface-datastore": "^2.0.0",
+    "interface-datastore": "^3.0.1",
     "ipfs-repo-migrations": "^5.0.3",
-    "ipfs-utils": "^5.0.1",
+    "ipfs-utils": "^6.0.0",
     "ipld-block": "^0.11.0",
     "it-map": "^1.0.2",
     "it-pushable": "^1.4.0",
     "just-safe-get": "^2.0.0",
     "just-safe-set": "^2.1.0",
+    "merge-options": "^3.0.4",
     "multibase": "^3.0.0",
     "p-queue": "^6.0.0",
     "proper-lockfile": "^4.0.0",
     "sort-keys": "^4.0.0",
-    "uint8arrays": "^1.0.0"
+    "uint8arrays": "^2.0.5"
+  },
+  "eslintConfig": {
+    "extends": "ipfs"
   },
   "license": "MIT",
   "contributors": [

src/api-addr.js

@@ -5,6 +5,10 @@ const uint8ArrayFromString = require('uint8arrays/from-string')
 
 const apiFile = new Key('api')
 
+/**
+ *
+ * @param {import("interface-datastore").Datastore} store
+ */
 module.exports = (store) => {
   return {
     /**
@@ -18,19 +22,17 @@ module.exports = (store) => {
     },
     /**
      * Set the current configuration for this repo.
+     * TODO: fix find the proper type or remove this API
      *
-     * @param {Object} value - the api address to be written
-     * @returns {Promise<?>}
+     * @param {string} value - the api address to be written
      */
-    async set (value) { // eslint-disable-line require-await
+    set (value) {
       return store.put(apiFile, uint8ArrayFromString(value.toString()))
     },
     /**
      * Deletes api file
-     *
-     * @returns {Promise<void>}
      */
-    async delete () { // eslint-disable-line require-await
+    delete () {
       return store.delete(apiFile)
     }
   }

src/backends.js

@@ -1,7 +1,25 @@
 'use strict'
 
-exports.create = function createBackend (name, path, options) {
+/**
+ * @typedef {import("interface-datastore").Datastore} Datastore
+ * @typedef {import("./types").Backends} Backends
+ * @typedef {import("./types").InternalOptions} Options
+ */
+
+/**
+ *
+ * @param {Backends} name
+ * @param {string} path
+ * @param {Options} options
+ * @returns {Datastore}
+ */
+function createBackend (name, path, options) {
   const Ctor = options.storageBackends[name]
   const backendOptions = Object.assign({}, options.storageBackendOptions[name] || {})
+  // @ts-ignore we don't have a signature for the constructor
   return new Ctor(path, backendOptions)
 }
+
+module.exports = {
+  create: createBackend
+}

src/blockstore.js

@@ -1,34 +1,50 @@
 'use strict'
 
-const core = require('datastore-core')
-const ShardingStore = core.ShardingDatastore
+const { shard, ShardingDatastore } = require('datastore-core')
 const Block = require('ipld-block')
 const { cidToKey, keyToCid } = require('./blockstore-utils')
 const map = require('it-map')
 const drain = require('it-drain')
 const pushable = require('it-pushable')
-
+/**
+ * @typedef {import("interface-datastore").Query} Query
+ * @typedef {import("interface-datastore").Datastore} Datastore
+ * @typedef {import("interface-datastore").Options} DatastoreOptions
+ * @typedef {import("cids")} CID
+ */
+
+/**
+ *
+ * @param {Datastore} filestore
+ * @param {*} options
+ */
 module.exports = async (filestore, options) => {
   const store = await maybeWithSharding(filestore, options)
   return createBaseStore(store)
 }
 
+/**
+ * @param {Datastore} filestore
+ * @param {{ sharding: any; }} options
+ */
 function maybeWithSharding (filestore, options) {
   if (options.sharding) {
-    const shard = new core.shard.NextToLast(2)
-    return ShardingStore.createOrOpen(filestore, shard)
+    return ShardingDatastore.createOrOpen(filestore, new shard.NextToLast(2))
   }
   return filestore
 }
 
+/**
+ * @param {Datastore | ShardingDatastore} store
+ */
 function createBaseStore (store) {
   return {
     /**
      * Query the store
      *
-     * @param {Object} query
-     * @param {Object} options
-     * @returns {AsyncIterator<Block|CID>}
+     * @param {Query} query
+     * @param {DatastoreOptions} [options]
+     * @returns {AsyncIterable<Block|CID>}
      */
     async * query (query, options) {
       for await (const { key, value } of store.query(query, options)) {
@@ -45,7 +61,7 @@ function createBaseStore (store) {
      * Get a single block by CID
      *
      * @param {CID} cid
-     * @param {Object} options
+     * @param {DatastoreOptions} [options]
      * @returns {Promise<Block>}
      */
     async get (cid, options) {
@@ -58,9 +74,9 @@ function createBaseStore (store) {
     /**
      * Like get, but for more
      *
-     * @param {AsyncIterator<CID>} cids
-     * @param {Object} options
-     * @returns {AsyncIterator<Block>}
+     * @param {Iterable<CID> | AsyncIterable<CID>} cids
+     * @param {DatastoreOptions} [options]
+     * @returns {AsyncIterable<Block>}
      */
     async * getMany (cids, options) {
       for await (const cid of cids) {
@@ -72,7 +88,7 @@ function createBaseStore (store) {
      * Write a single block to the store
      *
      * @param {Block} block
-     * @param {Object} options
+     * @param {DatastoreOptions} [options]
      * @returns {Promise<Block>}
      */
     async put (block, options) {
@@ -94,7 +110,7 @@ function createBaseStore (store) {
      * Like put, but for more
      *
      * @param {AsyncIterable<Block>|Iterable<Block>} blocks
-     * @param {Object} options
+     * @param {DatastoreOptions} [options]
      * @returns {AsyncIterable<Block>}
      */
     async * putMany (blocks, options) { // eslint-disable-line require-await
@@ -142,41 +158,38 @@ function createBaseStore (store) {
      * Does the store contain block with this CID?
      *
      * @param {CID} cid
-     * @param {Object} options
-     * @returns {Promise<bool>}
+     * @param {DatastoreOptions} [options]
      */
-    async has (cid, options) { // eslint-disable-line require-await
+    has (cid, options) {
       return store.has(cidToKey(cid), options)
     },
 
     /**
      * Delete a block from the store
      *
      * @param {CID} cid
-     * @param {Object} options
+     * @param {DatastoreOptions} [options]
      * @returns {Promise<void>}
      */
-    async delete (cid, options) { // eslint-disable-line require-await
+    delete (cid, options) {
       return store.delete(cidToKey(cid), options)
     },
 
     /**
      * Delete a block from the store
      *
-     * @param {AsyncIterable<CID>} cids
-     * @param {Object} options
-     * @returns {Promise<void>}
+     * @param {AsyncIterable<any> | Iterable<any>} cids
+     * @param {DatastoreOptions} [options]
      */
-    async * deleteMany (cids, options) { // eslint-disable-line require-await
-      yield * store.deleteMany(map(cids, cid => cidToKey(cid)), options)
+    deleteMany (cids, options) {
+      return store.deleteMany(map(cids, cid => cidToKey(cid)), options)
     },
 
     /**
      * Close the store
      *
-     * @returns {Promise<void>}
      */
-    async close () { // eslint-disable-line require-await
+    close () {
       return store.close()
     }
   }

src/config.js

@@ -1,8 +1,10 @@
 'use strict'
 
-const Key = require('interface-datastore').Key
+const { Key } = require('interface-datastore')
 const { default: Queue } = require('p-queue')
+// @ts-ignore
 const _get = require('just-safe-get')
+// @ts-ignore
 const _set = require('just-safe-set')
 const errcode = require('err-code')
 const errors = require('./errors')
@@ -11,28 +13,32 @@ const uint8ArrayFromString = require('uint8arrays/from-string')
 
 const configKey = new Key('config')
 
+/**
+ *
+ * @param {import("interface-datastore").Datastore} store
+ */
 module.exports = (store) => {
   const setQueue = new Queue({ concurrency: 1 })
 
   const configStore = {
     /**
      * Get the current configuration from the repo.
      *
-     * @param {Object} options - options
-     * @param {AbortSignal} options.signal - abort this config read
-     * @returns {Promise<Object>}
+     * @param {Object} [options] - options
+     * @param {AbortSignal} [options.signal] - abort this config read
+     * @returns {Promise<unknown>}
      */
-    async getAll (options = {}) { // eslint-disable-line require-await
+    getAll (options = {}) { // eslint-disable-line require-await
       return configStore.get(undefined, options)
     },
 
     /**
      * Get the value for the passed configuration key from the repo.
      *
-     * @param {string} key - the config key to get
-     * @param {Object} options - options
-     * @param {AbortSignal} options.signal - abort this config read
-     * @returns {Promise<Object>}
+     * @param {string} [key] - the config key to get
+     * @param {Object} [options] - options
+     * @param {AbortSignal} [options.signal] - abort this config read
+     * @returns {Promise<unknown>}
      */
     async get (key, options = {}) {
       if (!key) {
@@ -57,13 +63,12 @@ module.exports = (store) => {
     /**
      * Set the current configuration for this repo.
      *
-     * @param {string} key - the config key to be written
-     * @param {Object} value - the config value to be written
-     * @param {Object} options - options
-     * @param {AbortSignal} options.signal - abort this config write
-     * @returns {void}
+     * @param {string | unknown} [key] - the config key to be written
+     * @param {unknown} [value] - the config value to be written
+     * @param {Object} [options] - options
+     * @param {AbortSignal} [options.signal] - abort this config write
      */
-    async set (key, value, options = {}) { // eslint-disable-line require-await
+    set (key, value, options = {}) {
       if (arguments.length === 1) {
         value = key
         key = undefined
@@ -84,12 +89,11 @@ module.exports = (store) => {
     /**
      * Set the current configuration for this repo.
      *
-     * @param {Object} value - the config value to be written
-     * @param {Object} options - options
-     * @param {AbortSignal} options.signal - abort this config write
-     * @returns {void}
+     * @param {Object} [value] - the config value to be written
+     * @param {Object} [options] - options
+     * @param {AbortSignal} [options.signal] - abort this config write
      */
-    async replace (value, options = {}) { // eslint-disable-line require-await
+    replace (value, options = {}) {
       if (!value || (value instanceof Uint8Array)) {
         throw errcode(new Error('Invalid value type: ' + typeof value), 'ERR_INVALID_VALUE')
       }
@@ -103,15 +107,18 @@ module.exports = (store) => {
     /**
      * Check if a config file exists.
      *
-     * @returns {Promise<bool>}
      */
-    async exists () { // eslint-disable-line require-await
+    exists () {
       return store.has(configKey)
     }
   }
 
   return configStore
 
+  /**
+   * @param {{ key: any; value: any; }} m
+   * @param {AbortSignal | undefined} signal
+   */
   async function _maybeDoSet (m, signal) {
     if (signal && signal.aborted) {
       return
@@ -127,6 +134,9 @@ module.exports = (store) => {
     return _saveAll(value)
   }
 
+  /**
+   * @param {unknown} config
+   */
   function _saveAll (config) {
     const buf = uint8ArrayFromString(JSON.stringify(config, null, 2))
     return store.put(configKey, buf)

src/default-options.js

@@ -1,6 +1,10 @@
 'use strict'
 
 // Default configuration for a repo in node.js
+
+/**
+ * @type {import("./types").InternalOptions}
+ */
 module.exports = {
   lock: 'fs',
   storageBackends: {