@ts-common/azure-js-dev-tools/dist/lib/blobStorage.d.ts

Developer dependencies for TypeScript related projects

/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License. See License.txt in the project root for
 * license information.
 */
import { Credential } from "@azure/storage-blob";
import { URLBuilder } from "./url";
/**
 * The type of anonymous access allowed for a container. "blob" means that individual blobs are
 * accessible from anonymous requests, but the container and container-level operations (such as
 * list blobs) are not allowed. "container" means that the container and all of its contents
 * and settings are publicly readable. If no value is provided then the container and its blobs are
 * not accessible from anonymous requests.
 * See https://docs.microsoft.com/en-us/azure/storage/blobs/storage-manage-access-to-resources for
 * more information.
 */
export declare type ContainerAccessPolicy = "private" | "blob" | "container";
/**
 * The options that can be used when creating a container.
 */
export interface CreateContainerOptions {
    /**
     * The type of anonymous access allowed for a container. "blob" means that individual blobs are
     * accessible from anonymous requests, but the container and container-level operations (such as
     * list blobs) are not allowed. "container" means that the container and all of its contents
     * and settings are publicly readable. If no value is provided then the container and its blobs are
     * not accessible from anonymous requests.
     * See https://docs.microsoft.com/en-us/azure/storage/blobs/storage-manage-access-to-resources for
     * more information.
     */
    accessPolicy?: ContainerAccessPolicy;
}
/**
 * Get the number of bytes in the provided file.
 * @param filePath The path to the file.
 */
export declare function getFileLengthInBytes(filePath: string): Promise<number>;
/**
 * An optional argument interface that adds an etag to a request.
 */
export interface ETagOptions {
    /**
     * The etag that the request must be matched to in order for the operation to occur.
     */
    etag?: string;
}
/**
 * A result that has an etag property.
 */
export interface ETagResult {
    /**
     * A version identifier for a BlobStorage result.
     */
    etag?: string;
}
/**
 * The result of attempting to create a blob.
 */
export interface CreateBlobResult extends ETagResult {
    /**
     * Whether or not the blob was created.
     */
    created: boolean;
}
/**
 * The result of getting a blob's contents.
 */
export interface BlobContentsResult extends ETagResult {
    /**
     * The contents of the blob.
     */
    contents: string;
}
/**
 * The properties associated with a blob.
 */
export interface BlobPropertiesResult extends ETagResult {
}
/**
 * A path to a blob.
 */
export declare class BlobPath {
    /**
     * The name of the container that the blob is in.
     */
    readonly containerName: string;
    /**
     * The name of the blob. The name is the path to the blob relative to the container.
     */
    readonly blobName: string;
    constructor(containerName: string, blobName: string);
    /**
     * Concatenate the provided blobName onto this BlobPath.
     * @param blobName The blobName to concatenate to this BlobPath.
     */
    concatenate(blobName: string): BlobPath;
    /**
     * Get the string representation of this BlobPath object.
     */
    toString(): string;
    /**
     * Parse a BlobPath object from the provided blobPath. The blobPath string must contain a forward
     * slash.
     * @param blobPath The blob path to parse.
     */
    static parse(blobPath: string | BlobPath): BlobPath;
}
/**
 * A prefix to other BlobStorageBlobs.
 */
