@synnaxlabs/x 0.47.0 → 0.49.0

package/src/spatial/xy/xy.spec.ts

@@ -268,4 +268,59 @@ describe("XY", () => {
       expect(result).toEqual({ x: 7, y: 17 });
     });
   });
+
+  describe("set", () => {
+    it("should set x coordinate to target value", () => {
+      expect(xy.set([5, 10], "x", 20)).toEqual({ x: 20, y: 10 });
+    });
+
+    it("should set y coordinate to target value", () => {
+      expect(xy.set([5, 10], "y", 20)).toEqual({ x: 5, y: 20 });
+    });
+
+    it("should accept crude directions like locations", () => {
+      expect(xy.set([5, 10], "left", 20)).toEqual({ x: 20, y: 10 });
+      expect(xy.set([5, 10], "right", 20)).toEqual({ x: 20, y: 10 });
+      expect(xy.set([5, 10], "top", 20)).toEqual({ x: 5, y: 20 });
+      expect(xy.set([5, 10], "bottom", 20)).toEqual({ x: 5, y: 20 });
+    });
+
+    it("should work with different coordinate input formats", () => {
+      expect(xy.set({ width: 5, height: 10 }, "x", 15)).toEqual({ x: 15, y: 10 });
+      expect(xy.set({ x: 3, y: 4 }, "y", 8)).toEqual({ x: 3, y: 8 });
+    });
+  });
+
+  describe("rotate", () => {
+    it("should rotate a point 90 degrees clockwise around the origin", () => {
+      const point = { x: 1, y: 0 };
+      const center = { x: 0, y: 0 };
+      const result = xy.rotate(point, center, "clockwise");
+      expect(result.x).toBeCloseTo(0);
+      expect(result.y).toBeCloseTo(1);
+    });
+
+    it("should rotate a point 90 degrees counterclockwise around the origin", () => {
+      const point = { x: 1, y: 0 };
+      const center = { x: 0, y: 0 };
+      const result = xy.rotate(point, center, "counterclockwise");
+      expect(result.x).toBeCloseTo(0);
+      expect(result.y).toBeCloseTo(-1);
+    });
+
+    it("should rotate a point around a non-origin center", () => {
+      const point = { x: 2, y: 1 };
+      const center = { x: 1, y: 1 };
+      const result = xy.rotate(point, center, "clockwise");
+      expect(result.x).toBeCloseTo(1);
+      expect(result.y).toBeCloseTo(2);
+    });
+
+    it("should return the same point when rotating around itself", () => {
+      const point = { x: 5, y: 5 };
+      const result = xy.rotate(point, point, "clockwise");
+      expect(result.x).toBeCloseTo(5);
+      expect(result.y).toBeCloseTo(5);
+    });
+  });
 });

package/src/spatial/xy/xy.ts

