REFS.md

Refs API

• refs
• refsReadableStream
• refsPullStream
• refs.local
• refs.localReadableStream
• refs.localPullStream

refs

Get links (references) from an object.

ipfs.refs(ipfsPath, [options], [callback])

ipfsPath can be of type:

• cid of type:
  • a CID instance
  • Buffer, the raw Buffer of the cid
  • String, the base58 encoded version of the cid
• String, including the ipfs handler, a cid and a path to traverse to, ie:
  • '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66'
  • '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
  • 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'

options is an optional object that may contain the following keys:

• recursive (false): recursively list references of child nodes
• unique (false): omit duplicate references from output
• format ("<dst>"): output edges with given format. Available tokens: <src>, <dst>, <linkname>
• edges (false): output references in edge format: "<src> -> <dst>"
• maxDepth (1): only for recursive refs, limits fetch and listing to the given depth

callback must follow function (err, refs) {} signature, where err is an error if the operation was not successful and refs is an array of { ref: "myref", err: "error msg" }

If no callback is passed, a promise is returned.

Example:

ipfs.refs(ipfsPath, { recursive: true }, function (err, refs) {
  if (err) {
    throw err
  }

  for (const ref of refs) {
    if (ref.err) {
      console.error(ref.err)
    } else {
      console.log(ref.ref)
      // output: "QmHash"
    }
  }
})

refsReadableStream

Output references using a Readable Stream

ipfs.refsReadableStream(ipfsPath, [options]) -> Readable Stream

options is an optional object argument identical to the options for ipfs.refs

Example:

const stream = ipfs.refsReadableStream(ipfsPath, { recursive: true })
stream.on('data', function (ref) {
  // 'ref' will be of the form
  // {
  //   ref: 'QmHash',
  //   err: 'err message'
  // }
})

refsPullStream

Output references using a Pull Stream.

ipfs.refsReadableStream(ipfsPath, [options]) -> Pull Stream

options is an optional object argument identical to the options for ipfs.refs

Example:

const stream = ipfs.refsPullStream(ipfsPath, { recursive: true })

pull(
  stream,
  pull.collect((err, values) => {
    // values will be an array of objects, each one of the form
    // {
    //   ref: 'QmHash',
    //   err: 'err message'
    // }
  })
)

refs.local

Output all local references (CIDs of all blocks in the blockstore. CIDs are reconstructed, hence they might not match the CIDs under the blocks were originally stored)

ipfs.refs.local([options], [callback])

options is an optional object that may contain the following keys:

• multihash (false): instead of reconstructed CIDs, the original multihashes are returned as base32 encoded strings

callback must follow function (err, refs) {} signature, where err is an error if the operation was not successful and refs is an array of { ref: "myref", err: "error msg" }

If no callback is passed, a promise is returned.

Example:

ipfs.refs.local(function (err, refs) {
  if (err) {
    throw err
  }

  for (const ref of refs) {
    if (ref.err) {
      console.error(ref.err)
    } else {
      console.log(ref.ref)
      // output: "QmHash"
    }
  }
})

refs.localReadableStream([options])

Output all local references using a Readable Stream

options is an optional object that may contain the following keys:

• multihash (false): instead of reconstructed CIDs, the original multihashes are returned as base32 encoded strings

ipfs.localReadableStream() -> Readable Stream

Example:

const stream = ipfs.refs.localReadableStream()
stream.on('data', function (ref) {
  // 'ref' will be of the form
  // {
  //   ref: 'QmHash',
  //   err: 'err message'
  // }
})

refs.localPullStream([options])

Output all local references using a Pull Stream.

options is an optional object that may contain the following keys:

• multihash (false): instead of reconstructed CIDs, the original multihashes are returned as base32 encoded strings

ipfs.refs.localReadableStream() -> Pull Stream

Example:

const stream = ipfs.refs.localPullStream()

pull(
  stream,
  pull.collect((err, values) => {
    // values will be an array of objects, each one of the form
    // {
    //   ref: 'QmHash',
    //   err: 'err message'
    // }
  })
)

A great source of examples can be found in the tests for this API.