@synnaxlabs/x 0.52.3 → 0.52.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synnaxlabs/x",
-  "version": "0.52.3",
+  "version": "0.52.4",
   "type": "module",
   "description": "Common Utilities for Synnax Labs",
   "repository": "https://github.com/synnaxlabs/synnax/tree/main/x/ts",

package/src/telem/telem.spec.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { describe, expect, it, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, test } from "vitest";
 
 import { binary } from "@/binary";
 import {
@@ -727,6 +727,122 @@ describe("TimeStamp", () => {
       const diff = Math.abs(Number(roundTrip.valueOf() - ts.valueOf()));
       expect(diff).toBeLessThan(1000000000); // Less than 1 second in nanoseconds
     });
+
+    describe("timezone sensitive", () => {
+      let originalTZ: string | undefined;
+      beforeEach(() => {
+        originalTZ = process.env.TZ;
+        process.env.TZ = "Pacific/Auckland";
+      });
+      afterEach(() => {
+        process.env.TZ = originalTZ;
+      });
+
+      test("localYear", () => {
+        // 2022-12-31T23:00:00Z -> Auckland (UTC+13): 2023-01-01T12:00:00
+        const ts = new TimeStamp(Date.UTC(2022, 11, 31, 23, 0, 0, 0) * 1e6);
+        expect(ts.year).toEqual(2022);
+        expect(ts.localYear).toEqual(2023);
+      });
+
+      test("setLocalYear", () => {
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 10, 30, 20, 0) * 1e6);
+        const updated = ts.setLocalYear(2025);
+        expect(updated.localYear).toEqual(2025);
+        expect(updated.localMonth).toEqual(ts.localMonth);
+        expect(updated.localDay).toEqual(ts.localDay);
+        expect(updated.localHour).toEqual(ts.localHour);
+      });
+
+      test("localMonth", () => {
+        // 2022-06-30T23:00:00Z -> Auckland (UTC+12): 2022-07-01T11:00:00
+        const ts = new TimeStamp(Date.UTC(2022, 5, 30, 23, 0, 0, 0) * 1e6);
+        expect(ts.month).toEqual(5); // June (0-indexed)
+        expect(ts.localMonth).toEqual(6); // July (0-indexed)
+      });
+
+      test("setLocalMonth", () => {
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 10, 30, 0, 0) * 1e6);
+        const updated = ts.setLocalMonth(11);
+        expect(updated.localMonth).toEqual(11);
+        expect(updated.localDay).toEqual(ts.localDay);
+        expect(updated.localHour).toEqual(ts.localHour);
+      });
+
+      test("localDay", () => {
+        // 2022-06-15T23:00:00Z -> Auckland (UTC+12): 2022-06-16T11:00:00
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 23, 0, 0, 0) * 1e6);
+        expect(ts.day).toEqual(15);
+        expect(ts.localDay).toEqual(16);
+      });
+
+      test("setLocalDay", () => {
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 10, 30, 0, 0) * 1e6);
+        const updated = ts.setLocalDay(25);
+        expect(updated.localDay).toEqual(25);
+        expect(updated.localMonth).toEqual(ts.localMonth);
+        expect(updated.localHour).toEqual(ts.localHour);
+      });
+
+      test("localMinute", () => {
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 10, 30, 0, 0) * 1e6);
+        expect(ts.localMinute).toEqual(ts.date().getMinutes());
+      });
+
+      test("setLocalMinute", () => {
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 10, 0, 0, 0) * 1e6);
+        const updated = ts.setLocalMinute(45);
+        expect(updated.localMinute).toEqual(45);
+        expect(updated.localHour).toEqual(ts.localHour);
+        expect(updated.localSecond).toEqual(ts.localSecond);
+      });
+
+      test("localSecond", () => {
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 10, 0, 42, 0) * 1e6);
+        expect(ts.localSecond).toEqual(ts.date().getSeconds());
+      });
+
+      test("setLocalSecond", () => {
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 10, 0, 0, 0) * 1e6);
+        const updated = ts.setLocalSecond(30);
+        expect(updated.localSecond).toEqual(30);
+        expect(updated.localMinute).toEqual(ts.localMinute);
+        expect(updated.localHour).toEqual(ts.localHour);
+      });
+
+      test("localMillisecond", () => {
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 10, 0, 0, 500) * 1e6);
+        expect(ts.localMillisecond).toEqual(ts.date().getMilliseconds());
+      });
+
+      test("setLocalMillisecond", () => {
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 10, 0, 0, 0) * 1e6);
+        const updated = ts.setLocalMillisecond(750);
+        expect(updated.localMillisecond).toEqual(750);
+        expect(updated.localSecond).toEqual(ts.localSecond);
+        expect(updated.localHour).toEqual(ts.localHour);
+      });
+
+      test("local getters and setters round trip", () => {
+        const ts = new TimeStamp(Date.UTC(2022, 5, 15, 10, 30, 20, 500) * 1e6);
+        const roundTrip = ts
+          .setLocalYear(ts.localYear)
+          .setLocalMonth(ts.localMonth)
+          .setLocalDay(ts.localDay)
+          .setLocalHour(ts.localHour)
+          .setLocalMinute(ts.localMinute)
+          .setLocalSecond(ts.localSecond)
+          .setLocalMillisecond(ts.localMillisecond);
+
+        expect(roundTrip.localYear).toEqual(ts.localYear);
+        expect(roundTrip.localMonth).toEqual(ts.localMonth);
+        expect(roundTrip.localDay).toEqual(ts.localDay);
+        expect(roundTrip.localHour).toEqual(ts.localHour);
+        expect(roundTrip.localMinute).toEqual(ts.localMinute);
+        expect(roundTrip.localSecond).toEqual(ts.localSecond);
+        expect(roundTrip.localMillisecond).toEqual(ts.localMillisecond);
+      });
+    });
   });
 
   describe("remainder", () => {

package/src/telem/telem.ts

@@ -398,13 +398,18 @@ export class TimeStamp
     return Number(this.valueOf());
   }
 
-  /** @returns the integer year that the timestamp corresponds to. */
+  /** @returns the integer year that the timestamp corresponds to in UTC. */
   get year(): number {
     return this.date().getUTCFullYear();
   }
 
+  /** @returns the integer year that the timestamp corresponds to in local time. */
+  get localYear(): number {
+    return this.date().getFullYear();
+  }
+
   /**
-   * @returns a copy of the timestamp with the year changed.
+   * @returns a copy of the timestamp with the year changed in UTC.
    * @param year the value to set the year to.
    */
   setYear(year: number): TimeStamp {
@@ -413,13 +418,30 @@ export class TimeStamp
     return new TimeStamp(d);
   }
 
-  /** @returns the integer month that the timestamp corresponds to with its year. */
+  /**
+   * @returns a copy of the timestamp with the year changed in local time.
+   * @param year the value to set the year to.
+   */
+  setLocalYear(year: number): TimeStamp {
+    const d = this.date();
+    d.setFullYear(year);
+    return new TimeStamp(d);
+  }
+
+  /** @returns the integer month that the timestamp corresponds to within its year in
+   * UTC. */
   get month(): number {
     return this.date().getUTCMonth();
   }
 
+  /** @returns the integer month that the timestamp corresponds to within its year in
+   * local time. */
+  get localMonth(): number {
+    return this.date().getMonth();
+  }
+
   /**
-   * @returns a copy of the timestamp with the month changed.
+   * @returns a copy of the timestamp with the month changed in UTC.
    * @param month the value to set the month to.
    */
   setMonth(month: number): TimeStamp {
@@ -428,13 +450,30 @@ export class TimeStamp
     return new TimeStamp(d);
   }
 
-  /** @returns the integer day that the timestamp corresponds to within its month. */
+  /**
+   * @returns a copy of the timestamp with the month changed in local time.
+   * @param month the value to set the month to.
+   */
+  setLocalMonth(month: number): TimeStamp {
+    const d = this.date();
+    d.setMonth(month);
+    return new TimeStamp(d);
+  }
+
+  /** @returns the integer day that the timestamp corresponds to within its month in
+   * UTC. */
   get day(): number {
     return this.date().getUTCDate();
   }
 
+  /** @returns the integer day that the timestamp corresponds to within its month in
+   * local time. */
+  get localDay(): number {
+    return this.date().getDate();
+  }
+
   /**
-   * @returns a copy of the timestamp with the day changed.
+   * @returns a copy of the timestamp with the day changed in UTC.
    * @param day the value the set the day to.
    */
   setDay(day: number): TimeStamp {
@@ -443,6 +482,16 @@ export class TimeStamp
     return new TimeStamp(d);
   }
 
+  /**
+   * @returns a copy of the timestamp with the day changed in local time.
+   * @param day the value to set the day to.
+   */
+  setLocalDay(day: number): TimeStamp {
+    const d = this.date();
+    d.setDate(day);
+    return new TimeStamp(d);
+  }
+
   /**
    * @returns the integer hour that the timestamp corresponds to within its day.
    */
@@ -451,7 +500,8 @@ export class TimeStamp
   }
 
   /**
-   * @returns the integer hour that the timestamp corresponds to within its day in local time.
+   * @returns the integer hour that the timestamp corresponds to within its day in local
+   * time.
    */
   get localHour(): number {
     return this.date().getHours();
@@ -477,13 +527,20 @@ export class TimeStamp
     return new TimeStamp(d);
   }
 
