@synnaxlabs/x 0.46.2 → 0.48.0

package/src/migrate/migrate.spec.ts

@@ -56,6 +56,59 @@ const migrations: migrate.Migrations = {
   "1.0.0": migrateV2,
 };
 
+describe("semVerZ", () => {
+  describe("valid versions", () => {
+    it("should accept standard semver format", () => {
+      expect(() => migrate.semVerZ.parse("1.0.0")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("0.0.0")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("99.99.99")).not.toThrow();
+    });
+
+    it("should accept pre-release versions with single identifier", () => {
+      expect(() => migrate.semVerZ.parse("1.0.0-alpha")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("1.0.0-beta")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("1.0.0-rc")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("0.48.0-rc")).not.toThrow();
+    });
+
+    it("should accept pre-release versions with numeric identifiers", () => {
+      expect(() => migrate.semVerZ.parse("1.0.0-1")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("1.0.0-0")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("1.0.0-99")).not.toThrow();
+    });
+
+    it("should accept pre-release versions with multiple identifiers", () => {
+      expect(() => migrate.semVerZ.parse("1.0.0-alpha.1")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("1.0.0-rc.1")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("1.0.0-beta.2.3")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("1.0.0-0.3.7")).not.toThrow();
+    });
+
+    it("should accept pre-release versions with hyphens", () => {
+      expect(() => migrate.semVerZ.parse("1.0.0-x-beta")).not.toThrow();
+      expect(() => migrate.semVerZ.parse("1.0.0-alpha-beta")).not.toThrow();
+    });
+  });
+
+  describe("invalid versions", () => {
+    it("should reject versions without patch", () => {
+      expect(() => migrate.semVerZ.parse("1.0")).toThrow();
+    });
+
+    it("should reject versions without minor", () => {
+      expect(() => migrate.semVerZ.parse("1")).toThrow();
+    });
+
+    it("should reject versions with build metadata (not supported)", () => {
+      expect(() => migrate.semVerZ.parse("1.0.0+build")).toThrow();
+    });
+
+    it("should reject versions with empty pre-release", () => {
+      expect(() => migrate.semVerZ.parse("1.0.0-")).toThrow();
+    });
+  });
+});
+
 describe("compareSemVer", () => {
   it("should return true when the major version is higher", () => {
     expect(migrate.compareSemVer("1.0.0", "0.0.0")).toBeGreaterThan(0);
@@ -139,6 +192,98 @@ describe("compareSemVer", () => {
       ).toBeLessThan(0);
     });
   });
+
+  describe("pre-release versions", () => {
+    it("should consider release version newer than pre-release", () => {
+      expect(migrate.compareSemVer("1.0.0", "1.0.0-rc")).toBeGreaterThan(0);
+      expect(migrate.compareSemVer("1.0.0", "1.0.0-alpha")).toBeGreaterThan(0);
+      expect(migrate.compareSemVer("1.0.0", "1.0.0-beta")).toBeGreaterThan(0);
+      expect(migrate.compareSemVer("0.48.0", "0.48.0-rc")).toBeGreaterThan(0);
+      expect(migrate.semVerNewer("1.0.0", "1.0.0-rc")).toBe(true);
+    });
+
+    it("should consider pre-release version older than release", () => {
+      expect(migrate.compareSemVer("1.0.0-rc", "1.0.0")).toBeLessThan(0);
+      expect(migrate.compareSemVer("1.0.0-alpha", "1.0.0")).toBeLessThan(0);
+      expect(migrate.compareSemVer("0.48.0-rc", "0.48.0")).toBeLessThan(0);
+      expect(migrate.semVerOlder("1.0.0-rc", "1.0.0")).toBe(true);
+    });
+
+    it("should compare pre-release versions lexicographically", () => {
+      expect(migrate.compareSemVer("1.0.0-alpha", "1.0.0-beta")).toBeLessThan(0);
+      expect(migrate.compareSemVer("1.0.0-beta", "1.0.0-rc")).toBeLessThan(0);
+      expect(migrate.compareSemVer("1.0.0-rc", "1.0.0-alpha")).toBeGreaterThan(0);
+      expect(migrate.semVerNewer("1.0.0-rc", "1.0.0-alpha")).toBe(true);
+      expect(migrate.semVerOlder("1.0.0-alpha", "1.0.0-beta")).toBe(true);
+    });
+
+    it("should compare numeric pre-release identifiers numerically", () => {
+      expect(migrate.compareSemVer("1.0.0-1", "1.0.0-2")).toBeLessThan(0);
+      expect(migrate.compareSemVer("1.0.0-2", "1.0.0-10")).toBeLessThan(0);
+      expect(migrate.compareSemVer("1.0.0-10", "1.0.0-2")).toBeGreaterThan(0);
+    });
+
+    it("should compare pre-release versions with multiple identifiers", () => {
+      expect(migrate.compareSemVer("1.0.0-rc.1", "1.0.0-rc.2")).toBeLessThan(0);
+      expect(migrate.compareSemVer("1.0.0-rc.2", "1.0.0-rc.10")).toBeLessThan(0);
+      expect(migrate.compareSemVer("1.0.0-alpha.1", "1.0.0-alpha.2")).toBeLessThan(0);
+      expect(
+        migrate.compareSemVer("1.0.0-alpha.beta", "1.0.0-alpha.gamma"),
+      ).toBeLessThan(0);
+    });
+
+    it("should consider numeric identifiers lower than alphanumeric", () => {
+      expect(migrate.compareSemVer("1.0.0-1", "1.0.0-alpha")).toBeLessThan(0);
+      expect(migrate.compareSemVer("1.0.0-alpha", "1.0.0-1")).toBeGreaterThan(0);
+      expect(migrate.compareSemVer("1.0.0-rc.1", "1.0.0-rc.beta")).toBeLessThan(0);
+    });
+
+    it("should consider longer pre-release identifiers higher precedence", () => {
+      expect(migrate.compareSemVer("1.0.0-rc", "1.0.0-rc.1")).toBeLessThan(0);
+      expect(migrate.compareSemVer("1.0.0-rc.1", "1.0.0-rc")).toBeGreaterThan(0);
+      expect(migrate.compareSemVer("1.0.0-alpha.1", "1.0.0-alpha.1.2")).toBeLessThan(0);
+    });
+
+    it("should consider equal pre-release versions equal", () => {
+      expect(migrate.compareSemVer("1.0.0-rc", "1.0.0-rc")).toBe(0);
+      expect(migrate.compareSemVer("1.0.0-alpha.1", "1.0.0-alpha.1")).toBe(0);
+      expect(migrate.versionsEqual("1.0.0-rc", "1.0.0-rc")).toBe(true);
+    });
+
+    it("should handle complex pre-release comparison chains", () => {
+      const versions = [
+        "1.0.0-alpha",
+        "1.0.0-alpha.1",
+        "1.0.0-alpha.beta",
+        "1.0.0-beta",
+        "1.0.0-beta.2",
+        "1.0.0-beta.11",
+        "1.0.0-rc.1",
+        "1.0.0",
+      ];
+
+      for (let i = 0; i < versions.length - 1; i++) {
+        expect(migrate.compareSemVer(versions[i], versions[i + 1])).toBeLessThan(0);
+        expect(migrate.compareSemVer(versions[i + 1], versions[i])).toBeGreaterThan(0);
+      }
+    });
+
+    it("should respect checkMajor/checkMinor/checkPatch with pre-release", () => {
+      expect(
+        migrate.compareSemVer("2.0.0-rc", "1.0.0", {
+          checkMinor: false,
+          checkPatch: false,
+        }),
+      ).toBeGreaterThan(0);
+
+      expect(
+        migrate.compareSemVer("1.2.0-rc", "1.1.0", {
+          checkMajor: false,
+          checkPatch: false,
+        }),
+      ).toBeGreaterThan(0);
+    });
+  });
 });
 
 describe("migrator", () => {
@@ -172,4 +317,97 @@ describe("migrator", () => {
     })(entity);
     expect(migrated).toEqual(entity);
   });
