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)

$3

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

Install

``sh
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

`js
import B2 from "./src/b2";

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

$3

#### Buffers

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

`js
// 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(10110001000 / 101MB */)));
`

#### Streams

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

`js
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.

`js
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);
`




$3


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

$3

#### By id

`js
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.

`js
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.