From 25bd6b8c61ca9dbefdc81a3039892f65ced46d0c Mon Sep 17 00:00:00 2001
From: Mehran <behroziyan.mhrn@gmail.com>
Date: Thu, 19 Sep 2024 22:15:37 +0330
Subject: [PATCH] feat(docs): add mdx file for secondsToTime function

---
 docs/pages/function/seconds-to-time.mdx | 85 +++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 docs/pages/function/seconds-to-time.mdx

diff --git a/docs/pages/function/seconds-to-time.mdx b/docs/pages/function/seconds-to-time.mdx
new file mode 100644
index 00000000..e71b7625
--- /dev/null
+++ b/docs/pages/function/seconds-to-time.mdx
@@ -0,0 +1,85 @@
+# secondsToTime
+
+Formats a number of seconds into a string representation based on a specified format.
+
+
+### Import
+
+```typescript copy
+import { secondsToTime } from '@fullstacksjs/toolbox';
+```
+
+### Signature
+
+```typescript copy
+function secondsToTime({
+  sec,
+  format,
+}: {
+  sec: number;
+  format: 'hh:mm:ss' | 'hh:mm' | 'mm:ss';
+}): string;
+```
+
+### Examples
+
+```typescript copy
+sleep(1000).then(() => console.log("Hi")) // Logs hi after 1 second
+await sleep(1000); console.log("Hi")      // Logs hi after 1 second
+```
+
+
+## Import
+
+```typescript copy
+import { secondsToTime } from './secondsToTime';
+```
+
+## Signature
+
+```typescript
+function secondsToTime({
+  sec,
+  format,
+}: {
+  sec: number;
+  format: 'hh:mm:ss' | 'hh:mm' | 'mm:ss';
+}): string;
+```
+
+## Parameters
+
+- **`sec`** (`number`): The total number of seconds to be converted.
+- **`format`** (`'hh:mm:ss' | 'hh:mm' | 'mm:ss'`): The desired output format.
+
+## Returns
+
+- **`string`**: The formatted time string based on the specified format.
+
+## Examples
+
+### Formatting to `hh:mm:ss`
+
+```typescript
+const time1 = secondsToTime({ sec: 3661, format: 'hh:mm:ss' });
+// Output: '01:01:01'
+```
+
+### Formatting Zero Seconds
+
+```typescript
+const time4 = secondsToTime({ sec: 0, format: 'mm:ss' });
+// Output: '00:00'
+```
+
+## Error Handling
+
+If an invalid format is provided, the function will throw an error:
+
+```typescript
+try {
+  secondsToTime({ sec: 120, format: 'ss:ss:ss' });
+} catch (e) {
+  console.error(e.message); // 'Invalid format: 'ss:ss:ss'. Accepted formats are 'hh:mm:ss', 'hh:mm', or 'mm:ss'.'
+}
+```