@@ -10,8 +10,10 @@
 import { z } from "zod";
 
 import {
+  type AngularDirection,
   type ClientXY,
   clientXY,
+  type CrudeDirection,
   dimensions,
   type Direction,
   type NumberCouple,
@@ -20,6 +22,7 @@ import {
   type XY,
   xy,
 } from "@/spatial/base";
+import { direction as dir } from "@/spatial/direction";
 import { type location } from "@/spatial/location";
 
 export { type ClientXY as Client, clientXY, type XY, xy };
@@ -139,9 +142,10 @@ export const translate: Translate = (a, b, v, ...cb): XY => {
  * @returns the given coordinate the given direction set to the given value.
  * @example set({ x: 1, y: 2 }, "x", 3) // { x: 3, y: 2 }
  */
-export const set = (c: Crude, direction: Direction, value: number): XY => {
+export const set = (c: Crude, direction: CrudeDirection, value: number): XY => {
   const xy = construct(c);
-  if (direction === "x") return { x: value, y: xy.y };
+  const d = dir.construct(direction);
+  if (d === "x") return { x: value, y: xy.y };
   return { x: xy.x, y: value };
 };
 
@@ -328,3 +332,24 @@ export const reciprocal = (a: Crude): XY => {
   const xy = construct(a);
   return { x: 1 / xy.x, y: 1 / xy.y };
 };
+
+/**
+ * Rotates a point 90 degrees around a center point.
+ * @param point - The point to rotate.
+ * @param center - The center point to rotate around.
+ * @param dir - The direction to rotate (clockwise or counterclockwise).
+ * @returns The rotated point.
+ */
+export const rotate = (point: Crude, center: Crude, dir: AngularDirection): XY => {
+  const p = construct(point);
+  const c = construct(center);
+  const angle = dir === "clockwise" ? Math.PI / 2 : -Math.PI / 2;
+  const relativeX = p.x - c.x;
+  const relativeY = p.y - c.y;
+  const rotatedX = relativeX * Math.cos(angle) - relativeY * Math.sin(angle);
+  const rotatedY = relativeX * Math.sin(angle) + relativeY * Math.cos(angle);
+  return {
+    x: rotatedX + c.x,
+    y: rotatedY + c.y,
+  };
+};

package/src/status/status.ts

@@ -12,7 +12,7 @@ import { z } from "zod";
 import { array } from "@/array";
 import { id } from "@/id";
 import { label } from "@/label";
-import { type Optional } from "@/optional";
+import { type optional } from "@/optional";
 import { TimeStamp } from "@/telem";
 
 export const variantZ = z.enum([
@@ -75,10 +75,10 @@ type Base<V extends Variant> = {
 export type Status<DetailsSchema = z.ZodNever, V extends Variant = Variant> = Base<V> &
   ([DetailsSchema] extends [z.ZodNever] ? {} : { details: z.output<DetailsSchema> });
 
-export type Crude<DetailsSchema = z.ZodNever, V extends Variant = Variant> = Optional<
-  Base<V>,
-  "key" | "time" | "name"
-> &
+export type Crude<
+  DetailsSchema = z.ZodNever,
+  V extends Variant = Variant,
+> = optional.Optional<Base<V>, "key" | "time" | "name"> &
   ([DetailsSchema] extends [z.ZodNever] ? {} : { details: z.output<DetailsSchema> });
 
 export const exceptionDetailsSchema = z.object({

package/src/telem/series.ts

@@ -14,7 +14,7 @@ import { caseconv } from "@/caseconv";
 import { compare } from "@/compare";
 import { id } from "@/id";
 import { instance } from "@/instance";
-import { type math } from "@/math";
+import { math } from "@/math";
 import { bounds } from "@/spatial";
 import {
   type GLBufferController,
@@ -22,7 +22,6 @@ import {
   glBufferUsageZ,
 } from "@/telem/gl";
 import {
-  addSamples,
   convertDataType,
   type CrudeDataType,
   type CrudeTimeStamp,
@@ -200,7 +199,7 @@ export class Series<T extends TelemValue = TelemValue>
       z.instanceof(ArrayBuffer),
       z.instanceof(Uint8Array),
     ]),
-    glBufferUsage: glBufferUsageZ.optional().default("static").optional(),
+    glBufferUsage: glBufferUsageZ.default("static").optional(),
   });
 
   /**
@@ -635,7 +634,7 @@ export class Series<T extends TelemValue = TelemValue>
       throw new Error("cannot calculate maximum on a variable length data type");
     if (this.writePos === 0) return -Infinity;
     this.cachedMax ??= this.calcRawMax();
-    return addSamples(this.cachedMax, this.sampleOffset);
+    return math.add(this.cachedMax, this.sampleOffset);
   }
 
   private calcRawMin(): math.Numeric {
@@ -661,7 +660,7 @@ export class Series<T extends TelemValue = TelemValue>
       throw new Error("cannot calculate minimum on a variable length data type");
     if (this.writePos === 0) return Infinity;
     this.cachedMin ??= this.calcRawMin();
-    return addSamples(this.cachedMin, this.sampleOffset);
+    return math.add(this.cachedMin, this.sampleOffset);
   }
 
   /** @returns the bounds of the series. */
@@ -726,7 +725,7 @@ export class Series<T extends TelemValue = TelemValue>
       if (required === true) throw new Error(`[series] - no value at index ${index}`);
       return undefined;
     }
-    return addSamples(v, this.sampleOffset) as T;
+    return math.add(v, this.sampleOffset) as T;
   }
 
   private atUUID(index: number, required: boolean): string | undefined {

package/src/telem/telem.spec.ts

@@ -11,7 +11,6 @@ import { describe, expect, it, test } from "vitest";
 
 import { binary } from "@/binary";
 import {
-  addSamples,
   type CrudeDataType,
   DataType,
   Density,
@@ -98,6 +97,55 @@ describe("TimeStamp", () => {
     ).toBe(true);
   });
 
+  describe("datetime-local format parsing", () => {
+    test("should parse as UTC by default", () => {
+      const ts = new TimeStamp("2025-11-03T17:44:45.500");
+      const utcTS = new TimeStamp("2025-11-03T17:44:45.500Z");
+
+      expect(ts.valueOf()).toEqual(utcTS.valueOf());
+    });
+
+    test("should handle 1-digit milliseconds with default UTC", () => {
+      const ts = new TimeStamp("2025-11-03T17:44:45.5");
+      expect(ts.millisecond).toBe(500);
+    });
+
+    test("should handle 1-digit milliseconds with local", () => {
+      const ts = new TimeStamp("2025-11-03T17:44:45.5", "local");
+      expect(ts.millisecond).toBe(500);
+    });
+
+    test("should handle 2-digit milliseconds", () => {
+      const ts = new TimeStamp("2025-11-03T17:44:45.50");
+      expect(ts.millisecond).toBe(500);
+    });
+
+    test("should handle 3-digit milliseconds", () => {
+      const ts = new TimeStamp("2025-11-03T17:44:45.809");
+      expect(ts.millisecond).toBe(809);
+    });
+
+    test("should handle 810 milliseconds", () => {
+      const ts = new TimeStamp("2025-11-03T17:44:45.810");
+      expect(ts.millisecond).toBeGreaterThanOrEqual(809);
+      expect(ts.millisecond).toBeLessThanOrEqual(810);
+    });
+
+    test("should handle datetime without milliseconds", () => {
+      const ts = new TimeStamp("2025-11-03T17:44:45");
+      expect(ts.millisecond).toBe(0);
+    });
+
+    test("should round-trip when using local tzInfo", () => {
+      const input = "2025-11-03T17:44:45.809";
+      const ts1 = new TimeStamp(input, "local");
+      const output = ts1.toString("ISO", "local").slice(0, -1);
+      const ts2 = new TimeStamp(output, "local");
+
+      expect(ts1.valueOf()).toEqual(ts2.valueOf());
+    });
+  });
+
   test("construct from date", () => {
     const ts = new TimeStamp([2021, 1, 1], "UTC");
     expect(ts.date().getUTCFullYear()).toEqual(2021);
@@ -734,6 +782,44 @@ describe("TimeStamp", () => {
       });
     });
   });
+
+  describe("formatBySpan", () => {
+    test("should return 'shortDate' for spans >= 30 days", () => {
+      const ts = new TimeStamp([2022, 12, 15], "UTC");
+      const span = TimeSpan.days(30);
+      expect(ts.formatBySpan(span)).toBe("shortDate");
+    });
+
+    test("should return 'dateTime' for spans >= 1 day", () => {
+      const ts = new TimeStamp([2022, 12, 15], "UTC");
+      const span = TimeSpan.days(1);
+      expect(ts.formatBySpan(span)).toBe("dateTime");
+    });
+
+    test("should return 'time' for spans >= 1 hour", () => {
+      const ts = new TimeStamp([2022, 12, 15], "UTC");
+      const span = TimeSpan.hours(1);
+      expect(ts.formatBySpan(span)).toBe("time");
+    });
+
+    test("should return 'preciseTime' for spans >= 1 second", () => {
+      const ts = new TimeStamp([2022, 12, 15], "UTC");
+      const span = TimeSpan.seconds(1);
+      expect(ts.formatBySpan(span)).toBe("preciseTime");
+    });
+
+    test("should return 'ISOTime' for spans < 1 second", () => {
+      const ts = new TimeStamp([2022, 12, 15], "UTC");
+      const span = TimeSpan.milliseconds(500);
+      expect(ts.formatBySpan(span)).toBe("ISOTime");
+    });
+
+    test("should work with very small spans", () => {
+      const ts = new TimeStamp([2022, 12, 15], "UTC");
+      const span = TimeSpan.microseconds(100);
+      expect(ts.formatBySpan(span)).toBe("ISOTime");
+    });
+  });
 });
 
 describe("TimeSpan", () => {
@@ -1935,30 +2021,3 @@ describe("Size", () => {
     });
   });
 });
