clockey 1.0.0 → 1.0.2

package/README.md

@@ -1,3 +1,160 @@
-## Clockey
+# Clockey ⏰
 
-API-first time utilities for backend developers
+Beautiful, tiny utilities for working with current time and date in Node.js with ready-to-use API response wrappers for servers and lambdas.
+
+---
+
+## ✨ Highlights
+
+- Minimal, dependency-free TypeScript helpers for time & date.
+- Small API response wrappers returning a consistent `{ success, code, msg, ... }` shape for easy use in Express or serverless handlers.
+- Works with CommonJS and ES Modules.
+
+---
+
+## 💿 Installation
+
+```bash
+npm install clockey
+```
+
+---
+
+## ⚙️ Quick Examples
+
+CommonJS:
+
+```js
+const { formatCurrentTime, currentHour24Str } = require("clockey");
+console.log(formatCurrentTime());
+console.log(currentHour24Str()); // '09'
+```
+
+ESM / TypeScript:
+
+```ts
+import { getCurrentTimeResponse } from "clockey/response/timeResponse";
+console.log(getCurrentTimeResponse());
+```
+
+Express example (route):
+
+```js
+const express = require("express");
+const { getCurrentTimeResponse } = require("clockey/response/timeResponse");
+const app = express();
+
+app.get("/api/time", (req, res) => res.json(getCurrentTimeResponse()));
+app.listen(3000);
+```
+
+---
+
+## 📚 Methods (Quick usage)
+
+Below are grouped, easy-to-read tables for the package exports. Each table shows usage and what the function returns.
+
+### ⏱️ Time helpers
+
+| Name                  | Example               | Returns                                                                   |
+| --------------------- | --------------------- | ------------------------------------------------------------------------- | ------- |
+| `formatCurrentTime()` | `formatCurrentTime()` | Full object: numbers, padded strings, `timeAsString24` / `timeAsString12` |
+| `currentHour()`       | `currentHour()`       | `{ hour24, hour12, hour24Str, hour12Str }`                                |
+| `currentMinute()`     | `currentMinute()`     | `{ minute, minuteStr }`                                                   |
+| `currentSecond()`     | `currentSecond()`     | `{ second, secondStr }`                                                   |
+| `currentHour24Str()`  | `currentHour24Str()`  | `'09'` (string)                                                           |
+| `currentHour12Str()`  | `currentHour12Str()`  | `'09'` (string)                                                           |
+| `currentMinuteStr()`  | `currentMinuteStr()`  | `'05'` (string)                                                           |
+| `currentSecondStr()`  | `currentSecondStr()`  | `'07'` (string)                                                           |
+| `currentPeriod()`     | `currentPeriod()`     | `{ period: 'AM'                                                           | 'PM' }` |
+
+### 🧾 Time response helpers
+
+| Name                            | Example                         | Returns                                                             |
+| ------------------------------- | ------------------------------- | ------------------------------------------------------------------- |
+| `getCurrentTime()`              | `getCurrentTime()`              | `{ timeAsString12, timeAsString24 }`                                |
+| `getCurrentTimeResponse()`      | `getCurrentTimeResponse()`      | `{ success, code, msg, data }` where `data` = `formatCurrentTime()` |
+| `getCurrentHr()`                | `getCurrentHr()`                | returns `currentHour()`                                             |
+| `getCurrenHrResponse()`         | `getCurrenHrResponse()`         | `{ success, code, msg, hour }`                                      |
+| `getCurrentMinute()`            | `getCurrentMinute()`            | returns `currentMinute()`                                           |
+| `getCurrentMinuteResponse()`    | `getCurrentMinuteResponse()`    | `{ success, code, msg, minute }`                                    |
+| `getCurrentSecond()`            | `getCurrentSecond()`            | returns `currentSecond()`                                           |
+| `getCurrentSecondResponse()`    | `getCurrentSecondResponse()`    | `{ success, code, msg, second }`                                    |
+| `getCurrentHour24Str()`         | `getCurrentHour24Str()`         | string                                                              |
+| `getCurrentHour24StrResponse()` | `getCurrentHour24StrResponse()` | `{ success, code, msg, value }`                                     |
+| `getCurrentHour12Str()`         | `getCurrentHour12Str()`         | string                                                              |
+| `getCurrentHour12StrResponse()` | `getCurrentHour12StrResponse()` | `{ success, code, msg, value }`                                     |
+| `getCurrentMinuteStr()`         | `getCurrentMinuteStr()`         | string                                                              |
+| `getCurrentMinuteStrResponse()` | `getCurrentMinuteStrResponse()` | `{ success, code, msg, value }`                                     |
+| `getCurrentSecondStr()`         | `getCurrentSecondStr()`         | string                                                              |
+| `getCurrentSecondStrResponse()` | `getCurrentSecondStrResponse()` | `{ success, code, msg, value }`                                     |
+| `getCurrentPeriod()`            | `getCurrentPeriod()`            | `{ period }`                                                        |
+| `getCurrentPeriodResponse()`    | `getCurrentPeriodResponse()`    | `{ success, code, msg, period }`                                    |
+
+### 📅 Date helpers
+
+| Name                  | Example               | Returns                                                 |
+| --------------------- | --------------------- | ------------------------------------------------------- |
+| `formatCurrentDate()` | `formatCurrentDate()` | `{ date: { yr, month, day, date, ordinal, fullDate } }` |
+| `currentYear()`       | `currentYear()`       | `2025` (number)                                         |
+| `currentMonth()`      | `currentMonth()`      | `{ monthNumber, monthName, monthStr }`                  |
+| `currentDay()`        | `currentDay()`        | `{ dayIndex, dayName }`                                 |
+| `currentDateNumber()` | `currentDateNumber()` | `{ date, dateStr }`                                     |
+| `currentOrdinal()`    | `currentOrdinal()`    | `{ ordinal }`                                           |
+| `currentFullDate()`   | `currentFullDate()`   | `{ fullDate }`                                          |
+
+### 🗂 Date response helpers
+
+| Name                             | Example                          | Returns                                                |
+| -------------------------------- | -------------------------------- | ------------------------------------------------------ |
+| `getCurrentDate()`               | `getCurrentDate()`               | `ClockeyDateResponse` (`{ success, code, msg, data }`) |
+| `getCurrentYearResponse()`       | `getCurrentYearResponse()`       | `{ success, code, msg, value }`                        |
+| `getCurrentMonthResponse()`      | `getCurrentMonthResponse()`      | `{ success, code, msg, value }`                        |
+| `getCurrentDayResponse()`        | `getCurrentDayResponse()`        | `{ success, code, msg, value }`                        |
+| `getCurrentDateNumberResponse()` | `getCurrentDateNumberResponse()` | `{ success, code, msg, value }`                        |
+| `getCurrentOrdinalResponse()`    | `getCurrentOrdinalResponse()`    | `{ success, code, msg, value }`                        |
+| `getCurrentFullDateResponse()`   | `getCurrentFullDateResponse()`   | `{ success, code, msg, value }`                        |
+
+---
+
+## ✅ Response shapes
+
+Success (example):
+
+```json
+{
+  "success": true,
+  "code": 200,
+  "msg": "Current time fetched successfully",
+  "data": {
+    /* payload */
+  }
+}
+```
+
+String-only helper responses use `value`:
+
+```json
+{
+  "success": true,
+  "code": 200,
+  "msg": "Current hour string fetched",
+  "value": "09"
+}
+```
+
+---
+
+## 🤝 Contributing
+
+PRs welcome. Keep changes small and add tests for functional changes.
+
+---
+
+## 🌐 Links & socials
+
+- GitHub: https://github.com/yasasbanukaofficial
+- NPM: https://www.npmjs.com/~yasasbanukaofficial
+- LinkedIn: https://www.linkedin.com/in/yasasbanukagunasena/
+
+---

