Skip to content

feat: remove redundant language selectors from User Documentation #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 5, 2022
Merged

feat: remove redundant language selectors from User Documentation #98

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5dea5fc
docs: add information to README about bee-js submodule requirement
trentrand Dec 23, 2021
a165fd1
fix: remove redundant language selectors from User Documentation
trentrand Dec 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,22 @@ Documentation for the [Swarm Bee-js javascript library](https://github.com/ether

You must use **node 14** or above. We recommend [nvm](https://github.com/nvm-sh/nvm).

### Prerequisites

This project requires the bee-js repository to be cloned as a git submodule.

You can fetch it by cloning the entire repository with the following command:

```
$ git clone --recurse-submodules https://github.com/ethersphere/bee-js.git
```

Or optionally fetch the submodule after cloning with the following command:

```
$ git submodule update --init
```

### Installation

```
Expand Down
22 changes: 0 additions & 22 deletions docs/user-documentation/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,34 +43,12 @@ yarn add @ethersphere/bee-js --save
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).
Be aware, if you will pass invalid URL the constructor will throw an exception!


<Tabs
groupId="lang_preferrence"
defaultValue="ts"
values={[
{label: 'TypeScript', value: 'ts'},
{label: 'JavaScript', value: 'js'},
]}>
<TabItem value="ts">

```ts
import { Bee } from "@ethersphere/bee-js"

const bee = new Bee('http://localhost:1633')
```

</TabItem>
<TabItem value="js">

```js
import { Bee } from "@ethersphere/bee-js"

const bee = new Bee('http://localhost:1633')
```

</TabItem>
</Tabs>

That’s it! now you can use the `bee` object.

:::info Run your own Bee node
Expand Down
4 changes: 2 additions & 2 deletions docs/user-documentation/pss.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,8 +174,8 @@ subscription.cancel()

```js
const handler = {
onMessage: (message: Data) => {console.log(message.text())},
onError: (error: BeeError) => {console.log(error)}
onMessage: (message) => {console.log(message.text())},
onError: (error) => {console.log(error)}
}

// Subscribe
Expand Down
68 changes: 0 additions & 68 deletions docs/user-documentation/track-upload.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,57 +45,14 @@ If you are using a node that is in Gateway mode then this operation is not allow

Creating a tag is easy. Just use the `createTag` function.

<Tabs
groupId="lang_preferrence"
defaultValue="ts"
values={[
{label: 'TypeScript', value: 'ts'},
{label: 'JavaScript', value: 'js'},
]}>
<TabItem value="ts">

```ts
const tag = await bee.createTag()
```

</TabItem>
<TabItem value="js">

```js
const tag = await bee.createTag()
```

</TabItem>
</Tabs>

## Upload with tag

You can then use the tag when uploading data, by providing it in the options arguments for each of these methods.

<Tabs
groupId="lang_preferrence"
defaultValue="ts"
values={[
{label: 'TypeScript', value: 'ts'},
{label: 'JavaScript', value: 'js'},
]}>
<TabItem value="ts">

```ts
const postageBatchId = getOrCreatePostageBatch()

await bee.uploadData(postageBatchId, "Bee is awesome!", { tag })
// OR
await bee.uploadFile(postageBatchId, file, "foo.txt", { tag })
// OR
await bee.uploadFiles(postageBatchId, files, { tag })
// OR
await bee.uploadFilesFromDirectory(postageBatchId, "./", { tag })
```

</TabItem>
<TabItem value="js">

```js
const postageBatchId = getOrCreatePostageBatch()

Expand All @@ -108,9 +65,6 @@ await bee.uploadFiles(postageBatchId, files, { tag })
await bee.uploadFilesFromDirectory(postageBatchId, "./", { tag })
```

</TabItem>
</Tabs>

## Retrieve tag

:::warning Forbidden on Gateways
Expand All @@ -119,30 +73,8 @@ If you are using a node that is in Gateway mode then this operation is not allow

Each time you want to check the upload status, you can use the `retrieveTag` function.


<Tabs
groupId="lang_preferrence"
defaultValue="ts"
values={[
{label: 'TypeScript', value: 'ts'},
{label: 'JavaScript', value: 'js'},
]}>
<TabItem value="ts">

```ts
const updatedTag = await bee.retrieveTag(tag)
// OR
const updatedTag = await bee.retrieveTag(tag.uid)
```

</TabItem>
<TabItem value="js">

```js
const updatedTag = await bee.retrieveTag(tag)
// OR
const updatedTag = await bee.retrieveTag(tag.uid)
```

</TabItem>
</Tabs>
138 changes: 1 addition & 137 deletions docs/user-documentation/upload-download.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,31 +30,6 @@ When you download data the return type is [`Data`](../api/interfaces/data.md) in
- `hex()` that converts the bytes into **non-prefixed** hex string
- `json()` that converts the bytes into JSON object

<Tabs
groupId="lang_preferrence"
defaultValue="ts"
values={[
{label: 'TypeScript', value: 'ts'},
{label: 'JavaScript', value: 'js'},
]}>
<TabItem value="ts">

```ts
const postageBatchId = await bee.createPostageBatch("100", 17)
const result = await bee.uploadData(postageBatchId, "Bee is awesome!")

// prints Swarm hash of the file with which it can be retrieved
// here it is fd79d5e0ebd8407e422f53ce1d7c4c41ebf403be55143900f8d1490560294780
console.log(result.reference)

const retrievedData = await bee.downloadData(result.reference)

console.log(retrievedData.text()) // prints 'Bee is awesome!'
```

</TabItem>
<TabItem value="js">

```js
const postageBatchId = await bee.createPostageBatch("100", 17)
const result = await bee.uploadData(postageBatchId, "Bee is awesome!")
Expand All @@ -68,9 +43,6 @@ const retrievedData = await bee.downloadData(result.reference)
console.log(retrievedData.text()) // prints 'Bee is awesome!'
```

</TabItem>
</Tabs>

:::info Tip
Swarm reference or hash is a 64 characters long hex string which is the address of the uploaded data, file or directory.
:::
Expand All @@ -79,28 +51,6 @@ Swarm reference or hash is a 64 characters long hex string which is the address

You can also upload files and include a filename. When you download the file, `bee-js` will return additional information like `contentType` or `name` of the file.

<Tabs
groupId="lang_preferrence"
defaultValue="ts"
values={[
{label: 'TypeScript', value: 'ts'},
{label: 'JavaScript', value: 'js'},
]}>
<TabItem value="ts">

```ts
const postageBatchId = await bee.createPostageBatch("100", 17)
const result = await bee.uploadFile(postageBatchId, "Bee is awesome!", "textfile.txt")
const retrievedFile = await bee.downloadFile(result.reference)

console.log(retrievedFile.name) // prints 'textfile.txt'
console.log(retrievedFile.contentType) // prints 'application/octet-stream'
console.log(retrievedFile.data.text()) // prints 'Bee is awesome!'
```

</TabItem>
<TabItem value="js">

```js
const postageBatchId = await bee.createPostageBatch("100", 17)
const result = await bee.uploadFile(postageBatchId, "Bee is awesome!", "textfile.txt")
Expand All @@ -111,35 +61,8 @@ console.log(retrievedFile.contentType) // prints 'application/octet-stream'
console.log(retrievedFile.data.text()) // prints 'Bee is awesome!'
```

</TabItem>
</Tabs>

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/classes/bee.md#uploadfile))

<Tabs
groupId="lang_preferrence"
defaultValue="ts"
values={[
{label: 'TypeScript', value: 'ts'},
{label: 'JavaScript', value: 'js'},
]}>
<TabItem value="ts">

```ts
const file = new File(["foo"], "foo.txt", { type: "text/plain" })

const postageBatchId = await bee.createPostageBatch("100", 17)
const result = await bee.uploadFile(postageBatchId, file)
const retrievedFile = await bee.downloadFile(result.reference)

console.log(retrievedFile.name) // prints 'foo.txt'
console.log(retrievedFile.contentType) // prints 'text/plain'
console.log(retrievedFile.data.text()) // prints 'foo'
```

</TabItem>
<TabItem value="js">

```js
const file = new File(["foo"], "foo.txt", { type: "text/plain" })

Expand All @@ -152,39 +75,10 @@ console.log(retrievedFile.contentType) // prints 'text/plain'
console.log(retrievedFile.data.text()) // prints 'foo'
```

</TabItem>
</Tabs>

### 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.

<Tabs
groupId="lang_preferrence"
defaultValue="ts"
values={[
{label: 'TypeScript', value: 'ts'},
{label: 'JavaScript', value: 'js'},
]}>
<TabItem value="ts">

```ts
const foo = new File(["foo"], "foo.txt", { type: "text/plain" })
const bar = new File(["bar"], "bar.txt", { type: "text/plain" })

const postageBatchId = await bee.createPostageBatch("100", 17)
const result = await bee.uploadFiles(postageBatchId, [ foo, bar ]) // upload

const rFoo = await bee.downloadFile(result.reference, './foo.txt') // download foo
const rBar = await bee.downloadFile(result.reference, './bar.txt') // download bar

console.log(rFoo.data.text()) // prints 'foo'
console.log(rBar.data.text()) // prints 'bar'
```

</TabItem>
<TabItem value="js">

```js
const foo = new File(["foo"], "foo.txt", { type: "text/plain" })
const bar = new File(["bar"], "bar.txt", { type: "text/plain" })
Expand All @@ -199,9 +93,6 @@ console.log(rFoo.data.text()) // prints 'foo'
console.log(rBar.data.text()) // prints 'bar'
```

</TabItem>
</Tabs>

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
Expand All @@ -211,34 +102,10 @@ In nodejs, you may utilise the `uploadFilesFromDirectory` function, which takes
| +-- bar.txt
```

<Tabs
groupId="lang_preferrence"
defaultValue="ts"
values={[
{label: 'TypeScript', value: 'ts'},
{label: 'JavaScript', value: 'js'},
]}>
<TabItem value="ts">

```ts
const postageBatchId = await bee.createPostageBatch("100", 17)

const result = await bee.uploadFilesFromDirectory(postageBatchId, './') // upload recursively current folder

const rFoo = await bee.downloadFile(result.reference, './foo.txt') // download foo
const rBar = await bee.downloadFile(result.reference, './dir/bar.txt') // download bar

console.log(rFoo.data.text()) // prints 'foo'
console.log(rBar.data.text()) // prints 'bar'
```

</TabItem>
<TabItem value="js">

```js
const postageBatchId = await bee.createPostageBatch("100", 17)

const hash = await bee.uploadFilesFromDirectory(postageBatchId, './') // upload recursively current folder
const result = await bee.uploadFilesFromDirectory(postageBatchId, './') // upload recursively current folder

const rFoo = await bee.downloadFile(result.reference, './foo.txt') // download foo
const rBar = await bee.downloadFile(result.reference, './dir/bar.txt') // download bar
Expand All @@ -247,9 +114,6 @@ console.log(rFoo.data.text()) // prints 'foo'
console.log(rBar.data.text()) // prints 'bar'
```

</TabItem>
</Tabs>

## 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)
Expand Down