export declare class BlobStoragePrefix {
    /**
     * The BlobStorage system that this prefix is targeting.
     */
    readonly storage: BlobStorage;
    /**
     * The path of this prefix.
     */
    readonly path: BlobPath;
    /**
     * Create a new prefix within the provided BlobStorage system.
     * @param storage The BlobStorage system that this prefix targets.
     * @param path The path of this prefix.
     */
    constructor(storage: BlobStorage, path: string | BlobPath);
    /**
     * Get the URL for this prefix.
     */
    getURL(options?: GetPrefixURLOptions): string;
    /**
     * Get the container that this prefix belongs to.
     */
    getContainer(): BlobStorageContainer;
    /**
     * Get a blob with the provided name relative to this prefix.
     * @param blobName The name to append to this prefix.
     */
    getBlob(blobName: string): BlobStorageBlob;
    /**
     * Get a block blob with the provided name relative to this prefix.
     * @param blockBlobName The name to append to this prefix.
     */
    getBlockBlob(blockBlobName: string): BlobStorageBlockBlob;
    /**
     * Get an append blob with the provided name relative to this prefix.
     * @param appendBlobName The name to append to this prefix.
     */
    getAppendBlob(appendBlobName: string): BlobStorageAppendBlob;
    /**
     * Get a prefix that can be used to perform blob operations relative to the provided path.
     * @param blobName The path to the prefix.
     */
    getPrefix(blobName: string): BlobStoragePrefix;
    /**
     * Create a block blob relative to this container with the provided name.
     * @param blockBlobName The name of the blob relative to this container.
     */
    createBlockBlob(blockBlobName: string, options?: BlobContentOptions): Promise<CreateBlobResult>;
    /**
     * Create an append blob relative to this container with the provided name.
     * @param appendBlobName The name of the append blob relative to this container.
     */
    createAppendBlob(appendBlobName: string, options?: BlobContentOptions): Promise<CreateBlobResult>;
    /**
     * Get whether or not a blob exists with the provided name relative to this prefix.
     * @param blobName The name of the blob relative to this prefix.
     */
    blobExists(blobName: string): Promise<boolean>;
    /**
     * Get the properties for the blob at the provided path.
     * @param blobPath The path to the blob.
     */
    getBlobProperties(blobName: string): Promise<BlobPropertiesResult>;
    /**
     * Get the content type that has been assigned to the provided blob.
     * @param blobName The name of to the blob.
     */
    getBlobContentType(blobName: string): Promise<string | undefined>;
    /**
     * Assign the provided content type to the provided blob.
     * @param blobName The name of the blob.
     * @param contentType The content type to assign to the provided blob.
     */
    setBlobContentType(blobName: string, contentType: string): Promise<unknown>;
    /**
     * Get the contents of the blob with the provided name relative to this prefix.
     * @param blobName The name of the blob relative to this prefix.
     */
    getBlobContentsAsString(blobName: string): Promise<BlobContentsResult>;
    /**
     * Set the contents of the blob with the provided name relative to this prefix.
     * @param blockBlobName The name of the blob relative to this prefix.
     * @param blobContents The contents to set.
     */
    setBlockBlobContentsFromString(blockBlobName: string, blobContents: string, options?: BlobContentOptions): Promise<ETagResult>;
    /**
     * Add the provided blob contents to append to the append blob with the provided name relative to
     * this container.
     * @param appendBlobName The name of the append blob relative to this container.
     * @param blobContentsToAppend The contents to add the append blob.
     */
    addToAppendBlobContentsFromString(appendBlobName: string, blobContentsToAppend: string, options?: ETagOptions): Promise<ETagResult>;
    /**
     * Delete the blob with the provided name relative to this prefix. This method returns whether or
     * not the blob was deleted. Returning false means that the blob didn't exist before this method
     * was called.
     * @param blobPath The path to the blob to delete relative to this prefix.
     */
    deleteBlob(blobName: string): Promise<boolean>;
}
export declare class BlobStorageContainer extends BlobStoragePrefix {
    /**
     * The name of this container.
     */
    readonly name: string;
    /**
     * Create a new reference to a container within the provided BlobStorage system.
     * @param storage The BlobStorage system that this container belongs to.
     * @param name The name of the container.
     */
    constructor(storage: BlobStorage, name: string);
    /**
     * Get the URL for this prefix.
     */
    getURL(options?: GetURLOptions): string;
    /**
     * Get the container that this prefix belongs to.
     */
    getContainer(): BlobStorageContainer;
    /**
     * Create this container. This method will return false when the container already exists.
     */
    create(options?: CreateContainerOptions): Promise<boolean>;
    /**
     * Get whether or not this container exists.
     */
    exists(): Promise<boolean>;
    /**
     * Get the access policy for this container.
     */
    getAccessPolicy(): Promise<ContainerAccessPolicy>;
    /**
     * Set the access policy for this container.
     * @param policy The new access policy for this container.
     */
    setAccessPolicy(policy: ContainerAccessPolicy): Promise<unknown>;
    /**
     * Delete this container. This method returns whether or not the container was deleted. Returning
     * false means that the container didn't exist before this method was called.
     */
    delete(): Promise<boolean>;
}
/**
 * Options that can be applied when updating a blob's contents.
 */
