@synnaxlabs/x 0.55.0 → 0.56.1

package/src/status/status.spec.ts

@@ -110,9 +110,24 @@ describe("status", () => {
       expect(s.details.error).toBe(error);
     });
 
-    it("should throw when exception is not an Error instance", () => {
+    it("should coerce a non-Error throwable into an error status via fromUnknown", () => {
       const notAnError = "just a string";
-      expect(() => status.fromException(notAnError)).toThrow("just a string");
+      const s = status.fromException(notAnError);
+      expect(s.variant).toEqual("error");
+      // JSON.stringify of a string quotes it.
+      expect(s.message).toEqual('"just a string"');
+      expect(s.details.error).toBeInstanceOf(Error);
+      expect(s.details.error.cause).toEqual("just a string");
+    });
+
+    it("should pick up custom toStatus contributions from non-Error throwables", () => {
+      const custom = {
+        toStatus: () => ({ message: "custom msg", description: "custom desc" }),
+      };
+      const s = status.fromException(custom);
+      expect(s.variant).toEqual("error");
+      expect(s.message).toEqual("custom msg");
+      expect(s.description).toEqual("custom desc");
     });
 
     it("should include valid key and timestamp", () => {
@@ -448,4 +463,69 @@ describe("status", () => {
       });
     });
   });
+
+  describe("toError", () => {
+    it("should use the wrapped status message as the Error message", () => {
+      const inner = new Error("raw");
+      const s = status.fromException(inner, "Failed to fetch");
+      const err = status.toError(s);
+
+      expect(err.message).toBe("Failed to fetch");
+    });
+
+    it("should copy name from the inner error", () => {
+      class NotFoundError extends Error {
+        constructor(message: string) {
+          super(message);
+          this.name = "NotFoundError";
+        }
+      }
+      const inner = new NotFoundError("missing");
+      const s = status.fromException(inner, "Failed to fetch");
+      const err = status.toError(s);
+
+      expect(err.name).toBe("NotFoundError");
+    });
+
+    it("should copy stack from the inner error", () => {
+      const inner = new Error("raw");
+      inner.stack = "Error: raw\n    at someFn (file.ts:1:1)";
+      const s = status.fromException(inner, "Failed to fetch");
+      const err = status.toError(s);
+
+      expect(err.stack).toBe("Error: raw\n    at someFn (file.ts:1:1)");
+    });
+
+    it("should not leak the toError call-site stack when inner stack is missing", () => {
+      const inner = new Error("raw");
+      inner.stack = undefined;
+      const s = status.fromException(inner, "Failed to fetch");
+      const err = status.toError(s);
+
+      expect(err.stack).toBeUndefined();
+    });
+
+    it("should set cause to the original status", () => {
+      const inner = new Error("raw");
+      const s = status.fromException(inner, "Failed to fetch");
+      const err = status.toError(s);
+
+      expect(err.cause).toBe(s);
+    });
+
+    it("should round-trip through throw/catch", () => {
+      const inner = new TypeError("not a function");
+      const s = status.fromException(inner, "Failed to invoke");
+
+      try {
+        throw status.toError(s);
+      } catch (caught) {
+        expect(caught).toBeInstanceOf(Error);
+        const e = caught as Error;
+        expect(e.name).toBe("TypeError");
+        expect(e.message).toBe("Failed to invoke");
+        expect(e.cause).toBe(s);
+      }
+    });
+  });
 });

package/src/status/status.ts

@@ -9,6 +9,7 @@
 
 import { z } from "zod";
 
+import { errors } from "@/errors";
 import { id } from "@/id";
 import { narrow } from "@/narrow";
 import { type optional } from "@/optional";
