Nobody's Perfect, Man

    @dfinity/assets
    TypeScript icon, indicating that this package has built-in type declarations

    0.15.3 • Public • Published

    @dfinity/assets

    Manage assets on an Internet Computer assets canister.

    Visit the Dfinity Forum and SDK Documentation for more information and support building on the Internet Computer.

    Additional API Documentation can be found here.


    Installation

    Using AssetManager:

    npm i --save @dfinity/assets
    

    In the browser:

    import { AssetManager } from "@dfinity/assets";
    

    In Node.js:

    const { AssetManager } = require("@dfinity/assets");
    

    Using AssetManager

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

    Create an asset manager instance

    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

    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

    const input = document.createElement('input');
    input.type = 'file';
    input.addEventListener('change', async () => {
        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

    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

    const file = fs.readFileSync('./example.csv');
    const key = await assetManager.store(file, {fileName: 'example.csv'});

    Delete file from asset canister

    const key = '/path/to/example.jpg'
    await assetManager.delete(key);

    List files in asset canister

    const files = await assetManager.list();

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

    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

    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

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

    Install

    npm i @dfinity/assets

    DownloadsWeekly Downloads

    15

    Version

    0.15.3

    License

    Apache-2.0

    Unpacked Size

    300 kB

    Total Files

    71

    Last publish

    Collaborators

    • frederikrothenberger
    • bitdivine
    • ielashi
    • liadrit
    • dayyildiz
    • anthony_dfinity
    • eric-swanson-dfinity
    • krpeacock
    • terrorjack
    • npm-dfinity-org