export interface BlobContentOptions extends ETagOptions {
    /**
     * The MIME content type that will be associated with this blob's content.
     */
    contentType?: string;
}
/**
 * An class that describes the common functions between the different types of blobs in a
 * BlobStorage system.
 */
export declare class BlobStorageBlob {
    /**
     * The BlobStorage system that this blob came from.
     */
    readonly storage: BlobStorage;
    /**
     * The path to this blob.
     */
    readonly path: BlobPath;
    /**
     * Create a new reference to a block blob within the provided BlobStorage system.
     * @param storage The BlobStorage system that this blob belongs to.
     * @param path The path to this block blob.
     */
    constructor(storage: BlobStorage, path: string | BlobPath);
    /**
     * Get the URL for this blob.
     */
    getURL(options?: GetURLOptions): string;
    /**
     * Get the container that contains this blob.
     */
    getContainer(): BlobStorageContainer;
    /**
     * Get whether or not this blob exists.
     */
    exists(): Promise<boolean>;
    /**
     * Get the properties for this blob.
     */
    getProperties(): Promise<BlobPropertiesResult>;
    /**
     * Delete this blob. This method returns whether or not the blob was deleted. Returning false
     * means that the blob didn't exist before this method was called.
     */
    delete(): Promise<boolean>;
    /**
     * Get the contents of this blob as a UTF-8 decoded string.
     */
    getContentsAsString(): Promise<BlobContentsResult>;
    /**
     * Get the content type that has been assigned to this blob.
     */
    getContentType(): Promise<string | undefined>;
    /**
     * Assign the provided content type to this blob.
     * @param contentType The content type to assign to this blob.
     */
    setContentType(contentType: string): Promise<unknown>;
}
/**
 * A class that can be used to interact with a block blob in a BlobStorage system.
 */
export declare class BlobStorageBlockBlob extends BlobStorageBlob {
    /**
     * Create this block blob. This method will return false when the block blob already exists.
     */
    create(options?: BlobContentOptions): Promise<CreateBlobResult>;
    /**
     * Set the contents of this block blob to be the provided UTF-8 encoded string.
     * @param blockBlobContents The contents to set. This will be UTF-8 encoded.
     */
    setContentsFromString(blockBlobContents: string, options?: BlobContentOptions): Promise<unknown>;
    /**
     * Upload the file at the provided path to this block blob.
     * @param filePath The path to the file that contains the block blob's contents.
     * @param options Options that will be applied to the block blob.
     */
    setContentsFromFile(filePath: string, options?: BlobContentOptions): Promise<unknown>;
}
/**
 * A class that can be used to interact with an append blob in a BlobStorage system.
 */
export declare class BlobStorageAppendBlob extends BlobStorageBlob {
    /**
     * Create this append blob. This method will return false when the append blob already exists.
     */
    create(options?: BlobContentOptions): Promise<CreateBlobResult>;
    /**
     * Append the provided UTF-8 encoded contents to this append blob.
     * @param contentsToAppend The contents to append to this append blob. This will be UTF-8 encoded.
     */
    addToContents(contentsToAppend: string): Promise<unknown>;
}
export interface SASTokenPermissions {
    read?: boolean;
    add?: boolean;
    create?: boolean;
    write?: boolean;
    delete?: boolean;
}
/**
 * Options that can be used to create a SAS token.
 */
