@dfinity/assets/lib/cjs/index.d.ts

JavaScript and TypeScript library to manage assets on the Internet Computer

import { type ActorConfig, type ActorSubclass } from '@dfinity/agent';
import { type AssetsCanisterRecord } from './canisters/assets.ts';
import { type Readable } from './readable/readable.ts';
import { type LimitFn } from './utils/limit.ts';
/**
 * Supported content encodings by asset canister
 */
export type ContentEncoding = 'identity' | 'gzip' | 'compress' | 'deflate' | 'br';
/**
 * Upload progress in bytes
 */
export interface Progress {
    current: number;
    total: number;
}
/**
 * Configuration that can be passed to set and override defaults and add progress callback
 */
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;
    /**
     * Custom headers to be sent with the asset
     * @default []
     */
    headers?: Array<[string, 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;
}
export type StoreReadableArgs = [readable: Readable, config?: StoreConfig];
export type StoreFileArgs = [file: File, config?: StoreConfig];
export type StoreBlobArgs = [
    blob: Blob,
    config: Omit<StoreConfig, 'fileName'> & Required<Pick<StoreConfig, 'fileName'>>
];
export type StorePathArgs = [path: string, config?: StoreConfig];
export type StoreBytesArgs = [
    bytes: Uint8Array | ArrayBuffer | number[],
    config: Omit<StoreConfig, 'fileName'> & Required<Pick<StoreConfig, 'fileName'>>
];
/**
 * Arguments to store an asset in asset manager
 */
export type StoreArgs = StoreReadableArgs | StoreFileArgs | StoreBlobArgs | StorePathArgs | StoreBytesArgs;
/**
 * Arguments to commit batch in asset manager
 */
export interface CommitBatchArgs {
    onProgress?: (progress: Progress) => void;
}
/**
 * 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.
 */
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;
}
export declare class AssetManager {
    private readonly _actor;
    private readonly _limit;
    private readonly _maxSingleFileSize;
    private readonly _maxChunkSize;
    /**
     * Create assets canister manager instance
     * @param config Additional configuration options, canister id is required
     */
    constructor(config: AssetManagerConfig);
    /**
     * Create readable from store arguments
     * @param args Arguments with either a file, blob, path, bytes or custom Readable implementation
     */
    static toReadable(...args: StoreArgs): Promise<Readable>;
    /**
     * Get list of all files in assets canister
     * @returns All files in asset canister
     */
    list(): ReturnType<AssetsCanisterRecord['list']>;
    /**
     * Store data on assets canister
     * @param args Arguments with either a file, blob, path, bytes or custom Readable implementation
     */
    store(...args: StoreArgs): Promise<string>;
    /**
     * Delete file from assets canister
     * @param key The path to the file on the assets canister e.g. /folder/to/my_file.txt
     */
    delete(key: string): Promise<void>;
    /**
     * Delete all files from assets canister
     */
    clear(): Promise<void>;
    /**
     * Get asset instance from assets canister
     * @param key The path to the file on the assets canister e.g. /folder/to/my_file.txt
     * @param acceptEncodings The accepted content encodings, defaults to ['identity']
     */
    get(key: string, acceptEncodings?: ContentEncoding[]): Promise<Asset>;
    /**
     * Create a batch assets operations instance, commit multiple operations in a single request
     */
    batch(): AssetManagerBatch;
}
declare class AssetManagerBatch {
    private readonly _actor;
    private readonly _limit;
    private readonly _maxChunkSize;
    private _scheduledOperations;
    private _sha256;
    private _progress;
    constructor(_actor: ActorSubclass<AssetsCanisterRecord>, _limit: LimitFn, _maxChunkSize: number);
    /**
     * Insert batch operation to store data on assets canister
     * @param args Arguments with either a file, blob, path, bytes or custom Readable implementation
     */
    store(...args: StoreArgs): Promise<string>;
    /**
     * Insert batch operation to delete file from assets canister
     * @param key The path to the file on the assets canister e.g. /folder/to/my_file.txt
     */
    delete(key: string): void;
    /**
     * Commit all batch operations to assets canister
     * @param args Optional arguments with optional progress callback for commit progress
     */
    commit(args?: CommitBatchArgs): Promise<void>;
}
declare class Asset {
    private readonly _actor;
    private readonly _limit;
    private readonly _key;
    private readonly _acceptEncodings;
    private readonly _content;
    readonly contentType: string;
    readonly length: number;
    readonly contentEncoding: string;
    readonly chunkSize: number;
    readonly sha256?: Uint8Array | undefined;
    constructor(_actor: ActorSubclass<AssetsCanisterRecord>, _limit: LimitFn, _key: string, _acceptEncodings: ContentEncoding[], _content: Uint8Array, contentType: string, length: number, contentEncoding: string, chunkSize: number, sha256?: Uint8Array | undefined);
    /**
     * Get asset content as blob (web), most browsers are able to use disk storage for larger blobs
     */
    toBlob(): Promise<Blob>;
    /**
     * Get asset content as unsigned 8-bit integer array, use `toBlob` (web) or `write` (Node.js) for larger files
     */
    toUint8Array(): Promise<Uint8Array>;
    /**
     * Get asset content as number array, use `toBlob` (web) or `write` (Node.js) for larger files
     */
    toNumberArray(): Promise<number[]>;
    /**
     * Write asset content to file (Node.js)
     * @param path File path to write to
     */
    write(path: string): Promise<void>;
    /**
     * Get All chunks of asset through `onChunk` callback, can be used for a custom storage implementation
     * @param onChunk Called on each received chunk
     * @param sequential Chunks are received in sequential order when true or `concurrency` is `1` in config
     */
    getChunks(onChunk: (index: number, chunk: Uint8Array) => void, sequential?: boolean): Promise<void>;
    /**
     * Check if asset has been certified, which means that the content's hash is in the canister hash tree
     */
    isCertified(): Promise<boolean>;
    /**
     * Check if the hash of the asset data is equal to the hash that has been certified
     * @param bytes Optionally pass data to hash instead of waiting for asset data to be fetched and hashed
     */
    verifySha256(bytes?: Uint8Array | number[]): Promise<boolean>;
}
export {};
//# sourceMappingURL=index.d.ts.map