Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

182 lines (135 sloc) 4.5 KB

Refs API

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)

ipfs.refs.local([callback])

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

Output all local references using a Readable Stream

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

Output all local references using a Pull Stream.

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.

You can’t perform that action at this time.