Javascript client library for connecting to Bee decentralised storage
BSD-3-CLAUSE License
Published by bee-worker over 2 years ago
This is a breaking release that brings support for Bee 1.7 and cleans up some long awaiting breaking changes that we had lined up:
DebugPostageBatch
(for PostageBatch
) and NodesInfo
(for NodeInfo
).cid
property of the UploadResultWithCid
interface to be a function instead of getter as this property is not available for encrypted references which caused some troubles when serializing the whole object.waitForUsable
property of the BeeDebug.createPostageBatch()
defaulted to false
, now it is true
).Bee. createFeedManifest()
to return object instead of directly reference that also has support for getting CID with the .cid()
function.Published by bee-worker over 2 years ago
Shortly after the last release, we bring you another release that brings some nice improvements and new features together with some fixes.
We have verified the support for Node 18. It introduces a native implementation of fetch
API that we use as HTTP client. This implementation wraps the errors that it throws into a nested Error object, so we unwrap these errors for better error handling.
When a postage stamp is created the (BeeDebug.createPostageStamp()
method is called), Bee creates an on-chain transaction that creates this transaction in the smart contract, but the stamp is not immediately "usable" as Bee waits for several blockchain blocks in order to be sure that the postage stamp won't disappear from the blockchain. During this period Bee won't accept this stamp and will return the error stamp is not usable
. After this period Bee pronounces it as usable and the users can upload content using it.
In most use cases, when you create the postage stamp you want to actually wait until the stamp is usable and only then return it to the user. For that, you had to implement your own waiting logic, but no more!
The BeeDebug.createPostageStamp()
method has a new option waitForUsable
which if specified, then the Promise this method returns is resolved only after the Bee confirms the postage stamp to be usable. Be aware that if used, then the call time of this method raises dramatically!
In the next breaking release this option will be turned on, by default!
The Bee 1.6.0 release introduced /wallet
endpoint that exposes the balance of the node's wallet and some other related metrics. In this release we add support for this endpoint.
Published by bee-worker over 2 years ago
This release brings several new features and one ad-hoc breaking fix that is passed on from the new Bee version 1.6.0, but affects only the BeeDebug.getReserveState()
method.
Bee supports ENS for resolution of ENS domains into Swarm references. bee-js
was until now refusing ENS domains with the input validation. Now we are bringing support for all the download*
methods and a few other ones as well.
The FeedReader.download()
function now accepts an option index
where you can specify which of the feed's updates you want to download.
There is a new method Bee.isFeedRetrievable()
that helps you to check whether a given feed is available.
It operates in two modes. If you know the last index of the feed update then you can use it as an optional parameter and then be sure that this update is present in the network. If you won't specify the index
parameter, then it will check for the "latest" update by traversing all the known updates from the start. This does not guarantee though that the found "latest" update is indeed the latest one though and hence provides a weaker guarantee.
BeeDebug.getReserveState()
based on Bee 1.6.0 (#675)Published by bee-worker over 2 years ago
Published by bee-worker over 2 years ago
Published by bee-worker over 2 years ago
This is another small release that brings support for Bee 1.5.0 and a few small improvements.
The Bee 1.5.0 introduced new mode called ultra-light mode. This mode has been added to the existing BeeModes
.
The bee-js v3.3.0 introduced support for ES Modules. In 3.3.2 we include several fixes to resolve some of the reported issues and broken builds.
Published by AuHau over 2 years ago
This is a patching release that targets especially issues discovered thanks to the introduction of the ESM hybrid build. The main change is that if you want to use the function Utils.readableWebToNode()
in browser then you have to polyfill stream
package with your bundler.
Major changes of the last 3.3.0 release are:
We plan to migrate our bee-js package to ES Modules (see the issue for more info) when Node v12 will reach its end-of-life (on 30th of April). With this release, we are starting a transition period by supporting both ES Modules and CommonJS builds. Please start migrating your applications to the ESM stack otherwise, you won't be able to upgrade bee-js after we drop support for CommonJS.
Since we are in a fast-paced environment where Bee's versions can be incompatible with each other, it is important that in your application you check whether the Bee that you connect to has the correct version that you expect and support (through bee-js
).
Untill now we had the isSupportedVersion()
function that indicated if the Bee node version is not matching the one that bee-js
was tested and built against. This implementation has its downside because it is very strict and if for example there is a small Bee's release that patches only something internal and does not touch the API, which means that the bee-js
should be compatible, you will still get a false
with this check.
Except for Bee's version itself, there are two other versions that version the Bee endpoint's API and the Bee Debug endpoint's API. We have decided to implement methods that do compatibility checks using these versions and hence should be more relaxed towards Bee's small patches but might pose some risk if some change will be unnoticed and API versions not bumped accordingly.
These methods are:
BeeDebug.isSupportedExactVersion()
- renamed isSupportedVersion
which is now deprecatedBeeDebug.isSupportedMainApiVersion()
which checks compatibility only for the main Bee endpointBeeDebug.isSupportedDebugApiVersion()
which checks compatibility only for the Bee Debug endpointBeeDebug.isSupportedApiVersion()
which checks compatibility for both endpointsThe compatibility is checked using the major versions of the API. If you would like to make your own assertions you can get all the versions (both from Bee itself and the one that bee-js should support) using the method BeeDebug.getVersions()
Published by bee-worker over 2 years ago
This is a smaller update with two main changes.
We plan to migrate our bee-js package to ES Modules (see the issue for more info) when Node v12 will reach its end-of-life (on 30th of April). With this release, we are starting a transition period by supporting both ES Modules and CommonJS builds. Please start migrating your applications to the ESM stack otherwise, you won't be able to upgrade bee-js after we drop support for CommonJS.
Since we are in a fast-paced environment where Bee's versions can be incompatible with each other, it is important that in your application you check whether the Bee that you connect to has the correct version that you expect and support (through bee-js
).
Untill now we had the isSupportedVersion()
function that indicated if the Bee node version is not matching the one that bee-js
was tested and built against. This implementation has its downside because it is very strict and if for example there is a small Bee's release that patches only something internal and does not touch the API, which means that the bee-js
should be compatible, you will still get a false
with this check.
Except for Bee's version itself, there are two other versions that version the Bee endpoint's API and the Bee Debug endpoint's API. We have decided to implement methods that do compatibility checks using these versions and hence should be more relaxed towards Bee's small patches but might pose some risk if some change will be unnoticed and API versions not bumped accordingly.
These methods are:
BeeDebug.isSupportedExactVersion()
- renamed isSupportedVersion
which is now deprecatedBeeDebug.isSupportedMainApiVersion()
which checks compatibility only for the main Bee endpointBeeDebug.isSupportedDebugApiVersion()
which checks compatibility only for the Bee Debug endpointBeeDebug.isSupportedApiVersion()
which checks compatibility for both endpointsThe compatibility is checked using the major versions of the API. If you would like to make your own assertions you can get all the versions (both from Bee itself and the one that bee-js should support) using the method BeeDebug.getVersions()
Published by bee-worker almost 3 years ago
This is after some time a bigger update that brings some new goodies from Bee 1.4.1 version and improved error handling and support.
Bee introduced direct upload mode, where Bee directly pushes the data to the network instead of the intermediate step of locally saving the data and then syncing it with the network. You can enable this behavior by passing deferred = false
into UploadOptions
interface. When you enable this mode the Promise
returned by the upload methods will resolve only once the data is uploaded and synchronized with the network so if you use timeouts you should adjust those base on the size of data you upload.
Currently, the direct upload mode is by default turned off, but it is a plan in the future to enable this behavior by default!
Now BeeResponseError
and BeeRequestError
instances contain information about the request (and if applicable also response) that triggered the Error. Also, it has improved for non-JSON responses that were causing unclear errors.
In this release, there are two changes in Interface's names that are non-breaking as there are backward compatible aliases, but these aliases will be removed with the next breaking change.
DebugPostageBatch
was renamed to PostageBatch
NodesInfo
was renamed to NodeInfo
Published by bee-worker almost 3 years ago
This is another small release that brings support for Bee 1.4.1 and a few small improvements
The Bee 1.4.1 release brought a new endpoint on Debug API called /node
which provides information about in what mode the Bee node runs (such as dev mode, light mode, or full mode or information about gateway mode).
We used chunk endpoints internally in bee-js but now we have decided to expose them for your usage as well.
In order to calculate the usage of a postage stamp (eq. percentage in form of a number between 0 and 1) we have added a small utility function that calculates it called getStampUsage()
.
Published by bee-worker almost 3 years ago
This is a small release in size, but big on impact. It is a breaking release thanks to breaking changes introduced in Bee 1.4.
Bee
class (#458)/health
endpoint and methods (#459) (98afdcd)Published by bee-worker almost 3 years ago
Published by bee-worker about 3 years ago
This release is a compatibility release with Bee 1.2.0 release, which brings few new features.
The new method bee.isReferenceRetrievable()
allows you to check whether the data represented by a reference is present in the network. This is part of the Stewardship endpoint, which also allows you to reupload the data that you have locally available (pinned).
There is a new method beeDebug.topUpBatch()
, that allows you to top-up the amount of existing batch, effectively prolonging its lifetime.
Moreover, there is also a new method beeDebug.diluteBatch()
that increases the depth of a batch, effectively extending the number of chunks that the batch can stamp and lowering the lifetime of a batch.
⚠️ If you use the utility function makeMaxTarget
, then the time of sending a PSS message will increase! Consider using your own criteria based on your use-case.
Published by bee-worker about 3 years ago
This is our first major version bump as we did a big revamp of bee-js
internals and fixed a few things and shortcomings that required breaking changes.
In the JS browser ecosystem, there are two main HTTP clients: old XMLHttpRequest (XHR) API and new modern fetch
API.
We originally used axios
library that employs the XHR client, but XHR is old and will not get any new features as it is superseded with fetch
API that is actively developed by the WHATWG group, and hence it has its limitations. Many limitations can be overcome using polyfills etc. but a hard stop is networking that only browsers decide what to allow (usually based on the specification). In the case of XHR the limitation is streaming support.
We have therefore decided to use fetch
based library ky
that supports streaming downloads and hopefully in close future will support also streaming uploads (see whatwg/fetch#966, there is also already functional experiment that enables this in Chrome). fetch
is also more future-proof.
This change, unfortunately, does not come without a cost and that is support for tracking upload progress, that fetch
still does not have (if interested please comment on the relevant whatwg/fetch#607 issue to raise importance).
If this feature is crucial for you, we have devised a workaround thanks to @mattiaz9, which is demonstrated in our example upload-progress
.
This change unfortunately is breaking as we originally exposed AxiosOptions
on our API. We have refactored this into more generic HTTP options that should be more future-proof. Thanks to ky
we also now have support for retries of failed requests (only for non-POST
requests, defaults are seen here) and timeouts. Both are possible to set generally for the Bee
instance and/or override it for each method call.
As part of the HTTP client revamp, we had a deeper look at how we handle streams. In the JS land, there are two main types of streams the NodeJS Readable
and the browser WHATWG ReadableStream
. As our design mindset is browser-first and polyfill the rest in NodeJs, we have unified all returned streams into the WHATWG ReadableStream
no matter what platform you are on. Most probably you will want to use NodeJs Readable
on NodeJs platform, so we have included utility function readableWebToNode
that converts WHATWG stream into NodeJs. There are also more stream-related utility functions that you can check out.
For stream inputs, we accept both types of streams and convert them internally.
One of our short-coming was dropping the returned object from upload methods in favor of the simple string Reference
. Later on, we discovered that there is actually a need to return more information from upload operations because Bee automatically creates a Tag for each upload that we could return. Hence we have introduced back UploadResult
interface that all the upload methods will now return.
We have merged all the Utils.*
namespaces directly into Utils
and we have filtered out the functions only to those that make sense to expose in order to minimize the public API and possible future breaking changes.
uploadCollection()
methodWe have introduced new uploadCollection
method that is more flexible in uploading collection if you do not want to use our convenience methods like uploadFilesFromDirectory()
or uploadFiles
. This new method accepts the Collection<Uint8Array | Readable>
interface.
bee-js
are now reported with User-Agent: bee-js/<<bee-js's version>>
(#390)Utils.setDefaultHeaders()
was removed in favor of Bee
/BeeDebug
instance's option defaultHeaders
(#390)Utils.hooks.*
was removed in favor of Bee
/BeeDebug
instance's options onRequest
and onResponse
WHATWG ReadableStream
. If you need NodeJS's Readable you can use Utils.readableWebToNode()
utility function. (#390)axiosOptions
were removed from those methods that supported it (for example bee.downloadReadableData()
, bee.reuploadPinnedData()
, UploadOptions
does not have axiosOptions
property anymore) (#390)fetch
does not support tracking of upload progress (like XHR/axios supported with the onUploadProgress
). Please see our example upload-progress
for work-around. (#390)UploadResult
interface (#408)bee.pssSend()
now throws error if the specified target exceeds maximal value. Use Utils.makeMaxTarget()
that will give you the max target that Bee accepts. (#384)Utils
namespace is flattened and limited on the functions (#395)UploadResult
for upload methods (#408) (e58b8e8)Published by bee-worker about 3 years ago
This is a small patch release that fixes wrongly reporting incompatible version with Bee 1.1.0 builds for Mac and Windows. Related to https://github.com/ethersphere/bee/pull/2451
Published by bee-worker about 3 years ago
This is mainly a compatibility release with Bee 1.1.0 release.
The Stamps API was moved to Debug API and on normal API it is now deprecated. Moreover, Bee provides more information on Debug API with for example batchTtl
that gives an estimation for how long the batch will be valid.
New Debug API was added that allows you to manage pending transactions and do things like:
Published by bee-worker over 3 years ago
Published by bee-worker over 3 years ago
This is a small incremental release that brings two new features.
If you need to know what exact HTTP requests bee-js
sends to Bee you can now register hooks for outgoing requests and incoming responses using Utils.Hooks
interface.
Be aware! These listeners listen to all outgoing bee-js
's requests/responses, so if you have multiple Bee
/BeeDebug
instances for different Bee nodes, than all requests will be forwarded to your callbacks!
With the 1.0
Bee release few new endpoints related to Tags were introduced that allows you to list, update and delete tags.