@synnaxlabs/x 0.45.0 → 0.46.0

package/src/math/constants.ts

@@ -0,0 +1,29 @@
+// 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 const MAX_UINT8 = 2 ** 8 - 1;
+export const MAX_UINT16 = 2 ** 16 - 1;
+export const MAX_UINT32 = 2 ** 32 - 1;
+export const MAX_UINT64 = 2n ** 64n - 1n;
+export const MAX_UINT64_NUMBER = 2 ** 64 - 1;
+
+export const MIN_INT8 = -(2 ** 7);
+export const MAX_INT8 = 2 ** 7 - 1;
+
+export const MIN_INT16 = -(2 ** 15);
+export const MAX_INT16 = 2 ** 15 - 1;
+
+export const MIN_INT32 = -(2 ** 31);
+export const MAX_INT32 = 2 ** 31 - 1;
+
+export const MIN_INT64 = -(2n ** 63n);
+export const MAX_INT64 = 2n ** 63n - 1n;
+
+export const MIN_INT64_NUMBER = -(2 ** 63);
+export const MAX_INT64_NUMBER = 2 ** 63 - 1;

package/src/math/external.ts

@@ -7,5 +7,6 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+export * from "@/math/constants";
 export * from "@/math/math";
 export * from "@/math/round";

package/src/spatial/box/box.ts

@@ -249,8 +249,7 @@ export const loc = (b: Crude, loc: location.Location): number => {
 };
 
 /** @returns true if the area of the box is 0 and false otherwise. */
-export const areaIsZero = (b: Box): boolean =>
-  b.one.x === b.two.x && b.one.y === b.two.y;
+export const areaIsZero = (b: Box): boolean => area(b) === 0;
 
 /** @returns the width of the box. */
 export const width = (b: Crude): number => dim(b, "x");

package/src/spatial/xy/xy.ts

