chore: factor out types into ipfs-interface

Author: Gozala

packages/ipfs-core-utils/package.json

@@ -44,6 +44,7 @@
     "cids": "^1.0.0",
     "err-code": "^2.0.3",
     "ipfs-utils": "^5.0.0",
+    "ipfs-interface": "^0.1.0",
     "it-all": "^1.0.4",
     "it-map": "^1.0.4",
     "it-peekable": "^1.0.1",

packages/ipfs-core-utils/src/files/format-mode.js

@@ -26,7 +26,7 @@ function checkPermission (mode, perm, type, output) {
 
 /**
  *
- * @param {Mode} mode
+ * @param {import('ipfs-interface/src/files').Mode} mode
  * @param {boolean} isDirectory
  * @returns {string}
  */
@@ -70,7 +70,3 @@ function formatMode (mode, isDirectory) {
 }
 
 module.exports = formatMode
-
-/**
- * @typedef {number} Mode
- */

packages/ipfs-core-utils/src/files/format-mtime.js

@@ -1,7 +1,7 @@
 'use strict'
 
 /**
- * @param {MTime} mtime
+ * @param {import('ipfs-interface/src/files').MTime} mtime
  * @returns {string}
  */
 function formatMtime (mtime) {
@@ -22,12 +22,4 @@ function formatMtime (mtime) {
   })
 }
 
-/**
- * @typedef {object} MTime
- * @property {number} secs - the number of seconds since (positive) or before
- * (negative) the Unix Epoch began
- * @property {number} nsecs - the number of nanoseconds since the last full
- * second.
- */
-
 module.exports = formatMtime

packages/ipfs-core-utils/src/files/normalise-input/index.browser.js

@@ -12,7 +12,7 @@ const normaliseInput = require('./normalise-input')
  *
  * See https://github.com/ipfs/js-ipfs/blob/master/docs/core-api/FILES.md#ipfsadddata-options
  *
- * @param {import('./normalise-input').Source} input
- * @returns {AsyncIterable<import('./normalise-input').Entry<Blob>>}
+ * @param {import('ipfs-interface/src/files').ImportSource} input
+ * @returns {AsyncIterable<import('ipfs-interface/src/files').Entry<Blob>>}
  */
 module.exports = (input) => normaliseInput(input, normaliseContent)

packages/ipfs-core-utils/src/files/normalise-input/index.js

@@ -12,7 +12,7 @@ const normaliseInput = require('./normalise-input')
  *
  * See https://github.com/ipfs/js-ipfs/blob/master/docs/core-api/FILES.md#ipfsadddata-options
  *
- * @param {import('./normalise-input').Source} input
- * @returns {AsyncIterable<import('./normalise-input').Entry<AsyncIterable<Uint8Array>>>}
+ * @param {import('ipfs-interface/src/files').ImportSource} input
+ * @returns {AsyncIterable<import('ipfs-interface/src/files').Entry<AsyncIterable<Uint8Array>>>}
  */
 module.exports = (input) => normaliseInput(input, normaliseContent)

packages/ipfs-core-utils/src/files/normalise-input/normalise-input.js

