Enhanced currency and account APIs for precision and flexibility

Updated `Currency` methods to return `Optional`, improving null safety. Redesigned `setBalance` in `WrappedAccount` to return `BigDecimal` for better precision. Adjusted `WrappedCurrency` to include editing logic and improve locale-based display name handling for currencies. Bumped version to 3.0.0-pre3.

Author: NonSwag

plugin/src/main/java/net/thenextlvl/service/wrapper/VaultEconomyServiceWrapper.java

@@ -64,14 +64,14 @@ public String format(double amount) {
 
     @Override
     public String currencyNamePlural() {
-        var name = economyController.getDefaultCurrency().getDisplayNamePlural(Locale.US);
-        return PlainTextComponentSerializer.plainText().serialize(name);
+        return economyController.getDefaultCurrency().getDisplayNamePlural(Locale.US)
+                .map(PlainTextComponentSerializer.plainText()::serialize).orElse("");
     }
 
     @Override
     public String currencyNameSingular() {
-        var name = economyController.getDefaultCurrency().getDisplayNameSingular(Locale.US);
-        return PlainTextComponentSerializer.plainText().serialize(name);
+        return economyController.getDefaultCurrency().getDisplayNameSingular(Locale.US)
+                .map(PlainTextComponentSerializer.plainText()::serialize).orElse("");
     }
 
     @Override

plugin/src/main/java/net/thenextlvl/service/wrapper/service/BankServiceWrapper.java

@@ -5,6 +5,7 @@
 import net.thenextlvl.service.api.economy.bank.Bank;
 import net.thenextlvl.service.api.economy.bank.BankController;
 import net.thenextlvl.service.wrapper.service.model.WrappedBank;
+import net.thenextlvl.service.wrapper.service.model.WrappedCurrency;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.World;
 import org.bukkit.plugin.Plugin;

plugin/src/main/java/net/thenextlvl/service/wrapper/service/EconomyServiceWrapper.java

@@ -4,6 +4,7 @@
 import net.thenextlvl.service.api.economy.Account;
 import net.thenextlvl.service.api.economy.EconomyController;
 import net.thenextlvl.service.wrapper.service.model.WrappedAccount;
+import net.thenextlvl.service.wrapper.service.model.WrappedCurrency;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.World;
 import org.bukkit.plugin.Plugin;

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

@@ -62,9 +62,10 @@ public UUID getOwner() {
     }
 
     @Override
-    public void setBalance(Number balance, Currency currency) {
+    public BigDecimal 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);
+        if (difference > 0) return deposit(difference, currency);
+        else if (difference < 0) return withdraw(-difference, currency);
+        return BigDecimal.ZERO;
     }
 }

plugin/src/main/java/net/thenextlvl/service/wrapper/service/WrappedCurrency.java renamed to plugin/src/main/java/net/thenextlvl/service/wrapper/service/model/WrappedCurrency.java

@@ -1,11 +1,13 @@
-package net.thenextlvl.service.wrapper.service;
+package net.thenextlvl.service.wrapper.service.model;
 
 import net.kyori.adventure.text.Component;
 import net.milkbowl.vault.economy.Economy;
 import net.thenextlvl.service.api.economy.currency.Currency;
 import org.jspecify.annotations.NullMarked;
 
 import java.util.Locale;
+import java.util.Optional;
+import java.util.function.Consumer;
 
 @NullMarked
 public class WrappedCurrency implements Currency {
@@ -21,13 +23,13 @@ public String getName() {
     }
 
     @Override
-    public Component getDisplayNameSingular(Locale locale) {
-        return Component.text(economy.currencyNameSingular());
+    public Optional<Component> getDisplayNameSingular(Locale locale) {
+        return Optional.ofNullable(economy.currencyNameSingular()).map(Component::text);
     }
 
     @Override
-    public Component getDisplayNamePlural(Locale locale) {
-        return Component.text(economy.currencyNamePlural());
+    public Optional<Component> getDisplayNamePlural(Locale locale) {
+        return Optional.ofNullable(economy.currencyNamePlural()).map(Component::text);
     }
 
     @Override
@@ -44,4 +46,9 @@ public Component format(Number amount, Locale locale) {
     public int getFractionalDigits() {
         return economy.fractionalDigits();
     }
+
+    @Override
+    public boolean editCurrency(Consumer<Builder> consumer) {
+        return false;
+    }
 }

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

@@ -3,7 +3,6 @@
 import net.kyori.adventure.audience.Audience;
 import net.kyori.adventure.identity.Identity;
 import net.kyori.adventure.text.Component;
-import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.Unmodifiable;
 import org.jspecify.annotations.NullMarked;
@@ -111,16 +110,9 @@ default Component format(Number amount, Audience audience) {
      * 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
+     * @return {@code true} if the edit succeeded, otherwise {@code false}
      */
-    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();
+    boolean editCurrency(Consumer<Builder> consumer);
 
     /**
      * A builder interface for constructing instances of {@link Currency}.
@@ -136,14 +128,14 @@ interface Builder {
          */
         @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.
          *
@@ -240,14 +232,5 @@ interface Builder {
          */
         @Contract(value = "-> new")
         OptionalInt fractionalDigits();
-
-        /**
-         * Builds and returns a {@link Currency} instance based on the properties set on the {@code Builder}.
-         *
-         * @return the constructed {@link Currency} instance
-         */
-        @Contract("-> new")
-        @ApiStatus.OverrideOnly
-        Currency build();
     }
 }

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

@@ -90,13 +90,17 @@ default Currency createCurrency(String name, Consumer<Currency.Builder> builder)
     }
 
     /**
-     * Adds a new currency to the currency holder.
+     * Creates a new currency using the specified builder.
+     * <p>
+     * This method enables modifying existing currencies by utilizing a
+     * pre-configured builder to create a new currency.
      *
-     * @param currency the {@code Currency} object to add
-     * @return {@code true} if the currency was successfully added, otherwise {@code false}
+     * @param builder the {@link Currency.Builder} containing the configuration for the currency creation
+     * @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
      */
-    default boolean addCurrency(Currency currency) {
+    default Currency createCurrency(Currency.Builder builder) {
         throw new UnsupportedOperationException("Not implemented yet");
     }