> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/podstawy-pracy-ze-skryptami/operacje-matematyczne-w-scriptcode.md).

# Operacje matematyczne na liczbach

Środowisko języka JavaScript (w którym domyślnie wykonywane są skrypty) natywnie wykorzystuje 64-bitowy format zmiennoprzecinkowy do przechowywania wszystkich liczb. Prowadzi to do dobrze znanych problemów z utratą precyzji podczas prostych obliczeń.

Aby całkowicie wyeliminować to zjawisko, zalecane jest, aby **wszystkie operacje matematyczne** – a w szczególności obliczenia finansowe, podatkowe i walutowe – wykonywać wyłącznie przy użyciu globalnego obiektu `BigDecimal`. Gwarantuje on absolutną dokładność obliczeń niezależnie od stopnia skomplikowania ułamków.

## Definicje interfejsów API

### BigDecimal

Interfejs `BigDecimal` to fundament precyzyjnych obliczeń w systemie Eximee. Stanowi on abstrakcję reprezentującą liczby dziesiętne o dowolnej precyzji, co pozwala na całkowite wyeliminowanie błędów zaokrągleń znanych z natywnego typu `Number` w języku JavaScript (zjawisko tzw. arytmetyki zmiennoprzecinkowej IEEE 754). Obiekt ten projektowany jest jako całkowicie niezmienny (immutable), co ułatwia śledzenie przepływu danych i gwarantuje bezpieczeństwo podczas skomplikowanych kalkulacji.

```javascript
interface BigDecimal {
  valueOf(value: string | number | BigDecimal): BigDecimal
  add(augend: string | number | BigDecimal): BigDecimal
  subtract(subtrahend: string | number | BigDecimal): BigDecimal
  multiply(multiplicand: string | number | BigDecimal): BigDecimal
  divide(divisor: string | number | BigDecimal): BigDecimal
  divide(divisor: string | number | BigDecimal, roundingMode: string): BigDecimal
  divide(divisor: string | number | BigDecimal, scale: number): BigDecimal
  divide(divisor: string | number | BigDecimal, scale: number, roundingMode: string): BigDecimal
  setScale(newScale: number): BigDecimal
  setScale(newScale: number, roudingMode: string): BigDecimal
  equals(equated: string | number | BigDecimal): boolean
  compareTo(compared: string | number | BigDecimal): int 
}
```

| Metoda                                     | Akceptowane argumenty                            | Opis                                                                                                                  |                                                                                     |                                                    |                                                                                                                                 |
| ------------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `valueOf(value)`                           | `string` \| `number` \| `BigDecimal`             | Tworzy i zwraca nowy obiekt `BigDecimal` na podstawie przekazanej wartości.                                           |                                                                                     |                                                    |                                                                                                                                 |
| `add(augend)`                              | `string` \| `number` \| `BigDecimal`             | Dodaje przekazaną wartość i zwraca nowy obiekt z wynikiem.                                                            |                                                                                     |                                                    |                                                                                                                                 |
| `subtract(subtrahend)`                     | `string` \| `number` \| `BigDecimal`             | Odejmuje przekazaną wartość i zwraca nowy obiekt z wynikiem.                                                          |                                                                                     |                                                    |                                                                                                                                 |
| `multiply(multiplicand)`                   | `string` \| `number` \| `BigDecimal`             | Mnoży przez przekazaną wartość i zwraca nowy obiekt z wynikiem.                                                       |                                                                                     |                                                    |                                                                                                                                 |
| `divide(divisor, [scale], [roundingMode])` | <p><code>string</code>                           | <code>number</code>                                                                                                   | <code>BigDecimal</code><br>(opcjonalnie)\*: <code>scale</code>: <code>number</code> | <code>roundingMode</code>: <code>string</code></p> | Dzieli przez przekazaną wartość. Pozwala opcjonalnie wskazać docelową skalę i tryb zaokrąglenia. Zwraca nowy obiekt z wynikiem. |
| `setScale(newScale, [roundingMode])`       | `newScale`: `number` \| `roundingMode`: `string` | Ustawia nową skalę (liczbę miejsc po przecinku), opcjonalnie stosując wskazany tryb zaokrąglania. Zwraca nowy obiekt. |                                                                                     |                                                    |                                                                                                                                 |
| `equals(equated)`                          | `string` \| `number` \| `BigDecimal`             | Zwraca wartość logiczną (`true`/`false`) informującą, czy wartości są równe.                                          |                                                                                     |                                                    |                                                                                                                                 |
| `compareTo(compared)`                      | `string` \| `number` \| `BigDecimal`             | Porównuje wartości. Zwraca: `1` (większe), `0` (równe) lub `-1` (mniejsze).                                           |                                                                                     |                                                    |                                                                                                                                 |

### DecimalFormat

