@synnaxlabs/x 0.40.0 → 0.41.0

package/src/math/round.ts

@@ -0,0 +1,68 @@
+// 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 { bounds } from "@/spatial/bounds";
+
+const LARGE_SPAN_DECIMAL_PLACES = 2;
+const MEDIUM_SPAN_DECIMAL_PLACES = 3;
+
+// The number of additional decimal places to show past the precision of the span.
+const EXTRA_DECIMAL_PLACES = 2;
+
+/**
+ * Rounds a number  based on the span of the provided bounds. The function adjusts the
+ * number of decimal places based on the magnitude of the bounds.
+ *
+ * @param value - The number to be rounded.
+ * @param bounds - The bounds object containing the min and max values that provide
+ * context for rounding.
+ * @returns The rounded number.
+ *
+ * Rules for decimal places:
+ * - For spans >= 1000: 2 decimal places
+ * - For spans >= 1: 3 decimal places
+ * - For spans < 1: 2 decimal places + 2 decimal places past the precision of the span
+ *
+ * Edge cases:
+ * - If the value is `NaN`, returns `NaN`
+ * - If the value is `Infinity` or `-Infinity`, returns the original value
+ * - If the bounds span is 0, returns the original value
+ *
+ * Examples:
+ * ```typescript
+ * // Large spans (>= 1000) use 2 decimal places
+ * roundBySpan(1234.5678, { start: 0, end: 2000 }); // 1200
+ *
+ * // Medium spans (>= 1) use 3 decimal places
+ * roundBySpan(1.23456, { start: 0, end: 2 }); // 1.235
+ *
+ * // Small spans (< 1) adapt based on the span
+ * roundBySpan(0.123456, { start: 0, end: 0.2 }); // 0.123 = 1 + 2 decimal places
+ * roundBySpan(0.0001234, { start: 0, end: 0.001 }); // 0.00012 = 3 + 2 decimal places
+ *
+ * // Edge cases
+ * roundBySpan(NaN, { start: 0, end: 1 }); // NaN
+ * roundBySpan(Infinity, { start: 0, end: 1 }); // Infinity
+ * roundBySpan(123, { start: 1, end: 1 }); // 123 (span is 0)
+ * ```
+ */
+export const roundBySpan = (value: number, b: bounds.Bounds<number>): number => {
+  if (Number.isNaN(value) || !Number.isFinite(value)) return value;
+  const span = bounds.span(b);
+  if (span == 0) return value;
+  let decimalPlaces: number;
+  if (span >= 1000) decimalPlaces = LARGE_SPAN_DECIMAL_PLACES;
+  else if (span >= 1) decimalPlaces = MEDIUM_SPAN_DECIMAL_PLACES;
+  else {
+    const decimalPlacesInSpan = Math.ceil(-Math.log10(span));
+    decimalPlaces = decimalPlacesInSpan + EXTRA_DECIMAL_PLACES;
+  }
+  const multiplier = 10 ** decimalPlaces;
+  return Math.round(value * multiplier) / multiplier;
+};

package/src/notation/index.ts

@@ -0,0 +1,10 @@
+// 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.
+
+export * as notation from "@/notation/notation";

package/src/notation/notation.spec.ts