-  /** @returns the integer minute that the timestamp corresponds to within its hour. */
+  /** @returns the integer minute that the timestamp corresponds to within its hour in
+   * UTC. */
   get minute(): number {
     return this.date().getUTCMinutes();
   }
 
+  /** @returns the integer minute that the timestamp corresponds to within its hour in
+   * local time. */
+  get localMinute(): number {
+    return this.date().getMinutes();
+  }
+
   /**
-   * @returns a copy of the timestamp with the minute changed.
+   * @returns a copy of the timestamp with the minute changed in UTC.
    * @param minute the value to set the minute to.
    */
   setMinute(minute: number): TimeStamp {
@@ -492,16 +549,34 @@ export class TimeStamp
     return new TimeStamp(d);
   }
 
+  /**
+   * @returns a copy of the timestamp with the minute changed in local time.
+   * @param minute the value to set the minute to.
+   */
+  setLocalMinute(minute: number): TimeStamp {
+    const d = this.date();
+    d.setMinutes(minute);
+    return new TimeStamp(d);
+  }
+
   /**
    * @returns the integer second that the timestamp corresponds to within its
-   * minute.
+   * minute in UTC.
    */
   get second(): number {
     return this.date().getUTCSeconds();
   }
 
   /**
-   * @returns a copy of the timestamp with the second changed.
+   * @returns the integer second that the timestamp corresponds to within its minute in
+   * local time.
+   */
+  get localSecond(): number {
+    return this.date().getSeconds();
+  }
+
+  /**
+   * @returns a copy of the timestamp with the second changed in UTC.
    * @param second the value to set the second to.
    */
   setSecond(second: number): TimeStamp {
@@ -510,16 +585,34 @@ export class TimeStamp
     return new TimeStamp(d);
   }
 
