chore: declare interface types in .d.ts file

- Moves all types into `.d.ts` files so they do not get duplicated in generated types
- Switches to named exports
- Loosens mtime definition for unixfs
- Exports utility functions for converting mtimes and modes
- Runs ts check during linting

BREAKING CHANGE: switches to named exports

Author: achingbrain

packages/ipfs-unixfs-exporter/README.md

@@ -26,8 +26,8 @@
       - [Raw entries](#raw-entries)
       - [CBOR entries](#cbor-entries)
       - [`entry.content({ offset, length })`](#entrycontent-offset-length-)
-    - [`exporter.path(cid, ipld)`](#exporterpathcid-ipld)
-    - [`exporter.recursive(cid, ipld)`](#exporterrecursivecid-ipld)
+    - [`walkPath(cid, ipld)`](#walkpathcid-ipld)
+    - [`recursive(cid, ipld)`](#recursivecid-ipld)
   - [Contribute](#contribute)
   - [License](#license)
 
@@ -43,8 +43,8 @@
 
 ```js
 // import a file and export it again
-const importer = require('ipfs-unixfs-importer')
-const exporter = require('ipfs-unixfs-exporter')
+const { importer } = require('ipfs-unixfs-importer')
+const { exporter } = require('ipfs-unixfs-exporter')
 
 const files = []
 
@@ -80,7 +80,7 @@ console.info(bytes) // 0, 1, 2, 3
 #### API
 
 ```js
-const exporter = require('ipfs-unixfs-exporter')
+const { exporter } = require('ipfs-unixfs-exporter')
 ```
 
 ### `exporter(cid, ipld, options)`
@@ -202,28 +202,32 @@ for await (const entry of dir.content({
 // `entries` contains the first 5 files/directories in the directory
 ```
 
-### `exporter.path(cid, ipld)`
+### `walkPath(cid, ipld)`
 
-`exporter.path` will return an async iterator that yields entries for all segments in a path:
+`walkPath` will return an async iterator that yields entries for all segments in a path:
 
 ```javascript
+const { walkPath } = require('ipfs-unixfs-exporter')
+
 const entries = []
 
-for await (const entry of exporter.path('Qmfoo/foo/bar/baz.txt', ipld)) {
+for await (const entry of walkPath('Qmfoo/foo/bar/baz.txt', ipld)) {
   entries.push(entry)
 }
 
 // entries contains 4x `entry` objects
 ```
 
-### `exporter.recursive(cid, ipld)`
+### `recursive(cid, ipld)`
 
-`exporter.recursive` will return an async iterator that yields all entries beneath a given CID or IPFS path, as well as the containing directory.
+`recursive` will return an async iterator that yields all entries beneath a given CID or IPFS path, as well as the containing directory.
 
 ```javascript
+const { recursive } = require('ipfs-unixfs-exporter')
+
 const entries = []
 
-for await (const child of exporter.recursive('Qmfoo/foo/bar', ipld)) {
+for await (const child of recursive('Qmfoo/foo/bar', ipld)) {
   entries.push(entry)
 }
 

packages/ipfs-unixfs-exporter/package.json

@@ -8,12 +8,12 @@
     "fs": false
   },
   "scripts": {
-    "prepare": "aegir build --no-bundle",
     "test": "aegir test",
+    "build": "aegir build",
     "clean": "rimraf ./dist",
-    "lint": "aegir lint",
+    "lint": "aegir ts --check && aegir lint",
     "coverage": "nyc -s npm run test -t node && nyc report --reporter=html",
-    "depcheck": "aegir dep-check -i @types/mocha -i @types/sinon -i nyc -i abort-controller -i rimraf -i ipfs-core-types"
+    "depcheck": "aegir dep-check -i @types/mocha -i @types/sinon -i nyc -i abort-controller -i rimraf -i ipfs-core-types -i copy"
   },
   "repository": {
     "type": "git",
@@ -35,18 +35,20 @@
     "@types/mocha": "^8.2.1",
     "@types/sinon": "^9.0.10",
     "abort-controller": "^3.0.0",
-    "aegir": "^30.3.0",
+    "aegir": "^31.0.4",
+    "copy": "^0.3.2",
     "detect-node": "^2.0.4",
-    "ipfs-core-types": "^0.3.0",
+    "ipfs-core-types": "^0.3.1",
     "ipfs-unixfs-importer": "^6.0.1",
-    "ipld": "^0.28.0",
-    "ipld-dag-pb": "^0.21.0",
-    "ipld-in-memory": "^7.0.0",
+    "ipld": "^0.29.0",
+    "ipld-block": "^0.11.1",
+    "ipld-dag-pb": "^0.22.1",
+    "ipld-in-memory": "^8.0.0",
     "it-all": "^1.0.5",
     "it-buffer-stream": "^2.0.0",
     "it-first": "^1.0.6",
     "merge-options": "^3.0.4",
-    "multicodec": "^2.1.0",
+    "multicodec": "^3.0.1",
     "native-abort-controller": "^1.0.3",
     "nyc": "^15.0.0",
     "rimraf": "^3.0.2",

packages/ipfs-unixfs-exporter/src/index.js

@@ -6,66 +6,12 @@ const resolve = require('./resolvers')
 const last = require('it-last')
 
 /**
- * @typedef {import('ipfs-unixfs')} UnixFS
+ * @typedef {import('ipfs-unixfs').UnixFS} UnixFS
  * @typedef {import('ipld-dag-pb').DAGNode} DAGNode
- * @typedef {import('ipfs-core-types/src/ipld').IPLD} IPLD
- *
- * @typedef {object} UnixFSFile
- * @property {'file'} type
- * @property {string} name
- * @property {string} path
- * @property {CID} cid
- * @property {number} depth
- * @property {UnixFS} unixfs
- * @property {DAGNode} node
- * @property {(options?: ExporterOptions) => AsyncIterable<Uint8Array>} content
- *
- * @typedef {object} UnixFSDirectory
- * @property {'directory'} type
- * @property {string} name
- * @property {string} path
- * @property {CID} cid
- * @property {number} depth
- * @property {UnixFS} unixfs
- * @property {DAGNode} node
- * @property {(options?: ExporterOptions) => AsyncIterable<UnixFSEntry>} content
- *
- * @typedef {object} ObjectNode
- * @property {'object'} type
- * @property {string} name
- * @property {string} path
- * @property {CID} cid
- * @property {number} depth
- * @property {Uint8Array} node
- * @property {(options?: ExporterOptions) => AsyncIterable<any>} content
- *
- * @typedef {object} RawNode
- * @property {'raw'} type
- * @property {string} name
- * @property {string} path
- * @property {CID} cid
- * @property {number} depth
- * @property {Uint8Array} node
- * @property {(options?: ExporterOptions) => AsyncIterable<Uint8Array>} content
- *
- * @typedef {object} IdentityNode
- * @property {'identity'} type
- * @property {string} name
- * @property {string} path
- * @property {CID} cid
- * @property {number} depth
- * @property {Uint8Array} node
- * @property {(options?: ExporterOptions) => AsyncIterable<Uint8Array>} content
- *
- * @typedef {UnixFSFile | UnixFSDirectory | ObjectNode | RawNode | IdentityNode} UnixFSEntry
- */
-
-/**
- * @typedef {object} ExporterOptions
- * @property {number} [offset=0]
- * @property {number} [length]
- * @property {AbortSignal} [signal]
- * @property {number} [timeout]
+ * @typedef {import('ipld')} IPLD
+ * @typedef {import('./types').ExporterOptions} ExporterOptions
+ * @typedef {import('./types').UnixFSDirectory} UnixFSDirectory
+ * @typedef {import('./types').UnixFSEntry} UnixFSEntry
  */
 
 const toPathComponents = (path = '') => {
@@ -115,7 +61,7 @@ const cidAndRest = (path) => {
  * @param {IPLD} ipld
  * @param {ExporterOptions} [options]
  */
-const walkPath = async function * (path, ipld, options = {}) {
+async function * walkPath (path, ipld, options = {}) {
   let {
     cid,
     toResolve
@@ -152,7 +98,7 @@ const walkPath = async function * (path, ipld, options = {}) {
  * @param {IPLD} ipld
  * @param {ExporterOptions} [options]
  */
-const exporter = async (path, ipld, options = {}) => {
+async function exporter (path, ipld, options = {}) {
   const result = await last(walkPath(path, ipld, options))
 
   if (!result) {
@@ -167,7 +113,7 @@ const exporter = async (path, ipld, options = {}) => {
  * @param {IPLD} ipld
  * @param {ExporterOptions} [options]
  */
-const recursive = async function * (path, ipld, options = {}) {
+async function * recursive (path, ipld, options = {}) {
   const node = await exporter(path, ipld, options)
 
   if (!node) {
@@ -202,7 +148,8 @@ const recursive = async function * (path, ipld, options = {}) {
   }
 }
 
-exporter.path = walkPath
-exporter.recursive = recursive
-
-module.exports = exporter
+module.exports = {
+  exporter,
+  walkPath,
+  recursive
+}

packages/ipfs-unixfs-exporter/src/resolvers/dag-cbor.js

@@ -4,7 +4,11 @@ const CID = require('cids')
 const errCode = require('err-code')
 
 /**
- * @type {import('./').Resolver}
+ * @typedef {import('../types').Resolver} Resolver
+ */
+
+/**
+ * @type {Resolver}
  */
 const resolve = async (cid, name, path, toResolve, resolve, depth, ipld, options) => {
   const object = await ipld.get(cid, options)
@@ -29,6 +33,7 @@ const resolve = async (cid, name, path, toResolve, resolve, depth, ipld, options
             cid,
             node: block,
             depth,
+            size: block.data.length,
             content: async function * () {
               yield object
             }
@@ -57,6 +62,7 @@ const resolve = async (cid, name, path, toResolve, resolve, depth, ipld, options
       cid,
       node: block,
       depth,
+      size: block.data.length,
       content: async function * () {
         yield object
       }

packages/ipfs-unixfs-exporter/src/resolvers/identity.js

@@ -6,7 +6,8 @@ const validateOffsetAndLength = require('../utils/validate-offset-and-length')
 const mh = require('multihashing-async').multihash
 
 /**
- * @typedef {import('../').ExporterOptions} ExporterOptions
+ * @typedef {import('../types').ExporterOptions} ExporterOptions
+ * @typedef {import('../types').Resolver} Resolver
  */
 
 /**
@@ -29,7 +30,7 @@ const rawContent = (node) => {
 }
 
 /**
- * @type {import('./').Resolver}
+ * @type {Resolver}
  */
 const resolve = async (cid, name, path, toResolve, resolve, depth, ipld, options) => {
   if (toResolve.length) {
@@ -46,6 +47,7 @@ const resolve = async (cid, name, path, toResolve, resolve, depth, ipld, options
       cid,
       content: rawContent(buf.digest),
       depth,
+      size: buf.length,
       node: buf.digest
     }
   }

packages/ipfs-unixfs-exporter/src/resolvers/index.js

@@ -3,30 +3,15 @@
 const errCode = require('err-code')
 
 /**
- * @typedef {import('ipfs-core-types/src/ipld').IPLD} IPLD
- * @typedef {import('../').ExporterOptions} ExporterOptions
- * @typedef {import('../').UnixFSEntry} UnixFSEntry
  * @typedef {import('cids')} CID
+ * @typedef {import('ipld')} IPLD
+ * @typedef {import('../types').ExporterOptions} ExporterOptions
+ * @typedef {import('../types').UnixFSEntry} UnixFSEntry
+ * @typedef {import('../types').Resolver} Resolver
+ * @typedef {import('../types').Resolve} Resolve
  */
 
 /**
- * @typedef {object} NextResult
- * @property {CID} cid
- * @property {string} name
- * @property {string} path
- * @property {string[]} toResolve
- *
- * @typedef {object} ResolveResult
- * @property {UnixFSEntry} entry
- * @property {NextResult} [next]
- */
-
-/**
- *
- * @typedef {(cid: CID, name: string, path: string, toResolve: string[], depth: number, ipld: IPLD, options: ExporterOptions) => Promise<ResolveResult>} Resolve
- *
- * @typedef {(cid: CID, name: string, path: string, toResolve: string[], resolve: Resolve, depth: number, ipld: IPLD, options: ExporterOptions) => Promise<ResolveResult>} Resolver
- *
  * @type {{ [ key: string ]: Resolver }}
  */
 const resolvers = {

packages/ipfs-unixfs-exporter/src/resolvers/raw.js

@@ -5,7 +5,7 @@ const extractDataFromBlock = require('../utils/extract-data-from-block')
 const validateOffsetAndLength = require('../utils/validate-offset-and-length')
 
 /**
- * @typedef {import('../').ExporterOptions} ExporterOptions
+ * @typedef {import('../types').ExporterOptions} ExporterOptions
  */
 
 /**
@@ -28,7 +28,7 @@ const rawContent = (node) => {
 }
 
 /**
- * @type {import('./').Resolver}
+ * @type {import('../types').Resolver}
  */
 const resolve = async (cid, name, path, toResolve, resolve, depth, ipld, options) => {
   if (toResolve.length) {
@@ -45,6 +45,7 @@ const resolve = async (cid, name, path, toResolve, resolve, depth, ipld, options
       cid,
       content: rawContent(buf),
       depth,
+      size: buf.length,
       node: buf
     }
   }

packages/ipfs-unixfs-exporter/src/resolvers/unixfs-v1/content/directory.js

@@ -1,10 +1,13 @@
 'use strict'
 
 /**
- * @typedef {import('../../../').ExporterOptions} ExporterOptions
- * @typedef {import('../').UnixfsV1DirectoryContent} UnixfsV1DirectoryContent
- *
- * @type {import('../').UnixfsV1Resolver}
+ * @typedef {import('../../../types').ExporterOptions} ExporterOptions
+ * @typedef {import('../../../types').UnixfsV1DirectoryContent} UnixfsV1DirectoryContent
+ * @typedef {import('../../../types').UnixfsV1Resolver} UnixfsV1Resolver
+ */
+
+/**
+ * @type {UnixfsV1Resolver}
  */
 const directoryContent = (cid, node, unixfs, path, resolve, depth, ipld) => {
   /**

packages/ipfs-unixfs-exporter/src/resolvers/unixfs-v1/content/file.js

@@ -2,14 +2,16 @@
 
 const extractDataFromBlock = require('../../../utils/extract-data-from-block')
 const validateOffsetAndLength = require('../../../utils/validate-offset-and-length')
-const UnixFS = require('ipfs-unixfs')
+const { UnixFS } = require('ipfs-unixfs')
 const errCode = require('err-code')
 
 /**
- * @typedef {import('../../../').ExporterOptions} ExporterOptions
- * @typedef {import('ipfs-core-types/src/ipld').IPLD} IPLD
+ * @typedef {import('../../../types').ExporterOptions} ExporterOptions
+ * @typedef {import('ipld')} IPLD
  * @typedef {import('ipld-dag-pb').DAGNode} DAGNode
- *
+ */
+
+/**
  * @param {IPLD} ipld
  * @param {DAGNode} node
  * @param {number} start
@@ -62,8 +64,7 @@ async function * emitBytes (ipld, node, start, end, streamPosition = 0, options)
         (end > childStart && end <= childEnd) || // child has end byte
         (start < childStart && end > childEnd)) { // child is between offset and end bytes
       const child = await ipld.get(childLink.Hash, {
-        signal: options.signal,
-        timeout: options.timeout
+        signal: options.signal
       })
 
       for await (const buf of emitBytes(ipld, child, start, end, streamPosition, options)) {