clockey 1.4.1 → 1.4.2
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 +88 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -34,7 +34,22 @@ ESM / TypeScript:
|
|
|
34
34
|
|
|
35
35
|
```ts
|
|
36
36
|
import { getCurrentTimeResponse } from "clockey/response/timeResponse";
|
|
37
|
+
import { createTimer, isBefore, relativeTime } from "clockey";
|
|
38
|
+
|
|
37
39
|
console.log(getCurrentTimeResponse());
|
|
40
|
+
|
|
41
|
+
// Timer example
|
|
42
|
+
const timer = createTimer();
|
|
43
|
+
timer.start();
|
|
44
|
+
// ... some code ...
|
|
45
|
+
console.log(timer.end());
|
|
46
|
+
|
|
47
|
+
// Diff checker example
|
|
48
|
+
const pastDate = new Date("2025-12-25");
|
|
49
|
+
console.log(isBefore(pastDate)); // Check if date is before now
|
|
50
|
+
|
|
51
|
+
// Relative time example
|
|
52
|
+
console.log(relativeTime("2025-12-25")); // Human-readable relative time
|
|
38
53
|
```
|
|
39
54
|
|
|
40
55
|
Express example (route):
|
|
@@ -54,6 +69,30 @@ app.listen(3000);
|
|
|
54
69
|
|
|
55
70
|
Below are grouped, easy-to-read tables for the package exports. Each table shows usage and what the function returns.
|
|
56
71
|
|
|
72
|
+
### ⏲️ Utility Helpers
|
|
73
|
+
|
|
74
|
+
#### Timer
|
|
75
|
+
|
|
76
|
+
| Name | Example Usage | Output Format | Example Data |
|
|
77
|
+
| --------------- | ------------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
78
|
+
| `createTimer()` | `const timer = createTimer();` | `{ start, end, lap }` | Returns object with `start()`, `end()`, and `lap()` methods for performance timing |
|
|
79
|
+
| `timer.start()` | `timer.start();` | `void` | Starts the timer |
|
|
80
|
+
| `timer.end()` | `const result = timer.end();` | `{ elapsedMs, elapsedSec, elapsedMin, elapsedHrs, text }` \| `null` | `{ elapsedMs: 1234.5, elapsedSec: 1.23, elapsedMin: 0.02, elapsedHrs: 0.0003, text: '1234.50 ms' }` |
|
|
81
|
+
| `timer.lap()` | `const result = timer.lap();` | `{ durationMs, durationSec, durationMin, durationHrs, text }` \| `null` | `{ durationMs: 1234.5, durationSec: 1.23, durationMin: 0.02, durationHrs: 0.0003, text: '1234.50 ms' }` |
|
|
82
|
+
|
|
83
|
+
#### Diff Checker
|
|
84
|
+
|
|
85
|
+
| Name | Example Usage | Output Format | Example Data |
|
|
86
|
+
| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
|
87
|
+
| `isBefore()` | `const result = isBefore(timestamp);` | `{ isBefore, durationInMs, durationInSeconds, durationInMinutes, durationInHours, durationInDays }` \| `{ error }` | `{ isBefore: true, durationInMs: 5000, durationInSeconds: 5, durationInMinutes: 0.08, durationInHours: 0.001, durationInDays: 0.00006 }` |
|
|
88
|
+
| `isAfter()` | `const result = isAfter(timestamp);` | `{ isAfter, durationInMs, durationInSeconds, durationInMinutes, durationInHours, durationInDays }` \| `{ error }` | `{ isAfter: false, durationInMs: 5000, durationInSeconds: 5, durationInMinutes: 0.08, durationInHours: 0.001, durationInDays: 0.00006 }` |
|
|
89
|
+
|
|
90
|
+
#### Relative Time
|
|
91
|
+
|
|
92
|
+
| Name | Example Usage | Output Format | Example Data |
|
|
93
|
+
| ---------------- | ----------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
|
|
94
|
+
| `relativeTime()` | `const result = relativeTime(timestamp);` | `{ timestamp, timestampDate, humanReadable, isInFuture }` \| `{ error }` | `{ timestamp: 1735334400000, timestampDate: Date, humanReadable: '2 hours ago', isInFuture: false }` |
|
|
95
|
+
|
|
57
96
|
### ⏱️ Time helpers
|
|
58
97
|
|
|
59
98
|
| Name | Example Usage | Output Format | Example Data |
|
|
@@ -143,6 +182,55 @@ String only helper responses use `value`:
|
|
|
143
182
|
}
|
|
144
183
|
```
|
|
145
184
|
|
|
185
|
+
## ❌ Error Handling
|
|
186
|
+
|
|
187
|
+
Utility functions like `isBefore()`, `isAfter()`, and `relativeTime()` return error objects when invalid inputs are provided:
|
|
188
|
+
|
|
189
|
+
**Error Response Format:**
|
|
190
|
+
|
|
191
|
+
```json
|
|
192
|
+
{
|
|
193
|
+
"error": "invalid timestamp, please read documentation for more info"
|
|
194
|
+
}
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
**Common Error Cases:**
|
|
198
|
+
|
|
199
|
+
| Error Type | Example | How to Fix |
|
|
200
|
+
| ------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
|
|
201
|
+
| Invalid Date String | `isBefore('not-a-date')` | Use valid ISO 8601 format: `isBefore('2025-12-25')` |
|
|
202
|
+
| Invalid Date Object | `isBefore(new Date('invalid'))` | Create valid Date: `isBefore(new Date())` |
|
|
203
|
+
| NaN Number | `isBefore(NaN)` | Pass valid timestamp number: `isBefore(1735334400000)` |
|
|
204
|
+
| Null/Undefined | `isBefore(null)` or `isBefore(undefined)` | Ensure value is provided: `isBefore(timestamp)` |
|
|
205
|
+
| Invalid Type | `isBefore({})` | Use Date, number (milliseconds), or string: `isBefore(new Date())` |
|
|
206
|
+
|
|
207
|
+
**Example Error Handling:**
|
|
208
|
+
|
|
209
|
+
```ts
|
|
210
|
+
import { isBefore, relativeTime } from "clockey";
|
|
211
|
+
|
|
212
|
+
const result = isBefore("2025-12-25");
|
|
213
|
+
|
|
214
|
+
// Check for error
|
|
215
|
+
if ("error" in result) {
|
|
216
|
+
console.error("Error:", result.error);
|
|
217
|
+
// Handle the error appropriately
|
|
218
|
+
} else {
|
|
219
|
+
console.log("Duration:", result.durationInSeconds, "seconds");
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
**Accepted Timestamp Formats:**
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
// All of these are valid:
|
|
227
|
+
isBefore(new Date("2025-12-25")); // Date object
|
|
228
|
+
isBefore("2025-12-25"); // ISO 8601 string
|
|
229
|
+
isBefore("2025-12-25T10:30:00Z"); // ISO 8601 with time
|
|
230
|
+
isBefore(1735334400000); // Unix timestamp in milliseconds
|
|
231
|
+
isBefore(1735334400); // Unix timestamp in seconds (converted to ms)
|
|
232
|
+
```
|
|
233
|
+
|
|
146
234
|
## 🌐 Links & socials
|
|
147
235
|
|
|
148
236
|
- GitHub: https://github.com/yasasbanukaofficial
|