@@ -0,0 +1,88 @@
+// 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 { notation } from "@/notation";
+
+interface TestCase {
+  number: number;
+  precision: number;
+  expected: Record<notation.Notation, string>;
+}
+
+const TEST_CASES: TestCase[] = [
+  {
+    number: 12345.678,
+    precision: 1,
+    expected: { standard: "12345.7", scientific: "1.2ᴇ4", engineering: "12.3ᴇ3" },
+  },
+  {
+    number: 12345.678,
+    precision: 0,
+    expected: { standard: "12346", scientific: "1ᴇ4", engineering: "12ᴇ3" },
+  },
+  {
+    number: 0,
+    precision: 1,
+    expected: { standard: "0.0", scientific: "0.0ᴇ0", engineering: "0.0ᴇ0" },
+  },
+  {
+    number: 0,
+    precision: 0,
+    expected: { standard: "0", scientific: "0ᴇ0", engineering: "0ᴇ0" },
+  },
+  {
+    number: -1234.5678,
+    precision: 1,
+    expected: { standard: "-1234.6", scientific: "-1.2ᴇ3", engineering: "-1.2ᴇ3" },
+  },
+  {
+    number: -1234.5678,
+    precision: 0,
+    expected: { standard: "-1235", scientific: "-1ᴇ3", engineering: "-1ᴇ3" },
+  },
+  {
+    number: NaN,
+    precision: 0,
+    expected: { standard: "NaN", scientific: "NaN", engineering: "NaN" },
+  },
+  {
+    number: Infinity,
+    precision: 0,
+    expected: { standard: "∞", scientific: "∞", engineering: "∞" },
+  },
+  {
+    number: -Infinity,
+    precision: 0,
+    expected: { standard: "-∞", scientific: "-∞", engineering: "-∞" },
+  },
+  {
+    number: 0.0001234,
+    precision: 1,
+    expected: { standard: "0.0", scientific: "1.2ᴇ-4", engineering: "123.4ᴇ-6" },
+  },
+  {
+    number: 0.0001234,
+    precision: 0,
+    expected: { standard: "0", scientific: "1ᴇ-4", engineering: "123ᴇ-6" },
+  },
+];
+
+describe("stringifyNumber", () => {
+  TEST_CASES.forEach(({ number, precision, expected }) =>
+    describe(`number: ${number}, precision: ${precision}`, () =>
+      notation.NOTATIONS.forEach((n) =>
+        it(`should format correctly in ${n} notation`, () => {
+          const result = notation.stringifyNumber(number, precision, n);
+          expect(result).toBe(expected[n]);
+        }),
+      )),
+  );
+});

package/src/notation/notation.ts

@@ -0,0 +1,61 @@
+// 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";
+
+export const NOTATIONS = ["standard", "scientific", "engineering"] as const;
+export const notationZ = z.enum(NOTATIONS);
+export type Notation = z.infer<typeof notationZ>;
+
+/**
+ * Converts a number to a string representation with a specified precision and notation.
+ *
+ * @param value - The number to be converted.
+ * @param precision - The number of decimal places to include in the output. Must be between 0 and 20.
+ * @param notation - The notation to use for the conversion. Can be "standard", "scientific", or "engineering".
+ * @returns The string representation of the number.
+ *
+ * Edge cases:
+ * - If the value is `NaN`, returns "NaN".
+ * - If the value is `Infinity`, returns "∞".
+ * - If the value is `-Infinity`, returns "-∞".
+ *
+ * Examples:
+ *
+ * ```typescript
+ * stringifyNumber(1234.5678, 2, "standard"); // "1234.57"
+ * stringifyNumber(1234.5678, 2, "scientific"); // "1.23ᴇ3"
+ * stringifyNumber(1234.5678, 2, "engineering"); // "1.23ᴇ3"
+ * stringifyNumber(0.0001234, 4, "standard"); // "0.0001"
+ * stringifyNumber(0.0001234, 4, "scientific"); // "1.2340ᴇ-4"
+ * stringifyNumber(0.0001234, 4, "engineering"); // "123.4000ᴇ-6"
+ * stringifyNumber(NaN, 2, "standard"); // "NaN"
+ * stringifyNumber(Infinity, 2, "standard"); // "∞"
+ * stringifyNumber(-Infinity, 2, "standard"); // "-∞"
+ * ```
+ */
+export const stringifyNumber = (
+  value: number,
+  precision: number,
+  notation: Notation,
+): string => {
+  if (Number.isNaN(value)) return "NaN";
+  if (value === Infinity) return "∞";
+  if (value === -Infinity) return "-∞";
+  if (notation === "standard") return value.toFixed(precision);
+  if (value === 0) {
+    if (precision === 0) return "0ᴇ0";
+    return `0.${"0".repeat(precision)}ᴇ0`;
+  }
+  let exp: number;
+  if (notation === "scientific") exp = Math.floor(Math.log10(Math.abs(value)));
+  else exp = Math.floor(Math.log10(Math.abs(value)) / 3) * 3;
+  const mantissa = value / 10 ** exp;
+  return `${mantissa.toFixed(precision)}ᴇ${exp}`;
+};

