utills 0.1.2 → 0.1.3

package/README.md

@@ -1,13 +1,13 @@
-# utils
+# utills
 
-![thumbmail](./public/assets/utills-web.jpg)
+![thumbmail](https://raw.githubusercontent.com/safayet35/utills/main/public/assets/utills-web.jpg)
 
 Lightweight, dependency-free utility functions for modern JavaScript and TypeScript projects.
 
-This package is designed to be simple, secure, and developer-friendly.  
+This package is designed to be **simple**, **secure**, and **developer-friendly**.  
 It works in both **Node.js** and **browser environments** and follows modern **ESM standards**.
 
-**Check out** 👉 [Docs](https://utills.vercel.app/)
+👉 **Documentation:** https://utills.vercel.app/
 
 ---
 
@@ -18,30 +18,30 @@ It works in both **Node.js** and **browser environments** and follows modern **E
 -   Zero external dependencies
 -   Tree-shaking friendly
 -   Browser & Node.js support
--   Secure (crypto-based utilities)
+-   Crypto-based secure utilities
+-   Fully unit-tested with **Vitest**
 
 ---
 
 ## 📦 Installation
 
 ```bash
-npm install utils
+npm install utills
 ```
 
 # Usage
 
 ```bash
-
 import {
   randomId,
   timeAgo,
-} from "utils";
+} from "utills";
 
 randomId();
 timeAgo(Date.now() - 60000);
 ```
 
-## Available Utilities
+## Example Utilities
 
 | Method             | Parameters        | Returns  | Description                                                  |
 | ------------------ | ----------------- | -------- | ------------------------------------------------------------ |
@@ -49,9 +49,33 @@ timeAgo(Date.now() - 60000);
 | **generateSecret** | `length?`         | `string` | Generates a cryptographically secure secret token.           |
 | **timeAgo**        | `date`, `locale?` | `string` | Returns human-readable relative time (e.g. "2 minutes ago"). |
 
+## Testing
+
+This project uses Vitest for unit testing.
+
+All utility functions must include tests, even if they generate random values.
+
+Run test
+
+```bash
+npm run test
+```
+
+Testing rules:
+
+-   Each utility must have a corresponding test file
+-   Random-based utilities should be tested using:
+    -   output length
+    -   output type
+    -   allowed character sets
+    -   error cases
+-   Edge cases must be covered
+
 ## Contributing
 
-Contributions are welcome and appreciated.
+Contributions are welcome and appreciated!
+
+Before contributing, please read the guidelines below carefully.
 
 ## How to contribute
 
@@ -76,6 +100,12 @@ git checkout -b feature/new-utility
 src/core/
 ```
 
+Rules
+
+-   One utility per file
+-   Must support both JS & TS
+-   Must handle invalid inputs properly
+
 5: Export it from:
 
 ```bash
@@ -84,13 +114,58 @@ src/core/index.ts
 
 6: Build and test
 
+Add tests using Vitest for your utility.
+
+```bash
+npm run test
+```
+
+Pull requests **without tests will not be accepted**
+
+7: Update Docs (Required)
+
+This project has a docs website.
+
+After adding a utility, you must update the docs data file:
+
+```bash
+docs/src/api/methods.data.js
+```
+
+Add your utility following the existing pattern, including:
+
+-   name
+-   description
+-   parameters
+-   return type
+-   example usage
+
+Example structure:
+
+```bash
+yourUtility: {
+  name: "yourUtility",
+  description: "What this utility does",
+  params: [],
+  returns: "string",
+  example: `import { yourUtility } from "utills"
+
+yourUtility();`
+}
+```
+
+This data is used to render the API documentation UI
+
+8: Build and verify
+
 ```bash
 npm run build
+npm run test
 ```
 
-7: Commit your changes with a clear message
+9: Commit & Open PR
 
-8: Open a Pull Request
+Use clear commit messages and open a Pull Request with a proper description.
 
 ## Contribution Guideline
 
@@ -99,6 +174,8 @@ npm run build
 -   Use native APIs where possible
 -   Handle edge cases properly
 -   Keep code clean and readable
+-   Tests are mandatory
+-   Utilities should be reusable & generic
 
 ## Roadmap
 
@@ -110,3 +187,6 @@ npm run build
 ## License
 
 MIT License © Safayet Rahman
+
+
+

package/dist/core/generateSecret.d.ts

@@ -7,3 +7,4 @@
  * generateSecret(64)
  */
 export declare function generateSecret(length?: number): string;
+//# sourceMappingURL=generateSecret.d.ts.map

package/dist/core/generateSecret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateSecret.d.ts","sourceRoot":"","sources":["../../src/core/generateSecret.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,MAAW,GAAG,MAAM,CAwB1D"}

package/dist/core/generateSecret.js

@@ -25,3 +25,4 @@ export function generateSecret(length = 32) {
     }
     return secret;
 }
+//# sourceMappingURL=generateSecret.js.map

package/dist/core/generateSecret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateSecret.js","sourceRoot":"","sources":["../../src/core/generateSecret.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE;IAChD,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;IAClE,CAAC;IAED,MAAM,OAAO,GAAG,gEAAgE,CAAA;IAChF,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAA;IAEpC,mCAAmC;IACnC,MAAM,SAAS,GACb,OAAO,MAAM,KAAK,WAAW;QAC3B,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,aAAa;YACb,OAAO,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAA;IAEjC,MAAM,YAAY,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAAA;IAC5C,SAAS,CAAC,eAAe,CAAC,YAAY,CAAC,CAAA;IAEvC,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAA;IACpD,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/core/index.d.ts

@@ -1,3 +1,5 @@
 export { randomId } from "./randomId.js";
 export { generateSecret } from "./generateSecret.js";
 export { timeAgo } from "./timeAgo.js";
+export { timePeriod } from "./timePeriod.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/core/index.js

@@ -1,3 +1,5 @@
 export { randomId } from "./randomId.js";
 export { generateSecret } from "./generateSecret.js";
 export { timeAgo } from "./timeAgo.js";
+export { timePeriod } from "./timePeriod.js";
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/core/randomId.d.ts

@@ -27,3 +27,4 @@ export interface RandomIdOptions {
  * randomId({ length: 12, safe: true })
  */
 export declare function randomId(options?: RandomIdOptions): string;
+//# sourceMappingURL=randomId.d.ts.map

package/dist/core/randomId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"randomId.d.ts","sourceRoot":"","sources":["../../src/core/randomId.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAQD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,MAAM,CA4B9D"}

package/dist/core/randomId.js

@@ -27,3 +27,4 @@ export function randomId(options = {}) {
     }
     return result;
 }
+//# sourceMappingURL=randomId.js.map

package/dist/core/randomId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"randomId.js","sourceRoot":"","sources":["../../src/core/randomId.ts"],"names":[],"mappings":"AAuBA,MAAM,eAAe,GACnB,gEAAgE,CAAA;AAElE,MAAM,YAAY,GAChB,2DAA2D,CAAA;AAE7D;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,UAA2B,EAAE;IACpD,MAAM,EACJ,MAAM,GAAG,EAAE,EACX,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe,GACxD,GAAG,OAAO,CAAA;IAEX,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;IAC5D,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAA;IAClC,IAAI,MAAM,GAAG,EAAE,CAAA;IAEf,mCAAmC;IACnC,MAAM,SAAS,GACb,OAAO,MAAM,KAAK,WAAW;QAC3B,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,aAAa;YACb,OAAO,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAA;IAEjC,MAAM,YAAY,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAAA;IAC5C,SAAS,CAAC,eAAe,CAAC,YAAY,CAAC,CAAA;IAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAA;IAClD,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/core/timeAgo.d.ts

@@ -7,3 +7,4 @@
  * timeAgo(1700000000000)
  */
 export declare function timeAgo(date: Date | string | number, locale?: string): string;
+//# sourceMappingURL=timeAgo.d.ts.map

package/dist/core/timeAgo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeAgo.d.ts","sourceRoot":"","sources":["../../src/core/timeAgo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAC5B,MAAM,GAAE,MAAa,GACpB,MAAM,CA+BR"}

package/dist/core/timeAgo.js

@@ -32,3 +32,4 @@ export function timeAgo(date, locale = "en") {
     }
     return "just now";
 }
