qznt 1.0.2 → 1.0.21
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 +13 -13
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# qznt
|
|
2
2
|
|
|
3
|
-
**qznt** (pronounced as in _ex-quisite_) is a
|
|
3
|
+
**qznt** (pronounced as in _ex-quisite_) is a lightweight, typed, high-performant utility toolkit for modern TypeScript/JavaScript and Node.js environments.
|
|
4
4
|
|
|
5
5
|
## 🚀 Installation
|
|
6
6
|
|
|
@@ -23,21 +23,21 @@ import { $ } from "qznt";
|
|
|
23
23
|
// or
|
|
24
24
|
import { obj, Loop, date } from "qznt";
|
|
25
25
|
|
|
26
|
-
//
|
|
26
|
+
// Nested object access (defaults to "dark" if mode is undefined)
|
|
27
27
|
const theme = qznt.obj.get(settings, "ui.theme.mode", "dark");
|
|
28
28
|
|
|
29
|
-
//
|
|
30
|
-
const timeRemaining = $.date.duration(Date.now() + 5000); // "5 seconds"
|
|
29
|
+
// Readable durations
|
|
30
|
+
const timeRemaining = $.date.duration(Date.now() + 5000); // "in 5 seconds"
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
## 📦 Namespaces
|
|
34
34
|
|
|
35
|
-
- **`qznt.arr` (
|
|
35
|
+
- **`qznt.arr` (Arrays)**: Advanced `chunk`, `cluster`, `shuffle`, `unique`, and `seqMap`
|
|
36
36
|
- **`qznt.async` (Promises)**: `retry` logic with exponential backoff and delay
|
|
37
37
|
- **`qznt.date` (Time)**: Shorthand parsing (`"1h 30m"`), `duration` (digital/hms), and `eta`
|
|
38
38
|
- **`qznt.fn` (Functions)**: `memoize` with TTL and custom resolvers
|
|
39
39
|
- **`qznt.format` (Strings)**: `currency`, `memory` (bytes), `ordinal`, and `compactNumber`
|
|
40
|
-
-
|
|
40
|
+
- **`qznt.fs` (File System)**: Efficient recursive directory scanning with `readDir`
|
|
41
41
|
- **`qznt.is` (Predicates)**: Type guards: `is.today`, `is.empty`, `is.object`, and `is.sorted`
|
|
42
42
|
- **`qznt.math` (Calculations)**: `lerp`, `invLerp`, `remap`, `percent`, and `sum`
|
|
43
43
|
- **`qznt.num` (Numbers)**: Essential logic like `clamp` and range handling
|
|
@@ -50,7 +50,7 @@ const timeRemaining = $.date.duration(Date.now() + 5000); // "5 seconds"
|
|
|
50
50
|
|
|
51
51
|
### The Smart `Loop`
|
|
52
52
|
|
|
53
|
-
|
|
53
|
+
`qznt.Loop` ensures async tasks never overlap. It waits for execution to finish before scheduling the next interval, and supports precise pausing/resuming. This is usually more efficient than `node-cron` for tasks that don't need scheduling.
|
|
54
54
|
|
|
55
55
|
```ts
|
|
56
56
|
import qznt from "qznt";
|
|
@@ -70,8 +70,8 @@ heartbeat.resume(); // Resumes with the exact remaining delay
|
|
|
70
70
|
|
|
71
71
|
`qznt` provides high-performant data persistence and memory management.
|
|
72
72
|
|
|
73
|
-
- `qznt.Cache`:
|
|
74
|
-
- `qznt.Storage`:
|
|
73
|
+
- `qznt.Cache`: Is an in-memory TTL cache with Sampled Passive/Active Eviction. It automatically purges expired entries to prevent memory leaks without blocking the event loop.
|
|
74
|
+
- `qznt.Storage`: Is a persistence layer. It automatically uses `localStorage` in browsers and falls back to local JSON files in Node.js environments. Think a mini-Redis cache.
|
|
75
75
|
|
|
76
76
|
```ts
|
|
77
77
|
// Cache with a 1-minute global TTL
|
|
@@ -85,7 +85,7 @@ settings.set("theme", "dark");
|
|
|
85
85
|
|
|
86
86
|
### Seedable Randomness
|
|
87
87
|
|
|
88
|
-
Every random utility in `qznt` accepts an optional seed. This allows you to generate predictable random data for testing, games, or procedural generation.
|
|
88
|
+
Every random utility in `qznt.rnd` accepts an optional seed. This allows you to generate predictable random data for testing, games, or procedural generation.
|
|
89
89
|
|
|
90
90
|
```ts
|
|
91
91
|
// Always returns the same item for seed 12345
|
|
@@ -94,7 +94,7 @@ const item = qznt.rnd.choice(["Sword", "Shield", "Potion"], 12345);
|
|
|
94
94
|
|
|
95
95
|
### Object Merging
|
|
96
96
|
|
|
97
|
-
A deep, recursive merge that maintains
|
|
97
|
+
A deep, recursive merge that maintains type safety across multiple sources.
|
|
98
98
|
|
|
99
99
|
```ts
|
|
100
100
|
const config = qznt.obj.merge(defaultConfig, userConfig, envOverrides);
|
|
@@ -102,7 +102,7 @@ const config = qznt.obj.merge(defaultConfig, userConfig, envOverrides);
|
|
|
102
102
|
|
|
103
103
|
### Type Guards
|
|
104
104
|
|
|
105
|
-
The `is` namespace provides predicates that act as
|
|
105
|
+
The `qznt.is` namespace provides predicates that act as type guards, ensuring type safety across your app.
|
|
106
106
|
|
|
107
107
|
```ts
|
|
108
108
|
if (qznt.is.today(user.lastLogin)) {
|
|
@@ -116,7 +116,7 @@ if (qznt.is.empty(results)) {
|
|
|
116
116
|
|
|
117
117
|
### Type-Safe Transformations
|
|
118
118
|
|
|
119
|
-
The `to` and `arr` namespaces provide
|
|
119
|
+
The `qznt.to` and `qznt.arr` namespaces also provide _✨ exquisite ✨_ ways to transform data structures while maintaining type safety.
|
|
120
120
|
|
|
121
121
|
```ts
|
|
122
122
|
const userRecord = qznt.to.record(usersArray, u => ({
|