@dfinity/assets
Version:
JavaScript and TypeScript library to manage assets on the Internet Computer
184 lines (145 loc) • 4.42 kB
Markdown
# @dfinity/assets
Manage assets on an Internet Computer assets canister.
Do you want to know more about developing on the Internet Computer? Visit the [Developer Docs](https://internetcomputer.org/docs/home).
Additional API Documentation can be found [here](https://js.icp.build/core/v3.2/libs/assets/api).
---
## Installation
Using AssetManager:
```shell
npm i --save @dfinity/assets
```
### In the browser:
```ts
import { AssetManager } from '@dfinity/assets';
```
### In Node.js:
```ts
const { AssetManager } = require('@dfinity/assets');
```
## Using AssetManager
AssetManager supports the (chunked) upload of File, Blob, ArrayBuffer, Uint8Array and number[].
Create an asset manager instance
```ts
const assetManager = new AssetManager({
canisterId: ..., // Principal of assets canister
agent: ..., // Identity in agent must be authorized by the assets canister to make any changes
});
```
AssetManager config extends Actor config with additional options
```ts
export interface AssetManagerConfig extends ActorConfig {
/**
* Max number of concurrent requests to the Internet Computer
* @default 16
*/
concurrency?: number;
/**
* Max file size in bytes that the asset manager shouldn't chunk
* @default 1900000
*/
maxSingleFileSize?: number;
/**
* Size of each chunk in bytes when the asset manager has to chunk a file
* @default 1900000
*/
maxChunkSize?: number;
}
```
Select file and upload to asset canister in browser
```ts
const input = document.createElement('input');
input.type = 'file';
input.addEventListener('change', async e => {
const file = e.target.files[0];
const key = await assetManager.store(file);
});
input.click();
```
Config can be optionally passed as second argument in the `store` method.
The `fileName` property is required when the data passed in the first argument
is not a `File`, file path or custom `Readable` implementation
```ts
export interface StoreConfig {
/**
* File name
* @default File object name or name in file path
*/
fileName?: string;
/**
* File path that file will be uploaded to
* @default '/'
*/
path?: string;
/**
* File content type
* @default File/Blob object type or type from file name extension
*/
contentType?: string;
/**
* Content encoding
* @default 'identity'
*/
contentEncoding?: ContentEncoding;
/**
* File hash generation will be skipped if hash is provided
*/
sha256?: Uint8Array;
/**
* Callback method to get upload progress in bytes (current / total)
*/
onProgress?: (progress: Progress) => void;
}
```
Read file from disk and upload to asset canister in Node.js
```ts
const file = fs.readFileSync('./example.csv');
const key = await assetManager.store(file, { fileName: 'example.csv' });
```
Delete file from asset canister
```ts
const key = '/path/to/example.jpg';
await assetManager.delete(key);
```
List files in asset canister
```ts
const files = await assetManager.list();
```
Upload multiple files and delete an existing file as batch in Node.js
```ts
const fs = require('fs');
const banana = fs.readFileSync('./banana.png');
const apple = fs.readFileSync('./apple.png');
const strawberry = fs.readFileSync('./strawberry.png');
const batch = assetManager.batch();
const keys = [
await batch.store(banana, { fileName: 'banana.png' }),
await batch.store(apple, { fileName: 'apple.png', path: '/directory/with/apples' }),
await batch.store(strawberry, { fileName: 'strawberry.png' }),
];
await batch.delete('/path/to/old/file.csv');
await batch.commit();
```
Read file from disk, compress with gzip and upload to asset canister in Node.js,
GZIP compression is recommended for HTML and JS files
```ts
const fs = require('fs');
const pako = require('pako');
const file = fs.readFileSync('./index.html');
const gzippedFile = pako.gzip(file);
const key = await assetManager.insert(gzippedFile, {
fileName: 'index.html',
contentEncoding: 'gzip',
});
```
Download image asset to blob and open in new browser tab
```ts
const asset = await assetManager.get('/path/to/file/on/asset/canister/motoko.png');
const blob = await asset.toBlob();
const url = URL.createObjectURL(blob);
window.open(URL.createObjectURL(blob, '_blank'));
```
Download and write asset to path in Node.js
```ts
const asset = await assetManager.get('/large_dataset.csv');
asset.write('/large_dataset.csv');
```