Overview

Quick Start

The AssetManager supports the (chunked) upload of File, Blob, ArrayBuffer, Uint8Array and number[].

Create an asset manager instance:

import { AssetManager } from "@icp-sdk/canisters/assets";

const assetManager = new AssetManager({
    canisterId: ..., // Principal of assets canister
    agent: ..., // Identity in agent must be authorized by the assets canister to make any changes
});

Select file and upload to asset canister from the browser:

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();

A config argument 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.

List files stored in the asset canister:

const files = await assetManager.list();

Upload multiple files and delete an existing file as batch in Node.js:

import fs from '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:

import fs from 'fs';

const file = fs.readFileSync('./index.html');
const gzippedFile = // gzip the file here
const key = await assetManager.insert(gzippedFile, {
  fileName: 'index.html',
  contentEncoding: 'gzip',
});

Download image asset to blob and open in new browser tab:

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:

const asset = await assetManager.get('/large_dataset.csv');
asset.write('/large_dataset.csv');

Classes

AssetManager

Defined in: packages/canisters/src/assets/index.ts:237

Constructors

Constructor

new AssetManager(config): AssetManager

Defined in: packages/canisters/src/assets/index.ts:247

Create assets canister manager instance

Parameters

config

AssetManagerConfig

Additional configuration options, canister id is required

Returns

AssetManager

Methods

batch()

batch(): AssetManagerBatch

Defined in: packages/canisters/src/assets/index.ts:426

Create a batch assets operations instance, commit multiple operations in a single request

Returns

AssetManagerBatch

clear()

clear(): Promise<void>

Defined in: packages/canisters/src/assets/index.ts:391

Delete all files from assets canister

Returns

Promise<void>

delete()

delete(key): Promise<void>

Defined in: packages/canisters/src/assets/index.ts:384

Delete file from assets canister

Parameters

key

string

The path to the file on the assets canister e.g. /folder/to/my_file.txt

Returns

Promise<void>

get()

get(key, acceptEncodings?): Promise<Asset>

Defined in: packages/canisters/src/assets/index.ts:400

Get asset instance from assets canister

Parameters

key

string

The path to the file on the assets canister e.g. /folder/to/my_file.txt

acceptEncodings?

ContentEncoding[]

The accepted content encodings, defaults to [‘identity’]

Returns

Promise<Asset>

list()

list(): Promise<object[]>

Defined in: packages/canisters/src/assets/index.ts:293

Get list of all files in assets canister.

Returns

Promise<object[]>

All files in asset canister

store()

store(…args): Promise<string>

Defined in: packages/canisters/src/assets/index.ts:342

Store data on assets canister

Parameters

args

…StoreArgs

Arguments with either a file, blob, path, bytes or custom Readable implementation

Returns

Promise<string>

toReadable()

static toReadable(…args): Promise<Readable>

Defined in: packages/canisters/src/assets/index.ts:260

Create readable from store arguments

Parameters

args

…StoreArgs

Arguments with either a file, blob, path, bytes or custom Readable implementation

Returns

Promise<Readable>

Interfaces

AssetManagerConfig

Defined in: packages/canisters/src/assets/index.ts:219

Configuration that can be passed to set the canister id of the assets canister to be managed, inherits actor configuration and has additional asset manager specific configuration options.

Extends

ActorConfig

Properties

agent?

optional agent: Agent

Defined in: node_modules/@icp-sdk/core/lib/esm/agent/actor.d.ts:21

An agent to use in this call, otherwise the actor or call will try to discover the agent to use.

Inherited from

ActorConfig.agent

blsVerify?

optional blsVerify: VerifyFunc

Defined in: node_modules/@icp-sdk/core/lib/esm/agent/actor.d.ts:58

Polyfill for BLS Certificate verification in case wasm is not supported

Inherited from

ActorConfig.blsVerify

canisterId

canisterId: string | Principal

Defined in: node_modules/@icp-sdk/core/lib/esm/agent/actor.d.ts:46

The Canister ID of this Actor. This is required for an Actor.

Inherited from

ActorConfig.canisterId

concurrency?

optional concurrency: number

Defined in: packages/canisters/src/assets/index.ts:224

Max number of concurrent requests to the Internet Computer

Default

effectiveCanisterId?

optional effectiveCanisterId: Principal

Defined in: node_modules/@icp-sdk/core/lib/esm/agent/actor.d.ts:33

The effective canister ID.

Inherited from

ActorConfig.effectiveCanisterId

maxChunkSize?

optional maxChunkSize: number

Defined in: packages/canisters/src/assets/index.ts:234

Size of each chunk in bytes when the asset manager has to chunk a file

Default

maxSingleFileSize?

optional maxSingleFileSize: number

Defined in: packages/canisters/src/assets/index.ts:229

