new API branchStream()

[staltz]

• implement pull source branchStream()
• tests
• Update README
• Hide/deprecate other APIs?

[staltz]

This PR is ready for review, and it's stable since I'm using it in ssbc/ssb-replication-scheduler#5 .

I took a look at all usages of ssb-meta-feeds and it seems like filter was never used, and in all cases where create is used, we should use findOrCreate instead, so I ended up deprecating (just by hiding from the README) those APIs that are not used. I think it's better to build APIs for actual use cases, than to work for imaginary use cases.

Now that we have loadState, I think find could be repurposed so that it works also on foreign meta feeds. Currently it's a bit confusing that some APIs operate only on your own meta feeds (find, findOrCreate) while other APIs operate on meta feeds from anyone (findByIdSync, branchStream). If we make find work for any meta feed, then it's obvious that findOrCreate is only for your own meta feed due to the name 'create'.

But I could do that change to find in a separate PR because this one is about branchStream, and it's ready.

[arj03]

This PR is ready for review, and it's stable since I'm using it in ssbc/ssb-replication-scheduler#5 .

This is a bit light on tests for this new api, but since it is used in the other module I guess that counts as testing :)

But I could do that change to find in a separate PR because this one is about branchStream, and it's ready.

Yes! It would be great if find worked on any feed.

[arj03]

Lets get this merged and continue working on the API in another branch. Overall it's great to have this kind of API in here because it makes it similar to ssb-friends and other modules.