Skip to content
This repository has been archived by the owner on Aug 11, 2021. It is now read-only.

Major API changes #185

Closed
wants to merge 5 commits into from
Closed

Major API changes #185

wants to merge 5 commits into from

Commits on Nov 26, 2018

  1. docs: major API changes

    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 committed Nov 26, 2018
    Configuration menu
    Copy the full SHA
    5139f53 View commit details
    Browse the repository at this point in the history

Commits on Jan 28, 2019

  1. fix: various fixes

    Most importantly the `tree()` method is added again. It's really needed
    for backwards compatibility.
    vmx committed Jan 28, 2019
    Configuration menu
    Copy the full SHA
    8165bf9 View commit details
    Browse the repository at this point in the history
  2. docs: update options.loadFormat() documentation

    Loading a format is no longer callback based but is using an
    async function.
    vmx committed Jan 28, 2019
    Configuration menu
    Copy the full SHA
    221fab0 View commit details
    Browse the repository at this point in the history
  3. docs: update TOC of README

    `doctoc` was used to update the table of contents.
    vmx committed Jan 28, 2019
    Configuration menu
    Copy the full SHA
    1a2c0ad View commit details
    Browse the repository at this point in the history

Commits on Feb 6, 2019

  1. docs: change put() signature

    The `format` is no longer part of the the options object, but a
    separate parameter. The `version` option was renamed to `cidVersion`.
    vmx committed Feb 6, 2019
    Configuration menu
    Copy the full SHA
    2365ae3 View commit details
    Browse the repository at this point in the history