Cashu-TS - v4.5.1
    Preparing search index...

    Class Amount

    Immutable, non-negative integer amount value object.

    Internal representation is bigint. Use factory methods to instantiate.

    Amount.from('21'); // string
        Amount.from(21); // number
        Amount.from(21n); // bigint
        Amount.zero();
        Amount.one();
    Index

    Methods

    add ceilPercent clamp compareTo divideBy equals floorPercent greaterThan greaterThanOrEqual inRange isSafeNumber isZero lessThan lessThanOrEqual modulo multiplyBy scaledBy subtract toBigInt toJSON toNumber toNumberUnsafe toString withUnit from max min one sum zero

    Methods

    • Returns ceil(this × numerator / denominator) using integer arithmetic only.

      The default denominator of 100 makes common percentage calculations natural. Use a larger denominator to express fractional percentages without floats.

      Parameters

      • numerator: number
      • denominator: number = 100

      Returns Amount

      amount.ceilPercent(2); // ceil(2% of amount)
          amount.ceilPercent(1, 200); // ceil(0.5% of amount)
          amount.ceilPercent(15, 10); // ceil(1.5% of amount)

      If numerator or denominator are not positive integers.

    • Compares this Amount with another Amount.

      Defines the natural ordering of Amount values. Useful for sorting and ordering logic.

      Parameters

      Returns -1 | 0 | 1

      -1 if this < other, 0 if equal, 1 if this > other.

    • Returns floor(this × numerator / denominator) using integer arithmetic only.

      The natural complement to Amount.ceilPercent — use when you need the conservative lower bound, e.g. "maximum spendable after reserving fees".

      Parameters

      • numerator: number
      • denominator: number = 100

      Returns Amount

      amount.floorPercent(98); // floor(98% of amount)
          amount.floorPercent(1, 200); // floor(0.5% of amount)

      If numerator or denominator are not positive integers.

    • Whether this Amount can be safely converted to a number.

      Returns boolean

    • Returns round(this × numerator / denominator) using integer arithmetic only.

      Useful for proportional rescaling — currency conversion, capacity checks, partial fills — without floating-point imprecision or overflow risk.

      Uses the identity: round(a × b / c) = floor((2 × a × b + c) / (2 × c))

      Parameters

      Returns Amount

      // Scale a 1000-sat amount down by a 3/4 ratio → 750
          Amount.from(1000).scaledBy(3, 4);

          // Proportional rescale: if neededAmount is too high, shrink estInvAmount to fit
          estInvAmount.scaledBy(tokenAmount, neededAmount).subtract(1);

      If numerator or denominator are zero or negative.

    • Used by JSON.stringify() to convert Amount to string.

      Returns string

    • Safe conversion to number.

      Returns number

      If value exceeds Number.MAX_SAFE_INTEGER.

    • Unsafe conversion to number. Precision can be lost above MAX_SAFE_INTEGER.

      Returns number

    • Canonical decimal representation for logs/JSON string mode.

      Returns string

    • Parse/normalize supported inputs into an Amount.

      Parameters

      Returns Amount

      If input is negative, or if a number input exceeds the safe integer limit, or if input is not a finite integer.

    Settings

    Member Visibility

    On This Page

    Methods