utills 0.1.2

package/README.md

@@ -0,0 +1,112 @@
+# utils
+
+![thumbmail](./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.  
+It works in both **Node.js** and **browser environments** and follows modern **ESM standards**.
+
+**Check out** 👉 [Docs](https://utills.vercel.app/)
+
+---
+
+## ✨ Features
+
+-   JavaScript & TypeScript compatible
+-   Modern ESM support
+-   Zero external dependencies
+-   Tree-shaking friendly
+-   Browser & Node.js support
+-   Secure (crypto-based utilities)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install utils
+```
+
+# Usage
+
+```bash
+
+import {
+  randomId,
+  timeAgo,
+} from "utils";
+
+randomId();
+timeAgo(Date.now() - 60000);
+```
+
+## Available Utilities
+
+| Method             | Parameters        | Returns  | Description                                                  |
+| ------------------ | ----------------- | -------- | ------------------------------------------------------------ |
+| **randomId**       | `options?`        | `string` | Generates a secure random ID with configurable options.      |
+| **generateSecret** | `length?`         | `string` | Generates a cryptographically secure secret token.           |
+| **timeAgo**        | `date`, `locale?` | `string` | Returns human-readable relative time (e.g. "2 minutes ago"). |
+
+## Contributing
+
+Contributions are welcome and appreciated.
+
+## How to contribute
+
+1: Fork the repository
+Clone your Fork
+
+2: Clone your fork
+
+```bash
+git clone https://github.com/safayet35/utills
+```
+
+3: Create a new branch
+
+```bash
+git checkout -b feature/new-utility
+```
+
+4: Add your utility function inside :
+
+```bash
+src/core/
+```
+
+5: Export it from:
+
+```bash
+src/core/index.ts
+```
+
+6: Build and test
+
+```bash
+npm run build
+```
+
+7: Commit your changes with a clear message
+
+8: Open a Pull Request
+
+## Contribution Guideline
+
+-   One utility per file
+-   No external dependencies
+-   Use native APIs where possible
+-   Handle edge cases properly
+-   Keep code clean and readable
+
+## Roadmap
+
+-   More utility functions
+-   Logging utilities
+-   Optional advanced helpers
+-   Unit tests
+
+## License
+
+MIT License © Safayet Rahman

package/dist/core/generateSecret.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generate a cryptographically secure secret token
+ *
+ * @example
+ * generateSecret()
+ * generateSecret(32)
+ * generateSecret(64)
+ */
+export declare function generateSecret(length?: number): string;

package/dist/core/generateSecret.js

@@ -0,0 +1,27 @@
+/**
+ * Generate a cryptographically secure secret token
+ *
+ * @example
+ * generateSecret()
+ * generateSecret(32)
+ * generateSecret(64)
+ */
+export function generateSecret(length = 32) {
+    if (length <= 0) {
+        throw new Error("generateSecret: length must be greater than 0");
+    }
+    const charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+    const charsetLength = charset.length;
+    // Browser & Node compatible crypto
+    const cryptoObj = typeof crypto !== "undefined"
+        ? crypto
+        : // @ts-ignore
+            require("crypto").webcrypto;
+    const randomValues = new Uint32Array(length);
+    cryptoObj.getRandomValues(randomValues);
+    let secret = "";
+    for (let i = 0; i < length; i++) {
+        secret += charset[randomValues[i] % charsetLength];
+    }
+    return secret;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export { randomId } from "./randomId.js";
+export { generateSecret } from "./generateSecret.js";
+export { timeAgo } from "./timeAgo.js";

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export { randomId } from "./randomId.js";
+export { generateSecret } from "./generateSecret.js";
+export { timeAgo } from "./timeAgo.js";

package/dist/core/randomId.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Options for randomId generator
+ */
+export interface RandomIdOptions {
+    /**
+     * Length of the generated ID
+     * @default 16
+     */
+    length?: number;
+    /**
+     * Custom characters to use
+     * @default alphanumeric (a-zA-Z0-9)
+     */
+    charset?: string;
+    /**
+     * If true, removes visually confusing characters (0, O, l, I)
+     * @default false
+     */
+    safe?: boolean;
+}
+/**
+ * Generate a secure random ID
+ *
+ * @example
+ * randomId()
+ * randomId({ length: 10 })
+ * randomId({ length: 12, safe: true })
+ */
+export declare function randomId(options?: RandomIdOptions): string;

package/dist/core/randomId.js

@@ -0,0 +1,29 @@
+const DEFAULT_CHARSET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+const SAFE_CHARSET = "abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+/**
+ * Generate a secure random ID
+ *
+ * @example
+ * randomId()
+ * randomId({ length: 10 })
+ * randomId({ length: 12, safe: true })
+ */
+export function randomId(options = {}) {
+    const { length = 16, charset = options.safe ? SAFE_CHARSET : DEFAULT_CHARSET, } = options;
+    if (length <= 0) {
+        throw new Error("randomId: length must be greater than 0");
+    }
+    const charsLength = charset.length;
+    let result = "";
+    // Browser & Node compatible crypto
+    const cryptoObj = typeof crypto !== "undefined"
+        ? crypto
+        : // @ts-ignore
+            require("crypto").webcrypto;
+    const randomValues = new Uint32Array(length);
+    cryptoObj.getRandomValues(randomValues);
+    for (let i = 0; i < length; i++) {
+        result += charset[randomValues[i] % charsLength];
+    }
+    return result;
+}

package/dist/core/timeAgo.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns human readable relative time
+ *
+ * @example
+ * timeAgo(new Date())
+ * timeAgo("2025-01-01")
+ * timeAgo(1700000000000)
+ */
+export declare function timeAgo(date: Date | string | number, locale?: string): string;

package/dist/core/timeAgo.js

@@ -0,0 +1,34 @@
+/**
+ * Returns human readable relative time
+ *
+ * @example
+ * timeAgo(new Date())
+ * timeAgo("2025-01-01")
+ * timeAgo(1700000000000)
+ */
+export function timeAgo(date, locale = "en") {
+    const inputDate = new Date(date);
+    const now = new Date();
+    if (isNaN(inputDate.getTime())) {
+        throw new Error("timeAgo: invalid date");
+    }
+    const diff = now.getTime() - inputDate.getTime();
+    if (diff < 1000)
+        return "just now";
+    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+    const units = [
+        ["year", 1000 * 60 * 60 * 24 * 365],
+        ["month", 1000 * 60 * 60 * 24 * 30],
+        ["day", 1000 * 60 * 60 * 24],
+        ["hour", 1000 * 60 * 60],
+        ["minute", 1000 * 60],
+        ["second", 1000],
+    ];
+    for (const [unit, ms] of units) {
+        const value = Math.floor(diff / ms);
+        if (value >= 1) {
+            return rtf.format(-value, unit);
+        }
+    }
+    return "just now";
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./core/index.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./core/index.js";

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "utills",
+  "version": "0.1.2",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  }
+}