-
-describe("addSamples", () => {
-  test("adds two numbers", () => {
-    expect(addSamples(1, 2)).toBe(3);
-    expect(addSamples(1.5, 2.5)).toBe(4);
-    expect(addSamples(-1, 1)).toBe(0);
-  });
-
-  test("adds two bigints", () => {
-    expect(addSamples(1n, 2n)).toBe(3n);
-    expect(addSamples(-1n, 1n)).toBe(0n);
-    expect(addSamples(9007199254740991n, 1n)).toBe(9007199254740992n);
-  });
-
-  test("handles mixed numeric types", () => {
-    expect(addSamples(1, 2n)).toBe(3);
-    expect(addSamples(2n, 1)).toBe(3);
-    expect(addSamples(1.5, 2n)).toBe(3.5);
-    expect(addSamples(2n, 1.5)).toBe(3.5);
-  });
-
-  test("handles edge cases", () => {
-    expect(addSamples(0, 0)).toBe(0);
-    expect(addSamples(Number.MAX_SAFE_INTEGER, 1)).toBe(Number.MAX_SAFE_INTEGER + 1);
-    expect(addSamples(Number.MIN_SAFE_INTEGER, -1)).toBe(Number.MIN_SAFE_INTEGER - 1);
-  });
-});

package/src/telem/telem.ts

