Skip to content

Commit 5535ec2

Browse files
vojtechsimetkavojtechsimetka
authored
feat: getting-started and upload/download section (#12)
* feat: basic getting-started * feat: added groups for taps * fix: import in JS * feat: upload data * refactor: improved wording, fixed default import * feat: added tags documentation, expanded upload & download sections
1 parent 7b53a1f commit 5535ec2

File tree

9 files changed

+482
-25
lines changed

9 files changed

+482
-25
lines changed

‎docs/getting-started/upload-your-data.md

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎docs/installation/quick-start.md

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎docs/introduction.md

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,26 @@
11
---
22
id: introduction
33
slug: /
4-
title: Welcome!
4+
title: "bee-js: Ethereum Swarm JavaScript API"
5+
sidebar_label: Introduction
56
---
67

7-
Welcome to Bee-js!
8+
`bee-js` is a library that allows you to interact with a local or remote [Bee node](https://docs.ethswarm.org/docs/).
9+
10+
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).
11+
12+
## Development
13+
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).
14+
15+
## Community
16+
There is a vibrant and buzzing community behind Swarm, get involved in one of our group channels.
17+
18+
- [Swarm](http://swarm.ethereum.org).
19+
- [Beehive Chat on Mattermost](https://beehive.ethswarm.org/).
20+
- [Orange Lounge](https://t.me/joinchat/GoVG8RHYjUpD_-bEnLC4EQ).
21+
- [Twitter @ethswarm](https://twitter.com/ethswarm).
22+
- [reddit channel](https://www.reddit.com/r/ethswarm/).
23+
24+
## Reporting a bug
25+
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. 🐝
26+

‎docs/user-documentation/getting-started.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Getting Started
3+
id: getting-started
4+
slug: /getting-started
5+
---
6+
7+
import Tabs from '@theme/Tabs'
8+
import TabItem from '@theme/TabItem'
9+
10+
First you need to get `bee-js` into your project. This can be done using your favourite package management tool or directly:
11+
12+
<Tabs
13+
groupId="pcgmng_preferrence"
14+
defaultValue="npm"
15+
values={[
16+
{label: 'npm', value: 'npm'},
17+
{label: 'yarn', value: 'yarn'},
18+
{label: 'script tag', value: 'script'},
19+
]}>
20+
<TabItem value="npm">
21+
22+
```sh
23+
npm install @ethersphere/bee-js --save
24+
```
25+
26+
</TabItem>
27+
<TabItem value="yarn">
28+
29+
```sh
30+
yarn add @ethersphere/bee-js --save
31+
```
32+
33+
</TabItem>
34+
<TabItem value="script">
35+
36+
```html
37+
<script src="https://unpkg.com/@ethersphere/bee-js/dist/index.js"></script>
38+
```
39+
40+
</TabItem>
41+
</Tabs>
42+
43+
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).
44+
45+
46+
<Tabs
47+
groupId="lang_preferrence"
48+
defaultValue="ts"
49+
values={[
50+
{label: 'TypeScript', value: 'ts'},
51+
{label: 'JavaScript', value: 'js'},
52+
]}>
53+
<TabItem value="ts">
54+
55+
```ts
56+
import { Bee } from "@ethersphere/bee-js"
57+
58+
const bee = new Bee('http://localhost:1633')
59+
```
60+
61+
</TabItem>
62+
<TabItem value="js">
63+
64+
```js
65+
import { Bee } from "@ethersphere/bee-js"
66+
67+
const bee = new Bee('http://localhost:1633')
68+
```
69+
70+
</TabItem>
71+
</Tabs>
72+
73+
That’s it! now you can use the `bee` object.
74+
75+
:::info Run your own Bee node
76+
You can find out more about running Bee node in the [Bee docs](https://docs.ethswarm.org/docs/installation/quick-start)
77+
:::

‎docs/user-documentation/pss.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Postal Service over Swarm
3+
hide_title: true
4+
id: pss
5+
slug: /pss
6+
sidebar_label: Postal Service over Swarm
7+
---
8+
9+
import Tabs from '@theme/Tabs'
10+
import TabItem from '@theme/TabItem'

‎docs/user-documentation/track-upload.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Track Upload Status
3+
id: track-upload
4+
slug: /track-upload
5+
sidebar_label: Track Upload
6+
---
7+
8+
import Tabs from '@theme/Tabs'
9+
import TabItem from '@theme/TabItem'
10+
11+
In Swarm, an instruction to upload data to the network goes through 3 consecutive stages before it is completed:
12+
13+
- Splitting
14+
- Storing
15+
- Sending
16+
17+
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.
18+
19+
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.
20+
21+
## What is a tag
22+
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:
23+
24+
```ts
25+
interface Tag {
26+
total: number // total number of chunks belonging to a tag
27+
split: number // number of chunks already processed by splitter for hashing
28+
seen: number // number of chunks already seen
29+
stored: number // number of chunks already stored locally
30+
sent: number // number of chunks sent for push syncing
31+
synced: number // number of chunks synced with proof
32+
33+
uid: number // a unique identifier for this tag
34+
address: string // the associated swarm hash for this tag
35+
startedAt: string // when the tag was first used
36+
}
37+
```
38+
39+
## Create tag
40+
41+
Creating a tag is easy. Just use the `createTag` function.
42+
43+
<Tabs
44+
groupId="lang_preferrence"
45+
defaultValue="ts"
46+
values={[
47+
{label: 'TypeScript', value: 'ts'},
48+
{label: 'JavaScript', value: 'js'},
49+
]}>
50+
<TabItem value="ts">
51+
52+
```ts
53+
const tag = await bee.createTag()
54+
```
55+
56+
</TabItem>
57+
<TabItem value="js">
58+
59+
```js
60+
const tag = await bee.createTag()
61+
```
62+
63+
</TabItem>
64+
</Tabs>
65+
66+
## Upload with tag
67+
68+
You can then use the tag when uploading data, by providing it in the options arguments for each of these methods.
69+
70+
<Tabs
71+
groupId="lang_preferrence"
72+
defaultValue="ts"
73+
values={[
74+
{label: 'TypeScript', value: 'ts'},
75+
{label: 'JavaScript', value: 'js'},
76+
]}>
77+
<TabItem value="ts">
78+
79+
```ts
80+
await bee.uploadData("Bee is awesome!", { tag })
81+
// OR
82+
await bee.uploadFile(file, "foo.txt", { tag })
83+
// OR
84+
await bee.uploadFiles(files, { tag })
85+
// OR
86+
await bee.uploadFilesToCollection("./", true, { tag })
87+
```
88+
89+
</TabItem>
90+
<TabItem value="js">
91+
92+
```js
93+
await bee.uploadData("Bee is awesome!", { tag })
94+
// OR
95+
await bee.uploadFile(file, "foo.txt", { tag })
96+
// OR
97+
await bee.uploadFiles(files, { tag })
98+
// OR
99+
await bee.uploadFilesToCollection("./", true, { tag })
100+
```
101+
102+
</TabItem>
103+
</Tabs>
104+
105+
## Retrieve tag
106+
107+
Each time you want to check the upload status, you can use the `retrieveTag` function
108+
109+
110+
<Tabs
111+
groupId="lang_preferrence"
112+
defaultValue="ts"
113+
values={[
114+
{label: 'TypeScript', value: 'ts'},
115+
{label: 'JavaScript', value: 'js'},
116+
]}>
117+
<TabItem value="ts">
118+
119+
```ts
120+
const updatedTag = await bee.retrieveTag(tag)
121+
// OR
122+
const updatedTag = await bee.retrieveTag(tag.uid)
123+
```
124+
125+
</TabItem>
126+
<TabItem value="js">
127+
128+
```js
129+
const updatedTag = await bee.retrieveTag(tag)
130+
// OR
131+
const updatedTag = await bee.retrieveTag(tag.uid)
132+
```
133+
134+
</TabItem>
135+
</Tabs>

0 commit comments

Comments
 (0)