export interface CreateSASTokenOptions {
    /**
     * The time that the SAS token will start being valid.
     */
    startTime?: Date;
    /**
     * The time that the SAS token will stop being valid.
     */
    endTime: Date;
    /**
     * The permissions that will be permitted to the SAS token.
     */
    permissions?: SASTokenPermissions;
}
export interface GetURLOptions {
    /**
     * Whether or not to include the SAS token when getting the URL.
     */
    sasToken?: boolean | CreateSASTokenOptions;
    /**
     * Whether or not to encode the blob name in the URL (when there is a blob name).
     */
    encodeBlobName?: boolean;
}
export interface GetPrefixURLOptions extends GetURLOptions {
    /**
     * Whether or not to include the SAS token when getting the URL.
     */
    sasToken?: boolean;
}
/**
 * A class for interacting with a blob storage system.
 */
export declare abstract class BlobStorage {
    /**
     * Get a reference to a blob at the provided path. This will not modify the BlobStorage system at
     * all. This simply gets a reference to the blob.
     * @param blobPath The path to the blob.
     */
    getBlob(blobPath: string | BlobPath): BlobStorageBlob;
    /**
     * Get a reference to a block blob at the provided path. This will not modify the BlobStorage
     * system at all. This simply gets a reference to the block blob.
     * @param blockBlobPath The path to the block blob.
     */
    getBlockBlob(blockBlobPath: string | BlobPath): BlobStorageBlockBlob;
    /**
     * Get a reference to an append blob at the provided path. This will not modify the BlobStorage
     * system at all. This simply gets a reference to the append blob.
     * @param appendBlobPath The path to the blob.
     */
    getAppendBlob(appendBlobPath: string | BlobPath): BlobStorageAppendBlob;
    /**
     * Get a prefix that can be used to perform blob operations relative to the provided prefix.
     * @param prefix The path to the prefix.
     */
    getPrefix(prefix: string | BlobPath): BlobStoragePrefix;
    /**
     * Get a reference to a container with the provided name. This will not modify the BlobStorage
     * system at all. This simply gets a reference to the container.
     * @param containerName The name of the container.
     */
    getContainer(containerName: string): BlobStorageContainer;
    /**
     * Get the URL to this storage account.
     */
    abstract getURL(options?: GetURLOptions): string;
    /**
     * Get the URL to the provided container.
     * @param containerName The name of the container.
     */
    abstract getContainerURL(containerName: string, options?: GetURLOptions): string;
    /**
     * Get the URL to the provided blob.
     * @param blobPath The path to the blob.
     */
    abstract getBlobURL(blobPath: string | BlobPath, options?: GetURLOptions): string;
    /**
     * Create a block blob at the provided blockBlobPath. This method will return false when the block
     * blob already exists.
     * @param blockBlobPath The path to the block blob to create.
     */
    abstract createBlockBlob(blockBlobPath: string | BlobPath, options?: BlobContentOptions): Promise<CreateBlobResult>;
    /**
     * Create an append blob at the provided appendBlobPath. This method will return false when the
     * append blob already exists.
     * @param appendBlobPath The path to the append blob to create.
     */
    abstract createAppendBlob(appendBlobPath: string | BlobPath, options?: BlobContentOptions): Promise<CreateBlobResult>;
    /**
     * Get whether or not the blob at the provided path exists.
     * @param blobPath The path to the blob.
     */
    abstract blobExists(blobPath: string | BlobPath): Promise<boolean>;
    /**
     * Get the properties for the blob at the provided path.
     * @param blobPath The path to the blob.
     */
    abstract getBlobProperties(blobPath: string | BlobPath): Promise<BlobPropertiesResult>;
    /**
     * Get the contents of the blob at the provided path as a UTF-8 decoded string.
     * @param blobPath The path to the blob.
     */
    abstract getBlobContentsAsString(blobPath: string | BlobPath): Promise<BlobContentsResult>;
    /**
     * Set the contents of the block blob at the provided path to be the provided UTF-8 encoded
     * string.
     * @param blockBlobPath The path to the block blob.
     * @param blockBlobContents The contents to set. This will be UTF-8 encoded.
     */
    abstract setBlockBlobContentsFromString(blockBlobPath: string | BlobPath, blockBlobContents: string, options?: BlobContentOptions): Promise<ETagResult>;
    /**
     * Upload the file at the provided path to the provided block blob path.
     * @param blockBlobPath The path to the block blob.
     * @param filePath The path to the file that contains the blob's contents.
     * @param options Options that will be applied to the blob.
     */
    abstract setBlockBlobContentsFromFile(blockBlobPath: string | BlobPath, filePath: string, options?: BlobContentOptions): Promise<ETagResult>;
    /**
     * Add the provided blob contents to append to the append blob with the provided name relative to
     * this container.
     * @param appendBlobName The name of the append blob relative to this container.
     * @param blobContentsToAppend The contents to add the append blob.
     * @param options Options that will be applied to the operation.
     */
    abstract addToAppendBlobContentsFromString(appendBlobPath: string | BlobPath, blobContentsToAppend: string, options?: ETagOptions): Promise<ETagResult>;
    /**
     * Get the content type that has been assigned to the provided blob.
     * @param blobPath The path to the blob.
     */
    abstract getBlobContentType(blobPath: string | BlobPath): Promise<string | undefined>;
    /**
     * Assign the provided content type to the provided blob.
     * @param blobPath The path to the blob.
     * @param contentType The content type to assign to the provided blob.
     */
    abstract setBlobContentType(blobPath: string | BlobPath, contentType: string): Promise<unknown>;
    /**
     * Delete the blob at the provided blobPath. This method returns whether or not the blob was
     * deleted. Returning false means that the blob didn't exist before this method was called.
     * @param blobPath The path to the blob to delete.
     */
    abstract deleteBlob(blobPath: string | BlobPath): Promise<boolean>;
    /**
     * Create a container with the provided name.
     * @param containerName The name of the container to create.
     */
    abstract createContainer(containerName: string, options?: CreateContainerOptions): Promise<boolean>;
    /**
     * Get whether or not a container with the provided name exists.
     * @param containerName The name of the container.
     */
    abstract containerExists(containerName: string): Promise<boolean>;
    /**
     * Get the access policy for the provided container.
     * @param containerName The name of the container.
     */
    abstract getContainerAccessPolicy(containerName: string): Promise<ContainerAccessPolicy>;
    /**
     * Set the access permissions for the provided container.
     * @param containerName The name of the container.
     */
    abstract setContainerAccessPolicy(containerName: string, policy: ContainerAccessPolicy): Promise<unknown>;
    /**
     * Delete the container with the provided name. This method returns whether or not the container
     * was deleted. Returning false means that the container didn't exist before this method was
     * called.
     * @param containerName The name of the container to delete.
     */
    abstract deleteContainer(containerName: string): Promise<boolean>;
    /**
     * Get all of the containers that exist in this BlobStorage system.
     */
    abstract listContainers(): Promise<BlobStorageContainer[]>;
}
export declare function constructBlobStorageURL(storageAccountNameOrUrl: string | URLBuilder): string;
export declare function getStorageAccountName(storageAccountNameOrUrl: string): string;
export declare function constructBlobStorageCredentials(storageAccountUrl: string, credentials?: Credential | string): Credential;
/**
 * A BlobStorage system that is stored in memory.
 */