+//# sourceMappingURL=timeAgo.js.map

package/dist/core/timeAgo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeAgo.js","sourceRoot":"","sources":["../../src/core/timeAgo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CACrB,IAA4B,EAC5B,SAAiB,IAAI;IAErB,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAA;IAChC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAA;IAEtB,IAAI,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAA;IAC1C,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,CAAA;IAEhD,IAAI,IAAI,GAAG,IAAI;QAAE,OAAO,UAAU,CAAA;IAElC,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;IAEpE,MAAM,KAAK,GAA4C;QACrD,CAAC,MAAM,EAAE,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC;QACnC,CAAC,OAAO,EAAE,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;QACnC,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;QAC5B,CAAC,MAAM,EAAE,IAAI,GAAG,EAAE,GAAG,EAAE,CAAC;QACxB,CAAC,QAAQ,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,CAAC,QAAQ,EAAE,IAAI,CAAC;KACjB,CAAA;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,EAAE,CAAC,CAAA;QACnC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YACf,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;QACjC,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC"}

package/dist/core/timePeriod.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns the current time period of the day
+ *
+ * @example
+ * timePeriod() // "morning"
+ * timePeriod(new Date("2025-01-01T14:00:00")) // "afternoon"
+ */
+export declare function timePeriod(date?: Date): "morning" | "afternoon" | "evening" | "night";
+//# sourceMappingURL=timePeriod.d.ts.map

