@pol-studios/utils 1.0.0 → 1.0.6

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 (2) hide show
  1. package/README.md +199 -0
  2. package/package.json +86 -27
package/README.md ADDED
@@ -0,0 +1,199 @@
1
+ # @pol-studios/utils
2
+
3
+ > Utility functions for POL applications
4
+
5
+ The foundation package for the POL-One monorepo. Provides common utility functions for string manipulation, array operations, object handling, date parsing, async patterns, formatting, and more. This package has no internal dependencies and serves as the base for other `@pol-studios/*` packages.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ pnpm add @pol-studios/utils
11
+ ```
12
+
13
+ ## Peer Dependencies
14
+
15
+ ```bash
16
+ pnpm add moment
17
+ ```
18
+
19
+ ## Quick Start
20
+
21
+ ```tsx
22
+ import { cn, camelize, groupBy, formatCurrency } from "@pol-studios/utils";
23
+
24
+ // Tailwind class merging
25
+ const className = cn("px-4 py-2", isActive && "bg-blue-500");
26
+
27
+ // String transformation
28
+ const camelCase = camelize("hello-world"); // "helloWorld"
29
+
30
+ // Array grouping
31
+ const grouped = groupBy(items, (item) => item.category);
32
+
33
+ // Currency formatting
34
+ const price = formatCurrency(1234.56); // "$1,234.56"
35
+ ```
36
+
37
+ ## Subpath Exports
38
+
39
+ | Path | Description |
40
+ |------|-------------|
41
+ | `@pol-studios/utils` | All exports combined |
42
+ | `@pol-studios/utils/string` | String manipulation utilities |
43
+ | `@pol-studios/utils/array` | Array operations and transformations |
44
+ | `@pol-studios/utils/object` | Object manipulation utilities |
45
+ | `@pol-studios/utils/date` | Date parsing, comparison, and manipulation |
46
+ | `@pol-studios/utils/async` | Async utilities (delay, debounce, semaphore) |
47
+ | `@pol-studios/utils/format` | Currency and decimal formatting |
48
+ | `@pol-studios/utils/tailwind` | Tailwind CSS class utilities |
49
+ | `@pol-studios/utils/cache` | Function result caching |
50
+ | `@pol-studios/utils/types` | TypeScript type utilities |
51
+ | `@pol-studios/utils/color` | Color manipulation utilities |
52
+ | `@pol-studios/utils/validation` | Input validation and password utilities |
53
+ | `@pol-studios/utils/error` | Error handling utilities |
54
+ | `@pol-studios/utils/device` | Device detection utilities |
55
+ | `@pol-studios/utils/uuid` | UUID generation utilities |
56
+ | `@pol-studios/utils/state` | State management utilities |
57
+ | `@pol-studios/utils/enum` | Enum handling utilities |
58
+ | `@pol-studios/utils/dev` | Development utilities |
59
+
60
+ ## API Reference
61
+
62
+ ### String Utilities
63
+
64
+ ```tsx
65
+ import { camelize, pascalize, slugify, sanitizeInput, isBlank } from "@pol-studios/utils/string";
66
+
67
+ camelize("hello-world"); // "helloWorld"
68
+ pascalize("hello-world"); // "HelloWorld"
69
+ pascalizeWithSpaces("hello_world"); // "Hello World"
70
+ slugify("Hello World"); // "hello-world"
71
+ generateSlug("My Title"); // "my-title"
72
+ sanitizeInput("<script>alert()</script>"); // Sanitized string
73
+ isBlank(""); // true
74
+ isNullOrWhitespace(" "); // true
75
+ ```
76
+
77
+ ### Array Utilities
78
+
79
+ ```tsx
80
+ import { sortBy, groupBy, chunk, unique, range, tryGetSum, tryGetAverage } from "@pol-studios/utils/array";
81
+
82
+ sortBy(items, "name"); // Sort by property
83
+ groupBy(items, (i) => i.category); // Group by function
84
+ groupByMultipleCriteria(items, ["a", "b"]); // Multi-level grouping
85
+ chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
86
+ unique([1, 2, 2, 3]); // [1, 2, 3]
87
+ mapUnique(items, "id"); // Unique by property
88
+ range(1, 5); // [1, 2, 3, 4, 5]
89
+ tryGetSum(items, "amount"); // Sum of property values
90
+ tryGetAverage(items, "score"); // Average of property values
91
+ selectByMin(items, "price"); // Item with minimum value
92
+ convertArrayToObject(items, "id"); // Convert to keyed object
93
+ ```
94
+
95
+ ### Object Utilities
96
+
97
+ ```tsx
98
+ import { omit, pick, diff, getPath, setPath, deepEquals } from "@pol-studios/utils/object";
99
+
100
+ omit(obj, ["password", "secret"]); // Remove properties
101
+ pick(obj, ["name", "email"]); // Keep only specified properties
102
+ includeOnly(obj, ["a", "b"]); // Alias for pick
103
+ diff(objA, objB); // Get differences between objects
104
+ getPath(obj, "user.address.city"); // Deep property access
105
+ getValueByPath(obj, "a.b.c"); // Alias for getPath
106
+ setPath(obj, "user.name", "John"); // Deep property setting
107
+ setValueByPath(obj, "a.b", value); // Alias for setPath
108
+ deepEquals(objA, objB); // Deep equality comparison
109
+ isDeepEqual(objA, objB); // Alias for deepEquals
110
+ ```
111
+
112
+ ### Date Utilities
113
+
114
+ ```tsx
115
+ import { parseDate, compareDates, addDays, toUTC } from "@pol-studios/utils/date";
116
+
117
+ // Parsing, comparison, addition, and UTC conversion utilities
118
+ // Requires moment as a peer dependency
119
+ ```
120
+
121
+ ### Async Utilities
122
+
123
+ ```tsx
124
+ import { delay, debounce, runConcurrent, Semaphore } from "@pol-studios/utils/async";
125
+
126
+ await delay(1000); // Wait 1 second
127
+ const debouncedFn = debounce(fn, 300); // Debounce function calls
128
+ await runConcurrent(tasks, 5); // Run with concurrency limit
129
+ const semaphore = new Semaphore(3); // Limit concurrent operations
130
+ ```
131
+
132
+ ### Format Utilities
133
+
134
+ ```tsx
135
+ import { formatCurrency, formatDecimal } from "@pol-studios/utils/format";
136
+
137
+ formatCurrency(1234.56); // "$1,234.56"
138
+ formatDecimal(0.1234, 2); // "0.12"
139
+ ```
140
+
141
+ ### Tailwind Utilities
142
+
143
+ ```tsx
144
+ import { cn } from "@pol-studios/utils/tailwind";
145
+
146
+ // Merge Tailwind classes with conflict resolution (clsx + tailwind-merge)
147
+ cn("px-4 py-2", isActive && "bg-blue-500", "px-8"); // "py-2 bg-blue-500 px-8"
148
+ ```
149
+
150
+ ### Cache Utilities
151
+
152
+ ```tsx
153
+ import { cacheFunction, clearCache, clearAllCache } from "@pol-studios/utils/cache";
154
+
155
+ // Cache async function results
156
+ const data = await cacheFunction("key", fetchData, 60000); // Cache for 1 minute
157
+ clearCache("key"); // Clear specific cache
158
+ clearAllCache(); // Clear all cached data
159
+ ```
160
+
161
+ ### Color Utilities
162
+
163
+ ```tsx
164
+ import { isDarkColor } from "@pol-studios/utils/color";
165
+
166
+ isDarkColor("#000000"); // true
167
+ isDarkColor("#ffffff"); // false
168
+ ```
169
+
170
+ ### Validation Utilities
171
+
172
+ ```tsx
173
+ import { isValidEmail, isValidPhone, validatePassword } from "@pol-studios/utils/validation";
174
+
175
+ // Input validation and password strength checking
176
+ ```
177
+
178
+ ## TypeScript Types
179
+
180
+ The package exports namespace modules for tree-shaking:
181
+
182
+ ```tsx
183
+ import { string, array, object, date } from "@pol-studios/utils";
184
+
185
+ string.camelize("hello-world");
186
+ array.groupBy(items, fn);
187
+ object.pick(obj, keys);
188
+ ```
189
+
190
+ ## Related Packages
191
+
192
+ - [@pol-studios/db/auth](../auth) - Authentication (depends on utils)
193
+ - [@pol-studios/db](../db) - Database layer (depends on utils)
194
+ - [@pol-studios/hooks](../hooks) - React hooks (depends on utils)
195
+ - [@pol-studios/ui](../ui) - UI components (depends on utils)
196
+
197
+ ## License
198
+
199
+ UNLICENSED
package/package.json CHANGED
@@ -1,37 +1,92 @@
1
1
  {
2
2
  "name": "@pol-studios/utils",
3
- "version": "1.0.0",
3
+ "version": "1.0.6",
4
4
  "description": "Utility functions for POL applications",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
7
7
  "main": "./dist/index.js",
8
8
  "types": "./dist/index.d.ts",
9
- "files": ["dist"],
10
- "keywords": ["utils", "utilities", "helpers"],
9
+ "files": [
10
+ "dist"
11
+ ],
12
+ "keywords": [
13
+ "utils",
14
+ "utilities",
15
+ "helpers"
16
+ ],
11
17
  "exports": {
12
- ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
13
- "./string": { "import": "./dist/string/index.js", "types": "./dist/string/index.d.ts" },
14
- "./array": { "import": "./dist/array/index.js", "types": "./dist/array/index.d.ts" },
15
- "./object": { "import": "./dist/object/index.js", "types": "./dist/object/index.d.ts" },
16
- "./date": { "import": "./dist/date/index.js", "types": "./dist/date/index.d.ts" },
17
- "./async": { "import": "./dist/async/index.js", "types": "./dist/async/index.d.ts" },
18
- "./format": { "import": "./dist/format/index.js", "types": "./dist/format/index.d.ts" },
19
- "./tailwind": { "import": "./dist/tailwind/index.js", "types": "./dist/tailwind/index.d.ts" },
20
- "./cache": { "import": "./dist/cache/index.js", "types": "./dist/cache/index.d.ts" },
21
- "./types": { "import": "./dist/types/index.js", "types": "./dist/types/index.d.ts" },
22
- "./color": { "import": "./dist/color/index.js", "types": "./dist/color/index.d.ts" },
23
- "./validation": { "import": "./dist/validation/index.js", "types": "./dist/validation/index.d.ts" },
24
- "./error": { "import": "./dist/error/index.js", "types": "./dist/error/index.d.ts" },
25
- "./device": { "import": "./dist/device/index.js", "types": "./dist/device/index.d.ts" },
26
- "./uuid": { "import": "./dist/uuid/index.js", "types": "./dist/uuid/index.d.ts" },
27
- "./state": { "import": "./dist/state/index.js", "types": "./dist/state/index.d.ts" },
28
- "./enum": { "import": "./dist/enum/index.js", "types": "./dist/enum/index.d.ts" },
29
- "./dev": { "import": "./dist/dev/index.js", "types": "./dist/dev/index.d.ts" }
30
- },
31
- "scripts": {
32
- "build": "tsup",
33
- "dev": "tsup --watch",
34
- "prepublishOnly": "pnpm build"
18
+ ".": {
19
+ "import": "./dist/index.js",
20
+ "types": "./dist/index.d.ts"
21
+ },
22
+ "./string": {
23
+ "import": "./dist/string/index.js",
24
+ "types": "./dist/string/index.d.ts"
25
+ },
26
+ "./array": {
27
+ "import": "./dist/array/index.js",
28
+ "types": "./dist/array/index.d.ts"
29
+ },
30
+ "./object": {
31
+ "import": "./dist/object/index.js",
32
+ "types": "./dist/object/index.d.ts"
33
+ },
34
+ "./date": {
35
+ "import": "./dist/date/index.js",
36
+ "types": "./dist/date/index.d.ts"
37
+ },
38
+ "./async": {
39
+ "import": "./dist/async/index.js",
40
+ "types": "./dist/async/index.d.ts"
41
+ },
42
+ "./format": {
43
+ "import": "./dist/format/index.js",
44
+ "types": "./dist/format/index.d.ts"
45
+ },
46
+ "./tailwind": {
47
+ "import": "./dist/tailwind/index.js",
48
+ "types": "./dist/tailwind/index.d.ts"
49
+ },
50
+ "./cache": {
51
+ "import": "./dist/cache/index.js",
52
+ "types": "./dist/cache/index.d.ts"
53
+ },
54
+ "./types": {
55
+ "import": "./dist/types/index.js",
56
+ "types": "./dist/types/index.d.ts"
57
+ },
58
+ "./color": {
59
+ "import": "./dist/color/index.js",
60
+ "types": "./dist/color/index.d.ts"
61
+ },
62
+ "./validation": {
63
+ "import": "./dist/validation/index.js",
64
+ "types": "./dist/validation/index.d.ts"
65
+ },
66
+ "./error": {
67
+ "import": "./dist/error/index.js",
68
+ "types": "./dist/error/index.d.ts"
69
+ },
70
+ "./device": {
71
+ "import": "./dist/device/index.js",
72
+ "types": "./dist/device/index.d.ts"
73
+ },
74
+ "./uuid": {
75
+ "import": "./dist/uuid/index.js",
76
+ "types": "./dist/uuid/index.d.ts"
77
+ },
78
+ "./state": {
79
+ "import": "./dist/state/index.js",
80
+ "types": "./dist/state/index.d.ts"
81
+ },
82
+ "./enum": {
83
+ "import": "./dist/enum/index.js",
84
+ "types": "./dist/enum/index.d.ts"
85
+ },
86
+ "./dev": {
87
+ "import": "./dist/dev/index.js",
88
+ "types": "./dist/dev/index.d.ts"
89
+ }
35
90
  },
36
91
  "publishConfig": {
37
92
  "access": "public"
@@ -46,5 +101,9 @@
46
101
  "devDependencies": {
47
102
  "tsup": "^8.0.0",
48
103
  "typescript": "^5.0.0"
104
+ },
105
+ "scripts": {
106
+ "build": "tsup",
107
+ "dev": "tsup --watch"
49
108
  }
50
- }
109
+ }