package/src/spatial/box/box.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 { describe, expect, it, test } from "vitest";
 
 import * as box from "@/spatial/box/box";
 import * as location from "@/spatial/location/location";
@@ -102,8 +102,8 @@ describe("Box", () => {
     describe("xyLoc", () => {
       const v: location.XY[] = [
         location.BOTTOM_CENTER,
-        location.LEFT_CENTER,
-        location.RIGHT_CENTER,
+        location.CENTER_LEFT,
+        location.CENTER_RIGHT,
         location.TOP_CENTER,
         location.BOTTOM_LEFT,
         location.BOTTOM_RIGHT,

package/src/spatial/box/box.ts

@@ -278,12 +278,20 @@ export const signedHeight = (b: Crude): number => {
 
 export const topLeft = (b: Crude): xy.XY => xyLoc(b, location.TOP_LEFT);
 
+export const topCenter = (b: Crude): xy.XY => xyLoc(b, location.TOP_CENTER);
+
 export const topRight = (b: Crude): xy.XY => xyLoc(b, location.TOP_RIGHT);
 
 export const bottomLeft = (b: Crude): xy.XY => xyLoc(b, location.BOTTOM_LEFT);
 
+export const bottomCenter = (b: Crude): xy.XY => xyLoc(b, location.BOTTOM_CENTER);
+
 export const bottomRight = (b: Crude): xy.XY => xyLoc(b, location.BOTTOM_RIGHT);
 
+export const centerLeft = (b: Crude): xy.XY => xyLoc(b, location.CENTER_LEFT);
+
+export const centerRight = (b: Crude): xy.XY => xyLoc(b, location.CENTER_RIGHT);
+
 export const right = (b: Crude): number => loc(b, "right");
 
 export const bottom = (b: Crude): number => loc(b, "bottom");

package/src/spatial/location/location.ts

@@ -102,11 +102,11 @@ export const BOTTOM_RIGHT: CornerXY = Object.freeze({ x: "right", y: "bottom" })
 export const CENTER: XY = Object.freeze({ x: "center", y: "center" });
 export const TOP_CENTER: XY = Object.freeze({ x: "center", y: "top" });
 export const BOTTOM_CENTER: XY = Object.freeze({ x: "center", y: "bottom" });
-export const RIGHT_CENTER: XY = Object.freeze({ x: "right", y: "center" });
-export const LEFT_CENTER: XY = Object.freeze({ x: "left", y: "center" });
+export const CENTER_RIGHT: XY = Object.freeze({ x: "right", y: "center" });
+export const CENTER_LEFT: XY = Object.freeze({ x: "left", y: "center" });
 export const XY_LOCATIONS: readonly XY[] = Object.freeze([
-  LEFT_CENTER,
-  RIGHT_CENTER,
+  CENTER_LEFT,
+  CENTER_RIGHT,
   TOP_CENTER,
   BOTTOM_CENTER,
   TOP_LEFT,

package/src/spatial/position/position.spec.ts

@@ -24,7 +24,7 @@ describe("position", () => {
         target: box.construct(45, 55, 10, 10),
         dialog: box.construct(0, 0, 20, 20),
       },
-      location.LEFT_CENTER,
+      location.CENTER_LEFT,
     ];
 
     const SPEC_CASE_2: Spec = [
@@ -54,7 +54,7 @@ describe("position", () => {
         dialog: box.construct(0, 0, 20, 20),
         initial: "left",
       },
-      location.LEFT_CENTER,
+      location.CENTER_LEFT,
     ];
 
     const SPEC_CASE_5: Spec = [
@@ -64,7 +64,7 @@ describe("position", () => {
         dialog: box.construct(0, 0, 20, 20),
         initial: "right",
       },
-      location.RIGHT_CENTER,
+      location.CENTER_RIGHT,
     ];
 
     // Target is in bottom right corner
@@ -74,7 +74,7 @@ describe("position", () => {
         target: box.construct(90, 90, 10, 10),
         dialog: box.construct(0, 0, 20, 20),
       },
-      location.LEFT_CENTER,
+      location.CENTER_LEFT,
     ];
 
     // Target is in the top left corner
@@ -186,12 +186,12 @@ describe("position", () => {
       [location.TOP_CENTER, "start", location.BOTTOM_LEFT],
       [location.TOP_CENTER, "center", location.BOTTOM_CENTER],
       [location.TOP_CENTER, "end", location.BOTTOM_RIGHT],
-      [location.LEFT_CENTER, "start", location.BOTTOM_RIGHT],
-      [location.LEFT_CENTER, "center", location.RIGHT_CENTER],
-      [location.LEFT_CENTER, "end", location.TOP_RIGHT],
-      [location.RIGHT_CENTER, "start", location.BOTTOM_LEFT],
-      [location.RIGHT_CENTER, "center", location.LEFT_CENTER],
-      [location.RIGHT_CENTER, "end", location.TOP_LEFT],
+      [location.CENTER_LEFT, "start", location.BOTTOM_RIGHT],
+      [location.CENTER_LEFT, "center", location.CENTER_RIGHT],
+      [location.CENTER_LEFT, "end", location.TOP_RIGHT],
+      [location.CENTER_RIGHT, "start", location.BOTTOM_LEFT],
+      [location.CENTER_RIGHT, "center", location.CENTER_LEFT],
+      [location.CENTER_RIGHT, "end", location.TOP_LEFT],
       [location.BOTTOM_LEFT, "start", location.TOP_RIGHT],
       [location.BOTTOM_LEFT, "center", location.TOP_CENTER],
       [location.BOTTOM_LEFT, "end", location.TOP_LEFT],

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

@@ -143,4 +143,12 @@ describe("XY", () => {
       ]);
     });
   });
+
+  describe("swap", () => {
+    it("should swap x and y coordinates", () => {
+      expect(xy.swap([1, 2])).toEqual({ x: 2, y: 1 });
+      expect(xy.swap({ x: 3, y: 4 })).toEqual({ x: 4, y: 3 });
+      expect(xy.swap({ width: 5, height: 6 })).toEqual({ x: 6, y: 5 });
+    });
+  });
 });

package/src/spatial/xy/xy.ts

@@ -279,3 +279,17 @@ export const calculateMiters = (path: XY[], offset: number): XY[] => {
   }
   return miters;
 };
+
+/**
+ * Swaps the x and y coordinates of a point.
+ * @param a - The coordinate to swap. Can be provided in any supported format (couple, object, dimensions, etc.)
+ * @returns A new XY coordinate with the x and y values swapped.
+ * @example
+ * swap([1, 2]) // returns { x: 2, y: 1 }
+ * swap({ x: 3, y: 4 }) // returns { x: 4, y: 3 }
+ * swap({ width: 5, height: 6 }) // returns { x: 6, y: 5 }
+ */
+export const swap = (a: Crude): XY => {
+  const xy = construct(a);
+  return { x: xy.y, y: xy.x };
+};

package/src/telem/series.spec.ts

@@ -1064,4 +1064,43 @@ describe("MultiSeries", () => {
       expect(multi.timeRange).toEqual(new TimeRange(1, 4));
     });
   });
+
+  describe("as", () => {
+    it("should correctly cast a numeric series to number type", () => {
+      const a = new Series(new Float32Array([1, 2, 3]));
+      const b = new Series(new Float32Array([4, 5, 6]));
+      const multi = new MultiSeries([a, b]);
+      const asNum = multi.as("number");
+      expect(asNum.at(0)).toEqual(1);
+      expect(asNum.at(5)).toEqual(6);
+      expect(Array.from(asNum)).toEqual([1, 2, 3, 4, 5, 6]);
+    });
+
+    it("should correctly cast a string series to string type", () => {
+      const a = new Series(["apple", "banana"]);
+      const b = new Series(["carrot", "date"]);
+      const multi = new MultiSeries([a, b]);
+      const asStr = multi.as("string");
+      expect(asStr.at(0)).toEqual("apple");
+      expect(asStr.at(3)).toEqual("date");
+      expect(Array.from(asStr)).toEqual(["apple", "banana", "carrot", "date"]);
+    });
+
+    it("should correctly cast a bigint series to bigint type", () => {
+      const a = new Series([1n, 2n]);
+      const b = new Series([3n, 4n]);
+      const multi = new MultiSeries([a, b]);
+      const asBigInt = multi.as("bigint");
+      expect(asBigInt.at(0)).toEqual(1n);
+      expect(asBigInt.at(3)).toEqual(4n);
+      expect(Array.from(asBigInt)).toEqual([1n, 2n, 3n, 4n]);
+    });
+
+    it("should throw an error when trying to cast to an incompatible type", () => {
+      const a = new Series(new Float32Array([1, 2, 3]));
+      const b = new Series(new Float32Array([4, 5, 6]));
+      const multi = new MultiSeries([a, b]);
+      expect(() => multi.as("string")).toThrow();
+    });
+  });
 });

package/src/telem/series.ts

@@ -126,6 +126,17 @@ const nullArrayZ = z
 
 const NEW_LINE = 10;
 
+type JSType = "string" | "number" | "bigint";
+
+const checkAsType = (jsType: JSType, dataType: DataType) => {
+  if (jsType === "string" && !dataType.isVariable)
+    throw new Error(`cannot convert series of type ${dataType.toString()} to string`);
+  if (jsType === "number" && !dataType.isNumeric)
+    throw new Error(`cannot convert series of type ${dataType.toString()} to number`);
+  if (jsType === "bigint" && !dataType.usesBigInt)
+    throw new Error(`cannot convert series of type ${dataType.toString()} to bigint`);
+};
+
 /**
  * Series is a strongly typed array of telemetry samples backed by an underlying binary
  * buffer.
@@ -696,28 +707,8 @@ export class Series<T extends TelemValue = TelemValue> {
   as(jsType: "bigint"): Series<bigint>;
 
   as<T extends TelemValue>(jsType: "string" | "number" | "bigint"): Series<T> {
-    if (jsType === "string") {
-      if (!this.dataType.equals(DataType.STRING))
-        throw new Error(
-          `cannot convert series of type ${this.dataType.toString()} to string`,
-        );
-      return this as unknown as Series<T>;
-    }
-    if (jsType === "number") {
-      if (!this.dataType.isNumeric)
-        throw new Error(
-          `cannot convert series of type ${this.dataType.toString()} to number`,
-        );
-      return this as unknown as Series<T>;
-    }
-    if (jsType === "bigint") {
-      if (!this.dataType.equals(DataType.INT64))
-        throw new Error(
-          `cannot convert series of type ${this.dataType.toString()} to bigint`,
-        );
-      return this as unknown as Series<T>;
-    }
-    throw new Error(`cannot convert series to ${jsType as string}`);
+    checkAsType(jsType, this.dataType);
+    return this as unknown as Series<T>;
   }
 
   get digest(): SeriesDigest {
@@ -950,11 +941,8 @@ export class MultiSeries<T extends TelemValue = TelemValue> implements Iterable<
 
   as(jsType: "bigint"): MultiSeries<bigint>;
 
-  as<T extends TelemValue>(dataType: CrudeDataType): MultiSeries<T> {
-    if (!new DataType(dataType).equals(this.dataType))
-      throw new Error(
-        `cannot convert series of type ${this.dataType.toString()} to ${dataType.toString()}`,
-      );
+  as<T extends TelemValue>(jsType: "string" | "number" | "bigint"): MultiSeries<T> {
+    checkAsType(jsType, this.dataType);
     return this as unknown as MultiSeries<T>;
   }
 

package/src/telem/telem.ts

@@ -360,6 +360,14 @@ export class TimeStamp implements Stringer {
     return Number(this.valueOf()) / Number(TimeStamp.MILLISECOND.valueOf());
   }
 
+  get microseconds(): number {
+    return Number(this.valueOf()) / Number(TimeStamp.MICROSECOND.valueOf());
+  }
+
+  get nanoseconds(): number {
+    return Number(this.valueOf());
+  }
+
   /** @returns the integer year that the timestamp corresponds to. */
   get year(): number {
     return this.date().getFullYear();