+
+  describe("with pre-release versions", () => {
+    const entityV1RC = z.object({
+      version: z.literal("1.0.0-rc"),
+      title: z.string(),
+    });
+
+    type EntityV1RC = z.infer<typeof entityV1RC>;
+
+    const migrateV1RC = migrate.createMigration<EntityV1RC, EntityV2>({
+      name: "entity",
+      inputSchema: entityV1RC,
+      outputSchema: entityV2,
+      migrate: (entity) => ({ ...entity, version: "2.0.0", description: "" }),
+    });
+
+    const migrationsWithRC: migrate.Migrations = {
+      "0.0.0": migrateV1,
+      "1.0.0-rc": migrateV1RC,
+      "1.0.0": migrateV2,
+    };
+
+    it("should migrate from pre-release version to stable", () => {
+      const entity: EntityV1RC = { version: "1.0.0-rc", title: "foo" };
+      const DEFAULT: EntityV2 = { version: "2.0.0", title: "", description: "" };
+      const migrated = migrate.migrator({
+        name: "entity",
+        migrations: migrationsWithRC,
+        def: DEFAULT,
+      })(entity);
+      expect(migrated).toEqual({ version: "2.0.0", title: "foo", description: "" });
+    });
+
+    it("should handle version sorting with pre-release correctly", () => {
+      const versions = ["0.0.0", "1.0.0-rc", "1.0.0"];
+      const sorted = versions.sort(migrate.compareSemVer);
+      expect(sorted).toEqual(["0.0.0", "1.0.0-rc", "1.0.0"]);
+    });
+
+    it("should not migrate if current version is newer than pre-release target", () => {
+      const entity: EntityV1 = { version: "1.0.0", title: "foo" };
+      const DEFAULT: EntityV1RC = { version: "1.0.0-rc", title: "" };
+      const migrated = migrate.migrator({
+        name: "entity",
+        migrations: { "0.0.0": migrateV1 },
+        def: DEFAULT,
+      })(entity);
+      expect(migrated).toEqual({ version: "1.0.0", title: "foo" });
+    });
+
+    it("should migrate through multiple pre-release versions", () => {
+      interface EntityV1Alpha {
+        version: "1.0.0-alpha";
+        title: string;
+      }
+
+      interface EntityV1Beta extends Omit<EntityV1Alpha, "version"> {
+        version: "1.0.0-beta";
+        newField: string;
+      }
+
+      const migrateAlphaToBeta = migrate.createMigration<EntityV1Alpha, EntityV1Beta>({
+        name: "entity",
+        migrate: (entity) => ({
+          ...entity,
+          version: "1.0.0-beta",
+          newField: "added",
+        }),
+      });
+
+      const migrateBetaToRC = migrate.createMigration<EntityV1Beta, EntityV1RC>({
+        name: "entity",
+        migrate: (entity) => {
+          const { newField, ...rest } = entity;
+          return { ...rest, version: "1.0.0-rc" };
+        },
+      });
+
+      const preReleaseMigrations: migrate.Migrations = {
+        "1.0.0-alpha": migrateAlphaToBeta,
+        "1.0.0-beta": migrateBetaToRC,
+      };
+
+      const entity: EntityV1Alpha = { version: "1.0.0-alpha", title: "test" };
+      const DEFAULT: EntityV1RC = { version: "1.0.0-rc", title: "" };
+      const migrated = migrate.migrator({
+        name: "entity",
+        migrations: preReleaseMigrations,
+        def: DEFAULT,
+      })(entity);
+      expect(migrated).toEqual({ version: "1.0.0-rc", title: "test" });
+    });
+  });
 });

