blocklift v1.0.0

blocklift-js

A dead simple and developer friendly JavaScript library for handling object storage on Azure

Developer Friendly API

For a simple blob operation, the official @azure/storage-blob SDK requires 3 "clients" for the blob service, the container and the blob itself. Blocklift.js abstracts away the complexity to provide a better developer experience.

This is a complete example to upload a file in just a few lines:

const Blocklift = require('blocklift')

const lift = new Blocklift({
	account: 'accountname',
	accessKey: 'key',
	defaultContainer: 'dev' // optional
})

lift.upload('hello.txt', 'Hello World')
	.then((upload) => { console.log(upload.url) })
	.catch((err) => { … })

You can also use the async/await syntax:

async function main () {
	const blob =  await lift.upload('hello.txt', 'Hello World')
	console.log(blob.url)
}
main()

Easier than the official SDK

Unfortunately the official @azure/storage-blob SDK is cumbersome to use.

Compare the above with this official example, which has been slightly simplified for fairer comparison:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");
const defaultAzureCredential = new DefaultAzureCredential();
const account = ACCOUNT_NAME;

const blobServiceClient = new BlobServiceClient(
  `https://${ACCOUNT_NAME}.blob.core.windows.net`,
  defaultAzureCredential
);

const content = "Hello world!";
const containerClient = blobServiceClient.getContainerClient('dev');
const blockBlobClient = containerClient.getBlockBlobClient('hello.txt');
blockBlobClient.upload(content, content.length)
	.then((response) => { … })
	.catch((err) => { … })

Automatically get Blob URLs

In addition to standard Blob REST API response, blocklift.js also returns a url property for you, for example:

https://accountname.blob.core.windows.net/dev/hello.txt

Set a default container

Why repeatedly pass a container parameter or client, when you can just set a default once and then forget about it?

const lift = new Blocklift({
	account: ACCOUNT_NAME,
	accessKey: ACCESS_KEY,
	defaultContainer: 'dev' // must already exist
})

Of course, you can always choose to use a different container and pass an optional container parameter in individual operations:

const options = { conatiner: 'not-default' }
lift.upload('hello.txt', 'Hello World', options)

Automatic Content-Type detection

Blocklift.js automatically sets a Content-Type based on file contents or filename. This helps browsers identify file types and decide how to handle them. You want to show users content as quickly as possible, i.e. in browser and not have them dig through their Downloads folder.

Of course other file types are supported including PDFs, Microsoft Word, Powerpoint, Videos, and more. See file-type package for detailed list.

Examples

Everything is a Promise. For a better overview, the then(), catch(), async, and await have been left out.

For full details, see the API documentation →

Containers

lift.listContainers()
lift.createContainer('name')
lift.deleteContainer('name')

Blobs

lift.listBlobs('container')
lift.getBlobUrl('my-image.png')

Upload a Blob or Create a File

lift.upload('hello.txt', 'Hello World', { contentType: 'text/plain' })
lift.uploadFile('local-file.png', 'folder/image.png')

Delete a Blob

lift.deleteBlob('folder/image.png')
lift.deleteBlob('folder/image.png', { container: 'not-default' })

Responses

Blocklift.js uses the official SDK under the hood and will bubble up the responses.

For example, url is added by blocklift and serverResponse is the unaltered response from the SDK.

{
  url: 'https://myaccount.blob.core.windows.net/default/hello-2020-03-22.txt',
  serverReponse: {
    etag: '"0x8D7CE6FCC47FC45"',
    lastModified: 2020-03-22T14:46:26.000Z,
    contentMD5: <Buffer c4 85 73 58 38 b0 05 75 7f 3f 31 99 50 0c 0e ca>,
    clientRequestId: 'd749b9a2-5fba-489d-a230-ba5df662f4f0',
    requestId: '283595f3-a01e-0009-1b58-00e0fc000000',
    version: '2019-02-02',
    date: 2020-03-22T14:46:25.000Z,
    isServerEncrypted: true,
    encryptionKeySha256: undefined,
    errorCode: undefined,
    'content-length': '0',
    server: 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0',
    'x-ms-content-crc64': 'awyymjQimGI=',
    body: undefined
  }
}

For more examples, see the API documentation →