export declare class InMemoryBlobStorage extends BlobStorage {
    private readonly url;
    private readonly containers;
    private readonly credentials;
    constructor(storageAccountNameOrUrl?: string, credentials?: Credential);
    private getInMemoryContainer;
    private getInMemoryBlob;
    getURL(options?: GetURLOptions): string;
    getContainerURL(containerName: string, options?: GetURLOptions): string;
    getBlobURL(blobPath: string | BlobPath, options?: GetURLOptions): string;
    private createInMemoryBlob;
    createBlockBlob(blobPath: string | BlobPath, options?: BlobContentOptions): Promise<CreateBlobResult>;
    createAppendBlob(appendBlobPath: string | BlobPath, options?: BlobContentOptions): Promise<CreateBlobResult>;
    blobExists(blobPath: string | BlobPath): Promise<boolean>;
    getBlobProperties(blobPath: string | BlobPath): Promise<BlobPropertiesResult>;
    getBlobContentsAsString(blobPath: string | BlobPath): Promise<BlobContentsResult>;
    setBlockBlobContentsFromString(blobPath: string | BlobPath, blobContents: string, options?: BlobContentOptions): Promise<CreateBlobResult>;
    setBlockBlobContentsFromFile(blockBlobPath: string | BlobPath, filePath: string, options?: BlobContentOptions): Promise<CreateBlobResult>;
    addToAppendBlobContentsFromString(appendBlobPath: string | BlobPath, blobContentsToAppend: string, options?: ETagOptions): Promise<ETagResult>;
    getBlobContentType(blobPath: string | BlobPath): Promise<string | undefined>;
    setBlobContentType(blobPath: string | BlobPath, contentType: string): Promise<unknown>;
    deleteBlob(blobPath: string | BlobPath): Promise<boolean>;
    createContainer(containerName: string, options?: CreateContainerOptions): Promise<boolean>;
    containerExists(containerName: string): Promise<boolean>;
    getContainerAccessPolicy(containerName: string): Promise<ContainerAccessPolicy>;
    setContainerAccessPolicy(containerName: string, permissions: ContainerAccessPolicy): Promise<unknown>;
    deleteContainer(containerName: string): Promise<boolean>;
    listContainers(): Promise<BlobStorageContainer[]>;
}
/**
 * Validate that the provided BlobPath's blobName is defined and not-empty.
 * @param blobPath The blob path to validate.
 */