@@ -52,11 +53,14 @@ const customReturnZ = z.object({
   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;
+const safeToStatus = (exc: unknown): z.infer<typeof customReturnZ> | undefined => {
+  if (
+    exc == null ||
+    typeof exc !== "object" ||
+    !("toStatus" in exc) ||
+    typeof exc.toStatus !== "function"
+  )
+    return undefined;
   let raw: unknown;
   try {
     raw = exc.toStatus();
@@ -78,13 +82,15 @@ export const fromException = (
   exc: unknown,
   message?: string,
 ): Status<typeof exceptionDetailsSchema, z.ZodLiteral<"error">> => {
-  if (!(exc instanceof Error)) throw exc;
+  const err = errors.fromUnknown(exc);
   const crude: Crude<typeof exceptionDetailsSchema, "error"> = {
     variant: "error",
-    message: message ?? exc.message,
-    description: message != null ? exc.message : undefined,
-    details: { stack: exc.stack ?? "", error: exc },
+    message: message ?? err.message,
+    description: message != null ? err.message : undefined,
+    details: { stack: err.stack ?? "", error: err },
   };
+  // Probe the original (pre-coercion) value so a non-Error throwable with a custom
+  // `toStatus()` method still contributes its status fields.
   const custom = safeToStatus(exc);
   if (custom != null) {
     if (message != null && custom.message != null)
@@ -97,6 +103,26 @@ export const fromException = (
   return create<typeof exceptionDetailsSchema, "error">(crude);
 };
 
+/**
+ * Converts an exception-shaped status (one built via {@link fromException}) back
+ * into a thrown-shaped {@link Error}. The returned error carries the status's
+ * wrapped message, copies `name` and `stack` from the inner error preserved on
+ * `details.error`, and stashes the full status on `cause` for callers that need
+ * the rich shape.
+ *
+ * Use this when bridging the status pipeline back into a context that expects
+ * a real Error — typically before `throw`-ing across an error boundary.
+ */
+export const toError = (
+  s: Status<typeof exceptionDetailsSchema, z.ZodLiteral<"error">>,
+): Error => {
+  const inner = s.details.error;
+  const err = new Error(s.message, { cause: s });
+  err.name = inner.name;
+  err.stack = inner.stack;
+  return err;
+};
+
 export const create = <
   DetailsSchema extends z.ZodType = z.ZodNever,
   V extends Variant = Variant,

package/src/telem/external.ts

@@ -11,3 +11,11 @@ export * from "@/telem/clockSkew";
 export { type GLBufferController } from "@/telem/gl";
 export * from "@/telem/series";
 export * from "@/telem/telem";
+export {
+  TIME_ZONES,
+  TIMESTAMP_FORMATS,
+  type TimestampFormat,
+  timestampFormatZ,
+  type TimeZone,
+  timeZoneZ,
+} from "@/telem/types.gen";

package/src/telem/series.spec.ts

@@ -369,6 +369,155 @@ describe("Series", () => {
     });
   });
 
+  describe("asString", () => {
+    it("should return the string value for a string series", () => {
+      const series = new Series({
+        data: ["apple", "banana"],
+        dataType: DataType.STRING,
+      });
+      expect(series.asString(0, true)).toEqual("apple");
+      expect(series.asString(1, true)).toEqual("banana");
+    });
+
+    it("should return the raw JSON string without parsing for a JSON series", () => {
+      const series = new Series({
+        data: [{ a_b: 1, c_d: "apple" }],
+        dataType: DataType.JSON,
+      });
+      const result = series.asString(0, true);
+      expect(result).toEqual('{"a_b":1,"c_d":"apple"}');
+    });
+
+    it("should preserve raw snake_case keys while at() converts them to camelCase", () => {
+      const series = new Series({
+        data: [{ user_id: 1, first_name: "alice" }],
+        dataType: DataType.JSON,
+      });
+      expect(series.asString(0, true)).toEqual('{"user_id":1,"first_name":"alice"}');
+      expect(series.at(0, true)).toEqual({ userId: 1, firstName: "alice" });
+    });
+
+    it("should decode UTF-8 bytes for a BYTES series", () => {
+      const payload = new TextEncoder().encode("hello world");
+      const buf = new ArrayBuffer(4 + payload.byteLength);
+      new DataView(buf).setUint32(0, payload.byteLength, true);
+      new Uint8Array(buf).set(payload, 4);
+      const series = new Series({ data: buf, dataType: DataType.BYTES });
+      expect(series.asString(0, true)).toEqual("hello world");
+    });
+
+    it("should emit the U+FFFD replacement character for invalid UTF-8 in a BYTES series", () => {
+      const payload = new Uint8Array([0xff, 0xfe]);
+      const buf = new ArrayBuffer(4 + payload.byteLength);
+      new DataView(buf).setUint32(0, payload.byteLength, true);
+      new Uint8Array(buf).set(payload, 4);
+      const series = new Series({ data: buf, dataType: DataType.BYTES });
+      expect(series.asString(0, true)).toEqual("��");
+    });
+
+    it("should return a string representation for a numeric series", () => {
+      const series = new Series({
+        data: new Float32Array([3.5, 7]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(series.asString(0, true)).toEqual("3.5");
+      expect(series.asString(1, true)).toEqual("7");
+    });
+
+    it("should return the shortest f32-roundtrippable decimal for typical FLOAT32 values", () => {
+      const series = new Series({
+        data: new Float32Array([1.234, 0.1, 100.5, -1.234, 3.14, -0]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(series.asString(0, true)).toEqual("1.234");
+      expect(series.asString(1, true)).toEqual("0.1");
+      expect(series.asString(2, true)).toEqual("100.5");
+      expect(series.asString(3, true)).toEqual("-1.234");
+      expect(series.asString(4, true)).toEqual("3.14");
+      expect(series.asString(5, true)).toEqual("0");
+    });
+
+    it("should stringify integer-valued FLOAT32 values without decimals", () => {
+      const series = new Series({
+        data: new Float32Array([0, 1, -1, 1000000, -1000000]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(series.asString(0, true)).toEqual("0");
+      expect(series.asString(1, true)).toEqual("1");
+      expect(series.asString(2, true)).toEqual("-1");
+      expect(series.asString(3, true)).toEqual("1000000");
+      expect(series.asString(4, true)).toEqual("-1000000");
+    });
+
+    it("should preserve f32 representation for very small FLOAT32 values", () => {
+      const subnormal = Math.fround(1e-40);
+      const series = new Series({
+        data: new Float32Array([Number.MIN_VALUE, subnormal]),
+        dataType: DataType.FLOAT32,
+      });
+      // Number.MIN_VALUE (5e-324) underflows to 0 in f32.
+      expect(series.asString(0, true)).toEqual("0");
+      expect(Math.fround(parseFloat(series.asString(1, true)))).toBe(subnormal);
+    });
+
+    it("should preserve f32 representation for very large FLOAT32 values", () => {
+      const maxF32 = Math.fround(3.4e38);
+      const large = Math.fround(1e30);
+      const series = new Series({
+        data: new Float32Array([maxF32, large]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(Math.fround(parseFloat(series.asString(0, true)))).toBe(maxF32);
+      expect(Math.fround(parseFloat(series.asString(1, true)))).toBe(large);
+    });
+
+    it("should stringify non-finite FLOAT32 values", () => {
+      const series = new Series({
+        data: new Float32Array([NaN, Infinity, -Infinity]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(series.asString(0, true)).toEqual("NaN");
+      expect(series.asString(1, true)).toEqual("Infinity");
+      expect(series.asString(2, true)).toEqual("-Infinity");
+    });
+
+    it("should produce idempotent stringification under FLOAT32 round-trip", () => {
+      const cases = [1.234, 0.1, 100.5, -1.234, 1.2339999675750732, Math.PI, 1e-20];
+      for (const v of cases) {
+        const s1 = new Series({
+          data: new Float32Array([v]),
+          dataType: DataType.FLOAT32,
+        }).asString(0, true);
+        const s2 = new Series({
+          data: new Float32Array([parseFloat(s1)]),
+          dataType: DataType.FLOAT32,
+        }).asString(0, true);
+        expect(s2).toBe(s1);
+      }
+    });
+
+    it("should return undefined when index is out of bounds", () => {
+      const series = new Series({
+        data: ["apple"],
+        dataType: DataType.STRING,
+      });
+      expect(series.asString(5)).toBeUndefined();
+    });
+
+    it("should throw when index is out of bounds and required is true", () => {
+      const series = new Series({
+        data: ["apple"],
+        dataType: DataType.STRING,
+      });
+      expect(() => series.asString(5, true)).toThrow();
+    });
+
+    it("should return the UUID string for a UUID series", () => {
+      const series = new Series({ data: SAMPLE_UUID_BYTES, dataType: DataType.UUID });
+      expect(series.asString(0, true)).toEqual("123e4567-e89b-40d3-8056-426614174000");
+    });
+  });
+
   describe("atAlignment", () => {
     it("should return the value at a particular alignment", () => {
       const series = new Series({
@@ -382,6 +531,40 @@ describe("Series", () => {
     });
   });
 
+  describe("bigint sampleOffset precision", () => {
+    it("preserves precision in at when sampleOffset is a bigint above 2^53", () => {
+      const offset = 1778020940471336960n;
+      const series = new Series({
+        data: new Float32Array([0, 1, 2]),
+        dataType: DataType.FLOAT32,
+        sampleOffset: offset,
+      });
+      expect(series.at(0)).toBe(offset);
+      expect(series.at(1)).toBe(offset + 1n);
+      expect(series.at(2)).toBe(offset + 2n);
+    });
+
+    it("preserves precision in max when sampleOffset is a bigint above 2^53", () => {
+      const offset = 1778020940471336960n;
+      const series = new Series({
+        data: new Float32Array([0, 1, 2]),
+        dataType: DataType.FLOAT32,
+        sampleOffset: offset,
+      });
+      expect(series.max).toBe(offset + 2n);
+    });
+
+    it("preserves precision in min when sampleOffset is a bigint above 2^53", () => {
+      const offset = 1778020940471336960n;
+      const series = new Series({
+        data: new Float32Array([0, 1, 2]),
+        dataType: DataType.FLOAT32,
+        sampleOffset: offset,
+      });
+      expect(series.min).toBe(offset);
+    });
+  });
+
   describe("slice", () => {
     it("should slice a lazy array", () => {
       const a = new Series({

package/src/telem/series.ts

@@ -45,6 +45,17 @@ interface GL {
 
 interface IterableIterator<T> extends Iterator<T>, Iterable<T> {}
 
+/** Shortest decimal string that round-trips through f32 — JS analogue of Go's strconv.FormatFloat(_, 'g', -1, 32). */
+const stringifyFloat32 = (value: number): string => {
+  const f32 = Math.fround(value);
+  if (!Number.isFinite(f32)) return f32.toString();
+  for (let p = 1; p <= 9; p++) {
+    const parsed = parseFloat(f32.toPrecision(p));
+    if (Math.fround(parsed) === f32) return parsed.toString();
+  }
+  return f32.toString();
+};
+
 /** A condensed set of information describing the layout of a series. */
 export interface SeriesDigest {
   key: string;
@@ -193,12 +204,14 @@ export class Series<T extends TelemValue = TelemValue>
     timeRange: TimeRange.z.optional(),
     dataType: DataType.z,
     alignment: z.coerce.bigint().optional(),
-    data: z.union([
-      stringArrayZ,
-      nullArrayZ,
-      z.instanceof(ArrayBuffer),
-      z.instanceof(Uint8Array),
-    ]),
+    data: z
+      .union([
+        stringArrayZ,
+        nullArrayZ,
+        z.instanceof(ArrayBuffer),
+        z.instanceof(Uint8Array),
+      ])
+      .default(() => new Uint8Array().buffer),
     glBufferUsage: glBufferUsageZ.default("static").optional(),
   });
 
@@ -294,7 +307,7 @@ export class Series<T extends TelemValue = TelemValue>
       data,
     } = props;
     if (isSeries(data)) {
-      const data_ = data as Series;
+      const data_ = data;
       this.key = data_.key;
       this.dataType = data_.dataType;
       this.sampleOffset = data_.sampleOffset;
@@ -319,7 +332,7 @@ export class Series<T extends TelemValue = TelemValue>
         "cannot infer data type from an ArrayBuffer instance when constructing a Series. Please provide a data type.",
       );
     else if (isArray || isSingle) {
-      let first: TelemValue | unknown = data as TelemValue;
+      let first: TelemValue | unknown = data;
       if (!isSingle) {
         if (data.length === 0)
           throw new Error(
@@ -694,7 +707,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 math.add(this.cachedMax, this.sampleOffset);
+    return this.applyOffset(this.cachedMax);
   }
 
   private calcRawMin(): math.Numeric {
@@ -720,7 +733,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 math.add(this.cachedMin, this.sampleOffset);
+    return this.applyOffset(this.cachedMin);
   }
 
   /** @returns the bounds of the series. */
@@ -777,7 +790,12 @@ export class Series<T extends TelemValue = TelemValue>
   at(index: number, required?: false): T | undefined;
 
   at(index: number, required: boolean = false): T | undefined {
-    if (this.dataType.isVariable) return this.atVariable(index, required ?? false);
+    if (this.dataType.isVariable) {
+      const str = this.atVariable(index, required);
+      if (str == null) return undefined;
+      if (this.dataType.equals(DataType.STRING)) return str as T;
+      return caseconv.snakeToCamel(JSON.parse(str)) as T;
+    }
     if (this.dataType.equals(DataType.UUID)) return this.atUUID(index, required) as T;
     if (index < 0) index = this.length + index;
     const v = this.data[index];
@@ -785,7 +803,16 @@ export class Series<T extends TelemValue = TelemValue>
       if (required === true) throw new Error(`[series] - no value at index ${index}`);
       return undefined;
     }
-    return math.add(v, this.sampleOffset) as T;
+    return this.applyOffset(v) as T;
+  }
+
+  // For huge bigint offsets (i64 timestamps narrowed to float32 for GL), math.add would
+  // coerce through Number() and lose precision above 2^53; do the addition in bigint
+  // space when the offset is a bigint.
+  private applyOffset(v: math.Numeric): math.Numeric {
+    if (typeof this.sampleOffset === "bigint" && typeof v === "number")
+      return BigInt(Math.round(v)) + this.sampleOffset;
+    return math.add(v, this.sampleOffset);
   }
 
   private atUUID(index: number, required: boolean): string | undefined {
@@ -800,7 +827,20 @@ export class Series<T extends TelemValue = TelemValue>
     return uuidString;
   }
 
-  private atVariable(index: number, required: boolean): T | undefined {
+  asString(index: number, required: true): string;
+
+  asString(index: number, required?: false): string | undefined;
+
+  asString(index: number, required: boolean = false): string | undefined {
+    if (this.dataType.isVariable) return this.atVariable(index, required);
+    if (this.dataType.equals(DataType.UUID)) return this.atUUID(index, required);
+    const v = this.at(index, required as true);
+    if (v == null) return undefined;
+    if (this.dataType.equals(DataType.FLOAT32)) return stringifyFloat32(v as number);
+    return String(v);
+  }
+
+  private atVariable(index: number, required: boolean): string | undefined {
     let start = 0;
     let len = 0;
     const buf = this.buffer;
@@ -836,9 +876,7 @@ export class Series<T extends TelemValue = TelemValue>
       }
     }
     const slice = new Uint8Array(buf, start, len);
-    if (this.dataType.equals(DataType.STRING))
-      return new TextDecoder().decode(slice) as T;
-    return caseconv.snakeToCamel(JSON.parse(new TextDecoder().decode(slice))) as T;
+    return new TextDecoder().decode(slice);
   }
 
   /**