From a5a12d4c6dc580ccdd0cbae722310416e14742c7 Mon Sep 17 00:00:00 2001
From: "planetrenox@protonmail.com" <planetrenox@protonmail.com>
Date: Mon, 19 Oct 2026 19:53:28 +0000
Subject: [PATCH] Add JSDoc hints for every function and unit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 index.d.ts   | 80 ++++++++++++++++++++++++++++++++++++++++++++++++----
 package.json |  2 +-
 2 files changed, 75 insertions(+), 7 deletions(-)

diff --git a/index.d.ts b/index.d.ts
index 85cf787..901e669 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -1,16 +1,84 @@
-/** PRT units: milliseconds (official), seconds, minutes, hours, days, weeks */
+/**
+ * PRT unit:
+ * - `'ms'` milliseconds (official PRT unit)
+ * - `'s'` seconds
+ * - `'m'` minutes
+ * - `'h'` hours
+ * - `'d'` days, always 86,400,000 ms
+ * - `'w'` weeks, always 7 days
+ */
 export type Unit = 'ms' | 's' | 'm' | 'h' | 'd' | 'w'
 
+/**
+ * PRT (Planet Renox Time): milliseconds since `1998-03-14T03:00:00.000Z`.
+ *
+ * - Results are integers, rounded down toward −∞ (`1.5s → 1`, `-1.5s → -2`).
+ * - Times before the epoch are negative.
+ * - Exact across the full JS `Date` range (±275,000 years). Outside it throws.
+ * - Leap seconds are ignored, the same as JS `Date`.
+ */
 export declare const PRT: Readonly<{
-  /** Current PRT, rounded down. Defaults to ms. */
+  /**
+   * Current PRT.
+   * @param unit Unit to return. Default `'ms'`.
+   * @returns Integer PRT, rounded down.
+   * @throws {RangeError} Unknown unit.
+   * @example
+   * PRT.now()     // ms
+   * PRT.now('d')  // days
+   */
   now(unit?: Unit): number
-  /** PRT at the given Date, rounded down. Defaults to ms. */
+
+  /**
+   * PRT at a `Date`.
+   * @param date A valid `Date`. Anything else throws, including numbers.
+   * @param unit Unit to return. Default `'ms'`.
+   * @returns Integer PRT, rounded down.
+   * @throws {TypeError} `date` is not a valid `Date`.
+   * @throws {RangeError} Unknown unit.
+   * @example
+   * PRT.fromDate(new Date('1998-03-14T03:00:00Z'))   // 0
+   * PRT.fromDate(new Date('2010-06-01'), 'd')        // 4461
+   */
   fromDate(date: Date, unit?: Unit): number
-  /** Date at the given integer PRT value. Defaults to ms. */
+
+  /**
+   * `Date` at a PRT value.
+   * @param value Integer PRT, in `unit`.
+   * @param unit Unit of `value`. Default `'ms'`.
+   * @returns The `Date` at the start of that PRT `unit`.
+   * @throws {TypeError} `value` is not a safe integer.
+   * @throws {RangeError} Unknown unit, or result is outside the `Date` range.
+   * @example
+   * PRT.toDate(0)          // 1998-03-14T03:00:00.000Z
+   * PRT.toDate(1e9, 's')   // 2029-11-20T04:46:40.000Z
+   */
   toDate(value: number, unit?: Unit): Date
-  /** PRT at the given integer Unix ms, rounded down. Defaults to ms. */
+
+  /**
+   * PRT at a Unix timestamp in milliseconds, like `Date.now()`. Not Unix seconds.
+   * @param unixMs Integer Unix ms, within the `Date` range.
+   * @param unit Unit to return. Default `'ms'`.
+   * @returns Integer PRT, rounded down.
+   * @throws {TypeError} `unixMs` is not an integer.
+   * @throws {RangeError} Unknown unit, or `unixMs` is outside the `Date` range.
+   * @example
+   * PRT.fromUnixMs(889844400000)   // 0
+   * PRT.fromUnixMs(0, 'd')         // -10300
+   */
   fromUnixMs(unixMs: number, unit?: Unit): number
-  /** Unix ms at the given integer PRT value. Defaults to ms. */
+
+  /**
+   * Unix timestamp in milliseconds at a PRT value. Same as `PRT.toDate(value, unit).getTime()`.
+   * @param value Integer PRT, in `unit`.
+   * @param unit Unit of `value`. Default `'ms'`.
+   * @returns Integer Unix ms at the start of that PRT `unit`.
+   * @throws {TypeError} `value` is not a safe integer.
+   * @throws {RangeError} Unknown unit, or result is outside the `Date` range.
+   * @example
+   * PRT.toUnixMs(0)        // 889844400000
+   * PRT.toUnixMs(1, 'w')   // 890449200000
+   */
   toUnixMs(value: number, unit?: Unit): number
 }>
 
diff --git a/package.json b/package.json
index 9493074..c12aa22 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ortus",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "PRT (Planet Renox Time): milliseconds since 1998-03-14T03:00:00Z",
   "type": "module",
   "exports": {