Skip to content

Commit 221b524

Browse files
peterpeterparkerpeterpeterparker
authored
docs: review storage - upload file and blob (#456)
Signed-off-by: David Dal Busco <david.dalbusco@outlook.com>
1 parent c331011 commit 221b524

9 files changed

Lines changed: 101 additions & 16 deletions

File tree

‎docs/build/components/http-headers.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,6 @@ The `headers` is an array of objects, each containing `key` and `value`, and the
4444

4545
- The `Content-Type` header is calculated automatically and cannot be altered.
4646
- No validation or check for uniqueness is performed. For example, if a header matches a file based on multiple rules, multiple headers will be set.
47-
- Likewise, if you provide the same header when you [upload](https://juno.build/docs/build/storage#upload-asset) file to your "Storage" and within the configuration, both headers will be set in the response.
47+
- Likewise, if you provide the same header when you [upload](https://juno.build/docs/build/storage#upload-file) file to your "Storage" and within the configuration, both headers will be set in the response.
4848

4949
:::

‎docs/build/storage/development.mdx‎

Lines changed: 93 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,11 @@ import ClientSide from "../components/client-side.mdx";
88

99
---
1010

11-
## Upload asset
11+
## Upload file
1212

13-
To upload an asset, use the following code:
13+
When you upload a file, it becomes an **asset** stored in the Storage of your Satellite. Assets are accessible over the web and can be listed, deleted, or protected using tokens.
14+
15+
To upload a file, use the following code:
1416

1517
```typescript
1618
import { uploadFile } from "@junobuild/core";
@@ -21,7 +23,9 @@ const result = await uploadFile({
2123
});
2224
```
2325

24-
The `data` parameter is the file you want to upload. This is typically selected using an HTML `<input type="file" /> ` element.
26+
#### Parameters
27+
28+
The `data` parameter is the file you want to upload. This is a `Blob`, typically selected using an HTML `<input type="file" />` element.
2529

2630
The `uploadFile` function provides various options, including:
2731

@@ -38,7 +42,36 @@ The `uploadFile` function provides various options, including:
3842

3943
:::
4044

41-
### Protected asset
45+
#### Returns
46+
47+
The function returns the uploaded asset key as an object with the following fields:
48+
49+
- `fullPath`: The unique path to the asset. Example: `/images/myimage.jpg`.
50+
- `name`: The name of the asset (typically the filename). Example: `myimage.jpg`.
51+
- `downloadUrl`: The URL to access the asset on the web or to download it. This URL can be used in a browser or embedded directly in HTML elements like `<img>` or `<a>`.
52+
53+
---
54+
55+
## Upload blob
56+
57+
The `uploadBlob` function works like [`uploadFile`](#upload-file) but does **not** infer the filename from the data.
58+
You must explicitly provide the `filename`.
59+
60+
```typescript
61+
import { uploadBlob } from "@junobuild/core";
62+
63+
const result = await uploadBlob({
64+
data: new Blob([myBuffer]),
65+
filename: "generated.jpg",
66+
collection: "images"
67+
});
68+
```
69+
70+
This is useful when uploading raw binary data that wasn't selected via a file input.
71+
72+
---
73+
74+
## Protected assets
4275

4376
While all assets can be found on the internet, it is possible to make their URL difficult to guess so that they remain undiscoverable (**as long as they are not shared**) and considered "private".
4477

@@ -71,7 +104,7 @@ const myList = await listAssets({
71104
});
72105
```
73106

74-
### Parameters
107+
#### Parameters
75108

76109
The function requires a collection and accepts various optional parameters, including a matcher (a regex applied to the assets fullPaths and descriptions), pagination options, and sorting order.
77110

@@ -225,7 +258,7 @@ The function returns the assets and various information, in the form of an objec
225258

226259
```typescript
227260
{
228-
items: []; // The data - array of assets
261+
items: []; // The data - array of assets without their content
229262
items_length: bigint; // The number of assets - basically items.length
230263
items_page?: bigint; // If the query is paginated, at what page (starting from 0) do the items find the place
231264
matches_length: bigint; // The total number of matching results
@@ -235,6 +268,58 @@ The function returns the assets and various information, in the form of an objec
235268

236269
---
237270

271+
## Download URL
272+
273+
The `downloadUrl` function is used to generate a public URL for accessing a specific asset stored on a Satellite.
274+
275+
:::note
276+
277+
You get similar information directly from the result of an upload.
278+
This function can be used to generate the URL on the fly.
279+
280+
:::
281+
282+
This URL can be used to:
283+
284+
- Open the file directly in a browser
285+
- Embed the asset in HTML elements such as `<img src="...">` or `<a href="...">`
286+
- Trigger a download when used in an `<a href="..." download>` link
287+
288+
```typescript
289+
import { downloadUrl } from "@junobuild/core";
290+
291+
const url = downloadUrl({
292+
assetKey: {
293+
fullPath: "/images/logo.png",
294+
token: "a-secret-token" // optional
295+
}
296+
});
297+
298+
// Example usage
299+
<img src={url} alt="Logo" />
300+
```
301+
302+
#### Parameters
303+
304+
- **`assetKey`** (required)
305+
- **`fullPath`**: The full path to the asset (e.g., `/images/file.jpg`).
306+
- **`token`** (optional): A secret token used to access protected assets.
307+
308+
- **`satellite`** (optional)
309+
Required only in Node.js environments to specify which Satellite to use.
310+
311+
#### Returns
312+
313+
- A `string` representing the full URL to access the asset.
314+
315+
:::note
316+
317+
If a `token` is provided when uploading the asset, it must also be included in the URL to access it. This makes the asset effectively private until shared with the token.
318+
319+
:::
320+
321+
---
322+
238323
## Count assets
239324

240325
The `countAssets` function is used to count the number of assets in a specified collection without retrieving the actual assets.
@@ -247,7 +332,7 @@ const assetCount = await countAssets({
247332
});
248333
```
249334

250-
### Usage
335+
#### Usage
251336

252337
This function accepts similar parameters as the `listAssets` function, including `collection`, `matcher`, and `owner`, and returns the count of matching documents.
253338

@@ -304,7 +389,7 @@ import { deleteFilteredAssets } from "@junobuild/core";
304389
await deleteFilteredAssets({
305390
collection: "my_collection_key",
306391
filter: {
307-
// Same options as filter of listAssets
392+
// Uses the same filter options as listAssets
308393
}
309394
});
310395
```

‎docs/examples/angular.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,5 +125,5 @@ The following functions from `@junobuild/core` are used in this example:
125125
| `listDocs` | List documents in a collection | [`src/app/services/docs.service.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/services/docs.service.ts) | [List documents](../build/datastore/development#list-documents) |
126126
| `setDoc` | Create or update a document | [`src/app/components/modal/modal.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/modal/modal.component.ts) | [Add a document](../build/datastore/development#add-a-document) |
127127
| `deleteDoc` | Delete a document | [`src/app/components/delete/delete.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/delete/delete.component.ts) | [Delete a document](../build/datastore/development#delete-a-document) |
128-
| `uploadFile` | Upload a file to storage | [`src/app/components/modal/modal.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/modal/modal.component.ts) | [Upload asset](../build/storage/development#upload-asset) |
128+
| `uploadFile` | Upload a file to storage | [`src/app/components/modal/modal.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/modal/modal.component.ts) | [Upload file](../build/storage/development#upload-file) |
129129
| `deleteAsset` | Delete a file from storage | [`src/app/components/delete/delete.component.ts`](https://github.com/junobuild/create-juno/blob/main/templates/angular-example/src/app/components/delete/delete.component.ts) | [Delete asset](../build/storage/development#delete-asset) |

‎docs/examples/nextjs.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,5 +125,5 @@ The following functions from `@junobuild/core` are used in this example:
125125
| `listDocs` | List documents in a collection | [`src/components/table.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/table.tsx) | [List documents](../build/datastore/development#list-documents) |
126126
| `setDoc` | Create or update a document | [`src/components/modal.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/modal.tsx) | [Add a document](../build/datastore/development#add-a-document) |
127127
| `deleteDoc` | Delete a document | [`src/components/delete.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/delete.tsx) | [Delete a document](../build/datastore/development#delete-a-document) |
128-
| `uploadFile` | Upload a file to storage | [`src/components/modal.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/modal.tsx) | [Upload asset](../build/storage/development#upload-asset) |
128+
| `uploadFile` | Upload a file to storage | [`src/components/modal.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/modal.tsx) | [Upload file](../build/storage/development#upload-file) |
129129
| `deleteAsset` | Delete a file from storage | [`src/components/delete.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/nextjs-example/src/components/delete.tsx) | [Delete asset](../build/storage/development#delete-asset) |

‎docs/examples/react-javascript.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -133,5 +133,5 @@ The following functions from `@junobuild/core` are used in this example:
133133
| `listDocs` | List documents in a collection | [`src/components/Table.jsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-example/src/components/Table.jsx) | [List documents](../build/datastore/development#list-documents) |
134134
| `setDoc` | Create or update a document | [`src/components/Modal.jsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-example/src/components/Modal.jsx) | [Add a document](../build/datastore/development#add-a-document) |
135135
| `deleteDoc` | Delete a document | [`src/components/Delete.jsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-example/src/components/Delete.jsx) | [Delete a document](../build/datastore/development#delete-a-document) |
136-
| `uploadFile` | Upload a file to storage | [`src/components/Modal.jsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-example/src/components/Modal.jsx) | [Upload asset](../build/storage/development#upload-asset) |
136+
| `uploadFile` | Upload a file to storage | [`src/components/Modal.jsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-example/src/components/Modal.jsx) | [Upload file](../build/storage/development#upload-file) |
137137
| `deleteAsset` | Delete a file from storage | [`src/components/Delete.jsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-example/src/components/Delete.jsx) | [Delete asset](../build/storage/development#delete-asset) |

‎docs/examples/react-typescript.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,5 +129,5 @@ The following functions from `@junobuild/core` are used in this example:
129129
| `listDocs` | List documents in a collection | [`src/components/Table.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-ts-example/src/components/Table.tsx) | [List documents](../build/datastore/development#list-documents) |
130130
| `setDoc` | Create or update a document | [`src/components/Modal.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-ts-example/src/components/Modal.tsx) | [Add a document](../build/datastore/development#add-a-document) |
131131
| `deleteDoc` | Delete a document | [`src/components/Delete.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-ts-example/src/components/Delete.tsx) | [Delete a document](../build/datastore/development#delete-a-document) |
132-
| `uploadFile` | Upload a file to storage | [`src/components/Modal.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-ts-example/src/components/Modal.tsx) | [Upload asset](../build/storage/development#upload-asset) |
132+
| `uploadFile` | Upload a file to storage | [`src/components/Modal.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-ts-example/src/components/Modal.tsx) | [Upload file](../build/storage/development#upload-file) |
133133
| `deleteAsset` | Delete a file from storage | [`src/components/Delete.tsx`](https://github.com/junobuild/create-juno/blob/main/templates/react-ts-example/src/components/Delete.tsx) | [Delete asset](../build/storage/development#delete-asset) |

‎docs/examples/sveltekit.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,5 +126,5 @@ The following functions from `@junobuild/core` are used in this example:
126126
| `listDocs` | List documents in a collection | [`src/lib/components/Table.svelte`](https://github.com/junobuild/create-juno/blob/main/templates/sveltekit-example/src/lib/components/Table.svelte) | [List documents](../build/datastore/development#list-documents) |
127127
| `setDoc` | Create or update a document | [`src/lib/components/Modal.svelte`](https://github.com/junobuild/create-juno/blob/main/templates/sveltekit-example/src/lib/components/Modal.svelte) | [Add a document](../build/datastore/development#add-a-document) |
128128
| `deleteDoc` | Delete a document | [`src/lib/components/Delete.svelte`](https://github.com/junobuild/create-juno/blob/main/templates/sveltekit-example/src/lib/components/Delete.svelte) | [Delete a document](../build/datastore/development#delete-a-document) |
129-
| `uploadFile` | Upload a file to storage | [`src/lib/components/Modal.svelte`](https://github.com/junobuild/create-juno/blob/main/templates/sveltekit-example/src/lib/components/Modal.svelte) | [Upload asset](../build/storage/development#upload-asset) |
129+
| `uploadFile` | Upload a file to storage | [`src/lib/components/Modal.svelte`](https://github.com/junobuild/create-juno/blob/main/templates/sveltekit-example/src/lib/components/Modal.svelte) | [Upload file](../build/storage/development#upload-file) |
130130
| `deleteAsset` | Delete a file from storage | [`src/lib/components/Delete.svelte`](https://github.com/junobuild/create-juno/blob/main/templates/sveltekit-example/src/lib/components/Delete.svelte) | [Delete asset](../build/storage/development#delete-asset) |

‎docs/examples/vanilla-javascript.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,5 +127,5 @@ The following functions from `@junobuild/core` are used in this example:
127127
| `listDocs` | List documents in a collection | [`src/components/table.js`](https://github.com/junobuild/create-juno/blob/main/templates/vanilla-js-example/src/components/table.js) | [List documents](../build/datastore/development#list-documents) |
128128
| `setDoc` | Create or update a document | [`src/components/modal.js`](https://github.com/junobuild/create-juno/blob/main/templates/vanilla-js-example/src/components/modal.js) | [Add a document](../build/datastore/development#add-a-document) |
129129
| `deleteDoc` | Delete a document | [`src/components/delete.js`](https://github.com/junobuild/create-juno/blob/main/templates/vanilla-js-example/src/components/delete.js) | [Delete a document](../build/datastore/development#delete-a-document) |
130-
| `uploadFile` | Upload a file to storage | [`src/components/modal.js`](https://github.com/junobuild/create-juno/blob/main/templates/vanilla-js-example/src/components/modal.js) | [Upload asset](../build/storage/development#upload-asset) |
130+
| `uploadFile` | Upload a file to storage | [`src/components/modal.js`](https://github.com/junobuild/create-juno/blob/main/templates/vanilla-js-example/src/components/modal.js) | [Upload file](../build/storage/development#upload-file) |
131131
| `deleteAsset` | Delete a file from storage | [`src/components/delete.js`](https://github.com/junobuild/create-juno/blob/main/templates/vanilla-js-example/src/components/delete.js) | [Delete asset](../build/storage/development#delete-asset) |

‎docs/examples/vue.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,5 +127,5 @@ The following functions from `@junobuild/core` are used in this example:
127127
| `listDocs` | List documents in a collection | [`src/components/Table.vue`](https://github.com/junobuild/create-juno/blob/main/templates/vue-example/src/components/Table.vue) | [List documents](../build/datastore/development#list-documents) |
128128
| `setDoc` | Create or update a document | [`src/components/Modal.vue`](https://github.com/junobuild/create-juno/blob/main/templates/vue-example/src/components/Modal.vue) | [Add a document](../build/datastore/development#add-a-document) |
129129
| `deleteDoc` | Delete a document | [`src/components/Delete.vue`](https://github.com/junobuild/create-juno/blob/main/templates/vue-example/src/components/Delete.vue) | [Delete a document](../build/datastore/development#delete-a-document) |
130-
| `uploadFile` | Upload a file to storage | [`src/components/Modal.vue`](https://github.com/junobuild/create-juno/blob/main/templates/vue-example/src/components/Modal.vue) | [Upload asset](../build/storage/development#upload-asset) |
130+
| `uploadFile` | Upload a file to storage | [`src/components/Modal.vue`](https://github.com/junobuild/create-juno/blob/main/templates/vue-example/src/components/Modal.vue) | [Upload file](../build/storage/development#upload-file) |
131131
| `deleteAsset` | Delete a file from storage | [`src/components/Delete.vue`](https://github.com/junobuild/create-juno/blob/main/templates/vue-example/src/components/Delete.vue) | [Delete asset](../build/storage/development#delete-asset) |

0 commit comments

Comments
 (0)