package/dist/core/timePeriod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timePeriod.d.ts","sourceRoot":"","sources":["../../src/core/timePeriod.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,IAAiB,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAwBjG"}

package/dist/core/timePeriod.js

@@ -0,0 +1,28 @@
+/**
+ * Returns the current time period of the day
+ *
+ * @example
+ * timePeriod() // "morning"
+ * timePeriod(new Date("2025-01-01T14:00:00")) // "afternoon"
+ */
+export function timePeriod(date = new Date()) {
+    if (!(date instanceof Date) || isNaN(date.getTime())) {
+        throw new Error("timePeriod: invalid date");
+    }
+    const hour = date.getHours();
+    // morning — 5:00 AM to 11:59 AM
+    if (hour >= 5 && hour < 12) {
+        return "morning";
+    }
+    // afternoon — 12:00 PM to 4:59 PM
+    if (hour >= 12 && hour < 17) {
+        return "afternoon";
+    }
+    // evening — 5:00 PM to 8:59 PM
+    if (hour >= 17 && hour < 21) {
+        return "evening";
+    }
+    // night — 9:00 PM to 4:59 AM
+    return "night";
+}
+//# sourceMappingURL=timePeriod.js.map

package/dist/core/timePeriod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timePeriod.js","sourceRoot":"","sources":["../../src/core/timePeriod.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,OAAa,IAAI,IAAI,EAAE;IAChD,IAAI,CAAC,CAAC,IAAI,YAAY,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAA;IAC7C,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAA;IAE5B,gCAAgC;IAChC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,EAAE,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,kCAAkC;IAClC,IAAI,IAAI,IAAI,EAAE,IAAI,IAAI,GAAG,EAAE,EAAE,CAAC;QAC5B,OAAO,WAAW,CAAA;IACpB,CAAC;IAED,+BAA+B;IAC/B,IAAI,IAAI,IAAI,EAAE,IAAI,IAAI,GAAG,EAAE,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,6BAA6B;IAC7B,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/index.d.ts

@@ -1 +1,2 @@
 export * from "./core/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA"}

package/dist/index.js

@@ -1 +1,2 @@
 export * from "./core/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utills",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,6 +11,10 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
   }
 }