@upcoming/bee-js 0.15.1 → 0.16.1

package/dist/mjs/bee.js

@@ -1145,24 +1145,24 @@ export class Bee {
     }
     return stamp;
   }
-  async buyStorage(gigabytes, duration, options, requestOptions) {
+  async buyStorage(size, duration, options, requestOptions) {
     const chainState = await this.getChainState(requestOptions);
     const amount = getAmountForDuration(duration, chainState.currentPrice);
-    const depth = getDepthForSize(gigabytes);
+    const depth = getDepthForSize(size);
     if (options) {
       options = preparePostageBatchOptions(options);
     }
     return this.createPostageBatch(amount, depth, options, requestOptions);
   }
-  async getStorageCost(gigabytes, duration, options) {
+  async getStorageCost(size, duration, options) {
     const chainState = await this.getChainState(options);
     const amount = getAmountForDuration(duration, chainState.currentPrice);
-    const depth = getDepthForSize(gigabytes);
+    const depth = getDepthForSize(size);
     return getStampCost(depth, amount);
   }
-  async extendStorageSize(postageBatchId, gigabytes, options) {
+  async extendStorageSize(postageBatchId, size, options) {
     const batch = await this.getPostageBatch(postageBatchId, options);
-    const depth = getDepthForSize(gigabytes);
+    const depth = getDepthForSize(size);
     const delta = depth - batch.depth;
     if (delta <= 0) {
       throw new BeeArgumentError('New depth has to be greater than the original depth', depth);
@@ -1176,18 +1176,18 @@ export class Bee {
     const amount = getAmountForDuration(duration, chainState.currentPrice);
     return this.topUpBatch(batch.batchID, amount, options);
   }
-  async getExtensionCost(postageBatchId, gigabytes, duration, options) {
+  async getExtensionCost(postageBatchId, size, duration, options) {
     const batch = await this.getPostageBatch(postageBatchId, options);
     const chainState = await this.getChainState(options);
     const amount = getAmountForDuration(duration, chainState.currentPrice);
-    const depth = getDepthForSize(gigabytes);
+    const depth = getDepthForSize(size);
     const currentValue = getStampCost(batch.depth, batch.amount);
     const newValue = getStampCost(depth, amount);
     return newValue.minus(currentValue);
   }
-  async getSizeExtensionCost(postageBatchId, gigabytes, options) {
+  async getSizeExtensionCost(postageBatchId, size, options) {
     const batch = await this.getPostageBatch(postageBatchId, options);
-    const depth = getDepthForSize(gigabytes);
+    const depth = getDepthForSize(size);
     const delta = depth - batch.depth;
     if (delta <= 0) {
       throw new BeeArgumentError('New depth has to be greater than the original depth', depth);

package/dist/mjs/index.js

@@ -10,6 +10,7 @@ export * from "./utils/constants.js";
 export { Duration } from "./utils/duration.js";
 export * from "./utils/error.js";
 export * as Utils from "./utils/expose.js";
+export { Size } from "./utils/size.js";
 export * from "./utils/tokens.js";
 export * from "./utils/typed-bytes.js";
 export { Bee, BeeDev, Stamper };

package/dist/mjs/modules/debug/stamps.js

@@ -1,6 +1,7 @@
 import { Types } from 'cafe-utility';
 import { Duration } from "../../utils/duration.js";
 import { http } from "../../utils/http.js";
+import { Size } from "../../utils/size.js";
 import { getStampEffectiveBytes, getStampTheoreticalBytes, getStampUsage } from "../../utils/stamps.js";
 import { asNumberString } from "../../utils/type.js";
 import { BatchId, EthAddress } from "../../utils/typed-bytes.js";
@@ -100,9 +101,10 @@ export async function getAllPostageBatches(requestOptions) {
         name: 'immutableFlag'
       }),
       usage,
-      size: getStampEffectiveBytes(depth),
-      remainingSize: Math.ceil(getStampEffectiveBytes(depth) * (1 - usage)),
-      theoreticalSize: getStampTheoreticalBytes(depth),
+      usageText: `${Math.round(usage * 100)}%`,
+      size: Size.fromBytes(getStampEffectiveBytes(depth)),
+      remainingSize: Size.fromBytes(Math.ceil(getStampEffectiveBytes(depth) * (1 - usage))),
+      theoreticalSize: Size.fromBytes(getStampTheoreticalBytes(depth)),
       duration
     };
   });
@@ -153,9 +155,10 @@ export async function getPostageBatch(requestOptions, postageBatchId) {
       name: 'immutableFlag'
     }),
     usage,
-    size: getStampEffectiveBytes(depth),
-    remainingSize: Math.ceil(getStampEffectiveBytes(depth) * (1 - usage)),
-    theoreticalSize: getStampTheoreticalBytes(depth),
+    usageText: `${Math.round(usage * 100)}%`,
+    size: Size.fromBytes(getStampEffectiveBytes(depth)),
+    remainingSize: Size.fromBytes(Math.ceil(getStampEffectiveBytes(depth) * (1 - usage))),
+    theoreticalSize: Size.fromBytes(getStampTheoreticalBytes(depth)),
     duration
   };
 }

package/dist/mjs/utils/size.js

@@ -0,0 +1,31 @@
+import { Numbers } from 'cafe-utility';
+/**
+ * Represents a size in bytes.
+ *
+ * Uses 1000 instead of 1024 for converting between units.
+ * This is to stay consistent with the Swarm papers
+ * on theoretical and effective storage capacity.
+ */
+export class Size {
+  constructor(bytes) {
+    this.bytes = Math.ceil(bytes);
+    if (bytes < 0) {
+      throw Error('Size must be at least 0');
+    }
+  }
+  static fromBytes(bytes) {
+    return new Size(bytes);
+  }
+  static fromGigabytes(gigabytes) {
+    return new Size(gigabytes * 1000 * 1000 * 1000);
+  }
+  toBytes() {
+    return this.bytes;
+  }
+  toGigabytes() {
+    return this.bytes / 1000 / 1000 / 1000;
+  }
+  toFormattedString() {
+    return Numbers.convertBytes(this.bytes, 1000);
+  }
+}

package/dist/mjs/utils/stamps.js

@@ -92,14 +92,14 @@ export function getAmountForDuration(duration, pricePerBlock, blockTime = 5) {
   return BigInt(duration.toSeconds()) / BigInt(blockTime) * BigInt(pricePerBlock);
 }
 /**
- * Utility function that calculates the depth required for a postage batch to achieve the specified effective size in gigabytes.
+ * Utility function that calculates the depth required for a postage batch to achieve the specified effective size
  *
- * @param gigabytes
+ * @param size The effective size of the postage batch
  * @returns
  */
-export function getDepthForSize(gigabytes) {
-  for (const [depth, size] of effectiveSizeBreakpoints) {
-    if (gigabytes <= size) {
+export function getDepthForSize(size) {
+  for (const [depth, sizeBreakpoint] of effectiveSizeBreakpoints) {
+    if (size.toGigabytes() <= sizeBreakpoint) {
       return depth;
     }
   }

package/dist/types/bee.d.ts

@@ -6,6 +6,7 @@ import type { AllSettlements, BalanceResponse, BeeOptions, BeeRequestOptions, Be
 import { AllTagsOptions, Collection, PostageBatchOptions, TransactionOptions, UploadResult } from './types';
 import { Bytes } from './utils/bytes';
 import { Duration } from './utils/duration';
+import { Size } from './utils/size';
 import { BZZ } from './utils/tokens';
 import { BatchId, EthAddress, FeedIndex, Identifier, PeerAddress, PrivateKey, PublicKey, Reference, Topic, TransactionId } from './utils/typed-bytes';
 import { UploadProgress } from './utils/upload-progress';
@@ -649,12 +650,12 @@ export declare class Bee {
      * @see [Bee Debug API reference - `POST /stamps`](https://docs.ethswarm.org/debug-api/#tag/Postage-Stamps/paths/~1stamps~1{amount}~1{depth}/post)
      */
     createPostageBatch(amount: NumberString | string | bigint, depth: number, options?: PostageBatchOptions, requestOptions?: BeeRequestOptions): Promise<BatchId>;
-    buyStorage(gigabytes: number, duration: Duration, options?: PostageBatchOptions, requestOptions?: BeeRequestOptions): Promise<BatchId>;
-    getStorageCost(gigabytes: number, duration: Duration, options?: BeeRequestOptions): Promise<BZZ>;
-    extendStorageSize(postageBatchId: BatchId | Uint8Array | string, gigabytes: number, options?: BeeRequestOptions): Promise<BatchId>;
+    buyStorage(size: Size, duration: Duration, options?: PostageBatchOptions, requestOptions?: BeeRequestOptions): Promise<BatchId>;
+    getStorageCost(size: Size, duration: Duration, options?: BeeRequestOptions): Promise<BZZ>;
+    extendStorageSize(postageBatchId: BatchId | Uint8Array | string, size: Size, options?: BeeRequestOptions): Promise<BatchId>;
     extendStorageDuration(postageBatchId: BatchId | Uint8Array | string, duration: Duration, options?: BeeRequestOptions): Promise<BatchId>;
-    getExtensionCost(postageBatchId: BatchId | Uint8Array | string, gigabytes: number, duration: Duration, options?: BeeRequestOptions): Promise<BZZ>;
-    getSizeExtensionCost(postageBatchId: BatchId | Uint8Array | string, gigabytes: number, options?: BeeRequestOptions): Promise<BZZ>;
+    getExtensionCost(postageBatchId: BatchId | Uint8Array | string, size: Size, duration: Duration, options?: BeeRequestOptions): Promise<BZZ>;
+    getSizeExtensionCost(postageBatchId: BatchId | Uint8Array | string, size: Size, options?: BeeRequestOptions): Promise<BZZ>;
     getDurationExtensionCost(postageBatchId: BatchId | Uint8Array | string, duration: Duration, options?: BeeRequestOptions): Promise<BZZ>;
     /**
      * Topup a fresh amount of BZZ to given Postage Batch.

package/dist/types/index.d.ts

@@ -10,6 +10,7 @@ export * from './utils/constants';
 export { Duration } from './utils/duration';
 export * from './utils/error';
 export * as Utils from './utils/expose';
+export { Size } from './utils/size';
 export * from './utils/tokens';
 export * from './utils/typed-bytes';
 export { Bee, BeeDev, Stamper };
@@ -21,6 +22,7 @@ declare global {
             Stamper: typeof import('./stamper/stamper').Stamper;
             Utils: typeof import('./utils/expose');
             Duration: typeof import('./utils/duration').Duration;
+            Size: typeof import('./utils/size').Size;
             BeeError: typeof import('./utils/error').BeeError;
             BeeArgumentError: typeof import('./utils/error').BeeArgumentError;
             BeeResponseError: typeof import('./utils/error').BeeResponseError;

package/dist/types/types/index.d.ts

@@ -5,6 +5,7 @@ import type { FeedPayloadResult, FeedReferenceResult, FeedUpdateOptions } from '
 import { Bytes } from '../utils/bytes';
 import { Duration } from '../utils/duration';
 import type { BeeError } from '../utils/error';
+import { Size } from '../utils/size';
 import { BatchId, EthAddress, Identifier, PrivateKey, PublicKey, Reference, Topic, TransactionId } from '../utils/typed-bytes';
 export * from './debug';
 export declare const SECTION_SIZE = 32;
@@ -394,17 +395,21 @@ export interface PostageBatch {
      */
     usage: number;
     /**
-     * Effective size in bytes
+     * Human readable usage text, like "50%" or "100%", no fractions
      */
-    size: number;
+    usageText: string;
+    /**
+     * Effective size
+     */
+    size: Size;
     /**
-     * Estimated remaining size in bytes
+     * Estimated remaining size
      */
-    remainingSize: number;
+    remainingSize: Size;
     /**
      * Theoretical size in bytes
      */
-    theoreticalSize: number;
+    theoreticalSize: Size;
 }
 export interface BatchBucket {
     bucketID: number;

package/dist/types/utils/size.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Represents a size in bytes.
+ *
+ * Uses 1000 instead of 1024 for converting between units.
+ * This is to stay consistent with the Swarm papers
+ * on theoretical and effective storage capacity.
+ */
+export declare class Size {
+    private bytes;
+    private constructor();
+    static fromBytes(bytes: number): Size;
+    static fromGigabytes(gigabytes: number): Size;
+    toBytes(): number;
+    toGigabytes(): number;
+    toFormattedString(): string;
+}

package/dist/types/utils/stamps.d.ts

@@ -1,6 +1,7 @@
 import { EnvelopeWithBatchId, NumberString } from '../types';
 import { Bytes } from './bytes';
 import { Duration } from './duration';
+import { Size } from './size';
 import { BZZ } from './tokens';
 /**
  * Utility function that calculates usage of postage batch based on its utilization, depth and bucket depth.
@@ -49,11 +50,11 @@ export declare function getStampDuration(amount: NumberString | string | bigint,
  */
 export declare function getAmountForDuration(duration: Duration, pricePerBlock: number, blockTime?: number): bigint;
 /**
- * Utility function that calculates the depth required for a postage batch to achieve the specified effective size in gigabytes.
+ * Utility function that calculates the depth required for a postage batch to achieve the specified effective size
  *
- * @param gigabytes
+ * @param size The effective size of the postage batch
  * @returns
  */
-export declare function getDepthForSize(gigabytes: number): number;
+export declare function getDepthForSize(size: Size): number;
 export declare function convertEnvelopeToMarshaledStamp(envelope: EnvelopeWithBatchId): Bytes;
 export declare function marshalStamp(signature: Uint8Array, batchId: Uint8Array, timestamp: Uint8Array, index: Uint8Array): Bytes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upcoming/bee-js",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "description": "Javascript client for Bee",
   "keywords": [
     "bee",
@@ -63,7 +63,7 @@
   },
   "dependencies": {
     "axios": "^0.28.1",
-    "cafe-utility": "^27.13.0",
+    "cafe-utility": "^27.14.1",
     "isomorphic-ws": "^4.0.1",
     "semver": "^7.3.5",
     "ws": "^8.7.0"