From c2f208fe8599a9f1a0be28997c38de7afe3ca605 Mon Sep 17 00:00:00 2001 From: Vojtech Simetka Date: Wed, 3 Feb 2021 17:43:08 +0100 Subject: [PATCH 1/6] feat: basic getting-started --- docs/getting-started/upload-your-data.md | 6 -- docs/installation/quick-start.md | 6 -- docs/introduction.md | 23 +++++- docs/user-documentation/getting-started.md | 71 +++++++++++++++++++ .../upload-download-data.md | 8 +++ sidebars.js | 13 +--- src/css/custom.css | 2 +- 7 files changed, 104 insertions(+), 25 deletions(-) delete mode 100644 docs/getting-started/upload-your-data.md delete mode 100644 docs/installation/quick-start.md create mode 100644 docs/user-documentation/getting-started.md create mode 100644 docs/user-documentation/upload-download-data.md diff --git a/docs/getting-started/upload-your-data.md b/docs/getting-started/upload-your-data.md deleted file mode 100644 index a0bfcee1..00000000 --- a/docs/getting-started/upload-your-data.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Upload Data to Swarm -id: upload-your-data ---- - -Uploading your data to Swarm is easy with bee-js! \ No newline at end of file diff --git a/docs/installation/quick-start.md b/docs/installation/quick-start.md deleted file mode 100644 index 7c0f2569..00000000 --- a/docs/installation/quick-start.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Quick Start -id: quick-start ---- - -To get started quickly with bee-js... \ No newline at end of file diff --git a/docs/introduction.md b/docs/introduction.md index 55ba5b80..07c1bb74 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,7 +1,26 @@ --- id: introduction slug: / -title: Welcome! +title: "bee-js: Ethereum Swarm JavaScript API" +sidebar_label: Introduction --- -Welcome to Bee-js! \ No newline at end of file +bee-js is a library that allows you to interact with a local or remote [Bee node](https://docs.ethswarm.org/docs/). + +The following documentation will guide you through installing and using bee-js as well as providing an API reference documentation with examples. + +## Development +We'd love you to join us! Are you up to the challenge of helping us to create bee-js and the other incredible technologies we're building? Have alook at our Github - [Ethersphere](https://github.com/ethersphere). + +## Community +There is a vibrant and buzzing community behind Swarm, get involved in one of our group channels. + +- [Swarm](http://swarm.ethereum.org). +- [Beehive Chat on Mattermost](https://beehive.ethswarm.org/). +- [Orange Lounge](https://t.me/joinchat/GoVG8RHYjUpD_-bEnLC4EQ). +- [Twitter @ethswarm](https://twitter.com/ethswarm). +- [reddit channel](https://www.reddit.com/r/ethswarm/). + +## Reporting a bug +If anything isn't working, [get in touch and let us know!](https://github.com/ethersphere/bee-js/issues) Every Bee is important to us and we'll get right to work on fixing it for you as soon as possible. 🐝 + diff --git a/docs/user-documentation/getting-started.md b/docs/user-documentation/getting-started.md new file mode 100644 index 00000000..a7580d21 --- /dev/null +++ b/docs/user-documentation/getting-started.md @@ -0,0 +1,71 @@ +--- +title: Getting Started +id: getting-started +slug: /getting-started +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +First you need to get bee-js into your project. This can be done using your favourite package management tool or directly: + + + + +```sh +npm install @ethersphere/bee-js --save +``` + + + + +```sh +yarn add @ethersphere/bee-js --save +``` + + + + +```html + +``` + + + + +After that you need to import the Bee class and create a bee instance. + + + + + +```ts +import Bee from "@ethersphere/bee-js"; + +const bee = new Bee('http://localhost:1633') +``` + + + + +```js +import Bee from "@ethersphere/bee-js"; + +const bee = new Bee('http://localhost:1633') +``` + + + + +That’s it! now you can use the bee object. \ No newline at end of file diff --git a/docs/user-documentation/upload-download-data.md b/docs/user-documentation/upload-download-data.md new file mode 100644 index 00000000..ebcdda8c --- /dev/null +++ b/docs/user-documentation/upload-download-data.md @@ -0,0 +1,8 @@ +--- +title: Upload and Download data to Swarm +id: upload-download-data +slug: /upload-download-data +sidebar_label: Upload and download data +--- + +Uploading your data to Swarm is easy with bee-js! \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 32753753..17ef6a0e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -3,20 +3,13 @@ module.exports = { 'introduction', { type: 'category', - label: 'Installation', + label: 'User Documentation', items: [ - 'installation/quick-start' + 'user-documentation/getting-started', + 'user-documentation/upload-download-data', ], collapsed: false }, - { - type: 'category', - label: 'Basic Usage', - items: [ - 'getting-started/upload-your-data', - ], - collapsed: false, - }, { type: 'category', label: 'API Reference', diff --git a/src/css/custom.css b/src/css/custom.css index 1f838552..256c350b 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -126,7 +126,7 @@ code{ color: rgb(191, 199, 213); } -code, .codeBlockLines_node_modules-\@docusaurus-theme-classic-lib-theme-CodeBlock-{ +pre, code, .codeBlockLines_node_modules-\@docusaurus-theme-classic-lib-theme-CodeBlock-{ background: #242424 !important; } From 2c15fcaa38467e0ad15b3b2d28ca6c9e42598307 Mon Sep 17 00:00:00 2001 From: Vojtech Simetka Date: Thu, 4 Feb 2021 09:27:34 +0100 Subject: [PATCH 2/6] feat: added groups for taps --- docs/user-documentation/getting-started.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/user-documentation/getting-started.md b/docs/user-documentation/getting-started.md index a7580d21..abfe7b66 100644 --- a/docs/user-documentation/getting-started.md +++ b/docs/user-documentation/getting-started.md @@ -10,6 +10,7 @@ import TabItem from '@theme/TabItem'; First you need to get bee-js into your project. This can be done using your favourite package management tool or directly: Date: Thu, 4 Feb 2021 18:03:41 +0100 Subject: [PATCH 3/6] fix: import in JS --- docs/user-documentation/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-documentation/getting-started.md b/docs/user-documentation/getting-started.md index abfe7b66..16be7dcf 100644 --- a/docs/user-documentation/getting-started.md +++ b/docs/user-documentation/getting-started.md @@ -62,7 +62,7 @@ const bee = new Bee('http://localhost:1633') ```js -import Bee from "@ethersphere/bee-js"; +import { Bee } from "@ethersphere/bee-js"; const bee = new Bee('http://localhost:1633') ``` From 82c6cf7b3eddcfcb609c9f8213ee93c6b6bd9a6a Mon Sep 17 00:00:00 2001 From: Vojtech Simetka Date: Thu, 4 Feb 2021 18:04:02 +0100 Subject: [PATCH 4/6] feat: upload data --- .../upload-download-data.md | 46 +++++++++++++++++-- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/docs/user-documentation/upload-download-data.md b/docs/user-documentation/upload-download-data.md index ebcdda8c..0f3f03f9 100644 --- a/docs/user-documentation/upload-download-data.md +++ b/docs/user-documentation/upload-download-data.md @@ -1,8 +1,48 @@ --- -title: Upload and Download data to Swarm +title: Upload and Download data or files to Swarm id: upload-download-data slug: /upload-download-data -sidebar_label: Upload and download data +sidebar_label: Upload and Download data or files --- -Uploading your data to Swarm is easy with bee-js! \ No newline at end of file +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Uploading your data to Swarm is easy with bee-js! + + + + +```ts +import Bee from "@ethersphere/bee-js"; + +const bee = new Bee('http://localhost:1633') + +const hash = await bee.uploadData("Bee is awesome!"); +const retrievedData = await bee.downloadData(hash); + +console.log(retrievedData.toString()); // prints 'Bee is awesome!' +``` + + + + +```js +import { Bee } from "@ethersphere/bee-js"; + +const bee = new Bee('http://localhost:1633') + +const hash = await bee.uploadData("Bee is awesome!"); +const retrievedData = await bee.downloadData(hash); + +console.log(retrievedData.toString()); // prints 'Bee is awesome!' +``` + + + \ No newline at end of file From 6d043673e88a2d0fa03e0cb58c7d04c4bdb12bb0 Mon Sep 17 00:00:00 2001 From: Vojtech Simetka Date: Fri, 5 Feb 2021 19:39:12 +0100 Subject: [PATCH 5/6] refactor: improved wording, fixed default import --- docs/introduction.md | 4 +- docs/user-documentation/getting-started.md | 18 ++-- .../upload-download-data.md | 95 ++++++++++++++++--- 3 files changed, 96 insertions(+), 21 deletions(-) diff --git a/docs/introduction.md b/docs/introduction.md index 07c1bb74..9d0fce18 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -5,9 +5,9 @@ title: "bee-js: Ethereum Swarm JavaScript API" sidebar_label: Introduction --- -bee-js is a library that allows you to interact with a local or remote [Bee node](https://docs.ethswarm.org/docs/). +`bee-js` is a library that allows you to interact with a local or remote [Bee node](https://docs.ethswarm.org/docs/). -The following documentation will guide you through installing and using bee-js as well as providing an API reference documentation with examples. +The following documentation will guide you through installing and using `bee-js` as well as providing an API reference documentation with examples. Your next step should be the [Getting Started section](./getting-started). ## Development We'd love you to join us! Are you up to the challenge of helping us to create bee-js and the other incredible technologies we're building? Have alook at our Github - [Ethersphere](https://github.com/ethersphere). diff --git a/docs/user-documentation/getting-started.md b/docs/user-documentation/getting-started.md index 16be7dcf..57b3687a 100644 --- a/docs/user-documentation/getting-started.md +++ b/docs/user-documentation/getting-started.md @@ -4,10 +4,10 @@ id: getting-started slug: /getting-started --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +import Tabs from '@theme/Tabs' +import TabItem from '@theme/TabItem' -First you need to get bee-js into your project. This can be done using your favourite package management tool or directly: +First you need to get `bee-js` into your project. This can be done using your favourite package management tool or directly: -After that you need to import the Bee class and create a bee instance. +After that you need to import the Bee class and create a bee instance connecting to your Bee node (here we assume it runs on localhost on default port). ```ts -import Bee from "@ethersphere/bee-js"; +import { Bee } from "@ethersphere/bee-js" const bee = new Bee('http://localhost:1633') ``` @@ -62,7 +62,7 @@ const bee = new Bee('http://localhost:1633') ```js -import { Bee } from "@ethersphere/bee-js"; +import { Bee } from "@ethersphere/bee-js" const bee = new Bee('http://localhost:1633') ``` @@ -70,4 +70,8 @@ const bee = new Bee('http://localhost:1633') -That’s it! now you can use the bee object. \ No newline at end of file +That’s it! now you can use the `bee` object. + +:::info Run your own Bee node +You can find out more about running Bee node in the [Bee docs](https://docs.ethswarm.org/docs/installation/quick-start) +::: diff --git a/docs/user-documentation/upload-download-data.md b/docs/user-documentation/upload-download-data.md index 0f3f03f9..516ac0e6 100644 --- a/docs/user-documentation/upload-download-data.md +++ b/docs/user-documentation/upload-download-data.md @@ -1,12 +1,15 @@ --- title: Upload and Download data or files to Swarm +hide_title: true id: upload-download-data slug: /upload-download-data sidebar_label: Upload and Download data or files --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +import Tabs from '@theme/Tabs' +import TabItem from '@theme/TabItem' + +## Upload and Download data Uploading your data to Swarm is easy with bee-js! @@ -20,28 +23,96 @@ Uploading your data to Swarm is easy with bee-js! ```ts -import Bee from "@ethersphere/bee-js"; +const hash = await bee.uploadData("Bee is awesome!") +const retrievedData = await bee.downloadData(hash) + +console.log(retrievedData.toString()) // prints 'Bee is awesome!' +``` + + + + +```js +const hash = await bee.uploadData("Bee is awesome!") +const retrievedData = await bee.downloadData(hash) + +console.log(retrievedData.toString()) // prints 'Bee is awesome!' +``` + + + -const bee = new Bee('http://localhost:1633') +## Upload and Download files -const hash = await bee.uploadData("Bee is awesome!"); -const retrievedData = await bee.downloadData(hash); +You can also upload files including filenames + + + + +```ts +const hash = await bee.uploadFile("Bee is awesome!", "textfile.txt") +const retrievedData = await bee.downloadFile(hash) -console.log(retrievedData.toString()); // prints 'Bee is awesome!' +console.log(retrievedData.name) // prints 'textfile.txt' +console.log(retrievedData.contentType) // prints 'application/octet-stream' +console.log(new TextDecoder("utf-8").decode(retrievedData.data)) // prints 'Bee is awesome!' ``` ```js -import { Bee } from "@ethersphere/bee-js"; +const hash = await bee.uploadFile("Bee is awesome!", "textfile.txt") +const retrievedData = await bee.downloadFile(hash) -const bee = new Bee('http://localhost:1633') +console.log(retrievedData.name) // prints 'textfile.txt' +console.log(retrievedData.contentType) // prints 'application/octet-stream' +console.log(new TextDecoder("utf-8").decode(retrievedData.data)) // prints 'Bee is awesome!' +``` + + + + +In browsers, you can upload directly `File` type. The filename is taken from the file object itself, but can be overwritten through the second argument of the `uploadFile` function (see the [API docs](./api-reference/classes/bee#uploadfile)) + + + + +```ts +const file = new File(["foo"], "foo.txt", { type: "text/plain" }) + +const hash = await bee.uploadFile(file) +const retrievedData = await bee.downloadFile(hash) + +console.log(retrievedData.name) // prints 'foo.txt' +console.log(retrievedData.contentType) // prints 'text/plain' +console.log(new TextDecoder("utf-8").decode(retrievedData.data)) // prints 'foo' +``` + + + + +```js +const file = new File(["foo"], "foo.txt", { type: "text/plain" }) -const hash = await bee.uploadData("Bee is awesome!"); -const retrievedData = await bee.downloadData(hash); +const hash = await bee.uploadFile(file) +const retrievedData = await bee.downloadFile(hash) -console.log(retrievedData.toString()); // prints 'Bee is awesome!' +console.log(retrievedData.name) // prints 'foo.txt' +console.log(retrievedData.contentType) // prints 'text/plain' +console.log(new TextDecoder("utf-8").decode(retrievedData.data)) // prints 'foo' ``` From 0b207bd406bba17ca681409588d6f72d6f3c81e5 Mon Sep 17 00:00:00 2001 From: Vojtech Simetka Date: Mon, 8 Feb 2021 19:52:11 +0100 Subject: [PATCH 6/6] feat: added tags documentation, expanded upload & download sections --- docs/user-documentation/pss.md | 10 + docs/user-documentation/track-upload.md | 135 ++++++++++ .../upload-download-data.md | 119 --------- docs/user-documentation/upload-download.md | 233 ++++++++++++++++++ sidebars.js | 4 +- 5 files changed, 381 insertions(+), 120 deletions(-) create mode 100644 docs/user-documentation/pss.md create mode 100644 docs/user-documentation/track-upload.md delete mode 100644 docs/user-documentation/upload-download-data.md create mode 100644 docs/user-documentation/upload-download.md diff --git a/docs/user-documentation/pss.md b/docs/user-documentation/pss.md new file mode 100644 index 00000000..ef8fc08b --- /dev/null +++ b/docs/user-documentation/pss.md @@ -0,0 +1,10 @@ +--- +title: Postal Service over Swarm +hide_title: true +id: pss +slug: /pss +sidebar_label: Postal Service over Swarm +--- + +import Tabs from '@theme/Tabs' +import TabItem from '@theme/TabItem' diff --git a/docs/user-documentation/track-upload.md b/docs/user-documentation/track-upload.md new file mode 100644 index 00000000..ac87eda6 --- /dev/null +++ b/docs/user-documentation/track-upload.md @@ -0,0 +1,135 @@ +--- +title: Track Upload Status +id: track-upload +slug: /track-upload +sidebar_label: Track Upload +--- + +import Tabs from '@theme/Tabs' +import TabItem from '@theme/TabItem' + +In Swarm, an instruction to upload data to the network goes through 3 consecutive stages before it is completed: + +- Splitting +- Storing +- Sending + +In the splitting state, the file is deconstructed in chunks (Swarms canonical data unit) and packaged in a [Binary Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree). After splitting, the chunks are stored in your local database where they enter a queue, to be sent to the network. + +Sending starts immediately when the first chunks are split and stored. After the chunk is sent, your node will receive a receipt from the node that has stored the chunk, marking the completion of the upload for that chunk. After a receipt has been received for all chunks, the upload is complete. + +## What is a tag +The status of your upload can be followed by using `tags`. A `tag` is a label given to all chunks that belong to the same upload instruction. In the `bee-js` library, tag looks as follows: + +```ts +interface Tag { + total: number // total number of chunks belonging to a tag + split: number // number of chunks already processed by splitter for hashing + seen: number // number of chunks already seen + stored: number // number of chunks already stored locally + sent: number // number of chunks sent for push syncing + synced: number // number of chunks synced with proof + + uid: number // a unique identifier for this tag + address: string // the associated swarm hash for this tag + startedAt: string // when the tag was first used +} +``` + +## Create tag + +Creating a tag is easy. Just use the `createTag` function. + + + + +```ts +const tag = await bee.createTag() +``` + + + + +```js +const tag = await bee.createTag() +``` + + + + +## Upload with tag + +You can then use the tag when uploading data, by providing it in the options arguments for each of these methods. + + + + +```ts +await bee.uploadData("Bee is awesome!", { tag }) +// OR +await bee.uploadFile(file, "foo.txt", { tag }) +// OR +await bee.uploadFiles(files, { tag }) +// OR +await bee.uploadFilesToCollection("./", true, { tag }) +``` + + + + +```js +await bee.uploadData("Bee is awesome!", { tag }) +// OR +await bee.uploadFile(file, "foo.txt", { tag }) +// OR +await bee.uploadFiles(files, { tag }) +// OR +await bee.uploadFilesToCollection("./", true, { tag }) +``` + + + + +## Retrieve tag + +Each time you want to check the upload status, you can use the `retrieveTag` function + + + + + +```ts +const updatedTag = await bee.retrieveTag(tag) +// OR +const updatedTag = await bee.retrieveTag(tag.uid) +``` + + + + +```js +const updatedTag = await bee.retrieveTag(tag) +// OR +const updatedTag = await bee.retrieveTag(tag.uid) +``` + + + diff --git a/docs/user-documentation/upload-download-data.md b/docs/user-documentation/upload-download-data.md deleted file mode 100644 index 516ac0e6..00000000 --- a/docs/user-documentation/upload-download-data.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Upload and Download data or files to Swarm -hide_title: true -id: upload-download-data -slug: /upload-download-data -sidebar_label: Upload and Download data or files ---- - -import Tabs from '@theme/Tabs' -import TabItem from '@theme/TabItem' - -## Upload and Download data - -Uploading your data to Swarm is easy with bee-js! - - - - -```ts -const hash = await bee.uploadData("Bee is awesome!") -const retrievedData = await bee.downloadData(hash) - -console.log(retrievedData.toString()) // prints 'Bee is awesome!' -``` - - - - -```js -const hash = await bee.uploadData("Bee is awesome!") -const retrievedData = await bee.downloadData(hash) - -console.log(retrievedData.toString()) // prints 'Bee is awesome!' -``` - - - - -## Upload and Download files - -You can also upload files including filenames - - - - -```ts -const hash = await bee.uploadFile("Bee is awesome!", "textfile.txt") -const retrievedData = await bee.downloadFile(hash) - -console.log(retrievedData.name) // prints 'textfile.txt' -console.log(retrievedData.contentType) // prints 'application/octet-stream' -console.log(new TextDecoder("utf-8").decode(retrievedData.data)) // prints 'Bee is awesome!' -``` - - - - -```js -const hash = await bee.uploadFile("Bee is awesome!", "textfile.txt") -const retrievedData = await bee.downloadFile(hash) - -console.log(retrievedData.name) // prints 'textfile.txt' -console.log(retrievedData.contentType) // prints 'application/octet-stream' -console.log(new TextDecoder("utf-8").decode(retrievedData.data)) // prints 'Bee is awesome!' -``` - - - - -In browsers, you can upload directly `File` type. The filename is taken from the file object itself, but can be overwritten through the second argument of the `uploadFile` function (see the [API docs](./api-reference/classes/bee#uploadfile)) - - - - -```ts -const file = new File(["foo"], "foo.txt", { type: "text/plain" }) - -const hash = await bee.uploadFile(file) -const retrievedData = await bee.downloadFile(hash) - -console.log(retrievedData.name) // prints 'foo.txt' -console.log(retrievedData.contentType) // prints 'text/plain' -console.log(new TextDecoder("utf-8").decode(retrievedData.data)) // prints 'foo' -``` - - - - -```js -const file = new File(["foo"], "foo.txt", { type: "text/plain" }) - -const hash = await bee.uploadFile(file) -const retrievedData = await bee.downloadFile(hash) - -console.log(retrievedData.name) // prints 'foo.txt' -console.log(retrievedData.contentType) // prints 'text/plain' -console.log(new TextDecoder("utf-8").decode(retrievedData.data)) // prints 'foo' -``` - - - \ No newline at end of file diff --git a/docs/user-documentation/upload-download.md b/docs/user-documentation/upload-download.md new file mode 100644 index 00000000..48621111 --- /dev/null +++ b/docs/user-documentation/upload-download.md @@ -0,0 +1,233 @@ +--- +title: Upload and Download +hide_title: true +id: upload-download +slug: /upload-download +sidebar_label: Upload and Download +--- + +import Tabs from '@theme/Tabs' +import TabItem from '@theme/TabItem' + +## Upload and Download + +Uploading your data to Swarm is easy with `bee-js`. Based on your needs you can either upload directly unstructured data, single file or even complex directories. Let's walk through the options one by one. + +### Data + +You can upload and retrieve any `string` or `Uint8Array` data with [`uploadData`](./api-reference/classes/bee#uploaddata) and [`downloadData`](./api-reference/classes/bee#downloaddata) functions. + + + +```ts +const hash = await bee.uploadData("Bee is awesome!") + +// prints Swarm hash of the file with which it can be retrieved +// here it is fd79d5e0ebd8407e422f53ce1d7c4c41ebf403be55143900f8d1490560294780 +console.log(hash) + +const retrievedData = await bee.downloadData(hash) + +console.log(new TextDecoder("utf-8").decode(retrievedData)) // prints 'Bee is awesome!' +``` + + + + +```js +const hash = await bee.uploadData("Bee is awesome!") + +// prints Swarm hash of the file with which it can be retrieved +// here it is fd79d5e0ebd8407e422f53ce1d7c4c41ebf403be55143900f8d1490560294780 +console.log(hash) + +const retrievedData = await bee.downloadData(hash) + +console.log(new TextDecoder("utf-8").decode(retrievedData)) // prints 'Bee is awesome!' +``` + + + + +:::info Tip +Swarm reference or hash is a 64 characters long hex string which is the address of the uploaded data, file or directory. +::: + +### Single file + +You can also upload files and include a filename. When you download the file, `bee-js` will return aditional information like `contentType` or `name` of the file. + + + + +```ts +const hash = await bee.uploadFile("Bee is awesome!", "textfile.txt") +const retrievedFile = await bee.downloadFile(hash) + +console.log(retrievedFile.name) // prints 'textfile.txt' +console.log(retrievedFile.contentType) // prints 'application/octet-stream' +console.log(new TextDecoder("utf-8").decode(retrievedFile.data)) // prints 'Bee is awesome!' +``` + + + + +```js +const hash = await bee.uploadFile("Bee is awesome!", "textfile.txt") +const retrievedFile = await bee.downloadFile(hash) + +console.log(retrievedFile.name) // prints 'textfile.txt' +console.log(retrievedFile.contentType) // prints 'application/octet-stream' +console.log(new TextDecoder("utf-8").decode(retrievedFile.data)) // prints 'Bee is awesome!' +``` + + + + +In browsers, you can upload directly `File` type. The filename is taken from the file object itself, but can be overwritten through the second argument of the `uploadFile` function (see the [API docs](./api-reference/classes/bee#uploadfile)) + + + + +```ts +const file = new File(["foo"], "foo.txt", { type: "text/plain" }) + +const hash = await bee.uploadFile(file) +const retrievedFile = await bee.downloadFile(hash) + +console.log(retrievedFile.name) // prints 'foo.txt' +console.log(retrievedFile.contentType) // prints 'text/plain' +console.log(new TextDecoder("utf-8").decode(retrievedFile.data)) // prints 'foo' +``` + + + + +```js +const file = new File(["foo"], "foo.txt", { type: "text/plain" }) + +const hash = await bee.uploadFile(file) +const retrievedFile = await bee.downloadFile(hash) + +console.log(retrievedFile.name) // prints 'foo.txt' +console.log(retrievedFile.contentType) // prints 'text/plain' +console.log(new TextDecoder("utf-8").decode(retrievedFile.data)) // prints 'foo' +``` + + + + +### Files and Directories + +The last supported mode is upload of files and directories. In browsers, you can easily upload an array of `File` comming from your form directly as well as [`FileList`](https://developer.mozilla.org/en-US/docs/Web/API/FileList). If the files uploaded through `uploadFiles` have a relative path, they are added relative to this filepath. Otherwise, the whole structure is flattened into single directory. + + + + +```ts +const foo = new File(["foo"], "foo.txt", { type: "text/plain" }) +const bar = new File(["bar"], "bar.txt", { type: "text/plain" }) + +const hash = await bee.uploadFiles([ foo, bar ]) // upload + +const rFoo = await bee.downloadFileFromCollection(hash, './foo.txt') // download foo +const rBar = await bee.downloadFileFromCollection(hash, './bar.txt') // download bar + +console.log(new TextDecoder("utf-8").decode(rFoo.data)) // prints 'foo' +console.log(new TextDecoder("utf-8").decode(rBar.data)) // prints 'bar' +``` + + + + +```js +const foo = new File(["foo"], "foo.txt", { type: "text/plain" }) +const bar = new File(["bar"], "bar.txt", { type: "text/plain" }) + +const hash = await bee.uploadFiles([ foo, bar ]) // upload + +const rFoo = await bee.downloadFileFromCollection(hash, './foo.txt') // download foo +const rBar = await bee.downloadFileFromCollection(hash, './bar.txt') // download bar + +console.log(new TextDecoder("utf-8").decode(rFoo.data)) // prints 'foo' +console.log(new TextDecoder("utf-8").decode(rBar.data)) // prints 'bar' +``` + + + + +In nodejs, you may utilise the `uploadFilesFromDirectory` function, which takes directory path as input and upload all files in that directory. Lets assum we have following data structure: + +```sh +. ++-- foo.txt ++-- dir +| +-- bar.txt +``` + + + + +```ts +const hash = await bee.uploadFilesFromDirectory('./', true) // upload recursively current folder + +const rFoo = await bee.downloadFileFromCollection(hash, './foo.txt') // download foo +const rBar = await bee.downloadFileFromCollection(hash, './dir/bar.txt') // download bar + +console.log(new TextDecoder("utf-8").decode(rFoo.data)) // prints 'foo' +console.log(new TextDecoder("utf-8").decode(rBar.data)) // prints 'bar' +``` + + + + +```js +const hash = await bee.uploadFilesFromDirectory('./', true) // upload recursively current folder + +const rFoo = await bee.downloadFileFromCollection(hash, './foo.txt') // download foo +const rBar = await bee.downloadFileFromCollection(hash, './dir/bar.txt') // download bar + +console.log(new TextDecoder("utf-8").decode(rFoo.data)) // prints 'foo' +console.log(new TextDecoder("utf-8").decode(rBar.data)) // prints 'bar' +``` + + + + +## Retrieve file from node or gateway + +You can always retrieve your files and data directly from the bee node through browser as well. For example, if you want to retrieve the "Bee is awesome!" text uploaded to Swarm in section [upload data](#data), you can directly access it with: [http://localhost:1633/files/fd79d5...294780](http://localhost:1633/files/fd79d5e0ebd8407e422f53ce1d7c4c41ebf403be55143900f8d1490560294780) + +To share files with someone who isn't running a Bee node yet, simply change the host in the link to be one of our public gateways. Send the link to your friends, and they will be able to download the file too! + +[https://gateway.ethswarm.org/files/fd79d5...294780](https://gateway.ethswarm.org/files/fd79d5e0ebd8407e422f53ce1d7c4c41ebf403be55143900f8d1490560294780) diff --git a/sidebars.js b/sidebars.js index 17ef6a0e..a37787bf 100644 --- a/sidebars.js +++ b/sidebars.js @@ -6,7 +6,9 @@ module.exports = { label: 'User Documentation', items: [ 'user-documentation/getting-started', - 'user-documentation/upload-download-data', + 'user-documentation/upload-download', + 'user-documentation/track-upload', + // 'user-documentation/pss', ], collapsed: false },