feat: add pinning API

[achingbrain]

Adds the pinning API with the reference counting implementation as specified in #28 - see that issue for discussion

Benchmarks prove reference counting is faster than DAG traversal during gc, see this comment for results & discussion.

Closes: #28

[achingbrain]

I've updated the benchmark to omit setup and teardown from the timed sections, though it needs tinylibs/tinybench#33 to be merged before it can be run.

The benchmark creates a load of small pinned dags and a load of unpinned blocks, then runs garbage collection.

In the results below we start with 1,000 dags/unpinned blocks, up to 10,000, increasing in increments of 1,000, so we start with 4k blocks (1k DAGs of 3 blocks each + 1k unpinned blocks) and end with 40k blocks.

It tests helia, js-ipfs and kubo though I've omitted js-ipfs from the graphs because it skewed them so far to make the helia/kubo series be plotted as flat lines at the bottom of the graph. As an indication running gc with 40k blocks took js-ipfs 5.5 hours, it takes helia about 4 seconds(!) The difference is that js-ipfs walks the DAG of each block in the blockstore to build up a list of unpinned blocks whereas helia already knows which blocks are pinned due to reference counting.

I ran these benchmarks on my laptop while doing other things which is why there is some wobble in the lines so I've added trend lines to make things a bit clearer.

---

Splitting the setup out of the timed function also allowed me to benchmark the different steps separately for some bonus stats.

This is deleting pins (start with deleting 1k pins, end with 10k pins):

Adding blocks (kubo adds blocks with the ipfs.block.put RPC command, helia uses the blockstore putMany function, which allows the blockstore to control concurrency):

Finally adding new pins to the pinset, (start with adding 1k pins, end with 10k pins, the ms value is how long adding that many pins takes). Helia scales better because it's not mutating a giant DAG that gets bigger with every pin added:

[SgtPooki]

@achingbrain , this is great. nice work

[achingbrain]

Vive le JS!

[github-actions]

🎉 This PR is included in version @helia/interface-v1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version helia-v1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[logesh2496]

How do I use this to pin a CID. I have tried below options and none of them are working,

helia.pins?.add("QmRrzxiXGefcF9VbbThGrkhiQeuhPFjRbGgqYZmxYXYkHr")

and

import CID from "cids"
const newcid = new CID(cid)
const pin = await helia.pins?.add(newcid);