package/src/migrate/migrate.ts

@@ -12,7 +12,9 @@ import { z } from "zod";
 import { compare } from "@/compare";
 import { type Optional } from "@/optional";
 
-export const semVerZ = z.string().regex(/^\d+\.\d+\.\d+$/);
+export const semVerZ = z
+  .string()
+  .regex(/^\d+\.\d+\.\d+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/);
 
 export type SemVer = z.infer<typeof semVerZ>;
 
@@ -34,6 +36,48 @@ export interface CompareSemVerOptions {
   checkPatch?: boolean;
 }
 
+/**
+ * Compares two pre-release identifiers according to semver spec.
+ * @param a - First pre-release identifier (without leading hyphen)
+ * @param b - Second pre-release identifier (without leading hyphen)
+ * @returns compare.LESS_THAN if a < b, compare.GREATER_THAN if a > b, compare.EQUAL if equal
+ */
+const comparePreRelease = (a: string, b: string): number => {
+  const aParts = a.split(".");
+  const bParts = b.split(".");
+  const maxLength = Math.max(aParts.length, bParts.length);
+
+  for (let i = 0; i < maxLength; i++) {
+    const aPart = aParts[i];
+    const bPart = bParts[i];
+
+    // A larger set of pre-release fields has higher precedence
+    if (aPart === undefined) return compare.LESS_THAN;
+    if (bPart === undefined) return compare.GREATER_THAN;
+
+    const aIsNumeric = /^\d+$/.test(aPart);
+    const bIsNumeric = /^\d+$/.test(bPart);
+
+    // Numeric identifiers always have lower precedence than non-numeric
+    if (aIsNumeric && !bIsNumeric) return compare.LESS_THAN;
+    if (!aIsNumeric && bIsNumeric) return compare.GREATER_THAN;
+
+    if (aIsNumeric && bIsNumeric) {
+      // Compare numerically
+      const aNum = parseInt(aPart);
+      const bNum = parseInt(bPart);
+      if (aNum < bNum) return compare.LESS_THAN;
+      if (aNum > bNum) return compare.GREATER_THAN;
+    } else {
+      // Compare lexically (ASCII sort order)
+      if (aPart < bPart) return compare.LESS_THAN;
+      if (aPart > bPart) return compare.GREATER_THAN;
+    }
+  }
+
+  return compare.EQUAL;
+};
+
 /**
  * Compares the two semantic versions.
  *
@@ -55,8 +99,14 @@ export const compareSemVer = ((
   opts.checkPatch ??= true;
   const semA = semVerZ.parse(a);
   const semB = semVerZ.parse(b);
-  const [aMajor, aMinor, aPatch] = semA.split(".").map(Number);
-  const [bMajor, bMinor, bPatch] = semB.split(".").map(Number);
+
+  // Split version and pre-release parts
+  const [aCore, aPreRelease] = semA.split("-");
+  const [bCore, bPreRelease] = semB.split("-");
+
+  const [aMajor, aMinor, aPatch] = aCore.split(".").map(Number);
+  const [bMajor, bMinor, bPatch] = bCore.split(".").map(Number);
+
   if (opts.checkMajor) {
     if (aMajor < bMajor) return compare.LESS_THAN;
     if (aMajor > bMajor) return compare.GREATER_THAN;
@@ -69,7 +119,15 @@ export const compareSemVer = ((
     if (aPatch < bPatch) return compare.LESS_THAN;
     if (aPatch > bPatch) return compare.GREATER_THAN;
   }
-  return compare.EQUAL;
+
+  // When major.minor.patch are equal, compare pre-release versions
+  // Version without pre-release > version with pre-release
+  if (aPreRelease === undefined && bPreRelease === undefined) return compare.EQUAL;
+  if (aPreRelease === undefined) return compare.GREATER_THAN;
+  if (bPreRelease === undefined) return compare.LESS_THAN;
+
+  // Both have pre-release, compare them
+  return comparePreRelease(aPreRelease, bPreRelease);
 }) satisfies compare.Comparator<SemVer>;
 
 /**

package/src/spatial/bounds/bounds.spec.ts

@@ -10,7 +10,7 @@
 import { describe, expect, it, test } from "vitest";
 
 import { type numeric } from "@/numeric";
-import * as bounds from "@/spatial/bounds/bounds";
+import { bounds } from "@/spatial/bounds";
 import { testutil } from "@/testutil";
 
 describe("Bounds", () => {

package/src/spatial/bounds/bounds.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 { math } from "@/math";
+import { abs, add, equal as mathEqual, min as mathMin, sub } from "@/math/math";
 import { type numeric } from "@/numeric";
 import { type Bounds, bounds, type CrudeBounds } from "@/spatial/base";
 
@@ -479,7 +479,7 @@ export const buildInsertionPlan = <T extends numeric.Value>(
   }
   let deleteInBetween = upper.index - lower.index;
   let insertInto = lower.index;
-  let removeBefore = math.sub(Number(span(_bounds[lower.index])), lower.position);
+  let removeBefore = sub(Number(span(_bounds[lower.index])), lower.position);
   // If we're overlapping with the previous bound, we need to slice out one less
   // and insert one further up.
   if (lower.position !== 0) {
@@ -596,7 +596,7 @@ export const traverse = <T extends numeric.Value = number>(
   let remainingDist = dist;
   let currentPosition = start as number | bigint;
 
-  while (math.equal(remainingDist, 0) === false) {
+  while (mathEqual(remainingDist, 0) === false) {
     // Find the bound we're currently in or adjacent to
     const index = _bounds.findIndex((b) => {
       if (dir > 0) return currentPosition >= b.lower && currentPosition < b.upper;
@@ -606,19 +606,16 @@ export const traverse = <T extends numeric.Value = number>(
     if (index !== -1) {
       const b = _bounds[index];
       let distanceInBound: T;
-      if (dir > 0) distanceInBound = math.sub(b.upper, currentPosition);
-      else distanceInBound = math.sub(currentPosition, b.lower) as T;
+      if (dir > 0) distanceInBound = sub(b.upper, currentPosition);
+      else distanceInBound = sub(currentPosition, b.lower) as T;
 
       if (distanceInBound > (0 as T)) {
-        const moveDist = math.min(math.abs(remainingDist), distanceInBound);
-        currentPosition = math.add(
-          currentPosition,
-          dir > 0 ? moveDist : -moveDist,
-        ) as T;
-        remainingDist = math.sub<T>(remainingDist, dir > 0 ? moveDist : -moveDist);
+        const moveDist = mathMin(abs(remainingDist), distanceInBound);
+        currentPosition = add(currentPosition, dir > 0 ? moveDist : -moveDist) as T;
+        remainingDist = sub<T>(remainingDist, dir > 0 ? moveDist : -moveDist);
 
         // If we've exhausted the distance, return the current position
-        if (math.equal(remainingDist, 0)) return currentPosition as T;
+        if (mathEqual(remainingDist, 0)) return currentPosition as T;
         continue;
       }
     }

package/src/spatial/box/box.spec.ts

@@ -9,9 +9,9 @@
 
 import { describe, expect, it, test } from "vitest";
 
-import * as box from "@/spatial/box/box";
-import * as location from "@/spatial/location/location";
-import type * as xy from "@/spatial/xy/xy";
+import { box } from "@/spatial/box";
+import { location } from "@/spatial/location";
+import { type xy } from "@/spatial/xy";
 
 describe("Box", () => {
   describe("construction", () => {

package/src/spatial/box/box.ts

@@ -9,11 +9,11 @@
 
 import { z } from "zod";
 
-import type * as bounds from "@/spatial/bounds/bounds";
-import type * as dimensions from "@/spatial/dimensions/dimensions";
-import * as direction from "@/spatial/direction/direction";
-import * as location from "@/spatial/location/location";
-import * as xy from "@/spatial/xy/xy";
+import { type bounds } from "@/spatial/bounds";
+import { type dimensions } from "@/spatial/dimensions";
+import { direction } from "@/spatial/direction";
+import { location } from "@/spatial/location";
+import { xy } from "@/spatial/xy";
 
 const cssPos = z.union([z.number(), z.string()]);
 

package/src/spatial/dimensions/dimensions.spec.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, test } from "vitest";
 
-import * as dimensions from "@/spatial/dimensions/dimensions";
+import { dimensions } from "@/spatial/dimensions";
 
 describe("Dimensions", () => {
   describe("construction", () => {

package/src/spatial/direction/direction.spec.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, it, test } from "vitest";
 
-import * as direction from "@/spatial/direction/direction";
+import { direction } from "@/spatial/direction";
 
 describe("Direction", () => {
   describe("construction", () => {

package/src/spatial/location/location.spec.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, test } from "vitest";
 
-import * as location from "@/spatial/location/location";
+import { location } from "@/spatial/location";
 
 describe("Location", () => {
   describe("construction", () => {

package/src/spatial/scale/scale.spec.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, it, test } from "vitest";
 
-import * as box from "@/spatial/box/box";
+import { box } from "@/spatial/box";
 import { Scale, XY } from "@/spatial/scale/scale";
 
 type ScaleSpec = [name: string, scale: Scale<number>, i: number, o: number];

package/src/spatial/scale/scale.ts

@@ -11,12 +11,12 @@ import { z } from "zod";
 
 import { clamp } from "@/clamp/clamp";
 import { type numeric } from "@/numeric";
-import * as bounds from "@/spatial/bounds/bounds";
+import { bounds } from "@/spatial/bounds";
+import { box } from "@/spatial/box";
 import { type Box, isBox } from "@/spatial/box/box";
-import * as box from "@/spatial/box/box";
-import type * as dims from "@/spatial/dimensions/dimensions";
-import * as location from "@/spatial/location/location";
-import * as xy from "@/spatial/xy/xy";
+import { type dimensions } from "@/spatial/dimensions";
+import { location } from "@/spatial/location";
+import { xy } from "@/spatial/xy";
 
 export const crudeXYTransform = z.object({ offset: xy.crudeZ, scale: xy.crudeZ });
 export type XYTransformT = z.infer<typeof crudeXYTransform>;
@@ -449,7 +449,7 @@ export class XY {
     return new XY().magnify(xy);
   }
 
-  static scale(box: dims.Dimensions | Box): XY {
+  static scale(box: dimensions.Dimensions | Box): XY {
     return new XY().scale(box);
   }
 
@@ -484,7 +484,7 @@ export class XY {
     return next;
   }
 
-  scale(b: Box | dims.Dimensions): XY {
+  scale(b: Box | dimensions.Dimensions): XY {
     const next = this.copy();
     if (isBox(b)) {
       const prevRoot = this.currRoot;

package/src/telem/telem.spec.ts

@@ -98,6 +98,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 +783,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", () => {