package/dist/index.d.mts

@@ -0,0 +1,194 @@
+interface TimeData {
+  hr24: number;
+  hr12: number;
+  min: number;
+  sec: number;
+  period: "AM" | "PM" | string;
+  timeAsString24: string;
+  timeAsString12: string;
+}
+
+interface ClockeyTimeResponse {
+  success: boolean;
+  code: number;
+  msg: string;
+  data: TimeData;
+}
+
+declare function getCurrentTime(): {
+    timeAsString12: string;
+    timeAsString24: string;
+};
+declare function getCurrentTimeResponse(): ClockeyTimeResponse;
+declare function getCurrentHr(): {
+    hour24: number;
+    hour12: number;
+    hour24Str: string;
+    hour12Str: string;
+};
+declare function getCurrenHrResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    hour: {
+        hour24: number;
+        hour12: number;
+        hour24Str: string;
+        hour12Str: string;
+    };
+};
+declare function getCurrentMinute(): {
+    minute: number;
+    minuteStr: string;
+};
+declare function getCurrentMinuteResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    minute: {
+        minute: number;
+        minuteStr: string;
+    };
+};
+declare function getCurrentSecond(): {
+    second: number;
+    secondStr: string;
+};
+declare function getCurrentSecondResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    second: {
+        second: number;
+        secondStr: string;
+    };
+};
+declare function getCurrentHour24Str(): string;
+declare function getCurrentHour24StrResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: string;
+};
+declare function getCurrentHour12Str(): string;
+declare function getCurrentHour12StrResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: string;
+};
+declare function getCurrentMinuteStr(): string;
+declare function getCurrentMinuteStrResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: string;
+};
+declare function getCurrentSecondStr(): string;
+declare function getCurrentSecondStrResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: string;
+};
+declare function getCurrentPeriod(): {
+    period: string;
+};
+declare function getCurrentPeriodResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    period: {
+        period: string;
+    };
+};
+
+interface DateData {
+  yr: number;
+  month: string;
+  day: string;
+  date: number;
+  ordinal: string;
+  fullDate: string;
+}
+
+interface ClockeyDateResponse {
+  success: boolean;
+  code: number;
+  msg: string;
+  data: DateData;
+}
+
+declare function getCurrentDate(): ClockeyDateResponse;
+declare function getCurrentYear(): number;
+declare function getCurrentYearResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: number;
+};
+declare function getCurrentMonth(): {
+    monthNumber: number;
+    monthName: string;
+    monthStr: string;
+};
+declare function getCurrentMonthResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: {
+        monthNumber: number;
+        monthName: string;
+        monthStr: string;
+    };
+};
+declare function getCurrentDay(): {
+    dayIndex: number;
+    dayName: string;
+};
+declare function getCurrentDayResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: {
+        dayIndex: number;
+        dayName: string;
+    };
+};
+declare function getCurrentDateNumber(): {
+    date: number;
+    dateStr: string;
+};
+declare function getCurrentDateNumberResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: {
+        date: number;
+        dateStr: string;
+    };
+};
+declare function getCurrentOrdinal(): {
+    ordinal: string;
+};
+declare function getCurrentOrdinalResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: {
+        ordinal: string;
+    };
+};
+declare function getCurrentFullDate(): {
+    fullDate: string;
+};
+declare function getCurrentFullDateResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: {
+        fullDate: string;
+    };
+};
+
+export { getCurrenHrResponse, getCurrentDate, getCurrentDateNumber, getCurrentDateNumberResponse, getCurrentDay, getCurrentDayResponse, getCurrentFullDate, getCurrentFullDateResponse, getCurrentHour12Str, getCurrentHour12StrResponse, getCurrentHour24Str, getCurrentHour24StrResponse, getCurrentHr, getCurrentMinute, getCurrentMinuteResponse, getCurrentMinuteStr, getCurrentMinuteStrResponse, getCurrentMonth, getCurrentMonthResponse, getCurrentOrdinal, getCurrentOrdinalResponse, getCurrentPeriod, getCurrentPeriodResponse, getCurrentSecond, getCurrentSecondResponse, getCurrentSecondStr, getCurrentSecondStrResponse, getCurrentTime, getCurrentTimeResponse, getCurrentYear, getCurrentYearResponse };

