b2-js

Backblaze B2 JavaScript Client

A powerful library for using Backblaze B2.

✅ Streaming uploads (automatic switching between single and multi-part)
✅ Single-part uploads
✅ Streaming downloads
✅ Graceful error handling (exponential back-off)
✅ Requires ES2018
✅ Used in production at Mintere
🚫 Browser Not Supported (uses node-fetch and streams)

📜 Documentation

Developed for Mintere Sites, a platform enabling websites to be global, easy-to-develop, performant and dynamic.

Install

npm install b2-js

yarn install b2-js

Principles

• Backblaze allows uploading files as a single-part or as multiple parts. However, you must know the length of each file in advance, and you cannot use chunked-encoding.
• Single-part uploads are generally faster for smaller files. Backblaze recommends a part-size.
• The library should handle the complexity of working with the B2 API, including handling splitting streams into multi-part uploads.

Key Considerations

• For streams of unknown length, each part must be read into memory (up-to 100MB). You can configure this down to b2.auth.absoluteMinimumPartSize using b2.partSize = BYTES.
• It's generally faster to use single part upload for smaller files. The library will make the decision for you based on b2.partSize.

Usage

import B2 from "./src/b2";
 
const b2 = await B2.authorize({ applicationKeyId: "KEY_ID", applicationKey: "SECRET_KEY"});
const bucket = b2.bucket("bucket-name");

Uploading

Buffers

When uploading Buffers, the library automatically decides whether to conduct a single or multi-part upload based on the Buffer's byteLength.

// a single-part upload will be attempted.
bucket.upload("test.txt", Buffer.from("foobar"));
 
// a multi-part upload will automatically be attempted for larger files
bucket.upload("test.txt", Buffer.from("*".repeat(101*1000*1000 /* 101MB */)));

Streams

When the contentLength is known, you may conduct a single part upload without loading the stream into memory.

const fileStream = require("fs").createReadStream("./README.md")
// In order to conduct a single-part upload without loading a stream
// into memory, the content length of the stream in bytes must be known.
bucket.uploadSinglePart("readme", fileStream, {contentLength: 2174}) 

When the contentLength is unknown, or a stream is too large for a single-part upload, each part of the stream must be loaded into memory in order to size the stream, compute a digest of the content and properly split the stream into parts.

If the stream less than or equal to b2.partSize bytes, a single-part upload will be attempted. Otherwise, a multi-part upload will be attempted by loading up-to b2.partSize bytes of the stream into memory at a time.

const file = bucket.file("example");
const stream = file.createWriteStream();
 
stream.on("error", (err) => {
  // handle the error 
  // note that retries are automatically attempted before errors are 
  // thrown for most potentially recoverable errors, as per the B2 docs.
})
 
stream.on("finish", (err) => {
  // upload done, the file instance has been updated to reflect this
})
 
res.body.pipe(stream);

Downloading

const file = bucket.file("text.txt");
file.createReadStream();

Stat

By id

const file = bucket.file({fileId: "...."});
const fileData = await file.stat(); //=> see https://www.backblaze.com/b2/docs/b2_get_file_info.html

By name

Note that statting a file by name involves a Class C transaction as it involves listing files with a call to b2_list_file_names.

const file = bucket.file("text.txt");
try {
  const fileData = await file.stat(); //=> see https://www.backblaze.com/b2/docs/b2_get_file_info.html
} catch (e) {
  if (e instanceof BackblazeLibraryError.FileNotFound) {
    // handle file not found.
  } else {
    throw e;  // re-throw the error unchanged
  }
}

Author

👤 Ben Aubin (benaubin.com)

• Website: benaubin.com
• Twitter: @BenAubin_
• Github: @benaubin
• LinkedIn: @benaubin

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page. You can also take a look at the contributing guide.

Users

• Mintere uses b2-js to serve static assets for its CDN and to deploy files on servers around the world.

Using b2-js in production? Submit a PR to add yourself to this list!

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2020 Ben Aubin (benaubin.com).
This project is MIT licensed.