+  /**
+   * @returns a copy of the timestamp with the second changed in local time.
+   * @param second the value to set the second to.
+   */
+  setLocalSecond(second: number): TimeStamp {
+    const d = this.date();
+    d.setSeconds(second);
+    return new TimeStamp(d);
+  }
+
   /**
    * @returns the integer millisecond that the timestamp corresponds to within its
-   * second.
+   * second in UTC.
    */
   get millisecond(): number {
     return this.date().getUTCMilliseconds();
   }
 
   /**
-   * @returns a copy of the timestamp with the milliseconds changed.
+   * @returns the integer millisecond that the timestamp corresponds to within its
+   * second in local time.
+   */
+  get localMillisecond(): number {
+    return this.date().getMilliseconds();
+  }
+
+  /**
+   * @returns a copy of the timestamp with the milliseconds changed in UTC.
    * @param millisecond the value to set the millisecond to.
    */
   setMillisecond(millisecond: number): TimeStamp {
@@ -528,6 +621,16 @@ export class TimeStamp
     return new TimeStamp(d);
   }
 
+  /**
+   * @returns a copy of the timestamp with the milliseconds changed in local time.
+   * @param millisecond the value to set the millisecond to.
+   */
+  setLocalMillisecond(millisecond: number): TimeStamp {
+    const d = this.date();
+    d.setMilliseconds(millisecond);
+    return new TimeStamp(d);
+  }
+
   /**
    * Returns a string representation of the TimeStamp.
    *