polish-pluralize 1.0.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.
Files changed (6) hide show
  1. package/README.md +93 -7
  2. package/dist/index.d.mts +1 -1
  3. package/dist/index.d.ts +1 -1
  4. package/dist/index.js +21 -14
  5. package/dist/index.mjs +21 -14
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -1,21 +1,107 @@
1
1
  # polish-pluralize 🇵🇱
2
2
 
3
- Mała i szybka biblioteka do poprawnej odmiany słów z liczebnikami w języku polskim (np. 1 plik, 2 pliki, 5 plików).
3
+ [![npm version](https://img.shields.io/npm/v/polish-pluralize.svg)](https://www.npmjs.com/package/polish-pluralize)
4
+ [![npm bundle size](https://img.shields.io/bundlephobia/minzip/polish-pluralize)](https://bundlephobia.com/package/polish-pluralize)
5
+ [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-blue.svg)](https://www.typescriptlang.org/)
6
+ [![License: ISC](https://img.shields.io/badge/License-ISC-green.svg)](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
- ## Użycie
24
+ ## Podstawowe użycie
12
25
 
13
- ```bash
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 count = 5;
17
- const text = pluralize(count, ['plik', 'pliki', 'plików']);
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
- console.log(`Pobrano ${count} ${text}`);
20
- // Wynik: Pobrano 5 plików
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)
package/dist/index.d.mts CHANGED
@@ -1,3 +1,3 @@
1
- declare function pluralize(count: number, forms: [string, string, string]): string;
1
+ declare function pluralize(count: number, forms: [string, string, string], includeNumber?: boolean): string;
2
2
 
3
3
  export { pluralize };
package/dist/index.d.ts CHANGED
@@ -1,3 +1,3 @@
1
- declare function pluralize(count: number, forms: [string, string, string]): string;
1
+ declare function pluralize(count: number, forms: [string, string, string], includeNumber?: boolean): string;
2
2
 
3
3
  export { pluralize };
package/dist/index.js CHANGED
@@ -23,22 +23,29 @@ __export(index_exports, {
23
23
  pluralize: () => pluralize
24
24
  });
25
25
  module.exports = __toCommonJS(index_exports);
26
- function pluralize(count, forms) {
27
- const remainder = count % 10;
28
- const remainder100 = count % 100;
29
- if (remainder100 > 10 && remainder100 < 20) {
30
- return forms[2];
26
+ function pluralize(count, forms, includeNumber = false) {
27
+ if (!Array.isArray(forms) || forms.length !== 3) {
28
+ throw new Error(
29
+ "Biblioteka polish-pluralize wymaga parametru 'forms' jako tablicy z dok\u0142adnie 3 formami s\u0142owa (np. ['plik', 'pliki', 'plik\xF3w'])."
30
+ );
31
31
  }
32
- switch (remainder) {
33
- case 1:
34
- return forms[0];
35
- case 2:
36
- case 3:
37
- case 4:
38
- return forms[1];
39
- default:
40
- return forms[2];
32
+ if (typeof count !== "number" || Number.isNaN(count)) {
33
+ throw new Error("Parametr 'count' musi by\u0107 poprawn\u0105 liczb\u0105.");
41
34
  }
35
+ const absoluteCount = Math.floor(Math.abs(count));
36
+ let form;
37
+ if (absoluteCount === 1 && count === 1) {
38
+ form = forms[0];
39
+ } else {
40
+ const remainder100 = absoluteCount % 100;
41
+ const remainder10 = absoluteCount % 10;
42
+ if (remainder10 >= 2 && remainder10 <= 4 && (remainder100 < 10 || remainder100 >= 20)) {
43
+ form = forms[1];
44
+ } else {
45
+ form = forms[2];
46
+ }
47
+ }
48
+ return includeNumber ? `${count} ${form}` : form;
42
49
  }
43
50
  // Annotate the CommonJS export names for ESM import in node:
44
51
  0 && (module.exports = {
package/dist/index.mjs CHANGED
@@ -1,20 +1,27 @@
1
1
  // src/index.ts
2
- function pluralize(count, forms) {
3
- const remainder = count % 10;
4
- const remainder100 = count % 100;
5
- if (remainder100 > 10 && remainder100 < 20) {
6
- return forms[2];
2
+ function pluralize(count, forms, includeNumber = false) {
3
+ if (!Array.isArray(forms) || forms.length !== 3) {
4
+ throw new Error(
5
+ "Biblioteka polish-pluralize wymaga parametru 'forms' jako tablicy z dok\u0142adnie 3 formami s\u0142owa (np. ['plik', 'pliki', 'plik\xF3w'])."
6
+ );
7
7
  }
8
- switch (remainder) {
9
- case 1:
10
- return forms[0];
11
- case 2:
12
- case 3:
13
- case 4:
14
- return forms[1];
15
- default:
16
- return forms[2];
8
+ if (typeof count !== "number" || Number.isNaN(count)) {
9
+ throw new Error("Parametr 'count' musi by\u0107 poprawn\u0105 liczb\u0105.");
17
10
  }
11
+ const absoluteCount = Math.floor(Math.abs(count));
12
+ let form;
13
+ if (absoluteCount === 1 && count === 1) {
14
+ form = forms[0];
15
+ } else {
16
+ const remainder100 = absoluteCount % 100;
17
+ const remainder10 = absoluteCount % 10;
18
+ if (remainder10 >= 2 && remainder10 <= 4 && (remainder100 < 10 || remainder100 >= 20)) {
19
+ form = forms[1];
20
+ } else {
21
+ form = forms[2];
22
+ }
23
+ }
24
+ return includeNumber ? `${count} ${form}` : form;
18
25
  }
19
26
  export {
20
27
  pluralize
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "polish-pluralize",
3
- "version": "1.0.0",
3
+ "version": "1.1.1",
4
4
  "description": "Mała biblioteka do odmiany słów w języku polskim dla liczebników.",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",