@@ -194,7 +194,10 @@ export const css = (a: Crude): { left: number; top: number } => {
  */
 export const truncate = (a: Crude, precision: number = 0): XY => {
   const xy = construct(a);
-  return { x: Number(xy.x.toFixed(precision)), y: Number(xy.y.toFixed(precision)) };
+  return {
+    x: Number(xy.x.toFixed(precision)),
+    y: Number(xy.y.toFixed(precision)),
+  };
 };
 
 /**
@@ -311,3 +314,17 @@ export const round = (a: Crude): XY => {
   const xy = construct(a);
   return { x: Math.round(xy.x), y: Math.round(xy.y) };
 };
+
+/**
+ * Reciprocal of a point.
+ * @param a - The coordinate to invert. Can be provided in any supported format (couple, object, dimensions, etc.)
+ * @returns A new XY coordinate with the x and y values inverted.
+ * @example
+ * reciprocal([1, 2]) // returns { x: 1, y: 0.5 }
+ * reciprocal({ x: 3, y: 4 }) // returns { x: 0.3333333333333333, y: 0.25 }
+ * reciprocal({ width: 5, height: 6 }) // returns { x: 0.2, y: 0.16666666666666666 }
+ */
+export const reciprocal = (a: Crude): XY => {
+  const xy = construct(a);
+  return { x: 1 / xy.x, y: 1 / xy.y };
+};

package/src/status/status.ts

@@ -9,7 +9,9 @@
 
 import { z } from "zod";
 
+import { array } from "@/array";
 import { id } from "@/id";
+import { label } from "@/label";
 import { type Optional } from "@/optional";
 import { TimeStamp } from "@/telem";
 
@@ -25,53 +27,70 @@ export const variantZ = z.enum([
 // Represents one of the possible variants of a status message.
 export type Variant = z.infer<typeof variantZ>;
 
-type StatusZodObject<D extends z.ZodType> = z.ZodObject<{
-  key: z.ZodString;
-  variant: typeof variantZ;
-  message: z.ZodString;
-  description: z.ZodOptional<z.ZodString>;
-  time: typeof TimeStamp.z;
-  details: D;
-}>;
+export type StatusZodObject<DetailsSchema extends z.ZodType = z.ZodNever> = z.ZodObject<
+  {
+    key: z.ZodString;
+    name: z.ZodDefault<z.ZodString>;
+    variant: typeof variantZ;
+    message: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<ReturnType<typeof array.nullableZ<typeof label.labelZ>>>;
+    time: typeof TimeStamp.z;
+  } & ([DetailsSchema] extends [z.ZodNever] ? {} : { details: DetailsSchema })
+>;
 
-interface StatusZFunction {
-  (): StatusZodObject<z.ZodOptional<z.ZodUnknown>>;
-  <D extends z.ZodType>(details: D): StatusZodObject<D>;
+export interface StatusZFunction {
+  <DetailsSchema extends z.ZodType>(
+    details: DetailsSchema,
+  ): StatusZodObject<DetailsSchema>;
+  <DetailsSchema extends z.ZodType = z.ZodNever>(
+    details?: DetailsSchema,
+  ): StatusZodObject<DetailsSchema>;
 }
 
-export const statusZ: StatusZFunction = <D extends z.ZodType>(details?: D) =>
+export const statusZ: StatusZFunction = <DetailsSchema extends z.ZodType>(
+  details?: DetailsSchema,
+) =>
   z.object({
     key: z.string(),
+    name: z.string().default(""),
     variant: variantZ,
     message: z.string(),
     description: z.string().optional(),
     time: TimeStamp.z,
+    labels: array.nullableZ(label.labelZ).optional(),
     details: details ?? z.unknown().optional(),
   });
 
-export type Status<D = undefined, V extends Variant = Variant> = {
+type Base<V extends Variant> = {
   key: string;
+  name: string;
   variant: V;
   message: string;
   description?: string;
   time: TimeStamp;
-} & (D extends undefined ? {} : { details: D });
+  labels?: label.Label[];
+};
 
-export type Crude<D = undefined, V extends Variant = Variant> = Optional<
-  Status<D, V>,
-  "time" | "key"
->;
+export type Status<DetailsSchema = z.ZodNever, V extends Variant = Variant> = Base<V> &
+  ([DetailsSchema] extends [z.ZodNever] ? {} : { details: z.output<DetailsSchema> });
 
-export interface ExceptionDetails {
-  stack: string;
-}
+export type Crude<DetailsSchema = z.ZodNever, V extends Variant = Variant> = Optional<
+  Base<V>,
+  "key" | "time" | "name"
+> &
+  ([DetailsSchema] extends [z.ZodNever] ? {} : { details: z.output<DetailsSchema> });
+
+export const exceptionDetailsSchema = z.object({
+  stack: z.string(),
+});
 
 export const fromException = (
   exc: unknown,
   message?: string,
-): Status<ExceptionDetails, "error"> => {
+): Status<typeof exceptionDetailsSchema, "error"> => {
   if (!(exc instanceof Error)) throw exc;
-  return create<ExceptionDetails, "error">({
+  return create<typeof exceptionDetailsSchema, "error">({
     variant: "error",
     message: message ?? exc.message,
     description: message != null ? exc.message : undefined,
@@ -81,14 +100,15 @@ export const fromException = (
   });
 };
 
-export const create = <D = undefined, V extends Variant = Variant>(
-  spec: Crude<D, V>,
-): Status<D, V> =>
+export const create = <DetailsSchema = z.ZodNever, V extends Variant = Variant>(
+  spec: Crude<DetailsSchema, V>,
+): Status<DetailsSchema, V> =>
   ({
     key: id.create(),
     time: TimeStamp.now(),
+    name: "",
     ...spec,
-  }) as unknown as Status<D, V>;
+  }) as Status<DetailsSchema, V>;
 
 export const keepVariants = (
   variant?: Variant,

package/src/strings/strings.spec.ts

@@ -103,3 +103,45 @@ describe("trimPrefix", () => {
   it("should handle numbers in prefix", () =>
     expect(strings.trimPrefix("123abc", "123")).toBe("abc"));
 });
+
+describe("pluralName", () => {
+  it("should handle empty string", () => expect(strings.pluralName("")).toBe(""));
+
+  it("should add 's' to regular words", () => {
+    expect(strings.pluralName("cat")).toBe("cats");
+    expect(strings.pluralName("dog")).toBe("dogs");
+    expect(strings.pluralName("regularType")).toBe("regularTypes");
+  });
+
+  it("should convert 'y' endings to 'ies'", () => {
+    expect(strings.pluralName("company")).toBe("companies");
+    expect(strings.pluralName("yEndingType")).toBe("yEndingTypes");
+    expect(strings.pluralName("baby")).toBe("babies");
+  });
+
+  it("should add 'es' to words ending in 's'", () => {
+    expect(strings.pluralName("class")).toBe("classes");
+    expect(strings.pluralName("bus")).toBe("buses");
+  });
+
+  it("should add 'es' to words ending in 'x'", () => {
+    expect(strings.pluralName("box")).toBe("boxes");
+    expect(strings.pluralName("fox")).toBe("foxes");
+  });
+
+  it("should add 'es' to words ending in 'ch'", () => {
+    expect(strings.pluralName("catch")).toBe("catches");
+    expect(strings.pluralName("church")).toBe("churches");
+  });
+
+  it("should add 'es' to words ending in 'sh'", () => {
+    expect(strings.pluralName("bush")).toBe("bushes");
+    expect(strings.pluralName("brush")).toBe("brushes");
+  });
+
+  it("should work with built-in type names", () => {
+    expect(strings.pluralName("string")).toBe("strings");
+    expect(strings.pluralName("number")).toBe("numbers");
+    expect(strings.pluralName("object")).toBe("objects");
+  });
+});

package/src/strings/strings.ts

@@ -108,3 +108,17 @@ export const trimPrefix = (str: string, prefix: string): string => {
   if (str.startsWith(prefix)) return str.slice(prefix.length);
   return str;
 };
+
+export const pluralName = (name: string): string => {
+  if (name.length === 0) return name;
+  if (name[name.length - 1] === "y") return `${name.slice(0, -1)}ies`;
+  if (
+    name[name.length - 1] === "s" ||
+    name[name.length - 1] === "x" ||
+    name[name.length - 1] === "z" ||
+    name.endsWith("ch") ||
+    name.endsWith("sh")
+  )
+    return `${name}es`;
+  return `${name}s`;
+};

package/src/telem/series.ts

@@ -359,13 +359,12 @@ export class Series<T extends TelemValue = TelemValue>
         data_ = data_.map((v) => new TimeStamp(v as CrudeTimeStamp).valueOf());
       if (this.dataType.equals(DataType.STRING)) {
         this.cachedLength = data_.length;
-        this._data = new TextEncoder().encode(`${data_.join("\n")}\n`)
-          .buffer as ArrayBuffer;
+        this._data = new TextEncoder().encode(`${data_.join("\n")}\n`).buffer;
       } else if (this.dataType.equals(DataType.JSON)) {
         this.cachedLength = data_.length;
         this._data = new TextEncoder().encode(
           `${data_.map((d) => binary.JSON_CODEC.encodeString(d)).join("\n")}\n`,
-        ).buffer as ArrayBuffer;
+        ).buffer;
       } else if (this.dataType.usesBigInt && typeof first === "number")
         this._data = new this.dataType.Array(
           data_.map((v) => BigInt(Math.round(v as number))),

package/src/telem/telem.spec.ts

@@ -73,6 +73,11 @@ describe("TimeStamp", () => {
     expect(ts.equals(TimeSpan.microseconds(10).add(TimeStamp.utcOffset))).toBe(true);
   });
 
+  test("constructing from MIN and MAX as numbers", () => {
+    expect(new TimeStamp(TimeStamp.MIN.nanoseconds).equals(TimeStamp.MIN)).toBe(true);
+    expect(new TimeStamp(TimeStamp.MAX.nanoseconds).equals(TimeStamp.MAX)).toBe(true);
+  });
+
   test("construct from time string", () => {
     const ts = new TimeStamp("12:30", "UTC");
     expect(ts.date().getUTCHours()).toEqual(12);
@@ -460,7 +465,7 @@ describe("TimeStamp", () => {
     });
   });
 
-  describe("fString", () => {
+  describe("toString with formats", () => {
     const ts = new TimeStamp([2022, 12, 15], "UTC")
       .add(TimeSpan.hours(12))
       .add(TimeSpan.minutes(20))
@@ -479,7 +484,7 @@ describe("TimeStamp", () => {
 
     FORMAT_TESTS.forEach(([format, expected]) => {
       test(`should format timestamp as ${format}`, () => {
-        expect(ts.fString(format, "UTC")).toEqual(expected);
+        expect(ts.toString(format, "UTC")).toEqual(expected);
       });
     });
   });
@@ -925,6 +930,137 @@ describe("TimeSpan", () => {
     });
   });
 
+  describe("toString with semantic format", () => {
+    const TESTS: [TimeSpan, string][] = [
+      // Sub-second durations
+      [TimeSpan.ZERO, "0s"],
+      [TimeSpan.nanoseconds(50), "< 1s"],
+      [TimeSpan.microseconds(50), "< 1s"],
+      [TimeSpan.milliseconds(50), "< 1s"],
+      [TimeSpan.milliseconds(999), "< 1s"],
+
+      // Seconds
+      [TimeSpan.seconds(1), "1s"],
+      [TimeSpan.seconds(30), "30s"],
+      [TimeSpan.seconds(59), "59s"],
+
+      // Minutes with seconds (< 5 minutes)
+      [TimeSpan.seconds(60), "1m"],
+      [TimeSpan.seconds(90), "1m 30s"],
+      [TimeSpan.seconds(119), "1m 59s"],
+      [TimeSpan.seconds(120), "2m"],
+      [TimeSpan.seconds(150), "2m 30s"],
+      [TimeSpan.seconds(240), "4m"],
+      [TimeSpan.seconds(270), "4m 30s"],
+
+      // Minutes without seconds (>= 5 minutes)
+      [TimeSpan.seconds(300), "5m"],
+      [TimeSpan.seconds(330), "5m"], // seconds dropped
+      [TimeSpan.minutes(30), "30m"],
+      [TimeSpan.minutes(59), "59m"],
+
+      // Hours with minutes (< 3 hours)
+      [TimeSpan.minutes(60), "1h"],
+      [TimeSpan.minutes(90), "1h 30m"],
+      [TimeSpan.minutes(119), "1h 59m"],
+      [TimeSpan.minutes(120), "2h"],
+      [TimeSpan.minutes(150), "2h 30m"],
+      [TimeSpan.minutes(179), "2h 59m"],
+
+      // Hours without minutes (>= 3 hours)
+      [TimeSpan.minutes(180), "3h"],
+      [TimeSpan.minutes(195), "3h"], // minutes dropped
+      [TimeSpan.hours(12), "12h"],
+      [TimeSpan.hours(23), "23h"],
+
+      // Days with hours (< 2 days)
+      [TimeSpan.hours(24), "1d"],
+      [TimeSpan.hours(25), "1d 1h"],
+      [TimeSpan.hours(36), "1d 12h"],
+      [TimeSpan.hours(47), "1d 23h"],
+
+      // Days without hours (>= 2 days)
+      [TimeSpan.hours(48), "2d"],
+      [TimeSpan.hours(50), "2d"], // hours dropped
+      [TimeSpan.days(3), "3d"],
+      [TimeSpan.days(6), "6d"],
+
+      // Weeks with days (< 2 weeks)
+      [TimeSpan.days(7), "1w"],
+      [TimeSpan.days(8), "1w 1d"],
+      [TimeSpan.days(10), "1w 3d"],
+      [TimeSpan.days(13), "1w 6d"],
+
+      // Weeks without days (>= 2 weeks)
+      [TimeSpan.days(14), "2w"],
+      [TimeSpan.days(15), "2w"], // days dropped
+      [TimeSpan.days(21), "3w"],
+      [TimeSpan.days(28), "4w"],
+
+      // Months with days (< 3 months)
+      [TimeSpan.days(30), "1mo"],
+      [TimeSpan.days(35), "1mo 5d"],
+      [TimeSpan.days(45), "1mo 15d"],
+      [TimeSpan.days(60), "2mo"],
+      [TimeSpan.days(75), "2mo 15d"],
+
+      // Months without days (>= 3 months)
+      [TimeSpan.days(90), "3mo"],
+      [TimeSpan.days(95), "3mo"], // days dropped
+      [TimeSpan.days(180), "6mo"],
+      [TimeSpan.days(330), "11mo"],
+
+      // Years with months (< 2 years)
+      [TimeSpan.days(364), "12mo"],
+      [TimeSpan.days(365), "1y"],
+      [TimeSpan.days(395), "1y 1mo"],
+      [TimeSpan.days(500), "1y 4mo"],
+      [TimeSpan.days(700), "1y 11mo"],
+
+      // Years without months (>= 2 years)
+      [TimeSpan.days(730), "2y"],
+      [TimeSpan.days(750), "2y"], // months dropped
+      [TimeSpan.days(1095), "3y"],
+      [TimeSpan.days(3650), "10y"],
+
+      // Complex durations
+      [TimeSpan.seconds(3661), "1h 1m"],
+      [TimeSpan.minutes(1441), "1d"], // 24h 1m, but minutes are dropped at day level
+      [TimeSpan.minutes(1500), "1d 1h"], // 25h exactly
+      [TimeSpan.hours(169), "1w 1h"],
+
+      // Negative durations
+      [TimeSpan.seconds(-30), "-30s"],
+      [TimeSpan.minutes(-90), "-1h 30m"],
+      [TimeSpan.hours(-25), "-1d 1h"],
+      [TimeSpan.days(-8), "-1w 1d"],
+      [TimeSpan.days(-400), "-1y 1mo"],
+    ];
+
+    TESTS.forEach(([ts, expected]) => {
+      test(`${ts.valueOf()} => ${expected}`, () => {
+        expect(ts.toString("semantic")).toEqual(expected);
+      });
+    });
+  });
+
+  describe("toString with format", () => {
+    test("toString with semantic format", () => {
+      const ts = TimeSpan.hours(25);
+      expect(ts.toString("semantic")).toEqual("1d 1h");
+    });
+
+    test("toString with default format", () => {
+      const ts = TimeSpan.hours(25);
+      expect(ts.toString()).toEqual("1d 1h");
+    });
+
+    test("toString with full format", () => {
+      const ts = TimeSpan.hours(25).add(TimeSpan.minutes(30)).add(TimeSpan.seconds(15));
+      expect(ts.toString("full")).toEqual("1d 1h 30m 15s");
+    });
+  });
+
   describe("schema", () => {
     it("should parse bigint", () => {
       const ts = TimeSpan.z.parse(1000000000n);
@@ -1632,28 +1768,29 @@ describe("DataType", () => {
     });
 
     const testCases = [
-      { input: "int8", expected: "int8" },
-      { input: "int16", expected: "int16" },
-      { input: "int32", expected: "int32" },
-      { input: "int64", expected: "int64" },
-      { input: "uint8", expected: "uint8" },
-      { input: "uint16", expected: "uint16" },
-      { input: "uint32", expected: "uint32" },
-      { input: "uint64", expected: "uint64" },
-      { input: "float32", expected: "float32" },
-      { input: "float64", expected: "float64" },
-      { input: "string", expected: "string" },
-      { input: "boolean", expected: "boolean" },
-      { input: "timestamp", expected: "timestamp" },
-      { input: "uuid", expected: "uuid" },
-      { input: "json", expected: "json" },
+      { input: "int8", expected: "int8", short: "i8" },
+      { input: "int16", expected: "int16", short: "i16" },
+      { input: "int32", expected: "int32", short: "i32" },
+      { input: "int64", expected: "int64", short: "i64" },
+      { input: "uint8", expected: "uint8", short: "u8" },
+      { input: "uint16", expected: "uint16", short: "u16" },
+      { input: "uint32", expected: "uint32", short: "u32" },
+      { input: "uint64", expected: "uint64", short: "u64" },
+      { input: "float32", expected: "float32", short: "f32" },
+      { input: "float64", expected: "float64", short: "f64" },
+      { input: "string", expected: "string", short: "str" },
+      { input: "boolean", expected: "boolean", short: "bool" },
+      { input: "timestamp", expected: "timestamp", short: "ts" },
+      { input: "uuid", expected: "uuid", short: "uuid" },
+      { input: "json", expected: "json", short: "json" },
     ];
 
-    testCases.forEach(({ input, expected }) => {
+    testCases.forEach(({ input, expected, short }) => {
       it(`should parse "${input}" to DataType with value "${expected}"`, () => {
         const dt = DataType.z.parse(input);
         expect(dt).toBeInstanceOf(DataType);
         expect(dt.toString()).toBe(expected);
+        expect(dt.toString(true)).toBe(short);
       });
     });
   });