export declare function validateBlobName(blobPath: string | BlobPath): Promise<void>;
export declare function getAzureContainerAccessPermissions(permissions?: ContainerAccessPolicy): "container" | "blob" | undefined;
/**
 * A BlobStorage system that uses Azure Blob Storage to store data.
 */
export declare class AzureBlobStorage extends BlobStorage {
    private readonly url;
    private readonly serviceUrl;
    private readonly credentials;
    constructor(storageAccountNameOrUrl: string | URLBuilder, credentials?: Credential | string);
    private getAzureContainerURL;
    private getBlockBlobURL;
    private getAppendBlobURL;
    getURL(options?: GetURLOptions): string;
    getContainerURL(containerName: string, options?: GetURLOptions): string;
    getBlobURL(blobPath: string | BlobPath, options?: GetURLOptions): string;
    blobExists(blobPath: string | BlobPath): Promise<boolean>;
    getBlobProperties(blobPath: string | BlobPath): Promise<BlobPropertiesResult>;
    getBlobContentsAsString(blobPath: string | BlobPath): Promise<BlobContentsResult>;
    setBlockBlobContentsFromString(blockBlobPath: string | BlobPath, blockBlobContents: string, options?: BlobContentOptions): Promise<ETagResult>;
    setBlockBlobContentsFromFile(blobPath: string | BlobPath, filePath: string, options?: BlobContentOptions): Promise<ETagResult>;
    addToAppendBlobContentsFromString(appendBlobPath: string | BlobPath, blobContentsToAppend: string, options?: ETagOptions): Promise<ETagResult>;
    getBlobContentType(blobPath: string | BlobPath): Promise<string | undefined>;
    setBlobContentType(blobPath: string | BlobPath, contentType: string): Promise<unknown>;
    containerExists(containerName: string): Promise<boolean>;
    getContainerAccessPolicy(containerName: string): Promise<ContainerAccessPolicy>;
    setContainerAccessPolicy(containerName: string, permissions: ContainerAccessPolicy): Promise<unknown>;
    createBlockBlob(blockBlobPath: string | BlobPath, options?: BlobContentOptions): Promise<CreateBlobResult>;
    createAppendBlob(appendBlobPath: string | BlobPath, options?: BlobContentOptions): Promise<CreateBlobResult>;
    deleteBlob(blobPath: string | BlobPath): Promise<boolean>;
    createContainer(containerName: string, options?: CreateContainerOptions): Promise<boolean>;
    deleteContainer(containerName: string): Promise<boolean>;
    listContainers(): Promise<BlobStorageContainer[]>;
}
//# sourceMappingURL=blobStorage.d.ts.map