Skip to content
This repository was archived by the owner on Mar 10, 2020. It is now read-only.

add level option to ipfs.dag.tree #137

Closed
wanderer opened this issue Apr 26, 2017 · 1 comment · Fixed by ipld/js-ipld#191
Closed

add level option to ipfs.dag.tree #137

wanderer opened this issue Apr 26, 2017 · 1 comment · Fixed by ipld/js-ipld#191
Labels
difficulty:moderate help wanted P1 - High

Comments

@wanderer
Copy link

wanderer commented Apr 26, 2017 •
edited
Loading

a level options would specify the number of levels to fetch in a tree. This could replace the recusive options. Since you could (in JS) use Infinity

This type of thing was implemented in js-ipld-graph-builder

@jbenet @diasdavid
@daviddias
Copy link
Contributor

@vmx ^^

@daviddias daviddias mentioned this issue Nov 20, 2018
Merged
@vmx vmx mentioned this issue Nov 20, 2018
Closed
vmx added a commit to ipld/js-ipld that referenced this issue Nov 22, 2018
@vmx
Major API changes
3375a4d 
The whole IPLD APIs get a review to make them more consistent and
easier to use.

Changes to compared to the current spec:

 - No more callbacks, everything is Promises.
 - `get()`:
   - Is renamed to `resolve()` to indicate that it also takes a mandatory
     path argument.
   - Doesn’t have a `cid` in the return value anymore. That use case is
     covered by returning all objects that were traversed. Their `value`
     will always be the CID of the next one to traverse. So if you want
     to know the CID of the current IPLD Node, just look at the `value`
     of the previously returned IPLD Node.
   - Doesn’t return a single value, but an iterator.
   - `localResolve` option is removed. If you want to resolve a single IPLD
      Node only, just stop the iterator after the first item.
 - `getStream()` is removed without replacement. Use `resolve()` which uses
    async iterators instead.
 - `getMany()` is renamed to `get()`:
   - takes an iterable of CIDs as parameter.
 - `put()`:
   - takes an iterable of CIDs as parameter.
   - Doesn’t take `cid` as an option anymore. The CID is always calculated
     (#175).
   - The options don’t take the `format` (which is a string), but the `codec`
     (which is a `multicodec`) (#175).
   - the `version` option always defaults to `1`.
 - `.treeStream()` is removed without replacement (the only current user seems
   to be the IPFS DAG API tree command and the ipld-explorer-cli). IPLD Nodes
   are just normal JavaScript objects, so you can call `Object.keys()`
   recursively on a IPLD Node to get all its resolvable paths. If you want to
   follow all the CIDs, write the tree traversal yourself. This could perhaps
   be an example bundled with js-ipld.
 - `remove()`:
   - takes an iterable of CIDs as parameter.
 - `.support.add()` is renamed to `.addFormat()`.
 - `.support.rm()` is renamed to `.removeFormat()`.

Almost all open issues in regards to the IPLD API got adressed. One bigger
thing is the Patch API, which also isn’t part of the current specification.
Here’s an overview of the issues:

 - #66
   - [ ] IPLD Resolver `patch` API: There is no patch API yet
 - #70
   - [x] lazu value lookups: Can be done as IPLD Formats is pure JavaScript
   - [x] get external / local paths only: @vmx doesn’t know what this is,
         considers it a “won’t fix”
   - [x] toJSON + fromJSON - roundtrip: A roundtrip is not a goal anymore
         => won’t fix
   - [ ] put + patch api #66: Patch API is still missing
   - [x] text summary: @vmx doesn’t see a strong use case for this => “won’t fix”
   - [x] globbing: Out of scope for js-ipld
 - #175
   - [x] Deprecate passing a CID to `ipld.put`?: Current spec doesn’t allow
         `put()` with a CID
 - #182
   - [x] API Review: Links to many other issues, I list the individual issues
         below
 - #183
   - [x] getting the merkle proof with resolver.resolve: `resolve()` returns
         all CIDs along the traversed path
 - #184
   - [ ] Pass down the `options` object to resolver.resolve(): This needs a
         custom resolver. @vmx isn’t sure if the js-ipld API should make this
         possible, or of it should just be easy enough to create your own
         resolver.
 - https://github.com/ipfs/interface-ipfs-core/issues/81
   - [x] The `dag` API - One API to manipulate all the IPLD Format objects:
         Interesting discussion, but not relevant anymore.
 - ipfs-inactive/interface-js-ipfs-core#121
   - [x] dag api: add {ls, tree}: `tree()` is not part of js-ipld anymore as
         the IPLD Nodes are just JavaScript objects which you can easily traverse
         if you like. Though `tree()`-like functionality might be added as an
         example or separate module.
 - ipfs-inactive/interface-js-ipfs-core#125
   - [x] `dag get --localResolve` vs `dag resolve`: This is solved by the new
         `resolve()` API
 - ipfs-inactive/interface-js-ipfs-core#137
   - [x] add `level` option to ipfs.dag.tree: `tree()` is not part of js-ipld
         anymore. It should be considered if `tree()` is implemented (probably
         as an example or separate module)

Closes #182.
@vmx vmx mentioned this issue Nov 22, 2018
Closed
15 tasks
vmx added a commit to ipld/js-ipld that referenced this issue Nov 26, 2018
@vmx
docs: major API changes
5139f53 
The whole IPLD APIs get a review to make them more consistent and
easier to use.

Changes to compared to the current spec:

 - No more callbacks, everything is Promises.
 - `get()`:
   - Is renamed to `resolve()` to indicate that it also takes a mandatory
     path argument.
   - Doesn’t have a `cid` in the return value anymore. That use case is
     covered by returning all objects that were traversed. Their `value`
     will always be the CID of the next one to traverse. So if you want
     to know the CID of the current IPLD Node, just look at the `value`
     of the previously returned IPLD Node.
   - Doesn’t return a single value, but an iterator.
   - `localResolve` option is removed. If you want to resolve a single IPLD
      Node only, just stop the iterator after the first item.
 - `getStream()` is removed without replacement. Use `resolve()` which uses
    async iterators instead.
 - `getMany()` is renamed to `get()`:
   - takes an iterable of CIDs as parameter.
 - `put()`:
   - takes an iterable of CIDs as parameter.
   - Doesn’t take `cid` as an option anymore. The CID is always calculated
     (#175).
   - The options don’t take the `format` (which is a string), but the `codec`
     (which is a `multicodec`) (#175).
   - the `version` option always defaults to `1`.
 - `.treeStream()` is removed without replacement (the only current user seems
   to be the IPFS DAG API tree command and the ipld-explorer-cli). IPLD Nodes
   are just normal JavaScript objects, so you can call `Object.keys()`
   recursively on a IPLD Node to get all its resolvable paths. If you want to
   follow all the CIDs, write the tree traversal yourself. This could perhaps
   be an example bundled with js-ipld.
 - `remove()`:
   - takes an iterable of CIDs as parameter.
 - `.support.add()` is renamed to `.addFormat()`.
 - `.support.rm()` is renamed to `.removeFormat()`.

Almost all open issues in regards to the IPLD API got adressed. One bigger
thing is the Patch API, which also isn’t part of the current specification.
Here’s an overview of the issues:

 - #66
   - [ ] IPLD Resolver `patch` API: There is no patch API yet
 - #70
   - [x] lazu value lookups: Can be done as IPLD Formats is pure JavaScript
   - [x] get external / local paths only: @vmx doesn’t know what this is,
         considers it a “won’t fix”
   - [x] toJSON + fromJSON - roundtrip: A roundtrip is not a goal anymore
         => won’t fix
   - [ ] put + patch api #66: Patch API is still missing
   - [x] text summary: @vmx doesn’t see a strong use case for this => “won’t fix”
   - [x] globbing: Out of scope for js-ipld
 - #175
   - [x] Deprecate passing a CID to `ipld.put`?: Current spec doesn’t allow
         `put()` with a CID
 - #182
   - [x] API Review: Links to many other issues, I list the individual issues
         below
 - #183
   - [x] getting the merkle proof with resolver.resolve: `resolve()` returns
         all CIDs along the traversed path
 - #184
   - [ ] Pass down the `options` object to resolver.resolve(): This needs a
         custom resolver. @vmx isn’t sure if the js-ipld API should make this
         possible, or of it should just be easy enough to create your own
         resolver.
 - https://github.com/ipfs/interface-ipfs-core/issues/81
   - [x] The `dag` API - One API to manipulate all the IPLD Format objects:
         Interesting discussion, but not relevant anymore.
 - ipfs-inactive/interface-js-ipfs-core#121
   - [x] dag api: add {ls, tree}: `tree()` is not part of js-ipld anymore as
         the IPLD Nodes are just JavaScript objects which you can easily traverse
         if you like. Though `tree()`-like functionality might be added as an
         example or separate module.
 - ipfs-inactive/interface-js-ipfs-core#125
   - [x] `dag get --localResolve` vs `dag resolve`: This is solved by the new
         `resolve()` API
 - ipfs-inactive/interface-js-ipfs-core#137
   - [x] add `level` option to ipfs.dag.tree: `tree()` is not part of js-ipld
         anymore. It should be considered if `tree()` is implemented (probably
         as an example or separate module)

Closes #182.
vmx added a commit to ipld/js-ipld that referenced this issue Feb 7, 2019
@vmx
docs: major API changes
4b68189 
The whole IPLD APIs get a review to make them more consistent and
easier to use.

Changes to compared to the current spec:

 - No more callbacks, everything is Promises.
 - `get()`:
   - Is renamed to `resolve()` to indicate that it also takes a mandatory
     path argument.
   - Doesn’t have a `cid` in the return value anymore. That use case is
     covered by returning all objects that were traversed. Their `value`
     will always be the CID of the next one to traverse. So if you want
     to know the CID of the current IPLD Node, just look at the `value`
     of the previously returned IPLD Node.
   - Doesn’t return a single value, but an iterator.
   - `localResolve` option is removed. If you want to resolve a single IPLD
      Node only, just stop the iterator after the first item.
 - `getStream()` is removed without replacement. Use `resolve()` which uses
    async iterators instead.
 - `getMany()` is renamed to `get()`:
   - takes an iterable of CIDs as parameter.
 - `put()`:
   - takes an iterable of CIDs as parameter.
   - Doesn’t take `cid` as an option anymore. The CID is always calculated
     (#175).
   - The options don’t take the `format` (which is a string), but the `codec`
     (which is a `multicodec`) (#175).
   - the `cidVersion` option always defaults to `1`.
 - `.treeStream()` is renamed to `.tree()` and returns an async iterator.
 - `remove()`:
   - takes an iterable of CIDs as parameter.
 - `.support.add()` is renamed to `.addFormat()`.
 - `.support.rm()` is renamed to `.removeFormat()`.
 - `options.loadFormat()` is no longer callback based but is using an async
   function.

Almost all open issues in regards to the IPLD API got adressed. One bigger
thing is the Patch API, which also isn’t part of the current specification.
Here’s an overview of the issues:

 - #66
   - [ ] IPLD Resolver `patch` API: There is no patch API yet
 - #70
   - [x] lazy value lookups: Can be done as IPLD Formats is pure JavaScript
   - [x] get external / local paths only: @vmx doesn’t know what this is,
         considers it a “won’t fix”
   - [x] toJSON + fromJSON - roundtrip: A roundtrip is not a goal anymore
         => won’t fix
   - [ ] put + patch api #66: Patch API is still missing
   - [x] text summary: @vmx doesn’t see a strong use case for this => “won’t fix”
   - [x] globbing: Out of scope for js-ipld
 - #175
   - [x] Deprecate passing a CID to `ipld.put`?: Current spec doesn’t allow
         `put()` with a CID
 - #182
   - [x] API Review: Links to many other issues, I list the individual issues
         below
 - #183
   - [x] getting the merkle proof with resolver.resolve: `resolve()` returns
         all CIDs along the traversed path
 - #184
   - [ ] Pass down the `options` object to resolver.resolve(): This needs a
         custom resolver. @vmx isn’t sure if the js-ipld API should make this
         possible, or of it should just be easy enough to create your own
         resolver.
 - https://github.com/ipfs/interface-ipfs-core/issues/81
   - [x] The `dag` API - One API to manipulate all the IPLD Format objects:
         Interesting discussion, but not relevant anymore.
 - ipfs-inactive/interface-js-ipfs-core#121
   - [x] dag api: add {ls, tree}: `tree()` is not part of js-ipld anymore as
         the IPLD Nodes are just JavaScript objects which you can easily traverse
         if you like. Though `tree()`-like functionality might be added as an
         example or separate module.
 - ipfs-inactive/interface-js-ipfs-core#125
   - [x] `dag get --localResolve` vs `dag resolve`: This is solved by the new
         `resolve()` API
 - ipfs-inactive/interface-js-ipfs-core#137
   - [x] add `level` option to ipfs.dag.tree: `tree()` is not part of js-ipld
         anymore. It should be considered if `tree()` is implemented (probably
         as an example or separate module)

Closes #70, #175, #182, #183
Closes ipfs-inactive/interface-js-ipfs-core#121
Closes ipfs-inactive/interface-js-ipfs-core#125
Closed ipfs-inactive/interface-js-ipfs-core#137
@vmx vmx mentioned this issue Feb 7, 2019
Merged
15 tasks
vmx added a commit to ipld/js-ipld that referenced this issue Feb 21, 2019
@vmx
docs: major API changes
f5fa4ce 
The whole IPLD APIs get a review to make them more consistent and
easier to use.

Changes to compared to the current spec:

 - No more callbacks, everything is Promises.
 - `get()`:
   - Is renamed to `resolve()` to indicate that it also takes a mandatory
     path argument.
   - Doesn’t have a `cid` in the return value anymore. That use case is
     covered by returning all objects that were traversed. Their `value`
     will always be the CID of the next one to traverse. So if you want
     to know the CID of the current IPLD Node, just look at the `value`
     of the previously returned IPLD Node.
   - Doesn’t return a single value, but an iterator.
   - `localResolve` option is removed. If you want to resolve a single IPLD
      Node only, just stop the iterator after the first item.
 - `getStream()` is removed without replacement. Use `resolve()` which uses
    async iterators instead.
 - `getMany()` is renamed to `get()`:
   - takes an iterable of CIDs as parameter.
 - `put()`:
   - takes an iterable of CIDs as parameter.
   - Doesn’t take `cid` as an option anymore. The CID is always calculated
     (#175).
   - The options don’t take the `format` (which is a string), but the `codec`
     (which is a `multicodec`) (#175).
   - the `cidVersion` option always defaults to `1`.
 - `.treeStream()` is renamed to `.tree()` and returns an async iterator.
 - `remove()`:
   - takes an iterable of CIDs as parameter.
 - `.support.add()` is renamed to `.addFormat()`.
 - `.support.rm()` is renamed to `.removeFormat()`.
 - `options.loadFormat()` is no longer callback based but is using an async
   function.

Almost all open issues in regards to the IPLD API got adressed. One bigger
thing is the Patch API, which also isn’t part of the current specification.
Here’s an overview of the issues:

 - #66
   - [ ] IPLD Resolver `patch` API: There is no patch API yet
 - #70
   - [x] lazy value lookups: Can be done as IPLD Formats is pure JavaScript
   - [x] get external / local paths only: @vmx doesn’t know what this is,
         considers it a “won’t fix”
   - [x] toJSON + fromJSON - roundtrip: A roundtrip is not a goal anymore
         => won’t fix
   - [ ] put + patch api #66: Patch API is still missing
   - [x] text summary: @vmx doesn’t see a strong use case for this => “won’t fix”
   - [x] globbing: Out of scope for js-ipld
 - #175
   - [x] Deprecate passing a CID to `ipld.put`?: Current spec doesn’t allow
         `put()` with a CID
 - #182
   - [x] API Review: Links to many other issues, I list the individual issues
         below
 - #183
   - [x] getting the merkle proof with resolver.resolve: `resolve()` returns
         all CIDs along the traversed path
 - #184
   - [ ] Pass down the `options` object to resolver.resolve(): This needs a
         custom resolver. @vmx isn’t sure if the js-ipld API should make this
         possible, or of it should just be easy enough to create your own
         resolver.
 - https://github.com/ipfs/interface-ipfs-core/issues/81
   - [x] The `dag` API - One API to manipulate all the IPLD Format objects:
         Interesting discussion, but not relevant anymore.
 - ipfs-inactive/interface-js-ipfs-core#121
   - [x] dag api: add {ls, tree}: `tree()` is not part of js-ipld anymore as
         the IPLD Nodes are just JavaScript objects which you can easily traverse
         if you like. Though `tree()`-like functionality might be added as an
         example or separate module.
 - ipfs-inactive/interface-js-ipfs-core#125
   - [x] `dag get --localResolve` vs `dag resolve`: This is solved by the new
         `resolve()` API
 - ipfs-inactive/interface-js-ipfs-core#137
   - [x] add `level` option to ipfs.dag.tree: `tree()` is not part of js-ipld
         anymore. It should be considered if `tree()` is implemented (probably
         as an example or separate module)

Closes #70, #175, #182, #183
Closes ipfs-inactive/interface-js-ipfs-core#121
Closes ipfs-inactive/interface-js-ipfs-core#125
Closed ipfs-inactive/interface-js-ipfs-core#137
vmx added a commit to ipld/js-ipld that referenced this issue Mar 18, 2019
@vmx
docs: major API changes
459c22d 
The whole IPLD APIs get a review to make them more consistent and
easier to use.

Changes to compared to the current spec:

 - No more callbacks, everything is Promises.
 - `get()`:
   - Is renamed to `resolve()` to indicate that it also takes a mandatory
     path argument.
   - Doesn’t have a `cid` in the return value anymore. That use case is
     covered by returning all objects that were traversed. Their `value`
     will always be the CID of the next one to traverse. So if you want
     to know the CID of the current IPLD Node, just look at the `value`
     of the previously returned IPLD Node.
   - Doesn’t return a single value, but an iterator.
   - `localResolve` option is removed. If you want to resolve a single IPLD
      Node only, just stop the iterator after the first item.
 - `getStream()` is removed without replacement. Use `resolve()` which uses
    async iterators instead.
 - `getMany()` takes an iterable as input now.
 - `put()`:
   - Doesn’t take `cid` as an option anymore. The CID is always calculated
     (#175).
   - The options don’t take the `format` (which is a string), but the `codec`
     (which is a `multicodec`) (#175).
   - the `cidVersion` option always defaults to `1`.
 - `.treeStream()` is renamed to `.tree()` and returns an async iterator.
 - `.support.add()` is renamed to `.addFormat()`.
 - `.support.rm()` is renamed to `.removeFormat()`.
 - `options.loadFormat()` is no longer callback based but is using an async
   function.
 - `putMany()` and `removeMany()` are introduced which both take an iterable
   as input.

Almost all open issues in regards to the IPLD API got adressed. One bigger
thing is the Patch API, which also isn’t part of the current specification.
Here’s an overview of the issues:

 - #66
   - [ ] IPLD Resolver `patch` API: There is no patch API yet
 - #70
   - [x] lazy value lookups: Can be done as IPLD Formats is pure JavaScript
   - [x] get external / local paths only: @vmx doesn’t know what this is,
         considers it a “won’t fix”
   - [x] toJSON + fromJSON - roundtrip: A roundtrip is not a goal anymore
         => won’t fix
   - [ ] put + patch api #66: Patch API is still missing
   - [x] text summary: @vmx doesn’t see a strong use case for this => “won’t fix”
   - [x] globbing: Out of scope for js-ipld
 - #175
   - [x] Deprecate passing a CID to `ipld.put`?: Current spec doesn’t allow
         `put()` with a CID
 - #182
   - [x] API Review: Links to many other issues, I list the individual issues
         below
 - #183
   - [x] getting the merkle proof with resolver.resolve: `resolve()` returns
         all CIDs along the traversed path
 - #184
   - [ ] Pass down the `options` object to resolver.resolve(): This needs a
         custom resolver. @vmx isn’t sure if the js-ipld API should make this
         possible, or of it should just be easy enough to create your own
         resolver.
 - https://github.com/ipfs/interface-ipfs-core/issues/81
   - [x] The `dag` API - One API to manipulate all the IPLD Format objects:
         Interesting discussion, but not relevant anymore.
 - ipfs-inactive/interface-js-ipfs-core#121
   - [x] dag api: add {ls, tree}: `tree()` is not part of js-ipld anymore as
         the IPLD Nodes are just JavaScript objects which you can easily traverse
         if you like. Though `tree()`-like functionality might be added as an
         example or separate module.
 - ipfs-inactive/interface-js-ipfs-core#125
   - [x] `dag get --localResolve` vs `dag resolve`: This is solved by the new
         `resolve()` API
 - ipfs-inactive/interface-js-ipfs-core#137
   - [x] add `level` option to ipfs.dag.tree: `tree()` is not part of js-ipld
         anymore. It should be considered if `tree()` is implemented (probably
         as an example or separate module)

Closes #70, #175, #182, #183
Closes ipfs-inactive/interface-js-ipfs-core#121
Closes ipfs-inactive/interface-js-ipfs-core#125
Closed ipfs-inactive/interface-js-ipfs-core#137
vmx added a commit to ipld/js-ipld that referenced this issue Mar 18, 2019
@vmx
docs: major API changes
103ba9f 
The whole IPLD APIs get a review to make them more consistent and
easier to use.

Changes to compared to the current spec:

 - No more callbacks, everything is Promises.
 - `get()`:
   - Is renamed to `resolve()` to indicate that it also takes a mandatory
     path argument.
   - Doesn’t have a `cid` in the return value anymore. That use case is
     covered by returning all objects that were traversed. Their `value`
     will always be the CID of the next one to traverse. So if you want
     to know the CID of the current IPLD Node, just look at the `value`
     of the previously returned IPLD Node.
   - Doesn’t return a single value, but an iterator.
   - `localResolve` option is removed. If you want to resolve a single IPLD
      Node only, just stop the iterator after the first item.
 - `getStream()` is removed without replacement. Use `resolve()` which uses
    async iterators instead.
 - `getMany()` takes an iterable as input now.
 - `put()`:
   - Doesn’t take `cid` as an option anymore. The CID is always calculated
     (#175).
   - The options don’t take the `format` (which is a string), but the `codec`
     (which is a `multicodec`) (#175).
   - the `cidVersion` option always defaults to `1`.
 - `.treeStream()` is renamed to `.tree()` and returns an async iterator.
 - `.support.add()` is renamed to `.addFormat()`.
 - `.support.rm()` is renamed to `.removeFormat()`.
 - `options.loadFormat()` is no longer callback based but is using an async
   function.
 - `putMany()` and `removeMany()` are introduced which both take an iterable
   as input.

Almost all open issues in regards to the IPLD API got adressed. One bigger
thing is the Patch API, which also isn’t part of the current specification.
Here’s an overview of the issues:

 - #66
   - [ ] IPLD Resolver `patch` API: There is no patch API yet
 - #70
   - [x] lazy value lookups: Can be done as IPLD Formats is pure JavaScript
   - [x] get external / local paths only: @vmx doesn’t know what this is,
         considers it a “won’t fix”
   - [x] toJSON + fromJSON - roundtrip: A roundtrip is not a goal anymore
         => won’t fix
   - [ ] put + patch api #66: Patch API is still missing
   - [x] text summary: @vmx doesn’t see a strong use case for this => “won’t fix”
   - [x] globbing: Out of scope for js-ipld
 - #175
   - [x] Deprecate passing a CID to `ipld.put`?: Current spec doesn’t allow
         `put()` with a CID
 - #182
   - [x] API Review: Links to many other issues, I list the individual issues
         below
 - #183
   - [x] getting the merkle proof with resolver.resolve: `resolve()` returns
         all CIDs along the traversed path
 - #184
   - [ ] Pass down the `options` object to resolver.resolve(): This needs a
         custom resolver. @vmx isn’t sure if the js-ipld API should make this
         possible, or of it should just be easy enough to create your own
         resolver.
 - https://github.com/ipfs/interface-ipfs-core/issues/81
   - [x] The `dag` API - One API to manipulate all the IPLD Format objects:
         Interesting discussion, but not relevant anymore.
 - ipfs-inactive/interface-js-ipfs-core#121
   - [x] dag api: add {ls, tree}: `tree()` is not part of js-ipld anymore as
         the IPLD Nodes are just JavaScript objects which you can easily traverse
         if you like. Though `tree()`-like functionality might be added as an
         example or separate module.
 - ipfs-inactive/interface-js-ipfs-core#125
   - [x] `dag get --localResolve` vs `dag resolve`: This is solved by the new
         `resolve()` API
 - ipfs-inactive/interface-js-ipfs-core#137
   - [x] add `level` option to ipfs.dag.tree: `tree()` is not part of js-ipld
         anymore. It should be considered if `tree()` is implemented (probably
         as an example or separate module)

Closes #70, #175, #182, #183
Closes ipfs-inactive/interface-js-ipfs-core#121
Closes ipfs-inactive/interface-js-ipfs-core#125
Closed ipfs-inactive/interface-js-ipfs-core#137
vmx added a commit to ipld/js-ipld that referenced this issue Mar 19, 2019
@vmx
docs: major API changes
3cbd7e8 
The whole IPLD APIs get a review to make them more consistent and
easier to use.

Changes to compared to the current spec:

 - No more callbacks, everything is Promises.
 - `get()`:
   - Is renamed to `resolve()` to indicate that it also takes a mandatory
     path argument.
   - Doesn’t have a `cid` in the return value anymore. That use case is
     covered by returning all objects that were traversed. Their `value`
     will always be the CID of the next one to traverse. So if you want
     to know the CID of the current IPLD Node, just look at the `value`
     of the previously returned IPLD Node.
   - Doesn’t return a single value, but an iterator.
   - `localResolve` option is removed. If you want to resolve a single IPLD
      Node only, just stop the iterator after the first item.
 - `getStream()` is removed without replacement. Use `resolve()` which uses
    async iterators instead.
 - `getMany()` takes an iterable as input now.
 - `put()`:
   - Doesn’t take `cid` as an option anymore. The CID is always calculated
     (#175).
   - The options don’t take the `format` (which is a string), but the `codec`
     (which is a `multicodec`) (#175).
   - the `cidVersion` option always defaults to `1`.
 - `.treeStream()` is renamed to `.tree()` and returns an async iterator.
 - `.support.add()` is renamed to `.addFormat()`.
 - `.support.rm()` is renamed to `.removeFormat()`.
 - `options.loadFormat()` is no longer callback based but is using an async
   function.
 - `putMany()` and `removeMany()` are introduced which both take an iterable
   as input.

Almost all open issues in regards to the IPLD API got adressed. One bigger
thing is the Patch API, which also isn’t part of the current specification.
Here’s an overview of the issues:

 - #66
   - [ ] IPLD Resolver `patch` API: There is no patch API yet
 - #70
   - [x] lazy value lookups: Can be done as IPLD Formats is pure JavaScript
   - [x] get external / local paths only: @vmx doesn’t know what this is,
         considers it a “won’t fix”
   - [x] toJSON + fromJSON - roundtrip: A roundtrip is not a goal anymore
         => won’t fix
   - [ ] put + patch api #66: Patch API is still missing
   - [x] text summary: @vmx doesn’t see a strong use case for this => “won’t fix”
   - [x] globbing: Out of scope for js-ipld
 - #175
   - [x] Deprecate passing a CID to `ipld.put`?: Current spec doesn’t allow
         `put()` with a CID
 - #182
   - [x] API Review: Links to many other issues, I list the individual issues
         below
 - #183
   - [x] getting the merkle proof with resolver.resolve: `resolve()` returns
         all CIDs along the traversed path
 - #184
   - [ ] Pass down the `options` object to resolver.resolve(): This needs a
         custom resolver. @vmx isn’t sure if the js-ipld API should make this
         possible, or of it should just be easy enough to create your own
         resolver.
 - https://github.com/ipfs/interface-ipfs-core/issues/81
   - [x] The `dag` API - One API to manipulate all the IPLD Format objects:
         Interesting discussion, but not relevant anymore.
 - ipfs-inactive/interface-js-ipfs-core#121
   - [x] dag api: add {ls, tree}: `tree()` is not part of js-ipld anymore as
         the IPLD Nodes are just JavaScript objects which you can easily traverse
         if you like. Though `tree()`-like functionality might be added as an
         example or separate module.
 - ipfs-inactive/interface-js-ipfs-core#125
   - [x] `dag get --localResolve` vs `dag resolve`: This is solved by the new
         `resolve()` API
 - ipfs-inactive/interface-js-ipfs-core#137
   - [x] add `level` option to ipfs.dag.tree: `tree()` is not part of js-ipld
         anymore. It should be considered if `tree()` is implemented (probably
         as an example or separate module)

Closes #70, #175, #182, #183
Closes ipfs-inactive/interface-js-ipfs-core#121
Closes ipfs-inactive/interface-js-ipfs-core#125
Closed ipfs-inactive/interface-js-ipfs-core#137
vmx added a commit to ipld/js-ipld that referenced this issue Mar 21, 2019
@vmx
docs: major API changes
47a8dd1 
The whole IPLD APIs get a review to make them more consistent and
easier to use.

Changes to compared to the current spec:

 - No more callbacks, everything is Promises.
 - `get()`:
   - Is renamed to `resolve()` to indicate that it also takes a mandatory
     path argument.
   - Doesn’t have a `cid` in the return value anymore. That use case is
     covered by returning all objects that were traversed. Their `value`
     will always be the CID of the next one to traverse. So if you want
     to know the CID of the current IPLD Node, just look at the `value`
     of the previously returned IPLD Node.
   - Doesn’t return a single value, but an iterator.
   - `localResolve` option is removed. If you want to resolve a single IPLD
      Node only, just stop the iterator after the first item.
 - `getStream()` is removed without replacement. Use `resolve()` which uses
    async iterators instead.
 - `getMany()` takes an iterable as input now.
 - `put()`:
   - Doesn’t take `cid` as an option anymore. The CID is always calculated
     (#175).
   - The options don’t take the `format` (which is a string), but the `codec`
     (which is a `multicodec`) (#175).
   - the `cidVersion` option always defaults to `1`.
 - `.treeStream()` is renamed to `.tree()` and returns an async iterator.
 - `.support.add()` is renamed to `.addFormat()`.
 - `.support.rm()` is renamed to `.removeFormat()`.
 - `options.loadFormat()` is no longer callback based but is using an async
   function.
 - `putMany()` and `removeMany()` are introduced which both take an iterable
   as input.

Almost all open issues in regards to the IPLD API got adressed. One bigger
thing is the Patch API, which also isn’t part of the current specification.
Here’s an overview of the issues:

 - #66
   - [ ] IPLD Resolver `patch` API: There is no patch API yet
 - #70
   - [x] lazy value lookups: Can be done as IPLD Formats is pure JavaScript
   - [x] get external / local paths only: @vmx doesn’t know what this is,
         considers it a “won’t fix”
   - [x] toJSON + fromJSON - roundtrip: A roundtrip is not a goal anymore
         => won’t fix
   - [ ] put + patch api #66: Patch API is still missing
   - [x] text summary: @vmx doesn’t see a strong use case for this => “won’t fix”
   - [x] globbing: Out of scope for js-ipld
 - #175
   - [x] Deprecate passing a CID to `ipld.put`?: Current spec doesn’t allow
         `put()` with a CID
 - #182
   - [x] API Review: Links to many other issues, I list the individual issues
         below
 - #183
   - [x] getting the merkle proof with resolver.resolve: `resolve()` returns
         all CIDs along the traversed path
 - #184
   - [ ] Pass down the `options` object to resolver.resolve(): This needs a
         custom resolver. @vmx isn’t sure if the js-ipld API should make this
         possible, or of it should just be easy enough to create your own
         resolver.
 - https://github.com/ipfs/interface-ipfs-core/issues/81
   - [x] The `dag` API - One API to manipulate all the IPLD Format objects:
         Interesting discussion, but not relevant anymore.
 - ipfs-inactive/interface-js-ipfs-core#121
   - [x] dag api: add {ls, tree}: `tree()` is not part of js-ipld anymore as
         the IPLD Nodes are just JavaScript objects which you can easily traverse
         if you like. Though `tree()`-like functionality might be added as an
         example or separate module.
 - ipfs-inactive/interface-js-ipfs-core#125
   - [x] `dag get --localResolve` vs `dag resolve`: This is solved by the new
         `resolve()` API
 - ipfs-inactive/interface-js-ipfs-core#137
   - [x] add `level` option to ipfs.dag.tree: `tree()` is not part of js-ipld
         anymore. It should be considered if `tree()` is implemented (probably
         as an example or separate module)

Closes #70, #175, #182, #183
Closes ipfs-inactive/interface-js-ipfs-core#121
Closes ipfs-inactive/interface-js-ipfs-core#125
Closed ipfs-inactive/interface-js-ipfs-core#137
@ghost ghost removed the ready label Mar 21, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
difficulty:moderate help wanted P1 - High
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

docs: major API changes ipld/js-ipld
3 participants
@vmx @wanderer @daviddias