From 9177b2523f75bff165325d59407c27a39359190e Mon Sep 17 00:00:00 2001 From: Dietrich Ayala <50103+autonome@users.noreply.github.com> Date: Tue, 18 Apr 2023 04:26:34 -0400 Subject: [PATCH 1/5] add usage example --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 3a845fef..166d5ebb 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,18 @@ [![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 + +``` +import { createHelia } from 'helia'; + +const ipfs = await createHelia(); + +const myImmutableAddress = ipfs.add(JSON.stringify({ foo: "bar" })); + +console.log(ipfs.get(myImmutableAddress)); +``` + ## Table of contents - [🥅 Purpose and goals](#-purpose-and-goals) From 00cdb996d2777ccf1523828de671f80c030f98cc Mon Sep 17 00:00:00 2001 From: achingbrain Date: Wed, 3 May 2023 15:16:45 +0100 Subject: [PATCH 2/5] docs: update examples --- README.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 97 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 166d5ebb..4a22bf98 100644 --- a/README.md +++ b/README.md @@ -11,20 +11,112 @@ [![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 +## 🌟 Usage +A quick overview of how to get 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 ``` -import { createHelia } from 'helia'; -const ipfs = await createHelia(); +### 🌃 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 myImmutableAddress = ipfs.add(JSON.stringify({ foo: "bar" })); +const helia = await createHelia() +const j = json(helia) -console.log(ipfs.get(myImmutableAddress)); +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 linked objects: + +```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 +- [🌟 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) From e8348050ac2bdf5d31cc414c798a54303e0662e2 Mon Sep 17 00:00:00 2001 From: achingbrain Date: Wed, 3 May 2023 15:18:44 +0100 Subject: [PATCH 3/5] docs: update examples --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4a22bf98..0539861d 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,8 @@ console.log(await j.get(myImmutableAddress)) ### 🌠 DAG-JSON The [@helia/dag-json](https://www.npmjs.com/package/@helia/dag-json) allows you -to store linked objects: +to store references to linked objects as +[CIDs](https://docs.ipfs.tech/concepts/content-addressing): ```js import { createHelia } from 'helia' @@ -177,6 +178,10 @@ Helia embraces a modular approach and encourages users to bring their own implem - [`@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. From 541c20ed74213b579b138243cd9b285e177f5299 Mon Sep 17 00:00:00 2001 From: achingbrain Date: Wed, 3 May 2023 15:19:14 +0100 Subject: [PATCH 4/5] docs: update examples --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0539861d..7eec4326 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ ## 🌟 Usage -A quick overview of how to get data in and out of your Helia node. +A quick overview of how to get different types of data in and out of your Helia node. ### 🪢 Strings From f7782a9d1bf1bedb3b0d37c0325c478c0543d0e2 Mon Sep 17 00:00:00 2001 From: achingbrain Date: Wed, 3 May 2023 15:19:32 +0100 Subject: [PATCH 5/5] docs: update examples --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7eec4326..08e9ffb9 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,8 @@ ## 🌟 Usage -A quick overview of how to get different types of data in and out of your Helia node. +A quick overview of how to get different types of data in and out of your Helia +node. ### 🪢 Strings