@velony/utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VelonY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @velony/utils
+
+A TypeScript utility library providing common helper functions.
+
+## Installation
+
+```bash
+npm install @velony/utils
+```
+
+## Utilities
+
+### Time Conversion
+
+Convert time strings to multiple time units:
+
+```typescript
+import { convertTime } from '@velony/utils';
+
+const result = convertTime("1h30m");
+console.log(result);
+// {
+//   seconds: 5400,
+//   milliseconds: 5400000,
+//   minutes: 90,
+//   hours: 1.5,
+//   days: 0.0625,
+//   weeks: 0.008928571428571428
+// }
+```
+
+### Supported Time Units
+
+- `ms` - Milliseconds
+- `s` - Seconds
+- `m` - Minutes
+- `h` - Hours
+- `d` - Days
+- `w` - Weeks
+
+### Compound Time Strings
+
+You can combine multiple units in a single string:
+
+```typescript
+import { convertTime } from '@velony/utils';
+
+// Complex time duration
+const result = convertTime("2d3h15m30s500ms");
+console.log(result.hours); // 51.258055555555554
+
+// Simple durations
+convertTime("500ms");  // 0.5 seconds
+convertTime("1h");     // 1 hour
+convertTime("1w");     // 1 week = 604800 seconds
+```
+
+### Validation
+
+Check if a string is a valid time format:
+
+```typescript
+import { isTimeString } from '@velony/utils';
+
+isTimeString("1h30m");     // true
+isTimeString("500ms");     // true
+isTimeString("2x");        // false
+isTimeString("");          // false
+isTimeString("1h30m15s");  // true
+```
+
+### Error Handling
+
+The `convertTime` function throws an `InvalidTimeStringError` if the input format is invalid:
+
+```typescript
+import { convertTime, InvalidTimeStringError } from '@velony/utils';
+
+try {
+  convertTime("invalid");
+} catch (error) {
+  if (error instanceof InvalidTimeStringError) {
+    console.error("Invalid time format provided");
+  }
+}
+```
+
+## API Reference
+
+### `convertTime(input: string)`
+
+Converts a valid time string into multiple time units.
+
+**Parameters:**
+- `input: string` - The time string to convert (e.g., `"1h30m"`, `"500ms"`, `"2d3h"`)
+
+**Returns:**
+```typescript
+{
+  seconds: number;
+  milliseconds: number;
+  minutes: number;
+  hours: number;
+  days: number;
+  weeks: number;
+}
+```
+
+**Throws:**
+- `InvalidTimeStringError` - If the input format is invalid
+
+### `isTimeString(input: string): boolean`
+
+Checks if a given string is a valid time format.
+
+**Parameters:**
+- `input: string` - The time string to validate
+
+**Returns:**
+- `boolean` - `true` if the input is valid, otherwise `false`
+
+### `InvalidTimeStringError`
+
+Custom error class thrown when an invalid time string format is provided.
+
+**Extends:** `Error`
+
+## License
+
+MIT
+
+## Repository
+
+[https://github.com/velony-ai/utils](https://github.com/velony-ai/utils)
+
+## Issues
+
+[https://github.com/velony-ai/utils/issues](https://github.com/velony-ai/utils/issues)

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@velony/utils",
+  "version": "1.0.0",
+  "description": "TypeScript utility library providing common helper functions for time conversion and formatting",
+  "keywords": [
+    "utils",
+    "utilities",
+    "typescript",
+    "helper-functions"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velony-ai/utils.git"
+  },
+  "author": "velony-ai",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/velony-ai/utils/issues"
+  },
+  "homepage": "https://github.com/velony-ai/utils#readme",
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-security": "^3.0.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.51.0"
+  }
+}