Interfejs `DecimalFormat` pełni rolę mostu pomiędzy ścisłą logiką matematyczną a interfejsem użytkownika. Zapewnia on niezawodne mechanizmy do dwukierunkowej konwersji danych. Z jednej strony pozwala na sformatowanie obiektów `BigDecimal` na czytelne ciągi znaków (z uwzględnieniem walut, procentów oraz lokalnych separatorów tysięcy i dziesiętnych), a z drugiej – na bezpieczne parsowanie surowego tekstu z pól formularza z powrotem na użyteczne obiekty matematyczne.

```javascript
interface DecimalFormat {
    of(pattern: string): DecimalFormat
    of(pattern: string, symbols: DecimalFormatSymbols): DecimalFormat
    format(value: BigDecimal): string
    parse(value: string): BigDecimal
}
```

| Metoda                   | Akceptowane argumenty                                                                            | Opis / Zwracany typ                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `of(pattern, [symbols])` | <p><code>pattern</code>: <code>string</code><br><em>(opcjonalnie)</em>: <code>symbols</code></p> | Inicjalizuje i zwraca nowy formater na podstawie wzorca i opcjonalnego symbolu (np. regionu `PL`). |
| `format(value)`          | `value`: `BigDecimal`                                                                            | Formatuje obiekt matematyczny do czytelnego tekstu (`string`).                                     |
| `parse(value)`           | `value`: `string`                                                                                | Konwertuje tekst wprowadzony przez użytkownika z powrotem do obiektu `BigDecimal`.                 |

### Obiekty pomocnicze

W tej grupie zgromadzono typy wyliczeniowe oraz interfejsy narzędziowe, które ściśle współpracują z operacjami matematycznymi i logiką biznesową wniosku.

* Typ `RoundingMode` daje programiście absolutną kontrolę nad algorytmami zaokrąglania w przypadku ucinania skali ułamków.
* Typ `DecimalFormatSymbols` ułatwia szybkie dostosowanie formatu liczbowego do specyfiki wybranego regionu (np. polskie przecinki vs angielskie kropki).
* Obiekt `Random` dostarcza bezpieczny i ustandaryzowany generator unikalnych identyfikatorów (UUID), niezbędny przy dynamicznym tworzeniu paczek danych.

```javascript
enum RoundingMode { UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN }

enum DecimalFormatSymbols { PL, EN, ES, SK, CZ }

interface Random {
    uuid(): string
}
```

## Praca z obiektem BigDecimal

### Tworzenie obiektu (Inicjalizacja)

Najbezpieczniejszym sposobem inicjalizacji wartości jest użycie metody `valueOf()` i przekazanie liczby w formie tekstowej (`String`). Gwarantuje to, że silnik JavaScript nie wprowadzi błędu precyzji jeszcze przed utworzeniem obiektu.

```javascript
let value = BigDecimal.valueOf("10.1000"); // Zdecydowanie zalecane podejście
```

{% hint style="warning" %}
**Niezmienność (Immutability)** Obiekt `BigDecimal` jest z założenia niezmienny. Operacje takie jak `add()` czy `divide()` obliczają wynik i zawsze zwracają zupełnie **nowy** obiekt. Błędem jest wywołanie metody bez przypisania wyniku z powrotem do zmiennej.
{% endhint %}

### Przykłady operacji matematycznych

**Dodawanie i odejmowanie**

```javascript
let value = BigDecimal.valueOf("100.50");
value = value.add("5.25");      // Wynik: 105.75
value = value.subtract("5.75"); // Wynik: 100.00
```

**Mnożenie i dzielenie**

Podczas dzielenia z wynikiem o nieskończonym rozwinięciu dziesiętnym (np. 10 podzielone przez 3), podanie samej wartości dzielnika spowoduje błąd. W takich przypadkach zawsze należy podawać docelową skalę oraz tryb zaokrąglenia.

```javascript
let value = BigDecimal.valueOf("100");
value = value.multiply("20"); // 100 * 20 = 2000

// Dzielenie ze wskazaniem precyzji: 10 / 3 = 3.33334
let shared = BigDecimal.valueOf("10");
shared = shared.divide("3", 5, RoundingMode.UP); 
```

**Ustawienie skali i porównywanie**

Do porównywania kwot nie należy używać standardowych operatorów JavaScript (np. `==`), lecz wbudowanych metod obiektowych `equals` oraz `compareTo`.

```javascript
let value = BigDecimal.valueOf("10.1234");
value = value.setScale(2, RoundingMode.HALF_UP); // Obcina i zaokrągla do: 10.12

let limit = BigDecimal.valueOf("10.50");
let isEqual = limit.equals("10.50"); // Zwraca: true
let comparison = limit.compareTo("5"); // Zwraca: 1 (wartość limit jest większa od 5)
```