package/dist/index.d.ts

@@ -0,0 +1,194 @@
+interface TimeData {
+  hr24: number;
+  hr12: number;
+  min: number;
+  sec: number;
+  period: "AM" | "PM" | string;
+  timeAsString24: string;
+  timeAsString12: string;
+}
+
+interface ClockeyTimeResponse {
+  success: boolean;
+  code: number;
+  msg: string;
+  data: TimeData;
+}
+
+declare function getCurrentTime(): {
+    timeAsString12: string;
+    timeAsString24: string;
+};
+declare function getCurrentTimeResponse(): ClockeyTimeResponse;
+declare function getCurrentHr(): {
+    hour24: number;
+    hour12: number;
+    hour24Str: string;
+    hour12Str: string;
+};
+declare function getCurrenHrResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    hour: {
+        hour24: number;
+        hour12: number;
+        hour24Str: string;
+        hour12Str: string;
+    };
+};
+declare function getCurrentMinute(): {
+    minute: number;
+    minuteStr: string;
+};
+declare function getCurrentMinuteResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    minute: {
+        minute: number;
+        minuteStr: string;
+    };
+};
+declare function getCurrentSecond(): {
+    second: number;
+    secondStr: string;
+};
+declare function getCurrentSecondResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    second: {
+        second: number;
+        secondStr: string;
+    };
+};
+declare function getCurrentHour24Str(): string;
+declare function getCurrentHour24StrResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: string;
+};
+declare function getCurrentHour12Str(): string;
+declare function getCurrentHour12StrResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: string;
+};
+declare function getCurrentMinuteStr(): string;
+declare function getCurrentMinuteStrResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: string;
+};
+declare function getCurrentSecondStr(): string;
+declare function getCurrentSecondStrResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: string;
+};
+declare function getCurrentPeriod(): {
+    period: string;
+};
+declare function getCurrentPeriodResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    period: {
+        period: string;
+    };
+};
+
+interface DateData {
+  yr: number;
+  month: string;
+  day: string;
+  date: number;
+  ordinal: string;
+  fullDate: string;
+}
+
+interface ClockeyDateResponse {
+  success: boolean;
+  code: number;
+  msg: string;
+  data: DateData;
+}
+
+declare function getCurrentDate(): ClockeyDateResponse;
+declare function getCurrentYear(): number;
+declare function getCurrentYearResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: number;
+};
+declare function getCurrentMonth(): {
+    monthNumber: number;
+    monthName: string;
+    monthStr: string;
+};
+declare function getCurrentMonthResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: {
+        monthNumber: number;
+        monthName: string;
+        monthStr: string;
+    };
+};
+declare function getCurrentDay(): {
+    dayIndex: number;
+    dayName: string;
+};
+declare function getCurrentDayResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: {
+        dayIndex: number;
+        dayName: string;
+    };
+};
+declare function getCurrentDateNumber(): {
+    date: number;
+    dateStr: string;
+};
+declare function getCurrentDateNumberResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: {
+        date: number;
+        dateStr: string;
+    };
+};
+declare function getCurrentOrdinal(): {
+    ordinal: string;
+};
+declare function getCurrentOrdinalResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: {
+        ordinal: string;
+    };
+};
+declare function getCurrentFullDate(): {
+    fullDate: string;
+};
+declare function getCurrentFullDateResponse(): {
+    success: boolean;
+    code: number;
+    msg: string;
+    value: {
+        fullDate: string;
+    };
+};
+
+export { getCurrenHrResponse, getCurrentDate, getCurrentDateNumber, getCurrentDateNumberResponse, getCurrentDay, getCurrentDayResponse, getCurrentFullDate, getCurrentFullDateResponse, getCurrentHour12Str, getCurrentHour12StrResponse, getCurrentHour24Str, getCurrentHour24StrResponse, getCurrentHr, getCurrentMinute, getCurrentMinuteResponse, getCurrentMinuteStr, getCurrentMinuteStrResponse, getCurrentMonth, getCurrentMonthResponse, getCurrentOrdinal, getCurrentOrdinalResponse, getCurrentPeriod, getCurrentPeriodResponse, getCurrentSecond, getCurrentSecondResponse, getCurrentSecondStr, getCurrentSecondStrResponse, getCurrentTime, getCurrentTimeResponse, getCurrentYear, getCurrentYearResponse };