@synnaxlabs/x 0.54.1 → 0.55.0

package/src/narrow/narrow.ts

@@ -18,3 +18,18 @@ export type IsUndefined<T> = [T] extends [undefined] // T can be assigned to und
 export const isObject = <T extends record.Unknown = record.Unknown>(
   item?: unknown,
 ): item is T => item != null && typeof item === "object" && !Array.isArray(item);
+
+/**
+ * A stricter version of {@link isObject} that additionally rejects class instances,
+ * arrays, and any non-`Object.prototype` objects. Returns true only for plain objects
+ * created via `{}`, `Object.create(null)`, or an object literal.
+ *
+ * Useful for walkers that need to distinguish "plain data bag" from "wrapped instance"
+ * (e.g. `Date`, `Map`, `Error`), which `isObject` treats the same.
+ */
+export const isPlainObject = (item?: unknown): item is Record<string, unknown> => {
+  if (item == null || typeof item !== "object") return false;
+  if (Array.isArray(item)) return false;
+  const proto = Object.getPrototypeOf(item);
+  return proto === Object.prototype || proto === null;
+};

package/src/primitive/primitive.spec.ts

@@ -64,6 +64,57 @@ describe("primitive", () => {
     });
   });
 
+  describe("is", () => {
+    it("should return true for null and undefined", () => {
+      expect(primitive.is(null)).toBe(true);
+      expect(primitive.is(undefined)).toBe(true);
+    });
+
+    it("should return true for strings", () => {
+      expect(primitive.is("")).toBe(true);
+      expect(primitive.is("hello")).toBe(true);
+    });
+
+    it("should return true for numbers", () => {
+      expect(primitive.is(0)).toBe(true);
+      expect(primitive.is(3.14)).toBe(true);
+      expect(primitive.is(NaN)).toBe(true);
+    });
+
+    it("should return true for booleans", () => {
+      expect(primitive.is(true)).toBe(true);
+      expect(primitive.is(false)).toBe(true);
+    });
+
+    it("should return true for bigints", () => {
+      expect(primitive.is(42n)).toBe(true);
+    });
+
+    it("should return true for symbols", () => {
+      expect(primitive.is(Symbol("x"))).toBe(true);
+    });
+
+    it("should return false for plain objects", () => {
+      expect(primitive.is({})).toBe(false);
+      expect(primitive.is({ a: 1 })).toBe(false);
+    });
+
+    it("should return false for arrays", () => {
+      expect(primitive.is([])).toBe(false);
+      expect(primitive.is([1, 2, 3])).toBe(false);
+    });
+
+    it("should return false for class instances", () => {
+      expect(primitive.is(new Date())).toBe(false);
+      expect(primitive.is(new Map())).toBe(false);
+      expect(primitive.is(new Error())).toBe(false);
+    });
+
+    it("should return false for functions", () => {
+      expect(primitive.is(() => 1)).toBe(false);
+    });
+  });
+
   describe("ValueExtension", () => {
     class MyValueExtension extends primitive.ValueExtension<bigint> {
       valueOf(): bigint {

package/src/primitive/primitive.ts

@@ -105,3 +105,15 @@ export const isZero = <V extends Value>(value: V): value is V & ZeroValue => {
  */
 export const isNonZero = <V extends Value>(value: V): value is V & NonZeroValue =>
   !isZero(value);
+
+/**
+ * @returns true if the given value is a JavaScript primitive: `null`, `undefined`,
+ * or a value whose `typeof` is not `"object"` or `"function"`. Returns false for
+ * objects (including arrays), functions, and class instances.
+ *
+ * Complements {@link isZero} and {@link isNonZero}, which check for the zero value
+ * of a known primitive type. Use `is` when you have an `unknown` value and want to
+ * decide whether to render it inline vs. recurse into it.
+ */
+export const is = (value: unknown): boolean =>
+  value == null || (typeof value !== "object" && typeof value !== "function");

package/src/status/status.spec.ts

@@ -14,6 +14,8 @@ import { id } from "@/id";
 import { status } from "@/status";
 import { TimeStamp } from "@/telem";
 
+type CustomCrude = Partial<status.Crude<z.ZodRecord, "error">>;
+
 describe("status", () => {
   describe("create", () => {
     it("should create a status", () => {
@@ -129,6 +131,117 @@ describe("status", () => {
       const result = status.exceptionDetailsSchema.safeParse(s.details);
       expect(result.success).toBe(true);
     });
+
+    describe("custom errors (toStatus)", () => {
+      class CustomError extends Error implements status.Custom {
+        constructor(message: string) {
+          super(message);
+          this.name = "CustomError";
+        }
+
+        toStatus(): CustomCrude {
+          return {
+            message: "custom headline",
+            description: "custom description body",
+            details: { code: 42, hint: "try again" },
+          };
+        }
+      }
+
+      it("should use toStatus.message as the status message", () => {
+        const s = status.fromException(new CustomError("raw"));
+        expect(s.message).toBe("custom headline");
+      });
+
+      it("should use toStatus.description as the status description", () => {
+        const s = status.fromException(new CustomError("raw"));
+        expect(s.description).toBe("custom description body");
+      });
+
+      it("should merge toStatus.details into status.details", () => {
+        const s = status.fromException(new CustomError("raw"));
+        const details = s.details as Record<string, unknown>;
+        expect(details.code).toBe(42);
+        expect(details.hint).toBe("try again");
+        expect(details.stack).toBeDefined();
+        expect(details.error).toBeInstanceOf(Error);
+      });
+
+      it("should prefix toStatus.message when the caller provides a custom message", () => {
+        const s = status.fromException(new CustomError("raw"), "Saving failed");
+        expect(s.message).toBe("Saving failed: custom headline");
+      });
+
+      it("should fall through to the default path for errors without toStatus", () => {
+        const s = status.fromException(new Error("plain"));
+        expect(s.message).toBe("plain");
+        expect(s.description).toBeUndefined();
+      });
+
+      it("should ignore toStatus if it throws", () => {
+        class Bad extends Error {
+          toStatus() {
+            throw new Error("explode");
+          }
+        }
+        const s = status.fromException(new Bad("fallback"));
+        expect(s.message).toBe("fallback");
+        expect(s.description).toBeUndefined();
+      });
+
+      it("should ignore toStatus if it returns a non-object", () => {
+        class Bad extends Error {
+          toStatus() {
+            return "nope" as unknown as CustomCrude;
+          }
+        }
+        const s = status.fromException(new Bad("fallback"));
+        expect(s.message).toBe("fallback");
+      });
+
+      it("should ignore toStatus if it returns null", () => {
+        class Bad extends Error {
+          toStatus() {
+            return null as unknown as CustomCrude;
+          }
+        }
+        const s = status.fromException(new Bad("fallback"));
+        expect(s.message).toBe("fallback");
+      });
+
+      it("should ignore individual fields with the wrong type", () => {
+        class Bad extends Error {
+          toStatus() {
+            return {
+              message: 42 as unknown as string,
+              description: { not: "a string" } as unknown as string,
+              details: "also not a record" as unknown as Record<string, unknown>,
+            };
+          }
+        }
+        const s = status.fromException(new Bad("fallback"));
+        expect(s.message).toBe("fallback");
+        expect(s.description).toBeUndefined();
+      });
+
+      it("should accept a partial return with only some valid fields", () => {
+        class Partial extends Error {
+          toStatus() {
+            return { message: "only headline" };
+          }
+        }
+        const s = status.fromException(new Partial("raw"));
+        expect(s.message).toBe("only headline");
+        expect(s.description).toBeUndefined();
+      });
+
+      it("should ignore toStatus if it is not a function", () => {
+        const err = new Error("fallback") as Error & { toStatus: string };
+        err.toStatus = "not a function";
+        const s = status.fromException(err);
+        expect(s.message).toBe("fallback");
+      });
+    });
   });
 
   describe("toString", () => {
@@ -301,5 +414,38 @@ describe("status", () => {
       const result = status.toString(s);
       expect(result).toContain("cat");
     });
+
+    describe("custom errors (toStatus)", () => {
+      class CustomError extends Error implements status.Custom {
+        constructor() {
+          super("raw");
+          this.name = "CustomError";
+        }
+
+        toStatus(): CustomCrude {
+          return {
+            message: "custom headline",
+            description: "line one\nline two\nline three",
+            details: { code: 42 },
+          };
+        }
+      }
+
+      it("should render the toStatus headline as the status message", () => {
+        const s = status.fromException(new CustomError());
+        expect(status.toString(s)).toContain("ERROR: custom headline");
+      });
+
+      it("should render a multi-line description on its own block", () => {
+        const out = status.toString(status.fromException(new CustomError()));
+        expect(out).toContain("Description:\nline one\nline two\nline three");
+      });
+
+      it("should include merged details under the Details section", () => {
+        const out = status.toString(status.fromException(new CustomError()));
+        expect(out).toContain("Details:");
+        expect(out).toContain('"code": 42');
+      });
+    });
   });
 });

package/src/status/status.ts

@@ -13,6 +13,7 @@ import { id } from "@/id";
 import { narrow } from "@/narrow";
 import { type optional } from "@/optional";
 import { primitive } from "@/primitive";
+import { record } from "@/record";
 import { type Status, type Variant } from "@/status/types.gen";
 import { TimeStamp } from "@/telem";
 
@@ -32,22 +33,68 @@ export type Crude<
 > = optional.Optional<Base<V>, "key" | "time" | "name"> &
   ([DetailsSchema] extends [z.ZodNever] ? {} : { details: z.output<DetailsSchema> });
 
-export const exceptionDetailsSchema = z.object({
-  stack: z.string(),
-  error: z.instanceof(Error),
+/**
+ * Interface that errors may optionally implement to provide richer rendering when
+ * passed to {@link fromException}. Implementers return a partial {@link Crude} spec
+ * whose fields override the defaults derived from the underlying `Error`.
+ *
+ * This is a duck-typed contract: `fromException` checks for the presence of a
+ * `toStatus` method via the `in` operator, so there is no need to import this
+ * interface to use it.
+ */
+export interface Custom {
+  toStatus(): Partial<Crude<z.ZodRecord, "error">>;
+}
+
+const customReturnZ = z.object({
+  message: z.string().optional(),
+  description: z.string().optional(),
+  details: record.unknownZ().optional(),
 });
 
+const hasToStatusMethod = (exc: Error): exc is Error & { toStatus: () => unknown } =>
+  "toStatus" in exc && typeof (exc as { toStatus: unknown }).toStatus === "function";
+
+const safeToStatus = (exc: Error): z.infer<typeof customReturnZ> | undefined => {
+  if (!hasToStatusMethod(exc)) return undefined;
+  let raw: unknown;
+  try {
+    raw = exc.toStatus();
+  } catch {
+    return undefined;
+  }
+  const parsed = customReturnZ.safeParse(raw);
+  return parsed.success ? parsed.data : undefined;
+};
+
+export const exceptionDetailsSchema = z
+  .object({
+    stack: z.string(),
+    error: z.instanceof(Error),
+  })
+  .and(record.unknownZ());
+
 export const fromException = (
   exc: unknown,
   message?: string,
 ): Status<typeof exceptionDetailsSchema, z.ZodLiteral<"error">> => {
   if (!(exc instanceof Error)) throw exc;
-  return create<typeof exceptionDetailsSchema, "error">({
+  const crude: Crude<typeof exceptionDetailsSchema, "error"> = {
     variant: "error",
     message: message ?? exc.message,
     description: message != null ? exc.message : undefined,
     details: { stack: exc.stack ?? "", error: exc },
-  });
+  };
+  const custom = safeToStatus(exc);
+  if (custom != null) {
+    if (message != null && custom.message != null)
+      crude.message = `${message}: ${custom.message}`;
+    else if (custom.message != null) crude.message = custom.message;
+    if (custom.description != null) crude.description = custom.description;
+    if (custom.details != null && crude.details != null)
+      crude.details = { ...crude.details, ...custom.details };
+  }
+  return create<typeof exceptionDetailsSchema, "error">(crude);
 };
 
 export const create = <
@@ -97,6 +144,16 @@ const DEFAULT_TO_STRING_OPTIONS: ToStringOptions = {
   includeName: true,
 };
 
+const renderDescription = (description: string): string => {
+  if (description.includes("\n")) return `Description:\n${description}`;
+  try {
+    const parsed = JSON.parse(description);
+    return `Description:\n${JSON.stringify(parsed, null, 2)}`;
+  } catch {
+    return `Description: ${description}`;
+  }
+};
+
 export const toString = <Details extends z.ZodType = z.ZodNever>(
   stat: Status<Details>,
   options: ToStringOptions = {},
@@ -108,21 +165,11 @@ export const toString = <Details extends z.ZodType = z.ZodNever>(
   header += `: ${stat.message}`;
   if (opts.includeTimestamp) header += ` (${stat.time.toString("dateTime", "local")})`;
   parts.push(header);
-  if (stat.description != null) {
-    let descriptionText: string;
-    try {
-      const parsed = JSON.parse(stat.description);
-      descriptionText = `Description:\n${JSON.stringify(parsed, null, 2)}`;
-    } catch {
-      descriptionText = `Description: ${stat.description}`;
-    }
-    parts.push(descriptionText);
-  }
+  if (stat.description != null) parts.push(renderDescription(stat.description));
   if ("details" in stat && narrow.isObject(stat.details)) {
     const details = stat.details as Record<string, unknown>;
-    // Extract stack trace separately for special formatting
-    if ("stack" in details) parts.push(`Stack Trace:\n${String(details.stack)}`);
-    // Include other details (excluding stack and error which don't serialize well)
+    if ("stack" in details && typeof details.stack === "string" && details.stack !== "")
+      parts.push(`Stack Trace:\n${details.stack}`);
     const extraDetails = Object.fromEntries(
       Object.entries(details).filter(([k]) => k !== "stack" && k !== "error"),
     );

package/src/strings/strings.spec.ts

@@ -103,3 +103,22 @@ describe("trimPrefix", () => {
   it("should handle numbers in prefix", () =>
     expect(strings.trimPrefix("123abc", "123")).toBe("abc"));
 });
+
+describe("escapeHTML", () => {
+  it("should escape ampersands", () =>
+    expect(strings.escapeHTML("a&b")).toBe("a&b"));
+
+  it("should escape angle brackets", () =>
+    expect(strings.escapeHTML("<div>")).toBe("&lt;div&gt;"));
+
+  it("should escape quotes", () =>
+    expect(strings.escapeHTML(`"it's"`)).toBe("&quot;it&#39;s&quot;"));
+
+  it("should return the original string when no special characters", () =>
+    expect(strings.escapeHTML("hello")).toBe("hello"));
+
+  it("should escape all special characters together", () =>
+    expect(strings.escapeHTML(`<a href="x">&`)).toBe(
+      "&lt;a href=&quot;x&quot;&gt;&amp;",
+    ));
+});

package/src/strings/strings.ts

@@ -108,3 +108,19 @@ export const trimPrefix = (str: string, prefix: string): string => {
   if (str.startsWith(prefix)) return str.slice(prefix.length);
   return str;
 };
+
+/**
+ * Escapes HTML special characters in a string to prevent XSS and ensure
+ * correct rendering in HTML contexts.
+ *
+ * @param s - The string to escape.
+ * @returns The escaped string with &, <, >, ", and ' replaced by their
+ * HTML entity equivalents.
+ */
+export const escapeHTML = (s: string): string =>
+  s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");

package/src/telem/clockSkew.spec.ts

@@ -0,0 +1,58 @@
+// Copyright 2026 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 { ClockSkewCalculator, TimeSpan, TimeStamp } from "@/telem";
+
+describe("ClockSkewCalculator", () => {
+  it("should correctly calculate clock skew from a single measurement", () => {
+    let mockTime = TimeStamp.seconds(0);
+    const calc = new ClockSkewCalculator(() => mockTime);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    // Remote midpoint is 3s, local midpoint is 5s, so skew is 2s
+    calc.end(TimeStamp.seconds(3));
+    expect(calc.skew).toEqual(TimeSpan.seconds(2));
+    expect(calc.exceeds(TimeSpan.seconds(1))).toBe(true);
+    expect(calc.exceeds(TimeSpan.seconds(3))).toBe(false);
+  });
+
+  it("should report zero skew when times match perfectly", () => {
+    let mockTime = TimeStamp.seconds(0);
+    const calc = new ClockSkewCalculator(() => mockTime);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    // Remote midpoint matches local midpoint at 5s
+    calc.end(TimeStamp.seconds(5));
+    expect(calc.skew).toEqual(TimeSpan.ZERO);
+    expect(calc.exceeds(TimeSpan.seconds(1))).toBe(false);
+  });
+
+  it("should return the most recent measurement", () => {
+    let mockTime = TimeStamp.seconds(0);
+    const calc = new ClockSkewCalculator(() => mockTime);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    calc.end(TimeStamp.seconds(3));
+    expect(calc.skew).toEqual(TimeSpan.seconds(2));
+    mockTime = TimeStamp.seconds(0);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    // Remote midpoint is 7s, local midpoint is 5s, so skew is -2s
+    calc.end(TimeStamp.seconds(7));
+    expect(calc.skew).toEqual(TimeSpan.seconds(-2));
+  });
+
+  it("should return zero skew when no measurements taken", () => {
+    const calc = new ClockSkewCalculator();
+    expect(calc.skew).toEqual(TimeSpan.ZERO);
+    expect(calc.exceeds(TimeSpan.seconds(1))).toBe(false);
+  });
+});

package/src/telem/clockSkew.ts

@@ -0,0 +1,46 @@
+// Copyright 2026 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 { type CrudeTimeSpan, TimeSpan, TimeStamp } from "@/telem/telem";
+
+/**
+ * Calculates and tracks clock skew between two systems using a midpoint
+ * synchronization algorithm. Useful for distributed systems where clock
+ * synchronization is critical.
+ */
+export class ClockSkewCalculator {
+  private readonly now: () => TimeStamp;
+  private localStartT: TimeStamp = new TimeStamp(0);
+  private lastSkew: TimeSpan = TimeSpan.ZERO;
+
+  constructor(now: () => TimeStamp = () => TimeStamp.now()) {
+    this.now = now;
+  }
+
+  start(): void {
+    this.localStartT = this.now();
+  }
+
+  end(remoteMidpointT: TimeStamp): void {
+    const localEndT = this.now();
+    const halfSpan = localEndT.span(this.localStartT).valueOf() / 2n;
+    const thisMidpointT = this.localStartT.add(halfSpan);
+    this.lastSkew = new TimeSpan(thisMidpointT.valueOf() - remoteMidpointT.valueOf());
+  }
+
+  get skew(): TimeSpan {
+    return this.lastSkew;
+  }
+
+  exceeds(threshold: CrudeTimeSpan): boolean {
+    const skewVal = this.skew.valueOf();
+    const abs = skewVal < 0n ? -skewVal : skewVal;
+    return abs > new TimeSpan(threshold).valueOf();
+  }
+}

package/src/telem/external.ts

@@ -7,6 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+export * from "@/telem/clockSkew";
 export { type GLBufferController } from "@/telem/gl";
 export * from "@/telem/series";
 export * from "@/telem/telem";

package/src/telem/series.spec.ts

@@ -141,7 +141,7 @@ describe("Series", () => {
       const s = new Series({ data: [{ a: 1, b: "apple" }] });
       expect(s.dataType.equals(DataType.JSON));
       expect(s.length).toEqual(1);
-      expect(s.data.at(-1)).toEqual(10);
+      expect(s.at(0)).toEqual({ a: 1, b: "apple" });
     });
 
     it("should correctly interpret a bigint as an int64", () => {
@@ -214,8 +214,8 @@ describe("Series", () => {
 
     it("should convert encoded keys to snake_case", () => {
       const a = new Series({ data: [{ aB: 1, bC: "apple" }], dataType: DataType.JSON });
-      const strContent = new TextDecoder().decode(a.data);
-      expect(strContent).toBe('{"a_b":1,"b_c":"apple"}\n');
+      expect(a.length).toEqual(1);
+      expect(a.at(0)).toEqual({ aB: 1, bC: "apple" });
     });
 
     it("should throw an error when an empty JS array is provided and no data type is provided", () => {
@@ -502,7 +502,7 @@ describe("Series", () => {
     });
 
     it("should recompute the length of a variable density array", () => {
-      const series = Series.alloc({ capacity: 12, dataType: DataType.STRING });
+      const series = Series.alloc({ capacity: 18, dataType: DataType.STRING });
       expect(series.length).toEqual(0);
       const writeOne = new Series({ data: ["apple"] });
       expect(series.write(writeOne)).toEqual(1);
@@ -689,6 +689,54 @@ describe("Series", () => {
         { a: 3, b: "carrot" },
       ]);
     });
+
+    it("should handle a single JSON value", () => {
+      const s = new Series([{ key: "val" }]);
+      expect(s.length).toEqual(1);
+      expect(s.at(0)).toEqual({ key: "val" });
+    });
+
+    it("should handle empty JSON objects", () => {
+      const s = new Series([{}, {}, {}]);
+      expect(s.length).toEqual(3);
+      expect(s.at(0)).toEqual({});
+      expect(s.at(2)).toEqual({});
+    });
+
+    it("should support negative indexing", () => {
+      const s = new Series([{ a: 1 }, { a: 2 }, { a: 3 }]);
+      expect(s.at(-1)).toEqual({ a: 3 });
+      expect(s.at(-2)).toEqual({ a: 2 });
+    });
+
+    it("should handle an empty JSON series", () => {
+      const s = new Series({ data: new ArrayBuffer(0), dataType: DataType.JSON });
+      expect(s.length).toEqual(0);
+      expect(Array.from(s)).toEqual([]);
+    });
+  });
+
+  describe("bytes series", () => {
+    it("should handle an empty bytes series", () => {
+      const s = new Series({ data: new ArrayBuffer(0), dataType: DataType.BYTES });
+      expect(s.length).toEqual(0);
+      expect(Array.from(s)).toEqual([]);
+    });
+
+    it("should correctly compute the length of a bytes series from a length-prefixed buffer", () => {
+      const payload1 = new Uint8Array([1, 2, 3]);
+      const payload2 = new Uint8Array([4, 5]);
+      const totalBytes = 4 + payload1.byteLength + 4 + payload2.byteLength;
+      const buf = new ArrayBuffer(totalBytes);
+      const view = new DataView(buf);
+      const bytes = new Uint8Array(buf);
+      view.setUint32(0, payload1.byteLength, true);
+      bytes.set(payload1, 4);
+      view.setUint32(4 + payload1.byteLength, payload2.byteLength, true);
+      bytes.set(payload2, 4 + payload1.byteLength + 4);
+      const s = new Series({ data: buf, dataType: DataType.BYTES });
+      expect(s.length).toEqual(2);
+    });
   });
 
   describe("binarySearch", () => {