## Zaokrąglanie i skale wyników

### Tryby zaokrąglania (RoundingMode)

Stałe z obiektu `RoundingMode` pozwalają na pełną kontrolę nad tym, co dzieje się z najmniej znaczącymi cyframi w przypadku dzielenia lub ucinania skali.

| Tryb        | Opis zachowania                                                                                                                                |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `HALF_UP`   | Zaokrągla w górę, jeśli część dziesiętna ≥ 0.5 (standardowe zaokrąglanie matematyczne).                                                        |
| `HALF_DOWN` | Zaokrągla w dół, jeśli część dziesiętna ≤ 0.5.                                                                                                 |
| `HALF_EVEN` | Tzw. zaokrąglenie "bankierskie". Zaokrągla do najbliższej liczby parzystej w przypadku idealnej połowy (0.5). Minimalizuje błędy statystyczne. |
| `CEILING`   | Zawsze powiększa liczbę w kierunku dodatniej nieskończoności.                                                                                  |
| `FLOOR`     | Zawsze pomniejsza liczbę w kierunku ujemnej nieskończoności.                                                                                   |
| `UP`        | Zaokrągla w kierunku "od zera" (zwiększa wartość absolutną liczby).                                                                            |
| `DOWN`      | Zwyczajnie obcina (odrzuca) niechciane ułamki dziesiętne, kierując się w stronę zera.                                                          |

### Preferowane skale dla operacji

Aby uniknąć ukrytej utraty danych po wykonaniu kilku kolejnych obliczeń matematycznych, zaleca się stosowanie poniższych wyliczeń skali wynikowej:

| Operacja                  | Zalecana skala wyniku                       |
| ------------------------- | ------------------------------------------- |
| Add (Dodawanie)           | `max(addend.scale(), augend.scale())`       |
| Subtract (Odejmowanie)    | `max(minuend.scale(), subtrahend.scale())`  |
| Multiply (Mnożenie)       | `multiplier.scale() + multiplicand.scale()` |
| Divide (Dzielenie)        | `dividend.scale() - divisor.scale()`        |
| Square root (Pierwiastek) | `radicand.scale() / 2`                      |

## Formatowanie danych do widoku (DecimalFormat)

Obiekt `DecimalFormat` odpowiada za bezpieczne rzutowanie z wartości matematycznej na reprezentację tekstową (formatowanie) oraz z reprezentacji tekstowej na obiekt `BigDecimal` (parsowanie).

### Symbole we wzorcach formatowania

| Symbol | Znaczenie                                                                                                                   |
| ------ | --------------------------------------------------------------------------------------------------------------------------- |
| `0`    | Zastępca dla cyfry. Wymusza wyświetlenie zera (np. tworzy zera wiodące lub sztywne zera końcowe dla groszy).                |
| `#`    | Opcjonalny zastępca dla cyfry. Zostanie wyświetlony tylko wtedy, gdy liczba go posiada, ukrywając niepotrzebne zera.        |
| `,`    | Separator dziesiętny lub grupowania tysięcy (odpowiednio tłumaczony w zależności od lokalizacji, np. spacja lub przecinek). |
| `%`    | Mnoży daną wartość przez 100 i na samym końcu dopisuje znak procentu.                                                       |
| `E`    | Oddziela mantysę od wykładnika, wymuszając wyświetlanie liczby w notacji naukowej (eksponencjalnej), np. `1.23E4`.          |

### Przykłady formatowania i parsowania

W poniższym przykładzie generowany jest polski format liczbowy.

```javascript
// Utworzenie formatera dla języka polskiego z wymuszeniem jednego miejsca po przecinku
let decimalFormatPL = DecimalFormat.of("#.0", DecimalFormatSymbols.PL);

// Z OBIEKTU DO TEKSTU: Formatowanie gotowe do pokazania użytkownikowi
let stringValue = decimalFormatPL.format(BigDecimal.valueOf("34.567")); 
// Zwróci tekst: "34,6"

// Z TEKSTU DO OBIEKTU: Parsowanie wartości pobranej np. z pola formularza
let decimalValue = decimalFormatPL.parse("34,6"); 
// Zwróci techniczny obiekt: BigDecimal(34.6)
```

## Narzędzia dodatkowe (Random)

API udostępnia klasę `Random` do generowania losowych identyfikatorów, przydatnych m.in. podczas zasilania struktur danych.

```javascript
function callService(context) {
    // Generowanie globalnie unikalnego, 128-bitowego identyfikatora UUID (wersja 4)
    let uniqueId = Random.uuid();
    
    return [{ 'output': uniqueId }];
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.eximee.com/budowanie-aplikacji/logika-biznesowa/scriptcode/skrypty-scriptservice/api-skryptow/podstawy-pracy-ze-skryptami/operacje-matematyczne-w-scriptcode.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
