Refactored currency and account APIs for flexibility

Updated `Currency` interface methods to return `Optional` values, improving null safety. Added builders and editing functionalities. Enhanced `Account` methods for simpler balance operations, with `BigDecimal` returns for precision. Bumped version to 3.0.0-pre2.

Author: NonSwag

plugin/src/main/java/net/thenextlvl/service/wrapper/service/model/WrappedBank.java

@@ -3,6 +3,7 @@
 import net.milkbowl.vault.economy.Economy;
 import net.thenextlvl.service.ServicePlugin;
 import net.thenextlvl.service.api.economy.bank.Bank;
+import net.thenextlvl.service.api.economy.currency.Currency;
 import net.thenextlvl.service.api.economy.currency.CurrencyHolder;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.World;
@@ -67,10 +68,12 @@ public UUID getOwner() {
     }
 
     @Override
-    public void setBalance(Number balance, Currency currency) {
-        var difference = balance.doubleValue() - getBalance(currency).doubleValue();
-        if (difference > 0) deposit(difference, currency);
-        else if (difference < 0) withdraw(-difference, currency);
+    public BigDecimal setBalance(Number balance, Currency currency) {
+        var current = getBalance(currency);
+        var difference = balance.doubleValue() - current.doubleValue();
+        if (difference > 0) return deposit(difference, currency);
+        else if (difference < 0) return withdraw(-difference, currency);
+        return current;
     }
 
     @Override

src/main/java/net/thenextlvl/service/api/economy/Account.java

@@ -46,7 +46,9 @@ default BigDecimal deposit(Number amount) {
      * @return the new balance after the deposit
      * @since 3.0.0
      */
-    BigDecimal deposit(Number amount, Currency currency);
+    default BigDecimal deposit(Number amount, Currency currency) {
+        return setBalance(getBalance(currency).add(BigDecimal.valueOf(amount.doubleValue())), currency);
+    }
 
     /**
      * Retrieves the balance of the account.
@@ -88,7 +90,9 @@ default BigDecimal withdraw(Number amount) {
      * @return the new balance after the withdrawal
      * @since 3.0.0
      */
-    BigDecimal withdraw(Number amount, Currency currency);
+    default BigDecimal withdraw(Number amount, Currency currency) {
+        return setBalance(getBalance(currency).subtract(BigDecimal.valueOf(amount.doubleValue())), currency);
+    }
 
     /**
      * Returns an optional containing the world associated with this account.
@@ -147,7 +151,8 @@ default void setBalance(Number balance) {
      *
      * @param balance  the new balance to be set
      * @param currency the currency of the balance
+     * @return the new balance after the operation
      * @since 3.0.0
      */
-    void setBalance(Number balance, Currency currency);
+    BigDecimal setBalance(Number balance, Currency currency);
 }

src/main/java/net/thenextlvl/service/api/economy/EconomyController.java

@@ -34,7 +34,7 @@ public interface EconomyController extends Controller, CurrencyHolder {
      */
     @Deprecated(forRemoval = true, since = "3.0.0")
     default String getCurrencyNamePlural(Locale locale) {
-        return PlainTextComponentSerializer.plainText().serialize(getDefaultCurrency().getDisplayNamePlural(locale));
+        return getDefaultCurrency().getDisplayNamePlural(locale).map(PlainTextComponentSerializer.plainText()::serialize).orElse("");
     }
 
     /**
@@ -46,7 +46,7 @@ default String getCurrencyNamePlural(Locale locale) {
      */
     @Deprecated(forRemoval = true, since = "3.0.0")
     default String getCurrencyNameSingular(Locale locale) {
-        return PlainTextComponentSerializer.plainText().serialize(getDefaultCurrency().getDisplayNameSingular(locale));
+        return getDefaultCurrency().getDisplayNameSingular(locale).map(PlainTextComponentSerializer.plainText()::serialize).orElse("");
     }
 
     /**

src/main/java/net/thenextlvl/service/api/economy/currency/Currency.java

@@ -7,11 +7,13 @@
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.Unmodifiable;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Locale;
 import java.util.Map;
 import java.util.Optional;
 import java.util.OptionalInt;
+import java.util.function.Consumer;
 
 /**
  * Represents a currency with support for localization, formatting, and symbolic representation.
@@ -34,39 +36,39 @@ public interface Currency {
      * If the audience does not specify a locale, {@link Locale#US} is used.
      *
      * @param audience the audience whose locale is used to determine the singular display name
-     * @return the singular display name as a {@code Component} for the audience's locale
+     * @return an {@code Optional} containing the singular display name as a {@code Component} for the audience's locale, or empty
      */
-    default Component getDisplayNameSingular(Audience audience) {
+    default Optional<Component> getDisplayNameSingular(Audience audience) {
         return getDisplayNameSingular(audience.getOrDefault(Identity.LOCALE, Locale.US));
     }
 
     /**
      * Retrieves the singular display name component of the currency for the specified locale.
      *
      * @param locale the locale for which the singular display name should be retrieved
-     * @return the singular display name as a {@code Component} for the specified locale
+     * @return an {@code Optional} containing the singular display name as a {@code Component} for the specified locale, or empty
      */
-    Component getDisplayNameSingular(Locale locale);
+    Optional<Component> getDisplayNameSingular(Locale locale);
 
     /**
      * Retrieves the plural display name component of the currency based on the audience's locale.
      * <p>
      * If the audience does not specify a locale, {@link Locale#US} is used.
      *
      * @param audience the audience whose locale is used to determine the plural display name
-     * @return the plural display name as a {@code Component} for the audience's locale
+     * @return an {@code Optional} containing the plural display name as a {@code Component} for the audience's locale, or empty
      */
-    default Component getDisplayNamePlural(Audience audience) {
+    default Optional<Component> getDisplayNamePlural(Audience audience) {
         return getDisplayNamePlural(audience.getOrDefault(Identity.LOCALE, Locale.US));
     }
 
     /**
      * Retrieves the plural display name component of the currency for the specified locale.
      *
      * @param locale the locale for which the plural display name should be retrieved
-     * @return the plural display name as a {@code Component} for the specified locale
+     * @return an {@code Optional} containing the plural display name as a {@code Component} for the specified locale, or empty
      */
-    Component getDisplayNamePlural(Locale locale);
+    Optional<Component> getDisplayNamePlural(Locale locale);
 
     /**
      * Retrieves the currency symbol.
@@ -104,12 +106,44 @@ default Component format(Number amount, Audience audience) {
      */
     int getFractionalDigits();
 
+    /**
+     * Modifies the current configuration of the currency using the provided builder.
+     * The builder allows customization of various currency properties.
+     *
+     * @param consumer a {@code Consumer} that accepts a {@code Builder} instance to define customizations for the currency
+     */
+    void editCurrency(Consumer<Builder> consumer);
+
+    /**
+     * Converts the current {@code Currency} instance into a {@code Builder} for modification or reconstruction.
+     *
+     * @return a {@code Builder} instance initialized with the properties of the current {@code Currency}
+     */
+    @ApiStatus.OverrideOnly
+    Builder toBuilder();
+
     /**
      * A builder interface for constructing instances of {@link Currency}.
      * The {@code Builder} allows for the configuration of currency properties such as
      * singular and plural display names, currency symbol, and fractional digits.
      */
     interface Builder {
+        /**
+         * Sets the name of the currency.
+         *
+         * @param name the name to be set
+         * @return the builder instance for method chaining
+         */
+        @Contract(value = "_ -> this")
+        Builder name(String name);
+        
+        /**
+         * Retrieves the name currently set on the builder.
+         *
+         * @return the name as a string, or {@code null} if not set
+         */
+        String name();
+        
         /**
          * Retrieves a map containing the singular display names of the currency for various locales.
          *
@@ -122,12 +156,12 @@ interface Builder {
         /**
          * Sets the singular display name of the currency for a specific locale.
          *
+         * @param locale the locale for which the singular display name is being set, or {@code null} to remove
          * @param name   the singular display name component of the currency
-         * @param locale the locale for which the singular display name is being set
          * @return the builder instance for chaining
          */
-        @Contract(value = "_, _ -> this", pure = true)
-        Builder displayNameSingular(Component name, Locale locale);
+        @Contract(value = "_, _ -> this")
+        Builder displayNameSingular(Locale locale, @Nullable Component name);
 
         /**
          * Retrieves the singular display name component of the currency for the specified locale.
@@ -150,12 +184,12 @@ interface Builder {
         /**
          * Sets the plural display name of the currency for a specific locale.
          *
+         * @param locale the locale for which the plural display name is being set, or {@code null} to remove
          * @param name   the plural display name component of the currency
-         * @param locale the locale for which the plural display name is being set
          * @return the builder instance for chaining
          */
-        @Contract(value = "_, _ -> this", pure = true)
-        Builder displayNamePlural(Component name, Locale locale);
+        @Contract(value = "_, _ -> this")
+        Builder displayNamePlural(Locale locale, @Nullable Component name);
 
         /**
          * Retrieves the plural display name component of the currency for the specified locale.
@@ -169,11 +203,11 @@ interface Builder {
         /**
          * Sets the currency symbol as a {@code Component}.
          *
-         * @param symbol the symbol component to represent the currency
+         * @param symbol the symbol component to represent the currency, or {@code null} to remove
          * @return the builder instance for chaining
          */
-        @Contract(value = "_ -> this", pure = true)
-        Builder symbol(Component symbol);
+        @Contract(value = "_ -> this")
+        Builder symbol(@Nullable Component symbol);
 
         /**
          * Retrieves the currency symbol set on the {@code Builder}.
@@ -189,12 +223,12 @@ interface Builder {
          * Fractional digits are generally used to specify the precision of the currency values,
          * for example, 2 fractional digits for most currencies such as USD (representing cents).
          *
-         * @param fractionalDigits the number of fractional digits to set (must be a non-negative integer)
+         * @param fractionalDigits the number of fractional digits to set (must be a non-negative integer), or {@code null} to remove
          * @return the builder instance for chaining
          * @throws IllegalArgumentException if {@code fractionalDigits} is negative
          */
         @Contract(value = "_ -> this")
-        Builder fractionalDigits(int fractionalDigits) throws IllegalArgumentException;
+        Builder fractionalDigits(@Nullable Integer fractionalDigits) throws IllegalArgumentException;
 
         /**
          * Retrieves the number of fractional digits set for the currency.

src/main/java/net/thenextlvl/service/api/economy/currency/CurrencyHolder.java

@@ -77,16 +77,26 @@ default boolean hasCurrency(String name) {
 
     /**
      * Creates a new currency by configuring a {@link Currency.Builder}.
-     * <p>
-     * If a currency with the same name already exists, this method returns empty.
      *
      * @param name    the name of the new currency
      * @param builder a consumer to configure the {@link Currency.Builder} for currency creation
-     * @return an optional containing the created {@link Currency}, or empty
+     * @return the newly created {@link Currency}
      * @throws UnsupportedOperationException if {@link #hasMultiCurrencySupport()} is {@code false}
+     * @throws IllegalArgumentException      if a currency with the same name already exists
      */
     @Contract("_, _ -> new")
-    default Optional<Currency> createCurrency(String name, Consumer<Currency.Builder> builder) {
+    default Currency createCurrency(String name, Consumer<Currency.Builder> builder) throws IllegalArgumentException {
+        throw new UnsupportedOperationException("Not implemented yet");
+    }
+
+    /**
+     * Adds a new currency to the currency holder.
+     *
+     * @param currency the {@code Currency} object to add
+     * @return {@code true} if the currency was successfully added, otherwise {@code false}
+     * @throws UnsupportedOperationException if {@link #hasMultiCurrencySupport()} is {@code false}
+     */
+    default boolean addCurrency(Currency currency) {
         throw new UnsupportedOperationException("Not implemented yet");
     }