Merge branch 'main' into fix/locking

* main:
  chore(release): 1.0.4 [skip ci]
  docs: add usage example (#97)
  chore: bump aegir from 38.1.8 to 39.0.4 (#111)
  chore: Update CODEOWNERS [skip ci]
  docs: add system diagram (#93)
  deps(dev): bump libp2p from 0.43.4 to 0.44.0 (#96)

README.md

@@ -11,11 +11,118 @@
 [![codecov](https://img.shields.io/codecov/c/github/ipfs/helia.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia/main.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia/actions/workflows/main.yml?query=branch%3Amain)
 
+## 🌟 Usage
+
+A quick overview of how to get different types of data in and out of your Helia
+node.
+
+### 🪢 Strings
+
+You can use the [@helia/strings](https://www.npmjs.com/package/@helia/strings)
+module to easily add and get strings from your Helia node:
+
+```js
+import { createHelia } from 'helia'
+import { strings } from '@helia/strings'
+
+const helia = await createHelia()
+const s = strings(helia)
+
+const myImmutableAddress = await s.add('hello world')
+
+console.log(await s.get(myImmutableAddress))
+// hello world
+```
+
+### 🌃 JSON
+
+The [@helia/json](https://www.npmjs.com/package/@helia/json) module lets you add
+or get plain JS objects:
+
+```js
+import { createHelia } from 'helia'
+import { json } from '@helia/json'
+
+const helia = await createHelia()
+const j = json(helia)
+
+const myImmutableAddress = await j.add({ hello: 'world' })
+
+console.log(await j.get(myImmutableAddress))
+// { hello: 'world' }
+```
+
+### 🌠 DAG-JSON
+
+The [@helia/dag-json](https://www.npmjs.com/package/@helia/dag-json) allows you
+to store references to linked objects as
+[CIDs](https://docs.ipfs.tech/concepts/content-addressing):
+
+```js
+import { createHelia } from 'helia'
+import { dagJson } from '@helia/dag-json'
+
+const helia = await createHelia()
+const d = dagJson(helia)
+
+const object1 = { hello: 'world' }
+const myImmutableAddress1 = await d.add(object1)
+
+const object2 = { link: myImmutableAddress1 }
+const myImmutableAddress2 = await d.add(object2)
+
+const retrievedObject = await d.get(myImmutableAddress2)
+console.log(retrievedObject)
+// { link: CID(baguqeerasor...) }
+
+console.log(await d.get(retrievedObject.link))
+// { hello: 'world' }
+```
+
+### 🌌 DAG-CBOR
+
+[@helia/dag-cbor](https://www.npmjs.com/package/@helia/dag-json) works in a
+similar way to `@helia/dag-json` but stores objects using
+[Concise Binary Object Representation](https://cbor.io/):
+
+```js
+import { createHelia } from 'helia'
+import { dagCbor } from '@helia/dag-cbor'
+
+const helia = await createHelia()
+const d = dagJson(helia)
+
+const object1 = { hello: 'world' }
+const myImmutableAddress1 = await d.add(object1)
+
+const object2 = { link: myImmutableAddress1 }
+const myImmutableAddress2 = await d.add(object2)
+
+const retrievedObject = await d.get(myImmutableAddress2)
+console.log(retrievedObject)
+// { link: CID(baguqeerasor...) }
+
+console.log(await d.get(retrievedObject.link))
+// { hello: 'world' }
+```
+
+### 🐾 Next steps
+
+Check out the [helia-examples](https://github.com/ipfs-examples/helia-examples)
+repo for how to do mostly anything with your Helia node.
+
 ## Table of contents <!-- omit in toc -->
 
+- [🌟 Usage](#-usage)
+  - [🪢 Strings](#-strings)
+  - [🌃 JSON](#-json)
+  - [🌠 DAG-JSON](#-dag-json)
+  - [🌌 DAG-CBOR](#-dag-cbor)
+  - [🐾 Next steps](#-next-steps)
 - [🥅 Purpose and goals](#-purpose-and-goals)
 - [🏃‍♀️ Getting Started](#️-getting-started)
 - [📒 API Docs](#-api-docs)
+- [📐 System diagram](#-system-diagram)
 - [🏭 Code Structure](#-code-structure)
 - [📣 Project status](#-project-status)
 - [🛣️ Roadmap](#️-roadmap)
@@ -39,11 +146,43 @@ Check out the [Helia examples repo](https://github.com/ipfs-examples/helia-examp
 
 - https://ipfs.github.io/helia
 
+## 📐 System diagram
+
+```mermaid
+graph TD;
+    User["User or application"]-->IPNS["@helia/ipns"];
+    User-->UnixFS["@helia/unixfs"];
+    User-->Libp2p;
+    User-->Datastore;
+    User-->Blockstore;
+    UnixFS-->Blockstore;
+    IPNS-->Datastore;
+    subgraph helia [Helia]
+      Datastore
+      Blockstore-->Bitswap;
+      Libp2p-->DHT;
+      Libp2p-->PubSub;
+      Libp2p-->IPNI;
+      Libp2p-->Reframe;
+    end
+    Blockstore-->BlockStorage["File system/IDB/S3/etc"]
+    Datastore-->DataStorage["Level/S3/IDB/etc"]
+    Bitswap-->Network;
+    DHT-->Network;
+    PubSub-->Network;
+    IPNI-->Network;
+    Reframe-->Network;
+```
+
 ## 🏭 Code Structure
 Helia embraces a modular approach and encourages users to bring their own implementations of interfacing libraries to suit their needs. Helia also ships supplemental libraries and tools including:
 
 - [`@helia/UnixFS`](https://github.com/ipfs/helia-unixfs)
 - [`@helia/ipns`](https://github.com/ipfs/helia-ipns)
+- [`@helia/strings`](https://github.com/ipfs/helia-strings)
+- [`@helia/json`](https://github.com/ipfs/helia-json)
+- [`@helia/dag-json`](https://github.com/ipfs/helia-dag-json)
+- [`@helia/dag-cbor`](https://github.com/ipfs/helia-dag-cbor)
 
 These libraries are by no means the "one true implementation", but instead instead provide optionality depending on one's needs.
 

package.json

@@ -38,8 +38,8 @@
     "dep-check": "aegir run dep-check",
     "release": "npm run docs:no-publish && aegir run release && npm run docs"
   },
-  "dependencies": {
-    "aegir": "^38.1.0"
+  "devDependencies": {
+    "aegir": "^39.0.4"
   },
   "type": "module",
   "workspaces": [

packages/helia/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [helia-v1.0.4](https://github.com/ipfs/helia/compare/helia-v1.0.3...helia-v1.0.4) (2023-05-04)
+
+
+### Bug Fixes
+
+* **types:** Add missing types ([#95](https://github.com/ipfs/helia/issues/95)) ([e858b8d](https://github.com/ipfs/helia/commit/e858b8dbbff548b42dde225db674f0edd1990ed3))
+
+
+### Dependencies
+
+* **dev:** bump libp2p from 0.43.4 to 0.44.0 ([#96](https://github.com/ipfs/helia/issues/96)) ([6e37d9f](https://github.com/ipfs/helia/commit/6e37d9f8be58955c5ddc5472fe3adb4bd9a0459c))
+
+
+### Trivial Changes
+
+* bump aegir from 38.1.8 to 39.0.4 ([#111](https://github.com/ipfs/helia/issues/111)) ([2156568](https://github.com/ipfs/helia/commit/215656870cb821dd6be2f8054dc39932ba25af14))
+
 ## [helia-v1.0.3](https://github.com/ipfs/helia/compare/helia-v1.0.2...helia-v1.0.3) (2023-04-05)
 
 

packages/helia/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helia",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "An implementation of IPFS in JavaScript",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/ipfs/helia/tree/master/packages/helia#readme",
@@ -167,9 +167,10 @@
     "@ipld/dag-cbor": "^9.0.0",
     "@ipld/dag-json": "^10.0.1",
     "@libp2p/websockets": "^5.0.3",
-    "aegir": "^38.1.0",
+    "@types/sinon": "^10.0.14",
+    "aegir": "^39.0.4",
     "delay": "^5.0.0",
-    "libp2p": "^0.43.0",
+    "libp2p": "^0.44.0",
     "sinon": "^15.0.2",
     "sinon-ts": "^1.0.0"
   },

packages/helia/src/helia.ts

@@ -1,21 +1,21 @@
+import { logger } from '@libp2p/logger'
+import { MemoryBlockstore } from 'blockstore-core'
+import { MemoryDatastore } from 'datastore-core'
+import { type Bitswap, createBitswap } from 'ipfs-bitswap'
+import drain from 'it-drain'
+import { identity } from 'multiformats/hashes/identity'
+import { sha256, sha512 } from 'multiformats/hashes/sha2'
+import { CustomProgressEvent } from 'progress-events'
+import { PinsImpl } from './pins.js'
+import { BlockStorage } from './storage.js'
+import { assertDatastoreVersionIsCurrent } from './utils/datastore-version.js'
+import type { HeliaInit } from '.'
 import type { GCOptions, Helia } from '@helia/interface'
+import type { Pins } from '@helia/interface/pins'
 import type { Libp2p } from '@libp2p/interface-libp2p'
 import type { Datastore } from 'interface-datastore'
 import type { CID } from 'multiformats/cid'
-import { identity } from 'multiformats/hashes/identity'
-import { sha256, sha512 } from 'multiformats/hashes/sha2'
 import type { MultihashHasher } from 'multiformats/hashes/interface'
-import type { HeliaInit } from '.'
-import { Bitswap, createBitswap } from 'ipfs-bitswap'
-import { BlockStorage } from './storage.js'
-import type { Pins } from '@helia/interface/pins'
-import { PinsImpl } from './pins.js'
-import { assertDatastoreVersionIsCurrent } from './utils/datastore-version.js'
-import drain from 'it-drain'
-import { CustomProgressEvent } from 'progress-events'
-import { MemoryDatastore } from 'datastore-core'
-import { MemoryBlockstore } from 'blockstore-core'
-import { logger } from '@libp2p/logger'
 
 const log = logger('helia')
 

packages/helia/src/index.ts

@@ -25,13 +25,13 @@
  * ```
  */
 
+import { HeliaImpl } from './helia.js'
 import type { Helia } from '@helia/interface'
 import type { Libp2p } from '@libp2p/interface-libp2p'
 import type { Blockstore } from 'interface-blockstore'
 import type { Datastore } from 'interface-datastore'
 import type { CID } from 'multiformats/cid'
 import type { MultihashHasher } from 'multiformats/hashes/interface'
-import { HeliaImpl } from './helia.js'
 
 /**
  * DAGWalkers take a block and yield CIDs encoded in that block

packages/helia/src/pins.ts

@@ -1,15 +1,15 @@
-import type { AddOptions, IsPinnedOptions, LsOptions, Pin, Pins, RmOptions } from '@helia/interface/pins'
-import { Datastore, Key } from 'interface-datastore'
-import { CID, Version } from 'multiformats/cid'
 import * as cborg from 'cborg'
+import { type Datastore, Key } from 'interface-datastore'
 import { base36 } from 'multiformats/bases/base36'
-import type { Blockstore } from 'interface-blockstore'
+import { CID, type Version } from 'multiformats/cid'
+import defer from 'p-defer'
 import PQueue from 'p-queue'
-import type { AbortOptions } from '@libp2p/interfaces'
 import { equals as uint8ArrayEquals } from 'uint8arrays/equals'
-import defer from 'p-defer'
-import type { DAGWalker } from './index.js'
 import { cborWalker, dagPbWalker, jsonWalker, rawWalker } from './utils/dag-walkers.js'
+import type { DAGWalker } from './index.js'
+import type { AddOptions, IsPinnedOptions, LsOptions, Pin, Pins, RmOptions } from '@helia/interface/pins'
+import type { AbortOptions } from '@libp2p/interfaces'
+import type { Blockstore } from 'interface-blockstore'
 
 const DEFAULT_DAG_WALKERS = [
   rawWalker,
@@ -233,6 +233,6 @@ export class PinsImpl implements Pins {
   async isPinned (cid: CID, options: IsPinnedOptions = {}): Promise<boolean> {
     const blockKey = new Key(`${DATASTORE_BLOCK_PREFIX}${DATASTORE_ENCODING.encode(cid.multihash.bytes)}`)
 
-    return await this.datastore.has(blockKey, options)
+    return this.datastore.has(blockKey, options)
   }
 }

packages/helia/src/storage.ts

@@ -1,15 +1,15 @@
 import filter from 'it-filter'
-import type { Blockstore } from 'interface-blockstore'
+import forEach from 'it-foreach'
+import createMortice from 'mortice'
+import { CustomProgressEvent, type ProgressOptions } from 'progress-events'
 import type { Blocks, Pair, DeleteManyBlocksProgressEvents, DeleteBlockProgressEvents, GetBlockProgressEvents, GetManyBlocksProgressEvents, PutManyBlocksProgressEvents, PutBlockProgressEvents, GetAllBlocksProgressEvents } from '@helia/interface/blocks'
-import type { Bitswap } from 'ipfs-bitswap'
-import type { CID } from 'multiformats/cid'
+import type { Pins } from '@helia/interface/pins'
 import type { AbortOptions } from '@libp2p/interfaces'
+import type { Blockstore } from 'interface-blockstore'
 import type { AwaitIterable } from 'interface-store'
+import type { Bitswap } from 'ipfs-bitswap'
 import type { Mortice } from 'mortice'
-import createMortice from 'mortice'
-import type { Pins } from '@helia/interface/pins'
-import forEach from 'it-foreach'
-import { CustomProgressEvent, ProgressOptions } from 'progress-events'
+import type { CID } from 'multiformats/cid'
 
 export interface BlockStorageInit {
   holdGcLock?: boolean

packages/helia/src/utils/dag-walkers.ts

@@ -4,10 +4,10 @@ import * as dagPb from '@ipld/dag-pb'
 import * as cborg from 'cborg'
 import { Type, Token } from 'cborg'
 import * as cborgJson from 'cborg/json'
-import type { DAGWalker } from '../index.js'
-import * as raw from 'multiformats/codecs/raw'
 import { CID } from 'multiformats'
 import { base64 } from 'multiformats/bases/base64'
+import * as raw from 'multiformats/codecs/raw'
+import type { DAGWalker } from '../index.js'
 
 /**
  * Dag walker for dag-pb CIDs

packages/helia/src/utils/datastore-version.ts

@@ -1,4 +1,4 @@
-import { Datastore, Key } from 'interface-datastore'
+import { type Datastore, Key } from 'interface-datastore'
 import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
 

packages/helia/test/fixtures/create-block.ts

@@ -1,6 +1,6 @@
-import type { Blockstore } from 'interface-blockstore'
 import { CID } from 'multiformats/cid'
 import { sha256 } from 'multiformats/hashes/sha2'
+import type { Blockstore } from 'interface-blockstore'
 
 export async function createBlock <Codec extends number> (codec: Codec, block: Uint8Array): Promise<{ cid: CID<unknown, Codec, 18>, block: Uint8Array }> {
   const mh = await sha256.digest(block)

packages/helia/test/fixtures/create-dag.ts

@@ -1,7 +1,7 @@
-import type { Blockstore } from 'interface-blockstore'
-import type { CID } from 'multiformats/cid'
 import { fromString as uint8arrayFromString } from 'uint8arrays/from-string'
 import { createAndPutBlock } from './create-block.js'
+import type { Blockstore } from 'interface-blockstore'
+import type { CID } from 'multiformats/cid'
 
 export interface DAGNode {
   cid: CID

packages/helia/test/fixtures/dag-walker.ts

@@ -1,6 +1,6 @@
-import type { DAGWalker } from '../../src/index.js'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
 import type { DAGNode } from './create-dag.js'
+import type { DAGWalker } from '../../src/index.js'
 
 export function dagWalker (codec: number, dag: Record<string, DAGNode>): DAGWalker {
   return {

packages/helia/test/gc.spec.ts

@@ -1,18 +1,18 @@
 /* eslint-env mocha */
+import { noise } from '@chainsafe/libp2p-noise'
+import { yamux } from '@chainsafe/libp2p-yamux'
+import * as dagCbor from '@ipld/dag-cbor'
+import * as dagJson from '@ipld/dag-json'
+import * as dagPb from '@ipld/dag-pb'
+import { webSockets } from '@libp2p/websockets'
 import { expect } from 'aegir/chai'
 import { MemoryBlockstore } from 'blockstore-core'
 import { MemoryDatastore } from 'datastore-core'
 import { createLibp2p } from 'libp2p'
-import { webSockets } from '@libp2p/websockets'
-import { noise } from '@chainsafe/libp2p-noise'
-import { yamux } from '@chainsafe/libp2p-yamux'
-import { createHelia } from '../src/index.js'
-import type { GcEvents, Helia } from '@helia/interface'
 import * as raw from 'multiformats/codecs/raw'
+import { createHelia } from '../src/index.js'
 import { createAndPutBlock } from './fixtures/create-block.js'
-import * as dagPb from '@ipld/dag-pb'
-import * as dagCbor from '@ipld/dag-cbor'
-import * as dagJson from '@ipld/dag-json'
+import type { GcEvents, Helia } from '@helia/interface'
 
 describe('gc', () => {
   let helia: Helia