@@ -154,6 +154,32 @@ export class TimeStamp
   private static parseDateTimeString(str: string, tzInfo: TZInfo = "UTC"): bigint {
     if (!str.includes("/") && !str.includes("-"))
       return TimeStamp.parseTimeString(str, tzInfo);
+
+    const isDateTimeLocal =
+      str.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?$/) != null;
+
+    if (isDateTimeLocal) {
+      let datePart = str;
+      let ms = 0;
+
+      if (str.includes(".")) {
+        const parts = str.split(".");
+        datePart = parts[0];
+        const msPart = parts[1] || "0";
+        ms = parseInt(msPart.padEnd(3, "0").slice(0, 3));
+      }
+
+      const d =
+        tzInfo === "local"
+          ? new Date(datePart.replace("T", " "))
+          : new Date(`${datePart}Z`);
+
+      const baseBigInt = BigInt(d.getTime()) * TimeStamp.MILLISECOND.valueOf();
+      const msBigInt = BigInt(ms) * TimeStamp.MILLISECOND.valueOf();
+
+      return baseBigInt + msBigInt;
+    }
+
     const d = new Date(str);
     // Essential to note that this makes the date midnight in UTC! Not local!
     // As a result, we need to add the tzInfo offset back in.
@@ -560,6 +586,28 @@ export class TimeStamp
     return this.sub(this.remainder(span));
   }
 
