Skip to content

Commit

Permalink
chore: declare interface types in .d.ts file
Browse files Browse the repository at this point in the history
- 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
  • Loading branch information
achingbrain committed Mar 13, 2021
1 parent 9a2b5f2 commit b8a4512
Show file tree
Hide file tree
Showing 60 changed files with 619 additions and 544 deletions.
1 change: 0 additions & 1 deletion .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,6 @@ jobs:
- stage: check
name: linting
script:
- npm --version
- npm run lint

- stage: check
Expand Down
26 changes: 15 additions & 11 deletions packages/ipfs-unixfs-exporter/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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 = []

Expand Down Expand Up @@ -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)`
Expand Down Expand Up @@ -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)
}

Expand Down
19 changes: 11 additions & 8 deletions packages/ipfs-unixfs-exporter/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,11 @@
"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",
Expand All @@ -35,18 +36,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",
Expand Down
83 changes: 17 additions & 66 deletions packages/ipfs-unixfs-exporter/src/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -6,66 +6,16 @@ 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').UnixFSFile} UnixFSFile
* @typedef {import('./types').UnixFSDirectory} UnixFSDirectory
* @typedef {import('./types').ObjectNode} ObjectNode
* @typedef {import('./types').RawNode} RawNode
* @typedef {import('./types').IdentityNode} IdentityNode
* @typedef {import('./types').UnixFSEntry} UnixFSEntry
*/

const toPathComponents = (path = '') => {
Expand Down Expand Up @@ -115,7 +65,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
Expand Down Expand Up @@ -152,7 +102,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) {
Expand All @@ -167,7 +117,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) {
Expand Down Expand Up @@ -202,7 +152,8 @@ const recursive = async function * (path, ipld, options = {}) {
}
}

exporter.path = walkPath
exporter.recursive = recursive

module.exports = exporter
module.exports = {
exporter,
walkPath,
recursive
}
8 changes: 7 additions & 1 deletion packages/ipfs-unixfs-exporter/src/resolvers/dag-cbor.js
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -29,6 +33,7 @@ const resolve = async (cid, name, path, toResolve, resolve, depth, ipld, options
cid,
node: block,
depth,
size: block.length,
content: async function * () {
yield object
}
Expand Down Expand Up @@ -57,6 +62,7 @@ const resolve = async (cid, name, path, toResolve, resolve, depth, ipld, options
cid,
node: block,
depth,
size: block.length,
content: async function * () {
yield object
}
Expand Down
6 changes: 4 additions & 2 deletions packages/ipfs-unixfs-exporter/src/resolvers/identity.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/

/**
Expand All @@ -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) {
Expand All @@ -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
}
}
Expand Down
25 changes: 5 additions & 20 deletions packages/ipfs-unixfs-exporter/src/resolvers/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down
5 changes: 3 additions & 2 deletions packages/ipfs-unixfs-exporter/src/resolvers/raw.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/

/**
Expand All @@ -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) {
Expand All @@ -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
}
}
Expand Down
Original file line number Diff line number Diff line change
@@ -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) => {
/**
Expand Down
Loading

0 comments on commit b8a4512

Please sign in to comment.