@@ -15,11 +15,14 @@ const {
 
 // eslint-disable-next-line complexity
 
+/**
+ * @typedef {import('ipfs-interface/src/files').ToContent} ToContent
+ */
 /**
  * @template {Blob|AsyncIterable<Uint8Array>} Content
- * @param {Source} input
+ * @param {import('ipfs-interface/src/files').ImportSource} input
  * @param {(content:ToContent) => Content|Promise<Content>} normaliseContent
- * @returns {AsyncIterable<Entry<Content>>}
+ * @returns {AsyncIterable<import('ipfs-interface/src/files').Entry<Content>>}
  */
 // eslint-disable-next-line complexity
 module.exports = async function * normaliseInput (input, normaliseContent) {
@@ -100,9 +103,9 @@ module.exports = async function * normaliseInput (input, normaliseContent) {
 
 /**
  * @template {Blob|AsyncIterable<Uint8Array>} Content
- * @param {ToFile} input
+ * @param {import('ipfs-interface/src/files').ToEntry} input
  * @param {(content:ToContent) => Content|Promise<Content>} normaliseContent
- * @returns {Promise<Entry<Content>>}
+ * @returns {Promise<import('ipfs-interface/src/files').Entry<Content>>}
  */
 async function toFileObject (input, normaliseContent) {
   // @ts-ignore - Those properties don't exist on most input types
@@ -119,42 +122,3 @@ async function toFileObject (input, normaliseContent) {
 
   return file
 }
-
-/**
- * @typedef {import('../format-mtime').MTime} MTime
- * @typedef {import('../format-mode').Mode} Mode
- * @typedef {Object} Directory
- * @property {string} path
- * @property {Mode} [mode]
- * @property {MTime} [mtime]
- * @property {undefined} [content]
- *
- * @typedef {Object} FileInput
- * @property {string} [path]
- * @property {ToContent} [content]
- * @property {number | string} [mode]
- * @property {UnixTime} [mtime]
- *
- * @typedef {Date | MTime | HRTime} UnixTime
- *
- * Time representation as tuple of two integers, as per the output of
- * [`process.hrtime()`](https://nodejs.org/dist/latest/docs/api/process.html#process_process_hrtime_time).
- * @typedef {[number, number]} HRTime
- *
- * @typedef {string|InstanceType<typeof window.String>|ArrayBufferView|ArrayBuffer|Blob|Iterable<Uint8Array> | AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>} ToContent
- * @typedef {ToContent|FileInput} ToFile
- * @typedef {Iterable<ToFile> | AsyncIterable<ToFile> | ReadableStream<ToFile>} Source
- */
-/**
- * @template {AsyncIterable<Uint8Array>|Blob} Content
- * @typedef {Object} File
- * @property {string} path
- * @property {Mode} [mode]
- * @property {MTime} [mtime]
- * @property {Content} [content]
- */
-
-/**
- * @template {AsyncIterable<Uint8Array>|Blob} Content
- * @typedef {File<Content>|Directory} Entry
- */

packages/ipfs-core-utils/src/files/normalise-input/utils.js

@@ -22,7 +22,7 @@ function isBlob (obj) {
  * An object with a path or content property
  *
  * @param {any} obj
- * @returns {obj is import('./normalise-input').FileInput}
+ * @returns {obj is import('ipfs-interface/src/files').ToEntry}
  */
 function isFileObject (obj) {
   return typeof obj === 'object' && (obj.path || obj.content)

packages/ipfs-core/package.json

@@ -71,6 +71,7 @@
     "ipfs-bitswap": "^4.0.0",
     "ipfs-block-service": "^0.18.0",
     "ipfs-core-utils": "^0.5.3",
+    "ipfs-interface": "^0.1.0",
     "ipfs-repo": "^7.0.0",
     "ipfs-unixfs": "^2.0.3",
     "ipfs-unixfs-exporter": "^3.0.4",

packages/ipfs-core/src/components/add-all/index.js

@@ -13,17 +13,12 @@ const mergeOptions = require('merge-options').bind({ ignoreUndefined: true })
  * @param {import('..').GCLock} config.gcLock
  * @param {import('..').Preload} config.preload
  * @param {import('..').Pin} config.pin
- * @param {ShardingOptions} [config.options]
+ * @param {import('ipfs-interface/src/root').ShardingOptions} [config.options]
  */
 module.exports = ({ block, gcLock, preload, pin, options }) => {
   const isShardingEnabled = options && options.sharding
-  /**
-   * Import multiple files and data into IPFS.
-   *
-   * @param {FileStream} source
-   * @param {AddAllOptions & AbortOptions} [options]
-   * @returns {AsyncIterable<UnixFSEntry>}
-   */
+
+  /** @type {import('ipfs-interface/src/root').AddAll} */
   async function * addAll (source, options = {}) {
     const opts = mergeOptions({
       shardSplitThreshold: isShardingEnabled ? 1000 : Infinity,
@@ -169,43 +164,3 @@ function pinFile (pin, opts) {
     }
   }
 }
-
-/**
- * @typedef {object} UnixFSEntry
- * @property {string} path
- * @property {CID} cid
- * @property {number} [mode]
- * @property {MTime} [mtime]
- * @property {number} size
- *
- * @typedef {Object} AddAllOptions
- * @property {string} [chunker='size-262144'] - Chunking algorithm used to build
- * ipfs DAGs.
- * @property {0|1} [cidVersion=0] - The CID version to use when storing the data.
- * @property {boolean} [enableShardingExperiment=false] - Allows to create
- * directories with an unlimited number of entries currently size of unixfs
- * directories is limited by the maximum block size. **Note** that this is an
- * experimental feature.
- * @property {string} [hashAlg='sha2-256'] - Multihash hashing algorithm to use.
- * @property {boolean} [onlyHash=false] - If true, will not add blocks to the
- * blockstore.
- * @property {boolean} [pin=true] - Pin this object when adding.
- * @property {(bytes:number, path:string) => void} [progress] - a function that will be called with the number of bytes added as a file is added to ipfs and the path of the file being added
- * @property {boolean} [rawLeaves=false] - If true, DAG leaves will contain raw
- * file data and not be wrapped in a protobuf.
- * @property {number} [shardSplitThreshold=1000] - Directories with more than this
- * number of files will be created as HAMT-sharded directories.
- * @property {boolean} [trickle=false] - If true will use the
- * [trickle DAG](https://godoc.org/github.com/ipsn/go-ipfs/gxlibs/github.com/ipfs/go-unixfs/importer/trickle)
- * format for DAG generation.
- * @property {boolean} [wrapWithDirectory=false] - Adds a wrapping node around
- * the content.
- *
- * @typedef {import('ipfs-core-utils/src/files/normalise-input/normalise-input').Source} FileStream
- * @typedef {import('../../utils').MTime} MTime
- * @typedef {import('../../utils').AbortOptions} AbortOptions
- * @typedef {import('..').CID} CID
- *
- * @typedef {Object} ShardingOptions
- * @property {boolean} [sharding]
- */

packages/ipfs-core/src/components/add.js

@@ -2,39 +2,25 @@
 
 const last = require('it-last')
 
+/**
+ * @param {Object} config
+ * @param {import('ipfs-interface/src/root').AddAll} config.addAll
+ */
 module.exports = ({ addAll }) => {
-  /**
-   * Import a file or data into IPFS.
-   *
-   * @param {Source} source
-   * @param {AddOptions & AbortOptions} [options]
-   * @returns {AddResult}
-   */
-  async function add (source, options) { // eslint-disable-line require-await
-    /** @type {UnixFSEntry} - Could be undefined if empty */
-    const result = (await last(addAll(source, options)))
+  /** @type {import('ipfs-interface/src/root').Add} */
+  async function add (entry, options) {
+    /** @type {import('ipfs-interface/src/files').ImportSource} */
+    const source = (entry) //
+    const result = await last(addAll(source, options))
+    // Note this should never happen as `addAll` should yield at least one item
+    // but to satisfy type checker we perfom this check and for good measure
+    // throw an error in case it does happen.
+    if (result == null) {
+      throw Error('Failed to add a file, if you see this please report a bug')
+    }
+
     return result
   }
+
   return add
 }
-
-/**
- * @typedef {object} AddOptions
- * @property {string} [chunker] - chunking algorithm used to build ipfs DAGs (default: `'size-262144'`)
- * @property {number} [cidVersion] - the CID version to use when storing the data (default: `0`)
- * @property {string} [hashAlg] - multihash hashing algorithm to use (default: `'sha2-256'`)
- * @property {boolean} [onlyHash] - If true, will not add blocks to the blockstore (default: `false`)
- * @property {boolean} [pin] - pin this object when adding (default: `true`)
- * @property {(bytes:number, path:string) => void} [progress] - a function that will be called with the number of bytes added as a file is added to ipfs and the path of the file being added
- * @property {boolean} [rawLeaves] - if true, DAG leaves will contain raw file data and not be wrapped in a protobuf (default: `false`)
- * @property {boolean} [trickle] - if true will use the [trickle DAG](https://godoc.org/github.com/ipsn/go-ipfs/gxlibs/github.com/ipfs/go-unixfs/importer/trickle) format for DAG generation (default: `false`)
- * @property {boolean} [wrapWithDirectory] - Adds a wrapping node around the content (default: `false`)
- *
- * @typedef {Promise<UnixFSEntry>} AddResult
- *
- * @typedef {import('ipfs-core-utils/src/files/normalise-input/normalise-input').FileInput} Source
- *
- * @typedef {import('./add-all').UnixFSEntry} UnixFSEntry
- *
- * @typedef {import('../utils').AbortOptions} AbortOptions
- */

packages/ipfs-core/src/components/cat.js

@@ -10,13 +10,7 @@ const withTimeoutOption = require('ipfs-core-utils/src/with-timeout-option')
  * @param {import('.').Preload} config.preload
  */
 module.exports = function ({ ipld, preload }) {
-  /**
-   * Returns content of the file addressed by a valid IPFS Path or CID.
-   *
-   * @param {CID|string} ipfsPath - An IPFS path or CID to export
-   * @param {Options} [options]
-   * @returns {AsyncIterable<Uint8Array>}
-   */
+  /** @type {import('ipfs-interface/src/root').Cat} */
   async function * cat (ipfsPath, options = {}) {
     ipfsPath = normalizeCidPath(ipfsPath)
 
@@ -41,16 +35,3 @@ module.exports = function ({ ipld, preload }) {
 
   return withTimeoutOption(cat)
 }
-
-/**
- * @typedef {CatOptions & AbortOptions} Options
- *
- * @typedef {Object} CatOptions
- * @property {number} [offset] - An offset to start reading the file from
- * @property {number} [length] - An optional max length to read from the file
- * @property {boolean} [preload]
- *
- * @typedef {import('../utils').AbortOptions} AbortOptions
- *
- * @typedef {import('.').CID} CID
- */

packages/ipfs-core/src/components/files/mkdir.js

@@ -143,14 +143,16 @@ const addEmptyDir = async (context, childName, emptyDir, parent, trail, options)
 /**
  * @typedef {Object} MkdirOptions
  * @property {boolean} [parents=false] - If true, create intermediate directories
- * @property {number} [mode] - An integer that represents the file mode
- * @property {Mtime|Hrtime|Date} [mtime] - A Date object, an object with `{ secs, nsecs }` properties where secs is the number of seconds since (positive) or before (negative) the Unix Epoch began and nsecs is the number of nanoseconds since the last full second, or the output of `process.hrtime()
+ * @property {ToMode} [mode] - An integer that represents the file mode
+ * @property {ToMTime} [mtime] - A Date object, an object with `{ secs, nsecs }` properties where secs is the number of seconds since (positive) or before (negative) the Unix Epoch began and nsecs is the number of nanoseconds since the last full second, or the output of `process.hrtime()
  * @property {boolean} [flush] - If true the changes will be immediately flushed to disk
  * @property {string} [hashAlg='sha2-256'] - The hash algorithm to use for any updated entries
- * @property {0|1} [cidVersion=0] - The CID version to use for any updated entries
+ * @property {CIDVersion} [cidVersion=0] - The CID version to use for any updated entries
  *
  * @typedef {import('cids')} CID
- * @typedef {import('../../utils').AbortOptions} AbortOptions
- * @typedef {import('../../utils').Mtime} Mtime
- * @typedef {import('../../utils').Hrtime} Hrtime
+ * @typedef {import('cids').CIDVersion} CIDVersion
+ * @typedef {import('ipfs-interface/src/basic').AbortOptions} AbortOptions
+ * @typedef {import('ipfs-interface/src/files').MTime} Mtime
+ * @typedef {import('ipfs-interface/src/files').ToMTime} ToMTime
+ * @typedef {import('ipfs-interface/src/files').ToMode} ToMode
  */

packages/ipfs-core/src/components/files/stat.js

@@ -180,8 +180,8 @@ const statters = {
  * @property {number} [sizeLocal] - An integer indicating the cumulative size of
  * the data present locally.
  * @property {number} [mode] - File mode
- * @property {import('../add-all').MTime} [mtime] - Modification time
+ * @property {import('ipfs-interface/src/files').MTime} [mtime] - Modification time
  *
- * @typedef {import('..').CID} CID
- * @typedef {import('../../utils').AbortOptions} AbortOptions
+ * @typedef {import('cids')} CID
+ * @typedef {import('ipfs-interface/src/basic').AbortOptions} AbortOptions
  */

packages/ipfs-core/src/components/files/touch.js

@@ -15,7 +15,7 @@ const mh = require('multihashing-async').multihash
 const withTimeoutOption = require('ipfs-core-utils/src/with-timeout-option')
 
 const defaultOptions = {
-  /** @type {UnixTime|undefined} */
+  /** @type {ToMTime|undefined} */
   mtime: undefined,
   flush: true,
   shardSplitThreshold: 1000,
@@ -121,14 +121,12 @@ module.exports = (context) => {
 
 /**
  * @typedef {Object} TouchOptions
- * @property {UnixTime} [mtime] - A Date object, an object with `{ secs, nsecs }` properties where secs is the number of seconds since (positive) or before (negative) the Unix Epoch began and nsecs is the number of nanoseconds since the last full second, or the output of `process.hrtime()`
+ * @property {ToMTime} [mtime] - A Date object, an object with `{ secs, nsecs }` properties where secs is the number of seconds since (positive) or before (negative) the Unix Epoch began and nsecs is the number of nanoseconds since the last full second, or the output of `process.hrtime()`
  * @property {boolean} [flush=false] - If true the changes will be immediately flushed to disk
  * @property {string} [hashAlg='sha2-256'] - The hash algorithm to use for any updated entries
- * @property {0|1} [cidVersion] - The CID version to use for any updated entries
+ * @property {import('cids').CIDVersion} [cidVersion] - The CID version to use for any updated entries
  *
  * @typedef {import('cids')} CID
- * @typedef {import('../../utils').AbortOptions} AbortOptions
- * @typedef {import('../../utils').Mtime} Mtime
- * @typedef {import('../../utils').Hrtime} Hrtime
- * @typedef {import('ipfs-core-utils/src/files/normalise-input/normalise-input').UnixTime} UnixTime
+ * @typedef {import('ipfs-interface/src/basic').AbortOptions} AbortOptions
+ * @typedef {import('ipfs-interface/src/files').ToMTime} ToMTime
  */

packages/ipfs-core/src/components/files/write.js

@@ -299,13 +299,11 @@ const countBytesStreamed = async function * (source, notify) {
  * @property {boolean} [parents=false] - Create intermediate MFS paths if they do not exist
  * @property {boolean} [truncate=false] - Truncate the file at the MFS path if it would have been larger than the passed content
  * @property {boolean} [rawLeaves=false] - If true, DAG leaves will contain raw file data and not be wrapped in a protobuf
- * @property {number} [mode] - An integer that represents the file mode
- * @property {Mtime|Hrtime|Date} [mtime] - A Date object, an object with `{ secs, nsecs }` properties where secs is the number of seconds since (positive) or before (negative) the Unix Epoch began and nsecs is the number of nanoseconds since the last full second, or the output of `process.hrtime()
+ * @property {import('ipfs-interface/src/files').ToMode} [mode] - An integer that represents the file mode
+ * @property {import('ipfs-interface/src/files').ToMTime} [mtime] - A Date object, an object with `{ secs, nsecs }` properties where secs is the number of seconds since (positive) or before (negative) the Unix Epoch began and nsecs is the number of nanoseconds since the last full second, or the output of `process.hrtime()
  * @property {boolean} [flush] - If true the changes will be immediately flushed to disk
  * @property {string} [hashAlg='sha2-256'] - The hash algorithm to use for any updated entries
  * @property {0|1} [cidVersion=0] - The CID version to use for any updated entries
  *
  * @typedef {import('../../utils').AbortOptions} AbortOptions
- * @typedef {import('../../utils').Mtime} Mtime
- * @typedef {import('../../utils').Hrtime} Hrtime
  */