polish-pluralize 1.1.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,21 +1,107 @@
|
|
|
1
1
|
# polish-pluralize 🇵🇱
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/polish-pluralize)
|
|
4
|
+
[](https://bundlephobia.com/package/polish-pluralize)
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
[](https://opensource.org/licenses/ISC)
|
|
7
|
+
|
|
8
|
+
Mała, szybka i w pełni otypowana biblioteka do poprawnej odmiany rzeczowników z liczebnikami w języku polskim. Bezpieczna dla środowiska produkcyjnego – z wbudowaną walidacją i obsługą liczb ujemnych.
|
|
9
|
+
|
|
10
|
+
> A tiny, fully-typed library for correct Polish noun pluralization. Production-safe with built-in validation and negative number support.
|
|
4
11
|
|
|
5
12
|
## Instalacja
|
|
6
13
|
|
|
14
|
+
Możesz zainstalować paczkę za pomocą wybranego menedżera pakietów:
|
|
15
|
+
|
|
7
16
|
```bash
|
|
8
17
|
npm install polish-pluralize
|
|
18
|
+
# lub
|
|
19
|
+
yarn add polish-pluralize
|
|
20
|
+
# lub
|
|
21
|
+
pnpm add polish-pluralize
|
|
9
22
|
```
|
|
10
23
|
|
|
11
|
-
##
|
|
24
|
+
## Podstawowe użycie
|
|
12
25
|
|
|
13
|
-
|
|
26
|
+
Funkcja przyjmuje liczbę oraz tablicę z trzema formami słowa (odpowiednio dla: 1, 2–4, 5+). Zwraca poprawnie odmienione słowo.
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { pluralize } from 'polish-pluralize';
|
|
30
|
+
|
|
31
|
+
const forms: [string, string, string] = ['plik', 'pliki', 'plików'];
|
|
32
|
+
|
|
33
|
+
pluralize(1, forms); // → "plik"
|
|
34
|
+
pluralize(3, forms); // → "pliki"
|
|
35
|
+
pluralize(5, forms); // → "plików"
|
|
36
|
+
pluralize(22, forms); // → "pliki"
|
|
37
|
+
pluralize(112, forms); // → "plików"
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Automatyczne dodawanie liczby
|
|
41
|
+
|
|
42
|
+
Zamiast ręcznie łączyć liczbę z odmienionym słowem, możesz przekazać trzeci, opcjonalny argument `includeNumber` jako `true`.
|
|
43
|
+
|
|
44
|
+
```ts
|
|
14
45
|
import { pluralize } from 'polish-pluralize';
|
|
15
46
|
|
|
16
|
-
const
|
|
17
|
-
|
|
47
|
+
const apples: [string, string, string] = ['jabłko', 'jabłka', 'jabłek'];
|
|
48
|
+
|
|
49
|
+
pluralize(1, apples, true); // → "1 jabłko"
|
|
50
|
+
pluralize(4, apples, true); // → "4 jabłka"
|
|
51
|
+
pluralize(12, apples, true); // → "12 jabłek"
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Obsługa liczb ujemnych i ułamków
|
|
55
|
+
|
|
56
|
+
Biblioteka poprawnie obsługuje wartości ujemne (np. przy wyświetlaniu salda czy punktów). Ułamki są zaokrąglane w dół (`Math.floor`).
|
|
18
57
|
|
|
19
|
-
|
|
20
|
-
|
|
58
|
+
> **Uwaga:** Forma pojedyncza (`forms[0]`) jest używana **wyłącznie** dla wartości `1`. Dla `-1` zostanie użyta forma trzecia (`forms[2]`).
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
const points: [string, string, string] = ['punkt', 'punkty', 'punktów'];
|
|
62
|
+
|
|
63
|
+
pluralize(-2, points, true); // → "-2 punkty"
|
|
64
|
+
pluralize(-10, points, true); // → "-10 punktów"
|
|
65
|
+
pluralize(-1, points, true); // → "-1 punktów"
|
|
66
|
+
pluralize(2.7, points); // → "punkty" (zaokrąglone do 2)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Walidacja w runtime
|
|
70
|
+
|
|
71
|
+
Biblioteka wyrzuca czytelne błędy, gdy przekazane argumenty są niepoprawne:
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
// ❌ Brak trzech form
|
|
75
|
+
pluralize(1, ['plik', 'pliki'] as any);
|
|
76
|
+
// Error: Biblioteka polish-pluralize wymaga parametru 'forms' jako tablicy z dokładnie 3 formami słowa
|
|
77
|
+
|
|
78
|
+
// ❌ Niepoprawna wartość count
|
|
79
|
+
pluralize(NaN, ['plik', 'pliki', 'plików']);
|
|
80
|
+
// Error: Parametr 'count' musi być poprawną liczbą.
|
|
21
81
|
```
|
|
82
|
+
|
|
83
|
+
## API
|
|
84
|
+
|
|
85
|
+
### `pluralize(count, forms, includeNumber?)`
|
|
86
|
+
|
|
87
|
+
| Parametr | Typ | Opis |
|
|
88
|
+
| --------------- | -------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
89
|
+
| `count` | `number` | Liczba, na podstawie której dokonywana jest odmiana. |
|
|
90
|
+
| `forms` | `[string, string, string]` | Tablica z trzema formami gramatycznymi (np. `['kot', 'koty', 'kotów']`). |
|
|
91
|
+
| `includeNumber` | `boolean` | *(Opcjonalnie)* Jeśli `true`, zwraca ciąg w formacie `„{liczba} {słowo}"`. Domyślnie `false`. |
|
|
92
|
+
|
|
93
|
+
**Zwraca:** `string` — odmienione słowo lub `„{liczba} {słowo}"` gdy `includeNumber = true`.
|
|
94
|
+
|
|
95
|
+
## Reguły odmiany
|
|
96
|
+
|
|
97
|
+
Biblioteka implementuje standardowe zasady polskiej gramatyki:
|
|
98
|
+
|
|
99
|
+
| Liczba | Forma | Przykład (`plik`) |
|
|
100
|
+
| --------------------- | ---------- | ------------------ |
|
|
101
|
+
| 1 | `forms[0]` | plik |
|
|
102
|
+
| 2–4, 22–24, 32–34... | `forms[1]` | pliki |
|
|
103
|
+
| 0, 5–21, 25–31, 112.. | `forms[2]` | plików |
|
|
104
|
+
|
|
105
|
+
## Licencja
|
|
106
|
+
|
|
107
|
+
[ISC](https://opensource.org/licenses/ISC) © [lapkaq](https://github.com/lapkaq)
|