Max file size in bytes that the asset manager shouldn’t chunk

Default

pollingOptions?

optional pollingOptions: PollingOptions

Defined in: node_modules/@icp-sdk/core/lib/esm/agent/actor.d.ts:62

Polling options to use when making update calls. This will override the default DEFAULT_POLLING_OPTIONS.

Inherited from

ActorConfig.pollingOptions

queryStrategy?

optional queryStrategy: QueryStrategy

Defined in: node_modules/@icp-sdk/core/lib/esm/agent/actor.d.ts:69

Controls how query and composite_query methods are executed.

'query' (default) — standard non-replicated query call.
'update' — send query methods as update calls that go through consensus.

Default

'query'

Inherited from

ActorConfig.queryStrategy

Methods

callTransform()?

optional callTransform(methodName, args, callConfig): void | Partial<CallConfig>

Defined in: node_modules/@icp-sdk/core/lib/esm/agent/actor.d.ts:50

An override function for update calls’ CallConfig. This will be called on every calls.

Parameters

methodName

string

args

unknown[]

callConfig

CallConfig

Returns

void | Partial<CallConfig>

Inherited from

ActorConfig.callTransform

queryTransform()?

optional queryTransform(methodName, args, callConfig): void | Partial<CallConfig>

Defined in: node_modules/@icp-sdk/core/lib/esm/agent/actor.d.ts:54

An override function for query calls’ CallConfig. This will be called on every query.

Parameters

methodName

string

args

unknown[]

callConfig

CallConfig

Returns

void | Partial<CallConfig>

Inherited from

ActorConfig.queryTransform

CommitBatchArgs

Defined in: packages/canisters/src/assets/index.ts:210

Arguments to commit batch in asset manager

Properties

onProgress()?

optional onProgress: (progress) => void

Defined in: packages/canisters/src/assets/index.ts:211

Parameters

progress

Progress

Returns

void

Progress

Defined in: packages/canisters/src/assets/index.ts:135

Upload progress in bytes

Properties

current

current: number

Defined in: packages/canisters/src/assets/index.ts:136

total

total: number

Defined in: packages/canisters/src/assets/index.ts:137

StoreConfig

Defined in: packages/canisters/src/assets/index.ts:143

Configuration that can be passed to set and override defaults and add progress callback

Properties

contentEncoding?

optional contentEncoding: ContentEncoding

Defined in: packages/canisters/src/assets/index.ts:168

Content encoding

Default

'identity'

contentType?

optional contentType: string

Defined in: packages/canisters/src/assets/index.ts:158

File content type

Default

File/Blob object type or type from file name extension

fileName?

optional fileName: string

Defined in: packages/canisters/src/assets/index.ts:148

File name

Default

File object name or name in file path

headers?

optional headers: [string, string][]

Defined in: packages/canisters/src/assets/index.ts:163

Custom headers to be sent with the asset

Default

[]

onProgress()?

optional onProgress: (progress) => void

Defined in: packages/canisters/src/assets/index.ts:176

Callback method to get upload progress in bytes (current / total)

Parameters

progress

Progress

Returns

void

path?

optional path: string

Defined in: packages/canisters/src/assets/index.ts:153

File path that file will be uploaded to

Default

'/'

sha256?

optional sha256: Uint8Array<ArrayBufferLike>

Defined in: packages/canisters/src/assets/index.ts:172

File hash generation will be skipped if hash is provided

Type Aliases

ContentEncoding

ContentEncoding = "identity" | "gzip" | "compress" | "deflate" | "br"

Defined in: packages/canisters/src/assets/index.ts:125

Supported content encodings by asset canister

StoreArgs

StoreArgs = StoreReadableArgs | StoreFileArgs | StoreBlobArgs | StorePathArgs | StoreBytesArgs

Defined in: packages/canisters/src/assets/index.ts:200

Arguments to store an asset in asset manager

StoreBlobArgs

StoreBlobArgs = [Blob, Omit<StoreConfig, "fileName"> & Required<Pick<StoreConfig, "fileName">>]

Defined in: packages/canisters/src/assets/index.ts:183

StoreBytesArgs

StoreBytesArgs = [Uint8Array | ArrayBuffer | number[], Omit<StoreConfig, "fileName"> & Required<Pick<StoreConfig, "fileName">>]

Defined in: packages/canisters/src/assets/index.ts:191

StoreFileArgs

StoreFileArgs = [File, StoreConfig]

Defined in: packages/canisters/src/assets/index.ts:181

StorePathArgs

StorePathArgs = [string, StoreConfig]

Defined in: packages/canisters/src/assets/index.ts:189

StoreReadableArgs

StoreReadableArgs = [Readable, StoreConfig]

Defined in: packages/canisters/src/assets/index.ts:179