+  /**
+   * Determines the appropriate string format based on the span magnitude.
+   *
+   * @param span - The span that provides context for format selection
+   * @returns The appropriate TimeStampStringFormat
+   *
+   * Rules:
+   * - For spans >= 30 days: "shortDate" (e.g., "Nov 5")
+   * - For spans >= 1 day: "dateTime" (e.g., "Nov 5 14:23:45")
+   * - For spans >= 1 hour: "time" (e.g., "14:23:45")
+   * - For spans >= 1 second: "preciseTime" (e.g., "14:23:45.123")
+   * - For spans < 1 second: "ISOTime" (full precision time)
+   */
+  formatBySpan(span: TimeSpan): TimeStampStringFormat {
+    if (span.greaterThanOrEqual(TimeSpan.days(30))) return "shortDate";
+    if (span.greaterThanOrEqual(TimeSpan.DAY)) return "dateTime";
+    if (span.greaterThanOrEqual(TimeSpan.HOUR)) return "time";
+    if (span.greaterThanOrEqual(TimeSpan.SECOND)) return "preciseTime";
+
+    return "ISOTime";
+  }
+
   /**
    * @returns A new TimeStamp representing the current time in UTC. It's important to
    * note that this TimeStamp is only accurate to the millisecond level (that's the best
@@ -2250,13 +2298,5 @@ export const convertDataType = (
   if (source.usesBigInt && !target.usesBigInt) return Number(value) - Number(offset);
   if (!source.usesBigInt && target.usesBigInt)
     return BigInt(value.valueOf()) - BigInt(offset.valueOf());
-  return addSamples(value, -offset);
-};
-
-export const addSamples = (a: math.Numeric, b: math.Numeric): math.Numeric => {
-  if (b == 0) return a;
-  if (a == 0) return b;
-  if (typeof a === "bigint" && typeof b === "bigint") return a + b;
-  if (typeof a === "number" && typeof b === "number") return a + b;
-  return Number(a) + Number(b);
+  return math.sub(value, offset);
 };

package/src/{clamp → types}/index.ts

@@ -7,4 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * as clamp from "@/clamp/clamp";
+export type NotUndefined = {} | null;

package/src/zod/external.ts

@@ -8,5 +8,6 @@
 // included in the file licenses/APL.txt.
 
 export * from "@/zod/nullToUndefined";
+export * from "@/zod/schemas";
 export * from "@/zod/toArray";
 export * from "@/zod/util";

package/src/zod/schemas.spec.ts

@@ -0,0 +1,51 @@
+// Copyright 2025 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// 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 } from "vitest";
+
+import { zod } from "@/zod";
+
+describe("zod", () => {
+  describe("uint12", () => {
+    describe("success", () => {
+      interface Spec {
+        input: number;
+        expected: number;
+      }
+      const specs: Spec[] = [
+        { input: 0, expected: 0 },
+        { input: 1, expected: 1 },
+        { input: 2 ** 12 - 1, expected: 2 ** 12 - 1 },
+      ];
+      specs.forEach(({ input, expected }) => {
+        it(`should parse ${input} as ${expected}`, () => {
+          const result = zod.uint12.parse(input);
+          expect(result).toBe(expected);
+        });
+      });
+    });
+    describe("failure", () => {
+      interface Spec {
+        input: unknown;
+        expected: string;
+      }
+      const specs: Spec[] = [
+        { input: -1, expected: "Too small: expected number to be >=0" },
+        { input: 2 ** 12, expected: "Too big: expected number to be <=4095" },
+        { input: "1", expected: "Invalid input: expected number, received string" },
+        { input: 1.5, expected: "Invalid input: expected int, received number" },
+      ];
+      specs.forEach(({ input, expected }) => {
+        it(`should throw for ${String(input)}`, () => {
+          expect(() => zod.uint12.parse(input)).toThrow(expected);
+        });
+      });
+    });
+  });
+});

package/src/zod/schemas.ts

@@ -0,0 +1,14 @@
+// Copyright 2025 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { z } from "zod";
+
+import { MAX_UINT12 } from "@/math/constants";
+
+export const uint12 = z.int().min(0).max(MAX_UINT12);